Metadata-Version: 2.4
Name: yy-workload-receipt
Version: 0.1.0
Summary: Deterministic, prompt-free receipts for AI workload consumption
Author: Cameron Emery
Maintainer: Cameron Emery
License-Expression: Apache-2.0
Project-URL: Homepage, https://github.com/yycore/yy-workload-receipt
Project-URL: Documentation, https://github.com/yycore/yy-workload-receipt#readme
Project-URL: Source, https://github.com/yycore/yy-workload-receipt
Project-URL: Issues, https://github.com/yycore/yy-workload-receipt/issues
Project-URL: Security, https://github.com/yycore/yy-workload-receipt/security
Keywords: ai,audit,provenance,receipts,usage
Classifier: Development Status :: 3 - Alpha
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
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 :: Software Development :: Quality Assurance
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Provides-Extra: dev
Requires-Dist: build==1.3.0; extra == "dev"
Requires-Dist: pytest==8.4.2; extra == "dev"
Requires-Dist: ruff==0.15.21; extra == "dev"
Requires-Dist: twine==6.2.0; extra == "dev"
Dynamic: license-file

# 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:

```console
python -m pip install yy-workload-receipt
```

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

```console
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:

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

The same commands are available through the module entry point:

```console
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:

```console
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:

```json
{"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

| Code | Meaning |
| ---: | --- |
| `0` | Receipt generation or verification completed successfully. |
| `1` | Input, build, I/O, or verification failed. |
| `2` | A partial JSONL receipt was written, but one or more input lines were rejected. |

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

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