unalloc 0.3.0__tar.gz → 0.3.2__tar.gz

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

@@ -1,5 +1,26 @@
 # Changelog
 
+## 0.3.2 — 2026-10-05
+
+### Added
+- `unalloc --version` (and `-V`), alongside the existing `unalloc version` command.
+- `reconcile --fixtures` reconciles against bundled sample invoices when no `--invoice` is given: Anthropic ties out within tolerance and OpenAI shows an $381.44 (8.6%) gap, so the invoice check can be demoed without inventing a number. An explicit `--invoice` replaces the bundled ones.
+
+### Changed
+- The bundled LiteLLM fixture now routes to Azure OpenAI, Vertex AI and Bedrock instead of the OpenAI and Anthropic APIs, so the default four-source demo no longer counts gateway spend that the direct provider fixtures could also bill. Dollar amounts are unchanged: the fixture headline is still 73.5% of $66,630.38. `src/unalloc/fixtures/README.md` documents what each fixture covers.
+- The quick start shows `--fallback cost_center` and `reconcile --fixtures`; `make demo` uses the bundled invoices.
+
+Fixture attribution results are unchanged. The LiteLLM fixture bytes changed, so its provenance digest differs from 0.3.1.
+
+## 0.3.1 — 2026-10-05
+
+### Documentation
+- Prominent source-overlap warning: the CLI defaults to all four sources and appends normalized rows without automatic economic deduplication. Source selection must account for both coverage and overlap.
+- Research summaries describe disagreement between allocation rules rather than established overcharging or mispricing. GPU queue claims are limited to no waiting observed at about 0.5-second telemetry sampling.
+- Synthetic billing and illustrative allocation pools, and the one-GPU/model/run-per-load limits, are explicit.
+
+Accounting behavior and source defaults are unchanged. This patch includes the corrected README in package metadata and distributions; provenance reports version 0.3.1.
+
 ## 0.3.0 — 2026-10-04
 
 ### Added

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: unalloc
-Version: 0.3.0
+Version: 0.3.2
 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
@@ -55,6 +55,8 @@ Description-Content-Type: text/markdown
 
 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.
 
