ctxoptimizer 0.4.1__py3-none-any.whl

ctxoptimizer/analysis/recommend.py

@@ -0,0 +1,114 @@
+"""Ranked recommendations from measured evidence (SPEC section 13.7).
+
+P2 scope: a deterministic, advisory list. Nothing is auto-applied.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from ctxoptimizer.models import WasteFinding
+
+
+def recommendations(
+    findings: list[WasteFinding],
+    *,
+    cache_serve_enabled: bool = False,
+    volatile_normalizer_enabled: bool = False,
+    transforms_enabled: bool = True,
+) -> list[dict[str, Any]]:
+    grouped: dict[str, list[WasteFinding]] = {}
+    for finding in findings:
+        grouped.setdefault(finding.detector, []).append(finding)
+
+    result: list[dict[str, Any]] = []
+    rereads = grouped.get("redundant_reread", [])
+    if rereads and not cache_serve_enabled:
+        tokens = sum(item.est_tokens_wasted or 0 for item in rereads)
+        result.append(
+            {
+                "id": "enable_cache_serve",
+                "title": "Enable cache_serve for repeated file reads",
+                "evidence": f"{len(rereads)} redundant re-read finding(s)",
+                "est_tokens": tokens,
+                "label": "sim.",
+                "action": "set transforms.cache_serve.enabled = true",
+            }
+        )
+    drift = grouped.get("recurring_drift", [])
+    if drift and not volatile_normalizer_enabled:
+        tokens = sum(item.est_tokens_wasted or 0 for item in drift)
+        result.append(
+            {
+                "id": "enable_volatile_normalizer",
+                "title": "Stabilize volatile system-prompt tokens",
+                "evidence": f"{len(drift)} recurring drift finding(s)",
+                "est_tokens": tokens,
+                "label": "sim.",
+                "action": "investigate timestamps/UUIDs in the system prompt",
+            }
+        )
+    if grouped.get("unbatched_fanout"):
+        result.append(
+            {
+                "id": "batch_reads",
+                "title": "Batch consecutive read calls",
+                "evidence": f"{len(grouped['unbatched_fanout'])} fan-out finding(s)",
+                "est_tokens": 0,
+                "label": "est.",
+                "action": "advisory: issue independent reads together",
+            }
+        )
+    if grouped.get("runaway_session"):
+        result.append(
+            {
+                "id": "investigate_runaway",
+                "title": "Investigate long-running unattended sessions",
+                "evidence": f"{len(grouped['runaway_session'])} runaway finding(s)",
+                "est_tokens": sum(
+                    item.est_tokens_wasted or 0 for item in grouped["runaway_session"]
+                ),
+                "label": "est.",
+                "action": "advisory: stop idle agents before resuming",
+            }
+        )
+    if grouped.get("schema_bloat"):
+        result.append(
+            {
+                "id": "prune_mcp_schemas",
+                "title": "Prune unused tool schemas",
+                "evidence": f"{len(grouped['schema_bloat'])} unused schema finding(s)",
+                "est_tokens": sum(item.est_tokens_wasted or 0 for item in grouped["schema_bloat"]),
+                "label": "sim.",
+                "action": "advisory: remove MCP tools the agent never calls",
+            }
+        )
+    if grouped.get("churn_detector"):
+        result.append(
+            {
+                "id": "investigate_churn",
+                "title": "Investigate revert/whitespace edit churn",
+                "evidence": f"{len(grouped['churn_detector'])} churn finding(s)",
+                "est_tokens": sum(
+                    item.est_tokens_wasted or 0 for item in grouped["churn_detector"]
+                ),
+                "label": "est.",
+                "action": "advisory: fix instructions or formatter loops",
+            }
+        )
+    if not transforms_enabled:
+        result.append(
+            {
+                "id": "enable_transforms",
+                "title": "Enable the deterministic transform pipeline",
+                "evidence": "pipeline disabled in config",
+                "est_tokens": 0,
+                "label": "sim.",
+                "action": "set mode = active after a shadow run",
+            }
+        )
+    result.sort(key=lambda item: int(item["est_tokens"]), reverse=True)
+    return result
+
+
+__all__ = ["recommendations"]

ctxoptimizer/analysis/segments.py

@@ -0,0 +1,57 @@
+"""Canonical segments and content hashing (SPEC section 13.3)."""
+
+from __future__ import annotations
+
+import math
+from dataclasses import dataclass
+from hashlib import blake2b
+from typing import Any, Literal
+
+import orjson
+
+from ctxoptimizer.analysis.tokens import estimate_tokens
+
+
+@dataclass(frozen=True, slots=True)
+class Segment:
+    kind: Literal["tool_def", "system", "message"]
+    msg_index: int | None
+    block_index: int | None
+    hash: bytes
+    est_tokens: int
+    has_marker: bool
+
+
+def block_hash(block: dict[str, Any]) -> bytes:
+    """Stable 8-byte hash of a block, ignoring cache markers."""
+    clean = {key: value for key, value in block.items() if key != "cache_control"}
+    encoded = orjson.dumps(clean, option=orjson.OPT_SORT_KEYS)
+    return blake2b(encoded, digest_size=8).digest()
+
+
+def block_tokens(block: dict[str, Any]) -> int:
+    for key in ("text", "content"):
+        value = block.get(key)
+        if isinstance(value, str):
+            return estimate_tokens(value)
+    return max(1, math.ceil(len(orjson.dumps(block)) / 3.5))
+
+
+def make_segment(
+    kind: Literal["tool_def", "system", "message"],
+    block: dict[str, Any],
+    *,
+    msg_index: int | None = None,
+    block_index: int | None = None,
+) -> Segment:
+    return Segment(
+        kind=kind,
+        msg_index=msg_index,
+        block_index=block_index,
+        hash=block_hash(block),
+        est_tokens=block_tokens(block),
+        has_marker="cache_control" in block,
+    )
+
+
+__all__ = ["Segment", "block_hash", "block_tokens", "make_segment"]

ctxoptimizer/analysis/session.py

@@ -0,0 +1,62 @@
+"""Session and project identification (SPEC section 13.1)."""
+
+from __future__ import annotations
+
+import re
+from collections.abc import Mapping
+from hashlib import blake2b, sha256
+from typing import Any
+
+from ctxoptimizer.models import Provider
+from ctxoptimizer.providers.base import ProviderAdapter
+
+_WORKDIR_PATTERNS = (
+    re.compile(r"Working directory:\s*(\S+)"),
+    re.compile(r"<cwd>(.*?)</cwd>"),
+    re.compile(r"Primary working directory:\s*(\S+)"),
+)
+
+
+def key_fingerprint(headers: Mapping[str, str]) -> str:
+    """Stable fingerprint of the client credential; the raw key is never kept."""
+    value = headers.get("x-api-key") or headers.get("authorization") or ""
+    if not value:
+        return "anonymous"
+    return sha256(value.encode("utf-8")).hexdigest()[:12]
+
+
+def derive_session_id(
+    provider: Provider,
+    headers: Mapping[str, str],
+    payload: dict[str, Any],
+    adapter: ProviderAdapter,
+) -> str:
+    system = adapter.system_text(payload)[:4096]
+    tool_names = "|".join(adapter.tool_names(payload))
+    first_user = adapter.first_user_text(payload)[:2048]
+    system_hash = blake2b((system + tool_names).encode("utf-8"), digest_size=8).hexdigest()
+    user_hash = blake2b(first_user.encode("utf-8"), digest_size=8).hexdigest()
+    material = "|".join((provider.value, key_fingerprint(headers), system_hash, user_hash))
+    return sha256(material.encode("utf-8")).hexdigest()[:16]
+
+
+def project_from_text(text: str) -> str | None:
+    for pattern in _WORKDIR_PATTERNS:
+        match = pattern.search(text)
+        if match:
+            value = match.group(1).strip().rstrip("/\\")
+            if value:
+                return value.replace("\\", "/").split("/")[-1]
+    return None
+
+
+def project_from_payload(payload: dict[str, Any], adapter: ProviderAdapter) -> str | None:
+    return project_from_text(f"{adapter.system_text(payload)}\n{adapter.first_user_text(payload)}")
+
+
+__all__ = [
+    "derive_session_id",
+    "key_fingerprint",
+    "project_from_payload",
+    "project_from_text",
+]

ctxoptimizer/analysis/state.py

@@ -0,0 +1,239 @@
+"""Per-session analysis state: drift + waste findings (P2 wiring)."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from hashlib import sha256
+
+from ctxoptimizer.analysis.baseline import CacheSim, simulate
+from ctxoptimizer.analysis.drift import DriftEvent, detect_drift
+from ctxoptimizer.analysis.markers import MarkerQuality, marker_quality
+from ctxoptimizer.analysis.segments import Segment
+from ctxoptimizer.analysis.tokens import estimate_tokens
+from ctxoptimizer.analysis.waste import (
+    EditObservation,
+    HashObservation,
+    churn_edits,
+    identical_outputs,
+    recurring_drift,
+    redundant_rereads,
+    runaway_session,
+    schema_bloat,
+)
+from ctxoptimizer.models import WasteFinding
+from ctxoptimizer.transforms.ansi import clean as ansi_clean
+from ctxoptimizer.transforms.progress import clean as progress_clean
+
+
+@dataclass
+class SessionState:
+    hashes: dict[bytes, HashObservation] = field(default_factory=dict)
+    observations: list[HashObservation] = field(default_factory=list)
+    segments: list[Segment] | None = None
+    last_ts: float | None = None
+    turns: int = 0
+    drift_events: list[DriftEvent] = field(default_factory=list)
+    used_tools: set[str] = field(default_factory=set)
+    last_edits: dict[str, EditObservation] = field(default_factory=dict)
+    schema_reported: set[str] = field(default_factory=set)
+
+
+@dataclass(frozen=True, slots=True)
+class AnalysisResult:
+    drift: DriftEvent | None
+    findings: list[WasteFinding]
+    marker_quality: MarkerQuality
+    baseline: CacheSim
+
+
+class AnalysisState:
+    """Bounded in-memory analysis for the dashboard and CLI."""
+
+    def __init__(self, max_sessions: int = 256, max_findings: int = 500) -> None:
+        self.max_sessions = max_sessions
+        self.max_findings = max_findings
+        self._sessions: dict[str, SessionState] = {}
+        self._findings: list[WasteFinding] = []
+
+    def observe(
+        self,
+        *,
+        session_id: str,
+        project: str | None,
+        ts: float,
+        segments: list[Segment],
+        observations: list[HashObservation],
+        model: str,
+        config_hash: str,
+        ttl_s: float = 300.0,
+        tool_schemas: list[tuple[str, int]] | None = None,
+        used_tools: list[str] | None = None,
+        edits: list[EditObservation] | None = None,
+        churn_enabled: bool = False,
+        schema_bloat_enabled: bool = True,
+        schema_min_requests: int = 10,
+        cache_policy: str = "none",
+    ) -> AnalysisResult:
+        state = self._sessions.get(session_id)
+        if state is None:
+            if len(self._sessions) >= self.max_sessions:
+                self._sessions.pop(next(iter(self._sessions)))
+            state = SessionState()
+            self._sessions[session_id] = state
+
+        drift = detect_drift(
+            state.segments,
+            segments,
+            previous_ts=state.last_ts,
+            current_ts=ts,
+            ttl_s=ttl_s,
+            previous_params=model,
+            current_params=model,
+            previous_config_hash=config_hash,
+            current_config_hash=config_hash,
+            previous_model=model,
+            current_model=model,
+        )
+        baseline = simulate(
+            cache_policy,
+            state.segments,
+            state.last_ts,
+            segments,
+            ts,
+            ttl_s=ttl_s,
+        )
+        if drift is not None:
+            state.drift_events.append(drift)
+
+        findings: list[WasteFinding] = []
+        findings.extend(
+            redundant_rereads(
+                observations, state.hashes, session_id=session_id, project=project, ts=ts
+            )
+        )
+        findings.extend(
+            identical_outputs(
+                [*state.observations, *observations],
+                session_id=session_id,
+                project=project,
+                ts=ts,
+            )
+        )
+        runaway = runaway_session(
+            state.last_ts,
+            ts,
+            state.turns,
+            session_id=session_id,
+            project=project,
+            tokens=sum(item.tokens for item in observations),
+        )
+        if runaway is not None:
+            findings.append(runaway)
+        if drift is not None:
+            findings.extend(
+                recurring_drift(state.drift_events, session_id=session_id, project=project, ts=ts)
+            )
+        if used_tools:
+            state.used_tools.update(used_tools)
+        if schema_bloat_enabled and tool_schemas:
+            request_count = state.turns + 1
+            for name, tokens in tool_schemas:
+                if name in state.used_tools or name in state.schema_reported:
+                    continue
+                bloat = schema_bloat(
+                    name,
+                    tokens,
+                    request_count,
+                    session_id=session_id,
+                    project=project,
+                    ts=ts,
+                    min_requests=schema_min_requests,
+                )
+                if bloat is not None:
+                    findings.append(bloat)
+                    state.schema_reported.add(name)
+        if churn_enabled and edits:
+            findings.extend(
+                churn_edits(
+                    edits,
+                    state.last_edits,
+                    session_id=session_id,
+                    project=project,
+                    ts=ts,
+                )
+            )
+
+        for observation in observations:
+            state.hashes[observation.hash] = observation
+        state.observations.extend(observations)
+        state.observations = state.observations[-2000:]
+        state.segments = segments
+        state.last_ts = ts
+        state.turns += 1
+        self._findings.extend(findings)
+        self._findings = self._dedupe(self._findings)[-self.max_findings :]
+        return AnalysisResult(
+            drift=drift,
+            findings=findings,
+            marker_quality=marker_quality(segments),
+            baseline=baseline,
+        )
+
+    def findings(self) -> list[WasteFinding]:
+        return list(self._findings)
+
+    @staticmethod
+    def _dedupe(findings: list[WasteFinding]) -> list[WasteFinding]:
+        by_key: dict[tuple[str, bytes], WasteFinding] = {}
+        for finding in findings:
+            key = (finding.detector, finding.key_hash)
+            existing = by_key.get(key)
+            if existing is None or existing.status not in {"new", "ack"}:
+                by_key[key] = finding
+            else:
+                existing.occurrences += finding.occurrences
+                existing.last_seen_ts = max(existing.last_seen_ts, finding.last_seen_ts)
+                existing.est_tokens_wasted = max(
+                    existing.est_tokens_wasted or 0,
+                    finding.est_tokens_wasted or 0,
+                )
+                existing.evidence = finding.evidence
+        return list(by_key.values())
+
+    def set_status(self, finding_id: str, status: str) -> bool:
+        allowed = {"new", "ack", "fixed", "skipped"}
+        if status not in allowed:
+            return False
+        for finding in self._findings:
+            if finding.finding_id == finding_id:
+                finding.status = status  # type: ignore[assignment]
+                return True
+        return False
+
+    def clear(self) -> None:
+        self._sessions.clear()
+        self._findings.clear()
+
+
+def observations_from_texts(
+    texts: list[tuple[str | None, str | None, str]],
+) -> list[HashObservation]:
+    observations: list[HashObservation] = []
+    for _tool_use_id, tool_name, text in texts:
+        sigma = progress_clean(ansi_clean(text))
+        observations.append(
+            HashObservation(
+                hash=sha256(sigma.encode("utf-8")).digest(),
+                tokens=estimate_tokens(text),
+                tool_name=tool_name,
+            )
+        )
+    return observations
+
+
+__all__ = [
+    "AnalysisResult",
+    "AnalysisState",
+    "SessionState",
+    "observations_from_texts",
+]

