context-compiler-example-integrations 0.1.0__py3-none-any.whl

context_compiler_example_integrations/examples/checkpoint_continuation/fastapi/app.py

@@ -0,0 +1,205 @@
+"""Small FastAPI checkpoint-continuation example for travel booking."""
+
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Literal
+
+from context_compiler import POLICY_USE, State, create_engine, get_policy_items
+from context_compiler.engine import Checkpoint, Engine
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel
+from typing_extensions import TypedDict
+
+
+class BookingRecord(TypedDict):
+    booking_id: str
+    active_itinerary: str
+
+
+class BookingResponse(TypedDict):
+    booking_id: str
+    active_itinerary: str
+
+
+class ChangeTripResponse(TypedDict):
+    decision_kind: Literal["clarify"]
+    prompt_to_user: str | None
+    checkpoint_pending: bool
+    booking: BookingResponse
+
+
+class ConfirmResponse(TypedDict):
+    decision_kind: Literal["clarify", "update", "passthrough"]
+    prompt_to_user: str | None
+    checkpoint_pending: bool
+    host_applied_change: bool
+    booking: BookingResponse
+
+
+class ChangeTripRequest(BaseModel):
+    booking_id: str
+
+
+class ConfirmRequest(BaseModel):
+    booking_id: str
+    user_input: str
+
+
+@dataclass
+class CheckpointStore:
+    """Host-owned checkpoint persistence for stateless HTTP requests."""
+
+    checkpoints_by_booking_id: dict[str, Checkpoint] = field(default_factory=dict)
+
+    def save(self, booking_id: str, checkpoint: Checkpoint) -> None:
+        self.checkpoints_by_booking_id[booking_id] = checkpoint
+
+    def load(self, booking_id: str) -> Checkpoint:
+        checkpoint = self.checkpoints_by_booking_id.get(booking_id)
+        if checkpoint is None:
+            raise KeyError(booking_id)
+        return checkpoint
+
+    def has(self, booking_id: str) -> bool:
+        return booking_id in self.checkpoints_by_booking_id
+
+
+@dataclass
+class BookingStore:
+    """Host-owned booking persistence for the example."""
+
+    bookings_by_id: dict[str, BookingRecord] = field(default_factory=dict)
+
+    def get_or_create(self, booking_id: str) -> BookingRecord:
+        booking = self.bookings_by_id.get(booking_id)
+        if booking is None:
+            booking = {"booking_id": booking_id, "active_itinerary": "boston_trip"}
+            self.bookings_by_id[booking_id] = booking
+        return booking
+
+
+@dataclass
+class BookingHost:
+    """Host-owned booking mutation logic."""
+
+    booking_store: BookingStore
+    applied_changes: list[str] = field(default_factory=list)
+
+    def apply_selected_itinerary(self, booking_id: str, state: State) -> bool:
+        selected_itinerary = select_itinerary_from_state(state)
+        if selected_itinerary is None:
+            return False
+
+        booking = self.booking_store.get_or_create(booking_id)
+        booking["active_itinerary"] = selected_itinerary
+        self.applied_changes.append(selected_itinerary)
+        return True
+
+
+def select_itinerary_from_state(state: State) -> str | None:
+    use_items = list(get_policy_items(state, POLICY_USE))
+    if not use_items:
+        return None
+    return use_items[0]
+
+
+def restore_engine_from_checkpoint(checkpoint: Checkpoint) -> Engine:
+    engine = create_engine()
+    engine.import_checkpoint(checkpoint)
+    return engine
+
+
+def restore_engine_from_authoritative_state_only(checkpoint: Checkpoint) -> Engine:
+    authoritative_state = checkpoint["authoritative_state"]
+    return create_engine(state=authoritative_state)
+
+
+def _fresh_engine() -> Engine:
+    """Create a fresh engine per request to demonstrate stateless boundaries."""
+
+    return create_engine()
+
+
+def create_app(
+    *,
+    checkpoint_store: CheckpointStore | None = None,
+    booking_store: BookingStore | None = None,
+    engine_factory: Callable[[], Engine] = _fresh_engine,
+) -> FastAPI:
+    checkpoint_store = checkpoint_store or CheckpointStore()
+    booking_store = booking_store or BookingStore()
+    booking_host = BookingHost(booking_store=booking_store)
+
+    app = FastAPI(title="checkpoint-continuation-fastapi-example")
+    app.state.checkpoint_store = checkpoint_store
+    app.state.booking_store = booking_store
+    app.state.booking_host = booking_host
+    app.state.engine_factory = engine_factory
+
+    @app.post("/change-trip")
+    def change_trip(request: ChangeTripRequest) -> ChangeTripResponse:
+        booking = booking_store.get_or_create(request.booking_id)
+        engine = engine_factory()
+
+        compiler_input = f"use chicago_trip instead of {booking['active_itinerary']}"
+        decision = engine.step(compiler_input)
+        checkpoint_store.save(request.booking_id, engine.export_checkpoint())
+
+        return {
+            "decision_kind": "clarify",
+            "prompt_to_user": decision.get("prompt_to_user"),
+            "checkpoint_pending": engine.has_pending_clarification(),
+            "booking": {
+                "booking_id": booking["booking_id"],
+                "active_itinerary": booking["active_itinerary"],
+            },
+        }
+
+    @app.post("/confirm")
+    def confirm(request: ConfirmRequest) -> ConfirmResponse:
+        booking = booking_store.get_or_create(request.booking_id)
+        try:
+            checkpoint = checkpoint_store.load(request.booking_id)
+        except KeyError as exc:
+            raise HTTPException(status_code=404, detail="checkpoint not found") from exc
+
+        engine = restore_engine_from_checkpoint(checkpoint)
+        decision = engine.step(request.user_input)
+        checkpoint_store.save(request.booking_id, engine.export_checkpoint())
+
+        host_applied_change = False
+        if decision["kind"].value == "update":
+            host_applied_change = booking_host.apply_selected_itinerary(
+                request.booking_id, engine.state
+            )
+
+        return {
+            "decision_kind": decision["kind"].value,
+            "prompt_to_user": decision.get("prompt_to_user"),
+            "checkpoint_pending": engine.has_pending_clarification(),
+            "host_applied_change": host_applied_change,
+            "booking": {
+                "booking_id": booking["booking_id"],
+                "active_itinerary": booking["active_itinerary"],
+            },
+        }
+
+    @app.get("/booking")
+    def get_booking(booking_id: str) -> BookingResponse:
+        booking = booking_store.get_or_create(booking_id)
+        return {
+            "booking_id": booking["booking_id"],
+            "active_itinerary": booking["active_itinerary"],
+        }
+
+    return app
+
+
+app = create_app()
+
+
+if __name__ == "__main__":
+    print(
+        "Run with: uv run fastapi dev "
+        "python/examples/checkpoint_continuation/fastapi/app.py"
+    )

