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) – Database store implementation (e.g., AsyncpgADKStore).

Example

from sqlspec.adapters.asyncpg import AsyncpgConfig from sqlspec.adapters.asyncpg.adk.store import AsyncpgADKStore from sqlspec.extensions.adk.service import SQLSpecSessionService

config = AsyncpgConfig(connection_config={“dsn”: “postgresql://…”}) store = AsyncpgADKStore(config) await store.ensure_tables()

service = SQLSpecSessionService(store) session = await service.create_session(

app_name=”my_app”, user_id=”user123”, state={“key”: “value”}

)

__init__(store)

Initialize the session service.

Parameters:

store (BaseAsyncADKStore) – Database store implementation.

property store: BaseAsyncADKStore

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 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.

Parameters:

• session (Session) – Session to append to.

• event (Event) – Event to append.

Return type:

Event

Returns:

The appended event.

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 (e.g., AsyncpgADKMemoryStore).

Example

from sqlspec.adapters.asyncpg import AsyncpgConfig from sqlspec.adapters.asyncpg.adk.store import AsyncpgADKMemoryStore from sqlspec.extensions.adk.memory.service import SQLSpecMemoryService

config = AsyncpgConfig(

connection_config={“dsn”: “postgresql://…”}, extension_config={

“adk”: {

“memory_table”: “adk_memory_entries”, “memory_use_fts”: True,

}

}

) store = AsyncpgADKMemoryStore(config) await store.ensure_tables()

service = SQLSpecMemoryService(store) await service.add_session_to_memory(completed_session)

response = await service.search_memory(

app_name=”my_app”, user_id=”user123”, query=”previous conversation about Python”

)

__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

Notes

• Events without content are skipped

• Duplicate event_ids are silently ignored (idempotent)

• Uses bulk insert for efficiency

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 with memories

Base 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_sessions”) - events_table: Events table name (default: “adk_events”) - 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_sessions”) - events_table: Events table name (default: “adk_events”) - owner_id_column: Optional owner FK column DDL (default: 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 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_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(session_id)

Get a session by ID.

Parameters:

session_id (str) – Session identifier.

Return type:

SessionRecord | None

Returns:

Session record if found, None otherwise.

abstractmethod async update_session_state(session_id, state)

Update session state.

Parameters:

• 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(session_id)

Delete a session and its events.

Parameters:

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 get_events(session_id, after_timestamp=None, limit=None)

Get events for a session.

Parameters:

• 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 create_tables()

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

Return type:

None

async ensure_tables()

Create tables and emit a standardized log entry.

Return type:

None

class sqlspec.extensions.adk.BaseSyncADKStore

Bases: ABC, Generic[ConfigT]

Base class for sync SQLSpec-backed ADK session stores.

Implements storage operations for Google ADK sessions and events using SQLSpec database adapters with synchronous execution.

This abstract base class provides common functionality for sync 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/sqlite/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_sessions”) - events_table: Events table name (default: “adk_events”) - owner_id_column: Optional owner FK column DDL (default: None)

__init__(config)

Initialize the sync 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_sessions”) - events_table: Events table name (default: “adk_events”) - owner_id_column: Optional owner FK column DDL (default: 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 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_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 get_session(session_id)

Get a session by ID.

Parameters:

session_id (str) – Session identifier.

Return type:

SessionRecord | None

Returns:

Session record if found, None otherwise.

abstractmethod update_session_state(session_id, state)

Update session state.

Parameters:

• session_id (str) – Session identifier.

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

Return type:

None

abstractmethod 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 delete_session(session_id)

Delete a session and its events.

Parameters:

session_id (str) – Session identifier.

Return type:

None

abstractmethod create_event(event_id, session_id, app_name, user_id, author=None, actions=None, content=None, **kwargs)

Create a new event.

Parameters:

• event_id (str) – Unique event identifier.

• session_id (str) – Session identifier.

• app_name (str) – Application name.

• user_id (str) – User identifier.

• author (str | None) – Event author (user/assistant/system).

• actions (bytes | None) – Pickled actions object.

• content (dict[str, typing.Any] | None) – Event content (JSONB/JSON).

• **kwargs (Any) – Additional optional fields.

Return type:

EventRecord

Returns:

Created event record.

abstractmethod list_events(session_id)

List events for a session ordered by timestamp.

Parameters:

session_id (str) – Session identifier.

Return type:

list[EventRecord]

Returns:

List of event records ordered by timestamp ASC.

abstractmethod create_tables()

Create both sessions and events tables if they don’t exist.

Return type:

None

ensure_tables()

Create tables and emit a standardized log entry.

Return type:

None

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 (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”]: - memory_table: Memory table name (default: “adk_memory_entries”) - memory_use_fts: Enable full-text search when supported (default: False) - memory_max_results: Max search results (default: 20) - owner_id_column: Optional owner FK column DDL (default: None) - enable_memory: Whether memory is enabled (default: True)

__init__(config)

Initialize the ADK memory store.

Parameters:

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

Notes

Reads configuration from config.extension_config[“adk”]: - memory_table: Memory table name (default: “adk_memory_entries”) - memory_use_fts: Enable full-text search when supported (default: False) - memory_max_results: Max search results (default: 20) - owner_id_column: Optional owner FK column DDL (default: None) - enable_memory: Whether memory is enabled (default: True)

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 (e.g., sqlspec/adapters/sqlite/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”]: - memory_table: Memory table name (default: “adk_memory_entries”) - memory_use_fts: Enable full-text search when supported (default: False) - memory_max_results: Max search results (default: 20) - owner_id_column: Optional owner FK column DDL (default: None) - enable_memory: Whether memory is enabled (default: True)

__init__(config)

Initialize the sync ADK memory store.

Parameters:

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

Notes

Reads configuration from config.extension_config[“adk”]: - memory_table: Memory table name (default: “adk_memory_entries”) - memory_use_fts: Enable full-text search when supported (default: False) - memory_max_results: Max search results (default: 20) - owner_id_column: Optional owner FK column DDL (default: None) - enable_memory: Whether memory is enabled (default: True)

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.