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

context_compiler_example_integrations/examples/tool_gating/calendar_admin/example.py

@@ -0,0 +1,195 @@
+"""Host-side tool gating using authoritative Context Compiler state."""
+
+from dataclasses import dataclass
+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 CalendarToolCall(TypedDict):
+    tool_name: str
+    calendar_id: str
+    event_title: str
+
+
+class ToolRegistrySnapshot(TypedDict):
+    available_tools: list[str]
+    hidden_tools: list[str]
+
+
+class CalendarToolExecutionResult(TypedDict):
+    authorization_state: Literal["allowed", "blocked"]
+    tool_visible: bool
+    executed: bool
+    blocked_reason: str | None
+    tool_result: str | None
+    registry_snapshot: ToolRegistrySnapshot
+    execution_log: list[str]
+
+
+class CalendarToolTurnResult(TypedDict):
+    decision_kind: Literal["clarify", "update", "passthrough"]
+    prompt_to_user: str | None
+    execution_result: CalendarToolExecutionResult
+
+
+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 CalendarAdminHost:
+    """Host-owned tool registry and execution layer."""
+
+    execution_log: list[str]
+
+    def __init__(self) -> None:
+        self.execution_log = []
+        self._always_available_tools = ["calendar_view_events"]
+        self._calendar_admin_tools = ["calendar_admin_create_event"]
+
+    def visible_tools(self, state: State) -> ToolRegistrySnapshot:
+        available_tools = self._always_available_tools.copy()
+        hidden_tools = self._calendar_admin_tools.copy()
+
+        if calendar_admin_tools_are_allowed(state):
+            available_tools.extend(self._calendar_admin_tools)
+            hidden_tools = []
+
+        return {
+            "available_tools": available_tools,
+            "hidden_tools": hidden_tools,
+        }
+
+    def execute_calendar_admin_tool(self, tool_call: CalendarToolCall) -> str:
+        self.execution_log.append(
+            f"{tool_call['tool_name']}:{tool_call['calendar_id']}:{tool_call['event_title']}"
+        )
+        return (
+            f"created event '{tool_call['event_title']}' "
+            f"on calendar '{tool_call['calendar_id']}'"
+        )
+
+
+def calendar_admin_tools_are_allowed(state: State) -> bool:
+    """Allow calendar admin tools only from authoritative compiler state."""
+
+    use_items = set(get_policy_items(state, POLICY_USE))
+    prohibit_items = set(get_policy_items(state, POLICY_PROHIBIT))
+
+    if "calendar_admin" in prohibit_items:
+        return False
+
+    return "calendar_admin" in use_items
+
+
+def execute_calendar_admin_tool_if_allowed(
+    tool_call: CalendarToolCall,
+    *,
+    state: State,
+    host: CalendarAdminHost,
+) -> CalendarToolExecutionResult:
+    """Hide or execute the admin tool based only on authoritative state."""
+
+    registry_snapshot = host.visible_tools(state)
+    tool_visible = tool_call["tool_name"] in registry_snapshot["available_tools"]
+
+    if not tool_visible:
+        return {
+            "authorization_state": "blocked",
+            "tool_visible": False,
+            "executed": False,
+            "blocked_reason": "calendar_admin state not authorized",
+            "tool_result": None,
+            "registry_snapshot": registry_snapshot,
+            "execution_log": host.execution_log.copy(),
+        }
+
+    tool_result = host.execute_calendar_admin_tool(tool_call)
+    return {
+        "authorization_state": "allowed",
+        "tool_visible": True,
+        "executed": True,
+        "blocked_reason": None,
+        "tool_result": tool_result,
+        "registry_snapshot": registry_snapshot,
+        "execution_log": host.execution_log.copy(),
+    }
+
+
+def handle_calendar_admin_turn(
+    engine: Engine,
+    *,
+    compiler_input: str,
+    tool_call: CalendarToolCall,
+    host: CalendarAdminHost,
+) -> CalendarToolTurnResult:
+    """Block tool exposure on clarify and otherwise enforce current state."""
+
+    decision = engine.step(compiler_input)
+
+    if is_clarify(decision):
+        return {
+            "decision_kind": "clarify",
+            "prompt_to_user": decision.get("prompt_to_user"),
+            "execution_result": {
+                "authorization_state": "blocked",
+                "tool_visible": False,
+                "executed": False,
+                "blocked_reason": "clarification required before exposing calendar admin tools",
+                "tool_result": None,
+                "registry_snapshot": host.visible_tools(engine.state),
+                "execution_log": host.execution_log.copy(),
+            },
+        }
+
+    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"),
+        "execution_result": execute_calendar_admin_tool_if_allowed(
+            tool_call,
+            state=authoritative_state,
+            host=host,
+        ),
+    }
+
+
+def run_demo() -> CalendarToolExecutionResult:
+    """Run a deterministic demonstration with explicit authorization state."""
+
+    engine = create_engine()
+    engine.step("use calendar_admin")
+    host = CalendarAdminHost()
+
+    return execute_calendar_admin_tool_if_allowed(
+        {
+            "tool_name": "calendar_admin_create_event",
+            "calendar_id": "ops-admin",
+            "event_title": "Quarterly access review",
+        },
+        state=engine.state,
+        host=host,
+    )

