unalloc 0.2.0__py3-none-any.whl

unalloc/__init__.py

@@ -0,0 +1,6 @@
+"""unalloc — find the AI spend nobody owns."""
+
+from __future__ import annotations
+
+__version__ = "0.2.0"
+__all__ = ["__version__"]

unalloc/cli.py

@@ -0,0 +1,252 @@
+"""unalloc command line interface.
+
+Three commands, one question each:
+  report      how much of our AI spend is unattributed?
+  labels      which cost objects should we fix first?
+  reconcile   does the ledger agree with the invoice?
+"""
+
+from __future__ import annotations
+
+import os
+from datetime import UTC, datetime, timedelta
+from decimal import Decimal
+from pathlib import Path
+
+import typer
+
+from unalloc import __version__
+from unalloc.core.attribute import attribute, unallocated_rows
+from unalloc.core.models import CostRow, Invoice
+from unalloc.core.normalize import dimensions
+from unalloc.core.reconcile import DEFAULT_TOLERANCE_PCT, reconcile
+from unalloc.render import table as render
+from unalloc.sources import REGISTRY
+
+app = typer.Typer(
+    add_completion=False,
+    help="Find the AI spend nobody owns. Joins Kubernetes allocation data with "
+    "LLM provider bills and reports what is unattributed.",
+)
+
+# Fixtures ship inside the package so `--fixtures` works from an installed
+# wheel, not just from a clone. A clean-venv install is the only way to
+# catch this, so `make check-wheel` does exactly that.
+FIXTURE_DIR = Path(__file__).resolve().parent / "fixtures"
+
+FIXTURE_FILES = {
+    "opencost": "opencost_allocation.json",
+    "litellm": "litellm_spend.json",
+    "openai": "openai_costs.json",
+    "anthropic": "anthropic_cost_report.json",
+}
+
+ENV_URL = {
+    "opencost": "UNALLOC_OPENCOST_URL",
+    "litellm": "UNALLOC_LITELLM_URL",
+    "openai": "UNALLOC_OPENAI_URL",
+    "anthropic": "UNALLOC_ANTHROPIC_URL",
+}
+
+ENV_TOKEN = {
+    "litellm": "UNALLOC_LITELLM_KEY",
+    "openai": "OPENAI_ADMIN_KEY",
+    "anthropic": "ANTHROPIC_ADMIN_KEY",
+}
+
+
+def _window(days: int) -> tuple[datetime, datetime]:
+    end = datetime.now(tz=UTC)
+    return end - timedelta(days=days), end
+
+
+def _load(
+    sources: list[str],
+    *,
+    fixtures: bool,
+    days: int,
+    fixture_dir: Path,
+) -> list[CostRow]:
+    start, end = _window(days)
+    rows: list[CostRow] = []
+    for name in sources:
+        if name not in REGISTRY:
+            raise typer.BadParameter(
+                f"unknown source '{name}'. Known: {', '.join(sorted(REGISTRY))}"
+            )
+        adapter = REGISTRY[name](
+            base_url=os.environ.get(ENV_URL.get(name, "")) or None,
+            token=os.environ.get(ENV_TOKEN.get(name, "")) or None,
+        )
+        if fixtures:
+            path = fixture_dir / FIXTURE_FILES[name]
+            if not path.exists():
+                typer.secho(f"skipping {name}: no fixture at {path}", fg="yellow")
+                continue
+            rows.extend(adapter.from_fixture(path))
+        else:
+            try:
+                rows.extend(adapter.fetch(start, end))
+            except Exception as exc:
+                typer.secho(f"{name}: {exc}", fg="red", err=True)
+    return rows
+
+
+SourcesOpt = typer.Option(
+    ["opencost", "litellm", "openai", "anthropic"],
+    "--source",
+    "-s",
+    help="Source to pull. Repeat the flag for several.",
+)
+FixturesOpt = typer.Option(
+    False, "--fixtures", help="Run against bundled sample payloads. No infra needed."
+)
+DaysOpt = typer.Option(30, "--days", "-d", help="Lookback window in days.")
+DimensionOpt = typer.Option(
+    "team", "--dimension", "-D", help="Label key to attribute on."
+)
+FallbackOpt = typer.Option(
+    [],
+    "--fallback",
+    "-f",
+    help="Second-choice label keys, tried in order before a row is called "
+    "unallocated. Keep this short and defensible.",
+)
+JsonOpt = typer.Option(False, "--json", help="Emit JSON instead of tables.")
+FixtureDirOpt = typer.Option(FIXTURE_DIR, "--fixture-dir", help="Where fixtures live.")
+
+
+@app.command()
+def report(
+    source: list[str] = SourcesOpt,
+    dimension: str = DimensionOpt,
+    fallback: list[str] = FallbackOpt,
+    days: int = DaysOpt,
+    fixtures: bool = FixturesOpt,
+    fixture_dir: Path = FixtureDirOpt,
+    top: int = typer.Option(20, "--top", help="Rows to show."),
+    as_json: bool = JsonOpt,
+    budget: float | None = typer.Option(
+        None,
+        "--budget",
+        help="Exit with code 2 when the unallocated share exceeds this percent. "
+        "Lets CI fail a deploy that ships unlabeled spend.",
+    ),
+) -> None:
+    """Attribute joined spend and report the unallocated share."""
+    rows = _load(source, fixtures=fixtures, days=days, fixture_dir=fixture_dir)
+    if not rows:
+        typer.secho("No cost rows loaded. Try --fixtures.", fg="yellow")
+        raise typer.Exit(code=1)
+
+    result = attribute(rows, dimension, fallback_dimensions=tuple(fallback))
+    if as_json:
+        typer.echo(
+            render.to_json(
+                {
+                    "dimension": result.dimension,
+                    "total_usd": result.total_usd,
+                    "unallocated_usd": result.unallocated_usd,
+                    "unallocated_pct": result.unallocated_pct,
+                    "fallback_dimensions": result.fallback_dimensions,
+                    "fallback_usd": result.fallback_usd,
+                    "by_source": result.by_source,
+                    "buckets": result.buckets,
+                }
+            )
+        )
+    else:
+        render.render_report(result, top=top)
+
+    if budget is not None and result.unallocated_pct > Decimal(str(budget)):
+        typer.secho(
+            f"unallocated {result.unallocated_pct}% exceeds budget {budget}%",
+            fg="red",
+            err=True,
+        )
+        raise typer.Exit(code=2)
+
+
+@app.command()
+def labels(
+    source: list[str] = SourcesOpt,
+    dimension: str = DimensionOpt,
+    fallback: list[str] = FallbackOpt,
+    days: int = DaysOpt,
+    fixtures: bool = FixturesOpt,
+    fixture_dir: Path = FixtureDirOpt,
+    limit: int = typer.Option(20, "--limit", help="Rows in the backlog."),
+    available: bool = typer.Option(
+        False, "--available", help="List label keys present in the data instead."
+    ),
+) -> None:
+    """Show the labeling backlog: unattributed cost objects, priciest first."""
+    rows = _load(source, fixtures=fixtures, days=days, fixture_dir=fixture_dir)
+    if not rows:
+        # Without this, an unreachable source reads as "Nothing unallocated".
+        typer.secho("No cost rows loaded. Try --fixtures.", fg="yellow")
+        raise typer.Exit(code=1)
+    if available:
+        for key, count in dimensions(rows).items():
+            typer.echo(f"{count:>6}  {key}")
+        return
+    backlog = unallocated_rows(
+        rows, dimension, fallback_dimensions=tuple(fallback), limit=limit
+    )
+    render.render_unallocated(backlog, dimension)
+
+
+@app.command(name="reconcile")
+def reconcile_cmd(
+    source: list[str] = SourcesOpt,
+    days: int = DaysOpt,
+    fixtures: bool = FixturesOpt,
+    fixture_dir: Path = FixtureDirOpt,
+    invoice: list[str] = typer.Option(
+        [],
+        "--invoice",
+        "-i",
+        help="Billed total per source as SOURCE=AMOUNT, e.g. openai=4210.55. "
+        "Repeat the flag per source.",
+    ),
+    tolerance: float = typer.Option(
+        float(DEFAULT_TOLERANCE_PCT),
+        "--tolerance",
+        help="Percent delta treated as rounding rather than a real gap.",
+    ),
+) -> None:
+    """Check the ledger against what each provider actually billed."""
+    rows = _load(source, fixtures=fixtures, days=days, fixture_dir=fixture_dir)
+    start, end = _window(days)
+
+    invoices: list[Invoice] = []
+    for entry in invoice:
+        if "=" not in entry:
+            raise typer.BadParameter(f"expected SOURCE=AMOUNT, got '{entry}'")
+        name, _, amount = entry.partition("=")
+        invoices.append(
+            Invoice(
+                source=name.strip(),
+                amount_usd=Decimal(amount.strip()),
+                start=start,
+                end=end,
+            )
+        )
+
+    render.render_reconciliation(
+        reconcile(rows, invoices, tolerance_pct=Decimal(str(tolerance)))
+    )
+
+
+@app.command()
+def version() -> None:
+    """Print the installed version."""
+    typer.echo(__version__)
+
+
+def main() -> None:
+    app()
+
+
+if __name__ == "__main__":
+    main()

