Metadata-Version: 2.4
Name: trackit-train
Version: 0.1.1
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

[![PyPI version](https://img.shields.io/pypi/v/trackit-train.svg)](https://pypi.org/project/trackit-train/)
[![Python](https://img.shields.io/pypi/pyversions/trackit-train.svg)](https://pypi.org/project/trackit-train/)
[![License](https://img.shields.io/pypi/l/trackit-train.svg)](https://pypi.org/project/trackit-train/)

**A lightweight, local-first ML experiment tracker for Python.**

TrackIt is a simpler alternative to MLflow and Weights & Biases. No servers, no accounts, no configuration — just install and start tracking.

---

## Why TrackIt?

| | MLflow | W&B | **TrackIt** |
|---|---|---|---|
| Setup | Server + DB | Account + API key | **`pip install`** |
| Storage | Remote / managed | Cloud | **SQLite file** |
| Accounts | Yes | Yes | **None** |
| Offline | Partial | No | **Yes, always** |
| Install size | Heavy | Medium | **Lightweight** |

If you just want to track experiments locally without signing up for anything, TrackIt is the right tool.

---

## Installation

```bash
pip install trackit-train
```

---

## Quick Start

### Log your first experiment

```python
from trackit import Experiment

exp = Experiment(name="baseline")

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()
```

That's it. Your experiment is saved to `.trackit/experiments.db`.

### Use as a context manager

The `with` statement automatically finishes the experiment when the block exits — even if an error occurs.

```python
from trackit import Experiment

with Experiment(name="resnet50-augmented") as exp:
    exp.log_param("lr", 0.001)
    exp.log_param("epochs", 10)

    for epoch in range(10):
        acc = evaluate(model, val_loader)
        loss = compute_loss(model, train_loader)
        exp.log_metric("accuracy", acc, step=epoch)
        exp.log_metric("loss", loss, step=epoch)
```

### Integrate into a training loop

```python
from trackit import Experiment

with Experiment(name="bert-finetune") as exp:
    # Log all hyperparameters
    config = {"lr": 2e-5, "epochs": 3, "batch_size": 16, "model": "bert-base"}
    for k, v in config.items():
        exp.log_param(k, v)

    # Track metrics each epoch
    for epoch in range(config["epochs"]):
        train_loss = train_one_epoch(model, optimizer)
        val_acc = evaluate(model, val_loader)

        exp.log_metric("train_loss", train_loss, step=epoch)
        exp.log_metric("val_accuracy", val_acc, step=epoch)
```

---

## CLI

TrackIt provides a `trackit` command-line tool with three subcommands.

### `trackit list` — View all experiments

```bash
trackit list
```

```
┌───────────────────────────────────────────────────────────────────┐
│                         Experiments                               │
├────┬───────────────────┬──────────┬─────────────────┬────────┬─────────┤
│ ID │ Name              │ Status   │ Created         │ Params │ Metrics │
├────┼───────────────────┼──────────┼─────────────────┼────────┼─────────┤
│  1 │ baseline          │ finished │ 2025-06-11 10:30│      2 │       4 │
│  2 │ resnet50-aug      │ finished │ 2025-06-11 11:15│      3 │       6 │
│  3 │ bert-finetune     │ running  │ 2025-06-11 12:00│      4 │       2 │
└────┴───────────────────┴──────────┴─────────────────┴────────┴─────────┘
```

### `trackit best` — Find the best run

Find the experiment with the highest (or lowest) value for any metric:

```bash
# Highest accuracy
trackit best accuracy

# Lowest loss
trackit best loss --minimize
```

```
Best run for 'accuracy'

  Experiment : 2 — resnet50-aug
  Status     : finished
  Created    : 2025-06-11 11:15:00
  accuracy   : 0.965000
  Step       : 9

  Parameters
    lr                   = 0.0005
    batch_size           = 64
    augmentation         = True
```

### `trackit ui` — Launch the web dashboard

```bash
trackit ui
```

Opens a local web dashboard at **http://localhost:8042** with:

- **Experiment table** — sortable list of all runs with status, params, and metrics
- **Detail panel** — click any experiment to see all logged params and metrics
- **Charts** — interactive accuracy and loss curves powered by Chart.js
- **Best run finder** — search for the best experiment by any metric name

---

## Storage

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

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

This file is created automatically in your project root on first use.

**Tips:**
- Add `.trackit/` to your `.gitignore` to avoid committing experiment history
- Copy the `.db` file to back up or share experiment data
- Delete it to start fresh — it will be recreated on the next `Experiment()` call

---

## API Reference

### `Experiment(name=None, db_path=None)`

Creates a new experiment run and registers it in the database.

| Parameter | Type | Default | Description |
|---|---|---|---|
| `name` | `str \| None` | Auto-generated timestamp | Human-readable experiment name |
| `db_path` | `str \| None` | `.trackit/experiments.db` | Custom database file path |

#### Methods

| Method | Signature | Description |
|---|---|---|
| `log_param` | `log_param(key: str, value: Any)` | Log a hyperparameter. Value is stored as string. |
| `log_metric` | `log_metric(key: str, value: float, step: int \| None = None)` | Log a metric value. Step auto-increments per key if omitted. |
| `finish` | `finish()` | Mark the experiment as finished. Safe to call multiple times. |

#### Properties

| Property | Type | Description |
|---|---|---|
| `id` | `int` | Database-assigned experiment ID |
| `name` | `str` | Experiment name |

#### Context manager

`Experiment` supports `with` for automatic cleanup:

```python
with Experiment() as exp:
    exp.log_param("lr", 0.001)
# exp.finish() is called automatically here
```

---

## Comparison with other tools

**Use TrackIt when:**
- You want zero-setup local tracking
- You don't want to create accounts or manage API keys
- You want full data ownership in a portable SQLite file
- You're doing personal/hobby ML projects or quick experiments

**Use MLflow/W&B when:**
- You need team collaboration and shared dashboards
- You need experiment sharing across machines
- You need model registry and deployment pipelines
- You need cloud-hosted experiment storage

---

## Requirements

- Python 3.10+
- FastAPI, SQLModel, Typer, Jinja2, Rich (installed automatically)

---

## License

[MIT](https://opensource.org/licenses/MIT)
