context-compiler 0.1.0

Deterministic conversational state engine for LLM applications.

Context Compiler

Deterministic conversational state for LLM systems.

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.

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.

Once a directive is accepted, it becomes authoritative for the remainder of the session.

---

10-Second Example

User sets a constraint once:

User: don't use docker

State becomes:

{
  "facts": {
    "focus.device": null
  },
  "policies": {
    "prohibit": ["docker"]
  },
  "version": 1
}

Later in the conversation:

User: how should I deploy my service?

The host supplies the compiled state to the model so the constraint persists across turns.

---

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 snapshot 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

User Input
   ↓
Context Compiler
   ↓
Decision (passthrough | update | clarify)
   ↓
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

---

Decision API

Each user message produces a Decision.

class Decision(TypedDict):
    kind: Literal["passthrough", "update", "clarify"]
    state: dict | None
    prompt_to_user: str | None

Meaning:

kind	host behavior
passthrough	forward user input to LLM
update	forward input with updated state
clarify	show prompt_to_user and do not call the LLM

---

State Model

The compiler maintains an authoritative state snapshot:

{
  "facts": {
    "focus.device": null
  },
  "policies": {
    "prohibit": []
  },
  "version": 1
}

Note In M1, the fact schema contains a single exclusive slot: facts["focus.device"].

This slot exists to demonstrate deterministic fact replacement and correction semantics. Richer fact schemas may be introduced in future milestones.

State Properties

• Facts are exclusive (last write wins)
• Policies are additive
• No inference or semantic reasoning
• State is deterministic

The same input sequence always produces the same state.

---

Directive Examples

Hard negative directive:

User: don't use docker

Result:

{
  "policies": {
    "prohibit": ["docker"]
  }
}

Fact configuration:

User: I'm using MacBook M3

State update:

facts.focus.device = "MacBook M3"

Correction:

User: actually MacBook M2

Result:

facts.focus.device = "MacBook M2"

Ambiguous mutation:

User: no use docker

Compiler response:

Decision.kind = "clarify"

No state mutation occurs until confirmation.

---

Examples

The examples/ directory contains small integration demonstrations.

• Persistent guardrails
  Demonstrates constraints persisting across turns.

• Configuration with correction
  Shows deterministic fact replacement.

• Ambiguity detection with clarification
  Demonstrates clarification before state mutation.

• Tool governance for agents
  Shows how host applications can block tools using compiler policies.

• LLM integration pattern
  Demonstrates the host control flow around the Decision API.

---

Quickstart

Run the interactive REPL:

context-compiler

Run an example:

python examples/01_persistent_guardrails.py

Run tests:

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
• Facts are exclusive
• Policies are additive
• Pending clarification blocks mutation

---

Current Milestone

The current implementation corresponds to:

M1 — Deterministic State Engine

Goal:

Ensure explicit user corrections and constraints persist reliably within a single conversation.

---

Future Milestones

Only M1 is currently implemented.

Possible future work:

M2 — Scope & Session Control (optional)

Introduce isolation boundaries so state applies only within the intended conversational context.

M3 — Cross-Session Recall

Allow explicit recall of prior authoritative state across sessions.

M4 — MCP Integration (optional)

Expose the state engine through a standardized context interface.

M5 — Branch Awareness (optional / experimental)

Provide tools for managing multiple conversation branches during exploratory discussions.

---

Design Philosophy

The Context Compiler deliberately avoids:

• 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:

M1Design.md

Future milestone documents describe potential extensions but are not normative for current behavior.

---

License

Apache-2.0.