sqlspec 0.36.0__cp310-cp310-manylinux2014_aarch64.manylinux_2_17_aarch64.manylinux_2_28_aarch64.whl

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

sqlspec/extensions/adk/memory/converters.py

@@ -0,0 +1,149 @@
+"""Conversion functions for ADK memory records.
+
+Provides utilities for extracting searchable text from ADK Content objects
+and converting between ADK models and database records.
+"""
+
+import uuid
+from datetime import datetime, timezone
+from typing import TYPE_CHECKING, Any
+
+from sqlspec.extensions.adk.memory._types import MemoryRecord
+from sqlspec.utils.logging import get_logger
+
+if TYPE_CHECKING:
+    from google.adk.events.event import Event
+    from google.adk.memory.memory_entry import MemoryEntry
+    from google.adk.sessions import Session
+    from google.genai import types
+
+logger = get_logger("sqlspec.extensions.adk.memory.converters")
+
+__all__ = ("event_to_memory_record", "extract_content_text", "record_to_memory_entry", "session_to_memory_records")
+
+
+def extract_content_text(content: "types.Content") -> str:
+    """Extract plain text from ADK Content for search indexing.
+
+    Handles multi-modal Content.parts including text, function calls,
+    and other part types. Non-text parts are indexed by their type
+    for discoverability.
+
+    Args:
+        content: ADK Content object with parts list.
+
+    Returns:
+        Space-separated plain text extracted from all parts.
+    """
+    parts_text: list[str] = []
+
+    if not content.parts:
+        return ""
+
+    for part in content.parts:
+        if part.text:
+            parts_text.append(part.text)
+        elif part.function_call is not None:
+            parts_text.append(f"function:{part.function_call.name}")
+        elif part.function_response is not None:
+            parts_text.append(f"response:{part.function_response.name}")
+
+    return " ".join(parts_text)
+
+
+def event_to_memory_record(event: "Event", session_id: str, app_name: str, user_id: str) -> "MemoryRecord | None":
+    """Convert an ADK Event to a memory record.
+
+    Args:
+        event: ADK Event object.
+        session_id: ID of the parent session.
+        app_name: Name of the application.
+        user_id: ID of the user.
+
+    Returns:
+        MemoryRecord for database storage, or None if event has no content.
+    """
+    if event.content is None:
+        return None
+
+    content_text = extract_content_text(event.content)
+    if not content_text.strip():
+        return None
+
+    content_dict = event.content.model_dump(exclude_none=True, mode="json")
+
+    custom_metadata = event.custom_metadata or None
+
+    now = datetime.now(timezone.utc)
+
+    return MemoryRecord(
+        id=str(uuid.uuid4()),
+        session_id=session_id,
+        app_name=app_name,
+        user_id=user_id,
+        event_id=event.id,
+        author=event.author,
+        timestamp=datetime.fromtimestamp(event.timestamp, tz=timezone.utc),
+        content_json=content_dict,
+        content_text=content_text,
+        metadata_json=custom_metadata,
+        inserted_at=now,
+    )
+
+
+def session_to_memory_records(session: "Session") -> list["MemoryRecord"]:
+    """Convert a completed ADK Session to a list of memory records.
+
+    Extracts all events with content from the session and converts
+    them to memory records for storage.
+
+    Args:
+        session: ADK Session object with events.
+
+    Returns:
+        List of MemoryRecord objects for database storage.
+    """
+    records: list[MemoryRecord] = []
+
+    if not session.events:
+        return records
+
+    for event in session.events:
+        record = event_to_memory_record(
+            event=event, session_id=session.id, app_name=session.app_name, user_id=session.user_id
+        )
+        if record is not None:
+            records.append(record)
+
+    return records
+
+
+def record_to_memory_entry(record: "MemoryRecord") -> "MemoryEntry":
+    """Convert a database record to an ADK MemoryEntry.
+
+    Args:
+        record: Memory database record.
+
+    Returns:
+        ADK MemoryEntry object.
+    """
+    from google.adk.memory.memory_entry import MemoryEntry
+    from google.genai import types
+
+    content = types.Content.model_validate(record["content_json"])
+
+    timestamp_str = record["timestamp"].isoformat() if record["timestamp"] else None
+
+    return MemoryEntry(content=content, author=record["author"], timestamp=timestamp_str)
+
+
+def records_to_memory_entries(records: list["MemoryRecord"]) -> list["Any"]:
+    """Convert a list of database records to ADK MemoryEntry objects.
+
+    Args:
+        records: List of memory database records.
+
+    Returns:
+        List of ADK MemoryEntry objects.
+    """
+    return [record_to_memory_entry(record) for record in records]

sqlspec/extensions/adk/memory/service.py

