ML Intern

The ML Intern Agent is an asynchronous, queue-based system powered by LiteLLM. The architecture follows a flow where user input submissions enter an Agent Loop, which then emits events that can be used for UI updates.

Key architectural features include:

• Session State: Maintains context and tools to support future Context Engineering.
• Event-Driven Control: Handlers manage operations such as USER_INPUT, COMPACT, UNDO, and SHUTDOWN to enable UI control.

ML Intern operates via a submission_loop (defined in agent_loop.py) that processes operations from a submission_queue and emits status updates to an event_queue.

Key components include:

• Handlers.run_agent(): Manages the core agentic loop (up to 300 iterations).
• ContextManager: Manages message history (using litellm.Message[]), handles auto-compaction (at 170k tokens), and uploads sessions to Hugging Face.
• ToolRouter: Routes requests to various capabilities including HF docs/research, HF repos/datasets/jobs/papers, GitHub code search, Sandbox/local tools, Planning, and MCP server tools.
• Doom Loop Detector: Monitors for repeated tool patterns and injects corrective prompts to prevent infinite loops.

You can run ml-intern in two modes:

1. Interactive mode: Starts a chat session.

   ml-intern

2. Headless mode: Executes a single prompt with auto-approval.

   ml-intern "your prompt"

CLI Options

ML Intern can send one-way status updates (approval requests, errors, turn completions) to Slack.

Setup

1. Create a Slack app with a bot token containing the chat:write scope.
2. Invite the bot to your target channel.
3. Set SLACK_BOT_TOKEN and SLACK_CHANNEL_ID in your environment.

Configuration via JSON

You can define persistent messaging destinations in ~/.config/ml-intern/cli_agent_config.json or by setting the ML_INTERN_CLI_CONFIG environment variable.

{
  "messaging": {
    "enabled": true,
    "auto_event_types": ["approval_required", "error", "turn_complete"],
    "destinations": {
      "slack.ops": {
        "provider": "slack",
        "token": "${SLACK_BOT_TOKEN}",
        "channel": "${SLACK_CHANNEL_ID}",
        "allow_agent_tool": true,
        "allow_auto_events": true
      }
    }
  }
}

Every review must follow a specific structure. Start with a single-line tally and an explicit verdict on two lines, followed by a "What I checked" list.

Verdict Options:

• Verdict: ready to merge: No P0 findings; contributor can merge once CI passes.
• Verdict: changes requested: At least one P0 must be addressed.
• Verdict: needs discussion: A design-level concern for maintainers.
• For clean reviews, use LGTM followed by Verdict: ready to merge.

Example Summary Format:

2 P0, 3 P1
Verdict: changes requested

Verification Requirement: Every behavior claim must cite file:line. If you cannot cite a specific line, do not post the finding.

Create a .env file in the project root or export the following variables in your shell to provide necessary credentials and configuration:

HF_TOKEN=<your-hugging-face-token>
GITHUB_TOKEN=<github-personal-access-token>

Every session is automatically uploaded to a private Hugging Face dataset in Claude Code JSONL format (e.g., {your-hf-username}/ml-intern-sessions).

Commands (Inside Interactive Mode)

• /share-traces: Shows current visibility and the dataset URL.
• /share-traces public: Makes the dataset public.
• /share-traces private: Makes the dataset private.

Configuration

To opt out of sharing, set share_traces: false in your config file. To change the destination, use personal_trace_repo_template.

For PRs that only involve lockfile bumps, pyproject.toml changes, or new dependencies, focus on provenance and framing rather than code logic:

• Ensure every claim in the title or body (CVE IDs, version numbers, behavior fixes) matches the actual diff.
• Require justification for any new transitive dependencies.
• A PR that misrepresents its purpose or changes in its framing is considered a P0 issue.

ML Intern supports local models via OpenAI-compatible HTTP endpoints through LiteLLM. You must start your inference server first. Use provider-specific prefixes to select the model.

Supported Prefixes

• ollama/
• vllm/
• lm_studio/
• llamacpp/

Configuration

Set LOCAL_LLM_BASE_URL and LOCAL_LLM_API_KEY for a shared endpoint. You can override these with provider-specific variables like OLLAMA_BASE_URL or VLLM_API_KEY which take precedence.

When reviewing this repository, categorize every finding into one of three priority levels. Use plain text labels (P0, P1, P2) in finding headers. Do not use emojis or colored markers.

• P0: Blocks the merge. Must be addressed.
• P1: Worth fixing, but does not block the merge.
• P2: Informational only.

Use judgment to determine the level; the repository does not provide an exhaustive list of P0 cases.

Install the ml-intern CLI tool using uv. After installation, the ml-intern command will be available in any directory.

Prerequisites

• uv installed on your system.
• A Hugging Face token (HF_TOKEN) for inference and Hub actions.
• A GitHub personal access token (GITHUB_TOKEN) for repository interactions.

git clone git@github.com:huggingface/ml-intern.git
cd ml-intern
uv sync
uv tool install -e .