hindsight-api 0.0.13__py3-none-any.whl

hindsight_api/engine/task_backend.py

@@ -0,0 +1,223 @@
+"""
+Abstract task backend for running async tasks.
+
+This provides an abstraction that can be adapted to different execution models:
+- AsyncIO queue (default implementation)
+- Pub/Sub architectures (future)
+- Message brokers (future)
+"""
+from abc import ABC, abstractmethod
+from typing import Any, Dict, Optional, Callable, Awaitable
+import asyncio
+import logging
+
+logger = logging.getLogger(__name__)
+
+
+class TaskBackend(ABC):
+    """
+    Abstract base class for task execution backends.
+
+    Implementations must:
+    1. Store/publish task events (as serializable dicts)
+    2. Execute tasks through a provided executor callback
+
+    The backend treats tasks as pure dictionaries that can be serialized
+    and sent over the network. The executor (typically MemoryEngine.execute_task)
+    receives the dict and routes it to the appropriate handler.
+    """
+
+    def __init__(self):
+        """Initialize the task backend."""
+        self._executor: Optional[Callable[[Dict[str, Any]], Awaitable[None]]] = None
+        self._initialized = False
+
+    def set_executor(self, executor: Callable[[Dict[str, Any]], Awaitable[None]]):
+        """
+        Set the executor callback for processing tasks.
+
+        Args:
+            executor: Async function that takes a task dict and executes it
+        """
+        self._executor = executor
+
+    @abstractmethod
+    async def initialize(self):
+        """
+        Initialize the backend (e.g., start workers, connect to broker).
+        """
+        pass
+
+    @abstractmethod
+    async def submit_task(self, task_dict: Dict[str, Any]):
+        """
+        Submit a task for execution.
+
+        Args:
+            task_dict: Task as a dictionary (must be serializable)
+        """
+        pass
+
+    @abstractmethod
+    async def shutdown(self):
+        """
+        Shutdown the backend gracefully (e.g., stop workers, close connections).
+        """
+        pass
+
+    async def _execute_task(self, task_dict: Dict[str, Any]):
+        """
+        Execute a task through the registered executor.
+
+        Args:
+            task_dict: Task dictionary to execute
+        """
+        if self._executor is None:
+            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')
+            logger.error(f"Error executing task {task_type}: {e}")
+            import traceback
+            traceback.print_exc()
+
+
+class AsyncIOQueueBackend(TaskBackend):
+    """
+    Task backend implementation using asyncio queues.
+
+    This is the default implementation that uses in-process asyncio queues
+    and a periodic consumer worker.
+    """
+
+    def __init__(
+        self,
+        batch_size: int = 100,
+        batch_interval: float = 1.0
+    ):
+        """
+        Initialize AsyncIO queue backend.
+
+        Args:
+            batch_size: Maximum number of tasks to process in one batch
+            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._batch_size = batch_size
+        self._batch_interval = batch_interval
+
+    async def initialize(self):
+        """Initialize the queue and start the worker."""
+        if self._initialized:
+            return
+
+        self._queue = asyncio.Queue()
+        self._shutdown_event = asyncio.Event()
+        self._worker_task = asyncio.create_task(self._worker())
+        self._initialized = True
+        logger.info("AsyncIOQueueBackend initialized")
+
+    async def submit_task(self, task_dict: Dict[str, Any]):
+        """
+        Submit a task by putting it in the queue.
+
+        Args:
+            task_dict: Task dictionary to execute
+        """
+        if not self._initialized:
+            await self.initialize()
+
+        await self._queue.put(task_dict)
+        task_type = task_dict.get('type', 'unknown')
+        task_id = task_dict.get('id')
+
+    async def wait_for_pending_tasks(self, timeout: float = 5.0):
+        """
+        Wait for all pending tasks in the queue to be processed.
+
+        This is useful in tests to ensure background tasks complete before assertions.
+
+        Args:
+            timeout: Maximum time to wait in seconds
+        """
+        if not self._initialized or self._queue is None:
+            return
+
+        # Wait for queue to be empty and give worker time to process
+        start_time = asyncio.get_event_loop().time()
+        while asyncio.get_event_loop().time() - start_time < timeout:
+            if self._queue.empty():
+                # Queue is empty, give worker a bit more time to finish any in-flight task
+                await asyncio.sleep(0.3)
+                # Check again - if still empty, we're done
+                if self._queue.empty():
+                    return
+            else:
+                # Queue not empty, wait a bit
+                await asyncio.sleep(0.1)
+
+    async def shutdown(self):
+        """Shutdown the worker and drain the queue."""
+        if not self._initialized:
+            return
+
+        logger.info("Shutting down AsyncIOQueueBackend...")
+
+        # Signal shutdown
+        self._shutdown_event.set()
+
+        # Cancel worker
+        if self._worker_task is not None:
+            self._worker_task.cancel()
+            try:
+                await self._worker_task
+            except asyncio.CancelledError:
+                pass  # Worker cancelled successfully
+
+        self._initialized = False
+        logger.info("AsyncIOQueueBackend shutdown complete")
+
+    async def _worker(self):
+        """
+        Background worker that processes tasks in batches.
+
+        Collects tasks for up to batch_interval seconds or batch_size items,
+        then processes them.
+        """
+        while not self._shutdown_event.is_set():
+            try:
+                # Collect tasks for batching
+                tasks = []
+                deadline = asyncio.get_event_loop().time() + self._batch_interval
+
+                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
+                        )
+                        tasks.append(task_dict)
+                    except asyncio.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
+                    )
+
+            except asyncio.CancelledError:
+                break
+            except Exception as e:
+                logger.error(f"Worker error: {e}")
+                await asyncio.sleep(1)  # Backoff on error

hindsight_api/engine/utils.py

@@ -0,0 +1,203 @@
+"""
+Utility functions for memory system.
+"""
+import logging
+from datetime import datetime
+from typing import List, Dict, TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .llm_wrapper import LLMConfig
+    from .retain.fact_extraction import Fact
+
+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]]]:
+    """
+    Extract semantic facts from text using LLM.
+
+    Uses LLM for intelligent fact extraction that:
+    - Filters out social pleasantries and filler words
+    - Creates self-contained statements with absolute dates
+    - Handles conversational text well
+    - Resolves relative time expressions to absolute dates
+
+    Args:
+        text: Input text (conversation, article, etc.)
+        event_date: Reference date for resolving relative times
+        context: Context about the conversation/document
+        llm_config: LLM configuration to use
+        agent_name: Optional agent name to help identify agent-related facts
+        extract_opinions: If True, extract ONLY opinions. If False, extract world and agent facts (no opinions)
+
+    Returns:
+        Tuple of (facts, chunks) where:
+        - facts: List of Fact model instances
+        - chunks: List of tuples (chunk_text, fact_count) for each chunk
+
+    Raises:
+        Exception: If LLM fact extraction fails
+    """
+    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)
+
+    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}")
+        return [], chunks
+
+    return facts, chunks
+
+
+def cosine_similarity(vec1: List[float], vec2: List[float]) -> float:
+    """
+    Calculate cosine similarity between two vectors.
+
+    Args:
+        vec1: First vector
+        vec2: Second vector
+
+    Returns:
+        Similarity score between 0 and 1
+    """
+    if len(vec1) != len(vec2):
+        raise ValueError("Vectors must have same dimension")
+
+    dot_product = sum(a * b for a, b in zip(vec1, vec2))
+    magnitude1 = sum(a * a for a in vec1) ** 0.5
+    magnitude2 = sum(b * b for b in vec2) ** 0.5
+
+    if magnitude1 == 0 or magnitude2 == 0:
+        return 0.0
+
+    return dot_product / (magnitude1 * magnitude2)
+
+
+def calculate_recency_weight(days_since: float, half_life_days: float = 365.0) -> float:
+    """
+    Calculate recency weight using logarithmic decay.
+
+    This provides much better differentiation over long time periods compared to
+    exponential decay. Uses a log-based decay where the half-life parameter controls
+    when memories reach 50% weight.
+
+    Examples:
+        - Today (0 days): 1.0
+        - 1 year (365 days): ~0.5 (with default half_life=365)
+        - 2 years (730 days): ~0.33
+        - 5 years (1825 days): ~0.17
+        - 10 years (3650 days): ~0.09
+
+    This ensures that 2-year-old and 5-year-old memories have meaningfully
+    different weights, unlike exponential decay which makes them both ~0.
+
+    Args:
+        days_since: Number of days since the memory was created
+        half_life_days: Number of days for weight to reach 0.5 (default: 1 year)
+
+    Returns:
+        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
+    return 1.0 / (1.0 + math.log1p(normalized_age))
+
+
+def calculate_frequency_weight(access_count: int, max_boost: float = 2.0) -> float:
+    """
+    Calculate frequency weight based on access count.
+
+    Frequently accessed memories are weighted higher.
+    Uses logarithmic scaling to avoid over-weighting.
+
+    Args:
+        access_count: Number of times the memory was accessed
+        max_boost: Maximum multiplier for frequently accessed memories
+
+    Returns:
+        Weight between 1.0 and max_boost
+    """
+    import math
+    if access_count <= 0:
+        return 1.0
+
+    # Logarithmic scaling: log(access_count + 1) / log(10)
+    # This gives: 0 accesses = 1.0, 9 accesses ~= 1.5, 99 accesses ~= 2.0
+    normalized = math.log(access_count + 1) / math.log(10)
+    return 1.0 + min(normalized, max_boost - 1.0)
+
+
+def calculate_temporal_anchor(occurred_start: datetime, occurred_end: datetime) -> datetime:
+    """
+    Calculate a single temporal anchor point from a temporal range.
+
+    Used for spreading activation - we need a single representative date
+    to calculate temporal proximity between facts. This simplifies the
+    range-to-range distance problem.
+
+    Strategy: Use midpoint of the range for balanced representation.
+
+    Args:
+        occurred_start: Start of temporal range
+        occurred_end: End of temporal range
+
+    Returns:
+        Single datetime representing the temporal anchor (midpoint)
+
+    Examples:
+        - Point event (July 14): start=July 14, end=July 14 → anchor=July 14
+        - Month range (February): start=Feb 1, end=Feb 28 → anchor=Feb 14
+        - Year range (2023): start=Jan 1, end=Dec 31 → anchor=July 1
+    """
+    # Calculate midpoint
+    time_delta = occurred_end - occurred_start
+    midpoint = occurred_start + (time_delta / 2)
+    return midpoint
+
+
+def calculate_temporal_proximity(
+    anchor_a: datetime,
+    anchor_b: datetime,
+    half_life_days: float = 30.0
+) -> float:
+    """
+    Calculate temporal proximity between two temporal anchors.
+
+    Used for spreading activation to determine how "close" two facts are
+    in time. Uses logarithmic decay so that temporal similarity doesn't
+    drop off too quickly.
+
+    Args:
+        anchor_a: Temporal anchor of first fact
+        anchor_b: Temporal anchor of second fact
+        half_life_days: Number of days for proximity to reach 0.5
+                       (default: 30 days = 1 month)
+
+    Returns:
+        Proximity score in [0, 1] where:
+        - 1.0 = same day
+        - 0.5 = ~half_life days apart
+        - 0.0 = very distant in time
+
+    Examples:
+        - Same day: 1.0
+        - 1 week apart (half_life=30): ~0.7
+        - 1 month apart (half_life=30): ~0.5
+        - 1 year apart (half_life=30): ~0.2
+    """
+    import math
+
+    days_apart = abs((anchor_a - anchor_b).days)
+
+    if days_apart == 0:
+        return 1.0
+
+    # Logarithmic decay: 1 / (1 + log(1 + days_apart/half_life))
+    # Similar to calculate_recency_weight but for proximity between events
+    normalized_distance = days_apart / half_life_days
+    proximity = 1.0 / (1.0 + math.log1p(normalized_distance))
+
+    return proximity

