omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/nodes/handlers/graph/contract.yaml

@@ -0,0 +1,127 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+# Contract for Graph Handler - Neo4j/Memgraph database operations
+name: "handler_graph"
+node_type: "EFFECT_GENERIC"
+description: "Graph database handler for Cypher queries via neo4j async driver (Memgraph/Neo4j)"
+contract_version:
+  major: 1
+  minor: 0
+  patch: 0
+node_version:
+  major: 0
+  minor: 1
+  patch: 0
+input_model:
+  name: "ModelEventEnvelope"
+  module: "omnibase_core.models.events.model_event_envelope"
+output_model:
+  name: "ModelHandlerOutput"
+  module: "omnibase_core.models.dispatch.model_handler_output"
+handler_routing:
+  routing_strategy: "operation_match"
+  handlers:
+    - handler_type: "graph"
+      handler:
+        name: "HandlerGraph"
+        module: "omnibase_infra.handlers.handler_graph"
+      supported_operations:
+        - "graph.execute_query"
+        - "graph.execute_query_batch"
+        - "graph.create_node"
+        - "graph.create_relationship"
+        - "graph.delete_node"
+        - "graph.delete_relationship"
+        - "graph.traverse"
+operation_bindings:
+  version:
+    major: 1
+    minor: 0
+    patch: 0
+  global_bindings:
+    - parameter_name: "correlation_id"
+      expression: "${envelope.correlation_id}"
+      required: true
+  bindings:
+    "graph.execute_query":
+      - parameter_name: "query"
+        expression: "${payload.query}"
+        required: true
+      - parameter_name: "parameters"
+        expression: "${payload.parameters}"
+        required: false
+    "graph.execute_query_batch":
+      - parameter_name: "queries"
+        expression: "${payload.queries}"
+        required: true
+      - parameter_name: "transaction"
+        expression: "${payload.transaction}"
+        required: false
+    "graph.create_node":
+      - parameter_name: "labels"
+        expression: "${payload.labels}"
+        required: false
+      - parameter_name: "properties"
+        expression: "${payload.properties}"
+        required: false
+    "graph.create_relationship":
+      - parameter_name: "from_node_id"
+        expression: "${payload.from_node_id}"
+        required: true
+      - parameter_name: "to_node_id"
+        expression: "${payload.to_node_id}"
+        required: true
+      - parameter_name: "relationship_type"
+        expression: "${payload.relationship_type}"
+        required: true
+      - parameter_name: "properties"
+        expression: "${payload.properties}"
+        required: false
+    "graph.delete_node":
+      - parameter_name: "node_id"
+        expression: "${payload.node_id}"
+        required: true
+      - parameter_name: "detach"
+        expression: "${payload.detach}"
+        required: false
+    "graph.delete_relationship":
+      - parameter_name: "relationship_id"
+        expression: "${payload.relationship_id}"
+        required: true
+    "graph.traverse":
+      - parameter_name: "start_node_id"
+        expression: "${payload.start_node_id}"
+        required: true
+      - parameter_name: "relationship_types"
+        expression: "${payload.relationship_types}"
+        required: false
+      - parameter_name: "direction"
+        expression: "${payload.direction}"
+        required: false
+      - parameter_name: "max_depth"
+        expression: "${payload.max_depth}"
+        required: false
+      - parameter_name: "filters"
+        expression: "${payload.filters}"
+        required: false
+metadata:
+  handler_id: "graph-handler"
+  handler_type: "infra_handler"
+  handler_category: "effect"
+  transport_type: "graph"
+  security_features:
+    - "Parameterized Cypher queries"
+    - "Label validation for injection prevention"
+    - "Credential sanitization"
+  resilience_features:
+    - "Circuit breaker pattern"
+    - "Connection pool management"
+    - "Transaction support"
+  capabilities:
+    - "cypher"
+    - "parameterized_queries"
+    - "transactions"
+    - "node_crud"
+    - "relationship_crud"
+    - "traversal"
+    - "batch_operations"

omnibase_infra/nodes/handlers/http/contract.yaml

