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

context_compiler_example_integrations/examples/tool_gating/mcp_calendar_admin/live_model.py

@@ -0,0 +1,369 @@
+"""Opt-in live-model tool-gating comparison for MCP calendar admin."""
+
+from __future__ import annotations
+
+import json
+from collections.abc import Callable, Mapping
+from dataclasses import dataclass
+from importlib import import_module
+from pathlib import Path
+from typing import Literal, TypedDict, cast
+
+from context_compiler import State, create_engine, get_decision_state, is_clarify
+
+from context_compiler_example_integrations.examples._shared.litellm_request import (
+    build_litellm_provider_kwargs,
+)
+from context_compiler_example_integrations.examples.tool_gating.mcp_calendar_admin.example import (
+    CalendarAdminMcpHost,
+    McpToolCall,
+)
+from context_compiler_example_integrations.examples._shared.provider_mode import (
+    print_startup_config,
+    resolve_provider_config,
+)
+
+
+class SideEffectRecord(TypedDict):
+    tool_name: str
+    calendar_id: str
+    event_title: str
+    authorization_source: Literal["context_compiler_state"]
+
+
+class LiveModelResult(TypedDict):
+    decision_kind: Literal["clarify", "update", "passthrough"] | None
+    prompt_to_user: str | None
+    exposed_tool_names: list[str]
+    hidden_tool_names: list[str]
+    protected_tool_exposed: bool
+    model_selected_tool_name: str | None
+    executed: bool
+    blocked_reason: str | None
+    tool_result: str | None
+    execution_log: list[str]
+    side_effect_path: str
+    side_effect_count: int
+
+
+class _LiteLLMCallKwargs(TypedDict, total=False):
+    model: str
+    messages: list[dict[str, str]]
+    tools: list[dict[str, object]]
+    tool_choice: str
+    temperature: float
+    drop_params: bool
+    api_base: str
+    api_key: str
+
+
+@dataclass(frozen=True)
+class _SelectedToolCall:
+    name: str | None
+    arguments: dict[str, str]
+
+
+@dataclass
+class CalendarAdminSideEffectStore:
+    """Host-owned append-only artifact for successful protected execution."""
+
+    artifact_path: Path
+
+    def append(self, *, tool_call: McpToolCall) -> None:
+        record: SideEffectRecord = {
+            "tool_name": tool_call["tool_name"],
+            "calendar_id": tool_call["arguments"]["calendar_id"],
+            "event_title": tool_call["arguments"]["event_title"],
+            "authorization_source": "context_compiler_state",
+        }
+        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")
+
+    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 _get_litellm_completion() -> Callable[..., object]:
+    litellm_module = import_module("litellm")
+    return cast(Callable[..., object], litellm_module.completion)
+
+
+def _state_for_request(authoritative_state: State | None) -> State | None:
+    return authoritative_state
+
+
+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 _exposed_tool_names(
+    host: CalendarAdminMcpHost, state: State
+) -> tuple[list[str], list[str]]:
+    exposed_tools = host.exposed_mcp_tools(state)
+    return (
+        [tool["name"] for tool in exposed_tools["tools"]],
+        exposed_tools["hidden_tool_names"],
+    )
+
+
+def _build_openai_tools(
+    host: CalendarAdminMcpHost, state: State
+) -> list[dict[str, object]]:
+    exposed_tools = host.exposed_mcp_tools(state)["tools"]
+    tools: list[dict[str, object]] = []
+    for tool in exposed_tools:
+        if tool["name"] == "calendar_view_events":
+            input_schema: dict[str, object] = {
+                "type": "object",
+                "properties": {
+                    "calendar_id": {
+                        "type": "string",
+                        "description": "Calendar identifier to inspect.",
+                    }
+                },
+                "required": ["calendar_id"],
+                "additionalProperties": False,
+            }
+        elif tool["name"] == "calendar_admin_create_event":
+            input_schema = {
+                "type": "object",
+                "properties": {
+                    "calendar_id": {
+                        "type": "string",
+                        "description": "Administrative calendar identifier.",
+                    },
+                    "event_title": {
+                        "type": "string",
+                        "description": "Administrative event title to create.",
+                    },
+                },
+                "required": ["calendar_id", "event_title"],
+                "additionalProperties": False,
+            }
+        else:
+            continue
+
+        tools.append(
+            {
+                "type": "function",
+                "function": {
+                    "name": tool["name"],
+                    "description": tool["description"],
+                    "parameters": input_schema,
+                },
+            }
+        )
+    return tools
+
+
+def _build_messages(user_intent: str) -> list[dict[str, str]]:
+    return [
+        {
+            "role": "system",
+            "content": (
+                "You are a careful assistant.\n"
+                "Use a tool if one is available to complete the user's request.\n"
+                "Do not invent unavailable tools."
+            ),
+        },
+        {"role": "user", "content": user_intent},
+    ]
+
+
+def _mapping_value(obj: object, key: str) -> object | None:
+    if isinstance(obj, Mapping):
+        return obj.get(key)
+    return getattr(obj, key, None)
+
+
+def _extract_selected_tool_call(response: object) -> _SelectedToolCall:
+    choices = _mapping_value(response, "choices")
+    if not isinstance(choices, list) or not choices:
+        choices = getattr(response, "choices", None)
+    if not isinstance(choices, list) or not choices:
+        return _SelectedToolCall(name=None, arguments={})
+
+    message = _mapping_value(choices[0], "message")
+    if message is None:
+        return _SelectedToolCall(name=None, arguments={})
+
+    tool_calls = _mapping_value(message, "tool_calls")
+    if not isinstance(tool_calls, list) or not tool_calls:
+        return _SelectedToolCall(name=None, arguments={})
+
+    first_tool_call = tool_calls[0]
+    function_payload = _mapping_value(first_tool_call, "function")
+    if function_payload is None:
+        return _SelectedToolCall(name=None, arguments={})
+
+    name = _mapping_value(function_payload, "name")
+    raw_arguments = _mapping_value(function_payload, "arguments")
+    if not isinstance(name, str):
+        return _SelectedToolCall(name=None, arguments={})
+
+    if isinstance(raw_arguments, str):
+        decoded_arguments = json.loads(raw_arguments)
+    elif isinstance(raw_arguments, Mapping):
+        decoded_arguments = dict(raw_arguments)
+    else:
+        decoded_arguments = {}
+
+    arguments = {
+        key: str(value)
+        for key, value in decoded_arguments.items()
+        if isinstance(key, str)
+    }
+    return _SelectedToolCall(name=name, arguments=arguments)
+
+
+def _call_live_model(
+    *, user_intent: str, tools: list[dict[str, object]]
+) -> _SelectedToolCall:
+    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)
+
+    kwargs: _LiteLLMCallKwargs = {
+        **build_litellm_provider_kwargs(config),
+        "messages": _build_messages(user_intent),
+        "tools": tools,
+        "tool_choice": "auto",
+    }
+
+    response = completion(**kwargs)
+    return _extract_selected_tool_call(response)
+
+
+def run_live_model_turn(
+    *,
+    user_intent: str,
+    authoritative_state: State | None = None,
+    compiler_input: str = "",
+    artifact_path: Path | None = None,
+    model_tool_selector: Callable[..., _SelectedToolCall] | None = None,
+) -> LiveModelResult:
+    """Run one tool-gated turn with a live model or injected selector."""
+
+    if artifact_path is None:
+        artifact_path = Path(
+            "/tmp/context_compiler_mcp_calendar_admin/tool_calls.jsonl"
+        )
+
+    side_effect_store = CalendarAdminSideEffectStore(artifact_path=artifact_path)
+    host = CalendarAdminMcpHost()
+    engine = create_engine(state=_state_for_request(authoritative_state))
+    decision_kind: Literal["clarify", "update", "passthrough"] | None = None
+    prompt_to_user: str | None = None
+    effective_state = engine.state
+
+    if compiler_input:
+        decision = engine.step(compiler_input)
+        decision_kind = _decision_kind_name(decision)
+        prompt_to_user = decision.get("prompt_to_user")
+        if is_clarify(decision):
+            exposed_tool_names, hidden_tool_names = _exposed_tool_names(
+                host, engine.state
+            )
+            return {
+                "decision_kind": decision_kind,
+                "prompt_to_user": prompt_to_user,
+                "exposed_tool_names": exposed_tool_names,
+                "hidden_tool_names": hidden_tool_names,
+                "protected_tool_exposed": "calendar_admin_create_event"
+                in exposed_tool_names,
+                "model_selected_tool_name": None,
+                "executed": False,
+                "blocked_reason": (
+                    "clarification required before exposing calendar admin MCP tools"
+                ),
+                "tool_result": None,
+                "execution_log": host.execution_log.copy(),
+                "side_effect_path": str(side_effect_store.artifact_path),
+                "side_effect_count": side_effect_store.count(),
+            }
+
+        decision_state = get_decision_state(decision)
+        effective_state = decision_state if decision_state is not None else engine.state
+
+    exposed_tool_names, hidden_tool_names = _exposed_tool_names(host, effective_state)
+    protected_tool_exposed = "calendar_admin_create_event" in exposed_tool_names
+    tools = _build_openai_tools(host, effective_state)
+    selector = model_tool_selector or _call_live_model
+    selected_tool_call = selector(user_intent=user_intent, tools=tools)
+
+    if selected_tool_call.name != "calendar_admin_create_event":
+        return {
+            "decision_kind": decision_kind,
+            "prompt_to_user": prompt_to_user,
+            "exposed_tool_names": exposed_tool_names,
+            "hidden_tool_names": hidden_tool_names,
+            "protected_tool_exposed": protected_tool_exposed,
+            "model_selected_tool_name": selected_tool_call.name,
+            "executed": False,
+            "blocked_reason": (
+                "model did not select protected admin tool"
+                if protected_tool_exposed
+                else "protected admin tool was not exposed to the model"
+            ),
+            "tool_result": None,
+            "execution_log": host.execution_log.copy(),
+            "side_effect_path": str(side_effect_store.artifact_path),
+            "side_effect_count": side_effect_store.count(),
+        }
+
+    if not protected_tool_exposed:
+        return {
+            "decision_kind": decision_kind,
+            "prompt_to_user": prompt_to_user,
+            "exposed_tool_names": exposed_tool_names,
+            "hidden_tool_names": hidden_tool_names,
+            "protected_tool_exposed": False,
+            "model_selected_tool_name": selected_tool_call.name,
+            "executed": False,
+            "blocked_reason": "calendar_admin state not authorized",
+            "tool_result": None,
+            "execution_log": host.execution_log.copy(),
+            "side_effect_path": str(side_effect_store.artifact_path),
+            "side_effect_count": side_effect_store.count(),
+        }
+
+    tool_call: McpToolCall = {
+        "tool_name": "calendar_admin_create_event",
+        "arguments": selected_tool_call.arguments,
+    }
+    tool_result = host.execute_mcp_tool(tool_call)
+    side_effect_store.append(tool_call=tool_call)
+    return {
+        "decision_kind": decision_kind,
+        "prompt_to_user": prompt_to_user,
+        "exposed_tool_names": exposed_tool_names,
+        "hidden_tool_names": hidden_tool_names,
+        "protected_tool_exposed": True,
+        "model_selected_tool_name": selected_tool_call.name,
+        "executed": True,
+        "blocked_reason": None,
+        "tool_result": tool_result,
+        "execution_log": host.execution_log.copy(),
+        "side_effect_path": str(side_effect_store.artifact_path),
+        "side_effect_count": side_effect_store.count(),
+    }