unalloc/core/__init__.py

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

unalloc/core/attribute.py

@@ -0,0 +1,140 @@
+"""Attribution: group a mixed ledger on one dimension and expose the gap.
+
+Everything here is deliberately boring. The interesting claim unalloc makes is
+not the grouping, it is that infra rows and LLM API rows can sit in the same
+grouping at all.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+from dataclasses import dataclass, field
+from decimal import Decimal
+
+from unalloc.core.models import UNALLOCATED, CostRow
+
+ZERO = Decimal("0")
+
+
+@dataclass(frozen=True, slots=True)
+class Bucket:
+    """Spend for one value of the attribution dimension."""
+
+    key: str
+    amount_usd: Decimal
+    by_source: dict[str, Decimal] = field(default_factory=dict)
+    row_count: int = 0
+
+    @property
+    def is_unallocated(self) -> bool:
+        return self.key == UNALLOCATED
+
+
+@dataclass(frozen=True, slots=True)
+class AttributionReport:
+    dimension: str
+    total_usd: Decimal
+    buckets: list[Bucket]
+    by_source: dict[str, Decimal]
+    unallocated_usd: Decimal
+    row_count: int
+    fallback_dimensions: tuple[str, ...] = ()
+    fallback_usd: Decimal = ZERO
+    """Spend that counts as allocated only because a fallback key matched.
+    Reported separately so a fallback onto something that is not an owner
+    (a chart name, a namespace shared by teams) cannot hide inside the
+    headline percentage."""
+
+    @property
+    def unallocated_pct(self) -> Decimal:
+        """The headline number. Zero total means zero gap, not a crash."""
+        if self.total_usd == ZERO:
+            return ZERO
+        return (self.unallocated_usd / self.total_usd * 100).quantize(Decimal("0.1"))
+
+    @property
+    def allocated_usd(self) -> Decimal:
+        return self.total_usd - self.unallocated_usd
+
+
+def attribute(
+    rows: Iterable[CostRow],
+    dimension: str,
+    *,
+    fallback_dimensions: Sequence[str] = (),
+) -> AttributionReport:
+    """Group `rows` by `dimension`, bucketing label-less spend as unallocated.
+
+    `fallback_dimensions` lets you accept a second-best key before giving up on
+    a row: attributing on `team`, falling back to `namespace`, is usually more
+    honest than reporting 60% unallocated when the data is merely inconsistent.
+    Fallback hits are still counted as allocated, so keep the list short and
+    defensible.
+    """
+    rows = list(rows)
+    totals: dict[str, Decimal] = {}
+    per_source: dict[str, dict[str, Decimal]] = {}
+    counts: dict[str, int] = {}
+    by_source: dict[str, Decimal] = {}
+    total = ZERO
+    via_fallback = ZERO
+
+    for row in rows:
+        key = row.label(dimension)
+        if key is None:
+            for alt in fallback_dimensions:
+                key = row.label(alt)
+                if key is not None:
+                    via_fallback += row.amount_usd
+                    break
+        key = key or UNALLOCATED
+
+        totals[key] = totals.get(key, ZERO) + row.amount_usd
+        counts[key] = counts.get(key, 0) + 1
+        per_source.setdefault(key, {})
+        per_source[key][row.source] = per_source[key].get(row.source, ZERO) + row.amount_usd
+        by_source[row.source] = by_source.get(row.source, ZERO) + row.amount_usd
+        total += row.amount_usd
+
+    buckets = [
+        Bucket(
+            key=key,
+            amount_usd=amount,
+            by_source=dict(sorted(per_source[key].items())),
+            row_count=counts[key],
+        )
+        for key, amount in totals.items()
+    ]
+    # Largest spend first, but the unallocated bucket always sorts last so it
+    # reads as the punchline rather than getting lost mid-table.
+    buckets.sort(key=lambda b: (b.is_unallocated, -b.amount_usd))
+
+    return AttributionReport(
+        dimension=dimension,
+        total_usd=total,
+        buckets=buckets,
+        by_source=dict(sorted(by_source.items())),
+        unallocated_usd=totals.get(UNALLOCATED, ZERO),
+        row_count=len(rows),
+        fallback_dimensions=tuple(fallback_dimensions),
+        fallback_usd=via_fallback,
+    )
+
+
+def unallocated_rows(
+    rows: Iterable[CostRow],
+    dimension: str,
+    *,
+    fallback_dimensions: Sequence[str] = (),
+    limit: int = 20,
+) -> list[CostRow]:
+    """The rows that have no value for `dimension`, most expensive first.
+
+    This is the actionable output: a labeling backlog sorted by dollars. It
+    honours the same fallbacks as `attribute`, so the backlog always sums to
+    the unallocated bucket of the matching report.
+    """
+    keys = (dimension, *fallback_dimensions)
+    missing = [row for row in rows if all(row.label(key) is None for key in keys)]
+    missing.sort(key=lambda r: r.amount_usd, reverse=True)
+    return missing[:limit]

unalloc/core/models.py

@@ -0,0 +1,72 @@
+"""The one data structure every cost source normalizes into.
+
+The entire design of unalloc rests on this: an adapter's only job is to turn a
+provider's payload into CostRows. Attribution, reconciliation and rendering all
+operate on CostRows and know nothing about where they came from.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from decimal import Decimal
+from typing import Any
+
+# Label key used to bucket spend that carries no value for the requested
+# attribution dimension. This is the number the tool exists to produce.
+UNALLOCATED = "<unallocated>"
+
+
+@dataclass(frozen=True, slots=True)
+class CostRow:
+    """A single unit of spend, normalized across infra and LLM providers.
+
+    Money is Decimal, never float. Cost attribution that disagrees with the
+    invoice by a penny per row is how you lose an argument with finance.
+    """
+
+    source: str
+    """Adapter that produced this row: opencost, litellm, openai, anthropic."""
+
+    name: str
+    """Human-readable identity of the cost object (pod, key, project, model)."""
+
+    amount_usd: Decimal
+    """Cost in USD for the window [start, end)."""
+
+    start: datetime
+    end: datetime
+
+    labels: dict[str, str] = field(default_factory=dict)
+    """Normalized, lowercased label keys -> values. The attribution dimension
+    is looked up here."""
+
+    quantity: Decimal | None = None
+    """Optional usage amount (tokens, core-hours). Not used for attribution,
+    but carried through so unit-economics math is possible later."""
+
+    unit: str | None = None
+    """Unit for `quantity`, e.g. "tokens", "core-hours", "gpu-hours"."""
+
+    meta: dict[str, Any] = field(default_factory=dict)
+    """Anything source-specific worth keeping for debugging. Never read by
+    core logic."""
+
+    def label(self, dimension: str) -> str | None:
+        """Return the value for `dimension`, or None if this row is unallocated."""
+        value = self.labels.get(dimension)
+        if value is None:
+            return None
+        value = value.strip()
+        return value or None
+
+
+@dataclass(frozen=True, slots=True)
+class Invoice:
+    """What the provider says you owe, for reconciliation against the ledger."""
+
+    source: str
+    amount_usd: Decimal
+    start: datetime
+    end: datetime
+    note: str = ""

