context-compiler 0.9.0.dev15__tar.gz → 0.9.2__tar.gz

context_compiler-0.9.2/PKG-INFO

@@ -0,0 +1,218 @@
+Metadata-Version: 2.5
+Name: context-compiler
+Version: 0.9.2
+Summary: Deterministic conversational state engine for LLM applications.
+Project-URL: Homepage, https://github.com/rlippmann/context-compiler
+Project-URL: Repository, https://github.com/rlippmann/context-compiler
+Project-URL: Issues, https://github.com/rlippmann/context-compiler/issues
+Author: Robert Lippmann
+License: Apache-2.0
+License-File: LICENSE
+Keywords: ai-infrastructure,conversation-state,conversational-ai,deterministic,llm,state-machine,state-management
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.11
+Provides-Extra: demos
+Requires-Dist: litellm>=1.0.0; extra == 'demos'
+Description-Content-Type: text/markdown
+
+# 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/)
+[![codecov](https://codecov.io/gh/rlippmann/context-compiler/branch/main/graph/badge.svg)](https://codecov.io/gh/rlippmann/context-compiler)
+
+Context Compiler maintains host-side working memory consisting of a premise and
+policies, separate from the model's conversational context. The Engine applies
+directives to that working memory so applications can maintain explicit state
+across model interactions without relying on the model to remember or infer it.
+It blocks invalid or conflicting changes and returns structured decisions.
+
+Use it when saved context and policy rules need to shape what an application
+does, not just what the model sees or says.
+
+The [`context-compiler-example-integrations`](https://github.com/rlippmann/context-compiler-example-integrations)
+show this approach working in applications, and the [demo results](https://github.com/rlippmann/context-compiler/blob/main/docs/demos-results.md)
+show consistent behavior across models and prompt conditions.
+
+## Quickstart
+
+This example shows premise and policy updates directly:
+
+```python
+from context_compiler import Engine, SemanticErrorDecision, UpdateDecision
+
+engine = Engine()
+
+engine.step("set premise project deadline is Friday")
+print(engine.premise)
+# project deadline is Friday
+
+engine.step("change premise to project deadline is Thursday")
+print(engine.premise)
+# project deadline is Thursday
+
+engine.step("use docker")
+
+result = engine.step("use podman instead of docker")
+if isinstance(result, UpdateDecision):
+    print(result.changed)
+# True
+
+result = engine.step("use podman")
+if isinstance(result, UpdateDecision):
+    print(result.changed)
+# False
+
+result = engine.step("use npm instead of yarn")
+if isinstance(result, SemanticErrorDecision):
+    print(result.message)
+
+# "yarn" is not currently in use.
+# Replacement requires an active 'use' policy.
+```
+
+## Installation
+
+Requirements:
+
+- Python 3.11+
+
+Install:
+
+```bash
+pip install context-compiler
+```
+
+Packaging notes:
+
+- Base install includes the Context Compiler engine and CLI.
+- Example and demo source files are available in the repository and source distribution.
+- To run the demos from this repository, clone the repo and install `context-compiler[demos]`.
+- The `[demos]` extra installs optional dependencies such as LiteLLM. It does not install demo source files into site-packages.
+
+## API and behavior
+
+The main public API is `Engine` and its Decision results.
+
+- `Engine.step(...)` accepts raw input and may return `no_directive`, `update`,
+  or `error`.
+- `Engine.apply_directive(...)` accepts a supported directive and returns an
+  `update` or `error`.
+- `engine.premise` and `engine.policies` expose live compiler state.
+- `engine.export_json()` and `engine.import_json(...)` transport compiler state
+  only.
+See the [API reference](https://github.com/rlippmann/context-compiler/blob/main/docs/api-reference.md) for fields, signatures, and
+repair behavior.
+
+---
+
+## State Model
+
+Working memory contains explicit user commitments:
+
+| State | Meaning |
+| --- | --- |
+| `premise` | One factual or contextual value that changes how future answers should be interpreted |
+| `use` | An affirmative per-item policy |
+| `prohibit` | An excluding per-item policy |
+
+### Directive commands
+
+Set or change the premise with:
+
+```text
+set premise project deadline is Friday
+change premise to project deadline is Thursday
+```
+
+Policy commands:
+
+```text
+use docker
+prohibit peanuts
+```
+
+To replace an existing `use` policy:
+
+```text
+use podman instead of docker
+```
+
+If `docker` is absent from working memory, the replacement fails and leaves
+working memory unchanged. It does not become plain `use podman`.
+
+To remove a policy or clear state:
+
+```text
+remove policy peanuts
+reset policies
+clear state
+```
+
+---
+
+### When to use `premise`
+
+Use `premise` for **persistent background context or factual state that changes how answers should be interpreted**, especially when it:
+
+- applies across many turns
+- significantly changes what solutions are valid
+- cannot be fully captured as simple `use` / `prohibit` policies
+
+Examples:
+
+- `set premise current medications: …`
+- `set premise outdoor event; no seating available`
+- `set premise GDPR data handling requirements apply`
+- `set premise system is deployed across multiple regions`
+- `set premise project deadline is Friday`
+
+The premise stays in effect until it is changed or cleared.
+
+Use policies instead when the constraint is explicit and enforceable.
+
+```text
+use concise replies
+use a formal tone
+prohibit introducing new external dependencies
+```
+
+## Examples and demos
+
+- [examples](https://github.com/rlippmann/context-compiler/tree/main/examples) — minimal usage patterns for the Context Compiler engine
+- [demos](https://github.com/rlippmann/context-compiler/tree/main/demos) — concrete scenarios showing how behavior differs with and without the compiler
+- [`context-compiler-example-integrations`](https://github.com/rlippmann/context-compiler-example-integrations) — runnable integrations using compiler state
+- [demo results](https://github.com/rlippmann/context-compiler/blob/main/docs/demos-results.md) — evidence that the compiler works in practice
+
+---
+
+## CLI and REPL
+
+The package includes an interactive REPL and a machine-readable JSON CLI. See
+the [CLI and REPL guide](https://github.com/rlippmann/context-compiler/blob/main/docs/cli-repl.md) for commands, preload options, and
+JSON output behavior.
+
+---
+
+## Documentation
+
+- [Design philosophy](https://github.com/rlippmann/context-compiler/blob/main/docs/DesignPhilosophy.md)
+- [Architecture boundaries](https://github.com/rlippmann/context-compiler/blob/main/docs/architecture.md)
+- [Project overview](https://github.com/rlippmann/context-compiler/blob/main/docs/DescriptionAndMilestones.md)
+- [Directive grammar specification](https://github.com/rlippmann/context-compiler/blob/main/docs/DirectiveGrammarSpec.md)
+- [Multiple engines](https://github.com/rlippmann/context-compiler/blob/main/docs/multi-engine.md)
+- [`tests/fixtures/`](https://github.com/rlippmann/context-compiler/tree/main/tests/fixtures) — Cross-language fixtures that help keep compiler behavior consistent across implementations.
+
+For the full map, see [docs/README.md](https://github.com/rlippmann/context-compiler/blob/main/docs/README.md).
+
+---
+
+## License
+
+Apache-2.0.

context_compiler-0.9.2/README.md

@@ -0,0 +1,196 @@
+# 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/)
+[![codecov](https://codecov.io/gh/rlippmann/context-compiler/branch/main/graph/badge.svg)](https://codecov.io/gh/rlippmann/context-compiler)
+
+Context Compiler maintains host-side working memory consisting of a premise and
+policies, separate from the model's conversational context. The Engine applies
+directives to that working memory so applications can maintain explicit state
+across model interactions without relying on the model to remember or infer it.
+It blocks invalid or conflicting changes and returns structured decisions.
+
+Use it when saved context and policy rules need to shape what an application
+does, not just what the model sees or says.
+
+The [`context-compiler-example-integrations`](https://github.com/rlippmann/context-compiler-example-integrations)
+show this approach working in applications, and the [demo results](https://github.com/rlippmann/context-compiler/blob/main/docs/demos-results.md)
+show consistent behavior across models and prompt conditions.
+
+## Quickstart
+
+This example shows premise and policy updates directly:
+
+```python
+from context_compiler import Engine, SemanticErrorDecision, UpdateDecision
+
+engine = Engine()
+
+engine.step("set premise project deadline is Friday")
+print(engine.premise)
+# project deadline is Friday
+
+engine.step("change premise to project deadline is Thursday")
+print(engine.premise)
+# project deadline is Thursday
+
+engine.step("use docker")
+
+result = engine.step("use podman instead of docker")
+if isinstance(result, UpdateDecision):
+    print(result.changed)
+# True
+
+result = engine.step("use podman")
+if isinstance(result, UpdateDecision):
+    print(result.changed)
+# False
+
+result = engine.step("use npm instead of yarn")
+if isinstance(result, SemanticErrorDecision):
+    print(result.message)
+
+# "yarn" is not currently in use.
+# Replacement requires an active 'use' policy.
+```
+
+## Installation
+
+Requirements:
+
+- Python 3.11+
+
+Install:
+
+```bash
+pip install context-compiler
+```
+
+Packaging notes:
+
+- Base install includes the Context Compiler engine and CLI.
+- Example and demo source files are available in the repository and source distribution.
+- To run the demos from this repository, clone the repo and install `context-compiler[demos]`.
+- The `[demos]` extra installs optional dependencies such as LiteLLM. It does not install demo source files into site-packages.
+
+## API and behavior
+
+The main public API is `Engine` and its Decision results.
+
+- `Engine.step(...)` accepts raw input and may return `no_directive`, `update`,
+  or `error`.
+- `Engine.apply_directive(...)` accepts a supported directive and returns an
+  `update` or `error`.
+- `engine.premise` and `engine.policies` expose live compiler state.
+- `engine.export_json()` and `engine.import_json(...)` transport compiler state
+  only.
+See the [API reference](https://github.com/rlippmann/context-compiler/blob/main/docs/api-reference.md) for fields, signatures, and
+repair behavior.
+
+---
+
+## State Model
+
+Working memory contains explicit user commitments:
+
+| State | Meaning |
+| --- | --- |
+| `premise` | One factual or contextual value that changes how future answers should be interpreted |
+| `use` | An affirmative per-item policy |
+| `prohibit` | An excluding per-item policy |
+
+### Directive commands
+
+Set or change the premise with:
+
+```text
+set premise project deadline is Friday
+change premise to project deadline is Thursday
+```
+
+Policy commands:
+
+```text
+use docker
+prohibit peanuts
+```
+
+To replace an existing `use` policy:
+
+```text
+use podman instead of docker
+```
+
+If `docker` is absent from working memory, the replacement fails and leaves
+working memory unchanged. It does not become plain `use podman`.
+
+To remove a policy or clear state:
+
+```text
+remove policy peanuts
+reset policies
+clear state
+```
+
+---
+
+### When to use `premise`
+
+Use `premise` for **persistent background context or factual state that changes how answers should be interpreted**, especially when it:
+
+- applies across many turns
+- significantly changes what solutions are valid
+- cannot be fully captured as simple `use` / `prohibit` policies
+
+Examples:
+
+- `set premise current medications: …`
+- `set premise outdoor event; no seating available`
+- `set premise GDPR data handling requirements apply`
+- `set premise system is deployed across multiple regions`
+- `set premise project deadline is Friday`
+
+The premise stays in effect until it is changed or cleared.
+
+Use policies instead when the constraint is explicit and enforceable.
+
+```text
+use concise replies
+use a formal tone
+prohibit introducing new external dependencies
+```
+
+## Examples and demos
+
+- [examples](https://github.com/rlippmann/context-compiler/tree/main/examples) — minimal usage patterns for the Context Compiler engine
+- [demos](https://github.com/rlippmann/context-compiler/tree/main/demos) — concrete scenarios showing how behavior differs with and without the compiler
+- [`context-compiler-example-integrations`](https://github.com/rlippmann/context-compiler-example-integrations) — runnable integrations using compiler state
+- [demo results](https://github.com/rlippmann/context-compiler/blob/main/docs/demos-results.md) — evidence that the compiler works in practice
+
+---
+
+## CLI and REPL
+
+The package includes an interactive REPL and a machine-readable JSON CLI. See
+the [CLI and REPL guide](https://github.com/rlippmann/context-compiler/blob/main/docs/cli-repl.md) for commands, preload options, and
+JSON output behavior.
+
+---
+
+## Documentation
+
+- [Design philosophy](https://github.com/rlippmann/context-compiler/blob/main/docs/DesignPhilosophy.md)
+- [Architecture boundaries](https://github.com/rlippmann/context-compiler/blob/main/docs/architecture.md)
+- [Project overview](https://github.com/rlippmann/context-compiler/blob/main/docs/DescriptionAndMilestones.md)
+- [Directive grammar specification](https://github.com/rlippmann/context-compiler/blob/main/docs/DirectiveGrammarSpec.md)
+- [Multiple engines](https://github.com/rlippmann/context-compiler/blob/main/docs/multi-engine.md)
+- [`tests/fixtures/`](https://github.com/rlippmann/context-compiler/tree/main/tests/fixtures) — Cross-language fixtures that help keep compiler behavior consistent across implementations.
+
+For the full map, see [docs/README.md](https://github.com/rlippmann/context-compiler/blob/main/docs/README.md).
+
+---
+
+## License
+
+Apache-2.0.

{context_compiler-0.9.0.dev15 → context_compiler-0.9.2}/demos/03_llm_premise_guardrail.py

@@ -1,4 +1,4 @@
-"""Demo 3: explicit premise change removes stale values deterministically."""
+"""Demo 3: explicit contextual-premise change removes stale values deterministically."""
 
 import re
 
@@ -61,8 +61,6 @@ def _plan_uses_value(output: str, value: str) -> bool:
         lowered = line.lower()
         if token not in lowered:
             continue
-        if token == "vegetarian" and "vegan" in lowered:
-            continue
         if _NEGATION_RE.search(lowered):
             continue
         return True
@@ -72,9 +70,9 @@ def _plan_uses_value(output: str, value: str) -> bool:
 def main() -> None:
     engine = Engine()
     user_inputs = [
-        "set premise vegetarian curry",
-        "change premise to vegan curry",
-        ("Give me a shopping list and 3-step plan. First line must be PREMISE:<value>."),
+        "set premise project deadline is Friday",
+        "change premise to project deadline is Thursday",
+        ("Give me a project plan and 3 steps. First line must be PREMISE:<value>."),
     ]
     print_user_inputs(user_inputs)
 
@@ -91,7 +89,7 @@ def main() -> None:
     baseline_messages = build_baseline_messages(
         [user_inputs[0], user_inputs[1], user_inputs[2]],
         baseline_system_prompt=(
-            "Be a helpful assistant. Use conversation history to infer the user's current premise."
+            "Be a helpful assistant. Use conversation history to infer the current project context."
         ),
     )
     print_messages("baseline", baseline_messages)
@@ -100,7 +98,7 @@ def main() -> None:
 
     _, reinjected_messages = build_reinjected_messages(
         [user_inputs[0], user_inputs[1], user_inputs[2]],
-        premise="vegan curry",
+        premise="project deadline is Thursday",
         use_policies=[],
         prohibit_policies=[],
     )
@@ -140,23 +138,23 @@ def main() -> None:
     reinjected_premise = extract_tag_value(reinjected_output, "PREMISE")
     mediated_premise = extract_tag_value(mediated_output, "PREMISE")
     compact_premise = extract_tag_value(compact_output, "PREMISE")
-    baseline_uses_vegan = _plan_uses_value(baseline_output, "vegan")
-    baseline_uses_vegetarian = _plan_uses_value(baseline_output, "vegetarian")
-    reinjected_uses_vegan = _plan_uses_value(reinjected_output, "vegan")
-    reinjected_uses_vegetarian = _plan_uses_value(reinjected_output, "vegetarian")
-    mediated_uses_vegan = _plan_uses_value(mediated_output, "vegan")
-    mediated_uses_vegetarian = _plan_uses_value(mediated_output, "vegetarian")
-    compact_uses_vegan = _plan_uses_value(compact_output, "vegan")
-    compact_uses_vegetarian = _plan_uses_value(compact_output, "vegetarian")
-    baseline_respects = not baseline_uses_vegetarian
-    reinjected_respects = not reinjected_uses_vegetarian
-    mediated_respects = not mediated_uses_vegetarian
-    compact_respects = compacted_prompt is None and not compact_uses_vegetarian
+    baseline_uses_friday = _plan_uses_value(baseline_output, "Friday")
+    baseline_uses_thursday = _plan_uses_value(baseline_output, "Thursday")
+    reinjected_uses_friday = _plan_uses_value(reinjected_output, "Friday")
+    reinjected_uses_thursday = _plan_uses_value(reinjected_output, "Thursday")
+    mediated_uses_friday = _plan_uses_value(mediated_output, "Friday")
+    mediated_uses_thursday = _plan_uses_value(mediated_output, "Thursday")
+    compact_uses_friday = _plan_uses_value(compact_output, "Friday")
+    compact_uses_thursday = _plan_uses_value(compact_output, "Thursday")
+    baseline_respects = not baseline_uses_friday
+    reinjected_respects = not reinjected_uses_friday
+    mediated_respects = not mediated_uses_friday
+    compact_respects = compacted_prompt is None and not compact_uses_friday
     print_host_check(
         "PLAN_VALUES",
         (
-            f"vegan={yes_no(baseline_uses_vegan)}, "
-            f"vegetarian={yes_no(baseline_uses_vegetarian)}, "
+            f"Friday={yes_no(baseline_uses_friday)}, "
+            f"Thursday={yes_no(baseline_uses_thursday)}, "
             f"premise_tag={baseline_premise or 'MISSING'}"
         ),
         context="baseline",
@@ -164,8 +162,8 @@ def main() -> None:
     print_host_check(
         "PLAN_VALUES",
         (
-            f"vegan={yes_no(reinjected_uses_vegan)}, "
-            f"vegetarian={yes_no(reinjected_uses_vegetarian)}, "
+            f"Friday={yes_no(reinjected_uses_friday)}, "
+            f"Thursday={yes_no(reinjected_uses_thursday)}, "
             f"premise_tag={reinjected_premise or 'MISSING'}"
         ),
         context="reinjected-state",
@@ -173,8 +171,8 @@ def main() -> None:
     print_host_check(
         "PLAN_VALUES",
         (
-            f"vegan={yes_no(mediated_uses_vegan)}, "
-            f"vegetarian={yes_no(mediated_uses_vegetarian)}, "
+            f"Friday={yes_no(mediated_uses_friday)}, "
+            f"Thursday={yes_no(mediated_uses_thursday)}, "
             f"premise_tag={mediated_premise or 'MISSING'}"
         ),
         context="compiler-mediated",
@@ -182,32 +180,32 @@ def main() -> None:
     print_host_check(
         "PLAN_VALUES",
         (
-            f"vegan={yes_no(compact_uses_vegan)}, "
-            f"vegetarian={yes_no(compact_uses_vegetarian)}, "
+            f"Friday={yes_no(compact_uses_friday)}, "
+            f"Thursday={yes_no(compact_uses_thursday)}, "
             f"premise_tag={compact_premise or 'MISSING'}"
         ),
         context="compiler-mediated + compact",
     )
     print_spec_report(
-        test_name="03_explicit_premise_change — stale value removed",
+        test_name="03_explicit_premise_change — stale context removed",
         baseline_pass=baseline_respects,
         reinjected_state_pass=reinjected_respects,
         compiler_pass=mediated_respects,
         compiler_compact_pass=compact_respects,
-        expected="explicit premise change should remove the stale vegetarian value",
+        expected="explicit premise change should remove the stale Friday context",
         actual=(
-            "baseline still used stale vegetarian value; "
-            "both compiler-mediated paths used vegan value"
-            if mediated_respects and compact_respects and baseline_uses_vegetarian
+            "baseline still used stale Friday context; "
+            "both compiler-mediated paths used Thursday context"
+            if mediated_respects and compact_respects and baseline_uses_friday
             else (
-                "all four paths used vegan value"
+                "all four paths used Thursday context"
                 if baseline_respects and mediated_respects and compact_respects
                 else (
-                    "at least one compiler-mediated path included stale vegetarian value"
+                    "at least one compiler-mediated path included stale Friday context"
                     if (not mediated_respects or not compact_respects)
                     else (
-                        "baseline already used vegan value; a compiler-mediated path "
-                        "still included stale vegetarian content"
+                        "baseline already used Thursday context; a compiler-mediated path "
+                        "still included stale Friday context"
                     )
                 )
             )