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

omnibase_infra/capabilities/contract_capability_extractor.py

@@ -0,0 +1,221 @@
+"""Contract capability extractor for ONEX nodes.
+
+Extracts ModelContractCapabilities from typed contract models.
+No side effects, deterministic output.
+
+OMN-1136: ContractCapabilityExtractor - Main extractor implementation.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from omnibase_core.models.capabilities import ModelContractCapabilities
+from omnibase_core.models.primitives.model_semver import ModelSemVer
+from omnibase_infra.capabilities.capability_inference_rules import (
+    CapabilityInferenceRules,
+)
+from omnibase_infra.capabilities.intent_type_extractor import IntentTypeExtractor
+
+if TYPE_CHECKING:
+    from omnibase_core.models.contracts import (
+        ModelContractBase,
+    )
+
+
+class ContractCapabilityExtractor:
+    """Extracts capabilities from typed contract models.
+
+    Responsibilities:
+    - Read capability-related fields from contract
+    - Apply inference rules to derive additional tags
+    - Union explicit + inferred capabilities
+    - Return deterministic, sorted output
+
+    This extractor is stateless and produces deterministic output
+    for the same contract input.
+
+    Args:
+        rules: Optional custom CapabilityInferenceRules instance. If not provided,
+            uses a default instance with standard rule mappings.
+
+    Example:
+        # Use default rules
+        extractor = ContractCapabilityExtractor()
+
+        # Use custom rules
+        custom_rules = CapabilityInferenceRules(
+            intent_patterns={"redis.": "redis.caching"}
+        )
+        extractor = ContractCapabilityExtractor(rules=custom_rules)
+    """
+
+    def __init__(self, rules: CapabilityInferenceRules | None = None) -> None:
+        """Initialize with optional custom inference rules.
+
+        Args:
+            rules: Custom CapabilityInferenceRules instance. If None, creates
+                a default instance with standard rule mappings.
+        """
+        self._rules = rules if rules is not None else CapabilityInferenceRules()
+        self._intent_extractor = IntentTypeExtractor()
+
+    def extract(self, contract: ModelContractBase) -> ModelContractCapabilities | None:
+        """Extract capabilities from a contract model.
+
+        Args:
+            contract: Typed contract model (Effect, Compute, Reducer, or Orchestrator)
+
+        Returns:
+            ModelContractCapabilities with extracted data, or None if contract is None
+
+        Raises:
+            Any exceptions from extraction propagate (fail-fast behavior).
+        """
+        if contract is None:
+            return None
+
+        # Extract contract type from node_type
+        contract_type = self._extract_contract_type(contract)
+
+        # Extract version
+        contract_version = self._extract_version(contract)
+
+        # Extract intent types (varies by node type)
+        intent_types = self._extract_intent_types(contract)
+
+        # Extract protocols from dependencies
+        protocols = self._extract_protocols(contract)
+
+        # Extract explicit capability tags from contract
+        explicit_tags = self._extract_explicit_tags(contract)
+
+        # Infer additional tags using rules
+        inferred_tags = self._rules.infer_all(
+            intent_types=intent_types,
+            protocols=protocols,
+            node_type=contract_type,
+        )
+
+        # Union explicit + inferred (deterministic), filtering out invalid tags
+        combined_tags = set(explicit_tags) | set(inferred_tags)
+        all_tags = sorted(tag for tag in combined_tags if self._validate_tag(tag))
+
+        return ModelContractCapabilities(
+            contract_type=contract_type,
+            contract_version=contract_version,
+            intent_types=sorted(set(intent_types)),
+            protocols=sorted(set(protocols)),
+            capability_tags=all_tags,
+        )
+
+    def _extract_contract_type(self, contract: ModelContractBase) -> str:
+        """Extract normalized contract type string.
+
+        Raises:
+            ValueError: If contract does not have node_type field.
+        """
+        node_type = getattr(contract, "node_type", None)
+        if node_type is None:
+            raise ValueError("Contract must have node_type field")
+
+        # Handle both enum and string, normalize to lowercase without _GENERIC suffix
+        type_str = node_type.value if hasattr(node_type, "value") else str(node_type)
+        return type_str.lower().replace("_generic", "")
+
+    def _extract_version(self, contract: ModelContractBase) -> ModelSemVer:
+        """Extract contract version.
+
+        Raises:
+            ValueError: If contract_version is missing or not a ModelSemVer instance.
+        """
+        version = getattr(contract, "contract_version", None)
+        if isinstance(version, ModelSemVer):
+            return version
+        raise ValueError(
+            f"Contract must have contract_version as ModelSemVer, "
+            f"got {type(version).__name__ if version is not None else 'None'}"
+        )
+
+    def _extract_intent_types(self, contract: ModelContractBase) -> list[str]:
+        """Extract intent types based on node type.
+
+        Delegates to IntentTypeExtractor which handles extraction from
+        multiple sources based on node type.
+
+        Args:
+            contract: The contract model to extract intent types from.
+
+        Returns:
+            Combined list of intent types from all applicable sources.
+        """
+        return self._intent_extractor.extract_all(contract)
+
+    def _extract_protocols(self, contract: ModelContractBase) -> list[str]:
+        """Extract protocol names from dependencies and interfaces."""
+        protocols: list[str] = []
+
+        # From protocol_interfaces field
+        if hasattr(contract, "protocol_interfaces"):
+            protocol_interfaces = contract.protocol_interfaces
+            if protocol_interfaces:
+                for proto in protocol_interfaces:
+                    if proto is not None:  # Skip None values
+                        protocols.append(proto)
+
+        # From dependencies where type is protocol
+        if hasattr(contract, "dependencies"):
+            dependencies = contract.dependencies
+            if dependencies:
+                for dep in dependencies:
+                    # Check if it's a protocol dependency using is_protocol() method
+                    if hasattr(dep, "is_protocol") and dep.is_protocol():
+                        if hasattr(dep, "name") and dep.name:
+                            protocols.append(dep.name)
+                    # Fallback: check dependency_type directly
+                    elif hasattr(dep, "dependency_type"):
+                        dep_type = dep.dependency_type
+                        type_str = (
+                            dep_type.value
+                            if hasattr(dep_type, "value")
+                            else str(dep_type)
+                        )
+                        if type_str.upper() == "PROTOCOL":
+                            if hasattr(dep, "name") and dep.name:
+                                protocols.append(dep.name)
+
+        return protocols
+
+    def _validate_tag(self, tag: str | None) -> bool:
+        """Validate a tag string.
+
+        Args:
+            tag: Tag string to validate.
+
+        Returns:
+            True if the tag is valid, False otherwise.
+            Invalid tags include: None, empty strings, whitespace-only strings.
+        """
+        if tag is None:
+            return False
+        if not isinstance(tag, str):
+            return False
+        if tag == "":
+            return False
+        if tag.strip() == "":
+            return False
+        return True
+
+    def _extract_explicit_tags(self, contract: ModelContractBase) -> list[str]:
+        """Extract explicitly declared capability tags from contract."""
+        tags: list[str] = []
+
+        # From top-level tags field (all contracts have this)
+        if hasattr(contract, "tags"):
+            contract_tags = contract.tags
+            if contract_tags:
+                for tag in contract_tags:
+                    if self._validate_tag(tag):
+                        tags.append(tag)
+
+        return tags

omnibase_infra/capabilities/intent_type_extractor.py

@@ -0,0 +1,160 @@
+"""Intent type extraction from ONEX contracts.
+
+Extracts intent types from various contract structures including
+event_type, consumed_events, published_events, and aggregation fields.
+
+OMN-1136: Intent type extraction helper for ContractCapabilityExtractor.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from omnibase_core.models.contracts import ModelContractBase
+
+
+class IntentTypeExtractor:
+    """Extracts intent types from contract models.
+
+    This class handles extraction of intent types from various contract
+    structures. Different node types expose intent information in different
+    locations:
+    - Effect nodes: event_type.primary_events
+    - Orchestrator nodes: consumed_events[].event_pattern, published_events[].event_name
+    - Reducer nodes: aggregation.aggregation_functions
+
+    This extractor is stateless and produces deterministic output.
+
+    Example:
+        extractor = IntentTypeExtractor()
+        intent_types = extractor.extract_all(contract)
+    """
+
+    def extract_all(self, contract: ModelContractBase) -> list[str]:
+        """Extract intent types from all applicable sources.
+
+        Combines intent types from event_type, consumed_events,
+        published_events, and aggregation fields.
+
+        Args:
+            contract: The contract model to extract intent types from.
+
+        Returns:
+            Combined list of intent types from all applicable sources.
+        """
+        intent_types: list[str] = []
+
+        intent_types.extend(self._extract_from_event_type(contract))
+        intent_types.extend(self._extract_from_consumed_events(contract))
+        intent_types.extend(self._extract_from_published_events(contract))
+        intent_types.extend(self._extract_from_aggregation(contract))
+
+        return intent_types
+
+    def _extract_from_event_type(self, contract: ModelContractBase) -> list[str]:
+        """Extract intent types from event_type.primary_events.
+
+        Used primarily by Effect nodes to declare the events they handle.
+
+        Args:
+            contract: The contract model to extract from.
+
+        Returns:
+            List of primary event types, or empty list if not present.
+        """
+        if not hasattr(contract, "event_type"):
+            return []
+
+        event_type = contract.event_type
+        if event_type is None or not hasattr(event_type, "primary_events"):
+            return []
+
+        primary_events = event_type.primary_events
+        if not primary_events:
+            return []
+
+        return list(primary_events)
+
+    def _extract_from_consumed_events(self, contract: ModelContractBase) -> list[str]:
+        """Extract intent types from consumed_events[].event_pattern.
+
+        Used by Orchestrator nodes to declare which events they subscribe to.
+
+        Args:
+            contract: The contract model to extract from.
+
+        Returns:
+            List of event patterns from consumed events, or empty list if not present.
+        """
+        if not hasattr(contract, "consumed_events"):
+            return []
+
+        consumed_events = contract.consumed_events
+        if not consumed_events:
+            return []
+
+        intent_types: list[str] = []
+        for event in consumed_events:
+            # ModelEventSubscription has event_pattern field
+            if hasattr(event, "event_pattern") and event.event_pattern:
+                intent_types.append(event.event_pattern)
+
+        return intent_types
+
+    def _extract_from_published_events(self, contract: ModelContractBase) -> list[str]:
+        """Extract intent types from published_events[].event_name.
+
+        Used by Orchestrator nodes to declare which events they publish.
+
+        Args:
+            contract: The contract model to extract from.
+
+        Returns:
+            List of event names from published events, or empty list if not present.
+        """
+        if not hasattr(contract, "published_events"):
+            return []
+
+        published_events = contract.published_events
+        if not published_events:
+            return []
+
+        intent_types: list[str] = []
+        for event in published_events:
+            # ModelEventDescriptor has event_name field
+            if hasattr(event, "event_name") and event.event_name:
+                intent_types.append(event.event_name)
+
+        return intent_types
+
+    def _extract_from_aggregation(self, contract: ModelContractBase) -> list[str]:
+        """Extract intent types from aggregation.aggregation_functions.
+
+        Used by Reducer nodes to declare aggregation patterns based on
+        the output fields of their aggregation functions.
+
+        Args:
+            contract: The contract model to extract from.
+
+        Returns:
+            List of aggregation intent types (prefixed with 'aggregate.'),
+            or empty list if not present.
+        """
+        if not hasattr(contract, "aggregation"):
+            return []
+
+        aggregation = contract.aggregation
+        if aggregation is None or not hasattr(aggregation, "aggregation_functions"):
+            return []
+
+        agg_funcs = aggregation.aggregation_functions
+        if not agg_funcs:
+            return []
+
+        intent_types: list[str] = []
+        for func in agg_funcs:
+            if hasattr(func, "output_field") and func.output_field:
+                intent_types.append(f"aggregate.{func.output_field}")
+
+        return intent_types

