Metadata-Version: 2.4
Name: buro
Version: 0.0.4
Summary: Experiment tracker and lab journal made for humans — and sexy human-agent interaction for AI research
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: lz4>=4.3
Requires-Dist: psutil>=6.0
Requires-Dist: typer>=0.12
Provides-Extra: dev
Requires-Dist: mutmut<3,>=2.5; extra == 'dev'
Requires-Dist: numpy>=1.26; extra == 'dev'
Requires-Dist: pillow>=10.0; extra == 'dev'
Requires-Dist: psycopg2-binary>=2.9; extra == 'dev'
Requires-Dist: pytest>=8.3; extra == 'dev'
Requires-Dist: respx>=0.22; extra == 'dev'
Provides-Extra: gpu
Requires-Dist: pynvml>=12.0; extra == 'gpu'
Description-Content-Type: text/markdown

# buro

An experiment tracker and lab journal made for humans — and for sexy human ⇄ agent
interaction in AI research. Log your runs, metrics, and media to a
[Buro](https://github.com/dunnolab/buro) server.

## Install

```bash
pip install buro
```

## Quickstart

```python
import buro

run = buro.init(project="my-project")        # or "team-slug/my-project"
for step in range(100):
    buro.log({"loss": 1.0 / (step + 1), "acc": step / 100}, step=step)
buro.finish()
```

`init(project=...)` resolves the project against the server and auto-creates it
if it doesn't exist. `project` is a slug ref: `"slug"` (personal) or
`"team-slug/slug"` (team).

## Authenticate

Log in once on your machine:

```bash
buro login --api-url https://<your-buro-server>
buro whoami
```

The SDK resolves credentials in this order:

1. `buro.setup(api_key=..., api_url=...)` in code
2. `BURO_API_KEY` / `BURO_API_URL` environment variables
3. `~/.buro/credentials` (written by `buro login`)

On a cluster or in CI, the env-var path is usually easiest:

```bash
export BURO_API_KEY=buro_key_...
export BURO_API_URL=https://<your-buro-server>
```

## Log media

```python
buro.log({"sample": buro.Image("path/to/image.png")})   # numpy array or PIL image also work
# also available: buro.Audio, buro.Video
```

## Code tracking

Every run automatically snapshots the **source code that actually ran**, so the
compare view can show exactly what changed between two runs — not just which
hyperparameters differed.

It works by *tracing*, not scanning: buro watches the Python modules your run
imports and keeps the ones that are *your* code — everything outside the
standard library, your installed packages, and buro itself. Each file is
recorded under its **import path** (`models/encoder.py`, not an absolute path on
your machine), hashed, and uploaded once — identical files are shared across
runs, so a hyperparameter sweep that doesn't touch the code uploads nothing new.

Because it follows the imports rather than walking a directory, the snapshot is:

- **exactly your run's code** — the entry script plus the modules it imported,
  across packages; never a stray sweep of your whole repo, a sibling project, or
  config/secret files that happen to sit nearby;
- **the same on every machine** — a file is identified by how it's imported, so
  the same code on your laptop and on a cluster diffs as *unchanged*;
- **best-effort** — snapshotting never slows down or crashes your run.

Config files (`config.yaml`, lockfiles, …) are **not** captured — their values
already live in your run config (`buro.init(config=...)`). For an unusual layout,
or to pin exactly what's captured, set `BURO_CODE_ROOT=/path/to/project`.

## Docs

- `wandb` API compatibility: [`docs/wandb-compatibility.md`](docs/wandb-compatibility.md)
- Release/publishing process: [`docs/publishing.md`](docs/publishing.md)
