API

Services

class sqlspec.extensions.adk.SQLSpecSessionService

Bases: BaseSessionService

SQLSpec-backed implementation of BaseSessionService.

Provides session and event storage using SQLSpec database adapters. Delegates all database operations to a store implementation.

Parameters:

store (BaseAsyncADKStore | BaseSyncADKStore) -- Database store implementation.

__init__(store)

Initialize the session service.

Parameters:

store (BaseAsyncADKStore | BaseSyncADKStore) -- Database store implementation.

property store: BaseAsyncADKStore | BaseSyncADKStore

Return the database store.

async create_session(*, app_name, user_id, state=None, session_id=None)

Create a new session.

Parameters:

• app_name (str) -- Name of the application.

• user_id (str) -- ID of the user.

• state (dict[str, typing.Any] | None) -- Initial state of the session.

• session_id (str | None) -- Client-provided session ID. If None, generates a UUID.

Return type:

Session

Returns:

The newly created session.

async get_session(*, app_name, user_id, session_id, config=None)

Get a session by ID.

Parameters:

• app_name (str) -- Name of the application.

• user_id (str) -- ID of the user.

• session_id (str) -- Session identifier.

• config (GetSessionConfig | None) -- Configuration for retrieving events.

Return type:

Session | None

Returns:

Session object if found, None otherwise.

async get_user_state(*, app_name, user_id)

Get user-scoped state for an app and user.

ADK's service API returns unprefixed user state keys, while SQLSpec stores the durable state using ADK's documented user: prefix.

Parameters:

• app_name (str) -- Name of the application.

• user_id (str) -- ID of the user.

Return type:

dict[str, typing.Any]

Returns:

User-scoped state with user: prefixes removed.

async list_sessions(*, app_name, user_id=None)

List all sessions for an app, optionally filtered by user.

Parameters:

• app_name (str) -- Name of the application.

• user_id (str | None) -- ID of the user. If None, all sessions for the app are listed.

Return type:

ListSessionsResponse

Returns:

Response containing list of sessions (without events).

async delete_session(*, app_name, user_id, session_id)

Delete a session and all its events.

Parameters:

• app_name (str) -- Name of the application.

• user_id (str) -- ID of the user.

• session_id (str) -- Session identifier.

Return type:

None

async append_event(session, event)

Append an event to a session.

Persists the event record and the post-append durable state atomically via store.append_event_and_update_state(), then updates the in-memory session only after persistence succeeds.

Implements stale-session detection: if the session has been modified in storage since it was last loaded, a ValueError is raised instead of silently overwriting.

temp: keys are stripped from the persisted state snapshot so they never survive a reload.

Parameters:

• session (Session) -- Session to append to.

• event (Event) -- Event to append.

Return type:

Event

Returns:

The appended event.

Raises:

ValueError -- If the session has been modified in storage since it was loaded (stale session).

class sqlspec.extensions.adk.memory.SQLSpecMemoryService

Bases: BaseMemoryService

SQLSpec-backed implementation of BaseMemoryService.

Provides memory entry storage using SQLSpec database adapters. Delegates all database operations to a store implementation.

ADK BaseMemoryService defines two core methods:

• add_session_to_memory(session) - Ingests session into memory (returns void)

• search_memory(app_name, user_id, query) - Searches stored memories

Parameters:

store (BaseAsyncADKMemoryStore) -- Database store implementation.

__init__(store)

Initialize the memory service.

Parameters:

store (BaseAsyncADKMemoryStore) -- Database store implementation.

property store: BaseAsyncADKMemoryStore

Return the database store.

async add_session_to_memory(session)

Add a completed session to the memory store.

Extracts all events with content from the session and stores them as searchable memory entries. Uses UPSERT to skip duplicates.

The Session object contains app_name and user_id properties. Events are converted to memory records and bulk inserted via store. Returns void per ADK BaseMemoryService contract.

Parameters:

session (Session) -- Completed ADK Session with events.

Return type:

None

async add_events_to_memory(*, app_name, user_id, events, session_id=None, custom_metadata=None)

Add an explicit list of events to the memory service.

Same Event-to-MemoryRecord extraction logic as add_session_to_memory, but operates on a sequence of Events directly (no Session wrapper needed).

Parameters:

• app_name (str) -- The application name for memory scope.

• user_id (str) -- The user ID for memory scope.

• events (Sequence[Event]) -- The events to add to memory.

• session_id (str | None) -- Optional session ID for memory scope/partitioning. If None, memory entries are user-scoped only.

• custom_metadata (Mapping[str, object] | None) -- Optional portable metadata stored in MemoryRecord.metadata_json.

Return type:

None

async add_memory(*, app_name, user_id, memories, custom_metadata=None)

Add explicit memory items directly to the memory service.

Each entry's content is serialized to content_json, text is extracted from content.parts for content_text, and custom_metadata merges the entry-level entry.custom_metadata with the call-level custom_metadata parameter.

Parameters:

• app_name (str) -- The application name for memory scope.

• user_id (str) -- The user ID for memory scope.

• memories (Sequence[MemoryEntry]) -- Explicit memory items to add.

• custom_metadata (Mapping[str, object] | None) -- Optional portable metadata for memory writes. Merged with each entry's custom_metadata.

Return type:

None

async search_memory(*, app_name, user_id, query)

Search memory entries by text query.

Uses the store's configured search strategy (simple ILIKE or FTS).

Parameters:

• app_name (str) -- Name of the application.

• user_id (str) -- ID of the user.

