token-runtime 0.1.0a2__py3-none-any.whl

token_runtime/metrics.py

@@ -0,0 +1,79 @@
+from __future__ import annotations
+
+import json
+import os
+from pathlib import Path
+import sqlite3
+import time
+from typing import Any, Mapping
+
+
+_ALLOWED = {
+    "decision", "adapter", "provider", "model",
+    "before_input_tokens", "after_input_tokens",
+    "provider_input_tokens", "provider_output_tokens", "cached_tokens",
+    "latency_ms", "reducer_ids", "reason_codes",
+}
+
+
+class MetricsStore:
+    def __init__(self, path: str | Path):
+        self.path = str(path)
+        Path(self.path).parent.mkdir(parents=True, exist_ok=True)
+        with sqlite3.connect(self.path) as conn:
+            conn.execute(
+                "CREATE TABLE IF NOT EXISTS events ("
+                "ts REAL NOT NULL, decision TEXT NOT NULL, adapter TEXT, provider TEXT, model TEXT, "
+                "before_input_tokens INTEGER, after_input_tokens INTEGER, provider_input_tokens INTEGER, "
+                "provider_output_tokens INTEGER, cached_tokens INTEGER, latency_ms REAL, "
+                "reducer_ids TEXT NOT NULL, reason_codes TEXT NOT NULL)"
+            )
+        if os.name == "posix":
+            os.chmod(self.path, 0o600)
+
+    def record(self, event: Mapping[str, Any]) -> None:
+        unknown = set(event) - _ALLOWED
+        if unknown:
+            raise ValueError(f"unsupported telemetry fields: {sorted(unknown)}")
+        decision = event.get("decision")
+        if decision not in {"optimize", "bypass"}:
+            raise ValueError("decision must be optimize or bypass")
+
+        values = (
+            time.time(), decision, event.get("adapter"), event.get("provider"), event.get("model"),
+            event.get("before_input_tokens"), event.get("after_input_tokens"),
+            event.get("provider_input_tokens"), event.get("provider_output_tokens"),
+            event.get("cached_tokens"), event.get("latency_ms"),
+            json.dumps(tuple(event.get("reducer_ids", ()))),
+            json.dumps(tuple(event.get("reason_codes", ()))),
+        )
+        with sqlite3.connect(self.path) as conn:
+            conn.execute(
+                "INSERT INTO events VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)",
+                values,
+            )
+
+    def summary(self) -> dict[str, int | float]:
+        with sqlite3.connect(self.path) as conn:
+            row = conn.execute(
+                "SELECT COUNT(*), "
+                "SUM(CASE WHEN decision='optimize' THEN 1 ELSE 0 END), "
+                "COALESCE(SUM(before_input_tokens),0), COALESCE(SUM(after_input_tokens),0), "
+                "COALESCE(SUM(provider_input_tokens),0), COALESCE(SUM(provider_output_tokens),0), "
+                "COALESCE(SUM(cached_tokens),0) FROM events"
+            ).fetchone()
+        requests, optimized, before, after, provider_in, provider_out, cached = row
+        saved = before - after
+        pct = round(saved * 100 / before, 1) if before else 0.0
+        return {
+            "requests": requests,
+            "optimized": optimized or 0,
+            "bypassed": requests - (optimized or 0),
+            "estimated_input_before": before,
+            "estimated_input_after": after,
+            "estimated_input_saved": saved,
+            "estimated_input_saved_pct": pct,
+            "provider_input_tokens": provider_in,
+            "provider_output_tokens": provider_out,
+            "cached_tokens": cached,
+        }

token_runtime/model.py