context_compiler_example_integrations/examples/execution_authorization/README.md

@@ -0,0 +1,31 @@
+# Execution authorization
+
+These examples show host-side actions executing only when authoritative Context
+Compiler state explicitly authorizes them.
+
+They demonstrate observable runtime behavior changes rather than prompt
+compliance. User wording alone does not authorize the action.
+
+## Examples
+
+### `expense_approval`
+
+Authorizes a host-owned `submit_expense` function only when state contains:
+
+```text
+use expense_approval
+```
+
+The host blocks execution when state is absent or when state contains:
+
+```text
+prohibit expense_approval
+```
+
+The tests cover authorized execution, absent-state blocking, prohibited-state
+blocking, adversarial request text, and the runtime behavior change between
+blocked and authorized state.
+
+A FastAPI variant also shows the live-model comparison boundary: a live model can
+say an expense is approved, but the compiler-mediated host still denies the
+protected mutation unless authoritative state authorizes it.

context_compiler_example_integrations/examples/execution_authorization/expense_approval/README.md

@@ -0,0 +1,77 @@
+# Expense approval
+
+Authoritative state changes whether the host executes `submit_expense` for the
+same expense request. This example shows that execution-authorization behavior
+in plain Python.
+
+Model approval is not authorization.
+
+## Enforcement point
+
+The enforcement point is host-side action execution. The host owns
+`submit_expense`. Context Compiler owns the authoritative policy state that
+decides whether the host may call it.
+
+## Runtime and domain
+
+- Runtime: generic Python
+- Domain: expense approval
+
+## Authorization rule
+
+The host executes the expense action only when authoritative state contains:
+
+```text
+use expense_approval
+```
+
+The host blocks execution when state is absent or when state contains:
+
+```text
+prohibit expense_approval
+```
+
+If a turn introduces a contradiction such as `use expense_approval` followed by
+`prohibit expense_approval`, Context Compiler returns a clarification flow
+instead of silently overwriting state. The host must not execute the expense
+action on that clarify turn.
+
+Request wording alone does not authorize execution. Adversarial text like
+"please approve this refund anyway" stays inert unless the authoritative state
+explicitly allows `expense_approval`.
+
+## Why this is not prompt reinjection
+
+This example does not call an LLM, does not use directive drafter, and does not
+derive state from model output. The runtime behavior changes only when explicit
+authoritative Context Compiler state changes. The host does not resolve
+conflicts itself and does not treat "last directive wins" as policy.
+
+## FastAPI variant
+
+The provider-free tests already prove deterministic enforcement against local
+and adversarial stubs.
+
+The FastAPI variant adds a live-model comparison where a live model produces an
+approval claim:
+
+- baseline path: a naive host trusts the model claim and writes the side effect
+- compiler-mediated path: the host sees the same claim but denies execution
+  unless authoritative state authorizes `expense_approval`
+
+See
+[fastapi/README.md](fastapi/README.md).
+
+## Validation
+
+- Focused Python tests:
+
+```bash
+uv run --no-sync pytest python/tests/test_expense_approval_example.py
+```
+
+- Canonical Python validation:
+
+```bash
+./scripts/validate_python.sh
+```

