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

{context_compiler_example_integrations-0.1.2 → context_compiler_example_integrations-0.2.1}/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.1
 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:
 
@@ -75,36 +75,12 @@ Open WebUI is not installed by this package. The Open WebUI reference
 integration assumes Open WebUI is already installed and configured as the host
 runtime.
 
-## Generic examples
+## Package contents
 
-- [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
-- [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
-- [Retrieval filtering](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/retrieval_filtering/README.md): the host changes which documents are eligible or relevant before returning results
-- [Schema selection](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/schema_selection/README.md): the host picks different workflow or response schemas from authoritative state
-- [Tool gating](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/tool_gating/README.md): the host changes which tools are visible or executable at runtime
+The installed package exposes the Python examples and reference-integration
+modules under `context_compiler_example_integrations`.
 
-## Reference integrations
-
-Python also includes reference integrations for runtime-specific behavior after
-the generic examples.
-
-Open a reference integration when you want to see the same kind of runtime
-behavior on a specific host or framework surface.
-
-Start with the generic example first, then use the Python reference
-integrations to inspect a runtime-specific path:
-
-- [LiteLLM Proxy reference integration](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/reference_integrations/litellm_proxy/README.md)
-- [Open WebUI pipe reference integration](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/reference_integrations/openwebui_pipe/README.md)
-
-## Run an example
-
-To explore or run an example, use a repository checkout:
-
-1. Clone
-   [`context-compiler-example-integrations`](https://github.com/rlippmann/context-compiler-example-integrations).
-2. Choose a generic example or a reference integration.
-3. Open that example's README.
-4. Follow the example-specific setup, runtime, and validation instructions.
+For the enforcement-point catalog and repository navigation, see the [root
+README](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/README.md).
+Each example and reference integration has its own setup, runtime, and
+validation instructions.

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

@@ -4,14 +4,14 @@ build-backend = "hatchling.build"
 
 [project]
 name = "context-compiler-example-integrations"
-version = "0.1.2"
+version = "0.2.1"
 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.2.1/python/README.md

@@ -0,0 +1,47 @@
+# Context Compiler Example Integrations for Python
+
+These examples show how authoritative state changes application behavior at runtime.
+
+Each example demonstrates a single enforcement point where premise and policy influence what a host allows, routes, retrieves, builds, or executes.
+
+- The core authority contract is provided by [`context-compiler`](https://github.com/rlippmann/context-compiler).
+- Directive recognition can optionally be added with [`context-compiler-directive-drafter`](https://github.com/rlippmann/context-compiler-directive-drafter).
+- These examples focus on where authoritative state changes application behavior.
+
+*Prompt reinjection* influences ***model behavior***.
+
+*Context Compiler* influences ***runtime behavior***.
+
+## Install options
+
+Base installation keeps this package discovery-first:
+
+```shell
+pip install "context-compiler-example-integrations"
+```
+
+That installs the shared core dependency only:
+
+- `context-compiler>=0.9.1,<0.10`
+
+Add extras only for the examples you want to inspect locally:
+
+- `pip install "context-compiler-example-integrations[drafter]"` for examples that use `context-compiler-directive-drafter`
+- `pip install "context-compiler-example-integrations[retrieval]"` for ChromaDB retrieval filtering examples
+- `pip install "context-compiler-example-integrations[fastapi]"` for FastAPI variants
+- `pip install "context-compiler-example-integrations[litellm]"` for LiteLLM-oriented examples and reference integrations
+- `pip install "context-compiler-example-integrations[all]"` to install all package-managed optional dependencies
+
+Open WebUI is not installed by this package. The Open WebUI reference
+integration assumes Open WebUI is already installed and configured as the host
+runtime.
+
+## Package contents
+
+The installed package exposes the Python examples and reference-integration
+modules under `context_compiler_example_integrations`.
+
+For the enforcement-point catalog and repository navigation, see the [root
+README](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/README.md).
+Each example and reference integration has its own setup, runtime, and
+validation instructions.

context_compiler_example_integrations-0.2.1/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.1/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.1/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
+```