@@ -0,0 +1,39 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Any, Mapping
+
+
+class OptimizationDecision(str, Enum):
+    BYPASS = "bypass"
+    OPTIMIZE = "optimize"
+
+
+@dataclass(frozen=True, slots=True)
+class ContextBlock:
+    id: str
+    kind: str
+    text: str
+    role: str | None = None
+    turn_index: int = 0
+    metadata: Mapping[str, Any] = field(default_factory=dict)
+
+
+@dataclass(frozen=True, slots=True)
+class RequestEnvelope:
+    blocks: tuple[ContextBlock, ...]
+    opaque: Mapping[str, Any] = field(default_factory=dict)
+    adapter: str = "normalized"
+    wire_safe: bool = True
+
+
+@dataclass(frozen=True, slots=True)
+class OptimizationResult:
+    decision: OptimizationDecision
+    envelope: RequestEnvelope
+    reasons: tuple[str, ...]
+    before_estimated_tokens: int
+    after_estimated_tokens: int
+    changed_block_ids: tuple[str, ...] = ()
+    recovery_refs: tuple[str, ...] = ()

token_runtime/openai_certification.py

@@ -0,0 +1,310 @@
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+
+from .adapters import ChatCompletionsAdapter, ResponsesAdapter
+from .capabilities import (
+    CapabilityDetector,
+    CapabilityKey,
+    CapabilityProfile,
+    CapabilityRegistry,
+)
+from .compatibility import (
+    CompatibilityMatrix,
+    CompatibilityRecord,
+    CompatibilityRegistry,
+    CompatibilityState,
+)
+from .conformance import ConformanceResult, require_conformance, run_conformance
+
+
+
+CODEX_RESPONSES_KEY = CapabilityKey(
+    "codex",
+    "responses",
+    "openai-compatible",
+    client_version="0.153.4",
+)
+OPENAI_RESPONSES_KEY = CapabilityKey(
+    "generic-openai",
+    "responses",
+    "openai-compatible",
+)
+OPENAI_CHAT_COMPLETIONS_KEY = CapabilityKey(
+    "generic-openai",
+    "chat_completions",
+    "openai-compatible",
+)
+
+
+@dataclass(frozen=True, slots=True)
+class CertificationEvidence:
+    evidence_id: str
+    version_scope: str
+    scope: str
+    assertion_ids: tuple[str, ...]
+
+    def to_primitive(self) -> dict[str, object]:
+        return {
+            "evidence_id": self.evidence_id,
+            "version_scope": self.version_scope,
+            "scope": self.scope,
+            "assertion_ids": list(self.assertion_ids),
+        }
+
+
+@dataclass(frozen=True, slots=True)
+class OpenAICertificationBundle:
+    profiles: tuple[CapabilityProfile, ...]
+    records: tuple[CompatibilityRecord, ...]
+    evidence: tuple[CertificationEvidence, ...]
+    detector: CapabilityDetector
+    matrix: CompatibilityMatrix
+
+
+def _profile(key: CapabilityKey, evidence_id: str) -> CapabilityProfile:
+    return CapabilityProfile(
+        key=key,
+        tool_calls=True,
+        reasoning_state="opaque-preserved",
+        streaming=True,
+        exact_byte_preservation=True,
+        evidence_id=evidence_id,
+    )
+
+
+def build_openai_certification() -> OpenAICertificationBundle:
+    definitions = (
+        (
+            CODEX_RESPONSES_KEY,
+            CertificationEvidence(
+                evidence_id="token-openai-cert-1:codex-responses-0.153.4",
+                version_scope="codex-cli-0.153.4",
+                scope="codex-responses/request-boundary",
+                assertion_ids=(
+                    "codex-live-smoke-v1",
+                    "responses-exact-roundtrip",
+                    "unsupported-exact-passthrough",
+                ),
+            ),
+        ),
+        (
+            OPENAI_CHAT_COMPLETIONS_KEY,
+            CertificationEvidence(
+                evidence_id="token-openai-cert-1:chat-completions-text-v1",
+                version_scope="token-request-contract-v1",
+                scope="openai-chat-completions/request-boundary-text-v1",
+                assertion_ids=(
+                    "chat-completions-exact-roundtrip",
+                    "chat-completions-unsupported-exact-passthrough",
+                ),
+            ),
+        ),
+        (
+            OPENAI_RESPONSES_KEY,
+            CertificationEvidence(
+                evidence_id="token-openai-cert-1:responses-text-v1",
+                version_scope="token-request-contract-v1",
+                scope="openai-responses/request-boundary-text-v1",
+                assertion_ids=(
+                    "responses-exact-roundtrip",
+                    "responses-unsupported-exact-passthrough",
+                ),
+            ),
+        ),
+    )
+    capabilities = CapabilityRegistry()
+    compatibility = CompatibilityRegistry()
+    evidence: list[CertificationEvidence] = []
+
+    for key, item in definitions:
+        capabilities.register(_profile(key, item.evidence_id))
+        compatibility.register(
+            CompatibilityRecord(
+                key=key,
+                state=CompatibilityState.CERTIFIED,
+                evidence_id=item.evidence_id,
+                reason="request_boundary_certified",
+            )
+        )
+        evidence.append(item)
+
+    return OpenAICertificationBundle(
+        profiles=capabilities.snapshot(),
+        records=compatibility.snapshot(),
+        evidence=tuple(sorted(evidence, key=lambda item: item.evidence_id)),
+        detector=CapabilityDetector(capabilities, compatibility),
+        matrix=compatibility.matrix(),
+    )
+
+
+def _responses_fixture() -> dict[str, object]:
+    return {
+        "model": "opaque-model",
+        "instructions": "Preserve exact constraints.",
+        "input": [
+            {"role": "developer", "content": "stable policy"},
+            {
+                "role": "user",
+                "content": [{"type": "input_text", "text": "current task"}],
+            },
+            {
+                "type": "function_call",
+                "call_id": "c1",
+                "name": "query",
+                "arguments": '{"q":"status"}',
+            },
+            {
+                "type": "function_call_output",
+                "call_id": "c1",
+                "output": "status=green",
+            },
+        ],
+        "tools": [
+            {
+                "type": "function",
+                "name": "query",
+                "description": "fixture",
+                "parameters": {"type": "object"},
+            }
+        ],
+        "reasoning": {"effort": "medium"},
+        "stream": True,
+        "metadata": {"fixture": "c3"},
+        "future_field": {"preserve": True},
+    }
+
+
+def _chat_completions_fixture() -> dict[str, object]:
+    return {
+        "model": "opaque-model",
+        "messages": [
+            {"role": "system", "content": "system"},
+            {"role": "developer", "content": "developer"},
+            {
+                "role": "assistant",
+                "content": "old",
+                "tool_calls": [
+                    {
+                        "id": "c1",
+                        "type": "function",
+                        "function": {"name": "query", "arguments": "{}"},
+                    }
+                ],
+            },
+            {"role": "tool", "tool_call_id": "c1", "content": "result"},
+            {
+                "role": "user",
+                "content": [{"type": "text", "text": "continue"}],
+            },
+        ],
+        "tools": [
+            {
+                "type": "function",
+                "function": {"name": "query", "parameters": {"type": "object"}},
+            }
+        ],
+        "response_format": {"type": "json_object"},
+        "stream": True,
+        "future_field": {"preserve": True},
+    }
+
+
+def _responses_roundtrip() -> bool:
+    payload = _responses_fixture()
+    adapter = ResponsesAdapter()
+    envelope = adapter.parse(payload)
+    return envelope.wire_safe and adapter.serialize(envelope) == payload
+
+
+def _chat_completions_roundtrip() -> bool:
+    payload = _chat_completions_fixture()
+    adapter = ChatCompletionsAdapter()
+    envelope = adapter.parse(payload)
+    return envelope.wire_safe and adapter.serialize(envelope) == payload
+
+
+def _responses_unsupported_passthrough() -> bool:
+    payload = {
+        "model": "opaque-model",
+        "input": [
+            {
+                "role": "user",
+                "content": [{"type": "input_image", "image_url": "fixture://image"}],
+            }
+        ],
+        "future_field": {"preserve": True},
+    }
+    adapter = ResponsesAdapter()
+    envelope = adapter.parse(payload)
+    return not envelope.wire_safe and adapter.serialize(envelope) == payload
+
+
+def _chat_completions_unsupported_passthrough() -> bool:
+    payload = {
+        "model": "opaque-model",
+        "messages": [
+            {
+                "role": "user",
+                "content": [
+                    {
+                        "type": "image_url",
+                        "image_url": {"url": "fixture://image"},
+                    }
+                ],
+            }
+        ],
+        "future_field": {"preserve": True},
+    }
+    adapter = ChatCompletionsAdapter()
+    envelope = adapter.parse(payload)
+    return not envelope.wire_safe and adapter.serialize(envelope) == payload
+
+
+def _certification_matrix_conforms() -> bool:
+    bundle = build_openai_certification()
+    expected = (
+        CODEX_RESPONSES_KEY,
+        OPENAI_CHAT_COMPLETIONS_KEY,
+        OPENAI_RESPONSES_KEY,
+    )
+    return (
+        tuple(profile.key for profile in bundle.profiles) == expected
+        and tuple(record.key for record in bundle.records) == expected
+        and all(record.state is CompatibilityState.CERTIFIED for record in bundle.records)
+    )
+
+
+def _unknown_key_passthrough() -> bool:
+    bundle = build_openai_certification()
+    unknown = bundle.detector.detect(
+        CapabilityKey(
+            "codex",
+            "responses",
+            "openai-compatible",
+            "future-model",
+         )
+    )
+    return (
+        unknown.profile is None
+        and unknown.compatibility.state is CompatibilityState.PASSTHROUGH_ONLY
+        and unknown.compatibility.reason == "unknown_capability"
+    )
+
+
+def openai_conformance_cases() -> Mapping[str, Callable[[], bool]]:
+    return {
+        "certification_matrix": _certification_matrix_conforms,
+        "chat_completions_roundtrip": _chat_completions_roundtrip,
+        "chat_completions_unsupported_passthrough": _chat_completions_unsupported_passthrough,
+        "responses_roundtrip": _responses_roundtrip,
+        "responses_unsupported_passthrough": _responses_unsupported_passthrough,
+        "unknown_key_passthrough": _unknown_key_passthrough,
+    }
+
+
+def run_openai_conformance() -> tuple[ConformanceResult, ...]:
+    results = run_conformance(openai_conformance_cases())
+    require_conformance(results)
+    return results

