Metadata-Version: 2.4
Name: trackit-train
Version: 0.1.0
Summary: A lightweight local-first ML experiment tracker
Author: TrackIt
License: MIT
Keywords: ml,experiment,tracker,machine-learning,local-first
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: fastapi>=0.110.0
Requires-Dist: uvicorn>=0.27.0
Requires-Dist: sqlmodel>=0.0.16
Requires-Dist: typer>=0.9.0
Requires-Dist: jinja2>=3.1.0
Requires-Dist: rich>=13.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: httpx>=0.27.0; extra == "dev"
Requires-Dist: pytest-cov>=4.1.0; extra == "dev"

# TrackIt

A lightweight, local-first ML experiment tracker. No servers, no accounts, no configuration.

**TrackIt** is a simpler alternative to MLflow and Weights & Biases for tracking experiments during local development.

---

## Features

- **Zero configuration** — install and start tracking in 30 seconds
- **Local-first** — all data stored in a single SQLite file
- **No accounts** — no remote server, no sign-up
- **Experiment SDK** — log params and metrics with a clean Python API
- **CLI** — list experiments, find best runs, launch a dashboard
- **Web dashboard** — interactive HTMX + Chart.js UI for exploring results

---

## Installation

```bash
pip install trackit
```

For development:

```bash
pip install trackit[dev]
```

---

## Quick Start

### Log an experiment

```python
from trackit import Experiment

exp = Experiment()

exp.log_param("lr", 0.001)
exp.log_param("batch_size", 32)

exp.log_metric("accuracy", 0.94)
exp.log_metric("loss", 0.12)

exp.finish()
```

### Use as a context manager

```python
from trackit import Experiment

with Experiment(name="resnet50-augmented") as exp:
    exp.log_param("lr", 0.001)
    for epoch in range(10):
        exp.log_metric("accuracy", evaluate(epoch))
        exp.log_metric("loss", compute_loss(epoch))
```

---

## CLI

### List experiments

```bash
trackit list
```

Output:

```
┌─────────────────────────────────────────────────────────────────┐
│                        Experiments                              │
├────┬──────────────────┬──────────┬───────────────────┬────────┬─────────┤
│ ID │ Name             │ Status   │ Created           │ Params │ Metrics │
├────┼──────────────────┼──────────┼───────────────────┼────────┼─────────┤
│  1 │ baseline         │ finished │ 2025-01-15 10:30  │      2 │       4 │
│  2 │ tuned            │ finished │ 2025-01-15 11:00  │      2 │       4 │
└────┴──────────────────┴──────────┴───────────────────┴────────┴─────────┘
```

### Find the best run

```bash
trackit best accuracy
```

To minimize (e.g. loss):

```bash
trackit best loss --minimize
```

### Launch the web dashboard

```bash
trackit ui
```

Open [http://localhost:8042](http://localhost:8042) in your browser.

---

## Storage

All experiment data is stored in a single SQLite database at:

```
.trackit/experiments.db
```

This file lives in your project root. Add it to `.gitignore` if you don't want to commit experiment history.

---

## Dashboard

The web dashboard provides:

- Experiment list with status, param count, and metric count
- Click-to-detail view showing all params and metrics
- Chart.js visualizations for accuracy and loss curves
- "Find Best Run" lookup for any metric

---

## API Reference

### `Experiment`

```python
Experiment(name: str | None = None, db_path: str | None = None)
```

| Method | Description |
|---|---|
| `log_param(key, value)` | Log a named parameter (stored as string) |
| `log_metric(key, value, step=None)` | Log a named metric; step auto-increments per key |
| `finish()` | Mark the experiment as finished |

`Experiment` also supports `with` statement for automatic finish on exit.

---

## Development

```bash
git clone <repo>
cd trackit
pip install -e ".[dev]"
pytest
```

---

## License

MIT
