hindsight-api 0.1.11__py3-none-any.whl → 0.1.13__py3-none-any.whl

hindsight_api/engine/retain/bank_utils.py

@@ -10,6 +10,7 @@ from typing import TypedDict
 from pydantic import BaseModel, Field
 
 from ..db_utils import acquire_with_retry
+from ..memory_engine import fq_table
 from ..response_models import DispositionTraits
 
 logger = logging.getLogger(__name__)
@@ -51,9 +52,9 @@ async def get_bank_profile(pool, bank_id: str) -> BankProfile:
     async with acquire_with_retry(pool) as conn:
         # Try to get existing bank
         row = await conn.fetchrow(
-            """
+            f"""
             SELECT name, disposition, background
-            FROM banks WHERE bank_id = $1
+            FROM {fq_table("banks")} WHERE bank_id = $1
             """,
             bank_id,
         )
@@ -70,8 +71,8 @@ async def get_bank_profile(pool, bank_id: str) -> BankProfile:
 
         # Bank doesn't exist, create with defaults
         await conn.execute(
-            """
-            INSERT INTO banks (bank_id, name, disposition, background)
+            f"""
+            INSERT INTO {fq_table("banks")} (bank_id, name, disposition, background)
             VALUES ($1, $2, $3::jsonb, $4)
             ON CONFLICT (bank_id) DO NOTHING
             """,
@@ -98,8 +99,8 @@ async def update_bank_disposition(pool, bank_id: str, disposition: dict[str, int
 
     async with acquire_with_retry(pool) as conn:
         await conn.execute(
-            """
-            UPDATE banks
+            f"""
+            UPDATE {fq_table("banks")}
             SET disposition = $2::jsonb,
                 updated_at = NOW()
             WHERE bank_id = $1
@@ -140,8 +141,8 @@ async def merge_bank_background(pool, llm_config, bank_id: str, new_info: str, u
         if inferred_disposition:
             # Update both background and disposition
             await conn.execute(
-                """
-                UPDATE banks
+                f"""
+                UPDATE {fq_table("banks")}
                 SET background = $2,
                     disposition = $3::jsonb,
                     updated_at = NOW()
@@ -154,8 +155,8 @@ async def merge_bank_background(pool, llm_config, bank_id: str, new_info: str, u
         else:
             # Update only background
             await conn.execute(
-                """
-                UPDATE banks
+                f"""
+                UPDATE {fq_table("banks")}
                 SET background = $2,
                     updated_at = NOW()
                 WHERE bank_id = $1
@@ -361,9 +362,9 @@ async def list_banks(pool) -> list:
     """
     async with acquire_with_retry(pool) as conn:
         rows = await conn.fetch(
-            """
+            f"""
             SELECT bank_id, name, disposition, background, created_at, updated_at
-            FROM banks
+            FROM {fq_table("banks")}
             ORDER BY updated_at DESC
             """
         )

hindsight_api/engine/retain/chunk_storage.py

@@ -6,6 +6,7 @@ Handles storage of document chunks in the database.
 
 import logging
 
+from ..memory_engine import fq_table
 from .types import ChunkMetadata
 
 logger = logging.getLogger(__name__)
@@ -42,8 +43,8 @@ async def store_chunks_batch(conn, bank_id: str, document_id: str, chunks: list[
 
     # Batch insert all chunks
     await conn.execute(
-        """
-        INSERT INTO chunks (chunk_id, document_id, bank_id, chunk_text, chunk_index)
+        f"""
+        INSERT INTO {fq_table("chunks")} (chunk_id, document_id, bank_id, chunk_text, chunk_index)
         SELECT * FROM unnest($1::text[], $2::text[], $3::text[], $4::text[], $5::integer[])
         """,
         chunk_ids,

hindsight_api/engine/retain/fact_storage.py

@@ -7,6 +7,7 @@ Handles insertion of facts into the database.
 import json
 import logging
 
+from ..memory_engine import fq_table
 from .types import ProcessedFact
 
 logger = logging.getLogger(__name__)
@@ -67,8 +68,8 @@ async def insert_facts_batch(
 
     # Batch insert all facts
     results = await conn.fetch(
-        """
-        INSERT INTO memory_units (bank_id, text, embedding, event_date, occurred_start, occurred_end, mentioned_at,
+        f"""
+        INSERT INTO {fq_table("memory_units")} (bank_id, text, embedding, event_date, occurred_start, occurred_end, mentioned_at,
                                  context, fact_type, confidence_score, access_count, metadata, chunk_id, document_id)
         SELECT $1, * FROM unnest(
             $2::text[], $3::vector[], $4::timestamptz[], $5::timestamptz[], $6::timestamptz[], $7::timestamptz[],
@@ -107,8 +108,8 @@ async def ensure_bank_exists(conn, bank_id: str) -> None:
         bank_id: Bank identifier
     """
     await conn.execute(
-        """
-        INSERT INTO banks (bank_id, disposition, background)
+        f"""
+        INSERT INTO {fq_table("banks")} (bank_id, disposition, background)
         VALUES ($1, $2::jsonb, $3)
         ON CONFLICT (bank_id) DO UPDATE
         SET updated_at = NOW()
@@ -141,12 +142,14 @@ async def handle_document_tracking(
     # Always delete old document first if it exists (cascades to units and links)
     # Only delete on the first batch to avoid deleting data we just inserted
     if is_first_batch:
-        await conn.fetchval("DELETE FROM documents WHERE id = $1 AND bank_id = $2 RETURNING id", document_id, bank_id)
+        await conn.fetchval(
+            f"DELETE FROM {fq_table('documents')} WHERE id = $1 AND bank_id = $2 RETURNING id", document_id, bank_id
+        )
 
     # Insert document (or update if exists from concurrent operations)
     await conn.execute(
-        """
-        INSERT INTO documents (id, bank_id, original_text, content_hash, metadata, retain_params)
+        f"""
+        INSERT INTO {fq_table("documents")} (id, bank_id, original_text, content_hash, metadata, retain_params)
         VALUES ($1, $2, $3, $4, $5, $6)
         ON CONFLICT (id, bank_id) DO UPDATE
         SET original_text = EXCLUDED.original_text,

hindsight_api/engine/retain/link_utils.py

@@ -7,6 +7,7 @@ import time
 from datetime import UTC, datetime, timedelta
 from uuid import UUID
 
+from ..memory_engine import fq_table
 from .types import EntityLink
 
 logger = logging.getLogger(__name__)
@@ -290,9 +291,9 @@ async def extract_entities_batch_optimized(
 
             entity_id_list = [uuid.UUID(eid) if isinstance(eid, str) else eid for eid in all_entity_ids]
             rows = await conn.fetch(
-                """
+                f"""
                 SELECT entity_id, unit_id
-                FROM unit_entities
+                FROM {fq_table("unit_entities")}
                 WHERE entity_id = ANY($1::uuid[])
                 """,
                 entity_id_list,
@@ -413,9 +414,9 @@ async def create_temporal_links_batch_per_fact(
         # Get the event_date for each new unit
         fetch_dates_start = time_mod.time()
         rows = await conn.fetch(
-            """
+            f"""
             SELECT id, event_date
-            FROM memory_units
+            FROM {fq_table("memory_units")}
             WHERE id::text = ANY($1)
             """,
             unit_ids,
@@ -432,9 +433,9 @@ async def create_temporal_links_batch_per_fact(
 
         fetch_neighbors_start = time_mod.time()
         all_candidates = await conn.fetch(
-            """
+            f"""
             SELECT id, event_date
-            FROM memory_units
+            FROM {fq_table("memory_units")}
             WHERE bank_id = $1
               AND event_date BETWEEN $2 AND $3
               AND id::text != ALL($4)
@@ -479,8 +480,8 @@ async def create_temporal_links_batch_per_fact(
         if links:
             insert_start = time_mod.time()
             await conn.executemany(
-                """
-                INSERT INTO memory_links (from_unit_id, to_unit_id, link_type, weight, entity_id)
+                f"""
+                INSERT INTO {fq_table("memory_links")} (from_unit_id, to_unit_id, link_type, weight, entity_id)
                 VALUES ($1, $2, $3, $4, $5)
                 ON CONFLICT (from_unit_id, to_unit_id, link_type, COALESCE(entity_id, '00000000-0000-0000-0000-000000000000'::uuid)) DO NOTHING
                 """,
@@ -535,9 +536,9 @@ async def create_semantic_links_batch(
         # Fetch ALL existing units with embeddings in ONE query
         fetch_start = time_mod.time()
         all_existing = await conn.fetch(
-            """
+            f"""
             SELECT id, embedding
-            FROM memory_units
+            FROM {fq_table("memory_units")}
             WHERE bank_id = $1
               AND embedding IS NOT NULL
               AND id::text != ALL($2)
@@ -644,8 +645,8 @@ async def create_semantic_links_batch(
         if all_links:
             insert_start = time_mod.time()
             await conn.executemany(
-                """
-                INSERT INTO memory_links (from_unit_id, to_unit_id, link_type, weight, entity_id)
+                f"""
+                INSERT INTO {fq_table("memory_links")} (from_unit_id, to_unit_id, link_type, weight, entity_id)
                 VALUES ($1, $2, $3, $4, $5)
                 ON CONFLICT (from_unit_id, to_unit_id, link_type, COALESCE(entity_id, '00000000-0000-0000-0000-000000000000'::uuid)) DO NOTHING
                 """,
@@ -721,8 +722,8 @@ async def insert_entity_links_batch(conn, links: list[EntityLink], chunk_size: i
 
     # Insert from temp table with ON CONFLICT (single query for all rows)
     insert_start = time_mod.time()
-    await conn.execute("""
-        INSERT INTO memory_links (from_unit_id, to_unit_id, link_type, weight, entity_id)
+    await conn.execute(f"""
+        INSERT INTO {fq_table("memory_links")} (from_unit_id, to_unit_id, link_type, weight, entity_id)
         SELECT from_unit_id, to_unit_id, link_type, weight, entity_id
         FROM _temp_entity_links
         ON CONFLICT (from_unit_id, to_unit_id, link_type, COALESCE(entity_id, '00000000-0000-0000-0000-000000000000'::uuid)) DO NOTHING
@@ -808,8 +809,8 @@ async def create_causal_links_batch(
             insert_start = time_mod.time()
             try:
                 await conn.executemany(
-                    """
-                    INSERT INTO memory_links (from_unit_id, to_unit_id, link_type, weight, entity_id)
+                    f"""
+                    INSERT INTO {fq_table("memory_links")} (from_unit_id, to_unit_id, link_type, weight, entity_id)
                     VALUES ($1, $2, $3, $4, $5)
                     ON CONFLICT (from_unit_id, to_unit_id, link_type, COALESCE(entity_id, '00000000-0000-0000-0000-000000000000'::uuid)) DO NOTHING
                     """,

hindsight_api/engine/retain/observation_regeneration.py

@@ -9,6 +9,7 @@ import time
 import uuid
 from datetime import UTC, datetime
 
+from ..memory_engine import fq_table
 from ..search import observation_utils
 from . import embedding_utils
 from .types import EntityLink
@@ -75,8 +76,8 @@ async def regenerate_observations_batch(
 
     # Batch query for entity names
     entity_rows = await conn.fetch(
-        """
-        SELECT id, canonical_name FROM entities
+        f"""
+        SELECT id, canonical_name FROM {fq_table("entities")}
         WHERE id = ANY($1) AND bank_id = $2
         """,
         entity_uuids,
@@ -86,10 +87,10 @@ async def regenerate_observations_batch(
 
     # Batch query for fact counts
     fact_counts = await conn.fetch(
-        """
+        f"""
         SELECT ue.entity_id, COUNT(*) as cnt
-        FROM unit_entities ue
-        JOIN memory_units mu ON ue.unit_id = mu.id
+        FROM {fq_table("unit_entities")} ue
+        JOIN {fq_table("memory_units")} mu ON ue.unit_id = mu.id
         WHERE ue.entity_id = ANY($1) AND mu.bank_id = $2
         GROUP BY ue.entity_id
         """,
@@ -154,10 +155,10 @@ async def _regenerate_entity_observations(
 
     # Get all facts mentioning this entity (exclude observations themselves)
     rows = await conn.fetch(
-        """
+        f"""
         SELECT mu.id, mu.text, mu.context, mu.occurred_start, mu.fact_type
-        FROM memory_units mu
-        JOIN unit_entities ue ON mu.id = ue.unit_id
+        FROM {fq_table("memory_units")} mu
+        JOIN {fq_table("unit_entities")} ue ON mu.id = ue.unit_id
         WHERE mu.bank_id = $1
           AND ue.entity_id = $2
           AND mu.fact_type IN ('world', 'experience')
@@ -193,12 +194,12 @@ async def _regenerate_entity_observations(
 
     # Delete old observations for this entity
     await conn.execute(
-        """
-        DELETE FROM memory_units
+        f"""
+        DELETE FROM {fq_table("memory_units")}
         WHERE id IN (
             SELECT mu.id
-            FROM memory_units mu
-            JOIN unit_entities ue ON mu.id = ue.unit_id
+            FROM {fq_table("memory_units")} mu
+            JOIN {fq_table("unit_entities")} ue ON mu.id = ue.unit_id
             WHERE mu.bank_id = $1
               AND mu.fact_type = 'observation'
               AND ue.entity_id = $2
@@ -217,8 +218,8 @@ async def _regenerate_entity_observations(
 
     for obs_text, embedding in zip(observations, embeddings):
         result = await conn.fetchrow(
-            """
-            INSERT INTO memory_units (
+            f"""
+            INSERT INTO {fq_table("memory_units")} (
                 bank_id, text, embedding, context, event_date,
                 occurred_start, occurred_end, mentioned_at,
                 fact_type, access_count
@@ -240,8 +241,8 @@ async def _regenerate_entity_observations(
 
         # Link observation to entity
         await conn.execute(
-            """
-            INSERT INTO unit_entities (unit_id, entity_id)
+            f"""
+            INSERT INTO {fq_table("unit_entities")} (unit_id, entity_id)
             VALUES ($1, $2)
             """,
             uuid.UUID(obs_id),

hindsight_api/engine/retain/orchestrator.py

@@ -8,7 +8,6 @@ import logging
 import time
 import uuid
 from datetime import UTC, datetime
-from typing import Any
 
 from ..db_utils import acquire_with_retry
 from . import bank_utils
@@ -29,7 +28,7 @@ from . import (
     link_creation,
     observation_regeneration,
 )
-from .types import ExtractedFact, ProcessedFact, RetainContent
+from .types import ExtractedFact, ProcessedFact, RetainContent, RetainContentDict
 
 logger = logging.getLogger(__name__)
 
@@ -43,7 +42,7 @@ async def retain_batch(
     format_date_fn,
     duplicate_checker_fn,
     bank_id: str,
-    contents_dicts: list[dict[str, Any]],
+    contents_dicts: list[RetainContentDict],
     document_id: str | None = None,
     is_first_batch: bool = True,
     fact_type_override: str | None = None,

hindsight_api/engine/retain/types.py

@@ -7,9 +7,33 @@ from content input to fact storage.
 
 from dataclasses import dataclass, field
 from datetime import UTC, datetime
+from typing import TypedDict
 from uuid import UUID
 
 
+class RetainContentDict(TypedDict, total=False):
+    """Type definition for content items in retain_batch_async.
+
+    Fields:
+        content: Text content to store (required)
+        context: Context about the content (optional)
+        event_date: When the content occurred (optional, defaults to now)
+        metadata: Custom key-value metadata (optional)
+        document_id: Document ID for this content item (optional)
+    """
+
+    content: str  # Required
+    context: str
+    event_date: datetime
+    metadata: dict[str, str]
+    document_id: str
+
+
+def _now_utc() -> datetime:
+    """Factory function for default event_date."""
+    return datetime.now(UTC)
+
+
 @dataclass
 class RetainContent:
     """
@@ -20,16 +44,9 @@ class RetainContent:
 
     content: str
     context: str = ""
-    event_date: datetime | None = None
+    event_date: datetime = field(default_factory=_now_utc)
     metadata: dict[str, str] = field(default_factory=dict)
 
-    def __post_init__(self):
-        """Ensure event_date is set."""
-        if self.event_date is None:
-            from datetime import datetime
-
-            self.event_date = datetime.now(UTC)
-
 
 @dataclass
 class ChunkMetadata:

hindsight_api/engine/search/graph_retrieval.py

@@ -10,6 +10,7 @@ import logging
 from abc import ABC, abstractmethod
 
 from ..db_utils import acquire_with_retry
+from ..memory_engine import fq_table
 from .types import RetrievalResult
 
 logger = logging.getLogger(__name__)
@@ -139,11 +140,11 @@ class BFSGraphRetriever(GraphRetriever):
 
         # Step 1: Find entry points
         entry_points = await conn.fetch(
-            """
+            f"""
             SELECT id, text, context, event_date, occurred_start, occurred_end,
                    mentioned_at, access_count, embedding, fact_type, document_id, chunk_id,
                    1 - (embedding <=> $1::vector) AS similarity
-            FROM memory_units
+            FROM {fq_table("memory_units")}
             WHERE bank_id = $2
               AND embedding IS NOT NULL
               AND fact_type = $3
@@ -188,13 +189,13 @@ class BFSGraphRetriever(GraphRetriever):
             if batch_nodes and budget_remaining > 0:
                 max_neighbors = len(batch_nodes) * 20
                 neighbors = await conn.fetch(
-                    """
+                    f"""
                     SELECT mu.id, mu.text, mu.context, mu.occurred_start, mu.occurred_end,
                            mu.mentioned_at, mu.access_count, mu.embedding, mu.fact_type,
                            mu.document_id, mu.chunk_id,
                            ml.weight, ml.link_type, ml.from_unit_id
-                    FROM memory_links ml
-                    JOIN memory_units mu ON ml.to_unit_id = mu.id
+                    FROM {fq_table("memory_links")} ml
+                    JOIN {fq_table("memory_units")} mu ON ml.to_unit_id = mu.id
                     WHERE ml.from_unit_id = ANY($1::uuid[])
                       AND ml.weight >= $2
                       AND mu.fact_type = $3

hindsight_api/engine/search/mpfp_retrieval.py

@@ -20,6 +20,7 @@ from collections import defaultdict
 from dataclasses import dataclass, field
 
 from ..db_utils import acquire_with_retry
+from ..memory_engine import fq_table
 from .graph_retrieval import GraphRetriever
 from .types import RetrievalResult
 
@@ -217,10 +218,10 @@ async def load_typed_adjacency(pool, bank_id: str) -> TypedAdjacency:
     """
     async with acquire_with_retry(pool) as conn:
         rows = await conn.fetch(
-            """
+            f"""
             SELECT ml.from_unit_id, ml.to_unit_id, ml.link_type, ml.weight
-            FROM memory_links ml
-            JOIN memory_units mu ON ml.from_unit_id = mu.id
+            FROM {fq_table("memory_links")} ml
+            JOIN {fq_table("memory_units")} mu ON ml.from_unit_id = mu.id
             WHERE mu.bank_id = $1
               AND ml.weight >= 0.1
             ORDER BY ml.from_unit_id, ml.weight DESC
@@ -252,10 +253,10 @@ async def fetch_memory_units_by_ids(
 
     async with acquire_with_retry(pool) as conn:
         rows = await conn.fetch(
-            """
+            f"""
             SELECT id, text, context, event_date, occurred_start, occurred_end,
                    mentioned_at, access_count, embedding, fact_type, document_id, chunk_id
-            FROM memory_units
+            FROM {fq_table("memory_units")}
             WHERE id = ANY($1::uuid[])
               AND fact_type = $2
             """,
@@ -418,9 +419,9 @@ class MPFPGraphRetriever(GraphRetriever):
         """Fallback: find semantic seeds via embedding search."""
         async with acquire_with_retry(pool) as conn:
             rows = await conn.fetch(
-                """
+                f"""
                 SELECT id, 1 - (embedding <=> $1::vector) AS similarity
-                FROM memory_units
+                FROM {fq_table("memory_units")}
                 WHERE bank_id = $2
                   AND embedding IS NOT NULL
                   AND fact_type = $3

hindsight_api/engine/search/reranking.py

@@ -26,6 +26,23 @@ class CrossEncoderReranker:
 
             cross_encoder = create_cross_encoder_from_env()
         self.cross_encoder = cross_encoder
+        self._initialized = False
+
+    async def ensure_initialized(self):
+        """Ensure the cross-encoder model is initialized (for lazy initialization)."""
+        if self._initialized:
+            return
+
+        import asyncio
+
+        cross_encoder = self.cross_encoder
+        # For local providers, run in thread pool to avoid blocking event loop
+        if cross_encoder.provider_name == "local":
+            loop = asyncio.get_event_loop()
+            await loop.run_in_executor(None, lambda: asyncio.run(cross_encoder.initialize()))
+        else:
+            await cross_encoder.initialize()
+        self._initialized = True
 
     def rerank(self, query: str, candidates: list[MergedCandidate]) -> list[ScoredResult]:
         """

hindsight_api/engine/search/retrieval.py

@@ -16,6 +16,7 @@ from typing import Optional
 
 from ...config import get_config
 from ..db_utils import acquire_with_retry
+from ..memory_engine import fq_table
 from .graph_retrieval import BFSGraphRetriever, GraphRetriever
 from .mpfp_retrieval import MPFPGraphRetriever
 from .types import RetrievalResult
@@ -80,10 +81,10 @@ async def retrieve_semantic(
         List of RetrievalResult objects
     """
     results = await conn.fetch(
-        """
+        f"""
         SELECT id, text, context, event_date, occurred_start, occurred_end, mentioned_at, access_count, embedding, fact_type, document_id, chunk_id,
                1 - (embedding <=> $1::vector) AS similarity
-        FROM memory_units
+        FROM {fq_table("memory_units")}
         WHERE bank_id = $2
           AND embedding IS NOT NULL
           AND fact_type = $3
@@ -131,10 +132,10 @@ async def retrieve_bm25(conn, query_text: str, bank_id: str, fact_type: str, lim
     query_tsquery = " | ".join(tokens)
 
     results = await conn.fetch(
-        """
+        f"""
         SELECT id, text, context, event_date, occurred_start, occurred_end, mentioned_at, access_count, embedding, fact_type, document_id, chunk_id,
                ts_rank_cd(search_vector, to_tsquery('english', $1)) AS bm25_score
-        FROM memory_units
+        FROM {fq_table("memory_units")}
         WHERE bank_id = $2
           AND fact_type = $3
           AND search_vector @@ to_tsquery('english', $1)
@@ -188,10 +189,10 @@ async def retrieve_temporal(
         end_date = end_date.replace(tzinfo=UTC)
 
     entry_points = await conn.fetch(
-        """
+        f"""
         SELECT id, text, context, event_date, occurred_start, occurred_end, mentioned_at, access_count, embedding, fact_type, document_id, chunk_id,
                1 - (embedding <=> $1::vector) AS similarity
-        FROM memory_units
+        FROM {fq_table("memory_units")}
         WHERE bank_id = $2
           AND fact_type = $3
           AND embedding IS NOT NULL
@@ -272,12 +273,12 @@ async def retrieve_temporal(
         # Get neighbors via temporal and causal links
         if budget_remaining > 0:
             neighbors = await conn.fetch(
-                """
+                f"""
                 SELECT mu.id, mu.text, mu.context, mu.event_date, mu.occurred_start, mu.occurred_end, mu.mentioned_at, mu.access_count, mu.embedding, mu.fact_type, mu.document_id, mu.chunk_id,
                        ml.weight, ml.link_type,
                        1 - (mu.embedding <=> $1::vector) AS similarity
-                FROM memory_links ml
-                JOIN memory_units mu ON ml.to_unit_id = mu.id
+                FROM {fq_table("memory_links")} ml
+                JOIN {fq_table("memory_units")} mu ON ml.to_unit_id = mu.id
                 WHERE ml.from_unit_id = $2
                   AND ml.link_type IN ('temporal', 'causes', 'caused_by', 'enables', 'prevents')
                   AND ml.weight >= 0.1
@@ -546,11 +547,11 @@ async def _get_temporal_entry_points(
         end_date = end_date.replace(tzinfo=UTC)
 
     rows = await conn.fetch(
-        """
+        f"""
         SELECT id, text, context, event_date, occurred_start, occurred_end, mentioned_at,
                access_count, embedding, fact_type, document_id, chunk_id,
                1 - (embedding <=> $1::vector) AS similarity
-        FROM memory_units
+        FROM {fq_table("memory_units")}
         WHERE bank_id = $2
           AND fact_type = $3
           AND embedding IS NOT NULL

hindsight_api/engine/search/think_utils.py

@@ -101,7 +101,7 @@ def build_think_prompt(
     name: str,
     disposition: DispositionTraits,
     background: str,
-    context: str = None,
+    context: str | None = None,
 ) -> str:
     """Build the think prompt for the LLM."""
     disposition_desc = build_disposition_description(disposition)

hindsight_api/engine/search/tracer.py

@@ -115,7 +115,7 @@ class SearchTracer:
         node_id: str,
         text: str,
         context: str,
-        event_date: datetime,
+        event_date: datetime | None,
         access_count: int,
         is_entry_point: bool,
         parent_node_id: str | None,

hindsight_api/engine/task_backend.py

@@ -89,6 +89,38 @@ class TaskBackend(ABC):
             traceback.print_exc()
 
 
+class SyncTaskBackend(TaskBackend):
+    """
+    Synchronous task backend that executes tasks immediately.
+
+    This is useful for embedded/CLI usage where we don't want background
+    workers that prevent clean exit. Tasks are executed inline rather than
+    being queued.
+    """
+
+    async def initialize(self):
+        """No-op for sync backend."""
+        self._initialized = True
+        logger.debug("SyncTaskBackend initialized")
+
+    async def submit_task(self, task_dict: dict[str, Any]):
+        """
+        Execute the task immediately (synchronously).
+
+        Args:
+            task_dict: Task dictionary to execute
+        """
+        if not self._initialized:
+            await self.initialize()
+
+        await self._execute_task(task_dict)
+
+    async def shutdown(self):
+        """No-op for sync backend."""
+        self._initialized = False
+        logger.debug("SyncTaskBackend shutdown")
+
+
 class AsyncIOQueueBackend(TaskBackend):
     """
     Task backend implementation using asyncio queues.