• query (str) -- Text query to search for.

Returns:

List[MemoryEntry].

Return type:

SearchMemoryResponse

class sqlspec.extensions.adk.memory.SQLSpecSyncMemoryService

Bases: object

Synchronous SQLSpec-backed memory service.

Provides memory entry storage using SQLSpec sync database adapters. This is a sync-compatible version for use with sync drivers like SQLite.

Note: This does NOT inherit from BaseMemoryService since ADK's base class requires async methods. Use this for sync-only deployments.

Parameters:

store (BaseSyncADKMemoryStore) -- Sync database store implementation.

__init__(store)

Initialize the sync memory service.

Parameters:

store (BaseSyncADKMemoryStore) -- Sync database store implementation.

property store: BaseSyncADKMemoryStore

Return the database store.

add_session_to_memory(session)

Add a completed session to the memory store.

Extracts all events with content from the session and stores them as searchable memory entries. Uses UPSERT to skip duplicates.

Parameters:

session (Session) -- Completed ADK Session with events.

Return type:

None

search_memory(*, app_name, user_id, query)

Search memory entries by text query.

Parameters:

• app_name (str) -- Name of the application.

• user_id (str) -- ID of the user.

• query (str) -- Text query to search for.

Return type:

list[MemoryEntry]

Returns:

List of MemoryEntry objects.

class sqlspec.extensions.adk.SQLSpecArtifactService

Bases: BaseArtifactService

SQLSpec-backed implementation of BaseArtifactService.

Composes SQL metadata storage with sqlspec/storage/ content backends to provide versioned artifact management for Google ADK.

Metadata (version number, filename, MIME type, custom metadata, canonical URI) is stored in a SQL table managed by the artifact store. Content bytes are stored in object storage (S3, GCS, Azure, local filesystem) via the storage registry.

Parameters:

• store (BaseAsyncADKArtifactStore) -- Artifact metadata store implementation.

• artifact_storage_uri (str) -- Base URI for content storage. Can also be a registered alias in the storage registry.

• registry (StorageRegistry | None) -- Storage registry to use. Defaults to the global singleton.

__init__(store, artifact_storage_uri, registry=None)

property store: BaseAsyncADKArtifactStore

Return the artifact metadata store.

property artifact_storage_uri: str

Return the base URI for content storage.

async save_artifact(*, app_name, user_id, filename, artifact, session_id=None, custom_metadata=None)

Save an artifact, returning the new version number.

Writes content to object storage first, then inserts the metadata row. If content write succeeds but metadata insert fails, the orphaned content blob is logged but not automatically cleaned up (eventual consistency is acceptable; orphan sweep can be added later).

Parameters:

• app_name (str) -- Application name.

• user_id (str) -- User identifier.

• filename (str) -- Artifact filename.

• artifact (Part | dict[str, typing.Any]) -- ADK Part or dict to save.

• session_id (str | None) -- Session identifier (None for user-scoped).

• custom_metadata (dict[str, typing.Any] | None) -- Optional per-version metadata dict.

Return type:

int

Returns:

The version number (0-based, incrementing).

async load_artifact(*, app_name, user_id, filename, session_id=None, version=None)

Load an artifact by reading metadata then fetching content.

Parameters:

• app_name (str) -- Application name.

• user_id (str) -- User identifier.

• filename (str) -- Artifact filename.

• session_id (str | None) -- Session identifier (None for user-scoped).

• version (int | None) -- Specific version, or None for latest.

Return type:

Part | None

Returns:

Deserialized Part, or None if not found.

async list_artifact_keys(*, app_name, user_id, session_id=None)

List distinct artifact filenames.

When session_id is provided, returns both session-scoped and user-scoped filenames. When None, returns only user-scoped filenames.

Parameters:

• app_name (str) -- Application name.

• user_id (str) -- User identifier.

• session_id (str | None) -- Session identifier.

Return type:

list[str]

Returns:

List of artifact filenames.

async delete_artifact(*, app_name, user_id, filename, session_id=None)

Delete an artifact and all its versions.

Deletes metadata rows first (fail-fast), then removes content objects from storage (best-effort).

Parameters:

• app_name (str) -- Application name.

• user_id (str) -- User identifier.

• filename (str) -- Artifact filename.

• session_id (str | None) -- Session identifier (None for user-scoped).

Return type:

None

async list_versions(*, app_name, user_id, filename, session_id=None)

List all version numbers for an artifact.

Parameters:

• app_name (str) -- Application name.

• user_id (str) -- User identifier.

• filename (str) -- Artifact filename.

• session_id (str | None) -- Session identifier (None for user-scoped).

Return type:

list[int]

Returns:

Sorted list of version numbers.

async list_artifact_versions(*, app_name, user_id, filename, session_id=None)

List all versions with full metadata for an artifact.

Parameters:

• app_name (str) -- Application name.

• user_id (str) -- User identifier.

• filename (str) -- Artifact filename.

• session_id (str | None) -- Session identifier (None for user-scoped).

Return type:

list[ArtifactVersion]

Returns:

List of ArtifactVersion objects ordered by version ascending.

async get_artifact_version(*, app_name, user_id, filename, session_id=None, version=None)

Get metadata for a specific artifact version.

Parameters:

• app_name (str) -- Application name.

• user_id (str) -- User identifier.

• filename (str) -- Artifact filename.

• session_id (str | None) -- Session identifier (None for user-scoped).

• version (int | None) -- Version number, or None for latest.

Return type:

ArtifactVersion | None

Returns:

ArtifactVersion if found, None otherwise.

