plugins/ml-intern/commands/run.md

/mlintern:run

Run an ML Intern task end-to-end.

Arguments

• prompt (required): A one-sentence description of the ML deliverable. Examples: "fine-tune Qwen3-4B for code completion on python-code-dataset", "benchmark sentence-transformers/all-MiniLM-L6-v2 on STS-B", "train a diffusion LoRA on my art dataset".
• --model (optional): LiteLLM model ID to use (e.g., huggingface/openai/gpt-oss-120b). Defaults to the environment default.
• --background (optional): Queue the task and return immediately. Check status later.
• --status <job-id> (optional): Check status of a background job.
• --result <job-id> (optional): Fetch the final report of a completed background job.
• --cancel <job-id> (optional): Cancel a running background job.

Workflow

1. Clarify the deliverable from the prompt.
2. If the task has 3 or more meaningful steps, create a full update_plan plan before deep work begins. Keep exactly one step in progress at a time and update it at phase transitions.
3. Research the task before writing code:
   • Use a research sub-agent for broad or novel research when the active Codex runtime explicitly allows delegation; otherwise run the same focused probes directly.
   • Mirror upstream research behavior: keep research read-only, papers-first, and isolated from implementation as much as Codex allows.
   • If the task is paper-backed or novel, search for landmark and recent papers first.
   • Trace citation graphs or related-paper recommendations for old anchors and fast-moving methods.
   • Search and inspect likely HF datasets, even for plan-only tasks.
   • Read HF docs for current API patterns.
   • Find and read a working GitHub implementation example.
   • Use web sources only when the answer depends on current information outside HF and GitHub.
   • If the user only wants a plan, stop after the full research floor and return the plan. Do not implement.
4. Validate inputs:
   • Inspect dataset schema, splits, sample rows.
   • Verify model repo exists, architecture matches, tokenizer available.
5. Implement the smallest working version.
6. Smoke test locally or in a small HF Job.
7. Run the full training/evaluation job with HF Jobs.
8. Evaluate results against the target.
9. Save code, configs, and reports; publish ML artifacts to Hugging Face.

Output

Return:

• Deliverable status (complete / partial / failed).
• Evidence checked: papers, datasets, docs, GitHub examples, and external sources.
• GitHub branch, commit, PR, or report path for code.
• Hugging Face model/dataset/Space URLs for published artifacts.
• Job ID and log URL for HF Jobs runs.
• Metrics and evaluation results when available.
• Known failures, compromises, and next recommended steps.

Guardrails

• Never silently substitute a dataset, model, or training method. Ask for approval if the original request is incompatible.
• For multi-step tasks, do not skip plan updates at start, phase change, or completion.
• Always set realistic timeouts for HF Jobs (at least 2 hours for real training).
• Always include push_to_hub=True and hub_model_id in training configs.
• Run one job first before launching sweeps or ablations.
• For OOM errors: reduce batch size and increase gradient accumulation, enable gradient checkpointing, or upgrade hardware. Do not change the requested method.