Skip to content

ARCHITECTURE.md

Latest commit

 

History

History
195 lines (153 loc) · 8.21 KB

ARCHITECTURE.md

File metadata and controls

195 lines (153 loc) · 8.21 KB

Architecture Overview

This document explains the different service implementations and their purposes in the PgVector ADK Memory Service.

🏗️ Service Architecture

1. Core Service (service.py)

Purpose: Raw pgvector implementation with all database logic

class PgVectorMemoryService:
    """Core implementation with direct database operations"""
    
    async def add_memories_from_session(self, session) -> None:
        # Extracts and stores memories from session
    
    async def search_memory(self, app_name: str, user_id: str, query: str) -> SearchMemoryResponse:
        # Performs vector similarity search
    
    async def health_check(self) -> Dict[str, Any]:
        # Database health monitoring

Key Features:

  • Direct PostgreSQL + pgvector operations
  • Embedding generation and text chunking
  • Database connection pooling
  • Memory extraction from sessions
  • Vector similarity search

2. ADK Wrapper Service (adk_service.py)

Purpose: ADK-compatible interface wrapper

class PgVectorADKMemoryService:
    """Wrapper that provides ADK-compatible interface"""
    
    def __init__(self, config):
        self._pgvector_service = PgVectorMemoryService(config)  # Wraps core service
    
    async def add_session_to_memory(self, session) -> None:
        # ADK interface method - calls core service
        await self._pgvector_service.add_memories_from_session(session)
    
    async def search_memory(self, app_name: str, user_id: str, query: str) -> SearchMemoryResponse:
        # ADK interface method - calls core service
        return await self._pgvector_service.search_memory(app_name, user_id, query)

Key Features:

  • Provides ADK-compatible interface
  • Wraps core service functionality
  • Error handling and logging
  • Auto-initialization

3. BaseMemoryService Extension (adk_base_service.py)

Purpose: Direct extension of Google ADK's BaseMemoryService

try:
    from google.adk.memory.base_memory_service import BaseMemoryService
    
    class PgVectorADKMemoryService(BaseMemoryService):  # ✅ Direct extension!
        """Direct extension of Google ADK's BaseMemoryService"""
        
        def __init__(self, config):
            super().__init__()  # Call parent constructor
            self._pgvector_service = PgVectorMemoryService(config)
        
        async def add_session_to_memory(self, session) -> None:
            # Implements BaseMemoryService abstract method
            await self._pgvector_service.add_memories_from_session(session)
        
        async def search_memory(self, app_name: str, user_id: str, query: str) -> SearchMemoryResponse:
            # Implements BaseMemoryService abstract method
            return await self._pgvector_service.search_memory(app_name, user_id, query)

except ImportError:
    # Fallback to wrapper if Google ADK not available
    class PgVectorADKMemoryService(PgVectorBaseMemoryService):
        pass

Key Features:

  • Directly extends BaseMemoryService when Google ADK is available
  • Implements all required abstract methods
  • Follows exact same pattern as Google's Vertex AI service
  • Graceful fallback when Google ADK is not available

🔄 Service Relationships

┌─────────────────────────────────────────────────────────────┐
│                    User Application                         │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│              PgVectorADKMemoryService                       │
│  (adk_base_service.py - extends BaseMemoryService)         │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│              PgVectorMemoryService                          │
│                    (service.py)                             │
└─────────────────────┬───────────────────────────────────────┘
                      │
                      ▼
┌─────────────────────────────────────────────────────────────┐
│              PostgreSQL + pgvector                          │
│                    Database                                 │
└─────────────────────────────────────────────────────────────┘

📋 Usage Patterns

1. Direct ADK Usage (Recommended)

from pgvector_adk_memory import PgVectorADKMemoryService

# This automatically extends BaseMemoryService if Google ADK is available
service = PgVectorADKMemoryService(config)
await service.add_session_to_memory(session)
results = await service.search_memory("app", "user", "query")

2. Custom BaseMemoryService Extension

from google.adk.memory.base_memory_service import BaseMemoryService
from pgvector_adk_memory import PgVectorADKMemoryService

class MyCustomMemoryService(BaseMemoryService):
    def __init__(self):
        self._pgvector_service = PgVectorADKMemoryService()
    
    async def add_session_to_memory(self, session):
        await self._pgvector_service.add_session_to_memory(session)
    
    async def search_memory(self, app_name: str, user_id: str, query: str):
        return await self._pgvector_service.search_memory(app_name, user_id, query)

3. Direct Core Service Usage

from pgvector_adk_memory import PgVectorMemoryService

# Use core service directly for custom implementations
service = PgVectorMemoryService(config)
await service.add_memories_from_session(session)
results = await service.search_memory("app", "user", "query")

🔍 Key Differences Summary

Aspect service.py adk_service.py adk_base_service.py
Purpose Core implementation ADK wrapper Direct ADK extension
Extends Nothing Nothing BaseMemoryService
Dependencies PostgreSQL, pgvector Core service Core service + Google ADK
Interface Raw methods ADK-compatible ADK-compatible
Error Handling Basic Enhanced Enhanced
Auto-init Manual Yes Yes
Google ADK Independent Independent Direct extension

🎯 Why This Architecture?

1. Separation of Concerns

  • Core Service: Handles all database and vector operations
  • ADK Wrapper: Provides ADK-compatible interface
  • Base Extension: Direct Google ADK integration

2. Flexibility

  • Can use core service independently
  • Can use ADK wrapper without Google ADK
  • Can use direct extension with full Google ADK integration

3. Dependency Management

  • Core service has minimal dependencies
  • ADK integration is optional
  • Graceful fallbacks when dependencies are missing

4. Production Ready

  • Follows Google ADK patterns exactly
  • Comprehensive error handling
  • Proper resource management
  • Extensive testing

🚀 Recommendation

Use PgVectorADKMemoryService from adk_base_service.py - it provides the best of all worlds:

  • ✅ Directly extends BaseMemoryService when Google ADK is available
  • ✅ Graceful fallback when Google ADK is not available
  • ✅ Same interface regardless of availability
  • ✅ Follows Google's official patterns exactly