unalloc 0.2.3__tar.gz → 0.3.0__tar.gz

{unalloc-0.2.3 → unalloc-0.3.0}/CHANGELOG.md

@@ -1,5 +1,20 @@
 # Changelog
 
+## 0.3.0 — 2026-10-04
+
+### Added
+- `report --json` carries a `provenance` block: unalloc version, window (live runs), alias-table digest, one entry per requested source with its status, payload SHA-256, byte count and row count, and a digest of the result body.
+- `report --keep-inputs DIR` writes the exact payloads the run parsed, named like the bundled fixtures, so the run can be replayed without the network.
+- `unalloc verify RESULT --inputs DIR` rebuilds a report from retained inputs. Exit 0 when it reproduces; 3 when an input is missing or its bytes changed at the same path; 4 when the inputs match but the result does not, naming a version or alias-table change; 5 when the recorded result does not conserve its own total.
+- Every command warns on stderr when the ledger is partial, naming each source that failed or had no input.
+- `Source.fetch_payload()` returns the raw provider payload; `fetch()` is now `parse(fetch_payload())` on the base class.
+
+### Fixed
+- A failed live source was printed to stderr and then dropped, so `report --json` gave no sign that its percentage covered only some sources. It is now recorded as `failed` in the provenance block.
+- With `--fixtures` and a missing fixture file, the "skipping" notice went to stdout and made `report --json` output invalid JSON. It goes to stderr.
+
+Attribution results are unchanged: every fixture report from 0.2.3 reproduces exactly.
+
 ## 0.2.3 — 2026-09-21
 
 ### Fixed

