omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/nodes/node_intent_storage_effect/models/model_intent_storage_input.py

@@ -0,0 +1,141 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 OmniNode Team
+"""Intent Storage Input Model for Intent Storage Operations.
+
+This module provides ModelIntentStorageInput, representing the input
+for storing a classified intent in the graph database.
+
+Architecture:
+    ModelIntentStorageInput is constructed from IntentClassifiedEvent payloads
+    and contains:
+    - intent_type: The classified intent type
+    - session_id: Optional session identifier for grouping
+    - payload: Intent-specific data to store as node properties
+    - correlation_id: Required correlation ID for tracing (fail-fast validation)
+
+    This model serves as the canonical input for the intent.store operation.
+
+Related:
+    - NodeIntentStorageEffect: Effect node that processes this input
+    - ModelIntentStorageOutput: Output model containing storage result
+    - HandlerIntent: Handler that executes storage operations
+"""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from omnibase_core.enums import EnumCoreErrorCode
+from omnibase_core.errors import OnexError
+from omnibase_core.types import JsonType
+
+
+class ModelIntentStorageInput(BaseModel):
+    """Input model for intent storage operations.
+
+    Defines the required fields for storing a classified intent as a
+    graph node in Memgraph.
+
+    Immutability:
+        This model uses frozen=True to ensure inputs are immutable
+        once created, enabling safe reuse and caching.
+
+    Attributes:
+        intent_type: The classified intent type (e.g., "query", "action").
+        session_id: Optional session identifier for grouping related intents.
+        payload: Intent-specific data to store as node properties.
+        correlation_id: Required correlation ID for request tracing.
+
+    Example:
+        >>> from uuid import uuid4
+        >>> input_model = ModelIntentStorageInput(
+        ...     intent_type="query",
+        ...     session_id="sess-12345",
+        ...     payload={"query": "What is ONEX?", "confidence": 0.95},
+        ...     correlation_id=uuid4(),
+        ... )
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    intent_type: str = Field(
+        ...,
+        description="The classified intent type",
+        min_length=1,
+        max_length=256,
+    )
+    session_id: str | None = Field(
+        default=None,
+        description="Optional session identifier for grouping related intents",
+        max_length=256,
+    )
+    payload: dict[str, JsonType] = Field(
+        default_factory=dict,
+        description="Intent-specific data to store as node properties",
+    )
+    correlation_id: UUID = Field(
+        ...,
+        description="Correlation ID for request tracing (required for observability)",
+    )
+
+    @field_validator("payload")
+    @classmethod
+    def validate_no_reserved_keys(cls, v: dict[str, JsonType]) -> dict[str, JsonType]:
+        """Validate payload does not contain reserved keys.
+
+        Reserved keys (intent_type, session_id, correlation_id) are used as
+        structured fields and cannot appear in the payload to prevent conflicts
+        during storage property merging.
+
+        Args:
+            v: The payload dictionary to validate.
+
+        Returns:
+            The validated payload dictionary.
+
+        Raises:
+            OnexError: If payload contains any reserved keys.
+        """
+        reserved_keys = {"intent_type", "session_id", "correlation_id"}
+        conflicting = reserved_keys & v.keys()
+        if conflicting:
+            raise OnexError(
+                message=f"Payload cannot contain reserved keys: {sorted(conflicting)}",
+                error_code=EnumCoreErrorCode.VALIDATION_ERROR,
+            )
+        return v
+
+    def has_session(self) -> bool:
+        """Check if this input has a session identifier.
+
+        Returns:
+            True if session_id is provided.
+        """
+        return self.session_id is not None
+
+    def to_storage_properties(self) -> dict[str, JsonType]:
+        """Convert input to storage-friendly properties dict.
+
+        Returns:
+            Dictionary containing all intent properties for graph storage,
+            including intent_type, correlation_id, and session_id merged with payload.
+
+        Note:
+            Reserved key validation (intent_type, session_id, correlation_id)
+            is performed at model construction time via field_validator,
+            so this method can safely merge payload with structured fields.
+        """
+        properties: dict[str, JsonType] = {
+            "intent_type": self.intent_type,
+            "correlation_id": str(self.correlation_id),
+        }
+        if self.session_id:
+            properties["session_id"] = self.session_id
+
+        properties.update(self.payload)
+        return properties
+
+
+__all__ = ["ModelIntentStorageInput"]

omnibase_infra/nodes/node_intent_storage_effect/models/model_intent_storage_output.py

@@ -0,0 +1,130 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 OmniNode Team
+"""Intent Storage Output Model for Intent Storage Operations.
+
+This module provides ModelIntentStorageOutput, representing the result
+of storing a classified intent in the graph database.
+
+Architecture:
+    ModelIntentStorageOutput is returned from intent.store operations
+    and contains:
+    - success: Whether the storage operation succeeded
+    - node_id: The graph node ID of the stored intent
+    - element_id: The graph element ID for the stored intent
+    - labels: Graph labels applied to the node
+    - properties: The stored properties (echoed back for verification)
+    - correlation_id: Correlation ID for request tracing
+    - error: Sanitized error message if operation failed
+
+    This model serves as the canonical output for the intent.store operation.
+
+Related:
+    - NodeIntentStorageEffect: Effect node that produces this output
+    - ModelIntentStorageInput: Input model for storage operations
+    - HandlerIntent: Handler that executes storage operations
+"""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_core.types import JsonType
+
+
+class ModelIntentStorageOutput(BaseModel):
+    """Output model for intent storage operations.
+
+    Contains the result of storing a classified intent as a graph node,
+    including the assigned node ID and stored properties.
+
+    Immutability:
+        This model uses frozen=True to ensure outputs are immutable
+        once created, enabling safe sharing and caching.
+
+    Attributes:
+        success: Whether the storage operation completed successfully.
+        node_id: The graph database node ID of the stored intent.
+        element_id: The graph element ID for the stored intent.
+        labels: Graph labels applied to the node (e.g., ["Intent"]).
+        properties: The stored properties (for verification).
+        correlation_id: Correlation ID for request tracing (required).
+        error: Sanitized error message if operation failed.
+        duration_ms: Time taken for the operation in milliseconds.
+
+    Example:
+        >>> output = ModelIntentStorageOutput(
+        ...     success=True,
+        ...     node_id="123",
+        ...     element_id="4:abc:123",
+        ...     labels=("Intent",),
+        ...     properties={"intent_type": "query", "session_id": "sess-12345"},
+        ...     correlation_id=correlation_id,
+        ...     duration_ms=15.2,
+        ... )
+        >>> if output:  # Uses custom __bool__
+        ...     print(f"Stored intent: {output.node_id}")
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    success: bool = Field(
+        ...,
+        description="Whether the storage operation completed successfully",
+    )
+    node_id: str | None = Field(
+        default=None,
+        description="The graph database node ID of the stored intent",
+    )
+    element_id: str | None = Field(
+        default=None,
+        description="The graph element ID for the stored intent",
+    )
+    labels: tuple[str, ...] = Field(
+        default_factory=tuple,
+        description="Graph labels applied to the node",
+    )
+    properties: dict[str, JsonType] = Field(
+        default_factory=dict,
+        description="The stored properties (for verification)",
+    )
+    correlation_id: UUID = Field(
+        ...,
+        description="Correlation ID for request tracing (required for traceability)",
+    )
+    error: str | None = Field(
+        default=None,
+        description="Sanitized error message if operation failed",
+    )
+    duration_ms: float = Field(
+        default=0.0,
+        description="Time taken for the operation in milliseconds",
+        ge=0.0,
+    )
+
+    def __bool__(self) -> bool:
+        """Return True if the storage operation succeeded.
+
+        Warning:
+            This is non-standard Pydantic behavior. Normally bool(model)
+            returns True for any instance. This override enables idiomatic
+            `if result:` checks for success validation.
+
+            See: docs/decisions/adr-custom-bool-result-models.md
+
+        Returns:
+            True if success is True, False otherwise.
+        """
+        return self.success
+
+    def has_node_id(self) -> bool:
+        """Check if a node ID was assigned.
+
+        Returns:
+            True if node_id is present.
+        """
+        return self.node_id is not None
+
+
+__all__ = ["ModelIntentStorageOutput"]

