Skip to content

xtr_ai_orm_conversation_store

Agent conversations stored in a relational database, for xtr-ai.

:class:OrmConversationStore is a pydantic-ai ConversationStore on two tables, written through an xtr-orm connection's engine in short transactions of its own. :class:ConversationMappingDriver adds those tables to a connection's definitions, so orm:migrations:diff writes them.

DEFAULT_TABLE_PREFIX module-attribute

DEFAULT_TABLE_PREFIX: Final = 'ai_'

What both table names start with unless told otherwise.

ConversationMappingDriver

ConversationMappingDriver(table_prefix: str = DEFAULT_TABLE_PREFIX)

Bases: MappingDriverInterface

Adds the two conversation tables to a connection's definitions.

Register it through xtr-orm's OrmMappingsPass so the connection's migrations know the tables; the store itself defines its own copy and needs nothing from here.

Add tables whose names start with table_prefix.

load_metadata

load_metadata(metadata: MetaData) -> tuple[str, ...]

Add the tables metadata lacks; return the names added, () the second time.

ConversationTables dataclass

ConversationTables(conversation: Table, entry: Table)

{prefix}conversation, a row per conversation; {prefix}conversation_entry, a message.

An entry holds one message and points at the entry before it; entries are shared between a conversation and its forks, so they carry no conversation of their own. Every structured value is pydantic's JSON, as text, so binary content keeps its base64 form on every database.

define classmethod

define(metadata: MetaData, table_prefix: str = DEFAULT_TABLE_PREFIX) -> ConversationTables

Return the tables in metadata, adding them first where they are not there.

OrmConversationStore

OrmConversationStore(engine: AsyncEngine, *, table_prefix: str = DEFAULT_TABLE_PREFIX)

Bases: ConversationStore

Conversations in {prefix}conversation and {prefix}conversation_entry.

Every call runs in a short transaction of its own on engine — give it the primary's — and commits before it returns: a conversation is never part of the caller's unit of work, so a long model call holds no database connection, and a rollback of the caller's work never takes a saved turn with it. Saving a record and the messages it adds is one transaction, so a conflict leaves neither behind.

A conversation's history is read with one recursive query. Deleting a conversation deletes every message only it reaches; the messages a fork of it — or the conversation it was forked from — still reaches stay until the last of them is deleted.

store = OrmConversationStore(engine)
conversation = await store.load(conversation_id) or Conversation(
    conversation_id=conversation_id
)
result = await agent.run(prompt, conversation=conversation)
await store.save(result)

Store through engine, in tables whose names start with table_prefix.

read_history async

read_history(head_id: str | None, *, limit: int | None = None) -> list[ConversationEntry]

Read the history up to head_id in one recursive query.

Raises:

  • KeyError –

    When an entry of the history is missing, as a concurrent delete leaves it.