unalloc 0.2.0__py3-none-any.whl

unalloc/sources/litellm.py

@@ -0,0 +1,75 @@
+"""LiteLLM adapter.
+
+LiteLLM's proxy already attributes spend per virtual key, team and tag, which
+makes it the single highest-signal LLM source. It is also the only one that can
+give you request-level granularity, so where a team runs LiteLLM this adapter
+should be preferred over the direct provider adapters to avoid double counting.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from unalloc.core.models import CostRow
+from unalloc.core.normalize import normalize_labels
+from unalloc.sources.base import Source, money, parse_ts
+
+
+class LiteLLMSource(Source):
+    name = "litellm"
+
+    def fetch(self, start: datetime, end: datetime) -> list[CostRow]:
+        payload = self._get(
+            "/spend/logs",
+            params={
+                "start_date": start.date().isoformat(),
+                "end_date": end.date().isoformat(),
+            },
+        )
+        return self.parse(payload)
+
+    def parse(self, payload: Any) -> list[CostRow]:
+        records = payload.get("data", payload) if isinstance(payload, dict) else payload
+        if not isinstance(records, list):
+            return []
+        return [self._row(rec) for rec in records if isinstance(rec, dict)]
+
+    def _row(self, rec: dict[str, Any]) -> CostRow:
+        metadata = rec.get("metadata") or {}
+        raw_labels: dict[str, Any] = dict(metadata) if isinstance(metadata, dict) else {}
+
+        # Tags arrive as a list; index them so a `team:platform` style tag
+        # becomes a real dimension instead of an opaque string.
+        for tag in rec.get("request_tags") or []:
+            text = str(tag)
+            if ":" in text:
+                key, _, value = text.partition(":")
+                raw_labels.setdefault(key, value)
+            else:
+                raw_labels.setdefault(text, "true")
+
+        for field in ("team_id", "user", "end_user", "api_key_alias", "model"):
+            if rec.get(field):
+                raw_labels.setdefault(field, rec[field])
+
+        tokens = rec.get("total_tokens")
+        if tokens is None:
+            tokens = (rec.get("prompt_tokens") or 0) + (rec.get("completion_tokens") or 0)
+
+        return CostRow(
+            source=self.name,
+            name=str(rec.get("model") or rec.get("api_key_alias") or "litellm-request"),
+            amount_usd=money(rec.get("spend") if rec.get("spend") is not None else rec.get("cost")),
+            start=parse_ts(rec.get("startTime") or rec.get("start_time")),
+            end=parse_ts(rec.get("endTime") or rec.get("end_time")),
+            labels=normalize_labels(raw_labels, self.aliases),
+            quantity=money(tokens) or None,
+            unit="tokens" if tokens else None,
+            meta={
+                "request_id": rec.get("request_id"),
+                "prompt_tokens": rec.get("prompt_tokens"),
+                "completion_tokens": rec.get("completion_tokens"),
+                "cache_hit": rec.get("cache_hit"),
+            },
+        )

unalloc/sources/openai.py

@@ -0,0 +1,68 @@
+"""OpenAI organization costs adapter.
+
+Uses the org-level costs endpoint, which buckets spend by time and (optionally)
+project. Project is the only attribution dimension the billing API exposes, so
+if an org runs everything under one project this adapter will correctly report
+near-100% unallocated. That is not a bug in unalloc; it is the finding.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Any
+
+from unalloc.core.models import CostRow
+from unalloc.core.normalize import normalize_labels
+from unalloc.sources.base import Source, money, parse_ts
+
+
+class OpenAISource(Source):
+    name = "openai"
+    default_base_url = "https://api.openai.com/v1"
+
+    def fetch(self, start: datetime, end: datetime) -> list[CostRow]:
+        payload = self._get_pages(
+            "/organization/costs",
+            params={
+                "start_time": int(start.timestamp()),
+                "end_time": int(end.timestamp()),
+                "bucket_width": "1d",
+                "group_by": "project_id",
+                "limit": 180,
+            },
+        )
+        return self.parse(payload)
+
+    def parse(self, payload: Any) -> list[CostRow]:
+        buckets = payload.get("data", []) if isinstance(payload, dict) else payload
+        if not isinstance(buckets, list):
+            return []
+        rows: list[CostRow] = []
+        for bucket in buckets:
+            if not isinstance(bucket, dict):
+                continue
+            start = parse_ts(bucket.get("start_time"))
+            end = parse_ts(bucket.get("end_time"), default=start)
+            for result in bucket.get("results") or []:
+                if not isinstance(result, dict):
+                    continue
+                rows.append(self._row(result, start, end))
+        return rows
+
+    def _row(self, result: dict[str, Any], start: datetime, end: datetime) -> CostRow:
+        amount = result.get("amount") or {}
+        raw_labels = {
+            "project_id": result.get("project_id"),
+            "project": result.get("project_name"),
+            "line_item": result.get("line_item"),
+            "provider": "openai",
+        }
+        return CostRow(
+            source=self.name,
+            name=str(result.get("line_item") or result.get("project_id") or "openai-usage"),
+            amount_usd=money(amount.get("value") if isinstance(amount, dict) else amount),
+            start=start,
+            end=end,
+            labels=normalize_labels(raw_labels, self.aliases),
+            meta={"currency": (amount or {}).get("currency") if isinstance(amount, dict) else None},
+        )

