context-engineering-core 0.12.0__py3-none-any.whl

context_engine/evaluation/run_commands.py

@@ -0,0 +1,146 @@
+"""CLI composition for synthetic or explicitly authorized benchmark execution and model swap."""
+
+import asyncio
+from pathlib import Path
+
+from ..config import TokenizerConfig
+from ..errors import BenchmarkError
+from ..providers.client import ProviderClient
+from ..providers.contracts import Completion, GenerationConfig, PriceCard, QuotaPolicy, Usage
+from ..providers.credentials import load_api_key, private_bytes
+from ..providers.store import RuntimeStore
+from ..tokens import TiktokenCounter
+from .corpus import load_bundle, strict_json
+from .execution import (
+    RunJournal,
+    execute,
+    execution_profile,
+    execution_snapshot,
+    load_execution,
+    save_execution,
+)
+from .protocol import load_freeze, make_manifest
+from .reporting import export_report, scorecard
+
+
+class OfflineBenchmarkTransport:
+    namespace = "c06-synthetic-unknown-v1"
+
+    async def send(self, payload, api_key, timeout):
+        # Deliberately no corpus, expected answer, fact ID or grading access.
+        return Completion(
+            payload["model"], "synthetic-response", "UNKNOWN", "stop", Usage(40, 5, 0, 2)
+        )
+
+
+def add_commands(commands):
+    for name in ("benchmark-run", "model-swap"):
+        parser = commands.add_parser(name, help="Run/resume frozen benchmark; offline by default")
+        parser.add_argument("--run-dir", type=Path, required=True)
+        parser.add_argument("--mode", choices=("offline", "live"), default="offline")
+        parser.add_argument("--allow-live", action="store_true")
+        parser.add_argument("--live-config", type=Path)
+        parser.add_argument("--env-file", type=Path, help="Explicit private GROQ_API_KEY file")
+        parser.add_argument("--max-calls", type=int, default=744)
+        parser.add_argument("--snapshot", type=Path, required=True)
+        parser.add_argument("--fact", action="append")
+        parser.add_argument("--budget", type=int, action="append")
+        parser.add_argument("--variant", action="append")
+        if name == "benchmark-run":
+            parser.add_argument("--model", action="append")
+    parser = commands.add_parser(
+        "benchmark-report", help="Regenerate validated reports without inference"
+    )
+    parser.add_argument("--snapshot", type=Path, required=True)
+    parser.add_argument("--output-dir", type=Path, required=True)
+
+
+def run_command(args):
+    bundle, frozen = load_bundle(), load_freeze()
+    if args.command == "benchmark-report":
+        payload = load_execution(args.snapshot, bundle, frozen)
+        card = scorecard(bundle, frozen, payload)
+        proof = export_report(args.output_dir, card)
+        return {"status": card["validity"]["status"], "report": proof, "inference_calls": 0}
+    models = bundle.get("protocol")["models"] if args.command == "model-swap" else args.model
+    manifest = make_manifest(
+        bundle, frozen, facts=args.fact, models=models, budgets=args.budget, variants=args.variant
+    )
+    if args.snapshot.exists():
+        raise BenchmarkError("Snapshot output exists; choose a new immutable export path")
+    if type(args.max_calls) is not int or not 0 <= args.max_calls <= 744:
+        raise BenchmarkError("Invalid execution batch size")
+    if args.mode == "live":
+        if not args.allow_live or bundle.get("protocol")["approval"] != "owner_approved":
+            raise BenchmarkError(
+                "Live execution requires explicit authorization and owner-approved registration"
+            )
+        if not args.live_config:
+            raise BenchmarkError("Live execution requires a private configuration and GROQ_API_KEY")
+        key = load_api_key(args.env_file)
+        try:
+            config = strict_json(private_bytes(args.live_config, 65536).decode(), maximum=65536)
+            if set(config) != {"quota", "prices", "max_run_cost_microusd", "ledger_path"}:
+                raise BenchmarkError("Unexpected live configuration fields")
+            quota = QuotaPolicy(**config["quota"])
+            if quota.daily_budget_microusd <= 0 and quota.billing_mode != "free_tier":
+                raise BenchmarkError("A positive daily spending cap is required")
+            prices = {
+                model: PriceCard(**config["prices"][model]) for model in manifest.data["models"]
+            }
+            for card in prices.values():
+                quota.validate_prices(card)
+            maximum = config["max_run_cost_microusd"]
+            if type(maximum) is not int or not 0 <= maximum <= 10**12:
+                raise BenchmarkError("Invalid run spending cap")
+            if (quota.billing_mode == "free_tier") != (maximum == 0):
+                raise BenchmarkError("Free-tier mode requires exactly zero run spending cap")
+            ledger_path = Path(config["ledger_path"])
+            if not ledger_path.is_absolute():
+                raise BenchmarkError(
+                    "Live account ledger path must be absolute and shared across runs"
+                )
+        except (OSError, KeyError, TypeError, ValueError):
+            raise BenchmarkError("Invalid private live configuration") from None
+        maximum = config["max_run_cost_microusd"]
+    else:
+        if args.env_file is not None:
+            raise BenchmarkError("Explicit credential files are only used in live mode")
+        quota = QuotaPolicy(
+            "synthetic-benchmark", 100000000, rpm=10000, tpm=100000000, rpd=10000, tpd=100000000
+        )
+        prices = {
+            m: PriceCard("synthetic-v1", 1000000, 500000, 2000000) for m in manifest.data["models"]
+        }
+        ledger_path = args.run_dir / "provider.sqlite"
+        key, maximum = "synthetic-not-a-credential", 100000000
+    store = RuntimeStore(ledger_path)
+    clients = {
+        model: ProviderClient(
+            store=store,
+            quota=quota,
+            prices=prices[model],
+            api_key=key,
+            generation=GenerationConfig(model=model, **manifest.data["protocol"]["generation"]),
+            counter=TiktokenCounter(TokenizerConfig(**manifest.data["protocol"]["tokenizer"])),
+            transport=OfflineBenchmarkTransport() if args.mode == "offline" else None,
+        )
+        for model in manifest.data["models"]
+    }
+    profile = execution_profile(manifest, clients, mode=args.mode, max_run_cost_microusd=maximum)
+    journal = RunJournal(args.run_dir / "run.sqlite", manifest, profile)
+    result = asyncio.run(
+        execute(
+            bundle, frozen, journal, clients, max_calls=args.max_calls, allow_live=args.allow_live
+        )
+    )
+    payload = execution_snapshot(journal)
+    save_execution(args.snapshot, payload)
+    return {
+        **result,
+        "execution_id": journal.execution_id,
+        "mode": args.mode,
+        "real_inference_calls": 0 if args.mode == "offline" else None,
+        "snapshot": str(args.snapshot),
+        "quality_acceptance": "NOT_EVALUATED",
+    }

