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

context_compiler_example_integrations/examples/retrieval_filtering/hr_policy_lookup/example.py

@@ -0,0 +1,300 @@
+"""Minimal retrieval-filtering example for HR policy lookup."""
+
+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,
+    get_premise_value,
+    is_clarify,
+)
+from context_compiler.engine import Engine
+
+EMPLOYEE_ACCESS = "employee_hr_access"
+MANAGER_ACCESS = "manager_hr_access"
+LEAVE_CASE_PREMISE = "case concerns leave eligibility after a parental leave request"
+GENERAL_HANDBOOK_PREMISE = (
+    "case concerns general employee handbook expectations for a new hire"
+)
+STAFFING_CASE_PREMISE = "case concerns staffing approval for a team reorganization"
+
+
+class PolicyDocument(TypedDict):
+    document_id: str
+    title: str
+    audience: Literal["employee", "manager", "executive"]
+    keywords: list[str]
+    relevance_tags: list[str]
+    content: str
+
+
+class RetrievalResult(TypedDict):
+    query: str
+    eligible_document_ids: list[str]
+    returned_document_ids: list[str]
+    blocked_reason: str | None
+
+
+class RetrievalTurnResult(TypedDict):
+    decision_kind: Literal["clarify", "update", "passthrough"]
+    prompt_to_user: str | None
+    retrieval_result: RetrievalResult
+
+
+CaseContext = Literal["general_handbook_case", "leave_case", "staffing_case"]
+
+
+@dataclass
+class HRPolicyRetriever:
+    """Host-owned retrieval implementation with deterministic filtering."""
+
+    documents: list[PolicyDocument] = field(default_factory=list)
+
+    def search(
+        self,
+        query: str,
+        *,
+        allowed_audiences: set[str],
+        case_context: CaseContext | None,
+    ) -> RetrievalResult:
+        eligible_documents = [
+            document
+            for document in self.documents
+            if document["audience"] in allowed_audiences
+        ]
+        relevance_filtered_documents = filter_documents_by_case_context(
+            eligible_documents,
+            case_context,
+        )
+        normalized_query_terms = set(query.lower().split())
+        returned_documents = [
+            document
+            for document in relevance_filtered_documents
+            if normalized_query_terms & set(document["keywords"])
+        ]
+
+        return {
+            "query": query,
+            "eligible_document_ids": [
+                document["document_id"] for document in eligible_documents
+            ],
+            "returned_document_ids": [
+                document["document_id"] for document in returned_documents
+            ],
+            "blocked_reason": None,
+        }
+
+
+def example_documents() -> list[PolicyDocument]:
+    return [
+        {
+            "document_id": "employee_handbook",
+            "title": "Employee Handbook",
+            "audience": "employee",
+            "keywords": ["employee", "handbook", "benefits", "leave"],
+            "relevance_tags": ["general_handbook_case", "general_hr"],
+            "content": "General HR policy, leave policy, and workplace expectations.",
+        },
+        {
+            "document_id": "leave_of_absence_policy",
+            "title": "Leave of Absence Policy",
+            "audience": "employee",
+            "keywords": ["leave", "eligibility", "parental"],
+            "relevance_tags": ["leave_case"],
+            "content": "Leave eligibility, parental leave steps, and required documentation.",
+        },
+        {
+            "document_id": "manager_handbook",
+            "title": "Manager Handbook",
+            "audience": "manager",
+            "keywords": ["manager", "handbook", "approvals", "staffing"],
+            "relevance_tags": ["general_handbook_case", "staffing_case"],
+            "content": "Manager escalation guidance, staffing policy, and approvals.",
+        },
+        {
+            "document_id": "executive_compensation_policy",
+            "title": "Executive Compensation Policy",
+            "audience": "executive",
+            "keywords": ["executive", "compensation", "bonus", "board"],
+            "relevance_tags": ["executive_only"],
+            "content": "Executive compensation bands, board review, and bonus structure.",
+        },
+    ]
+
+
+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)
+
+
+def allowed_audiences_from_state(state: State) -> set[str]:
+    """Read allowed retrieval audiences from authoritative compiler state."""
+
+    use_items = set(get_policy_items(state, POLICY_USE))
+    prohibit_items = set(get_policy_items(state, POLICY_PROHIBIT))
+
+    if MANAGER_ACCESS in prohibit_items:
+        return set()
+
+    if MANAGER_ACCESS in use_items:
+        return {"employee", "manager"}
+
+    if EMPLOYEE_ACCESS in prohibit_items:
+        return set()
+
+    if EMPLOYEE_ACCESS in use_items:
+        return {"employee"}
+
+    return set()
+
+
+def classify_premise_as_case_context(premise: str | None) -> CaseContext | None:
+    """Map saved HR case facts to a host-owned retrieval relevance context."""
+
+    if premise is None:
+        return None
+
+    normalized_premise = premise.casefold()
+    if (
+        "general employee handbook" in normalized_premise
+        and "new hire" in normalized_premise
+    ):
+        return "general_handbook_case"
+
+    if (
+        "leave eligibility" in normalized_premise
+        and "parental leave" in normalized_premise
+    ):
+        return "leave_case"
+
+    if (
+        "staffing approval" in normalized_premise
+        and "team reorganization" in normalized_premise
+    ):
+        return "staffing_case"
+
+    return None
+
+
+def filter_documents_by_case_context(
+    documents: list[PolicyDocument],
+    case_context: CaseContext | None,
+) -> list[PolicyDocument]:
+    """Limit relevance only within the already eligible document set."""
+
+    if case_context is None:
+        return [
+            document
+            for document in documents
+            if "general_handbook_case" in document["relevance_tags"]
+        ]
+
+    relevant_documents = [
+        document for document in documents if case_context in document["relevance_tags"]
+    ]
+    if relevant_documents:
+        return relevant_documents
+
+    return []
+
+
+def retrieve_hr_documents(
+    query: str,
+    *,
+    state: State,
+    retriever: HRPolicyRetriever,
+) -> RetrievalResult:
+    """Retrieve only documents the host deems eligible from compiler state."""
+
+    premise = get_premise_value(state)
+    return retriever.search(
+        query,
+        allowed_audiences=allowed_audiences_from_state(state),
+        case_context=classify_premise_as_case_context(premise),
+    )
+
+
+def handle_retrieval_turn(
+    engine: Engine,
+    *,
+    compiler_input: str,
+    query: str,
+    retriever: HRPolicyRetriever,
+) -> RetrievalTurnResult:
+    """Resolve policy updates, but block retrieval on contradictory turns."""
+
+    decision = engine.step(compiler_input)
+
+    if is_clarify(decision):
+        return {
+            "decision_kind": "clarify",
+            "prompt_to_user": decision.get("prompt_to_user"),
+            "retrieval_result": {
+                "query": query,
+                "eligible_document_ids": [],
+                "returned_document_ids": [],
+                "blocked_reason": "clarification required before retrieval policy changes",
+            },
+        }
+
+    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"),
+        "retrieval_result": retrieve_hr_documents(
+            query,
+            state=authoritative_state,
+            retriever=retriever,
+        ),
+    }
+
+
+def run_demo() -> dict[str, RetrievalResult]:
+    """Run a deterministic retrieval-filtering demonstration."""
+
+    query = "handbook policy"
+    retriever = HRPolicyRetriever(documents=example_documents())
+
+    absent_engine = create_engine()
+    employee_engine = create_engine()
+    employee_engine.step(f"use {EMPLOYEE_ACCESS}")
+    manager_engine = create_engine()
+    manager_engine.step(f"use {MANAGER_ACCESS}")
+
+    return {
+        "absent_state": retrieve_hr_documents(
+            query,
+            state=absent_engine.state,
+            retriever=retriever,
+        ),
+        "employee_access": retrieve_hr_documents(
+            query,
+            state=employee_engine.state,
+            retriever=retriever,
+        ),
+        "manager_access": retrieve_hr_documents(
+            query,
+            state=manager_engine.state,
+            retriever=retriever,
+        ),
+    }
+
+
+if __name__ == "__main__":
+    print(run_demo())