token_runtime/planner.py

@@ -0,0 +1,96 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+import json
+import re
+
+from .model import OptimizationDecision, RequestEnvelope
+
+
+_DECISION_RE = re.compile(r"(?im)^\s*DECISION\s*:\s*(.+?)\s*$")
+_CONSTRAINT_RE = re.compile(r"\b(must|never|do not|don't|constraint|required)\b", re.I)
+_EXACT_EDIT_MARKERS = ("old_string=", "new_string=", "diff --git", "*** Begin Patch")
+_PROTOCOL_KINDS = {
+    "system", "developer", "tools", "tool_schema", "tool_call", "function_call"
+}
+
+
+def _is_structured_json(text: str) -> bool:
+    try:
+        value = json.loads(text)
+    except (json.JSONDecodeError, TypeError):
+        return False
+    return isinstance(value, (dict, list))
+
+
+@dataclass(frozen=True, slots=True)
+class Plan:
+    decision: OptimizationDecision
+    protected_ids: frozenset[str]
+    reasons: tuple[str, ...]
+
+
+class ContextPlanner:
+    def plan(self, envelope: RequestEnvelope) -> Plan:
+        protected: set[str] = set()
+        reasons: list[str] = []
+        latest_turn = max((block.turn_index for block in envelope.blocks), default=0)
+
+        for block in envelope.blocks:
+            if block.kind in _PROTOCOL_KINDS:
+                protected.add(block.id)
+            if _CONSTRAINT_RE.search(block.text):
+                protected.add(block.id)
+            if block.turn_index == latest_turn:
+                protected.add(block.id)
+
+        self._protect_latest(envelope, "user", protected)
+        self._protect_latest(envelope, "tool_output", protected)
+
+        active_decisions: list[str] = []
+        for block in envelope.blocks:
+            matches = _DECISION_RE.findall(block.text)
+            if matches:
+                protected.add(block.id)
+            if block.turn_index != latest_turn or block.kind in _PROTOCOL_KINDS:
+                continue
+            for match in matches:
+                active_decisions.append(" ".join(match.lower().split()))
+
+        if not envelope.wire_safe:
+            reasons.append("unsupported_wire_shape")
+        if any(
+            marker in block.text
+            for block in envelope.blocks
+            for marker in _EXACT_EDIT_MARKERS
+        ):
+            reasons.append("exact_edit_context")
+        if len(set(active_decisions)) > 1:
+            reasons.append("competing_active_decisions")
+        has_decision_context = any(_DECISION_RE.search(block.text) for block in envelope.blocks)
+        has_structured_evidence = any(
+            block.kind == "tool_output" and _is_structured_json(block.text)
+            for block in envelope.blocks
+        )
+        if has_decision_context and has_structured_evidence:
+            reasons.append("structured_decision_context")
+
+        if reasons:
+            return Plan(OptimizationDecision.BYPASS, frozenset(protected), tuple(reasons))
+        return Plan(
+            OptimizationDecision.OPTIMIZE,
+            frozenset(protected),
+            ("eligible_request",),
+        )
+
+    @staticmethod
+    def _protect_latest(
+        envelope: RequestEnvelope, kind: str, protected: set[str]
+    ) -> None:
+        candidates = [
+            (block.turn_index, index, block.id)
+            for index, block in enumerate(envelope.blocks)
+            if block.kind == kind
+        ]
+        if candidates:
+            protected.add(max(candidates)[2])

