sqlspec 0.47.0__cp314-cp314-win_amd64.whl

sqlspec/extensions/adk/artifact/store.py

@@ -0,0 +1,361 @@
+"""Base store classes for ADK artifact metadata backend (sync and async).
+
+These abstract base classes define the database operations needed to manage
+artifact version metadata.  Content storage is handled separately by
+``sqlspec/storage/`` backends; these stores only manage the relational
+metadata rows.
+
+Concrete subclasses implement the abstract methods with dialect-specific SQL.
+"""
+
+import logging
+import re
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING, Any, Final, Generic, TypeVar
+
+from sqlspec.extensions.adk._config_utils import _get_adk_artifact_store_config, _get_adk_config_from_extension
+from sqlspec.observability import resolve_db_system
+from sqlspec.utils.logging import get_logger, log_with_context
+
+if TYPE_CHECKING:
+    from sqlspec.config import DatabaseConfigProtocol
+    from sqlspec.extensions.adk.artifact._types import ArtifactRecord
+
+ConfigT = TypeVar("ConfigT", bound="DatabaseConfigProtocol[Any, Any, Any]")
+
+logger = get_logger("sqlspec.extensions.adk.artifact.store")
+
+__all__ = ("BaseAsyncADKArtifactStore", "BaseSyncADKArtifactStore")
+
+VALID_TABLE_NAME_PATTERN: Final = re.compile(r"^[a-zA-Z_][a-zA-Z0-9_]*$")
+MAX_TABLE_NAME_LENGTH: Final = 63
+
+
+def _validate_table_name(table_name: str) -> None:
+    """Validate table name for SQL safety.
+
+    Args:
+        table_name: Table name to validate.
+
+    Raises:
+        ValueError: If table name is invalid.
+    """
+    if not table_name:
+        msg = "Table name cannot be empty"
+        raise ValueError(msg)
+
+    if len(table_name) > MAX_TABLE_NAME_LENGTH:
+        msg = f"Table name too long: {len(table_name)} chars (max {MAX_TABLE_NAME_LENGTH})"
+        raise ValueError(msg)
+
+    if not VALID_TABLE_NAME_PATTERN.match(table_name):
+        msg = (
+            f"Invalid table name: {table_name!r}. "
+            "Must start with letter/underscore and contain only alphanumeric characters and underscores"
+        )
+        raise ValueError(msg)
+
+
+class BaseAsyncADKArtifactStore(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.
+
+    Args:
+        config: SQLSpec database configuration with extension_config["adk"] settings.
+
+    Notes:
+        Configuration is read from config.extension_config["adk"]:
+        - artifact_table: Artifact versions table name (default: "adk_artifact_versions")
+    """
+
+    __slots__ = ("_artifact_table", "_config")
+
+    def __init__(self, config: ConfigT) -> None:
+        """Initialize the async ADK artifact store.
+
+        Args:
+            config: SQLSpec database configuration.
+        """
+        self._config = config
+        store_config = _get_adk_artifact_store_config(self._config)
+        self._artifact_table: str = store_config["artifact_table"]
+        _validate_table_name(self._artifact_table)
+
+    def _get_adk_config(self) -> "dict[str, Any]":
+        """Extract ADK configuration from extension_config.
+
+        Returns:
+            Dict with ADK configuration values.
+        """
+        return _get_adk_config_from_extension(self._config)
+
+    @property
+    def config(self) -> ConfigT:
+        """Return the database configuration."""
+        return self._config
+
+    @property
+    def artifact_table(self) -> str:
+        """Return the artifact versions table name."""
+        return self._artifact_table
+
+    @abstractmethod
+    async def insert_artifact(self, record: "ArtifactRecord") -> None:
+        """Insert an artifact version metadata row.
+
+        Args:
+            record: Artifact metadata record to insert.
+        """
+
+    @abstractmethod
+    async def get_artifact(
+        self, app_name: str, user_id: str, filename: str, session_id: "str | None" = None, version: "int | None" = None
+    ) -> "ArtifactRecord | None":
+        """Get a specific artifact version's metadata.
+
+        When ``version`` is None, returns the latest version.
+
+        Args:
+            app_name: Application name.
+            user_id: User identifier.
+            filename: Artifact filename.
+            session_id: Session identifier (None for user-scoped).
+            version: Specific version number, or None for latest.
+
+        Returns:
+            Artifact record if found, None otherwise.
+        """
+
+    @abstractmethod
+    async def list_artifact_keys(self, app_name: str, user_id: str, session_id: "str | None" = None) -> "list[str]":
+        """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.
+
+        Args:
+            app_name: Application name.
+            user_id: User identifier.
+            session_id: Session identifier (None for user-scoped only).
+
+        Returns:
+            List of distinct artifact filenames.
+        """
+
+    @abstractmethod
+    async def list_artifact_versions(
+        self, app_name: str, user_id: str, filename: str, session_id: "str | None" = None
+    ) -> "list[ArtifactRecord]":
+        """List all version records for an artifact, ordered by version ascending.
+
+        Args:
+            app_name: Application name.
+            user_id: User identifier.
+            filename: Artifact filename.
+            session_id: Session identifier (None for user-scoped).
+
+        Returns:
+            List of artifact records ordered by version ascending.
+        """
+
+    @abstractmethod
+    async def delete_artifact(
+        self, app_name: str, user_id: str, filename: str, session_id: "str | None" = None
+    ) -> "list[ArtifactRecord]":
+        """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.
+
+        Args:
+            app_name: Application name.
+            user_id: User identifier.
+            filename: Artifact filename.
+            session_id: Session identifier (None for user-scoped).
+
+        Returns:
+            List of deleted artifact records (needed for content cleanup).
+        """
+
+    @abstractmethod
+    async def get_next_version(
+        self, app_name: str, user_id: str, filename: str, session_id: "str | None" = None
+    ) -> int:
+        """Get the next version number for an artifact.
+
+        Returns 0 if no versions exist (first version), otherwise
+        ``max(version) + 1``.
+
+        Args:
+            app_name: Application name.
+            user_id: User identifier.
+            filename: Artifact filename.
+            session_id: Session identifier (None for user-scoped).
+
+        Returns:
+            Next version number (0-based).
+        """
+
+    @abstractmethod
+    async def create_table(self) -> None:
+        """Create the artifact versions table if it does not exist."""
+
+    async def ensure_table(self) -> None:
+        """Create the artifact table and emit a standardized log entry."""
+        await self.create_table()
+        log_with_context(
+            logger,
+            logging.DEBUG,
+            "adk.artifact.table.ready",
+            db_system=resolve_db_system(type(self).__name__),
+            artifact_table=self._artifact_table,
+        )
+
+
+class BaseSyncADKArtifactStore(ABC, Generic[ConfigT]):
+    """Base class for sync SQLSpec-backed ADK artifact metadata stores.
+
+    Synchronous counterpart of :class:`BaseAsyncADKArtifactStore`.
+
+    Args:
+        config: SQLSpec database configuration with extension_config["adk"] settings.
+    """
+
+    __slots__ = ("_artifact_table", "_config")
+
+    def __init__(self, config: ConfigT) -> None:
+        """Initialize the sync ADK artifact store.
+
+        Args:
+            config: SQLSpec database configuration.
+        """
+        self._config = config
+        store_config = _get_adk_artifact_store_config(self._config)
+        self._artifact_table: str = store_config["artifact_table"]
+        _validate_table_name(self._artifact_table)
+
+    def _get_adk_config(self) -> "dict[str, Any]":
+        """Extract ADK configuration from extension_config.
+
+        Returns:
+            Dict with ADK configuration values.
+        """
+        return _get_adk_config_from_extension(self._config)
+
+    @property
+    def config(self) -> ConfigT:
+        """Return the database configuration."""
+        return self._config
+
+    @property
+    def artifact_table(self) -> str:
+        """Return the artifact versions table name."""
+        return self._artifact_table
+
+    @abstractmethod
+    def insert_artifact(self, record: "ArtifactRecord") -> None:
+        """Insert an artifact version metadata row.
+
+        Args:
+            record: Artifact metadata record to insert.
+        """
+
+    @abstractmethod
+    def get_artifact(
+        self, app_name: str, user_id: str, filename: str, session_id: "str | None" = None, version: "int | None" = None
+    ) -> "ArtifactRecord | None":
+        """Get a specific artifact version's metadata.
+
+        When ``version`` is None, returns the latest version.
+
+        Args:
+            app_name: Application name.
+            user_id: User identifier.
+            filename: Artifact filename.
+            session_id: Session identifier (None for user-scoped).
+            version: Specific version number, or None for latest.
+
+        Returns:
+            Artifact record if found, None otherwise.
+        """
+
+    @abstractmethod
+    def list_artifact_keys(self, app_name: str, user_id: str, session_id: "str | None" = None) -> "list[str]":
+        """List distinct artifact filenames.
+
+        Args:
+            app_name: Application name.
+            user_id: User identifier.
+            session_id: Session identifier (None for user-scoped only).
+
+        Returns:
+            List of distinct artifact filenames.
+        """
+
+    @abstractmethod
+    def list_artifact_versions(
+        self, app_name: str, user_id: str, filename: str, session_id: "str | None" = None
+    ) -> "list[ArtifactRecord]":
+        """List all version records for an artifact, ordered by version ascending.
+
+        Args:
+            app_name: Application name.
+            user_id: User identifier.
+            filename: Artifact filename.
+            session_id: Session identifier (None for user-scoped).
+
+        Returns:
+            List of artifact records ordered by version ascending.
+        """
+
+    @abstractmethod
+    def delete_artifact(
+        self, app_name: str, user_id: str, filename: str, session_id: "str | None" = None
+    ) -> "list[ArtifactRecord]":
+        """Delete all version records for an artifact and return them.
+
+        Args:
+            app_name: Application name.
+            user_id: User identifier.
+            filename: Artifact filename.
+            session_id: Session identifier (None for user-scoped).
+
+        Returns:
+            List of deleted artifact records (needed for content cleanup).
+        """
+
+    @abstractmethod
+    def get_next_version(self, app_name: str, user_id: str, filename: str, session_id: "str | None" = None) -> int:
+        """Get the next version number for an artifact.
+
+        Args:
+            app_name: Application name.
+            user_id: User identifier.
+            filename: Artifact filename.
+            session_id: Session identifier (None for user-scoped).
+
+        Returns:
+            Next version number (0-based).
+        """
+
+    @abstractmethod
+    def create_table(self) -> None:
+        """Create the artifact versions table if it does not exist."""
+
+    def ensure_table(self) -> None:
+        """Create the artifact table and emit a standardized log entry."""
+        self.create_table()
+        log_with_context(
+            logger,
+            logging.DEBUG,
+            "adk.artifact.table.ready",
+            db_system=resolve_db_system(type(self).__name__),
+            artifact_table=self._artifact_table,
+        )

sqlspec/extensions/adk/converters.py

@@ -0,0 +1,212 @@
+"""Conversion functions between ADK models and database records.
+
+Implements full-event JSON storage: the entire Event is serialized via
+``Event.model_dump_json(exclude_none=True)`` into a single ``event_json``
+column, with a small set of indexed scalar columns extracted alongside for
+query performance.  Reconstruction uses ``Event.model_validate_json()``.
+
+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.
+"""
+
+from datetime import datetime, timezone
+from typing import Any
+
+from google.adk.events.event import Event
+from google.adk.sessions import Session
+
+from sqlspec.extensions.adk._types import EventRecord, SessionRecord
+
+__all__ = (
+    "compute_update_marker",
+    "event_to_record",
+    "filter_temp_state",
+    "merge_scoped_state",
+    "record_to_event",
+    "record_to_session",
+    "session_to_record",
+    "split_scoped_state",
+)
+
+
+# ---------------------------------------------------------------------------
+# Session converters
+# ---------------------------------------------------------------------------
+
+
+def session_to_record(session: "Session") -> SessionRecord:
+    """Convert ADK Session to database record.
+
+    Args:
+        session: ADK Session object.
+
+    Returns:
+        SessionRecord for database storage.
+    """
+    return SessionRecord(
+        id=session.id,
+        app_name=session.app_name,
+        user_id=session.user_id,
+        state=filter_temp_state(session.state),
+        create_time=datetime.now(timezone.utc),
+        update_time=datetime.fromtimestamp(session.last_update_time, tz=timezone.utc),
+    )
+
+
+def compute_update_marker(update_time: "datetime") -> str:
+    """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.
+
+    Args:
+        update_time: The session's update timestamp.
+
+    Returns:
+        ISO 8601 string with microsecond precision.
+    """
+    if update_time.tzinfo is not None:
+        update_time = update_time.astimezone(timezone.utc)
+    return update_time.isoformat(timespec="microseconds")
+
+
+def record_to_session(record: SessionRecord, events: "list[EventRecord]") -> "Session":
+    """Convert database record to ADK Session.
+
+    Sets ``_storage_update_marker`` so the service layer can detect
+    concurrent modifications on subsequent ``append_event`` calls.
+
+    Args:
+        record: Session database record.
+        events: List of event records for this session.
+
+    Returns:
+        ADK Session object with storage marker set.
+    """
+    event_objects = [record_to_event(event_record) for event_record in events]
+
+    session = Session(
+        id=record["id"],
+        app_name=record["app_name"],
+        user_id=record["user_id"],
+        state=record["state"],
+        events=event_objects,
+        last_update_time=record["update_time"].timestamp(),
+    )
+    session._storage_update_marker = compute_update_marker(record["update_time"])
+    return session
+
+
+# ---------------------------------------------------------------------------
+# Event converters  (full-event JSON storage)
+# ---------------------------------------------------------------------------
+
+
+def event_to_record(event: "Event", session_id: str) -> EventRecord:
+    """Convert ADK Event to database record using full-event JSON storage.
+
+    The entire Event is serialized into ``event_json`` via Pydantic's
+    ``model_dump_json(exclude_none=True)``.  A small number of indexed scalar
+    columns are extracted alongside for query performance.
+
+    Args:
+        event: ADK Event object.
+        session_id: ID of the parent session.
+
+    Returns:
+        EventRecord for database storage.
+    """
+    return EventRecord(
+        session_id=session_id,
+        invocation_id=event.invocation_id,
+        author=event.author,
+        timestamp=datetime.fromtimestamp(event.timestamp, tz=timezone.utc),
+        event_json=event.model_dump(exclude_none=True, mode="json"),
+    )
+
+
+def record_to_event(record: "EventRecord") -> "Event":
+    """Convert database record to ADK Event.
+
+    Reconstruction is lossless: the full Event is restored from
+    ``event_json`` via ``Event.model_validate_json()``.
+
+    Args:
+        record: Event database record.
+
+    Returns:
+        ADK Event object.
+    """
+    return Event.model_validate(record["event_json"])
+
+
+# ---------------------------------------------------------------------------
+# Scoped-state helpers
+# ---------------------------------------------------------------------------
+
+
+def filter_temp_state(state: "dict[str, Any]") -> "dict[str, Any]":
+    """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.
+
+    Args:
+        state: ADK state dictionary (may contain ``temp:`` prefixed keys).
+
+    Returns:
+        A new dict without any ``temp:``-prefixed keys.
+    """
+    return {k: v for k, v in state.items() if not k.startswith("temp:")}
+
+
+def split_scoped_state(state: "dict[str, Any]") -> "tuple[dict[str, Any], dict[str, Any], dict[str, Any]]":
+    """Split state into app-scoped, user-scoped, and session-scoped buckets.
+
+    Args:
+        state: Full session state dict (temp: already stripped).
+
+    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
+    """
+    app_state: dict[str, Any] = {}
+    user_state: dict[str, Any] = {}
+    session_state: dict[str, Any] = {}
+    for k, v in state.items():
+        if k.startswith("app:"):
+            app_state[k] = v
+        elif k.startswith("user:"):
+            user_state[k] = v
+        else:
+            session_state[k] = v
+    return app_state, user_state, session_state
+
+
+def merge_scoped_state(
+    session_state: "dict[str, Any]",
+    app_state: "dict[str, Any] | None" = None,
+    user_state: "dict[str, Any] | None" = None,
+) -> "dict[str, Any]":
+    """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.
+
+    Args:
+        session_state: Per-session state.
+        app_state: App-scoped state (shared across sessions for same app).
+        user_state: User-scoped state (shared across sessions for same app+user).
+
+    Returns:
+        Merged state dict.
+    """
+    merged = dict(session_state)
+    if app_state:
+        merged.update(app_state)
+    if user_state:
+        merged.update(user_state)
+    return merged

sqlspec/extensions/adk/memory/__init__.py

@@ -0,0 +1,69 @@
+"""Google ADK memory backend extension for SQLSpec.
+
+Provides memory entry storage for Google Agent Development Kit using
+SQLSpec database adapters. Memory stores are used to persist conversational
+context across agent sessions for long-term recall.
+
+Public API exports:
+    - SQLSpecMemoryService: Main async service class implementing BaseMemoryService
+    - SQLSpecSyncMemoryService: Sync service for sync adapters
+    - BaseAsyncADKMemoryStore: Base class for async database store implementations
+    - BaseSyncADKMemoryStore: Base class for sync database store implementations
+    - MemoryRecord: TypedDict for memory database records
+    - extract_content_text: Helper to extract searchable text from Content
+    - session_to_memory_records: Convert Session to memory records
+    - record_to_memory_entry: Convert database record to MemoryEntry
+
+Example (async):
+    from sqlspec.adapters.asyncpg import AsyncpgConfig
+    from sqlspec.adapters.asyncpg.adk import AsyncpgADKMemoryStore
+    from sqlspec.extensions.adk.memory import SQLSpecMemoryService
+
+    config = AsyncpgConfig(
+        connection_config={"dsn": "postgresql://..."},
+        extension_config={
+            "adk": {
+                "memory_table": "adk_memory_entries",
+                "memory_use_fts": True,
+                "memory_max_results": 50,
+            }
+        }
+    )
+
+    store = AsyncpgADKMemoryStore(config)
+    await store.ensure_tables()
+
+    service = SQLSpecMemoryService(store)
+
+    # Store completed session as memories
+    await service.add_session_to_memory(completed_session)
+
+    # Search memories
+    response = await service.search_memory(
+        app_name="my_app",
+        user_id="user123",
+        query="previous discussion about Python"
+    )
+    for entry in response.memories:
+        print(entry.content)
+"""
+
+from sqlspec.extensions.adk.memory._types import MemoryRecord
+from sqlspec.extensions.adk.memory.converters import (
+    extract_content_text,
+    record_to_memory_entry,
+    session_to_memory_records,
+)
+from sqlspec.extensions.adk.memory.service import SQLSpecMemoryService, SQLSpecSyncMemoryService
+from sqlspec.extensions.adk.memory.store import BaseAsyncADKMemoryStore, BaseSyncADKMemoryStore
+
+__all__ = (
+    "BaseAsyncADKMemoryStore",
+    "BaseSyncADKMemoryStore",
+    "MemoryRecord",
+    "SQLSpecMemoryService",
+    "SQLSpecSyncMemoryService",
+    "extract_content_text",
+    "record_to_memory_entry",
+    "session_to_memory_records",
+)

sqlspec/extensions/adk/memory/_types.py

@@ -0,0 +1,30 @@
+"""Type definitions for ADK memory extension.
+
+These types define the database record structures for storing memory entries.
+They are separate from the Pydantic models to keep mypyc compilation working.
+"""
+
+from datetime import datetime
+from typing import Any, TypedDict
+
+__all__ = ("MemoryRecord",)
+
+
+class MemoryRecord(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.
+    """
+
+    id: str
+    session_id: str
+    app_name: str
+    user_id: str
+    event_id: str
+    author: "str | None"
+    timestamp: datetime
+    content_json: "dict[str, Any]"
+    content_text: str
+    metadata_json: "dict[str, Any] | None"
+    inserted_at: datetime