ctxoptimizer 0.4.1__py3-none-any.whl

ctxoptimizer/__init__.py

@@ -0,0 +1,5 @@
+"""ctxoptimizer: a local, deterministic cost optimizer for AI coding agents."""
+
+from __future__ import annotations
+
+__version__ = "0.4.1"

ctxoptimizer/__main__.py

@@ -0,0 +1,14 @@
+"""Module entry point for ``python -m ctxoptimizer``."""
+
+from __future__ import annotations
+
+from ctxoptimizer.cli import app
+
+
+def main() -> None:
+    """Run the command line interface."""
+    app()
+
+
+if __name__ == "__main__":
+    main()

ctxoptimizer/admin_security.py

@@ -0,0 +1,130 @@
+"""Admin endpoint security: Host allowlist, token and CSRF (SPEC 16.1)."""
+
+from __future__ import annotations
+
+import hmac
+import json
+import os
+import secrets
+from pathlib import Path
+
+from starlette.middleware.base import BaseHTTPMiddleware, RequestResponseEndpoint
+from starlette.requests import Request
+from starlette.responses import JSONResponse, Response
+from starlette.types import ASGIApp
+
+from ctxoptimizer.config import LOOPBACK_HOSTS, Config, data_dir
+
+_MUTATING = frozenset({"POST", "PUT", "PATCH", "DELETE"})
+_HEALTH = "/_ctxoptimizer/health"
+
+
+class AdminSecurityMiddleware(BaseHTTPMiddleware):
+    def __init__(
+        self,
+        app: ASGIApp,
+        *,
+        config: Config,
+        admin_token: str | None = None,
+        csrf_token: str | None = None,
+    ) -> None:
+        super().__init__(app)
+        self.config = config
+        self.admin_token = admin_token or config.server.admin_token or secrets.token_urlsafe(24)
+        self.csrf_token = csrf_token or secrets.token_urlsafe(24)
+
+    async def dispatch(self, request: Request, call_next: RequestResponseEndpoint) -> Response:
+        path = request.url.path
+        if not path.startswith("/_ctxoptimizer") or path == _HEALTH:
+            return await call_next(request)
+
+        host = (request.url.hostname or "").lower()
+        allowed = set(LOOPBACK_HOSTS)
+        if self.config.server.allow_remote:
+            allowed.add(self.config.server.host.lower())
+        if host not in allowed:
+            return JSONResponse({"error": "forbidden admin host"}, status_code=403)
+
+        supplied = (
+            request.query_params.get("token")
+            or request.headers.get("x-ctxoptimizer-admin-token")
+            or request.cookies.get("ctxoptimizer_admin")
+        )
+        if not _same(supplied, self.admin_token):
+            return JSONResponse({"error": "admin token required"}, status_code=401)
+
+        if request.method in _MUTATING:
+            csrf = request.headers.get("x-ctxoptimizer-csrf") or request.query_params.get("csrf")
+            if not _same(csrf, self.csrf_token):
+                return JSONResponse({"error": "csrf token required"}, status_code=403)
+
+        response = await call_next(request)
+        if request.query_params.get("token"):
+            response.set_cookie(
+                "ctxoptimizer_admin",
+                self.admin_token,
+                httponly=True,
+                samesite="strict",
+                path="/_ctxoptimizer",
+            )
+            response.set_cookie(
+                "ctxoptimizer_csrf",
+                self.csrf_token,
+                httponly=False,
+                samesite="strict",
+                path="/_ctxoptimizer",
+            )
+        # No CORS support on admin endpoints (SPEC 16.1).
+        if "access-control-allow-origin" in response.headers:
+            del response.headers["access-control-allow-origin"]
+        return response
+
+
+def admin_credentials() -> tuple[str, str]:
+    """Create a fresh per-run admin token and CSRF token."""
+    return secrets.token_urlsafe(24), secrets.token_urlsafe(24)
+
+
+def token_file() -> Path:
+    return data_dir() / "admin-token.json"
+
+
+def save_tokens(admin_token: str, csrf_token: str) -> Path:
+    """Persist the per-run tokens for local CLI commands (0600 on POSIX)."""
+    path = token_file()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        json.dumps({"admin_token": admin_token, "csrf_token": csrf_token}),
+        encoding="utf-8",
+    )
+    if os.name == "posix":
+        os.chmod(path, 0o600)
+    return path
+
+
+def load_tokens() -> tuple[str | None, str | None]:
+    try:
+        payload = json.loads(token_file().read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError):
+        return None, None
+    admin = payload.get("admin_token")
+    csrf = payload.get("csrf_token")
+    return (
+        admin if isinstance(admin, str) else None,
+        csrf if isinstance(csrf, str) else None,
+    )
+
+
+def _same(left: str | None, right: str) -> bool:
+    if not left:
+        return False
+    return hmac.compare_digest(left, right)
+
+
+__all__ = [
+    "AdminSecurityMiddleware",
+    "admin_credentials",
+    "load_tokens",
+    "save_tokens",
+    "token_file",
+]