omnibase_infra/cli/commands.py

@@ -127,7 +127,7 @@ def validate_imports_cmd(directory: str) -> None:
     console.print(f"[bold blue]Checking circular imports in {directory}...[/bold blue]")
     result = validate_infra_circular_imports(directory)
 
-    # ModelModuleImportResult uses has_circular_imports property
+    # ModelImportValidationResult uses has_circular_imports property (plural)
     if not result.has_circular_imports:
         console.print("[bold green]Circular Imports: PASS[/bold green]")
         raise SystemExit(0)

omnibase_infra/configs/widget_mapping.yaml

@@ -0,0 +1,176 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+#
+# Widget Mapping Configuration for ONEX Registry Dashboard
+#
+# This file defines the mapping from node capabilities and semantic roles
+# to dashboard widget types. Used by the Registry API to inform dashboards
+# which widget to render for each node.
+#
+# Related Tickets:
+#   - OMN-1278: Contract-Driven Dashboard - Registry Discovery
+#
+# Widget Types:
+#   - status_indicator: Shows health/state with colored indicator
+#   - event_feed: Scrolling list of recent events
+#   - metric_card: Single metric with value and optional trend
+#   - info_card: General information display
+#   - status_grid: Grid of status indicators
+#   - timeline: Time-based visualization
+#   - gauge: Circular progress/threshold indicator
+#   - table: Tabular data display
+#
+# Configuration Sections:
+#   - version: Schema version for compatibility checking
+#   - capability_mappings: Maps capability tags to widget configs
+#   - semantic_mappings: Maps semantic roles to widget configs
+#   - fallback: Default config when no mapping matches
+version: "1.0.0"
+# Capability Mappings
+# Map specific capability tags to widget configurations.
+# These take precedence over semantic mappings.
+capability_mappings:
+  # Health and monitoring capabilities
+  health.check:
+    widget_type: status_indicator
+    defaults:
+      show_timestamp: true
+      refresh_interval_seconds: 10
+  health.heartbeat:
+    widget_type: status_indicator
+    defaults:
+      show_timestamp: true
+      show_last_seen: true
+  # Event-related capabilities
+  event.emit:
+    widget_type: event_feed
+    defaults:
+      max_items: 50
+      show_timestamp: true
+      auto_scroll: true
+  event.consume:
+    widget_type: event_feed
+    defaults:
+      max_items: 50
+      show_source: true
+  event.transform:
+    widget_type: timeline
+    defaults:
+      show_duration: true
+  # Kafka/messaging capabilities
+  kafka.consumer:
+    widget_type: metric_card
+    defaults:
+      refresh_interval_seconds: 5
+      show_lag: true
+  kafka.producer:
+    widget_type: metric_card
+    defaults:
+      refresh_interval_seconds: 5
+      show_throughput: true
+  kafka.stream:
+    widget_type: timeline
+    defaults:
+      show_offset: true
+  # Database capabilities
+  postgres.storage:
+    widget_type: metric_card
+    defaults:
+      show_connection_count: true
+      refresh_interval_seconds: 10
+  postgres.query:
+    widget_type: table
+    defaults:
+      show_query_time: true
+  # Service discovery
+  consul.register:
+    widget_type: status_indicator
+    defaults:
+      show_service_id: true
+  consul.discover:
+    widget_type: status_grid
+    defaults:
+      show_health: true
+      group_by: service_name
+  # Workflow capabilities
+  workflow.orchestrate:
+    widget_type: timeline
+    defaults:
+      show_steps: true
+      show_duration: true
+  workflow.reduce:
+    widget_type: gauge
+    defaults:
+      show_progress: true
+  # Compute capabilities
+  compute.transform:
+    widget_type: metric_card
+    defaults:
+      show_throughput: true
+      show_latency: true
+  compute.validate:
+    widget_type: status_indicator
+    defaults:
+      show_pass_rate: true
+  # Effect capabilities
+  effect.http:
+    widget_type: metric_card
+    defaults:
+      show_latency: true
+      show_error_rate: true
+  effect.grpc:
+    widget_type: metric_card
+    defaults:
+      show_latency: true
+      show_error_rate: true
+# Semantic Mappings
+# Map semantic roles/contexts to widget configurations.
+# Used when capability_mappings don't match.
+semantic_mappings:
+  # Node overview in dashboard
+  node_overview:
+    widget_type: info_card
+    defaults:
+      show_version: true
+      show_capabilities: true
+      show_state: true
+  # Instance health grid
+  instance_health:
+    widget_type: status_grid
+    defaults:
+      group_by: service_name
+      show_address: true
+      show_port: true
+  # Registration timeline
+  registration_timeline:
+    widget_type: timeline
+    defaults:
+      show_state_transitions: true
+      show_timestamps: true
+  # Capability matrix
+  capability_matrix:
+    widget_type: table
+    defaults:
+      group_by: node_type
+      show_capability_tags: true
+  # Summary statistics
+  summary_stats:
+    widget_type: metric_card
+    defaults:
+      show_trend: true
+      compare_to_previous: true
+  # Error monitoring
+  error_monitoring:
+    widget_type: event_feed
+    defaults:
+      filter_level: error
+      max_items: 100
+      highlight_critical: true
+# Fallback Configuration
+# Used when no capability or semantic mapping matches.
+fallback:
+  widget_type: info_card
+  defaults:
+    show_name: true
+    show_state: true
+    show_type: true

