Metadata-Version: 2.4
Name: caliper-py
Version: 0.1.1
Summary: Local-first ML experiment tracker with a real-time dashboard, convergence forecasting, and zero cloud dependencies
Author-email: Pirajesh M R <115163471+verz0@users.noreply.github.com>
License: MIT
Project-URL: Homepage, https://verz0.github.io/Caliper
Project-URL: Repository, https://github.com/verz0/Caliper
Project-URL: Bug Tracker, https://github.com/verz0/Caliper/issues
Keywords: machine-learning,experiment-tracking,ml,deep-learning,training,dashboard,local-first
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: Development Status :: 3 - Alpha
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# Caliper

**Local-first ML experiment tracker.** Log metrics, visualize training runs, compare experiments — all on your machine, zero cloud required.

[![PyPI](https://img.shields.io/pypi/v/caliper-py)](https://pypi.org/project/caliper-py/)
[![Python](https://img.shields.io/pypi/pyversions/caliper-py)](https://pypi.org/project/caliper-py/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)

---

## What is Caliper?

Caliper is a lightweight experiment tracker that stores everything locally as plain JSONL files and serves a rich dashboard from a single CLI command. No accounts, no API keys, no telemetry.

- **Convergence forecasting** — predicts final val loss and steps to convergence in real-time
- **Step-level annotations** — pin notes directly onto chart steps
- **Multi-run comparison** — overlay up to 8 runs with hyperparameter diffs
- **Project + tag filtering** — organize and filter runs from the sidebar
- **GPU monitoring** — log utilization, VRAM, temperature, and CPU alongside metrics
- **100% offline** — all data lives in `.caliper/runs/` in your working directory

---

## Installation

```bash
pip install caliper-py
```

Requires Python 3.8+. No heavy dependencies.

---

## Quickstart

### 1. Initialize a run in your training script

```python
import caliper

run = caliper.init(
    project="CIFAR-10",
    name="resnet50-baseline",
    tags=["ResNet-50", "baseline"],
    hyperparams={
        "model": "ResNet-50",
        "optimizer": "Adam",
        "learning_rate": 0.001,
        "batch_size": 64,
        "epochs": 50,
    }
)
```

### 2. Log metrics each step

```python
for step, batch in enumerate(dataloader):
    loss = train_step(batch)
    val_loss, val_acc = evaluate()

    run.log({
        "step": step,
        "trainLoss": loss,
        "valLoss": val_loss,
        "valAcc": val_acc,
        "lr": scheduler.get_last_lr()[0],
        # optional hardware metrics
        "gpuUtil": get_gpu_util(),
        "vramUsage": get_vram_gb(),
    })

run.finish()
```

### 3. Launch the dashboard

```bash
caliper ui
```

Opens `http://localhost:5173` automatically. All runs in `.caliper/runs/` load instantly.

---

## CLI Reference

```
caliper ui                  Launch the dashboard (default port 5173)
caliper ui --port 8080      Use a custom port
caliper ui --no-browser     Start server without opening a browser
```

---

## Data Format

Caliper writes two files per run inside `.caliper/runs/`:

| File | Description |
|---|---|
| `{run_id}_meta.json` | Run metadata: name, project, tags, hyperparams, status, annotations |
| `{run_id}_logs.jsonl` | One JSON object per logged step |

Both are plain text — you can read, edit, or version-control them however you like.

### Example `_meta.json`

```json
{
  "id": "run-001",
  "name": "resnet50-baseline",
  "project": "CIFAR-10",
  "status": "completed",
  "tags": ["ResNet-50", "baseline"],
  "hyperparams": { "model": "ResNet-50", "learning_rate": 0.001 },
  "annotations": [],
  "meta": { "startTime": "2026-06-01T10:00:00Z", "duration": 7260 }
}
```

### Example `_logs.jsonl` (one line per step)

```jsonl
{"step": 0, "trainLoss": 2.31, "valLoss": 2.45, "valAcc": 0.12, "lr": 0.001}
{"step": 1, "trainLoss": 2.18, "valLoss": 2.30, "valAcc": 0.15, "lr": 0.001}
```

---

## Generating Sample Data

A sample data generator is included for testing the dashboard:

```bash
python -c "
import subprocess, sys
subprocess.run([sys.executable, '-m', 'pip', 'show', '-f', 'caliper-py'])
"
```

Or clone the repo and run:

```bash
git clone https://github.com/verz0/Caliper
cd Caliper/caliper-py
python generate_sample_runs.py
caliper ui
```

---

## Links

- **Homepage & demo**: [verz0.github.io/Caliper](https://verz0.github.io/Caliper)
- **Source code**: [github.com/verz0/Caliper](https://github.com/verz0/Caliper)
- **Issues**: [github.com/verz0/Caliper/issues](https://github.com/verz0/Caliper/issues)

---

Made by [Pirajesh M R](https://github.com/verz0) · MIT License