context_compiler_example_integrations/examples/tool_gating/mcp_calendar_admin/README.md

@@ -0,0 +1,93 @@
+# `mcp_calendar_admin`
+
+Authoritative state changes whether the host exposes and executes the calendar
+admin MCP tool. This example shows tool gating with MCP as the integration
+surface.
+
+Context Compiler owns the authoritative policy state that decides whether the
+host exposes the calendar admin MCP tool.
+
+The host exposes and allows `calendar_admin_create_event` only when state
+contains:
+
+```text
+use calendar_admin
+```
+
+The host omits that tool from the exposed MCP tool set when state is absent or
+when state contains:
+
+```text
+prohibit calendar_admin
+```
+
+If a caller still invokes the hidden tool directly, the host blocks execution.
+
+Adversarial request text does not expose the tool or mutate policy state.
+
+The provider-free tests are the canonical proof for this example.
+
+This example also includes an opt-in live-model comparison that shows the same
+admin-calendar intent reaches different outcomes because authoritative Context
+Compiler state changes the model-visible tool surface.
+
+## Live-model comparison
+
+The live-model path keeps the same host-owned MCP tool registry and execution
+rules.
+
+The host exposes only the MCP tools allowed by authoritative state, then asks a
+real tool-calling model to complete the same admin action.
+
+The model can only use the tools the host exposes.
+
+This is not prompt reinjection:
+
+- the host does not derive authority from model output
+- the model does not create or mutate authoritative state
+- Context Compiler state determines whether the protected admin tool is visible
+  and executable
+
+### Same request, different state
+
+User intent:
+
+```text
+Create an admin calendar event named Quarterly access review on calendar ops-admin.
+```
+
+Outcome matrix:
+
+- absent state: protected tool is not exposed, and no protected side effect
+  occurs
+- `use calendar_admin`: protected tool is exposed; if the model selects it, the
+  host executes it and writes one side effect
+- contradiction with `prohibit calendar_admin`: Context Compiler returns
+  clarify/conflict and blocks protected execution before tool execution
+
+### Validation
+
+Canonical provider-free tests:
+
+```bash
+uv run --no-sync pytest python/tests/test_mcp_calendar_admin_tool_gating_example.py
+uv run --no-sync pytest python/tests/test_mcp_calendar_admin_live_model_helper.py
+```
+
+Opt-in live-model validation:
+
+```bash
+export RUN_MCP_CALENDAR_ADMIN_LIVE_MODEL=1
+export MODEL=openai/gpt-4o-mini
+export OPENAI_API_KEY=...
+uv run --no-sync pytest python/tests/test_mcp_calendar_admin_live_model.py
+```
+
+This live-model path uses the shared provider contract documented in
+[PROVIDER_CONTRACT.md](../../../../PROVIDER_CONTRACT.md).
+
+Example-specific note for local Ollama:
+
+- this example accepts either `PROVIDER=ollama` with a bare `MODEL` such as
+  `qwen2.5:1.5b-instruct`
+- or an explicit LiteLLM-style `MODEL=ollama/qwen2.5:1.5b-instruct`

context_compiler_example_integrations/examples/tool_gating/mcp_calendar_admin/__init__.py

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

context_compiler_example_integrations/examples/tool_gating/mcp_calendar_admin/example.py