omnibase_infra/contracts/handlers/filesystem/handler_contract.yaml

@@ -1,12 +1,15 @@
 # Handler ID follows convention: {node_type}.{domain}.handler
 handler_id: effect.filesystem.handler
 name: FileSystem Handler
-version: "1.0.0"
+contract_version:
+  major: 1
+  minor: 0
+  patch: 0
 description: >
   Effect handler for filesystem operations including read, write, list, delete, and directory management.
 
 descriptor:
-  handler_kind: effect
+  node_archetype: effect
   purity: side_effecting
   # Idempotent: false because write operations may append (non-idempotent).
   # Individual operations (write w/ overwrite, mkdir w/ exist_ok) can be

omnibase_infra/contracts/handlers/mcp/handler_contract.yaml

@@ -1,12 +1,15 @@
 # Handler ID follows convention: {node_type}.{domain}.handler
 handler_id: effect.mcp.handler
 name: MCP Handler
-version: "1.0.0"
+contract_version:
+  major: 1
+  minor: 0
+  patch: 0
 description: >
   Effect handler for Model Context Protocol (MCP) integration. Exposes ONEX nodes as MCP tools for AI agent integration via streamable HTTP transport.
 
 descriptor:
-  handler_kind: effect
+  node_archetype: effect
   purity: side_effecting
   # Idempotent: true for list_tools/describe, false for call_tool (depends on target)
   # Overall handler is marked non-idempotent since tool execution may have side effects.