Session Stores

class sqlspec.extensions.adk.BaseAsyncADKStore

Bases: ABC, Generic[ConfigT]

Base class for async SQLSpec-backed ADK session stores.

Implements storage operations for Google ADK sessions and events using SQLSpec database adapters with async/await.

This abstract base class provides common functionality for all database-specific store implementations including: - Connection management via SQLSpec configs - Table name validation - Session and event CRUD operations

Subclasses must implement dialect-specific SQL queries and will be created in each adapter directory (e.g., sqlspec/adapters/asyncpg/adk/store.py).

Parameters:

config (TypeVar(ConfigT, bound= DatabaseConfigProtocol[Any, Any, Any])) -- SQLSpec database configuration with extension_config["adk"] settings.

Notes

Configuration is read from config.extension_config["adk"]: - session_table: Sessions table name (default: "adk_session") - events_table: Events table name (default: "adk_event") - app_state_table: App-scoped state table name (default: "adk_app_state") - user_state_table: User-scoped state table name (default: "adk_user_state") - metadata_table: Internal metadata table name (default: "adk_internal_metadata") - owner_id_column: Optional owner FK column DDL (default: None)

__init__(config)

Initialize the ADK store.

Parameters:

config (TypeVar(ConfigT, bound= DatabaseConfigProtocol[Any, Any, Any])) -- SQLSpec database configuration.

Notes

Reads configuration from config.extension_config["adk"]: - session_table: Sessions table name (default: "adk_session") - events_table: Events table name (default: "adk_event") - app_state_table: App-scoped state table name (default: "adk_app_state") - user_state_table: User-scoped state table name (default: "adk_user_state") - metadata_table: Internal metadata table name (default: "adk_internal_metadata") - owner_id_column: Optional owner FK column DDL (default: None)

async create_tables()

Create the sessions and events tables if they don't exist.

Return type:

None

async create_session(session_id, app_name, user_id, state, owner_id=None)

Create a new session.

Parameters:

• session_id (str) -- Unique identifier for the session.

• app_name (str) -- Name of the application.

• user_id (str) -- ID of the user.

• state (dict[str, typing.Any]) -- Session state dictionary.

• owner_id (Optional[typing.Any]) -- Optional owner ID value for owner_id_column (if configured).

Return type:

SessionRecord

Returns:

The created session record.

abstractmethod async get_session(app_name, user_id, session_id, *, renew_for=None)

Get a session.

Parameters:

• app_name (str) -- Name of the application.

• user_id (str) -- ID of the user.

• session_id (str) -- Session identifier.

• renew_for (int | timedelta | None) -- If positive, touch the session update timestamp while reading.

Return type:

SessionRecord | None

Returns:

Session record if found, None otherwise.

abstractmethod async update_session_state(app_name, user_id, session_id, state)

Update session state.

Parameters:

• app_name (str) -- Name of the application.

• user_id (str) -- ID of the user.

• session_id (str) -- Session identifier.

• state (dict[str, typing.Any]) -- New state dictionary.

Return type:

None

abstractmethod async list_sessions(app_name, user_id=None)

List all sessions for an app, optionally filtered by user.

Parameters:

• app_name (str) -- Name of the application.

• user_id (str | None) -- ID of the user. If None, returns all sessions for the app.

Return type:

list[SessionRecord]

Returns:

List of session records.

abstractmethod async delete_session(app_name, user_id, session_id)

Delete a session and its events.

Parameters:

• app_name (str) -- Name of the application.

• user_id (str) -- ID of the user.

• session_id (str) -- Session identifier.

Return type:

None

abstractmethod async append_event(event_record)

Append an event to a session.

Parameters:

event_record (EventRecord) -- Event record to store.

Return type:

None

abstractmethod async append_event_and_update_state(event_record, app_name, user_id, session_id, state, *, app_state=None, user_state=None)

Atomically append an event and update the session's durable state.

This is the authoritative durable write boundary for post-creation session mutations. The event insert, session state update, and the optional scoped-state upserts must succeed together or fail together, and the updated session record is returned in the same round-trip so callers don't need a follow-up read.

When app_state is provided (non-None), it is a full merged app-scoped snapshot to replace/upsert for app_name. When user_state is provided, it is a full merged user-scoped snapshot to replace/upsert for (app_name, user_id). None means that scope was untouched by the event and must not be written.

Parameters:

• event_record (EventRecord) -- Event record to store.

• app_name (str) -- Application name for routing scoped-state upserts.

• user_id (str) -- User identifier for routing user-scoped upserts.

• session_id (str) -- Session identifier whose state should be updated.

• state (dict[str, typing.Any]) -- Post-append durable session-scoped state snapshot (temp: keys already stripped by the service layer).

• app_state (dict[str, typing.Any] | None) -- Full app-scoped state snapshot (app:* keys) to upsert atomically, or None when untouched.

• user_state (dict[str, typing.Any] | None) -- Full user-scoped state snapshot (user:* keys) to upsert atomically, or None when untouched.

Return type:

SessionRecord

Returns:

The updated SessionRecord reflecting the new state and update_time.

Raises:

ValueError -- If the session row no longer exists at update time (raced with delete_session).

abstractmethod async get_events(app_name, user_id, session_id, after_timestamp=None, limit=None)

Get events for a session.

Parameters:

• app_name (str) -- Name of the application.

• user_id (str) -- ID of the user.

• session_id (str) -- Session identifier.

• after_timestamp (datetime | None) -- Only return events after this time.