{unalloc-0.2.3 → unalloc-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: unalloc
-Version: 0.2.3
+Version: 0.3.0
 Summary: Find the AI spend nobody owns. Joins OpenCost allocation data with LLM provider bills and reports what's unattributed.
 Project-URL: Homepage, https://github.com/timurista/unalloc
 Project-URL: Issues, https://github.com/timurista/unalloc/issues
@@ -47,11 +47,11 @@ Description-Content-Type: text/markdown
 [![ci](https://github.com/timurista/unalloc/actions/workflows/ci.yml/badge.svg)](https://github.com/timurista/unalloc/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/timurista/unalloc/blob/main/LICENSE)
 [![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://github.com/timurista/unalloc/blob/main/pyproject.toml)
-[![Paper](https://img.shields.io/badge/paper-PDF-1f5b45.svg)](https://github.com/timurista/unalloc/blob/main/paper/unalloc-case-studies.pdf)
+[![arXiv](https://img.shields.io/badge/arXiv-2609.24991-b31b1b.svg)](https://arxiv.org/abs/2609.24991)
 [![Explorer](https://img.shields.io/badge/explorer-live-1f5b45.svg)](https://timurista.github.io/unalloc/explorer.html)
 [![DOI](https://zenodo.org/badge/1368528624.svg)](https://doi.org/10.5281/zenodo.22761012)
 
-**Project site: [timurista.github.io/unalloc](https://timurista.github.io/unalloc/)**, with the findings, case studies, [paper (PDF)](https://timurista.github.io/unalloc/paper/unalloc-case-studies.pdf), [blog post](https://timurista.github.io/unalloc/blog/who-pays-for-the-kv-cache.html), [GPU addendum](https://timurista.github.io/unalloc/blog/gpu-validation.html) and [ledger explorer](https://timurista.github.io/unalloc/explorer.html).
+**Project site: [timurista.github.io/unalloc](https://timurista.github.io/unalloc/)**, with the findings, case studies, [paper (arXiv:2609.24991)](https://arxiv.org/abs/2609.24991), [blog post](https://timurista.github.io/unalloc/blog/who-pays-for-the-kv-cache.html), [GPU addendum](https://timurista.github.io/unalloc/blog/gpu-validation.html) and [ledger explorer](https://timurista.github.io/unalloc/explorer.html).
 
 OpenCost tells you what your Kubernetes workloads cost. Your provider dashboard tells you what your OpenAI and Anthropic calls cost. Getting both into one view is possible today — OpenCost has an OpenAI plugin — but the answer still depends on a join nobody checks: the same dollar can arrive through both your gateway and your provider bill, and the labels that say who owns it are set per workload, not per pod template. `unalloc` pulls all four sources into one normalized ledger, joins them on a label dimension you choose, and reports the number your finance team keeps asking for: how much of this month's AI spend can't be attributed to any team — and how much of the rest was only rescued by a fallback key.
 
@@ -167,6 +167,42 @@ Configure sources by environment variable:
 
 Restrict the run with `--source` to avoid double counting: if your traffic goes through LiteLLM, prefer `--source opencost --source litellm` and skip the direct provider adapters, since the same tokens appear in both. The [end-to-end case study](#case-studies-and-paper) measures exactly how much that costs you if you forget.
 
+## Reproducing a result
+
+A percentage that ends up in a finance deck will be questioned later, after the
+source data has moved on. A path is not enough to answer that: a fixture or an
+export can be rewritten under the same name, and a live billing API answers a
+re-run with today's data. So `report --json` carries a `provenance` block, and
+`--keep-inputs` retains the exact payloads it parsed:
+
+```bash
+unalloc report -D team --json --keep-inputs runs/2026-09/ > runs/2026-09.json
+unalloc verify runs/2026-09.json --inputs runs/2026-09/
+# reproduced: 73.5% unallocated of $66,630.38, result sha256:…
+```
+
+The provenance block records the unalloc version, the window (live runs only;
+fixtures carry their own dates), a digest of the label alias table, and one
+entry per requested source: its status, the SHA-256 of the payload bytes, and
+the rows it produced. A source that failed or had no input is recorded as
+`failed` or `missing` rather than dropped, and every command warns on stderr
+when the ledger is partial, because the percentage then covers the loaded
+sources only.
+
+`verify` exits with a code that says which boundary moved:
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | Reproduced: same inputs, same result digest |
+| 3 | Cannot reconstruct: a retained input is missing, or its bytes changed |
+| 4 | Inputs match but the result differs: a rule or the tool changed in between |
+| 5 | The recorded result does not conserve its own total (a dollar counted twice or dropped) |
+
+A digest proves byte identity, not correctness. It cannot tell you a meter was
+accurate or a rule was fair, and it can only rebuild a result when the bytes
+it names were kept. Retained payloads contain your billing data; store them
+like the invoices they came from.
+
 ## How it works
 
 ```
@@ -193,7 +229,7 @@ Two design choices worth calling out:
 
 ## Case studies and paper
 
-Six studies push real (or realistically simulated) inference workloads through unalloc's own adapters, including a run with vLLM on an NVIDIA H100. They exposed nine defects in the tool along the way, all fixed with regression tests, and they're written up as a paper: **[paper/unalloc-case-studies.pdf](https://github.com/timurista/unalloc/blob/main/paper/unalloc-case-studies.pdf)**. For the readable version, see the [blog post](https://timurista.github.io/unalloc/blog/who-pays-for-the-kv-cache.html) and the [GPU addendum](https://timurista.github.io/unalloc/blog/gpu-validation.html) on the [project site](https://timurista.github.io/unalloc/).
+Six studies push real (or realistically simulated) inference workloads through unalloc's own adapters, including a run with vLLM on an NVIDIA H100. They exposed nine defects in the tool along the way, all fixed with regression tests, and they're written up as a paper: **[Who Pays for the KV Cache? (arXiv:2609.24991)](https://arxiv.org/abs/2609.24991)**, a preprint that has not been peer reviewed. The PDF built from this repository is at [paper/unalloc-case-studies.pdf](https://github.com/timurista/unalloc/blob/main/paper/unalloc-case-studies.pdf). For the readable version, see the [blog post](https://timurista.github.io/unalloc/blog/who-pays-for-the-kv-cache.html) and the [GPU addendum](https://timurista.github.io/unalloc/blog/gpu-validation.html) on the [project site](https://timurista.github.io/unalloc/).
 
 | Study | What runs | Headline |
 | --- | --- | --- |
@@ -245,6 +281,7 @@ What `unalloc` does is narrower: read all four sources yourself — OpenCost, a
 - [ ] Per-feature unit economics using the `quantity`/`unit` fields already carried on `CostRow`
 - [ ] Azure OpenAI and Bedrock adapters
 - [x] `--budget` mode: exit non-zero when unallocated share crosses a threshold, for CI
+- [x] Result provenance and `unalloc verify`: rebuild an earlier report from retained inputs, or say why it can't be
 - [ ] `--exclude label=value` on a source, so gateway traffic can be dropped from provider billing instead of whole sources
 - [ ] Warn when distinct raw label keys collide on one canonical key
 
@@ -259,16 +296,31 @@ ruff check . && pytest
 
 ## Citing
 
-If you use unalloc or its case studies, please cite the archived release. GitHub's "Cite this repository" button produces the same entry from [`CITATION.cff`](https://github.com/timurista/unalloc/blob/main/CITATION.cff).
+If you use the findings, please cite the paper, a preprint on arXiv ([arXiv:2609.24991](https://arxiv.org/abs/2609.24991), cs.DC):
+
+```bibtex
+@misc{urista_kvcache_2026,
+  author        = {Urista, Timothy},
+  title         = {Who Pays for the {KV} Cache? Attributing Shared {AI} Inference Spend Across {Kubernetes} and {LLM} Provider Bills},
+  year          = {2026},
+  eprint        = {2609.24991},
+  archivePrefix = {arXiv},
+  primaryClass  = {cs.DC},
+  doi           = {10.48550/arXiv.2609.24991},
+  url           = {https://arxiv.org/abs/2609.24991}
+}
+```
+
+If you use the software itself, cite the archived release. GitHub's "Cite this repository" button produces the same entry from [`CITATION.cff`](https://github.com/timurista/unalloc/blob/main/CITATION.cff).
 
-- **All versions:** [doi:10.5281/zenodo.22761012](https://doi.org/10.5281/zenodo.22761012), which always resolves to the latest release — currently 0.2.3, the code the paper describes
+- **All versions:** [doi:10.5281/zenodo.22761012](https://doi.org/10.5281/zenodo.22761012), which always resolves to the latest release — currently 0.3.0. The paper describes 0.2.3; 0.3.0 adds result provenance and `unalloc verify` and changes no attribution result
 - **Version 0.2.1:** [doi:10.5281/zenodo.22761013](https://doi.org/10.5281/zenodo.22761013)
 
 ```bibtex
 @software{urista_unalloc_2026,
   author  = {Urista, Timothy},
   title   = {unalloc: find the AI spend nobody owns},
-  version = {0.2.3},
+  version = {0.3.0},
   year    = {2026},
   doi     = {10.5281/zenodo.22761012},
   url     = {https://github.com/timurista/unalloc}

{unalloc-0.2.3 → unalloc-0.3.0}/README.md

@@ -5,11 +5,11 @@
 [![ci](https://github.com/timurista/unalloc/actions/workflows/ci.yml/badge.svg)](https://github.com/timurista/unalloc/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/license-Apache%202.0-blue.svg)](https://github.com/timurista/unalloc/blob/main/LICENSE)
 [![Python](https://img.shields.io/badge/python-3.11%2B-blue.svg)](https://github.com/timurista/unalloc/blob/main/pyproject.toml)
-[![Paper](https://img.shields.io/badge/paper-PDF-1f5b45.svg)](https://github.com/timurista/unalloc/blob/main/paper/unalloc-case-studies.pdf)
+[![arXiv](https://img.shields.io/badge/arXiv-2609.24991-b31b1b.svg)](https://arxiv.org/abs/2609.24991)
 [![Explorer](https://img.shields.io/badge/explorer-live-1f5b45.svg)](https://timurista.github.io/unalloc/explorer.html)
 [![DOI](https://zenodo.org/badge/1368528624.svg)](https://doi.org/10.5281/zenodo.22761012)
 
-**Project site: [timurista.github.io/unalloc](https://timurista.github.io/unalloc/)**, with the findings, case studies, [paper (PDF)](https://timurista.github.io/unalloc/paper/unalloc-case-studies.pdf), [blog post](https://timurista.github.io/unalloc/blog/who-pays-for-the-kv-cache.html), [GPU addendum](https://timurista.github.io/unalloc/blog/gpu-validation.html) and [ledger explorer](https://timurista.github.io/unalloc/explorer.html).
+**Project site: [timurista.github.io/unalloc](https://timurista.github.io/unalloc/)**, with the findings, case studies, [paper (arXiv:2609.24991)](https://arxiv.org/abs/2609.24991), [blog post](https://timurista.github.io/unalloc/blog/who-pays-for-the-kv-cache.html), [GPU addendum](https://timurista.github.io/unalloc/blog/gpu-validation.html) and [ledger explorer](https://timurista.github.io/unalloc/explorer.html).
 
 OpenCost tells you what your Kubernetes workloads cost. Your provider dashboard tells you what your OpenAI and Anthropic calls cost. Getting both into one view is possible today — OpenCost has an OpenAI plugin — but the answer still depends on a join nobody checks: the same dollar can arrive through both your gateway and your provider bill, and the labels that say who owns it are set per workload, not per pod template. `unalloc` pulls all four sources into one normalized ledger, joins them on a label dimension you choose, and reports the number your finance team keeps asking for: how much of this month's AI spend can't be attributed to any team — and how much of the rest was only rescued by a fallback key.
 
@@ -125,6 +125,42 @@ Configure sources by environment variable:
 
 Restrict the run with `--source` to avoid double counting: if your traffic goes through LiteLLM, prefer `--source opencost --source litellm` and skip the direct provider adapters, since the same tokens appear in both. The [end-to-end case study](#case-studies-and-paper) measures exactly how much that costs you if you forget.
 
+## Reproducing a result
+
+A percentage that ends up in a finance deck will be questioned later, after the
+source data has moved on. A path is not enough to answer that: a fixture or an
+export can be rewritten under the same name, and a live billing API answers a
+re-run with today's data. So `report --json` carries a `provenance` block, and
+`--keep-inputs` retains the exact payloads it parsed:
+
+```bash
+unalloc report -D team --json --keep-inputs runs/2026-09/ > runs/2026-09.json
+unalloc verify runs/2026-09.json --inputs runs/2026-09/
+# reproduced: 73.5% unallocated of $66,630.38, result sha256:…
+```
+
+The provenance block records the unalloc version, the window (live runs only;
+fixtures carry their own dates), a digest of the label alias table, and one
+entry per requested source: its status, the SHA-256 of the payload bytes, and
+the rows it produced. A source that failed or had no input is recorded as
+`failed` or `missing` rather than dropped, and every command warns on stderr
+when the ledger is partial, because the percentage then covers the loaded
+sources only.
+
+`verify` exits with a code that says which boundary moved:
+
+| Exit | Meaning |
+| --- | --- |
+| 0 | Reproduced: same inputs, same result digest |
+| 3 | Cannot reconstruct: a retained input is missing, or its bytes changed |
+| 4 | Inputs match but the result differs: a rule or the tool changed in between |
+| 5 | The recorded result does not conserve its own total (a dollar counted twice or dropped) |
+
+A digest proves byte identity, not correctness. It cannot tell you a meter was
+accurate or a rule was fair, and it can only rebuild a result when the bytes
+it names were kept. Retained payloads contain your billing data; store them
+like the invoices they came from.
+
 ## How it works
 
 ```
@@ -151,7 +187,7 @@ Two design choices worth calling out:
 
 ## Case studies and paper
 
-Six studies push real (or realistically simulated) inference workloads through unalloc's own adapters, including a run with vLLM on an NVIDIA H100. They exposed nine defects in the tool along the way, all fixed with regression tests, and they're written up as a paper: **[paper/unalloc-case-studies.pdf](https://github.com/timurista/unalloc/blob/main/paper/unalloc-case-studies.pdf)**. For the readable version, see the [blog post](https://timurista.github.io/unalloc/blog/who-pays-for-the-kv-cache.html) and the [GPU addendum](https://timurista.github.io/unalloc/blog/gpu-validation.html) on the [project site](https://timurista.github.io/unalloc/).
+Six studies push real (or realistically simulated) inference workloads through unalloc's own adapters, including a run with vLLM on an NVIDIA H100. They exposed nine defects in the tool along the way, all fixed with regression tests, and they're written up as a paper: **[Who Pays for the KV Cache? (arXiv:2609.24991)](https://arxiv.org/abs/2609.24991)**, a preprint that has not been peer reviewed. The PDF built from this repository is at [paper/unalloc-case-studies.pdf](https://github.com/timurista/unalloc/blob/main/paper/unalloc-case-studies.pdf). For the readable version, see the [blog post](https://timurista.github.io/unalloc/blog/who-pays-for-the-kv-cache.html) and the [GPU addendum](https://timurista.github.io/unalloc/blog/gpu-validation.html) on the [project site](https://timurista.github.io/unalloc/).
 
 | Study | What runs | Headline |
 | --- | --- | --- |
@@ -203,6 +239,7 @@ What `unalloc` does is narrower: read all four sources yourself — OpenCost, a
 - [ ] Per-feature unit economics using the `quantity`/`unit` fields already carried on `CostRow`
 - [ ] Azure OpenAI and Bedrock adapters
 - [x] `--budget` mode: exit non-zero when unallocated share crosses a threshold, for CI
+- [x] Result provenance and `unalloc verify`: rebuild an earlier report from retained inputs, or say why it can't be
 - [ ] `--exclude label=value` on a source, so gateway traffic can be dropped from provider billing instead of whole sources
 - [ ] Warn when distinct raw label keys collide on one canonical key
 
@@ -217,16 +254,31 @@ ruff check . && pytest
 
 ## Citing
 
-If you use unalloc or its case studies, please cite the archived release. GitHub's "Cite this repository" button produces the same entry from [`CITATION.cff`](https://github.com/timurista/unalloc/blob/main/CITATION.cff).
+If you use the findings, please cite the paper, a preprint on arXiv ([arXiv:2609.24991](https://arxiv.org/abs/2609.24991), cs.DC):
+
+```bibtex
+@misc{urista_kvcache_2026,
+  author        = {Urista, Timothy},
+  title         = {Who Pays for the {KV} Cache? Attributing Shared {AI} Inference Spend Across {Kubernetes} and {LLM} Provider Bills},
+  year          = {2026},
+  eprint        = {2609.24991},
+  archivePrefix = {arXiv},
+  primaryClass  = {cs.DC},
+  doi           = {10.48550/arXiv.2609.24991},
+  url           = {https://arxiv.org/abs/2609.24991}
+}
+```
+
+If you use the software itself, cite the archived release. GitHub's "Cite this repository" button produces the same entry from [`CITATION.cff`](https://github.com/timurista/unalloc/blob/main/CITATION.cff).
 
-- **All versions:** [doi:10.5281/zenodo.22761012](https://doi.org/10.5281/zenodo.22761012), which always resolves to the latest release — currently 0.2.3, the code the paper describes
+- **All versions:** [doi:10.5281/zenodo.22761012](https://doi.org/10.5281/zenodo.22761012), which always resolves to the latest release — currently 0.3.0. The paper describes 0.2.3; 0.3.0 adds result provenance and `unalloc verify` and changes no attribution result
 - **Version 0.2.1:** [doi:10.5281/zenodo.22761013](https://doi.org/10.5281/zenodo.22761013)
 
 ```bibtex
 @software{urista_unalloc_2026,
   author  = {Urista, Timothy},
   title   = {unalloc: find the AI spend nobody owns},
-  version = {0.2.3},
+  version = {0.3.0},
   year    = {2026},
   doi     = {10.5281/zenodo.22761012},
   url     = {https://github.com/timurista/unalloc}

{unalloc-0.2.3 → unalloc-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "unalloc"
-version = "0.2.3"
+version = "0.3.0"
 description = "Find the AI spend nobody owns. Joins OpenCost allocation data with LLM provider bills and reports what's unattributed."
 readme = "README.md"
 requires-python = ">=3.11"

{unalloc-0.2.3 → unalloc-0.3.0}/src/unalloc/__init__.py

@@ -2,5 +2,5 @@
 
 from __future__ import annotations
 
-__version__ = "0.2.3"
+__version__ = "0.3.0"
 __all__ = ["__version__"]