context_compiler_example_integrations/examples/schema_selection/README.md

@@ -0,0 +1,41 @@
+# Schema selection
+
+These examples show how authoritative state changes which host-side path runs.
+
+They demonstrate observable runtime behavior changes rather than model compliance.
+
+## Examples
+
+### `refund_intake`
+
+Shows two generic schema-selection mechanisms in the same customer
+order/support intake domain.
+
+Policy-driven selection can route requests when state contains:
+
+```text
+use refund_intake
+```
+
+Premise-driven selection can also change schema choice for the same ambiguous
+request when saved factual order context changes.
+
+This example keeps premise factual. It does not treat premise as a disguised
+workflow command.
+
+### `ollama_structured_output`
+
+Shows a host selecting an Ollama `format` schema from compiled policy state.
+
+### `litellm_response_format`
+
+Shows a host selecting a LiteLLM `response_format` from compiled policy state.
+
+## Technology-specific examples
+
+The generic examples teach the enforcement point first.
+
+Concrete runtime surfaces currently linked from this repo:
+
+- [python/examples/schema_selection/ollama_structured_output/README.md](ollama_structured_output/README.md)
+- `python/examples/schema_selection/litellm_response_format/response_format.py`

context_compiler_example_integrations/examples/schema_selection/litellm_response_format/response_format.py

