ctxoptimizer 0.4.1__py3-none-any.whl

ctxoptimizer/data/pricing.json

@@ -0,0 +1,421 @@
+{
+  "version": "2026-10-25",
+  "currency": "USD",
+  "per": 1000000,
+  "models": [
+    {
+      "provider": "anthropic",
+      "match": "claude-opus-5-5*",
+      "input": 4.0,
+      "output": 20.0,
+      "cache_read": 0.2,
+      "cache_write_5m": 5.0,
+      "cache_write_1h": 8.0,
+      "verified": true,
+      "source": "https://platform.claude.com/docs/en/build-with-claude/prompt-caching"
+    },
+    {
+      "provider": "anthropic",
+      "match": "claude-sonnet-5-5*",
+      "input": 2.0,
+      "output": 10.0,
+      "cache_read": 0.1,
+      "cache_write_5m": 2.5,
+      "cache_write_1h": 4.0,
+      "verified": true,
+      "source": "https://platform.claude.com/docs/en/build-with-claude/prompt-caching"
+    },
+    {
+      "provider": "anthropic",
+      "match": "claude-haiku-5-5*",
+      "input": 0.1,
+      "output": 0.5,
+      "cache_read": 0.01,
+      "cache_write_5m": 0.125,
+      "cache_write_1h": 0.2,
+      "verified": true,
+      "source": "https://platform.claude.com/docs/en/build-with-claude/prompt-caching",
+      "notes": "Applies to prompts up to 100k tokens; long-context tier is unsupported in v1."
+    },
+    {
+      "provider": "anthropic",
+      "match": "claude-opus-5*",
+      "input": 5.0,
+      "output": 25.0,
+      "cache_read": 0.5,
+      "cache_write_5m": 6.25,
+      "cache_write_1h": 10.0,
+      "verified": true,
+      "source": "https://platform.claude.com/docs/en/build-with-claude/prompt-caching"
+    },
+    {
+      "provider": "anthropic",
+      "match": "claude-sonnet-5*",
+      "input": 2.0,
+      "output": 10.0,
+      "cache_read": 0.2,
+      "cache_write_5m": 2.5,
+      "cache_write_1h": 4.0,
+      "verified": true,
+      "source": "https://platform.claude.com/docs/en/build-with-claude/prompt-caching"
+    },
+    {
+      "provider": "anthropic",
+      "match": "claude-sonnet-4-6*",
+      "input": 3.0,
+      "output": 15.0,
+      "cache_read": 0.3,
+      "cache_write_5m": 3.75,
+      "cache_write_1h": 6.0,
+      "verified": true,
+      "source": "https://platform.claude.com/docs/en/build-with-claude/prompt-caching"
+    },
+    {
+      "provider": "anthropic",
+      "match": "claude-sonnet-4-5*",
+      "input": 3.0,
+      "output": 15.0,
+      "cache_read": 0.3,
+      "cache_write_5m": 3.75,
+      "cache_write_1h": 6.0,
+      "verified": true,
+      "source": "https://platform.claude.com/docs/en/build-with-claude/prompt-caching"
+    },
+    {
+      "provider": "anthropic",
+      "match": "claude-opus-4-8*",
+      "input": 5.0,
+      "output": 25.0,
+      "cache_read": 0.5,
+      "cache_write_5m": 6.25,
+      "cache_write_1h": 10.0,
+      "verified": true,
+      "source": "https://platform.claude.com/docs/en/build-with-claude/prompt-caching"
+    },
+    {
+      "provider": "anthropic",
+      "match": "claude-opus-4-7*",
+      "input": 5.0,
+      "output": 25.0,
+      "cache_read": 0.5,
+      "cache_write_5m": 6.25,
+      "cache_write_1h": 10.0,
+      "verified": true,
+      "source": "https://platform.claude.com/docs/en/build-with-claude/prompt-caching"
+    },
+    {
+      "provider": "anthropic",
+      "match": "claude-opus-4-6*",
+      "input": 5.0,
+      "output": 25.0,
+      "cache_read": 0.5,
+      "cache_write_5m": 6.25,
+      "cache_write_1h": 10.0,
+      "verified": true,
+      "source": "https://platform.claude.com/docs/en/build-with-claude/prompt-caching"
+    },
+    {
+      "provider": "anthropic",
+      "match": "claude-opus-4-5*",
+      "input": 5.0,
+      "output": 25.0,
+      "cache_read": 0.5,
+      "cache_write_5m": 6.25,
+      "cache_write_1h": 10.0,
+      "verified": true,
+      "source": "https://platform.claude.com/docs/en/build-with-claude/prompt-caching"
+    },
+    {
+      "provider": "anthropic",
+      "match": "claude-haiku-4-5*",
+      "input": 1.0,
+      "output": 5.0,
+      "cache_read": 0.1,
+      "cache_write_5m": 1.25,
+      "cache_write_1h": 2.0,
+      "verified": true,
+      "source": "https://platform.claude.com/docs/en/build-with-claude/prompt-caching"
+    },
+    {
+      "provider": "anthropic",
+      "match": "claude-fable-5-1*",
+      "input": 10.0,
+      "output": 50.0,
+      "cache_read": 0.25,
+      "cache_write_5m": 12.5,
+      "cache_write_1h": 20.0,
+      "verified": true,
+      "source": "https://platform.claude.com/docs/en/build-with-claude/prompt-caching"
+    },
+    {
+      "provider": "anthropic",
+      "match": "claude-mythos-5-1*",
+      "input": 10.0,
+      "output": 50.0,
+      "cache_read": 0.25,
+      "cache_write_5m": 12.5,
+      "cache_write_1h": 20.0,
+      "verified": true,
+      "source": "https://platform.claude.com/docs/en/build-with-claude/prompt-caching"
+    },
+    {
+      "provider": "anthropic",
+      "match": "claude-fable-5*",
+      "input": 10.0,
+      "output": 50.0,
+      "cache_read": 1.0,
+      "cache_write_5m": 12.5,
+      "cache_write_1h": 20.0,
+      "verified": true,
+      "source": "https://platform.claude.com/docs/en/build-with-claude/prompt-caching"
+    },
+    {
+      "provider": "anthropic",
+      "match": "claude-mythos-5*",
+      "input": 10.0,
+      "output": 50.0,
+      "cache_read": 1.0,
+      "cache_write_5m": 12.5,
+      "cache_write_1h": 20.0,
+      "verified": true,
+      "source": "https://platform.claude.com/docs/en/build-with-claude/prompt-caching"
+    },
+    {
+      "provider": "openai",
+      "match": "gpt-6-astra*",
+      "input": 10.0,
+      "output": 50.0,
+      "cache_read": 1.0,
+      "cache_write_30m": 12.5,
+      "cache_write_12h": 25.0,
+      "verified": true,
+      "source": "https://developers.openai.com/api/docs/pricing",
+      "notes": "Short context (<=272K); long-context tier unsupported in v1."
+    },
+    {
+      "provider": "openai",
+      "match": "gpt-6.1-sol*",
+      "input": 2.0,
+      "output": 10.0,
+      "cache_read": 0.1,
+      "cache_write_30m": 2.5,
+      "cache_write_12h": 5.0,
+      "verified": true,
+      "source": "https://developers.openai.com/api/docs/pricing"
+    },
+    {
+      "provider": "openai",
+      "match": "gpt-6-luna*",
+      "input": 0.1,
+      "output": 0.5,
+      "cache_read": 0.01,
+      "cache_write_30m": 0.125,
+      "cache_write_12h": 0.25,
+      "verified": true,
+      "source": "https://developers.openai.com/api/docs/pricing"
+    },
+    {
+      "provider": "openai",
+      "match": "gpt-6-sol*",
+      "input": 2.0,
+      "output": 10.0,
+      "cache_read": 0.2,
+      "cache_write_30m": 2.5,
+      "cache_write_12h": 5.0,
+      "verified": true,
+      "source": "https://developers.openai.com/api/docs/pricing"
+    },
+    {
+      "provider": "openai",
+      "match": "gpt-5.6-sol*",
+      "input": 4.0,
+      "output": 20.0,
+      "cache_read": 0.4,
+      "cache_write_30m": 5.0,
+      "cache_write_12h": 10.0,
+      "verified": true,
+      "source": "https://developers.openai.com/api/docs/pricing"
+    },
+    {
+      "provider": "openai",
+      "match": "gpt-5.6-terra*",
+      "input": 2.0,
+      "output": 12.0,
+      "cache_read": 0.2,
+      "cache_write_30m": 2.5,
+      "cache_write_12h": 5.0,
+      "verified": true,
+      "source": "https://developers.openai.com/api/docs/pricing"
+    },
+    {
+      "provider": "openai",
+      "match": "gpt-5.6-luna*",
+      "input": 0.2,
+      "output": 1.2,
+      "cache_read": 0.02,
+      "cache_write_30m": 0.25,
+      "cache_write_12h": 0.5,
+      "verified": true,
+      "source": "https://developers.openai.com/api/docs/pricing"
+    },
+    {
+      "provider": "openai",
+      "match": "gpt-5.5*",
+      "input": 5.0,
+      "output": 30.0,
+      "cache_read": 0.5,
+      "verified": true,
+      "source": "https://developers.openai.com/api/docs/pricing",
+      "notes": "Short context; no separate cache-write charge on this model."
+    },
+    {
+      "provider": "openai",
+      "match": "gpt-5.4*",
+      "input": 2.5,
+      "output": 15.0,
+      "cache_read": 0.25,
+      "verified": true,
+      "source": "https://developers.openai.com/api/docs/pricing"
+    },
+    {
+      "provider": "openai",
+      "match": "gpt-5.3-codex*",
+      "input": 1.75,
+      "output": 14.0,
+      "cache_read": 0.175,
+      "verified": true,
+      "source": "https://developers.openai.com/api/docs/pricing"
+    },
+    {
+      "provider": "openai",
+      "match": "gpt-5.2*",
+      "input": 1.75,
+      "output": 14.0,
+      "cache_read": 0.175,
+      "verified": true,
+      "source": "https://developers.openai.com/api/docs/pricing"
+    },
+    {
+      "provider": "openai",
+      "match": "gpt-5.1*",
+      "input": 1.25,
+      "output": 10.0,
+      "cache_read": 0.125,
+      "verified": true,
+      "source": "https://developers.openai.com/api/docs/pricing"
+    },
+    {
+      "provider": "openai",
+      "match": "gpt-5*",
+      "input": 1.25,
+      "output": 10.0,
+      "cache_read": 0.125,
+      "verified": true,
+      "source": "https://developers.openai.com/api/docs/pricing"
+    },
+    {
+      "provider": "openai",
+      "match": "gpt-4.1*",
+      "input": 2.0,
+      "output": 8.0,
+      "cache_read": 0.5,
+      "verified": true,
+      "source": "https://developers.openai.com/api/docs/pricing"
+    },
+    {
+      "provider": "openai",
+      "match": "gpt-4o-mini*",
+      "input": 0.15,
+      "output": 0.6,
+      "cache_read": 0.075,
+      "verified": true,
+      "source": "https://developers.openai.com/api/docs/pricing"
+    },
+    {
+      "provider": "openai",
+      "match": "gpt-4o*",
+      "input": 2.5,
+      "output": 10.0,
+      "cache_read": 1.25,
+      "verified": true,
+      "source": "https://developers.openai.com/api/docs/pricing"
+    },
+    {
+      "provider": "deepseek",
+      "match": "deepseek-flash*",
+      "input": 0.3,
+      "output": 1.2,
+      "cache_read": 0.006,
+      "verified": true,
+      "source": "https://api-docs.deepseek.com/quick_start/pricing",
+      "notes": "Peak rates; off-peak is half. Cache writes have no fee."
+    },
+    {
+      "provider": "deepseek",
+      "match": "deepseek-v4-pro*",
+      "input": 1.32,
+      "output": 3.96,
+      "cache_read": 0.044,
+      "verified": true,
+      "source": "https://api-docs.deepseek.com/quick_start/pricing",
+      "notes": "Peak rates; off-peak is half. Cache writes have no fee."
+    },
+    {
+      "provider": "gemini",
+      "match": "gemini-4-argon*",
+      "input": 2.0,
+      "output": 10.0,
+      "cache_read": 0.1,
+      "verified": true,
+      "source": "https://ai.google.dev/gemini-api/docs/pricing",
+      "notes": "Standard tier through 2026-11-30; prices rise on 2026-12-01."
+    },
+    {
+      "provider": "gemini",
+      "match": "gemini-3.8-flash*",
+      "input": 0.75,
+      "output": 3.75,
+      "cache_read": 0.075,
+      "verified": true,
+      "source": "https://ai.google.dev/gemini-api/docs/pricing",
+      "notes": "Standard tier through 2026-12-31; prices rise on 2027-01-01."
+    },
+    {
+      "provider": "gemini",
+      "match": "gemini-3.6-flash*",
+      "input": 0.75,
+      "output": 3.75,
+      "cache_read": 0.075,
+      "verified": true,
+      "source": "https://ai.google.dev/gemini-api/docs/pricing"
+    },
+    {
+      "provider": "gemini",
+      "match": "gemini-3.5-flash-lite*",
+      "input": 0.3,
+      "output": 2.5,
+      "cache_read": 0.03,
+      "verified": true,
+      "source": "https://ai.google.dev/gemini-api/docs/pricing"
+    },
+    {
+      "provider": "gemini",
+      "match": "gemini-3.1-flash-lite*",
+      "input": 0.25,
+      "output": 1.5,
+      "cache_read": 0.025,
+      "verified": true,
+      "source": "https://ai.google.dev/gemini-api/docs/pricing"
+    },
+    {
+      "provider": "gemini",
+      "match": "gemini-3.1-pro-preview*",
+      "input": 2.0,
+      "output": 12.0,
+      "cache_read": 0.2,
+      "verified": true,
+      "source": "https://ai.google.dev/gemini-api/docs/pricing",
+      "notes": "Standard tier for prompts <=200k tokens."
+    }
+  ]
+}

