unalloc 0.2.0__py3-none-any.whl

unalloc/core/reconcile.py

@@ -0,0 +1,101 @@
+"""Reconcile the ledger against what the provider actually billed.
+
+An attribution report that doesn't tie back to the invoice is a guess. This is
+the step most tools skip, and it is the one that makes a FinOps team trust the
+number.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from dataclasses import dataclass
+from decimal import Decimal
+
+from unalloc.core.models import CostRow, Invoice
+
+ZERO = Decimal("0")
+
+# Below this, a delta is rounding and metric-scrape jitter, not a real gap.
+DEFAULT_TOLERANCE_PCT = Decimal("1.0")
+
+
+@dataclass(frozen=True, slots=True)
+class SourceReconciliation:
+    source: str
+    ledger_usd: Decimal
+    invoice_usd: Decimal | None
+
+    @property
+    def delta_usd(self) -> Decimal | None:
+        if self.invoice_usd is None:
+            return None
+        return self.ledger_usd - self.invoice_usd
+
+    @property
+    def delta_pct(self) -> Decimal | None:
+        if self.invoice_usd is None or self.invoice_usd == ZERO:
+            return None
+        return ((self.ledger_usd - self.invoice_usd) / self.invoice_usd * 100).quantize(
+            Decimal("0.1")
+        )
+
+    def status(self, tolerance_pct: Decimal = DEFAULT_TOLERANCE_PCT) -> str:
+        """One of: matched, over, under, no-invoice."""
+        if self.invoice_usd is None:
+            return "no-invoice"
+        pct = self.delta_pct
+        if pct is None:
+            return "no-invoice"
+        if abs(pct) <= tolerance_pct:
+            return "matched"
+        return "over" if pct > 0 else "under"
+
+
+@dataclass(frozen=True, slots=True)
+class ReconciliationReport:
+    per_source: list[SourceReconciliation]
+    tolerance_pct: Decimal
+
+    @property
+    def ledger_total(self) -> Decimal:
+        return sum((r.ledger_usd for r in self.per_source), ZERO)
+
+    @property
+    def invoice_total(self) -> Decimal:
+        return sum(
+            (r.invoice_usd for r in self.per_source if r.invoice_usd is not None), ZERO
+        )
+
+    @property
+    def clean(self) -> bool:
+        """True when every source with an invoice ties out within tolerance."""
+        return all(
+            r.status(self.tolerance_pct) in {"matched", "no-invoice"}
+            for r in self.per_source
+        )
+
+
+def reconcile(
+    rows: Iterable[CostRow],
+    invoices: Iterable[Invoice],
+    *,
+    tolerance_pct: Decimal = DEFAULT_TOLERANCE_PCT,
+) -> ReconciliationReport:
+    ledger: dict[str, Decimal] = {}
+    for row in rows:
+        ledger[row.source] = ledger.get(row.source, ZERO) + row.amount_usd
+
+    billed: dict[str, Decimal] = {}
+    for invoice in invoices:
+        billed[invoice.source] = billed.get(invoice.source, ZERO) + invoice.amount_usd
+
+    sources = sorted(set(ledger) | set(billed))
+    per_source = [
+        SourceReconciliation(
+            source=source,
+            ledger_usd=ledger.get(source, ZERO),
+            invoice_usd=billed.get(source),
+        )
+        for source in sources
+    ]
+    return ReconciliationReport(per_source=per_source, tolerance_pct=tolerance_pct)

unalloc/fixtures/anthropic_cost_report.json

@@ -0,0 +1,12 @@
+{
+  "data": [
+    {
+      "starting_at": "2026-08-01T00:00:00Z", "ending_at": "2026-09-01T00:00:00Z",
+      "results": [
+        {"amount": "4102.18", "currency": "USD", "workspace_id": "wrkspc_platform", "workspace_name": "platform", "description": "claude-sonnet-4-6 input", "token_type": "input"},
+        {"amount": "2890.55", "currency": "USD", "workspace_id": "wrkspc_platform", "workspace_name": "platform", "description": "claude-sonnet-4-6 output", "token_type": "output"},
+        {"amount": "1744.30", "currency": "USD", "workspace_id": null, "workspace_name": null, "description": "default workspace", "token_type": "input"}
+      ]
+    }
+  ]
+}

unalloc/fixtures/litellm_spend.json

@@ -0,0 +1,34 @@
+{
+  "data": [
+    {
+      "request_id": "req_01", "model": "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",
+      "request_tags": ["feature:rerank", "environment:prod"],
+      "metadata": {"service": "search-api"}, "cache_hit": false
+    },
+    {
+      "request_id": "req_02", "model": "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",
+      "request_tags": ["feature:agent-loop", "environment:prod"],
+      "metadata": {"service": "agent-runtime"}, "cache_hit": true
+    },
+    {
+      "request_id": "req_03", "model": "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",
+      "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"],
+      "metadata": {}, "cache_hit": false
+    }
+  ]
+}

unalloc/fixtures/openai_costs.json

@@ -0,0 +1,13 @@
+{
+  "object": "page",
+  "data": [
+    {
+      "object": "bucket", "start_time": 1785600000, "end_time": 1788278400,
+      "results": [
+        {"object": "organization.costs.result", "amount": {"value": 2210.44, "currency": "usd"}, "project_id": "proj_search", "project_name": "search", "line_item": "gpt-4o"},
+        {"object": "organization.costs.result", "amount": {"value": 1180.02, "currency": "usd"}, "project_id": "proj_default", "project_name": null, "line_item": "gpt-4o-mini"},
+        {"object": "organization.costs.result", "amount": {"value": 640.9, "currency": "usd"}, "project_id": null, "project_name": null, "line_item": "text-embedding-3-large"}
+      ]
+    }
+  ]
+}

unalloc/fixtures/opencost_allocation.json

@@ -0,0 +1,72 @@
+{
+  "code": 200,
+  "data": [
+    {
+      "inference/llm-d-gateway": {
+        "name": "inference/llm-d-gateway",
+        "start": "2026-08-01T00:00:00Z",
+        "end": "2026-09-01T00:00:00Z",
+        "properties": {
+          "namespace": "inference",
+          "controller": "llm-d-gateway",
+          "controllerKind": "deployment",
+          "cluster": "prod-us-west",
+          "labels": {"team": "platform", "environment": "prod", "app_kubernetes_io_name": "llm-d"}
+        },
+        "cpuCost": 412.18, "ramCost": 188.44, "gpuCost": 9120.5, "sharedCost": 240.0,
+        "gpuHours": 2880.0, "totalCost": 9961.12, "totalEfficiency": 0.61
+      },
+      "inference/vllm-llama-70b": {
+        "name": "inference/vllm-llama-70b",
+        "start": "2026-08-01T00:00:00Z",
+        "end": "2026-09-01T00:00:00Z",
+        "properties": {
+          "namespace": "inference",
+          "controller": "vllm-llama-70b",
+          "controllerKind": "statefulset",
+          "cluster": "prod-us-west",
+          "labels": {"environment": "prod", "costCenter": "CC-4471"},
+          "modelName": "llama-3.3-70b"
+        },
+        "cpuCost": 290.0, "ramCost": 144.2, "gpuCost": 18402.9, "sharedCost": 310.0,
+        "gpuHours": 5760.0, "totalCost": 19147.1, "totalEfficiency": 0.34
+      },
+      "batch/embeddings-worker": {
+        "name": "batch/embeddings-worker",
+        "start": "2026-08-01T00:00:00Z",
+        "end": "2026-09-01T00:00:00Z",
+        "properties": {
+          "namespace": "batch",
+          "controller": "embeddings-worker",
+          "controllerKind": "cronjob",
+          "cluster": "prod-us-west",
+          "labels": {}
+        },
+        "cpuCost": 980.4, "ramCost": 402.1, "gpuCost": 3120.0, "sharedCost": 96.0,
+        "gpuHours": 960.0, "totalCost": 4598.5, "totalEfficiency": 0.08
+      },
+      "search/api": {
+        "name": "search/api",
+        "start": "2026-08-01T00:00:00Z",
+        "end": "2026-09-01T00:00:00Z",
+        "properties": {
+          "namespace": "search",
+          "controller": "api",
+          "controllerKind": "deployment",
+          "cluster": "prod-us-west",
+          "labels": {"team": "search", "environment": "prod"}
+        },
+        "cpuCost": 1840.2, "ramCost": 620.8, "gpuCost": 0, "sharedCost": 180.0,
+        "totalCost": 2641.0, "totalEfficiency": 0.71
+      },
+      "__idle__": {
+        "name": "__idle__",
+        "start": "2026-08-01T00:00:00Z",
+        "end": "2026-09-01T00:00:00Z",
+        "properties": {"cluster": "prod-us-west", "labels": {}},
+        "cpuCost": 610.0, "ramCost": 220.0, "gpuCost": 5240.0,
+        "totalCost": 6070.0, "totalEfficiency": 0.0
+      }
+    }
+  ]
+}

unalloc/render/__init__.py

@@ -0,0 +1 @@
+from __future__ import annotations

unalloc/render/table.py

@@ -0,0 +1,159 @@
+"""Rendering. The unallocated percentage is the thing people screenshot, so it
+gets a banner rather than a row buried in a table.
+"""
+
+from __future__ import annotations
+
+import dataclasses
+import json
+from decimal import Decimal
+from typing import Any
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from unalloc.core.attribute import AttributionReport
+from unalloc.core.models import UNALLOCATED, CostRow
+from unalloc.core.reconcile import ReconciliationReport
+
+console = Console()
+
+
+def usd(amount: Decimal) -> str:
+    return f"${amount:,.2f}"
+
+
+def _severity(pct: Decimal) -> str:
+    if pct >= 25:
+        return "bold red"
+    if pct >= 10:
+        return "bold yellow"
+    return "bold green"
+
+
+def render_report(report: AttributionReport, *, top: int = 20) -> None:
+    style = _severity(report.unallocated_pct)
+    console.print(
+        Panel(
+            Text.assemble(
+                (f"{report.unallocated_pct}%", style),
+                (" of ", "dim"),
+                (usd(report.total_usd), "bold"),
+                (" AI spend is unattributed", "dim"),
+                ("\n", ""),
+                (f"{usd(report.unallocated_usd)} has no '{report.dimension}' label", "dim"),
+                *(
+                    [
+                        ("\n", ""),
+                        (
+                            f"{usd(report.fallback_usd)} attributed only via fallback "
+                            f"({', '.join(report.fallback_dimensions)})",
+                            "yellow",
+                        ),
+                    ]
+                    if report.fallback_usd
+                    else []
+                ),
+            ),
+            title="unalloc",
+            border_style=style.split()[-1],
+        )
+    )
+
+    table = Table(title=f"Spend by {report.dimension}", header_style="bold")
+    table.add_column(report.dimension)
+    table.add_column("Cost", justify="right")
+    table.add_column("Share", justify="right")
+    table.add_column("Sources")
+    table.add_column("Rows", justify="right")
+
+    for bucket in report.buckets[:top]:
+        share = (
+            (bucket.amount_usd / report.total_usd * 100).quantize(Decimal("0.1"))
+            if report.total_usd
+            else Decimal("0")
+        )
+        label = (
+            Text(UNALLOCATED, style="bold red")
+            if bucket.is_unallocated
+            else Text(bucket.key)
+        )
+        table.add_row(
+            label,
+            usd(bucket.amount_usd),
+            f"{share}%",
+            ", ".join(bucket.by_source),
+            str(bucket.row_count),
+        )
+    console.print(table)
+
+    sources = Table(title="By source", header_style="bold")
+    sources.add_column("Source")
+    sources.add_column("Cost", justify="right")
+    for source, amount in report.by_source.items():
+        sources.add_row(source, usd(amount))
+    sources.add_row(Text("total", style="bold"), Text(usd(report.total_usd), style="bold"))
+    console.print(sources)
+
+
+def render_unallocated(rows: list[CostRow], dimension: str) -> None:
+    table = Table(
+        title=f"Labeling backlog — rows missing '{dimension}', by cost",
+        header_style="bold",
+    )
+    table.add_column("#", justify="right", style="dim")
+    table.add_column("Source")
+    table.add_column("Cost object")
+    table.add_column("Cost", justify="right")
+    table.add_column("Labels it does have", style="dim")
+
+    for index, row in enumerate(rows, start=1):
+        available = ", ".join(sorted(row.labels)) or "none"
+        table.add_row(str(index), row.source, row.name, usd(row.amount_usd), available)
+    console.print(table)
+    if not rows:
+        console.print("[green]Nothing unallocated. Ship it.[/green]")
+
+
+def render_reconciliation(report: ReconciliationReport) -> None:
+    table = Table(title="Ledger vs invoice", header_style="bold")
+    table.add_column("Source")
+    table.add_column("Ledger", justify="right")
+    table.add_column("Invoice", justify="right")
+    table.add_column("Delta", justify="right")
+    table.add_column("Status")
+
+    palette = {"matched": "green", "over": "red", "under": "yellow", "no-invoice": "dim"}
+    for item in report.per_source:
+        status = item.status(report.tolerance_pct)
+        delta = item.delta_usd
+        table.add_row(
+            item.source,
+            usd(item.ledger_usd),
+            usd(item.invoice_usd) if item.invoice_usd is not None else "—",
+            f"{usd(delta)} ({item.delta_pct}%)" if delta is not None else "—",
+            Text(status, style=palette[status]),
+        )
+    console.print(table)
+    if not report.clean:
+        console.print(
+            "[yellow]The ledger does not tie out. Attribution built on this "
+            "is not defensible yet.[/yellow]"
+        )
+
+
+def to_json(payload: Any) -> str:
+    def default(value: Any) -> Any:
+        if isinstance(value, Decimal):
+            # String, not float: JSON floats would reintroduce the precision
+            # loss the whole ledger is built to avoid.
+            return str(value)
+        if hasattr(value, "isoformat"):
+            return value.isoformat()
+        if dataclasses.is_dataclass(value) and not isinstance(value, type):
+            return dataclasses.asdict(value)
+        raise TypeError(type(value))
+
+    return json.dumps(payload, indent=2, default=default)

unalloc/sources/__init__.py

@@ -0,0 +1,25 @@
+"""Cost source adapters."""
+
+from __future__ import annotations
+
+from unalloc.sources.anthropic import AnthropicSource
+from unalloc.sources.base import Source
+from unalloc.sources.litellm import LiteLLMSource
+from unalloc.sources.openai import OpenAISource
+from unalloc.sources.opencost import OpenCostSource
+
+REGISTRY: dict[str, type[Source]] = {
+    OpenCostSource.name: OpenCostSource,
+    LiteLLMSource.name: LiteLLMSource,
+    OpenAISource.name: OpenAISource,
+    AnthropicSource.name: AnthropicSource,
+}
+
+__all__ = [
+    "REGISTRY",
+    "AnthropicSource",
+    "LiteLLMSource",
+    "OpenAISource",
+    "OpenCostSource",
+    "Source",
+]

unalloc/sources/anthropic.py

@@ -0,0 +1,73 @@
+"""Anthropic organization cost report adapter.
+
+Shape mirrors the OpenAI adapter closely: time buckets containing per-workspace
+cost results. Workspace is the attribution dimension available here.
+"""
+
+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
+
+ANTHROPIC_VERSION = "2023-06-01"
+
+
+class AnthropicSource(Source):
+    name = "anthropic"
+    default_base_url = "https://api.anthropic.com/v1"
+
+    def _headers(self) -> dict[str, str]:
+        # The Admin API authenticates with x-api-key, not a Bearer token.
+        headers = {"Accept": "application/json", "anthropic-version": ANTHROPIC_VERSION}
+        if self.token:
+            headers["x-api-key"] = self.token
+        return headers
+
+    def fetch(self, start: datetime, end: datetime) -> list[CostRow]:
+        payload = self._get_pages(
+            "/organizations/cost_report",
+            params={
+                "starting_at": start.date().isoformat(),
+                "ending_at": end.date().isoformat(),
+                "group_by[]": "workspace_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("starting_at"))
+            end = parse_ts(bucket.get("ending_at"), 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:
+        raw_labels = {
+            "workspace_id": result.get("workspace_id"),
+            "workspace": result.get("workspace_name"),
+            "description": result.get("description"),
+            "provider": "anthropic",
+        }
+        return CostRow(
+            source=self.name,
+            name=str(result.get("description") or result.get("workspace_id") or "anthropic-usage"),
+            amount_usd=money(result.get("amount")),
+            start=start,
+            end=end,
+            labels=normalize_labels(raw_labels, self.aliases),
+            meta={"currency": result.get("currency"), "token_type": result.get("token_type")},
+        )

unalloc/sources/base.py

@@ -0,0 +1,140 @@
+"""Adapter contract.
+
+An adapter does exactly two things: fetch a provider payload, and turn it into
+CostRows. It must not aggregate, filter by cost, or make attribution decisions.
+Keeping adapters dumb is what lets new providers be added in an afternoon.
+"""
+
+from __future__ import annotations
+
+import json
+from abc import ABC, abstractmethod
+from datetime import UTC, datetime
+from decimal import Decimal, InvalidOperation
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+from unalloc.core.models import CostRow
+
+DEFAULT_TIMEOUT = 30.0
+
+# Hard stop for cursor pagination. A provider that keeps saying has_more is a
+# bug on their side, and looping forever against a billing API is worse.
+MAX_PAGES = 1000
+
+
+class Source(ABC):
+    """Base class for every cost source."""
+
+    name: str = "unknown"
+
+    default_base_url: str | None = None
+    """Public API root, for providers that have one. An unset or empty
+    `base_url` falls back to this, so a blank env var does not disable it."""
+
+    def __init__(
+        self,
+        *,
+        base_url: str | None = None,
+        token: str | None = None,
+        timeout: float = DEFAULT_TIMEOUT,
+        aliases: dict[str, str] | None = None,
+    ) -> None:
+        self.base_url = (base_url or self.default_base_url or "").rstrip("/")
+        self.token = token
+        self.timeout = timeout
+        self.aliases = aliases or {}
+
+    # --- to implement per provider -------------------------------------
+
+    @abstractmethod
+    def fetch(self, start: datetime, end: datetime) -> list[CostRow]:
+        """Call the provider and return normalized rows."""
+
+    @abstractmethod
+    def parse(self, payload: Any) -> list[CostRow]:
+        """Turn a raw provider payload into CostRows.
+
+        Kept separate from `fetch` so the fixtures in examples/ are a real test
+        of the parsing contract and the tool is demoable with zero infra.
+        """
+
+    # --- shared plumbing ------------------------------------------------
+
+    def from_fixture(self, path: str | Path) -> list[CostRow]:
+        with Path(path).open() as handle:
+            return self.parse(json.load(handle))
+
+    def _headers(self) -> dict[str, str]:
+        """Request headers. Override when a provider does not take Bearer auth."""
+        headers = {"Accept": "application/json"}
+        if self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+        return headers
+
+    def _get(self, path: str, params: dict[str, Any] | None = None) -> Any:
+        if not self.base_url:
+            raise ValueError(
+                f"{self.name}: no base_url configured. Set UNALLOC_{self.name.upper()}_URL "
+                f"or run with --fixtures to demo without infrastructure."
+            )
+        with httpx.Client(timeout=self.timeout) as client:
+            response = client.get(
+                f"{self.base_url}{path}", params=params, headers=self._headers()
+            )
+            response.raise_for_status()
+            return response.json()
+
+    def _get_pages(self, path: str, params: dict[str, Any]) -> dict[str, Any]:
+        """Follow `has_more` / `next_page` cursors and concatenate `data`.
+
+        OpenAI's and Anthropic's admin reporting APIs both page this way. A
+        30-day window grouped by project easily exceeds one page, and silently
+        reading only the first page under-reports spend.
+        """
+        data: list[Any] = []
+        query = dict(params)
+        for _ in range(MAX_PAGES):
+            payload = self._get(path, params=query)
+            if not isinstance(payload, dict):
+                break
+            data.extend(payload.get("data") or [])
+            cursor = payload.get("next_page")
+            if not payload.get("has_more") or not cursor:
+                break
+            query["page"] = cursor
+        return {"data": data}
+
+
+def money(value: Any) -> Decimal:
+    """Coerce a provider's cost field to Decimal without ever going via float.
+
+    Providers are inconsistent: OpenCost sends JSON floats, LiteLLM sends
+    strings, some send None for zero. str() before Decimal keeps float noise
+    (0.30000000000000004) out of the ledger.
+    """
+    if value is None:
+        return Decimal("0")
+    try:
+        return Decimal(str(value))
+    except (InvalidOperation, ValueError):
+        return Decimal("0")
+
+
+def parse_ts(value: Any, default: datetime | None = None) -> datetime:
+    """Parse the assorted timestamp formats providers emit, as UTC-aware."""
+    if isinstance(value, datetime):
+        return value if value.tzinfo else value.replace(tzinfo=UTC)
+    if isinstance(value, (int, float)):
+        return datetime.fromtimestamp(value, tz=UTC)
+    if isinstance(value, str) and value:
+        text = value.replace("Z", "+00:00")
+        try:
+            parsed = datetime.fromisoformat(text)
+        except ValueError:
+            pass
+        else:
+            return parsed if parsed.tzinfo else parsed.replace(tzinfo=UTC)
+    return default or datetime.now(tz=UTC)