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

context_compiler_example_integrations/examples/schema_selection/ollama_structured_output/example.py

@@ -0,0 +1,171 @@
+"""Minimal host-side Ollama structured-output schema selection.
+
+Flow:
+Context Compiler state -> host selection logic -> Ollama `format` JSON Schema.
+
+This example keeps model execution optional so tests can validate behavior without Ollama.
+"""
+
+import json
+import os
+import urllib.error
+import urllib.request
+from collections.abc import Mapping
+from typing import Any, TypedDict, cast
+
+from context_compiler import (
+    POLICY_PROHIBIT,
+    POLICY_USE,
+    State,
+    create_engine,
+    get_clarify_prompt,
+    get_decision_state,
+    get_policy_items,
+    is_clarify,
+)
+from context_compiler.engine import Engine
+
+PYTHON_SCRIPT_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "python_script": {
+            "type": "string",
+            "description": "A complete Python script.",
+        }
+    },
+    "required": ["python_script"],
+    "additionalProperties": False,
+}
+
+SHELL_COMMAND_SCHEMA: dict[str, Any] = {
+    "type": "object",
+    "properties": {
+        "shell_command": {
+            "type": "string",
+            "description": "A single shell command.",
+        }
+    },
+    "required": ["shell_command"],
+    "additionalProperties": False,
+}
+
+# Small, explicit mapping from policy item -> Ollama `format` schema.
+_SCHEMA_BY_ITEM: dict[str, dict[str, Any]] = {
+    "python_script": PYTHON_SCRIPT_SCHEMA,
+    "shell_command": SHELL_COMMAND_SCHEMA,
+}
+
+
+class TurnPlan(TypedDict):
+    decision_kind: str
+    clarify_prompt: str | None
+    selected_schema_item: str | None
+    format_schema: dict[str, Any] | None
+
+
+def select_ollama_format_schema(
+    state: State,
+) -> tuple[str | None, dict[str, Any] | None]:
+    """Return (policy_item, schema) or (None, None) when no safe match exists.
+
+    Unknown/insufficient policy state intentionally selects no schema.
+    """
+
+    use_items = set(get_policy_items(state, POLICY_USE))
+    prohibit_items = set(get_policy_items(state, POLICY_PROHIBIT))
+
+    for item, schema in _SCHEMA_BY_ITEM.items():
+        if item in use_items and item not in prohibit_items:
+            return item, schema
+
+    return None, None
+
+
+def plan_turn(user_input: str, engine: Engine) -> TurnPlan:
+    """Run compiler step and decide whether to request Ollama structured output."""
+
+    decision = engine.step(user_input)
+    if is_clarify(decision):
+        return {
+            "decision_kind": "clarify",
+            "clarify_prompt": get_clarify_prompt(decision),
+            "selected_schema_item": None,
+            "format_schema": None,
+        }
+
+    decision_state = get_decision_state(decision)
+    compiled_state = decision_state if decision_state is not None else engine.state
+    selected_item, format_schema = select_ollama_format_schema(compiled_state)
+
+    return {
+        "decision_kind": str(decision["kind"]),
+        "clarify_prompt": None,
+        "selected_schema_item": selected_item,
+        "format_schema": format_schema,
+    }
+
+
+def optional_ollama_call(
+    *,
+    user_input: str,
+    model: str,
+    format_schema: Mapping[str, Any] | None,
+    host: str | None = None,
+) -> dict[str, Any]:
+    """Optional smoke call to Ollama's /api/chat.
+
+    If `format_schema` is provided, it is passed through `format` exactly.
+    """
+
+    base_url = host or os.getenv("OLLAMA_BASE_URL") or "http://localhost:11434"
+    payload: dict[str, Any] = {
+        "model": model,
+        "messages": [{"role": "user", "content": user_input}],
+        "stream": False,
+    }
+    if format_schema is not None:
+        payload["format"] = dict(format_schema)
+
+    request = urllib.request.Request(
+        url=f"{base_url.rstrip('/')}/api/chat",
+        data=json.dumps(payload).encode("utf-8"),
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+
+    try:
+        with urllib.request.urlopen(request, timeout=30) as response:
+            raw = response.read().decode("utf-8")
+    except urllib.error.URLError as exc:
+        raise RuntimeError(f"Ollama call failed: {exc}") from exc
+
+    decoded = cast(object, json.loads(raw))
+    if not isinstance(decoded, dict):
+        raise RuntimeError("Ollama response must be a JSON object")
+    return cast(dict[str, Any], decoded)
+
+
+def main() -> None:
+    engine = create_engine()
+
+    # Demonstration setup.
+    engine.step("use python_script")
+    engine.step("prohibit shell_command")
+
+    plan = plan_turn("Write a helper script to parse CSV files.", engine)
+    print("decision_kind:", plan["decision_kind"])
+    print("selected_schema_item:", plan["selected_schema_item"])
+    print("format_schema_selected:", plan["format_schema"] is not None)
+
+    # Optional model execution path; disabled by default.
+    if os.getenv("RUN_OLLAMA_SMOKE") == "1":
+        response = optional_ollama_call(
+            user_input="Write a helper script to parse CSV files.",
+            model=os.getenv("OLLAMA_MODEL", "llama3.1"),
+            format_schema=plan["format_schema"],
+        )
+        print("ollama_response_keys:", sorted(response.keys()))
+
+
+if __name__ == "__main__":
+    main()

context_compiler_example_integrations/examples/schema_selection/refund_intake/README.md

@@ -0,0 +1,95 @@
+# Refund intake
+
+Authoritative state changes which intake workflow the host selects for the same
+ambiguous order request. This example shows two host-side schema-selection
+mechanisms in a customer order/support intake flow.
+
+The enforcement point stays the same:
+
+- same user request
+- different authoritative state
+- different host-selected schema
+
+Context Compiler does not choose the workflow by prompt wording. The host reads
+the saved authoritative state and selects the workflow/schema from that state.
+For premise-driven selection, the host applies a small deterministic
+order-intake rule:
+
+`saved order facts -> intake category -> selected schema`
+
+In this example, the host checks for a few explicit order facts in the saved
+premise, such as `delivered physical item` plus `damaged on arrival`, or
+`digital subscription` plus `login failure`.
+
+## Enforcement point
+
+Schema selection
+
+## State mechanisms
+
+- policy-driven schema selection via `use ...`
+- premise-driven schema selection via factual order context
+
+## What changes
+
+Without matching authoritative state, no workflow is selected.
+
+With policy state:
+
+```text
+use refund_intake
+```
+
+the refund workflow runs.
+
+With a factual premise:
+
+```text
+set premise order A-100 is a delivered physical item reported as damaged on arrival
+```
+
+the same ambiguous user request, `I need help with order A-100.`, selects the
+`refund_intake` schema.
+
+The host maps that saved premise to the `damaged_physical_delivery` intake
+category, which then maps to `refund_intake`.
+
+With a different factual premise:
+
+```text
+set premise order A-100 is a digital subscription with an active login failure after purchase
+```
+
+the same ambiguous user request selects the `technical_support` schema.
+
+The host maps that saved premise to the
+`digital_subscription_login_failure` intake category, which then maps to
+`technical_support`.
+
+The premise is factual context about the order. It is not a workflow command
+and it is not rewritten as `use refund_intake` or `use technical_support`.
+This mapping is host-owned business logic, not model inference.
+
+## Proof
+
+The tests verify:
+
+```python
+assert refund_handler.called is True
+assert technical_support_handler.called is False
+```
+
+They also verify:
+
+- `use refund_intake` selects `refund_intake`
+- `use technical_support` selects `technical_support`
+- saved premise facts map to a named intake category before schema selection
+- the same request plus different saved premise selects different schemas
+- unrelated premise selects no schema
+- adversarial user text does not override saved policy or saved premise
+
+## Test
+
+```shell
+uv run pytest python/tests/test_refund_intake_example.py
+```

context_compiler_example_integrations/examples/schema_selection/refund_intake/__init__.py

@@ -0,0 +1 @@
+"""Refund intake schema-selection example."""

context_compiler_example_integrations/examples/schema_selection/refund_intake/example.py

@@ -0,0 +1,180 @@
+"""Minimal host-side schema selection for refund intake."""
+
+from dataclasses import dataclass
+from typing import Literal, TypedDict
+
+from context_compiler import (
+    POLICY_USE,
+    State,
+    create_engine,
+    get_policy_items,
+    get_premise_value,
+)
+
+DAMAGED_ORDER_PREMISE = (
+    "order A-100 is a delivered physical item reported as damaged on arrival"
+)
+DIGITAL_LOGIN_FAILURE_PREMISE = (
+    "order A-100 is a digital subscription with an active login failure after purchase"
+)
+
+
+class IntakeRequest(TypedDict):
+    customer_id: str
+    message: str
+
+
+class RefundIntakeResult(TypedDict):
+    kind: Literal["refund"]
+    customer_id: str
+    reason: str
+
+
+class TechnicalSupportResult(TypedDict):
+    kind: Literal["technical_support"]
+    customer_id: str
+    issue: str
+
+
+OrderIntakeContext = Literal[
+    "damaged_physical_delivery", "digital_subscription_login_failure"
+]
+
+
+class IntakeRunResult(TypedDict):
+    selected_schema: str | None
+    refund_handler_called: bool
+    technical_support_handler_called: bool
+    result: RefundIntakeResult | TechnicalSupportResult | None
+
+
+_SCHEMA_BY_ORDER_INTAKE_CONTEXT: dict[OrderIntakeContext, str] = {
+    "damaged_physical_delivery": "refund_intake",
+    "digital_subscription_login_failure": "technical_support",
+}
+
+
+@dataclass
+class IntakeHandler:
+    name: str
+    called: bool = False
+
+    def handle(
+        self, request: IntakeRequest
+    ) -> RefundIntakeResult | TechnicalSupportResult:
+        self.called = True
+
+        if self.name == "refund_intake":
+            return {
+                "kind": "refund",
+                "customer_id": request["customer_id"],
+                "reason": request["message"],
+            }
+
+        if self.name == "technical_support":
+            return {
+                "kind": "technical_support",
+                "customer_id": request["customer_id"],
+                "issue": request["message"],
+            }
+
+        raise ValueError(f"unknown handler: {self.name}")
+
+
+def classify_premise_as_order_intake_context(
+    premise: str | None,
+) -> OrderIntakeContext | None:
+    """Map saved order facts to a host-owned intake context."""
+
+    if premise is None:
+        return None
+
+    normalized_premise = premise.casefold()
+    if (
+        "delivered physical item" in normalized_premise
+        and "damaged on arrival" in normalized_premise
+    ):
+        return "damaged_physical_delivery"
+
+    if (
+        "digital subscription" in normalized_premise
+        and "login failure" in normalized_premise
+    ):
+        return "digital_subscription_login_failure"
+
+    return None
+
+
+def select_schema_from_order_intake_context(
+    context: OrderIntakeContext | None,
+) -> str | None:
+    """Map a host-owned intake context to the selected schema."""
+
+    if context is None:
+        return None
+
+    return _SCHEMA_BY_ORDER_INTAKE_CONTEXT[context]
+
+
+def select_schema_from_state(state: State) -> str | None:
+    """Select a host-side workflow from authoritative state."""
+
+    use_items = set(get_policy_items(state, POLICY_USE))
+    premise = get_premise_value(state)
+
+    if "refund_intake" in use_items:
+        return "refund_intake"
+
+    if "technical_support" in use_items:
+        return "technical_support"
+
+    intake_context = classify_premise_as_order_intake_context(premise)
+    return select_schema_from_order_intake_context(intake_context)
+
+
+def run_intake(
+    request: IntakeRequest,
+    *,
+    selected_schema: str | None,
+    refund_handler: IntakeHandler,
+    technical_support_handler: IntakeHandler,
+) -> RefundIntakeResult | TechnicalSupportResult | None:
+    """Dispatch to the selected host-side handler, if any."""
+
+    if selected_schema == "refund_intake":
+        return refund_handler.handle(request)
+
+    if selected_schema == "technical_support":
+        return technical_support_handler.handle(request)
+
+    return None
+
+
+def run_demo() -> IntakeRunResult:
+    """Run a small demonstration with refund_intake enabled."""
+
+    engine = create_engine()
+    engine.step("use refund_intake")
+
+    request: IntakeRequest = {
+        "customer_id": "customer-123",
+        "message": "I need a refund for order A-100.",
+    }
+
+    refund_handler = IntakeHandler("refund_intake")
+    technical_support_handler = IntakeHandler("technical_support")
+
+    selected_schema = select_schema_from_state(engine.state)
+    result = run_intake(
+        request,
+        selected_schema=selected_schema,
+        refund_handler=refund_handler,
+        technical_support_handler=technical_support_handler,
+    )
+
+    return {
+        "selected_schema": selected_schema,
+        "refund_handler_called": refund_handler.called,
+        "technical_support_handler_called": technical_support_handler.called,
+        "result": result,
+    }

context_compiler_example_integrations/examples/tool_gating/README.md

@@ -0,0 +1,55 @@
+# Tool gating
+
+These examples show the host deciding which tools exist at runtime and which
+tool calls can execute.
+
+Context Compiler owns the authoritative policy state.
+
+The host owns the tool registry and tool execution.
+
+Adversarial wording does not expose hidden tools or authorize blocked tools.
+
+## Examples
+
+### `calendar_admin`
+
+Exposes a host-owned `calendar_admin_create_event` tool only when state
+contains:
+
+```text
+use calendar_admin
+```
+
+The host hides and blocks the tool when state is absent or when state contains:
+
+```text
+prohibit calendar_admin
+```
+
+The tests cover visible-tool changes, execution blocking, adversarial text, and
+contradiction / clarification behavior.
+
+### `mcp_calendar_admin`
+
+Uses MCP as the integration surface while keeping Context Compiler as the
+authority source.
+
+The host exposes the `calendar_admin_create_event` MCP tool only when state
+contains:
+
+```text
+use calendar_admin
+```
+
+When state is absent or contains:
+
+```text
+prohibit calendar_admin
+```
+
+the MCP tool is absent from the exposed tool set and blocked if invoked
+directly.
+
+This example also includes an opt-in live-model comparison showing that a real
+tool-calling model can only act through the MCP tool surface the host exposes
+from authoritative Context Compiler state.

context_compiler_example_integrations/examples/tool_gating/calendar_admin/README.md

@@ -0,0 +1,34 @@
+# `calendar_admin`
+
+This example shows host-side tool gating with explicit authoritative Context
+Compiler state.
+
+The host owns the tool registry and tool execution.
+
+Context Compiler owns the policy state that decides whether the host exposes
+`calendar_admin_create_event`.
+
+The host exposes and allows the calendar admin tool only when state contains:
+
+```text
+use calendar_admin
+```
+
+The host hides and blocks the calendar admin tool when state is absent or when
+state contains:
+
+```text
+prohibit calendar_admin
+```
+
+Adversarial request text does not enable the tool because the host never derives
+authority from user wording or model output.
+
+The tests cover:
+
+- allowed exposure and execution
+- absent-state hiding and blocking
+- prohibited-state hiding and blocking
+- adversarial text that tries to self-authorize
+- runtime behavior changing only when authoritative state changes
+- contradiction and clarification behavior for conflicting `use` and `prohibit`

context_compiler_example_integrations/examples/tool_gating/calendar_admin/__init__.py

@@ -0,0 +1 @@
+"""Calendar admin tool-gating example."""