The Problem

Machine‑learning practitioners often need a reproducible, isolated environment that bundles API keys, scientific‑skill libraries, and a lightweight UI for interactive model development. Setting up such a sandbox manually is error‑prone and time‑consuming.

What This Does

The repository provides a minimal “agentic” ML engineer that:

  • Creates a sandbox directory populated with Claude Scientific Skills. (karpathy/utils.py::download_scientific_skills)
  • Spins up a Python virtual environment using uv and installs common ML packages. (karpathy/utils.py::setup_uv_environment)
  • Copies a user‑supplied .env (containing OPENROUTER_API_KEY and AGENT_MODEL) into the sandbox so the agent can call external services. (karpathy/utils.py::copy_env_file)

The top‑level entry point is start.py → main(). The core orchestration lives in karpathy/utils.py, which defines the five public functions (load_instructions, download_scientific_skills, setup_uv_environment, copy_env_file, setup_sandbox). A single helper, karpathy/tools.py::delegate_task, is present but not wired into the current flow.

How It Is Wired

  1. Entry point – start.py line 11 defines main() and is the only start function identified.
  2. main() calls setup_sandbox() (in karpathy/utils.py). This is the sole path that leaves the process.
  3. setup_sandbox() performs three side‑effect actions: copy_env_file() → creates sandbox/.env (filesystem write). download_scientific_skills() → pulls skill packages from the Claude collection (external command / network). * setup_uv_environment() → runs uv venv and uv pip install to build the sandbox environment (external command).

The internal call graph shows 8 resolved edges; the most frequently referenced function is setup_sandbox, called from two places (currently only main).

karpathy/utils.py is the hub: it contains 5 functions, is imported by start.py, reads/writes files, and spawns external processes. karpathy/tools.py is peripheral with a single delegate_task function, imported nowhere else. No circular imports are present, and the import graph is shallow (4 edges, 5 modules).

The deepest nesting occurs in karpathy/utils.py and karpathy/tools.py (max indentation depth 8), making the control flow harder to follow.

How To Use It

# Clone the exact repository
git clone https://github.com/moses-y/karpathy
cd karpathy

# Install dependencies with uv (Python 3.13+ required)
uv sync

# Create .env in the package directory
cat > karpathy/.env <<EOF
OPENROUTER_API_KEY=your_openrouter_api_key_here
AGENT_MODEL=your_model_name_here
EOF

# Run the setup and launch the ADK web UI
python start.py

Running only the sandbox setup (no UI) is possible with:

python -m karpathy.utils

The UI is started separately via adk web after the sandbox is ready.

Real‑World Use

A data‑science team can place training scripts or datasets into sandbox/ and interact with the agent through the web UI at http://localhost:8000. The agent reads the copied .env to authenticate calls to external LLM services, then executes user‑directed ML pipelines inside the isolated environment, keeping the host system clean.

# Example: trigger a training job from the UI
POST /run
{
  "script": "train.py",
  "args": ["--epochs", "10"]
}
# The agent runs `python train.py --epochs 10` inside sandbox

Code Health & Issues

  • High – Missing lockfile – pyproject.toml declares dependencies but no lockfile is committed. This hampers reproducible builds.
  • Medium – No Dependabot – Only one manifest (pyproject.toml) is present; no automated dependency‑update bot is configured.
  • Medium – No test suite – No tests/ directory or test files detected.
  • Medium – No CI/CD – No .github/workflows or other pipeline definitions.
  • Low – Deep nesting – karpathy/utils.py and karpathy/tools.py have indentation depth 8, increasing cognitive load.

The repository includes a LICENSE (MIT) and a README.md but lacks Dockerfile, CI scripts, and a lockfile.

The Bottom Line

The project delivers a lightweight, scripted sandbox for Claude‑driven ML workflows with clear entry points and minimal external dependencies. However, the codebase suffers from poor reproducibility (no lockfile), absent automated testing/CI, and deeply nested logic that may hinder maintenance. It is suitable for prototyping or evaluation in controlled environments, but production teams should add tests, CI, and a lockfile before relying on it.