Local-first, zero-server experiment tracking for researchers
Project description
bathos
Local-first, zero-server experiment tracking for researchers working across multiple projects and SLURM clusters.
Never lose track of what ran, what it produced, or whether results are still valid.
Install
uv tool install bathos
Quick start
# Register this project (creates .bth.toml + scripts/ skeleton)
bth init
# Run and track an experiment
bth run scripts/experiments/benchmark_tip3p.py -- --n-steps 1000 --out outputs/run1.parquet
# Query recent runs
bth ls --since 7d
bth show <run-id>
# Check if a result is still valid (compares recorded git hash to HEAD)
bth check outputs/run1.parquet
# Escape hatch: raw DuckDB SQL against the catalog
bth sql "SELECT project_slug, count(*) FROM runs GROUP BY 1"
Script conventions
bth init scaffolds the following structure in your project:
| Directory | Purpose | Naming | Tracked |
|---|---|---|---|
scripts/experiments/ |
Typer experiment runners | verb_noun.py |
Yes |
scripts/analysis/ |
Post-hoc analysis and plots | verb_noun.py |
Optional |
scripts/validation/ |
Correctness checks | verb_noun.py |
Optional |
scripts/benchmarks/ |
Performance benchmarks | verb_noun.py |
Yes |
scripts/data/ |
Data pipeline / conversion | verb_noun.py |
No |
scripts/slurm/ |
SLURM job files + env helpers | verb_noun.slurm |
Via wrapper |
scripts/debug/ |
Debug specific issues | YYMMDD_desc.py |
No |
scripts/explore/ |
Open-ended investigation | YYMMDD_desc.py |
No |
scripts/scratch/ |
Catchall / ephemeral | YYMMDD_desc.py |
No (gitignored) |
Python decorator
For Typer-based scripts that want direct integration:
import bth
@bth.experiment(name="benchmark_tip3p", tags=["tip3p", "nvt"])
def main(n_steps: int, out: Path):
...
SLURM
bth init generates a scripts/slurm/_bth_env.sh helper. Source it in job scripts to get automatic provenance capture for batch runs.
Catalog
All runs land in ~/.bth/catalog/ as DuckDB + Parquet. Query with bth ls, bth find, or raw bth sql.
Documentation
Full documentation is available at https://bathos.readthedocs.io.
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file bathos-0.1.0.tar.gz.
File metadata
- Download URL: bathos-0.1.0.tar.gz
- Upload date:
- Size: 142.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via: uv/0.11.15 {"installer":{"name":"uv","version":"0.11.15","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
86973dff56f4d3494ba82a89b69f462bbce46b83246fd2490b9cc6591f15850e
|
|
| MD5 |
d462b658601fe39d1ca0ac5cc85aaa60
|
|
| BLAKE2b-256 |
84882a5ef3ad51963f7c83342d4bfb09e6ae4a0170773b9e283bb4e5b716e615
|
File details
Details for the file bathos-0.1.0-py3-none-any.whl.
File metadata
- Download URL: bathos-0.1.0-py3-none-any.whl
- Upload date:
- Size: 27.9 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via: uv/0.11.15 {"installer":{"name":"uv","version":"0.11.15","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Ubuntu","version":"24.04","id":"noble","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":true}
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
909be0dcbdc00c3499f591fc11dd28d697045c7d73f7875e43e53c5242c8b5f6
|
|
| MD5 |
6df61271b6b1bf689780abaf7cff7a02
|
|
| BLAKE2b-256 |
ed6e053c8201d6184af4ebcd55f7824ada31b2512bd629e4ac209d870536e7fc
|