ctxoptimizer/analysis/__init__.py

@@ -0,0 +1 @@
+"""Deterministic analysis: segments, drift, waste and baseline (SPEC section 13)."""

ctxoptimizer/analysis/baseline.py

@@ -0,0 +1,69 @@
+"""Cache baseline simulator (SPEC section 13.5)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ctxoptimizer.analysis.segments import Segment
+
+
+@dataclass(frozen=True, slots=True)
+class CacheSim:
+    fresh_tokens: int
+    read_tokens: int
+    write_5m_tokens: int
+    write_1h_tokens: int
+
+
+def common_prefix_tokens(previous: list[Segment], current: list[Segment]) -> int:
+    total = 0
+    for old, new in zip(previous, current, strict=False):
+        if old.hash != new.hash:
+            break
+        total += new.est_tokens
+    return total
+
+
+def simulate(
+    cache_policy: str,
+    previous: list[Segment] | None,
+    previous_ts: float | None,
+    current: list[Segment],
+    current_ts: float,
+    *,
+    ttl_s: float = 300.0,
+    min_prefix: int = 1024,
+) -> CacheSim:
+    total = sum(segment.est_tokens for segment in current)
+    if previous is None or previous_ts is None or current_ts - previous_ts > ttl_s:
+        return CacheSim(total, 0, 0, 0)
+    if cache_policy == "explicit-anthropic":
+        return _explicit(previous, current, total)
+    if cache_policy in {"implicit-openai", "gemini-implicit", "automatic-deepseek"}:
+        prefix = common_prefix_tokens(previous, current)
+        read = (prefix // 128) * 128 if prefix >= min_prefix else 0
+        return CacheSim(max(0, total - read), min(total, read), 0, 0)
+    return CacheSim(total, 0, 0, 0)
+
+
+def _explicit(previous: list[Segment], current: list[Segment], total: int) -> CacheSim:
+    previous_marker = _tokens_to_last_marker(previous)
+    current_marker = _tokens_to_last_marker(current)
+    if previous_marker == 0 or current_marker == 0:
+        return CacheSim(total, 0, 0, 0)
+    read = min(common_prefix_tokens(previous, current), previous_marker)
+    write = max(0, current_marker - read)
+    return CacheSim(max(0, total - read - write), read, write, 0)
+
+
+def _tokens_to_last_marker(segments: list[Segment]) -> int:
+    last = -1
+    for index, segment in enumerate(segments):
+        if segment.has_marker:
+            last = index
+    if last < 0:
+        return 0
+    return sum(segment.est_tokens for segment in segments[: last + 1])
+
+
+__all__ = ["CacheSim", "common_prefix_tokens", "simulate"]

ctxoptimizer/analysis/break_even.py

@@ -0,0 +1,49 @@
+"""Conservative break-even estimate for ``stale_result_elision`` (P6-4)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, slots=True)
+class StaleElisionEstimate:
+    elided_tokens: int
+    batch_turns: int
+    savings_per_request_usd: float
+    boundary_miss_cost_usd: float
+    requests_to_recover: float | None
+    break_even_within_batch: bool
+    method: str
+
+
+def estimate_stale_elision(
+    *,
+    elided_tokens: int,
+    batch_turns: int,
+    input_per_mtok: float,
+    cache_read_per_mtok: float,
+    cache_write_per_mtok: float = 0.0,
+) -> StaleElisionEstimate:
+    """Estimate the trade-off. All money is simulated, never billed."""
+    tokens = max(int(elided_tokens), 0)
+    batch = max(int(batch_turns), 1)
+    savings = tokens * max(input_per_mtok, 0.0) / 1_000_000
+    miss = (
+        tokens * max(input_per_mtok + cache_write_per_mtok - cache_read_per_mtok, 0.0) / 1_000_000
+    )
+    recover = (miss / savings) if savings > 0 else None
+    return StaleElisionEstimate(
+        elided_tokens=tokens,
+        batch_turns=batch,
+        savings_per_request_usd=savings,
+        boundary_miss_cost_usd=miss,
+        requests_to_recover=recover,
+        break_even_within_batch=(recover is not None and recover <= batch),
+        method=(
+            "sim.: assumes elided tokens would otherwise be fresh input; one "
+            "cache-miss per boundary advance at input + write - read rates."
+        ),
+    )
+
+
+__all__ = ["StaleElisionEstimate", "estimate_stale_elision"]

