ML Metaoptimization Skill Repo

This repository defines the ml-metaoptimization skill plus its supporting reference contracts and example campaign. This repository is a contract-only scope for the ml-metaoptimization skill. It pins the public docs, examples, and fixtures for the deterministic orchestration runtime. It does not simulate a live host runtime or remote backend.

Validation

Install the validation dependency from the repo root:

python3 -m pip install --user -r requirements.txt

Run the validation suite from the repo root:

python3 -m unittest discover -s tests -p 'test_*.py'

The tests pin the public contract for:

• the example campaign file
• backend stdout JSON payload shapes
• state-file fixtures and lifecycle pairing rules
• cross-document consistency between the skill and reference docs

Preflight Prerequisite

Before starting the resumable orchestrator loop, run the one-shot metaopt-preflight skill. It validates environment readiness and emits .ml-metaopt/preflight-readiness.json. LOAD_CAMPAIGN gates on this artifact — if it is missing, stale, or failed the orchestrator blocks with BLOCKED_CONFIG.

Runtime Notes

SKILL.md describes the intended Codex-ready goal-style orchestration runtime.

agents/openai.yaml is catalog metadata for OpenAI/Codex-style runtimes. It exists so those runtimes can surface this skill in their own UI/catalog flows; the live dispatch contract remains in SKILL.md and the references/ documents.

Codex Adaptation (v4)

The v4 execution model is designed for Codex goal-style orchestration. The orchestrator operates as a deterministic state machine, delegating semantic decisions to control agents and heavy lifting to leaf workers.

• Goal-Style Orchestration: The campaign is resumable and persistent via .ml-metaopt/state.json.
• Branch Agents: Control agents (e.g., metaopt-background-control) govern state transitions and plan work.
• CLI Worker Subagents: Concrete tasks (ideation, selection, analysis) are dispatched as CLI worker subagents.
• No-Code-Patch Policy: This skill exclusively manages sweeps and ML configurations; it does not produce file diffs or code changes.

Ecosystem (v4)

This orchestrator delegates to the following worker targets:

• metaopt-ideation-worker — Proposes WandB sweep search spaces.
• metaopt-selection-worker — Picks and refines the best sweep proposal.
• metaopt-analysis-worker — Analyzes WandB results against baseline.
• skypilot-wandb-worker — Directive-dispatched executor for WandB/SkyPilot/Vast.ai operations.

Historical v3 backends (hetzner-delegation, ray-hetzner) and materialization/patch/queue workers are historical references only. Live v4 runtime is sweep-oriented only and follows Codex goal-style orchestration.

Delegated Steps

The authoritative reference for control-agent scopes, handoff envelopes, and state-patch ownership is references/control-protocol.md. The state machine with the control-agent dispatch map is in references/state-machine.md.

Step 1 — metaopt-load-campaign

• Scope: LOAD_CAMPAIGN
• Action: Validates campaign YAML, computes identity hashes, checks preflight readiness.

Step 2 — metaopt-hydrate-state

• Scope: HYDRATE_STATE
• Action: Resumes or initializes state, manages AGENTS.md hook, verifies worker availability.

Step 3 — metaopt-background-control

• Scope: IDEATE, WAIT_FOR_PROPOSALS
• Action: Dispatches ideation workers, manages the proposal pool until the threshold is met.

Step 4 — metaopt-select-design

• Scope: SELECT_AND_DESIGN_SWEEP
• Action: Freezes the proposal pool, stages the selection task file, and finalizes the selected sweep from metaopt-selection-worker output.

Step 5 — metaopt-remote-execution-control

• Scope: LOCAL_SANITY, LAUNCH_SWEEP, WAIT_FOR_SWEEP, ANALYZE
• Action: Manages the smoke test, sweep launch/poll via directives, and dispatches the analysis worker.

Step 6 — metaopt-iteration-close-control

• Scope: ROLL_ITERATION
• Action: Filters proposals, checks stop conditions, increments iteration, or terminates the campaign.