context_compiler_example_integrations/reference_integrations/__init__.py

@@ -0,0 +1,12 @@
+"""Reference integrations 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" / "reference_integrations"
+
+__path__ = [str(_PACKAGE_DIR)]
+if _SOURCE_DIR.is_dir():
+    __path__.append(str(_SOURCE_DIR))

context_compiler_example_integrations/reference_integrations/litellm_proxy/README.md

@@ -0,0 +1,251 @@
+# LiteLLM Proxy (pre-call hook)
+
+Saved compiler state changes whether LiteLLM Proxy blocks a request, forwards
+it unchanged, or injects compiler state before the downstream call. This
+example shows LiteLLM Proxy acting as the host-owned gateway surface.
+
+Context Compiler is the authority layer for saved state. These hooks no longer
+derive authority from transcript history. They process only the latest user
+turn and rely on host-owned checkpoints for continuity.
+
+Available hook files:
+
+- Basic checkpoint-backed hook: `context_compiler_precall_hook.py`
+- Directive-drafter-enabled checkpoint-backed hook:
+  `context_compiler_precall_hook_with_directive_drafter.py`
+
+## Runtime behavior
+
+- LiteLLM Proxy is the gateway surface; Context Compiler remains the authority
+  layer for saved state.
+- By default, the hooks run in stateless mode and process only the latest user
+  turn with a fresh engine.
+- In explicit persistent mode, the hook resolves a session key, loads a saved
+  checkpoint, restores the engine, processes the latest user turn once, and
+  saves the resulting checkpoint after every decision, including `clarify`.
+- In stateless mode, no continuity is preserved across requests.
+- If result is `clarify`, the proxy does not call the downstream model and
+  LiteLLM surfaces the clarification as an HTTP 400 response.
+- If result is `passthrough`, the proxy forwards the request normally.
+- If result is `update`, the proxy injects compiler state as a system message
+  and then calls the model.
+- Unsupported LiteLLM callback `call_type` values return the original request
+  data unchanged.
+
+Optional directive-drafter behavior:
+
+- The drafter runs only on the current/latest user turn.
+- The hook restores checkpoints before drafting.
+- Heuristic runs first; if no directive is found, LLM fallback is attempted.
+- Forwarded upstream request messages are not rewritten except for the injected
+  compiler system message.
+
+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.
+
+## Session mode and session keys
+
+The reference hooks support two explicit modes:
+
+- `persistent`
+  - explicit mode
+  - requires a stable session key
+  - preserves saved state and pending clarification across requests
+- `stateless`
+  - default mode
+  - processes only the latest user turn
+  - preserves no continuity
+
+Set the mode with one of:
+
+- top-level request field `context_compiler_mode`
+- env var `CONTEXT_COMPILER_SESSION_MODE`
+
+Persistent mode resolves session keys in this order:
+
+1. `context_compiler_session_key`
+2. `metadata.context_compiler_session_key`
+
+If persistent mode cannot resolve a stable session key, the hook fails clearly
+and does not fall back to transcript replay or implicit stateless behavior.
+
+## Checkpoint store contract
+
+The hooks share a small repo-local support module:
+
+```python
+class CheckpointStore(Protocol):
+    def load(self, session_key: str) -> Mapping[str, object] | None: ...
+    def save(self, session_key: str, checkpoint: Mapping[str, object]) -> None: ...
+```
+
+The reference implementation uses an in-memory store for tests and local demos.
+It is single-process only:
+
+- no durability across restarts
+- no multi-worker coordination
+- no atomic compare-and-swap
+- no expiration/cleanup policy
+
+Real deployments should replace it with a host-owned store such as Redis or a
+database-backed implementation.
+
+## Requirements
+
+```shell
+pip install "context-compiler-example-integrations[litellm]"
+export OPENAI_API_KEY=...
+```
+
+Start with the compiler-only hook. Add `context-compiler-directive-drafter`
+only if you want the optional directive-drafter variant.
+
+For `context_compiler_precall_hook_with_directive_drafter.py`:
+
+```shell
+pip install "context-compiler-example-integrations[all]"
+```
+
+That variant requires `context-compiler-directive-drafter>=0.1.2`.
+
+For the opt-in runtime smoke test, install the proxy runtime extras:
+
+```shell
+uv sync --group proxy_runtime --no-editable
+```
+
+## Quickstart (copy/paste)
+
+From the repo root:
+
+```shell
+pip install "context-compiler-example-integrations[litellm]"
+export OPENAI_API_KEY=...
+litellm --config python/reference_integrations/litellm_proxy/config.example.yaml
+```
+
+`config.example.yaml` includes both OpenAI and Ollama model definitions.
+Use the Ollama model entry for local testing without API credentials.
+
+## Make a request
+
+```python
+from openai import OpenAI
+
+client = OpenAI(
+    api_key="anything",
+    base_url="http://localhost:4000",
+)
+
+response = client.chat.completions.create(
+    model="gpt-4o-mini",
+    messages=[{"role": "user", "content": "prohibit peanuts"}],
+    extra_body={"context_compiler_session_key": "demo-chat"},
+)
+```
+
+Or with curl:
+
+```shell
+curl http://localhost:4000/v1/chat/completions \
+  -H "Content-Type: application/json" \
+  -H "Authorization: Bearer anything" \
+  -d '{
+    "model": "gpt-4o-mini",
+    "context_compiler_session_key": "demo-chat",
+    "messages": [{"role": "user", "content": "prohibit peanuts"}]
+  }'
+```
+
+For explicit stateless mode:
+
+```json
+{
+  "model": "gpt-4o-mini",
+  "context_compiler_mode": "stateless",
+  "messages": [{"role": "user", "content": "prohibit peanuts"}]
+}
+```
+
+For explicit persistent mode:
+
+```json
+{
+  "model": "gpt-4o-mini",
+  "context_compiler_mode": "persistent",
+  "context_compiler_session_key": "demo-chat",
+  "messages": [{"role": "user", "content": "prohibit peanuts"}]
+}
+```
+
+## Run proxy
+
+The reference integration is covered by unit tests and an opt-in runtime smoke
+test. See "Opt-in Runtime Smoke Test" below for details.
+
+The proxy runs on `http://localhost:4000` by default. By default,
+`config.example.yaml` points to the basic checkpoint-backed hook. To use the
+directive-drafter variant, switch the callback path in the config. The callback
+path must be importable by LiteLLM in the environment where the proxy process
+starts.
+
+When starting LiteLLM from the repo root, prefer fully qualified callback
+imports in automated configs, for example:
+
+```text
+python.reference_integrations.litellm_proxy.context_compiler_precall_hook.proxy_handler_instance
+```
+
+Optional env vars for directive-drafter fallback:
+
+```shell
+export PREPROCESSOR_MODEL=openai/gpt-4o-mini
+export PREPROCESSOR_PROMPT_PROFILE=default
+```
+
+`PREPROCESSOR_MODEL` is optional and defaults to `MODEL`.
+
+For heuristic-first usage, keep `PREPROCESSOR_PROMPT_PROFILE=default`.
+Use `llama` only for LLM-only fallback drafting with Llama-family models.
+
+## Notes
+
+- Mixed-content user messages compile only text segments from the latest user
+  turn.
+- `MODEL` and `PREPROCESSOR_MODEL` use LiteLLM format: `<provider>/<model>`.
+- Corrupt or incompatible checkpoints fail clearly in persistent mode and do
+  not silently reset state.
+- In the directive-drafter hook, drafter state context now comes from restored
+  checkpoint state rather than transcript-prefix reconstruction.
+- Compound directive-shaped input such as `use docker and prohibit peanuts`
+  should produce a local clarify response telling the user to submit each
+  directive separately, without mutating saved state or forwarding upstream.
+
+## Troubleshooting
+
+- callback import failures: verify the callback path configured in
+  `config.example.yaml` is importable in the current LiteLLM environment
+- persistent mode rejects requests: provide a stable session key or opt into
+  explicit `stateless` mode
+- proxy starts but upstream calls fail: check `OPENAI_API_KEY` and upstream
+  model/provider config in `config.example.yaml`
+- directive-drafter fallback issues: `PREPROCESSOR_MODEL` defaults to `MODEL`;
+  set it explicitly only when using a separate fallback model
+
+## Opt-in Runtime Smoke Test
+
+This repo includes an opt-in runtime smoke test for the LiteLLM Proxy
+reference integration. The test starts a real LiteLLM Proxy process, runs the
+basic hook and the directive-drafter hook in separate proxy launches, sends
+local requests through the proxy with explicit session keys, verifies blocked
+requests do not reach upstream, verifies allowed requests reach a local stub
+upstream with the injected compiler contract, verifies the directive-drafter
+path preserves the original forwarded user prompt text, and shuts each proxy
+down cleanly.
+
+It is intentionally not part of `./scripts/validate_python.sh`.
+
+Run it from the repo root:
+
+```shell
+RUN_LITELLM_PROXY_RUNTIME=1 uv run --group proxy_runtime pytest python/tests/test_litellm_proxy_runtime.py
+```