keelgate.context

Stability of each symbol (stable or provisional) is listed in the API contract. Narrative and semantics are in the integration contract.

As-of-time context assembly. Nothing published after as_of may enter.

ApproxTokenCounter

Roughly four characters a token, rounded up.

Deterministic and dependency-free. It over-counts slightly for English and under-counts for some scripts, so keep a safety margin in the budget, or supply a provider-exact counter that implements :class:TokenCounter.

AsOfViolationError

Bases: ContextError

An item was published after as_of.

BuiltContext dataclass

The result of building a context.

The messages to send, the admitted items, token use against the budget, what was compacted or dropped, and what was rejected.

Compaction dataclass

A record that several context items were replaced by one summary item.

The summary points back to the full records.

ContextBudgetError

Bases: ContextError

Trusted content alone does not fit the token budget.

ContextBuilder

Assembles a prompt for a given as_of.

Rejects anything published after it, labels outside text untrusted and fences it, and compacts over-budget context into summaries that point to the full records.

add

add(item: ContextItem) -> None

Admit item or raise. Every refusal is recorded first.

try_add

try_add(item: ContextItem) -> bool

Like :meth:add, but returns False instead of raising on a refusal.

ContextError

Bases: Exception

Base class for context assembly failures.

ContextItem

Bases: BaseModel

One piece of context: its content, trust level, publication time and provenance.

Only harness-authored kinds can be trusted; anything from outside is untrusted by type.

harness classmethod

harness(
    kind: ItemKind,
    content: str,
    *,
    item_id: str,
    priority: int = 1000,
    origin: str = "harness",
) -> ContextItem

A trusted, harness-authored item (system prompt, instructions, the operator task).

outside classmethod

outside(
    kind: ItemKind,
    content: str,
    *,
    item_id: str,
    published_at: datetime | None,
    origin: str,
    ref: str = "",
    uri: str | None = None,
    priority: int = 0,
) -> ContextItem

An untrusted item carrying outside text: tool output, memory, a document.

DuplicateItemError

Bases: ContextError

Two items share an id.

ExtractiveSummarizer

Deterministic and model-free: the first sentence of each item, with a pointer.

InMemoryRecordStore

Process-local store of full context records, so a compacted summary can always be traced back to what it replaced.

ItemKind

Bases: StrEnum

What a context item is: system text, an instruction, the task, an observation, memory, a document or a summary.

LLMSummarizer

Asks a model for a structured summary, and falls back to extraction if it misbehaves.

The model supplies facts, decisions and open_questions only. Pointers always come from the items themselves.

Provenance

Bases: BaseModel

Where an item came from. origin is a stable label; ref is a record id.

RecordStore

Bases: Protocol

Keeps the full text behind a summary pointer.

Rejection dataclass

A refused item. Deliberately carries a hash, never the content.

RejectionReason

Bases: StrEnum

Why an item was kept out of the context: published after as_of, undated, or a duplicate id.

StructuredSummary

Bases: BaseModel

A compacted summary: facts, decisions and open questions, plus pointers back to the full records it replaced.

render

render() -> str

Deterministic text form, with the pointers spelled out.

Summarizer

Bases: Protocol

Compacts items into a structured summary.

A summary of untrusted text stays untrusted, and the pointers to the originals are not the summarizer's to forge.

TokenCounter

Bases: Protocol

Counts the tokens in a piece of text, so the builder can honour a budget.

Trust

Bases: StrEnum

Whether a context item may be treated as an instruction (TRUSTED) or only as data (UNTRUSTED).

UndatedItemError

Bases: ContextError

An outside item carries no publication time, so it cannot be shown to be earlier.