ml-intern
An AI agent that fully automates ML workflows, from literature search to post-training.
- End-to-end ML post-training automation: Autonomously performs the entire ML research loop, from exploring arXiv papers → traversing the citation graph → searching for and inspecting/formatting datasets on the Hugging Face Hub → executing SFT/GRPO training scripts → interpreting evaluation results → diagnosing failures (e.g., reward collapse). - ContextManager (170k token automatic compression): Automatically compresses message history at the 170k token threshold (auto-compaction) to reliably maintain long-running agent sessions. Automatically uploads session traces to HF datasets. - Doom Loop Detector: Detects repetitive tool calling patterns and injects corrective prompts, preventing the agent from infinitely repeating the same failure. Combined with a maximum of 300 iterations to ensure safe autonomous execution. - ToolRouter: Integrates Hugging Face docs/repos/datasets search, arXiv paper reading, GitHub code search, sandbox execution, planning, and MCP server tools into a single routing layer. - Pre-approval for paid/destructive tasks: GPU Job execution (Hugging Face Jobs) and destructive commands are only executed when explicitly approved by the user. Auto-approval workflows can be configured. - Multiple LLM backends: Supports Claude (via FAL-AI), GPT (OpenAI/FAL-AI), HF Router models (MiniMax, Kimi, GLM, DeepSeek), and local models (Ollama, vLLM, LM Studio, LlamaCPP). - Trackio experiment tracking + Slack notifications: Monitors training metrics with the Hub-native experiment tracker, Trackio, and sends progress notifications to a Slack gateway.
💻 System Requirements
The agent itself is CPU-only (LLM inference is delegated to an external API). When running local models (Ollama/vLLM), 8-24GB is required depending on the model size. For SFT/GRPO training, an H100 80GB-class GPU is recommended (can be delegated to the cloud using Hugging Face Jobs).
The package itself requires ~250MB. Including training datasets and checkpoints, each project requires 10-50GB.
⚡ Installation
### 4-1. Quick Start
```bash
pip install ml-intern
```
### 4-2. Detailed Installation (Development Mode)
```bash
git clone https://github.com/huggingface/ml-intern.git
cd ml-intern
uv sync
uv tool install -e .
```
### 4-3. Environment Variable Configuration
```bash
export HF_TOKEN="hf_..." # Hugging Face token (required)
export ANTHROPIC_API_KEY="sk-..." # When using Anthropic models
export OPENAI_API_KEY="sk-..." # When using OpenAI models
export GITHUB_TOKEN="ghp_..." # When searching GitHub code (optional)
```
### 4-4. Basic Usage
```bash
# Interactive mode
ml-intern
# Headless mode (single prompt)
ml-intern --headless --task "Improve Qwen3-1.7B on the GPQA benchmark"
# Optional dependencies
pip install ml-intern[eval] # Evaluation tools
pip install ml-intern[dev] # Development tools
pip install ml-intern[all] # All tools
```
The code style uses Ruff, and it integrates with local model endpoints through LiteLLM.🧬 Bio Use Cases
Automated LLM Post-Training
When a base model (e.g., Qwen3-1.7B) is specified, the agent autonomously searches for relevant papers, explores and validates suitable training datasets from the Hub, executes SFT or GRPO training, and performs evaluations using benchmarks like GPQA. A case study reported that, based on the PostTrainBench, a single H100 GPU session in 10 hours improved the Qwen3-1.7B GPQA score from approximately 10% to 32% of the baseline.
Domain-Specific Fine-Tuning Research
For specific domains such as medicine, mathematics, or law, the agent reads the latest methodology papers (e.g., GRPO, DPO) from arXiv, explores related follow-up studies by following the citation graph, implements the techniques, and applies them to training. If it fails, it diagnoses the cause, such as reward collapse, and retries by generating synthetic data for edge cases.
Paper-Based Reproduction Experiments + Large-Scale Evaluation
The agent automatically collects reference datasets by traversing the methodology section and citation graph of arXiv papers, finds matching data from the HF Hub, generates training scripts, and reproduces the experiments. It records and compares the results for various checkpoints or hyperparameter combinations using Trackio to identify the optimal configuration.
📝 Update Notes
No update notes yet.
🧪 Related Code of Life
No related Code of Life posts yet.