hindsight-api 0.1.0__tar.gz → 0.1.2__tar.gz

{hindsight_api-0.1.0 → hindsight_api-0.1.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hindsight-api
-Version: 0.1.0
+Version: 0.1.2
 Summary: Temporal + Semantic + Entity Memory System for AI agents using PostgreSQL
 Requires-Python: >=3.11
 Requires-Dist: alembic>=1.17.1

{hindsight_api-0.1.0 → hindsight_api-0.1.2}/hindsight_api/__init__.py

@@ -16,11 +16,15 @@ from .engine.search.trace import (
     SearchPhaseMetrics,
 )
 from .engine.search.tracer import SearchTracer
-from .engine.embeddings import Embeddings, SentenceTransformersEmbeddings
+from .engine.embeddings import Embeddings, LocalSTEmbeddings, RemoteTEIEmbeddings
+from .engine.cross_encoder import CrossEncoderModel, LocalSTCrossEncoder, RemoteTEICrossEncoder
 from .engine.llm_wrapper import LLMConfig
+from .config import HindsightConfig, get_config
 
 __all__ = [
     "MemoryEngine",
+    "HindsightConfig",
+    "get_config",
     "SearchTrace",
     "SearchTracer",
     "QueryInfo",
@@ -32,7 +36,11 @@ __all__ = [
     "SearchSummary",
     "SearchPhaseMetrics",
     "Embeddings",
-    "SentenceTransformersEmbeddings",
+    "LocalSTEmbeddings",
+    "RemoteTEIEmbeddings",
+    "CrossEncoderModel",
+    "LocalSTCrossEncoder",
+    "RemoteTEICrossEncoder",
     "LLMConfig",
 ]
 __version__ = "0.1.0"

{hindsight_api-0.1.0 → hindsight_api-0.1.2}/hindsight_api/api/http.py

@@ -729,9 +729,11 @@ def create_app(memory: MemoryEngine, initialize_memory: bool = True) -> FastAPI:
         await memory.close()
         logging.info("Memory system closed")
 
+    from hindsight_api import __version__
+
     app = FastAPI(
         title="Hindsight HTTP API",
-        version="1.0.0",
+        version=__version__,
         description="HTTP API for Hindsight",
         contact={
             "name": "Memory System",
@@ -793,7 +795,8 @@ def _register_routes(app: FastAPI):
         response_model=GraphDataResponse,
         summary="Get memory graph data",
         description="Retrieve graph data for visualization, optionally filtered by type (world/experience/opinion). Limited to 1000 most recent items.",
-        operation_id="get_graph"
+        operation_id="get_graph",
+        tags=["Memory"]
     )
     async def api_graph(bank_id: str,
         type: Optional[str] = None
@@ -814,7 +817,8 @@ def _register_routes(app: FastAPI):
         response_model=ListMemoryUnitsResponse,
         summary="List memory units",
         description="List memory units with pagination and optional full-text search. Supports filtering by type. Results are sorted by most recent first (mentioned_at DESC, then created_at DESC).",
-        operation_id="list_memories"
+        operation_id="list_memories",
+        tags=["Memory"]
     )
     async def api_list(bank_id: str,
         type: Optional[str] = None,
@@ -855,17 +859,14 @@ def _register_routes(app: FastAPI):
         "/v1/default/banks/{bank_id}/memories/recall",
         response_model=RecallResponse,
         summary="Recall memory",
-        description="""
-    Recall memory using semantic similarity and spreading activation.
-
-    The type parameter is optional and must be one of:
-    - 'world': General knowledge about people, places, events, and things that happen
-    - 'experience': Memories about experience, conversations, actions taken, and tasks performed
-    - 'opinion': The bank's formed beliefs, perspectives, and viewpoints
-
-    Set include_entities=true to get entity observations alongside recall results.
-        """,
-        operation_id="recall_memories"
+        description="Recall memory using semantic similarity and spreading activation.\n\n"
+        "The type parameter is optional and must be one of:\n"
+        "- `world`: General knowledge about people, places, events, and things that happen\n"
+        "- `experience`: Memories about experience, conversations, actions taken, and tasks performed\n"
+        "- `opinion`: The bank's formed beliefs, perspectives, and viewpoints\n\n"
+        "Set `include_entities=true` to get entity observations alongside recall results.",
+        operation_id="recall_memories",
+        tags=["Memory"]
     )
     async def api_recall(bank_id: str, request: RecallRequest):
         """Run a recall and return results with trace."""
@@ -972,18 +973,16 @@ def _register_routes(app: FastAPI):
         "/v1/default/banks/{bank_id}/reflect",
         response_model=ReflectResponse,
         summary="Reflect and generate answer",
-        description="""
-    Reflect and formulate an answer using bank identity, world facts, and opinions.
-
-    This endpoint:
-    1. Retrieves experience (conversations and events)
-    2. Retrieves world facts relevant to the query
-    3. Retrieves existing opinions (bank's perspectives)
-    4. Uses LLM to formulate a contextual answer
-    5. Extracts and stores any new opinions formed
-    6. Returns plain text answer, the facts used, and new opinions
-        """,
-        operation_id="reflect"
+        description="Reflect and formulate an answer using bank identity, world facts, and opinions.\n\n"
+        "This endpoint:\n"
+        "1. Retrieves experience (conversations and events)\n"
+        "2. Retrieves world facts relevant to the query\n"
+        "3. Retrieves existing opinions (bank's perspectives)\n"
+        "4. Uses LLM to formulate a contextual answer\n"
+        "5. Extracts and stores any new opinions formed\n"
+        "6. Returns plain text answer, the facts used, and new opinions",
+        operation_id="reflect",
+        tags=["Memory"]
     )
     async def api_reflect(bank_id: str, request: ReflectRequest):
         metrics = get_metrics_collector()
@@ -1029,7 +1028,8 @@ def _register_routes(app: FastAPI):
         response_model=BankListResponse,
         summary="List all memory banks",
         description="Get a list of all agents with their profiles",
-        operation_id="list_banks"
+        operation_id="list_banks",
+        tags=["Banks"]
     )
     async def api_list_banks():
         """Get list of all banks with their profiles."""
@@ -1046,7 +1046,8 @@ def _register_routes(app: FastAPI):
         "/v1/default/banks/{bank_id}/stats",
         summary="Get statistics for memory bank",
         description="Get statistics about nodes and links for a specific agent",
-        operation_id="get_agent_stats"
+        operation_id="get_agent_stats",
+        tags=["Banks"]
     )
     async def api_stats(bank_id: str):
         """Get statistics about memory nodes and links for a memory bank."""
