Metadata-Version: 2.4
Name: benchpress-sdk
Version: 0.1.0
Summary: Emit structured benchmark records from your training and experiment scripts.
Author: Mohammad Mehabadi
License: Apache-2.0
Project-URL: Homepage, https://benchpress.run
Project-URL: Repository, https://github.com/benchpress-run/benchpress-sdk
Keywords: benchmark,experiment-tracking,metrics,logging,machine-learning
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
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: Topic :: Scientific/Engineering
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.6
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Provides-Extra: sdk
Requires-Dist: numpy>=1.20; extra == "sdk"
Requires-Dist: pandas>=1.3; extra == "sdk"
Dynamic: license-file

# benchpress-sdk

Emit structured benchmark records from your training and experiment scripts.

`benchpress-sdk` is a tiny, dependency-free logging shim. You call a few
functions — `start_run`, `log_metrics`, `log_device`, `log_artifact`,
`end_run` — and it writes structured records to **stdout**, one per line, in a
simple `[BENCH:<KIND>] <json>` format. A runner that launches your script reads
those lines back. Because everything crosses the process boundary as text on
stdout, your script needs nothing from the runner and stays decoupled from it.

- **Zero required dependencies** — pure standard library at import time.
- **Python 3.6+** — works in older training environments.
- **Framework-agnostic** — metric values from torch / numpy / plain floats are
  coerced for you.

## Install

```bash
pip install benchpress-sdk
```

```python
import benchpress
```

The distribution is named `benchpress-sdk`; you import it as `benchpress`.

## Quickstart

```python
import benchpress

params = benchpress.start_run(run_name="demo", params={"lr": 0.01, "epochs": 3})
benchpress.log_device("cpu")

for step in range(params["epochs"]):
    loss = 1.0 / (step + 1)
    benchpress.log_metrics({"loss": loss}, step=step)

benchpress.end_run("FINISHED")
```

Run it and the records appear on stdout:

```
[BENCH:START]   {"run_id": "...", "run_name": "demo", ...}
[BENCH:DEVICE]  {"device": "cpu", ...}
[BENCH:METRICS] {"step": 0, "metrics": {"loss": 1.0}, ...}
...
[BENCH:END]     {"status": "success", "duration": ...}
```

## Declaring inputs

A runner can inject `--key=value` flags. Declare each one inline, next to the
code that uses it:

```python
from benchpress.sdk import DeclareArg

data_path = DeclareArg("data_path", str, "./data.csv", "Path to the input file")
```

Run standalone and the default is used; run under a runner and the injected
value is picked up.

## Saving synthetic arrays (optional)

`save_synthetic` writes an array as `.npy` plus a flat `.csv`. It needs numpy +
pandas, kept as an optional extra so the base install stays dependency-free:

```bash
pip install "benchpress-sdk[sdk]"
```

## The wire format

One record per line on stdout:

```
[BENCH:<KIND>] <single-line-json>
```

`<KIND>` is one of `START`, `DEVICE`, `METRICS`, `ARTIFACT`, `TAG`, `END`.
Lines that don't match are treated as ordinary log output and passed through
untouched. Each record is flushed immediately, so a reader sees it in real
time — even across a pipe into WSL or a container.

## License

Apache-2.0 — see [LICENSE](LICENSE) and [NOTICE](NOTICE).

Learn more at [benchpress.run](https://benchpress.run).