context_engine/evaluation/strategies.py

@@ -0,0 +1,261 @@
+"""Offline baseline comparison on the frozen 31-fact corpus. No inference is performed.
+
+Strategies (same frozen corpus, tokenizer and per-budget allowance):
+
+- full_history: the raw chronological request; non-fit when over the allowance.
+- recent_window: WINDOW only.
+- summary_window: WINDOW + a generated extractive summary of omitted turns.
+- retrieval_window: WINDOW + BM25 retrieval of omitted originals.
+- combined: CAP + PIN + RETRIEVE + WINDOW + generated summary (SDK defaults, which
+  since 0.11.0 include `recover_capped_window=True`: RETRIEVE restores original
+  evidence that CAP removed from WINDOW turns).
+- combined_no_recover: combined with `recover_capped_window=False`, the default
+  before 0.11.0 and the frozen-protocol setting.
+
+Summary and retrieval strategies receive the same optional allocation (the frozen
+retrieval + summary reserves), so they compete for equal space. Ground truth is
+used only after assembly, for scoring. Answer correctness needs model inference
+and is reported NOT_EVALUATED here; this measures what context reaches the model.
+"""
+
+import statistics
+import time
+
+from ..config import BudgetConfig, CapConfig, RetrievalConfig, TokenizerConfig
+from ..layers.summarize import PrefixSummaryPolicy
+from ..models import BlockKind, ChatRequest, Message, Role
+from ..pipeline import AssemblyOptions, assemble_context
+from ..summaries import ExtractiveSummarizer, update_summary
+from ..tokens import TiktokenCounter
+from .corpus import Bundle, aliases
+from .grading import present
+from .harness import evidence_locations
+
+SUMMARY_POLICY_VERSION = "extractive-v1"
+STRATEGIES = {
+    "recent_window": AssemblyOptions(cap=False, pins=False, retrieve=False, summarize=False),
+    "summary_window": AssemblyOptions(cap=False, pins=False, retrieve=False, summarize=True),
+    "retrieval_window": AssemblyOptions(cap=False, pins=False, retrieve=True, summarize=False),
+    "combined": AssemblyOptions(),
+    "combined_no_recover": AssemblyOptions(),
+}
+NO_RECOVER = {"combined_no_recover"}
+ORDER = ("full_history", *STRATEGIES)
+
+
+def _budget(protocol: dict, allowance: int, strategy: str) -> BudgetConfig:
+    reserves = protocol["budget"]
+    optional = reserves["retrieval_reserve"] + reserves["summary_reserve"]
+    settings = dict(reserves)
+    if strategy == "summary_window":
+        settings.update(retrieval_reserve=0, summary_reserve=optional)
+    elif strategy == "retrieval_window":  # Same optional space, all for evidence.
+        settings.update(retrieval_reserve=optional, summary_reserve=0)
+    return BudgetConfig(
+        input_cap=allowance,
+        completion_reservation=protocol["generation"]["max_completion_tokens"],
+        **settings,
+    )
+
+
+def _percentile(values: list[float], fraction: float) -> float | None:
+    if not values:
+        return None
+    ordered = sorted(values)
+    return ordered[min(len(ordered) - 1, round(fraction * (len(ordered) - 1)))]
+
+
+def _assemble(job, protocol, counter, fact, allowance, strategy):
+    """Assemble one strategy's request; returns (result, summary source tokens)."""
+    history = job.arguments["history"]
+    budget = _budget(protocol, allowance, strategy)
+    options = STRATEGIES[strategy]
+    arguments = dict(
+        system=job.arguments["system"],
+        at=job.arguments["at"],
+        token_counter=counter,
+        cap_config=CapConfig(**protocol["cap"]),
+        retrieval_config=RetrievalConfig(
+            **protocol["retrieval"], recover_capped_window=strategy not in NO_RECOVER
+        ),
+        options=options,
+    )
+    pins = job.arguments["pinned_facts"]
+    result = assemble_context(history, fact["question"], pins, budget, **arguments)
+    summary_tokens = 0
+    if options.summarize:
+        reserve = budget.summary_reserve
+        snapshot = update_summary(
+            history,
+            result.diagnostics.kept_turn_ids,
+            ExtractiveSummarizer(max_characters=max(1, reserve * 3)),
+            scope=pins.scope,
+            policy_version=SUMMARY_POLICY_VERSION,
+            created_at=job.arguments["at"],
+            min_new_turns=1,
+        )
+        if snapshot is not None:
+            covered = set(snapshot.covered_turn_ids)
+            summary_tokens = sum(
+                counter.count_text(m.content)
+                for t in history
+                if t.turn_id in covered
+                for m in t.messages
+            )
+            result = assemble_context(
+                history,
+                fact["question"],
+                pins,
+                budget,
+                summary_policy=PrefixSummaryPolicy(snapshot),
+                **arguments,
+            )
+    return result, summary_tokens
+
+
+def _probe(bundle, protocol, counter, fact, allowance, strategy) -> dict:
+    job = bundle.job(fact["question"])
+    history = job.arguments["history"]
+    values = aliases(fact)
+    raw = counter.count_request(
+        ChatRequest(
+            (
+                Message("raw:system", Role.SYSTEM, job.arguments["system"]),
+                *(m for turn in history for m in turn.messages),
+                Message("raw:question", Role.USER, fact["question"]),
+            )
+        )
+    )
+    base = {"fact_id": fact["fact_id"], "zone": fact["zone"], "raw_tokens": raw.estimated_tokens}
+    if strategy == "full_history":
+        fits = raw.estimated_tokens <= allowance
+        return {
+            **base,
+            "fits": fits,
+            "input_tokens": raw.estimated_tokens if fits else None,
+            # Oversized raw input cannot be sent, so it retains nothing usable.
+            "fact_present": fits,
+            "evidence_at_source": fits,
+            "fact_in_summary": False,
+            "retrieved_chunks": 0,
+            "source_chunks": 0,
+            "source_retrieved": False,
+            "summary_source_tokens": 0,
+            "latency_ms": 0.0,
+        }
+    started = time.perf_counter()
+    result, summary_tokens = _assemble(job, protocol, counter, fact, allowance, strategy)
+    latency = (time.perf_counter() - started) * 1000
+    source = fact["source_turn_id"]
+    chunks = [b for b in result.blocks if b.kind == BlockKind.RETRIEVED and b.content]
+    sources = [s for b in chunks for s in b.sources]
+    summary = next((b for b in result.blocks if b.kind == BlockKind.SUMMARY), None)
+    return {
+        **base,
+        "fits": True,
+        "input_tokens": result.diagnostics.estimate.estimated_tokens,
+        "fact_present": any(present(m.content, values) for m in result.request.messages),
+        "evidence_at_source": bool(evidence_locations(result, fact, history)),
+        "fact_in_summary": bool(summary and present(summary.content, values)),
+        "retrieved_chunks": len(result.diagnostics.retrieved_chunk_ids),
+        "source_chunks": sum(1 for s in sources if s.turn_id == source),
+        "source_retrieved": source in result.diagnostics.retrieved_turn_ids,
+        "summary_source_tokens": summary_tokens,
+        "latency_ms": latency,
+    }
+
+
+def _aggregate(probes: list[dict]) -> dict:
+    count = len(probes)
+    fit = [p for p in probes if p["fits"]]
+    retrieving = [p for p in fit if p["retrieved_chunks"]]
+    reductions = [1 - p["input_tokens"] / p["raw_tokens"] for p in fit]
+    latencies = [p["latency_ms"] for p in fit]
+    by_zone: dict[str, list[int]] = {}
+    for p in probes:
+        tally = by_zone.setdefault(p["zone"], [0, 0])
+        tally[0] += p["evidence_at_source"]
+        tally[1] += 1
+    return {
+        "probes": count,
+        "fit": len(fit),
+        "fact_present": sum(p["fact_present"] for p in probes),
+        "evidence_at_source": sum(p["evidence_at_source"] for p in probes),
+        "fact_in_summary": sum(p["fact_in_summary"] for p in probes),
+        "evidence_by_zone": {zone: f"{hit}/{total}" for zone, (hit, total) in by_zone.items()},
+        "median_input_tokens": statistics.median(p["input_tokens"] for p in fit) if fit else None,
+        "median_raw_tokens": statistics.median(p["raw_tokens"] for p in probes),
+        "median_token_reduction": round(statistics.median(reductions), 4) if fit else None,
+        # Chunk precision: share of retrieved chunks that come from the fact's source turn.
+        "retrieval_precision": (
+            round(
+                statistics.mean(p["source_chunks"] / p["retrieved_chunks"] for p in retrieving), 4
+            )
+            if retrieving
+            else None
+        ),
+        # Turn recall: share of probes whose source turn was retrieved at all.
+        "retrieval_recall": (
+            round(sum(p["source_retrieved"] for p in fit) / len(fit), 4) if retrieving else None
+        ),
+        "summary_source_tokens_total": sum(p["summary_source_tokens"] for p in probes),
+        "median_latency_ms": round(statistics.median(latencies), 3) if latencies else None,
+        "p95_latency_ms": round(_percentile(latencies, 0.95), 3) if latencies else None,
+        "answer_correct": "NOT_EVALUATED",
+    }
+
+
+def assemble_strategy(bundle: Bundle, fact: dict, allowance: int, strategy: str):
+    """The exact request a strategy sends for one frozen fact (for bounded live runs).
+
+    `full_history` is not assembled; it either fits raw or is a non-fit.
+    """
+    if strategy not in STRATEGIES:
+        raise ValueError("Unknown or non-assembled strategy")
+    protocol = bundle.get("protocol")
+    counter = TiktokenCounter(TokenizerConfig(**protocol["tokenizer"]))
+    job = bundle.job(fact["question"])
+    result, _ = _assemble(job, protocol, counter, fact, allowance, strategy)
+    return result, _budget(protocol, allowance, strategy)
+
+
+def compare_strategies(
+    bundle: Bundle, budgets: tuple[int, ...] | None = None, *, include_probes: bool = False
+) -> dict:
+    """Run every strategy on every frozen fact at each budget. Deterministic except latency."""
+    protocol = bundle.get("protocol")
+    budgets = tuple(protocol["budgets"]) if budgets is None else tuple(budgets)
+    if not budgets or any(type(b) is not int or b <= 0 for b in budgets):
+        raise ValueError("Budgets must be positive integers")
+    counter = TiktokenCounter(TokenizerConfig(**protocol["tokenizer"]))
+    results = []
+    for allowance in budgets:
+        for strategy in ORDER:
+            probes = [
+                _probe(bundle, protocol, counter, fact, allowance, strategy)
+                for fact in bundle.facts
+            ]
+            entry = {"budget": allowance, "strategy": strategy, **_aggregate(probes)}
+            if include_probes:
+                entry["probe_results"] = [
+                    {**p, "latency_ms": round(p["latency_ms"], 3)} for p in probes
+                ]
+            results.append(entry)
+    return {
+        "status": "COMPLETE",
+        "mode": "offline_strategy_comparison",
+        "inference_calls": 0,
+        "corpus": {"scenario_id": protocol["scenario_id"], "facts": len(bundle.facts)},
+        "fixture_hashes": bundle.hashes,
+        "summary_policy": SUMMARY_POLICY_VERSION,
+        "results": results,
+        "limitations": [
+            "Synthetic single-scenario corpus authored with the engine; not real-world quality.",
+            "Context retention only: answer correctness and faithfulness need model inference.",
+            "Token counts are local estimates, not provider-billed tokens.",
+            "Latency is local wall time and varies by machine.",
+        ],
+    }
+
+
+__all__ = ["NO_RECOVER", "ORDER", "STRATEGIES", "assemble_strategy", "compare_strategies"]

