cctally 1.21.3 → 1.22.0

package/bin/_lib_doctor.py

@@ -130,6 +130,16 @@ class DoctorState:
     cctally_reachable_on_path: Optional[bool] = None
     symlinks_path_pinned: bool = False
     install_is_brew: bool = False
+    # Pricing coverage (spec §5.1): the list[CoverageGap] of unpriced (Claude
+    # $0) / fallback (Codex gpt-5) models observed in the trailing 30-day
+    # window, populated by `doctor_gather_state` via `_pricing_observed_models`
+    # + `classify_coverage`. None means the cache could not be read (or the
+    # classification raised) — the check degrades to OK ("no cached usage to
+    # assess"), consistent with the kernel's degradation posture. Each element
+    # is a `_lib_pricing_check.CoverageGap` (provider/model/kind/entry_count/
+    # token_total); the kernel only reads `.kind`/`.model`/`.entry_count`/
+    # `.token_total`, so any duck-typed equivalent works for tests.
+    pricing_coverage: Optional[list] = None
 
 
 @dataclasses.dataclass(frozen=True)
@@ -761,6 +771,67 @@ def _check_data_post_credit_milestones(s: DoctorState) -> CheckResult:
     )
 
 
+def _check_pricing_coverage(s: DoctorState) -> CheckResult:
+    """WARN when recent (30-day) session data contains a model cctally cannot
+    price exactly (spec §5.1).
+
+    Two gap kinds (classified upstream in `_lib_pricing_check.classify_coverage`,
+    populated by `doctor_gather_state`):
+      * ``unpriced`` — a Claude model `_resolve_model_pricing` returns None for;
+        it silently contributes $0 (the serious undercount failure mode).
+      * ``fallback`` — a Codex model approximated via `gpt-5` pricing.
+
+    ``s.pricing_coverage is None`` means the cache could not be read (or the
+    classification raised) → OK ("no cached usage to assess"), matching the
+    rest of the kernel's degradation posture. An empty list → OK. Any gap →
+    WARN (a data-quality signal, deliberately NOT FAIL — doctor FAIL exits 2;
+    consistent with the other WARN-family Data checks).
+
+    ``details`` is a structured dict (sibling-check convention): two lists of
+    ``{model, entry_count, token_total}`` keyed by gap kind, so a `--json`
+    consumer can machine-read each gap. The human summary + remediation point
+    at `cctally pricing-check` and the pricing tables.
+    """
+    gaps = s.pricing_coverage
+    if not gaps:
+        return CheckResult(
+            id="pricing.coverage", title="Coverage",
+            severity="ok",
+            summary="all observed models priced",
+            remediation=None,
+            details={"unpriced": [], "fallback": []},
+        )
+
+    def _row(g) -> dict:
+        return {
+            "model": g.model,
+            "entry_count": g.entry_count,
+            "token_total": g.token_total,
+        }
+
+    unpriced = [_row(g) for g in gaps if g.kind == "unpriced"]
+    fallback = [_row(g) for g in gaps if g.kind == "fallback"]
+
+    parts: list[str] = []
+    if unpriced:
+        parts.append(f"{len(unpriced)} unpriced (Claude $0)")
+    if fallback:
+        parts.append(f"{len(fallback)} fallback (Codex gpt-5)")
+    # Defensive: a gap whose kind is neither (shouldn't happen) still WARNs.
+    summary = "; ".join(parts) if parts else f"{len(gaps)} coverage gaps"
+
+    return CheckResult(
+        id="pricing.coverage", title="Coverage",
+        severity="warn",
+        summary=summary,
+        remediation=(
+            "Run `cctally pricing-check`, then update CLAUDE_MODEL_PRICING / "
+            "CODEX_MODEL_PRICING in bin/_lib_pricing.py"
+        ),
+        details={"unpriced": unpriced, "fallback": fallback},
+    )
+
+
 _LOOPBACK_HOSTS = frozenset({"loopback", "127.0.0.1", "::1", "localhost"})
 
 
@@ -991,6 +1062,9 @@ _CATEGORY_DEFINITIONS: tuple[tuple[str, str, tuple[tuple[str, str], ...]], ...]
         ("data.forked_buckets", "_check_data_forked_buckets"),
         ("data.post_credit_milestones", "_check_data_post_credit_milestones"),
     )),
