sqlspec 0.47.0__cp314-cp314-win_amd64.whl

sqlspec/extensions/adk/memory/converters.py

@@ -0,0 +1,225 @@
+"""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",
+    "memory_entry_to_record",
+    "record_to_memory_entry",
+    "records_to_memory_entries",
+    "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,
+    function responses, 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 memory_entry_to_record(
+    entry: "MemoryEntry", app_name: str, user_id: str, extra_metadata: "dict[str, Any] | None" = None
+) -> "MemoryRecord | None":
+    """Convert an ADK MemoryEntry to a database record.
+
+    Serializes the entry's ``content`` to ``content_json``, extracts text
+    from ``content.parts`` for ``content_text``, and merges entry-level
+    ``custom_metadata`` with the optional ``extra_metadata`` parameter.
+
+    Args:
+        entry: ADK MemoryEntry object.
+        app_name: Name of the application.
+        user_id: ID of the user.
+        extra_metadata: Optional call-level metadata to merge with the
+            entry's own ``custom_metadata``.
+
+    Returns:
+        MemoryRecord for database storage, or None if entry has no
+        indexable content.
+    """
+    content_text = extract_content_text(entry.content)
+    if not content_text.strip():
+        return None
+
+    content_dict = entry.content.model_dump(exclude_none=True, mode="json")
+
+    # Merge entry-level and call-level metadata
+    merged_metadata: dict[str, Any] | None = None
+    if entry.custom_metadata or extra_metadata:
+        merged_metadata = {}
+        if extra_metadata:
+            merged_metadata.update(extra_metadata)
+        if entry.custom_metadata:
+            merged_metadata.update(entry.custom_metadata)
+
+    now = datetime.now(timezone.utc)
+
+    # Parse timestamp from entry if available
+    timestamp = now
+    if entry.timestamp:
+        try:
+            timestamp = datetime.fromisoformat(entry.timestamp)
+        except (ValueError, TypeError):
+            timestamp = now
+
+    return MemoryRecord(
+        id=entry.id or str(uuid.uuid4()),
+        session_id="",
+        app_name=app_name,
+        user_id=user_id,
+        event_id="",
+        author=entry.author or "",
+        timestamp=timestamp,
+        content_json=content_dict,
+        content_text=content_text,
+        metadata_json=merged_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.
+
+    Preserves ``id`` and ``custom_metadata`` fields that were previously
+    dropped on readback.
+
+    Args:
+        record: Memory database record.
+
+    Returns:
+        ADK MemoryEntry object with all available fields populated.
+    """
+    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(
+        id=record["id"],
+        content=content,
+        author=record["author"],
+        timestamp=timestamp_str,
+        custom_metadata=record["metadata_json"] or {},
+    )
+
+
+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,316 @@
+"""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 (
+    memory_entry_to_record,
+    records_to_memory_entries,
+    session_to_memory_records,
+)
+from sqlspec.utils.logging import get_logger
+
+if TYPE_CHECKING:
+    from collections.abc import Mapping, Sequence
+
+    from google.adk.events.event import Event
+    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 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 add_events_to_memory(
+        self,
+        *,
+        app_name: str,
+        user_id: str,
+        events: "Sequence[Event]",
+        session_id: "str | None" = None,
+        custom_metadata: "Mapping[str, object] | None" = None,
+    ) -> 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).
+
+        Args:
+            app_name: The application name for memory scope.
+            user_id: The user ID for memory scope.
+            events: The events to add to memory.
+            session_id: Optional session ID for memory scope/partitioning.
+                If None, memory entries are user-scoped only.
+            custom_metadata: Optional portable metadata stored in
+                ``MemoryRecord.metadata_json``.
+        """
+        from sqlspec.extensions.adk.memory.converters import event_to_memory_record
+
+        metadata_dict = dict(custom_metadata) if custom_metadata else None
+        records = []
+        for event in events:
+            record = event_to_memory_record(
+                event=event, session_id=session_id or "", app_name=app_name, user_id=user_id
+            )
+            if record is not None:
+                if metadata_dict:
+                    record["metadata_json"] = metadata_dict
+                records.append(record)
+
+        if not records:
+            logger.debug(
+                "No content to store for events (app=%s, user=%s, count=%d)", app_name, user_id, len(list(events))
+            )
+            return
+
+        inserted_count = await self._store.insert_memory_entries(records)
+        logger.debug(
+            "Stored %d memory entries from %d events (app=%s, user=%s)", inserted_count, len(records), app_name, user_id
+        )
+
+    async def add_memory(
+        self,
+        *,
+        app_name: str,
+        user_id: str,
+        memories: "Sequence[MemoryEntry]",
+        custom_metadata: "Mapping[str, object] | None" = None,
+    ) -> 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.
+
+        Args:
+            app_name: The application name for memory scope.
+            user_id: The user ID for memory scope.
+            memories: Explicit memory items to add.
+            custom_metadata: Optional portable metadata for memory writes.
+                Merged with each entry's ``custom_metadata``.
+        """
+        call_metadata = dict(custom_metadata) if custom_metadata else {}
+        records = []
+        for entry in memories:
+            record = memory_entry_to_record(
+                entry=entry, app_name=app_name, user_id=user_id, extra_metadata=call_metadata
+            )
+            if record is not None:
+                records.append(record)
+
+        if not records:
+            logger.debug("No content to store for memories (app=%s, user=%s)", app_name, user_id)
+            return
+
+        inserted_count = await self._store.insert_memory_entries(records)
+        logger.debug(
+            "Stored %d memory entries from %d memories (app=%s, user=%s)",
+            inserted_count,
+            len(records),
+            app_name,
+            user_id,
+        )
+
+    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 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