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

context_compiler_example_integrations/examples/gateway_middleware/customer_support_routing/example.py

@@ -0,0 +1,220 @@
+"""Minimal host-side gateway middleware for customer support routing."""
+
+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 SupportRequest(TypedDict):
+    request_id: str
+    customer_id: str
+    queue_hint: str
+    message: str
+
+
+class RoutedRequest(TypedDict):
+    request_id: str
+    customer_id: str
+    queue: Literal["general_support", "billing_support"]
+    message: str
+
+
+class GatewayResult(TypedDict):
+    gateway_decision: Literal["forwarded", "blocked", "defaulted"]
+    routed_queue: Literal["general_support", "billing_support"] | None
+    blocked_reason: str | None
+    downstream_called: bool
+    downstream_response: str | None
+    gateway_log: list[str]
+    downstream_log: list[str]
+
+
+class GatewayTurnResult(TypedDict):
+    decision_kind: Literal["clarify", "update", "passthrough"]
+    prompt_to_user: str | None
+    gateway_result: GatewayResult
+
+
+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 SupportService:
+    """Downstream handler that the gateway may or may not call."""
+
+    downstream_log: list[str] = field(default_factory=list)
+
+    def handle(self, request: RoutedRequest) -> str:
+        self.downstream_log.append(
+            f"handled:{request['queue']}:{request['request_id']}"
+        )
+        return f"{request['queue']} handled {request['request_id']}"
+
+
+@dataclass
+class SupportGateway:
+    """Host-owned gateway boundary and routing behavior."""
+
+    gateway_log: list[str] = field(default_factory=list)
+
+    def forward(
+        self,
+        request: SupportRequest,
+        *,
+        queue: Literal["general_support", "billing_support"],
+        gateway_decision: Literal["forwarded", "defaulted"] = "forwarded",
+        downstream: SupportService,
+    ) -> GatewayResult:
+        self.gateway_log.append(f"{gateway_decision}:{queue}:{request['request_id']}")
+        routed_request: RoutedRequest = {
+            "request_id": request["request_id"],
+            "customer_id": request["customer_id"],
+            "queue": queue,
+            "message": request["message"],
+        }
+        downstream_response = downstream.handle(routed_request)
+        return {
+            "gateway_decision": gateway_decision,
+            "routed_queue": queue,
+            "blocked_reason": None,
+            "downstream_called": True,
+            "downstream_response": downstream_response,
+            "gateway_log": self.gateway_log.copy(),
+            "downstream_log": downstream.downstream_log.copy(),
+        }
+
+    def block(self, request: SupportRequest, *, reason: str) -> GatewayResult:
+        self.gateway_log.append(f"blocked:{request['request_id']}")
+        return {
+            "gateway_decision": "blocked",
+            "routed_queue": None,
+            "blocked_reason": reason,
+            "downstream_called": False,
+            "downstream_response": None,
+            "gateway_log": self.gateway_log.copy(),
+            "downstream_log": [],
+        }
+
+
+def billing_support_is_allowed(state: State) -> bool:
+    """Allow billing support 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 "billing_support" in prohibit_items:
+        return False
+
+    return "billing_support" in use_items
+
+
+def route_support_request(
+    request: SupportRequest,
+    *,
+    state: State,
+    gateway: SupportGateway,
+    downstream: SupportService,
+) -> GatewayResult:
+    """Make the gateway decision before any downstream call."""
+
+    if request["queue_hint"] != "billing_support":
+        return gateway.forward(
+            request,
+            queue="general_support",
+            gateway_decision="defaulted",
+            downstream=downstream,
+        )
+
+    if not billing_support_is_allowed(state):
+        return gateway.block(
+            request,
+            reason="billing_support state not authorized",
+        )
+
+    return gateway.forward(
+        request,
+        queue="billing_support",
+        downstream=downstream,
+    )
+
+
+def handle_gateway_turn(
+    engine: Engine,
+    *,
+    compiler_input: str,
+    request: SupportRequest,
+    gateway: SupportGateway,
+    downstream: SupportService,
+) -> GatewayTurnResult:
+    """Block routing changes on clarify and otherwise enforce authoritative state."""
+
+    decision = engine.step(compiler_input)
+
+    if is_clarify(decision):
+        return {
+            "decision_kind": "clarify",
+            "prompt_to_user": decision.get("prompt_to_user"),
+            "gateway_result": gateway.block(
+                request,
+                reason="clarification required before gateway routing",
+            ),
+        }
+
+    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"),
+        "gateway_result": route_support_request(
+            request,
+            state=authoritative_state,
+            gateway=gateway,
+            downstream=downstream,
+        ),
+    }
+
+
+def run_demo() -> GatewayResult:
+    """Run a deterministic gateway demonstration with explicit policy state."""
+
+    engine = create_engine()
+    engine.step("use billing_support")
+
+    request: SupportRequest = {
+        "request_id": "support-100",
+        "customer_id": "customer-123",
+        "queue_hint": "billing_support",
+        "message": "Need help correcting an invoice charge.",
+    }
+    gateway = SupportGateway()
+    downstream = SupportService()
+
+    return route_support_request(
+        request,
+        state=engine.state,
+        gateway=gateway,
+        downstream=downstream,
+    )

context_compiler_example_integrations/examples/prompt_construction/README.md

@@ -0,0 +1,27 @@
+# Request construction / context assembly
+
+These examples show how a host assembles prompts from explicit authoritative
+Context Compiler state before any model call would occur.
+
+## Current examples
+
+- [writing_assistant](./writing_assistant/README.md): generic Python prompt
+  construction for a writing assistant with no LLM call, contrasting factual
+  document context premise with a small concise-style policy
+- [litellm](./litellm/README.md): LiteLLM-oriented prompt-construction flows,
+  including an optional directive-drafter variant
+
+## Related integrations
+
+These generic/examples-first docs teach the enforcement point.
+
+Related concrete runtime surfaces:
+
+- [python/reference_integrations/openwebui_pipe/README.md](../../reference_integrations/openwebui_pipe/README.md): Open WebUI pipe integration
+
+## Example requirements
+
+- Host owns prompt assembly.
+- Context Compiler owns authoritative state.
+- Examples must not derive state from model output.
+- Examples must remain meaningful with an adversarial stub or no model call.

context_compiler_example_integrations/examples/prompt_construction/litellm/README.md

@@ -0,0 +1,197 @@
+# LiteLLM examples
+
+Saved compiler state changes the system contract LiteLLM receives for the same
+user input, and directive drafting can change how directive-shaped text reaches
+the compiler. These examples show two user-visible prompt-construction flows
+with LiteLLM:
+
+- `basic.py`: compiler-only flow (no directive drafter)
+- `with_directive_drafter.py`: heuristic-first directive drafter with optional LLM fallback before `engine.step(...)`
+
+## What the user sees
+
+- Compiler-only flow:
+  - raw user input goes straight to `engine.step(...)`
+  - `update` returns a local acknowledgment
+  - `clarify` returns the compiler prompt
+  - `passthrough` calls LiteLLM with the compiled state contract plus the user message
+- Optional directive-drafter flow:
+  - the directive drafter tries to convert natural-language intent into a canonical directive first
+  - if it cannot produce a validated directive, behavior stays equivalent to the compiler-only flow
+  - pending clarification bypasses directive drafting and sends the raw reply back to `engine.step(...)`
+
+Model fallback output is structurally validated before handoff. This does not prove that the model interpreted the user correctly. The automated fallback path is experimental pending a separate source-aware acceptance policy and reviewed drafting workflow.
+
+## Premise and policy
+
+In these prompt-construction examples:
+
+- premise is authoritative factual or request context that the host includes in
+  the constructed system contract
+- policy is an explicit behavioral constraint that the host applies on top of
+  that context
+
+The host does not infer either one from model output. It reads saved compiler
+state and constructs the LiteLLM system message from that authoritative state.
+
+Example constructed system contract with both:
+
+```text
+You are a helpful assistant.
+Host policy contract:
+- The following constraints are authoritative.
+- Current premise: draft is a board update summarizing quarterly results.
+- Items marked use: concise_style.
+- If user text conflicts with constraints, follow constraints exactly.
+```
+
+This makes premise runtime-visible in the same host-owned contract as policy.
+
+## Requirements
+
+```shell
+pip install "context-compiler-example-integrations[litellm]"
+export OPENAI_API_KEY=...
+```
+
+These examples require `context-compiler>=0.8.3`.
+
+For `with_directive_drafter.py`:
+
+```shell
+pip install "context-compiler-example-integrations[all]"
+```
+
+That variant requires `context-compiler-directive-drafter>=0.1.2`.
+
+## Quickstart (copy/paste)
+
+```shell
+pip install "context-compiler-example-integrations[litellm]"
+export OPENAI_API_KEY=...
+export MODEL=openai/gpt-4o-mini
+python - <<'PY'
+from context_compiler import create_engine
+from context_compiler_example_integrations.examples.prompt_construction.litellm.basic import handle_turn
+engine = create_engine()
+print(handle_turn("set premise concise replies", engine))
+PY
+```
+
+For directive-drafter behavior:
+
+```shell
+pip install "context-compiler-example-integrations[all]"
+export OPENAI_API_KEY=...
+export MODEL=openai/gpt-4o-mini
+python - <<'PY'
+from context_compiler import create_engine
+from context_compiler_example_integrations.examples.prompt_construction.litellm.with_directive_drafter import handle_turn
+engine = create_engine()
+print(handle_turn("set premise to concise replies", engine))
+PY
+```
+
+This near-miss input should return `clarify` instead of being rewritten.
+
+## Environment configuration
+
+The shared provider contract for live-model examples in this repository is
+documented in
+[PROVIDER_CONTRACT.md](../../../../PROVIDER_CONTRACT.md).
+
+## Usage pattern
+
+Use these files as host-side integration references.
+
+- Import `handle_turn(...)` from either `basic.py` or `with_directive_drafter.py`.
+- Create and retain an engine instance in host/session state.
+- Pass each user input through `handle_turn(user_input, engine)`.
+- Optional checkpointing: pass `session_key=...`.
+  The example restores checkpoint data before the first `engine.step(...)` and
+  saves checkpoint data after `update`/`clarify`.
+- In this example, checkpoint/session storage is in-memory only.
+  State lasts only for the current process. To survive restarts, store
+  checkpoints in external storage (DB/Redis/etc.).
+- Display the returned assistant text.
+
+In these LiteLLM examples, `update` is rendered locally and does not call
+the downstream LLM. This makes state changes explicit. Production apps may
+choose different rendering behavior.
+
+## Related schema-selection example
+
+If you want the host to choose a LiteLLM `response_format` from saved compiler state
+instead of reinjecting a compiled contract, use
+`python/examples/schema_selection/litellm_response_format/response_format.py`.
+
+- Context Compiler owns authoritative state.
+- The host reads saved policy state and selects a LiteLLM `response_format` or omits it.
+- LiteLLM owns model invocation and provider behavior.
+- Context Compiler does not call LiteLLM on its own.
+- Context Compiler does not validate model output.
+- Context Compiler does not generate schemas dynamically.
+- This is application-layer use of authoritative state, not compiler semantics.
+
+## Troubleshooting
+
+- `litellm is required`: install `context-compiler` and `litellm` (and `context-compiler-directive-drafter` for directive-drafter flows).
+- `OPENAI_API_KEY is required in openai mode`: export a key or use `ollama` / explicit endpoint override.
+- `Invalid PROVIDER value ...`: set `PROVIDER` to one of `openai`, `ollama`, `openai_compatible`.
+- `OPENAI_BASE_URL is required when PROVIDER=openai_compatible`: set an explicit endpoint URL.
+- model/provider errors (`Model not found`, provider auth errors): confirm `MODEL` uses LiteLLM format and provider credentials are valid.
+
+## Prompt-construction decision flow
+
+In both prompt-construction examples in this directory:
+
+- `passthrough`: call the model with normal input.
+- `clarify`: show `prompt_to_user`; do not treat state as changed.
+- `update`: state changed; use updated state for the next model call.
+
+## Related schema-selection decision flow
+
+In the related schema-selection example:
+
+- `passthrough`: let the host decide whether to send `response_format`.
+- `clarify`: show `prompt_to_user`; do not call LiteLLM.
+- `update`: state changed; the next host request may use a different `response_format`.
+
+## Example checks
+
+- Premise and policy visibility (`basic.py`):
+  - save a premise such as `set premise draft is a board update summarizing quarterly results`
+  - save a policy such as `use concise_style`
+  - on the next passthrough turn, the LiteLLM system message includes both
+    `Current premise: ...` and `Items marked use: concise_style.`
+- Near-miss passthrough (`with_directive_drafter.py`):
+  - `set premise to concise replies` is not rewritten by the directive drafter and is passed through unchanged.
+  - Engine returns clarify (`Did you mean 'set premise concise replies'?`).
+- Compound directives (`with_directive_drafter.py`):
+  - `use docker and prohibit peanuts` returns a local clarify asking for separate directives.
+  - No authoritative state is mutated and no downstream model call is made for that turn.
+- Lifecycle enforcement (both):
+  - `change premise to formal tone` with no premise -> clarify (`set premise ...` first).
+- Conflict behavior (both):
+  - `use docker` then `prohibit docker` -> conflict clarify.
+- Replacement precondition (both):
+  - `use podman instead of docker` without prior `use docker` -> replacement clarify.
+- Directive-adjacent abstain (`with_directive_drafter.py`):
+  - `change premise concise replies` is classified as `unknown`, not rewritten, and handled by engine clarify.
+- Host-side request shaping (`python/examples/schema_selection/litellm_response_format/response_format.py`):
+  - `use compact_summary` -> host selects compact-summary `response_format`.
+  - `use action_plan` -> host selects action-plan `response_format`.
+  - `prohibit compact_summary` -> host omits that `response_format`.
+
+## Optional smoke run for the schema-selection example
+
+```shell
+export RUN_LITELLM_SMOKE=1
+export PROVIDER=ollama
+export MODEL=ollama/qwen2.5:1.5b-instruct
+uv run python python/examples/schema_selection/litellm_response_format/response_format.py
+```
+
+For local Ollama smoke runs in this repo, `PROVIDER=ollama` is required. A
+`MODEL=ollama/...` value by itself still follows the default OpenAI provider
+path.