hindsight-api 0.1.5__py3-none-any.whl → 0.1.7__py3-none-any.whl

hindsight_api/engine/search/tracer.py

@@ -4,24 +4,25 @@ Search tracer for collecting detailed search execution traces.
 The SearchTracer collects comprehensive information about each step
 of the spreading activation search process for debugging and visualization.
 """
+
 import time
-from datetime import datetime, timezone
-from typing import List, Optional, Dict, Any, Literal
+from datetime import UTC, datetime
+from typing import Any, Literal
 
 from .trace import (
-    SearchTrace,
-    QueryInfo,
     EntryPoint,
-    NodeVisit,
-    WeightComponents,
     LinkInfo,
+    NodeVisit,
     PruningDecision,
-    SearchSummary,
-    SearchPhaseMetrics,
-    RetrievalResult,
+    QueryInfo,
+    RerankedResult,
     RetrievalMethodResults,
+    RetrievalResult,
     RRFMergeResult,
-    RerankedResult,
+    SearchPhaseMetrics,
+    SearchSummary,
+    SearchTrace,
+    WeightComponents,
 )
 
 
@@ -58,17 +59,17 @@ class SearchTracer:
         self.max_tokens = max_tokens
 
         # Trace data
-        self.query_embedding: Optional[List[float]] = None
-        self.start_time: Optional[float] = None
-        self.entry_points: List[EntryPoint] = []
-        self.visits: List[NodeVisit] = []
-        self.pruned: List[PruningDecision] = []
-        self.phase_metrics: List[SearchPhaseMetrics] = []
+        self.query_embedding: list[float] | None = None
+        self.start_time: float | None = None
+        self.entry_points: list[EntryPoint] = []
+        self.visits: list[NodeVisit] = []
+        self.pruned: list[PruningDecision] = []
+        self.phase_metrics: list[SearchPhaseMetrics] = []
 
         # New 4-way retrieval tracking
-        self.retrieval_results: List[RetrievalMethodResults] = []
-        self.rrf_merged: List[RRFMergeResult] = []
-        self.reranked: List[RerankedResult] = []
+        self.retrieval_results: list[RetrievalMethodResults] = []
+        self.rrf_merged: list[RRFMergeResult] = []
+        self.reranked: list[RerankedResult] = []
 
         # Tracking state
         self.current_step = 0
@@ -83,7 +84,7 @@ class SearchTracer:
         """Start timing the search."""
         self.start_time = time.time()
 
-    def record_query_embedding(self, embedding: List[float]):
+    def record_query_embedding(self, embedding: list[float]):
         """Record the query embedding."""
         self.query_embedding = embedding
 
@@ -117,9 +118,9 @@ class SearchTracer:
         event_date: datetime,
         access_count: int,
         is_entry_point: bool,
-        parent_node_id: Optional[str],
-        link_type: Optional[Literal["temporal", "semantic", "entity"]],
-        link_weight: Optional[float],
+        parent_node_id: str | None,
+        link_type: Literal["temporal", "semantic", "entity"] | None,
+        link_weight: float | None,
         activation: float,
         semantic_similarity: float,
         recency: float,
@@ -199,10 +200,10 @@ class SearchTracer:
         to_node_id: str,
         link_type: Literal["temporal", "semantic", "entity"],
         link_weight: float,
-        entity_id: Optional[str],
-        new_activation: Optional[float],
+        entity_id: str | None,
+        new_activation: float | None,
         followed: bool,
-        prune_reason: Optional[str] = None,
+        prune_reason: str | None = None,
         is_supplementary: bool = False,
     ):
         """
@@ -266,7 +267,7 @@ class SearchTracer:
             )
         )
 
-    def add_phase_metric(self, phase_name: str, duration_seconds: float, details: Optional[Dict[str, Any]] = None):
+    def add_phase_metric(self, phase_name: str, duration_seconds: float, details: dict[str, Any] | None = None):
         """
         Record metrics for a search phase.
 
@@ -286,11 +287,11 @@ class SearchTracer:
     def add_retrieval_results(
         self,
         method_name: Literal["semantic", "bm25", "graph", "temporal"],
-        results: List[tuple],  # List of (doc_id, data) tuples
+        results: list[tuple],  # List of (doc_id, data) tuples
         duration_seconds: float,
         score_field: str,  # e.g., "similarity", "bm25_score"
-        metadata: Optional[Dict[str, Any]] = None,
-        fact_type: Optional[str] = None
+        metadata: dict[str, Any] | None = None,
+        fact_type: str | None = None,
     ):
         """
         Record results from a single retrieval method.
