Skip to main content

onetrace

onetrace records one hash-chained receipt per stage of a Python pipeline, so anyone can verify the record offline, with a verifier that doesn't trust the code that wrote it, and compare two runs stage by stage. It does not check whether a pipeline's output is true: it shows what each recorded stage received and produced, and that the record hasn't been altered since.

  • What a run folder holds. Each stage's outputs, which can include documents, prompts and answers, and fingerprints (SHA-256 digests) of its inputs: inputs are fingerprinted, not stored. Treat run folders like logs that may contain sensitive data.
  • Overhead. 23.6–31.4 ms per recorded stage, in one run of the decorated worked examples on one shared machine; how it was measured, and how to measure it on yours, is below.
  • No telemetry. onetrace sends nothing anywhere, and recording a run makes no network connection. A test runs a decorated run and its verification under a guard that refuses any network access, and fails if anything tries (tests/test_no_telemetry.py). The one command that contacts a network is onetrace anchor, and only when you run it.

Install and quickstart

pip install onetrace

onetrace-verify, the reference verifier, comes with it.

A pipeline in two modules, with two decorators added and nothing else changed. Save steps.py:

import onetrace as ot

CORPUS = [
    "The warranty covers manufacturing defects for twelve months.",
    "Shipping delays are handled by the courier, not the warranty.",
    "Batteries have a separate six-month warranty.",
]


@ot.stage("retrieve", instrument=ot.pkg("word-overlap", "onetrace", kind="retriever", config={"top_k": 2}))
def retrieve(question: str) -> list[str]:
    words = set(question.lower().rstrip("?").split())
    return sorted(CORPUS, key=lambda p: -len(words & set(p.lower().rstrip(".").split())))[:2]

and app.py:

import onetrace as ot
from steps import retrieve


@ot.stage("answer", instrument=ot.pkg("first-passage", "onetrace", kind="model-call"))
def answer(question: str, passages: list[str]) -> str:
    return passages[0]


@ot.run(stages=["retrieve", "answer"])
def main(question: str) -> str:
    return answer(question, retrieve(question))


if __name__ == "__main__":
    print(main("How long does the warranty cover defects?"))

@ot.run marks the function that does the whole job once; @ot.stage marks each step. retrieve is defined in another module than the run, so the run lists its stages. ot.pkg names the installed distribution whose version is recorded: this demo names onetrace; your code names the library that does the work.

python app.py
The warranty covers manufacturing defects for twelve months.

The run is a folder under runs/. onetrace doctor checks the installation and verifies the most recent run:

onetrace doctor
...
7 checks; all passed

Switch recording off with ONETRACE_DISABLE=1: the decorators pass straight through and nothing is written. Take onetrace out by deleting the import and the decorators.

ONETRACE_DISABLE=1 python app.py
The warranty covers manufacturing defects for twelve months.

docs/quickstart.md starts from one stage, says what that run records and what it doesn't, and shows switching off on Windows too. To instrument an existing pipeline with a coding agent, give it docs/agents/instrument.md. Everything the decorators record, and their defaults, is in the manual's Decorators section. For full control without decorators, the Recorder API is in the manual.

How the overhead is measured

In one run, recording added 23.6–31.4 ms per stage: the median for each worked example. This is one run on one shared machine. To know the cost on your own machine, run tools/measure_overhead.py from this repository; it is not part of the installed package.

  • What it runs: the decorated version of each worked example under examples/: tiny (4 stage receipts), plain_python_control (9) and dag (7). Each is called in one Python process, writing its run to a fresh folder that is removed afterwards.
  • How many times: the script's defaults, 30 pairs per example, after 3 warm-up pairs that are discarded. Each pair is one run recorded and one with ONETRACE_DISABLE=1: the same functions, unrecorded. The two kinds alternate, so any drift in the machine falls on both.
  • The figure: for each pair, the recorded run's time minus the switched-off run's time, divided by the number of stage receipts the recorded run wrote; the median for each example.
  • The run: an AMD EPYC 7543 server, Linux, Python 3.12.11, with a quota of 12.75 CPUs, using the script's defaults. The host's load average when the run started: 2.89 over 1 minute, 5.69 over 5 minutes, 8.29 over 15 minutes. Medians per stage: tiny 26.3 ms, plain_python_control 31.4 ms, dag 23.6 ms.

Five verdicts

