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.

python -m pip install viper-provenance

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

Create a project

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

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.

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:

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

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

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:

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 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.

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

Documentation

• Getting started
• Python and CLI API
• How VIPER works
• Formal protocol
• Versioning
• Contributing

Development

VIPER uses the mantra Conda environment for repository checks.

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

The testing guide 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.