hindsight-api 0.1.12__tar.gz → 0.1.14__tar.gz

{hindsight_api-0.1.12 → hindsight_api-0.1.14}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: hindsight-api
-Version: 0.1.12
+Version: 0.1.14
 Summary: Hindsight: Agent Memory That Works Like Human Memory
 Requires-Python: >=3.11
 Requires-Dist: alembic>=1.17.1

{hindsight_api-0.1.12 → hindsight_api-0.1.14}/hindsight_api/api/http.py

@@ -29,7 +29,7 @@ def _parse_metadata(metadata: Any) -> dict[str, Any]:
     return {}
 
 
-from pydantic import BaseModel, ConfigDict, Field
+from pydantic import BaseModel, ConfigDict, Field, field_validator
 
 from hindsight_api import MemoryEngine
 from hindsight_api.engine.db_utils import acquire_with_retry
@@ -291,7 +291,7 @@ class MemoryItem(BaseModel):
                 "metadata": {"source": "slack", "channel": "engineering"},
                 "document_id": "meeting_notes_2024_01_15",
             }
-        }
+        },
     )
 
     content: str
@@ -300,6 +300,23 @@ class MemoryItem(BaseModel):
     metadata: dict[str, str] | None = None
     document_id: str | None = Field(default=None, description="Optional document ID for this memory item.")
 
+    @field_validator("timestamp", mode="before")
+    @classmethod
+    def validate_timestamp(cls, v):
+        if v is None or v == "":
+            return None
+        if isinstance(v, datetime):
+            return v
+        if isinstance(v, str):
+            try:
+                # Try parsing as ISO format
+                return datetime.fromisoformat(v.replace("Z", "+00:00"))
+            except ValueError as e:
+                raise ValueError(
+                    f"Invalid timestamp/event_date format: '{v}'. Expected ISO format like '2024-01-15T10:30:00' or '2024-01-15T10:30:00Z'"
+                ) from e
+        raise ValueError(f"timestamp must be a string or datetime, got {type(v).__name__}")
+
 
 class RetainRequest(BaseModel):
     """Request model for retain endpoint."""

{hindsight_api-0.1.12 → hindsight_api-0.1.14}/hindsight_api/config.py

@@ -33,6 +33,10 @@ ENV_GRAPH_RETRIEVER = "HINDSIGHT_API_GRAPH_RETRIEVER"
 ENV_MCP_LOCAL_BANK_ID = "HINDSIGHT_API_MCP_LOCAL_BANK_ID"
 ENV_MCP_INSTRUCTIONS = "HINDSIGHT_API_MCP_INSTRUCTIONS"
 
+# Optimization flags
+ENV_SKIP_LLM_VERIFICATION = "HINDSIGHT_API_SKIP_LLM_VERIFICATION"
+ENV_LAZY_RERANKER = "HINDSIGHT_API_LAZY_RERANKER"
+
 # Default values
 DEFAULT_DATABASE_URL = "pg0"
 DEFAULT_LLM_PROVIDER = "openai"
@@ -107,6 +111,10 @@ class HindsightConfig:
     # Recall
     graph_retriever: str
 
+    # Optimization flags
+    skip_llm_verification: bool
+    lazy_reranker: bool
+
     @classmethod
     def from_env(cls) -> "HindsightConfig":
         """Create configuration from environment variables."""
@@ -133,6 +141,9 @@ class HindsightConfig:
             mcp_enabled=os.getenv(ENV_MCP_ENABLED, str(DEFAULT_MCP_ENABLED)).lower() == "true",
             # Recall
             graph_retriever=os.getenv(ENV_GRAPH_RETRIEVER, DEFAULT_GRAPH_RETRIEVER),
+            # Optimization flags
+            skip_llm_verification=os.getenv(ENV_SKIP_LLM_VERIFICATION, "false").lower() == "true",
+            lazy_reranker=os.getenv(ENV_LAZY_RERANKER, "false").lower() == "true",
         )
 
     def get_llm_base_url(self) -> str:

hindsight_api-0.1.14/hindsight_api/daemon.py

