hindsight-api 0.0.13__py3-none-any.whl

hindsight_api/api/mcp.py

@@ -0,0 +1,157 @@
+"""Hindsight MCP Server implementation using FastMCP."""
+
+import json
+import logging
+import os
+
+from fastmcp import FastMCP
+from hindsight_api import MemoryEngine
+
+# Configure logging from HINDSIGHT_API_LOG_LEVEL environment variable
+_log_level_str = os.environ.get("HINDSIGHT_API_LOG_LEVEL", "info").lower()
+_log_level_map = {"critical": logging.CRITICAL, "error": logging.ERROR, "warning": logging.WARNING,
+                  "info": logging.INFO, "debug": logging.DEBUG, "trace": logging.DEBUG}
+logging.basicConfig(
+    level=_log_level_map.get(_log_level_str, logging.INFO),
+    format="%(asctime)s - %(levelname)s - %(name)s - %(message)s"
+)
+logger = logging.getLogger(__name__)
+
+
+def create_mcp_server(memory: MemoryEngine) -> FastMCP:
+    """
+    Create and configure the Hindsight MCP server.
+
+    Args:
+        memory: MemoryEngine instance (required)
+
+    Returns:
+        Configured FastMCP server instance
+    """
+    # Create FastMCP server
+    mcp = FastMCP("hindsight-mcp-server")
+
+    @mcp.tool()
+    async def hindsight_put(bank_id: str, content: str, context: str, explanation: str = "") -> str:
+        """
+        **CRITICAL: Store important user information to long-term memory.**
+
+        **⚠️ PER-USER TOOL - REQUIRES USER IDENTIFICATION:**
+        - This tool is STRICTLY per-user. Each user MUST have a unique `bank_id`.
+        - ONLY use this tool if you have a valid user identifier (user ID, email, session ID, etc.) to map to `bank_id`.
+        - DO NOT use this tool if you cannot identify the specific user.
+        - DO NOT share memories between different users - each user's memories are isolated by their `bank_id`.
+        - If you don't have a user identifier, DO NOT use this tool at all.
+
+        Use this tool PROACTIVELY whenever the user shares:
+        - Personal facts, preferences, or interests (e.g., "I love hiking", "I'm a vegetarian")
+        - Important events or milestones (e.g., "I got promoted", "My birthday is June 15")
+        - User history, experiences, or background (e.g., "I used to work at Google", "I studied CS at MIT")
+        - Decisions, opinions, or stated preferences (e.g., "I prefer Python over JavaScript")
+        - Goals, plans, or future intentions (e.g., "I'm planning to visit Japan next year")
+        - Relationships or people mentioned (e.g., "My manager Sarah", "My wife Alice")
+        - Work context, projects, or responsibilities
+        - Any other information the user would want remembered for future conversations
+
+        **When to use**: Immediately after user shares personal information. Don't ask permission - just store it naturally.
+
+        **Context guidelines**: Use descriptive contexts like "personal_preferences", "work_history", "family", "hobbies",
+        "career_goals", "project_details", etc. This helps organize and retrieve related memories later.
+
+        Args:
+            bank_id: **REQUIRED** - The unique, persistent identifier for this specific user (e.g., user_id, email, session_id).
+                     This MUST be consistent across all interactions with the same user.
+                     Example: "user_12345", "alice@example.com", "session_abc123"
+            content: The fact/memory to store (be specific and include relevant details)
+            context: Categorize the memory (e.g., 'personal_preferences', 'work_history', 'hobbies', 'family')
+            explanation: Optional explanation for why this memory is being stored
+        """
+        try:
+            # Log explanation if provided
+            if explanation:
+                pass  # Explanation provided
+
+            # Store memory using put_batch_async
+            await memory.put_batch_async(
+                bank_id=bank_id,
+                contents=[{"content": content, "context": context}]
+            )
+            return f"Fact stored successfully"
+        except Exception as e:
+            logger.error(f"Error storing fact: {e}", exc_info=True)
+            return f"Error: {str(e)}"
+
+    @mcp.tool()
+    async def hindsight_search(bank_id: str, query: str, max_tokens: int = 4096, explanation: str = "") -> str:
+        """
+        **CRITICAL: Search user's memory to provide personalized, context-aware responses.**
+
+        **⚠️ PER-USER TOOL - REQUIRES USER IDENTIFICATION:**
+        - This tool is STRICTLY per-user. Each user MUST have a unique `bank_id`.
+        - ONLY use this tool if you have a valid user identifier (user ID, email, session ID, etc.) to map to `bank_id`.
+        - DO NOT use this tool if you cannot identify the specific user.
+        - DO NOT search across multiple users - each user's memories are isolated by their `bank_id`.
+        - If you don't have a user identifier, DO NOT use this tool at all.
+
+        Use this tool PROACTIVELY at the start of conversations or when making recommendations to:
+        - Check user's preferences before making suggestions (e.g., "what foods does the user like?")
+        - Recall user's history to provide continuity (e.g., "what projects has the user worked on?")
+        - Remember user's goals and context (e.g., "what is the user trying to accomplish?")
+        - Avoid repeating information or asking questions you should already know
+        - Personalize responses based on user's background, interests, and past interactions
+        - Reference past conversations or events the user mentioned
+
+        **When to use**:
+        - Start of conversation: Search for relevant context about the user
+        - Before recommendations: Check user preferences and past experiences
+        - When user asks about something they may have mentioned before
+        - To provide continuity across conversations
+
+        **Search tips**: Use natural language queries like "user's programming language preferences",
+        "user's work experience", "user's dietary restrictions", "what does the user know about X?"
+
+        Args:
+            bank_id: **REQUIRED** - The unique, persistent identifier for this specific user (e.g., user_id, email, session_id).
+                     This MUST be consistent across all interactions with the same user.
+                     Example: "user_12345", "alice@example.com", "session_abc123"
+            query: Natural language search query to find relevant memories
+            max_tokens: Maximum tokens for search context (default: 4096)
+            explanation: Optional explanation for why this search is being performed
+        """
+        try:
+            # Log all parameters for debugging
+            logger.info(f"hindsight_search called with: query={query!r}, max_tokens={max_tokens}, explanation={explanation!r}")
+
+            # Log explanation if provided
+            if explanation:
+                pass  # Explanation provided
+
+            # Search using recall_async
+            from hindsight_api.engine.memory_engine import Budget
+            search_result = await memory.recall_async(
+                bank_id=bank_id,
+                query=query,
+                fact_type=["world", "bank", "opinion"],  # Search all fact types
+                max_tokens=max_tokens,
+                budget=Budget.LOW
+            )
+
+            # Convert results to dict format
+            results = [
+                {
+                    "id": fact.id,
+                    "text": fact.text,
+                    "type": fact.fact_type,
+                    "context": fact.context,
+                    "event_date": fact.event_date,  # Already a string from the database
+                    "document_id": fact.document_id
+                }
+                for fact in search_result.results
+            ]
+
+            return json.dumps({"results": results}, indent=2)
+        except Exception as e:
+            logger.error(f"Error searching: {e}", exc_info=True)
+            return json.dumps({"error": str(e), "results": []})
+
+    return mcp

