YY Workload Receipt

YY Workload Receipt (wlr) creates deterministic, content-free receipts from AI workload usage metadata. It gives developers a small, local artifact they can verify after it is copied, archived, or shared without collecting prompts or tool payloads.

Use it to answer a narrow question:

What measurable resources and operations did this run consume, and has its receipt changed since it was generated?

The package has no runtime dependencies and makes no model or API calls.

Installation

Install a published release from PyPI:

python -m pip install yy-workload-receipt

Before the first PyPI release, install a release wheel directly:

python -m pip install ./yy_workload_receipt-0.1.0-py3-none-any.whl

Python 3.10 or newer is required.

Quick start

Generate a receipt from portable JSONL events and verify it later:

wlr receipt ./events.jsonl -o ./receipt
wlr verify ./receipt

The same commands are available through the module entry point:

python -m yy_workload_receipt receipt ./events.jsonl -o ./receipt
python -m yy_workload_receipt verify ./receipt

receipt writes exactly three files:

• summary.json: canonical aggregate measurements and explicit evidence gaps.
• report.md: a deterministic human-readable view of the same receipt.
• manifest.sha256: SHA-256 hashes covering both artifacts.

verify fails when either covered artifact is missing or changed, when the manifest is malformed or incomplete, or when the receipt directory contains an unexpected entry. Symbolic links cannot stand in for covered artifacts.

OpenAI Agents SDK usage adapter

The openai-usage adapter accepts the JSON object returned by the OpenAI Agents SDK public agents.usage.serialize_usage(...) helper. It does not inspect traces:

wlr receipt ./usage.json -o ./receipt --adapter openai-usage \
  --run-id run-001 --observed-at 2026-07-31T12:00:00Z \
  --provider openai --model example-model

In PowerShell, replace each trailing \ with a backtick. The adapter requires per-request usage entries. It reports disagreements between those entries and aggregate counters as evidence gaps rather than silently choosing one value. A sanitized input and generated receipt are available under examples/.

Portable JSONL format

Each non-empty line is one flat JSON event:

{"schema_version":"0.1","run_id":"run-001","seq":1,"ts":"2026-07-31T12:00:00Z","kind":"model_call","provider":"openai","model":"example-model","tokens_input":120,"tokens_output":30,"tokens_cached":0,"tokens_reasoning":0,"duration_ms":850}

Supported event kinds are model_call, tool_call, approval, retry, and error. See yy_workload_receipt.model.ALLOWED_FIELDS for the complete flat schema.

Unknown fields are discarded and reported without reproducing their names or values. Common content-bearing fields, including prompt, message, content, arguments, and payload fields, cause the entire line to be rejected without reproducing the field name or value in output.

Exit codes

Treat exit code 2 as incomplete evidence. Inspect the evidence gaps before using or sharing the receipt.

Privacy and security boundary

This project is designed for metadata, not content. Do not put prompts, messages, tool arguments, tool results, credentials, personal data, or raw exception messages into an input file. Its allowlist and rejection rules reduce accidental retention; they are not a substitute for reviewing data before it is shared.

The tool does not provide an observability dashboard, billing or cost estimate, security audit, compliance certification, or hardware recommendation. Missing observations remain explicit evidence gaps rather than assumed zeroes. The future hardware-analysis input boundary is documented, without an implementation, in docs/hardware-fit-input-contract.md.

Development

python -m venv .venv
python -m pip install -e ".[dev]"
python -m ruff check .
python -m pytest
python -m build
python -m twine check dist/*

See CONTRIBUTING.md for the initial contribution boundary, SUPPORT.md for support expectations, and SECURITY.md for private vulnerability reporting.

License

Licensed under Apache License 2.0. See LICENSE and NOTICE.