Metadata-Version: 2.4
Name: thesis-tracker
Version: 1.0.1
Summary: Push experiments, training curves, and figures (TensorBoard / wandb / matplotlib) into your self-hosted Thesis Tracker dashboard.
Project-URL: Homepage, https://github.com/Satwik-Miyyapuram/thesis_tracker
Project-URL: Repository, https://github.com/Satwik-Miyyapuram/thesis_tracker
Project-URL: Issues, https://github.com/Satwik-Miyyapuram/thesis_tracker/issues
Author: Satwik Miyyapuram
License: Apache-2.0
Keywords: experiment-tracking,machine-learning,mlops,research,supabase,tensorboard,thesis,wandb
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: Apache Software 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: Topic :: Scientific/Engineering :: Artificial Intelligence
Classifier: Typing :: Typed
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: supabase>=2.4
Provides-Extra: all
Requires-Dist: keras>=3.0; extra == 'all'
Requires-Dist: lightning>=2.0; extra == 'all'
Requires-Dist: matplotlib>=3.6; extra == 'all'
Requires-Dist: pillow>=10.0; extra == 'all'
Requires-Dist: tbparse>=0.0.8; extra == 'all'
Requires-Dist: wandb>=0.16; extra == 'all'
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: figures
Requires-Dist: matplotlib>=3.6; extra == 'figures'
Requires-Dist: pillow>=10.0; extra == 'figures'
Provides-Extra: keras
Requires-Dist: keras>=3.0; extra == 'keras'
Provides-Extra: lightning
Requires-Dist: lightning>=2.0; extra == 'lightning'
Provides-Extra: tensorboard
Requires-Dist: tbparse>=0.0.8; extra == 'tensorboard'
Provides-Extra: wandb
Requires-Dist: wandb>=0.16; extra == 'wandb'
Description-Content-Type: text/markdown

# thesis-tracker (Python SDK)

**Push ML experiments into the same dashboard as your papers and thesis plan.**

The [Thesis Tracker](../README.md) web app tracks literature, milestones, and report progress. This package connects your **training scripts** to that same Supabase database — runs, step-indexed curves, and figure artifacts show up under **Experiments** without a separate wandb/MLflow silo.

## Why use it

| Problem | This SDK |
|---------|----------|
| Experiment logs live in TensorBoard; thesis context lives elsewhere | One DB: link runs to `related_paper`, compare sweeps in the PWA |
| Wiring a custom API for every project | Same RLS + migrations as the web app — self-host once |
| Heavy MLOps platforms | Lightweight decorator + optional Lightning/Keras callbacks |

## Install

```bash
pip install thesis-tracker                 # core (supabase + httpx)
pip install 'thesis-tracker[figures]'      # matplotlib/Pillow artifacts
pip install 'thesis-tracker[tensorboard]'  # tbparse import
pip install 'thesis-tracker[wandb]'        # wandb import
pip install 'thesis-tracker[all,dev]'      # everything + pytest
```

Sync sources register at import time but stay unavailable until their extra is installed (clear error if you call one without deps).

## Configure

Email + password auth (enable Email in Supabase Auth) so RLS attributes rows to you:

```bash
export THESIS_TRACKER_SUPABASE_URL=https://<ref>.supabase.co
export THESIS_TRACKER_SUPABASE_ANON_KEY=eyJ...
export THESIS_TRACKER_EMAIL=you@example.com
export THESIS_TRACKER_PASSWORD=...
export THESIS_TRACKER_PROJECT="My Thesis"   # or THESIS_TRACKER_PROJECT_ID=<uuid>
```

Apply migrations through at least `0017` (metrics + artifacts bucket) — see root [README § Database](../README.md#database).

## Quick example

```python
from thesis_tracker import track_experiment

@track_experiment(name="beta-vae sweep", config={"latent_dim": 32},
                  sync={"tensorboard": "runs/beta4"})
def train(run, beta=4.0):
    for step in range(100):
        run.log_metric("val_loss", loss(step), step=step)
    run.log_figure(fig, name="reconstruction")
    return {"val_loss": 0.11}

train(beta=4.0)
```

- **`@track_experiment`** — creates row (`running`), pins git state, logs metrics, uploads figures, sets `done`/`failed` on exit.
- **`with track(...) as run:`** — same without a decorator.
- **Callbacks** — `thesis_tracker.integrations.lightning.ThesisTrackerCallback`, `.keras.ThesisTrackerCallback`.

## CLI

```bash
thesis-tracker list --project "My Thesis"
thesis-tracker import-tb runs/beta4 --name "beta-vae sweep"
thesis-tracker import-wandb entity/project/run_id
```

## Extend (Open/Closed)

Implement `MetricSource` (`id`, `available()`, `read(ref)`), register on `default_registry`, use `track(sync={"my_source": ref})`. Example: `examples/custom_source.py`.

## Architecture

Mirrors the web app: `features/experiments/{domain,application,infrastructure}`, `container.py` composition root, repository interfaces tested with in-memory fakes. **No duplicate schema** — migrations in `../supabase/migrations/` are the contract.

## Test

```bash
pip install -e '.[dev]'
pytest   # offline; Supabase integration test skips without env creds
```

## More

- Root pitch + web app: [../README.md](../README.md)
- Design principles: [../docs/DESIGN.md](../docs/DESIGN.md)
