context-compiler-example-integrations 0.1.2__tar.gz → 0.2.0__tar.gz

{context_compiler_example_integrations-0.1.2 → context_compiler_example_integrations-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: context-compiler-example-integrations
-Version: 0.1.2
+Version: 0.2.0
 Summary: Example integrations and enforcement-point demonstrations for Context Compiler.
 Project-URL: Homepage, https://github.com/rlippmann/context-compiler-example-integrations
 Project-URL: Repository, https://github.com/rlippmann/context-compiler-example-integrations
@@ -21,14 +21,14 @@ Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
 Classifier: Topic :: Software Development :: Libraries
 Classifier: Topic :: Software Development :: Testing
 Requires-Python: >=3.11
-Requires-Dist: context-compiler>=0.8.3
+Requires-Dist: context-compiler<0.10,>=0.9.1
 Provides-Extra: all
 Requires-Dist: chromadb; extra == 'all'
-Requires-Dist: context-compiler-directive-drafter>=0.1.2; extra == 'all'
+Requires-Dist: context-compiler-directive-drafter<0.3,>=0.2.0; extra == 'all'
 Requires-Dist: fastapi; extra == 'all'
 Requires-Dist: litellm; extra == 'all'
 Provides-Extra: drafter
-Requires-Dist: context-compiler-directive-drafter>=0.1.2; extra == 'drafter'
+Requires-Dist: context-compiler-directive-drafter<0.3,>=0.2.0; extra == 'drafter'
 Provides-Extra: fastapi
 Requires-Dist: fastapi; extra == 'fastapi'
 Provides-Extra: litellm
@@ -61,7 +61,7 @@ pip install "context-compiler-example-integrations"
 
 That installs the shared core dependency only:
 
-- `context-compiler>=0.8.3`
+- `context-compiler>=0.9.1,<0.10`
 
 Add extras only for the examples you want to inspect locally:
 
@@ -77,7 +77,7 @@ runtime.
 
 ## Generic examples
 
-- [Checkpoint continuation](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/checkpoint_continuation/README.md): persisted confirmation and resume flows change host behavior across turns or requests
+- [Checkpoint continuation](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/checkpoint_continuation/README.md): persisted authoritative state changes host behavior across turns or requests
 - [Execution authorization](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/execution_authorization/README.md): protected host actions execute only when authoritative state allows them
 - [Gateway middleware](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/gateway_middleware/README.md): the host allows, blocks, or routes requests before downstream work runs
 - [Prompt construction](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/prompt_construction/README.md): the host builds different request or prompt payloads from authoritative state

{context_compiler_example_integrations-0.1.2 → context_compiler_example_integrations-0.2.0}/pyproject.toml

@@ -4,14 +4,14 @@ build-backend = "hatchling.build"
 
 [project]
 name = "context-compiler-example-integrations"
-version = "0.1.2"
+version = "0.2.0"
 description = "Example integrations and enforcement-point demonstrations for Context Compiler."
 readme = "python/README.md"
 requires-python = ">=3.11"
 license = { text = "Apache-2.0" }
 authors = [{ name = "Robert Lippmann" }]
 dependencies = [
-  "context-compiler>=0.8.3",
+  "context-compiler>=0.9.1,<0.10",
 ]
 keywords = [
   "context-compiler",
@@ -47,12 +47,12 @@ Issues = "https://github.com/rlippmann/context-compiler-example-integrations/iss
 [project.optional-dependencies]
 all = [
   "chromadb",
-  "context-compiler-directive-drafter>=0.1.2",
+  "context-compiler-directive-drafter>=0.2.0,<0.3",
   "fastapi",
   "litellm",
 ]
 drafter = [
-  "context-compiler-directive-drafter>=0.1.2",
+  "context-compiler-directive-drafter>=0.2.0,<0.3",
 ]
 fastapi = [
   "fastapi",
@@ -67,7 +67,7 @@ retrieval = [
 [dependency-groups]
 dev = [
   "chromadb",
-  "context-compiler-directive-drafter>=0.1.2",
+  "context-compiler-directive-drafter>=0.2.0,<0.3",
   "fastapi",
   "httpx2>=2.5.0",
   "httpx>=0.28.1",

{context_compiler_example_integrations-0.1.2 → context_compiler_example_integrations-0.2.0}/python/README.md

@@ -22,7 +22,7 @@ pip install "context-compiler-example-integrations"
 
 That installs the shared core dependency only:
 
-- `context-compiler>=0.8.3`
+- `context-compiler>=0.9.1,<0.10`
 
 Add extras only for the examples you want to inspect locally:
 
@@ -38,7 +38,7 @@ runtime.
 
 ## Generic examples
 
-- [Checkpoint continuation](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/checkpoint_continuation/README.md): persisted confirmation and resume flows change host behavior across turns or requests
+- [Checkpoint continuation](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/checkpoint_continuation/README.md): persisted authoritative state changes host behavior across turns or requests
 - [Execution authorization](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/execution_authorization/README.md): protected host actions execute only when authoritative state allows them
 - [Gateway middleware](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/gateway_middleware/README.md): the host allows, blocks, or routes requests before downstream work runs
 - [Prompt construction](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/prompt_construction/README.md): the host builds different request or prompt payloads from authoritative state

context_compiler_example_integrations-0.2.0/python/examples/checkpoint_continuation/README.md

@@ -0,0 +1,65 @@
+# State Persistence
+
+Persisting authoritative compiler state lets a fresh host process recover the
+same premise and policy decisions without recreating them from model output or
+conversation history. This example shows state persistence in a generic Python
+travel-booking flow.
+
+## Domain
+
+The domain is a small travel-booking change flow.
+
+The user selects a new itinerary, the compiler records that selection in
+authoritative state, and the host later applies the booking change from a
+restored engine.
+
+## Runtime
+
+This is a generic Python example.
+
+It does not call an LLM.
+
+It does not use directive drafter.
+
+## What Context Compiler owns
+
+Context Compiler owns:
+
+- authoritative policy state
+- serialization of that state through `export_json()`
+- restoration of that state through `import_json()`
+
+## What the host owns
+
+The host owns:
+
+- the booking record
+- persisted state storage
+- process boundaries
+- the runtime behavior that actually applies the itinerary change
+
+The host reads restored authoritative Context Compiler state and decides whether
+to apply the booking change.
+
+## Example behavior
+
+1. The host starts with a booking on `boston_trip`.
+2. The user selects `chicago_trip`.
+3. Context Compiler updates authoritative state.
+4. The host persists that state JSON.
+5. A fresh host process restores the saved state into a new engine.
+6. The host applies the booking change from the restored authoritative state.
+
+## Run
+
+From the repository root:
+
+```bash
+uv run python python/examples/checkpoint_continuation/example.py
+uv run pytest python/tests/test_checkpoint_continuation_example.py
+```
+
+## FastAPI variant
+
+For a request-boundary example, see
+[python/examples/checkpoint_continuation/fastapi/README.md](fastapi/README.md).

context_compiler_example_integrations-0.2.0/python/examples/checkpoint_continuation/example.py

@@ -0,0 +1,163 @@
+"""Minimal persistence example for a travel booking change."""
+
+from collections.abc import Mapping
+from dataclasses import dataclass, field
+from typing import Literal, TypedDict
+
+from context_compiler import Decision, DecisionKind, Engine, POLICY_USE, PolicyValue
+
+
+class BookingRecord(TypedDict):
+    booking_id: str
+    active_itinerary: str
+
+
+class BookingChangeRuntimeResult(TypedDict):
+    compiler_input: str
+    decision_kind: Literal["error", "update", "passthrough"]
+    message_to_user: str | None
+    persisted_state_json: str
+    selected_itinerary: str | None
+    host_applied_change: bool
+    active_itinerary: str
+
+
+@dataclass
+class EnginePersistenceStore:
+    """Host-owned persistence for serialized authoritative compiler state."""
+
+    saved_state_json: str | None = None
+
+    def save(self, state_json: str) -> None:
+        self.saved_state_json = state_json
+
+    def load(self) -> str:
+        if self.saved_state_json is None:
+            raise ValueError("no saved state")
+        return self.saved_state_json
+
+
+@dataclass
+class BookingHost:
+    """Host-owned runtime behavior for the booking example."""
+
+    booking: BookingRecord
+    applied_changes: list[str] = field(default_factory=list)
+
+    def apply_selected_itinerary(self, policies: Mapping[str, PolicyValue]) -> bool:
+        selected_itinerary = select_itinerary_from_policies(policies)
+        if selected_itinerary is None:
+            return False
+
+        self.booking["active_itinerary"] = selected_itinerary
+        self.applied_changes.append(selected_itinerary)
+        return True
+
+
+def select_itinerary_from_policies(policies: Mapping[str, PolicyValue]) -> str | None:
+    """Select the host-visible itinerary from authoritative state."""
+
+    for item, kind in policies.items():
+        if kind == POLICY_USE:
+            return item
+    return None
+
+
+def _decision_kind_name(
+    decision: Decision,
+) -> Literal["error", "update", "passthrough"]:
+    kind = decision.kind
+    if kind == DecisionKind.ERROR:
+        return "error"
+    if kind == DecisionKind.UPDATE:
+        return "update"
+    if kind == DecisionKind.NO_DIRECTIVE:
+        return "passthrough"
+    raise ValueError(f"unexpected decision kind: {kind}")
+
+
+def persist_itinerary_selection(
+    engine: Engine,
+    *,
+    requested_itinerary: str,
+) -> BookingChangeRuntimeResult:
+    """Persist authoritative state after selecting an itinerary."""
+
+    compiler_input = f"use {requested_itinerary}"
+    decision = engine.step(compiler_input)
+    persisted_state_json = engine.export_json()
+    selected_itinerary = select_itinerary_from_policies(engine.policies)
+
+    return {
+        "compiler_input": compiler_input,
+        "decision_kind": _decision_kind_name(decision),
+        "message_to_user": decision.message
+        if decision.kind == DecisionKind.ERROR
+        else None,
+        "persisted_state_json": persisted_state_json,
+        "selected_itinerary": selected_itinerary,
+        "host_applied_change": False,
+        "active_itinerary": requested_itinerary
+        if selected_itinerary is not None
+        else "boston_trip",
+    }
+
+
+def restore_engine_from_persisted_state(state_json: str) -> Engine:
+    """Restore authoritative compiler state into a fresh engine."""
+
+    engine = Engine()
+    engine.import_json(state_json)
+    return engine
+
+
+def apply_restored_itinerary(
+    engine: Engine, host: BookingHost
+) -> BookingChangeRuntimeResult:
+    """Apply host behavior from restored authoritative compiler state."""
+
+    host_applied_change = host.apply_selected_itinerary(engine.policies)
+    selected_itinerary = select_itinerary_from_policies(engine.policies)
+
+    return {
+        "compiler_input": "",
+        "decision_kind": "update" if host_applied_change else "passthrough",
+        "message_to_user": None,
+        "persisted_state_json": engine.export_json(),
+        "selected_itinerary": selected_itinerary,
+        "host_applied_change": host_applied_change,
+        "active_itinerary": host.booking["active_itinerary"],
+    }
+
+
+def run_demo() -> dict[str, BookingChangeRuntimeResult | str]:
+    """Run a deterministic persistence demonstration."""
+
+    initial_booking: BookingRecord = {
+        "booking_id": "booking-100",
+        "active_itinerary": "boston_trip",
+    }
+    first_engine = Engine()
+    engine_persistence_store = EnginePersistenceStore()
+
+    persisted_result = persist_itinerary_selection(
+        first_engine,
+        requested_itinerary="chicago_trip",
+    )
+    engine_persistence_store.save(persisted_result["persisted_state_json"])
+
+    restored_engine = restore_engine_from_persisted_state(
+        engine_persistence_store.load()
+    )
+    restored_host = BookingHost(booking=initial_booking.copy())
+    applied_result = apply_restored_itinerary(restored_engine, restored_host)
+
+    return {
+        "persisted_result": persisted_result,
+        "applied_result": applied_result,
+        "saved_state_json": engine_persistence_store.load(),
+    }
+
+
+if __name__ == "__main__":
+    print(run_demo())

context_compiler_example_integrations-0.2.0/python/examples/checkpoint_continuation/fastapi/README.md

@@ -0,0 +1,65 @@
+# State Persistence with FastAPI
+
+Saved authoritative compiler state lets later HTTP requests recover the same
+policy decisions instead of starting over. This example shows state
+persistence across stateless HTTP request boundaries.
+
+## Enforcement Point
+
+Authoritative state persistence
+
+## Domain
+
+The domain is a small travel-booking change flow.
+
+The first request selects `chicago_trip` in compiler state. A later request
+restores that saved state and lets the host apply the booking change.
+
+## Runtime
+
+This is a small FastAPI example.
+
+FastAPI is secondary to the enforcement point.
+
+It exists to show that the host can persist authoritative state between
+separate HTTP requests and restore it later into a fresh engine.
+
+## Ownership Boundary
+
+Context Compiler owns:
+
+- authoritative policy state
+- state export through `export_json()`
+- state restore through `import_json()`
+
+The host owns:
+
+- persisted state storage
+- request routing
+- booking mutation
+
+In this example, the host creates a fresh engine per request.
+
+The second request applies the saved itinerary only because the host restores
+the persisted authoritative state, not because the process remembered a
+conversation.
+
+## Endpoints
+
+- `POST /change-trip`
+  - updates authoritative state with `use chicago_trip`
+  - persists the resulting state JSON in the host store
+- `POST /apply-trip`
+  - restores the saved state JSON into a fresh engine
+  - applies the booking change from restored policy state
+- `GET /booking`
+  - returns the host-owned booking state
+
+## Validate
+
+From the repository root:
+
+```bash
+uv run pytest python/tests/test_fastapi_checkpoint_continuation_example.py
+uv run pre-commit run --all-files
+```

{context_compiler_example_integrations-0.1.2 → context_compiler_example_integrations-0.2.0}/python/examples/checkpoint_continuation/fastapi/app.py

@@ -1,11 +1,10 @@
-"""Small FastAPI checkpoint-continuation example for travel booking."""
+"""Small FastAPI persistence example for travel booking."""
 
-from collections.abc import Callable
+from collections.abc import Callable, Mapping
 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 context_compiler import DecisionKind, Engine, POLICY_USE, PolicyValue
 from fastapi import FastAPI, HTTPException
 from pydantic import BaseModel
 from typing_extensions import TypedDict
@@ -22,17 +21,16 @@ class BookingResponse(TypedDict):
 
 
 class ChangeTripResponse(TypedDict):
-    decision_kind: Literal["clarify"]
-    prompt_to_user: str | None
-    checkpoint_pending: bool
+    decision_kind: Literal["error", "update", "passthrough"]
+    message_to_user: str | None
+    persisted_state_json: str
+    selected_itinerary: str | None
     booking: BookingResponse
 
 
-class ConfirmResponse(TypedDict):
-    decision_kind: Literal["clarify", "update", "passthrough"]
-    prompt_to_user: str | None
-    checkpoint_pending: bool
+class ApplyTripResponse(TypedDict):
     host_applied_change: bool
+    selected_itinerary: str | None
     booking: BookingResponse
 
 
@@ -40,28 +38,23 @@ 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."""
+class EnginePersistenceStore:
+    """Host-owned authoritative state persistence for stateless HTTP requests."""
 
-    checkpoints_by_booking_id: dict[str, Checkpoint] = field(default_factory=dict)
+    states_by_booking_id: dict[str, str] = field(default_factory=dict)
 
-    def save(self, booking_id: str, checkpoint: Checkpoint) -> None:
-        self.checkpoints_by_booking_id[booking_id] = checkpoint
+    def save(self, booking_id: str, state_json: str) -> None:
+        self.states_by_booking_id[booking_id] = state_json
 
-    def load(self, booking_id: str) -> Checkpoint:
-        checkpoint = self.checkpoints_by_booking_id.get(booking_id)
-        if checkpoint is None:
+    def load(self, booking_id: str) -> str:
+        state_json = self.states_by_booking_id.get(booking_id)
+        if state_json is None:
             raise KeyError(booking_id)
-        return checkpoint
+        return state_json
 
     def has(self, booking_id: str) -> bool:
-        return booking_id in self.checkpoints_by_booking_id
+        return booking_id in self.states_by_booking_id
 
 
 @dataclass
@@ -85,8 +78,10 @@ class BookingHost:
     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)
+    def apply_selected_itinerary(
+        self, booking_id: str, policies: Mapping[str, PolicyValue]
+    ) -> bool:
+        selected_itinerary = select_itinerary_from_policies(policies)
         if selected_itinerary is None:
             return False
 
@@ -96,42 +91,35 @@ class BookingHost:
         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 select_itinerary_from_policies(policies: Mapping[str, PolicyValue]) -> str | None:
+    for item, kind in policies.items():
+        if kind == POLICY_USE:
+            return item
+    return None
 
 
-def restore_engine_from_checkpoint(checkpoint: Checkpoint) -> Engine:
-    engine = create_engine()
-    engine.import_checkpoint(checkpoint)
+def restore_engine_from_persisted_state(state_json: str) -> Engine:
+    engine = Engine()
+    engine.import_json(state_json)
     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()
+    return Engine()
 
 
 def create_app(
     *,
-    checkpoint_store: CheckpointStore | None = None,
+    engine_persistence_store: EnginePersistenceStore | None = None,
     booking_store: BookingStore | None = None,
     engine_factory: Callable[[], Engine] = _fresh_engine,
 ) -> FastAPI:
-    checkpoint_store = checkpoint_store or CheckpointStore()
+    engine_persistence_store = engine_persistence_store or EnginePersistenceStore()
     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 = FastAPI(title="state-persistence-fastapi-example")
+    app.state.engine_persistence_store = engine_persistence_store
     app.state.booking_store = booking_store
     app.state.booking_host = booking_host
     app.state.engine_factory = engine_factory
@@ -141,43 +129,51 @@ def create_app(
         booking = booking_store.get_or_create(request.booking_id)
         engine = engine_factory()
 
-        compiler_input = f"use chicago_trip instead of {booking['active_itinerary']}"
+        compiler_input = "use chicago_trip"
         decision = engine.step(compiler_input)
-        checkpoint_store.save(request.booking_id, engine.export_checkpoint())
+        state_json = engine.export_json()
+        engine_persistence_store.save(request.booking_id, state_json)
+
+        selected_itinerary = select_itinerary_from_policies(engine.policies)
+        decision_kind: Literal["error", "update", "passthrough"]
+        if decision.kind == DecisionKind.ERROR:
+            decision_kind = "error"
+        elif decision.kind == DecisionKind.UPDATE:
+            decision_kind = "update"
+        else:
+            decision_kind = "passthrough"
 
         return {
-            "decision_kind": "clarify",
-            "prompt_to_user": decision.get("prompt_to_user"),
-            "checkpoint_pending": engine.has_pending_clarification(),
+            "decision_kind": decision_kind,
+            "message_to_user": decision.message
+            if decision.kind == DecisionKind.ERROR
+            else None,
+            "persisted_state_json": state_json,
+            "selected_itinerary": selected_itinerary,
             "booking": {
                 "booking_id": booking["booking_id"],
                 "active_itinerary": booking["active_itinerary"],
             },
         }
 
-    @app.post("/confirm")
-    def confirm(request: ConfirmRequest) -> ConfirmResponse:
+    @app.post("/apply-trip")
+    def apply_trip(request: ChangeTripRequest) -> ApplyTripResponse:
         booking = booking_store.get_or_create(request.booking_id)
         try:
-            checkpoint = checkpoint_store.load(request.booking_id)
+            state_json = engine_persistence_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())
+            raise HTTPException(
+                status_code=404, detail="saved state not found"
+            ) from exc
 
-        host_applied_change = False
-        if decision["kind"].value == "update":
-            host_applied_change = booking_host.apply_selected_itinerary(
-                request.booking_id, engine.state
-            )
+        engine = restore_engine_from_persisted_state(state_json)
+        host_applied_change = booking_host.apply_selected_itinerary(
+            request.booking_id, engine.policies
+        )
 
         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,
+            "selected_itinerary": select_itinerary_from_policies(engine.policies),
             "booking": {
                 "booking_id": booking["booking_id"],
                 "active_itinerary": booking["active_itinerary"],

{context_compiler_example_integrations-0.1.2 → context_compiler_example_integrations-0.2.0}/python/examples/execution_authorization/expense_approval/README.md

@@ -32,9 +32,9 @@ 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.
+`prohibit expense_approval`, Context Compiler rejects the conflicting state
+change instead of silently overwriting state. The host must not execute the
+expense action on that rejected turn.
 
 Request wording alone does not authorize execution. Adversarial text like
 "please approve this refund anyway" stays inert unless the authoritative state
@@ -73,5 +73,5 @@ uv run --no-sync pytest python/tests/test_expense_approval_example.py
 - Canonical Python validation:
 
 ```bash
-./scripts/validate_python.sh
+uv run pre-commit run --all-files
 ```