hindsight_api/engine/__init__.py

@@ -0,0 +1,47 @@
+"""
+Memory Engine - Core implementation of the memory system.
+
+This package contains all the implementation details of the memory engine:
+- MemoryEngine: Main class for memory operations
+- Utility modules: embedding_utils, link_utils, think_utils, bank_utils
+- Supporting modules: embeddings, cross_encoder, entity_resolver, etc.
+"""
+
+from .memory_engine import MemoryEngine
+from .db_utils import acquire_with_retry
+from .embeddings import Embeddings, SentenceTransformersEmbeddings
+from .search.trace import (
+    SearchTrace,
+    QueryInfo,
+    EntryPoint,
+    NodeVisit,
+    WeightComponents,
+    LinkInfo,
+    PruningDecision,
+    SearchSummary,
+    SearchPhaseMetrics,
+)
+from .search.tracer import SearchTracer
+from .llm_wrapper import LLMConfig
+from .response_models import RecallResult, ReflectResult, MemoryFact
+
+__all__ = [
+    "MemoryEngine",
+    "acquire_with_retry",
+    "Embeddings",
+    "SentenceTransformersEmbeddings",
+    "SearchTrace",
+    "SearchTracer",
+    "QueryInfo",
+    "EntryPoint",
+    "NodeVisit",
+    "WeightComponents",
+    "LinkInfo",
+    "PruningDecision",
+    "SearchSummary",
+    "SearchPhaseMetrics",
+    "LLMConfig",
+    "RecallResult",
+    "ReflectResult",
+    "MemoryFact",
+]

hindsight_api/engine/cross_encoder.py

