cc-session-tools 3.10.2__tar.gz → 3.10.4__tar.gz

{cc_session_tools-3.10.2/src/cc_session_tools.egg-info → cc_session_tools-3.10.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cc-session-tools
-Version: 3.10.2
+Version: 3.10.4
 Summary: Claude Code session management CLI tools (ccd, ccr, ccs, claude-code-usage, ccst) and hook library (hooks package)
 Author: raffishquartan
 License: MIT License

{cc_session_tools-3.10.2 → cc_session_tools-3.10.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "cc-session-tools"
-version = "3.10.2"
+version = "3.10.4"
 description = "Claude Code session management CLI tools (ccd, ccr, ccs, claude-code-usage, ccst) and hook library (hooks package)"
 readme = "README.md"
 license = { file = "LICENSE" }

{cc_session_tools-3.10.2 → cc_session_tools-3.10.4}/src/cc_session_tools/skills/pm-pdata-do-init/SKILL.md

@@ -141,6 +141,9 @@ relative to a subfolder rather than the project root (e.g. an index-of-a-subfold
 root) - `--write`'s file_path-resolution verification will fail with a bare "does not resolve
 under `<project_root>`" and no further guidance. Instead, map that column to a plain named field
 (e.g. `source_file_path`) and note in the field's `description` what path it's relative to.
+Likewise, a column documented to use multiple or shorthand path notations (e.g. brace expansion
+alongside plain paths) is unsafe to map to `file_path_column` at all - map it to a plain named TEXT
+field instead, exactly as for the subfolder-relative case.
 
 **`content_column: null` default caveat:** an entry with `content_column` left unset falls back to
 a raw `json.dumps(row)` dump as every record's content - rarely what you want for readable `ccst

{cc_session_tools-3.10.2 → cc_session_tools-3.10.4/src/cc_session_tools.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cc-session-tools
-Version: 3.10.2
+Version: 3.10.4
 Summary: Claude Code session management CLI tools (ccd, ccr, ccs, claude-code-usage, ccst) and hook library (hooks package)
 Author: raffishquartan
 License: MIT License

cc_session_tools-3.10.4/src/claude_code_usage/data/pricing.json

@@ -0,0 +1,181 @@
+{
+  "_source": "Anthropic published first-party API pricing (https://platform.claude.com/docs/en/about-claude/pricing), hand-curated. Per-token USD. Rows for retired models not on that page keep their historical list price.",
+  "_refreshed_at": "2026-09-29",
+  "models": {
+    "<synthetic>": {
+      "input": 0.0,
+      "output": 0.0,
+      "cache_creation_5m": 0.0,
+      "cache_creation_1h": 0.0,
+      "cache_read": 0.0
+    },
+    "claude-fable-5-1": {
+      "input": 0.00001,
+      "output": 0.00005,
+      "cache_creation_5m": 0.0000125,
+      "cache_creation_1h": 0.00002,
+      "cache_read": 0.00000025
+    },
+    "claude-mythos-5-1": {
+      "input": 0.00001,
+      "output": 0.00005,
+      "cache_creation_5m": 0.0000125,
+      "cache_creation_1h": 0.00002,
+      "cache_read": 0.00000025
+    },
+    "claude-fable-5": {
+      "input": 0.00001,
+      "output": 0.00005,
+      "cache_creation_5m": 0.0000125,
+      "cache_creation_1h": 0.00002,
+      "cache_read": 0.000001
+    },
+    "claude-mythos-5": {
+      "input": 0.00001,
+      "output": 0.00005,
+      "cache_creation_5m": 0.0000125,
+      "cache_creation_1h": 0.00002,
+      "cache_read": 0.000001
+    },
+    "claude-opus-5-5": {
+      "input": 0.000004,
+      "output": 0.00002,
+      "cache_creation_5m": 0.000005,
+      "cache_creation_1h": 0.000008,
+      "cache_read": 0.0000002
+    },
+    "claude-opus-5": {
+      "input": 0.000005,
+      "output": 0.000025,
+      "cache_creation_5m": 0.00000625,
+      "cache_creation_1h": 0.00001,
+      "cache_read": 0.0000005
+    },
+    "claude-opus-4-8": {
+      "input": 0.000005,
+      "output": 0.000025,
+      "cache_creation_5m": 0.00000625,
+      "cache_creation_1h": 0.00001,
+      "cache_read": 0.0000005
+    },
+    "claude-opus-4-7": {
+      "input": 0.000005,
+      "output": 0.000025,
+      "cache_creation_5m": 0.00000625,
+      "cache_creation_1h": 0.00001,
+      "cache_read": 0.0000005
+    },
+    "claude-opus-4-6": {
+      "input": 0.000005,
+      "output": 0.000025,
+      "cache_creation_5m": 0.00000625,
+      "cache_creation_1h": 0.00001,
+      "cache_read": 0.0000005
+    },
+    "claude-opus-4-5": {
+      "input": 0.000005,
+      "output": 0.000025,
+      "cache_creation_5m": 0.00000625,
+      "cache_creation_1h": 0.00001,
+      "cache_read": 0.0000005
+    },
+    "claude-opus-4-1": {
+      "input": 0.000015,
+      "output": 0.000075,
+      "cache_creation_5m": 0.00001875,
+      "cache_creation_1h": 0.00003,
+      "cache_read": 0.0000015
+    },
+    "claude-opus-4": {
+      "input": 0.000015,
+      "output": 0.000075,
+      "cache_creation_5m": 0.00001875,
+      "cache_creation_1h": 0.00003,
+      "cache_read": 0.0000015
+    },
+    "claude-sonnet-5-5": {
+      "input": 0.000002,
+      "output": 0.00001,
+      "cache_creation_5m": 0.0000025,
+      "cache_creation_1h": 0.000004,
+      "cache_read": 0.0000002
+    },
+    "claude-sonnet-5": {
+      "input": 0.000002,
+      "output": 0.00001,
+      "cache_creation_5m": 0.0000025,
+      "cache_creation_1h": 0.000004,
+      "cache_read": 0.0000002
+    },
+    "claude-sonnet-4-6": {
+      "input": 0.000003,
+      "output": 0.000015,
+      "cache_creation_5m": 0.00000375,
+      "cache_creation_1h": 0.000006,
+      "cache_read": 0.0000003
+    },
+    "claude-sonnet-4-5": {
+      "input": 0.000003,
+      "output": 0.000015,
+      "cache_creation_5m": 0.00000375,
+      "cache_creation_1h": 0.000006,
+      "cache_read": 0.0000003
+    },
+    "claude-sonnet-4": {
+      "input": 0.000003,
+      "output": 0.000015,
+      "cache_creation_5m": 0.00000375,
+      "cache_creation_1h": 0.000006,
+      "cache_read": 0.0000003
+    },
+    "claude-haiku-4-5": {
+      "input": 0.000001,
+      "output": 0.000005,
+      "cache_creation_5m": 0.00000125,
+      "cache_creation_1h": 0.000002,
+      "cache_read": 0.0000001
+    },
+    "claude-haiku-4": {
+      "input": 0.0000008,
+      "output": 0.000004,
+      "cache_creation_5m": 0.000001,
+      "cache_creation_1h": 0.0000016,
+      "cache_read": 0.00000008
+    },
+    "claude-3-7-sonnet-20250219": {
+      "input": 0.000003,
+      "output": 0.000015,
+      "cache_creation_5m": 0.00000375,
+      "cache_creation_1h": 0.000006,
+      "cache_read": 0.0000003
+    },
+    "claude-3-5-sonnet-20241022": {
+      "input": 0.000003,
+      "output": 0.000015,
+      "cache_creation_5m": 0.00000375,
+      "cache_creation_1h": 0.000006,
+      "cache_read": 0.0000003
+    },
+    "claude-3-5-haiku-20241022": {
+      "input": 0.0000008,
+      "output": 0.000004,
+      "cache_creation_5m": 0.000001,
+      "cache_creation_1h": 0.0000016,
+      "cache_read": 0.00000008
+    },
+    "claude-3-opus-20240229": {
+      "input": 0.000015,
+      "output": 0.000075,
+      "cache_creation_5m": 0.00001875,
+      "cache_creation_1h": 0.00003,
+      "cache_read": 0.0000015
+    }
+  },
+  "family_fallbacks": {
+    "fable": "claude-fable-5-1",
+    "mythos": "claude-mythos-5-1",
+    "opus": "claude-opus-5-5",
+    "sonnet": "claude-sonnet-5-5",
+    "haiku": "claude-haiku-4-5"
+  }
+}

cc_session_tools-3.10.4/src/claude_code_usage/pricing.py

@@ -0,0 +1,134 @@
+"""Per-token pricing data and dollar calculations.
+
+`data/pricing.json` is a hand-curated copy of Anthropic's published
+first-party API rates (its `_source` / `_refreshed_at` fields say where
+from and when); re-check it whenever a new model ships. Resolution order
+for a model id:
+
+1. an exact row;
+2. a dated snapshot (`<id>-YYYYMMDD`, exactly eight digits, stripped
+   once) resolves to the undated row;
+3. an id containing `claude-<family>-` for a family in `family_fallbacks`
+   is priced as that family's newest model - an estimate, which
+   `add_cost_column()` reports in a warning. Claude 3 ids (`claude-3-...`)
+   and non-Claude ids never match, so an unlisted old model is reported as
+   unpriced rather than given a newer model's price;
+4. otherwise `lookup()` raises `KeyError`.
+
+`<synthetic>` (Claude Code's zero-usage stub entries) has an explicit
+all-zero row.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import re
+from pathlib import Path
+from typing import Any
+
+import pandas as pd
+
+_THIS_DIR = Path(__file__).resolve().parent
+_PRICING_PATH = _THIS_DIR / "data" / "pricing.json"
+_DATED_SNAPSHOT = re.compile(r"(.+)-\d{8}")
+
+logger = logging.getLogger(__name__)
+
+
+def _load() -> dict[str, Any]:
+    return json.loads(_PRICING_PATH.read_text())
+
+
+def resolve(model: str) -> tuple[str, bool]:
+    """Return (pricing row key, True if the row came from a family fallback).
+    Raises KeyError if `model` has no row and no family match."""
+    data = _load()
+    models = data["models"]
+    if model in models:
+        return model, False
+    dated = _DATED_SNAPSHOT.fullmatch(model)
+    if dated and dated.group(1) in models:
+        return dated.group(1), False
+    for family, fallback_model in data["family_fallbacks"].items():
+        if f"claude-{family}-" in model:
+            return fallback_model, True
+    raise KeyError(model)
+
+
+def lookup(model: str) -> dict[str, float]:
+    """Return per-token rates for `model`. Raises KeyError if unknown."""
+    row, _ = resolve(model)
+    rates: dict[str, float] = _load()["models"][row]
+    return rates
+
+
+def cost_for_usage(
+    model: str,
+    input_tokens: int,
+    output_tokens: int,
+    cache_creation_5m: int = 0,
+    cache_creation_1h: int = 0,
+    cache_read: int = 0,
+) -> float:
+    """Return the dollar cost of one assistant message's token mix."""
+    rates = lookup(model)
+    return (
+        input_tokens * rates["input"]
+        + output_tokens * rates["output"]
+        + cache_creation_5m * rates["cache_creation_5m"]
+        + cache_creation_1h * rates["cache_creation_1h"]
+        + cache_read * rates["cache_read"]
+    )
+
+
+def add_cost_column(df: pd.DataFrame) -> pd.DataFrame:
+    """Return `df` with a `cost_usd` column added.
+
+    Vectorised over rows: builds a per-row rates frame from the model
+    column then dot-products against the token columns. Models that
+    can't be resolved (after family fallback) get cost = 0 with a
+    warning - we don't want a single unknown model to break a report.
+    Models priced by family fallback are named in a separate warning, so
+    an estimated price is never silent.
+    """
+    out = df.copy()
+    if out.empty:
+        out["cost_usd"] = pd.Series(dtype=float)
+        return out
+    models = _load()["models"]
+    zero = {"input": 0.0, "output": 0.0, "cache_creation_5m": 0.0,
+            "cache_creation_1h": 0.0, "cache_read": 0.0}
+    rates_by_model: dict[str, dict[str, float]] = {}
+    unknown: set[str] = set()
+    fallback: dict[str, str] = {}
+    for model in out["model"].unique():
+        try:
+            row, is_fallback = resolve(model)
+        except KeyError:
+            unknown.add(model)
+            rates_by_model[model] = zero
+            continue
+        rates_by_model[model] = models[row]
+        if is_fallback:
+            fallback[model] = row
+    rates_records = [rates_by_model[model] for model in out["model"]]
+    rates_df = pd.DataFrame(rates_records, index=out.index)
+    out["cost_usd"] = (
+        out["input_tokens"] * rates_df["input"]
+        + out["output_tokens"] * rates_df["output"]
+        + out["cache_creation_5m"] * rates_df["cache_creation_5m"]
+        + out["cache_creation_1h"] * rates_df["cache_creation_1h"]
+        + out["cache_read"] * rates_df["cache_read"]
+    )
+    if unknown:
+        logger.warning(
+            "no pricing for models: %s (cost set to 0 for those rows)",
+            sorted(unknown),
+        )
+    if fallback:
+        logger.warning(
+            "no exact pricing for models, priced by family fallback: %s",
+            ", ".join(f"{model} as {row}" for model, row in sorted(fallback.items())),
+        )
+    return out

{cc_session_tools-3.10.2 → cc_session_tools-3.10.4}/src/hooks/context_window_warning.py

@@ -26,6 +26,7 @@ from __future__ import annotations
 
 import datetime
 import json
+import re
 import sys
 from decimal import ROUND_DOWN, Decimal
 from pathlib import Path
@@ -41,10 +42,16 @@ class TranscriptError(Exception):
     not a single parseable JSON line."""
 
 
+SYNTHETIC_MODEL = "<synthetic>"
+
+
 def _current_context_tokens(transcript_path: Path) -> tuple[int, str]:
     """(token count, model id) from the last non-sidechain assistant message's
     usage. (0, "") for a fresh session with no assistant usage yet - that is a
-    legitimate state, not an error."""
+    legitimate state, not an error. Entries whose model is `<synthetic>` are
+    skipped: Claude Code writes them (with all-zero usage) for things that are
+    not API responses, such as a usage-limit notice, so they say nothing about
+    the context size."""
     if not transcript_path.is_file():
         raise TranscriptError(f"transcript not found: {transcript_path}")
 
@@ -68,9 +75,10 @@ def _current_context_tokens(transcript_path: Path) -> tuple[int, str]:
                     continue
                 message = obj.get("message") or {}
                 usage = message.get("usage")
-                if isinstance(usage, dict):
+                model = message.get("model") or ""
+                if isinstance(usage, dict) and model != SYNTHETIC_MODEL:
                     last_usage = usage
-                    last_model = message.get("model") or ""
+                    last_model = model
     except OSError as exc:
         raise TranscriptError(f"cannot read transcript: {exc}") from exc
 
@@ -102,19 +110,18 @@ def _window_label(window: int) -> str:
     return f"{(window + 500) // 1000}k"
 
 
-def _format_cost(*, tokens: int, price_per_mtok: float) -> str:
-    """Cache-read cost, ~0.1x the model's standard input price, truncated
-    (not rounded) to 2dp - matches `bc`'s `scale=2` semantics from the bash
-    original. Uses Decimal rather than native float arithmetic: a naive
-    math.floor(raw * 100) / 100 on a float hits representation error for
-    ordinary inputs (e.g. tokens=700_000, price=3.00 evaluates to
-    0.20999999999999996 in float, one cent short of the correct 0.21) -
-    caught by adversarial code review on this exact function, not
-    hypothetical. Decimal(str(price_per_mtok)) avoids reintroducing the same
+def _format_cost(*, tokens: int, cache_read_price_per_mtok: float) -> str:
+    """Cost of reading `tokens` from the prompt cache at the model's cache-read
+    price, truncated (not rounded) to 2dp - matches `bc`'s `scale=2`
+    semantics from the bash original. Uses Decimal rather than native float
+    arithmetic: a naive math.floor(raw * 100) / 100 on a float hits
+    representation error for ordinary inputs (e.g. tokens=350_000,
+    price=0.20 evaluates to 0.06999999999999999 in float, one cent short of
+    the correct 0.07). Decimal(str(price)) avoids reintroducing the same
     float-representation problem by round-tripping the price through its
     float form first.
     """
-    raw = Decimal(tokens) / Decimal(1_000_000) * Decimal(str(price_per_mtok)) * Decimal("0.1")
+    raw = Decimal(tokens) / Decimal(1_000_000) * Decimal(str(cache_read_price_per_mtok))
     return str(raw.quantize(Decimal("0.01"), rounding=ROUND_DOWN))
 
 
@@ -134,7 +141,7 @@ def _reason(*, tokens: int, window: int, price: float, name: str, now: str, red:
     k = _k_tokens(tokens)
     pct = _pct_of_window(tokens, window)
     label = _window_label(window)
-    cost = _format_cost(tokens=tokens, price_per_mtok=price)
+    cost = _format_cost(tokens=tokens, cache_read_price_per_mtok=price)
     emoji = "🔴" if red else "🟠"
     when = "when you get a natural break" if red else "whenever convenient"
     return (
@@ -149,6 +156,48 @@ def _reason(*, tokens: int, window: int, price: float, name: str, now: str, red:
     )
 
 
+REMEDIATION_HINT = (
+    "To fix: add the id to src/hooks/model_info.py in claude-code-session-tools; if ccst is just out "
+    "of date, run `uv tool upgrade cc-session-tools` (installed from PyPI with uv) or "
+    "`uv tool install --reinstall <path to your checkout>` (local checkout)."
+)
+
+_ID_DISALLOWED = re.compile(r"[^A-Za-z0-9._:<>\[\]-]")
+
+
+def _model_phrase(model_id: str) -> str:
+    """How the unknown model is named in the message. Characters outside the set real ids use are
+    replaced, so a corrupt or hostile transcript value cannot break the quoted lines the assistant
+    is told to echo."""
+    if not model_id:
+        return "an unknown model (no model id was recorded)"
+    return f"model `{_ID_DISALLOWED.sub('?', model_id)}`"
+
+
+def _reason_unknown(*, tokens: int, window: int, price: float, model_id: str, now: str, red: bool) -> str:
+    """Message for a model id missing from model_info's table: the window and price are
+    assumptions and the text says so, instead of presenting them as facts."""
+    k = _k_tokens(tokens)
+    pct = _pct_of_window(tokens, window)
+    label = _window_label(window)
+    cost = _format_cost(tokens=tokens, cache_read_price_per_mtok=price)
+    model = _model_phrase(model_id)
+    emoji = "🔴" if red else "🟠"
+    when = "when you get a natural break" if red else "whenever convenient"
+    return (
+        f"The context window has passed {k}k tokens. The session's {model} is not in ccst's model "
+        f"table, so the window size is ASSUMED to be {label} tokens; the real window may be much "
+        f"larger (1M for current models) and any percentage may be wrong. THIS IS A WARNING ONLY - "
+        f"output the two lines below at the start of your response, then end your turn as you "
+        f"normally would. Do not restart or repeat any work.\n"
+        f"'{emoji} CONTEXT ({now}): ~{k}k tokens used; window size ASSUMED ({label}) for {model} - "
+        f"the real window may be much larger, so ~{pct}% is unreliable. ~${cost}/turn assumes the "
+        f"default ${price:.2f}/MTok cache-read price. This is a nudge, not a limit - keep going; "
+        f"/compact {when}. {REMEDIATION_HINT}'\n"
+        f"'(To silence this warning for the rest of the session, run /context-override.)'"
+    )
+
+
 def main(argv: list[str] | None = None) -> int:
     try:
         stdin_obj = json.loads(sys.stdin.read() or "{}")
@@ -176,12 +225,19 @@ def main(argv: list[str] | None = None) -> int:
         return 0
 
     window = model_info.context_window(model_id)
-    price = model_info.input_price_per_mtok(model_id)
-    name = model_info.display_name(model_id)
+    price = model_info.cache_read_price_per_mtok(model_id)
     now = datetime.datetime.now().strftime("%H:%M")
     red = tokens >= THRESHOLD_RED
 
-    reason = _reason(tokens=tokens, window=window, price=price, name=name, now=now, red=red)
+    if model_info.is_known(model_id):
+        reason = _reason(
+            tokens=tokens, window=window, price=price, name=model_info.display_name(model_id),
+            now=now, red=red,
+        )
+    else:
+        reason = _reason_unknown(
+            tokens=tokens, window=window, price=price, model_id=model_id, now=now, red=red,
+        )
     print(json.dumps({"decision": "block", "reason": reason}))
     return 0
 

cc_session_tools-3.10.4/src/hooks/model_info.py

@@ -0,0 +1,83 @@
+"""Model id -> context window size, cache-read price, display name.
+
+Consumed by context_window_warning to phrase its nudge in terms of "% of the
+model's actual window" and to estimate a per-turn cache-read cost.
+
+Context windows as of 2026-09-29: Fable 5 / Mythos 5 / Opus 5 / Opus 4.6-4.8 /
+Sonnet 5 / Sonnet 5.5 / Opus 5.5 / Fable 5.1 / Mythos 5.1 / Sonnet 4.6 all 1,000,000 tokens
+(the default, not a beta long-context mode); Haiku 4.5 stays at 200,000.
+Prices are each model's published first-party cache-read ("cache hits and
+refreshes") rate per million tokens, from
+https://platform.claude.com/docs/en/about-claude/pricing (checked 2026-09-29).
+They are not a fixed fraction of the input price: Fable 5.1 and Mythos 5.1 read at 0.025x
+and Opus 5.5 at 0.05x, every other model here at 0.1x.
+
+Re-check this table whenever a new model ships. A model not matched by any
+case (`is_known` is False) falls through to the default window and price
+(200000 tokens / $0.50 per MTok) - deliberately the same window as every
+pre-Claude-5 model, so an unknown model degrades to conservative,
+already-correct-for-most-history behaviour rather than going quiet or firing
+too early. Those defaults are assumptions, and the warning says so; only
+`display_name` has no default (it raises KeyError for an unknown id).
+
+Deliberately not `claude_code_usage.pricing`: that module imports pandas, too
+heavy for a hook that runs on every Stop event. tests/test_pricing.py asserts
+that every cache-read price here matches that module's table.
+"""
+from __future__ import annotations
+
+import re
+
+_WINDOW_1M = {
+    "claude-fable-5", "claude-mythos-5",
+    "claude-opus-5", "claude-opus-4-8", "claude-opus-4-7", "claude-opus-4-6",
+    "claude-sonnet-5", "claude-sonnet-4-6",
+    "claude-sonnet-5-5", "claude-opus-5-5", "claude-fable-5-1", "claude-mythos-5-1",
+}
+_CACHE_READ_PRICE = {
+    "claude-fable-5-1": 0.25, "claude-mythos-5-1": 0.25, "claude-fable-5": 1.00, "claude-mythos-5": 1.00,
+    "claude-opus-5-5": 0.20,
+    "claude-opus-5": 0.50, "claude-opus-4-8": 0.50, "claude-opus-4-7": 0.50, "claude-opus-4-6": 0.50,
+    "claude-sonnet-5-5": 0.20, "claude-sonnet-5": 0.20, "claude-sonnet-4-6": 0.30,
+    "claude-haiku-4-5": 0.10,
+}
+_NAME = {
+    "claude-fable-5": "Fable 5", "claude-mythos-5": "Mythos 5",
+    "claude-opus-5": "Opus 5", "claude-opus-4-8": "Opus 4.8",
+    "claude-opus-4-7": "Opus 4.7", "claude-opus-4-6": "Opus 4.6",
+    "claude-sonnet-5": "Sonnet 5", "claude-sonnet-4-6": "Sonnet 4.6",
+    "claude-sonnet-5-5": "Sonnet 5.5", "claude-opus-5-5": "Opus 5.5",
+    "claude-fable-5-1": "Fable 5.1", "claude-mythos-5-1": "Mythos 5.1",
+    "claude-haiku-4-5": "Haiku 4.5",
+}
+_DEFAULT_WINDOW = 200_000
+_DEFAULT_CACHE_READ_PRICE = 0.50
+
+
+_DATED_SNAPSHOT = re.compile(r"(.+)-\d{8}")
+
+
+def _canonical(model_id: str) -> str:
+    """A dated snapshot id (`<id>-YYYYMMDD`) resolves to its undated row. Applied once, and
+    only for an exactly-eight-digit suffix: any other suffix (or a snapshot of an unknown id)
+    stays unknown. `[1m]`/`-latest` are not handled - transcripts' `message.model` never
+    carries them."""
+    match = _DATED_SNAPSHOT.fullmatch(model_id)
+    return match.group(1) if match else model_id
+
+
+def context_window(model_id: str) -> int:
+    return 1_000_000 if _canonical(model_id) in _WINDOW_1M else _DEFAULT_WINDOW
+
+
+def cache_read_price_per_mtok(model_id: str) -> float:
+    return _CACHE_READ_PRICE.get(_canonical(model_id), _DEFAULT_CACHE_READ_PRICE)
+
+
+def is_known(model_id: str) -> bool:
+    return _canonical(model_id) in _NAME
+
+
+def display_name(model_id: str) -> str:
+    """Raises KeyError for an unknown id: callers check `is_known` first."""
+    return _NAME[_canonical(model_id)]