Metadata-Version: 2.4
Name: blackboxml
Version: 0.5.2
Summary: ML experiment tracking. Local, lightweight, framework-agnostic.
Home-page: https://github.com/sxa-lab/blackboxml
Author: SxA Lab
Author-email: sxalab.team@gmail.com
Project-URL: Documentation, https://blackboxml.readthedocs.io
Project-URL: Source, https://github.com/sxa-lab/blackboxml
Project-URL: Bug Tracker, https://github.com/sxa-lab/blackboxml/issues
Keywords: machine learning,experiment tracking,mlops,pytorch,keras,scikit-learn,training,metrics
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: matplotlib
Requires-Dist: click
Provides-Extra: keras
Requires-Dist: tensorflow>=2.0.0; extra == "keras"
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license-file
Dynamic: project-url
Dynamic: provides-extra
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# blackboxml

[![PyPI version](https://badge.fury.io/py/blackboxml.svg)](https://badge.fury.io/py/blackboxml)
[![Python Version](https://img.shields.io/pypi/pyversions/blackboxml.svg)](https://pypi.org/project/blackboxml/)
[![Tests](https://github.com/sxa-lab/blackboxml/actions/workflows/test.yml/badge.svg)](https://github.com/sxa-lab/blackboxml/actions/workflows/test.yml)
[![Downloads](https://static.pepy.tech/badge/blackboxml)](https://pepy.tech/project/blackboxml)
[![Docs](https://readthedocs.org/projects/blackboxml/badge/?version=latest)](https://blackboxml.readthedocs.io)

ML experiment tracking. Local, lightweight, framework-agnostic.

blackboxml logs your training runs as structured JSON. No accounts, no servers. It works with PyTorch, Keras, scikit-learn, or any Python training loop.


## Install

```bash
pip install blackboxml
pip install blackboxml[keras]  #(opt) TensorFlow support
```

Requires Python 3.10+.

## Usage

### @track decorator

```python
from blackboxml import track, MetricStore

@track(name="resnet_cifar10", tags=["pytorch", "cifar10"])
def train():
    metrics = MetricStore()
    for epoch in range(10):
        metrics.reset()
        for batch in dataloader:
            loss, acc = train_step(batch)
            metrics.update({"loss": loss, "acc": acc}, n=len(batch))
        yield metrics.compute()

train()
```

### Run context manager

```python
from blackboxml import Run

with Run(name="resnet_cifar10", tags=["pytorch"]) as run:
    for epoch in range(10):
        run.log({"loss": train_one_epoch(), "epoch": epoch})
```

### Keras callback

```python
from blackboxml.callback import BlackBoxCallback

model.fit(x_train, y_train, epochs=10,
          callbacks=[BlackBoxCallback(name="lstm_nlp", tags=["keras"])])
```

### scikit-learn

```python
from sklearn.ensemble import RandomForestClassifier
from sklearn.model_selection import cross_val_score
from blackboxml import Run

with Run(name="rf_search", tags=["sklearn"]) as run:
    for n in [50, 100, 200]:
        scores = cross_val_score(RandomForestClassifier(n_estimators=n), X, y, cv=5)
        run.log({"n_estimators": n, "accuracy": scores.mean()})
```

## CLI

```
$ bbml runs
NAME              DATE                 DURATION  STEPS  TAGS
----------------------------------------------------------------
resnet_cifar10    2026-03-10 14:22:01    13m 46s     10  pytorch, cifar10
lstm_nlp          2026-03-10 11:05:33     4m 12s      5  keras

$ bbml show resnet_cifar10
$ bbml clean
```

## What gets logged

Each run saves to `blackboxml_logs/<name>_<timestamp>/run.json`:

```json
{
  "name": "resnet_cifar10",
  "tags": ["pytorch", "cifar10"],
  "environment": {
    "git_commit": "a3f91bc",
    "git_dirty": false,
    "python": "3.11.2",
    "torch": "2.3.0",
    "hostname": "lab-gpu-01"
  },
  "start": "2026-03-10T14:22:01",
  "end": "2026-03-10T14:35:47",
  "duration_seconds": 826,
  "steps": [
    {"loss": 0.842, "acc": 0.65},
    {"loss": 0.671, "acc": 0.78}
  ]
}
```

Git commit, Python version, framework versions, and hostname are captured automatically.

## Visualisation

```python
from blackboxml import visualise_run

visualise_run("blackboxml_logs/resnet_cifar10_20260310_142201/run.json")
visualise_run("blackboxml_logs/resnet_cifar10_20260310_142201/run.json",
              save_path="plots/", show=False)
```

## Releases

| Version | Date | What changed |
|---------|------|-------------|
| [0.1.0](https://pypi.org/project/blackboxml/0.1.0/) | Apr 2025 | Initial release, Keras auto-logging, `visualise_metrics` |
| [0.2.0](https://pypi.org/project/blackboxml/0.2.0/) | Jul 2025 | Type hints, logging module, error handling |
| [0.5.0](https://pypi.org/project/blackboxml/0.5.0/) | Mar 2026 | Framework-agnostic rewrite, `@track`, `Run`, `MetricStore`, `bbml` CLI |
| [0.5.1](https://pypi.org/project/blackboxml/0.5.1/) | Apr 2026 | Migrated repo to sxa-lab, updated license classifier, added PyPI metadata |
| **0.5.2** | Apr 2026 | Documentation update, ReadTheDocs, updated package authorship |

## Contributing

See [Contributing Guidelines](https://github.com/sxa-lab/blackboxml/blob/main/.github/CONTRIBUTING.MD) to get started. Bug reports, feature requests, and pull requests are welcome.

- [Bug reports](https://github.com/sxa-lab/blackboxml/blob/main/.github/ISSUE_TEMPLATE/bug_report.md)
- [Feature requests](https://github.com/sxa-lab/blackboxml/blob/main/.github/ISSUE_TEMPLATE/feature_request.md)
- [Security policy](https://github.com/sxa-lab/blackboxml/blob/main/.github/SECURITY.MD)
- [Code of conduct](https://github.com/sxa-lab/blackboxml/blob/main/.github/CODE_OF_CONDUCT.MD)

## License

[Apache License 2.0](https://github.com/sxa-lab/blackboxml/blob/main/LICENSE)

## Maintainer

Maintained by [SxA Lab](https://github.com/sxa-lab)