@@ -0,0 +1,97 @@
+"""
+Cross-encoder abstraction for reranking.
+
+Provides an interface for reranking with different backends.
+"""
+from abc import ABC, abstractmethod
+from typing import List, Tuple
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class CrossEncoderModel(ABC):
+    """
+    Abstract base class for cross-encoder reranking.
+
+    Cross-encoders take query-document pairs and return relevance scores.
+    """
+
+    @abstractmethod
+    def load(self) -> None:
+        """
+        Load the cross-encoder model.
+
+        This should be called during initialization to load the model
+        and avoid cold start latency on first predict() call.
+        """
+        pass
+
+    @abstractmethod
+    def predict(self, pairs: List[Tuple[str, str]]) -> List[float]:
+        """
+        Score query-document pairs for relevance.
+
+        Args:
+            pairs: List of (query, document) tuples to score
+
+        Returns:
+            List of relevance scores (higher = more relevant)
+        """
+        pass
+
+
+class SentenceTransformersCrossEncoder(CrossEncoderModel):
+    """
+    Cross-encoder implementation using SentenceTransformers.
+
+    Call load() during initialization to load the model and avoid cold starts.
+
+    Default model is cross-encoder/ms-marco-MiniLM-L-6-v2:
+    - Fast inference (~80ms for 100 pairs on CPU)
+    - Small model (80MB)
+    - Trained for passage re-ranking
+    """
+
+    def __init__(self, model_name: str = "cross-encoder/ms-marco-MiniLM-L-6-v2"):
+        """
+        Initialize SentenceTransformers cross-encoder.
+
+        Args:
+            model_name: Name of the CrossEncoder model to use.
+                       Default: cross-encoder/ms-marco-MiniLM-L-6-v2
+        """
+        self.model_name = model_name
+        self._model = None
+
+    def load(self) -> None:
+        """Load the cross-encoder model."""
+        if self._model is not None:
+            return
+
+        try:
+            from sentence_transformers import CrossEncoder
+        except ImportError:
+            raise ImportError(
+                "sentence-transformers is required for SentenceTransformersCrossEncoder. "
+                "Install it with: pip install sentence-transformers"
+            )
+
+        logger.info(f"Loading cross-encoder model: {self.model_name}...")
+        self._model = CrossEncoder(self.model_name)
+        logger.info("Cross-encoder model loaded")
+
+    def predict(self, pairs: List[Tuple[str, str]]) -> List[float]:
+        """
+        Score query-document pairs for relevance.
+
+        Args:
+            pairs: List of (query, document) tuples to score
+
+        Returns:
+            List of relevance scores (raw logits from the model)
+        """
+        if self._model is None:
+            self.load()
+        scores = self._model.predict(pairs, show_progress_bar=False)
+        return scores.tolist() if hasattr(scores, 'tolist') else list(scores)

hindsight_api/engine/db_utils.py

@@ -0,0 +1,93 @@
+"""
+Database utility functions for connection management with retry logic.
+"""
+import asyncio
+import logging
+from contextlib import asynccontextmanager
+import asyncpg
+
+logger = logging.getLogger(__name__)
+
+# Default retry configuration for database operations
+DEFAULT_MAX_RETRIES = 3
+DEFAULT_BASE_DELAY = 0.5  # seconds
+DEFAULT_MAX_DELAY = 5.0  # seconds
+
+# Exceptions that indicate transient connection issues worth retrying
+RETRYABLE_EXCEPTIONS = (
+    asyncpg.exceptions.InterfaceError,
+    asyncpg.exceptions.ConnectionDoesNotExistError,
+    asyncpg.exceptions.TooManyConnectionsError,
+    OSError,
+    ConnectionError,
+    asyncio.TimeoutError,
+)
+
+
+async def retry_with_backoff(
+    func,
+    max_retries: int = DEFAULT_MAX_RETRIES,
+    base_delay: float = DEFAULT_BASE_DELAY,
+    max_delay: float = DEFAULT_MAX_DELAY,
+    retryable_exceptions: tuple = RETRYABLE_EXCEPTIONS,
+):
+    """
+    Execute an async function with exponential backoff retry.
+
+    Args:
+        func: Async function to execute
+        max_retries: Maximum number of retry attempts
+        base_delay: Initial delay between retries (seconds)
+        max_delay: Maximum delay between retries (seconds)
+        retryable_exceptions: Tuple of exception types to retry on
+
+    Returns:
+        Result of the function
+
+    Raises:
+        The last exception if all retries fail
+    """
+    last_exception = None
+    for attempt in range(max_retries + 1):
+        try:
+            return await func()
+        except retryable_exceptions as e:
+            last_exception = e
+            if attempt < max_retries:
+                delay = min(base_delay * (2 ** attempt), max_delay)
+                logger.warning(
+                    f"Database operation failed (attempt {attempt + 1}/{max_retries + 1}): {e}. "
+                    f"Retrying in {delay:.1f}s..."
+                )
+                await asyncio.sleep(delay)
+            else:
+                logger.error(
+                    f"Database operation failed after {max_retries + 1} attempts: {e}"
+                )
+    raise last_exception
+
+
+@asynccontextmanager
+async def acquire_with_retry(pool: asyncpg.Pool, max_retries: int = DEFAULT_MAX_RETRIES):
+    """
+    Async context manager to acquire a connection with retry logic.
+
+    Usage:
+        async with acquire_with_retry(pool) as conn:
+            await conn.execute(...)
+
+    Args:
+        pool: The asyncpg connection pool
+        max_retries: Maximum number of retry attempts
+
+    Yields:
+        An asyncpg connection
+    """
+    async def acquire():
+        return await pool.acquire()
+
+    conn = await retry_with_backoff(acquire, max_retries=max_retries)
+    try:
+        yield conn
+    finally:
+        await pool.release(conn)

