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

context_compiler_example_integrations/examples/execution_authorization/expense_approval/fastapi/app.py

@@ -0,0 +1,312 @@
+"""FastAPI comparison demo for execution authorization with expense approval."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Literal, cast
+
+from context_compiler import State, create_engine, get_decision_state, is_clarify
+from fastapi import FastAPI, HTTPException
+from pydantic import BaseModel
+from typing_extensions import TypedDict
+
+from context_compiler_example_integrations.examples.execution_authorization.expense_approval.example import (
+    expense_execution_is_authorized,
+)
+
+from .model_approval import ModelApproval, get_model_approval_claim
+
+
+class ExpenseRequest(BaseModel):
+    expense_id: str
+    employee_id: str
+    amount_usd: int
+    note: str
+    authoritative_state: dict[str, object] | None = None
+    compiler_input: str = ""
+    agent_claim: str | None = None
+
+
+class SideEffectRecord(TypedDict):
+    expense_id: str
+    employee_id: str
+    amount_usd: int
+    note: str
+    path: Literal["baseline", "compiler"]
+    model_decision: str
+    authorization_source: Literal["model_claim", "context_compiler_state"]
+
+
+class ExpenseMutationResponse(TypedDict):
+    path: Literal["baseline", "compiler"]
+    decision_kind: Literal["clarify", "update", "passthrough"] | None
+    model_decision: str
+    model_message: str
+    agent_claim: str | None
+    authorization_state: Literal["authorized", "blocked"]
+    executed: bool
+    blocked_reason: str | None
+    prompt_to_user: str | None
+    submission: dict[str, str | int] | None
+    side_effect_path: str
+    side_effect_count: int
+
+
+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 kind_name
+
+
+def _state_for_request(authoritative_state: dict[str, object] | None) -> State | None:
+    if authoritative_state is None:
+        return None
+    return cast(State, authoritative_state)
+
+
+def _expense_summary(request: ExpenseRequest) -> str:
+    return (
+        f"expense_id={request.expense_id}; "
+        f"employee_id={request.employee_id}; "
+        f"amount_usd={request.amount_usd}; "
+        f"note={request.note}"
+    )
+
+
+@dataclass
+class ExpenseSideEffectStore:
+    """Host-owned append-only side-effect artifact for the comparison demo."""
+
+    artifact_path: Path
+
+    def append(
+        self,
+        *,
+        request: ExpenseRequest,
+        path_name: Literal["baseline", "compiler"],
+        model_decision: str,
+        authorization_source: Literal["model_claim", "context_compiler_state"],
+    ) -> dict[str, str | int]:
+        record: SideEffectRecord = {
+            "expense_id": request.expense_id,
+            "employee_id": request.employee_id,
+            "amount_usd": request.amount_usd,
+            "note": request.note,
+            "path": path_name,
+            "model_decision": model_decision,
+            "authorization_source": authorization_source,
+        }
+        self.artifact_path.parent.mkdir(parents=True, exist_ok=True)
+        with self.artifact_path.open("a", encoding="utf-8") as artifact:
+            artifact.write(json.dumps(record, sort_keys=True) + "\n")
+        return {
+            "expense_id": request.expense_id,
+            "employee_id": request.employee_id,
+            "amount_usd": request.amount_usd,
+            "note": request.note,
+        }
+
+    def count(self) -> int:
+        if not self.artifact_path.exists():
+            return 0
+        with self.artifact_path.open(encoding="utf-8") as artifact:
+            return sum(1 for _ in artifact)
+
+
+def _blocked_response(
+    *,
+    path_name: Literal["baseline", "compiler"],
+    model_claim: ModelApproval,
+    side_effect_store: ExpenseSideEffectStore,
+    blocked_reason: str,
+    prompt_to_user: str | None,
+    decision_kind: Literal["clarify", "update", "passthrough"] | None,
+    request_agent_claim: str | None,
+) -> ExpenseMutationResponse:
+    return {
+        "path": path_name,
+        "decision_kind": decision_kind,
+        "model_decision": model_claim.decision,
+        "model_message": model_claim.message,
+        "agent_claim": request_agent_claim,
+        "authorization_state": "blocked",
+        "executed": False,
+        "blocked_reason": blocked_reason,
+        "prompt_to_user": prompt_to_user,
+        "submission": None,
+        "side_effect_path": str(side_effect_store.artifact_path),
+        "side_effect_count": side_effect_store.count(),
+    }
+
+
+def _authorized_response(
+    *,
+    path_name: Literal["baseline", "compiler"],
+    model_claim: ModelApproval,
+    side_effect_store: ExpenseSideEffectStore,
+    submission: dict[str, str | int],
+    decision_kind: Literal["clarify", "update", "passthrough"] | None,
+    request_agent_claim: str | None,
+) -> ExpenseMutationResponse:
+    return {
+        "path": path_name,
+        "decision_kind": decision_kind,
+        "model_decision": model_claim.decision,
+        "model_message": model_claim.message,
+        "agent_claim": request_agent_claim,
+        "authorization_state": "authorized",
+        "executed": True,
+        "blocked_reason": None,
+        "prompt_to_user": None,
+        "submission": submission,
+        "side_effect_path": str(side_effect_store.artifact_path),
+        "side_effect_count": side_effect_store.count(),
+    }
+
+
+def create_app(
+    *,
+    artifact_path: Path | None = None,
+    model_approval_getter: Callable[[str], ModelApproval] = get_model_approval_claim,
+) -> FastAPI:
+    if artifact_path is None:
+        artifact_path = Path(
+            "/tmp/context_compiler_expense_approval/submitted_expenses.jsonl"
+        )
+
+    side_effect_store = ExpenseSideEffectStore(artifact_path=artifact_path)
+    app = FastAPI(title="expense-approval-fastapi-comparison")
+    app.state.side_effect_store = side_effect_store
+
+    @app.post("/baseline/expenses")
+    def submit_baseline_expense(request: ExpenseRequest) -> ExpenseMutationResponse:
+        model_claim = model_approval_getter(_expense_summary(request))
+        if not model_claim.is_approved:
+            raise HTTPException(
+                status_code=403,
+                detail=_blocked_response(
+                    path_name="baseline",
+                    model_claim=model_claim,
+                    side_effect_store=side_effect_store,
+                    blocked_reason="model claim did not approve expense",
+                    prompt_to_user=None,
+                    decision_kind=None,
+                    request_agent_claim=request.agent_claim,
+                ),
+            )
+
+        submission = side_effect_store.append(
+            request=request,
+            path_name="baseline",
+            model_decision=model_claim.decision,
+            authorization_source="model_claim",
+        )
+        return _authorized_response(
+            path_name="baseline",
+            model_claim=model_claim,
+            side_effect_store=side_effect_store,
+            submission=submission,
+            decision_kind=None,
+            request_agent_claim=request.agent_claim,
+        )
+
+    @app.post("/compiler/expenses")
+    def submit_compiler_mediated_expense(
+        request: ExpenseRequest,
+    ) -> ExpenseMutationResponse:
+        model_claim = model_approval_getter(_expense_summary(request))
+        if not model_claim.is_approved:
+            raise HTTPException(
+                status_code=403,
+                detail=_blocked_response(
+                    path_name="compiler",
+                    model_claim=model_claim,
+                    side_effect_store=side_effect_store,
+                    blocked_reason="model claim did not approve expense",
+                    prompt_to_user=None,
+                    decision_kind=None,
+                    request_agent_claim=request.agent_claim,
+                ),
+            )
+
+        engine = create_engine(state=_state_for_request(request.authoritative_state))
+        decision_kind: Literal["clarify", "update", "passthrough"] | None = None
+        prompt_to_user: str | None = None
+        authoritative_state = engine.state
+
+        if request.compiler_input:
+            decision = engine.step(request.compiler_input)
+            decision_kind = _decision_kind_name(decision)
+            prompt_to_user = decision.get("prompt_to_user")
+            if is_clarify(decision):
+                raise HTTPException(
+                    status_code=409,
+                    detail=_blocked_response(
+                        path_name="compiler",
+                        model_claim=model_claim,
+                        side_effect_store=side_effect_store,
+                        blocked_reason=(
+                            "clarification required before expense execution"
+                        ),
+                        prompt_to_user=prompt_to_user,
+                        decision_kind=decision_kind,
+                        request_agent_claim=request.agent_claim,
+                    ),
+                )
+
+            decision_state = get_decision_state(decision)
+            authoritative_state = (
+                decision_state if decision_state is not None else engine.state
+            )
+
+        if not expense_execution_is_authorized(authoritative_state):
+            raise HTTPException(
+                status_code=403,
+                detail=_blocked_response(
+                    path_name="compiler",
+                    model_claim=model_claim,
+                    side_effect_store=side_effect_store,
+                    blocked_reason="expense_approval state not authorized",
+                    prompt_to_user=prompt_to_user,
+                    decision_kind=decision_kind,
+                    request_agent_claim=request.agent_claim,
+                ),
+            )
+
+        submission = side_effect_store.append(
+            request=request,
+            path_name="compiler",
+            model_decision=model_claim.decision,
+            authorization_source="context_compiler_state",
+        )
+        return _authorized_response(
+            path_name="compiler",
+            model_claim=model_claim,
+            side_effect_store=side_effect_store,
+            submission=submission,
+            decision_kind=decision_kind,
+            request_agent_claim=request.agent_claim,
+        )
+
+    return app
+
+
+app = create_app()
+
+
+if __name__ == "__main__":
+    print(
+        "Run with: uv run fastapi dev "
+        "python/examples/execution_authorization/expense_approval/fastapi/app.py"
+    )

context_compiler_example_integrations/examples/execution_authorization/expense_approval/fastapi/model_approval.py

@@ -0,0 +1,98 @@
+"""Minimal provider-backed approval claim helper for the FastAPI demo."""
+
+from __future__ import annotations
+
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from importlib import import_module
+from typing import cast
+
+from context_compiler_example_integrations.examples._shared.litellm_request import (
+    build_litellm_provider_kwargs,
+)
+from context_compiler_example_integrations.examples._shared.provider_mode import (
+    print_startup_config,
+    resolve_provider_config,
+)
+
+
+@dataclass(frozen=True)
+class ModelApproval:
+    decision: str
+    message: str
+
+    @property
+    def is_approved(self) -> bool:
+        return self.decision == "approved"
+
+
+def _get_litellm_completion() -> Callable[..., object]:
+    litellm_module = import_module("litellm")
+    return cast(Callable[..., object], litellm_module.completion)
+
+
+def _extract_response_content(response: object) -> str | None:
+    if isinstance(response, Mapping):
+        choices = response.get("choices")
+        if isinstance(choices, list) and choices:
+            first = choices[0]
+            if isinstance(first, Mapping):
+                message = first.get("message")
+                if isinstance(message, Mapping):
+                    content = message.get("content")
+                    if isinstance(content, str):
+                        return content
+
+    choices_attr = getattr(response, "choices", None)
+    if isinstance(choices_attr, list) and choices_attr:
+        first = choices_attr[0]
+        message_attr = getattr(first, "message", None)
+        content_attr = getattr(message_attr, "content", None)
+        if isinstance(content_attr, str):
+            return content_attr
+
+    return None
+
+
+def classify_model_approval(message: str) -> str:
+    normalized = message.strip().lower()
+    if normalized.startswith("approved"):
+        return "approved"
+    if " approved" in f" {normalized} ":
+        return "approved"
+    return "not_approved"
+
+
+def get_model_approval_claim(expense_summary: str) -> ModelApproval:
+    """Return an approval-class claim from a live provider."""
+
+    try:
+        completion = _get_litellm_completion()
+    except ModuleNotFoundError as exc:
+        raise RuntimeError(
+            "litellm is required. Install with: pip install litellm"
+        ) from exc
+
+    config = resolve_provider_config(default_model="openai/gpt-4o-mini")
+    print_startup_config(config)
+
+    prompt = (
+        "You are an expense approver.\n"
+        "Reply with a short decision line that starts with APPROVED or DENIED.\n"
+        "Expense:\n"
+        f"{expense_summary}"
+    )
+    kwargs: dict[str, object] = {
+        **build_litellm_provider_kwargs(config),
+        "messages": [{"role": "user", "content": prompt}],
+    }
+
+    response = completion(**kwargs)
+    message = _extract_response_content(response)
+    if message is None:
+        raise RuntimeError("LiteLLM response missing choices[0].message.content")
+
+    return ModelApproval(
+        decision=classify_model_approval(message),
+        message=message,
+    )

context_compiler_example_integrations/examples/gateway_middleware/README.md

@@ -0,0 +1,49 @@
+# Gateway middleware
+
+These examples show a host-owned gateway making an allow / block / route
+decision before any downstream service call happens.
+
+Context Compiler owns the authoritative policy state.
+
+The host owns the gateway boundary, the default route, and the downstream
+handler invocation.
+
+Adversarial wording does not bypass the gateway or mutate authoritative state.
+
+## Examples
+
+### `customer_support_routing`
+
+Routes a host-owned customer support request to `billing_support` only when
+authoritative state contains:
+
+```text
+use billing_support
+```
+
+If state is absent, the gateway blocks billing-routed requests and still allows
+non-billing requests to follow the documented default path,
+`general_support`.
+
+If state contains:
+
+```text
+prohibit billing_support
+```
+
+the gateway blocks billing-routed requests before the downstream handler is
+called.
+
+The tests cover default-path behavior, authorized routing, blocked routing,
+adversarial text, downstream non-invocation when blocked, and contradiction /
+clarification behavior.
+
+## Related integrations
+
+The generic example teaches the gateway-middleware enforcement point in a small
+host-owned flow.
+
+For a concrete proxy runtime surface, see the LiteLLM Proxy reference
+integration:
+
+- [python/reference_integrations/litellm_proxy/README.md](../../reference_integrations/litellm_proxy/README.md)

context_compiler_example_integrations/examples/gateway_middleware/customer_support_routing/README.md

@@ -0,0 +1,40 @@
+# Customer support routing
+
+Authoritative state changes whether the gateway lets a billing request reach
+the downstream support handler. This example shows that gateway behavior in a
+host-owned customer support routing flow.
+
+The gateway calls the downstream support service only after it allows the
+request.
+
+## Policy mapping
+
+The gateway routes a billing request to `billing_support` only when state
+contains:
+
+```text
+use billing_support
+```
+
+If state is absent, the gateway blocks billing requests.
+
+If state contains:
+
+```text
+prohibit billing_support
+```
+
+the gateway also blocks billing requests.
+
+Requests that are not asking for billing support follow the host's documented
+default path, `general_support`.
+
+## What this example demonstrates
+
+- Context Compiler owns authoritative policy state.
+- The host owns the gateway middleware boundary and the downstream call.
+- Adversarial request text does not bypass the gateway decision.
+- Contradictory `use billing_support` and `prohibit billing_support` inputs
+  produce clarification behavior instead of a silent overwrite.
+- The example does not call an LLM, does not use directive drafter, and does
+  not derive state from model output.

context_compiler_example_integrations/examples/gateway_middleware/customer_support_routing/__init__.py

@@ -0,0 +1 @@
+"""Generic gateway middleware example for customer support routing."""