Every stage in a comparison gets exactly one of five verdicts, and nothing else:

  • same — the stage's output digest matches on both sides.
  • FIRST DIFFERENCE — the first stage, in order, whose output digest does not match.
  • downstream — after the first difference, still different; the divergence propagated.
  • reconverged — after diverging, a later stage's output matches again (different work, same result — this happens in practice and is reported honestly, not hidden).
  • COULD NOT CHECK — the stage can't be evaluated (an unimplemented format version, a declared boundary, a file that can't be read). This is not a pass, and it is not silently folded into "same."

A verdict is always about a stage's output. A difference in the instrument, its configuration, or the declared constants never changes a verdict by itself — it appears as an annotation alongside the ladder, naming exactly what differs, so a same result never hides that something about how the output was produced changed even though the bytes didn't.

diff and localize each also report one overall result word for the whole comparison (identical, diverged, not comparable, refused, or could not check, with exit codes 0/1/2/3/4 respectively — localize on a single run instead reports clean or located, exit 0 or 1); reproduce reports each stage as REPRODUCED, DIVERGED, or COULD NOT CHECK.

Documentation and the trust model

This package's source distribution ships its own documentation, rather than linking out to it: docs/ (the format in plain words, the five verdicts, the three verbs, one page per adapter, what onetrace does not claim, and docs/manual.md, the full developer manual), the stage-receipt format itself (an Internet-Draft, draft/), and the reference verifier with its rejection vectors (verifier/). A wheel install (pip install onetrace) does not include these — get the sdist instead: pip download --no-binary :all: --no-deps onetrace, then unpack the .tar.gz.

The verifier does not trust the SDK that emitted a record. Every record this SDK produces is checked the same way a record from any other emitter would be — the verifier reads bytes, not intentions, and it owes nothing to the code that wrote them.

What a run folder stores. Outputs are kept: a run folder holds each stage's outputs, which can include documents, prompts and answers. Inputs are fingerprinted, not stored: a receipt records an input's digest, length and trust class, never its bytes. So treat run folders like logs that may contain sensitive data. ot.chunks(..., keep_text=True) adds chunk text to them; without it, a chunk index holds digests only.

Stability

The current record format is stage-receipt/0.2 (format major version 0), specified by an Internet-Draft that has not yet reached RFC status. Anything in the format — required members, canonical-form rules, the rejection vectors — may still change before major version 1. Format major version is carried in every record: a manifest declaring one the reference verifier does not implement is refused outright, by name, rather than silently accepted (verify a manifest with an unrecognized format and it prints [REFUSED] manifest: format -- ... and exits non-zero); a verb comparing individual stages reports the stage's own verdict as COULD NOT CHECK for the same reason. Neither ever guesses.

License, security, and reporting a problem

Licensed under Apache-2.0 (LICENSE, in the source distribution).

This is pre-release software (see the classifiers in pyproject.toml). See SECURITY.md (in the source distribution) for what's in scope; report a vulnerability to onetrace@oneproof.dev, not as a public issue. For anything else — a bug, a question, a feature request — open an issue at github.com/shamiksaharcciit-oss/onetrace-issues.

Metadata

Release files for onetrace 0.2.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for onetrace 0.2.0
File Size Uploaded Provenance Actions
onetrace-0.2.0.tar.gz 5.4 MB Without provenance Details for onetrace-0.2.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for onetrace 0.2.0
File Interpreter ABI Platform Actions
onetrace-0.2.0-py3-none-any.whl Python 3 none any Details for onetrace-0.2.0-py3-none-any.whl

Total release size: 5.6 MB

Release files / onetrace-0.2.0.tar.gz

Download URL onetrace-0.2.0.tar.gz
Size 5.4 MB
Tags Source
SHA-256 checksum
How to use checksums
ff9932abb2cbd920f428d02b84e7fca83992c9d4e9bd8169e202341c69bd796f
BLAKE2b-256 checksum
How to use checksums
bd649bb6cba68ca2a52ed40dcbf0c4c5736f83f9ecf6c4fbfab74f612890281a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.10

Release files / onetrace-0.2.0-py3-none-any.whl

Download URL onetrace-0.2.0-py3-none-any.whl
Size 178.2 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0e8df2304582e1ab7f6ed7309b3d0ac4c4654897cd77e1c96194ce8a708ee481
BLAKE2b-256 checksum
How to use checksums
9e88b3b45db531b46d3734a2b71c149a8dfef681338187f92a827d59af51a3d8
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.12.10

Security for onetrace 0.2.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page