liveBook · Manning

Storage interface

As explained in Designing AI Systems

A storage interface is an abstract contract that defines operations for persisting and retrieving application data independently of a backend.

A storage interface defines the operations a service needs without tying its logic to a particular backend. A Session Service can validate requests and enforce business rules while delegating persistence to a configured implementation. Switching from PostgreSQL to Redis then need not change service logic or client code. section 4.3

In Python, SessionStorage uses an abstract base class to specify session and message operations. Its methods mirror the corresponding gRPC operations, including their parameters and return data. Each backend translates those calls into its own persistence operations. section 4.3.2

Listing 4.8 Abstract storage interface for session persistence
from abc import ABC, abstractmethod
from typing import List, Optional
from datetime import datetime
 
class SessionStorage(ABC):
    
    @abstractmethod
    def get_or_create_session(    
        self, 
        user_id: str, 
        session_id: Optional[str] = None
    ) -> Session:
        """Retrieve existing session or create new one."""
        pass
    
    @abstractmethod
    def list_sessions(
        self,
        user_id: str
    ) -> List[Session]:
        """Retrieve all sessions for a given user."""
        pass
    
    @abstractmethod
    def add_messages(    
        self, 
        session_id: str, 
        messages: List[Message]
    ) -> int:
        """Append messages to session. Returns count added."""
        pass
    
    @abstractmethod
    def get_messages(   
        self,
        session_id: str,
        limit: Optional[int] = None,
        offset: Optional[int] = None
    ) -> tuple[List[Message], int]:    #A
        """Retrieve messages with pagination. 
➥Returns messages and total count."""
        pass
    
    @abstractmethod
    def delete_session(self, session_id: str) -> bool:
        """Remove session and all its messages. Returns success."""
        pass

The abstract interface defines the session operations and their Python signatures. section 4.3.2

The contract separates responsibilities:

  • The service calls storage methods and works with returned session and message objects; it does not choose SQL queries or Redis commands. section 4.3 section 4.3.2
  • A backend implements the methods using its own data model and APIs. An in-memory implementation can use a Python dictionary to test service logic without a database. section 4.3.2
  • A new backend is added by implementing the contract rather than rewriting the service. Backend choice can change as workload needs change. section 4.3.2

PostgreSQL session storage

PostgresSessionStorage implements the abstract methods with psycopg2 and SQL. For get_or_create_session, it looks up a supplied session ID and returns the existing session if found; otherwise it creates one. An ON CONFLICT clause handles concurrent requests using the same session ID by updating the existing row rather than failing on a duplicate key. section 4.4.2

Listing 4.11 PostgreSQL storage implementation
import json
import uuid
from datetime import datetime
from typing import List, Optional, Tuple
import psycopg2    #A
from psycopg2.extras import RealDictCursor    #A
 
class PostgresSessionStorage(SessionStorage):
    
    def __init__(self, connection_string: str):    #B
        self.connection_string = 
➥connection_string    #B
        self.conn = psycopg2.connect(    #B
            connection_string,     #B
            cursor_factory=RealDictCursor    #C
        )    
    
    def get_or_create_session(
        self, 
        user_id: str, 
        session_id: Optional[str] = None
    ) -> Session:
        cursor = self.conn.cursor()    #D
        
        if session_id:    #E
            cursor.execute(    
                "SELECT * FROM sessions 
➥WHERE session_id = %s",    #F
                (session_id,)    
            )    
            row = cursor.fetchone()    
            if row:    #E
                return self._row_to_session(row)    
        
        new_session_id = session_id 
➥or str(uuid.uuid4())    #G
        now = datetime.utcnow()
        
        cursor.execute(
            """INSERT INTO sessions (session_id, user_id, created_at,
                updated_at)
            VALUES (%s, %s, %s, %s)
            ON CONFLICT (session_id)
                DO UPDATE SET updated_at = EXCLUDED.updated_at
            RETURNING *""",    #H
            (new_session_id, user_id, now, now)
        )
        self.conn.commit()    #I
        
        return self._row_to_session(cursor.fetchone())

The implementation connects through psycopg2 and begins translating the session contract into SQL. section 4.4.2