@@ -331,7 +332,7 @@ class SearchTracer:
             )
         )
 
-    def add_rrf_merged(self, merged_results: List[tuple]):
+    def add_rrf_merged(self, merged_results: list[tuple]):
         """
         Record RRF merged results.
 
@@ -350,7 +351,7 @@ class SearchTracer:
                 )
             )
 
-    def add_reranked(self, reranked_results: List[Dict[str, Any]], rrf_merged: List):
+    def add_reranked(self, reranked_results: list[dict[str, Any]], rrf_merged: list):
         """
         Record reranked results.
 
@@ -373,7 +374,15 @@ class SearchTracer:
             # Keys from ScoredResult.to_dict(): cross_encoder_score, cross_encoder_score_normalized,
             # rrf_normalized, temporal, recency, combined_score, weight
             score_components = {}
-            for key in ["cross_encoder_score", "cross_encoder_score_normalized", "rrf_score", "rrf_normalized", "temporal", "recency", "combined_score"]:
+            for key in [
+                "cross_encoder_score",
+                "cross_encoder_score_normalized",
+                "rrf_score",
+                "rrf_normalized",
+                "temporal",
+                "recency",
+                "combined_score",
+            ]:
                 if key in result and result[key] is not None:
                     score_components[key] = result[key]
 
@@ -389,7 +398,7 @@ class SearchTracer:
                 )
             )
 
-    def finalize(self, final_results: List[Dict[str, Any]]) -> SearchTrace:
+    def finalize(self, final_results: list[dict[str, Any]]) -> SearchTrace:
         """
         Finalize the trace and return the complete SearchTrace object.
 
@@ -416,7 +425,7 @@ class SearchTracer:
         query_info = QueryInfo(
             query_text=self.query_text,
             query_embedding=self.query_embedding or [],
-            timestamp=datetime.now(timezone.utc),
+            timestamp=datetime.now(UTC),
             budget=self.budget,
             max_tokens=self.max_tokens,
         )

hindsight_api/engine/search/types.py

@@ -6,8 +6,8 @@ providing type safety and making data flow explicit.
 """
 
 from dataclasses import dataclass, field
-from typing import Optional, List, Dict, Any
 from datetime import datetime
+from typing import Any
 
 
 @dataclass
@@ -17,28 +17,29 @@ class RetrievalResult:
 
     This represents a raw result from the database query, before merging or reranking.
     """
+
     id: str
     text: str
     fact_type: str
-    context: Optional[str] = None
-    event_date: Optional[datetime] = None
-    occurred_start: Optional[datetime] = None
-    occurred_end: Optional[datetime] = None
-    mentioned_at: Optional[datetime] = None
-    document_id: Optional[str] = None
-    chunk_id: Optional[str] = None
+    context: str | None = None
+    event_date: datetime | None = None
+    occurred_start: datetime | None = None
+    occurred_end: datetime | None = None
+    mentioned_at: datetime | None = None
+    document_id: str | None = None
+    chunk_id: str | None = None
     access_count: int = 0
-    embedding: Optional[List[float]] = None
+    embedding: list[float] | None = None
 
     # Retrieval-specific scores (only one will be set depending on retrieval method)
-    similarity: Optional[float] = None  # Semantic retrieval
-    bm25_score: Optional[float] = None  # BM25 retrieval
-    activation: Optional[float] = None  # Graph retrieval (spreading activation)
-    temporal_score: Optional[float] = None  # Temporal retrieval
-    temporal_proximity: Optional[float] = None  # Temporal retrieval
+    similarity: float | None = None  # Semantic retrieval
+    bm25_score: float | None = None  # BM25 retrieval
+    activation: float | None = None  # Graph retrieval (spreading activation)
+    temporal_score: float | None = None  # Temporal retrieval
+    temporal_proximity: float | None = None  # Temporal retrieval
 
     @classmethod
-    def from_db_row(cls, row: Dict[str, Any]) -> "RetrievalResult":
+    def from_db_row(cls, row: dict[str, Any]) -> "RetrievalResult":
         """Create from a database row (asyncpg Record converted to dict)."""
         return cls(
             id=str(row["id"]),
@@ -68,13 +69,14 @@ class MergedCandidate:
 
     Contains the original retrieval data plus RRF metadata.
     """
+
     # Original retrieval data
     retrieval: RetrievalResult
 
     # RRF metadata
     rrf_score: float
     rrf_rank: int = 0
