omnibase_infra 0.2.3__py3-none-any.whl → 0.2.5__py3-none-any.whl

omnibase_infra/nodes/node_intent_storage_effect/__init__.py

@@ -0,0 +1,50 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 OmniNode Team
+"""Node Intent Storage Effect - Capability-oriented intent storage node.
+
+This package provides the NodeIntentStorageEffect, a capability-oriented
+effect node for intent storage operations using Memgraph graph database.
+
+Core Principle:
+    "I'm interested in what you do, not what you are"
+
+    Named by capability (intent.storage), not by specific backend implementation.
+    Uses Memgraph for graph-based intent persistence.
+
+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
+
+Available Exports:
+    - NodeIntentStorageEffect: The declarative effect node
+
+Example:
+    >>> from omnibase_core.models.container import ModelONEXContainer
+    >>> from omnibase_infra.nodes.node_intent_storage_effect import (
+    ...     NodeIntentStorageEffect,
+    ... )
+    >>>
+    >>> container = ModelONEXContainer()
+    >>> node = NodeIntentStorageEffect(container)
+
+Related Modules:
+    - models: Pydantic models for intent storage operations
+    - registry: Dependency injection registration
+    - HandlerIntent: Handler for graph operations (omnibase_infra.handlers)
+"""
+
+from .node import NodeIntentStorageEffect
+
+__all__ = ["NodeIntentStorageEffect"]

omnibase_infra/nodes/node_intent_storage_effect/contract.yaml

