trackit-train 0.1.1

A lightweight local-first ML experiment tracker

TrackIt

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

pip install trackit-train

---

Quick Start

Log your first experiment

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.

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

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

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:

# 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

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:

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