From cda6810f9021a1a79b0f12b4ddf6b78dd2a65611 Mon Sep 17 00:00:00 2001 From: Robert Lippmann Date: Mon, 6 Jul 2026 16:23:17 -0400 Subject: [PATCH 1/8] docs: improve example navigation --- README.md | 10 ++++++++ python/README.md | 32 ++++++++++++++++++++++-- typescript/README.md | 22 ++++++++++++++++ typescript/starter_apps/nextjs/README.md | 12 +++++++++ typescript/starter_apps/node/README.md | 12 +++++++++ 5 files changed, 86 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 6088bbe..42833ad 100644 --- a/README.md +++ b/README.md @@ -16,6 +16,16 @@ Each example: - remains meaningful with an adversarial model stub - focuses on the enforcement point rather than the framework +## Start here + +Start with [python/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/README.md) or [typescript/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/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. + +Both language tracks include generic examples. TypeScript also includes starter +apps. Python also includes reference integrations. + ## Ecosystem map | Repo | Question | diff --git a/python/README.md b/python/README.md index e76611b..dd14c57 100644 --- a/python/README.md +++ b/python/README.md @@ -2,6 +2,12 @@ Python examples in this repo stay organized by enforcement point first. +Open this section when you want the smallest Python examples that show a +runtime behavior change from authoritative state. + +Start with a generic example README below if you want the clearest explanation +of an enforcement point before looking at framework-specific integrations. + Current generic Python examples include: - [python/examples/checkpoint_continuation/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/checkpoint_continuation/README.md) @@ -12,5 +18,27 @@ Current generic Python examples include: - [python/examples/schema_selection/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/schema_selection/README.md) - [python/examples/tool_gating/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/tool_gating/README.md) -Reference integrations and optional framework-specific examples remain -secondary to the enforcement point. +These generic examples are the main starting point for new readers. + +They are small, enforcement-point-first, and usually the fastest way to see +what changes at runtime when saved state changes. + +## 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: + +- [python/reference_integrations/litellm_proxy/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/reference_integrations/litellm_proxy/README.md) +- [python/reference_integrations/openwebui_pipe/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/reference_integrations/openwebui_pipe/README.md) + +Choose Python when you want: + +- generic examples with small host-side flows +- the current reference integrations in this repo +- runtime-specific behavior after you already understand the generic path diff --git a/typescript/README.md b/typescript/README.md index adc1566..5db11d5 100644 --- a/typescript/README.md +++ b/typescript/README.md @@ -2,6 +2,12 @@ TypeScript examples in this repo stay organized by enforcement point first. +Open this section when you want small TypeScript examples that show a runtime +behavior change from authoritative state. + +Start with a generic example README below if you want the clearest explanation +of an enforcement point before looking at starter apps. + Current generic TypeScript examples include: - [typescript/examples/checkpoint_continuation/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/examples/checkpoint_continuation/README.md) @@ -12,12 +18,22 @@ Current generic TypeScript examples include: - [typescript/examples/schema_selection/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/examples/schema_selection/README.md) - [typescript/examples/tool_gating/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/examples/tool_gating/README.md) +These generic examples are the main starting point for new readers. + +They are the most direct way to see the enforcement point before any framework +or app runtime details. + +## Starter apps + Starter apps are available when a small runnable host makes the enforcement point easier to see: - [starter_apps/node](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/starter_apps/node/README.md) - execution authorization starter variants for a small Node HTTP server - [starter_apps/nextjs](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/starter_apps/nextjs/README.md) - request construction and context assembly starter variants for a minimal Next.js App Router app +Open a starter app when you want a minimal host runtime around the enforcement +point instead of a generic example alone. + In these starters: - `@rlippmann/context-compiler` is the authority layer @@ -30,3 +46,9 @@ Each starter app now comes in two variants: The compiler-only flow is always the baseline. If a starter includes directive-drafter, it is there to help acquisition, not to own state changes. + +Choose TypeScript when you want: + +- generic examples in TypeScript with the same enforcement-point taxonomy +- minimal starter apps that show host/runtime boundaries +- a direct path into Node or Next.js-oriented examples diff --git a/typescript/starter_apps/nextjs/README.md b/typescript/starter_apps/nextjs/README.md index 1f41188..ac267c0 100644 --- a/typescript/starter_apps/nextjs/README.md +++ b/typescript/starter_apps/nextjs/README.md @@ -1,10 +1,22 @@ # Next.js starter apps +Open this folder when you want a minimal App Router host around the examples +instead of a generic example alone. + +This area teaches request construction first. It shows how a host restores +saved state, builds a request payload from that state, and makes the runtime +effect visible before any live model call. + The Next.js starter app now comes in two small variants: - [basic](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/starter_apps/nextjs/basic/README.md) - compiler-only baseline adapted from the last `nextjs-basic` example in `context-compiler-ts` - [with_drafter](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/starter_apps/nextjs/with_drafter/README.md) - optional directive-drafter layer before `engine.step(...)` +Open `basic` first if you want the smallest baseline. + +Open `with_drafter` when you want to compare that baseline with an optional +acquisition layer that still leaves saved-state authority with the compiler. + In both variants: - `@rlippmann/context-compiler` remains the authority over saved state diff --git a/typescript/starter_apps/node/README.md b/typescript/starter_apps/node/README.md index 6ace4c0..46ac84d 100644 --- a/typescript/starter_apps/node/README.md +++ b/typescript/starter_apps/node/README.md @@ -1,10 +1,22 @@ # Node starter apps +Open this folder when you want a small runnable Node host instead of a generic +example alone. + +This area teaches execution authorization first. It shows how a host preserves +saved state across requests and changes runtime behavior before any downstream +model or tool path would continue. + The Node starter app now comes in two small variants: - [basic](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/starter_apps/node/basic/README.md) - compiler-only baseline adapted from the last `node-basic` example in `context-compiler-ts` - [with_drafter](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/starter_apps/node/with_drafter/README.md) - optional directive-drafter layer before `engine.step(...)` +Open `basic` first if you want the smallest baseline. + +Open `with_drafter` when you want to compare that baseline with an optional +acquisition layer that still leaves saved-state authority with the compiler. + In both variants: - `@rlippmann/context-compiler` remains the authority over saved state From 0758360800567db39a57d129d6c9b9990062cf31 Mon Sep 17 00:00:00 2001 From: Robert Lippmann Date: Mon, 6 Jul 2026 16:29:54 -0400 Subject: [PATCH 2/8] docs: use Python README for package publication --- pyproject.toml | 4 ++-- python/README.md | 21 +++++++++++---------- 2 files changed, 13 insertions(+), 12 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 5b623a5..93a10de 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -6,7 +6,7 @@ build-backend = "hatchling.build" name = "context-compiler-example-integrations" version = "0.1.0" description = "Example integrations and enforcement-point demonstrations for Context Compiler." -readme = "README.md" +readme = "python/README.md" requires-python = ">=3.11" license = { text = "Apache-2.0" } authors = [{ name = "Robert Lippmann" }] @@ -52,7 +52,7 @@ proxy_runtime = [ ] [tool.hatch.build.targets.wheel] -only-include = ["python", "README.md", "LICENSE", "AGENTS.md", "CONTRIBUTING.md"] +only-include = ["python", "LICENSE", "AGENTS.md", "CONTRIBUTING.md"] [tool.ruff] diff --git a/python/README.md b/python/README.md index dd14c57..62a427d 100644 --- a/python/README.md +++ b/python/README.md @@ -1,6 +1,7 @@ # Python examples -Python examples in this repo stay organized by enforcement point first. +This package publishes Python example integrations organized by enforcement +point first. Open this section when you want the smallest Python examples that show a runtime behavior change from authoritative state. @@ -10,13 +11,13 @@ of an enforcement point before looking at framework-specific integrations. Current generic Python examples include: -- [python/examples/checkpoint_continuation/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/checkpoint_continuation/README.md) -- [python/examples/execution_authorization/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/execution_authorization/README.md) -- [python/examples/gateway_middleware/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/gateway_middleware/README.md) -- [python/examples/prompt_construction/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/prompt_construction/README.md) -- [python/examples/retrieval_filtering/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/retrieval_filtering/README.md) -- [python/examples/schema_selection/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/schema_selection/README.md) -- [python/examples/tool_gating/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/tool_gating/README.md) +- [python/examples/checkpoint_continuation/README.md](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/checkpoint_continuation/README.md) +- [python/examples/execution_authorization/README.md](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/execution_authorization/README.md) +- [python/examples/gateway_middleware/README.md](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/gateway_middleware/README.md) +- [python/examples/prompt_construction/README.md](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/prompt_construction/README.md) +- [python/examples/retrieval_filtering/README.md](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/retrieval_filtering/README.md) +- [python/examples/schema_selection/README.md](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/schema_selection/README.md) +- [python/examples/tool_gating/README.md](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/tool_gating/README.md) These generic examples are the main starting point for new readers. @@ -34,8 +35,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](/Users/rlippmann/Source/context-compiler-example-integrations/python/reference_integrations/litellm_proxy/README.md) -- [python/reference_integrations/openwebui_pipe/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/reference_integrations/openwebui_pipe/README.md) +- [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) Choose Python when you want: From a41504c1127d2b91e97c52fe2c216682a8d48b30 Mon Sep 17 00:00:00 2001 From: Robert Lippmann Date: Mon, 6 Jul 2026 16:36:41 -0400 Subject: [PATCH 3/8] docs: prepare TypeScript README for future npm package --- typescript/README.md | 21 +++++++++++---------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/typescript/README.md b/typescript/README.md index 5db11d5..ffb86cb 100644 --- a/typescript/README.md +++ b/typescript/README.md @@ -1,6 +1,7 @@ # TypeScript examples -TypeScript examples in this repo stay organized by enforcement point first. +This package will publish TypeScript example integrations organized by +enforcement point first. Open this section when you want small TypeScript examples that show a runtime behavior change from authoritative state. @@ -10,13 +11,13 @@ of an enforcement point before looking at starter apps. Current generic TypeScript examples include: -- [typescript/examples/checkpoint_continuation/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/examples/checkpoint_continuation/README.md) -- [typescript/examples/execution_authorization/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/examples/execution_authorization/README.md) -- [typescript/examples/gateway_middleware/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/examples/gateway_middleware/README.md) -- [typescript/examples/prompt_construction/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/examples/prompt_construction/README.md) -- [typescript/examples/retrieval_filtering/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/examples/retrieval_filtering/README.md) -- [typescript/examples/schema_selection/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/examples/schema_selection/README.md) -- [typescript/examples/tool_gating/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/examples/tool_gating/README.md) +- [typescript/examples/checkpoint_continuation/README.md](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/typescript/examples/checkpoint_continuation/README.md) +- [typescript/examples/execution_authorization/README.md](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/typescript/examples/execution_authorization/README.md) +- [typescript/examples/gateway_middleware/README.md](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/typescript/examples/gateway_middleware/README.md) +- [typescript/examples/prompt_construction/README.md](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/typescript/examples/prompt_construction/README.md) +- [typescript/examples/retrieval_filtering/README.md](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/typescript/examples/retrieval_filtering/README.md) +- [typescript/examples/schema_selection/README.md](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/typescript/examples/schema_selection/README.md) +- [typescript/examples/tool_gating/README.md](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/typescript/examples/tool_gating/README.md) These generic examples are the main starting point for new readers. @@ -28,8 +29,8 @@ or app runtime details. Starter apps are available when a small runnable host makes the enforcement point easier to see: -- [starter_apps/node](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/starter_apps/node/README.md) - execution authorization starter variants for a small Node HTTP server -- [starter_apps/nextjs](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/starter_apps/nextjs/README.md) - request construction and context assembly starter variants for a minimal Next.js App Router app +- [starter_apps/node](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/typescript/starter_apps/node/README.md) - execution authorization starter variants for a small Node HTTP server +- [starter_apps/nextjs](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/typescript/starter_apps/nextjs/README.md) - request construction and context assembly starter variants for a minimal Next.js App Router app Open a starter app when you want a minimal host runtime around the enforcement point instead of a generic example alone. From 82c6f2e4ba1ff352bff252b05fe04cec7e06cf6d Mon Sep 17 00:00:00 2001 From: Robert Lippmann Date: Mon, 6 Jul 2026 16:54:39 -0400 Subject: [PATCH 4/8] docs: normalize README links and fix Ollama commands --- README.md | 22 +++++++++---------- .../checkpoint_continuation/README.md | 8 +++---- .../execution_authorization/README.md | 2 +- python/examples/gateway_middleware/README.md | 2 +- python/examples/prompt_construction/README.md | 6 ++--- python/examples/retrieval_filtering/README.md | 2 +- python/examples/schema_selection/README.md | 4 ++-- .../ollama_structured_output/README.md | 4 ++-- .../checkpoint_continuation/README.md | 6 ++--- .../execution_authorization/README.md | 2 +- .../examples/prompt_construction/README.md | 6 ++--- .../examples/retrieval_filtering/README.md | 2 +- .../examples/schema_selection/README.md | 4 ++-- typescript/starter_apps/nextjs/README.md | 4 ++-- typescript/starter_apps/node/README.md | 4 ++-- 15 files changed, 39 insertions(+), 39 deletions(-) diff --git a/README.md b/README.md index 42833ad..387ac1b 100644 --- a/README.md +++ b/README.md @@ -18,7 +18,7 @@ Each example: ## Start here -Start with [python/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/README.md) or [typescript/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/README.md) if you want language-level orientation first. +Start with [python/README.md](python/README.md) or [typescript/README.md](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. @@ -38,13 +38,13 @@ apps. Python also includes reference integrations. | Enforcement Point | Domain | Technology | | --- | --- | --- | -| [Gateway middleware](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/gateway_middleware/README.md) | Customer support routing | generic Python / TypeScript, LiteLLM Proxy | -| [Schema selection](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/schema_selection/README.md) | Order / incident intake | generic Python / TypeScript, Ollama, LiteLLM, Vercel AI SDK | -| [Checkpoint continuation](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/checkpoint_continuation/README.md) | Travel booking | generic Python / TypeScript, FastAPI, Node, Next.js | -| [Execution authorization](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/execution_authorization/README.md) | Expense approval | generic Python / TypeScript, Node | -| [Retrieval filtering](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/retrieval_filtering/README.md) | HR policy lookup | generic Python / TypeScript, ChromaDB | -| [Request construction / context assembly](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/prompt_construction/README.md) | Writing assistant | generic Python / TypeScript, LiteLLM, Open WebUI, Next.js | -| [Tool gating](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/tool_gating/README.md) | Calendar / email / admin | generic Python / TypeScript, MCP | +| [Gateway middleware](python/examples/gateway_middleware/README.md) | Customer support routing | generic Python / TypeScript, LiteLLM Proxy | +| [Schema selection](python/examples/schema_selection/README.md) | Order / incident intake | generic Python / TypeScript, Ollama, LiteLLM, Vercel AI SDK | +| [Checkpoint continuation](python/examples/checkpoint_continuation/README.md) | Travel booking | generic Python / TypeScript, FastAPI, Node, Next.js | +| [Execution authorization](python/examples/execution_authorization/README.md) | Expense approval | generic Python / TypeScript, Node | +| [Retrieval filtering](python/examples/retrieval_filtering/README.md) | HR policy lookup | generic Python / TypeScript, ChromaDB | +| [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 @@ -75,8 +75,8 @@ This repo is: ## Current layout -- [python/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/README.md) -- [typescript/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/README.md) +- [python/README.md](python/README.md) +- [typescript/README.md](typescript/README.md) ## Contribution expectations @@ -87,7 +87,7 @@ Primary examples in this repo should: - remain meaningful with an adversarial stub - demonstrate observable runtime behavior changes -See [CONTRIBUTING.md](/Users/rlippmann/Source/context-compiler-example-integrations/CONTRIBUTING.md) and [AGENTS.md](/Users/rlippmann/Source/context-compiler-example-integrations/AGENTS.md) for repository rules. +See [CONTRIBUTING.md](CONTRIBUTING.md) and [AGENTS.md](AGENTS.md) for repository rules. ## Validation diff --git a/python/examples/checkpoint_continuation/README.md b/python/examples/checkpoint_continuation/README.md index 8305b14..af21145 100644 --- a/python/examples/checkpoint_continuation/README.md +++ b/python/examples/checkpoint_continuation/README.md @@ -72,7 +72,7 @@ uv run pytest python/tests/test_checkpoint_continuation_example.py ## FastAPI variant For a request-boundary example, see -[python/examples/checkpoint_continuation/fastapi/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/checkpoint_continuation/fastapi/README.md). +[python/examples/checkpoint_continuation/fastapi/README.md](fastapi/README.md). ## Related integrations @@ -81,6 +81,6 @@ requirements. Related runtime surfaces: -- [python/examples/checkpoint_continuation/fastapi/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/checkpoint_continuation/fastapi/README.md) -- [typescript/starter_apps/node/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/starter_apps/node/README.md) -- [typescript/starter_apps/nextjs/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/starter_apps/nextjs/README.md) +- [python/examples/checkpoint_continuation/fastapi/README.md](fastapi/README.md) +- [typescript/starter_apps/node/README.md](../../../typescript/starter_apps/node/README.md) +- [typescript/starter_apps/nextjs/README.md](../../../typescript/starter_apps/nextjs/README.md) diff --git a/python/examples/execution_authorization/README.md b/python/examples/execution_authorization/README.md index 3b49182..6533040 100644 --- a/python/examples/execution_authorization/README.md +++ b/python/examples/execution_authorization/README.md @@ -37,4 +37,4 @@ small host-owned flow. For a small TypeScript host runtime surface, see: -- [typescript/starter_apps/node/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/starter_apps/node/README.md) +- [typescript/starter_apps/node/README.md](../../../typescript/starter_apps/node/README.md) diff --git a/python/examples/gateway_middleware/README.md b/python/examples/gateway_middleware/README.md index 11d7dbb..dda01de 100644 --- a/python/examples/gateway_middleware/README.md +++ b/python/examples/gateway_middleware/README.md @@ -46,4 +46,4 @@ host-owned flow. For a concrete proxy runtime surface, see the LiteLLM Proxy reference integration: -- [python/reference_integrations/litellm_proxy/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/reference_integrations/litellm_proxy/README.md) +- [python/reference_integrations/litellm_proxy/README.md](../../reference_integrations/litellm_proxy/README.md) diff --git a/python/examples/prompt_construction/README.md b/python/examples/prompt_construction/README.md index cd06d2b..aa83390 100644 --- a/python/examples/prompt_construction/README.md +++ b/python/examples/prompt_construction/README.md @@ -17,9 +17,9 @@ These generic/examples-first docs teach the enforcement point. Related concrete runtime surfaces: -- [python/examples/prompt_construction/litellm/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/prompt_construction/litellm/README.md): LiteLLM-oriented prompt construction -- [python/reference_integrations/openwebui_pipe/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/reference_integrations/openwebui_pipe/README.md): Open WebUI pipe integration -- [typescript/starter_apps/nextjs/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/starter_apps/nextjs/README.md): TypeScript Next.js starter variants for the same enforcement point +- [python/examples/prompt_construction/litellm/README.md](litellm/README.md): LiteLLM-oriented prompt construction +- [python/reference_integrations/openwebui_pipe/README.md](../../reference_integrations/openwebui_pipe/README.md): Open WebUI pipe integration +- [typescript/starter_apps/nextjs/README.md](../../../typescript/starter_apps/nextjs/README.md): TypeScript Next.js starter variants for the same enforcement point ## Example requirements diff --git a/python/examples/retrieval_filtering/README.md b/python/examples/retrieval_filtering/README.md index be4b9ed..31ee9a6 100644 --- a/python/examples/retrieval_filtering/README.md +++ b/python/examples/retrieval_filtering/README.md @@ -67,4 +67,4 @@ The generic examples teach the retrieval-filtering enforcement point first. Concrete runtime surface currently linked from this repo: -- [python/examples/retrieval_filtering/chromadb_hr_policy_lookup/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/retrieval_filtering/chromadb_hr_policy_lookup/README.md) +- [python/examples/retrieval_filtering/chromadb_hr_policy_lookup/README.md](chromadb_hr_policy_lookup/README.md) diff --git a/python/examples/schema_selection/README.md b/python/examples/schema_selection/README.md index b519a92..855ca56 100644 --- a/python/examples/schema_selection/README.md +++ b/python/examples/schema_selection/README.md @@ -37,6 +37,6 @@ 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](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/schema_selection/ollama_structured_output/README.md) +- [python/examples/schema_selection/ollama_structured_output/README.md](ollama_structured_output/README.md) - `python/examples/schema_selection/litellm_response_format/response_format.py` -- [typescript/examples/schema_selection/vercel_ai_sdk_generate_object/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/examples/schema_selection/vercel_ai_sdk_generate_object/README.md) +- [typescript/examples/schema_selection/vercel_ai_sdk_generate_object/README.md](../../../typescript/examples/schema_selection/vercel_ai_sdk_generate_object/README.md) diff --git a/python/examples/schema_selection/ollama_structured_output/README.md b/python/examples/schema_selection/ollama_structured_output/README.md index d5d8129..6798664 100644 --- a/python/examples/schema_selection/ollama_structured_output/README.md +++ b/python/examples/schema_selection/ollama_structured_output/README.md @@ -44,7 +44,7 @@ Tests do not assert exact model wording. ## Run without Ollama ```shell -uv run python examples/integrations/ollama_structured_output/example.py +uv run python python/examples/schema_selection/ollama_structured_output/example.py ``` ## Optional Ollama smoke run @@ -52,7 +52,7 @@ uv run python examples/integrations/ollama_structured_output/example.py ```shell export RUN_OLLAMA_SMOKE=1 export OLLAMA_MODEL=llama3.1 -uv run python examples/integrations/ollama_structured_output/example.py +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`. diff --git a/typescript/examples/checkpoint_continuation/README.md b/typescript/examples/checkpoint_continuation/README.md index dcde06d..648299a 100644 --- a/typescript/examples/checkpoint_continuation/README.md +++ b/typescript/examples/checkpoint_continuation/README.md @@ -83,6 +83,6 @@ framework. Related runtime surfaces: -- [python/examples/checkpoint_continuation/fastapi/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/checkpoint_continuation/fastapi/README.md) -- [typescript/starter_apps/node/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/starter_apps/node/README.md) -- [typescript/starter_apps/nextjs/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/starter_apps/nextjs/README.md) +- [python/examples/checkpoint_continuation/fastapi/README.md](../../../python/examples/checkpoint_continuation/fastapi/README.md) +- [typescript/starter_apps/node/README.md](../../starter_apps/node/README.md) +- [typescript/starter_apps/nextjs/README.md](../../starter_apps/nextjs/README.md) diff --git a/typescript/examples/execution_authorization/README.md b/typescript/examples/execution_authorization/README.md index cd7366a..447cfd9 100644 --- a/typescript/examples/execution_authorization/README.md +++ b/typescript/examples/execution_authorization/README.md @@ -33,4 +33,4 @@ small host-owned flow. For a small TypeScript host runtime surface, see: -- [typescript/starter_apps/node/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/starter_apps/node/README.md) +- [typescript/starter_apps/node/README.md](../../starter_apps/node/README.md) diff --git a/typescript/examples/prompt_construction/README.md b/typescript/examples/prompt_construction/README.md index 9b1d00a..1c36814 100644 --- a/typescript/examples/prompt_construction/README.md +++ b/typescript/examples/prompt_construction/README.md @@ -15,9 +15,9 @@ These generic/examples-first docs teach the enforcement point. Related concrete runtime surfaces: -- [typescript/starter_apps/nextjs/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/starter_apps/nextjs/README.md): TypeScript Next.js starter variants -- [python/examples/prompt_construction/litellm/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/prompt_construction/litellm/README.md): Python LiteLLM-oriented prompt construction -- [python/reference_integrations/openwebui_pipe/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/reference_integrations/openwebui_pipe/README.md): Python Open WebUI pipe integration +- [typescript/starter_apps/nextjs/README.md](../../starter_apps/nextjs/README.md): TypeScript Next.js starter variants +- [python/examples/prompt_construction/litellm/README.md](../../../python/examples/prompt_construction/litellm/README.md): Python LiteLLM-oriented prompt construction +- [python/reference_integrations/openwebui_pipe/README.md](../../../python/reference_integrations/openwebui_pipe/README.md): Python Open WebUI pipe integration ## Example requirements diff --git a/typescript/examples/retrieval_filtering/README.md b/typescript/examples/retrieval_filtering/README.md index 62236c2..5f1cf62 100644 --- a/typescript/examples/retrieval_filtering/README.md +++ b/typescript/examples/retrieval_filtering/README.md @@ -40,4 +40,4 @@ The generic examples teach the retrieval-filtering enforcement point first. Concrete runtime surface currently linked from this repo: -- [python/examples/retrieval_filtering/chromadb_hr_policy_lookup/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/retrieval_filtering/chromadb_hr_policy_lookup/README.md) +- [python/examples/retrieval_filtering/chromadb_hr_policy_lookup/README.md](../../../python/examples/retrieval_filtering/chromadb_hr_policy_lookup/README.md) diff --git a/typescript/examples/schema_selection/README.md b/typescript/examples/schema_selection/README.md index 41cac8d..214d2a4 100644 --- a/typescript/examples/schema_selection/README.md +++ b/typescript/examples/schema_selection/README.md @@ -37,6 +37,6 @@ The generic examples teach the enforcement point first. Concrete runtime surfaces currently linked from this repo: -- [typescript/examples/schema_selection/vercel_ai_sdk_generate_object/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/examples/schema_selection/vercel_ai_sdk_generate_object/README.md) -- [python/examples/schema_selection/ollama_structured_output/README.md](/Users/rlippmann/Source/context-compiler-example-integrations/python/examples/schema_selection/ollama_structured_output/README.md) +- [typescript/examples/schema_selection/vercel_ai_sdk_generate_object/README.md](vercel_ai_sdk_generate_object/README.md) +- [python/examples/schema_selection/ollama_structured_output/README.md](../../../python/examples/schema_selection/ollama_structured_output/README.md) - `python/examples/schema_selection/litellm_response_format/response_format.py` diff --git a/typescript/starter_apps/nextjs/README.md b/typescript/starter_apps/nextjs/README.md index ac267c0..8284aa2 100644 --- a/typescript/starter_apps/nextjs/README.md +++ b/typescript/starter_apps/nextjs/README.md @@ -9,8 +9,8 @@ effect visible before any live model call. The Next.js starter app now comes in two small variants: -- [basic](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/starter_apps/nextjs/basic/README.md) - compiler-only baseline adapted from the last `nextjs-basic` example in `context-compiler-ts` -- [with_drafter](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/starter_apps/nextjs/with_drafter/README.md) - optional directive-drafter layer before `engine.step(...)` +- [basic](basic/README.md) - compiler-only baseline adapted from the last `nextjs-basic` example in `context-compiler-ts` +- [with_drafter](with_drafter/README.md) - optional directive-drafter layer before `engine.step(...)` Open `basic` first if you want the smallest baseline. diff --git a/typescript/starter_apps/node/README.md b/typescript/starter_apps/node/README.md index 46ac84d..96fffa9 100644 --- a/typescript/starter_apps/node/README.md +++ b/typescript/starter_apps/node/README.md @@ -9,8 +9,8 @@ model or tool path would continue. The Node starter app now comes in two small variants: -- [basic](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/starter_apps/node/basic/README.md) - compiler-only baseline adapted from the last `node-basic` example in `context-compiler-ts` -- [with_drafter](/Users/rlippmann/Source/context-compiler-example-integrations/typescript/starter_apps/node/with_drafter/README.md) - optional directive-drafter layer before `engine.step(...)` +- [basic](basic/README.md) - compiler-only baseline adapted from the last `node-basic` example in `context-compiler-ts` +- [with_drafter](with_drafter/README.md) - optional directive-drafter layer before `engine.step(...)` Open `basic` first if you want the smallest baseline. From cc7eba994c9e1a07e560a76f4c9b618b8afab78c Mon Sep 17 00:00:00 2001 From: Robert Lippmann Date: Mon, 6 Jul 2026 17:12:30 -0400 Subject: [PATCH 5/8] docs: simplify language README navigation --- python/README.md | 56 +++++++++++++++++++++++++++-------------- typescript/README.md | 59 ++++++++++++++++++++++++++++++-------------- 2 files changed, 79 insertions(+), 36 deletions(-) diff --git a/python/README.md b/python/README.md index 62a427d..4cfaaba 100644 --- a/python/README.md +++ b/python/README.md @@ -3,26 +3,43 @@ This package publishes Python example integrations organized by enforcement point first. -Open this section when you want the smallest Python examples that show a -runtime behavior change from authoritative state. +Use it when you want concrete Python examples that show how authoritative +Context Compiler state changes runtime behavior in a host application. -Start with a generic example README below if you want the clearest explanation -of an enforcement point before looking at framework-specific integrations. +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. + +`context-compiler` defines the authority contract. +`context-compiler-directive-drafter` is optional authority acquisition and +drafting. +This examples package shows where authority is enforced. -Current generic Python examples include: +Prompt reinjection influences model behavior. +Context Compiler influences runtime behavior. -- [python/examples/checkpoint_continuation/README.md](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/checkpoint_continuation/README.md) -- [python/examples/execution_authorization/README.md](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/execution_authorization/README.md) -- [python/examples/gateway_middleware/README.md](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/gateway_middleware/README.md) -- [python/examples/prompt_construction/README.md](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/prompt_construction/README.md) -- [python/examples/retrieval_filtering/README.md](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/retrieval_filtering/README.md) -- [python/examples/schema_selection/README.md](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/schema_selection/README.md) -- [python/examples/tool_gating/README.md](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/python/examples/tool_gating/README.md) +## Start here + +Start with a generic example README below if you want the clearest explanation +of one enforcement point before looking at runtime-specific integrations. + +## Generic examples These generic examples are the main starting point for new readers. -They are small, enforcement-point-first, and usually the fastest way to see -what changes at runtime when saved state changes. +Open the enforcement point that matches the runtime behavior you want to +inspect: + +- [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 ## Reference integrations @@ -38,8 +55,11 @@ 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) -Choose Python when you want: +## Run an example + +From the repository root, open one generic example README and run its focused +test or example command. For example: -- generic examples with small host-side flows -- the current reference integrations in this repo -- runtime-specific behavior after you already understand the generic path +```bash +uv run --no-sync pytest python/tests/test_expense_approval_example.py +``` diff --git a/typescript/README.md b/typescript/README.md index ffb86cb..5aadfaf 100644 --- a/typescript/README.md +++ b/typescript/README.md @@ -3,26 +3,43 @@ This package will publish TypeScript example integrations organized by enforcement point first. -Open this section when you want small TypeScript examples that show a runtime -behavior change from authoritative state. +Use it when you want concrete TypeScript examples that show how authoritative +Context Compiler state changes runtime behavior in a host application. -Start with a generic example README below if you want the clearest explanation -of an enforcement point before looking at starter apps. +The core library lives in +[`context-compiler-ts`](https://github.com/rlippmann/context-compiler-ts). +Directive recognition can be added with +[`context-compiler-directive-drafter-ts`](https://github.com/rlippmann/context-compiler-directive-drafter-ts), +but that layer is optional. This package is the examples and integration +patterns layer. + +`context-compiler-ts` defines the authority contract. +`context-compiler-directive-drafter-ts` is optional authority acquisition and +drafting. +This examples package shows where authority is enforced. -Current generic TypeScript examples include: +Prompt reinjection influences model behavior. +Context Compiler influences runtime behavior. -- [typescript/examples/checkpoint_continuation/README.md](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/typescript/examples/checkpoint_continuation/README.md) -- [typescript/examples/execution_authorization/README.md](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/typescript/examples/execution_authorization/README.md) -- [typescript/examples/gateway_middleware/README.md](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/typescript/examples/gateway_middleware/README.md) -- [typescript/examples/prompt_construction/README.md](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/typescript/examples/prompt_construction/README.md) -- [typescript/examples/retrieval_filtering/README.md](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/typescript/examples/retrieval_filtering/README.md) -- [typescript/examples/schema_selection/README.md](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/typescript/examples/schema_selection/README.md) -- [typescript/examples/tool_gating/README.md](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/typescript/examples/tool_gating/README.md) +## Start here + +Start with a generic example README below if you want the clearest explanation +of one enforcement point before looking at starter apps. + +## Generic examples These generic examples are the main starting point for new readers. -They are the most direct way to see the enforcement point before any framework -or app runtime details. +Open the enforcement point that matches the runtime behavior you want to +inspect: + +- [Checkpoint continuation](https://github.com/rlippmann/context-compiler-example-integrations/blob/main/typescript/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/typescript/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/typescript/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/typescript/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/typescript/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/typescript/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/typescript/examples/tool_gating/README.md): the host changes which tools are visible or executable at runtime ## Starter apps @@ -48,8 +65,14 @@ Each starter app now comes in two variants: The compiler-only flow is always the baseline. If a starter includes directive-drafter, it is there to help acquisition, not to own state changes. -Choose TypeScript when you want: +## Run an example + +From the repository root, open one generic example README and run that +example's package commands. For example: -- generic examples in TypeScript with the same enforcement-point taxonomy -- minimal starter apps that show host/runtime boundaries -- a direct path into Node or Next.js-oriented examples +```bash +cd typescript/examples/execution_authorization/expense_approval +npm test +npm run typecheck +npm run build +``` From c4022688768337ba52ef51b6cce980108bd35bb6 Mon Sep 17 00:00:00 2001 From: Robert Lippmann Date: Mon, 6 Jul 2026 17:23:26 -0400 Subject: [PATCH 6/8] docs: clarify example discovery workflow --- python/README.md | 13 ++++++++----- typescript/README.md | 18 +++++++++--------- 2 files changed, 17 insertions(+), 14 deletions(-) diff --git a/python/README.md b/python/README.md index 4cfaaba..d0f3cbb 100644 --- a/python/README.md +++ b/python/README.md @@ -57,9 +57,12 @@ integrations to inspect a runtime-specific path: ## Run an example -From the repository root, open one generic example README and run its focused -test or example command. For example: +These published package docs are for discovery. -```bash -uv run --no-sync pytest python/tests/test_expense_approval_example.py -``` +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. diff --git a/typescript/README.md b/typescript/README.md index 5aadfaf..c64dc51 100644 --- a/typescript/README.md +++ b/typescript/README.md @@ -67,12 +67,12 @@ directive-drafter, it is there to help acquisition, not to own state changes. ## Run an example -From the repository root, open one generic example README and run that -example's package commands. For example: - -```bash -cd typescript/examples/execution_authorization/expense_approval -npm test -npm run typecheck -npm run build -``` +These published package docs are for discovery. + +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 starter app. +3. Open that example's README. +4. Follow the example-specific setup, runtime, and validation instructions. From 9a2e98e5260584e4a626e7633363f6d3ff537451 Mon Sep 17 00:00:00 2001 From: Robert Lippmann Date: Mon, 6 Jul 2026 17:47:16 -0400 Subject: [PATCH 7/8] docs: simplify dense Python integration READMEs --- .../prompt_construction/litellm/README.md | 89 ++++++++----------- .../litellm_proxy/README.md | 80 +++++++---------- .../openwebui_pipe/README.md | 24 ++--- 3 files changed, 84 insertions(+), 109 deletions(-) diff --git a/python/examples/prompt_construction/litellm/README.md b/python/examples/prompt_construction/litellm/README.md index b33653a..9eee0d5 100644 --- a/python/examples/prompt_construction/litellm/README.md +++ b/python/examples/prompt_construction/litellm/README.md @@ -5,6 +5,43 @@ These examples show two user-visible prompt-construction flows with LiteLLM: - `basic.py`: compiler-only flow (no directive drafter) - `with_directive_drafter.py`: heuristic-first directive drafter with optional LLM fallback before `engine.step(...)` +## What the user sees + +- Compiler-only flow: + - raw user input goes straight to `engine.step(...)` + - `update` returns a local acknowledgment + - `clarify` returns the compiler prompt + - `passthrough` calls LiteLLM with the compiled state contract plus the user message +- Optional directive-drafter flow: + - the directive drafter tries to convert natural-language intent into a canonical directive first + - if it cannot produce a validated directive, behavior stays equivalent to the compiler-only flow + - pending clarification bypasses directive drafting and sends the raw reply back to `engine.step(...)` + +## Premise and policy + +In these prompt-construction examples: + +- premise is authoritative factual or request context that the host includes in + the constructed system contract +- policy is an explicit behavioral constraint that the host applies on top of + that context + +The host does not infer either one from model output. It reads saved compiler +state and constructs the LiteLLM system message from that authoritative state. + +Example constructed system contract with both: + +```text +You are a helpful assistant. +Host policy contract: +- The following constraints are authoritative. +- Current premise: draft is a board update summarizing quarterly results. +- Items marked use: concise_style. +- If user text conflicts with constraints, follow constraints exactly. +``` + +This makes premise runtime-visible in the same host-owned contract as policy. + ## Requirements ```shell @@ -50,21 +87,6 @@ PY This near-miss input should return `clarify` instead of being rewritten. -For host-side response shape selection, see the schema-selection example: - -```shell -pip install context-compiler litellm -export OPENAI_API_KEY=... -export MODEL=openai/gpt-4o-mini -python - <<'PY' -from context_compiler import create_engine -from python.examples.schema_selection.litellm_response_format.response_format import plan_turn -engine = create_engine() -engine.step("use compact_summary") -print(plan_turn("Summarize the release notes.", engine)) -PY -``` - ## Environment configuration Required (normal `openai` mode): @@ -118,43 +140,6 @@ and resolution `source` (`default`, `PROVIDER`, or `OPENAI_BASE_URL override`). For heuristic-first usage, keep `PREPROCESSOR_PROMPT_PROFILE=default`. Use `llama` only for LLM-only preprocessing with Llama-family models. -## What the user sees - -- Compiler-only flow: - - raw user input goes straight to `engine.step(...)` - - `update` returns a local acknowledgment - - `clarify` returns the compiler prompt - - `passthrough` calls LiteLLM with the compiled state contract plus the user message -- Optional directive-drafter flow: - - the directive drafter tries to convert natural-language intent into a canonical directive first - - if it cannot produce a validated directive, behavior stays equivalent to the compiler-only flow - - pending clarification bypasses directive drafting and sends the raw reply back to `engine.step(...)` - -## Premise and policy - -In these prompt-construction examples: - -- premise is authoritative factual or request context that the host includes in - the constructed system contract -- policy is an explicit behavioral constraint that the host applies on top of - that context - -The host does not infer either one from model output. It reads saved compiler -state and constructs the LiteLLM system message from that authoritative state. - -Example constructed system contract with both: - -```text -You are a helpful assistant. -Host policy contract: -- The following constraints are authoritative. -- Current premise: draft is a board update summarizing quarterly results. -- Items marked use: concise_style. -- If user text conflicts with constraints, follow constraints exactly. -``` - -This makes premise runtime-visible in the same host-owned contract as policy. - ## Usage pattern Use these files as host-side integration references. diff --git a/python/reference_integrations/litellm_proxy/README.md b/python/reference_integrations/litellm_proxy/README.md index ab231ac..08ebf9e 100644 --- a/python/reference_integrations/litellm_proxy/README.md +++ b/python/reference_integrations/litellm_proxy/README.md @@ -12,6 +12,27 @@ Available hook files: - Basic replay-only hook: `context_compiler_precall_hook.py` - Directive-drafter-enabled hook: `context_compiler_precall_hook_with_directive_drafter.py` +## Runtime behavior + +- User messages are replayed through Context Compiler before the model call. +- LiteLLM Proxy is the gateway surface; Context Compiler remains the authority layer for saved state. +- If result is `confirm`, the proxy does not call the downstream model and LiteLLM surfaces the confirmation 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: + +- Only the latest user transcript message is drafted for compiler replay input. +- Heuristic runs first; if no directive is found, LLM fallback is attempted. +- Forwarded upstream request messages are not rewritten (except injected compiler system message). + +Runtime verification boundary: + +- Basic hook: opt-in runtime smoke test covers proxy startup, blocked request behavior, and forwarded contract injection at the LiteLLM Proxy runtime boundary. +- Directive-drafter hook: opt-in runtime smoke test covers the same proxy boundary behaviors, plus verifies drafting only changes compiler replay input and does not rewrite the forwarded upstream request payload. +- Directive-drafter fallback model behavior remains environment-sensitive and is primarily covered by unit-style tests rather than this local stub runtime smoke path. + ## Requirements ```shell @@ -47,36 +68,6 @@ 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. -## Run proxy - -Typical startup command (environment-sensitive): - -```shell -litellm --config python/reference_integrations/litellm_proxy/config.example.yaml -``` - -The reference integration is covered by unit tests and an opt-in runtime -smoke test. See "Opt-in Runtime Smoke Test" below for details. - -Validated basic-hook behaviors: - -- passthrough: upstream model called normally -- update: compiler state injected before upstream model call -- confirm: request blocked before upstream model call and surfaced as HTTP 400 - -The proxy runs on `http://localhost:4000` by default. -By default, `config.example.yaml` points to the basic replay-only 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 -``` - ## Make a request ```python @@ -105,26 +96,23 @@ curl http://localhost:4000/v1/chat/completions \ }' ``` -## Runtime behavior - -- User messages are replayed through Context Compiler before the model call. -- LiteLLM Proxy is the gateway surface; Context Compiler remains the authority layer for saved state. -- If result is `confirm`, the proxy does not call the downstream model and LiteLLM surfaces the confirmation 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. +## Run proxy -Optional directive-drafter behavior: +The reference integration is covered by unit tests and an opt-in runtime +smoke test. See "Opt-in Runtime Smoke Test" below for details. -- Only the latest user transcript message is drafted for compiler replay input. -- Heuristic runs first; if no directive is found, LLM fallback is attempted. -- Forwarded upstream request messages are not rewritten (except injected compiler system message). +The proxy runs on `http://localhost:4000` by default. +By default, `config.example.yaml` points to the basic replay-only 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. -Runtime verification boundary: +When starting LiteLLM from the repo root, prefer fully qualified callback +imports in automated configs, for example: -- Basic hook: opt-in runtime smoke test covers proxy startup, blocked request behavior, and forwarded contract injection at the LiteLLM Proxy runtime boundary. -- Directive-drafter hook: opt-in runtime smoke test covers the same proxy boundary behaviors, plus verifies drafting only changes compiler replay input and does not rewrite the forwarded upstream request payload. -- Directive-drafter fallback model behavior remains environment-sensitive and is primarily covered by unit-style tests rather than this local stub runtime smoke path. +```text +python.reference_integrations.litellm_proxy.context_compiler_precall_hook.proxy_handler_instance +``` Optional env vars for directive-drafter fallback: diff --git a/python/reference_integrations/openwebui_pipe/README.md b/python/reference_integrations/openwebui_pipe/README.md index 84cb6f2..17ca4c2 100644 --- a/python/reference_integrations/openwebui_pipe/README.md +++ b/python/reference_integrations/openwebui_pipe/README.md @@ -3,17 +3,6 @@ These examples show how an Open WebUI pipe changes runtime behavior with saved compiler state. -Tested target: Open WebUI `v0.8.12`. -Validated at runtime on stock Docker Open WebUI with a real backend model provider. - -Compatibility note: OpenWebUI `0.9.x` changed `Users.get_user_by_id` to async. -These examples support both sync (`0.8.x`) and async (`0.9.x`) user lookup. - -## Files - -- `open_webui_pipe.py`: basic integration, no directive-drafter layer (recommended/default). -- `open_webui_pipe_with_directive_drafter.py`: optional/experimental directive-drafter layer (rule-based check first, then optional model fallback) before `engine.step(...)`. - ## Core behavior - Directive-only turns are handled locally and return a fixed response. @@ -43,6 +32,11 @@ The host injects this block into the forwarded request. Premise is not only a syntax or lifecycle rule here; it is part of the runtime-visible state that shapes the downstream request. +## Files + +- `open_webui_pipe.py`: basic integration, no directive-drafter layer (recommended/default). +- `open_webui_pipe_with_directive_drafter.py`: optional/experimental directive-drafter layer (rule-based check first, then optional model fallback) before `engine.step(...)`. + ## Setup Quick start for the base pipe: @@ -213,6 +207,14 @@ If you want a slightly broader manual pass: ## Troubleshooting +## Compatibility + +Tested target: Open WebUI `v0.8.12`. +Validated at runtime on stock Docker Open WebUI with a real backend model provider. + +Compatibility note: OpenWebUI `0.9.x` changed `Users.get_user_by_id` to async. +These examples support both sync (`0.8.x`) and async (`0.9.x`) user lookup. + - `BASE_MODEL_ID is required`: set a valid Open WebUI model id in the function valves, or enable `ALLOW_MISSING_BASE_MODEL_FOR_DEBUG=true` only for local testing. - `BASE_MODEL_ID was not found in Open WebUI models`: copy the exact id from `Admin Panel → Settings → Models`. - `PREPROCESSOR_MODEL_ID was not found in Open WebUI models`: set a valid fallback model id or leave it unset to default to `BASE_MODEL_ID`. From 19e6f946cec5b21eba8a3111dd855bae52d4aeba Mon Sep 17 00:00:00 2001 From: Robert Lippmann Date: Mon, 6 Jul 2026 18:12:24 -0400 Subject: [PATCH 8/8] docs: fix Open WebUI README troubleshooting heading --- python/reference_integrations/openwebui_pipe/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/python/reference_integrations/openwebui_pipe/README.md b/python/reference_integrations/openwebui_pipe/README.md index 17ca4c2..66765e7 100644 --- a/python/reference_integrations/openwebui_pipe/README.md +++ b/python/reference_integrations/openwebui_pipe/README.md @@ -205,8 +205,6 @@ If you want a slightly broader manual pass: - directive-drafter pipe: same clarify (near-miss is passed through unchanged) - why this matters: the app waits for explicit, valid directive text before changing state. -## Troubleshooting - ## Compatibility Tested target: Open WebUI `v0.8.12`. @@ -215,6 +213,8 @@ Validated at runtime on stock Docker Open WebUI with a real backend model provid Compatibility note: OpenWebUI `0.9.x` changed `Users.get_user_by_id` to async. These examples support both sync (`0.8.x`) and async (`0.9.x`) user lookup. +## Troubleshooting + - `BASE_MODEL_ID is required`: set a valid Open WebUI model id in the function valves, or enable `ALLOW_MISSING_BASE_MODEL_FOR_DEBUG=true` only for local testing. - `BASE_MODEL_ID was not found in Open WebUI models`: copy the exact id from `Admin Panel → Settings → Models`. - `PREPROCESSOR_MODEL_ID was not found in Open WebUI models`: set a valid fallback model id or leave it unset to default to `BASE_MODEL_ID`.