@@ -0,0 +1,218 @@
+"""Minimal LiteLLM response_format selection from authoritative state.
+
+Flow:
+Context Compiler state -> host response_format decision -> LiteLLM model call.
+
+This example keeps model execution optional so tests can validate behavior
+without a live provider.
+"""
+
+import os
+from collections.abc import Callable, Mapping
+from importlib import import_module
+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
+
+from context_compiler_example_integrations.examples._shared.provider_mode import (
+    print_startup_config,
+    resolve_provider_config,
+)
+
+COMPACT_SUMMARY_RESPONSE_FORMAT: dict[str, Any] = {
+    "type": "json_schema",
+    "json_schema": {
+        "name": "compact_summary",
+        "schema": {
+            "type": "object",
+            "properties": {
+                "summary": {
+                    "type": "string",
+                    "description": "A compact summary of the answer.",
+                }
+            },
+            "required": ["summary"],
+            "additionalProperties": False,
+        },
+    },
+}
+
+ACTION_PLAN_RESPONSE_FORMAT: dict[str, Any] = {
+    "type": "json_schema",
+    "json_schema": {
+        "name": "action_plan",
+        "schema": {
+            "type": "object",
+            "properties": {
+                "steps": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "Ordered next steps for the user.",
+                }
+            },
+            "required": ["steps"],
+            "additionalProperties": False,
+        },
+    },
+}
+
+_RESPONSE_FORMAT_BY_ITEM: dict[str, dict[str, Any]] = {
+    "compact_summary": COMPACT_SUMMARY_RESPONSE_FORMAT,
+    "action_plan": ACTION_PLAN_RESPONSE_FORMAT,
+}
+
+
+class TurnPlan(TypedDict):
+    decision_kind: str
+    clarify_prompt: str | None
+    selected_response_format_item: str | None
+    response_format: dict[str, Any] | None
+
+
+class _LiteLLMCallKwargs(TypedDict, total=False):
+    model: str
+    messages: list[dict[str, str]]
+    temperature: float
+    api_base: str
+    api_key: str
+    response_format: dict[str, Any]
+
+
+def select_litellm_response_format(
+    state: State,
+) -> tuple[str | None, dict[str, Any] | None]:
+    """Return (policy_item, response_format) or (None, None) when no safe match exists."""
+
+    use_items = set(get_policy_items(state, POLICY_USE))
+    prohibit_items = set(get_policy_items(state, POLICY_PROHIBIT))
+
+    for item, response_format in _RESPONSE_FORMAT_BY_ITEM.items():
+        if item in use_items and item not in prohibit_items:
+            return item, response_format
+
+    return None, None
+
+
+def plan_turn(user_input: str, engine: Engine) -> TurnPlan:
+    """Run compiler step and decide whether to request LiteLLM structured output."""
+
+    decision = engine.step(user_input)
+    if is_clarify(decision):
+        return {
+            "decision_kind": "clarify",
+            "clarify_prompt": get_clarify_prompt(decision),
+            "selected_response_format_item": None,
+            "response_format": None,
+        }
+
+    decision_state = get_decision_state(decision)
+    compiled_state = decision_state if decision_state is not None else engine.state
+    selected_item, response_format = select_litellm_response_format(compiled_state)
+
+    return {
+        "decision_kind": str(decision["kind"]),
+        "clarify_prompt": None,
+        "selected_response_format_item": selected_item,
+        "response_format": response_format,
+    }
+
+
+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 optional_litellm_call(
+    *,
+    user_input: str,
+    response_format: Mapping[str, Any] | None,
+) -> str:
+    """Optional smoke call to LiteLLM.
+
+    If `response_format` is provided, it is passed through unchanged.
+    """
+
+    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 = {
+        "model": config.model,
+        "messages": [{"role": "user", "content": user_input}],
+        "temperature": 0,
+        "api_base": config.base_url,
+    }
+    if config.api_key:
+        kwargs["api_key"] = config.api_key
+    if response_format is not None:
+        kwargs["response_format"] = dict(response_format)
+
+    response = completion(**kwargs)
+    content = _extract_response_content(response)
+    if content is None:
+        raise RuntimeError("LiteLLM response missing choices[0].message.content")
+    return content
+
+
+def main() -> None:
+    engine = create_engine()
+
+    # Demonstration setup.
+    engine.step("use compact_summary")
+    engine.step("prohibit action_plan")
+
+    plan = plan_turn("Summarize what changed in this project.", engine)
+    print("decision_kind:", plan["decision_kind"])
+    print("selected_response_format_item:", plan["selected_response_format_item"])
+    print("response_format_selected:", plan["response_format"] is not None)
+
+    # Optional model execution path; disabled by default.
+    if os.getenv("RUN_LITELLM_SMOKE") == "1":
+        response = optional_litellm_call(
+            user_input="Summarize what changed in this project.",
+            response_format=plan["response_format"],
+        )
+        print("litellm_response:", response)
+
+
+if __name__ == "__main__":
+    main()

