diff --git a/AGENTS.md b/AGENTS.md index 48eb0e7..e4edcf3 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -56,15 +56,15 @@ Domains are teaching aids. Enforcement points are primary. ## Validation -- Canonical Python validation: `uv run pre-commit run --all-files` +- Canonical validation: `uv run pre-commit run --all-files` - Markdown validation: `npx --yes markdownlint-cli2` - Before reporting a task complete or opening a PR, run validation relevant to the changed files. -- If Python files changed, run `uv run pre-commit run --all-files`. +- If code files changed, run `uv run pre-commit run --all-files`. - If Markdown files changed, run `npx --yes markdownlint-cli2`. - If multiple areas changed, run all relevant checks. - Report the exact validation commands and results. - If a required or relevant validation command cannot be run, report why instead of saying the task is complete. -- Python contributors may use local hooks: `uv run pre-commit run --all-files` +- Contributors may use local hooks: `uv run pre-commit run --all-files` - CI is the authoritative validation path. ## Example design requirements @@ -141,10 +141,7 @@ changes are acceptance criteria. Documentation examples explicitly referenced by a task are part of the expected deliverable. -Root README owns cross-language discovery. - -Language-specific and example README files should avoid cross-language links or -navigation mentions unless there is a deliberate exception. +The root README owns repository-level discovery. Do not treat documentation as merely illustrative unless explicitly stated. diff --git a/README.md b/README.md index 8bb4ae1..49244b7 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -# Context Compiler Example Integrations +# Context Compiler Python Example Integrations What runtime behavior changes when authoritative state exists? @@ -21,14 +21,9 @@ Each example: - remains meaningful with an adversarial model stub - focuses on the enforcement point rather than the framework -## Start here - -Start with the [Python guide](python/README.md). - -Use the enforcement-point catalog below when you already know which runtime -behavior you want to inspect. - -Python includes generic examples and reference integrations. +This repository contains the Python examples and reference integrations. Use +the enforcement-point catalog below to find the runtime behavior you want to +inspect. ## Ecosystem map @@ -50,15 +45,39 @@ Python includes generic examples and reference integrations. | [Request construction / context assembly](python/examples/prompt_construction/README.md) | Writing assistant | Python, LiteLLM, Open WebUI | | [Tool gating](python/examples/tool_gating/README.md) | Calendar / email / admin | Python, MCP | -## Organization +## Install + +Install the package from PyPI for the shared examples and core dependency: + +```shell +pip install "context-compiler-example-integrations" +``` + +Add an extra for the examples you want to run locally: + +- `pip install "context-compiler-example-integrations[drafter]"` for Directive Drafter examples +- `pip install "context-compiler-example-integrations[retrieval]"` for ChromaDB retrieval examples +- `pip install "context-compiler-example-integrations[fastapi]"` for FastAPI variants +- `pip install "context-compiler-example-integrations[litellm]"` for LiteLLM examples and reference integrations +- `pip install "context-compiler-example-integrations[all]"` for all package-managed optional dependencies + +Open WebUI is not installed by this package. Its reference integration assumes +that Open WebUI is already installed and configured as the host runtime. + +## Reference integrations + +The repository also includes runtime-specific integrations for: -Examples are organized by enforcement point. +- [LiteLLM Proxy](python/reference_integrations/litellm_proxy/README.md) +- [Open WebUI](python/reference_integrations/openwebui_pipe/README.md) -- Python includes generic examples and reference integrations. +## Run an example -## Current layout +Use a repository checkout to explore an example: -- [python/README.md](python/README.md) - Python examples and reference integrations +1. Choose an enforcement point from the catalog above. +2. Open its README for setup, runtime, and validation instructions. +3. Run the example from the repository root as documented. ## Adding examples @@ -81,14 +100,14 @@ uv run pre-commit run --all-files npx --yes markdownlint-cli2 ``` -Python contributors may install and run local pre-commit hooks: +Contributors may install and run local pre-commit hooks: ```bash uv run pre-commit install uv run pre-commit run --all-files ``` -CI runs Python validation through pre-commit and Markdown lint separately. +CI runs pre-commit and Markdown lint separately. ## License diff --git a/pyproject.toml b/pyproject.toml index 040fb1e..831360d 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "context-compiler-example-integrations" -version = "0.2.0" +version = "0.2.1" description = "Example integrations and enforcement-point demonstrations for Context Compiler." readme = "python/README.md" requires-python = ">=3.11" diff --git a/python/README.md b/python/README.md index a0f422f..9e4a08b 100644 --- a/python/README.md +++ b/python/README.md @@ -36,36 +36,12 @@ 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 +## Package contents -- [Checkpoint continuation](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/checkpoint_continuation/README.md): persisted authoritative state changes 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 +The installed package exposes the Python examples and reference-integration +modules under `context_compiler_example_integrations`. -## Reference integrations - -Python also includes reference integrations for runtime-specific behavior after -the generic examples. - -Open a reference integration when you want to see the same kind of runtime -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: - -- [LiteLLM Proxy reference integration](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/reference_integrations/litellm_proxy/README.md) -- [Open WebUI pipe reference integration](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/reference_integrations/openwebui_pipe/README.md) - -## Run an example - -To explore or run an example, use a repository checkout: - -1. Clone - [`context-compiler-example-integrations`](https://github.com/rlippmann/context-compiler-example-integrations). -2. Choose a generic example or a reference integration. -3. Open that example's README. -4. Follow the example-specific setup, runtime, and validation instructions. +For the enforcement-point catalog and repository navigation, see the [root +README](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/README.md). +Each example and reference integration has its own setup, runtime, and +validation instructions. diff --git a/uv.lock b/uv.lock index f4cc85a..29f11e8 100644 --- a/uv.lock +++ b/uv.lock @@ -679,7 +679,7 @@ wheels = [ [[package]] name = "context-compiler-example-integrations" -version = "0.2.0" +version = "0.2.1" source = { editable = "." } dependencies = [ { name = "context-compiler" },