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
show this approach working in applications, and the demo results
show consistent behavior across models and prompt conditions.
Quickstart
This example shows premise and policy updates directly:
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:
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 returnno_directive,update, orerror.Engine.apply_directive(...)accepts a supported directive and returns anupdateorerror.engine.premiseandengine.policiesexpose live compiler state.engine.export_json()andengine.import_json(...)transport compiler state only. See the API reference 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:
set premise project deadline is Friday
change premise to project deadline is Thursday
Policy commands:
use docker
prohibit peanuts
To replace an existing use policy:
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:
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/prohibitpolicies
Examples:
set premise current medications: …set premise outdoor event; no seating availableset premise GDPR data handling requirements applyset premise system is deployed across multiple regionsset 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.
use concise replies
use a formal tone
prohibit introducing new external dependencies
Examples and demos
- examples — minimal usage patterns for the Context Compiler engine
- demos — concrete scenarios showing how behavior differs with and without the compiler
context-compiler-example-integrations— runnable integrations using compiler state- demo results — 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 for commands, preload options, and JSON output behavior.
Documentation
- Design philosophy
- Architecture boundaries
- Project overview
- Directive grammar specification
- Multiple engines
tests/fixtures/— Cross-language fixtures that help keep compiler behavior consistent across implementations.
For the full map, see docs/README.md.
License
Apache-2.0.
1 maintainer
Release files for context-compiler 0.9.2
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| context_compiler-0.9.2.tar.gz | 50.1 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| context_compiler-0.9.2-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 72.3 kB
Release files / context_compiler-0.9.2.tar.gz
| Download URL | context_compiler-0.9.2.tar.gz |
|---|---|
| Size | 50.1 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
ee53e4d877fb4edf4dca6ab9439842ec4dacb3821b5ae578a7f983ba4d097089
|
|
BLAKE2b-256 checksum How to use checksums |
b4b2e5d7ca157617179335ac8946b2bfeb6c2804ce7bcd9dc9ac21b982cc887f
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 14, 2026.
Transparency logRelease files / context_compiler-0.9.2-py3-none-any.whl
| Download URL | context_compiler-0.9.2-py3-none-any.whl |
|---|---|
| Size | 22.1 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
4c9d8184a24cf3f6cab55bf7b43bb72a11145177847134a2ebd94f5154efb286
|
|
BLAKE2b-256 checksum How to use checksums |
8d21cbcedecf6158d738c24a952f8cc95637d24f000ee60f066a43673d09754a
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 14, 2026.
Transparency log