• limit (int | None) -- Maximum number of events to return.

Return type:

list[EventRecord]

Returns:

List of event records ordered by timestamp ascending.

abstractmethod async delete_expired_events(before)

Delete events older than the given timestamp.

Parameters:

before (datetime) -- Timestamp threshold; events with timestamp earlier than this value are deleted.

Return type:

int

Returns:

Number of event rows deleted.

abstractmethod async delete_idle_sessions(updated_before)

Delete sessions whose update_time predates the given threshold.

Parameters:

updated_before (datetime) -- Timestamp threshold; sessions updated earlier than this value are deleted.

Return type:

int

Returns:

Number of session rows deleted.

abstractmethod async get_app_state(app_name)

Return app-scoped state for an application.

Parameters:

app_name (str) -- Application name.

Return type:

dict[str, typing.Any] | None

Returns:

App-scoped state mapping if present, otherwise None.

abstractmethod async get_user_state(app_name, user_id)

Return user-scoped state for an application user.

Parameters:

• app_name (str) -- Application name.

• user_id (str) -- User identifier.

Return type:

dict[str, typing.Any] | None

Returns:

User-scoped state mapping if present, otherwise None.

abstractmethod async upsert_app_state(app_name, state)

Insert or replace app-scoped state for an application.

Parameters:

• app_name (str) -- Application name.

• state (dict[str, typing.Any]) -- App-scoped state mapping.

Return type:

None

abstractmethod async upsert_user_state(app_name, user_id, state)

Insert or replace user-scoped state for an application user.

Parameters:

• app_name (str) -- Application name.

• user_id (str) -- User identifier.

• state (dict[str, typing.Any]) -- User-scoped state mapping.

Return type:

None

abstractmethod async get_metadata(key)

Return a value from the ADK internal metadata table.

Parameters:

key (str) -- Metadata key.

Return type:

str | None

Returns:

Metadata value if present, otherwise None.

abstractmethod async set_metadata(key, value)

Set a value in the ADK internal metadata table.

Parameters:

• key (str) -- Metadata key.

• value (str) -- Metadata value.

Return type:

None

property config: ConfigT

Return the database configuration.

property session_table: str

Return the sessions table name.

property events_table: str

Return the events table name.

property app_state_table: str

Return the app-scoped state table name.

property user_state_table: str

Return the user-scoped state table name.

property metadata_table: str

Return the ADK metadata table name.

property owner_id_column_ddl: str | None

Return the full owner ID column DDL (or None if not configured).

property owner_id_column_name: str | None

Return the owner ID column name only (or None if not configured).

async ensure_tables()

Create tables and emit a standardized log entry.

Return type:

None

async drop_tables()

Drop all ADK tables managed by this store in FK-safe order.

Return type:

None

async recreate_tables()

Drop and recreate all ADK tables managed by this store.

Return type:

None

class sqlspec.extensions.adk.BaseSyncADKStore

Bases: ABC, Generic[ConfigT]

Base class for sync SQLSpec-backed ADK session stores.

Sync-backed adapters expose a real synchronous API for direct use in synchronous applications. Async bridging belongs in SQLSpecSessionService when Google ADK calls into a sync store from its async service surface.

Parameters:

config (TypeVar(ConfigT, bound= DatabaseConfigProtocol[Any, Any, Any])) -- SQLSpec database configuration with extension_config["adk"] settings.

__init__(config)

Initialize the sync ADK store.

Parameters:

config (TypeVar(ConfigT, bound= DatabaseConfigProtocol[Any, Any, Any])) -- SQLSpec database configuration.

abstractmethod create_tables()

Create the sessions and events tables if they don't exist.

Return type:

None

abstractmethod create_session(session_id, app_name, user_id, state, owner_id=None)

Create a new session.

Return type:

SessionRecord

abstractmethod get_session(app_name, user_id, session_id, *, renew_for=None)

Get a session.

Return type:

SessionRecord | None

abstractmethod update_session_state(app_name, user_id, session_id, state)

Update session state.

Return type:

None

abstractmethod list_sessions(app_name, user_id=None)

List all sessions for an app, optionally filtered by user.

Return type:

list[SessionRecord]

abstractmethod delete_session(app_name, user_id, session_id)

Delete a session and its events.

Return type:

None

abstractmethod append_event(event_record)

Append an event to a session.

Return type:

None

abstractmethod append_event_and_update_state(event_record, app_name, user_id, session_id, state, *, app_state=None, user_state=None)

Atomically append an event and update the session's durable state.

Return type:

SessionRecord

abstractmethod get_events(app_name, user_id, session_id, after_timestamp=None, limit=None)

Get events for a session.

Return type:

list[EventRecord]

abstractmethod delete_expired_events(before)

Delete events older than the given timestamp.

Return type:

int

abstractmethod delete_idle_sessions(updated_before)

Delete sessions whose update_time predates the given threshold.

Return type:

int

abstractmethod get_app_state(app_name)

Return app-scoped state for an application.

Return type:

dict[str, typing.Any] | None

abstractmethod get_user_state(app_name, user_id)

Return user-scoped state for an application user.

Return type:

dict[str, typing.Any] | None

abstractmethod upsert_app_state(app_name, state)

Insert or replace app-scoped state for an application.

Return type:

None

abstractmethod upsert_user_state(app_name, user_id, state)

Insert or replace user-scoped state for an application user.

Return type:

None

abstractmethod get_metadata(key)

Return a value from the ADK internal metadata table.

Return type:

str | None

abstractmethod set_metadata(key, value)