@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+# Contract for HTTP Handler - REST API operations
+name: "handler_http"
+node_type: "EFFECT_GENERIC"
+description: "HTTP REST handler for GET and POST operations using httpx async client"
+contract_version:
+  major: 1
+  minor: 0
+  patch: 0
+node_version:
+  major: 0
+  minor: 1
+  patch: 0
+input_model:
+  name: "ModelEventEnvelope"
+  module: "omnibase_core.models.events.model_event_envelope"
+output_model:
+  name: "ModelHandlerOutput"
+  module: "omnibase_core.models.dispatch.model_handler_output"
+handler_routing:
+  routing_strategy: "operation_match"
+  handlers:
+    - handler_type: "http"
+      handler:
+        name: "HandlerHttpRest"
+        module: "omnibase_infra.handlers.handler_http"
+      supported_operations:
+        - "http.get"
+        - "http.post"
+operation_bindings:
+  version:
+    major: 1
+    minor: 0
+    patch: 0
+  global_bindings:
+    - parameter_name: "correlation_id"
+      expression: "${envelope.correlation_id}"
+      required: true
+  bindings:
+    "http.get":
+      - parameter_name: "url"
+        expression: "${payload.url}"
+        required: true
+      - parameter_name: "headers"
+        expression: "${payload.headers}"
+        required: false
+    "http.post":
+      - parameter_name: "url"
+        expression: "${payload.url}"
+        required: true
+      - parameter_name: "headers"
+        expression: "${payload.headers}"
+        required: false
+      - parameter_name: "body"
+        expression: "${payload.body}"
+        required: false
+metadata:
+  handler_id: "http-handler"
+  handler_type: "infra_handler"
+  handler_category: "effect"
+  transport_type: "http"
+  security_features:
+    - "Configurable request/response size limits"
+    - "Pre-read Content-Length validation"
+    - "Streaming body validation"
+    - "DoS protection"
+  resilience_features:
+    - "Configurable timeout"
+    - "Follow redirects"
+  notes:
+    - "PUT, DELETE, PATCH deferred to Beta"
+    - "Retry logic deferred to Beta"
+    - "Rate limiting deferred to Beta"

omnibase_infra/nodes/handlers/intent/contract.yaml

@@ -0,0 +1,66 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+# Contract for Intent Handler - Graph-based intent storage operations
+name: "handler_intent"
+node_type: "EFFECT_GENERIC"
+description: "Intent handler wrapping HandlerGraph for intent-specific graph operations (DEMO)"
+contract_version:
+  major: 1
+  minor: 0
+  patch: 0
+node_version:
+  major: 0
+  minor: 1
+  patch: 0
+input_model:
+  name: "ModelEventEnvelope"
+  module: "omnibase_core.models.events.model_event_envelope"
+output_model:
+  name: "ModelHandlerOutput"
+  module: "omnibase_core.models.dispatch.model_handler_output"
+handler_routing:
+  routing_strategy: "operation_match"
+  handlers:
+    - handler_type: "intent"
+      handler:
+        name: "HandlerIntent"
+        module: "omnibase_infra.handlers.handler_intent"
+      supported_operations:
+        - "intent.store"
+        - "intent.query_session"
+        - "intent.query_distribution"
+operation_bindings:
+  version:
+    major: 1
+    minor: 0
+    patch: 0
+  global_bindings:
+    - parameter_name: "correlation_id"
+      expression: "${envelope.correlation_id}"
+      required: true
+  bindings:
+    "intent.store":
+      - parameter_name: "intent_type"
+        expression: "${payload.intent_type}"
+        required: true
+      - parameter_name: "session_id"
+        expression: "${payload.session_id}"
+        required: false
+    "intent.query_session":
+      - parameter_name: "session_id"
+        expression: "${payload.session_id}"
+        required: true
+    # No payload bindings required - aggregates all intents by type (read-only)
+    "intent.query_distribution": []
+metadata:
+  handler_id: "intent-handler"
+  handler_type: "intent_handler"
+  handler_category: "effect"
+  transport_type: "graph"
+  notes:
+    - "TEMPORARY demo wiring - will be replaced by contract-driven routing"
+    - "intent.store is NOT idempotent (creates new node each call)"
+    - "intent.query_session is idempotent (read-only)"
+    - "intent.query_distribution is idempotent (read-only aggregation)"
+  dependencies:
+    - "Requires pre-initialized HandlerGraph instance"

omnibase_infra/nodes/handlers/mcp/contract.yaml

