build: prepare Python and TypeScript packages for publication

.github/workflows/ci.yml

@@ -41,7 +41,7 @@ jobs:
           python-version: ${{ matrix.python-version }}
 
       - name: Sync Python dependencies
-        run: uv sync --group dev
+        run: uv sync --group dev --no-editable
 
       - name: Run Python validation
         run: ./scripts/validate_python.sh

README.md

@@ -2,12 +2,17 @@
 
 What runtime behavior changes when authoritative state exists?
 
-These examples demonstrate how Context Compiler's authority contract can
-influence runtime behavior across different AI pipeline stages.
+These examples show how authoritative state changes application behavior at runtime.
 
-Prompt reinjection influences model behavior.
+Each example demonstrates a single enforcement point where premise and policy influence what a host allows, routes, retrieves, builds, or executes.
 
-Context Compiler influences runtime behavior.
+- The core authority contract is provided by [`context-compiler`](https://github.com/rlippmann/context-compiler) and [`context-compiler`](https://github.com/rlippmann/context-compiler-ts).
+- Directive recognition can optionally be added with [`context-compiler-directive-drafter`](https://github.com/rlippmann/context-compiler-directive-drafter) and [`context-compiler-directive-drafter`](https://github.com/rlippmann/context-compiler-directive-drafter-ts).
+- This repository focuses on where authoritative state changes runtime behavior.
+
+*Prompt reinjection* influences ***model behavior***.
+
+*Context Compiler* influences ***runtime behavior***.
 
 Each example:
 
@@ -18,7 +23,7 @@ Each example:
 
 ## Start here
 
-Start with [python/README.md](python/README.md) or [typescript/README.md](typescript/README.md) if you want language-level orientation first.
+Start with [Python guide](python/README.md) or [TypeScript guide](typescript/README.md) if you want language-level orientation first.
 
 Use the enforcement-point catalog below when you already know which runtime
 behavior you want to inspect.
@@ -28,10 +33,10 @@ apps. Python also includes reference integrations.
 
 ## Ecosystem map
 
-| Repo | Question |
+| Project | Question |
 | --- | --- |
-| [context-compiler (Python)](https://github.com/rlippmann/context-compiler), [context-compiler-ts (TypeScript)](https://github.com/rlippmann/context-compiler-ts) | What is the authority contract? |
-| [context-compiler-directive-drafter (Python)](https://github.com/rlippmann/context-compiler-directive-drafter), [context-compiler-directive-drafter-ts (TypeScript)](https://github.com/rlippmann/context-compiler-directive-drafter-ts) | How is authority acquired? |
+| [context-compiler (Python)](https://github.com/rlippmann/context-compiler), [context-compiler (TypeScript)](https://github.com/rlippmann/context-compiler-ts) | What is the authority contract? |
+| [context-compiler-directive-drafter (Python)](https://github.com/rlippmann/context-compiler-directive-drafter), [context-compiler-directive-drafter (TypeScript)](https://github.com/rlippmann/context-compiler-directive-drafter-ts) | How is authority acquired? |
 | [context-compiler-example-integrations](https://github.com/rlippmann/context-compiler-example-integrations) | Where can authority be enforced? |
 
 ## Enforcement-point catalog
@@ -46,55 +51,36 @@ apps. Python also includes reference integrations.
 | [Request construction / context assembly](python/examples/prompt_construction/README.md) | Writing assistant | generic Python / TypeScript, LiteLLM, Open WebUI, Next.js |
 | [Tool gating](python/examples/tool_gating/README.md) | Calendar / email / admin | generic Python / TypeScript, MCP |
 
-## How this repo is organized
-
-Technology is secondary to enforcement point.
-
-Examples are organized by enforcement point, not framework.
-
-Python and TypeScript share the taxonomy. Implementations may differ by
-language.
-
-There is no parity requirement between Python and TypeScript examples.
-
-Python examples may arrive before TypeScript examples.
-
-TypeScript starter apps now split compiler-only and with-drafter variants.
-
-## Repository boundaries
+## Organization
 
-This repo is:
+Examples are organized by enforcement point.
 
-- an examples/integrations repo
-- organized around runtime enforcement points
-- not the core Context Compiler library package
-- not the authority contract
-- not the directive drafter
-- not an acquisition-layer repo
-- not a framework showcase
+- Python includes generic examples and reference integrations.
+- TypeScript includes generic examples and starter apps.
+- Available examples differ between Python and TypeScript.
 
 ## Current layout
 
-- [python/README.md](python/README.md)
-- [typescript/README.md](typescript/README.md)
+- [python/README.md](python/README.md) - Python examples and reference integrations
+- [typescript/README.md](typescript/README.md) - TypeScript examples and starter apps
 
-## Contribution expectations
+## Adding examples
 
-Primary examples in this repo should:
+Examples in this repo should:
 
 - use explicit authoritative state
 - avoid deriving Context Compiler state from model output
 - remain meaningful with an adversarial stub
 - demonstrate observable runtime behavior changes
 
-See [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md) for repository rules.
+See [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md) for more detail.
 
 ## Validation
 
 Canonical repo-level validation commands:
 
 ```bash
-uv sync --group dev
+uv sync --group dev --no-editable
 ./scripts/validate_python.sh
 ./scripts/validate_typescript_fast.sh
 ./scripts/validate_typescript.sh

pyproject.toml

@@ -11,21 +11,26 @@ requires-python = ">=3.11"
 license = { text = "Apache-2.0" }
 authors = [{ name = "Robert Lippmann" }]
 dependencies = [
-  "chromadb",
-  "context-compiler>=0.7.4",
-  "context-compiler-directive-drafter",
-  "fastapi",
-  "litellm",
+  "context-compiler>=0.8.0",
 ]
 keywords = [
   "context-compiler",
   "examples",
   "integrations",
   "llm",
+  "litellm",
+  "fastapi",
+  "chromadb",
+  "ollama",
+  "mcp",
+  "open-webui",
 ]
 classifiers = [
   "Development Status :: 3 - Alpha",
   "Intended Audience :: Developers",
+  "Topic :: Scientific/Engineering :: Artificial Intelligence",
+  "Topic :: Software Development :: Libraries",
+  "Topic :: Software Development :: Testing",
   "License :: OSI Approved :: Apache Software License",
   "Programming Language :: Python :: 3",
   "Programming Language :: Python :: 3.11",
@@ -39,9 +44,34 @@ Homepage = "https://github.com/rlippmann/context-compiler-example-integrations"
 Repository = "https://github.com/rlippmann/context-compiler-example-integrations"
 Issues = "https://github.com/rlippmann/context-compiler-example-integrations/issues"
 
+[project.optional-dependencies]
+all = [
+  "chromadb",
+  "context-compiler-directive-drafter",
+  "fastapi",
+  "litellm",
+]
+drafter = [
+  "context-compiler-directive-drafter",
+]
+fastapi = [
+  "fastapi",
+]
+litellm = [
+  "litellm",
+]
+retrieval = [
+  "chromadb",
+]
+
 [dependency-groups]
 dev = [
+  "chromadb",
+  "context-compiler-directive-drafter",
+  "fastapi",
   "httpx2>=2.5.0",
+  "httpx>=0.28.1",
+  "litellm",
   "mypy",
   "pre-commit",
   "pytest",
@@ -52,7 +82,26 @@ proxy_runtime = [
 ]
 
 [tool.hatch.build.targets.wheel]
-only-include = ["python", "LICENSE", "AGENTS.md", "CONTRIBUTING.md"]
+only-include = ["python", "LICENSE"]
+exclude = [
+  "python/tests",
+  "python/**/__pycache__",
+  "python/**/*.pyc",
+  "python/**/.DS_Store",
+]
+
+[tool.hatch.build.targets.wheel.sources]
+"python" = "context_compiler_example_integrations"
+
+[tool.hatch.build.targets.sdist]
+only-include = ["python", "LICENSE", "pyproject.toml"]
+exclude = [
+  "python/tests",
+  "python/**/__pycache__",
+  "python/**/*.pyc",
+  "python/**/.DS_Store",
+  ".gitignore",
+]
 
 
 [tool.ruff]

python/README.md

@@ -1,35 +1,50 @@
-# Python examples
+# Context Compiler Example Integrations for Python
 
-These examples show how Context Compiler state changes application behavior at
-runtime.
+These examples show how authoritative state changes application behavior at runtime.
+
+Each example demonstrates a single enforcement point where premise and policy influence what a host allows, routes, retrieves, builds, or executes.
+
+- The core authority contract is provided by [`context-compiler`](https://github.com/rlippmann/context-compiler).
+- Directive recognition can optionally be added with [`context-compiler-directive-drafter`](https://github.com/rlippmann/context-compiler-directive-drafter).
+- These examples focus on where authoritative state changes application behavior.
+
+*Prompt reinjection* influences ***model behavior***.
+
+*Context Compiler* influences ***runtime behavior***.
 
-Each example focuses on an enforcement point where saved premise and policy
-affect what a host allows, routes, retrieves, builds, or executes.
+## Install options
 
-The core library lives in
-[`context-compiler`](https://github.com/rlippmann/context-compiler).
-Directive recognition can be added with
-[`context-compiler-directive-drafter`](https://github.com/rlippmann/context-compiler-directive-drafter),
-but that layer is optional. This package is the examples and integration
-patterns layer.
+Base installation keeps this package discovery-first:
 
-`context-compiler` defines the authority contract.
-`context-compiler-directive-drafter` can optionally help acquire and draft
-authority, but it is not the authority layer.
-This examples package shows where authority is enforced.
+```shell
+pip install "context-compiler-example-integrations"
+```
 
-Prompt reinjection influences model behavior.
-Context Compiler influences runtime behavior.
+That installs the shared core dependency only:
+
+- `context-compiler>=0.8.0`
+
+Add extras only for the examples you want to inspect locally:
+
+- `pip install "context-compiler-example-integrations[drafter]"` for examples that use `context-compiler-directive-drafter`
+- `pip install "context-compiler-example-integrations[retrieval]"` for ChromaDB retrieval filtering examples
+- `pip install "context-compiler-example-integrations[fastapi]"` for FastAPI variants
+- `pip install "context-compiler-example-integrations[litellm]"` for LiteLLM-oriented examples and reference integrations
+- `pip install "context-compiler-example-integrations[all]"` to install all package-managed optional dependencies
+
+Open WebUI is not installed by this package. The Open WebUI reference
+integration assumes Open WebUI is already installed and configured as the host
+runtime.
 
 ## Generic examples
 
-- [Checkpoint continuation](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/checkpoint_continuation/README.md): persisted confirmation and resume flows change host behavior across turns or requests
-- [Execution authorization](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/execution_authorization/README.md): protected host actions execute only when authoritative state allows them
-- [Gateway middleware](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/gateway_middleware/README.md): the host allows, blocks, or routes requests before downstream work runs
-- [Prompt construction](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/prompt_construction/README.md): the host builds different request or prompt payloads from authoritative state
-- [Retrieval filtering](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/retrieval_filtering/README.md): the host changes which documents are eligible or relevant before returning results
-- [Schema selection](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/schema_selection/README.md): the host picks different workflow or response schemas from authoritative state
-- [Tool gating](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/tool_gating/README.md): the host changes which tools are visible or executable at runtime
+- [Checkpoint continuation](examples/checkpoint_continuation/README.md): persisted confirmation and resume flows change host behavior across turns or requests
+- [Execution authorization](examples/execution_authorization/README.md): protected host actions execute only when authoritative state allows them
+- [Gateway middleware](examples/gateway_middleware/README.md): the host allows, blocks, or routes requests before downstream work runs
+- [Prompt construction](examples/prompt_construction/README.md): the host builds different request or prompt payloads from authoritative state
+- [Retrieval filtering](examples/retrieval_filtering/README.md): the host changes which documents are eligible or relevant before returning results
+- [Schema selection](examples/schema_selection/README.md): the host picks different workflow or response schemas from authoritative state
+- [Tool gating](examples/tool_gating/README.md): the host changes which tools are visible or executable at runtime
 
 ## Reference integrations
 
@@ -42,8 +57,8 @@ behavior on a specific host or framework surface.
 Start with the generic example first, then use the Python reference
 integrations to inspect a runtime-specific path:
 
-- [python/reference_integrations/litellm_proxy/README.md](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/reference_integrations/litellm_proxy/README.md)
-- [python/reference_integrations/openwebui_pipe/README.md](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/reference_integrations/openwebui_pipe/README.md)
+- [python/reference_integrations/litellm_proxy/README.md](reference_integrations/litellm_proxy/README.md)
+- [python/reference_integrations/openwebui_pipe/README.md](reference_integrations/openwebui_pipe/README.md)
 
 ## Run an example
 

python/examples/_shared/provider_mode.py

@@ -0,0 +1,91 @@
+"""Shared provider mode resolution for installed example modules."""
+
+import logging
+import os
+from dataclasses import dataclass
+from typing import Literal, cast
+
+_ALLOWED_PROVIDER_VALUES = ("openai", "ollama", "openai_compatible")
+_STARTUP_LOGGED = False
+
+
+@dataclass(frozen=True)
+class ProviderConfig:
+    mode: Literal["openai", "ollama", "openai_compatible"]
+    source: Literal["default", "PROVIDER", "OPENAI_BASE_URL override"]
+    base_url: str
+    model: str
+    api_key: str | None
+
+
+def resolve_provider_config(
+    default_model: str = "openai/gpt-4o-mini",
+) -> ProviderConfig:
+    """Resolve provider mode config from environment using strict contract."""
+    base_url = os.getenv("OPENAI_BASE_URL", "").strip() or None
+    provider = os.getenv("PROVIDER", "").strip().lower() or None
+    api_key = os.getenv("OPENAI_API_KEY", "").strip() or None
+    model = os.getenv("MODEL", "").strip() or default_model
+
+    if base_url:
+        return ProviderConfig(
+            mode="openai_compatible",
+            source="OPENAI_BASE_URL override",
+            base_url=base_url,
+            model=model,
+            api_key=api_key,
+        )
+
+    if provider is not None and provider not in _ALLOWED_PROVIDER_VALUES:
+        allowed_values = ", ".join(_ALLOWED_PROVIDER_VALUES)
+        raise RuntimeError(
+            f"Invalid PROVIDER value '{provider}'. Allowed values: {allowed_values}"
+        )
+
+    mode: Literal["openai", "ollama", "openai_compatible"]
+    source: Literal["default", "PROVIDER", "OPENAI_BASE_URL override"]
+    if provider is None:
+        mode = "openai"
+        source = "default"
+    else:
+        mode = cast(Literal["openai", "ollama", "openai_compatible"], provider)
+        source = "PROVIDER"
+
+    if mode == "openai":
+        if not api_key:
+            raise RuntimeError("OPENAI_API_KEY is required in openai mode.")
+        return ProviderConfig(
+            mode=mode,
+            source=source,
+            base_url="https://api.openai.com/v1",
+            model=model,
+            api_key=api_key,
+        )
+    if mode == "ollama":
+        return ProviderConfig(
+            mode=mode,
+            source=source,
+            base_url="http://localhost:11434",
+            model=model,
+            api_key=api_key,
+        )
+
+    raise RuntimeError("OPENAI_BASE_URL is required when PROVIDER=openai_compatible.")
+
+
+def print_startup_config(
+    config: ProviderConfig, logger: logging.Logger | None = None
+) -> None:
+    """Emit one startup line per process with resolved provider config."""
+    global _STARTUP_LOGGED
+    if _STARTUP_LOGGED:
+        return
+    target_logger = logger or logging.getLogger(__name__)
+    target_logger.info(
+        "litellm_config mode=%s base_url=%s model=%s source=%s",
+        config.mode,
+        config.base_url,
+        config.model,
+        config.source,
+    )
+    _STARTUP_LOGGED = True