The Problem
Data scientists and ML engineers often need a reproducible sandbox that can spin up a full Python environment, expose a web UI, and let a language‑model‑driven agent execute code, install packages, and access local files. Setting this up manually requires scripting, environment management, and careful handling of API keys.
What This Does
The repository ships a minimal “agentic” ML engineer built around Claude’s Code SDK.
karpathy/agent.py defines the core Agent class that receives prompts, calls Claude, and executes generated code in a sandboxed virtual environment. karpathy/utils.py contains helper routines (setupsandbox, copyenv, etc.) used by the CLI entry points. start.py orchestrates the end‑to‑end workflow: creates a sandbox directory, provisions a virtual environment with PyTorch, Transformers, scikit‑learn, copies the user’s .env into the sandbox, and launches the ADK web interface (adk web).
The surrounding files (tools.py, instructions.yaml) provide reusable tool definitions and configuration for the Claude Scientific Skills collection.
How To Use It
Setup
git clone https://github.com/K-Dense-AI/karpathy.git cd karpathy uv sync # installs dependencies from pyproject.toml
uv is the recommended package manager (declared in the README). No lockfile is present, so repeatability depends on the current package index.
Configuration
Create a .env file inside the karpathy package (or copy .env.example and fill in values):
OPENROUTERAPIKEY=youropenrouterapikeyhere
AGENTMODEL=yourmodelnamehere
The file is read by karpathy/utils.py and copied into the sandbox at startup.
Running
python start.py
start.py performs the following, as documented in its source: Calls karpathy.utils.setup_sandbox() → creates sandbox/ and a venv. Installs ML libraries (torch, transformers, scikit-learn, …) inside the sandbox. Copies the .env file into the sandbox. Executes adk web to launch the ADK UI on http://localhost:8000. The UI lets you select the karpathy agent and interact with it; all generated files appear under sandbox/.
For head‑less operation, you can run only the sandbox setup:
python -m karpathy.utils
Real‑World Use
A data‑science team can place a dataset (data.csv) into sandbox/, then ask the agent to train a model:
User: Train a RandomForest on data.csv and export the model to model.pkl
The agent will generate and execute a Python script inside the sandbox, using the pre‑installed scikit-learn. Results (model file, logs) are written to sandbox/, where the team can retrieve them directly.
Code Health & Issues
Med – Untested code – No tests/ directory; functions in agent.py and utils.py are not exercised by automated tests. Med – Missing CI/CD – No .github/workflows or other pipeline files; builds are not automatically validated. Low – No lockfile – pyproject.toml lists dependencies but lacks a uv.lock or requirements.txt, risking nondeterministic installs. Low – Minimal documentation – README covers basic usage; internal functions lack docstrings, making IDE assistance limited. Low – Hard‑coded paths – start.py assumes a sandbox directory at the repository root; running from another cwd may fail. Info – License present – MIT license is included, satisfying basic legal requirements.
The Bottom Line
The repo delivers a lightweight, Claude‑driven ML assistant that can auto‑provision an isolated Python environment and expose a web UI. It is functional for prototyping and small‑team experimentation but lacks automated testing, CI, and reproducible lockfiles, which raises maintenance risk for production use. Suitable for proof‑of‑concept work or teams comfortable with manual validation; not ready for mission‑critical pipelines without additional engineering effort.