ctxoptimizer/doctor.py

@@ -0,0 +1,129 @@
+"""Shared diagnostic checks for the CLI and dashboard Doctor page (P5)."""
+
+from __future__ import annotations
+
+import importlib.util
+import socket
+import sqlite3
+from dataclasses import dataclass
+from datetime import date
+from pathlib import Path
+
+from ctxoptimizer.config import LOOPBACK_HOSTS, Config, data_dir
+from ctxoptimizer.telemetry.pricing import load_pricing
+
+
+@dataclass(frozen=True, slots=True)
+class Check:
+    name: str
+    ok: bool
+    detail: str
+    warning: bool = False
+
+
+def run_checks(config: Config, *, offline: bool = True) -> list[Check]:
+    checks: list[Check] = []
+    checks.append(
+        Check(
+            "bind host",
+            config.server.host in LOOPBACK_HOSTS or config.server.allow_remote,
+            config.server.host,
+        )
+    )
+    db_path = (
+        Path(config.telemetry.db_path)
+        if config.telemetry.db_path
+        else data_dir() / "ctxoptimizer.db"
+    )
+    try:
+        with sqlite3.connect(db_path) as conn:
+            conn.execute("PRAGMA user_version").fetchone()
+        checks.append(Check("database writable", True, str(db_path)))
+    except Exception as exc:
+        checks.append(Check("database writable", False, str(exc)))
+
+    try:
+        table = load_pricing(Path(config.pricing.file) if config.pricing.file else None)
+        verified = sum(1 for price in table.models if price.verified)
+        checks.append(
+            Check(
+                "pricing",
+                True,
+                f"version {table.version}, {verified} verified entries",
+            )
+        )
+        try:
+            age = (date.today() - date.fromisoformat(table.version)).days
+            if age > 60:
+                checks.append(
+                    Check(
+                        "pricing age",
+                        False,
+                        f"{age} days; check provider pages",
+                        warning=True,
+                    )
+                )
+        except ValueError:
+            checks.append(
+                Check(
+                    "pricing age",
+                    False,
+                    f"unparseable version {table.version!r}",
+                    warning=True,
+                )
+            )
+    except Exception as exc:
+        checks.append(Check("pricing", False, str(exc)))
+
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as sock:
+            sock.bind((config.server.host, config.server.port))
+        checks.append(Check("port free", True, str(config.server.port)))
+    except OSError:
+        checks.append(
+            Check(
+                "port free",
+                False,
+                f"{config.server.port} already in use (is ctxoptimizer running?)",
+                warning=True,
+            )
+        )
+
+    checks.append(
+        Check(
+            "tiktoken",
+            importlib.util.find_spec("tiktoken") is not None,
+            "available" if importlib.util.find_spec("tiktoken") else "fallback estimator",
+            warning=True,
+        )
+    )
+    if config.transforms.cache_serve.enabled and config.telemetry.capture_payloads == "off":
+        checks.append(
+            Check(
+                "cache_serve capture",
+                False,
+                "cache_serve requires capture_payloads != off",
+            )
+        )
+    if not offline:
+        import httpx
+
+        for name, entry in sorted(config.upstreams.items()):
+            base = entry if isinstance(entry, str) else entry.url
+            try:
+                response = httpx.head(base, timeout=2.0, follow_redirects=False)
+                checks.append(
+                    Check(
+                        f"upstream {name}",
+                        response.status_code < 500,
+                        f"HTTP {response.status_code}",
+                        warning=True,
+                    )
+                )
+            except httpx.HTTPError as exc:
+                checks.append(Check(f"upstream {name}", False, str(exc), warning=True))
+
+    return checks
+
+
+__all__ = ["Check", "run_checks"]