omnibase_infra/enums/__init__.py

@@ -23,11 +23,13 @@ Exports:
     EnumHandlerErrorType: Handler error types for validation and lifecycle
     EnumHandlerLoaderError: Handler loader error codes for plugin loading
     EnumResponseStatus: Handler response status (SUCCESS, ERROR)
+    EnumHandlerSourceMode: Handler source modes for loading strategy (BOOTSTRAP, CONTRACT, HYBRID)
     EnumHandlerSourceType: Handler validation error source types
     EnumHandlerType: Handler architectural roles (INFRA_HANDLER, NODE_HANDLER)
     EnumHandlerTypeCategory: Behavioral classification (COMPUTE, EFFECT)
     EnumInfraTransportType: Infrastructure transport type enumeration
     EnumIntrospectionReason: Introspection event reasons (STARTUP, SHUTDOWN, etc.)
+    EnumKafkaAcks: Kafka producer acknowledgment policy (ALL, NONE, LEADER, ALL_REPLICAS)
     EnumMessageCategory: Message categories (EVENT, COMMAND, INTENT)
     EnumNodeArchetype: 4-node architecture (EFFECT, COMPUTE, REDUCER, ORCHESTRATOR)
     EnumNodeOutputType: Node output types for execution shape validation
@@ -61,11 +63,13 @@ from omnibase_infra.enums.enum_execution_shape_violation import (
 )
 from omnibase_infra.enums.enum_handler_error_type import EnumHandlerErrorType
 from omnibase_infra.enums.enum_handler_loader_error import EnumHandlerLoaderError
