Add deterministic examples and canonical JSON output

README.md

@@ -1,2 +1,9 @@
 # context-compiler
 Deterministic state engine for managing authoritative conversational constraints in LLM applications.
+
+## Examples
+- [Persistent guardrails](examples/01_persistent_guardrails.py)
+- [Configuration with correction](examples/02_configuration_and_correction.py)
+- [Ambiguity detection with clarification](examples/03_ambiguity_with_clarification.py)
+- [Tool governance for agents](examples/04_tool_governance_denylist.py)
+- [LLM integration pattern](examples/05_llm_integration_pattern.py)

examples/01_persistent_guardrails.py

@@ -0,0 +1,44 @@
+"""Example 1: persistent guardrails across turns."""
+
+from _util import print_json
+
+from context_compiler import State, create_engine
+
+
+def build_prompt(state: State, user_input: str) -> str:
+    prohibit = state["policies"]["prohibit"]
+    prohibit_text = ", ".join(prohibit) if prohibit else "(none)"
+    return (
+        "System: Follow authoritative conversation state.\n"
+        "Compiled context:\n"
+        f"- policies.prohibit: {prohibit_text}\n"
+        f"User: {user_input}"
+    )
+
+
+def main() -> None:
+    engine = create_engine()
+
+    print("User: don't use docker")
+    decision1 = engine.step("don't use docker")
+    print("Decision:")
+    print_json(decision1)
+    print("State after turn 1:")
+    print_json(engine.state)
+    print()
+
+    print("User: how should I deploy my service?")
+    decision2 = engine.step("how should I deploy my service?")
+    print("Decision:")
+    print_json(decision2)
+    print("State after turn 2:")
+    print_json(engine.state)
+    print()
+
+    print("Host prompt construction with persisted policy:")
+    prompt = build_prompt(engine.state, "how should I deploy my service?")
+    print(prompt)
+
+
+if __name__ == "__main__":
+    main()

examples/02_configuration_and_correction.py

@@ -0,0 +1,28 @@
+"""Example 2: conversational configuration with correction (last-write-wins)."""
+
+from _util import print_json
+
+from context_compiler import create_engine
+
+
+def main() -> None:
+    engine = create_engine()
+
+    print("User: I'm using MacBook M3")
+    decision1 = engine.step("I'm using MacBook M3")
+    print("Decision:")
+    print_json(decision1)
+    print("State:")
+    print_json(engine.state)
+    print()
+
+    print("User: actually MacBook M2")
+    decision2 = engine.step("actually MacBook M2")
+    print("Decision:")
+    print_json(decision2)
+    print("State (last write wins):")
+    print_json(engine.state)
+
+
+if __name__ == "__main__":
+    main()

examples/03_ambiguity_with_clarification.py

@@ -0,0 +1,38 @@
+"""Example 3: ambiguous directive flow with clarification handling."""
+
+from _util import print_json
+
+from context_compiler import create_engine
+
+
+def fake_llm(user_input: str) -> str:
+    print(f"LLM would be called with user_input={user_input!r}")
+    return "[example LLM response]"
+
+
+def main() -> None:
+    engine = create_engine()
+
+    print("User: no use docker")
+    decision1 = engine.step("no use docker")
+    print("Decision:")
+    print_json(decision1)
+    print()
+
+    if decision1["kind"] == "clarify":
+        print("Host behavior: clarification pending, do NOT call LLM.")
+        print(f"Prompt to user: {decision1['prompt_to_user']}")
+    else:
+        fake_llm("no use docker")
+    print()
+
+    print("User: yes")
+    decision2 = engine.step("yes")
+    print("Decision:")
+    print_json(decision2)
+    print("State after clarification acceptance:")
+    print_json(engine.state)
+
+
+if __name__ == "__main__":
+    main()

examples/04_tool_governance_denylist.py

@@ -0,0 +1,46 @@
+"""Example 4: host-side tool governance using policies.prohibit denylist."""
+
+from dataclasses import dataclass
+
+from _util import print_json
+
+from context_compiler import create_engine
+
+
+@dataclass
+class Tool:
+    name: str
+
+
+def block_tool(tool: Tool) -> None:
+    print(f"Blocked tool: {tool.name}")
+
+
+def allow_tool(tool: Tool) -> None:
+    print(f"Allowed tool: {tool.name}")
+
+
+def main() -> None:
+    engine = create_engine()
+
+    user_input = "don't use docker"
+    print(f"User: {user_input}")
+    decision = engine.step(user_input)
+    print("Decision:")
+    print_json(decision)
+    print("State after turn:")
+    state = engine.state
+    print_json(state)
+    print()
+
+    print("Host-side tool denylist behavior:")
+    tools = [Tool("docker"), Tool("kubectl")]
+    for tool in tools:
+        if tool.name in state["policies"]["prohibit"]:
+            block_tool(tool)
+        else:
+            allow_tool(tool)
+
+
+if __name__ == "__main__":
+    main()

examples/05_llm_integration_pattern.py

@@ -0,0 +1,43 @@
+"""Example 5: host integration pattern using Decision API."""
+
+from _util import canonical_json, print_json
+
+from context_compiler import Engine, State, create_engine
+
+
+def fake_llm(state: State | None, user_input: str) -> str:
+    print("LLM would be called with:")
+    print(f"state: {canonical_json(state)}")
+    print("user_input:", user_input)
+    return "[example LLM response]"
+
+
+def handle_turn(engine_input: str, engine: Engine) -> None:
+    decision = engine.step(engine_input)
+    print(f"User: {engine_input}")
+    print("Decision:")
+    print_json(decision)
+
+    if decision["kind"] == "passthrough":
+        print("Host action: passthrough -> call fake_llm() without state")
+        fake_llm(None, engine_input)
+    elif decision["kind"] == "update":
+        print("Host action: update -> call fake_llm() with compiled state")
+        fake_llm(decision["state"], engine_input)
+    elif decision["kind"] == "clarify":
+        print("Host action: clarify -> show prompt, DO NOT call LLM")
+        print("prompt_to_user:", decision["prompt_to_user"])
+    print()
+
+
+def main() -> None:
+    engine = create_engine()
+
+    handle_turn("hello there", engine)
+    handle_turn("don't use docker", engine)
+    handle_turn("no use kubernetes", engine)
+    handle_turn("yes", engine)
+
+
+if __name__ == "__main__":
+    main()

examples/_util.py

@@ -0,0 +1,10 @@
+import json
+from typing import Any
+
+
+def canonical_json(obj: Any) -> str:
+    return json.dumps(obj, sort_keys=True, separators=(",", ":"))
+
+
+def print_json(obj: Any) -> None:
+    print(canonical_json(obj))