mltrackr 0.3.0__py3-none-any.whl

mltrackr-0.3.0.dist-info/METADATA

@@ -0,0 +1,358 @@
+Metadata-Version: 2.4
+Name: mltrackr
+Version: 0.3.0
+Summary: Zero-setup ML experiment tracker with live dashboard, anomaly detection, and hyperparameter suggestions
+License: MIT
+Project-URL: Homepage, https://github.com/naialorente/datalog
+Project-URL: Issues, https://github.com/naialorente/datalog/issues
+Keywords: machine-learning,experiment-tracking,mlops,data-science,pytorch,scikit-learn,keras,huggingface,tensorflow,hyperparameter-tuning,model-monitoring,local-first,research,jupyter,kaggle,anomaly-detection,dashboard,experiment-logger,ml-tracker,training-monitor
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Intended Audience :: Education
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Database
+Classifier: License :: OSI Approved :: MIT License
+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: Operating System :: OS Independent
+Classifier: Environment :: Console
+Classifier: Environment :: Web Environment
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Requires-Dist: flask>=2.0
+Requires-Dist: click>=8.0
+Requires-Dist: rich>=13.0
+
+# trainlog
+
+> Track ML experiments in 2 lines of code. No server. No account. No config.
+
+[![CI](https://github.com/NaiaLorente/datalog/actions/workflows/ci.yml/badge.svg)](https://github.com/NaiaLorente/datalog/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/pypi/v/mltrackr)](https://pypi.org/project/mltrackr/)
+[![Python](https://img.shields.io/pypi/pyversions/mltrackr)](https://pypi.org/project/mltrackr/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+[![Stars](https://img.shields.io/github/stars/NaiaLorente/datalog?style=social)](https://github.com/NaiaLorente/datalog)
+
+You're running a training loop. You want to know which hyperparameters worked best. You don't want to:
+
+- Set up a tracking server
+- Create an account on any service
+- Write to a cloud API
+- Configure environment variables
+- Install 47 dependencies
+
+**trainlog is the answer.** Install it, wrap your loop, open a beautiful local dashboard. Done.
+
+---
+
+## Quickstart (5 steps)
+
+**1. Install**
+```bash
+pip install mltrackr
+```
+> This installs the `trainlog` command and `import trainlog` Python package.
+
+**2. Generate a ready-to-run example**
+```bash
+python -m trainlog.cli init --framework plain -o demo.py
+```
+> On most systems `trainlog init` works directly. If not, use `python -m trainlog.cli` instead.
+
+**3. Run the demo (creates 6 fake training runs)**
+```bash
+python demo.py
+```
+
+**4. Inspect results in the terminal**
+```bash
+python -m trainlog.cli list
+python -m trainlog.cli best accuracy
+python -m trainlog.cli suggest accuracy
+```
+
+**5. Open the visual dashboard**
+```bash
+python -m trainlog.cli ui
+```
+Then open **http://localhost:7000** in your browser. Press `Ctrl+C` to stop.
+
+---
+
+## Your first real experiment
+
+```python
+import trainlog
+
+with trainlog.run("resnet-baseline", tags=["cv", "baseline"]):
+    trainlog.log(lr=1e-3, batch_size=64, optimizer="adam")
+
+    for epoch in range(50):
+        loss, acc = train_one_epoch(model, dataloader)
+        trainlog.log(loss=loss, accuracy=acc, epoch=epoch)
+
+    trainlog.note("Solid baseline - try lr=5e-4 next")
+```
+
+```bash
+# If 'trainlog' works directly on your system:
+trainlog ui
+trainlog list
+trainlog best accuracy
+trainlog suggest accuracy
+trainlog report
+
+# If not (e.g. Windows), use:
+python -m trainlog.cli ui
+python -m trainlog.cli list
+python -m trainlog.cli best accuracy
+```
+
+Everything is saved locally in `~/.trainlog/experiments.db`. A single SQLite file. Copy it, back it up, open it in any SQLite browser.
+
+---
+
+## Why trainlog?
+
+**The real problem:** you're hacking on a model, you want to log some metrics, but setting up MLflow takes 15 minutes and W&B wants you to create an account and send your data to the cloud. So you end up writing metrics to a text file or just... not tracking anything. Then you forget which hyperparameters worked. Then you run the same failed experiment again.
+
+**trainlog is the experiment tracker that's actually available when you need it.**
+
+| | **trainlog** | **MLflow** | **Weights & Biases** |
+|---|---|---|---|
+| Setup time | **5 seconds** | ~15 minutes | ~5 minutes |
+| Requires account | ❌ No | ❌ No | ✅ Yes |
+| Requires running server | ❌ No | ✅ Yes | ❌ No (cloud) |
+| Works offline | ✅ Always | ⚠️ Partial | ❌ No |
+| Data stays local | ✅ Always | ✅ Yes | ❌ No |
+| Live anomaly detection | ✅ Built-in | ❌ No | ⚠️ Paid |
+| Hyperparameter suggestions | ✅ Built-in | ❌ No | ⚠️ Paid |
+| Auto-generated reports | ✅ Built-in | ❌ No | ❌ No |
+| Free forever | ✅ MIT | ✅ Apache | ⚠️ Usage limits |
+
+---
+
+## Features you'll actually use
+
+### ✅ Zero-friction tracking
+Wrap any loop. Log any value. Works with every framework.
+```python
+import trainlog
+
+with trainlog.run("gpt-finetune", tags=["nlp", "v3"]):
+    trainlog.log(lr=2e-5, epochs=3, model="gpt2")
+    for step, batch in enumerate(dataloader):
+        loss = model.train_step(batch)
+        trainlog.log(loss=loss.item(), step=step)
+```
+
+### ✅ Beautiful live dashboard
+```bash
+trainlog ui
+```
+Opens at `http://localhost:7000` — a fast, dark-mode single-page app with:
+- Searchable run list with **inline sparkline charts** in the sidebar
+- **Trend indicators** (↑ ↓) showing whether each metric is improving
+- **Side-by-side comparison** of any runs you select (best value highlighted)
+- **Auto-generated time-series charts** with gradient fills
+- **Metric progress bars** showing where the latest value sits in its historical range
+- Global statistics view — success rate, most-logged metrics, run timeline
+- Auto-refresh every 5 seconds — open while training, watch it update
+
+### ✅ Live anomaly detection — catch bad runs early
+```python
+trainlog.configure_watch(nan_check=True, divergence_window=5, plateau_window=15)
+
+with trainlog.run("training"):
+    for epoch in range(100):
+        trainlog.log(loss=compute_loss())
+        # Automatically warns if: loss → NaN, loss diverges for 5 epochs,
+        # loss plateaus for 15 epochs (and suggests adjusting LR)
+```
+Stop wasting GPU hours on runs that are already failing.
+
+### ✅ Hyperparameter suggestions
+```bash
+trainlog suggest accuracy
+```
+Analyzes your run history and tells you which hyperparameter values are statistically correlated with better results. No black box — plain English insights like:
+```
+Best config: lr=0.001 → avg accuracy 0.943 (vs 0.871 for other values, +8.2%)
+Next experiment: try batch_size=128 — larger batches correlated with +5.1% accuracy
+```
+
+### ✅ Auto-generated experiment reports
+```bash
+trainlog report --output results.md
+```
+Generates a thesis-ready markdown report with:
+- Summary statistics (total runs, completion rate, best configurations)
+- Chronological experiment timeline
+- Key findings (computed automatically)
+- Notes from all your runs
+- Optional AI narrative: `trainlog report --ai` (uses local Ollama, no API keys)
+
+### ✅ Generate a ready-to-run example
+```bash
+trainlog init                           # plain Python example
+trainlog init --framework pytorch       # PyTorch training loop
+trainlog init --framework sklearn       # scikit-learn grid search
+trainlog init --framework keras         # Keras callback
+```
+Generates a complete working script you can run immediately.
+
+### ✅ Works with every framework
+
+| Framework | How |
+|-----------|-----|
+| **PyTorch** | `trainlog.log(loss=loss.item(), acc=acc)` inside the training loop |
+| **scikit-learn** | `trainlog.log(**params, cv_score=score)` in your hyperparam loop |
+| **Keras / TF** | One-file `TrainlogCallback` for `model.fit()` |
+| **HuggingFace** | Custom `TrainerCallback` — see `examples/huggingface_example.py` |
+| **XGBoost / LightGBM** | Log in the eval callback |
+| **JAX / Flax** | Log at end of each training step |
+| **Plain Python** | Anything that produces a number |
+
+---
+
+## Full API reference
+
+### Python API
+
+```python
+import trainlog
+
+# ── Tracking ──────────────────────────────────────────────────────────────────
+with trainlog.run("name", tags=["tag1", "tag2"]) as run_id:
+    trainlog.log(accuracy=0.95, loss=0.05)          # log any key-value pairs
+    trainlog.note("Cosine LR schedule helped a lot") # attach plain-text notes
+
+trainlog.tag(run_id, "production")       # add tags after the fact
+trainlog.tag("experiment-name", "best")  # also works by name
+
+# ── Querying ──────────────────────────────────────────────────────────────────
+runs = trainlog.get_runs()                           # all runs, newest first
+best = trainlog.get_best_run("accuracy")             # highest final value
+best_low = trainlog.get_best_run("loss", mode="min") # lowest final value
+cmp = trainlog.compare_runs(1, 2, 3)                 # list of run dicts
+
+# ── Anomaly detection ─────────────────────────────────────────────────────────
+trainlog.configure_watch(
+    nan_check=True,           # warn on NaN/Inf values
+    divergence_window=5,      # warn if metric diverges for N steps
+    plateau_window=15,        # warn if metric plateaus for N steps
+    enabled=True,
+)
+
+# Or temporarily with a context manager:
+with trainlog.watch(divergence_window=3):
+    # stricter watch for this block
+    trainlog.log(loss=0.5)
+
+# ── Export & analysis ─────────────────────────────────────────────────────────
+trainlog.export_csv("results.csv")
+trainlog.export_json("results.json")
+trainlog.generate_report("report.md", use_ollama=False)
+suggestions = trainlog.suggest("accuracy", mode="max", top_n=3)
+trainlog.clear_all()  # deletes everything (irreversible)
+```
+
+### CLI reference
+
+```bash
+# Dashboard
+trainlog ui                             # open at localhost:7000
+trainlog ui --port 8080 --no-browser    # custom port, no auto-open
+
+# Inspect runs
+trainlog list                           # rich table, newest first
+trainlog list --limit 50
+trainlog compare 1 2 3                  # side-by-side metric comparison
+trainlog best accuracy                  # best run for a metric
+trainlog best loss --mode min
+
+# Annotate
+trainlog tag 42 production tuned        # add tags to run #42
+trainlog note 42 "Try cosine annealing" # add note to run #42
+
+# Analyse
+trainlog stats                          # aggregate statistics
+trainlog suggest accuracy               # hyperparameter recommendations
+trainlog suggest loss --mode min --top 5
+
+# Generate
+trainlog report                         # write report.md
+trainlog report -o results.md --ai      # with Ollama AI narrative
+trainlog init --framework pytorch       # generate example script
+
+# Export / clean
+trainlog export --format csv -o data.csv
+trainlog export --format json -o data.json
+trainlog clear                          # delete all (asks confirmation)
+```
+
+---
+
+## How it works
+
+- **SQLite** — `~/.trainlog/experiments.db`. One file. No server. Inspect it with any SQLite browser. Back it up with `cp`.
+- **Flask** — the dashboard is a local Flask server. Vanilla JS, Chart.js, zero npm, zero build step.
+- **Thread-local state** — each training job in its own thread gets an isolated run context. Concurrent experiments just work.
+- **Git-aware** — captures the current commit hash via `git rev-parse HEAD`. Silently skipped outside a git repo.
+- **Watch hooks** — anomaly detection runs inside every `log()` call. Zero external services, works offline.
+
+---
+
+## Quickstart with examples
+
+```bash
+trainlog init --framework pytorch -o train.py
+python train.py
+trainlog ui
+```
+
+That's the whole flow. Five commands. Zero config.
+
+---
+
+## Roadmap
+
+**Done ✅**
+- Live anomaly detection (`configure_watch`)
+- Auto-generated experiment reports (`trainlog report`, Ollama support)
+- Hyperparameter suggestions (`trainlog suggest`)
+- Quick-start example generator (`trainlog init`)
+- Sparkline charts in sidebar with trend indicators
+- Metric progress bars and trend arrows in detail view
+- Framework examples: PyTorch, scikit-learn, Keras, HuggingFace
+
+**Coming up**
+- [ ] `trainlog.log_artifact("model.pt")` — save file paths alongside metrics
+- [ ] Native PyTorch `TrainlogCallback` (pip-installable plugin)
+- [ ] VS Code extension — inline run summary on hover
+- [ ] `trainlog serve` — shareable read-only dashboard URL (ngrok/localtunnel)
+- [ ] Team sync via shared git-tracked SQLite
+- [ ] Slack / Discord webhook on run completion
+
+Have an idea? [Open a feature request](https://github.com/NaiaLorente/datalog/issues/new) — or submit a PR.
+
+---
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md). TL;DR: `pip install -e .`, make your change, open a PR.
+
+All contributions welcome — typos, docs, features, bug fixes.
+
+---
+
+## License
+
+MIT — use it however you want, forever.

mltrackr-0.3.0.dist-info/RECORD

@@ -0,0 +1,11 @@
+trainlog/__init__.py,sha256=ZXSeUsbzPhBdAja9AVUDcOewknZ-Ab4bFB6Kcgf8_8g,447
+trainlog/cli.py,sha256=RhDtsfSNrciidL2bak6gUp4x_pSeBdVrogzUdH0Lcjo,20927
+trainlog/core.py,sha256=LJx52c6X-tod2IV-rpJxdgTOvqZv2bpniqTVSsaCWS8,38849
+trainlog/dashboard/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+trainlog/dashboard/server.py,sha256=EME-fZAjRCsaSJc7Zfu1IlwEYHWXXBnRe47I1grLs7A,5709
+trainlog/dashboard/templates/index.html,sha256=3XsHJoBhmx7ttNROMHqdAkETARci_ayfFYW1QtP_12A,51787
+mltrackr-0.3.0.dist-info/METADATA,sha256=L-GjoaJXSTiSOVMsxm57BIEhzIxhNLrmQxvLkgkMKdw,14097
+mltrackr-0.3.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+mltrackr-0.3.0.dist-info/entry_points.txt,sha256=sOTYOsdc3BBNu5qqQsOScAFRbjN-YyO4ReGQLdfs3tM,46
+mltrackr-0.3.0.dist-info/top_level.txt,sha256=q9N7aVrJR-Ox3UAxVZBBAmgmRGIa6qfitE-kpS_j5_A,9
+mltrackr-0.3.0.dist-info/RECORD,,

mltrackr-0.3.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mltrackr-0.3.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+trainlog = trainlog.cli:cli

mltrackr-0.3.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+trainlog

trainlog/__init__.py

@@ -0,0 +1,14 @@
+from .core import (
+    run, log, note, tag,
+    get_runs, get_best_run, compare_runs, get_stats,
+    export_csv, export_json, clear_all,
+    generate_report, configure_watch, watch, suggest,
+)
+
+__all__ = [
+    "run", "log", "note", "tag",
+    "get_runs", "get_best_run", "compare_runs", "get_stats",
+    "export_csv", "export_json", "clear_all",
+    "generate_report", "configure_watch", "watch", "suggest",
+]
+__version__ = "0.3.0"