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

context_compiler_example_integrations/README.md

@@ -0,0 +1,71 @@
+# 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.8.0`
+
+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.
+
+## Generic examples
+
+- [Checkpoint continuation](examples/checkpoint_continuation/README.md): persisted confirmation and resume flows change host behavior across turns or requests
+- [Execution authorization](examples/execution_authorization/README.md): protected host actions execute only when authoritative state allows them
+- [Gateway middleware](examples/gateway_middleware/README.md): the host allows, blocks, or routes requests before downstream work runs
+- [Prompt construction](examples/prompt_construction/README.md): the host builds different request or prompt payloads from authoritative state
+- [Retrieval filtering](examples/retrieval_filtering/README.md): the host changes which documents are eligible or relevant before returning results
+- [Schema selection](examples/schema_selection/README.md): the host picks different workflow or response schemas from authoritative state
+- [Tool gating](examples/tool_gating/README.md): the host changes which tools are visible or executable at runtime
+
+## 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:
+
+- [python/reference_integrations/litellm_proxy/README.md](reference_integrations/litellm_proxy/README.md)
+- [python/reference_integrations/openwebui_pipe/README.md](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.

context_compiler_example_integrations/__init__.py

@@ -0,0 +1 @@
+"""Package root for installed example integrations."""

context_compiler_example_integrations/examples/__init__.py

@@ -0,0 +1,12 @@
+"""Example modules for installed and editable package use."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+_PACKAGE_DIR = Path(__file__).resolve().parent
+_SOURCE_DIR = _PACKAGE_DIR.parents[1] / "python" / "examples"
+
+__path__ = [str(_PACKAGE_DIR)]
+if _SOURCE_DIR.is_dir():
+    __path__.append(str(_SOURCE_DIR))

context_compiler_example_integrations/examples/_shared/__init__.py

@@ -0,0 +1 @@
+"""Shared helpers for Python examples."""

context_compiler_example_integrations/examples/_shared/litellm_request.py

@@ -0,0 +1,61 @@
+"""Tiny shared helper for LiteLLM live-validation request kwargs."""
+
+from __future__ import annotations
+
+from typing import Literal, TypedDict
+
+
+class ProviderConfigLike(TypedDict):
+    mode: Literal["openai", "ollama", "openai_compatible"]
+    source: str
+    base_url: str
+    model: str
+    api_key: str | None
+
+
+class LiteLLMProviderKwargs(TypedDict, total=False):
+    model: str
+    api_base: str
+    api_key: str
+    temperature: float
+    drop_params: bool
+
+
+def build_litellm_provider_kwargs(
+    config: ProviderConfigLike,
+) -> LiteLLMProviderKwargs:
+    """Return LiteLLM-safe provider/model kwargs for live validations."""
+
+    model = _normalize_litellm_model_id(config)
+    base_url = _config_value(config, "base_url")
+    if base_url is None:
+        raise RuntimeError("Provider config missing base_url.")
+
+    kwargs: LiteLLMProviderKwargs = {
+        "model": model,
+        "api_base": base_url,
+        "drop_params": True,
+    }
+    api_key = _config_value(config, "api_key")
+    if api_key:
+        kwargs["api_key"] = api_key
+    kwargs["temperature"] = 0
+    return kwargs
+
+
+def _normalize_litellm_model_id(config: ProviderConfigLike) -> str:
+    mode = _config_value(config, "mode")
+    model = _config_value(config, "model")
+    if model is None:
+        raise RuntimeError("Provider config missing model.")
+    if mode == "ollama" and "/" not in model:
+        return f"ollama/{model}"
+    return model
+
+
+def _config_value(config: object, key: str) -> str | None:
+    if isinstance(config, dict):
+        value = config.get(key)
+    else:
+        value = getattr(config, key, None)
+    return value if isinstance(value, str) or value is None else str(value)

context_compiler_example_integrations/examples/_shared/provider_mode.py

@@ -0,0 +1,91 @@
+"""Shared provider mode resolution for installed example modules."""
+
+import logging
+import os
+from dataclasses import dataclass
+from typing import Literal, cast
+
+_ALLOWED_PROVIDER_VALUES = ("openai", "ollama", "openai_compatible")
+_STARTUP_LOGGED = False
+
+
+@dataclass(frozen=True)
+class ProviderConfig:
+    mode: Literal["openai", "ollama", "openai_compatible"]
+    source: Literal["default", "PROVIDER", "OPENAI_BASE_URL override"]
+    base_url: str
+    model: str
+    api_key: str | None
+
+
+def resolve_provider_config(
+    default_model: str = "openai/gpt-4o-mini",
+) -> ProviderConfig:
+    """Resolve provider mode config from environment using strict contract."""
+    base_url = os.getenv("OPENAI_BASE_URL", "").strip() or None
+    provider = os.getenv("PROVIDER", "").strip().lower() or None
+    api_key = os.getenv("OPENAI_API_KEY", "").strip() or None
+    model = os.getenv("MODEL", "").strip() or default_model
+
+    if base_url:
+        return ProviderConfig(
+            mode="openai_compatible",
+            source="OPENAI_BASE_URL override",
+            base_url=base_url,
+            model=model,
+            api_key=api_key,
+        )
+
+    if provider is not None and provider not in _ALLOWED_PROVIDER_VALUES:
+        allowed_values = ", ".join(_ALLOWED_PROVIDER_VALUES)
+        raise RuntimeError(
+            f"Invalid PROVIDER value '{provider}'. Allowed values: {allowed_values}"
+        )
+
+    mode: Literal["openai", "ollama", "openai_compatible"]
+    source: Literal["default", "PROVIDER", "OPENAI_BASE_URL override"]
+    if provider is None:
+        mode = "openai"
+        source = "default"
+    else:
+        mode = cast(Literal["openai", "ollama", "openai_compatible"], provider)
+        source = "PROVIDER"
+
+    if mode == "openai":
+        if not api_key:
+            raise RuntimeError("OPENAI_API_KEY is required in openai mode.")
+        return ProviderConfig(
+            mode=mode,
+            source=source,
+            base_url="https://api.openai.com/v1",
+            model=model,
+            api_key=api_key,
+        )
+    if mode == "ollama":
+        return ProviderConfig(
+            mode=mode,
+            source=source,
+            base_url="http://localhost:11434",
+            model=model,
+            api_key=api_key,
+        )
+
+    raise RuntimeError("OPENAI_BASE_URL is required when PROVIDER=openai_compatible.")
+
+
+def print_startup_config(
+    config: ProviderConfig, logger: logging.Logger | None = None
+) -> None:
+    """Emit one startup line per process with resolved provider config."""
+    global _STARTUP_LOGGED
+    if _STARTUP_LOGGED:
+        return
+    target_logger = logger or logging.getLogger(__name__)
+    target_logger.info(
+        "litellm_config mode=%s base_url=%s model=%s source=%s",
+        config.mode,
+        config.base_url,
+        config.model,
+        config.source,
+    )
+    _STARTUP_LOGGED = True

context_compiler_example_integrations/examples/checkpoint_continuation/README.md

@@ -0,0 +1,77 @@
+# Checkpoint continuation
+
+Restoring a saved checkpoint changes whether a fresh host process can resume
+and apply a pending itinerary change. This example shows checkpoint
+continuation in a generic Python travel-booking flow.
+
+## Domain
+
+The domain is a small travel-booking change flow.
+
+The user requests a change from the current itinerary to a new itinerary.
+That change requires confirmation before the host applies it.
+
+## 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
+- the pending confirmation continuation state
+- the checkpoint that captures both
+
+In this example, the pending checkpoint state is what makes the resumed
+confirmation meaningful.
+
+Restoring authoritative state alone is not enough to resume the pending change.
+
+## What the host owns
+
+The host owns:
+
+- the booking record
+- checkpoint persistence
+- request/process boundaries
+- the runtime behavior that actually applies the itinerary change
+
+The host reads authoritative Context Compiler state after confirmation and
+decides whether to apply the booking change.
+
+## Why this is not prompt reinjection
+
+This example does not re-send hidden instructions to a model.
+
+The observable behavior change is host-side: the booking record changes only
+after a restored engine resumes the pending confirmation and authoritative
+state changes.
+
+## Example behavior
+
+1. The host starts with a booking on `boston_trip`.
+2. The user initiates a switch to `chicago_trip`.
+3. Context Compiler enters a pending confirmation state.
+4. The host exports and persists the checkpoint.
+5. A fresh host process restores that checkpoint into a new engine.
+6. If the user confirms, the host applies the itinerary change.
+7. If the user rejects or sends unrelated text, the booking remains unchanged.
+
+## 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/examples/checkpoint_continuation/example.py

@@ -0,0 +1,169 @@
+"""Minimal checkpoint-continuation example for a travel booking change."""
+
+from dataclasses import dataclass, field
+from typing import Literal, TypedDict, cast
+
+from context_compiler import POLICY_USE, State, create_engine, get_policy_items
+from context_compiler.engine import Checkpoint, Engine, State as EngineState
+
+
+class BookingRecord(TypedDict):
+    booking_id: str
+    active_itinerary: str
+
+
+class BookingChangeRuntimeResult(TypedDict):
+    compiler_input: str
+    decision_kind: Literal["clarify", "update", "passthrough"]
+    prompt_to_user: str | None
+    checkpoint_pending: bool
+    active_itinerary: str
+    host_applied_change: bool
+
+
+@dataclass
+class CheckpointStore:
+    """Host-owned persistence for serialized engine checkpoints."""
+
+    saved_checkpoint: Checkpoint | None = None
+
+    def save(self, checkpoint: Checkpoint) -> None:
+        self.saved_checkpoint = checkpoint
+
+    def load(self) -> Checkpoint:
+        if self.saved_checkpoint is None:
+            raise ValueError("no checkpoint saved")
+        return self.saved_checkpoint
+
+
+@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, state: State) -> bool:
+        selected_itinerary = select_itinerary_from_state(state)
+        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_state(state: State) -> str | None:
+    """Select the host-visible itinerary from authoritative state."""
+
+    use_items = list(get_policy_items(state, POLICY_USE))
+    if not use_items:
+        return None
+    return use_items[0]
+
+
+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)
+
+
+def initiate_itinerary_change(
+    engine: Engine,
+    *,
+    current_itinerary: str,
+    requested_itinerary: str,
+) -> BookingChangeRuntimeResult:
+    """Ask Context Compiler to hold a travel change behind confirmation."""
+
+    compiler_input = f"use {requested_itinerary} instead of {current_itinerary}"
+    decision = engine.step(compiler_input)
+
+    return {
+        "compiler_input": compiler_input,
+        "decision_kind": _decision_kind_name(decision),
+        "prompt_to_user": decision.get("prompt_to_user"),
+        "checkpoint_pending": engine.has_pending_clarification(),
+        "active_itinerary": select_itinerary_from_state(engine.state)
+        or current_itinerary,
+        "host_applied_change": False,
+    }
+
+
+def restore_engine_from_checkpoint(checkpoint: Checkpoint) -> Engine:
+    """Restore both authoritative state and pending continuation state."""
+
+    engine = create_engine()
+    engine.import_checkpoint(checkpoint)
+    return engine
+
+
+def restore_engine_from_authoritative_state_only(
+    checkpoint: Checkpoint,
+) -> Engine:
+    """Restore only authoritative state, without pending continuation state."""
+
+    authoritative_state = cast(EngineState, checkpoint["authoritative_state"])
+    return create_engine(state=authoritative_state)
+
+
+def continue_itinerary_change(
+    engine: Engine,
+    host: BookingHost,
+    user_input: str,
+) -> BookingChangeRuntimeResult:
+    """Resume a pending change and apply host behavior only after confirmation."""
+
+    decision = engine.step(user_input)
+    host_applied_change = False
+    if _decision_kind_name(decision) == "update":
+        host_applied_change = host.apply_selected_itinerary(engine.state)
+
+    return {
+        "compiler_input": user_input,
+        "decision_kind": _decision_kind_name(decision),
+        "prompt_to_user": decision.get("prompt_to_user"),
+        "checkpoint_pending": engine.has_pending_clarification(),
+        "active_itinerary": host.booking["active_itinerary"],
+        "host_applied_change": host_applied_change,
+    }
+
+
+def run_demo() -> dict[str, BookingChangeRuntimeResult | Checkpoint]:
+    """Run a deterministic checkpoint-continuation demonstration."""
+
+    initial_booking: BookingRecord = {
+        "booking_id": "booking-100",
+        "active_itinerary": "boston_trip",
+    }
+    first_host = BookingHost(booking=initial_booking.copy())
+    first_engine = create_engine()
+    checkpoint_store = CheckpointStore()
+
+    pending_result = initiate_itinerary_change(
+        first_engine,
+        current_itinerary=first_host.booking["active_itinerary"],
+        requested_itinerary="chicago_trip",
+    )
+    checkpoint_store.save(first_engine.export_checkpoint())
+
+    resumed_engine = restore_engine_from_checkpoint(checkpoint_store.load())
+    resumed_host = BookingHost(booking=first_host.booking.copy())
+    confirmed_result = continue_itinerary_change(resumed_engine, resumed_host, "yes")
+
+    return {
+        "pending_result": pending_result,
+        "confirmed_result": confirmed_result,
+        "saved_checkpoint": checkpoint_store.load(),
+    }
+
+
+if __name__ == "__main__":
+    print(run_demo())

context_compiler_example_integrations/examples/checkpoint_continuation/fastapi/README.md

@@ -0,0 +1,85 @@
+# Checkpoint continuation with FastAPI
+
+A saved checkpoint lets later HTTP requests resume or reject a pending
+itinerary change instead of starting over. This example shows checkpoint
+continuation across stateless HTTP request boundaries.
+
+## Enforcement point
+
+Checkpoint continuation
+
+## Domain
+
+The domain is a small travel-booking change flow.
+
+The first request initiates a change from `boston_trip` to `chicago_trip`.
+
+That change requires confirmation before the host applies it.
+
+## Runtime
+
+This is a small FastAPI example.
+
+FastAPI is secondary to the enforcement point.
+
+It exists to show that the host can persist a checkpoint between separate HTTP
+requests and restore it later into a fresh engine.
+
+## Ownership boundary
+
+Context Compiler owns:
+
+- authoritative policy state
+- pending continuation state
+- checkpoint export and import
+
+The host owns:
+
+- checkpoint storage
+- request routing
+- booking mutation
+
+In this example, the host creates a fresh engine per request.
+
+The second request resumes the flow only because the host restores the saved
+checkpoint, not because the process remembered a conversation.
+
+## Why checkpoint continuation differs from state restore
+
+Checkpoint continuation includes pending confirmation state.
+
+Authoritative-state-only restore does not.
+
+That difference matters here:
+
+- restoring the full checkpoint lets a later `yes` resume the pending trip
+  change
+- restoring authoritative state alone does not resume that pending confirmation
+
+## Why this is not prompt reinjection
+
+This example does not re-send hidden instructions to a model.
+
+The observable behavior change is host-side: the booking only changes after a
+later request restores the checkpoint and confirmation succeeds.
+
+## Endpoints
+
+- `POST /change-trip`
+  - creates a pending confirmation
+  - persists a checkpoint in the host store
+- `POST /confirm`
+  - restores the saved checkpoint into a fresh engine
+  - accepts `yes`, `no`, or unrelated text
+  - applies the booking change only after successful confirmation
+- `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
+./scripts/validate_python.sh
+```