ctxoptimizer 0.4.1__py3-none-any.whl

ctxoptimizer/transforms/backref.py

@@ -0,0 +1,74 @@
+"""Duplicate tool-result back-references within a request (SPEC 12.6)."""
+
+from __future__ import annotations
+
+import time
+from hashlib import sha256
+from typing import Any
+
+from ctxoptimizer.analysis.tokens import estimate_tokens
+from ctxoptimizer.config import Config
+from ctxoptimizer.models import RequestContext, TransformReport
+from ctxoptimizer.providers.base import ProviderAdapter
+from ctxoptimizer.transforms.ansi import clean as ansi_clean
+from ctxoptimizer.transforms.eligibility import is_never_touch
+from ctxoptimizer.transforms.progress import clean as progress_clean
+
+
+class DuplicateBackref:
+    id = "duplicate_backref"
+
+    def applies(
+        self, ctx: RequestContext, payload: dict[str, Any], adapter: ProviderAdapter
+    ) -> bool:
+        return ctx.config.transforms.duplicate_backref.enabled
+
+    def apply(
+        self,
+        ctx: RequestContext,
+        payload: dict[str, Any],
+        adapter: ProviderAdapter,
+        config: Config,
+    ) -> TransformReport:
+        started = time.perf_counter()
+        settings = config.transforms.duplicate_backref
+        seen: dict[bytes, str] = {}
+        items = 0
+        bytes_before = 0
+        bytes_after = 0
+        tokens_before = 0
+        tokens_after = 0
+        for ref in adapter.iter_tool_results(payload):
+            if is_never_touch(ref, config) and not settings.include_never_touch:
+                continue
+            text = ref.get_text()
+            if text is None or len(text.encode("utf-8")) < settings.min_bytes:
+                continue
+            sigma = progress_clean(ansi_clean(text))
+            digest = sha256(sigma.encode("utf-8")).digest()
+            if digest not in seen:
+                seen[digest] = ref.tool_use_id or "earlier"
+                continue
+            stub = f"[ctxoptimizer: output identical to earlier tool result {seen[digest]}]"
+            if len(stub.encode("utf-8")) >= len(text.encode("utf-8")):
+                continue
+            items += 1
+            bytes_before += len(text.encode("utf-8"))
+            bytes_after += len(stub.encode("utf-8"))
+            tokens_before += estimate_tokens(text)
+            tokens_after += estimate_tokens(stub)
+            ref.set_text(stub)
+        return TransformReport(
+            transform_id=self.id,
+            ran=True,
+            changed=items > 0,
+            items_touched=items,
+            bytes_before=bytes_before,
+            bytes_after=bytes_after,
+            est_tokens_before=tokens_before,
+            est_tokens_after=tokens_after,
+            duration_ms=(time.perf_counter() - started) * 1000,
+        )
+
+
+__all__ = ["DuplicateBackref"]

ctxoptimizer/transforms/base.py

@@ -0,0 +1,93 @@
+"""Transform protocol and the pure-text transform driver (SPEC section 12.0.1)."""
+
+from __future__ import annotations
+
+import time
+from collections.abc import Callable
+from typing import Any, Protocol
+
+from ctxoptimizer.analysis.tokens import estimate_tokens
+from ctxoptimizer.config import Config
+from ctxoptimizer.models import RequestContext, ToolResultRef, TransformReport
+from ctxoptimizer.providers.base import ProviderAdapter
+
+
+class Transform(Protocol):
+    id: str
+
+    def applies(
+        self, ctx: RequestContext, payload: dict[str, Any], adapter: ProviderAdapter
+    ) -> bool: ...
+
+    def apply(
+        self,
+        ctx: RequestContext,
+        payload: dict[str, Any],
+        adapter: ProviderAdapter,
+        config: Config,
+    ) -> TransformReport: ...
+
+
+class TextTransform:
+    """Run a pure ``str -> str`` function over every eligible tool result."""
+
+    def __init__(
+        self,
+        transform_id: str,
+        clean: Callable[[str], str],
+        *,
+        enabled: bool = True,
+        eligible: Callable[[ToolResultRef], bool] | None = None,
+    ) -> None:
+        self.id = transform_id
+        self._clean = clean
+        self._enabled = enabled
+        self._eligible = eligible or (lambda ref: True)
+
+    def applies(
+        self, ctx: RequestContext, payload: dict[str, Any], adapter: ProviderAdapter
+    ) -> bool:
+        return self._enabled
+
+    def apply(
+        self,
+        ctx: RequestContext,
+        payload: dict[str, Any],
+        adapter: ProviderAdapter,
+        config: Config,
+    ) -> TransformReport:
+        started = time.perf_counter()
+        items = 0
+        bytes_before = 0
+        bytes_after = 0
+        tokens_before = 0
+        tokens_after = 0
+        for ref in adapter.iter_tool_results(payload):
+            if not self._eligible(ref):
+                continue
+            text = ref.get_text()
+            if text is None:
+                continue
+            new_text = self._clean(text)
+            if new_text == text:
+                continue
+            items += 1
+            bytes_before += len(text.encode("utf-8"))
+            bytes_after += len(new_text.encode("utf-8"))
+            tokens_before += estimate_tokens(text)
+            tokens_after += estimate_tokens(new_text)
+            ref.set_text(new_text)
+        return TransformReport(
+            transform_id=self.id,
+            ran=True,
+            changed=items > 0,
+            items_touched=items,
+            bytes_before=bytes_before,
+            bytes_after=bytes_after,
+            est_tokens_before=tokens_before,
+            est_tokens_after=tokens_after,
+            duration_ms=(time.perf_counter() - started) * 1000,
+        )
+
+
+__all__ = ["TextTransform", "Transform"]