@@ -0,0 +1,194 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 OmniNode Team
+#
+# ONEX Node Contract
+# Node: NodeIntentStorageEffect
+#
+# Capability-oriented effect node for intent storage operations.
+# Wraps HandlerIntent for graph-based intent persistence in Memgraph.
+#
+# This contract defines the interface for storing and querying intents
+# as graph nodes, enabling session-based intent retrieval and distribution
+# analysis.
+#
+# Related Tickets:
+#   - OMN-1509: Intent Processing System
+#   - WS-1: Intent Storage Effect Node
+# Contract identifiers
+name: "node_intent_storage_effect"
+contract_name: "node_intent_storage_effect"
+node_name: "node_intent_storage_effect"
+contract_version:
+  major: 1
+  minor: 0
+  patch: 0
+node_version:
+  major: 1
+  minor: 0
+  patch: 0
+# Node type
+node_type: "EFFECT_GENERIC"
+# Description
+description: >
+  Capability-oriented effect node for intent storage operations. Handles storing classified intents in Memgraph graph database and querying intents by session or distribution statistics.
+
+# Strongly typed I/O models
+input_model:
+  name: "ModelIntentStorageInput"
+  module: "omnibase_infra.nodes.node_intent_storage_effect.models"
+  description: "Input model for intent storage operations (classified intent event)."
+output_model:
+  name: "ModelIntentStorageOutput"
+  module: "omnibase_infra.nodes.node_intent_storage_effect.models"
+  description: "Output model for intent storage results (storage confirmation)."
+# Capability declaration (capability-oriented naming)
+capabilities:
+  - name: "intent.storage"
+    description: "Store, query, and analyze intents in graph database"
+    version: "1.0.0"
+  - name: "intent.storage.store"
+    description: "Store classified intents as graph nodes"
+  - name: "intent.storage.query_session"
+    description: "Query intents by session identifier"
+  - name: "intent.storage.query_distribution"
+    description: "Get intent distribution statistics"
+# Event-driven topic configuration
+# Uses {env}.{namespace} placeholders for environment-aware topics
+consumed_events:
+  - topic: "{env}.{namespace}.onex.evt.intent-classified.v1"
+    event_type: "IntentClassifiedEvent"
+    description: "Classified intent ready for storage"
+  - topic: "{env}.{namespace}.onex.cmd.intent-query-session.v1"
+    event_type: "IntentQuerySessionCommand"
+    message_category: "COMMAND"
+    description: "Command to query intents by session"
+  - topic: "{env}.{namespace}.onex.cmd.intent-query-distribution.v1"
+    event_type: "IntentQueryDistributionCommand"
+    message_category: "COMMAND"
+    description: "Command to get intent distribution statistics"
+published_events:
+  - topic: "{env}.{namespace}.onex.evt.intent-stored.v1"
+    event_type: "IntentStoredEvent"
+    description: "Confirmation that intent was stored successfully"
+  - topic: "{env}.{namespace}.onex.evt.intent-session-query-result.v1"
+    event_type: "IntentSessionQueryResultEvent"
+    description: "Result of session-based intent query"
+  - topic: "{env}.{namespace}.onex.evt.intent-distribution-result.v1"
+    event_type: "IntentDistributionResultEvent"
+    description: "Result of intent distribution statistics query"
+# IO operations (EFFECT node specific)
+# Note: correlation_id is required (UUID) for all operations.
+# Callers must provide a correlation_id for tracing.
+io_operations:
+  - operation: "intent.store"
+    description: "Store a classified intent as a graph node"
+    input_fields:
+      - intent_type: "str"
+      - session_id: "str | None"
+      - payload: "dict[str, object]"
+      - correlation_id: "UUID"
+    output_fields:
+      - node_id: "str"
+      - element_id: "str"
+      - success: "bool"
+    # Not idempotent: Each call creates a new graph node with unique element_id.
+    # Duplicate calls with same input will create multiple nodes.
+    # Use correlation_id for deduplication at the caller level if needed.
+    idempotent: false
+  - operation: "intent.query_session"
+    description: "Query intents by session identifier"
+    input_fields:
+      - session_id: "str"
+      - correlation_id: "UUID"
+    output_fields:
+      - intents: "list[dict]"
+      - count: "int"
+    idempotent: true
+  - operation: "intent.query_distribution"
+    description: "Get intent count and distribution by intent_type"
+    input_fields:
+      - correlation_id: "UUID"
+    output_fields:
+      - total_count: "int"
+      - distribution: "dict[str, int]"
+    idempotent: true
+# Handler routing (wraps HandlerIntent which wraps HandlerGraph)
+handler_routing:
+  routing_strategy: "operation_match"
+  default_handler: "memgraph"
+  handlers:
+    - handler_type: "memgraph"
+      handler:
+        name: "HandlerIntent"
+        module: "omnibase_infra.handlers.handler_intent"
+      description: "Memgraph graph database handler for intent storage"
+      supported_operations:
+        - "intent.store"
+        - "intent.query_session"
+        - "intent.query_distribution"
+# Dependencies (protocols this node requires)
+dependencies:
+  - name: "handler_intent"
+    type: "handler"
+    class_name: "HandlerIntent"
+    module: "omnibase_infra.handlers.handler_intent"
+    description: "Intent handler for graph operations"
+  - name: "handler_graph"
+    type: "handler"
+    class_name: "HandlerGraph"
+    module: "omnibase_infra.handlers.handler_graph"
+    description: "Underlying graph handler (Memgraph)"
+    transitive: true
+# 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
+  error_types:
+    - name: "GraphConnectionError"
+      description: "Unable to connect to Memgraph"
+      recoverable: true
+      retry_strategy: "exponential_backoff"
+    - name: "GraphTimeoutError"
+      description: "Graph operation timed out"
+      recoverable: true
+      retry_strategy: "exponential_backoff"
+    - name: "IntentNotFoundError"
+      description: "Intent not found in graph"
+      recoverable: false
+      retry_strategy: "none"
+    - name: "ValidationError"
+      description: "Input validation failed"
+      recoverable: false
+      retry_strategy: "none"
+# Health check configuration
+health_check:
+  enabled: true
+  endpoint: "/health"
+  interval_seconds: 30
+  timeout_ms: 5000
+  checks:
+    - name: "graph_backend"
+      type: "connection"
+      critical: true
+# Metadata
+metadata:
+  author: "OmniNode Team"
+  license: "MIT"
+  created: "2026-01-26"
+  tags:
+    - effect
+    - intent
+    - storage
+    - graph
+    - memgraph
+    - capability-oriented

omnibase_infra/nodes/node_intent_storage_effect/models/__init__.py

@@ -0,0 +1,24 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2026 OmniNode Team
+"""Models for Intent Storage Effect Node.
+
+This module exports models used by the NodeIntentStorageEffect for
+capability-oriented intent storage operations in Memgraph.
+
+Available Models:
+    - ModelIntentStorageInput: Input model for intent storage (classified intent data)
+    - ModelIntentStorageOutput: Output model for storage results (node ID, success)
+
+All models are:
+    - Frozen (immutable after creation)
+    - Extra="forbid" (no extra fields allowed)
+    - Strongly typed (no Any types)
+"""
+
+from .model_intent_storage_input import ModelIntentStorageInput
+from .model_intent_storage_output import ModelIntentStorageOutput
+
+__all__ = [
+    "ModelIntentStorageInput",
+    "ModelIntentStorageOutput",
+]

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"]