Set a value in the ADK internal metadata table.

Return type:

None

property config: ConfigT

Return the database configuration.

property session_table: str

Return the sessions table name.

property events_table: str

Return the events table name.

property app_state_table: str

Return the app-scoped state table name.

property user_state_table: str

Return the user-scoped state table name.

property metadata_table: str

Return the ADK metadata table name.

property owner_id_column_ddl: str | None

Return the full owner ID column DDL (or None if not configured).

property owner_id_column_name: str | None

Return the owner ID column name only (or None if not configured).

ensure_tables()

Create tables and emit a standardized log entry.

Return type:

None

drop_tables()

Drop all ADK tables managed by this store in FK-safe order.

Return type:

None

recreate_tables()

Drop and recreate all ADK tables managed by this store.

Return type:

None

Memory Stores

class sqlspec.extensions.adk.BaseAsyncADKMemoryStore

Bases: ABC, Generic[ConfigT]

Base class for async SQLSpec-backed ADK memory stores.

Implements storage operations for Google ADK memory entries using SQLSpec database adapters with async/await.

This abstract base class provides common functionality for all database-specific memory store implementations including: - Connection management via SQLSpec configs - Table name validation - Memory entry CRUD operations - Text search with optional full-text search support

Subclasses must implement dialect-specific SQL queries and will be created in each adapter directory.

Parameters:

config (TypeVar(ConfigT, bound= DatabaseConfigProtocol[Any, Any, Any])) -- SQLSpec database configuration with extension_config["adk"] settings.

__init__(config)

Initialize the ADK memory store.

Parameters:

config (TypeVar(ConfigT, bound= DatabaseConfigProtocol[Any, Any, Any])) -- SQLSpec database configuration.

property config: ConfigT

Return the database configuration.

property memory_table: str

Return the memory table name.

property enabled: bool

Return whether memory store is enabled.

property use_fts: bool

Return whether full-text search is enabled.

property max_results: int

Return the max search results limit.

property owner_id_column_ddl: str | None

Return the full owner ID column DDL (or None if not configured).

property owner_id_column_name: str | None

Return the owner ID column name only (or None if not configured).

abstractmethod async create_tables()

Create the memory table and indexes if they don't exist.

Should check self._enabled and skip table creation if False.

Return type:

None

async ensure_tables()

Create tables when enabled and emit a standardized log entry.

Return type:

None

abstractmethod async insert_memory_entries(entries, owner_id=None)

Bulk insert memory entries with deduplication.

Uses UPSERT pattern to skip duplicates based on event_id.

Parameters:

• entries (list[MemoryRecord]) -- List of memory records to insert.

• owner_id (object | None) -- Optional owner ID value for owner_id_column (if configured).

Return type:

int

Returns:

Number of entries actually inserted (excludes duplicates).

Raises:

RuntimeError -- If memory store is disabled.

abstractmethod async search_entries(query, app_name, user_id, limit=None)

Search memory entries by text query.

Uses the configured search strategy (simple ILIKE or FTS).

Parameters:

• query (str) -- Text query to search for.

• app_name (str) -- Application name to filter by.

• user_id (str) -- User ID to filter by.

• limit (int | None) -- Maximum number of results (defaults to max_results config).

Return type:

list[MemoryRecord]

Returns:

List of matching memory records ordered by relevance/timestamp.

Raises:

RuntimeError -- If memory store is disabled.

abstractmethod async delete_entries_by_session(session_id)

Delete all memory entries for a specific session.

Parameters:

session_id (str) -- Session ID to delete entries for.

Return type:

int

Returns:

Number of entries deleted.

abstractmethod async delete_entries_older_than(days)

Delete memory entries older than specified days.

Used for TTL cleanup operations.

Parameters:

days (int) -- Number of days to retain entries.

Return type:

int

Returns:

Number of entries deleted.

class sqlspec.extensions.adk.BaseSyncADKMemoryStore

Bases: ABC, Generic[ConfigT]

Base class for sync SQLSpec-backed ADK memory stores.

Implements storage operations for Google ADK memory entries using SQLSpec database adapters with synchronous execution.

This abstract base class provides common functionality for sync database-specific memory store implementations including: - Connection management via SQLSpec configs - Table name validation - Memory entry CRUD operations - Text search with optional full-text search support

Subclasses must implement dialect-specific SQL queries and will be created in each adapter directory.

Parameters:

config (TypeVar(ConfigT, bound= DatabaseConfigProtocol[Any, Any, Any])) -- SQLSpec database configuration with extension_config["adk"] settings.

__init__(config)

Initialize the sync ADK memory store.

Parameters:

config (TypeVar(ConfigT, bound= DatabaseConfigProtocol[Any, Any, Any])) -- SQLSpec database configuration.

property config: ConfigT

Return the database configuration.

property memory_table: str

Return the memory table name.

property enabled: bool

Return whether memory store is enabled.

property use_fts: bool

Return whether full-text search is enabled.

property max_results: int

Return the max search results limit.

property owner_id_column_ddl: str | None

Return the full owner ID column DDL (or None if not configured).

property owner_id_column_name: str | None

Return the owner ID column name only (or None if not configured).

abstractmethod create_tables()

Create the memory table and indexes if they don't exist.

Should check self._enabled and skip table creation if False.

Return type:

None

ensure_tables()

Create tables when enabled and emit a standardized log entry.

Return type:

None

abstractmethod insert_memory_entries(entries, owner_id=None)

Bulk insert memory entries with deduplication.