@@ -0,0 +1,217 @@
+"""SQLSpec-backed memory service for Google ADK."""
+
+from typing import TYPE_CHECKING
+
+from google.adk.memory.base_memory_service import BaseMemoryService, SearchMemoryResponse
+
+from sqlspec.extensions.adk.memory.converters import records_to_memory_entries, session_to_memory_records
+from sqlspec.utils.logging import get_logger
+
+if TYPE_CHECKING:
+    from google.adk.memory.memory_entry import MemoryEntry
+    from google.adk.sessions import Session
+
+    from sqlspec.extensions.adk.memory.store import BaseAsyncADKMemoryStore, BaseSyncADKMemoryStore
+
+logger = get_logger("sqlspec.extensions.adk.memory.service")
+
+__all__ = ("SQLSpecMemoryService", "SQLSpecSyncMemoryService")
+
+
+class SQLSpecMemoryService(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
+
+    Args:
+        store: 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"
+        )
+    """
+
+    def __init__(self, store: "BaseAsyncADKMemoryStore") -> None:
+        """Initialize the memory service.
+
+        Args:
+            store: Database store implementation.
+        """
+        self._store = store
+
+    @property
+    def store(self) -> "BaseAsyncADKMemoryStore":
+        """Return the database store."""
+        return self._store
+
+    async def add_session_to_memory(self, session: "Session") -> None:
+        """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.
+
+        Args:
+            session: Completed ADK Session with events.
+
+        Notes:
+            - Events without content are skipped
+            - Duplicate event_ids are silently ignored (idempotent)
+            - Uses bulk insert for efficiency
+        """
+        records = session_to_memory_records(session)
+
+        if not records:
+            logger.debug(
+                "No content to store for session %s (app=%s, user=%s)", session.id, session.app_name, session.user_id
+            )
+            return
+
+        inserted_count = await self._store.insert_memory_entries(records)
+        logger.debug(
+            "Stored %d memory entries for session %s (total events: %d)", inserted_count, session.id, len(records)
+        )
+
+    async def search_memory(self, *, app_name: str, user_id: str, query: str) -> "SearchMemoryResponse":
+        """Search memory entries by text query.
+
+        Uses the store's configured search strategy (simple ILIKE or FTS).
+
+        Args:
+            app_name: Name of the application.
+            user_id: ID of the user.
+            query: Text query to search for.
+
+        Returns:
+            SearchMemoryResponse with memories: List[MemoryEntry].
+        """
+        records = await self._store.search_entries(query=query, app_name=app_name, user_id=user_id)
+
+        memories = records_to_memory_entries(records)
+
+        logger.debug("Found %d memories for query '%s' (app=%s, user=%s)", len(memories), query[:50], app_name, user_id)
+
+        return SearchMemoryResponse(memories=memories)
+
+
+class SQLSpecSyncMemoryService:
+    """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.
+
+    Args:
+        store: Sync database store implementation.
+
+    Example:
+        from sqlspec.adapters.sqlite import SqliteConfig
+        from sqlspec.adapters.sqlite.adk.store import SqliteADKMemoryStore
+        from sqlspec.extensions.adk.memory.service import SQLSpecSyncMemoryService
+
+        config = SqliteConfig(
+            connection_config={"database": "app.db"},
+            extension_config={
+                "adk": {
+                    "memory_table": "adk_memory_entries",
+                }
+            }
+        )
+        store = SqliteADKMemoryStore(config)
+        store.ensure_tables()
+
+        service = SQLSpecSyncMemoryService(store)
+        service.add_session_to_memory(completed_session)
+
+        memories = service.search_memory(
+            app_name="my_app",
+            user_id="user123",
+            query="Python discussion"
+        )
+    """
+
+    def __init__(self, store: "BaseSyncADKMemoryStore") -> None:
+        """Initialize the sync memory service.
+
+        Args:
+            store: Sync database store implementation.
+        """
+        self._store = store
+
+    @property
+    def store(self) -> "BaseSyncADKMemoryStore":
+        """Return the database store."""
+        return self._store
+
+    def add_session_to_memory(self, session: "Session") -> None:
+        """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.
+
+        Args:
+            session: Completed ADK Session with events.
+        """
+        records = session_to_memory_records(session)
+
+        if not records:
+            logger.debug(
+                "No content to store for session %s (app=%s, user=%s)", session.id, session.app_name, session.user_id
+            )
+            return
+
+        inserted_count = self._store.insert_memory_entries(records)
+        logger.debug(
+            "Stored %d memory entries for session %s (total events: %d)", inserted_count, session.id, len(records)
+        )
+
+    def search_memory(self, *, app_name: str, user_id: str, query: str) -> list["MemoryEntry"]:
+        """Search memory entries by text query.
+
+        Args:
+            app_name: Name of the application.
+            user_id: ID of the user.
+            query: Text query to search for.
+
+        Returns:
+            List of MemoryEntry objects.
+        """
+        records = self._store.search_entries(query=query, app_name=app_name, user_id=user_id)
+
+        memories = records_to_memory_entries(records)
+
+        logger.debug("Found %d memories for query '%s' (app=%s, user=%s)", len(memories), query[:50], app_name, user_id)
+
+        return memories