Metadata-Version: 2.4
Name: viper-provenance
Version: 0.1.0a2
Summary: Run and verify reproducible ML experiments with machine-readable guardrails for agents.
Author-email: Peter Driscoll <peterdriscoll27@gmail.com>
Maintainer-email: Peter Driscoll <peterdriscoll27@gmail.com>
License-Expression: Apache-2.0
Project-URL: Repository, https://github.com/pvd232/viper
Project-URL: Documentation, https://github.com/pvd232/viper/tree/main/docs
Project-URL: Issues, https://github.com/pvd232/viper/issues
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Topic :: Scientific/Engineering :: Information Analysis
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: huggingface_hub<2,>=1
Requires-Dist: httpx<1,>=0.28
Requires-Dist: numpy<3,>=2
Requires-Dist: pydantic<3,>=2.12
Requires-Dist: PyYAML<7,>=6
Requires-Dist: torch<3,>=2.6
Requires-Dist: torchdata==0.11.0
Provides-Extra: test
Requires-Dist: pyright<2,>=1.1.400; extra == "test"
Requires-Dist: pytest<10,>=9; extra == "test"
Requires-Dist: ruff<1,>=0.12; extra == "test"
Provides-Extra: release
Requires-Dist: build<2,>=1.2; extra == "release"
Requires-Dist: twine<7,>=6; extra == "release"
Dynamic: license-file

# VIPER

Run and verify reproducible ML experiments with machine-readable guardrails for
agents.

VIPER freezes an experiment before execution. The frozen plan identifies the
source commit, stage code, parameters, inputs, environment, and reproducibility
controls. After execution, VIPER verifies the files and relationships that
support the result.

## Install

VIPER requires Python 3.11 or newer.

```bash
python -m pip install viper-provenance
```

The distribution installs the `viper` Python package and the `viper` command.

## Create a project

```bash
viper init my-project --package my_project
cd my-project
python -m pip install -e ".[test]"
python -m pytest -q
```

The generated project contains one decorated function for each stage kind. The
project owns those functions, its parameter classes, its metrics, and its
artifact loaders.

## Define a stage

```python
from pathlib import Path

import viper


class TrainParameters(viper.parameters.Train):
    epochs: int
    learning_rate: float


@viper.train_stage(parameter_model=TrainParameters)
def train(context: viper.StageContext[TrainParameters]) -> None:
    dataset: Path = context.inputs["dataset"]
    weights_path: Path = context.artifacts["parameters"]
    run_training(
        dataset=dataset,
        weights_path=weights_path,
        epochs=context.params.epochs,
        learning_rate=context.params.learning_rate,
    )
```

Freezing identifies `train`, `TrainParameters`, and their source files by
repository-relative path, SHA-256 digest, and byte count. Execution constructs
the validated `TrainParameters` value and passes it through `context.params`.
The `parameters` artifact key is VIPER's required slot for trained model state;
`weights_path` is the destination used by the project code.

## Run a frozen plan

Commit the project source before freezing the plan.

```bash
viper freeze-run path/to/draft.yaml --repository-root .
viper preflight path/to/run/spec.yaml --repository-root .
viper run path/to/run/spec.yaml --repository-root .
```

A project can start the same coordinator from its Python entrypoint:

```python
if __name__ == "__main__":
    viper.run(train)
```

```bash
python train.py \
  --run path/to/run/spec.yaml \
  --stage train \
  --repository-root .
```

Both entrypoints execute inside the selected host. The same commands work in a
local terminal and in a terminal connected to a provisioned VM.

## Inspect the result

```bash
viper --json verify-run path/to/resolved.yaml \
  --trust-source https://github.com/example/project
viper --json lineage path/to/resolved.yaml \
  --trust-source https://github.com/example/project
viper --json compare-runs left.yaml right.yaml \
  --trust-source https://github.com/example/project
```

`verify-run` starts from `ResolvedRun`, retrieves every hash-bound dependency,
checks the frozen plan, validates each attempt, and returns the accepted stage
and measurement summary. JSON mode emits one document with a stable operation
name and error code.

## What VIPER verifies

For one terminal run, VIPER checks the following chain:

```text
RunSpec
  -> exact stage specifications
  -> typed stage invocations
  -> resolved inputs and artifacts
  -> measurements and metric recomputation
  -> canonical attempt files
  -> ResolvedRun
```

Each file reference carries a path, byte count, and SHA-256 digest. Each stage
invocation carries the selected implementation and a serializable binding for
the values delivered to the callable. Runtime evidence describes the host,
compute backend, Python environment, and applied reproducibility controls.

An evaluation measures one candidate. A benchmark applies one evaluation
definition across candidates and requires an independently executed
confirmation. `viper execute-benchmark` produces that confirmation and verifies
artifact parity plus the declared metric criteria.

## Example

[`examples/synthetic`](https://github.com/pvd232/viper/tree/main/examples/synthetic)
contains the project generated by
`viper init`, an authored download stage, and project tests. The release test
copies that project into a temporary Git repository and executes acquisition,
the five-stage candidate plan, benchmark confirmation, and terminal
verification.

```bash
python -m pytest tests/test_generated_project_acceptance.py -q -m release
```

## Documentation

- [Getting started](https://github.com/pvd232/viper/blob/main/docs/tutorials/getting-started.md)
- [Python and CLI API](https://github.com/pvd232/viper/blob/main/docs/reference/api.md)
- [How VIPER works](https://github.com/pvd232/viper/blob/main/docs/explanation/how-viper-works.md)
- [Formal protocol](https://github.com/pvd232/viper/blob/main/docs/reference/protocol.md)
- [Versioning](https://github.com/pvd232/viper/blob/main/docs/reference/versioning.md)
- [Contributing](https://github.com/pvd232/viper/blob/main/CONTRIBUTING.md)

## Development

VIPER uses the `mantra` Conda environment for repository checks.

```bash
conda activate mantra
make check
make check-integration
make check-release
```

The [testing guide](https://github.com/pvd232/viper/blob/main/docs/development/testing.md)
defines the cost tiers, domain
markers, CI jobs, installed-wheel checks, and live CUDA gate.

## License

VIPER is licensed under the
[Apache License 2.0](https://github.com/pvd232/viper/blob/main/LICENSE).