@@ -0,0 +1,204 @@
+"""
+Daemon mode support for Hindsight API.
+
+Provides idle timeout and lockfile management for running as a background daemon.
+"""
+
+import asyncio
+import fcntl
+import logging
+import os
+import sys
+import time
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+# Default daemon configuration
+DEFAULT_DAEMON_PORT = 8889
+DEFAULT_IDLE_TIMEOUT = 0  # 0 = no auto-exit (hindsight-embed passes its own timeout)
+LOCKFILE_PATH = Path.home() / ".hindsight" / "daemon.lock"
+DAEMON_LOG_PATH = Path.home() / ".hindsight" / "daemon.log"
+
+
+class IdleTimeoutMiddleware:
+    """ASGI middleware that tracks activity and exits after idle timeout."""
+
+    def __init__(self, app, idle_timeout: int = DEFAULT_IDLE_TIMEOUT):
+        self.app = app
+        self.idle_timeout = idle_timeout
+        self.last_activity = time.time()
+        self._checker_task = None
+
+    async def __call__(self, scope, receive, send):
+        # Update activity timestamp on each request
+        self.last_activity = time.time()
+        await self.app(scope, receive, send)
+
+    def start_idle_checker(self):
+        """Start the background task that checks for idle timeout."""
+        self._checker_task = asyncio.create_task(self._check_idle())
+
+    async def _check_idle(self):
+        """Background task that exits the process after idle timeout."""
+        # If idle_timeout is 0, don't auto-exit
+        if self.idle_timeout <= 0:
+            return
+
+        while True:
+            await asyncio.sleep(30)  # Check every 30 seconds
+            idle_time = time.time() - self.last_activity
+            if idle_time > self.idle_timeout:
+                logger.info(f"Idle timeout reached ({self.idle_timeout}s), shutting down daemon")
+                # Give a moment for any in-flight requests
+                await asyncio.sleep(1)
+                os._exit(0)
+
+
+class DaemonLock:
+    """
+    File-based lock to prevent multiple daemon instances.
+
+    Uses fcntl.flock for atomic locking on Unix systems.
+    """
+
+    def __init__(self, lockfile: Path = LOCKFILE_PATH):
+        self.lockfile = lockfile
+        self._fd = None
+
+    def acquire(self) -> bool:
+        """
+        Try to acquire the daemon lock.
+
+        Returns True if lock acquired, False if another daemon is running.
+        """
+        self.lockfile.parent.mkdir(parents=True, exist_ok=True)
+
+        try:
+            self._fd = open(self.lockfile, "w")
+            fcntl.flock(self._fd.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+            # Write PID for debugging
+            self._fd.write(str(os.getpid()))
+            self._fd.flush()
+            return True
+        except (IOError, OSError):
+            # Lock is held by another process
+            if self._fd:
+                self._fd.close()
+                self._fd = None
+            return False
+
+    def release(self):
+        """Release the daemon lock."""
+        if self._fd:
+            try:
+                fcntl.flock(self._fd.fileno(), fcntl.LOCK_UN)
+                self._fd.close()
+            except Exception:
+                pass
+            finally:
+                self._fd = None
+                # Remove lockfile
+                try:
+                    self.lockfile.unlink()
+                except Exception:
+                    pass
+
+    def is_locked(self) -> bool:
+        """Check if the lock is held by another process."""
+        if not self.lockfile.exists():
+            return False
+
+        try:
+            fd = open(self.lockfile, "r")
+            fcntl.flock(fd.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
+            # We got the lock, so no one else has it
+            fcntl.flock(fd.fileno(), fcntl.LOCK_UN)
+            fd.close()
+            return False
+        except (IOError, OSError):
+            return True
+
+    def get_pid(self) -> int | None:
+        """Get the PID of the daemon holding the lock."""
+        if not self.lockfile.exists():
+            return None
+        try:
+            with open(self.lockfile, "r") as f:
+                return int(f.read().strip())
+        except (ValueError, IOError):
+            return None
+
+
+def daemonize():
+    """
+    Fork the current process into a background daemon.
+
+    Uses double-fork technique to properly detach from terminal.
+    """
+    # First fork
+    pid = os.fork()
+    if pid > 0:
+        # Parent exits
+        sys.exit(0)
+
+    # Create new session
+    os.setsid()
+
+    # Second fork to prevent zombie processes
+    pid = os.fork()
+    if pid > 0:
+        sys.exit(0)
+
+    # Redirect standard file descriptors to log file
+    DAEMON_LOG_PATH.parent.mkdir(parents=True, exist_ok=True)
+
+    sys.stdout.flush()
+    sys.stderr.flush()
+
+    # Redirect stdin to /dev/null
+    with open("/dev/null", "r") as devnull:
+        os.dup2(devnull.fileno(), sys.stdin.fileno())
+
+    # Redirect stdout/stderr to log file
+    log_fd = open(DAEMON_LOG_PATH, "a")
+    os.dup2(log_fd.fileno(), sys.stdout.fileno())
+    os.dup2(log_fd.fileno(), sys.stderr.fileno())
+
+
+def check_daemon_running(port: int = DEFAULT_DAEMON_PORT) -> bool:
+    """Check if a daemon is running and responsive on the given port."""
+    import socket
+
+    try:
+        sock = socket.socket(socket.AF_INET, socket.SOCK_STREAM)
+        sock.settimeout(1)
+        result = sock.connect_ex(("127.0.0.1", port))
+        sock.close()
+        return result == 0
+    except Exception:
+        return False
+
+
+def stop_daemon(port: int = DEFAULT_DAEMON_PORT) -> bool:
+    """Stop a running daemon by sending SIGTERM to the process."""
+    lock = DaemonLock()
+    pid = lock.get_pid()
+
+    if pid is None:
+        return False
+
+    try:
+        import signal
+
+        os.kill(pid, signal.SIGTERM)
+        # Wait for process to exit
+        for _ in range(50):  # Wait up to 5 seconds
+            time.sleep(0.1)
+            try:
+                os.kill(pid, 0)  # Check if process exists
+            except OSError:
+                return True  # Process exited
+        return False
+    except OSError:
+        return False

{hindsight_api-0.1.12 → hindsight_api-0.1.14}/hindsight_api/engine/memory_engine.py

@@ -202,6 +202,8 @@ class MemoryEngine(MemoryEngineInterface):
         run_migrations: bool = True,
         operation_validator: "OperationValidatorExtension | None" = None,
         tenant_extension: "TenantExtension | None" = None,
+        skip_llm_verification: bool | None = None,
+        lazy_reranker: bool | None = None,
     ):
         """
         Initialize the temporal + semantic memory system.
@@ -227,12 +229,23 @@ class MemoryEngine(MemoryEngineInterface):
                                 If provided, retain/recall/reflect operations will be validated.
             tenant_extension: Optional extension for multi-tenancy and API key authentication.
                              If provided, operations require a RequestContext for authentication.
+            skip_llm_verification: Skip LLM connection verification during initialization.
+                                  Defaults to HINDSIGHT_API_SKIP_LLM_VERIFICATION env var or False.
+            lazy_reranker: Delay reranker initialization until first use. Useful for retain-only
+                          operations that don't need the cross-encoder. Defaults to
+                          HINDSIGHT_API_LAZY_RERANKER env var or False.
         """
         # Load config from environment for any missing parameters
         from ..config import get_config
 
         config = get_config()
 
+        # Apply optimization flags from config if not explicitly provided
+        self._skip_llm_verification = (
+            skip_llm_verification if skip_llm_verification is not None else config.skip_llm_verification
+        )
+        self._lazy_reranker = lazy_reranker if lazy_reranker is not None else config.lazy_reranker
+
         # Apply defaults from config
         db_url = db_url or config.database_url
         memory_llm_provider = memory_llm_provider or config.llm_provider
@@ -396,22 +409,22 @@ class MemoryEngine(MemoryEngineInterface):
 
         Args:
             task_dict: Dict with 'node_ids' key containing list of node IDs to update
+
+        Raises:
+            Exception: Any exception from database operations (propagates to execute_task for retry)
         """
         node_ids = task_dict.get("node_ids", [])
         if not node_ids:
             return
 
         pool = await self._get_pool()
-        try:
-            # Convert string UUIDs to UUID type for faster matching
-            uuid_list = [uuid.UUID(nid) for nid in node_ids]
-            async with acquire_with_retry(pool) as conn:
-                await conn.execute(
-                    f"UPDATE {fq_table('memory_units')} SET access_count = access_count + 1 WHERE id = ANY($1::uuid[])",
-                    uuid_list,
-                )
-        except Exception as e:
-            logger.error(f"Access count handler: Error updating access counts: {e}")
+        # Convert string UUIDs to UUID type for faster matching
+        uuid_list = [uuid.UUID(nid) for nid in node_ids]
+        async with acquire_with_retry(pool) as conn:
+            await conn.execute(
+                f"UPDATE {fq_table('memory_units')} SET access_count = access_count + 1 WHERE id = ANY($1::uuid[])",
+                uuid_list,
+            )
 
     async def _handle_batch_retain(self, task_dict: dict[str, Any]):
         """
@@ -419,29 +432,27 @@ class MemoryEngine(MemoryEngineInterface):
 
         Args:
             task_dict: Dict with 'bank_id', 'contents'
-        """
-        try:
-            bank_id = task_dict.get("bank_id")
-            if not bank_id:
-                raise ValueError("bank_id is required for batch retain task")
-            contents = task_dict.get("contents", [])
 
-            logger.info(
-                f"[BATCH_RETAIN_TASK] Starting background batch retain for bank_id={bank_id}, {len(contents)} items"
-            )
+        Raises:
+            ValueError: If bank_id is missing
+            Exception: Any exception from retain_batch_async (propagates to execute_task for retry)
+        """
+        bank_id = task_dict.get("bank_id")
+        if not bank_id:
+            raise ValueError("bank_id is required for batch retain task")
+        contents = task_dict.get("contents", [])
 
-            # Use internal request context for background tasks
-            from hindsight_api.models import RequestContext
+        logger.info(
+            f"[BATCH_RETAIN_TASK] Starting background batch retain for bank_id={bank_id}, {len(contents)} items"
+        )
 
-            internal_context = RequestContext()
-            await self.retain_batch_async(bank_id=bank_id, contents=contents, request_context=internal_context)
+        # Use internal request context for background tasks
+        from hindsight_api.models import RequestContext
 
-            logger.info(f"[BATCH_RETAIN_TASK] Completed background batch retain for bank_id={bank_id}")
-        except Exception as e:
-            logger.error(f"Batch retain handler: Error processing batch retain: {e}")
-            import traceback
+        internal_context = RequestContext()
+        await self.retain_batch_async(bank_id=bank_id, contents=contents, request_context=internal_context)
 
-            traceback.print_exc()
+        logger.info(f"[BATCH_RETAIN_TASK] Completed background batch retain for bank_id={bank_id}")
 
     async def execute_task(self, task_dict: dict[str, Any]):
         """
@@ -594,6 +605,8 @@ class MemoryEngine(MemoryEngineInterface):
                 await loop.run_in_executor(None, lambda: asyncio.run(cross_encoder.initialize()))
             else:
                 await cross_encoder.initialize()
+            # Mark reranker as initialized
+            self._cross_encoder_reranker._initialized = True
 
         async def init_query_analyzer():
             """Initialize query analyzer model."""
@@ -602,16 +615,26 @@ class MemoryEngine(MemoryEngineInterface):
 
         async def verify_llm():
             """Verify LLM connection is working."""
-            await self._llm_config.verify_connection()
+            if not self._skip_llm_verification:
+                await self._llm_config.verify_connection()
 
-        # Run pg0 and all model initializations in parallel
-        await asyncio.gather(
+        # Build list of initialization tasks
+        init_tasks = [
             start_pg0(),
             init_embeddings(),
-            init_cross_encoder(),
             init_query_analyzer(),
-            verify_llm(),
-        )
+        ]
+
+        # Only init cross-encoder eagerly if not using lazy initialization
+        if not self._lazy_reranker:
+            init_tasks.append(init_cross_encoder())
+
+        # Only verify LLM if not skipping
+        if not self._skip_llm_verification:
+            init_tasks.append(verify_llm())
+
+        # Run pg0 and selected model initializations in parallel
+        await asyncio.gather(*init_tasks)
 
         # Run database migrations if enabled
         if self._run_migrations:
@@ -1641,6 +1664,9 @@ class MemoryEngine(MemoryEngineInterface):
             step_start = time.time()
             reranker_instance = self._cross_encoder_reranker
 
+            # Ensure reranker is initialized (for lazy initialization mode)
+            await reranker_instance.ensure_initialized()
+
             # Rerank using cross-encoder
             scored_results = reranker_instance.rerank(query, merged_candidates)
 
@@ -3649,90 +3675,87 @@ Guidelines:
             task_dict: Dict with 'bank_id' and either:
                        - 'entity_ids' (list): Process multiple entities
                        - 'entity_id', 'entity_name': Process single entity (legacy)
+
+        Raises:
+            ValueError: If required fields are missing
+            Exception: Any exception from regenerate_entity_observations (propagates to execute_task for retry)
         """
-        try:
-            bank_id = task_dict.get("bank_id")
-            # Use internal request context for background tasks
-            from hindsight_api.models import RequestContext
+        bank_id = task_dict.get("bank_id")
+        # Use internal request context for background tasks
+        from hindsight_api.models import RequestContext
 
-            internal_context = RequestContext()
+        internal_context = RequestContext()
 
-            # New format: multiple entity_ids
-            if "entity_ids" in task_dict:
-                entity_ids = task_dict.get("entity_ids", [])
-                min_facts = task_dict.get("min_facts", 5)
+        # New format: multiple entity_ids
+        if "entity_ids" in task_dict:
+            entity_ids = task_dict.get("entity_ids", [])
+            min_facts = task_dict.get("min_facts", 5)
 
-                if not bank_id or not entity_ids:
-                    logger.error(f"[OBSERVATIONS] Missing required fields in task: {task_dict}")
-                    return
+            if not bank_id or not entity_ids:
+                raise ValueError(f"[OBSERVATIONS] Missing required fields in task: {task_dict}")
 
-                # Process each entity
-                pool = await self._get_pool()
-                async with pool.acquire() as conn:
-                    for entity_id in entity_ids:
-                        try:
-                            # Fetch entity name and check fact count
-                            import uuid as uuid_module
+            # Process each entity
+            pool = await self._get_pool()
+            async with pool.acquire() as conn:
+                for entity_id in entity_ids:
+                    try:
+                        # Fetch entity name and check fact count
+                        import uuid as uuid_module
 
-                            entity_uuid = uuid_module.UUID(entity_id) if isinstance(entity_id, str) else entity_id
+                        entity_uuid = uuid_module.UUID(entity_id) if isinstance(entity_id, str) else entity_id
 
-                            # First check if entity exists
-                            entity_exists = await conn.fetchrow(
-                                f"SELECT canonical_name FROM {fq_table('entities')} WHERE id = $1 AND bank_id = $2",
-                                entity_uuid,
-                                bank_id,
-                            )
+                        # First check if entity exists
+                        entity_exists = await conn.fetchrow(
+                            f"SELECT canonical_name FROM {fq_table('entities')} WHERE id = $1 AND bank_id = $2",
+                            entity_uuid,
+                            bank_id,
+                        )
 
-                            if not entity_exists:
-                                logger.debug(f"[OBSERVATIONS] Entity {entity_id} not yet in bank {bank_id}, skipping")
-                                continue
+                        if not entity_exists:
+                            logger.debug(f"[OBSERVATIONS] Entity {entity_id} not yet in bank {bank_id}, skipping")
+                            continue
 
-                            entity_name = entity_exists["canonical_name"]
+                        entity_name = entity_exists["canonical_name"]
 
-                            # Count facts linked to this entity
-                            fact_count = (
-                                await conn.fetchval(
-                                    f"SELECT COUNT(*) FROM {fq_table('unit_entities')} WHERE entity_id = $1",
-                                    entity_uuid,
-                                )
-                                or 0
+                        # Count facts linked to this entity
+                        fact_count = (
+                            await conn.fetchval(
+                                f"SELECT COUNT(*) FROM {fq_table('unit_entities')} WHERE entity_id = $1",
+                                entity_uuid,
                             )
+                            or 0
+                        )
 
-                            # Only regenerate if entity has enough facts
-                            if fact_count >= min_facts:
-                                await self.regenerate_entity_observations(
-                                    bank_id, entity_id, entity_name, version=None, request_context=internal_context
-                                )
-                            else:
-                                logger.debug(
-                                    f"[OBSERVATIONS] Skipping {entity_name} ({fact_count} facts < {min_facts} threshold)"
-                                )
-
-                        except Exception as e:
-                            logger.error(f"[OBSERVATIONS] Error processing entity {entity_id}: {e}")
-                            continue
-
-            # Legacy format: single entity
-            else:
-                entity_id = task_dict.get("entity_id")
-                entity_name = task_dict.get("entity_name")
-                version = task_dict.get("version")
+                        # Only regenerate if entity has enough facts
+                        if fact_count >= min_facts:
+                            await self.regenerate_entity_observations(
+                                bank_id, entity_id, entity_name, version=None, request_context=internal_context
+                            )
+                        else:
+                            logger.debug(
+                                f"[OBSERVATIONS] Skipping {entity_name} ({fact_count} facts < {min_facts} threshold)"
+                            )
 
-                if not all([bank_id, entity_id, entity_name]):
-                    logger.error(f"[OBSERVATIONS] Missing required fields in task: {task_dict}")
-                    return
+                    except Exception as e:
+                        # Log but continue processing other entities - individual entity failures
+                        # shouldn't fail the whole batch
+                        logger.error(f"[OBSERVATIONS] Error processing entity {entity_id}: {e}")
+                        continue
 
-                # Type assertions after validation
-                assert isinstance(bank_id, str) and isinstance(entity_id, str) and isinstance(entity_name, str)
-                await self.regenerate_entity_observations(
-                    bank_id, entity_id, entity_name, version=version, request_context=internal_context
-                )
+        # Legacy format: single entity
+        else:
+            entity_id = task_dict.get("entity_id")
+            entity_name = task_dict.get("entity_name")
+            version = task_dict.get("version")
 
-        except Exception as e:
-            logger.error(f"[OBSERVATIONS] Error regenerating observations: {e}")
-            import traceback
+            if not all([bank_id, entity_id, entity_name]):
+                raise ValueError(f"[OBSERVATIONS] Missing required fields in task: {task_dict}")
 
-            traceback.print_exc()
+            # Type assertions after validation
+            assert isinstance(bank_id, str) and isinstance(entity_id, str) and isinstance(entity_name, str)
+            await self.regenerate_entity_observations(
+                bank_id, entity_id, entity_name, version=version, request_context=internal_context
+            )
 
     # =========================================================================
     # Statistics & Operations (for HTTP API layer)

{hindsight_api-0.1.12 → hindsight_api-0.1.14}/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-0.1.12 → hindsight_api-0.1.14}/hindsight_api/main.py

@@ -4,6 +4,9 @@ Command-line interface for Hindsight API.
 Run the server with:
     hindsight-api
 
+Run as background daemon:
+    hindsight-api --daemon
+
 Stop with Ctrl+C.
 """
 
@@ -21,9 +24,13 @@ from . import MemoryEngine
 from .api import create_app
 from .banner import print_banner
 from .config import HindsightConfig, get_config
-
-print()
-print_banner()
+from .daemon import (
+    DEFAULT_DAEMON_PORT,
+    DEFAULT_IDLE_TIMEOUT,
+    DaemonLock,
+    IdleTimeoutMiddleware,
+    daemonize,
+)
 
 # Filter deprecation warnings from third-party libraries
 warnings.filterwarnings("ignore", message="websockets.legacy is deprecated")
@@ -106,8 +113,52 @@ def main():
     parser.add_argument("--ssl-keyfile", default=None, help="SSL key file")
     parser.add_argument("--ssl-certfile", default=None, help="SSL certificate file")
 
+    # Daemon mode options
+    parser.add_argument(
+        "--daemon",
+        action="store_true",
+        help=f"Run as background daemon (uses port {DEFAULT_DAEMON_PORT}, auto-exits after idle)",
+    )
+    parser.add_argument(
+        "--idle-timeout",
+        type=int,
+        default=DEFAULT_IDLE_TIMEOUT,
+        help=f"Idle timeout in seconds before auto-exit in daemon mode (default: {DEFAULT_IDLE_TIMEOUT})",
+    )
+
     args = parser.parse_args()
 
+    # Daemon mode handling
+    if args.daemon:
+        # Use fixed daemon port
+        args.port = DEFAULT_DAEMON_PORT
+        args.host = "127.0.0.1"  # Only bind to localhost for security
+
+        # Check if another daemon is already running
+        daemon_lock = DaemonLock()
+        if not daemon_lock.acquire():
+            print(f"Daemon already running (PID: {daemon_lock.get_pid()})", file=sys.stderr)
+            sys.exit(1)
+
+        # Fork into background
+        daemonize()
+
+        # Re-acquire lock in child process
+        daemon_lock = DaemonLock()
+        if not daemon_lock.acquire():
+            sys.exit(1)
+
+        # Register cleanup to release lock
+        def release_lock():
+            daemon_lock.release()
+
+        atexit.register(release_lock)
+
+    # Print banner (not in daemon mode)
+    if not args.daemon:
+        print()
+        print_banner()
+
     # Configure Python logging based on log level
     # Update config with CLI override if provided
     if args.log_level != config.log_level:
@@ -128,9 +179,12 @@ def main():
             log_level=args.log_level,
             mcp_enabled=config.mcp_enabled,
             graph_retriever=config.graph_retriever,
+            skip_llm_verification=config.skip_llm_verification,
+            lazy_reranker=config.lazy_reranker,
         )
     config.configure_logging()
-    config.log_config()
+    if not args.daemon:
+        config.log_config()
 
     # Register cleanup handlers
     atexit.register(_cleanup)
@@ -149,6 +203,12 @@ def main():
         initialize_memory=True,
     )
 
+    # Wrap with idle timeout middleware in daemon mode
+    idle_middleware = None
+    if args.daemon:
+        idle_middleware = IdleTimeoutMiddleware(app, idle_timeout=args.idle_timeout)
+        app = idle_middleware
+
     # Prepare uvicorn config
     uvicorn_config = {
         "app": app,
@@ -172,18 +232,38 @@ 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,
-        database_url=config.database_url,
-        llm_provider=config.llm_provider,
-        llm_model=config.llm_model,
-        embeddings_provider=config.embeddings_provider,
-        reranker_provider=config.reranker_provider,
-        mcp_enabled=config.mcp_enabled,
-    )
+    # Print startup info (not in daemon mode)
+    if not args.daemon:
+        from .banner import print_startup_info
+
+        print_startup_info(
+            host=args.host,
+            port=args.port,
+            database_url=config.database_url,
+            llm_provider=config.llm_provider,
+            llm_model=config.llm_model,
+            embeddings_provider=config.embeddings_provider,
+            reranker_provider=config.reranker_provider,
+            mcp_enabled=config.mcp_enabled,
+        )
+
+    # Start idle checker in daemon mode
+    if idle_middleware is not None:
+        # Start the idle checker in a background thread with its own event loop
+        import threading
+
+        def run_idle_checker():
+            import time
+
+            time.sleep(2)  # Wait for uvicorn to start
+            try:
+                loop = asyncio.new_event_loop()
+                asyncio.set_event_loop(loop)
+                loop.run_until_complete(idle_middleware._check_idle())
+            except Exception:
+                pass
+
+        threading.Thread(target=run_idle_checker, daemon=True).start()
 
     uvicorn.run(**uvicorn_config)  # type: ignore[invalid-argument-type] - dict kwargs
 

{hindsight_api-0.1.12 → hindsight_api-0.1.14}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "hindsight-api"
-version = "0.1.12"
+version = "0.1.14"
 description = "Hindsight: Agent Memory That Works Like Human Memory"
 readme = "README.md"
 requires-python = ">=3.11"