Uses UPSERT pattern to skip duplicates based on event_id.

Parameters:

• entries (list[MemoryRecord]) -- List of memory records to insert.

• owner_id (object | None) -- Optional owner ID value for owner_id_column (if configured).

Return type:

int

Returns:

Number of entries actually inserted (excludes duplicates).

Raises:

RuntimeError -- If memory store is disabled.

abstractmethod search_entries(query, app_name, user_id, limit=None)

Search memory entries by text query.

Uses the configured search strategy (simple ILIKE or FTS).

Parameters:

• query (str) -- Text query to search for.

• app_name (str) -- Application name to filter by.

• user_id (str) -- User ID to filter by.

• limit (int | None) -- Maximum number of results (defaults to max_results config).

Return type:

list[MemoryRecord]

Returns:

List of matching memory records ordered by relevance/timestamp.

Raises:

RuntimeError -- If memory store is disabled.

abstractmethod delete_entries_by_session(session_id)

Delete all memory entries for a specific session.

Parameters:

session_id (str) -- Session ID to delete entries for.

Return type:

int

Returns:

Number of entries deleted.

abstractmethod delete_entries_older_than(days)

Delete memory entries older than specified days.

Used for TTL cleanup operations.

Parameters:

days (int) -- Number of days to retain entries.

Return type:

int

Returns:

Number of entries deleted.

Artifact Stores

class sqlspec.extensions.adk.BaseAsyncADKArtifactStore

Bases: ABC, Generic[ConfigT]

Base class for async SQLSpec-backed ADK artifact metadata stores.

Manages artifact version metadata in a SQL table. Content bytes are stored externally via sqlspec/storage/ backends and referenced by canonical URI in each metadata row.

Subclasses must implement dialect-specific SQL queries.

Parameters:

config (TypeVar(ConfigT, bound= DatabaseConfigProtocol[Any, Any, Any])) -- SQLSpec database configuration with extension_config["adk"] settings.

__init__(config)

Initialize the async ADK artifact store.

Parameters:

config (TypeVar(ConfigT, bound= DatabaseConfigProtocol[Any, Any, Any])) -- SQLSpec database configuration.

property config: ConfigT

Return the database configuration.

property artifact_table: str

Return the artifact versions table name.

abstractmethod async insert_artifact(record)

Insert an artifact version metadata row.

Parameters:

record (ArtifactRecord) -- Artifact metadata record to insert.

Return type:

None

abstractmethod async get_artifact(app_name, user_id, filename, session_id=None, version=None)

Get a specific artifact version's metadata.

When version is None, returns the latest version.

Parameters:

• app_name (str) -- Application name.

• user_id (str) -- User identifier.

• filename (str) -- Artifact filename.

• session_id (str | None) -- Session identifier (None for user-scoped).

• version (int | None) -- Specific version number, or None for latest.

Return type:

ArtifactRecord | None

Returns:

Artifact record if found, None otherwise.

abstractmethod async list_artifact_keys(app_name, user_id, session_id=None)

List distinct artifact filenames.

When session_id is provided, returns filenames from both session-scoped and user-scoped artifacts. When None, returns only user-scoped artifact filenames.

Parameters:

• app_name (str) -- Application name.

• user_id (str) -- User identifier.

• session_id (str | None) -- Session identifier (None for user-scoped only).

Return type:

list[str]

Returns:

List of distinct artifact filenames.

abstractmethod async list_artifact_versions(app_name, user_id, filename, session_id=None)

List all version records for an artifact, ordered by version ascending.

Parameters:

• app_name (str) -- Application name.

• user_id (str) -- User identifier.

• filename (str) -- Artifact filename.

• session_id (str | None) -- Session identifier (None for user-scoped).

Return type:

list[ArtifactRecord]

Returns:

List of artifact records ordered by version ascending.

abstractmethod async delete_artifact(app_name, user_id, filename, session_id=None)

Delete all version records for an artifact and return them.

The caller uses the returned records to clean up content from object storage. Metadata is deleted first (fail-fast); content cleanup is best-effort.

Parameters:

• app_name (str) -- Application name.

• user_id (str) -- User identifier.

• filename (str) -- Artifact filename.

• session_id (str | None) -- Session identifier (None for user-scoped).

Return type:

list[ArtifactRecord]

Returns:

List of deleted artifact records (needed for content cleanup).

abstractmethod async get_next_version(app_name, user_id, filename, session_id=None)

Get the next version number for an artifact.

Returns 0 if no versions exist (first version), otherwise max(version) + 1.

Parameters:

• app_name (str) -- Application name.

• user_id (str) -- User identifier.

• filename (str) -- Artifact filename.

• session_id (str | None) -- Session identifier (None for user-scoped).

Return type:

int

Returns:

Next version number (0-based).

abstractmethod async create_table()

Create the artifact versions table if it does not exist.

Return type:

None

async ensure_table()

Create the artifact table and emit a standardized log entry.

Return type:

None

class sqlspec.extensions.adk.BaseSyncADKArtifactStore

Bases: ABC, Generic[ConfigT]

Base class for sync SQLSpec-backed ADK artifact metadata stores.

Synchronous counterpart of BaseAsyncADKArtifactStore.

Parameters:

config (TypeVar(ConfigT, bound= DatabaseConfigProtocol[Any, Any, Any])) -- SQLSpec database configuration with extension_config["adk"] settings.

__init__(config)

Initialize the sync ADK artifact store.

Parameters:

config (TypeVar(ConfigT, bound= DatabaseConfigProtocol[Any, Any, Any])) -- SQLSpec database configuration.