+from omnibase_infra.enums.enum_handler_source_mode import EnumHandlerSourceMode
 from omnibase_infra.enums.enum_handler_source_type import EnumHandlerSourceType
 from omnibase_infra.enums.enum_handler_type import EnumHandlerType
 from omnibase_infra.enums.enum_handler_type_category import EnumHandlerTypeCategory
 from omnibase_infra.enums.enum_infra_transport_type import EnumInfraTransportType
 from omnibase_infra.enums.enum_introspection_reason import EnumIntrospectionReason
+from omnibase_infra.enums.enum_kafka_acks import EnumKafkaAcks
 from omnibase_infra.enums.enum_message_category import EnumMessageCategory
 from omnibase_infra.enums.enum_node_archetype import EnumNodeArchetype
 from omnibase_infra.enums.enum_node_output_type import EnumNodeOutputType
@@ -100,11 +104,13 @@ __all__: list[str] = [
     "EnumExecutionShapeViolation",
     "EnumHandlerErrorType",
     "EnumHandlerLoaderError",
+    "EnumHandlerSourceMode",
     "EnumHandlerSourceType",
     "EnumHandlerType",
     "EnumHandlerTypeCategory",
     "EnumInfraTransportType",
     "EnumIntrospectionReason",
+    "EnumKafkaAcks",
     "EnumMessageCategory",
     "EnumNodeArchetype",
     "EnumNodeOutputType",

omnibase_infra/enums/enum_handler_error_type.py

@@ -43,6 +43,13 @@ class EnumHandlerErrorType(str, Enum):
             The parsed contract contains invalid field values or violates
             schema constraints defined in the ONEX contract specification.
 
+    Discovery Errors:
+        DISCOVERY_ERROR: Handler discovery failed due to infrastructure issues.
+            The handler could not be discovered due to connection failures,
+            timeouts, or other infrastructure problems (e.g., Consul unavailable,
+            network errors). This is distinct from parse/validation errors which
+            occur AFTER the contract is successfully retrieved.
+
     Validation Errors:
         DESCRIPTOR_VALIDATION_ERROR: Handler descriptor validation failed.
             The handler descriptor (metadata, annotations, signature) does not
@@ -80,6 +87,9 @@ class EnumHandlerErrorType(str, Enum):
     CONTRACT_PARSE_ERROR = "contract_parse_error"
     CONTRACT_VALIDATION_ERROR = "contract_validation_error"
 
+    # Discovery errors
+    DISCOVERY_ERROR = "discovery_error"
+
     # Validation errors
     DESCRIPTOR_VALIDATION_ERROR = "descriptor_validation_error"
     SECURITY_VALIDATION_ERROR = "security_validation_error"