The contract can grow with the service. Memory methods save or update a value, retrieve one key or a user's memories, delete a key, and clear all memories for a user. An optional session ID supports session-scoped access; clearing user memory supports requests to be forgotten. PostgreSQL and Redis can implement these operations with different data structures while preserving the application-facing calls. section 4.6.3

Listing 4.20 Memory methods for SessionStorage interface
class SessionStorage(ABC):
    # ... existing methods from Listing 4.8: get_or_create_session,
    #     add_messages, get_messages, delete_session ...
    
    @abstractmethod
    def save_memory(
        self, 
        user_id: str,
        key: str, 
        value: Any,
        session_id: Optional[str] = None    #A
    ) -> bool:
        """Save a fact to memory.
        
        If the key exists for this user (and session, if scoped), 
        the value is updated. Returns True if successful.
        """
        pass
    
    @abstractmethod
    def get_memory(
        self, 
        user_id: str,
        key: Optional[str] = None,
        session_id: Optional[str] = None    #B
    ) -> Dict[str, Any]:
        """Retrieve memories for a user.
        
        If key is provided, returns {key: entry} or empty dict.
        If session_id is provided, filters to that session's memories.
        """
        pass
    
    @abstractmethod
    def delete_memory(
        self, 
        user_id: str,
        key: str,
        session_id: Optional[str] = None
    ) -> bool:
        """Remove a fact from memory. Returns True if key existed."""
        pass
    
    @abstractmethod
    def clear_user_memory(
        self, 
        user_id: str
    ) -> int:
        """Remove all memories for a user. 
➥Returns count deleted."""    #C
        pass
 

The memory extension shows user identifiers, keys, values, and optional session scope in the abstract methods. section 4.6.3

Vector storage contract

A vector store needs both ingestion and search operations. Its write interface inserts chunks with embeddings and deletes by document or index, returning counts for verification. Its search interface accepts a query embedding and optional filters and returns search results. Because deletion is destructive, a production implementation should check the caller's identity against the index owner. section 5.4.1

Listing 5.16 VectorStore abstract base class: write operations
class VectorStore(ABC):
 
    @abstractmethod
    def insert(
        self,
        index_name: str,
        document_id: str,
        chunks: List[Chunk],
        embeddings: List[List[float]],
        metadata: Dict[str, str]
    ) -> int:    #A
        """Insert chunks with embeddings. Returns count inserted."""
        pass
 
    @abstractmethod
    def delete_by_document(
        self, index_name: str, document_id: str
    ) -> int:    #B
        """Delete all chunks for a document. Returns count deleted."""
        pass
 
    @abstractmethod
    def delete_index
➥(self, index_name: str) -> int:    #C
        """Delete all data for an index. Returns count deleted."""
        pass

The write signatures show how index and document identifiers scope insertion and deletion. section 5.4.1

Listing 5.17 VectorStore abstract base class: search operation and result model
@dataclass
class SearchResult:
    chunk_id: str
    document_id: str
    text: str
    score: float    #A
    metadata: Dict[str, str]
 
class VectorStore(ABC):
    # ... write operations from Listing 5.16 ...
 
    @abstractmethod
    def search(
        self,
        index_name: str,
        query_embedding: List[float],
        top_k: int = 5,
        metadata_filters: Optional[Dict[str, str]] = None,
        score_threshold: Optional[float] = None
    ) -> List[SearchResult]:    #B
        """Find chunks most similar to the query embedding."""
        pass

The search signature and result model define the read side of the vector store contract. section 5.4.1

How Designing AI Systems covers it

How deep it goes
Defines abstract operations and works through a PostgreSQL implementation, then extends the contract to user memories.
Examples
Uses session creation, message history, user memories, and document-scoped vector insertion and deletion as interface examples.
What you can do after
Builds a storage interface and a PostgreSQL implementation for session persistence, with extensions for memory operations.
How it connects
Connects abstract base classes, gRPC operations, database backends, and vector search.

Related concepts

This explainer was generated by Manning's knowledge graph from the text of Designing AI Systems. The section links point to the parts of the book it draws on.