xtr-ai-orm-conversation-store 6.6.0__tar.gz

xtr_ai_orm_conversation_store-6.6.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 xterr
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

xtr_ai_orm_conversation_store-6.6.0/PKG-INFO

@@ -0,0 +1,95 @@
+Metadata-Version: 2.4
+Name: xtr-ai-orm-conversation-store
+Version: 6.6.0
+Summary: Agent conversations stored in a relational database through xtr-orm, for xtr-ai.
+Keywords: ai,llm,agent,pydantic-ai,conversation,sqlalchemy,database
+Author: Xterr
+Author-email: Xterr <me@xterr.dev>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: pydantic-ai-slim>=2.66,<3
+Requires-Dist: sqlalchemy[asyncio]>=2.0.41
+Requires-Dist: typing-extensions>=4.12
+Requires-Dist: xtr-ai>=6.0,<7
+Requires-Dist: xtr-orm>=6.0,<7
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# xtr-ai-orm-conversation-store
+
+Agent conversations kept in two tables on an [xtr-orm](../xtr-orm) connection, for
+[xtr-ai](../xtr-ai).
+
+## Install
+
+```sh
+uv add "xtr-ai[orm]"
+```
+
+The `orm` extra installs this package.
+
+## Use
+
+`OrmConversationStore` is a pydantic-ai `ConversationStore`. Give it the connection's primary
+engine:
+
+```python
+from pydantic_ai.conversation import Conversation
+
+from xtr_ai_orm_conversation_store import OrmConversationStore
+
+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)
+```
+
+In an application, configure it in xtr-ai instead, as
+`conversation_stores={"default": OrmConversationStoreConfig(connection="default")}`, and inject
+`ConversationStore`. See xtr-ai's [Use in an application](../xtr-ai#use-in-an-application).
+
+## Tables
+
+| Table | Holds |
+|---|---|
+| `ai_conversation` | One row per conversation: where its history ends, usage, pending tool calls, scope, branches, fork origin, revision |
+| `ai_conversation_entry` | One row per message, pointing at the one before it; shared by a conversation and its forks |
+
+`table_prefix` changes `ai_`. `ConversationMappingDriver` adds the tables to a connection's
+definitions, so `orm:migrations:diff` writes them. xtr-ai registers it when the store is
+configured.
+
+## Behaviour
+
+- **Own transactions.** Every call runs in a short transaction of its own and commits before it
+  returns. A store never joins the caller's unit of work.
+  - A long model call holds no database connection.
+  - Rolling back the caller's work never undoes a saved turn.
+  - A conversation cannot be saved atomically with the application's own rows.
+- **Conflicts.** A record and the messages it adds are written in one transaction. A save over a
+  newer revision raises `ConversationConflict` and leaves neither behind.
+- **History.** A conversation's history is read in one recursive query.
+- **Deleting.** Deleting a conversation deletes the messages only it reaches. Messages a fork,
+  or its origin, still reaches stay until the last of them is deleted.
+  - A fork saved while its origin is being deleted can lose the messages it shares with it,
+    except on SQLite, where writes take turns. Don't fork a conversation you are deleting.
+- **Databases.** It runs on PostgreSQL, MySQL 8 and SQLite, through their async drivers.
+
+## Development
+
+```sh
+uv sync
+uv run ruff check && uv run ruff format --check && uv run basedpyright && uv run ty check && uv run pytest
+```
+
+## License
+
+MIT

xtr_ai_orm_conversation_store-6.6.0/README.md