@@ -1167,7 +1168,8 @@ def _register_routes(app: FastAPI):
         response_model=EntityListResponse,
         summary="List entities",
         description="List all entities (people, organizations, etc.) known by the bank, ordered by mention count.",
-        operation_id="list_entities"
+        operation_id="list_entities",
+        tags=["Entities"]
     )
     async def api_list_entities(bank_id: str,
         limit: int = Query(default=100, description="Maximum number of entities to return")
@@ -1189,7 +1191,8 @@ def _register_routes(app: FastAPI):
         response_model=EntityDetailResponse,
         summary="Get entity details",
         description="Get detailed information about an entity including observations (mental model).",
-        operation_id="get_entity"
+        operation_id="get_entity",
+        tags=["Entities"]
     )
     async def api_get_entity(bank_id: str, entity_id: str):
         """Get entity details with observations."""
@@ -1239,7 +1242,8 @@ def _register_routes(app: FastAPI):
         response_model=EntityDetailResponse,
         summary="Regenerate entity observations",
         description="Regenerate observations for an entity based on all facts mentioning it.",
-        operation_id="regenerate_entity_observations"
+        operation_id="regenerate_entity_observations",
+        tags=["Entities"]
     )
     async def api_regenerate_entity_observations(bank_id: str, entity_id: str):
         """Regenerate observations for an entity."""
@@ -1296,7 +1300,8 @@ def _register_routes(app: FastAPI):
         response_model=ListDocumentsResponse,
         summary="List documents",
         description="List documents with pagination and optional search. Documents are the source content from which memory units are extracted.",
