Skip to content

api-reference.md

Latest commit

 

History

History
317 lines (219 loc) · 8.41 KB

api-reference.md

File metadata and controls

317 lines (219 loc) · 8.41 KB
Raw

API Reference

Public API reference for context_compiler.

This page documents the exported package surface and typical usage patterns. It does not redefine behavioral semantics.

Authoritative behavior documents:

For behavioral semantics, use the authoritative documents above. This page documents the supported public package surface without redefining directive or continuation behavior.

Core boundary:

  • core consumes canonical directives
  • canonical directive validation remains in core
  • semantic validation and authoritative state transitions remain in core
  • pending continuation, when supported, is created only by semantic evaluation of canonical directives
  • human-facing normalization, malformed-input recovery, and intent drafting are outside the core contract
  • core does not convert failed canonical operations into different directives

Engine Lifecycle

create_engine(state=None)

Create a new engine instance.

  • state=None: start from empty authoritative state
  • state=<State>: initialize from a validated authoritative state snapshot

Typical use:

from context_compiler import create_engine

engine = create_engine()

engine.step(user_input)

Parse one user turn and return a deterministic Decision.

Typical use:

decision = engine.step("set premise current project uses uv")

Behavior for directive handling and clarification is defined by the Directive Grammar Specification.

Important grammar contract:

  • one input may contain at most one canonical directive
  • directive-shaped invalid input is outside the canonical language
  • clarify is reserved for canonical directives that fail semantic evaluation
  • quote characters do not create protected literal regions inside recognized directive payloads

context_compiler.grammar

Canonical grammar helpers are available from the context_compiler.grammar submodule.

Public grammar surface:

  • DirectiveKind
  • ValidatedDirective
  • validate_directive(text)
  • is_canonical_directive(text)
  • render_directive(kind, /, **operands)

Use this surface for exact canonical validation or canonical directive string construction only.

Boundary notes:

  • no public parser is exposed
  • validation returns None for any non-canonical input
  • rendering is syntax-only and performs no state interpretation
  • engine.step(...) remains the authority for clarification, state transitions, and mutation behavior
  • engine.step(...) is not a general natural-language repair surface; host code should send canonical directives when it wants deterministic mutation
  • failed replacement requests are not reinterpreted by core into different directives
  • use <new> instead of <old> with an absent <old> is not a pending or clarification-only runtime category; it follows the deterministic semantic rules defined in the specification

engine.state

Read the current authoritative in-memory state snapshot.

The internal structure is intentionally opaque for normal host use. Prefer get_premise_value(state) and get_policy_items(state, ...) over direct key traversal unless you are working at an explicit serialization boundary.

engine.has_pending_clarification()

Return whether a confirmation-required semantic continuation is currently pending.

Contract boundary:

  • pending continuation is runtime state, not grammar
  • pending continuation must never arise from malformed or non-canonical input
  • pending continuation, when supported, comes only from semantic evaluation of an already parsed canonical directive
  • the historical missing-source replacement case does not, by itself, create pending continuation

Current implementation note:

  • the updated specification allows supported pending continuation semantics
  • the current runtime implementation may still return False for all inputs until the continuation behavior is restored

Typical use:

if engine.has_pending_clarification():
    show_pending_ui()

Decision API

Each user message produces a Decision.

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

Decision kinds:

kind Intended host use
passthrough forward the user input to the model/runtime
update authoritative state changed; host may apply downstream behavior using updated state
clarify show prompt_to_user; do not continue normal downstream processing yet

Helper functions:

  • is_passthrough(decision)
  • is_update(decision)
  • is_clarify(decision)
  • get_clarify_prompt(decision)
  • get_decision_state(decision)

Typical use:

from context_compiler import get_clarify_prompt, is_clarify, is_update

decision = engine.step(user_input)

if is_clarify(decision):
    show_to_user(get_clarify_prompt(decision))
elif is_update(decision):
    apply_runtime_rules()

State Access

Use the exported helpers for normal reads from a State snapshot.

Premise helpers

  • get_premise_value(state) returns the current premise value or None

Policy helpers

  • get_policy_items(state) returns all policy items
  • get_policy_items(state, "use") returns use items
  • get_policy_items(state, "prohibit") returns prohibit items

Typical use:

from context_compiler import POLICY_PROHIBIT, get_policy_items

blocked_tools = get_policy_items(state, POLICY_PROHIBIT)

See the README’s State Model section for conceptual guidance on premise vs policy usage.

State Import/Export

engine.export_json()

Export authoritative state as canonical JSON text.

engine.import_json(payload)

Validate and restore authoritative state from exported JSON text.

Use these APIs for authoritative-state transport or persistence only.

Conceptual boundary:

  • export_json() / import_json() are the current persistence contract
  • pending continuation, when supported by the engine contract, is runtime state rather than a documented persistence feature
  • imported policy keys are normalized during import_json(...)
  • if a policy key normalizes to "", the payload is invalid and is rejected

Controller APIs

These controller APIs are public package exports and can be used directly in host code, not only through the REPL.

step(engine, user_input)

Run one turn through an engine and return a StepResult.

StepResult contains:

  • output_version
  • mode
  • decision
  • state

preview(engine, user_input)

Run a deterministic dry-run preview and return a PreviewResult.

PreviewResult contains:

  • output_version
  • mode
  • decision
  • state_before
  • state_after
  • diff
  • would_mutate

preview(...) restores live engine state after the dry run.

state_diff(state_before, state_after)

Return a StructuralDiff describing premise and policy changes between two state snapshots.

Typical use:

from context_compiler import (
    create_engine,
    diff_has_changes,
    get_preview_state_after,
    preview,
    state_diff,
)

engine = create_engine()
before = engine.state
dry_run = preview(engine, "prohibit peanuts")
diff = state_diff(before, get_preview_state_after(dry_run))

if diff_has_changes(diff):
    show_preview(diff)

Controller helper functions:

  • get_step_decision(step_result)
  • get_step_state(step_result)
  • get_preview_decision(preview_result)
  • get_preview_state_after(preview_result)
  • preview_would_mutate(preview_result)
  • diff_has_changes(diff)

For controller result-envelope details, see the controller conformance fixture documentation in tests/fixtures/README.md.

Public Constants

Decision-kind constants:

  • DECISION_PASSTHROUGH
  • DECISION_UPDATE
  • DECISION_CLARIFY

Policy-value constants:

  • POLICY_USE
  • POLICY_PROHIBIT

Use these when you want explicit string comparisons without hard-coding literals in host code.

Result Object Summaries

Public result and data object names exported at package root include:

  • Decision
  • State
  • Checkpoint
  • StepResult
  • PreviewResult
  • StructuralDiff
  • Engine

These names are part of the public package surface. For the exact portable API export contract used by tests and ports, see tests/fixtures/conformance/api/public-api-v1.json.