+    ("pricing", "Pricing", (
+        ("pricing.coverage", "_check_pricing_coverage"),
+    )),
     ("safety", "Safety", (
         ("safety.dashboard_bind", "_check_safety_dashboard_bind"),
         ("safety.config_json_valid", "_check_safety_config_json_valid"),

package/bin/_lib_pricing.py

@@ -46,9 +46,28 @@ def _chip_for_model(name: str) -> str:
     return "other"
 
 
+# Date the embedded pricing snapshots below were last verified against
+# vendor sources. Bump whenever CLAUDE_MODEL_PRICING / CODEX_MODEL_PRICING
+# is synced. Read by `pricing-check` + the release pre-flight staleness nudge.
+PRICING_SNAPSHOT_DATE = "2026-05-04"
+PRICING_STALENESS_DAYS = 60  # release pre-flight WARNs past this age
+
+# Canonical machine-readable pricing source (Claude values + Codex values).
+LITELLM_PRICES_URL = (
+    "https://raw.githubusercontent.com/BerriAI/litellm/main/"
+    "model_prices_and_context_window.json"
+)
+
+# Deliberate divergences from LiteLLM the drift check must NOT flag. Each
+# entry suppresses either a specific value mismatch ({"model","field","reason"})
+# or an intentionally-omitted in-scope model ({"model","reason"} — no field).
+# Guarded by `stale_allowlist_entries` (tests/test_pricing_check.py): an entry
+# that no longer corresponds to a real divergence fails the suite.
+PRICING_DRIFT_ALLOWLIST: list[dict] = []
+
 # Anthropic API pricing snapshot:
 # - Source: https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json
-# - Captured: 2026-05-04
+# - Captured: 2026-05-04 (see PRICING_SNAPSHOT_DATE)
 # - Verified by maintainer against docs.claude.com/en/docs/about-claude/pricing;
 #   update in PRs touching this table.
 CLAUDE_MODEL_PRICING: dict[str, dict[str, Any]] = {
@@ -246,7 +265,7 @@ _unknown_model_warnings: set[str] = set()
 #
 # Codex (OpenAI) API pricing snapshot:
 # - Source: https://raw.githubusercontent.com/BerriAI/litellm/main/model_prices_and_context_window.json
-# - Captured: 2026-05-04
+# - Captured: 2026-05-04 (see PRICING_SNAPSHOT_DATE)
 # - Models listed are those observed in ~/.codex/sessions/ at implementation
 #   time plus common Codex/GPT-5 variants. Models absent from this table fall
 #   back to `gpt-5` pricing with isFallback=true (matches upstream's
@@ -411,8 +430,16 @@ def _is_codex_fallback(model: str) -> bool:
     return model not in CODEX_MODEL_PRICING
 
 
-def _resolve_model_pricing(model: str) -> dict[str, Any] | None:
-    """Look up pricing for a model name. Returns None if unknown."""
+def _resolve_model_pricing(model: str, warn: bool = True) -> dict[str, Any] | None:
+    """Look up pricing for a model name. Returns None if unknown.
+
+    `warn=True` (default) emits a one-shot `[cost] unknown model` stderr warning
+    on a miss — correct for cost computation. Detection-only callers (e.g. the
+    doctor pricing-coverage scan, whose whole job is to find unpriced models)
+    pass `warn=False` so they don't fire the cost-engine warning as a side
+    effect, and don't poison `_unknown_model_warnings` (which would suppress a
+    later genuine cost-path warning for the same model).
+    """
     pricing = CLAUDE_MODEL_PRICING.get(model)
     if pricing is not None:
         return pricing
@@ -422,7 +449,7 @@ def _resolve_model_pricing(model: str) -> dict[str, Any] | None:
             pricing = CLAUDE_MODEL_PRICING.get(stripped)
             if pricing is not None:
                 return pricing
-    if model not in _unknown_model_warnings:
+    if warn and model not in _unknown_model_warnings:
         _unknown_model_warnings.add(model)
         _eprint(f"[cost] unknown model, treating cost as $0: {model}")
     return None

package/bin/_lib_pricing_check.py

@@ -0,0 +1,201 @@
+"""Pure-fn kernel for the pricing-freshness check (spec 2026-05-29).
+
+No I/O, no import of `cctally`/`_lib_pricing` at module scope — every
+dependency (pricing predicates, tables, observed rows, LiteLLM snapshot)
+is passed in by the I/O glue in bin/cctally. Re-exported there like the
+other _lib_* kernels.
+"""
+from __future__ import annotations
+
+import dataclasses
+
+
+@dataclasses.dataclass(frozen=True)
+class CoverageGap:
+    provider: str        # "claude" | "codex"
+    model: str
+    kind: str            # "unpriced" | "fallback"
+    entry_count: int
+    token_total: int
+
+
+@dataclasses.dataclass(frozen=True)
+class DriftRow:
+    model: str
+    field: str           # "" for whole-model categories
+    ours: float | None
+    theirs: float | None
+
+
+@dataclasses.dataclass(frozen=True)
+class DriftResult:
+    value_drift: list[DriftRow]
+    missing_from_us: list[str]
+    ahead_of_litellm: list[str]   # informational; never actionable
+
+
+def classify_coverage(observed, resolve_claude, is_codex_fallback) -> list[CoverageGap]:
+    """observed: iterable of (provider, model, entry_count, token_total).
+
+    Claude model with resolve_claude(model) is None -> kind="unpriced".
+    Codex model with is_codex_fallback(model) True  -> kind="fallback".
+    Priced models produce no gap. Order preserved.
+    """
+    gaps: list[CoverageGap] = []
+    for provider, model, entry_count, token_total in observed:
+        if provider == "claude":
+            if resolve_claude(model) is None:
+                gaps.append(CoverageGap("claude", model, "unpriced", entry_count, token_total))
+        elif provider == "codex":
+            if is_codex_fallback(model):
+                gaps.append(CoverageGap("codex", model, "fallback", entry_count, token_total))
+    return gaps
+
+
+def _is_codex_scope(name: str) -> bool:
+    # The Codex models we track are the gpt-5* family (incl. -codex variants).
+    # Keep this in sync with CODEX_MODEL_PRICING's key prefixes.
+    return name.startswith("gpt-5")
+
+
+def scope_litellm(litellm: dict) -> dict[str, dict]:
+    """Filter a full LiteLLM model_prices map down to the models we track:
+    anthropic-provider Claude models, and the gpt-5* Codex family. Skips the
+    `sample_spec` doc entry and any entry lacking a dict body."""
+    scoped: dict[str, dict] = {}
+    for name, body in litellm.items():
+        if not isinstance(body, dict):
+            continue
+        provider = body.get("litellm_provider")
+        if provider == "anthropic" and name.startswith("claude-"):
+            scoped[name] = body
+        elif provider == "openai" and _is_codex_scope(name):
+            scoped[name] = body
+    return scoped
+
+
+_DRIFT_EPS = 1e-12  # cost-per-token values are tiny; compare with a small abs epsilon
+
+
+def _allow_index(allowlist):
+    field_suppress = set()   # (model, field)
+    model_suppress = set()   # model (no field -> suppresses missing_from_us)
+    for e in allowlist or []:
+        if e.get("field"):
+            field_suppress.add((e["model"], e["field"]))
+        else:
+            model_suppress.add(e["model"])
+    return field_suppress, model_suppress
+
+
+def diff_pricing(claude_tbl, codex_tbl, litellm_scoped, allowlist=None) -> DriftResult:
+    """Direction-aware drift between our embedded tables and the scoped LiteLLM
+    snapshot.
+
+    value_drift     — shared model, a cost field differs beyond _DRIFT_EPS
+                      (actionable, unless allowlisted by model+field).
+    missing_from_us — scoped LiteLLM model absent from our tables
+                      (actionable, unless allowlisted by model with no field).
+    ahead_of_litellm — model we price that scoped LiteLLM lacks (informational;
+                      NEVER actionable — we may legitimately lead the source).
+
+    Value-drift is one-directional: it only compares fields LiteLLM carries, so
+    a cost field present in our table but absent upstream is not value-compared
+    (ahead_of_litellm reports at model granularity only). That matches the
+    feature's intent — catch vendor price moves on fields we track.
+    """
+    field_suppress, model_suppress = _allow_index(allowlist)
+    ours = {**claude_tbl, **codex_tbl}
+    value_drift: list[DriftRow] = []
+    missing: list[str] = []
+    ahead: list[str] = []
+
+    for model, body in litellm_scoped.items():
+        if model in ours:
+            for field, theirs in body.items():
+                # Broad cost-field filter; the `mine is None` guard below is what
+                # keeps it safe (skips any upstream cost field we don't carry), so
+                # don't remove that guard thinking this filter is precise.
+                if not field.endswith("_cost_per_token") and "cost" not in field:
+                    continue
+                # bool is an int subclass — exclude it so a non-numeric "cost" flag
+                # can never be read as a 0/1 price.
+                if isinstance(theirs, bool) or not isinstance(theirs, (int, float)):
+                    continue
+                if (model, field) in field_suppress:
+                    continue
+                mine = ours[model].get(field)
+                if mine is None:
+                    continue  # we don't carry this field; not a value-drift signal
+                if abs(float(mine) - float(theirs)) > _DRIFT_EPS:
+                    value_drift.append(DriftRow(model, field, float(mine), float(theirs)))
+        else:
+            if model not in model_suppress:
+                missing.append(model)
+
+    for model in ours:
+        if model not in litellm_scoped:
+            ahead.append(model)
+
+    return DriftResult(value_drift=value_drift, missing_from_us=missing, ahead_of_litellm=ahead)
+
+
+def stale_allowlist_entries(allowlist, claude_tbl, codex_tbl, litellm_scoped) -> list:
+    """Return allowlist entries that NO LONGER correspond to a real divergence.
+
+    An entry is stale if, with it removed, diff_pricing reports nothing it would
+    have suppressed (i.e. the value now matches / the model is now present)."""
+    ours = {**claude_tbl, **codex_tbl}
+    stale: list = []
+    for e in allowlist or []:
+        model = e["model"]
+        if e.get("field"):
+            theirs = (litellm_scoped.get(model) or {}).get(e["field"])
+            mine = (ours.get(model) or {}).get(e["field"])
+            real = (theirs is not None and mine is not None
+                    and abs(float(mine) - float(theirs)) > _DRIFT_EPS)
+        else:
+            # model-suppress entry: real only if litellm has it AND we don't
+            real = (model in litellm_scoped and model not in ours)
+        if not real:
+            stale.append(e)
+    return stale
+
+
+_CLAUDE_REQUIRED = ("input_cost_per_token", "output_cost_per_token",
+                    "cache_creation_input_token_cost", "cache_read_input_token_cost")
+_CODEX_REQUIRED = ("input_cost_per_token", "cache_read_input_token_cost",
+                   "output_cost_per_token")
+
+
+def check_table_shapes(claude_tbl, codex_tbl, zero_sentinels) -> list:
+    """Provider-specific well-formedness. Claude entries need the 4 required
+    fields; Codex entries need the 3 base fields (NO cache_creation) and may
+    carry optional *_above_272k_tokens tiered fields. All present cost fields
+    must be >= 0. An all-zero Codex entry is allowed ONLY if its model is in
+    `zero_sentinels` (e.g. gpt-5.3-codex-spark mirroring upstream $0)."""
+    problems: list = []
+
+    def _check(model, body, required, allow_zero):
+        for f in required:
+            if f not in body:
+                problems.append(f"{model}: missing required field {f}")
+        cost_fields = {k: v for k, v in body.items() if "cost" in k}
+        for k, v in cost_fields.items():
+            if not isinstance(v, (int, float)) or v < 0:
+                problems.append(f"{model}: field {k} not a non-negative number ({v!r})")
+        if cost_fields and all(float(v) == 0.0 for v in cost_fields.values()) and not allow_zero:
+            problems.append(f"{model}: all cost fields zero but not a documented sentinel")
+
+    for model, body in claude_tbl.items():
+        _check(model, body, _CLAUDE_REQUIRED, allow_zero=False)
+    for model, body in codex_tbl.items():
+        _check(model, body, _CODEX_REQUIRED, allow_zero=model in zero_sentinels)
+    return problems
+
+
+def pricing_issue_action(drift_present: bool, existing_open: bool) -> str:
+    """Decide the cron's GitHub-issue action. Pure; the YAML executes it."""
+    if drift_present:
+        return "update" if existing_open else "create"
+    return "close" if existing_open else "noop"