ctxoptimizer/guard.py

@@ -0,0 +1,139 @@
+"""Auto-quarantine guard (SPEC section 12.14). Session-scoped and reversible."""
+
+from __future__ import annotations
+
+import time
+from collections import defaultdict, deque
+
+from ctxoptimizer.config import Config
+
+
+class Guard:
+    def __init__(self, config: Config) -> None:
+        self.config = config
+        self._fallbacks: dict[tuple[str, str], deque[float]] = defaultdict(
+            lambda: deque(
+                maxlen=max(
+                    1,
+                    config.guard.fallback_window,
+                    config.guard.fallback_limit + 1,
+                )
+            )
+        )
+        self._drift: dict[tuple[str, str], int] = defaultdict(int)
+        self._quarantined: dict[tuple[str, str], str] = {}
+        self._recovery: dict[tuple[str, str], int] = defaultdict(int)
+        self._savings: dict[tuple[str, str], deque[float]] = defaultdict(
+            lambda: deque(maxlen=max(1, config.guard.fallback_window))
+        )
+        self._store: object | None = None
+
+    def bind_store(self, store: object) -> None:
+        """Attach the telemetry store so quarantine events are persisted."""
+        self._store = store
+
+    def _record(self, session_id: str, transform_id: str, reason: str) -> None:
+        record = getattr(self._store, "record_guard_event", None)
+        if callable(record):
+            record(session_id, transform_id, reason, {"limit": self.config.guard.fallback_limit})
+
+    def quarantined_for(self, session_id: str) -> set[str]:
+        return {transform_id for (sid, transform_id) in self._quarantined if sid == session_id}
+
+    def is_quarantined(self, session_id: str, transform_id: str) -> bool:
+        return (session_id, transform_id) in self._quarantined
+
+    def observe_fallback(self, session_id: str, transform_ids: list[str]) -> None:
+        if not self.config.guard.enabled:
+            return
+        for transform_id in transform_ids:
+            key = (session_id, transform_id)
+            self._fallbacks[key].append(time.time())
+            if len(self._fallbacks[key]) > self.config.guard.fallback_limit:
+                self._quarantined[key] = "fallbacks"
+                self._record(session_id, transform_id, "fallbacks")
+
+    def observe_final_drift(
+        self, session_id: str, cause: str | None, transform_ids: list[str]
+    ) -> None:
+        if not self.config.guard.enabled or not cause:
+            return
+        for transform_id in transform_ids:
+            key = (session_id, transform_id)
+            self._drift[key] += 1
+            if self._drift[key] >= self.config.guard.our_fault_drift_limit:
+                self._quarantined[key] = "our_fault_drift"
+                self._record(session_id, transform_id, "our_fault_drift")
+
+    def observe_request(self, session_id: str) -> None:
+        """Count successful requests and optionally auto-re-enable."""
+        if not self.config.guard.enabled or self.config.guard.auto_reenable <= 0:
+            return
+        for key in list(self._quarantined):
+            if key[0] != session_id:
+                continue
+            self._recovery[key] += 1
+            if self._recovery[key] >= self.config.guard.auto_reenable:
+                self.enable(*key)
+
+    def observe_savings(self, session_id: str, transform_id: str, usd: float) -> None:
+        """Quarantine a reduction that costs more than it saves over a window."""
+        if not self.config.guard.enabled:
+            return
+        if transform_id in {"anthropic_cache", "openai_hints"}:
+            return
+        key = (session_id, transform_id)
+        window = self._savings[key]
+        window.append(max(usd, 0.0))
+        if (
+            len(window) >= self.config.guard.fallback_window
+            and sum(window) < self.config.guard.min_savings_to_stay
+        ):
+            self._quarantined[key] = "low_savings"
+            self._record(session_id, transform_id, "low_savings")
+
+    def observe_expand_health(self, session_id: str) -> None:
+        """Quarantine omission transforms when expand errors are too high."""
+        if not self.config.guard.enabled or self._store is None:
+            return
+        from ctxoptimizer.telemetry.expand import expand_stats
+
+        path = getattr(self._store, "path", None)
+        stats = expand_stats(db_path=path) if path is not None else expand_stats()
+        if stats["total"] < 10:
+            return
+        errors = int(stats["errors"])
+        if errors / max(int(stats["total"]), 1) <= self.config.guard.expand_error_rate:
+            return
+        for transform_id in ("cache_serve", "stale_result_elision"):
+            key = (session_id, transform_id)
+            if key not in self._quarantined:
+                self._quarantined[key] = "expand_errors"
+                self._record(session_id, transform_id, "expand_errors")
+
+    def enable(self, session_id: str, transform_id: str) -> None:
+        self._quarantined.pop((session_id, transform_id), None)
+        self._fallbacks.pop((session_id, transform_id), None)
+        self._drift.pop((session_id, transform_id), None)
+        self._recovery.pop((session_id, transform_id), None)
+        self._savings.pop((session_id, transform_id), None)
+        record = getattr(self._store, "record_guard_event", None)
+        if callable(record):
+            record(session_id, transform_id, "enabled", {"cleared": True}, cleared_ts=time.time())
+
+    def disable(self, session_id: str, transform_id: str, reason: str = "manual") -> None:
+        self._quarantined[(session_id, transform_id)] = reason
+        self._record(session_id, transform_id, reason)
+
+    def status(self) -> list[dict[str, str]]:
+        return [
+            {
+                "session_id": session_id,
+                "transform_id": transform_id,
+                "reason": reason,
+            }
+            for (session_id, transform_id), reason in self._quarantined.items()
+        ]
+
+
+__all__ = ["Guard"]