omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/handlers/handler_intent.py

@@ -0,0 +1,387 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Intent Handler - Temporary demo wiring for intent graph operations.
+
+Wraps HandlerGraph to provide intent-specific graph operations for the demo.
+This is temporary hardcoded routing that will be replaced by contract-driven
+handler routing in production.
+
+Supported Operations:
+    - intent.store: Store an intent as a graph node with label "Intent"
+    - intent.query_session: Query intents by session_id property
+    - intent.query_distribution: Get intent count/statistics
+
+Note:
+    This is TEMPORARY demo wiring. Keep it simple and focused on the demo use case.
+    Production implementation should use contract-driven handler routing.
+"""
+
+# TODO(OMN-1515): Remove demo wiring after intent routing is contract-driven
+
+from __future__ import annotations
+
+import logging
+from uuid import UUID, uuid4
+
+from omnibase_core.container import ModelONEXContainer
+from omnibase_core.types import JsonType
+from omnibase_infra.enums import EnumInfraTransportType
+from omnibase_infra.errors import (
+    ModelInfraErrorContext,
+    RuntimeHostError,
+)
+from omnibase_infra.handlers.handler_graph import HandlerGraph
+from omnibase_infra.mixins import MixinEnvelopeExtraction
+
+logger = logging.getLogger(__name__)
+
+HANDLER_ID_INTENT: str = "intent-handler"
+_SUPPORTED_OPERATIONS: frozenset[str] = frozenset(
+    {
+        "intent.store",
+        "intent.query_session",
+        "intent.query_distribution",
+    }
+)
+
+
+class HandlerIntent(MixinEnvelopeExtraction):  # DEMO ONLY
+    """Intent handler wrapping HandlerGraph for intent-specific operations.
+
+    This handler provides a simplified interface for storing and querying
+    intents in the graph database. It wraps HandlerGraph and translates
+    intent-specific operations to graph operations.
+
+    Note:
+        This is temporary demo wiring. The handler assumes HandlerGraph
+        is already initialized and passed via config during initialize().
+
+    Idempotency:
+        - intent.store: NOT idempotent (creates new node each call)
+        - intent.query_session: Idempotent (read-only query)
+        - intent.query_distribution: Idempotent (read-only aggregation)
+    """
+
+    def __init__(self, container: ModelONEXContainer) -> None:
+        """Initialize HandlerIntent with ONEX container for dependency injection.
+
+        Args:
+            container: ONEX container for dependency injection.
+        """
+        self._container = container
+        self._graph_handler: HandlerGraph | None = None
+        self._initialized: bool = False
+
+    async def initialize(self, config: dict[str, object]) -> None:
+        """Initialize the intent handler.
+
+        Args:
+            config: Configuration dict containing:
+                - graph_handler: Pre-initialized HandlerGraph instance (required)
+
+        Raises:
+            RuntimeHostError: If graph_handler is missing or invalid.
+        """
+        init_correlation_id = uuid4()
+
+        logger.info(
+            "Initializing %s",
+            self.__class__.__name__,
+            extra={
+                "handler": self.__class__.__name__,
+                "correlation_id": str(init_correlation_id),
+            },
+        )
+
+        graph_handler = config.get("graph_handler")
+        if not isinstance(graph_handler, HandlerGraph):
+            ctx = ModelInfraErrorContext.with_correlation(
+                transport_type=EnumInfraTransportType.GRAPH,
+                operation="initialize",
+                target_name="intent_handler",
+                correlation_id=init_correlation_id,
+            )
+            raise RuntimeHostError(
+                "Missing or invalid 'graph_handler' in config - "
+                "must be an initialized HandlerGraph instance",
+                context=ctx,
+            )
+
+        self._graph_handler = graph_handler
+        self._initialized = True
+
+        logger.info(
+            "%s initialized successfully",
+            self.__class__.__name__,
+            extra={
+                "handler": self.__class__.__name__,
+                "correlation_id": str(init_correlation_id),
+            },
+        )
+
+    async def shutdown(self) -> None:
+        """Shutdown the intent handler.
+
+        Note:
+            This handler does not own the graph handler, so we do not
+            shut it down here. The caller is responsible for managing
+            the graph handler lifecycle.
+        """
+        self._graph_handler = None
+        self._initialized = False
+        logger.info("HandlerIntent shutdown complete")
+
+    async def execute(self, envelope: dict[str, object]) -> dict[str, object]:
+        """Execute intent operation from envelope.
+
+        Args:
+            envelope: Request envelope containing:
+                - operation: Intent operation (intent.store, intent.query_session, etc.)
+                - payload: dict with operation-specific parameters
+                - correlation_id: Optional correlation ID for tracing
+                - envelope_id: Optional envelope ID for causality tracking
+
+        Returns:
+            dict containing operation result with:
+                - success: bool indicating operation success
+                - data: Operation-specific result data
+                - correlation_id: UUID string for tracing
+
+        Raises:
+            RuntimeHostError: If handler not initialized or invalid input.
+        """
+        correlation_id = self._extract_correlation_id(envelope)
+
+        if not self._initialized or self._graph_handler is None:
+            ctx = ModelInfraErrorContext.with_correlation(
+                transport_type=EnumInfraTransportType.GRAPH,
+                operation="execute",
+                target_name="intent_handler",
+                correlation_id=correlation_id,
+            )
+            raise RuntimeHostError(
+                "HandlerIntent not initialized. Call initialize() first.",
+                context=ctx,
+            )
+
+        operation = envelope.get("operation")
+        if not isinstance(operation, str):
+            ctx = ModelInfraErrorContext.with_correlation(
+                transport_type=EnumInfraTransportType.GRAPH,
+                operation="execute",
+                target_name="intent_handler",
+                correlation_id=correlation_id,
+            )
+            raise RuntimeHostError(
+                "Missing or invalid 'operation' in envelope",
+                context=ctx,
+            )
+
+        if operation not in _SUPPORTED_OPERATIONS:
+            ctx = ModelInfraErrorContext.with_correlation(
+                transport_type=EnumInfraTransportType.GRAPH,
+                operation=operation,
+                target_name="intent_handler",
+                correlation_id=correlation_id,
+            )
+            raise RuntimeHostError(
+                f"Operation '{operation}' not supported. "
+                f"Available: {', '.join(sorted(_SUPPORTED_OPERATIONS))}",
+                context=ctx,
+            )
+
+        payload = envelope.get("payload")
+        if not isinstance(payload, dict):
+            ctx = ModelInfraErrorContext.with_correlation(
+                transport_type=EnumInfraTransportType.GRAPH,
+                operation=operation,
+                target_name="intent_handler",
+                correlation_id=correlation_id,
+            )
+            raise RuntimeHostError(
+                "Missing or invalid 'payload' in envelope",
+                context=ctx,
+            )
+
+        # Route to appropriate handler method
+        if operation == "intent.store":
+            return await self._store_intent(payload, correlation_id)
+        elif operation == "intent.query_session":
+            return await self._query_session(payload, correlation_id)
+        else:  # intent.query_distribution
+            return await self._query_distribution(correlation_id)
+
+    async def _store_intent(
+        self, payload: dict[str, object], correlation_id: UUID
+    ) -> dict[str, object]:
+        """Store an intent as a graph node.
+
+        Args:
+            payload: Intent data to store. Should contain:
+                - intent_type: Type of intent (required)
+                - session_id: Session identifier (optional)
+                - Additional properties as needed
+
+        Returns:
+            dict with created node details.
+        """
+        # Note: _graph_handler is guaranteed non-None by execute() validation
+        assert self._graph_handler is not None  # Type narrowing for mypy
+
+        # Extract intent properties - use JsonType for graph compatibility
+        properties: dict[str, JsonType] = {
+            "correlation_id": str(correlation_id),
+        }
+
+        # Copy all payload properties to node properties
+        for key, value in payload.items():
+            # Convert non-primitive types to strings for graph storage
+            # NOTE: Using tuple form for isinstance to avoid union validator flag
+            if isinstance(value, (str, int, float, bool)) or value is None:
+                properties[key] = value
+            else:
+                properties[key] = str(value)
+
+        # Create the intent node
+        node = await self._graph_handler.create_node(
+            labels=["Intent"],
+            properties=properties,
+        )
+
+        return {
+            "success": True,
+            "data": {
+                "node_id": node.id,
+                "element_id": node.element_id,
+                "labels": node.labels,
+                "properties": node.properties,
+            },
+            "correlation_id": str(correlation_id),
+        }
+
+    async def _query_session(
+        self, payload: dict[str, object], correlation_id: UUID
+    ) -> dict[str, object]:
+        """Query intents by session_id.
+
+        Args:
+            payload: Query parameters. Should contain:
+                - session_id: Session identifier to filter by (required)
+
+        Returns:
+            dict with matching intent nodes.
+        """
+        # Note: _graph_handler is guaranteed non-None by execute() validation
+        assert self._graph_handler is not None  # Type narrowing for mypy
+
+        session_id = payload.get("session_id")
+        if not session_id:
+            ctx = ModelInfraErrorContext.with_correlation(
+                transport_type=EnumInfraTransportType.GRAPH,
+                operation="intent.query_session",
+                target_name="intent_handler",
+                correlation_id=correlation_id,
+            )
+            raise RuntimeHostError(
+                "Missing 'session_id' in payload",
+                context=ctx,
+            )
+
+        # Query intents by session_id
+        # SECURITY: Using parameterized query ($session_id) to prevent Cypher injection
+        query = """
+        MATCH (i:Intent {session_id: $session_id})
+        RETURN i, elementId(i) as eid, id(i) as nid
+        ORDER BY i.created_at DESC
+        """
+
+        result = await self._graph_handler.execute_query(
+            query=query,
+            parameters={"session_id": str(session_id)},
+        )
+
+        # Transform records to intent data
+        intents = []
+        for record in result.records:
+            node = record.get("i")
+            if node:
+                intents.append(
+                    {
+                        "node_id": str(record.get("nid", "")),
+                        "element_id": str(record.get("eid", "")),
+                        "properties": dict(node) if isinstance(node, dict) else {},
+                    }
+                )
+
+        return {
+            "success": True,
+            "data": {
+                "session_id": str(session_id),
+                "intents": intents,
+                "count": len(intents),
+            },
+            "correlation_id": str(correlation_id),
+        }
+
+    async def _query_distribution(self, correlation_id: UUID) -> dict[str, object]:
+        """Query intent distribution/statistics.
+
+        Returns:
+            dict with intent statistics including counts by intent_type.
+        """
+        # Note: _graph_handler is guaranteed non-None by execute() validation
+        assert self._graph_handler is not None  # Type narrowing for mypy
+
+        # Query total count
+        count_query = "MATCH (i:Intent) RETURN count(i) as total"
+        count_result = await self._graph_handler.execute_query(query=count_query)
+
+        total_count = 0
+        if count_result.records:
+            raw_total = count_result.records[0].get("total", 0)
+            total_count = int(raw_total) if isinstance(raw_total, int | float) else 0
+
+        # Query distribution by intent_type
+        distribution_query = """
+        MATCH (i:Intent)
+        RETURN i.intent_type as intent_type, count(i) as count
+        ORDER BY count DESC
+        """
+        distribution_result = await self._graph_handler.execute_query(
+            query=distribution_query
+        )
+
+        # Build distribution dict
+        distribution: dict[str, int] = {}
+        for record in distribution_result.records:
+            intent_type = record.get("intent_type")
+            raw_count = record.get("count", 0)
+            if intent_type:
+                count_val = int(raw_count) if isinstance(raw_count, int | float) else 0
+                distribution[str(intent_type)] = count_val
+
+        return {
+            "success": True,
+            "data": {
+                "total_count": total_count,
+                "distribution": distribution,
+            },
+            "correlation_id": str(correlation_id),
+        }
+
+    def describe(self) -> dict[str, object]:
+        """Return handler metadata and capabilities.
+
+        Returns:
+            dict containing handler information.
+        """
+        return {
+            "handler_id": HANDLER_ID_INTENT,
+            "handler_type": "intent_handler",
+            "supported_operations": sorted(_SUPPORTED_OPERATIONS),
+            "initialized": self._initialized,
+            "version": "0.1.0-demo",
+        }
+
+
+__all__: list[str] = ["HandlerIntent", "HANDLER_ID_INTENT"]

omnibase_infra/handlers/handler_manifest_persistence.contract.yaml

@@ -0,0 +1,184 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+#
+# ONEX Handler Contract
+# Handler: HandlerManifestPersistence
+#
+# This contract defines the interface for the manifest persistence handler,
+# which stores ModelExecutionManifest objects to the filesystem with
+# date-based partitioning, atomic writes, and query support.
+#
+# Contract identifiers
+name: "handler_manifest_persistence"
+contract_name: "handler_manifest_persistence"
+handler_name: "HandlerManifestPersistence"
+# Version (semantic versioning)
+version:
+  major: 0
+  minor: 1
+  patch: 0
+contract_version:
+  major: 0
+  minor: 1
+  patch: 0
+# Handler type and category
+handler_type: "INFRA_HANDLER"
+handler_category: "EFFECT"
+transport_type: "FILESYSTEM"
+# Description
+description: >
+  Manifest persistence handler for storing ModelExecutionManifest objects to the filesystem. Provides atomic writes via temp-file-rename pattern, idempotent storage by manifest_id, date-based partitioning for efficient archival, and query support with multiple filter options.
+
+# Handler module location
+handler:
+  name: "HandlerManifestPersistence"
+  module: "omnibase_infra.handlers.handler_manifest_persistence"
+# Supported operations
+operations:
+  - operation: "manifest.store"
+    description: "Store a manifest with atomic write and idempotent behavior"
+    input_fields:
+      - manifest: "dict (serialized ModelExecutionManifest)"
+    output_model:
+      name: "ModelManifestStoreResult"
+      module: "omnibase_infra.handlers.models.model_manifest_store_result"
+    idempotent: true
+    notes: >
+      Uses atomic write (temp file + rename) to prevent partial writes. If manifest_id already exists, returns created=False without overwriting.
+
+  - operation: "manifest.retrieve"
+    description: "Retrieve a manifest by ID (scans date directories)"
+    input_fields:
+      - manifest_id: "UUID or string"
+    output_model:
+      name: "ModelManifestRetrieveResult"
+      module: "omnibase_infra.handlers.models.model_manifest_retrieve_result"
+    idempotent: true
+    complexity: "O(d) where d is number of date directories"
+    notes: >
+      Scans year/month/day directories in reverse chronological order. Returns found=False if manifest does not exist.
+
+  - operation: "manifest.query"
+    description: "Query manifests with filters (correlation_id, node_id, date range)"
+    input_fields:
+      - correlation_id: "UUID | None - Filter by correlation_id"
+      - node_id: "str | None - Filter by node_id"
+      - created_after: "datetime | None - Filter by creation time"
+      - created_before: "datetime | None - Filter by creation time"
+      - metadata_only: "bool (default False) - Return only metadata summary"
+      - limit: "int (default 100, max 10000) - Maximum results"
+    output_model:
+      name: "ModelManifestQueryResult"
+      module: "omnibase_infra.handlers.models.model_manifest_query_result"
+    idempotent: true
+    complexity: "O(n) where n is total manifest files"
+    notes: >
+      Full deserialization required to access filter fields stored within manifest JSON. The metadata_only flag controls RETURN format, not read pattern (filesystem limitation).
+
+# Result models
+result_models:
+  - name: "ModelManifestStoreResult"
+    module: "omnibase_infra.handlers.models.model_manifest_store_result"
+    fields:
+      - manifest_id: "UUID"
+      - file_path: "str"
+      - created: "bool"
+      - bytes_written: "int"
+  - name: "ModelManifestRetrieveResult"
+    module: "omnibase_infra.handlers.models.model_manifest_retrieve_result"
+    fields:
+      - manifest_id: "UUID"
+      - manifest: "dict | None"
+      - file_path: "str | None"
+      - found: "bool"
+  - name: "ModelManifestQueryResult"
+    module: "omnibase_infra.handlers.models.model_manifest_query_result"
+    fields:
+      - manifests: "list[ModelManifestMetadata]"
+      - manifest_data: "list[dict]"
+      - total_count: "int"
+      - metadata_only: "bool"
+  - name: "ModelManifestMetadata"
+    module: "omnibase_infra.handlers.models.model_manifest_metadata"
+    fields:
+      - manifest_id: "UUID"
+      - created_at: "datetime"
+      - correlation_id: "UUID | None"
+      - node_id: "str | None"
+      - file_path: "str"
+      - file_size: "int"
+# Configuration requirements
+configuration:
+  required:
+    - name: "storage_path"
+      type: "str"
+      description: "Path to manifest storage directory"
+  optional:
+    - name: "max_file_size"
+      type: "int"
+      default: 52428800
+      description: "Maximum file size in bytes (default 50MB)"
+      env_var: "ONEX_MANIFEST_MAX_FILE_SIZE"
+# Storage structure
+storage:
+  pattern: "{storage_path}/{year}/{month:02d}/{day:02d}/{manifest_id}.json"
+  example: "/data/manifests/2025/01/14/550e8400-e29b-41d4-a716-446655440000.json"
+  partitioning: "date-based (year/month/day)"
+# Error handling configuration
+error_handling:
+  retry_policy:
+    max_retries: 3
+    initial_delay_ms: 100
+    max_delay_ms: 5000
+    exponential_base: 2
+    retry_on:
+      - "InfraConnectionError"
+      - "InfraTimeoutError"
+  circuit_breaker:
+    enabled: true
+    failure_threshold: 5
+    reset_timeout_ms: 60000
+    transport_type: "FILESYSTEM"
+  error_types:
+    - name: "ProtocolConfigurationError"
+      description: "Invalid configuration or payload"
+      recoverable: false
+    - name: "RuntimeHostError"
+      description: "Handler not initialized"
+      recoverable: false
+    - name: "InfraConnectionError"
+      description: "Filesystem I/O failure"
+      recoverable: true
+    - name: "InfraUnavailableError"
+      description: "Circuit breaker open or file too large"
+      recoverable: true
+# Security features
+security:
+  atomic_writes: true
+  idempotent_storage: true
+  file_size_validation: true
+  notes: >
+    Atomic writes prevent partial/corrupted files on crash. Idempotent storage prevents duplicate manifests. File size validation prevents memory exhaustion on read.
+
+# Datetime handling
+datetime_handling:
+  timezone_awareness: "recommended"
+  iso_parsing: true
+  z_suffix_handling: "converted to +00:00"
+  naive_datetime_behavior: "accepted with warning logged"
+  notes: >
+    Best practice is timezone-aware datetimes. Naive datetimes may cause comparison issues.
+
+# Metadata
+metadata:
+  author: "OmniNode Team"
+  license: "MIT"
+  created: "2025-01-14"
+  ticket: "OMN-1163"
+  tags:
+    - handler
+    - effect
+    - manifest
+    - persistence
+    - filesystem
+    - atomic-writes