context_compiler_example_integrations/examples/schema_selection/ollama_structured_output/README.md

@@ -0,0 +1,60 @@
+# Ollama structured output (host-side selection)
+
+Policy state changes which schema the host sends through Ollama's `format`
+field, or whether it sends none. This example shows that host-side
+schema-selection behavior without relying on prompt reinjection.
+
+Flow:
+
+`Context Compiler state -> host schema decision -> Ollama format request -> model call`
+
+The host reads compiled policy state, picks a JSON Schema (or none), and sends that choice through Ollama's `format` field.
+
+## What this example guarantees
+
+- Context Compiler provides deterministic state transitions.
+- The host integration decides whether to request a schema.
+- Ollama structured output is a runtime request made by the host.
+- If policy state is unknown or insufficient, the host requests no schema.
+
+## What `prohibit shell_command` means here
+
+- The host will not request the `shell_command` schema.
+- The host may still request a different schema when policy supports it (for example, `python_script`).
+- This does not block normal language discussion about shell commands.
+
+## Observable behavior
+
+Given policy state:
+
+```text
+use python_script
+prohibit shell_command
+```
+
+this host selects `python_script` schema and does not request `shell_command` schema.
+
+## Test boundary
+
+Tests verify schema selection behavior only:
+
+- compiler state -> selected schema (or no schema)
+- contradiction handling stays in compiler `clarify`
+
+Tests do not assert exact model wording.
+
+## Run without Ollama
+
+```shell
+uv run python python/examples/schema_selection/ollama_structured_output/example.py
+```
+
+## Optional Ollama smoke run
+
+```shell
+export RUN_OLLAMA_SMOKE=1
+export OLLAMA_MODEL=llama3.1
+uv run python python/examples/schema_selection/ollama_structured_output/example.py
+```
+
+When smoke mode is enabled, the host sends the selected JSON Schema through Ollama `format`.