hindsight_api/engine/embeddings.py

@@ -0,0 +1,113 @@
+"""
+Embeddings abstraction for the memory system.
+
+Provides an interface for generating embeddings with different backends.
+
+IMPORTANT: All embeddings must produce 384-dimensional vectors to match
+the database schema (pgvector column defined as vector(384)).
+"""
+from abc import ABC, abstractmethod
+from typing import List
+import logging
+
+logger = logging.getLogger(__name__)
+
+# Fixed embedding dimension required by database schema
+EMBEDDING_DIMENSION = 384
+
+
+class Embeddings(ABC):
+    """
+    Abstract base class for embedding generation.
+
+    All implementations MUST generate 384-dimensional embeddings to match
+    the database schema.
+    """
+
+    @abstractmethod
+    def load(self) -> None:
+        """
+        Load the embedding model.
+
+        This should be called during initialization to load the model
+        and avoid cold start latency on first encode() call.
+        """
+        pass
+
+    @abstractmethod
+    def encode(self, texts: List[str]) -> List[List[float]]:
+        """
+        Generate 384-dimensional embeddings for a list of texts.
+
+        Args:
+            texts: List of text strings to encode
+
+        Returns:
+            List of 384-dimensional embedding vectors (each is a list of floats)
+        """
+        pass
+
+
+class SentenceTransformersEmbeddings(Embeddings):
+    """
+    Embeddings implementation using SentenceTransformers.
+
+    Call load() during initialization to load the model and avoid cold starts.
+
+    Default model is BAAI/bge-small-en-v1.5 which produces 384-dimensional
+    embeddings matching the database schema.
+    """
+
+    def __init__(self, model_name: str = "BAAI/bge-small-en-v1.5"):
+        """
+        Initialize SentenceTransformers embeddings.
+
+        Args:
+            model_name: Name of the SentenceTransformer model to use.
+                       Must produce 384-dimensional embeddings.
+                       Default: BAAI/bge-small-en-v1.5
+        """
+        self.model_name = model_name
+        self._model = None
+
+    def load(self) -> None:
+        """Load the embedding model."""
+        if self._model is not None:
+            return
+
+        try:
+            from sentence_transformers import SentenceTransformer
+        except ImportError:
+            raise ImportError(
+                "sentence-transformers is required for SentenceTransformersEmbeddings. "
+                "Install it with: pip install sentence-transformers"
+            )
+
+        logger.info(f"Loading embedding model: {self.model_name}...")
+        self._model = SentenceTransformer(self.model_name)
+
+        # Validate dimension matches database schema
+        model_dim = self._model.get_sentence_embedding_dimension()
+        if model_dim != EMBEDDING_DIMENSION:
+            raise ValueError(
+                f"Model {self.model_name} produces {model_dim}-dimensional embeddings, "
+                f"but database schema requires {EMBEDDING_DIMENSION} dimensions. "
+                f"Use a model that produces {EMBEDDING_DIMENSION}-dimensional embeddings."
+            )
+
+        logger.info(f"Model loaded (embedding dim: {model_dim})")
+
+    def encode(self, texts: List[str]) -> List[List[float]]:
+        """
+        Generate 384-dimensional embeddings for a list of texts.
+
+        Args:
+            texts: List of text strings to encode
+
+        Returns:
+            List of 384-dimensional embedding vectors
+        """
+        if self._model is None:
+            self.load()
+        embeddings = self._model.encode(texts, convert_to_numpy=True, show_progress_bar=False)
+        return [emb.tolist() for emb in embeddings]