-    source_ranks: Dict[str, int] = field(default_factory=dict)  # method_name -> rank
+    source_ranks: dict[str, int] = field(default_factory=dict)  # method_name -> rank
 
     @property
     def id(self) -> str:
@@ -89,6 +91,7 @@ class ScoredResult:
 
     Contains all retrieval/merge data plus reranking scores and combined score.
     """
+
     # Original merged candidate
     candidate: MergedCandidate
 
@@ -115,7 +118,7 @@ class ScoredResult:
         """Convenience property to access retrieval data."""
         return self.candidate.retrieval
 
-    def to_dict(self) -> Dict[str, Any]:
+    def to_dict(self) -> dict[str, Any]:
         """
         Convert to dict for backwards compatibility.
 

hindsight_api/engine/task_backend.py

@@ -6,10 +6,12 @@ This provides an abstraction that can be adapted to different execution models:
 - Pub/Sub architectures (future)
 - Message brokers (future)
 """
-from abc import ABC, abstractmethod
-from typing import Any, Dict, Optional, Callable, Awaitable
+
 import asyncio
 import logging
+from abc import ABC, abstractmethod
+from collections.abc import Awaitable, Callable
+from typing import Any
 
 logger = logging.getLogger(__name__)
 
@@ -29,10 +31,10 @@ class TaskBackend(ABC):
 
     def __init__(self):
         """Initialize the task backend."""
-        self._executor: Optional[Callable[[Dict[str, Any]], Awaitable[None]]] = None
+        self._executor: Callable[[dict[str, Any]], Awaitable[None]] | None = None
         self._initialized = False
 
-    def set_executor(self, executor: Callable[[Dict[str, Any]], Awaitable[None]]):
+    def set_executor(self, executor: Callable[[dict[str, Any]], Awaitable[None]]):
         """
         Set the executor callback for processing tasks.
 
@@ -49,7 +51,7 @@ class TaskBackend(ABC):
         pass
 
     @abstractmethod
-    async def submit_task(self, task_dict: Dict[str, Any]):
+    async def submit_task(self, task_dict: dict[str, Any]):
         """
         Submit a task for execution.
 
@@ -65,7 +67,7 @@ class TaskBackend(ABC):
         """
         pass
 
-    async def _execute_task(self, task_dict: Dict[str, Any]):
+    async def _execute_task(self, task_dict: dict[str, Any]):
         """
         Execute a task through the registered executor.
 
@@ -73,16 +75,17 @@ class TaskBackend(ABC):
             task_dict: Task dictionary to execute
         """
         if self._executor is None:
-            task_type = task_dict.get('type', 'unknown')
+            task_type = task_dict.get("type", "unknown")
             logger.warning(f"No executor registered, skipping task {task_type}")
             return
 
         try:
             await self._executor(task_dict)
         except Exception as e:
-            task_type = task_dict.get('type', 'unknown')
+            task_type = task_dict.get("type", "unknown")
             logger.error(f"Error executing task {task_type}: {e}")
             import traceback
+
             traceback.print_exc()
 
 
@@ -94,11 +97,7 @@ class AsyncIOQueueBackend(TaskBackend):
     and a periodic consumer worker.
     """
 
-    def __init__(
-        self,
-        batch_size: int = 100,
-        batch_interval: float = 1.0
-    ):
+    def __init__(self, batch_size: int = 100, batch_interval: float = 1.0):
         """
         Initialize AsyncIO queue backend.
 
@@ -107,9 +106,9 @@ class AsyncIOQueueBackend(TaskBackend):
             batch_interval: Maximum time (seconds) to wait before processing batch
         """
         super().__init__()
-        self._queue: Optional[asyncio.Queue] = None
-        self._worker_task: Optional[asyncio.Task] = None
-        self._shutdown_event: Optional[asyncio.Event] = None
+        self._queue: asyncio.Queue | None = None
+        self._worker_task: asyncio.Task | None = None
+        self._shutdown_event: asyncio.Event | None = None
         self._batch_size = batch_size
         self._batch_interval = batch_interval
 
@@ -124,7 +123,7 @@ class AsyncIOQueueBackend(TaskBackend):
         self._initialized = True
         logger.info("AsyncIOQueueBackend initialized")
 
-    async def submit_task(self, task_dict: Dict[str, Any]):
+    async def submit_task(self, task_dict: dict[str, Any]):
         """
         Submit a task by putting it in the queue.
 
