AGENTS.md

Agent Notes

Local Dev Servers

• Frontend: from frontend/, run npm ci if dependencies are missing, then npm run dev.
• Backend: from backend/, run uv run uvicorn main:app --host ::1 --port 7860.
• Frontend URL: http://localhost:5173/
• Backend health check: curl -g http://[::1]:7860/api
• Frontend proxy health check: curl http://localhost:5173/api

Notes:

• Vite proxies /api and /auth to http://localhost:7860.
• If 127.0.0.1:7860 is already owned by another local process, binding the backend to ::1 lets the Vite proxy resolve localhost cleanly.
• Prefer npm ci over npm install for setup, since npm install may rewrite frontend/package-lock.json metadata depending on npm version.
• Non-local LLM calls use https://router.huggingface.co/v1 with the active Hugging Face user's token. Web sessions and the CLI default to GLM 5.2. For local development, set HF_TOKEN and optionally ML_INTERN_DEFAULT_MODEL_ID.
• When asked to start the local server, export the GitHub CLI token first with export GITHUB_TOKEN="$(gh auth token)".
• When debugging a web app issue tied to a session ID, inspect the session data in smolagents/ml-intern-sessions for additional context.

Development Checks

• Before every commit, run uv run ruff check . and uv run ruff format --check ..
• If formatting fails, run uv run ruff format ., then re-run the Ruff checks before committing.

Git Workflow

• Before creating any new branch or worktree, switch to main and pull the latest changes.

GitHub CLI

• Always use the gh CLI for GitHub operations such as opening, editing, inspecting, or commenting on PRs and issues.
• For multiline PR descriptions, prefer gh pr edit <number> --body-file <file> over inline --body so shell quoting, $ env-var names, backticks, and newlines are preserved correctly.
• If gh reports an invalid token or auth failure, retry the command with GH_TOKEN and GITHUB_TOKEN unset, for example env -u GH_TOKEN -u GITHUB_TOKEN gh pr create ..., so gh can use the stored login token instead of a stale environment token.
• In Codex, sandboxed gh auth checks can report a valid keyring login as invalid when GitHub network access is restricted. Before telling the user to re-authenticate, retry with both env tokens unset and GitHub network access enabled.

GitHub PRs

• Open code changes as GitHub PRs first. Do not push code changes directly to the Hugging Face Space deployment branch or Space remote before the PR has been opened, reviewed, and merged, unless the user explicitly asks to bypass the PR flow.
• After implementing a plan, run the required checks, commit the changes, open a GitHub PR, then start the backend and frontend local dev servers for testing.

Hugging Face Space Deploys

• The Space remote is space and points to https://huggingface.co/spaces/smolagents/ml-intern.
• Deploy GitHub main to the Space from the local space-main branch by merging origin/main into space-main with a single merge commit, then pushing space-main:main to the space remote.
• Keep the Space-only README frontmatter on space-main; .gitattributes should contain README.md merge=ours and the local repo config should include merge.ours.driver=true.
• Local dev commonly uses a personal HF_TOKEN, but the deployed Space uses HF OAuth tokens. When adding Hub features, make sure the Space README hf_oauth_scopes frontmatter and the backend OAuth request in backend/routes/auth.py include the scopes required by the Hub APIs being called. A feature can work locally with a broad PAT and still fail in production with 403s if OAuth scopes are missing; after changing scopes, users may need to log out and log in again to receive a fresh token.
• Recommended deploy flow:

git pull --ff-only origin main
git switch space-main
git config merge.ours.driver true
git merge --no-ff origin/main -m "Deploy $(date +%Y-%m-%d)" \
  -m "Co-authored-by: OpenAI Codex <codex@openai.com>"
git push space space-main:main
git switch main