property config: ConfigT

Return the database configuration.

property artifact_table: str

Return the artifact versions table name.

abstractmethod insert_artifact(record)

Insert an artifact version metadata row.

Parameters:

record (ArtifactRecord) -- Artifact metadata record to insert.

Return type:

None

abstractmethod get_artifact(app_name, user_id, filename, session_id=None, version=None)

Get a specific artifact version's metadata.

When version is None, returns the latest version.

Parameters:

• app_name (str) -- Application name.

• user_id (str) -- User identifier.

• filename (str) -- Artifact filename.

• session_id (str | None) -- Session identifier (None for user-scoped).

• version (int | None) -- Specific version number, or None for latest.

Return type:

ArtifactRecord | None

Returns:

Artifact record if found, None otherwise.

abstractmethod list_artifact_keys(app_name, user_id, session_id=None)

List distinct artifact filenames.

Parameters:

• app_name (str) -- Application name.

• user_id (str) -- User identifier.

• session_id (str | None) -- Session identifier (None for user-scoped only).

Return type:

list[str]

Returns:

List of distinct artifact filenames.

abstractmethod list_artifact_versions(app_name, user_id, filename, session_id=None)

List all version records for an artifact, ordered by version ascending.

Parameters:

• app_name (str) -- Application name.

• user_id (str) -- User identifier.

• filename (str) -- Artifact filename.

• session_id (str | None) -- Session identifier (None for user-scoped).

Return type:

list[ArtifactRecord]

Returns:

List of artifact records ordered by version ascending.

abstractmethod delete_artifact(app_name, user_id, filename, session_id=None)

Delete all version records for an artifact and return them.

Parameters:

• app_name (str) -- Application name.

• user_id (str) -- User identifier.

• filename (str) -- Artifact filename.

• session_id (str | None) -- Session identifier (None for user-scoped).

Return type:

list[ArtifactRecord]

Returns:

List of deleted artifact records (needed for content cleanup).

abstractmethod get_next_version(app_name, user_id, filename, session_id=None)

Get the next version number for an artifact.

Parameters:

• app_name (str) -- Application name.

• user_id (str) -- User identifier.

• filename (str) -- Artifact filename.

• session_id (str | None) -- Session identifier (None for user-scoped).

Return type:

int

Returns:

Next version number (0-based).

abstractmethod create_table()

Create the artifact versions table if it does not exist.

Return type:

None

ensure_table()

Create the artifact table and emit a standardized log entry.

Return type:

None

Record Types

class sqlspec.extensions.adk.SessionRecord

Bases: TypedDict

Database record for a session.

Represents the schema for sessions stored in the database.

class sqlspec.extensions.adk.EventRecord

Bases: TypedDict

Database record for an event.

Stores the full ADK Event as a single JSON blob (event_data) alongside indexed scalar columns used for scoped query filtering.

This design eliminates column drift with upstream ADK: new Event fields are automatically captured in event_data without schema changes.

class sqlspec.extensions.adk.MemoryRecord

Bases: TypedDict

Database record for a memory entry.

Represents the schema for memory entries stored in the database. Contains extracted content from ADK events for searchable long-term memory.

class sqlspec.extensions.adk.ArtifactRecord

Bases: TypedDict

Database record for an artifact version.

Represents the schema for artifact metadata stored in the database. Content is stored separately in object storage; this record tracks versioning, ownership, and the canonical URI pointing to the content.

The composite key is (app_name, user_id, session_id, filename, version), where session_id may be NULL for user-scoped artifacts.

Configuration

class sqlspec.extensions.adk.ADKConfig

Bases: TypedDict

Configuration options for ADK session and memory store extension.

All fields are optional with sensible defaults. Use in extension_config["adk"]:

Configuration supports three deployment scenarios:

1. SQLSpec manages everything (runtime + migrations)

2. SQLSpec runtime only (external migration tools like Alembic/Flyway)

3. Selective features (sessions OR memory, not both)

enable_sessions: NotRequired[bool]

True.

When False: session service unavailable, session store operations disabled. Independent of migration control - can use externally-managed tables.

Type:

Enable session store at runtime. Default

enable_memory: NotRequired[bool]

True.

When False: memory service unavailable, memory store operations disabled. Independent of migration control - can use externally-managed tables.

Type:

Enable memory store at runtime. Default

include_sessions_migration: NotRequired[bool]

True.

When False: session migration DDL skipped (use external migration tools). Decoupled from enable_sessions - allows external table management with SQLSpec runtime.

Type:

Include session tables in SQLSpec migrations. Default

include_memory_migration: NotRequired[bool]

True.

When False: memory migration DDL skipped (use external migration tools). Decoupled from enable_memory - allows external table management with SQLSpec runtime.

Type:

Include memory tables in SQLSpec migrations. Default

session_table: NotRequired[str]

'adk_session'

Type:

Name of the sessions table. Default

events_table: NotRequired[str]

'adk_event'

Type:

Name of the events table. Default

app_state_table: NotRequired[str]

'adk_app_state'

Type:

Name of the app-scoped state table. Default

user_state_table: NotRequired[str]

'adk_user_state'

Type:

Name of the user-scoped state table. Default

metadata_table: NotRequired[str]

'adk_internal_metadata'

Type:

Name of the internal metadata table. Default

memory_table: NotRequired[str]

'adk_memory'

Type:

Name of the memory entries table. Default

artifact_table: NotRequired[str]

'adk_artifact'

Type:

Name of the artifact metadata table. Default

artifact_storage_uri: NotRequired[str]

Base URI for artifact content storage.

Points to a sqlspec/storage/ backend where artifact binary content is stored. Can be a direct URI (s3://bucket/path, file:///path) or a registered alias in the storage registry.

memory_use_fts: NotRequired[bool]

False.

When True, adapters will use their native FTS capabilities where available: - PostgreSQL: to_tsvector/to_tsquery with GIN index - SQLite: FTS5 virtual table - DuckDB: FTS extension with match_bm25 - Oracle: CONTAINS() with CTXSYS.CONTEXT index - Spanner: TOKENIZE_FULLTEXT with search index - MySQL: MATCH...AGAINST with FULLTEXT index

When False, adapters use simple LIKE/ILIKE queries (works without indexes).

Type:

Enable full-text search when supported. Default

memory_max_results: NotRequired[int]

Limits the number of memory entries returned by search_memory(). Can be overridden per-query via the limit parameter.

Type:

Maximum number of results for memory search queries. Default

owner_id_column: NotRequired[str]

Optional owner ID column definition to link sessions/memories to a user, tenant, team, or other entity.

Format: "column_name TYPE [NOT NULL] REFERENCES table(column) [options...]"

The entire definition is passed through to DDL verbatim. We only parse the column name (first word) for use in INSERT/SELECT statements.

This column is added to both session and memory tables for consistent multi-tenant isolation.

Supports:

• Foreign key constraints: REFERENCES table(column)

• Nullable or NOT NULL

• CASCADE options: ON DELETE CASCADE, ON UPDATE CASCADE

• Dialect-specific options (DEFERRABLE, ENABLE VALIDATE, etc.)

• Plain columns without FK (just extra column storage)

Converters

Conversion functions between ADK models and database records.

Implements full-event JSON storage: the entire Event is serialized via Event.model_dump(exclude_none=True, mode="json") into a single event_data column, with a small set of indexed scalar columns extracted alongside for query performance. Reconstruction uses Event.model_validate().

Also provides scoped-state helpers that normalise ADK state prefixes (app:, user:, temp:) so the shared service layer can split, filter, and merge state before handing it to backend stores.

sqlspec.extensions.adk.converters.compute_update_marker(update_time)

Compute a stable revision marker from an update timestamp.

Uses the same format as ADK's StorageSession.get_update_marker(): ISO 8601 with microsecond precision, normalized to UTC.

Parameters:

update_time (datetime) -- The session's update timestamp.

Return type:

str

Returns:

ISO 8601 string with microsecond precision.

sqlspec.extensions.adk.converters.event_to_record(event, app_name, user_id, session_id)

Convert ADK Event to database record using full-event JSON storage.

The entire Event is serialized into event_data via Pydantic's model_dump(exclude_none=True, mode="json"). Indexed scalar columns are extracted alongside for scoped filtering.

Parameters:

• event (Event) -- ADK Event object.

• app_name (str) -- Name of the parent app.

• user_id (str) -- ID of the parent user.

• session_id (str) -- ID of the parent session.

Return type:

EventRecord

Returns:

EventRecord for database storage.

sqlspec.extensions.adk.converters.filter_temp_state(state)

Return a copy of state with all temp: keys removed.

temp: keys are process-local/session-runtime state and must never be written to persistent storage.

Parameters:

state (dict[str, typing.Any]) -- ADK state dictionary (may contain temp: prefixed keys).

Return type:

dict[str, typing.Any]

Returns:

A new dict without any temp:-prefixed keys.

sqlspec.extensions.adk.converters.merge_scoped_state(session_state, app_state=None, user_state=None)

Merge scoped state buckets into a single state dict.

Priority: session_state is base, app_state and user_state overlay. This matches ADK's documented merge semantics on session load.

Parameters:

• session_state (dict[str, typing.Any]) -- Per-session state.

• app_state (dict[str, typing.Any] | None) -- App-scoped state (shared across sessions for same app).

• user_state (dict[str, typing.Any] | None) -- User-scoped state (shared across sessions for same app+user).

Return type:

dict[str, typing.Any]

Returns:

Merged state dict.

sqlspec.extensions.adk.converters.record_to_event(record)

Convert database record to ADK Event.

Reconstruction is lossless for valid ADK payloads: the full Event is restored from event_data via Event.model_validate().

Parameters:

record (EventRecord) -- Event database record.

Return type:

Event

Returns:

ADK Event object.

sqlspec.extensions.adk.converters.record_to_session(record, events)

Convert database record to ADK Session.

Sets _storage_update_marker so the service layer can detect concurrent modifications on subsequent append_event calls.

Parameters:

• record (SessionRecord) -- Session database record.

• events (list[EventRecord]) -- List of event records for this session.

Return type:

Session

Returns:

ADK Session object with storage marker set.

sqlspec.extensions.adk.converters.session_to_record(session)

Convert ADK Session to database record.

Parameters:

session (Session) -- ADK Session object.

Return type:

SessionRecord

Returns:

SessionRecord for database storage.

sqlspec.extensions.adk.converters.split_scoped_state(state)

Split state into app-scoped, user-scoped, and session-scoped buckets.

Parameters:

state (dict[str, typing.Any]) -- Full session state dict (temp: already stripped).

Return type:

tuple[dict[str, typing.Any], dict[str, typing.Any], dict[str, typing.Any]]

Returns:

Tuple of (app_state, user_state, session_state). app_state: keys starting with "app:" user_state: keys starting with "user:" session_state: all other keys