@@ -0,0 +1,70 @@
+# xtr-ai-orm-conversation-store
+
+Agent conversations kept in two tables on an [xtr-orm](../xtr-orm) connection, for
+[xtr-ai](../xtr-ai).
+
+## Install
+
+```sh
+uv add "xtr-ai[orm]"
+```
+
+The `orm` extra installs this package.
+
+## Use
+
+`OrmConversationStore` is a pydantic-ai `ConversationStore`. Give it the connection's primary
+engine:
+
+```python
+from pydantic_ai.conversation import Conversation
+
+from xtr_ai_orm_conversation_store import OrmConversationStore
+
+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)
+```
+
+In an application, configure it in xtr-ai instead, as
+`conversation_stores={"default": OrmConversationStoreConfig(connection="default")}`, and inject
+`ConversationStore`. See xtr-ai's [Use in an application](../xtr-ai#use-in-an-application).
+
+## Tables
+
+| Table | Holds |
+|---|---|
+| `ai_conversation` | One row per conversation: where its history ends, usage, pending tool calls, scope, branches, fork origin, revision |
+| `ai_conversation_entry` | One row per message, pointing at the one before it; shared by a conversation and its forks |
+
+`table_prefix` changes `ai_`. `ConversationMappingDriver` adds the tables to a connection's
+definitions, so `orm:migrations:diff` writes them. xtr-ai registers it when the store is
+configured.
+
+## Behaviour
+
+- **Own transactions.** Every call runs in a short transaction of its own and commits before it
+  returns. A store never joins the caller's unit of work.
+  - A long model call holds no database connection.
+  - Rolling back the caller's work never undoes a saved turn.
+  - A conversation cannot be saved atomically with the application's own rows.
+- **Conflicts.** A record and the messages it adds are written in one transaction. A save over a
+  newer revision raises `ConversationConflict` and leaves neither behind.
+- **History.** A conversation's history is read in one recursive query.
+- **Deleting.** Deleting a conversation deletes the messages only it reaches. Messages a fork,
+  or its origin, still reaches stay until the last of them is deleted.
+  - A fork saved while its origin is being deleted can lose the messages it shares with it,
+    except on SQLite, where writes take turns. Don't fork a conversation you are deleting.
+- **Databases.** It runs on PostgreSQL, MySQL 8 and SQLite, through their async drivers.
+
+## Development
+
+```sh
+uv sync
+uv run ruff check && uv run ruff format --check && uv run basedpyright && uv run ty check && uv run pytest
+```
+
+## License
+
+MIT

xtr_ai_orm_conversation_store-6.6.0/pyproject.toml

@@ -0,0 +1,160 @@
+[project]
+name = "xtr-ai-orm-conversation-store"
+version = "6.6.0"
+description = "Agent conversations stored in a relational database through xtr-orm, for xtr-ai."
+readme = "README.md"
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = [
+    "ai",
+    "llm",
+    "agent",
+    "pydantic-ai",
+    "conversation",
+    "sqlalchemy",
+    "database",
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic-ai-slim>=2.66,<3",
+    "sqlalchemy[asyncio]>=2.0.41",
+    "typing-extensions>=4.12",
+    "xtr-ai>=6.0,<7",
+    "xtr-orm>=6.0,<7",
+]
+
+[[project.authors]]
+name = "Xterr"
+email = "me@xterr.dev"
+
+[dependency-groups]
+dev = [
+    "basedpyright>=1.21",
+    "ruff>=0.8",
+    "pytest>=8",
+    "pytest-cov>=5",
+    "anyio>=4.0",
+    "ty>=0.0.83",
+    "aiosqlite>=0.20",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.18,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.basedpyright]
+typeCheckingMode = "all"
+pythonVersion = "3.11"
+pythonPlatform = "All"
+include = [
+    "src",
+    "tests",
+]
+exclude = [
+    "**/__pycache__",
+    "**/.venv",
+    "**/build",
+    "**/dist",
+    ".tmp",
+]
+reportUnusedCallResult = "warning"
+reportUnnecessaryTypeIgnoreComment = "error"
+reportUnusedVariable = "error"
+reportMissingParameterType = "error"
+reportPrivateUsage = "error"
+reportImplicitStringConcatenation = "none"
+reportExplicitAny = "none"
+reportAny = "none"
+
+[[tool.basedpyright.executionEnvironments]]
+root = "tests"
+extraPaths = ["."]
+reportPrivateUsage = "none"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+src = [
+    "src",
+    "tests",
+]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "COM812",
+    "ISC001",
+    "D203",
+    "D213",
+    "CPY001",
+    "FBT001",
+    "FBT002",
+    "TD002",
+    "TD003",
+    "FIX002",
+    "TRY003",
+    "EM101",
+    "EM102",
+    "ANN401",
+]
+fixable = ["ALL"]
+unfixable = []
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+    "S101",
+    "ARG",
+    "PLR2004",
+    "SLF001",
+    "D",
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+docstring-code-format = true
+docstring-code-line-length = "dynamic"
+
+[tool.ty.src]
+include = [
+    "src",
+    "tests",
+]
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+addopts = [
+    "-ra",
+    "--strict-config",
+    "--strict-markers",
+]
+filterwarnings = [
+    "error",
+    "ignore:The declarative_mixin decorator:sqlalchemy.exc.SADeprecationWarning",
+]
+
+[tool.coverage.run]
+source = ["src"]
+branch = true
+
+[tool.coverage.report]
+fail_under = 95
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+]