ctxoptimizer/analysis/tokens.py

@@ -0,0 +1,62 @@
+"""Token estimation and calibration (SPEC section 12.0.2)."""
+
+from __future__ import annotations
+
+import importlib
+import importlib.util
+import math
+from functools import lru_cache
+from typing import Any
+
+
+def _load_tiktoken() -> Any | None:
+    if importlib.util.find_spec("tiktoken") is None:
+        return None
+    try:
+        return importlib.import_module("tiktoken")
+    except Exception:
+        return None
+
+
+_tiktoken = _load_tiktoken()
+
+
+@lru_cache(maxsize=2)
+def _encoding(name: str) -> Any:
+    if _tiktoken is None:
+        raise RuntimeError("tiktoken is not available")
+    return _tiktoken.get_encoding(name)
+
+
+def estimate_tokens(text: str, family: str = "generic") -> int:
+    """Estimate tokens with tiktoken when available, else a stable heuristic."""
+    if not text:
+        return 0
+    if _tiktoken is not None:
+        encoding_name = "o200k_base" if family == "openai" else "cl100k_base"
+        try:
+            return max(1, len(_encoding(encoding_name).encode(text)))
+        except Exception:
+            return max(1, math.ceil(len(text) / 3.5))
+    return max(1, math.ceil(len(text) / 3.5))
+
+
+class Calibrator:
+    """Exponential moving average of actual/estimated tokens per family."""
+
+    def __init__(self, alpha: float = 0.1) -> None:
+        self.alpha = alpha
+        self.ratios: dict[str, float] = {}
+
+    def update(self, family: str, actual: int, estimated: int) -> None:
+        if estimated <= 0 or actual <= 0:
+            return
+        ratio = actual / estimated
+        previous = self.ratios.get(family, 1.0)
+        self.ratios[family] = (1 - self.alpha) * previous + self.alpha * ratio
+
+    def apply(self, family: str, estimate: int) -> int:
+        return max(0, round(estimate * self.ratios.get(family, 1.0)))
+
+
+__all__ = ["Calibrator", "estimate_tokens"]