+> **Avoid double counting before interpreting totals.** By default, the CLI requests all four sources: OpenCost, LiteLLM, OpenAI and Anthropic. It appends their normalized `CostRow`s into one ledger; it does **not** automatically deduplicate the same economic spend across sources. Gateway charges can also appear in provider bills (or OpenCost plugin output). Choose non-overlapping sources for your setup. For traffic fully covered by LiteLLM, use `--source opencost --source litellm` only if OpenCost excludes those same provider charges. Direct-provider-only traffic needs a separate coverage plan. The bundled fixtures are built not to overlap: their LiteLLM rows route to Azure OpenAI, Vertex AI and Bedrock, which unalloc does not pull directly, and their OpenCost rows are self-hosted workloads only ([fixture notes](https://github.com/timurista/unalloc/blob/main/src/unalloc/fixtures/README.md)). Fixture totals are synthetic demonstrations, not validated unique spend.
+
 ## The output
 
 ```
@@ -86,11 +88,11 @@ $ unalloc labels --fixtures --dimension team
 ┡━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
 │  1 │ opencost │ inference/vllm-llama-70b  │ $19,147.10 │ cluster, controller, ...   │
 │  2 │ opencost │ __idle__                  │  $6,070.00 │ cluster                    │
-│  3 │ litellm  │ claude-opus-5             │  $5,412.75 │ environment, model         │
+│  3 │ litellm  │ bedrock/claude-opus-5     │  $5,412.75 │ environment, model         │
 └────┴──────────┴───────────────────────────┴────────────┴────────────────────────────┘
 ```
 
-`inference/vllm-llama-70b` is the whole pitch: $19K of GPU spend carrying a `costCenter` label but no `team`, sitting next to $5K of Claude API spend on an unlabeled legacy key. Two systems, one gap, no existing tool that shows them in the same table.
+`inference/vllm-llama-70b` is the whole pitch: $19K of GPU spend carrying a `costCenter` label but no `team`, sitting next to $5K of Claude spend routed through the gateway to Bedrock on an unlabeled legacy key. Two systems, one gap, no existing tool that shows them in the same table.
 
 Add a fallback and unalloc says how much of the "allocated" spend only got there through it, so a fallback onto something that is not an owner can't hide inside the headline:
 
@@ -101,11 +103,30 @@ $ unalloc report --fixtures -D team --fallback namespace
 │ $23,745.60 attributed only via fallback (namespace)              │
 ```
 
+Then check the ledger against what the providers billed. With `--fixtures`, the bundled sample invoices are used:
+
+```
+$ unalloc reconcile --fixtures
+┏━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┓
+┃ Source    ┃     Ledger ┃   Invoice ┃            Delta ┃ Status     ┃
+┡━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━┩
+│ anthropic │  $8,737.03 │ $8,779.84 │  $-42.81 (-0.5%) │ matched    │
+│ litellm   │ $11,444.27 │         — │                — │ no-invoice │
+│ openai    │  $4,031.36 │ $4,412.80 │ $-381.44 (-8.6%) │ under      │
+│ opencost  │ $42,417.72 │         — │                — │ no-invoice │
+└───────────┴────────────┴───────────┴──────────────────┴────────────┘
+The ledger does not tie out. Attribution built on this is not defensible yet.
+```
+
+Anthropic agrees within the 1% tolerance. OpenAI billed $381 more than its costs endpoint reported, so any attribution built on that ledger understates OpenAI spend until the gap is explained.
+
 ## Install
 
 ```bash
-pip install unalloc          # or: uv tool install unalloc
-unalloc report --fixtures    # works immediately, no infrastructure needed
+pip install unalloc                               # or: uv tool install unalloc
+unalloc report --fixtures --fallback cost_center  # works immediately, no infrastructure needed
+unalloc reconcile --fixtures                      # ledger vs. sample invoices
+unalloc --version
 ```
 
 From a clone:
@@ -119,11 +140,11 @@ make check    # ruff + pytest, same as CI
 Or as a container, which needs no Python on the host:
 
 ```bash
-docker build -t unalloc:0.2.0 .
-docker run --rm unalloc:0.2.0 report --fixtures -D team
+docker build -t unalloc .
+docker run --rm unalloc report --fixtures -D team
 
 # against real systems, reachable from the container
-docker run --rm --network host --env-file .env unalloc:0.2.0 report -D team
+docker run --rm --network host --env-file .env unalloc report -D team
 ```
 
 Copy `.env.example` to `.env` for the source configuration. unalloc stores
@@ -165,7 +186,9 @@ Configure sources by environment variable:
 | `ANTHROPIC_ADMIN_KEY` | Anthropic org admin key (cost report endpoint, sent as `x-api-key`) |
 | `UNALLOC_OPENAI_URL`, `UNALLOC_ANTHROPIC_URL` | Optional overrides for the public API roots, e.g. a proxy |
 
-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.
+Restrict the run with `--source` to avoid double counting: if LiteLLM covers all provider traffic and OpenCost excludes overlapping provider charges, use `--source opencost --source litellm` and skip the direct provider adapters. Confirm coverage and overlap for your setup. The [end-to-end case study](#case-studies-and-paper) demonstrates the resulting double count with synthetic billing and invoices; it does not measure customer savings.
+
+The case-study invoices and monthly cost pools are synthetic or illustrative. The GPU result covers one H100, one model and one two-minute run per load; waiting-request telemetry was sampled about every 0.5 seconds. Allocation-rule disagreement does not establish a uniquely correct charge or production savings.
 
 ## Reproducing a result
 
@@ -234,11 +257,11 @@ Six studies push real (or realistically simulated) inference workloads through u
 | Study | What runs | Headline |
 | --- | --- | --- |
 | [`kv_cache`](https://github.com/timurista/unalloc/blob/main/case_studies/kv_cache) | Discrete-event vLLM-style engine: paged KV blocks, prefix caching, continuous batching, preemption | Step-time metering shows ~0% idle once any request is in flight; KV-memory metering leaves a large share of the bill unowned |
-| [`torch_kv`](https://github.com/timurista/unalloc/blob/main/case_studies/torch_kv) | A from-scratch PyTorch decoder with a real KV cache serving a 4-tenant trace | Per-token showback over-charges a RAG tenant by 33 points of the pool ($5.7K/month) vs measured compute |
+| [`torch_kv`](https://github.com/timurista/unalloc/blob/main/case_studies/torch_kv) | A from-scratch PyTorch decoder with a real KV cache serving a 4-tenant trace | Token and measured-compute allocation rules differ by 33 points for a RAG tenant ($5.7K of an illustrative monthly pool) |
 | [`distributed`](https://github.com/timurista/unalloc/blob/main/case_studies/distributed) | Tensor and pipeline parallel on `torch.distributed` (gloo), verified against a single-process reference | Owner label on LeaderWorkerSet leaders only: 66% unallocated; falling back to `name` "fixes" it by sending 61% to a Helm chart name |
 | [`hybrid_e2e`](https://github.com/timurista/unalloc/blob/main/case_studies/hybrid_e2e) | The real CLI as a subprocess against live mock OpenCost / LiteLLM / OpenAI / Anthropic APIs (Postgres-backed LiteLLM in the dev container) | Enabling every source double counts $11.8K; reading only page one of the billing APIs reports 25% of spend |
 | [`use_cases`](https://github.com/timurista/unalloc/blob/main/case_studies/use_cases) | Labeling Pareto, per-feature unit economics, self-host break-even, CI budget gate | Three label fixes take a 67%-unallocated org under 10% |
-| [`gpu_validation`](https://github.com/timurista/unalloc/blob/main/case_studies/gpu_validation) | Real vLLM 0.29 serving Qwen2.5-7B on a DigitalOcean H100, driven with the simulator's tenants ([runbook](https://github.com/timurista/unalloc/blob/main/case_studies/gpu_validation/RUNBOOK.md), [evidence](https://github.com/timurista/unalloc/tree/main/case_studies/results/gpu_validation/evidence)) | Token metering over-charges search by 12–14 points vs time share; GPU "utilization" reads 97% at 2 req/s and 99% at 16 req/s |
+| [`gpu_validation`](https://github.com/timurista/unalloc/blob/main/case_studies/gpu_validation) | Real vLLM 0.29 serving Qwen2.5-7B on a DigitalOcean H100, driven with the simulator's tenants ([runbook](https://github.com/timurista/unalloc/blob/main/case_studies/gpu_validation/RUNBOOK.md), [evidence](https://github.com/timurista/unalloc/tree/main/case_studies/results/gpu_validation/evidence)) | Token and equal time-share allocation rules differ by 12–14 points for search; GPU "utilization" reads 97% at 2 req/s and 99% at 16 req/s |
 
 ```bash
 make research            # build ./.venv-research: CPU torch, notebook tooling, typst

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

@@ -13,6 +13,8 @@
 
 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.
 
+> **Avoid double counting before interpreting totals.** By default, the CLI requests all four sources: OpenCost, LiteLLM, OpenAI and Anthropic. It appends their normalized `CostRow`s into one ledger; it does **not** automatically deduplicate the same economic spend across sources. Gateway charges can also appear in provider bills (or OpenCost plugin output). Choose non-overlapping sources for your setup. For traffic fully covered by LiteLLM, use `--source opencost --source litellm` only if OpenCost excludes those same provider charges. Direct-provider-only traffic needs a separate coverage plan. The bundled fixtures are built not to overlap: their LiteLLM rows route to Azure OpenAI, Vertex AI and Bedrock, which unalloc does not pull directly, and their OpenCost rows are self-hosted workloads only ([fixture notes](https://github.com/timurista/unalloc/blob/main/src/unalloc/fixtures/README.md)). Fixture totals are synthetic demonstrations, not validated unique spend.
+
 ## The output
 
 ```
@@ -44,11 +46,11 @@ $ unalloc labels --fixtures --dimension team
 ┡━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
 │  1 │ opencost │ inference/vllm-llama-70b  │ $19,147.10 │ cluster, controller, ...   │
 │  2 │ opencost │ __idle__                  │  $6,070.00 │ cluster                    │
-│  3 │ litellm  │ claude-opus-5             │  $5,412.75 │ environment, model         │
+│  3 │ litellm  │ bedrock/claude-opus-5     │  $5,412.75 │ environment, model         │
 └────┴──────────┴───────────────────────────┴────────────┴────────────────────────────┘
 ```
 
-`inference/vllm-llama-70b` is the whole pitch: $19K of GPU spend carrying a `costCenter` label but no `team`, sitting next to $5K of Claude API spend on an unlabeled legacy key. Two systems, one gap, no existing tool that shows them in the same table.
+`inference/vllm-llama-70b` is the whole pitch: $19K of GPU spend carrying a `costCenter` label but no `team`, sitting next to $5K of Claude spend routed through the gateway to Bedrock on an unlabeled legacy key. Two systems, one gap, no existing tool that shows them in the same table.
 
 Add a fallback and unalloc says how much of the "allocated" spend only got there through it, so a fallback onto something that is not an owner can't hide inside the headline:
 
@@ -59,11 +61,30 @@ $ unalloc report --fixtures -D team --fallback namespace
 │ $23,745.60 attributed only via fallback (namespace)              │
 ```
 
+Then check the ledger against what the providers billed. With `--fixtures`, the bundled sample invoices are used:
+
+```
+$ unalloc reconcile --fixtures
+┏━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┓
+┃ Source    ┃     Ledger ┃   Invoice ┃            Delta ┃ Status     ┃
+┡━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━┩
+│ anthropic │  $8,737.03 │ $8,779.84 │  $-42.81 (-0.5%) │ matched    │
+│ litellm   │ $11,444.27 │         — │                — │ no-invoice │
+│ openai    │  $4,031.36 │ $4,412.80 │ $-381.44 (-8.6%) │ under      │
+│ opencost  │ $42,417.72 │         — │                — │ no-invoice │
+└───────────┴────────────┴───────────┴──────────────────┴────────────┘
+The ledger does not tie out. Attribution built on this is not defensible yet.
+```
+
+Anthropic agrees within the 1% tolerance. OpenAI billed $381 more than its costs endpoint reported, so any attribution built on that ledger understates OpenAI spend until the gap is explained.
+
 ## Install
 
 ```bash
-pip install unalloc          # or: uv tool install unalloc
-unalloc report --fixtures    # works immediately, no infrastructure needed
+pip install unalloc                               # or: uv tool install unalloc
+unalloc report --fixtures --fallback cost_center  # works immediately, no infrastructure needed
+unalloc reconcile --fixtures                      # ledger vs. sample invoices
+unalloc --version
 ```
 
 From a clone:
@@ -77,11 +98,11 @@ make check    # ruff + pytest, same as CI
 Or as a container, which needs no Python on the host:
 
 ```bash
-docker build -t unalloc:0.2.0 .
-docker run --rm unalloc:0.2.0 report --fixtures -D team
+docker build -t unalloc .
+docker run --rm unalloc report --fixtures -D team
 
 # against real systems, reachable from the container
-docker run --rm --network host --env-file .env unalloc:0.2.0 report -D team
+docker run --rm --network host --env-file .env unalloc report -D team
 ```
 
 Copy `.env.example` to `.env` for the source configuration. unalloc stores
@@ -123,7 +144,9 @@ Configure sources by environment variable:
 | `ANTHROPIC_ADMIN_KEY` | Anthropic org admin key (cost report endpoint, sent as `x-api-key`) |
 | `UNALLOC_OPENAI_URL`, `UNALLOC_ANTHROPIC_URL` | Optional overrides for the public API roots, e.g. a proxy |
 
-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.
+Restrict the run with `--source` to avoid double counting: if LiteLLM covers all provider traffic and OpenCost excludes overlapping provider charges, use `--source opencost --source litellm` and skip the direct provider adapters. Confirm coverage and overlap for your setup. The [end-to-end case study](#case-studies-and-paper) demonstrates the resulting double count with synthetic billing and invoices; it does not measure customer savings.
+
+The case-study invoices and monthly cost pools are synthetic or illustrative. The GPU result covers one H100, one model and one two-minute run per load; waiting-request telemetry was sampled about every 0.5 seconds. Allocation-rule disagreement does not establish a uniquely correct charge or production savings.
 
 ## Reproducing a result
 
@@ -192,11 +215,11 @@ Six studies push real (or realistically simulated) inference workloads through u
 | Study | What runs | Headline |
 | --- | --- | --- |
 | [`kv_cache`](https://github.com/timurista/unalloc/blob/main/case_studies/kv_cache) | Discrete-event vLLM-style engine: paged KV blocks, prefix caching, continuous batching, preemption | Step-time metering shows ~0% idle once any request is in flight; KV-memory metering leaves a large share of the bill unowned |
-| [`torch_kv`](https://github.com/timurista/unalloc/blob/main/case_studies/torch_kv) | A from-scratch PyTorch decoder with a real KV cache serving a 4-tenant trace | Per-token showback over-charges a RAG tenant by 33 points of the pool ($5.7K/month) vs measured compute |
+| [`torch_kv`](https://github.com/timurista/unalloc/blob/main/case_studies/torch_kv) | A from-scratch PyTorch decoder with a real KV cache serving a 4-tenant trace | Token and measured-compute allocation rules differ by 33 points for a RAG tenant ($5.7K of an illustrative monthly pool) |
 | [`distributed`](https://github.com/timurista/unalloc/blob/main/case_studies/distributed) | Tensor and pipeline parallel on `torch.distributed` (gloo), verified against a single-process reference | Owner label on LeaderWorkerSet leaders only: 66% unallocated; falling back to `name` "fixes" it by sending 61% to a Helm chart name |
 | [`hybrid_e2e`](https://github.com/timurista/unalloc/blob/main/case_studies/hybrid_e2e) | The real CLI as a subprocess against live mock OpenCost / LiteLLM / OpenAI / Anthropic APIs (Postgres-backed LiteLLM in the dev container) | Enabling every source double counts $11.8K; reading only page one of the billing APIs reports 25% of spend |
 | [`use_cases`](https://github.com/timurista/unalloc/blob/main/case_studies/use_cases) | Labeling Pareto, per-feature unit economics, self-host break-even, CI budget gate | Three label fixes take a 67%-unallocated org under 10% |
-| [`gpu_validation`](https://github.com/timurista/unalloc/blob/main/case_studies/gpu_validation) | Real vLLM 0.29 serving Qwen2.5-7B on a DigitalOcean H100, driven with the simulator's tenants ([runbook](https://github.com/timurista/unalloc/blob/main/case_studies/gpu_validation/RUNBOOK.md), [evidence](https://github.com/timurista/unalloc/tree/main/case_studies/results/gpu_validation/evidence)) | Token metering over-charges search by 12–14 points vs time share; GPU "utilization" reads 97% at 2 req/s and 99% at 16 req/s |
+| [`gpu_validation`](https://github.com/timurista/unalloc/blob/main/case_studies/gpu_validation) | Real vLLM 0.29 serving Qwen2.5-7B on a DigitalOcean H100, driven with the simulator's tenants ([runbook](https://github.com/timurista/unalloc/blob/main/case_studies/gpu_validation/RUNBOOK.md), [evidence](https://github.com/timurista/unalloc/tree/main/case_studies/results/gpu_validation/evidence)) | Token and equal time-share allocation rules differ by 12–14 points for search; GPU "utilization" reads 97% at 2 req/s and 99% at 16 req/s |
 
 ```bash
 make research            # build ./.venv-research: CPU torch, notebook tooling, typst

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "unalloc"
-version = "0.3.0"
+version = "0.3.2"
 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.3.0 → unalloc-0.3.2}/src/unalloc/__init__.py

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

{unalloc-0.3.0 → unalloc-0.3.2}/src/unalloc/cli.py

@@ -53,6 +53,10 @@ FIXTURE_FILES = {
     "anthropic": "anthropic_cost_report.json",
 }
 
+# What the providers billed for the fixture month, so `reconcile --fixtures`
+# has something to reconcile against without the reader inventing a number.
+FIXTURE_INVOICES = "invoices.json"
+
 ENV_URL = {
     "opencost": "UNALLOC_OPENCOST_URL",
     "litellm": "UNALLOC_LITELLM_URL",
@@ -67,6 +71,46 @@ ENV_TOKEN = {
 }
 
 
+def _print_version(value: bool) -> None:
+    if value:
+        typer.echo(__version__)
+        raise typer.Exit()
+
+
+@app.callback()
+def _root(
+    version: bool = typer.Option(
+        False,
+        "--version",
+        "-V",
+        callback=_print_version,
+        is_eager=True,
+        help="Print the installed version and exit.",
+    ),
+) -> None:
+    pass
+
+
+def _fixture_invoices(fixture_dir: Path) -> list[Invoice]:
+    path = fixture_dir / FIXTURE_INVOICES
+    if not path.exists():
+        return []
+    data = json.loads(path.read_text())
+    period = data.get("period") or {}
+    start = datetime.fromisoformat(period["start"])
+    end = datetime.fromisoformat(period["end"])
+    return [
+        Invoice(
+            source=item["source"],
+            amount_usd=Decimal(str(item["amount_usd"])),
+            start=start,
+            end=end,
+            note=item.get("note", ""),
+        )
+        for item in data.get("invoices", [])
+    ]
+
+
 def _window(days: int) -> tuple[datetime, datetime]:
     end = datetime.now(tz=UTC)
     return end - timedelta(days=days), end
@@ -281,7 +325,8 @@ def reconcile_cmd(
         "--invoice",
         "-i",
         help="Billed total per source as SOURCE=AMOUNT, e.g. openai=4210.55. "
-        "Repeat the flag per source.",
+        "Repeat the flag per source. With --fixtures and no --invoice, the "
+        "bundled sample invoices are used.",
     ),
     tolerance: float = typer.Option(
         float(DEFAULT_TOLERANCE_PCT),
@@ -307,6 +352,8 @@ def reconcile_cmd(
                 end=end,
             )
         )
+    if fixtures and not invoice:
+        invoices = _fixture_invoices(fixture_dir)
 
     render.render_reconciliation(
         reconcile(rows, invoices, tolerance_pct=Decimal(str(tolerance)))

unalloc-0.3.2/src/unalloc/fixtures/README.md

@@ -0,0 +1,16 @@
+# Bundled fixtures
+
+Synthetic payloads for `--fixtures`. They describe one month (August 2026) of a
+made-up organization and are built so that **no dollar appears in two sources**:
+
+| Source | Covers |
+| --- | --- |
+| `opencost_allocation.json` | Self-hosted GPU and CPU workloads in the cluster (vLLM, llm-d, batch jobs, idle). |
+| `litellm_spend.json` | Gateway traffic routed to Azure OpenAI, Vertex AI and Bedrock. unalloc has no direct adapter for those, so the gateway is their only record. |
+| `openai_costs.json` | Direct OpenAI API usage that does not go through the gateway. |
+| `anthropic_cost_report.json` | Direct Anthropic API usage that does not go through the gateway. |
+| `invoices.json` | What OpenAI and Anthropic billed for the month, used by `reconcile --fixtures`. |
+
+Real deployments rarely split this cleanly. If your gateway proxies calls to
+OpenAI or Anthropic, pulling the gateway and the direct provider sources together
+counts that spend twice; choose sources with `--source`.

unalloc-0.3.2/src/unalloc/fixtures/invoices.json

@@ -0,0 +1,7 @@
+{
+  "period": {"start": "2026-08-01T00:00:00Z", "end": "2026-09-01T00:00:00Z"},
+  "invoices": [
+    {"source": "anthropic", "amount_usd": "8779.84", "note": "August invoice; within rounding of the cost report"},
+    {"source": "openai", "amount_usd": "4412.80", "note": "August invoice; $381.44 more than the costs endpoint returned"}
+  ]
+}

{unalloc-0.3.0 → unalloc-0.3.2}/src/unalloc/fixtures/litellm_spend.json

@@ -1,7 +1,7 @@
 {
   "data": [
     {
-      "request_id": "req_01", "model": "gpt-4o", "spend": "1840.22",
+      "request_id": "req_01", "model": "azure/gpt-4o", "spend": "1840.22",
       "startTime": "2026-08-03T11:02:11Z", "endTime": "2026-08-03T11:02:14Z",
       "prompt_tokens": 812000, "completion_tokens": 240100, "total_tokens": 1052100,
       "api_key_alias": "search-rerank", "team_id": "search",
@@ -9,7 +9,7 @@
       "metadata": {"service": "search-api"}, "cache_hit": false
     },
     {
-      "request_id": "req_02", "model": "claude-sonnet-4-6", "spend": "3204.90",
+      "request_id": "req_02", "model": "vertex_ai/claude-sonnet-4-6", "spend": "3204.90",
       "startTime": "2026-08-07T09:41:00Z", "endTime": "2026-08-07T09:41:06Z",
       "prompt_tokens": 2140000, "completion_tokens": 512300, "total_tokens": 2652300,
       "api_key_alias": "agent-runtime", "team_id": "platform",
@@ -17,14 +17,14 @@
       "metadata": {"service": "agent-runtime"}, "cache_hit": true
     },
     {
-      "request_id": "req_03", "model": "gpt-4o-mini", "spend": "986.40",
+      "request_id": "req_03", "model": "azure/gpt-4o-mini", "spend": "986.40",
       "startTime": "2026-08-12T14:20:00Z", "endTime": "2026-08-12T14:20:02Z",
       "prompt_tokens": 9400000, "completion_tokens": 1100000, "total_tokens": 10500000,
       "api_key_alias": "sandbox-shared", "request_tags": [],
       "metadata": {}, "cache_hit": false
     },
     {
-      "request_id": "req_04", "model": "claude-opus-5", "spend": "5412.75",
+      "request_id": "req_04", "model": "bedrock/claude-opus-5", "spend": "5412.75",
       "startTime": "2026-08-19T17:55:00Z", "endTime": "2026-08-19T17:55:22Z",
       "prompt_tokens": 1802000, "completion_tokens": 940400, "total_tokens": 2742400,
       "api_key_alias": "unknown-legacy-key", "request_tags": ["environment:prod"],

unalloc-0.3.2/tests/test_cli.py

@@ -0,0 +1,71 @@
+from __future__ import annotations
+
+import json
+
+from typer.testing import CliRunner
+
+from unalloc.cli import app
+
+runner = CliRunner()
+
+
+def test_budget_gate_fails_ci_when_unallocated_share_is_too_high():
+    # Bundled fixtures are 73.5% unallocated on `team`.
+    over = runner.invoke(app, ["report", "--fixtures", "-D", "team", "--json", "--budget", "50"])
+    assert over.exit_code == 2
+    assert "exceeds budget" in over.stderr
+
+    under = runner.invoke(app, ["report", "--fixtures", "-D", "team", "--json", "--budget", "80"])
+    assert under.exit_code == 0
+    assert json.loads(under.stdout)["unallocated_pct"] == "73.5"
+
+
+def test_labels_backlog_honours_fallbacks():
+    plain = runner.invoke(app, ["labels", "--fixtures", "-D", "team", "--limit", "50"])
+    rescued = runner.invoke(
+        app, ["labels", "--fixtures", "-D", "team", "-f", "namespace", "--limit", "50"]
+    )
+    assert plain.exit_code == rescued.exit_code == 0
+    # Three OpenCost rows lack `team`; two of them (the vLLM pod and the
+    # embeddings job) carry a namespace, so only __idle__ stays on the backlog.
+    # Count rows rather than match names: rich truncates to terminal width.
+    assert plain.stdout.count("│ opencost") == 3
+    assert rescued.stdout.count("│ opencost") == 1
+
+
+def test_version_flag_matches_version_command():
+    from unalloc import __version__
+
+    for args in (["--version"], ["-V"], ["version"]):
+        result = runner.invoke(app, args)
+        assert result.exit_code == 0
+        assert result.stdout.strip() == __version__
+
+
+def test_reconcile_fixtures_uses_bundled_invoices():
+    result = runner.invoke(app, ["reconcile", "--fixtures"])
+    assert result.exit_code == 0
+    # Anthropic ties out within tolerance; OpenAI billed more than its
+    # costs endpoint returned, so the demo shows a real gap.
+    assert "matched" in result.stdout
+    assert "under" in result.stdout
+    assert "does not tie out" in result.stdout
+
+
+def test_explicit_invoice_replaces_bundled_invoices():
+    result = runner.invoke(app, ["reconcile", "--fixtures", "-i", "openai=4031.36"])
+    assert result.exit_code == 0
+    assert "under" not in result.stdout
+    assert "does not tie out" not in result.stdout
+
+
+def test_fixture_sources_do_not_overlap():
+    # The default demo pulls all four sources, so the gateway fixture must not
+    # carry traffic that the direct provider fixtures also bill.
+    from unalloc.cli import FIXTURE_DIR, FIXTURE_FILES
+
+    gateway = json.loads((FIXTURE_DIR / FIXTURE_FILES["litellm"]).read_text())["data"]
+    direct = ("openai/", "anthropic/")
+    for record in gateway:
+        model = record["model"]
+        assert "/" in model and not model.startswith(direct), model

unalloc-0.3.0/tests/test_cli.py

@@ -1,33 +0,0 @@
-from __future__ import annotations
-
-import json
-
-from typer.testing import CliRunner
-
-from unalloc.cli import app
-
-runner = CliRunner()
-
-
-def test_budget_gate_fails_ci_when_unallocated_share_is_too_high():
-    # Bundled fixtures are 73.5% unallocated on `team`.
-    over = runner.invoke(app, ["report", "--fixtures", "-D", "team", "--json", "--budget", "50"])
-    assert over.exit_code == 2
-    assert "exceeds budget" in over.stderr
-
-    under = runner.invoke(app, ["report", "--fixtures", "-D", "team", "--json", "--budget", "80"])
-    assert under.exit_code == 0
-    assert json.loads(under.stdout)["unallocated_pct"] == "73.5"
-
-
-def test_labels_backlog_honours_fallbacks():
-    plain = runner.invoke(app, ["labels", "--fixtures", "-D", "team", "--limit", "50"])
-    rescued = runner.invoke(
-        app, ["labels", "--fixtures", "-D", "team", "-f", "namespace", "--limit", "50"]
-    )
-    assert plain.exit_code == rescued.exit_code == 0
-    # Three OpenCost rows lack `team`; two of them (the vLLM pod and the
-    # embeddings job) carry a namespace, so only __idle__ stays on the backlog.
-    # Count rows rather than match names: rich truncates to terminal width.
-    assert plain.stdout.count("│ opencost") == 3
-    assert rescued.stdout.count("│ opencost") == 1