ctxoptimizer/analysis/drift.py

@@ -0,0 +1,151 @@
+"""Prefix-drift detector (SPEC section 13.4)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Literal
+
+from ctxoptimizer.analysis.segments import Segment
+
+DriftCause = Literal[
+    "tools_changed",
+    "system_changed",
+    "params_changed",
+    "history_mutated",
+    "ttl_expired",
+    "config_changed",
+    "model_switched",
+]
+
+_CAUSE_BY_KIND: dict[str, DriftCause] = {
+    "tool_def": "tools_changed",
+    "system": "system_changed",
+    "message": "history_mutated",
+}
+
+
+@dataclass(frozen=True, slots=True)
+class DriftEvent:
+    cause: DriftCause
+    at_segment: int | None
+    est_tokens_lost: int
+    detail: dict[str, object]
+
+
+def detect_drift(
+    previous: list[Segment] | None,
+    current: list[Segment],
+    *,
+    previous_ts: float | None = None,
+    current_ts: float | None = None,
+    ttl_s: float = 300.0,
+    previous_params: str | None = None,
+    current_params: str | None = None,
+    previous_config_hash: str | None = None,
+    current_config_hash: str | None = None,
+    previous_model: str | None = None,
+    current_model: str | None = None,
+) -> DriftEvent | None:
+    """Return the first divergence that would break prefix cache reuse."""
+    if previous is None:
+        return None
+    if previous_model and current_model and previous_model != current_model:
+        return DriftEvent(
+            "model_switched",
+            0,
+            _lost(previous, current, 0),
+            {"previous": previous_model, "current": current_model},
+        )
+    if (
+        previous_params is not None
+        and current_params is not None
+        and previous_params != current_params
+    ):
+        return DriftEvent(
+            "params_changed", 0, _lost(previous, current, 0), {"params": current_params}
+        )
+    if previous_config_hash and current_config_hash and previous_config_hash != current_config_hash:
+        return DriftEvent(
+            "config_changed",
+            0,
+            _lost(previous, current, 0),
+            {"config_hash": current_config_hash},
+        )
+
+    limit = min(len(previous), len(current))
+    first = next(
+        (index for index in range(limit) if previous[index].hash != current[index].hash),
+        None,
+    )
+    if first is None and len(current) < len(previous):
+        first = len(current)
+    if first is not None:
+        kind = current[first].kind if first < len(current) else previous[first].kind
+        return DriftEvent(
+            _CAUSE_BY_KIND.get(kind, "history_mutated"),
+            first,
+            _lost(previous, current, first),
+            {"kind": kind},
+        )
+
+    if previous_ts is not None and current_ts is not None:
+        delta = current_ts - previous_ts
+        if delta > ttl_s:
+            return DriftEvent(
+                "ttl_expired",
+                None,
+                sum(segment.est_tokens for segment in current),
+                {"delta_s": round(delta, 3), "ttl_s": ttl_s},
+            )
+    return None
+
+
+class DriftTracker:
+    """Keep the last segment list and fingerprint per session."""
+
+    def __init__(self, max_sessions: int = 256) -> None:
+        self.max_sessions = max_sessions
+        self._state: dict[str, tuple[list[Segment], float, str, str, str]] = {}
+
+    def observe(
+        self,
+        session_id: str,
+        segments: list[Segment],
+        ts: float,
+        *,
+        params: str = "",
+        config_hash: str = "",
+        model: str = "",
+        ttl_s: float = 300.0,
+    ) -> DriftEvent | None:
+        previous = self._state.get(session_id)
+        event = detect_drift(
+            previous[0] if previous else None,
+            segments,
+            previous_ts=previous[1] if previous else None,
+            current_ts=ts,
+            ttl_s=ttl_s,
+            previous_params=previous[2] if previous else None,
+            current_params=params,
+            previous_config_hash=previous[3] if previous else None,
+            current_config_hash=config_hash,
+            previous_model=previous[4] if previous else None,
+            current_model=model,
+        )
+        if len(self._state) >= self.max_sessions and session_id not in self._state:
+            self._state.pop(next(iter(self._state)))
+        self._state[session_id] = (segments, ts, params, config_hash, model)
+        return event
+
+    def clear(self) -> None:
+        self._state.clear()
+
+
+def _lost(previous: list[Segment], current: list[Segment], first: int) -> int:
+    end = min(len(previous), len(current))
+    if first >= end:
+        return 0
+    return sum(segment.est_tokens for segment in current[first:end])
+
+
+__all__ = ["DriftCause", "DriftEvent", "DriftTracker", "detect_drift"]

ctxoptimizer/analysis/edits.py

@@ -0,0 +1,148 @@
+"""Conservative tool-edit extraction for the opt-in churn detector (W7).
+
+Only argument dictionaries with a known old/new string pair are inspected. Raw
+edit text stays in memory for the current request and is never persisted.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import orjson
+
+from ctxoptimizer.analysis.tokens import estimate_tokens
+from ctxoptimizer.analysis.waste import EditObservation
+from ctxoptimizer.models import Provider
+from ctxoptimizer.providers.base import blocks_of
+
+_PAIRS: tuple[tuple[str, str], ...] = (
+    ("old_string", "new_string"),
+    ("oldText", "newText"),
+    ("old_str", "new_str"),
+    ("old_content", "new_content"),
+    ("search", "replace"),
+    ("old", "new"),
+)
+_PATH_KEYS = ("file_path", "path", "filename", "file", "target_file")
+
+
+def edit_observations(payload: dict[str, Any], provider: Provider) -> list[EditObservation]:
+    observations: list[EditObservation] = []
+    for tool_name, arguments in _tool_inputs(payload, provider):
+        if not isinstance(arguments, dict):
+            continue
+        path = _path_of(arguments) or tool_name or "<unknown>"
+        for old_key, new_key in _PAIRS:
+            old = arguments.get(old_key)
+            new = arguments.get(new_key)
+            if not isinstance(old, str) or not isinstance(new, str):
+                continue
+            observations.append(
+                EditObservation(
+                    path=path,
+                    old=old,
+                    new=new,
+                    tool_name=tool_name,
+                    tokens=max(estimate_tokens(old), estimate_tokens(new)),
+                )
+            )
+            break
+    return observations
+
+
+def _tool_inputs(payload: dict[str, Any], provider: Provider) -> list[tuple[str | None, object]]:
+    if provider is Provider.ANTHROPIC:
+        return _anthropic_inputs(payload)
+    if provider is Provider.GEMINI:
+        return _gemini_inputs(payload)
+    if provider is Provider.OLLAMA:
+        return _chat_inputs(payload)
+    return _openai_inputs(payload)
+
+
+def _anthropic_inputs(payload: dict[str, Any]) -> list[tuple[str | None, object]]:
+    result: list[tuple[str | None, object]] = []
+    result.extend(
+        (
+            block.get("name") if isinstance(block.get("name"), str) else None,
+            block.get("input"),
+        )
+        for message in payload.get("messages") or []
+        if isinstance(message, dict)
+        for block in blocks_of(message.get("content"))
+        if block.get("type") == "tool_use"
+    )
+    return result
+
+
+def _openai_inputs(payload: dict[str, Any]) -> list[tuple[str | None, object]]:
+    result: list[tuple[str | None, object]] = []
+    result.extend(
+        (
+            item.get("name") if isinstance(item.get("name"), str) else None,
+            _arguments(item.get("arguments")),
+        )
+        for item in payload.get("input") or []
+        if isinstance(item, dict) and item.get("type") == "function_call"
+    )
+    result.extend(_chat_inputs(payload))
+    return result
+
+
+def _chat_inputs(payload: dict[str, Any]) -> list[tuple[str | None, object]]:
+    result: list[tuple[str | None, object]] = []
+    for message in payload.get("messages") or []:
+        if not isinstance(message, dict):
+            continue
+        for call in message.get("tool_calls") or []:
+            if not isinstance(call, dict):
+                continue
+            function = call.get("function")
+            if not isinstance(function, dict):
+                continue
+            result.append(
+                (
+                    function.get("name") if isinstance(function.get("name"), str) else None,
+                    _arguments(function.get("arguments")),
+                )
+            )
+    return result
+
+
+def _gemini_inputs(payload: dict[str, Any]) -> list[tuple[str | None, object]]:
+    result: list[tuple[str | None, object]] = []
+    for content in payload.get("contents") or []:
+        if not isinstance(content, dict):
+            continue
+        for part in content.get("parts") or []:
+            if not isinstance(part, dict):
+                continue
+            call = part.get("functionCall")
+            if isinstance(call, dict):
+                result.append(
+                    (
+                        call.get("name") if isinstance(call.get("name"), str) else None,
+                        call.get("args"),
+                    )
+                )
+    return result
+
+
+def _arguments(value: object) -> object:
+    if isinstance(value, str):
+        try:
+            return orjson.loads(value)
+        except (orjson.JSONDecodeError, TypeError):
+            return None
+    return value
+
+
+def _path_of(arguments: dict[str, Any]) -> str | None:
+    for key in _PATH_KEYS:
+        value = arguments.get(key)
+        if isinstance(value, str) and value:
+            return value
+    return None
+
+
+__all__ = ["edit_observations"]

ctxoptimizer/analysis/markers.py

@@ -0,0 +1,34 @@
+"""Client cache-marker quality (SPEC section 12.9 / P4-3)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from ctxoptimizer.analysis.segments import Segment
+
+
+@dataclass(frozen=True, slots=True)
+class MarkerQuality:
+    markers: int
+    cacheable_tokens: int
+    total_tokens: int
+    coverage: float
+
+
+def marker_quality(segments: list[Segment]) -> MarkerQuality:
+    markers = sum(1 for segment in segments if segment.has_marker)
+    total = sum(segment.est_tokens for segment in segments)
+    last = -1
+    for index, segment in enumerate(segments):
+        if segment.has_marker:
+            last = index
+    cacheable = sum(segment.est_tokens for segment in segments[: last + 1]) if last >= 0 else 0
+    return MarkerQuality(
+        markers=markers,
+        cacheable_tokens=cacheable,
+        total_tokens=total,
+        coverage=(cacheable / total) if total else 0.0,
+    )
+
+
+__all__ = ["MarkerQuality", "marker_quality"]