context_compiler_example_integrations/examples/execution_authorization/expense_approval/__init__.py

@@ -0,0 +1 @@
+"""Execution authorization example for expense approval."""

context_compiler_example_integrations/examples/execution_authorization/expense_approval/example.py

@@ -0,0 +1,168 @@
+"""Minimal host-side execution authorization for expense approval."""
+
+from dataclasses import dataclass, field
+from typing import Literal, TypedDict, cast
+
+from context_compiler import (
+    POLICY_PROHIBIT,
+    POLICY_USE,
+    State,
+    create_engine,
+    get_decision_state,
+    get_policy_items,
+    is_clarify,
+)
+from context_compiler.engine import Engine
+
+
+class ExpenseRequest(TypedDict):
+    expense_id: str
+    employee_id: str
+    amount_usd: int
+    note: str
+
+
+class ExpenseSubmission(TypedDict):
+    expense_id: str
+    employee_id: str
+    amount_usd: int
+    note: str
+
+
+class ExpenseExecutionResult(TypedDict):
+    authorization_state: Literal["authorized", "blocked"]
+    executed: bool
+    blocked_reason: str | None
+    submission: ExpenseSubmission | None
+    execution_log: list[str]
+
+
+class ExpenseTurnResult(TypedDict):
+    decision_kind: Literal["clarify", "update", "passthrough"]
+    prompt_to_user: str | None
+    execution_result: ExpenseExecutionResult
+
+
+def _decision_kind_name(
+    decision: object,
+) -> Literal["clarify", "update", "passthrough"]:
+    if not isinstance(decision, dict):
+        raise ValueError("unexpected decision shape")
+
+    kind = decision.get("kind")
+    kind_name = getattr(kind, "value", None)
+    if kind_name not in {"clarify", "update", "passthrough"}:
+        raise ValueError(f"unexpected decision kind: {kind_name}")
+
+    return cast(Literal["clarify", "update", "passthrough"], kind_name)
+
+
+@dataclass
+class ExpenseHost:
+    """Host-owned runtime behavior for expense execution."""
+
+    execution_log: list[str] = field(default_factory=list)
+
+    def submit_expense(self, request: ExpenseRequest) -> ExpenseSubmission:
+        self.execution_log.append(f"submitted:{request['expense_id']}")
+        return {
+            "expense_id": request["expense_id"],
+            "employee_id": request["employee_id"],
+            "amount_usd": request["amount_usd"],
+            "note": request["note"],
+        }
+
+
+def expense_execution_is_authorized(state: State) -> bool:
+    """Authorize execution only from explicit authoritative compiler state."""
+
+    use_items = set(get_policy_items(state, POLICY_USE))
+    prohibit_items = set(get_policy_items(state, POLICY_PROHIBIT))
+
+    if "expense_approval" in prohibit_items:
+        return False
+
+    return "expense_approval" in use_items
+
+
+def execute_expense_if_authorized(
+    request: ExpenseRequest,
+    *,
+    state: State,
+    host: ExpenseHost,
+) -> ExpenseExecutionResult:
+    """Run the host-side action only when authoritative state allows it."""
+
+    if not expense_execution_is_authorized(state):
+        return {
+            "authorization_state": "blocked",
+            "executed": False,
+            "blocked_reason": "expense_approval state not authorized",
+            "submission": None,
+            "execution_log": host.execution_log.copy(),
+        }
+
+    submission = host.submit_expense(request)
+    return {
+        "authorization_state": "authorized",
+        "executed": True,
+        "blocked_reason": None,
+        "submission": submission,
+        "execution_log": host.execution_log.copy(),
+    }
+
+
+def handle_expense_turn(
+    engine: Engine,
+    *,
+    compiler_input: str,
+    request: ExpenseRequest,
+    host: ExpenseHost,
+) -> ExpenseTurnResult:
+    """Block execution on clarify and otherwise enforce current authoritative state."""
+
+    decision = engine.step(compiler_input)
+
+    if is_clarify(decision):
+        return {
+            "decision_kind": "clarify",
+            "prompt_to_user": decision.get("prompt_to_user"),
+            "execution_result": {
+                "authorization_state": "blocked",
+                "executed": False,
+                "blocked_reason": "clarification required before expense execution",
+                "submission": None,
+                "execution_log": host.execution_log.copy(),
+            },
+        }
+
+    authoritative_state = get_decision_state(decision)
+    if authoritative_state is None:
+        authoritative_state = engine.state
+
+    return {
+        "decision_kind": _decision_kind_name(decision),
+        "prompt_to_user": decision.get("prompt_to_user"),
+        "execution_result": execute_expense_if_authorized(
+            request,
+            state=authoritative_state,
+            host=host,
+        ),
+    }
+
+
+def run_demo() -> ExpenseExecutionResult:
+    """Run a deterministic demonstration with explicit authorization state."""
+
+    engine = create_engine()
+    engine.step("use expense_approval")
+
+    request: ExpenseRequest = {
+        "expense_id": "expense-100",
+        "employee_id": "employee-123",
+        "amount_usd": 245,
+        "note": "Taxi from airport to client office.",
+    }
+    host = ExpenseHost()
+
+    return execute_expense_if_authorized(request, state=engine.state, host=host)