ctxoptimizer/transforms/cache_serve.py

@@ -0,0 +1,146 @@
+"""Byte-true cross-request substitution (SPEC section 12.12)."""
+
+from __future__ import annotations
+
+import time
+from collections import OrderedDict
+from dataclasses import dataclass
+from hashlib import sha256
+from typing import Any
+
+from ctxoptimizer.analysis.tokens import estimate_tokens
+from ctxoptimizer.config import Config
+from ctxoptimizer.models import RequestContext, TransformReport
+from ctxoptimizer.providers.base import ProviderAdapter
+from ctxoptimizer.transforms.ansi import clean as ansi_clean
+from ctxoptimizer.transforms.progress import clean as progress_clean
+
+
+@dataclass(slots=True)
+class CacheEntry:
+    hash: bytes
+    size: int
+    first_turn: int
+    ref: str
+
+
+class CacheServeState:
+    """Bounded per-session content map (INV-17 says no silent loss)."""
+
+    def __init__(self, max_sessions: int = 256, max_entries: int = 512) -> None:
+        self.max_sessions = max_sessions
+        self.max_entries = max_entries
+        self._sessions: OrderedDict[str, OrderedDict[bytes, CacheEntry]] = OrderedDict()
+
+    def session(self, session_id: str) -> OrderedDict[bytes, CacheEntry]:
+        entries = self._sessions.get(session_id)
+        if entries is None:
+            if len(self._sessions) >= self.max_sessions:
+                self._sessions.popitem(last=False)
+            entries = OrderedDict()
+            self._sessions[session_id] = entries
+        else:
+            self._sessions.move_to_end(session_id)
+        return entries
+
+    def put(self, entries: OrderedDict[bytes, CacheEntry], entry: CacheEntry) -> None:
+        entries[entry.hash] = entry
+        entries.move_to_end(entry.hash)
+        while len(entries) > self.max_entries:
+            entries.popitem(last=False)
+
+    def entries(self, session_id: str) -> dict[bytes, CacheEntry]:
+        return dict(self.session(session_id))
+
+
+class CacheServe:
+    id = "cache_serve"
+
+    def __init__(self, state: CacheServeState) -> None:
+        self.state = state
+
+    def applies(
+        self, ctx: RequestContext, payload: dict[str, Any], adapter: ProviderAdapter
+    ) -> bool:
+        return (
+            ctx.config.transforms.cache_serve.enabled
+            and ctx.config.telemetry.capture_payloads != "off"
+        )
+
+    def apply(
+        self,
+        ctx: RequestContext,
+        payload: dict[str, Any],
+        adapter: ProviderAdapter,
+        config: Config,
+    ) -> TransformReport:
+        started = time.perf_counter()
+        settings = config.transforms.cache_serve
+        turns = _assistant_turns(payload)
+        boundary = max(
+            0,
+            ((turns - settings.keep_recent_turns) // settings.batch_turns) * settings.batch_turns,
+        )
+        entries = self.state.session(ctx.session_id)
+        seen: set[bytes] = set()
+        stubs = 0
+        tokens_before = 0
+        tokens_after = 0
+        for ref in adapter.iter_tool_results(payload):
+            text = ref.get_text()
+            if text is None or len(text.encode("utf-8")) < settings.min_bytes:
+                continue
+            sigma = progress_clean(ansi_clean(text))
+            digest = sha256(sigma.encode("utf-8")).digest()
+            if digest in seen:
+                continue
+            seen.add(digest)
+            entry = entries.get(digest)
+            if (
+                entry is not None
+                and entry.first_turn < boundary
+                and stubs < settings.max_stubs_per_request
+            ):
+                stub = (
+                    f"[ctxoptimizer: content identical to turn {entry.first_turn} "
+                    f"({entry.size / 1024:.1f} KB, sha256 {entry.ref}...); unchanged. "
+                    f"reread ref={entry.ref} | ctxoptimizer_expand({entry.ref}) retrieves it]"
+                )
+                if len(stub.encode("utf-8")) < len(text.encode("utf-8")):
+                    tokens_before += estimate_tokens(text)
+                    tokens_after += estimate_tokens(stub)
+                    ref.set_text(stub)
+                    stubs += 1
+                continue
+            if entry is None:
+                self.state.put(
+                    entries,
+                    CacheEntry(
+                        hash=digest,
+                        size=len(text.encode("utf-8")),
+                        first_turn=turns,
+                        ref=sha256(text.encode("utf-8")).hexdigest()[:8],
+                    ),
+                )
+        return TransformReport(
+            transform_id=self.id,
+            ran=True,
+            changed=stubs > 0,
+            items_touched=stubs,
+            est_tokens_before=tokens_before,
+            est_tokens_after=tokens_after,
+            duration_ms=(time.perf_counter() - started) * 1000,
+            notes={"boundary": boundary, "turns": turns, "stubs": stubs},
+        )
+
+
+def _assistant_turns(payload: dict[str, Any]) -> int:
+    items = payload.get("messages")
+    if not isinstance(items, list):
+        items = payload.get("input")
+    if not isinstance(items, list):
+        return 0
+    return sum(1 for item in items if isinstance(item, dict) and item.get("role") == "assistant")
+
+
+__all__ = ["CacheEntry", "CacheServe", "CacheServeState"]

ctxoptimizer/transforms/dedupe_lines.py

@@ -0,0 +1,69 @@
+"""Exact and near-duplicate line collapsing (SPEC section 12.3)."""
+
+from __future__ import annotations
+
+import re
+
+SIGNAL = re.compile(
+    r"error|fail(?:ed|ure)?|exception|fatal|warning|traceback|panic",
+    re.IGNORECASE,
+)
+_TS = re.compile(r"\b\d{4}-\d{2}-\d{2}T\S+|\b\d{2}:\d{2}:\d{2}\b")
+_HEX = re.compile(r"\b[0-9a-f]{8,}\b", re.IGNORECASE)
+_DIGITS = re.compile(r"\d+")
+
+
+def clean(text: str, min_repeat: int = 3) -> str:
+    lines = text.split("\n")
+    exact: list[str] = []
+    index = 0
+    while index < len(lines):
+        end = index
+        while end + 1 < len(lines) and lines[end + 1].rstrip() == lines[index].rstrip():
+            end += 1
+        run = end - index + 1
+        if run >= min_repeat:
+            exact.append(lines[index])
+            exact.append(f"[ctxoptimizer: line repeated {run - 1} more times]")
+        else:
+            exact.extend(lines[index : end + 1])
+        index = end + 1
+    return "\n".join(_collapse_near(exact, min_repeat))
+
+
+def _collapse_near(lines: list[str], min_repeat: int) -> list[str]:
+    result: list[str] = []
+    index = 0
+    while index < len(lines):
+        line = lines[index]
+        if line.startswith("[ctxoptimizer:") or SIGNAL.search(line):
+            result.append(line)
+            index += 1
+            continue
+        key = _normalise(line)
+        end = index
+        while (
+            end + 1 < len(lines)
+            and not lines[end + 1].startswith("[ctxoptimizer:")
+            and not SIGNAL.search(lines[end + 1])
+            and _normalise(lines[end + 1]) == key
+        ):
+            end += 1
+        run = end - index + 1
+        if run >= 2 * min_repeat:
+            result.append(lines[index])
+            result.append(f"[ctxoptimizer: {run - 2} similar lines omitted]")
+            result.append(lines[end])
+        else:
+            result.extend(lines[index : end + 1])
+        index = end + 1
+    return result
+
+
+def _normalise(line: str) -> str:
+    line = _TS.sub("<ts>", line)
+    line = _HEX.sub("<id>", line)
+    return _DIGITS.sub("#", line)
+
+
+__all__ = ["clean"]

ctxoptimizer/transforms/eligibility.py

@@ -0,0 +1,24 @@
+"""Tool eligibility from the ``[tools]`` globs (SPEC section 12.0.4)."""
+
+from __future__ import annotations
+
+from fnmatch import fnmatchcase
+
+from ctxoptimizer.config import Config
+from ctxoptimizer.models import ToolResultRef
+
+
+def matches(name: str, patterns: list[str]) -> bool:
+    lowered = name.lower()
+    return any(fnmatchcase(lowered, pattern.lower()) for pattern in patterns)
+
+
+def is_never_touch(ref: ToolResultRef, config: Config) -> bool:
+    return bool(ref.tool_name and matches(ref.tool_name, config.tools.never_touch))
+
+
+def is_compactable(ref: ToolResultRef, config: Config) -> bool:
+    return bool(ref.tool_name and matches(ref.tool_name, config.tools.compactable))
+
+
+__all__ = ["is_compactable", "is_never_touch", "matches"]

ctxoptimizer/transforms/openai_hints.py

@@ -0,0 +1,84 @@
+"""OpenAI prompt_cache_key hints (SPEC section 12.10)."""
+
+from __future__ import annotations
+
+import time
+from hashlib import sha256
+from typing import Any
+from urllib.parse import urlsplit
+
+from ctxoptimizer.config import Config
+from ctxoptimizer.models import Endpoint, Provider, RequestContext, TransformReport
+from ctxoptimizer.providers.base import ProviderAdapter
+
+
+class OpenAIHints:
+    id = "openai_hints"
+
+    def applies(
+        self, ctx: RequestContext, payload: dict[str, Any], adapter: ProviderAdapter
+    ) -> bool:
+        settings = ctx.config.transforms.openai_hints
+        if not settings.enabled:
+            return False
+        if ctx.provider is not Provider.OPENAI:
+            return False
+        if ctx.endpoint not in {Endpoint.CHAT, Endpoint.RESPONSES}:
+            return False
+        entry = ctx.config.upstreams.get(ctx.upstream_name)
+        if entry is None:
+            return False
+        url = entry if isinstance(entry, str) else entry.url
+        if (urlsplit(url).hostname or "").lower() != "api.openai.com":
+            return False
+        if settings.send_prompt_cache_key and "prompt_cache_key" not in payload:
+            return True
+        if (
+            settings.inject_stream_usage
+            and ctx.endpoint is Endpoint.CHAT
+            and payload.get("stream") is True
+        ):
+            options = payload.get("stream_options")
+            return not isinstance(options, dict) or options.get("include_usage") is not True
+        return False
+
+    def apply(
+        self,
+        ctx: RequestContext,
+        payload: dict[str, Any],
+        adapter: ProviderAdapter,
+        config: Config,
+    ) -> TransformReport:
+        started = time.perf_counter()
+        settings = config.transforms.openai_hints
+        changed = False
+        notes: dict[str, object] = {}
+        if settings.send_prompt_cache_key and "prompt_cache_key" not in payload:
+            key = "ctxp-" + sha256(ctx.session_id.encode("utf-8")).hexdigest()[:24]
+            payload["prompt_cache_key"] = key
+            notes["key"] = key
+            changed = True
+        if (
+            settings.inject_stream_usage
+            and ctx.endpoint is Endpoint.CHAT
+            and payload.get("stream") is True
+        ):
+            options = payload.get("stream_options")
+            if not isinstance(options, dict):
+                options = {}
+                payload["stream_options"] = options
+            if options.get("include_usage") is not True:
+                options["include_usage"] = True
+                notes["inject_stream_usage"] = True
+                changed = True
+        return TransformReport(
+            transform_id=self.id,
+            ran=True,
+            changed=changed,
+            items_touched=len(notes),
+            duration_ms=(time.perf_counter() - started) * 1000,
+            notes=notes,
+        )
+
+
+__all__ = ["OpenAIHints"]

ctxoptimizer/transforms/progress.py

@@ -0,0 +1,52 @@
+"""Progress-bar and carriage-return collapsing (SPEC section 12.2)."""
+
+from __future__ import annotations
+
+import re
+
+PROGRESS = re.compile(
+    r"(?:[#=>█▉▊▋▌▍▎▏.\- ]{8,}\s*\d{1,3}%"
+    r"|\b\d+(?:\.\d+)?\s?(?:kB|MB|GB|KiB|MiB)/s\b"
+    r"|^(?:Downloading|Fetching|Receiving objects|Resolving deltas|"
+    r"Compressing objects|Unpacking|Counting objects|Collecting|Installing)\b"
+    r".*?(?:\d{1,3}%|\d+\s?(?:kB|MB|GB|KiB|MiB)))",
+    re.IGNORECASE,
+)
+SIGNAL = re.compile(r"error|fail|fatal|warning", re.IGNORECASE)
+
+
+def clean(text: str) -> str:
+    lines = [_last_carriage_segment(line) for line in text.split("\n")]
+    result: list[str] = []
+    index = 0
+    while index < len(lines):
+        line = lines[index]
+        if not _is_progress(line):
+            result.append(line)
+            index += 1
+            continue
+        end = index
+        while end + 1 < len(lines) and _is_progress(lines[end + 1]):
+            end += 1
+        run = end - index + 1
+        if run >= 3:
+            result.append(f"[ctxoptimizer: {run} progress updates collapsed]")
+            result.append(lines[end])
+        else:
+            result.extend(lines[index : end + 1])
+        index = end + 1
+    return "\n".join(result)
+
+
+def _last_carriage_segment(line: str) -> str:
+    if "\r" not in line:
+        return line
+    segments = [part for part in line.split("\r") if part]
+    return segments[-1] if segments else ""
+
+
+def _is_progress(line: str) -> bool:
+    return bool(PROGRESS.search(line)) and not SIGNAL.search(line)
+
+
+__all__ = ["clean"]

ctxoptimizer/transforms/stale_result_elision.py

@@ -0,0 +1,109 @@
+"""Opt-in stale tool-result elision (SPEC section 12.8, P6-4)."""
+
+from __future__ import annotations
+
+import time
+from typing import Any
+
+from ctxoptimizer.config import Config
+from ctxoptimizer.models import RequestContext, TransformReport
+from ctxoptimizer.providers.base import ProviderAdapter
+
+
+class StaleResultElision:
+    id = "stale_result_elision"
+
+    def applies(
+        self, ctx: RequestContext, payload: dict[str, Any], adapter: ProviderAdapter
+    ) -> bool:
+        return ctx.config.transforms.stale_result_elision.enabled
+
+    def apply(
+        self,
+        ctx: RequestContext,
+        payload: dict[str, Any],
+        adapter: ProviderAdapter,
+        config: Config,
+    ) -> TransformReport:
+        started = time.perf_counter()
+        settings = config.transforms.stale_result_elision
+        turns = assistant_turns(payload)
+        boundary = max(
+            0,
+            ((turns - settings.keep_recent_turns) // settings.batch_turns) * settings.batch_turns,
+        )
+        turn_by_index = _turn_by_index(payload)
+        touched = 0
+        before = 0
+        after = 0
+        for ref in adapter.iter_tool_results(payload):
+            text = ref.get_text()
+            if text is None or text.startswith("[ctxoptimizer:"):
+                continue
+            size = len(text.encode("utf-8"))
+            if size < settings.min_bytes:
+                continue
+            turn = turn_by_index.get(ref.message_index, turns)
+            if turn >= boundary:
+                continue
+            stub = (
+                f"[ctxoptimizer: tool result elided ({size / 1024:.1f} KB); "
+                "re-run the tool if needed]"
+            )
+            if len(stub.encode("utf-8")) >= size:
+                continue
+            before += size
+            after += len(stub.encode("utf-8"))
+            ref.set_text(stub)
+            touched += 1
+        return TransformReport(
+            transform_id=self.id,
+            ran=True,
+            changed=touched > 0,
+            items_touched=touched,
+            bytes_before=before,
+            bytes_after=after,
+            duration_ms=(time.perf_counter() - started) * 1000,
+            notes={"boundary": boundary, "turns": turns, "elided": touched},
+        )
+
+
+def assistant_turns(payload: dict[str, Any]) -> int:
+    return sum(1 for item in _items(payload) if _is_assistant(item))
+
+
+def _turn_by_index(payload: dict[str, Any]) -> dict[int, int]:
+    turns = 0
+    result: dict[int, int] = {}
+    for index, item in enumerate(_items(payload)):
+        if _is_assistant(item):
+            turns += 1
+        result[index] = turns
+    return result
+
+
+def _items(payload: dict[str, Any]) -> list[Any]:
+    value = payload.get("messages")
+    if isinstance(value, list):
+        return value
+    value = payload.get("contents")
+    if isinstance(value, list):
+        return value
+    value = payload.get("input")
+    if isinstance(value, str):
+        return [{"type": "message", "role": "user", "content": value}]
+    return value if isinstance(value, list) else []
+
+
+def _is_assistant(item: Any) -> bool:
+    if not isinstance(item, dict):
+        return False
+    if item.get("type") == "function_call":
+        return True
+    role = item.get("role")
+    if role is None and item.get("type") == "message":
+        role = item.get("role")
+    return role in {"assistant", "model"}
+
+
+__all__ = ["StaleResultElision", "assistant_turns"]