unalloc/core/normalize.py

@@ -0,0 +1,143 @@
+"""Label canonicalization.
+
+The whole premise of unalloc is joining ledgers that never agreed on a key.
+OpenCost gives you `label_cost_center` or `labels.costCenter`. LiteLLM gives you
+`team_id` or a request tag. OpenAI gives you a project name. None of them will
+match on a naive dict lookup, so every adapter runs its labels through here
+before emitting a CostRow.
+"""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Iterable, Mapping
+
+_NON_ALNUM = re.compile(r"[^a-z0-9]+")
+
+# Prefixes providers bolt onto label keys that carry no meaning for us.
+_STRIP_PREFIXES = (
+    "label_",
+    "labels_",
+    "annotation_",
+    "kubernetes_io_",
+    "app_kubernetes_io_",
+    "tag_",
+    "request_tag_",
+)
+
+# Default alias table: many spellings of the same business dimension.
+# Extend this per-org via `aliases` in config rather than editing code.
+DEFAULT_ALIASES: dict[str, str] = {
+    "costcenter": "cost_center",
+    "cost_centre": "cost_center",
+    "cc": "cost_center",
+    "team_id": "team",
+    "teamid": "team",
+    "owning_team": "team",
+    "owner": "team",
+    "squad": "team",
+    "project_id": "project",
+    "projectid": "project",
+    "proj": "project",
+    "workspace_id": "workspace",
+    "svc": "service",
+    "app": "service",
+    "application": "service",
+    "env": "environment",
+    "stage": "environment",
+}
+
+
+def canonical_key(key: str) -> str:
+    """Normalize one label key to snake_case with provider noise stripped.
+
+    >>> canonical_key("label_costCenter")
+    'cost_center'
+    >>> canonical_key("app.kubernetes.io/name")
+    'name'
+    """
+    key = key.strip()
+    # camelCase -> camel_case before lowercasing, or we lose word boundaries.
+    key = re.sub(r"(?<=[a-z0-9])(?=[A-Z])", "_", key)
+    key = key.lower()
+    # Path-style keys: app.kubernetes.io/name -> name
+    if "/" in key:
+        key = key.rsplit("/", 1)[-1]
+    key = _NON_ALNUM.sub("_", key).strip("_")
+    # Strip until nothing matches: OpenCost's Prometheus-style keys stack
+    # prefixes (label_app_kubernetes_io_name), and stopping after one made the
+    # same Kubernetes label canonicalize differently depending on the endpoint.
+    stripped = True
+    while stripped:
+        stripped = False
+        for prefix in _STRIP_PREFIXES:
+            if key.startswith(prefix) and len(key) > len(prefix):
+                key = key[len(prefix) :]
+                stripped = True
+                break
+    return key
+
+
+def _precedence(raw_key: str, canon: str, aliased: bool) -> tuple[int, str]:
+    """Rank competing raw keys that land on the same canonical key.
+
+    Lower wins: a key already written canonically, then an alias, then a key
+    that needed rewriting (prefix, camelCase), then a path-derived key. Ties
+    break on the raw key itself, so the result never depends on the order a
+    provider happened to serialize its labels in.
+    """
+    written = raw_key.strip().lower()
+    if written == canon and not aliased:
+        rank = 0
+    elif aliased:
+        rank = 1
+    elif "/" not in written:
+        rank = 2
+    else:
+        rank = 3
+    return rank, written
+
+
+def normalize_labels(
+    raw: Mapping[str, object] | None,
+    aliases: Mapping[str, str] | None = None,
+) -> dict[str, str]:
+    """Canonicalize keys, apply the alias table, drop empty values.
+
+    When several raw keys collapse onto one canonical key, `_precedence`
+    decides deterministically: an explicit `team` label wins over a `team_id`
+    that aliases onto it, and `app.kubernetes.io/name` vs
+    `leaderworkerset.sigs.k8s.io/name` resolves the same way whatever order
+    the provider sent them in.
+    """
+    if not raw:
+        return {}
+    table = {**DEFAULT_ALIASES, **(aliases or {})}
+    best: dict[str, tuple[tuple[int, str], str]] = {}
+    for key, value in raw.items():
+        if value is None:
+            continue
+        text = str(value).strip()
+        if not text:
+            continue
+        shaped = canonical_key(str(key))
+        if not shaped:
+            continue
+        canon = table.get(shaped, shaped)
+        rank = _precedence(str(key), canon, aliased=canon != shaped)
+        if canon not in best or rank < best[canon][0]:
+            best[canon] = (rank, text)
+    return {canon: text for canon, (_, text) in best.items()}
+
+
+def dimensions(rows: Iterable) -> dict[str, int]:
+    """Count how many rows carry each label key.
+
+    Useful for `unalloc labels`: it tells you which dimensions are actually
+    viable to attribute on before you pick one.
+    """
+    counts: dict[str, int] = {}
+    for row in rows:
+        for key in row.labels:
+            counts[key] = counts.get(key, 0) + 1
+    return dict(sorted(counts.items(), key=lambda kv: -kv[1]))