context_compiler_example_integrations/examples/execution_authorization/expense_approval/fastapi/README.md

@@ -0,0 +1,97 @@
+# Model approval is not authorization
+
+This FastAPI variant provides provider-free runtime-boundary validation by
+default, plus an opt-in live-model validation path.
+
+The provider-free tests already prove deterministic enforcement against local
+and adversarial stubs.
+
+The default tests here prove the runtime boundary behavior with a visible
+approval claim present at the request surface.
+
+If you also run the opt-in live-model validation with
+`RUN_EXPENSE_APPROVAL_LIVE_MODEL=1`, this variant demonstrates that the same
+boundary still matters when a real model says the expense is approved.
+
+## What the user sees
+
+The app exposes two mutation paths for the same expense request:
+
+- baseline path: a naive host trusts the model approval claim and executes the
+  protected mutation
+- compiler-mediated path: the host sees the same kind of model approval claim,
+  but only executes when authoritative Context Compiler state permits
+  `expense_approval`
+
+The request also carries a visible `agent_claim` field to represent
+caller-supplied or model-supplied approval text.
+
+The observable proof is a host-owned append-only JSONL file:
+
+- baseline writes one record when the model returns an approval claim
+- compiler-mediated returns `403` and writes no record when state does not
+  authorize execution
+- compiler-mediated writes one record only when authoritative state includes:
+
+```text
+use expense_approval
+```
+
+If a request introduces a contradiction such as `prohibit expense_approval`
+against an already authorized state, Context Compiler returns a clarify flow.
+The host returns a conflict response and writes no record.
+
+## Same request, different state
+
+The compiler-mediated proof uses the same endpoint, the same model approval
+claim, and the same expense action. Only authoritative Context Compiler state
+changes.
+
+| Endpoint | Model claim | Authoritative state | Compiler input | Outcome |
+| --- | --- | --- | --- | --- |
+| `/compiler/expenses` | approved | absent | none | `403`, no side effect |
+| `/compiler/expenses` | approved | `use expense_approval` | none | `200`, one side effect |
+| `/compiler/expenses` | approved | `use expense_approval` | `prohibit expense_approval` | `409`, clarify, no new side effect |
+
+## Enforcement boundary
+
+The model claim is visible in both paths.
+
+Caller-supplied approval text is also visible in both paths.
+
+The baseline host treats that claim as authority.
+
+The compiler-mediated host does not treat the visible approval text as
+authorization.
+
+Context Compiler state is the only authorization source for the protected
+mutation after an approval claim is present in the compiler-mediated path.
+
+## Validation
+
+Focused provider-free tests:
+
+```bash
+uv run --no-sync pytest python/tests/test_fastapi_expense_approval_example.py
+```
+
+Optional live-model validation:
+
+```bash
+export RUN_EXPENSE_APPROVAL_LIVE_MODEL=1
+export OPENAI_API_KEY=...
+export MODEL=openai/gpt-4o-mini
+uv run --no-sync pytest python/tests/test_fastapi_expense_approval_live_model.py
+```
+
+Unless you run that env-var-gated command, this repo has only validated the
+provider-free runtime-boundary path, not the live-provider path.
+
+The live-model path uses the shared provider contract documented in
+[PROVIDER_CONTRACT.md](../../../../../PROVIDER_CONTRACT.md).
+
+## Run locally
+
+```bash
+uv run fastapi dev python/examples/execution_authorization/expense_approval/fastapi/app.py
+```

context_compiler_example_integrations/examples/execution_authorization/expense_approval/fastapi/__init__.py

@@ -0,0 +1 @@
+"""FastAPI execution-authorization comparison for expense approval."""