token_runtime/reducers.py

@@ -0,0 +1,179 @@
+from __future__ import annotations
+
+from dataclasses import dataclass, replace
+import json
+import re
+
+from .model import ContextBlock
+from .store import RecoveryStore
+
+
+_ANCHOR_RE = re.compile(
+    r"\b(error|failed|failure|exception|warning|must|never|constraint|decision|status|exit code)\b",
+    re.I,
+)
+
+
+@dataclass(frozen=True, slots=True)
+class Reduction:
+    block: ContextBlock
+    changed: bool
+    reducer_id: str | None = None
+    recovery_ref: str | None = None
+
+
+def _unchanged(block: ContextBlock) -> Reduction:
+    return Reduction(block=block, changed=False)
+
+
+def _is_json_container(text: str) -> bool:
+    try:
+        value = json.loads(text)
+    except (json.JSONDecodeError, TypeError):
+        return False
+    return isinstance(value, (dict, list))
+
+
+class RepeatedLineReducer:
+    reducer_id = "repeat_runs_v1"
+
+    def reduce(self, block: ContextBlock, store: RecoveryStore, *, protected: bool) -> Reduction:
+        if protected or _is_json_container(block.text):
+            return _unchanged(block)
+        lines = block.text.splitlines()
+        if len(lines) < 2:
+            return _unchanged(block)
+
+        out: list[str] = []
+        current = lines[0]
+        count = 1
+        for line in lines[1:]:
+            if line == current:
+                count += 1
+                continue
+            out.append(current if count == 1 else f"{current}  [repeated x{count}]")
+            current, count = line, 1
+        out.append(current if count == 1 else f"{current}  [repeated x{count}]")
+        candidate = "\n".join(out)
+        if candidate == block.text or len(candidate) >= len(block.text):
+            return _unchanged(block)
+        ref = store.put(block.text.encode())
+        return Reduction(
+            block=replace(block, text=candidate),
+            changed=True,
+            reducer_id=self.reducer_id,
+            recovery_ref=ref,
+        )
+
+
+class JsonToolOutputReducer:
+    reducer_id = "json_minify_v1"
+
+    def reduce(self, block: ContextBlock, store: RecoveryStore, *, protected: bool) -> Reduction:
+        if protected or block.kind != "tool_output" or not _is_json_container(block.text):
+            return _unchanged(block)
+        value = json.loads(block.text)
+        candidate = json.dumps(value, ensure_ascii=False, separators=(",", ":"))
+        if len(candidate) >= len(block.text):
+            return _unchanged(block)
+        ref = store.put(block.text.encode())
+        return Reduction(block=replace(block, text=candidate), changed=True,
+                         reducer_id=self.reducer_id, recovery_ref=ref)
+
+
+class ToolOutputReducer:
+    reducer_id = "tool_output_v1"
+
+    def __init__(self, min_chars: int = 1800, edge_lines: int = 8):
+        self.min_chars = min_chars
+        self.edge_lines = edge_lines
+
+    def reduce(self, block: ContextBlock, store: RecoveryStore, *, protected: bool) -> Reduction:
+        if (protected or block.kind != "tool_output" or len(block.text) < self.min_chars
+                or _is_json_container(block.text)):
+            return _unchanged(block)
+
+        lines = block.text.splitlines()
+        edge = self.edge_lines
+        if len(lines) <= edge * 2 + 1:
+            return _unchanged(block)
+        middle = lines[edge:-edge]
+        anchors = [line for line in middle if _ANCHOR_RE.search(line)]
+        ref = store.put(block.text.encode())
+        marker = f"[TOKEN_REF:{ref}]"
+        candidate_lines = lines[:edge] + anchors + [marker] + lines[-edge:]
+        candidate = "\n".join(dict.fromkeys(candidate_lines))
+        if len(candidate) >= len(block.text):
+            return _unchanged(block)
+        return Reduction(
+            block=replace(block, text=candidate),
+            changed=True,
+            reducer_id=self.reducer_id,
+            recovery_ref=ref,
+        )
+
+
+_EXPLICIT_GUARD_RE = re.compile(
+    r"(?im)^\s*DECISION\s*:|\b(must|never|do not|don't|required|constraint)\b"
+)
+
+
+class RetrievedDuplicateReducer:
+    """Remove long exact adjacent duplicate spans from old retrieval/tool evidence."""
+
+    reducer_id = "evidence_exact_duplicate_v1"
+
+    def __init__(self, min_words: int = 8):
+        self.min_words = min_words
+
+    def reduce(self, block: ContextBlock, store: RecoveryStore, *, protected: bool) -> Reduction:
+        if (protected or block.kind not in {"retrieved", "tool_output"}
+                or _EXPLICIT_GUARD_RE.search(block.text) or _is_json_container(block.text)):
+            return _unchanged(block)
+        candidate = self._collapse_text(block.text)
+        if candidate == block.text or len(candidate) >= len(block.text):
+            return _unchanged(block)
+        ref = store.put(block.text.encode())
+        return Reduction(
+            block=replace(block, text=candidate),
+            changed=True,
+            reducer_id=self.reducer_id,
+            recovery_ref=ref,
+        )
+
+    def _collapse_text(self, text: str) -> str:
+        lines = text.splitlines(keepends=True)
+        return "".join(self._collapse_line(line) for line in lines)
+
+    def _collapse_line(self, line: str) -> str:
+        newline = ""
+        body = line
+        if body.endswith("\r\n"):
+            body, newline = body[:-2], "\r\n"
+        elif body.endswith("\n"):
+            body, newline = body[:-1], "\n"
+
+        while True:
+            match = self._longest_adjacent_repeat(body)
+            if match is None:
+                return body + newline
+            start_second, end_second = match
+            left = body[:start_second].rstrip()
+            right = body[end_second:]
+            body = left + right
+
+    def _longest_adjacent_repeat(self, text: str) -> tuple[int, int] | None:
+        words = list(re.finditer(r"\S+", text))
+        tokens = [item.group(0) for item in words]
+        best: tuple[int, int, int] | None = None
+        for start in range(len(tokens)):
+            max_span = (len(tokens) - start) // 2
+            for span in range(max_span, self.min_words - 1, -1):
+                if tokens[start:start + span] != tokens[start + span:start + 2 * span]:
+                    continue
+                second_start = words[start + span].start()
+                second_end = words[start + 2 * span - 1].end()
+                if best is None or span > best[0]:
+                    best = (span, second_start, second_end)
+                break
+        return None if best is None else (best[1], best[2])