codex-usage-tracking 0.3.0__py3-none-any.whl

codex_usage_tracker/pricing.py

@@ -0,0 +1,57 @@
+"""Public pricing facade for config, source parsing, estimates, and costing."""
+
+from __future__ import annotations
+
+from codex_usage_tracker.costing import (
+    annotate_rows_with_efficiency,
+    efficiency_flags,
+    estimate_cache_savings_usd,
+    estimate_cost_usd,
+    summarize_pricing_coverage,
+)
+from codex_usage_tracker.pricing_config import (
+    PRICING_SCHEMA,
+    PRICING_TEMPLATE,
+    PricingConfig,
+    load_pricing_config,
+    pin_pricing_snapshot,
+    write_pricing_template,
+)
+from codex_usage_tracker.pricing_estimates import (
+    ESTIMATED_MODEL_PRICES,
+    OPENAI_CODEX_LAUNCH_URL,
+    OPENAI_CODEX_RATE_CARD_URL,
+    OPENAI_GPT_53_CODEX_MODEL_URL,
+)
+from codex_usage_tracker.pricing_openai import (
+    OPENAI_PRICING_MD_URL,
+    VALID_PRICING_TIERS,
+    PricingParseError,
+    PricingUpdateResult,
+    parse_openai_pricing_markdown,
+    update_pricing_from_openai_docs,
+)
+
+__all__ = [
+    "ESTIMATED_MODEL_PRICES",
+    "OPENAI_CODEX_LAUNCH_URL",
+    "OPENAI_CODEX_RATE_CARD_URL",
+    "OPENAI_GPT_53_CODEX_MODEL_URL",
+    "OPENAI_PRICING_MD_URL",
+    "PRICING_SCHEMA",
+    "PRICING_TEMPLATE",
+    "VALID_PRICING_TIERS",
+    "PricingConfig",
+    "PricingParseError",
+    "PricingUpdateResult",
+    "annotate_rows_with_efficiency",
+    "efficiency_flags",
+    "estimate_cache_savings_usd",
+    "estimate_cost_usd",
+    "load_pricing_config",
+    "parse_openai_pricing_markdown",
+    "pin_pricing_snapshot",
+    "summarize_pricing_coverage",
+    "update_pricing_from_openai_docs",
+    "write_pricing_template",
+]

codex_usage_tracker/pricing_config.py

