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

hindsight_api/extensions/operation_validator.py

@@ -0,0 +1,325 @@
+"""Operation Validator Extension for validating retain/recall/reflect operations."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import TYPE_CHECKING, Any
+
+from hindsight_api.extensions.base import Extension
+
+if TYPE_CHECKING:
+    from hindsight_api.engine.memory_engine import Budget
+    from hindsight_api.engine.response_models import RecallResult as RecallResultModel
+    from hindsight_api.engine.response_models import ReflectResult
+    from hindsight_api.models import RequestContext
+
+
+class OperationValidationError(Exception):
+    """Raised when an operation fails validation."""
+
+    def __init__(self, reason: str):
+        self.reason = reason
+        super().__init__(f"Operation validation failed: {reason}")
+
+
+@dataclass
+class ValidationResult:
+    """Result of an operation validation."""
+
+    allowed: bool
+    reason: str | None = None
+
+    @classmethod
+    def accept(cls) -> "ValidationResult":
+        """Create an accepted validation result."""
+        return cls(allowed=True)
+
+    @classmethod
+    def reject(cls, reason: str) -> "ValidationResult":
+        """Create a rejected validation result with a reason."""
+        return cls(allowed=False, reason=reason)
+
+
+# =============================================================================
+# Pre-operation Contexts (all user-provided parameters)
+# =============================================================================
+
+
+@dataclass
+class RetainContext:
+    """Context for a retain operation validation (pre-operation).
+
+    Contains ALL user-provided parameters for the retain operation.
+    """
+
+    bank_id: str
+    contents: list[dict]  # List of {content, context, event_date, document_id}
+    request_context: "RequestContext"
+    document_id: str | None = None
+    fact_type_override: str | None = None
+    confidence_score: float | None = None
+
+
+@dataclass
+class RecallContext:
+    """Context for a recall operation validation (pre-operation).
+
+    Contains ALL user-provided parameters for the recall operation.
+    """
+
+    bank_id: str
+    query: str
+    request_context: "RequestContext"
+    budget: "Budget | None" = None
+    max_tokens: int = 4096
+    enable_trace: bool = False
+    fact_types: list[str] = field(default_factory=list)
+    question_date: datetime | None = None
+    include_entities: bool = False
+    max_entity_tokens: int = 500
+    include_chunks: bool = False
+    max_chunk_tokens: int = 8192
+
+
+@dataclass
+class ReflectContext:
+    """Context for a reflect operation validation (pre-operation).
+
+    Contains ALL user-provided parameters for the reflect operation.
+    """
+
+    bank_id: str
+    query: str
+    request_context: "RequestContext"
+    budget: "Budget | None" = None
+    context: str | None = None
+
+
+# =============================================================================
+# Post-operation Contexts (includes results)
+# =============================================================================
+
+
+@dataclass
+class RetainResult:
+    """Result context for post-retain hook.
+
+    Contains the operation parameters and the result.
+    """
+
+    bank_id: str
+    contents: list[dict]
+    request_context: "RequestContext"
+    document_id: str | None
+    fact_type_override: str | None
+    confidence_score: float | None
+    # Result
+    unit_ids: list[list[str]]  # List of unit IDs per content item
+    success: bool = True
+    error: str | None = None
+
+
+@dataclass
+class RecallResult:
+    """Result context for post-recall hook.
+
+    Contains the operation parameters and the result.
+    """
+
+    bank_id: str
+    query: str
+    request_context: "RequestContext"
+    budget: "Budget | None"
+    max_tokens: int
+    enable_trace: bool
+    fact_types: list[str]
+    question_date: datetime | None
+    include_entities: bool
+    max_entity_tokens: int
+    include_chunks: bool
+    max_chunk_tokens: int
+    # Result
+    result: "RecallResultModel | None" = None
+    success: bool = True
+    error: str | None = None
+
+
+@dataclass
+class ReflectResultContext:
+    """Result context for post-reflect hook.
+
+    Contains the operation parameters and the result.
+    """
+
+    bank_id: str
+    query: str
+    request_context: "RequestContext"
+    budget: "Budget | None"
+    context: str | None
+    # Result
+    result: "ReflectResult | None" = None
+    success: bool = True
+    error: str | None = None
+
+
+class OperationValidatorExtension(Extension, ABC):
+    """
+    Validates and hooks into retain/recall/reflect operations.
+
+    This extension allows implementing custom logic such as:
+    - Rate limiting (pre-operation)
+    - Quota enforcement (pre-operation)
+    - Permission checks (pre-operation)
+    - Content filtering (pre-operation)
+    - Usage tracking (post-operation)
+    - Audit logging (post-operation)
+    - Metrics collection (post-operation)
+
+    Enable via environment variable:
+        HINDSIGHT_API_OPERATION_VALIDATOR_EXTENSION=mypackage.validators:MyValidator
+
+    Configuration is passed from prefixed environment variables:
+        HINDSIGHT_API_OPERATION_VALIDATOR_MAX_REQUESTS=100
+        -> config = {"max_requests": "100"}
+
+    Hook execution order:
+        1. validate_retain/validate_recall/validate_reflect (pre-operation)
+        2. [operation executes]
+        3. on_retain_complete/on_recall_complete/on_reflect_complete (post-operation)
+    """
+
+    # =========================================================================
+    # Pre-operation validation hooks (abstract - must be implemented)
+    # =========================================================================
+
+    @abstractmethod
+    async def validate_retain(self, ctx: RetainContext) -> ValidationResult:
+        """
+        Validate a retain operation before execution.
+
+        Called before the retain operation is processed. Return ValidationResult.reject()
+        to prevent the operation from executing.
+
+        Args:
+            ctx: Context containing all user-provided parameters:
+                - bank_id: Bank identifier
+                - contents: List of content dicts
+                - request_context: Request context with auth info
+                - document_id: Optional document ID
+                - fact_type_override: Optional fact type override
+                - confidence_score: Optional confidence score
+
+        Returns:
+            ValidationResult indicating whether the operation is allowed.
+        """
+        ...
+
+    @abstractmethod
+    async def validate_recall(self, ctx: RecallContext) -> ValidationResult:
+        """
+        Validate a recall operation before execution.
+
+        Called before the recall operation is processed. Return ValidationResult.reject()
+        to prevent the operation from executing.
+
+        Args:
+            ctx: Context containing all user-provided parameters:
+                - bank_id: Bank identifier
+                - query: Search query
+                - request_context: Request context with auth info
+                - budget: Budget level
+                - max_tokens: Maximum tokens to return
+                - enable_trace: Whether to include trace info
+                - fact_types: List of fact types to search
+                - question_date: Optional date context for query
+                - include_entities: Whether to include entity data
+                - max_entity_tokens: Max tokens for entities
+                - include_chunks: Whether to include chunks
+                - max_chunk_tokens: Max tokens for chunks
+
+        Returns:
+            ValidationResult indicating whether the operation is allowed.
+        """
+        ...
+
+    @abstractmethod
+    async def validate_reflect(self, ctx: ReflectContext) -> ValidationResult:
+        """
+        Validate a reflect operation before execution.
+
+        Called before the reflect operation is processed. Return ValidationResult.reject()
+        to prevent the operation from executing.
+
+        Args:
+            ctx: Context containing all user-provided parameters:
+                - bank_id: Bank identifier
+                - query: Question to answer
+                - request_context: Request context with auth info
+                - budget: Budget level
+                - context: Optional additional context
+
+        Returns:
+            ValidationResult indicating whether the operation is allowed.
+        """
+        ...
+
+    # =========================================================================
+    # Post-operation hooks (optional - override to implement)
+    # =========================================================================
+
+    async def on_retain_complete(self, result: RetainResult) -> None:
+        """
+        Called after a retain operation completes (success or failure).
+
+        Override this method to implement post-operation logic such as:
+        - Usage tracking
+        - Audit logging
+        - Metrics collection
+        - Notifications
+
+        Args:
+            result: Result context containing:
+                - All original operation parameters
+                - unit_ids: List of created unit IDs (if success)
+                - success: Whether the operation succeeded
+                - error: Error message (if failed)
+        """
+        pass
+
+    async def on_recall_complete(self, result: RecallResult) -> None:
+        """
+        Called after a recall operation completes (success or failure).
+
+        Override this method to implement post-operation logic such as:
+        - Usage tracking
+        - Audit logging
+        - Metrics collection
+        - Query analytics
+
+        Args:
+            result: Result context containing:
+                - All original operation parameters
+                - result: RecallResultModel (if success)
+                - success: Whether the operation succeeded
+                - error: Error message (if failed)
+        """
+        pass
+
+    async def on_reflect_complete(self, result: ReflectResultContext) -> None:
+        """
+        Called after a reflect operation completes (success or failure).
+
+        Override this method to implement post-operation logic such as:
+        - Usage tracking
+        - Audit logging
+        - Metrics collection
+        - Response analytics
+
+        Args:
+            result: Result context containing:
+                - All original operation parameters
+                - result: ReflectResult (if success)
+                - success: Whether the operation succeeded
+                - error: Error message (if failed)
+        """
+        pass

hindsight_api/extensions/tenant.py

@@ -0,0 +1,63 @@
+"""Tenant Extension for multi-tenancy and API key authentication."""
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+from hindsight_api.extensions.base import Extension
+from hindsight_api.models import RequestContext
+
+
+class AuthenticationError(Exception):
+    """Raised when authentication fails."""
+
+    def __init__(self, reason: str):
+        self.reason = reason
+        super().__init__(f"Authentication failed: {reason}")
+
+
+@dataclass
+class TenantContext:
+    """
+    Tenant context returned by authentication.
+
+    Contains the PostgreSQL schema name for tenant isolation.
+    All database queries will use fully-qualified table names
+    with this schema (e.g., schema_name.memory_units).
+    """
+
+    schema_name: str
+
+
+class TenantExtension(Extension, ABC):
+    """
+    Extension for multi-tenancy and API key authentication.
+
+    This extension validates incoming requests and returns the tenant context
+    including the PostgreSQL schema to use for database operations.
+
+    Built-in implementation:
+        hindsight_api.extensions.builtin.tenant.ApiKeyTenantExtension
+
+    Enable via environment variable:
+        HINDSIGHT_API_TENANT_EXTENSION=hindsight_api.extensions.builtin.tenant:ApiKeyTenantExtension
+        HINDSIGHT_API_TENANT_API_KEY=your-secret-key
+
+    The returned schema_name is used for fully-qualified table names in queries,
+    enabling tenant isolation at the database level.
+    """
+
+    @abstractmethod
+    async def authenticate(self, context: RequestContext) -> TenantContext:
+        """
+        Authenticate the action context and return tenant context.
+
+        Args:
+            context: The action context containing API key and other auth data.
+
+        Returns:
+            TenantContext with the schema_name for database operations.
+
+        Raises:
+            AuthenticationError: If authentication fails.
+        """
+        ...

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,20 +232,40 @@ 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)
+    uvicorn.run(**uvicorn_config)  # type: ignore[invalid-argument-type] - dict kwargs
 
 
 if __name__ == "__main__":

hindsight_api/mcp_local.py

@@ -87,6 +87,7 @@ def create_local_mcp_server(bank_id: str, memory=None) -> FastMCP:
     from hindsight_api import MemoryEngine
     from hindsight_api.engine.memory_engine import Budget
     from hindsight_api.engine.response_models import VALID_RECALL_FACT_TYPES
+    from hindsight_api.models import RequestContext
 
     # Create memory engine with pg0 embedded database if not provided
     if memory is None:
@@ -115,7 +116,11 @@ def create_local_mcp_server(bank_id: str, memory=None) -> FastMCP:
 
         async def _retain():
             try:
-                await memory.retain_batch_async(bank_id=bank_id, contents=[{"content": content, "context": context}])
+                await memory.retain_batch_async(
+                    bank_id=bank_id,
+                    contents=[{"content": content, "context": context}],
+                    request_context=RequestContext(),
+                )
             except Exception as e:
                 logger.error(f"Error storing memory: {e}", exc_info=True)
 
@@ -142,6 +147,7 @@ def create_local_mcp_server(bank_id: str, memory=None) -> FastMCP:
                 fact_type=list(VALID_RECALL_FACT_TYPES),
                 budget=budget_enum,
                 max_tokens=max_tokens,
+                request_context=RequestContext(),
             )
 
             return search_result.model_dump()