@@ -135,8 +134,8 @@ class AsyncIOQueueBackend(TaskBackend):
             await self.initialize()
 
         await self._queue.put(task_dict)
-        task_type = task_dict.get('type', 'unknown')
-        task_id = task_dict.get('id')
+        task_type = task_dict.get("type", "unknown")
+        task_id = task_dict.get("id")
 
     async def wait_for_pending_tasks(self, timeout: float = 5.0):
         """
@@ -200,20 +199,16 @@ class AsyncIOQueueBackend(TaskBackend):
                 while len(tasks) < self._batch_size and asyncio.get_event_loop().time() < deadline:
                     try:
                         remaining_time = max(0.1, deadline - asyncio.get_event_loop().time())
-                        task_dict = await asyncio.wait_for(
-                            self._queue.get(),
-                            timeout=remaining_time
-                        )
+                        task_dict = await asyncio.wait_for(self._queue.get(), timeout=remaining_time)
                         tasks.append(task_dict)
-                    except asyncio.TimeoutError:
+                    except TimeoutError:
                         break
 
                 # Process batch
                 if tasks:
                     # Execute tasks concurrently
                     await asyncio.gather(
-                        *[self._execute_task(task_dict) for task_dict in tasks],
-                        return_exceptions=True
+                        *[self._execute_task(task_dict) for task_dict in tasks], return_exceptions=True
                     )
 
             except asyncio.CancelledError:

hindsight_api/engine/utils.py

@@ -1,9 +1,10 @@
 """
 Utility functions for memory system.
 """
+
 import logging
 from datetime import datetime
-from typing import List, Dict, TYPE_CHECKING
+from typing import TYPE_CHECKING
 
 if TYPE_CHECKING:
     from .llm_wrapper import LLMConfig
@@ -12,7 +13,14 @@ if TYPE_CHECKING:
 from .retain.fact_extraction import extract_facts_from_text
 
 
-async def extract_facts(text: str, event_date: datetime, context: str = "", llm_config: 'LLMConfig' = None, agent_name: str = None, extract_opinions: bool = False) -> tuple[List['Fact'], List[tuple[str, int]]]:
+async def extract_facts(
+    text: str,
+    event_date: datetime,
+    context: str = "",
+    llm_config: "LLMConfig" = None,
+    agent_name: str = None,
+    extract_opinions: bool = False,
+) -> tuple[list["Fact"], list[tuple[str, int]]]:
     """
     Extract semantic facts from text using LLM.
 
