Skip to content

Compress context in model calls and Flow

Set a context header to reduce editable model input or tool-result text. The same policy works on a concrete interact_with_* action and on interact_with_llm, including calls made by Flow. It requires no agent loop.

import a11
from a11.sdk.llm_context import LlmContextConfig, LlmContextHeaders
from a11.sdk.interact_with_llm import interact_with_llm
from a11.sdk.interact_with_llm_schema import INTERACT_WITH_LLM_SCHEMA

policy = LlmContextConfig(input_content="lossless", tool_results="lossless")
call = (
    a11.Action(INTERACT_WITH_LLM_SCHEMA)
    .bind_handler(interact_with_llm)
    .set_header(LlmContextHeaders.CONFIG, policy.model_dump_json())
)

Supply the normal provider/model headers and ports, then run the action using the model-call protocol. Tool execution, typed output fragments, provider generation options, and action statuses retain their normal owners. Only editable request spans and successful model-facing tool results are projected. System instructions, assistant output, signed reasoning, images, and unknown blocks remain outside deterministic text compression.

The native transforms remove JSON whitespace or encode repeated content. A reversible envelope is model-facing content, so evaluate the model's ability to read it on your workload. strategy="json" selects whitespace compaction alone. Neither strategy silently truncates data.

To prepare model context before choosing a provider, use portable Interaction views. Proposal generation, owner acceptance, and replay are separate calls. The same accepted checkpoint works with compatible backends and through programmatic host callbacks or utility RPC.

Return a compact view from an agnostic tool

A library caller can use the utilities without constructing an Action:

from a11.sdk.llm_context import compress_content, expand_content

original = "Repeated diagnostic line\n" * 1000
projected = compress_content(original, {"strategy": "lines"})
assert expand_content(projected["text"]) == original

A callable tool can return projected["text"] through its existing result API. Keep the original in its existing owner. When a tool exposes an explicit view schema, return the view, report, and optional original reference together. The tool's caller needs no A11-specific agent or model routing.

Use the same utilities as actions and in Flow

import a11
from a11.sdk.llm_context import register

registry = a11.ActionRegistry()
register(registry, names=["llm_context_compress", "llm_context_count", "llm_context_compact"])

A llm_context_compress call writes {"text": ...} to request and reads result. Configure its header before running it. For Flow, register the same handlers:

flow shrink {
  in  request: object

  out result: object
  nodes scratch
  compact = run llm_context_compress(request: request) via scratch
  compact.result -> result
}

Invoke the program with headers={"x-a11-llm-context-config": '{"strategy":"lines"}'}. A Flow that already calls a model action needs only that header/configuration to enable the same request preparation. Raw typed ports continue to carry original data for Flow arithmetic and filtering.

Compact a history prefix

from a11.sdk.llm_context import LlmContextConfig, compact_history

policy = LlmContextConfig(
    compaction="summary", max_tokens=12000, reserve_tokens=2000,
    retain_recent=4,
)
proposal = await compact_history(history, policy, summarizer=summarize_prefix)

summarize_prefix(prefix) returns nonempty text, synchronously or asynchronously. Include goals, decisions, constraints, unresolved work, and source references in your summarizer's instructions. The utility keeps recent entries and complete tool groups, checks the resulting budget, and returns source_digest, covered_ids, and retained_boundary for validation. A standalone proposal becomes active only when the host installs it.

Automatic request compaction binds the summarizer at the receiving registry:

from a11.sdk.llm_context import LlmContextServices, bind_services

bind_services(registry, LlmContextServices(summarizers={"checkpoint": summarize_prefix}))

Set summarizer="checkpoint" on the action policy. Alternatively, register a summarizer action with a history input and checkpoint output. Its nested call inherits the action deadline and explicitly disables recursive compaction.

Replay-based providers can send the projected history after their host installs it for later requests. Recomputing a summary from the original prefix on each request changes the cache prefix and can repeat summarization work. Resumed Codex/Claude Code sessions and Gemini ID chains own history on another service; a client-side history edit cannot replace that state. The integration returns FAILED_PRECONDITION when automatic summary compaction requires that missing capability. Use a standalone proposal and a supported host replacement API.

Retain originals and resume a view

from a11.sdk.llm_context import LlmContextServices, RetainedContentStore, bind_services

store = RetainedContentStore("/host/context", owner="analysis-host")
bind_services(registry, LlmContextServices(
    retention=store,
    authorize_scope=authorize_context_scope,
))

The authorization callback receives the actual Action and validated scope. Check it against the host's authenticated identity and access policy. Set retention=true in context policy and send an explicit scope header:

{
  "owner": "analysis-host",
  "conversation": "conversation-42",
  "branch": "main",
  "expected_revision": 0,
  "operation_id": "request-1"
}

The SDK retains original messages and saves the projected view with a revision check. Its internal context log records the resulting descriptor. Pass the returned revision in the next explicit operation; use a new operation ID when input changes. Repeating an operation with the same source reuses its stored view. A source mismatch or stale revision returns ABORTED. Automatic request preparation derives a request operation from the caller operation ID, source digest, policy, and host service revision. Each completed model round advances the action's serialized scope revision; callers use the emitted revision across separate actions. A durable pending claim prevents a retry from duplicating a summary call after an uncertain outcome. Reconcile pending work at its owner before retrying it.

llm_context_load_view and llm_context_retrieve recover authorized views/data through ordinary actions. Library hosts can call load_view and retrieve directly under their own authorization. Retrieval is paged on UTF-8 byte boundaries. Expiry and quotas bound retention; purge_expired() releases expired payloads. Applications select the owner and root path, never caller headers.

Each process receiving actions binds its own services. Policy/scope headers and references survive transport; Python objects and caches do not establish remote identity or correctness. SDK-registered Python handlers retain their receiving host binding through native registry copies for sessions. A cold remote process registers its own services. The gateway also binds its configured services on each receiving session registry.

Publish configured defaults

configure_registry(registry, policy, names=[...], services=...) publishes policy through existing header schema defaults. Explicit call headers, including {"enabled":false}, override them. The gateway exposes the same default with a11 gateway --llm-context-config '{"input_content":"lossless"}' and with GatewayConfig.llm_context_config for embedded operation.

See the reference for settings, return contracts, and measurement before comparing workloads.

Recover retained operations

Read the stored operation ID from load_view or the operation report when recovering an automatically projected view. Derived operation IDs hash the owner/conversation/branch, caller operation, source digest, and policy revision; they fit the same bounded wire scope as caller IDs.

The receiving host owns durable retention state. inspect_operation reads its claim token and pending/committed/released/abandoned/expired state. reconcile_operation requires the observed token and an audit note. An explicit owner decision can abandon work or release it for a retry after reconciling external effects. A replacement token fences the previous worker. Lost replies receive no automatic summarizer retry.

The ordinary actions llm_context_inspect_operation and llm_context_reconcile_operation carry those requests over existing transports. Their scope, including operation ID, is authorized on the receiving host. llm_context_fork_view authorizes both source and destination scopes, copies retained source into the destination, and starts that branch at revision one. llm_context_save_view accepts an optional claim token and requires it when completing previously claimed work.

collect_garbage is a host-owned maintenance operation. It clears expired, failed, and abandoned payloads and preserves revision heads as tombstones. Its pending grace accounts for live writers. A process restart retains claims, accepted manifests, and revision checks in SQLite; no task-local cache supplies recovery evidence. Quotas bound payload bytes and metadata record counts.