unalloc 0.3.1__tar.gz → 0.3.3__tar.gz

{unalloc-0.3.1 → unalloc-0.3.3}/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Changelog
 
+## 0.3.3 — 2026-11-13
+
+### Added
+- Repository-only synthetic environment-lifetime memory allocation case study: per-environment overlap handling, exact equal-share allocation, explicit uncovered residual, and missing-telemetry comparison.
+- 43 focused tests and reproducible output checks in CI. The synthetic fixture reconciles 270 GB-seconds as 120 assigned plus 150 residual; omitting a request still reconciles, illustrating why conservation does not prove correct attribution.
+
+No production CLI or source-adapter behavior changes. This is not AWS ingestion, an observed AWS bill, CPU billing, or a savings claim. The case study lives in the GitHub source tree and source archive, not the PyPI wheel/sdist. The package patch includes updated README metadata and version identity.
+
+## 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

{unalloc-0.3.1 → unalloc-0.3.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: unalloc
-Version: 0.3.1
+Version: 0.3.3
 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,7 +55,7 @@ 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. Fixture totals below are synthetic demonstrations, not validated unique spend.
+> **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
 
@@ -88,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:
 
@@ -103,11 +103,45 @@ $ 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.
+
+## Environment-lifetime accounting example
+
+A new [repository-only case study](case_studies/environment_lifetime/README.md) separates
+summed request duration from environment-lifetime memory in a synthetic, offline fixture.
+It splits overlapping requests within each environment, preserves uncovered capacity as a
+residual, and shows that missing request telemetry can change attribution while totals still
+reconcile exactly. Equal sharing and constant memory are explicit modeling choices, not
+measured AWS ownership. No AWS ingestion, pricing, savings, or production CLI integration
+is claimed. Clone the repository to run it; case studies are not installed by `pip install unalloc`.
+
+```bash
+python3 -m case_studies.environment_lifetime
+python3 -m unittest discover -s case_studies/environment_lifetime -t . -v
+```
+
 ## 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:
@@ -121,11 +155,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

{unalloc-0.3.1 → unalloc-0.3.3}/README.md

@@ -13,7 +13,7 @@
 
 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. Fixture totals below are synthetic demonstrations, not validated unique spend.
+> **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
 
@@ -46,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:
 
@@ -61,11 +61,45 @@ $ 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.
+
+## Environment-lifetime accounting example
+
+A new [repository-only case study](case_studies/environment_lifetime/README.md) separates
+summed request duration from environment-lifetime memory in a synthetic, offline fixture.
+It splits overlapping requests within each environment, preserves uncovered capacity as a
+residual, and shows that missing request telemetry can change attribution while totals still
+reconcile exactly. Equal sharing and constant memory are explicit modeling choices, not
+measured AWS ownership. No AWS ingestion, pricing, savings, or production CLI integration
+is claimed. Clone the repository to run it; case studies are not installed by `pip install unalloc`.
+
+```bash
+python3 -m case_studies.environment_lifetime
+python3 -m unittest discover -s case_studies/environment_lifetime -t . -v
+```
+
 ## 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:
@@ -79,11 +113,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

unalloc-0.3.3/case_studies/environment_lifetime/README.md

@@ -0,0 +1,184 @@
+# Environment-lifetime memory allocation (synthetic)
+
+This is a small example that runs offline and uses only the standard library. It splits each
+environment's **lifetime memory GB-seconds** among the requests that ran in that
+environment. Any time not covered by a request becomes a residual.
+
+> **Scope.** The example does synthetic arithmetic on a hand-written fixture. It is
+> **not** validated AWS ingestion, **not** an AWS bill, and **not** a CPU billing model.
+> It contains no prices and no dollar or savings figures. The case study is not wired into the `unalloc` CLI or its sources,
+> and it changes no existing product behavior.
+
+## Why environment lifetime and not request duration
+
+The AWS Lambda docs (checked 2026-11-13) describe two facts this example models:
+
+- [Lambda web functions](https://docs.aws.amazon.com/lambda/latest/dg/web-functions.html):
+  memory is billed over the life of the environment.
+- [Environment lifecycle](https://docs.aws.amazon.com/lambda/latest/dg/web-functions-env-lifecycle.html):
+  an environment has no guaranteed lifetime.
+
+So the sum of request durations is not the quantity that memory accrues over. Concurrent
+requests share one environment's memory, and memory also accrues while no request is
+running. This example only shows the arithmetic for those two effects. It reads no AWS data.
+
+## Model
+
+For each environment, the fixture gives:
+
+- An observed lifetime `[lifetime_start_s, lifetime_end_s]`, which must have positive length.
+- A synthetic constant memory capacity `memory_gb`, which must be greater than 0.
+- `lifetime_gb_seconds = memory_gb × (lifetime_end_s − lifetime_start_s)`.
+
+For each request, the fixture gives:
+
+- An `environment` that must exist.
+- A span `[start_s, end_s]` that must lie inside that environment's lifetime.
+
+The example integrates each environment independently:
+
+1. Cut the lifetime into non-overlapping slices at every lifetime boundary and every request
+   boundary.
+2. Check how many requests cover each slice:
+   - If `n ≥ 1` requests cover the slice, the slice counts as busy. Each covering request
+     receives `memory_gb × width / n`.
+   - If no request covers the slice, it counts as uncovered. Its GB-seconds go to the
+     **residual**.
+3. Never share a slice across environments. Two requests on different environments get
+   separate allocations, even when their wall-clock spans overlap.
+
+### Reported quantities
+
+The example reports each quantity per environment and as a total (except `overlap_seconds`, which is per-environment only):
+
+| Field | Meaning |
+|---|---|
+| `raw_request_seconds` | Sum of request durations. Counts overlapping time more than once. |
+| `union_busy_seconds` | Per-environment union of request spans. The total sums these environment-seconds, not a global wall-clock union. |
+| `overlap_seconds` | `raw_request_seconds − union_busy_seconds`. |
+| `uncovered_seconds` | Lifetime seconds that no request covers. |
+| `lifetime_gb_seconds` | `memory_gb × lifetime seconds`. |
+| `allocated_gb_seconds` | Sum of per-request allocations, equal to `memory_gb × union_busy_seconds`. |
+| `residual_gb_seconds` | `memory_gb × uncovered_seconds`. |
+| `reconciliation` | Checks that `allocated + residual == lifetime` exactly. The `difference` field must be `"0"`. |
+
+The output also lists `allocated_gb_seconds` for each request.
+
+### Residual: unobserved unless the fixture claims completeness
+
+By default, the example labels the residual `unobserved`. A gap in request telemetry might
+mean the environment sat idle, or it might mean a request went unrecorded.
+
+The residual is labelled `idle_by_complete_synthetic_fixture` only when the fixture sets both
+`"synthetic": true` and `"telemetry_complete": true`. The bundled fixture sets both, because
+it is hand-written and lists every request by construction. When you run with
+`--drop-request`, the example always sets `telemetry_complete` to false. In that case, the
+residual is labelled `unobserved`.
+
+### Zero-length requests
+
+A request with `start_s == end_s` is accepted if it lies inside its environment's
+lifetime, including the lifetime's endpoints. A zero-length request has the following
+properties:
+
+- It covers no slice.
+- It receives exactly `0` GB-seconds.
+- It adds `0` to `raw_request_seconds`.
+- It is flagged `"zero_duration": true`.
+
+### Exactness and validation
+
+All arithmetic uses `fractions.Fraction`. The example accepts numbers in these forms:
+
+- Decimal strings, such as `"1.5"`.
+- Integers.
+- JSON numbers, which the example parses as `Decimal`, so `0.1` stays exactly 1/10.
+- In-memory `Decimal` or `Fraction` values.
+
+The output writes each value as an exact string. A value that terminates in base 10 is written
+as a decimal, such as `"28.75"`. Any other value is written as `"numerator/denominator"`, such
+as `"155/6"`.
+
+The example rejects the following inputs with a `FixtureError` that names the offending field:
+
+- Binary floats, booleans, `NaN`, `sNaN`, `Infinity`, and the JSON `NaN` or `Infinity`
+  literals.
+- Malformed number strings.
+- Negative times, and a memory capacity of 0 or less.
+- Lifetimes where `end <= start`, and requests where `end < start`.
+- Requests that fall outside their environment's lifetime.
+- Unknown environments.
+- Duplicate environment IDs, duplicate request IDs (checked across all environments), and
+  duplicate JSON keys.
+- IDs that are empty, not a string, or padded with whitespace.
+- Missing or unknown fields, and a wrong `schema` value.
+
+## Bundled fixture
+
+The fixture is [`fixture.json`](fixture.json). All values are synthetic.
+
+| Environment | Memory (GB) | Lifetime (s) | Requests | What it shows |
+|---|---|---|---|---|
+| `env-a` | 1.5 | [0, 100] | `a-1` [10,40], `a-2` [20,50], `a-3` [30,35], `a-4` [60,60], `a-5` [70,90] | Three-way overlap, a zero-length request, and gaps |
+| `env-b` | 0.5 | [5, 65] | `b-1` [5,65], `b-2` [15,25], `b-3` [20,30] | Up to 3 concurrent requests. The thirds don't terminate as decimals. |
+| `env-c` | 3 | [0, 30] | none | The whole lifetime is residual |
+
+The bundled fixture produces these results, from [`fixture_output.json`](fixture_output.json):
+
+| Environment | Raw request s | Union busy s | Lifetime GB-s | Allocated GB-s | Residual GB-s |
+|---|---|---|---|---|---|
+| `env-a` | 85 | 60 | 150 | 90 | 60 |
+| `env-b` | 80 | 60 | 30 | 30 | 0 |
+| `env-c` | 0 | 0 | 90 | 0 | 90 |
+| **total** | **165** | **120** | **270** | **120** | **150** |
+
+The per-request allocations are:
+
+- `a-1` 28.75, `a-2` 28.75, `a-3` 2.5, `a-4` 0, `a-5` 30.
+- `b-1` 155/6, `b-2` 25/12, `b-3` 25/12.
+
+### Missing telemetry
+
+The file [`fixture_output_missing_a-2.json`](fixture_output_missing_a-2.json) shows the result
+when request `a-2` is removed:
+
+- The residual for `env-a` grows from 60 to **75** GB-s. The extra 15 GB-s comes from
+  [40, 50], the 10 seconds when only `a-2` was running, at 1.5 GB.
+- The slices that `a-2` shared now go to `a-1` (41.25) and `a-3` (3.75).
+- The lifetime GB-seconds don't change, and the reconciliation is still exact.
+- The residual is labelled `unobserved`.
+
+## Reproduce
+
+Run these commands from the repository root. They need Python 3.9 or later, no third-party
+packages, and no network access.
+
+```sh
+# Print the result JSON for the bundled fixture.
+python3 -m case_studies.environment_lifetime
+
+# Check that the stored outputs match the current code byte for byte. The command exits 1 on a mismatch.
+python3 -m case_studies.environment_lifetime --check case_studies/environment_lifetime/fixture_output.json
+python3 -m case_studies.environment_lifetime --drop-request a-2 \
+    --check case_studies/environment_lifetime/fixture_output_missing_a-2.json
+
+# Regenerate the stored outputs.
+python3 -m case_studies.environment_lifetime --out case_studies/environment_lifetime/fixture_output.json
+python3 -m case_studies.environment_lifetime --drop-request a-2 \
+    --out case_studies/environment_lifetime/fixture_output_missing_a-2.json
+
+# Run the tests with unittest from the standard library. pytest is not required.
+python3 -m unittest discover -s case_studies/environment_lifetime -t . -v
+```
+
+The repository's `pytest` configuration only collects tests from `tests/`, so this suite
+runs only when you invoke the `unittest` command above.
+
+## Files
+
+- `lifetime.py`: parsing, validation, exact integration, and reconciliation.
+- `__main__.py`: the command-line interface (`--fixture`, `--drop-request`, `--out`, and
+  `--check`).
+- `fixture.json`: the synthetic input.
+- `fixture_output.json` and `fixture_output_missing_a-2.json`: the stored outputs.
+- `test_lifetime.py`: the `unittest` suite.

{unalloc-0.3.1 → unalloc-0.3.3}/pyproject.toml

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

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

{unalloc-0.3.1 → unalloc-0.3.3}/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.3/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.3/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.1 → unalloc-0.3.3}/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.3/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.1/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