Metadata-Version: 2.4
Name: zvondb
Version: 0.2.0
Summary: Python SDK for the ML Artifact Registry
Author-email: Zvonimir Bednarcik <zvonimir.bednarcik@prosus.com>
License-Expression: MIT
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: httpx>=0.27.0
Requires-Dist: pydantic>=2.0.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0.0; extra == "dev"
Requires-Dist: pytest-httpx>=0.34.0; extra == "dev"
Requires-Dist: ruff>=0.8.0; extra == "dev"
Dynamic: license-file

# zvondb

Python SDK for the ML Artifact Registry — track artifacts, their lineage, and versions across ML experiments.

## Installation

```bash
pip install zvondb
```

## Quick start

```python
from zvondb import Registry

with Registry(project="my-project") as reg:
    exp = reg.ensure_experiment("my-experiment", parent="baseline")

    with exp.start_job(name="train", git_sha="abc123") as job:
        # Resolve input artifacts (walks parent chain)
        data = job.resolve("TrainingData")
        print(f"Using {data.name} v{data.version} from {data.path}")

        # ... train your model ...

        # Register output artifact
        job.create(
            "TrainedModel",
            storage_name="s3",
            description="Model trained on latest data",
            metadata={"val_loss": 0.15},
            tags=["v1"],
        )
        job.complete()
```

## Configuration

| Environment variable | Constructor param | Default | Description |
|---|---|---|---|
| `ZVONDB_URL` | `base_url` | `http://localhost:8000` | Registry server URL |
| `ZVONDB_API_KEY` | `api_key` | `""` | API authentication token |

## Key concepts

- **Registry** — entry point; manages projects and experiments
- **Experiment** — a branch of work that can inherit artifacts from a parent experiment
- **Job** — a unit of work that consumes and produces artifacts
- **Artifact** — a versioned, named piece of data with metadata, tags, and lineage

## W&B integration

```python
with exp.start_job(name="train", git_sha="abc123") as job:
    job.inject_wandb_env()  # Sets WANDB_API_KEY, WANDB_PROJECT, WANDB_RUN_ID etc.
    # Tracking URL auto-set to https://wandb.ai/{entity}/{project}/runs/{job_id}

    # Frameworks like Axolotl that respect W&B env vars just work.
    # For manual usage:
    import wandb
    wandb.init()
    wandb.log({"loss": 0.5})
```

## License

MIT
