Metadata-Version: 2.4
Name: mlcode-ai
Version: 0.1.3
Summary: AI coding agent for machine learning tasks: create, execute, and evaluate notebooks, and improve ML models.
Project-URL: Homepage, https://twotimespi.dev
Project-URL: Documentation, https://twotimespi.dev
Project-URL: Repository, https://github.com/alejandro-ao/tau
Project-URL: Issues, https://github.com/alejandro-ao/tau/issues
License-Expression: MIT
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: anyio>=4.0
Requires-Dist: httpx>=0.27
Requires-Dist: packaging>=24.0
Requires-Dist: pydantic>=2.0
Requires-Dist: rich>=13.0
Requires-Dist: textual>=1.0
Requires-Dist: typer>=0.12
Description-Content-Type: text/markdown

<h1 align="center">mlcode</h1>

<p align="center">
  <strong>AI coding agent for machine learning tasks</strong>
</p>

<p align="center">
  Create, execute, and evaluate Jupyter notebooks, iterate on model architectures, and automate ML workflows directly from your terminal.
</p>

---

## What is mlcode?

**mlcode** is an AI coding agent tailored for machine learning workflows. Operating inside your terminal or notebook workspace, it helps you:

- **Create, edit, & run Jupyter notebooks** for data exploration, model training, and evaluation.
- **Iterate on ML models** — tweak hyperparameters, benchmark metrics, and refactor training pipelines.
- **Automate experiment loops** — inspect stack traces, fix code errors, and log results.
- **Maintain session history** — durable session trees with branching, resume, and compaction.

```text
tau_coding  →  tau_agent  →  tau_ai
```

- `tau_ai`: Model provider streaming layer (OpenAI, Anthropic, OpenRouter, local models).
- `tau_agent`: Portable agent brain (messages, tools, events, session tree).
- `tau_coding`: CLI application, Textual interactive TUI, file/shell tools, and resources.

---

## Quickstart

### Installation

`mlcode` requires Python 3.12 or newer.

**From PyPI:**

```bash
# Using uv (recommended)
uv tool install mlcode-ai

# Using pip
pip install mlcode-ai
```

**For local development:**

```bash
uv run mlcode
```

### Usage

Run `mlcode` from your ML project directory:

```bash
cd my-ml-project
mlcode
```

Then prompt `mlcode` in the interactive TUI:

```text
build a baseline PyTorch model for CIFAR-10 in a notebook and evaluate accuracy
```

Non-interactive print mode for scripts:

```bash
mlcode -p "summarize dataset structure in data/"
mlcode --cwd /path/to/project -p "run notebook and output evaluation metrics"
```

### Connect a Model Provider

Start `mlcode` and authenticate your AI provider with `/login`:

```text
/login
/login openai
/model
```

Supported providers include OpenAI, Anthropic, OpenRouter, OpenAI Codex, Hugging Face, and local OpenAI-compatible endpoints (Ollama, vLLM, DeepSeek).

---

## Capabilities

- **Interactive TUI & Print Mode**: Full terminal interface powered by Textual or non-interactive CLI.
- **Coding & Execution Tools**: `read`, `write`, `edit`, and `bash` execution.
- **Notebook & ML Automation**: Work with scripts, notebooks, and experiment loops.
- **Durable Sessions**: Append-only JSONL session histories with tree branching (`/tree`) and recovery.
- **Custom Skills & Instructions**: Support for project-level instructions (`AGENTS.md`) and custom skills.

---

## License

Released under the [MIT License](LICENSE).