-        operation_id="list_documents"
+        operation_id="list_documents",
+        tags=["Documents"]
     )
     async def api_list_documents(bank_id: str,
         q: Optional[str] = None,
@@ -1332,7 +1337,8 @@ def _register_routes(app: FastAPI):
         response_model=DocumentResponse,
         summary="Get document details",
         description="Get a specific document including its original text",
-        operation_id="get_document"
+        operation_id="get_document",
+        tags=["Documents"]
     )
     async def api_get_document(bank_id: str,
         document_id: str
@@ -1363,7 +1369,8 @@ def _register_routes(app: FastAPI):
         response_model=ChunkResponse,
         summary="Get chunk details",
         description="Get a specific chunk by its ID",
-        operation_id="get_chunk"
+        operation_id="get_chunk",
+        tags=["Documents"]
     )
     async def api_get_chunk(chunk_id: str):
         """
@@ -1389,17 +1396,14 @@ def _register_routes(app: FastAPI):
     @app.delete(
         "/v1/default/banks/{bank_id}/documents/{document_id}",
         summary="Delete a document",
-        description="""
-Delete a document and all its associated memory units and links.
-
-This will cascade delete:
-- The document itself
-- All memory units extracted from this document
-- All links (temporal, semantic, entity) associated with those memory units
-
-This operation cannot be undone.
-        """,
-        operation_id="delete_document"
+        description="Delete a document and all its associated memory units and links.\n\n"
+        "This will cascade delete:\n"
+        "- The document itself\n"
+        "- All memory units extracted from this document\n"
+        "- All links (temporal, semantic, entity) associated with those memory units\n\n"
+        "This operation cannot be undone.",
+        operation_id="delete_document",
+        tags=["Documents"]
     )
     async def api_delete_document(bank_id: str,
         document_id: str
@@ -1436,7 +1440,8 @@ This operation cannot be undone.
         "/v1/default/banks/{bank_id}/operations",
         summary="List async operations",
         description="Get a list of all async operations (pending and failed) for a specific agent, including error messages for failed operations",
-        operation_id="list_operations"
+        operation_id="list_operations",
+        tags=["Operations"]
     )
     async def api_list_operations(bank_id: str):
         """List all async operations (pending and failed) for a memory bank."""
@@ -1480,7 +1485,8 @@ This operation cannot be undone.
         "/v1/default/banks/{bank_id}/operations/{operation_id}",
         summary="Cancel a pending async operation",
         description="Cancel a pending async operation by removing it from the queue",
-        operation_id="cancel_operation"
+        operation_id="cancel_operation",
+        tags=["Operations"]
     )
     async def api_cancel_operation(bank_id: str, operation_id: str):
         """Cancel a pending async operation."""
@@ -1530,7 +1536,8 @@ This operation cannot be undone.
         response_model=BankProfileResponse,
         summary="Get memory bank profile",
         description="Get disposition traits and background for a memory bank. Auto-creates agent with defaults if not exists.",
-        operation_id="get_bank_profile"
+        operation_id="get_bank_profile",
+        tags=["Banks"]
     )
     async def api_get_bank_profile(bank_id: str):
         """Get memory bank profile (disposition + background)."""
@@ -1556,7 +1563,8 @@ This operation cannot be undone.
         response_model=BankProfileResponse,
         summary="Update memory bank disposition",
         description="Update bank's disposition traits (skepticism, literalism, empathy)",
-        operation_id="update_bank_disposition"
+        operation_id="update_bank_disposition",
+        tags=["Banks"]
     )
     async def api_update_bank_disposition(bank_id: str,
         request: UpdateDispositionRequest
@@ -1590,7 +1598,8 @@ This operation cannot be undone.
         response_model=BackgroundResponse,
         summary="Add/merge memory bank background",
         description="Add new background information or merge with existing. LLM intelligently resolves conflicts, normalizes to first person, and optionally infers disposition traits.",
-        operation_id="add_bank_background"
+        operation_id="add_bank_background",
+        tags=["Banks"]
     )
     async def api_add_bank_background(bank_id: str,
         request: AddBackgroundRequest
@@ -1620,7 +1629,8 @@ This operation cannot be undone.
         response_model=BankProfileResponse,
         summary="Create or update memory bank",
         description="Create a new agent or update existing agent with disposition and background. Auto-fills missing fields with defaults.",
-        operation_id="create_or_update_bank"
+        operation_id="create_or_update_bank",
+        tags=["Banks"]
     )
     async def api_create_or_update_bank(bank_id: str,
         request: CreateBankRequest
@@ -1690,39 +1700,26 @@ This operation cannot be undone.
         "/v1/default/banks/{bank_id}/memories",
         response_model=RetainResponse,
         summary="Retain memories",
-        description="""
-    Retain memory items with automatic fact extraction.
-
-    This is the main endpoint for storing memories. It supports both synchronous and asynchronous processing
-    via the async parameter.
-
-    Features:
-    - Efficient batch processing
-    - Automatic fact extraction from natural language
-    - Entity recognition and linking
-    - Document tracking with automatic upsert (when document_id is provided on items)
-    - Temporal and semantic linking
-    - Optional asynchronous processing
-
-    The system automatically:
-    1. Extracts semantic facts from the content
-    2. Generates embeddings
-    3. Deduplicates similar facts
-    4. Creates temporal, semantic, and entity links
-    5. Tracks document metadata
-
-    When async=true:
-    - Returns immediately after queuing the task
-    - Processing happens in the background
-    - Use the operations endpoint to monitor progress
-
-    When async=false (default):
-    - Waits for processing to complete
-    - Returns after all memories are stored
-
-    Note: If a memory item has a document_id that already exists, the old document and its memory units will be deleted before creating new ones (upsert behavior). Items with the same document_id are grouped together for efficient processing.
-        """,
-        operation_id="retain_memories"
+        description="Retain memory items with automatic fact extraction.\n\n"
+        "This is the main endpoint for storing memories. It supports both synchronous and asynchronous processing via the `async` parameter.\n\n"
+        "**Features:**\n"
+        "- Efficient batch processing\n"
+        "- Automatic fact extraction from natural language\n"
+        "- Entity recognition and linking\n"
+        "- Document tracking with automatic upsert (when document_id is provided)\n"
+        "- Temporal and semantic linking\n"
+        "- Optional asynchronous processing\n\n"
+        "**The system automatically:**\n"
+        "1. Extracts semantic facts from the content\n"
+        "2. Generates embeddings\n"
+        "3. Deduplicates similar facts\n"
+        "4. Creates temporal, semantic, and entity links\n"
+        "5. Tracks document metadata\n\n"
+        "**When `async=true`:** Returns immediately after queuing. Use the operations endpoint to monitor progress.\n\n"
+        "**When `async=false` (default):** Waits for processing to complete.\n\n"
+        "**Note:** If a memory item has a `document_id` that already exists, the old document and its memory units will be deleted before creating new ones (upsert behavior).",
+        operation_id="retain_memories",
+        tags=["Memory"]
     )
     async def api_retain(bank_id: str, request: RetainRequest):
         """Retain memories with optional async processing."""
@@ -1763,7 +1760,7 @@ This operation cannot be undone.
 
                 # Submit task to background queue
                 await app.state.memory._task_backend.submit_task({
-                    'type': 'batch_put',
+                    'type': 'batch_retain',
                     'operation_id': str(operation_id),
                     'bank_id': bank_id,
                     'contents': contents
@@ -1803,7 +1800,8 @@ This operation cannot be undone.
         response_model=DeleteResponse,
         summary="Clear memory bank memories",
         description="Delete memory units for a memory bank. Optionally filter by type (world, experience, opinion) to delete only specific types. This is a destructive operation that cannot be undone. The bank profile (disposition and background) will be preserved.",
-        operation_id="clear_bank_memories"
+        operation_id="clear_bank_memories",
+        tags=["Memory"]
     )
     async def api_clear_bank_memories(bank_id: str,
         type: Optional[str] = Query(None, description="Optional fact type filter (world, experience, opinion)")

hindsight_api-0.1.2/hindsight_api/config.py

@@ -0,0 +1,154 @@
+"""
+Centralized configuration for Hindsight API.
+
+All environment variables and their defaults are defined here.
+"""
+import os
+from dataclasses import dataclass
+from typing import Optional
+import logging
+
+logger = logging.getLogger(__name__)
+
+# Environment variable names
+ENV_DATABASE_URL = "HINDSIGHT_API_DATABASE_URL"
+ENV_LLM_PROVIDER = "HINDSIGHT_API_LLM_PROVIDER"
+ENV_LLM_API_KEY = "HINDSIGHT_API_LLM_API_KEY"
+ENV_LLM_MODEL = "HINDSIGHT_API_LLM_MODEL"
+ENV_LLM_BASE_URL = "HINDSIGHT_API_LLM_BASE_URL"
+
+ENV_EMBEDDINGS_PROVIDER = "HINDSIGHT_API_EMBEDDINGS_PROVIDER"
+ENV_EMBEDDINGS_LOCAL_MODEL = "HINDSIGHT_API_EMBEDDINGS_LOCAL_MODEL"
+ENV_EMBEDDINGS_TEI_URL = "HINDSIGHT_API_EMBEDDINGS_TEI_URL"
+
+ENV_RERANKER_PROVIDER = "HINDSIGHT_API_RERANKER_PROVIDER"
+ENV_RERANKER_LOCAL_MODEL = "HINDSIGHT_API_RERANKER_LOCAL_MODEL"
+ENV_RERANKER_TEI_URL = "HINDSIGHT_API_RERANKER_TEI_URL"
+
+ENV_HOST = "HINDSIGHT_API_HOST"
+ENV_PORT = "HINDSIGHT_API_PORT"
+ENV_LOG_LEVEL = "HINDSIGHT_API_LOG_LEVEL"
+ENV_MCP_ENABLED = "HINDSIGHT_API_MCP_ENABLED"
+
+# Default values
+DEFAULT_DATABASE_URL = "pg0"
+DEFAULT_LLM_PROVIDER = "groq"
+DEFAULT_LLM_MODEL = "openai/gpt-oss-20b"
+
+DEFAULT_EMBEDDINGS_PROVIDER = "local"
+DEFAULT_EMBEDDINGS_LOCAL_MODEL = "BAAI/bge-small-en-v1.5"
+
+DEFAULT_RERANKER_PROVIDER = "local"
+DEFAULT_RERANKER_LOCAL_MODEL = "cross-encoder/ms-marco-MiniLM-L-6-v2"
+
+DEFAULT_HOST = "0.0.0.0"
+DEFAULT_PORT = 8888
+DEFAULT_LOG_LEVEL = "info"
+DEFAULT_MCP_ENABLED = True
+
+# Required embedding dimension for database schema
+EMBEDDING_DIMENSION = 384
+
+
+@dataclass
+class HindsightConfig:
+    """Configuration container for Hindsight API."""
+
+    # Database
+    database_url: str
+
+    # LLM
+    llm_provider: str
+    llm_api_key: Optional[str]
+    llm_model: str
+    llm_base_url: Optional[str]
+
+    # Embeddings
+    embeddings_provider: str
+    embeddings_local_model: str
+    embeddings_tei_url: Optional[str]
+
+    # Reranker
+    reranker_provider: str
+    reranker_local_model: str
+    reranker_tei_url: Optional[str]
+
+    # Server
+    host: str
+    port: int
+    log_level: str
+    mcp_enabled: bool
+
+    @classmethod
+    def from_env(cls) -> "HindsightConfig":
+        """Create configuration from environment variables."""
+        return cls(
+            # Database
+            database_url=os.getenv(ENV_DATABASE_URL, DEFAULT_DATABASE_URL),
+
+            # LLM
+            llm_provider=os.getenv(ENV_LLM_PROVIDER, DEFAULT_LLM_PROVIDER),
+            llm_api_key=os.getenv(ENV_LLM_API_KEY),
+            llm_model=os.getenv(ENV_LLM_MODEL, DEFAULT_LLM_MODEL),
+            llm_base_url=os.getenv(ENV_LLM_BASE_URL) or None,
+
+            # Embeddings
+            embeddings_provider=os.getenv(ENV_EMBEDDINGS_PROVIDER, DEFAULT_EMBEDDINGS_PROVIDER),
+            embeddings_local_model=os.getenv(ENV_EMBEDDINGS_LOCAL_MODEL, DEFAULT_EMBEDDINGS_LOCAL_MODEL),
+            embeddings_tei_url=os.getenv(ENV_EMBEDDINGS_TEI_URL),
+
+            # Reranker
+            reranker_provider=os.getenv(ENV_RERANKER_PROVIDER, DEFAULT_RERANKER_PROVIDER),
+            reranker_local_model=os.getenv(ENV_RERANKER_LOCAL_MODEL, DEFAULT_RERANKER_LOCAL_MODEL),
+            reranker_tei_url=os.getenv(ENV_RERANKER_TEI_URL),
+
+            # Server
+            host=os.getenv(ENV_HOST, DEFAULT_HOST),
+            port=int(os.getenv(ENV_PORT, DEFAULT_PORT)),
+            log_level=os.getenv(ENV_LOG_LEVEL, DEFAULT_LOG_LEVEL),
+            mcp_enabled=os.getenv(ENV_MCP_ENABLED, str(DEFAULT_MCP_ENABLED)).lower() == "true",
+        )
+
+    def get_llm_base_url(self) -> str:
+        """Get the LLM base URL, with provider-specific defaults."""
+        if self.llm_base_url:
+            return self.llm_base_url
+
+        provider = self.llm_provider.lower()
+        if provider == "groq":
+            return "https://api.groq.com/openai/v1"
+        elif provider == "ollama":
+            return "http://localhost:11434/v1"
+        else:
+            return ""
+
+    def get_python_log_level(self) -> int:
+        """Get the Python logging level from the configured log level string."""
+        log_level_map = {
+            "critical": logging.CRITICAL,
+            "error": logging.ERROR,
+            "warning": logging.WARNING,
+            "info": logging.INFO,
+            "debug": logging.DEBUG,
+            "trace": logging.DEBUG,  # Python doesn't have TRACE, use DEBUG
+        }
+        return log_level_map.get(self.log_level.lower(), logging.INFO)
+
+    def configure_logging(self) -> None:
+        """Configure Python logging based on the log level."""
+        logging.basicConfig(
+            level=self.get_python_log_level(),
+            format="%(asctime)s - %(levelname)s - %(name)s - %(message)s"
+        )
+
+    def log_config(self) -> None:
+        """Log the current configuration (without sensitive values)."""
+        logger.info(f"Database: {self.database_url}")
+        logger.info(f"LLM: provider={self.llm_provider}, model={self.llm_model}")
+        logger.info(f"Embeddings: provider={self.embeddings_provider}")
+        logger.info(f"Reranker: provider={self.reranker_provider}")
+
+
+def get_config() -> HindsightConfig:
+    """Get the current configuration from environment variables."""
+    return HindsightConfig.from_env()

{hindsight_api-0.1.0 → hindsight_api-0.1.2}/hindsight_api/engine/__init__.py

@@ -9,7 +9,8 @@ This package contains all the implementation details of the memory engine:
 
 from .memory_engine import MemoryEngine
 from .db_utils import acquire_with_retry
-from .embeddings import Embeddings, SentenceTransformersEmbeddings
+from .embeddings import Embeddings, LocalSTEmbeddings, RemoteTEIEmbeddings
+from .cross_encoder import CrossEncoderModel, LocalSTCrossEncoder, RemoteTEICrossEncoder
 from .search.trace import (
     SearchTrace,
     QueryInfo,
@@ -29,7 +30,11 @@ __all__ = [
     "MemoryEngine",
     "acquire_with_retry",
     "Embeddings",
-    "SentenceTransformersEmbeddings",
+    "LocalSTEmbeddings",
+    "RemoteTEIEmbeddings",
+    "CrossEncoderModel",
+    "LocalSTCrossEncoder",
+    "RemoteTEICrossEncoder",
     "SearchTrace",
     "SearchTracer",
     "QueryInfo",