xr_ai_conversation#

Application-instructed conversation and shareable participant-scoped context.

Classes#

`ConversationContextUpdate`	Text published on a configured conversation-context topic.
`Conversation`	Application-instructed conversation agent over participant-scoped context.
`CompactionPrompts`	System prompts for the model requests that compact context.
`ContextBlock`	One rendered piece of prior context and the time of its newest content.
`ContextManager`	Retain participant-scoped context and render it into prompts for any number of agents.

Package Contents#

class xr_ai_conversation.ConversationContextUpdate#

Text published on a configured conversation-context topic.

text: str#: Non-empty source-owned context text; handling comes from topic configuration.

class xr_ai_conversation.Conversation( llm: xr_ai_models.LLMService, *, context: xr_ai_conversation.ContextManager, instructions: str = '', system_prompt: str | None = None, routing: xr_ai_routing.RoutingAid | None = None, runtime: xr_ai_runtime.AgentRuntime, output_topic: xr_ai_runtime.Topic[xr_ai_interaction.ResponseOutput], )#

Application-instructed conversation agent over participant-scoped context.

The conversation owns its prompt and answer; context owns what is remembered. The caller creates the manager, may share it with other agents, registers its subscriber(), and closes it.

Parameters:

llm – Typed streamed language model service.
context – Participant context rendered into each request. The conversation records completed exchanges in it and never clears or closes it.
instructions – Application-owned prompt text defining domain, role, tone, and handling policy, appended to the system prompt.
system_prompt – Replaces the default general-conversation system prompt.
routing – Concise front-end metadata; defaults to a general conversation description.
runtime – Runtime used to publish answers. The application owns runtime startup and shutdown.
output_topic – Explicit ResponseOutput topic for routed answers. The conversation publishes replies with its routing name as source, the turn ID as request ID, and the originating timestamp. It owns stream framing and finalization. No default output or query topic is subscribed.

routing_aid(_participant_id: str) → xr_ai_routing.RoutingAid#: Return this destination’s routing metadata.

async admit( turn: xr_ai_routing.AgentTurn, *, focused: bool, ) → xr_ai_routing.Admission#: Accept ordinary turns without retaining participant focus.

async answer( turn: xr_ai_routing.AgentTurn, *, started: collections.abc.Callable[[], collections.abc.Awaitable[None]], ) → xr_ai_routing.DestinationResult#

Publish a routed answer directly to the configured output topic.

Requires runtime and output_topic. The answer is a reply to the turn’s ID. The first nonblank ready chunk awaits started() before publication, and an empty final frame closes a completed, failed, or canceled response once opened. Canceled answers publish no further text, and a publication failure publishes no further frames. Failures propagate after closing the model iterator; the router reports failures that occur before the first frame. A successful answer returns the complete text as routing context. The exchange joins the participant’s context only after its final frame is delivered.

async release(_participant_id: str) → None#

Keep completed participant context; this destination holds no active resources.

Participant context belongs to the context manager, whose owner clears it.

async participant_left(_participant_id: str) → None#: Hold nothing for a departed participant; the context manager’s owner clears its context.

async close() → None#: Stop answering. The caller closes the context manager and drains answer streams.

class xr_ai_conversation.CompactionPrompts#

System prompts for the model requests that compact context.

Each prompt says what to keep and how to treat the material. The manager adds the size limit and the output format, so a prompt does not state them.

source: str = 'Summarize only the source-owned background context below. Preserve factual details, user...#: Instructions for compacting an incremental topic’s updates into its summary.

dialogue: str = 'Summarize the completed conversation history for future turns. Preserve user-provided facts,...#: Instructions for compacting completed exchanges into the dialogue summary.

condense: str = 'Shorten this summary. Keep facts, preferences, corrections, unresolved requests, and uncertainty.'#: Instructions for shortening a summary that is over its size limit.

class xr_ai_conversation.ContextBlock#

One rendered piece of prior context and the time of its newest content.

A summary block has no timestamp and sorts before dated blocks.

timestamp_us: int | None#: Unix microseconds of the block’s newest content, or None for a summary.

text: str#: Rendered prompt text.

class xr_ai_conversation.ContextManager( llm: xr_ai_models.LLMService, *, summary_context_topics: collections.abc.Sequence[str] = (), incremental_context_topics: collections.abc.Sequence[str] = (), dialogue_budget_bytes: int = _DEFAULT_DIALOGUE_BUDGET_BYTES, topic_budget_bytes: int | collections.abc.Mapping[str, int] = _DEFAULT_TOPIC_BUDGET_BYTES, compaction_input_budget_bytes: int = _DEFAULT_COMPACTION_INPUT_BUDGET_BYTES, compaction_prompts: CompactionPrompts | None = None, )#

Retain participant-scoped context and render it into prompts for any number of agents.

Completed dialogue and each configured topic are separate sections with their own byte budget. A summary topic keeps only its latest state; an incremental topic and the dialogue keep recent entries verbatim and fold older ones into a rolling summary written by llm.

Every method runs on the event loop and none yields between reading and writing a participant’s context, so a participant’s context is never observed half-updated. Compaction runs as a background task per section.

The owner creates the manager, registers subscriber() with the runtime that delivers context updates, calls clear() when a participant leaves, and calls close() at shutdown. Agents that share a manager use its budgets, so those are configured here and not per agent.

Parameters:

llm – Model service that writes compaction summaries.
summary_context_topics – Runtime topic names whose text replaces that source’s state.
incremental_context_topics – Runtime topic names whose text appends to that source.
dialogue_budget_bytes – UTF-8 byte budget for completed dialogue rendered into a prompt.
topic_budget_bytes – UTF-8 byte budget for each topic’s context rendered into a prompt: one value for every topic, or a mapping with a value for each configured topic.
compaction_input_budget_bytes – UTF-8 byte budget for the summary and entries in one compaction request; at least half the largest section budget plus 256 bytes.
compaction_prompts – Compaction instructions; defaults to CompactionPrompts().

All budgets must be positive. Topic lists contain non-empty names; names must be unique within and across both lists.

subscriber() → xr_ai_runtime.Agent#

Return an Agent that applies the configured context topics to this manager.

Register the result with the same AgentRuntime as the consumer. Configure at least one topic before calling this method.

async update( participant_id: str, source: str, update: xr_ai_conversation.ConversationContextUpdate, *, mode: Literal['summary', 'incremental'], timestamp_us: int | None = None, ) → None#

Apply one configured topic update to a participant’s context.

Raises:: ValueError – If source is not a configured topic or mode is not its configured mode.

reconcile_history( participant_id: str, exchanges: collections.abc.Sequence[tuple[str, str, int | None]], *, exchange_ids: collections.abc.Sequence[object | None], ) → None#: Merge a front-end window of completed exchanges without replaying known ones.

record_exchange( participant_id: str, request: str, answer: str, *, timestamp_us: int, exchange_id: object | None, ) → None#: Add one completed exchange to a participant’s dialogue; dropped once closed.

blocks(participant_id: str) → tuple[ContextBlock, Ellipsis]#: Render a participant’s dialogue and topic context, summaries first, then newer entries in time order.

async clear(participant_id: str) → None#

Forget a participant’s context after cancelling its compaction jobs.

Later writes for that participant start new context.

async close() → None#: Drop later topic updates and forget all context after cancelling compaction jobs.