@@ -0,0 +1,250 @@
+"""MCP-surface tool gating using authoritative Context Compiler state."""
+
+from dataclasses import dataclass, field
+from typing import Literal, NotRequired, 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 McpToolDefinition(TypedDict):
+    name: str
+    title: str
+    description: str
+
+
+class McpToolCall(TypedDict):
+    tool_name: str
+    arguments: dict[str, str]
+
+
+class ExposedMcpTools(TypedDict):
+    tools: list[McpToolDefinition]
+    hidden_tool_names: list[str]
+
+
+class McpToolExecutionResult(TypedDict):
+    authorization_state: Literal["allowed", "blocked"]
+    tool_visible: bool
+    executed: bool
+    blocked_reason: str | None
+    tool_result: str | None
+    exposed_tools: ExposedMcpTools
+    execution_log: list[str]
+
+
+class McpToolTurnResult(TypedDict):
+    decision_kind: Literal["clarify", "update", "passthrough"]
+    prompt_to_user: str | None
+    execution_result: McpToolExecutionResult
+
+
+class McpDecisionResult(TypedDict):
+    decision_kind: Literal["clarify", "update", "passthrough"]
+    prompt_to_user: str | None
+    exposed_tools: ExposedMcpTools
+    execution_result: NotRequired[McpToolExecutionResult]
+
+
+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 CalendarAdminMcpHost:
+    """Host-owned MCP registry and execution layer."""
+
+    execution_log: list[str] = field(default_factory=list)
+    _always_available_tools: list[McpToolDefinition] = field(
+        default_factory=lambda: [
+            {
+                "name": "calendar_view_events",
+                "title": "View calendar events",
+                "description": "List visible events from a calendar.",
+            }
+        ]
+    )
+    _calendar_admin_tools: list[McpToolDefinition] = field(
+        default_factory=lambda: [
+            {
+                "name": "calendar_admin_create_event",
+                "title": "Create calendar event",
+                "description": "Create an administrative event on a calendar.",
+            }
+        ]
+    )
+
+    def exposed_mcp_tools(self, state: State) -> ExposedMcpTools:
+        tools = self._always_available_tools.copy()
+        hidden_tool_names = [tool["name"] for tool in self._calendar_admin_tools]
+
+        if calendar_admin_mcp_tools_are_allowed(state):
+            tools.extend(self._calendar_admin_tools)
+            hidden_tool_names = []
+
+        return {
+            "tools": tools,
+            "hidden_tool_names": hidden_tool_names,
+        }
+
+    def execute_mcp_tool(self, tool_call: McpToolCall) -> str:
+        calendar_id = tool_call["arguments"]["calendar_id"]
+        event_title = tool_call["arguments"]["event_title"]
+        self.execution_log.append(
+            f"{tool_call['tool_name']}:{calendar_id}:{event_title}"
+        )
+        return f"created event '{event_title}' on calendar '{calendar_id}'"
+
+
+def calendar_admin_mcp_tools_are_allowed(state: State) -> bool:
+    """Allow admin MCP tools only from authoritative compiler state."""
+
+    use_items = set(get_policy_items(state, POLICY_USE))
+    prohibit_items = set(get_policy_items(state, POLICY_PROHIBIT))
+
+    if "calendar_admin" in prohibit_items:
+        return False
+
+    return "calendar_admin" in use_items
+
+
+def execute_mcp_tool_if_allowed(
+    tool_call: McpToolCall,
+    *,
+    state: State,
+    host: CalendarAdminMcpHost,
+) -> McpToolExecutionResult:
+    """Expose and execute MCP tools only when authoritative state allows them."""
+
+    exposed_tools = host.exposed_mcp_tools(state)
+    visible_tool_names = [tool["name"] for tool in exposed_tools["tools"]]
+    tool_visible = tool_call["tool_name"] in visible_tool_names
+
+    if not tool_visible:
+        return {
+            "authorization_state": "blocked",
+            "tool_visible": False,
+            "executed": False,
+            "blocked_reason": "calendar_admin state not authorized",
+            "tool_result": None,
+            "exposed_tools": exposed_tools,
+            "execution_log": host.execution_log.copy(),
+        }
+
+    tool_result = host.execute_mcp_tool(tool_call)
+    return {
+        "authorization_state": "allowed",
+        "tool_visible": True,
+        "executed": True,
+        "blocked_reason": None,
+        "tool_result": tool_result,
+        "exposed_tools": exposed_tools,
+        "execution_log": host.execution_log.copy(),
+    }
+
+
+def handle_mcp_tool_turn(
+    engine: Engine,
+    *,
+    compiler_input: str,
+    tool_call: McpToolCall,
+    host: CalendarAdminMcpHost,
+) -> McpToolTurnResult:
+    """Block MCP tool exposure on clarify and otherwise enforce current state."""
+
+    decision = engine.step(compiler_input)
+
+    if is_clarify(decision):
+        return {
+            "decision_kind": "clarify",
+            "prompt_to_user": decision.get("prompt_to_user"),
+            "execution_result": {
+                "authorization_state": "blocked",
+                "tool_visible": False,
+                "executed": False,
+                "blocked_reason": "clarification required before exposing calendar admin MCP tools",
+                "tool_result": None,
+                "exposed_tools": host.exposed_mcp_tools(engine.state),
+                "execution_log": host.execution_log.copy(),
+            },
+        }
+
+    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"),
+        "execution_result": execute_mcp_tool_if_allowed(
+            tool_call,
+            state=authoritative_state,
+            host=host,
+        ),
+    }
+
+
+def describe_exposed_mcp_tools(
+    engine: Engine,
+    *,
+    compiler_input: str,
+    host: CalendarAdminMcpHost,
+) -> McpDecisionResult:
+    """Return the currently exposed MCP tools after applying compiler input."""
+
+    decision = engine.step(compiler_input)
+
+    if is_clarify(decision):
+        return {
+            "decision_kind": "clarify",
+            "prompt_to_user": decision.get("prompt_to_user"),
+            "exposed_tools": host.exposed_mcp_tools(engine.state),
+        }
+
+    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"),
+        "exposed_tools": host.exposed_mcp_tools(authoritative_state),
+    }
+
+
+def run_demo() -> McpToolExecutionResult:
+    """Run a deterministic MCP demonstration with explicit authorization state."""
+
+    engine = create_engine()
+    engine.step("use calendar_admin")
+    host = CalendarAdminMcpHost()
+
+    return execute_mcp_tool_if_allowed(
+        {
+            "tool_name": "calendar_admin_create_event",
+            "arguments": {
+                "calendar_id": "ops-admin",
+                "event_title": "Quarterly access review",
+            },
+        },
+        state=engine.state,
+        host=host,
+    )