From 0e923284d4c1194a1f390fd75cd361cb48c8efd3 Mon Sep 17 00:00:00 2001 From: Robert Lippmann Date: Wed, 27 May 2026 02:05:36 -0400 Subject: [PATCH 1/4] chore: bump version to 0.7.3 --- pyproject.toml | 2 +- uv.lock | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/pyproject.toml b/pyproject.toml index 5910ed0..e87c6c8 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "context-compiler" -version = "0.7.2" +version = "0.7.3" description = "Deterministic conversational state engine for LLM applications." readme = "README.md" requires-python = ">=3.11" diff --git a/uv.lock b/uv.lock index f433f94..d128a0c 100644 --- a/uv.lock +++ b/uv.lock @@ -468,7 +468,7 @@ wheels = [ [[package]] name = "context-compiler" -version = "0.7.2" +version = "0.7.3" source = { editable = "." } [package.optional-dependencies] From 74d2b2643e2e4552faf243e9d6adb94640c96cb8 Mon Sep 17 00:00:00 2001 From: Robert Lippmann Date: Wed, 27 May 2026 02:06:41 -0400 Subject: [PATCH 2/4] docs: clarify documentation style guidance --- AGENTS.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index 831789c..d1b3d03 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -105,6 +105,10 @@ Prefer plain, concrete wording when accurate. Examples: Avoid describing features only in architectural terms when a behavior-first explanation is possible. +Prefer direct subjects and strong verbs. +Avoid noun stacks and passive phrasing when a simpler active sentence is clearer. +Use simpler wording unless technical precision requires formal terminology. + Specification and contract documents are different: - preserve precise terminology - preserve unambiguous behavioral guarantees From 8dc7ba1a37dfbaa184f28db1146becd7ac2a6183 Mon Sep 17 00:00:00 2001 From: Robert Lippmann Date: Wed, 27 May 2026 02:11:08 -0400 Subject: [PATCH 3/4] docs: simplify documentation wording --- README.md | 12 ++++++------ docs/DescriptionAndMilestones.md | 12 ++++++------ docs/DesignPhilosophy.md | 8 ++++---- docs/llm-preprocessor.md | 9 ++++----- docs/multi-engine.md | 6 +++--- examples/integrations/README.md | 2 +- examples/integrations/litellm/README.md | 2 +- examples/integrations/litellm_proxy/README.md | 2 +- examples/integrations/openwebui/README.md | 10 +++++----- experimental/preprocessor/README.md | 10 +++++----- 10 files changed, 36 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 09ebbec..35600c0 100644 --- a/README.md +++ b/README.md @@ -4,11 +4,11 @@ [![Python versions](https://img.shields.io/pypi/pyversions/context-compiler)](https://pypi.org/project/context-compiler/) [![License](https://img.shields.io/pypi/l/context-compiler)](https://pypi.org/project/context-compiler/) -Some behaviors require explicit host-side state machinery. +Some behaviors require explicit host-side state handling. Context Compiler is a deterministic host-side state layer for LLM applications. -It handles explicit state transitions for premise and policies so that mutation -rules are fixed and repeatable. +It applies explicit premise and policy updates so state changes stay fixed and +repeatable. ## What prompting and reinjection can do @@ -23,17 +23,17 @@ pending confirmations from checkpoints. ## What prompting cannot do by itself Prompt text (including reinjected state text) helps, but it does not give your -app controlled rules for when state can change. By itself, it does not provide: +app clear rules for when state can change. By itself, it does not provide: - rules your app controls for state changes - replacement precondition checks (`use X instead of Y` when `Y` may be absent) - confirmation flows that must complete before anything else changes -- clear decisions about when a change is blocked +- clear rules for when to block a change - reliable checkpoint restore for both saved state and pending confirmation flow ## What Context Compiler provides -Context Compiler provides fixed host-side state machinery: +Context Compiler provides fixed host-side state handling: - deterministic directive handling for explicit user state changes - clarification instead of silent overwrite for blocked/ambiguous changes diff --git a/docs/DescriptionAndMilestones.md b/docs/DescriptionAndMilestones.md index f83ee5f..ff1fc67 100644 --- a/docs/DescriptionAndMilestones.md +++ b/docs/DescriptionAndMilestones.md @@ -10,9 +10,9 @@ conversations, and state can conflict over time. This project adds a deterministic state layer that is independent of the model. The model handles interpretation and generation; the engine handles premise and policies. Only explicit user directives can change state. -By separating reasoning from state ownership, the system improves reliability -without requiring model retraining. The system never derives authoritative state -from model responses. +When the model reasons and the engine owns state, behavior stays reliable +without retraining the model. The system never derives authoritative state from +model responses. The goal is not to make the model smarter, but to make interactions predictable: once a statement is corrected or scoped, future responses must respect that change. @@ -64,7 +64,7 @@ After correcting or constraining the assistant once, the behavior remains consis ### M3 — Cross-Session Recall (implemented, engine-level / host-enabled) **Goal** -Extend app-level workflows around persisted exported state safely and intentionally. +Help apps safely reuse saved exported state. **Core capability:** @@ -77,8 +77,8 @@ Extend app-level workflows around persisted exported state safely and intentiona **Deliverables:** -- App-side storage/recovery patterns built on the existing import/export API -- App-side storage/recovery patterns for checkpoint object/checkpoint JSON continuation restore +- App-side storage and recovery patterns built on the existing import/export API +- App-side storage and recovery patterns for checkpoint object and checkpoint JSON restore **User-visible outcome:** diff --git a/docs/DesignPhilosophy.md b/docs/DesignPhilosophy.md index 059bed9..2aaded7 100644 --- a/docs/DesignPhilosophy.md +++ b/docs/DesignPhilosophy.md @@ -2,7 +2,7 @@ ## The Problem with Implicit State -Modern LLM applications typically manage conversational state implicitly — the model reads the transcript, infers what constraints are active, and generates a response accordingly. This works well for short conversations and simple tasks. +Modern LLM applications often manage conversational state implicitly: the model reads the transcript, infers active constraints, and generates a response. This works well for short conversations and simple tasks. It breaks down reliably in longer conversations, correction flows, and multi-turn constraint management. Constraints drift. Corrections get partially applied or treated as additive rather than authoritative replacements. Contradictions accumulate instead of resolving. The model interprets intent rather than enforcing it. @@ -16,7 +16,7 @@ Explicit state management is not a new idea. Earlier AI systems maintained struc The core insight is simple: maintain an explicit active set of rules rather than inferring the relevant context from history each time. What is in the active set is known with certainty. What is not in it is not active. -These approaches succeeded in narrow, well-defined domains precisely because explicit state gives you guarantees that implicit inference cannot. The limitation was not the state management approach — it was that handling natural language and ambiguity was extraordinarily difficult. Those problems consumed most of the design effort. +These approaches succeeded in narrow, well-defined domains because explicit state gives guarantees that implicit inference cannot. The limitation was not state management itself. Handling natural language and ambiguity was the hard part, and that work consumed most of the design effort. Modern LLMs handle natural language interpretation and generation far more effectively than earlier systems. This changes the calculus: the language interface problem is largely addressed. As end-to-end neural approaches became dominant, many systems shifted toward transcript-driven implicit state management, assuming a capable model could handle state implicitly. @@ -26,8 +26,8 @@ That assumption is incorrect in practice, for the structural reason described ab Context Compiler applies explicit state management to the modern LLM context, with a clear division of responsibilities: -- The LLM handles what it is genuinely good at — language understanding, reasoning, generation, handling ambiguity in user intent -- The deterministic engine handles what probabilistic systems handle poorly — maintaining explicit state across turns, enforcing constraints, guaranteeing that corrections replace rather than compete with prior state +- The LLM handles what it does well: language understanding, reasoning, generation, and ambiguity in user intent +- The deterministic engine handles what probabilistic systems handle poorly: keep explicit state across turns, enforce constraints, and make corrections replace prior state instead of competing with it The preprocessor layer bridges the two: it uses the LLM's language understanding to translate natural language directive intent into canonical form, which the deterministic engine can then process reliably. Fuzzy where it needs to be fuzzy, deterministic where determinism matters. diff --git a/docs/llm-preprocessor.md b/docs/llm-preprocessor.md index b4b6f7a..dbf891d 100644 --- a/docs/llm-preprocessor.md +++ b/docs/llm-preprocessor.md @@ -15,8 +15,7 @@ layer. Do not rely on repo-relative preprocessor paths. ## Architectural framing -The preprocessor is a helper layer in your app, not the source of truth for -state changes. +The preprocessor helps your app, but it does not own state changes. Model/tool-description translation can help with simple direct cases, but integrations should not rely on model intent translation alone to decide when @@ -25,10 +24,10 @@ state changes. In simpler hosts without an embedded model, this preprocessor provides a conservative translation path. -In model-assisted hosts, the app still checks outputs before applying them. +In model-assisted hosts, the app still validates outputs before applying them. Both paths send canonical directives to the same deterministic engine. The -engine still controls state updates. +engine controls state updates. In MCP/tool-calling environments, over-eager tool calling on conversational or ambiguous input is a known failure mode. Conservative preprocessing and @@ -36,7 +35,7 @@ validation help reduce unintended mutation. ## Required flow -Recommended conceptual flow: +Recommended flow: 1. heuristic preprocessing 2. validate candidate output diff --git a/docs/multi-engine.md b/docs/multi-engine.md index e7c3a0c..858179c 100644 --- a/docs/multi-engine.md +++ b/docs/multi-engine.md @@ -73,7 +73,7 @@ Introduce multiple engines only when you need **independent lifecycle or isolati ## Combining Policies from Multiple Sources If you need to combine constraints from separate sources, do it explicitly in -host code by replaying directives through `step(...)` into a target engine. +host code: replay directives through `step(...)` into a target engine. Pattern: @@ -81,5 +81,5 @@ Pattern: 2. Replay each directive via `engine.step(...)` 3. Handle any returned `clarify` decisions explicitly -This keeps conflict handling in normal engine semantics and avoids adding merge -semantics to core state APIs. +This keeps conflict handling in normal engine behavior and avoids adding merge +rules to core state APIs. diff --git a/examples/integrations/README.md b/examples/integrations/README.md index 5d3a3fc..5bdb26f 100644 --- a/examples/integrations/README.md +++ b/examples/integrations/README.md @@ -29,7 +29,7 @@ See the LiteLLM examples README for setup and usage: - Context Compiler runs before each LLM call. - If result is `clarify`, show the question and do not call the LLM. - If result is `passthrough`, send normal user input. -- If result is `update`, use updated state and call the model with saved state added to the prompt. +- If result is `update`, use updated state and call the model with saved state in the prompt. ## LiteLLM Proxy diff --git a/examples/integrations/litellm/README.md b/examples/integrations/litellm/README.md index d4cc4ff..8c2d194 100644 --- a/examples/integrations/litellm/README.md +++ b/examples/integrations/litellm/README.md @@ -105,7 +105,7 @@ Use `llama` only for LLM-only preprocessing with Llama-family models. ## Usage pattern -These files are importable integration references for host applications. +You can import these files as integration references in host applications. - Import `handle_turn(...)` from either `basic.py` or `with_preprocessor.py`. - Create and retain an engine instance in host/session state. diff --git a/examples/integrations/litellm_proxy/README.md b/examples/integrations/litellm_proxy/README.md index ea4f65f..5e6b907 100644 --- a/examples/integrations/litellm_proxy/README.md +++ b/examples/integrations/litellm_proxy/README.md @@ -1,7 +1,7 @@ # LiteLLM Proxy (pre-call hook) This example shows how to run Context Compiler inside a LiteLLM proxy pre-call hook. -The hook applies fixed state handling before any upstream model call. +The hook applies fixed state rules before any upstream model call. Available hook files: diff --git a/examples/integrations/openwebui/README.md b/examples/integrations/openwebui/README.md index 63ee800..a5af1d9 100644 --- a/examples/integrations/openwebui/README.md +++ b/examples/integrations/openwebui/README.md @@ -1,9 +1,9 @@ # Open WebUI Pipe Integration -Examples of Open WebUI Pipe Functions that run Context Compiler. +Examples of Open WebUI Pipe Functions that use Context Compiler. Tested target: Open WebUI `v0.8.12` (latest at time of testing). -Runtime-validated on stock Docker Open WebUI with a real backend model provider. +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. @@ -49,11 +49,11 @@ If using `open_webui_pipe_with_preprocessor.py`: - Optional: set `PREPROCESSOR_MODEL_ID` to route fallback precompilation through a separate model. If unset, fallback uses `BASE_MODEL_ID`. - Fallback routing is Open WebUI-native (no LiteLLM dependency for this pipe). -- The heuristic preprocessor is intentionally conservative/high-precision and +- The heuristic preprocessor is intentionally conservative and high-precision, and may abstain on mixed-prose natural language (for example, `i think we should use docker`). In those cases, behavior may remain passthrough unless fallback precompilation returns a validated canonical directive. -- Invalid configured model ids return explicit runtime misconfiguration errors: +- If you configure invalid model ids, the pipe returns explicit runtime errors: - `BASE_MODEL_ID` not found in Open WebUI models - `PREPROCESSOR_MODEL_ID` not found in Open WebUI models @@ -80,7 +80,7 @@ Use the Open WebUI model picker/list to copy exact model ids for `BASE_MODEL_ID` - No Redis/DB/external storage. - No Filters or Pipelines. - No production hardening. -- Version-coupled to Open WebUI internal helper/import paths. +- Tied to Open WebUI internal helper/import paths by version. ## Manual Validation diff --git a/experimental/preprocessor/README.md b/experimental/preprocessor/README.md index b94b7ff..c74a963 100644 --- a/experimental/preprocessor/README.md +++ b/experimental/preprocessor/README.md @@ -1,12 +1,12 @@ # Experimental Preprocessor Package -This package provides optional app-layer preprocessing utilities for Context -Compiler integrations. +This package provides optional preprocessing helpers for app integrations with +Context Compiler. It is experimental and separate from the deterministic core engine in `src/`. -Model/tool-description translation can help with simple direct cases, but raw -model output is not safe by itself for state changes. The app must validate +Model or tool-description translation can help in simple direct cases, but raw +model output is not safe for state changes on its own. The app must validate outputs before applying them. In MCP/tool-calling environments, over-eager tool calling on conversational or @@ -65,7 +65,7 @@ Raw preprocessor/LLM outputs must not be passed directly to the compiler. Raw model output must never directly change state. The preprocessor does not expand directive grammar. It may emit only validated -canonical directives accepted by the compiler. +canonical directives that the compiler accepts. Conservative boundary policy: From 997e2136dffded2032bb5f91039d826a3c9479aa Mon Sep 17 00:00:00 2001 From: Robert Lippmann Date: Wed, 27 May 2026 02:13:37 -0400 Subject: [PATCH 4/4] docs: require issue template usage --- AGENTS.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/AGENTS.md b/AGENTS.md index d1b3d03..9ba1131 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -75,6 +75,7 @@ Prefer modern typing syntax: ## PR guidance - Never open or merge a PR targeting `main` from `main`; always use a feature branch. +- Always use the repository PR template when creating or updating PR descriptions. - PR titles must use the same format as commits: `: `. - PR descriptions should include: - what changed @@ -82,6 +83,11 @@ Prefer modern typing syntax: - Do not include a dedicated "Validation" section in PR text. - Keep PR scope aligned to the requested task; if scope grows, ask for guidance before expanding. +## Issue guidance +- Always use the repository issue templates when creating or updating issues. +- Use `bug_report` for defects and regressions. +- Use `feature_request` for new capabilities or enhancements. + ## CI Do not modify GitHub CI workflows unless explicitly asked.