omnibase_infra/nodes/node_intent_storage_effect/node.py

@@ -0,0 +1,94 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 OmniNode Team
+"""Node Intent Storage Effect - Capability-oriented intent storage node.
+
+This effect node provides intent storage capabilities using Memgraph graph database.
+Named by capability ("intent.storage"), not by vendor (e.g., Memgraph).
+
+Core Principle:
+    "I'm interested in what you do, not what you are"
+
+This node follows the ONEX declarative pattern:
+    - DECLARATIVE effect driven by contract.yaml
+    - Zero custom storage logic - all behavior from handler (HandlerIntent)
+    - Lightweight shell that delegates to HandlerIntent -> HandlerGraph
+    - Pattern: "Contract-driven, handlers wired externally"
+
+Extends NodeEffect from omnibase_core for external I/O operations.
+All storage logic is 100% driven by handler implementations, not Python code.
+
+Capabilities:
+    - intent.storage: Store, query, and analyze intents
+    - intent.storage.store: Store classified intents as graph nodes
+    - intent.storage.query_session: Query intents by session identifier
+    - intent.storage.query_distribution: Get intent distribution statistics
+
+Event Topics:
+    Consumed:
+        - {env}.{namespace}.onex.evt.intent-classified.v1
+        - {env}.{namespace}.onex.cmd.intent-query-session.v1
+        - {env}.{namespace}.onex.cmd.intent-query-distribution.v1
+    Published:
+        - {env}.{namespace}.onex.evt.intent-stored.v1
+        - {env}.{namespace}.onex.evt.intent-session-query-result.v1
+        - {env}.{namespace}.onex.evt.intent-distribution-result.v1
+
+Handler Stack:
+    NodeIntentStorageEffect -> HandlerIntent -> HandlerGraph -> Memgraph
+
+Design Decisions:
+    - 100% Contract-Driven: All capabilities in YAML, not Python
+    - Zero Custom Methods: Base class handles everything
+    - Declarative Execution: Handler wired externally
+    - Capability-Oriented: Named by what it does, not what it uses
+
+Related:
+    - contract.yaml: Capability definitions and IO operations
+    - HandlerIntent: Intent-specific graph operations handler
+    - HandlerGraph: Underlying Memgraph graph handler
+    - models/: Input, output models
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from omnibase_core.nodes.node_effect import NodeEffect
+
+if TYPE_CHECKING:
+    from omnibase_core.models.container.model_onex_container import ModelONEXContainer
+
+
+class NodeIntentStorageEffect(NodeEffect):
+    """Effect node for intent storage operations.
+
+    Capability: intent.storage
+
+    Provides a capability-oriented interface for intent storage operations.
+    Uses Memgraph graph database for storing intents as nodes with properties.
+
+    This node is declarative - all behavior is defined in contract.yaml and
+    implemented through the handler (HandlerIntent). No custom storage logic
+    exists in this class.
+
+    Attributes:
+        container: ONEX dependency injection container
+
+    Example:
+        >>> from omnibase_core.models.container import ModelONEXContainer
+        >>> container = ModelONEXContainer()
+        >>> node = NodeIntentStorageEffect(container)
+        >>> # Handler must be wired externally via registry
+    """
+
+    def __init__(self, container: ModelONEXContainer) -> None:
+        """Initialize the intent storage effect node.
+
+        Args:
+            container: ONEX dependency injection container for resolving
+                dependencies defined in contract.yaml.
+        """
+        super().__init__(container)
+
+
+__all__ = ["NodeIntentStorageEffect"]

omnibase_infra/nodes/node_intent_storage_effect/registry/__init__.py

@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 OmniNode Team
+"""Registry for Intent Storage Effect Node.
+
+This module exports the RegistryInfraIntentStorage for dependency registration
+with the ONEX container. The registry wires up the NodeIntentStorageEffect
+with its handler dependencies (HandlerIntent -> HandlerGraph -> Memgraph).
+
+Architecture:
+    The registry follows the ONEX container-based dependency injection pattern:
+    - Registers NodeIntentStorageEffect with the container
+    - Wires handler dependencies defined in contract.yaml
+    - Enables capability-oriented resolution (intent.storage)
+
+    Registration Flow:
+        Container -> RegistryInfraIntentStorage.register() -> NodeIntentStorageEffect
+                                                           -> HandlerIntent (resolved)
+
+Usage:
+    >>> from omnibase_core.models.container import ModelONEXContainer
+    >>> from omnibase_infra.nodes.node_intent_storage_effect.registry import (
+    ...     RegistryInfraIntentStorage,
+    ... )
+    >>> container = ModelONEXContainer()
+    >>> RegistryInfraIntentStorage.register(container)
+
+Related:
+    - NodeIntentStorageEffect: The effect node registered by this registry
+    - HandlerIntent: Handler wired for intent storage operations
+    - ModelONEXContainer: ONEX dependency injection container
+"""
+
+from .registry_infra_intent_storage import RegistryInfraIntentStorage
+
+__all__ = ["RegistryInfraIntentStorage"]

omnibase_infra/nodes/node_intent_storage_effect/registry/registry_infra_intent_storage.py

@@ -0,0 +1,294 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 OmniNode Team
+"""Registry for Intent Storage Node Dependencies.
+
+This module provides RegistryInfraIntentStorage, which registers
+dependencies for the NodeIntentStorageEffect node.
+
+Architecture:
+    The registry follows ONEX container-based dependency injection:
+    - Registers HandlerIntent with ModelONEXContainer
+    - Supports initialization with pre-configured HandlerGraph
+    - Enables runtime handler resolution via container
+
+    Registration is typically called during application bootstrap.
+
+Related:
+    - NodeIntentStorageEffect: Effect node that uses these dependencies
+    - HandlerIntent: Intent handler for graph operations
+    - HandlerGraph: Underlying Memgraph graph handler
+    - ModelONEXContainer: ONEX dependency injection container
+
+Testing:
+    This module uses module-level state (``_HANDLER_STORAGE``, ``_PROTOCOL_METADATA``)
+    for handler storage. Tests MUST call ``RegistryInfraIntentStorage.clear()`` in
+    setup and teardown fixtures to prevent test pollution between test cases.
+
+    Failure to clear state can cause:
+    - Tests passing in isolation but failing when run together
+    - Handlers from previous tests leaking into subsequent tests
+    - Flaky test behavior that is difficult to debug
+
+    Recommended fixture pattern:
+
+    .. code-block:: python
+
+        @pytest.fixture(autouse=True)
+        def clear_registry():
+            RegistryInfraIntentStorage.clear()
+            yield
+            RegistryInfraIntentStorage.clear()
+
+Note:
+    This registry uses a module-level dict for handler storage because the
+    ServiceRegistry in omnibase_core v1.0 doesn't support dict-style access
+    or string-keyed multi-handler routing. The handlers are still validated
+    but stored separately.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import TYPE_CHECKING, cast
+
+logger = logging.getLogger(__name__)
+
+if TYPE_CHECKING:
+    from omnibase_core.models.container.model_onex_container import ModelONEXContainer
+    from omnibase_infra.handlers.handler_intent import HandlerIntent
+
+__all__ = ["RegistryInfraIntentStorage"]
+
+# TODO(ServiceRegistry-v2): Migrate to container.service_registry once v2.0
+# supports dict-style access for multi-handler routing. Current module-level
+# storage is a workaround for v1.0 limitations. See docstring Note section.
+#
+# Module-level storage for handlers and metadata
+# ServiceRegistry in v1.0 doesn't support dict-style access needed for
+# handler routing
+_HANDLER_STORAGE: dict[str, object] = {}
+_PROTOCOL_METADATA: dict[str, dict[str, object]] = {}
+
+
+class RegistryInfraIntentStorage:
+    """Registry for intent storage node dependencies.
+
+    Registers handler implementations with the ONEX container.
+    Supports the HandlerIntent which wraps HandlerGraph for Memgraph operations.
+
+    Usage:
+        .. code-block:: python
+
+            from omnibase_core.models.container import ModelONEXContainer
+            from omnibase_infra.nodes.node_intent_storage_effect.registry import (
+                RegistryInfraIntentStorage,
+            )
+
+            # Create container
+            container = ModelONEXContainer()
+
+            # Register dependencies
+            RegistryInfraIntentStorage.register(container)
+
+            # Register the handler (must have graph_handler configured)
+            RegistryInfraIntentStorage.register_handler(
+                container,
+                handler=intent_handler,
+            )
+
+    Note:
+        This registry does NOT instantiate handlers. Handlers must be
+        created externally with their specific dependencies (HandlerGraph)
+        and then registered via register_handler().
+    """
+
+    # Handler key for container registration
+    HANDLER_KEY = "handler_intent"
+
+    # Default handler type
+    DEFAULT_HANDLER_TYPE = "memgraph"
+
+    @staticmethod
+    def _is_registered(handler_key: str) -> bool:
+        """Check if a handler is already registered for the given key.
+
+        This is a private helper method used to detect re-registration
+        attempts, which may indicate container lifecycle issues or
+        missing clear() calls in tests.
+
+        Args:
+            handler_key: The handler key to check (e.g., "handler_intent.memgraph").
+
+        Returns:
+            True if a handler is already registered for this key, False otherwise.
+        """
+        return handler_key in _HANDLER_STORAGE
+
+    @staticmethod
+    def register(_container: ModelONEXContainer) -> None:
+        """Register intent storage dependencies with the container.
+
+        Registers the handler key for later handler binding. This method
+        sets up the infrastructure but does not bind a specific handler.
+
+        Args:
+            _container: ONEX dependency injection container. Currently unused
+                because ServiceRegistry v1.0 doesn't support dict-style access
+                for multi-handler routing. The parameter is retained for API
+                consistency with other registry methods and future migration.
+
+        Example:
+            >>> from omnibase_core.models.container import ModelONEXContainer
+            >>> container = ModelONEXContainer()
+            >>> RegistryInfraIntentStorage.register(container)
+        """
+        # Register handler metadata for discovery
+        # Actual handler binding happens via register_handler()
+        _PROTOCOL_METADATA[RegistryInfraIntentStorage.HANDLER_KEY] = {
+            "handler": "HandlerIntent",
+            "module": "omnibase_infra.handlers.handler_intent",
+            "description": "Handler for intent storage operations in Memgraph",
+            "capabilities": [
+                "intent.storage",
+                "intent.storage.store",
+                "intent.storage.query_session",
+                "intent.storage.query_distribution",
+            ],
+        }
+
+    @staticmethod
+    def register_handler(
+        _container: ModelONEXContainer,
+        handler: HandlerIntent,
+    ) -> None:
+        """Register a specific intent handler with the container.
+
+        Binds a concrete HandlerIntent implementation to the handler key.
+        The handler must already be initialized with a HandlerGraph.
+
+        Args:
+            _container: ONEX dependency injection container. Currently unused
+                because ServiceRegistry v1.0 doesn't support dict-style access.
+                The parameter is retained for API consistency.
+            handler: HandlerIntent instance to register (must be initialized).
+
+        Raises:
+            ProtocolConfigurationError: If handler does not implement the required
+                protocol methods (initialize, shutdown, execute).
+
+        Example:
+            >>> from omnibase_infra.handlers.handler_intent import HandlerIntent
+            >>> handler = HandlerIntent(container)
+            >>> await handler.initialize({"graph_handler": graph_handler})
+            >>> RegistryInfraIntentStorage.register_handler(container, handler)
+        """
+        from omnibase_infra.enums import EnumInfraTransportType
+        from omnibase_infra.errors import (
+            ModelInfraErrorContext,
+            ProtocolConfigurationError,
+        )
+
+        # NOTE: Protocol-based duck typing is used here per ONEX conventions.
+        # We verify the handler implements required methods rather than checking
+        # concrete class inheritance. This enables:
+        # 1. Fail-fast validation: Immediately reject invalid handlers
+        # 2. Duck typing: Any object with the required methods is accepted
+        # 3. Testability: Mock handlers can be injected without subclassing
+        required_methods = ["initialize", "shutdown", "execute"]
+        missing = [
+            m for m in required_methods if not callable(getattr(handler, m, None))
+        ]
+        if missing:
+            context = ModelInfraErrorContext.with_correlation(
+                transport_type=EnumInfraTransportType.GRAPH,
+                operation="register_handler",
+                target_name="intent_handler",
+            )
+            raise ProtocolConfigurationError(
+                f"Handler missing required protocol methods: {missing}. "
+                f"Got {type(handler).__name__}",
+                context=context,
+            )
+
+        # Store handler in module-level storage
+        handler_key = (
+            f"{RegistryInfraIntentStorage.HANDLER_KEY}."
+            f"{RegistryInfraIntentStorage.DEFAULT_HANDLER_TYPE}"
+        )
+
+        # Warn if re-registering over an existing handler
+        if RegistryInfraIntentStorage._is_registered(handler_key):
+            logger.warning(
+                "Re-registering handler '%s'. This may indicate container lifecycle "
+                "issues or missing clear() calls in tests.",
+                handler_key,
+            )
+
+        _HANDLER_STORAGE[handler_key] = handler
+
+        # Also register as default
+        default_key = RegistryInfraIntentStorage.HANDLER_KEY + ".default"
+        if RegistryInfraIntentStorage._is_registered(default_key):
+            logger.warning(
+                "Re-registering handler '%s'. This may indicate container lifecycle "
+                "issues or missing clear() calls in tests.",
+                default_key,
+            )
+        _HANDLER_STORAGE[default_key] = handler
+
+    @staticmethod
+    def get_handler(
+        _container: ModelONEXContainer,
+        handler_type: str | None = None,
+    ) -> HandlerIntent | None:
+        """Retrieve a registered intent handler from the container.
+
+        Args:
+            _container: ONEX dependency injection container. Currently unused
+                because ServiceRegistry v1.0 doesn't support dict-style access.
+                The parameter is retained for API consistency.
+            handler_type: Specific handler type to retrieve. If None, returns default.
+
+        Returns:
+            The registered HandlerIntent, or None if not found.
+
+        Example:
+            >>> handler = RegistryInfraIntentStorage.get_handler(container)
+            >>> if handler:
+            ...     result = await handler.execute(envelope)
+        """
+        if handler_type is not None:
+            handler_key = f"{RegistryInfraIntentStorage.HANDLER_KEY}.{handler_type}"
+        else:
+            handler_key = RegistryInfraIntentStorage.HANDLER_KEY + ".default"
+
+        result = _HANDLER_STORAGE.get(handler_key)
+        return cast("HandlerIntent | None", result)
+
+    @staticmethod
+    def clear() -> None:
+        """Clear all registered handlers and protocol metadata.
+
+        Resets all module-level state to empty dicts. This method is essential
+        for test isolation.
+
+        Warning:
+            This method MUST be called in test setup and teardown to prevent
+            test pollution. Module-level state persists across test cases within
+            the same Python process. Failing to call this method can cause:
+
+            - Handlers from previous tests affecting subsequent tests
+            - Tests passing individually but failing when run together
+            - Non-deterministic test failures that are difficult to reproduce
+
+        Example:
+            .. code-block:: python
+
+                @pytest.fixture(autouse=True)
+                def clear_registry():
+                    RegistryInfraIntentStorage.clear()
+                    yield
+                    RegistryInfraIntentStorage.clear()
+        """
+        _HANDLER_STORAGE.clear()
+        _PROTOCOL_METADATA.clear()