xtr_ai_orm_conversation_store-6.6.0/pyproject.toml.orig

@@ -0,0 +1,137 @@
+[project]
+name = "xtr-ai-orm-conversation-store"
+version = "6.6.0"
+description = "Agent conversations stored in a relational database through xtr-orm, for xtr-ai."
+readme = "README.md"
+authors = [
+    { name = "Xterr", email = "me@xterr.dev" }
+]
+requires-python = ">=3.11"
+license = "MIT"
+license-files = ["LICENSE"]
+keywords = ["ai", "llm", "agent", "pydantic-ai", "conversation", "sqlalchemy", "database"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Framework :: AsyncIO",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = [
+    "pydantic-ai-slim>=2.66,<3",
+    "sqlalchemy[asyncio]>=2.0.41",
+    "typing-extensions>=4.12",
+    "xtr-ai>=6.0,<7",
+    "xtr-orm>=6.0,<7",
+]
+
+[dependency-groups]
+dev = [
+    "basedpyright>=1.21",
+    "ruff>=0.8",
+    "pytest>=8",
+    "pytest-cov>=5",
+    "anyio>=4.0",
+    "ty>=0.0.83",
+    # The store is tested against a real database: a SQLite file in the test's
+    # own directory, which needs an async driver for it.
+    "aiosqlite>=0.20",
+]
+
+[build-system]
+requires = ["uv_build>=0.9.18,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.basedpyright]
+typeCheckingMode = "all"
+pythonVersion = "3.11"
+pythonPlatform = "All"
+include = ["src", "tests"]
+exclude = ["**/__pycache__", "**/.venv", "**/build", "**/dist", ".tmp"]
+reportUnusedCallResult = "warning"
+reportUnnecessaryTypeIgnoreComment = "error"
+reportUnusedVariable = "error"
+reportMissingParameterType = "error"
+reportPrivateUsage = "error"
+reportImplicitStringConcatenation = "none"
+# SQLAlchemy's rows and pydantic-ai's generic types surface as Any.
+reportExplicitAny = "none"
+reportAny = "none"
+
+[[tool.basedpyright.executionEnvironments]]
+root = "tests"
+extraPaths = ["."]
+reportPrivateUsage = "none"
+
+[tool.ruff]
+target-version = "py311"
+line-length = 100
+src = ["src", "tests"]
+
+[tool.ruff.lint]
+select = ["ALL"]
+ignore = [
+    "COM812",
+    "ISC001",
+    "D203",
+    "D213",
+    "CPY001",
+    "FBT001",
+    "FBT002",
+    "TD002",
+    "TD003",
+    "FIX002",
+    "TRY003",
+    "EM101",
+    "EM102",
+    "ANN401",
+]
+fixable = ["ALL"]
+unfixable = []
+
+[tool.ruff.lint.per-file-ignores]
+"tests/**/*.py" = [
+    "S101",    # assert is the point of pytest
+    "ARG",     # fixtures look unused
+    "PLR2004", # magic numbers in test data
+    "SLF001",  # tests reach into privates
+    "D",       # test names are the docs
+]
+
+[tool.ruff.lint.pydocstyle]
+convention = "google"
+
+[tool.ruff.format]
+quote-style = "double"
+indent-style = "space"
+docstring-code-format = true
+docstring-code-line-length = "dynamic"
+
+[tool.ty.src]
+include = ["src", "tests"]
+
+[tool.pytest.ini_options]
+minversion = "8.0"
+testpaths = ["tests"]
+addopts = ["-ra", "--strict-config", "--strict-markers"]
+filterwarnings = [
+    "error",
+    # xtr-orm's database layer reaches advanced-alchemy, which still carries a decorator
+    # SQLAlchemy 2.1 retired; it warns once, on import, and changes nothing.
+    "ignore:The declarative_mixin decorator:sqlalchemy.exc.SADeprecationWarning",
+]
+
+[tool.coverage.run]
+source = ["src"]
+branch = true
+
+[tool.coverage.report]
+fail_under = 95
+exclude_lines = [
+    "pragma: no cover",
+    "if TYPE_CHECKING:",
+    "raise NotImplementedError",
+]

xtr_ai_orm_conversation_store-6.6.0/src/xtr_ai_orm_conversation_store/__init__.py

@@ -0,0 +1,20 @@
+"""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.
+"""
+
+from __future__ import annotations
+
+from .conversation_mapping_driver import ConversationMappingDriver
+from .conversation_tables import DEFAULT_TABLE_PREFIX, ConversationTables
+from .orm_conversation_store import OrmConversationStore
+
+__all__ = [
+    "DEFAULT_TABLE_PREFIX",
+    "ConversationMappingDriver",
+    "ConversationTables",
+    "OrmConversationStore",
+]

xtr_ai_orm_conversation_store-6.6.0/src/xtr_ai_orm_conversation_store/_rows.py

@@ -0,0 +1,89 @@
+"""Turning records and entries into rows and back."""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+from typing import TYPE_CHECKING, Any, Final, Literal, cast
+
+import pydantic
+from pydantic_ai import DeferredToolRequests
+from pydantic_ai.conversation_store import ConversationEntry, ConversationRecord
+from pydantic_ai.messages import ModelMessage
+from pydantic_ai.usage import RunUsage
+
+if TYPE_CHECKING:
+    from sqlalchemy import Row
+
+__all__ = ["entry_from_row", "entry_row", "record_from_row", "record_row"]
+
+# Bytes travel as base64 in both directions, as pydantic-ai's own message adapter does.
+_JSON: Final = pydantic.ConfigDict(ser_json_bytes="base64", val_json_bytes="base64")
+_MESSAGE: Final = pydantic.TypeAdapter[ModelMessage](ModelMessage, config=_JSON)
+_USAGE: Final = pydantic.TypeAdapter(RunUsage)
+_DEFERRED: Final = pydantic.TypeAdapter(DeferredToolRequests)
+_BRANCHES: Final = pydantic.TypeAdapter(list[str])
+
+
+def record_row(record: ConversationRecord) -> dict[str, Any]:
+    """The ``conversation`` row holding ``record``."""
+    deferred = record.deferred_tool_requests
+    return {
+        "conversation_id": record.conversation_id,
+        "head_id": record.head_id,
+        "scope": record.scope,
+        "usage": _USAGE.dump_json(record.usage).decode(),
+        "deferred_tool_requests": _DEFERRED.dump_json(deferred).decode() if deferred else None,
+        "forked_from": record.forked_from,
+        "forked_at": record.forked_at,
+        "branches": _BRANCHES.dump_json(record.branches).decode(),
+        "revision": record.revision,
+        "updated_at": _naive_utc(record.updated_at),
+        "format_version": record.format_version,
+    }
+
+
+def record_from_row(row: Row[Any]) -> ConversationRecord:
+    """The record a ``conversation`` row holds."""
+    deferred = cast("str | None", row.deferred_tool_requests)
+    updated_at = cast("datetime", row.updated_at)
+    return ConversationRecord(
+        conversation_id=cast("str", row.conversation_id),
+        head_id=cast("str | None", row.head_id),
+        usage=_USAGE.validate_json(cast("str", row.usage)),
+        deferred_tool_requests=_DEFERRED.validate_json(deferred) if deferred else None,
+        scope=cast("str | None", row.scope),
+        forked_from=cast("str | None", row.forked_from),
+        forked_at=cast("str | None", row.forked_at),
+        branches=_BRANCHES.validate_json(cast("str", row.branches)),
+        revision=cast("str", row.revision),
+        updated_at=updated_at.replace(tzinfo=UTC),
+        format_version=cast("Literal[1]", row.format_version),
+    )
+
+
+def entry_row(entry: ConversationEntry) -> dict[str, Any]:
+    """The ``conversation_entry`` row holding ``entry``."""
+    return {
+        "id": entry.id,
+        "parent_id": entry.parent_id,
+        "kind": entry.kind,
+        "message": _MESSAGE.dump_json(entry.message).decode(),
+    }
+
+
+def entry_from_row(row: Row[Any]) -> ConversationEntry:
+    """The entry a ``conversation_entry`` row holds."""
+    return ConversationEntry(
+        id=cast("str", row.id),
+        parent_id=cast("str | None", row.parent_id),
+        message=_MESSAGE.validate_json(cast("str", row.message)),
+        kind=cast("Literal['message']", row.kind),
+    )
+
+
+def _naive_utc(instant: datetime) -> datetime:
+    """``instant``'s UTC wall clock without a zone, as a zone-less column keeps it everywhere."""
+    utc = instant.astimezone(UTC)
+    return datetime(  # noqa: DTZ001 — a zone-less column wants exactly a naive value
+        utc.year, utc.month, utc.day, utc.hour, utc.minute, utc.second, utc.microsecond
+    )

xtr_ai_orm_conversation_store-6.6.0/src/xtr_ai_orm_conversation_store/conversation_mapping_driver.py

@@ -0,0 +1,38 @@
+"""Adding the conversation tables to a connection's definitions."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from typing_extensions import override
+from xtr_orm import MappingDriverInterface
+
+from .conversation_tables import DEFAULT_TABLE_PREFIX, ConversationTables
+
+if TYPE_CHECKING:
+    from sqlalchemy import MetaData
+
+__all__ = ["ConversationMappingDriver"]
+
+
+@final
+class ConversationMappingDriver(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.
+    """
+
+    __slots__ = ("_table_prefix",)
+
+    def __init__(self, table_prefix: str = DEFAULT_TABLE_PREFIX) -> None:
+        """Add tables whose names start with ``table_prefix``."""
+        self._table_prefix = table_prefix
+
+    @override
+    def load_metadata(self, metadata: MetaData, /) -> tuple[str, ...]:
+        """Add the tables ``metadata`` lacks; return the names added, ``()`` the second time."""
+        known = set(metadata.tables)
+        _ = ConversationTables.define(metadata, self._table_prefix)
+        return tuple(name for name in metadata.tables if name not in known)

xtr_ai_orm_conversation_store-6.6.0/src/xtr_ai_orm_conversation_store/conversation_tables.py

@@ -0,0 +1,76 @@
+"""The two tables a conversation is stored in."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from typing import Final, final
+
+from sqlalchemy import Column, DateTime, Index, MetaData, SmallInteger, String, Table, Text
+from sqlalchemy.dialects.mysql import DATETIME, LONGTEXT
+
+__all__ = ["DEFAULT_TABLE_PREFIX", "ConversationTables"]
+
+DEFAULT_TABLE_PREFIX: Final = "ai_"
+"""What both table names start with unless told otherwise."""
+
+_ID: Final = 64
+_NAME: Final = 255
+
+# MySQL's TEXT holds 64 KB, less than one message carrying an image, and its DATETIME keeps
+# whole seconds, which leaves conversations saved in the same second unordered.
+_JSON: Final = Text().with_variant(LONGTEXT(), "mysql")
+_INSTANT: Final = DateTime(timezone=False).with_variant(DATETIME(fsp=6), "mysql")
+
+
+@final
+@dataclass(frozen=True, slots=True)
+class ConversationTables:
+    """``{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.
+    """
+
+    conversation: Table
+    entry: Table
+
+    @classmethod
+    def define(
+        cls, metadata: MetaData, table_prefix: str = DEFAULT_TABLE_PREFIX
+    ) -> ConversationTables:
+        """Return the tables in ``metadata``, adding them first where they are not there."""
+        conversation_name = f"{table_prefix}conversation"
+        entry_name = f"{table_prefix}conversation_entry"
+        conversation = metadata.tables.get(conversation_name)
+        if conversation is None:
+            conversation = Table(
+                conversation_name,
+                metadata,
+                Column("conversation_id", String(_NAME), primary_key=True),
+                Column("head_id", String(_ID), nullable=True),
+                Column("scope", String(_NAME), nullable=True),
+                Column("usage", _JSON, nullable=False),
+                Column("deferred_tool_requests", _JSON, nullable=True),
+                Column("forked_from", String(_NAME), nullable=True),
+                Column("forked_at", String(_ID), nullable=True),
+                Column("branches", _JSON, nullable=False),
+                Column("revision", String(_ID), nullable=False),
+                Column("updated_at", _INSTANT, nullable=False),
+                Column("format_version", SmallInteger, nullable=False),
+                Index(None, "scope", "updated_at"),
+                Index(None, "forked_from"),
+            )
+        entry = metadata.tables.get(entry_name)
+        if entry is None:
+            entry = Table(
+                entry_name,
+                metadata,
+                Column("id", String(_ID), primary_key=True),
+                Column("parent_id", String(_ID), nullable=True),
+                Column("kind", String(32), nullable=False),
+                Column("message", _JSON, nullable=False),
+                Index(None, "parent_id"),
+            )
+        return cls(conversation=conversation, entry=entry)

xtr_ai_orm_conversation_store-6.6.0/src/xtr_ai_orm_conversation_store/orm_conversation_store.py

@@ -0,0 +1,243 @@
+"""A pydantic-ai conversation store on two database tables."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, final
+
+from pydantic_ai.conversation_store import ConversationConflict, ConversationStore
+from sqlalchemy import MetaData, delete, func, insert, literal, or_, select, update
+from sqlalchemy.exc import IntegrityError
+from typing_extensions import override
+
+from ._rows import entry_from_row, entry_row, record_from_row, record_row
+from .conversation_tables import DEFAULT_TABLE_PREFIX, ConversationTables
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable, Sequence
+
+    from pydantic_ai.conversation_store import ConversationEntry, ConversationRecord
+    from sqlalchemy.ext.asyncio import AsyncConnection, AsyncEngine
+
+__all__ = ["OrmConversationStore"]
+
+
+@final
+class OrmConversationStore(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.
+
+    ```python
+    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)
+    ```
+    """
+
+    def __init__(self, engine: AsyncEngine, *, table_prefix: str = DEFAULT_TABLE_PREFIX) -> None:
+        """Store through ``engine``, in tables whose names start with ``table_prefix``."""
+        self._engine = engine
+        self._tables = ConversationTables.define(MetaData(), table_prefix)
+
+    @override
+    async def read_record(self, conversation_id: str) -> ConversationRecord | None:
+        conversation = self._tables.conversation
+        async with self._engine.connect() as connection:
+            row = (
+                await connection.execute(
+                    select(conversation).where(conversation.c.conversation_id == conversation_id)
+                )
+            ).first()
+        return record_from_row(row) if row is not None else None
+
+    @override
+    async def read_records(
+        self, *, scope: str | None = None, limit: int | None = None
+    ) -> Sequence[ConversationRecord]:
+        conversation = self._tables.conversation
+        query = select(conversation).order_by(
+            conversation.c.updated_at.desc(), conversation.c.conversation_id
+        )
+        if scope is not None:
+            query = query.where(conversation.c.scope == scope)
+        if limit is not None:
+            query = query.limit(limit)
+        async with self._engine.connect() as connection:
+            rows = (await connection.execute(query)).all()
+        return [record_from_row(row) for row in rows]
+
+    @override
+    async def write_record(
+        self,
+        record: ConversationRecord,
+        *,
+        new_entries: Sequence[ConversationEntry] = (),
+        expected_revision: str | None,
+    ) -> None:
+        conversation = self._tables.conversation
+        async with self._engine.begin() as connection:
+            if expected_revision is None:
+                try:
+                    _ = await connection.execute(insert(conversation).values(record_row(record)))
+                except IntegrityError:
+                    raise ConversationConflict(record.conversation_id) from None
+            else:
+                result = await connection.execute(
+                    update(conversation)
+                    .where(
+                        conversation.c.conversation_id == record.conversation_id,
+                        conversation.c.revision == expected_revision,
+                    )
+                    .values(record_row(record))
+                )
+                if result.rowcount != 1:
+                    raise ConversationConflict(record.conversation_id)
+            if new_entries:
+                _ = await connection.execute(
+                    insert(self._tables.entry), [entry_row(entry) for entry in new_entries]
+                )
+            head = record.head_id
+            new_ids = {entry.id for entry in new_entries}
+            if (
+                head is not None
+                and head not in new_ids
+                and not await self._has_entry(connection, head)
+            ):
+                raise ConversationConflict(record.conversation_id)
+
+    @override
+    async def delete_record(self, conversation_id: str, *, expected_revision: str) -> None:
+        conversation = self._tables.conversation
+        async with self._engine.begin() as connection:
+            family = await self._fork_family(connection, conversation_id)
+            deleted = await connection.execute(
+                delete(conversation).where(
+                    conversation.c.conversation_id == conversation_id,
+                    conversation.c.revision == expected_revision,
+                )
+            )
+            if deleted.rowcount != 1:
+                raise ConversationConflict(conversation_id)
+            own = family.pop(conversation_id)
+            reached = await self._reachable(connection, own)
+            kept = await self._reachable(
+                connection, [tip for tips in family.values() for tip in tips]
+            )
+            released = sorted(reached - kept)
+            if released:
+                entry = self._tables.entry
+                _ = await connection.execute(delete(entry).where(entry.c.id.in_(released)))
+
+    @override
+    async def read_entry(self, entry_id: str) -> ConversationEntry:
+        entry = self._tables.entry
+        async with self._engine.connect() as connection:
+            row = (await connection.execute(select(entry).where(entry.c.id == entry_id))).first()
+        if row is None:
+            raise KeyError(entry_id)
+        return entry_from_row(row)
+
+    @override
+    async def read_history(
+        self, 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.
+        """
+        if head_id is None or limit == 0:
+            return []
+        entry = self._tables.entry
+        walk = (select(entry, literal(1).label("depth")).where(entry.c.id == head_id)).cte(
+            "history", recursive=True
+        )
+        step = select(entry, (walk.c.depth + 1).label("depth")).join(
+            walk, entry.c.id == walk.c.parent_id
+        )
+        if limit is not None:
+            step = step.where(walk.c.depth < limit)
+        walk = walk.union_all(step)
+        async with self._engine.connect() as connection:
+            rows = (await connection.execute(select(walk).order_by(walk.c.depth.desc()))).all()
+        if not rows:
+            raise KeyError(head_id)
+        reached_limit = limit is not None and len(rows) >= limit
+        if rows[0].parent_id is not None and not reached_limit:
+            raise KeyError(rows[0].parent_id)
+        return [entry_from_row(row) for row in rows]
+
+    async def _has_entry(self, connection: AsyncConnection, entry_id: str) -> bool:
+        entry = self._tables.entry
+        found = await connection.scalar(
+            select(func.count()).select_from(entry).where(entry.c.id == entry_id)
+        )
+        return bool(found)
+
+    async def _fork_family(
+        self, connection: AsyncConnection, conversation_id: str
+    ) -> dict[str, list[str]]:
+        """Every conversation sharing entries with ``conversation_id``, with its histories' tips.
+
+        Entries are shared only by forking, so the family is everything linked
+        to the conversation by ``forked_from``, in either direction.
+        """
+        conversation = self._tables.conversation
+        family: dict[str, list[str]] = {}
+        explored: set[str] = set()
+        pending: set[str] = {conversation_id}
+        while pending:
+            rows = (
+                await connection.execute(
+                    select(conversation).where(
+                        or_(
+                            conversation.c.conversation_id.in_(pending),
+                            conversation.c.forked_from.in_(pending),
+                        )
+                    )
+                )
+            ).all()
+            explored |= pending
+            pending = set()
+            for row in rows:
+                record = record_from_row(row)
+                family[record.conversation_id] = _tips(record)
+                pending.add(record.conversation_id)
+                if record.forked_from is not None:
+                    pending.add(record.forked_from)
+            pending -= explored
+        return family
+
+    async def _reachable(self, connection: AsyncConnection, tips: Iterable[str]) -> set[str]:
+        """Every entry on the histories ending at ``tips``."""
+        starts = sorted(set(tips))
+        if not starts:
+            return set()
+        entry = self._tables.entry
+        walk = (select(entry.c.id, entry.c.parent_id).where(entry.c.id.in_(starts))).cte(
+            "reached", recursive=True
+        )
+        walk = walk.union(
+            select(entry.c.id, entry.c.parent_id).join(walk, entry.c.id == walk.c.parent_id)
+        )
+        rows = (await connection.execute(select(walk.c.id))).all()
+        return {row.id for row in rows}
+
+
+def _tips(record: ConversationRecord) -> list[str]:
+    """Where ``record``'s histories end: its head, the branches it left, and where it was forked."""
+    return [tip for tip in (record.head_id, *record.branches, record.forked_at) if tip is not None]