@@ -41,16 +49,25 @@ async def extract_facts(text: str, event_date: datetime, context: str = "", llm_
     if not text or not text.strip():
         return [], []
 
-    facts, chunks = await extract_facts_from_text(text, event_date, context=context, llm_config=llm_config, agent_name=agent_name, extract_opinions=extract_opinions)
+    facts, chunks = await extract_facts_from_text(
+        text,
+        event_date,
+        context=context,
+        llm_config=llm_config,
+        agent_name=agent_name,
+        extract_opinions=extract_opinions,
+    )
 
     if not facts:
-        logging.warning(f"LLM extracted 0 facts from text of length {len(text)}. This may indicate the text contains no meaningful information, or the LLM failed to extract facts. Full text: {text}")
+        logging.warning(
+            f"LLM extracted 0 facts from text of length {len(text)}. This may indicate the text contains no meaningful information, or the LLM failed to extract facts. Full text: {text}"
+        )
         return [], chunks
 
     return facts, chunks
 
 
-def cosine_similarity(vec1: List[float], vec2: List[float]) -> float:
+def cosine_similarity(vec1: list[float], vec2: list[float]) -> float:
     """
     Calculate cosine similarity between two vectors.
 
@@ -100,6 +117,7 @@ def calculate_recency_weight(days_since: float, half_life_days: float = 365.0) -
         Weight between 0 and 1
     """
     import math
+
     # Logarithmic decay: 1 / (1 + log(1 + days_since/half_life))
     # This decays much slower than exponential, giving better long-term differentiation
     normalized_age = days_since / half_life_days
@@ -121,6 +139,7 @@ def calculate_frequency_weight(access_count: int, max_boost: float = 2.0) -> flo
         Weight between 1.0 and max_boost
     """
     import math
+
     if access_count <= 0:
         return 1.0
 
@@ -158,11 +177,7 @@ def calculate_temporal_anchor(occurred_start: datetime, occurred_end: datetime)
     return midpoint
 
 
-def calculate_temporal_proximity(
-    anchor_a: datetime,
-    anchor_b: datetime,
-    half_life_days: float = 30.0
-) -> float:
+def calculate_temporal_proximity(anchor_a: datetime, anchor_b: datetime, half_life_days: float = 30.0) -> float:
     """
     Calculate temporal proximity between two temporal anchors.
 

hindsight_api/main.py

@@ -6,6 +6,7 @@ Run the server with:
 
 Stop with Ctrl+C.
 """
+
 import argparse
 import asyncio
 import atexit
@@ -13,15 +14,14 @@ import os
 import signal
 import sys
 import warnings
-from typing import Optional
 
 import uvicorn
 
 from . import MemoryEngine
 from .api import create_app
-from .config import get_config, HindsightConfig
-
 from .banner import print_banner
+from .config import HindsightConfig, get_config
+
 print()
 print_banner()
 
@@ -33,7 +33,7 @@ warnings.filterwarnings("ignore", message="websockets.server.WebSocketServerProt
 os.environ["TOKENIZERS_PARALLELISM"] = "false"
 
 # Global reference for cleanup
-_memory: Optional[MemoryEngine] = None
+_memory: MemoryEngine | None = None
 
 
 def _cleanup():
@@ -70,59 +70,41 @@ def main():
 
     # Server options
     parser.add_argument(
-        "--host", default=config.host,
-        help=f"Host to bind to (default: {config.host}, env: HINDSIGHT_API_HOST)"
+        "--host", default=config.host, help=f"Host to bind to (default: {config.host}, env: HINDSIGHT_API_HOST)"
     )
     parser.add_argument(
-        "--port", type=int, default=config.port,
-        help=f"Port to bind to (default: {config.port}, env: HINDSIGHT_API_PORT)"
+        "--port",
+        type=int,
+        default=config.port,
+        help=f"Port to bind to (default: {config.port}, env: HINDSIGHT_API_PORT)",
     )
     parser.add_argument(
-        "--log-level", default=config.log_level,
+        "--log-level",
+        default=config.log_level,
         choices=["critical", "error", "warning", "info", "debug", "trace"],
-        help=f"Log level (default: {config.log_level}, env: HINDSIGHT_API_LOG_LEVEL)"
+        help=f"Log level (default: {config.log_level}, env: HINDSIGHT_API_LOG_LEVEL)",
     )
 
     # Development options
-    parser.add_argument(
-        "--reload", action="store_true",
-        help="Enable auto-reload on code changes (development only)"
-    )
-    parser.add_argument(
-        "--workers", type=int, default=1,
-        help="Number of worker processes (default: 1)"
-    )
+    parser.add_argument("--reload", action="store_true", help="Enable auto-reload on code changes (development only)")
+    parser.add_argument("--workers", type=int, default=1, help="Number of worker processes (default: 1)")
 
     # Access log options
-    parser.add_argument(
-        "--access-log", action="store_true",
-        help="Enable access log"
-    )
-    parser.add_argument(
-        "--no-access-log", dest="access_log", action="store_false",
-        help="Disable access log (default)"
-    )
+    parser.add_argument("--access-log", action="store_true", help="Enable access log")
+    parser.add_argument("--no-access-log", dest="access_log", action="store_false", help="Disable access log (default)")
     parser.set_defaults(access_log=False)
 
     # Proxy options
     parser.add_argument(
-        "--proxy-headers", action="store_true",
-        help="Enable X-Forwarded-Proto, X-Forwarded-For headers"
+        "--proxy-headers", action="store_true", help="Enable X-Forwarded-Proto, X-Forwarded-For headers"
     )
     parser.add_argument(
-        "--forwarded-allow-ips", default=None,
-        help="Comma separated list of IPs to trust with proxy headers"
+        "--forwarded-allow-ips", default=None, help="Comma separated list of IPs to trust with proxy headers"
     )
 
     # SSL options
-    parser.add_argument(
-        "--ssl-keyfile", default=None,
-        help="SSL key file"
-    )
-    parser.add_argument(
-        "--ssl-certfile", default=None,
-        help="SSL certificate file"
-    )
+    parser.add_argument("--ssl-keyfile", default=None, help="SSL key file")
+    parser.add_argument("--ssl-certfile", default=None, help="SSL certificate file")
 
     args = parser.parse_args()
 
@@ -188,9 +170,8 @@ def main():
     if args.ssl_certfile:
         uvicorn_config["ssl_certfile"] = args.ssl_certfile
 
-
-
     from .banner import print_startup_info
+
     print_startup_info(
         host=args.host,
         port=args.port,