unalloc/sources/opencost.py

@@ -0,0 +1,127 @@
+"""OpenCost adapter.
+
+Reads the /allocation endpoint, which returns one or more time windows, each a
+map of allocation name -> allocation object. Since 1.121.0 OpenCost also
+exposes per-model inference costs for vLLM/llm-d deployments; those arrive
+through the same allocation shape, so they land in the ledger for free and get
+tagged with `unalloc_layer=inference` where detectable.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from decimal import Decimal
+from typing import Any
+
+from unalloc.core.models import CostRow
+from unalloc.core.normalize import normalize_labels
+from unalloc.sources.base import Source, money, parse_ts
+
+
+class OpenCostSource(Source):
+    name = "opencost"
+
+    def fetch(self, start: datetime, end: datetime) -> list[CostRow]:
+        payload = self._get(
+            "/allocation",
+            params={
+                "window": f"{start.date().isoformat()},{end.date().isoformat()}",
+                "aggregate": "namespace,controller,label:team",
+                "accumulate": "true",
+                "includeIdle": "true",
+            },
+        )
+        return self.parse(payload)
+
+    def parse(self, payload: Any) -> list[CostRow]:
+        rows: list[CostRow] = []
+        for window in _windows(payload):
+            for name, alloc in window.items():
+                if not isinstance(alloc, dict):
+                    continue
+                rows.append(self._row(name, alloc))
+        return rows
+
+    def _row(self, name: str, alloc: dict[str, Any]) -> CostRow:
+        props = alloc.get("properties") or {}
+        raw_labels: dict[str, Any] = {}
+        raw_labels.update(props.get("labels") or {})
+        # Labels are the owner contract; an annotation with the same key must
+        # not silently override one.
+        for key, value in (props.get("annotations") or {}).items():
+            raw_labels.setdefault(key, value)
+        # Structural identity is a legitimate fallback dimension, so promote it
+        # into labels rather than hiding it in meta.
+        for key in ("namespace", "controller", "controllerKind", "cluster", "node"):
+            if props.get(key):
+                raw_labels.setdefault(key, props[key])
+
+        model = _inference_model(alloc, props)
+        if model:
+            raw_labels.setdefault("model", model)
+            raw_labels.setdefault("unalloc_layer", "inference")
+
+        total: Any = alloc.get("totalCost")
+        if total is None:
+            # Sum as Decimal: going via float here reintroduced exactly the
+            # 0.30000000000000004 noise that money() exists to keep out.
+            total = sum(
+                (
+                    money(alloc.get(field))
+                    for field in (
+                    "cpuCost",
+                    "ramCost",
+                    "gpuCost",
+                    "pvCost",
+                    "networkCost",
+                    "loadBalancerCost",
+                        "sharedCost",
+                        "externalCost",
+                    )
+                ),
+                Decimal("0"),
+            )
+
+        return CostRow(
+            source=self.name,
+            name=alloc.get("name") or name,
+            amount_usd=money(total),
+            start=parse_ts(alloc.get("start") or alloc.get("window", {}).get("start")),
+            end=parse_ts(alloc.get("end") or alloc.get("window", {}).get("end")),
+            labels=normalize_labels(raw_labels, self.aliases),
+            quantity=money(alloc.get("gpuHours")) or None,
+            unit="gpu-hours" if alloc.get("gpuHours") else None,
+            meta={
+                "cpuCost": alloc.get("cpuCost"),
+                "ramCost": alloc.get("ramCost"),
+                "gpuCost": alloc.get("gpuCost"),
+                "sharedCost": alloc.get("sharedCost"),
+                "efficiency": alloc.get("totalEfficiency"),
+            },
+        )
+
+
+def _windows(payload: Any) -> list[dict[str, Any]]:
+    """OpenCost has shipped several response envelopes. Accept all of them."""
+    data = payload.get("data") if isinstance(payload, dict) else payload
+    if data is None:
+        return []
+    if isinstance(data, dict):
+        return [data]
+    if isinstance(data, list):
+        return [window for window in data if isinstance(window, dict)]
+    return []
+
+
+def _inference_model(alloc: dict[str, Any], props: dict[str, Any]) -> str | None:
+    """Best-effort detection of the 1.121.0+ inference metadata.
+
+    The field naming here is the least stable part of this adapter. If it moves
+    upstream, only this function changes.
+    """
+    for container in (alloc, props):
+        for key in ("model", "modelName", "llmModel", "inferenceModel"):
+            value = container.get(key)
+            if value:
+                return str(value)
+    return None

unalloc-0.2.0.dist-info/METADATA

@@ -0,0 +1,254 @@
+Metadata-Version: 2.5
+Name: unalloc
+Version: 0.2.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
+Project-URL: Changelog, https://github.com/timurista/unalloc/blob/main/CHANGELOG.md
+Project-URL: Paper, https://github.com/timurista/unalloc/blob/main/paper/unalloc-case-studies.pdf
+Project-URL: Explorer, https://timurista.github.io/unalloc/
+Author: Timothy Urista
+License: Apache-2.0
+License-File: LICENSE
+Keywords: cost-attribution,finops,kubernetes,llm,llmops,opencost,showback
+Classifier: Development Status :: 3 - Alpha
+Classifier: Environment :: Console
+Classifier: Intended Audience :: System Administrators
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: System :: Monitoring
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: rich>=13.7
+Requires-Dist: typer>=0.12
+Provides-Extra: dev
+Requires-Dist: mypy>=1.11; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.6; extra == 'dev'
+Provides-Extra: research
+Requires-Dist: ipykernel>=6.29; extra == 'research'
+Requires-Dist: jupyterlab>=4.2; extra == 'research'
+Requires-Dist: matplotlib>=3.8; extra == 'research'
+Requires-Dist: nbclient>=0.10; extra == 'research'
+Requires-Dist: nbformat>=5.10; extra == 'research'
+Requires-Dist: numpy>=1.26; extra == 'research'
+Requires-Dist: psycopg[binary]>=3.2; extra == 'research'
+Requires-Dist: torch>=2.3; extra == 'research'
+Requires-Dist: typst>=0.13; extra == 'research'
+Description-Content-Type: text/markdown
+
+# unalloc
+
+**Find the AI spend nobody owns.** Joins OpenCost allocation data with LLM provider bills and reports what's unattributed.
+
+[![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)
+[![Explorer](https://img.shields.io/badge/explorer-live-1f5b45.svg)](https://timurista.github.io/unalloc/)
+
+OpenCost tells you what your Kubernetes workloads cost. Your provider dashboard tells you what your OpenAI and Anthropic calls cost. Neither tells you what a single AI feature costs, because the two live in different systems with different keys. `unalloc` pulls both 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.
+
+## The output
+
+```
+$ unalloc report --fixtures --dimension team
+
+╭──────────────────────────── unalloc ─────────────────────────────╮
+│ 73.5% of $66,630.38 AI spend is unattributed                     │
+│ $48,983.14 has no 'team' label                                   │
+╰──────────────────────────────────────────────────────────────────╯
+
+                        Spend by team
+┏━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━┓
+┃ team            ┃        Cost ┃ Share ┃ Sources                               ┃ Rows ┃
+┡━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━┩
+│ platform        │  $13,166.02 │ 19.8% │ litellm, opencost                     │    2 │
+│ search          │   $4,481.22 │  6.7% │ litellm, opencost                     │    2 │
+│ <unallocated>   │  $48,983.14 │ 73.5% │ anthropic, litellm, opencost, openai  │   11 │
+└─────────────────┴─────────────┴───────┴───────────────────────────────────────┴──────┘
+```
+
+Then the actionable half: a labeling backlog sorted by dollars.
+
+```
+$ unalloc labels --fixtures --dimension team
+
+      Labeling backlog — rows missing 'team', by cost
+┏━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
+┃  # ┃ Source   ┃ Cost object               ┃       Cost ┃ Labels it does have        ┃
+┡━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
+│  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         │
+└────┴──────────┴───────────────────────────┴────────────┴────────────────────────────┘
+```
+
+`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.
+
+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:
+
+```
+$ unalloc report --fixtures -D team --fallback namespace
+│ 37.9% of $66,630.38 AI spend is unattributed                     │
+│ $25,237.54 has no 'team' label                                   │
+│ $23,745.60 attributed only via fallback (namespace)              │
+```
+
+## Install
+
+```bash
+pip install unalloc          # or: uv tool install unalloc
+unalloc report --fixtures    # works immediately, no infrastructure needed
+```
+
+From a clone:
+
+```bash
+make dev      # editable install with test + lint tooling
+make demo     # all three commands against bundled fixtures
+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
+
+# against real systems, reachable from the container
+docker run --rm --network host --env-file .env unalloc:0.2.0 report -D team
+```
+
+Copy `.env.example` to `.env` for the source configuration. unalloc stores
+nothing: no database, no state directory, no cached credentials.
+
+## Usage
+
+```bash
+# What percentage of spend has no owner?
+unalloc report --dimension team --days 30
+
+# Accept a second-best key before declaring a row unallocated
+unalloc report -D team --fallback namespace --fallback cost_center
+
+# Fail a CI job when more than 10% of spend is unowned
+unalloc report -D team --budget 10
+
+# Which label keys does my data actually have?
+unalloc labels --available
+
+# The backlog honours the same fallbacks as the report
+unalloc labels -D team --fallback namespace
+
+# Does the ledger tie out to the invoice?
+unalloc reconcile --invoice openai=4031.36 --invoice anthropic=8737.03
+
+# Pipe it into something else
+unalloc report --json | jq '.unallocated_pct, .fallback_usd'
+```
+
+Configure sources by environment variable:
+
+| Variable | Purpose |
+| --- | --- |
+| `UNALLOC_OPENCOST_URL` | OpenCost API root, e.g. `http://opencost.opencost:9003` |
+| `UNALLOC_LITELLM_URL` | LiteLLM proxy root |
+| `UNALLOC_LITELLM_KEY` | LiteLLM master or admin key |
+| `OPENAI_ADMIN_KEY` | OpenAI org admin key (costs endpoint) |
+| `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.
+
+## How it works
+
+```
+  OpenCost /allocation ─┐
+  LiteLLM /spend/logs  ─┤
+  OpenAI  org costs    ─┼──▶ normalize (label canonicalization + aliases)
+  Anthropic cost report ┘              │
+                                       ▼
+                                    CostRow[]
+                                       │
+                      ┌────────────────┼────────────────┐
+                      ▼                ▼                ▼
+                  attribute        reconcile          labels
+              (unallocated %)   (vs invoice)     (backlog by $)
+```
+
+Everything rests on one dataclass. An adapter's only job is turning a provider payload into `CostRow`s; it never aggregates, filters or decides anything about attribution. Adding a provider is one file and one fixture.
+
+Two design choices worth calling out:
+
+**Money is `Decimal`, never `float`.** Attribution that disagrees with the invoice by a cent per row is how you lose an argument with finance.
+
+**Label canonicalization is the actual hard part.** OpenCost gives you `label_costCenter`. LiteLLM gives you `team_id` or a `team:platform` request tag. OpenAI gives you a project ID. None of those join on a naive dict lookup, so every adapter runs its labels through `normalize.py` first, which strips provider prefixes (repeatedly, so `label_app_kubernetes_io_name` and `app.kubernetes.io/name` agree), converts camelCase, and applies an alias table you can extend per-org. When two raw keys land on the same canonical key, a fixed precedence decides - explicit key, then alias, then rewritten key, then path-derived key - so the result never depends on the order a provider serialized its labels in.
+
+## Case studies and paper
+
+Five studies push real (or realistically simulated) inference workloads through unalloc's own adapters. 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)**.
+
+| 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 |
+| [`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% |
+
+```bash
+make research            # CPU torch, notebook tooling, typst
+make case-studies        # all five, full size (a few minutes)
+make paper               # figures + PDF
+make notebook            # execute case_studies/unalloc_case_studies.ipynb
+make ui                  # ledger explorer on http://127.0.0.1:8765
+```
+
+![Share of a shared vLLM pod's bill under five metering rules](https://raw.githubusercontent.com/timurista/unalloc/main/paper/figures/kv_shares.png)
+
+The **[ledger explorer](https://timurista.github.io/unalloc/)** (or `python -m case_studies.ui` locally) shows every dataset row by row: pick the label that means "owner", add fallbacks, and watch each row resolve to a team, a fallback value, or the backlog. `python -m case_studies.ui --export explorer.html` writes a self-contained copy you can share.
+
+## Development environment
+
+An isolated dev stack lives in [`.devcontainer/`](https://github.com/timurista/unalloc/blob/main/.devcontainer): a Python 3.11 workspace with the case-study dependencies (CPU-only PyTorch) and a small Postgres that backs the mock LiteLLM spend-log store. Open the folder in VS Code's Dev Containers, or from a terminal:
+
+```bash
+make devcontainer          # docker compose up
+make devcontainer-check    # lint, tests and every case study at smoke size, inside the container
+```
+
+## Scope, and what this is not
+
+OpenCost 1.121.0 added inference cost tracking for vLLM and llm-d deployments: cost per million tokens, KV-cache-corrected pricing, shared infrastructure attribution. That is excellent and `unalloc` does not reimplement it. Those rows arrive through the same `/allocation` shape and land in this ledger tagged `unalloc_layer=inference`.
+
+What OpenCost structurally cannot do is see your OpenAI and Anthropic bills, because they aren't Kubernetes objects. What LiteLLM cannot do is see your GPU nodes. `unalloc` lives in exactly that seam and nowhere else. It is:
+
+- **not** a dashboard — it prints a number and exits (the explorer is a case-study companion, not part of the CLI)
+- **not** an optimizer — it makes no recommendations about rightsizing or commitments
+- **not** a collector — it queries systems you already run, and stores nothing
+
+## Roadmap
+
+- [ ] Prometheus exporter so `unalloc_unallocated_ratio` can be alerted on
+- [ ] OpenCost external-cost plugin, so LLM API spend appears natively in OpenCost
+- [ ] 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
+- [ ] `--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
+
+## Contributing
+
+Adding a source is deliberately small: implement `parse()` on a `Source` subclass, add a fixture to `src/unalloc/fixtures/`, add a case to `tests/test_sources.py`. The fixtures are the contract, so a PR with a real (scrubbed) payload from a provider is valuable even without the adapter.
+
+```bash
+pip install -e ".[dev]"
+ruff check . && pytest
+```
+
+## License
+
+Apache 2.0, matching OpenCost.

unalloc-0.2.0.dist-info/RECORD

@@ -0,0 +1,24 @@
+unalloc/__init__.py,sha256=6L0WsNms3YMi2pc2yAPYOs8TOw0wEmiBU8oF4Adl1Io,134
+unalloc/cli.py,sha256=i16vWKPt5w6lKz_hmVl8nbH8VEBbomeH4QjVgWM9--U,8046
+unalloc/core/__init__.py,sha256=U4S_2y3zgLZVfMenHRaJFBW8yqh2mUBuI291LGQVOJ8,35
+unalloc/core/attribute.py,sha256=cmKIMT3clJ1HBkxEYD941r_lSi981XkpR5LCiXyfWLg,4634
+unalloc/core/models.py,sha256=E4Yzhru9jfuSgJ5QwewUzwCIcRfD_jm7XWGdGUyDe38,2335
+unalloc/core/normalize.py,sha256=PfKyp6a-mbMbuWefEh4NvTm4r_uA3WTqkwA29OIuET4,4707
+unalloc/core/reconcile.py,sha256=F_e54M30UA9gfOeE9AGzxG7O2rFb-Nv7Tn2sEVZ7xGM,3030
+unalloc/fixtures/anthropic_cost_report.json,sha256=xZLD3SjzdE9WAuWLXOYUkITLK54TowqgfoWjd_nOHf0,657
+unalloc/fixtures/litellm_spend.json,sha256=v3-kARdDBZHPiWfgdDOPQQrwnHMwBxmgppBYcrLfLOY,1634
+unalloc/fixtures/openai_costs.json,sha256=1o8ayWPLRDZE3JMaTxdG0SY-3as59IuxfgcY4DWJVMw,685
+unalloc/fixtures/opencost_allocation.json,sha256=GXrAglAqTi9qd9eV-JEUkkkM7T32ujD5Xiobh7q-m24,2657
+unalloc/render/__init__.py,sha256=U4S_2y3zgLZVfMenHRaJFBW8yqh2mUBuI291LGQVOJ8,35
+unalloc/render/table.py,sha256=_OBzS9Xel3SA5lHaXYD6SkBXSjujrk0tFrwxQ3aYkoY,5388
+unalloc/sources/__init__.py,sha256=R9ZTZdfzbne4QnrixQU-G4OtbJJWE5vKWQmjlnjq05A,641
+unalloc/sources/anthropic.py,sha256=gKbcQ3kEujP4c0S7Yjxnp1IHZmRFXNCZy9BQvTt_CIo,2711
+unalloc/sources/base.py,sha256=HI1tWAwQS1l6qxe3mZe69-w24KD91X4QYNLILav2YCU,5003
+unalloc/sources/litellm.py,sha256=bPhwCcND8nF6DfTBhPkUetwnMK5Luepa6Hkb1qcKc1U,2983
+unalloc/sources/openai.py,sha256=nScpuV3XwBfk3INoBrLLVHsHpDSk27i5mTBUibIaIiY,2608
+unalloc/sources/opencost.py,sha256=CILHj5PGd7RvVTP3AbiVp5cVXsusmrOsgXPXbJIHmyk,4799
+unalloc-0.2.0.dist-info/METADATA,sha256=UXZMgtir_Qs8R5wrI3Ew3H_Nx152Q6uRKsLhNWkltII,16269
+unalloc-0.2.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+unalloc-0.2.0.dist-info/entry_points.txt,sha256=NBLNMNWavNcp6Bya_aRUnSowUxx6Uk3uPQ5gGUFsjMY,45
+unalloc-0.2.0.dist-info/licenses/LICENSE,sha256=vkzgu9eNXnW1xeak-rrh2sdGg9Ypa0PjLBDEFPq-oLs,11345
+unalloc-0.2.0.dist-info/RECORD,,

unalloc-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

unalloc-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+unalloc = unalloc.cli:main