hindsight_api/metrics.py

@@ -0,0 +1,227 @@
+"""
+OpenTelemetry metrics instrumentation for Hindsight API.
+
+This module provides metrics for:
+- Operation latency (retain, recall, reflect) with percentiles
+- Token usage (input/output) per operation
+- Per-bank granularity via labels
+"""
+import logging
+from typing import Dict, Any, Optional
+from contextlib import contextmanager
+import time
+
+from opentelemetry import metrics
+from opentelemetry.sdk.metrics import MeterProvider
+from opentelemetry.sdk.resources import Resource
+from opentelemetry.exporter.prometheus import PrometheusMetricReader
+from prometheus_client import REGISTRY
+
+logger = logging.getLogger(__name__)
+
+# Global meter instance
+_meter = None
+
+
+def initialize_metrics(service_name: str = "hindsight-api", service_version: str = "1.0.0"):
+    """
+    Initialize OpenTelemetry metrics with Prometheus exporter.
+
+    This should be called once during application startup.
+
+    Args:
+        service_name: Name of the service for resource attributes
+        service_version: Version of the service
+
+    Returns:
+        PrometheusMetricReader instance (for accessing metrics endpoint)
+    """
+    global _meter
+
+    # Create resource with service information
+    resource = Resource.create({
+        "service.name": service_name,
+        "service.version": service_version,
+    })
+
+    # Create Prometheus metric reader
+    prometheus_reader = PrometheusMetricReader()
+
+    # Create meter provider with Prometheus exporter
+    provider = MeterProvider(
+        resource=resource,
+        metric_readers=[prometheus_reader]
+    )
+
+    # Set the global meter provider
+    metrics.set_meter_provider(provider)
+
+    # Get meter for this application
+    _meter = metrics.get_meter(__name__)
+
+    return prometheus_reader
+
+
+def get_meter():
+    """Get the global meter instance."""
+    if _meter is None:
+        raise RuntimeError("Metrics not initialized. Call initialize_metrics() first.")
+    return _meter
+
+
+class MetricsCollectorBase:
+    """Base class for metrics collectors."""
+
+    @contextmanager
+    def record_operation(self, operation: str, bank_id: str, budget: Optional[str] = None, max_tokens: Optional[int] = None):
+        """Context manager to record operation duration and status."""
+        raise NotImplementedError
+
+    def record_tokens(self, operation: str, bank_id: str, input_tokens: int = 0, output_tokens: int = 0, budget: Optional[str] = None, max_tokens: Optional[int] = None):
+        """Record token usage for an operation."""
+        raise NotImplementedError
+
+
+class NoOpMetricsCollector(MetricsCollectorBase):
+    """No-op metrics collector that does nothing. Used when metrics are disabled."""
+
+    @contextmanager
+    def record_operation(self, operation: str, bank_id: str, budget: Optional[str] = None, max_tokens: Optional[int] = None):
+        """No-op context manager."""
+        yield
+
+    def record_tokens(self, operation: str, bank_id: str, input_tokens: int = 0, output_tokens: int = 0, budget: Optional[str] = None, max_tokens: Optional[int] = None):
+        """No-op token recording."""
+        pass
+
+
+class MetricsCollector(MetricsCollectorBase):
+    """
+    Collector for Hindsight API metrics.
+
+    Provides methods to record latency and token usage for operations.
+    """
+
+    def __init__(self):
+        self.meter = get_meter()
+
+        # Operation latency histogram (in seconds)
+        # Records duration of retain, recall, reflect operations
+        self.operation_duration = self.meter.create_histogram(
+            name="hindsight.operation.duration",
+            description="Duration of Hindsight operations in seconds",
+            unit="s"
+        )
+
+        # Token usage counters
+        self.tokens_input = self.meter.create_counter(
+            name="hindsight.tokens.input",
+            description="Number of input tokens consumed",
+            unit="tokens"
+        )
+
+        self.tokens_output = self.meter.create_counter(
+            name="hindsight.tokens.output",
+            description="Number of output tokens generated",
+            unit="tokens"
+        )
+
+        # Operation counter (success/failure)
+        self.operation_total = self.meter.create_counter(
+            name="hindsight.operation.total",
+            description="Total number of operations executed",
+            unit="operations"
+        )
+
+    @contextmanager
+    def record_operation(self, operation: str, bank_id: str, budget: Optional[str] = None, max_tokens: Optional[int] = None):
+        """
+        Context manager to record operation duration and status.
+
+        Usage:
+            with metrics.record_operation("recall", bank_id="user123", budget="mid", max_tokens=4096):
+                # ... perform operation
+                pass
+
+        Args:
+            operation: Operation name (retain, recall, reflect)
+            bank_id: Memory bank ID
+            budget: Optional budget level (low, mid, high)
+            max_tokens: Optional max tokens for the operation
+        """
+        start_time = time.time()
+        attributes = {
+            "operation": operation,
+            "bank_id": bank_id,
+        }
+        if budget:
+            attributes["budget"] = budget
+        if max_tokens:
+            attributes["max_tokens"] = str(max_tokens)
+
+        success = True
+        try:
+            yield
+        except Exception:
+            success = False
+            raise
+        finally:
+            duration = time.time() - start_time
+            attributes["success"] = str(success).lower()
+
+            # Record duration
+            self.operation_duration.record(duration, attributes)
+
+            # Record operation count
+            self.operation_total.add(1, attributes)
+
+    def record_tokens(self, operation: str, bank_id: str, input_tokens: int = 0, output_tokens: int = 0, budget: Optional[str] = None, max_tokens: Optional[int] = None):
+        """
+        Record token usage for an operation.
+
+        Args:
+            operation: Operation name (retain, recall, reflect)
+            bank_id: Memory bank ID
+            input_tokens: Number of input tokens
+            output_tokens: Number of output tokens
+            budget: Optional budget level
+            max_tokens: Optional max tokens for the operation
+        """
+        attributes = {
+            "operation": operation,
+            "bank_id": bank_id,
+        }
+        if budget:
+            attributes["budget"] = budget
+        if max_tokens:
+            attributes["max_tokens"] = str(max_tokens)
+
+        if input_tokens > 0:
+            self.tokens_input.add(input_tokens, attributes)
+
+        if output_tokens > 0:
+            self.tokens_output.add(output_tokens, attributes)
+
+
+# Global metrics collector instance (defaults to no-op)
+_metrics_collector: MetricsCollectorBase = NoOpMetricsCollector()
+
+
+def get_metrics_collector() -> MetricsCollectorBase:
+    """
+    Get the global metrics collector instance.
+
+    Returns a no-op collector if metrics are not initialized.
+    """
+    return _metrics_collector
+
+
+def create_metrics_collector() -> MetricsCollector:
+    """
+    Create and set the global metrics collector.
+
+    Should be called after initialize_metrics().
+    """
+    global _metrics_collector
+    _metrics_collector = MetricsCollector()
+    return _metrics_collector