context_engine/inspection.py

@@ -0,0 +1,266 @@
+"""Bounded JSON input and content-opt-in offline inspection. No provider calls."""
+
+import json
+from dataclasses import dataclass, replace
+from datetime import datetime
+from pathlib import Path
+
+from .config import (
+    MAX_INSPECTION_BYTES,
+    MAX_INSPECTION_TURNS,
+    BudgetConfig,
+    CapConfig,
+    RetrievalConfig,
+    Settings,
+    TokenizerConfig,
+)
+from .errors import InspectionError
+from .layers.summarize import FrozenSummaryPolicy, SummarySnapshot
+from .models import KeyedPins, Message, Pin, Scope, ToolCall, ToolDefinition, Turn, canonical_json
+from .pipeline import assemble_context
+from .tokens import TiktokenCounter
+
+
+def _object(value, allowed, required=()):
+    if not isinstance(value, dict) or set(value) - set(allowed) or set(required) - set(value):
+        raise InspectionError("Input object contains missing or unsupported fields")
+    return value
+
+
+def _items(value):
+    if not isinstance(value, list):
+        raise InspectionError("Expected a JSON array")
+    return value
+
+
+def _time(value):
+    if not isinstance(value, str):
+        raise InspectionError("Expected an ISO timestamp with timezone")
+    try:
+        return datetime.fromisoformat(value)
+    except ValueError:
+        raise InspectionError("Invalid ISO timestamp") from None
+
+
+def _config(cls, value, default):
+    _object(value, cls.__dataclass_fields__)
+    return replace(default, **value)
+
+
+@dataclass(frozen=True)
+class InspectionJob:
+    arguments: dict
+    tokenizer: TokenizerConfig
+    synthetic: bool = False
+
+    def run(self, *, input_cap: int | None = None):
+        arguments = dict(self.arguments)
+        if input_cap is not None:
+            arguments["budget"] = replace(arguments["budget"], input_cap=input_cap)
+        return assemble_context(**arguments, token_counter=TiktokenCounter(self.tokenizer))
+
+
+def parse_job(payload: dict, settings: Settings) -> InspectionJob:
+    _object(
+        payload,
+        {
+            "schema_version",
+            "scope",
+            "system",
+            "question",
+            "at",
+            "history",
+            "pins",
+            "tools",
+            "budget",
+            "cap",
+            "retrieval",
+            "tokenizer",
+            "summary",
+        },
+        {"schema_version", "scope", "system", "question", "at", "history"},
+    )
+    if type(payload["schema_version"]) is not int or payload["schema_version"] != 1:
+        raise InspectionError("Unsupported inspection schema version")
+    scope = Scope(
+        **_object(payload["scope"], {"tenant_id", "session_id"}, {"tenant_id", "session_id"})
+    )
+    at = _time(payload["at"])
+    history = []
+    raw_history = _items(payload["history"])
+    if len(raw_history) > MAX_INSPECTION_TURNS:
+        raise InspectionError(
+            "Inspection history exceeds the turn limit", maximum=MAX_INSPECTION_TURNS
+        )
+    for item in raw_history:
+        item = _object(
+            item, {"turn_id", "revision", "timestamp", "messages"}, {"turn_id", "messages"}
+        )
+        messages = []
+        for message in _items(item["messages"]):
+            message = dict(
+                _object(
+                    message,
+                    {"message_id", "role", "content", "tool_call_id", "tool_calls"},
+                    {"message_id", "role", "content"},
+                )
+            )
+            calls = []
+            for call in _items(message.pop("tool_calls", [])):
+                calls.append(
+                    ToolCall(
+                        **_object(
+                            call,
+                            {"call_id", "name", "arguments_json"},
+                            {"call_id", "name", "arguments_json"},
+                        )
+                    )
+                )
+            messages.append(Message(**message, tool_calls=tuple(calls)))
+        history.append(
+            Turn(
+                item["turn_id"],
+                scope,
+                tuple(messages),
+                item.get("revision", 1),
+                _time(item["timestamp"]) if "timestamp" in item else at,
+            )
+        )
+    pins = []
+    for pin in _items(payload.get("pins", [])):
+        pin = dict(
+            _object(
+                pin,
+                {"key", "value", "origin", "revision", "effective_at", "expires_at"},
+                {"key", "value", "origin"},
+            )
+        )
+        effective = _time(pin.pop("effective_at")) if "effective_at" in pin else at
+        expires = _time(pin.pop("expires_at")) if pin.get("expires_at") is not None else None
+        pin.pop("expires_at", None)
+        pins.append(Pin(scope=scope, **pin, effective_at=effective, expires_at=expires))
+    tools = []
+    for tool in _items(payload.get("tools", [])):
+        tool = _object(tool, {"name", "description", "parameters"}, {"name", "parameters"})
+        tools.append(
+            ToolDefinition(
+                tool["name"], tool.get("description", ""), canonical_json(tool["parameters"])
+            )
+        )
+    policy = None
+    if payload.get("summary") is not None:
+        raw = _object(
+            payload["summary"],
+            {"content", "covered_turn_ids", "policy_version", "created_at", "expires_at"},
+            {"content", "covered_turn_ids", "policy_version", "created_at"},
+        )
+        ids = _items(raw["covered_turn_ids"])
+        if any(not isinstance(identifier, str) for identifier in ids) or len(set(ids)) != len(ids):
+            raise InspectionError("Summary turn IDs must be unique strings")
+        turns = {t.turn_id: t for t in history}
+        if set(ids) - turns.keys():
+            raise InspectionError("Summary refers to missing history")
+        policy = FrozenSummaryPolicy(
+            SummarySnapshot.from_history(
+                scope=scope,
+                content=raw["content"],
+                history=tuple(turns[i] for i in ids),
+                policy_version=raw["policy_version"],
+                created_at=_time(raw["created_at"]),
+                expires_at=_time(raw["expires_at"]) if raw.get("expires_at") is not None else None,
+            )
+        )
+    question = payload["question"]
+    if not isinstance(question, str):
+        raise InspectionError("Question must be a string")
+    return InspectionJob(
+        {
+            "history": tuple(history),
+            "question": question,
+            "pinned_facts": KeyedPins(scope, tuple(pins)),
+            "system": payload["system"],
+            "at": at,
+            "tools": tuple(tools),
+            "summary_policy": policy,
+            "budget": _config(BudgetConfig, payload.get("budget", {}), settings.budget),
+            "cap_config": _config(CapConfig, payload.get("cap", {}), settings.cap),
+            "retrieval_config": _config(
+                RetrievalConfig, payload.get("retrieval", {}), settings.retrieval
+            ),
+        },
+        _config(TokenizerConfig, payload.get("tokenizer", {}), settings.tokenizer),
+    )
+
+
+def load_job(path: Path, settings: Settings) -> InspectionJob:
+    def unique(pairs):
+        result = {}
+        for key, value in pairs:
+            if key in result:
+                raise InspectionError("Duplicate JSON keys are not allowed")
+            result[key] = value
+        return result
+
+    def reject_constant(_):
+        raise InspectionError("JSON numeric constants must be finite")
+
+    try:
+        with path.open("rb") as handle:
+            raw = handle.read(MAX_INSPECTION_BYTES + 1)
+        if len(raw) > MAX_INSPECTION_BYTES:
+            raise InspectionError(
+                "Inspection file exceeds the byte limit", maximum=MAX_INSPECTION_BYTES
+            )
+        payload = json.loads(
+            raw.decode("utf-8"), object_pairs_hook=unique, parse_constant=reject_constant
+        )
+    except OSError:
+        raise InspectionError("Cannot read inspection input") from None
+    except (UnicodeError, ValueError, RecursionError):
+        raise InspectionError("Inspection input must be valid UTF-8 JSON") from None
+    try:
+        return parse_job(payload, settings)
+    except (TypeError, KeyError, OverflowError, RecursionError):
+        raise InspectionError("Invalid inspection input structure") from None
+
+
+def demo_job(settings: Settings) -> InspectionJob:
+    from .demo import demo_context
+
+    class DemoPolicy:
+        def get_summary(self, history, scope, at):
+            return SummarySnapshot.from_history(
+                scope=scope,
+                content="Earlier discussion concerned an incident and routine telemetry.",
+                history=history,
+                policy_version="synthetic-demo-v1",
+                created_at=at,
+            )
+
+    context, budget, at = demo_context()
+    return InspectionJob(
+        {
+            "history": context.original_turns,
+            "question": context.question,
+            "pinned_facts": context.pins,
+            "budget": budget,
+            "at": at,
+            "system": "Use the supplied evidence to answer.",
+            "summary_policy": DemoPolicy(),
+        },
+        settings.tokenizer,
+        synthetic=True,
+    )
+
+
+def save_inspection(path: Path, result: dict) -> None:
+    """Explicit export never overwrites an existing file."""
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        with path.open("x", encoding="utf-8") as handle:
+            json.dump(result, handle, ensure_ascii=False, indent=2)
+            handle.write("\n")
+    except FileExistsError:
+        raise InspectionError("Output already exists; choose a new path") from None
+    except (OSError, ValueError):
+        raise InspectionError("Cannot write inspection output") from None