@@ -0,0 +1,223 @@
+"""Local pricing config loading and template writing."""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from codex_usage_tracker.paths import DEFAULT_PRICING_PATH
+
+PRICING_SCHEMA = "codex-usage-tracker-pricing-v1"
+PRICING_TEMPLATE = {
+    "_comment": (
+        "Fill in current prices in USD per 1 million tokens. The tracker does "
+        "not fetch pricing during normal reports. Prefer update-pricing when "
+        "you want to cache current OpenAI-published rates locally."
+    ),
+    "models": {
+        "replace-with-model-name": {
+            "input_per_million": 0.0,
+            "cached_input_per_million": 0.0,
+            "output_per_million": 0.0,
+        }
+    },
+    "aliases": {
+        "local-codex-model-label": "official-openai-model-id",
+    },
+}
+
+
+@dataclass(frozen=True)
+class PricingConfig:
+    """Parsed local model pricing config."""
+
+    path: Path
+    models: dict[str, dict[str, float]]
+    loaded: bool
+    aliases: dict[str, str] | None = None
+    estimated_models: set[str] | None = None
+    source: dict[str, Any] | None = None
+    error: str | None = None
+
+    def rates_for(self, model: object) -> dict[str, float] | None:
+        if not isinstance(model, str) or not model:
+            return None
+        direct = self.models.get(model)
+        if direct is not None:
+            return direct
+        alias_target = (self.aliases or {}).get(model)
+        if not alias_target:
+            return None
+        return self.models.get(alias_target)
+
+    def priced_as(self, model: object) -> str | None:
+        if not isinstance(model, str) or not model:
+            return None
+        if model in self.models:
+            return model
+        alias_target = (self.aliases or {}).get(model)
+        if alias_target and alias_target in self.models:
+            return alias_target
+        return None
+
+    def is_estimated_model(self, model: object) -> bool:
+        priced_as = self.priced_as(model)
+        return bool(priced_as and priced_as in (self.estimated_models or set()))
+
+
+def load_pricing_config(path: Path = DEFAULT_PRICING_PATH) -> PricingConfig:
+    """Load optional local pricing without contacting external services."""
+
+    if not path.exists():
+        return PricingConfig(path=path, models={}, loaded=False)
+    try:
+        raw = json.loads(path.read_text(encoding="utf-8"))
+        models = parse_models(raw)
+    except (OSError, ValueError, TypeError, json.JSONDecodeError) as exc:
+        return PricingConfig(path=path, models={}, loaded=False, error=str(exc))
+    source = raw.get("_source") if isinstance(raw, dict) else None
+    aliases = parse_aliases(raw)
+    return PricingConfig(
+        path=path,
+        models=models,
+        loaded=True,
+        aliases=aliases,
+        estimated_models=parse_estimated_models(raw),
+        source=source if isinstance(source, dict) else None,
+    )
+
+
+def write_pricing_template(path: Path = DEFAULT_PRICING_PATH, force: bool = False) -> Path:
+    """Write a local pricing template for user-maintained cost estimates."""
+
+    if path.exists() and not force:
+        raise FileExistsError(f"Pricing config already exists: {path}")
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(PRICING_TEMPLATE, indent=2) + "\n", encoding="utf-8")
+    return path
+
+
+def pin_pricing_snapshot(
+    *,
+    source_path: Path = DEFAULT_PRICING_PATH,
+    output_path: Path,
+    force: bool = False,
+) -> Path:
+    """Copy the current local pricing config to a reproducible report snapshot."""
+
+    config = load_pricing_config(source_path)
+    if config.error:
+        raise ValueError(f"pricing config is invalid: {config.error}")
+    if not config.loaded:
+        raise FileNotFoundError(f"pricing config does not exist: {source_path}")
+    output_path = output_path.expanduser()
+    if output_path.exists() and not force:
+        raise FileExistsError(f"pricing snapshot already exists: {output_path}")
+    raw = json.loads(source_path.expanduser().read_text(encoding="utf-8"))
+    if not isinstance(raw, dict):
+        raise ValueError("pricing config must be a JSON object")
+    source_payload = raw.get("_source")
+    source: dict[str, Any] = source_payload if isinstance(source_payload, dict) else {}
+    raw["_source"] = {
+        **source,
+        "pinned": True,
+        "pinned_at": datetime.now(timezone.utc)
+        .replace(microsecond=0)
+        .isoformat()
+        .replace("+00:00", "Z"),
+        "pin_note": "Use this file with --pricing for reproducible historical reports.",
+    }
+    output_path.parent.mkdir(parents=True, exist_ok=True)
+    output_path.write_text(json.dumps(raw, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    return output_path
+
+
+def parse_models(raw: object) -> dict[str, dict[str, float]]:
+    if not isinstance(raw, dict):
+        raise ValueError("pricing config must be a JSON object")
+    model_payload = raw.get("models", raw)
+    if not isinstance(model_payload, dict):
+        raise ValueError("pricing config 'models' must be an object")
+
+    models: dict[str, dict[str, float]] = {}
+    for model, rates in model_payload.items():
+        if not isinstance(model, str) or model.startswith("_"):
+            continue
+        if not isinstance(rates, dict):
+            continue
+        input_rate = _required_rate(rates, "input_per_million", model)
+        cached_rate = _optional_rate(rates, "cached_input_per_million")
+        output_rate = _required_rate(rates, "output_per_million", model)
+        models[model] = {
+            "input_per_million": float(input_rate),
+            "cached_input_per_million": float(
+                cached_rate if cached_rate is not None else input_rate
+            ),
+            "output_per_million": float(output_rate),
+        }
+    return models
+
+
+def parse_aliases(raw: object) -> dict[str, str]:
+    if not isinstance(raw, dict):
+        return {}
+    aliases = raw.get("aliases")
+    if not isinstance(aliases, dict):
+        return {}
+    parsed: dict[str, str] = {}
+    for source, target in aliases.items():
+        if isinstance(source, str) and isinstance(target, str) and source and target:
+            parsed[source] = target
+    return parsed
+
+
+def parse_estimated_models(raw: object) -> set[str]:
+    if not isinstance(raw, dict):
+        return set()
+    model_payload = raw.get("models", raw)
+    if not isinstance(model_payload, dict):
+        return set()
+    return {
+        model
+        for model, rates in model_payload.items()
+        if isinstance(model, str) and isinstance(rates, dict) and rates.get("estimated") is True
+    }
+
+
+def load_existing_aliases(path: Path) -> dict[str, str]:
+    if not path.exists():
+        return {}
+    try:
+        return parse_aliases(json.loads(path.read_text(encoding="utf-8")))
+    except (OSError, TypeError, json.JSONDecodeError):
+        return {}
+
+
+def _required_rate(rates: dict[str, Any], key: str, model: str) -> float:
+    value = _optional_rate(rates, key)
+    if value is None:
+        raise ValueError(f"missing {key} for model {model}")
+    return value
+
+
+def _optional_rate(rates: dict[str, Any], key: str) -> float | None:
+    value = rates.get(key)
+    if value is None:
+        return None
+    parsed = _number(value)
+    if parsed < 0:
+        raise ValueError(f"{key} cannot be negative")
+    return parsed
+
+
+def _number(value: object) -> float:
+    if isinstance(value, bool):
+        return float(int(value))
+    if isinstance(value, int | float):
+        return float(value)
+    if isinstance(value, str) and value.strip():
+        return float(value)
+    return 0.0

codex_usage_tracker/pricing_estimates.py

@@ -0,0 +1,44 @@
+"""Explicitly marked internal Codex model pricing estimates."""
+
+from __future__ import annotations
+
+OPENAI_CODEX_LAUNCH_URL = "https://openai.com/index/introducing-codex/"
+OPENAI_GPT_53_CODEX_MODEL_URL = "https://developers.openai.com/api/docs/models/gpt-5.3-codex"
+OPENAI_CODEX_RATE_CARD_URL = "https://help.openai.com/en/articles/20001106-codex-rate-card"
+
+PricingEstimateValue = float | bool | str
+
+ESTIMATED_MODEL_PRICES: dict[str, dict[str, PricingEstimateValue]] = {
+    "codex-auto-review": {
+        "input_per_million": 1.5,
+        "cached_input_per_million": 0.375,
+        "output_per_million": 6.0,
+        "estimated": True,
+        "estimate_basis_model": "codex-mini-latest",
+        "estimate_source_url": OPENAI_CODEX_LAUNCH_URL,
+        "estimate_reason": (
+            "codex-auto-review is an internal Codex model label without a public "
+            "pricing row; estimate uses OpenAI-published codex-mini-latest rates."
+        ),
+    },
+    "gpt-5.3-codex-spark": {
+        "input_per_million": 1.75,
+        "cached_input_per_million": 0.175,
+        "output_per_million": 14.0,
+        "estimated": True,
+        "estimate_basis_model": "gpt-5.3-codex",
+        "estimate_source_url": OPENAI_GPT_53_CODEX_MODEL_URL,
+        "estimate_reference_url": OPENAI_CODEX_RATE_CARD_URL,
+        "estimate_reason": (
+            "GPT-5.3-Codex-Spark is listed by OpenAI as a research preview "
+            "without final Codex credit rates; estimate uses the published "
+            "GPT-5.3-Codex text-token rates until Spark rates are finalized."
+        ),
+    },
+}
+
+
+def estimated_model_prices() -> dict[str, dict[str, PricingEstimateValue]]:
+    """Return a copy of configured internal model estimates."""
+
+    return {model: dict(rates) for model, rates in ESTIMATED_MODEL_PRICES.items()}

codex_usage_tracker/pricing_openai.py

@@ -0,0 +1,253 @@
+"""OpenAI pricing source fetching, parsing, and cache updates."""
+
+from __future__ import annotations
+
+import json
+import re
+import shutil
+from collections.abc import Callable
+from dataclasses import dataclass
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+from urllib.error import URLError
+from urllib.request import Request, urlopen
+
+from codex_usage_tracker import __version__
+from codex_usage_tracker.paths import DEFAULT_PRICING_PATH
+from codex_usage_tracker.pricing_config import PRICING_SCHEMA, load_existing_aliases
+from codex_usage_tracker.pricing_estimates import ESTIMATED_MODEL_PRICES, estimated_model_prices
+
+OPENAI_PRICING_MD_URL = "https://developers.openai.com/api/docs/pricing.md"
+VALID_PRICING_TIERS = ("standard", "batch", "flex", "priority")
+
+
+class PricingParseError(ValueError):
+    """Raised when the OpenAI pricing Markdown structure cannot be parsed."""
+
+
+@dataclass(frozen=True)
+class PricingUpdateResult:
+    """Result from refreshing the local pricing cache."""
+
+    path: Path
+    source_url: str
+    tier: str
+    fetched_at: str
+    model_count: int
+    estimated_model_count: int = 0
+    backup_path: Path | None = None
+
+
+def update_pricing_from_openai_docs(
+    path: Path = DEFAULT_PRICING_PATH,
+    *,
+    tier: str = "standard",
+    source_url: str = OPENAI_PRICING_MD_URL,
+    fetch_text: Callable[[str], str] | None = None,
+    include_estimates: bool = True,
+) -> PricingUpdateResult:
+    """Fetch OpenAI-published pricing rows and cache them in the local config."""
+
+    if tier not in VALID_PRICING_TIERS:
+        raise ValueError(
+            f"unknown pricing tier {tier!r}; expected one of {', '.join(VALID_PRICING_TIERS)}"
+        )
+    fetcher = fetch_text or _fetch_text
+    text = fetcher(source_url)
+    parsed_models = parse_openai_pricing_markdown(text, tier=tier)
+    if not parsed_models:
+        raise PricingParseError(
+            f"pricing source schema changed: no text-token pricing rows were parsed "
+            f"from {source_url} for tier {tier!r}"
+        )
+    models: dict[str, dict[str, Any]] = {
+        model: dict(rates) for model, rates in parsed_models.items()
+    }
+    aliases = load_existing_aliases(path)
+    estimated_model_count = 0
+    if include_estimates:
+        models.update(estimated_model_prices())
+        estimated_model_count = len(ESTIMATED_MODEL_PRICES)
+
+    fetched_at = datetime.now(timezone.utc).replace(microsecond=0).isoformat()
+    payload = {
+        "_schema": PRICING_SCHEMA,
+        "_source": {
+            "name": "OpenAI Developers pricing docs",
+            "url": source_url,
+            "tier": tier,
+            "fetched_at": fetched_at,
+            "model_count": len(models),
+            "official_model_count": len(models) - estimated_model_count,
+            "estimated_model_count": estimated_model_count,
+        },
+        "models": models,
+    }
+    if aliases:
+        payload["aliases"] = aliases
+    path.parent.mkdir(parents=True, exist_ok=True)
+    backup_path = _backup_existing_pricing(path)
+    tmp_path = path.with_name(f"{path.name}.tmp")
+    tmp_path.write_text(json.dumps(payload, indent=2, sort_keys=True) + "\n", encoding="utf-8")
+    tmp_path.replace(path)
+    return PricingUpdateResult(
+        path=path,
+        source_url=source_url,
+        tier=tier,
+        fetched_at=fetched_at,
+        model_count=len(models),
+        estimated_model_count=estimated_model_count,
+        backup_path=backup_path,
+    )
+
+
+def parse_openai_pricing_markdown(
+    markdown: str, *, tier: str = "standard"
+) -> dict[str, dict[str, float]]:
+    """Parse text-token rows from OpenAI's pricing markdown for one service tier."""
+
+    if tier not in VALID_PRICING_TIERS:
+        raise ValueError(
+            f"unknown pricing tier {tier!r}; expected one of {', '.join(VALID_PRICING_TIERS)}"
+        )
+    rows_block = _extract_text_token_rows_block(markdown, tier)
+    models: dict[str, dict[str, float]] = {}
+    for match in _OPENAI_PRICE_ROW_RE.finditer(rows_block):
+        model = _normalize_model_name(match.group("model"))
+        input_rate = _parse_openai_price_value(match.group("input"))
+        cached_rate = _parse_openai_price_value(match.group("cached"))
+        output_rate = _parse_openai_price_value(match.group("output"))
+        if not model or input_rate is None or output_rate is None:
+            continue
+        if cached_rate is None:
+            cached_rate = input_rate
+        models[model] = {
+            "input_per_million": input_rate,
+            "cached_input_per_million": cached_rate,
+            "output_per_million": output_rate,
+        }
+    if not models:
+        raise PricingParseError(
+            f"pricing source schema changed: tier {tier!r} rows block contained no "
+            "parseable text-token pricing rows"
+        )
+    return models
+
+
+_OPENAI_PRICE_ROW_RE = re.compile(
+    r"""\[
+        \s*"(?P<model>[^"]+)"\s*,
+        \s*(?P<input>[^,\]\n]+)\s*,
+        \s*(?P<cached>[^,\]\n]+)\s*,
+        \s*(?P<output>[^,\]\n]+)\s*
+    \]""",
+    re.VERBOSE,
+)
+
+
+def _fetch_text(url: str) -> str:
+    request = Request(
+        url,
+        headers={
+            "Accept": "text/markdown,text/plain;q=0.9,*/*;q=0.1",
+            "User-Agent": f"codex-usage-tracker/{__version__}",
+        },
+    )
+    try:
+        with urlopen(request, timeout=20) as response:
+            return response.read().decode("utf-8")
+    except URLError as exc:
+        raise RuntimeError(f"could not fetch pricing source {url}: {exc}") from exc
+
+
+def _backup_existing_pricing(path: Path) -> Path | None:
+    if not path.exists():
+        return None
+    stamp = datetime.now(timezone.utc).strftime("%Y%m%dT%H%M%SZ")
+    backup_path = path.with_name(f"{path.name}.{stamp}.bak")
+    shutil.copy2(path, backup_path)
+    return backup_path
+
+
+def _extract_text_token_rows_block(markdown: str, tier: str) -> str:
+    tier_marker = f'tier="{tier}"'
+    tier_index = markdown.find(tier_marker)
+    if tier_index == -1:
+        raise PricingParseError(
+            f"pricing source schema changed: could not find text-token tier marker {tier_marker!r}"
+        )
+    search_end = _pricing_component_end(markdown, tier_index)
+    rows_marker_index = markdown.find("rows={[", tier_index, search_end)
+    if rows_marker_index == -1:
+        raise PricingParseError(
+            f"pricing source schema changed: tier {tier!r} does not contain a rows={{[ block"
+        )
+    bracket_index = markdown.find("[", rows_marker_index, search_end)
+    if bracket_index == -1:
+        raise PricingParseError(
+            f"pricing source schema changed: tier {tier!r} has a malformed rows block"
+        )
+    end_index = _find_matching_bracket(markdown, bracket_index)
+    if end_index > search_end:
+        raise PricingParseError(
+            f"pricing source schema changed: tier {tier!r} rows block extends past its component"
+        )
+    return markdown[bracket_index + 1 : end_index]
+
+
+def _pricing_component_end(markdown: str, tier_index: int) -> int:
+    candidates = [
+        index
+        for index in (
+            markdown.find("/>", tier_index),
+            markdown.find("</TextTokenPricingTables>", tier_index),
+            markdown.find("<TextTokenPricingTables", tier_index + 1),
+        )
+        if index != -1
+    ]
+    return min(candidates) if candidates else len(markdown)
+
+
+def _find_matching_bracket(text: str, start_index: int) -> int:
+    depth = 0
+    quote: str | None = None
+    escaped = False
+    for index in range(start_index, len(text)):
+        char = text[index]
+        if quote:
+            if escaped:
+                escaped = False
+            elif char == "\\":
+                escaped = True
+            elif char == quote:
+                quote = None
+            continue
+        if char in {'"', "'", "`"}:
+            quote = char
+        elif char == "[":
+            depth += 1
+        elif char == "]":
+            depth -= 1
+            if depth == 0:
+                return index
+    raise PricingParseError("pricing source schema changed: rows block is unterminated")
+
+
+def _normalize_model_name(model: str) -> str:
+    return re.sub(r"\s+\([^)]*context length[^)]*\)\s*$", "", model.strip(), flags=re.I)
+
+
+def _parse_openai_price_value(value: str) -> float | None:
+    normalized = value.strip()
+    if normalized in {"", "null", "undefined", "-", '""', "''", '"-"', "'-'"}:
+        return None
+    if (
+        len(normalized) >= 2
+        and normalized[0] == normalized[-1]
+        and normalized[0] in {'"', "'"}
+    ):
+        normalized = normalized[1:-1].strip()
+    if normalized in {"", "-", "Free"}:
+        return None
+    return float(normalized.replace("_", ""))