@@ -0,0 +1,69 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+# Contract for MCP Handler - Model Context Protocol integration
+name: "handler_mcp"
+node_type: "EFFECT_GENERIC"
+description: "MCP protocol handler for exposing ONEX nodes as AI agent tools"
+contract_version:
+  major: 1
+  minor: 0
+  patch: 0
+node_version:
+  major: 0
+  minor: 1
+  patch: 0
+input_model:
+  name: "ModelEventEnvelope"
+  module: "omnibase_core.models.events.model_event_envelope"
+output_model:
+  name: "ModelHandlerOutput"
+  module: "omnibase_core.models.dispatch.model_handler_output"
+handler_routing:
+  routing_strategy: "operation_match"
+  handlers:
+    - handler_type: "mcp"
+      handler:
+        name: "HandlerMCP"
+        module: "omnibase_infra.handlers.handler_mcp"
+      supported_operations:
+        - "mcp.list_tools"
+        - "mcp.call_tool"
+        - "mcp.describe"
+operation_bindings:
+  version:
+    major: 1
+    minor: 0
+    patch: 0
+  global_bindings:
+    - parameter_name: "correlation_id"
+      expression: "${envelope.correlation_id}"
+      required: true
+  bindings:
+    # No payload bindings required - returns all registered tools
+    "mcp.list_tools": []
+    "mcp.call_tool":
+      - parameter_name: "tool_name"
+        expression: "${payload.tool_name}"
+        required: true
+      - parameter_name: "arguments"
+        expression: "${payload.arguments}"
+        required: false
+    # No payload bindings required - returns MCP server capabilities
+    "mcp.describe": []
+metadata:
+  handler_id: "mcp-handler"
+  handler_type: "infra_handler"
+  handler_category: "effect"
+  transport_type: "mcp"
+  security_features:
+    - "Tool execution timeout enforcement"
+    - "Request size limits"
+    - "Correlation ID propagation"
+    - "Circuit breaker protection"
+  resilience_features:
+    - "Circuit breaker pattern (threshold: 5, reset: 60s)"
+    - "Internal uvicorn server lifecycle management"
+  notes:
+    - "Authentication NOT yet implemented in MVP"
+    - "Streamable HTTP transport for production scalability"
+    - "Dynamic tool discovery from ONEX node registry"

omnibase_infra/nodes/handlers/vault/contract.yaml

@@ -0,0 +1,91 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+# Contract for Vault Handler - HashiCorp Vault secret management
+name: "handler_vault"
+node_type: "EFFECT_GENERIC"
+description: "HashiCorp Vault handler for secret management operations using hvac client"
+contract_version:
+  major: 1
+  minor: 0
+  patch: 0
+node_version:
+  major: 0
+  minor: 1
+  patch: 0
+input_model:
+  name: "ModelEventEnvelope"
+  module: "omnibase_core.models.events.model_event_envelope"
+output_model:
+  name: "ModelHandlerOutput"
+  module: "omnibase_core.models.dispatch.model_handler_output"
+handler_routing:
+  routing_strategy: "operation_match"
+  handlers:
+    - handler_type: "vault"
+      handler:
+        name: "HandlerVault"
+        module: "omnibase_infra.handlers.handler_vault"
+      supported_operations:
+        - "vault.read_secret"
+        - "vault.write_secret"
+        - "vault.delete_secret"
+        - "vault.list_secrets"
+        - "vault.renew_token"
+operation_bindings:
+  version:
+    major: 1
+    minor: 0
+    patch: 0
+  global_bindings:
+    - parameter_name: "correlation_id"
+      expression: "${envelope.correlation_id}"
+      required: true
+  bindings:
+    "vault.read_secret":
+      - parameter_name: "path"
+        expression: "${payload.path}"
+        required: true
+      - parameter_name: "mount_point"
+        expression: "${payload.mount_point}"
+        required: false
+    "vault.write_secret":
+      - parameter_name: "path"
+        expression: "${payload.path}"
+        required: true
+      - parameter_name: "secret"
+        expression: "${payload.secret}"
+        required: true
+      - parameter_name: "mount_point"
+        expression: "${payload.mount_point}"
+        required: false
+    "vault.delete_secret":
+      - parameter_name: "path"
+        expression: "${payload.path}"
+        required: true
+      - parameter_name: "mount_point"
+        expression: "${payload.mount_point}"
+        required: false
+    "vault.list_secrets":
+      - parameter_name: "path"
+        expression: "${payload.path}"
+        required: true
+      - parameter_name: "mount_point"
+        expression: "${payload.mount_point}"
+        required: false
+    # No payload bindings required - renews the current auth token from connection config
+    "vault.renew_token": []
+metadata:
+  handler_id: "vault-handler"
+  handler_type: "infra_handler"
+  handler_category: "effect"
+  transport_type: "vault"
+  security_features:
+    - "SecretStr protection for tokens"
+    - "Sanitized error messages"
+    - "SSL verification enabled by default"
+    - "Automatic token renewal management"
+  resilience_features:
+    - "Circuit breaker pattern"
+    - "Exponential backoff retry"
+    - "Thread pool management"
+    - "Token expiration tracking"

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