Prepare Interaction views before choosing a backend¶
Build a model-facing view from A11 interactions, inspect its coverage, and accept
it through the history owner. The accepted checkpoint replays through compatible
interact_with_* backends without another summarizer call. These utilities run
as ordinary Python functions and require no A11 agent.
| History | Contents | Owner |
|---|---|---|
| Canonical interactions | Original records, typed chunks, action fragments, metadata, and IDs. | The application's existing history owner. |
| Interaction view | A source archive, projected normalized parts, instructions, covered IDs, and an explicit installation acknowledgement. | The host that accepts the view. |
| Harness-native history | Codex thread, Claude Code session, or ACP host history, including server-held records. | The actual harness/session service. |
A local Interaction view does not install a checkpoint in a server-held session. Use native harness coordination for those histories.
Build and inspect a proposal¶
import a11
from a11.sdk.llm import Interaction
from a11.sdk.llm_context import LlmContextConfig, project_interactions
canonical = [
Interaction(
system_instructions=[a11.to_chunk("Preserve exact identifiers")],
content=[a11.to_chunk("Earlier measurements " * 2000)],
),
Interaction(content=[a11.to_chunk("Continue the investigation")]),
]
policy = LlmContextConfig(
boundary="interaction",
input_content="lossless",
compaction="summary",
max_tokens=500,
reserve_tokens=100,
retain_recent=1,
)
proposal = await project_interactions(
canonical,
policy,
source_revision=7,
checkpoint="The accepted result is ALPHA-17; verify its measurement.",
)
assert proposal["state"] == "proposal"
assert proposal["covered_ids"] == [canonical[0].id]
Supply summarizer=callback instead of checkpoint for a host-selected
synchronous or asynchronous summarizer. The callback receives complete prefix
messages from the shared compaction engine and returns nonempty text. There is
no default summarization model. Supplied checkpoint text covers the selected
prefix; use an accepted view for reuse of an already committed checkpoint. compact_interactions selects summary
compaction explicitly; project_interactions applies the supplied policy.
The proposal's entries exclude the covered prefix and contain generated
checkpoint text separately from retained source entries. sources contains
complete typed Interaction chunk documents. interaction_view_sources(proposal)
recovers independent canonical records. source_ids, source_digest,
source_revision, covered_ids, retained_boundary, and view_id describe the
snapshot and projection. These identity fields remain explicit on the wire.
Instructions retain their order and precede model history. Recent history and complete tool-call/result groups stay together. Images, signed reasoning, and opaque blocks form protected boundaries during prefix selection. The shared counter applies the byte/token budget; provider framing, tool schemas, image charges, and hidden server history remain outside that count.
Accept through the history owner¶
from a11.sdk.llm_context import accept_interaction_view, use_interaction_view
accepted = await accept_interaction_view(
proposal,
read_history=host.read_snapshot,
install_view=host.install_projection,
)
model_history = use_interaction_view(accepted)
read_snapshot() returns {"interactions": [...], "revision": 7}.
install_projection(proposal, *, expected_revision, source_digest) atomically
checks that revision and digest, retains canonical history, and installs a
separate model-facing view. Both callbacks can be synchronous or asynchronous.
The installer acknowledges the exact committed view:
acknowledgement = {
"installed": True,
"owner": "application-history",
"view_id": proposal["view_id"],
"source_digest": proposal["source_digest"],
"source_revision": 7,
"revision": 8,
}
A11 rechecks sources before calling the installer. The owner's atomic check
covers concurrent changes during installation. A changed revision or source
returns ABORTED. Missing, mismatched, or uncertain installation receives an
explicit error and no automatic retry. Reconcile the operation with the owner
before retrying. Digests validate integrity; authorization comes from the host's
ordinary authenticated storage and transport boundaries.
Persist the accepted JSON document through the existing history owner. A host
using RetainedContentStore can call persist_interaction_view(proposal, store,
scope) and load_interaction_view(store, scope). This owner adopts the declared
canonical snapshot beside its projected view, using existing scoped manifests,
revision checks, operation IDs, and retained nodes. It does not validate an
external application's canonical revision: use that application's atomic
installer for its history. Ordinary utility actions additionally require the
receiving host's authorize_scope callback.
Continue with compatible backends¶
Pass model_history to the usual interactions port on a concrete backend or
on interact_with_llm. Choose the provider with the ordinary model/provider
headers. For example, select gpt for one fresh replay and claude for another,
using the same accepted JSON document. The receiving backend validates the
complete projected prefix and formats its existing NormalizedMessage parts.
Source producers are unnecessary after acceptance; the archive stays typed and
the portable projection contains the committed model content.
Append new canonical interactions after the materialized view for continuation.
Keep the complete projected prefix and its provenance together. Partial,
reordered, edited, or spliced projected prefixes fail validation. Persist new
canonical outputs through their ordinary owner. new_interactions continues to
carry original outputs and typed action fragments. Projected tool-result clones
feed only the backend conversation.
The view retains instructions, text, inline images, and identified tool calls
and results that existing normalization represents faithfully. Remote image
URLs with detail settings, signed reasoning, unknown blocks/metadata, failed
records, and unavailable producer normalizers remain opaque in proposals.
Portable replay of retained opaque entries returns FAILED_PRECONDITION.
Original chunks remain available for native replay through their existing owner.
Same-backend provider-message projection preserves native blocks directly.
Replay requires a fresh provider history. Codex/Claude session resumes, GPT
previous_response_id, and Gemini server-history continuations reject local
view substitution. A new fresh session can consume a compatible portable view;
its subsequent server-held history belongs to that new session.
Configure automatic request-local projection¶
With boundary="interaction", participating SDK backends build and accept a
request-local view before formatting provider messages. This selection changes
the request's model context; it installs no canonical application or native
harness history. retention=True additionally commits through a configured,
authorized retained-view owner. Absent headers disable automatic transforms.
The default boundary="provider" retains provider-message projection.
Without a selected Interaction policy or an explicitly supplied accepted view,
SDK inputs stream incrementally through their existing backend preparation.
Absent or disabled policies with measurement off apply no context-specific host
limits; active processing and explicit utility calls retain those limits.
| Boundary | Projection responsibility |
|---|---|
| Router | Forward Interaction fragments and provenance unchanged. |
| Concrete backend | Validate an accepted view, or apply the opted-in Interaction policy once. |
| Provider formatter | Format projected parts and enforce backend replay restrictions. |
| Tool bridge | Preserve raw canonical fragments; the active Interaction projection owns model-facing result compression. |
| Provider-message HTTP proxy | Apply provider policy to editable native message trees. |
An accepted view selects the Interaction boundary even without a policy header. Provider-message transforms skip a validated Interaction stage in that action. The stage carries the current action identity; inherited stages do not suppress unrelated nested actions. Equal decoded policies and immutable proof metadata use bounded caches. Serialized identities, revisions, and owner acknowledgements establish correctness across processes; those caches establish no ownership.
Select one projection owner for each request path. Configure an HTTP relay as
passthrough when an upstream SDK already projects its Interaction view. A proxy
cannot reconstruct A11 provenance from provider text and rejects
boundary="interaction". Completed-shell compression and Interaction projection
also require separate result ownership; selecting both returns a capability
error. Automatic generative shadow compaction requires a standalone proposal.
If an accepted prefix plus new history exceeds the configured summary budget,
request a new checkpoint through its owner.
Call utilities through actions and Flow¶
Register the ordinary handlers with register(registry, services=...). Send
encode_interactions(canonical) as request.interactions, an optional
source_revision, and an optional checkpoint. Policy travels in
x-a11-llm-context-config. The returned proposal is the same JSON contract as
the direct function.
flow project {
in request: object
out result: object
nodes scratch
view = run llm_context_compact_interactions(request: request) via scratch
view.result -> result
}
Use llm_context_accept_interaction_view with view and an authorized scope
to install through the receiving retained-view owner. Use
llm_context_load_interaction_view to recover it and
llm_context_use_interaction_view to receive typed projected Interaction chunk
documents. llm_context_project_interactions also supports compression without
summary compaction. Existing Flows that call model actions receive automatic
Interaction projection through their headers; the Flow language and runtime
require no changes.
Install from an external harness¶
from a11.sdk.llm_context import compact_host_interactions
accepted = await compact_host_interactions(
read_history=host.read_interaction_snapshot,
install_view=host.install_interaction_projection,
config=policy,
summarizer=host.summarize_prefix,
)
The host maps its editable records into A11 interactions and installs the accepted projection through its supported checkpoint API. Its inference client, agent loop, tool executor, and session persistence remain with the host. Programmatic callbacks require no shell or HTTP wrapper. Other languages can request standalone proposals over ordinary utility RPC and validate/install them through their native host APIs. The receiving utility's retained-view acknowledgement attests only that store; installation in the harness requires that harness owner's acknowledgement. Codex, Claude Code, and ACP native compaction remain separate coordination protocols.
Measure baseline and treatment through the same host path, including summary usage, installation outcome, and task quality. See Interaction measurement.