From dd4897751372e648d737f46f9e9b19d86137b211 Mon Sep 17 00:00:00 2001 From: Robert Lippmann Date: Sat, 14 Mar 2026 01:10:04 -0400 Subject: [PATCH 01/10] docs: finalize README wording --- README.md | 216 +++++++++++++-------------------------------- examples/README.md | 28 ++++++ 2 files changed, 90 insertions(+), 154 deletions(-) create mode 100644 examples/README.md diff --git a/README.md b/README.md index 9d946db..32890c1 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,26 @@ # Context Compiler -Deterministic conversational state for LLM systems. +A deterministic directive engine that converts explicit user instructions +into structured conversational state for LLM applications. -Modern language models are strong at reasoning but unreliable at maintaining consistent state across interactions. Corrections compete with earlier statements, constraints disappear, and long conversations accumulate contradictions. +Modern language models reason well but are unreliable at maintaining +consistent state across interactions. + +Corrections compete with earlier statements, constraints disappear, +and long conversations accumulate contradictions. The **Context Compiler** introduces a deterministic state layer that governs authoritative conversational state independently of the model. -The model performs reasoning and generation. -The compiler manages facts and constraints. +The model performs reasoning and generation while the compiler manages facts and constraints. Once accepted, directives remain authoritative until explicitly corrected or reset. + +## Installation -Once a directive is accepted, it becomes authoritative for the remainder of the session. +- Python 3.11+ +- `pip install context-compiler` +- Dev/test: `uv sync --group dev` and `uv run pytest` +- Examples: see [examples/README.md](examples/README.md) +- Demonstrations: see [demos/README.md](demos/README.md) --- @@ -46,22 +56,6 @@ The host supplies the authoritative state to the model so the constraint persist --- -## Why Not Just Prompt Engineering? - -Prompt instructions are soft and easy to lose across long interactions. - -The Context Compiler gives the host an **authoritative state representation** that is independent of transcript drift. - -Only **explicit user directives** can modify state. - -In other words: - -- the model reasons -- the compiler decides whether state changes -- the host controls when the LLM runs - ---- - ## Architecture ```text @@ -76,30 +70,8 @@ Host Application LLM ``` -The compiler governs conversational state. It never calls the LLM. - -The LLM performs reasoning and generation but cannot modify authoritative state. - -The host application decides whether the model runs based on the compiler’s `Decision`. - -### Compiler responsibilities - -The compiler: - -1. Parses user input -2. Detects explicit directives -3. Ensures mutations are unambiguous -4. Returns a deterministic `Decision` - -The compiler **never calls the LLM**. - -### Host responsibilities - -The host: - -- displays clarification prompts -- calls the LLM when allowed -- formats prompts using compiled state +The compiler governs authoritative conversational state and never calls the LLM. +The host decides whether to call the model based on the returned `Decision`. --- @@ -122,6 +94,30 @@ Meaning: | update | forward input with updated state | | clarify | show `prompt_to_user` and do not call the LLM | +### Host Integration Example + +```python +engine = create_engine() +decision = engine.step(user_input) + +if decision["kind"] == "clarify": + show_to_user(decision["prompt_to_user"]) +else: + state = decision["state"] or engine.state + messages = build_messages(state, user_input) + render(call_llm(messages)) +``` + +### API Reference + +| API | Description | +|---|---| +| `create_engine(...)` | Create a new compiler engine, optionally with replacement initial state. | +| `step(user_input)` | Parse one user turn and return a deterministic `Decision`. | +| `engine.state` | Read or replace full in-memory authoritative state. | +| `export_json()` | Export current state as JSON for persistence/transport. | +| `import_json(payload)` | Load state from exported JSON payload. | + --- ## State Model @@ -142,57 +138,22 @@ The compiler maintains an authoritative state: ## State Access and Persistence -The compiler exposes authoritative state through in-memory replacement APIs -and JSON persistence/transport APIs. - -Supported host interaction model: - -```python -engine = create_engine() -engine = create_engine(state=initial_state_obj) -decision = engine.step(user_input) -state = engine.state -engine.state = replacement_state_obj -payload = engine.export_json() -engine.import_json(payload) -``` - -API boundaries: - -- `step()` performs directive-driven mutation. -- `engine.state` / `engine.state = ...` are in-memory inspection/replacement APIs. -- `export_json()` / `import_json()` are persistence/transport APIs. -- No imperative convenience mutation methods are provided; operations such as - `reset policies` and `clear state` are handled through directive input to `step()`. - -Example persistence lifecycle: - -```python -payload = engine.export_json() -save_to_storage(payload) - -restored_payload = load_from_storage() -engine = create_engine() -engine.import_json(restored_payload) -``` - -The compiler does not manage storage or snapshots. Persistence policies -belong to the host application. +Hosts may inspect or replace in-memory state (`engine.state`) or persist it using `export_json()` and `import_json()`. State changes occur only through directives processed by `step()`. Storage is managed by the host application. -**Note** -The fact schema currently contains a single exclusive slot: `facts["focus.primary"]`. +### Fact Schema -This slot exists to demonstrate deterministic fact replacement and correction semantics. -Richer fact schemas may be introduced in future releases. +The current schema contains a single exclusive slot: `facts["focus.primary"]`. +This demonstrates deterministic fact replacement and correction behavior. +Richer schemas may be introduced in future releases. ### State Properties -- **Facts are exclusive** (last write wins) -- **Policies are additive** -- **No inference or semantic reasoning** -- **State is deterministic** +- Facts are exclusive (last write wins) +- Policies are additive +- No inference or semantic reasoning -The same input sequence always produces the same state. +Identical input sequences always produce identical compiler state. +LLM responses may still vary unless deterministic decoding is used by the host. --- @@ -295,22 +256,9 @@ After `clear state`: ## Examples -The `examples/` directory contains small integration demonstrations. - -- [Persistent guardrails](examples/01_persistent_guardrails.py) - Demonstrates constraints persisting across turns. - -- [Configuration with correction](examples/02_configuration_and_correction.py) - Shows deterministic fact replacement. - -- [Ambiguity detection with clarification](examples/03_ambiguity_with_clarification.py) - Demonstrates clarification before state mutation. +Integration examples are available in the [examples/](examples/) directory. -- [Tool governance for agents](examples/04_tool_governance_denylist.py) - Shows how host applications can block tools using compiler policies. - -- [LLM integration pattern](examples/05_llm_integration_pattern.py) - Demonstrates the host control flow around the `Decision` API. +See [examples/README.md](examples/README.md) for walkthroughs. --- @@ -331,66 +279,26 @@ python examples/01_persistent_guardrails.py Run tests: ```bash -pytest +uv run pytest ``` --- ## Guarantees -The compiler enforces several invariants: - -- State never changes without explicit directive or confirmation -- The same input sequence always produces the same state -- LLM output never affects state -- No mutation occurs during clarification -- Administrative state replacement clears pending clarification state -- Facts are exclusive -- Policies are additive -- Pending clarification blocks mutation - ---- - -## Implementation Status - -The current implementation provides the deterministic directive compiler -defined in [this document](/docs/M1Design.md). +- State changes only through explicit user directives or confirmation. +- Identical input sequences produce identical compiler state. +- Model responses never modify compiler state. +- Ambiguous directives trigger clarification instead of changing state. --- -## Future Work - -This project intentionally focuses on the deterministic directive compiler itself. - -Higher-level systems such as session scope management, memory layers, agent tooling, -or context routing belong in host applications or separate projects built on top of -the compiler. - ---- - -## Design Philosophy - -The Context Compiler deliberately avoids: +## Design Notes -- semantic reasoning -- ontology inference -- machine-learning parsing -- transcript reconstruction -- passive memory - -Authoritative state must originate only from **explicit user directives**. - ---- - -## Specification - -The authoritative behavioral specification is: - -```text -M1Design.md -``` +More detailed design and milestone documents are available in: -Future milestone documents describe potential extensions but are not normative for current behavior. +- [Project overview](docs/DescriptionAndMilestones.md) +- [M1 design document](docs/M1Design.md) --- diff --git a/examples/README.md b/examples/README.md new file mode 100644 index 0000000..42c7934 --- /dev/null +++ b/examples/README.md @@ -0,0 +1,28 @@ +# Examples + +This directory contains small integration examples showing typical host-side usage of the Context Compiler. + +## 01_persistent_guardrails.py + +Demonstrates how a prohibition persists as authoritative state across later turns. +Shows the host using compiled state to keep constraints active. + +## 02_configuration_and_correction.py + +Demonstrates deterministic fact replacement with explicit correction. +Shows last-write-wins behavior for `facts.focus.primary`. + +## 03_ambiguity_with_clarification.py + +Demonstrates ambiguity detection before state mutation. +Shows how the host handles `Decision.kind == "clarify"` and resumes after confirmation. + +## 04_tool_governance_denylist.py + +Demonstrates tool-governance policy handling via prohibition directives. +Shows how hosts can prevent denied tools from being selected. + +## 05_llm_integration_pattern.py + +Demonstrates the end-to-end host control flow around `Decision`. +Shows when to clarify, when to call the model, and how to include compiled state in prompts. From 40a7987c880f4e9e5ee03fd4b8705245faecdc4e Mon Sep 17 00:00:00 2001 From: Robert Lippmann Date: Sat, 14 Mar 2026 01:15:50 -0400 Subject: [PATCH 02/10] docs: add documentation index --- docs/README.md | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 docs/README.md diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..dcb6c6b --- /dev/null +++ b/docs/README.md @@ -0,0 +1,6 @@ +# Documentation + +This directory contains the project design and milestone specifications. + +- `DescriptionAndMilestones.md` — project overview and milestone roadmap +- `M1Design.md` — authoritative behavioral specification for the deterministic directive engine From 6cea3119990e5e117063470fdf0b6f9718693d06 Mon Sep 17 00:00:00 2001 From: Robert Lippmann Date: Sat, 14 Mar 2026 01:21:07 -0400 Subject: [PATCH 03/10] docs: add contributing guide --- CONTRIBUTING.md | 36 ++++++++++++++++++++++++++++++++++++ 1 file changed, 36 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 0000000..190533d --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,36 @@ +# Contributing + +Thanks for your interest in improving this project. Contributions are welcome. + +## Workflow + +Contributions are typically submitted via fork and pull request: + +- fork the repository +- create a feature branch +- run tests and pre-commit checks +- open a pull request + +## Development Setup + +```bash +uv sync --group dev +``` + +## Running Tests + +```bash +uv run pytest +``` + +## Code Quality + +```bash +pre-commit run --all-files +``` + +## Scope of Changes + +- keep pull requests focused +- include tests if behavior changes +- open an issue first for large design changes From 54e86f3a57023900f3d90bb4499efd96c33a7d55 Mon Sep 17 00:00:00 2001 From: Robert Lippmann Date: Sat, 14 Mar 2026 01:26:22 -0400 Subject: [PATCH 04/10] docs: add testing note to guarantees --- README.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/README.md b/README.md index 32890c1..dd07c40 100644 --- a/README.md +++ b/README.md @@ -291,6 +291,8 @@ uv run pytest - Model responses never modify compiler state. - Ambiguous directives trigger clarification instead of changing state. +These invariants are verified through behavioral tests and Hypothesis-based property tests. + --- ## Design Notes From 122983e770a1d4ffe46bf346365a93f65065d237 Mon Sep 17 00:00:00 2001 From: Robert Lippmann Date: Sat, 14 Mar 2026 01:33:09 -0400 Subject: [PATCH 05/10] docs: add pypi badges --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index dd07c40..a044c09 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,10 @@ # Context Compiler +[![PyPI version](https://img.shields.io/pypi/v/context-compiler)](https://pypi.org/project/context-compiler/) +[![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/) + A deterministic directive engine that converts explicit user instructions into structured conversational state for LLM applications. From d5bfe41957bca0dd6ad714d64d6f1e5712cdc37e Mon Sep 17 00:00:00 2001 From: Robert Lippmann Date: Sat, 14 Mar 2026 01:38:39 -0400 Subject: [PATCH 06/10] feat: expose package __version__ --- src/context_compiler/__init__.py | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/src/context_compiler/__init__.py b/src/context_compiler/__init__.py index d4268bf..0946943 100644 --- a/src/context_compiler/__init__.py +++ b/src/context_compiler/__init__.py @@ -1,3 +1,7 @@ +from importlib.metadata import version + from .engine import Decision, Engine, State, create_engine +__version__ = version("context-compiler") + __all__ = ["Decision", "Engine", "State", "create_engine"] From 86cf4acddf6a97a3075b7889b580424c61238e15 Mon Sep 17 00:00:00 2001 From: Robert Lippmann Date: Sat, 14 Mar 2026 01:42:13 -0400 Subject: [PATCH 07/10] docs: add project URLs to pyproject --- pyproject.toml | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/pyproject.toml b/pyproject.toml index d20ae2c..4d3badd 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -12,6 +12,11 @@ license = { text = "Apache-2.0" } authors = [{ name = "Robert Lippmann" }] dependencies = [] +[project.urls] +Homepage = "https://github.com/rlippmann/context-compiler" +Repository = "https://github.com/rlippmann/context-compiler" +Issues = "https://github.com/rlippmann/context-compiler/issues" + [project.scripts] context-compiler = "context_compiler.repl:main" From bacf54e3eb00b407a5b2cb6e112512c233c261e3 Mon Sep 17 00:00:00 2001 From: Robert Lippmann Date: Sat, 14 Mar 2026 01:47:08 -0400 Subject: [PATCH 08/10] Add project metadata keywords and a --- pyproject.toml | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/pyproject.toml b/pyproject.toml index 4d3badd..87b541e 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -11,6 +11,20 @@ requires-python = ">=3.11" license = { text = "Apache-2.0" } authors = [{ name = "Robert Lippmann" }] dependencies = [] +keywords = [ + "llm", + "conversation-state", + "state-machine", + "ai-infrastructure", +] +classifiers = [ + "Development Status :: 4 - Beta", + "Intended Audience :: Developers", + "License :: OSI Approved :: Apache Software License", + "Programming Language :: Python :: 3", + "Topic :: Software Development :: Libraries", + "Topic :: Scientific/Engineering :: Artificial Intelligence", +] [project.urls] Homepage = "https://github.com/rlippmann/context-compiler" From e34a5acad55502189116eba26842f542eb6b0e82 Mon Sep 17 00:00:00 2001 From: Robert Lippmann Date: Sat, 14 Mar 2026 01:53:32 -0400 Subject: [PATCH 09/10] Bump version to 0.2.0 --- pyproject.toml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pyproject.toml b/pyproject.toml index 87b541e..333cb2b 100644 --- a/pyproject.toml +++ b/pyproject.toml @@ -4,7 +4,7 @@ build-backend = "hatchling.build" [project] name = "context-compiler" -version = "0.1.0" +version = "0.2.0" description = "Deterministic conversational state engine for LLM applications." readme = "README.md" requires-python = ">=3.11" From fbb1ccbf68e759c0f3d1b94f79078432f6f66cce Mon Sep 17 00:00:00 2001 From: Robert Lippmann Date: Sat, 14 Mar 2026 01:57:33 -0400 Subject: [PATCH 10/10] Update lockfile for 0.2.0 version bump --- uv.lock | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/uv.lock b/uv.lock index 51ca4e7..c0d361f 100644 --- a/uv.lock +++ b/uv.lock @@ -53,7 +53,7 @@ wheels = [ [[package]] name = "context-compiler" -version = "0.1.0" +version = "0.2.0" source = { editable = "." } [package.optional-dependencies]