From 0a79f683a17c073f9d2c795b4b736184da64b8d3 Mon Sep 17 00:00:00 2001 From: Robert Lippmann Date: Thu, 28 May 2026 01:36:45 -0400 Subject: [PATCH 1/3] docs: polish readability and helper usage in examples --- README.md | 14 +++++++------- demos/README.md | 8 ++++---- examples/08_controller_preview_diff.ts | 9 ++++++--- examples/README.md | 6 +++--- 4 files changed, 20 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index bb6d978..f21c999 100644 --- a/README.md +++ b/README.md @@ -6,7 +6,7 @@ Context Compiler helps applications keep explicit user instructions separate fro The model writes responses. The compiler stores premise and policy rules. -This package is the TypeScript implementation of the Context Compiler engine, aligned with Python 0.7 API behavior. +This package is the TypeScript implementation of the Context Compiler engine, aligned with Python 0.7 behavior. ## What it does @@ -45,12 +45,12 @@ Directive examples: - checkpoint restore - experimental preprocessor behavior - public API behavior -- Core public API for engine usage and transcript compilation. +- Core public API for engine usage and transcript replay. - Checkpoint APIs for saving and restoring rules plus pending clarification state. - Controller APIs for step envelopes, preview/dry-run, and structural state diffs. -- Decision constants exported for host-side checks. +- Decision constants for host-side checks. - Experimental preprocessor module exposed through a package subpath import. -- Fixture parity aligned to the Python 0.7.3 fixture snapshot. +- Fixture parity aligned with the Python 0.7.3 fixture snapshot. ## Not Included Yet @@ -73,7 +73,7 @@ npm install @rlippmann/context-compiler ## Quick Start ```ts -import { createEngine, get_clarify_prompt, is_clarify, is_update } from '@rlippmann/context-compiler'; +import { createEngine, get_clarify_prompt, is_clarify, is_passthrough, is_update } from '@rlippmann/context-compiler'; const engine = createEngine(); const decision = engine.step('set premise concise replies'); @@ -83,7 +83,7 @@ if (is_update(decision)) { console.log(engine.state); } else if (is_clarify(decision)) { console.log(get_clarify_prompt(decision)); -} else { +} else if (is_passthrough(decision)) { // passthrough } ``` @@ -95,7 +95,7 @@ if (is_update(decision)) { - `engine.state` -> current stored premise/policy rules snapshot. - `engine.has_pending_clarification()` -> check whether confirmation-only input is currently required. - `engine.exportJson()` / `engine.importJson(payload)` -> state serialization utilities. -- `engine.exportCheckpoint()` / `engine.importCheckpoint(payload)` -> checkpoint persistence (`authoritative_state` + pending confirmation state) for safe resume. +- `engine.exportCheckpoint()` / `engine.importCheckpoint(payload)` -> checkpoint persistence (`authoritative_state` + pending confirmation state) that safely resumes pending confirmations. - `engine.exportCheckpointJson()` / `engine.importCheckpointJson(payload)` -> JSON checkpoint wrapper persistence helpers. - `compile_transcript(messages)` -> replay user messages and return `state` or `confirm`. - `engine.apply_transcript(messages)` -> replay user messages onto an existing engine instance. diff --git a/demos/README.md b/demos/README.md index 0f6eec2..75ce652 100644 --- a/demos/README.md +++ b/demos/README.md @@ -2,16 +2,16 @@ These scripts show side-by-side LLM outcomes with and without stored compiler rules, aligned with the [Python reference demos](https://github.com/rlippmann/context-compiler/blob/main/demos/README.md). -Scored demos compare three host flows: +Scored demos compare three host-side flows: - baseline -- compiler path (full transcript + injected stored rules/state) -- compiler+compact (compacted transcript + injected stored rules/state) +- compiler path (full transcript + injected stored rules and state) +- compiler+compact (compacted transcript + injected stored rules and state) Demo 06 is informational (context/prompt compaction metrics), not scored. ## Result variability note -LLM demo outcomes can vary across environments. In practice, PASS/FAIL patterns may differ based on: +LLM demo outcomes can vary across environments. PASS/FAIL patterns may differ based on: - provider - client layer - model serving path diff --git a/examples/08_controller_preview_diff.ts b/examples/08_controller_preview_diff.ts index 184892c..f2066fe 100644 --- a/examples/08_controller_preview_diff.ts +++ b/examples/08_controller_preview_diff.ts @@ -2,8 +2,11 @@ import { DECISION_CLARIFY, DECISION_PASSTHROUGH, DECISION_UPDATE, + POLICY_PROHIBIT, + POLICY_USE, createEngine, getPolicyItems, + get_clarify_prompt, getPremiseValue, get_decision_state, is_clarify, @@ -24,8 +27,8 @@ function summarizeState(state: EngineState): { } { return { premise: getPremiseValue(state), - usePolicies: getPolicyItems(state, 'use'), - prohibitPolicies: getPolicyItems(state, 'prohibit') + usePolicies: getPolicyItems(state, POLICY_USE), + prohibitPolicies: getPolicyItems(state, POLICY_PROHIBIT) }; } @@ -46,7 +49,7 @@ function summarizeDecision(decision: Decision): { if (is_clarify(decision)) { return { kind: DECISION_CLARIFY, - promptToUser: decision.prompt_to_user, + promptToUser: get_clarify_prompt(decision), decisionState: null }; } diff --git a/examples/README.md b/examples/README.md index 4de769b..a2bcb3f 100644 --- a/examples/README.md +++ b/examples/README.md @@ -3,7 +3,7 @@ TypeScript examples showing how host applications keep rules and corrections consistent across turns. These examples follow the Python 0.7 behavior baseline and use only core APIs. -Request-scoped integrations can persist compiler state with checkpoint APIs so rules and corrections stay consistent across turns. +Request-based integrations can persist compiler state with checkpoint APIs so rules and corrections stay consistent across turns. ## 01_persistent_guardrails.ts @@ -30,7 +30,7 @@ Includes single-item correction with `remove policy `. ## 06_transcript_replay.ts -Demonstrates transcript replay behavior with `compile_transcript(messages)` and replay onto current engine state via `engine.apply_transcript(...)`. +Shows transcript replay with `compile_transcript(messages)` and replay onto current engine state with `engine.apply_transcript(...)`. ## 07_single_policy_correction.ts @@ -39,5 +39,5 @@ Demonstrates explicit single-policy correction without `reset policies`: ## 08_controller_preview_diff.ts -Demonstrates controller-layer auditability with `preview(engine, input)` and `state_diff(before, after)`. +Shows controller-layer auditability with `preview(engine, input)` and `state_diff(before, after)`. Shows that preview does not mutate live engine state, then applies the same input with `step(engine, input)`. From e1dae3534d0aa30e57d840e12f44c2b699cadb0a Mon Sep 17 00:00:00 2001 From: Robert Lippmann Date: Thu, 28 May 2026 01:41:33 -0400 Subject: [PATCH 2/3] chore: bump package version to 0.7.0 --- package-lock.json | 43 ++----------------------------------------- package.json | 2 +- 2 files changed, 3 insertions(+), 42 deletions(-) diff --git a/package-lock.json b/package-lock.json index e3e4867..a260b33 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1,12 +1,12 @@ { "name": "@rlippmann/context-compiler", - "version": "0.5.2", + "version": "0.7.0", "lockfileVersion": 3, "requires": true, "packages": { "": { "name": "@rlippmann/context-compiler", - "version": "0.5.2", + "version": "0.7.0", "license": "Apache-2.0", "devDependencies": { "typescript": "^5.9.3", @@ -554,9 +554,6 @@ "arm" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -571,9 +568,6 @@ "arm" ], "dev": true, - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -588,9 +582,6 @@ "arm64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -605,9 +596,6 @@ "arm64" ], "dev": true, - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -622,9 +610,6 @@ "loong64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -639,9 +624,6 @@ "loong64" ], "dev": true, - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -656,9 +638,6 @@ "ppc64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -673,9 +652,6 @@ "ppc64" ], "dev": true, - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -690,9 +666,6 @@ "riscv64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -707,9 +680,6 @@ "riscv64" ], "dev": true, - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ @@ -724,9 +694,6 @@ "s390x" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -741,9 +708,6 @@ "x64" ], "dev": true, - "libc": [ - "glibc" - ], "license": "MIT", "optional": true, "os": [ @@ -758,9 +722,6 @@ "x64" ], "dev": true, - "libc": [ - "musl" - ], "license": "MIT", "optional": true, "os": [ diff --git a/package.json b/package.json index 2bfd31a..3a71bbf 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "@rlippmann/context-compiler", - "version": "0.6.1", + "version": "0.7.0", "description": "Store AI rules and corrections separately from chat history so they stay consistent across turns.", "keywords": [ "llm", From 6c6962e3b5b2c610145d44d9b7f6c3a0e0fc9ce3 Mon Sep 17 00:00:00 2001 From: Robert Lippmann Date: Thu, 28 May 2026 01:43:05 -0400 Subject: [PATCH 3/3] chore: run npm audit fix --- package-lock.json | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/package-lock.json b/package-lock.json index a260b33..e53f67b 100644 --- a/package-lock.json +++ b/package-lock.json @@ -1161,9 +1161,9 @@ "license": "MIT" }, "node_modules/nanoid": { - "version": "3.3.11", - "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.11.tgz", - "integrity": "sha512-N8SpfPUnUp1bK+PMYW8qSWdl9U+wwNWI4QKxOYDy9JAro3WMX7p2OeVRF9v+347pnakNevPmiHhNmZ2HbFA76w==", + "version": "3.3.12", + "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-3.3.12.tgz", + "integrity": "sha512-ZB9RH/39qpq5Vu6Y+NmUaFhQR6pp+M2Xt76XBnEwDaGcVAqhlvxrl3B2bKS5D3NH3QR76v3aSrKaF/Kiy7lEtQ==", "dev": true, "funding": [ { @@ -1217,9 +1217,9 @@ } }, "node_modules/postcss": { - "version": "8.5.8", - "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.8.tgz", - "integrity": "sha512-OW/rX8O/jXnm82Ey1k44pObPtdblfiuWnrd8X7GJ7emImCOstunGbXUpp7HdBrFQX6rJzn3sPT397Wp5aCwCHg==", + "version": "8.5.15", + "resolved": "https://registry.npmjs.org/postcss/-/postcss-8.5.15.tgz", + "integrity": "sha512-FfR8sjd4em2T6fb3I2MwAJU7HWVMr9zba+enmQeeWFfCbm+UOC/0X4DS8XtpUTMwWMGbjKYP7xjfNekzyGmB3A==", "dev": true, "funding": [ { @@ -1237,7 +1237,7 @@ ], "license": "MIT", "dependencies": { - "nanoid": "^3.3.11", + "nanoid": "^3.3.12", "picocolors": "^1.1.1", "source-map-js": "^1.2.1" },