omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/models/registration/model_node_capabilities.py

@@ -0,0 +1,190 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Node Capabilities Model.
+
+This module provides ModelNodeCapabilities for strongly-typed node capabilities
+in the ONEX 2-way registration pattern.
+
+Note:
+    This model does NOT use MixinDictLikeAccessors because it requires custom
+    logic to differentiate between known model fields (model_fields) and custom
+    capabilities stored in model_extra. The mixin's simple hasattr/getattr pattern
+    would not correctly handle this distinction.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_core.types import JsonType
+from omnibase_infra.models.mcp.model_mcp_contract_config import ModelMCPContractConfig
+
+
+class ModelNodeCapabilities(BaseModel):
+    """Strongly-typed node capabilities model.
+
+    Uses explicit capability fields instead of generic dictionaries.
+    Uses extra="allow" to support custom capabilities while
+    providing type safety for known fields.
+
+    Known capability fields are typed explicitly. Additional custom
+    capabilities can be added via the extra="allow" config, and they
+    will be stored as model extra fields accessible via model_extra.
+
+    Attributes:
+        postgres: Whether node has PostgreSQL capability.
+        read: Whether node has read capability.
+        write: Whether node has write capability.
+        database: Whether node has generic database capability.
+        processing: Whether node has processing capability.
+        batch_size: Optional batch size limit.
+        max_batch: Optional maximum batch size.
+        supported_types: List of supported data types.
+        routing: Whether node has routing capability.
+        config: Nested configuration dictionary (JSON-serializable values only).
+        transactions: Whether node supports transactions.
+        feature: Generic feature flag.
+
+    Example:
+        >>> caps = ModelNodeCapabilities(
+        ...     postgres=True,
+        ...     read=True,
+        ...     write=True,
+        ... )
+        >>> caps.postgres
+        True
+
+        >>> # Custom capabilities via extra="allow"
+        >>> caps = ModelNodeCapabilities(
+        ...     custom_capability=True,  # type: ignore[call-arg]
+        ...     another_field="value",  # type: ignore[call-arg]
+        ... )
+        >>> caps.model_extra["custom_capability"]
+        True
+    """
+
+    model_config = ConfigDict(
+        extra="allow",  # Accept additional fields not explicitly defined
+        frozen=False,  # Allow updates (ModelNodeRegistration is mutable)
+        from_attributes=True,
+    )
+
+    # Database capabilities
+    postgres: bool = Field(default=False, description="PostgreSQL capability")
+    read: bool = Field(default=False, description="Read capability")
+    write: bool = Field(default=False, description="Write capability")
+    database: bool = Field(default=False, description="Generic database capability")
+    transactions: bool = Field(default=False, description="Transaction support")
+
+    # Processing capabilities
+    processing: bool = Field(default=False, description="Processing capability")
+    batch_size: int | None = Field(default=None, description="Batch size limit")
+    max_batch: int | None = Field(default=None, description="Maximum batch size")
+    supported_types: list[str] = Field(
+        default_factory=list, description="Supported data types"
+    )
+
+    # Network capabilities
+    routing: bool = Field(default=False, description="Routing capability")
+
+    # Generic feature flag (used in tests)
+    feature: bool = Field(default=False, description="Generic feature flag")
+
+    # Configuration (nested) - uses JsonType for JSON-serializable values.
+    # Supports primitives (str, int, float, bool, None), lists, and nested dicts.
+    config: dict[str, JsonType] = Field(
+        default_factory=dict,
+        description="Nested configuration (JSON-serializable values)",
+    )
+
+    # MCP configuration for exposing node as AI agent tool
+    # Only valid for ORCHESTRATOR nodes - ignored for other node types
+    mcp: ModelMCPContractConfig | None = Field(
+        default=None,
+        description="MCP configuration for exposing node as AI agent tool. "
+        "Only valid for ORCHESTRATOR_GENERIC nodes.",
+    )
+
+    def __getitem__(self, key: str) -> object:
+        """Enable dict-like access to capabilities.
+
+        Args:
+            key: The capability name to retrieve.
+
+        Returns:
+            The capability value (from known field or model_extra).
+
+        Raises:
+            KeyError: If key is not found in known fields or model_extra.
+
+        Example:
+            >>> caps = ModelNodeCapabilities(postgres=True, custom=42)
+            >>> caps["postgres"]
+            True
+            >>> caps["custom"]  # Custom capability from model_extra
+            42
+        """
+        if key in type(self).model_fields:
+            return getattr(self, key)
+        extra = self.model_extra or {}
+        if key in extra:
+            return extra[key]
+        raise KeyError(key)
+
+    def __contains__(self, key: object) -> bool:
+        """Enable membership testing for capabilities.
+
+        Returns True if key is a known field OR exists in model_extra.
+
+        Args:
+            key: The capability name to check.
+
+        Returns:
+            True if the key exists as a known field or in model_extra.
+
+        Example:
+            >>> caps = ModelNodeCapabilities(postgres=True, custom=42)
+            >>> "postgres" in caps
+            True
+            >>> "custom" in caps  # Custom capability in model_extra
+            True
+            >>> "unknown" in caps
+            False
+        """
+        if not isinstance(key, str):
+            return False
+
+        # Check known fields first (access via class to avoid deprecation)
+        if key in type(self).model_fields:
+            return True
+
+        # Check model_extra for custom capabilities
+        return bool(self.model_extra and key in self.model_extra)
+
+    def get(self, key: str, default: object = None) -> object:
+        """Safely get a capability value with optional default.
+
+        Args:
+            key: The capability name to retrieve.
+            default: Value to return if key is not found (defaults to None).
+
+        Returns:
+            The capability value if found, otherwise the default value.
+
+        Example:
+            >>> caps = ModelNodeCapabilities(postgres=True)
+            >>> caps.get("postgres")
+            True
+            >>> caps.get("unknown", False)
+            False
+            >>> caps.get("unknown")  # Returns None by default
+        """
+        try:
+            return self[key]
+        except KeyError:
+            return default
+
+
+__all__ = [
+    "ModelNodeCapabilities",
+]

omnibase_infra/models/registration/model_node_event_bus_config.py

@@ -0,0 +1,99 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Node Event Bus Configuration Model.
+
+This module provides the model for a node's resolved event bus configuration,
+containing lists of topics the node subscribes to and publishes to.
+
+Key Design Decisions:
+    1. Topics stored as environment-qualified strings (e.g., "dev.onex.evt.intent-classified.v1")
+    2. Metadata fields are tooling-only; routing uses ONLY topic strings
+    3. Property methods extract topic strings only for routing lookups
+    4. Model is frozen (immutable) with extra="forbid" for safety
+
+Example:
+    >>> from omnibase_infra.models.registration import (
+    ...     ModelEventBusTopicEntry,
+    ...     ModelNodeEventBusConfig,
+    ... )
+    >>> entry = ModelEventBusTopicEntry(
+    ...     topic="dev.onex.evt.intent-classified.v1",
+    ...     event_type="ModelIntentClassified",
+    ... )
+    >>> config = ModelNodeEventBusConfig(subscribe_topics=[entry])
+    >>> config.subscribe_topic_strings
+    ['dev.onex.evt.intent-classified.v1']
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.models.registration.model_event_bus_topic_entry import (
+    ModelEventBusTopicEntry,
+)
+
+
+class ModelNodeEventBusConfig(BaseModel):
+    """Resolved event bus configuration for registry storage.
+
+    This model holds the resolved, environment-qualified topic strings
+    that a node subscribes to and publishes to. It is designed for
+    storage in the registry to enable dynamic topic-based routing.
+
+    The property methods (subscribe_topic_strings, publish_topic_strings)
+    extract only the topic strings for routing lookups, ignoring all
+    metadata fields.
+
+    Attributes:
+        subscribe_topics: List of topics the node subscribes to.
+        publish_topics: List of topics the node publishes to.
+
+    Example:
+        >>> config = ModelNodeEventBusConfig(
+        ...     subscribe_topics=[
+        ...         ModelEventBusTopicEntry(topic="dev.onex.evt.input.v1"),
+        ...     ],
+        ...     publish_topics=[
+        ...         ModelEventBusTopicEntry(topic="dev.onex.evt.output.v1"),
+        ...     ],
+        ... )
+        >>> config.subscribe_topic_strings
+        ['dev.onex.evt.input.v1']
+        >>> config.publish_topic_strings
+        ['dev.onex.evt.output.v1']
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid")
+
+    subscribe_topics: list[ModelEventBusTopicEntry] = Field(
+        default_factory=list,
+        description="List of topics the node subscribes to.",
+    )
+    publish_topics: list[ModelEventBusTopicEntry] = Field(
+        default_factory=list,
+        description="List of topics the node publishes to.",
+    )
+
+    @property
+    def subscribe_topic_strings(self) -> list[str]:
+        """Extract topic strings only, for routing lookups.
+
+        Returns:
+            List of environment-qualified topic strings from subscribe_topics.
+            Metadata fields are ignored.
+        """
+        return [entry.topic for entry in self.subscribe_topics]
+
+    @property
+    def publish_topic_strings(self) -> list[str]:
+        """Extract topic strings only, for routing lookups.
+
+        Returns:
+            List of environment-qualified topic strings from publish_topics.
+            Metadata fields are ignored.
+        """
+        return [entry.topic for entry in self.publish_topics]
+
+
+__all__ = ["ModelNodeEventBusConfig"]

omnibase_infra/models/registration/model_node_heartbeat_event.py

@@ -0,0 +1,126 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Node Heartbeat Event Model.
+
+This module provides ModelNodeHeartbeatEvent for periodic node heartbeat broadcasts
+in the ONEX 2-way registration pattern.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from omnibase_core.enums import EnumNodeKind
+from omnibase_core.models.primitives.model_semver import ModelSemVer
+from omnibase_infra.utils import validate_timezone_aware_datetime
+
+
+class ModelNodeHeartbeatEvent(BaseModel):
+    """Event model for periodic node heartbeat broadcasts.
+
+    Nodes publish this event periodically to indicate they are alive and
+    report current health metrics. Used by the Registry node to detect
+    node failures and track resource usage.
+
+    Attributes:
+        node_id: Node identifier.
+        node_type: ONEX node type (EnumNodeKind).
+        node_version: Semantic version of the node emitting this event.
+        uptime_seconds: Node uptime in seconds (must be >= 0).
+        active_operations_count: Number of active operations (must be >= 0).
+        memory_usage_mb: Optional memory usage in megabytes.
+        cpu_usage_percent: Optional CPU usage percentage (0-100).
+        correlation_id: Request correlation ID for tracing.
+        timestamp: Event timestamp.
+
+    Example:
+        >>> from datetime import UTC, datetime
+        >>> from uuid import uuid4
+        >>> from omnibase_core.enums import EnumNodeKind
+        >>> from omnibase_core.models.primitives.model_semver import ModelSemVer
+        >>> event = ModelNodeHeartbeatEvent(
+        ...     node_id=uuid4(),
+        ...     node_type=EnumNodeKind.EFFECT,
+        ...     node_version=ModelSemVer(major=1, minor=2, patch=3),
+        ...     uptime_seconds=3600.5,
+        ...     active_operations_count=5,
+        ...     memory_usage_mb=256.0,
+        ...     cpu_usage_percent=15.5,
+        ...     timestamp=datetime(2025, 1, 15, 12, 0, 0, tzinfo=UTC),
+        ... )
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    # Required fields
+    node_id: UUID = Field(..., description="Node identifier")
+    # Design Note: node_type uses EnumNodeKind for type consistency across the codebase.
+    # This aligns with ModelNodeIntrospectionEvent which also uses EnumNodeKind, ensuring
+    # consistent type handling for all node-related events. The previous relaxed `str`
+    # validation was speculative support for experimental/plugin nodes that never existed.
+    node_type: EnumNodeKind = Field(..., description="ONEX node type")
+    node_version: ModelSemVer = Field(
+        default_factory=lambda: ModelSemVer(major=1, minor=0, patch=0),
+        description="Semantic version of the node emitting this event",
+    )
+
+    @field_validator("node_version", mode="before")
+    @classmethod
+    def parse_node_version(cls, v: ModelSemVer | str) -> ModelSemVer:
+        """Parse node_version from string or ModelSemVer.
+
+        Args:
+            v: Either a ModelSemVer instance or a semver string.
+
+        Returns:
+            Validated ModelSemVer instance.
+
+        Raises:
+            ValueError: If the string is not a valid semantic version.
+        """
+        if isinstance(v, str):
+            try:
+                return ModelSemVer.parse(v)
+            except Exception as e:
+                raise ValueError(f"node_version: {e!s}") from e
+        return v
+
+    # Health metrics
+    uptime_seconds: float = Field(..., ge=0, description="Node uptime in seconds")
+    active_operations_count: int = Field(
+        default=0, ge=0, description="Number of active operations"
+    )
+
+    # Resource usage (optional)
+    memory_usage_mb: float | None = Field(
+        default=None, ge=0, description="Memory usage in megabytes"
+    )
+    cpu_usage_percent: float | None = Field(
+        default=None, ge=0, le=100, description="CPU usage percentage (0-100)"
+    )
+
+    # Metadata
+    correlation_id: UUID | None = Field(
+        default=None, description="Request correlation ID for tracing"
+    )
+    # Timestamps - MUST be explicitly injected (no default_factory for testability)
+    timestamp: datetime = Field(..., description="Event timestamp")
+
+    @field_validator("timestamp")
+    @classmethod
+    def validate_timestamp_timezone_aware(cls, v: datetime) -> datetime:
+        """Validate that timestamp is timezone-aware.
+
+        Delegates to shared utility for consistent validation across all models.
+        """
+        return validate_timezone_aware_datetime(v)
+
+
+__all__ = ["ModelNodeHeartbeatEvent"]

omnibase_infra/models/registration/model_node_introspection_event.py

@@ -0,0 +1,195 @@
+# SPDX-License-Identifier: Apache-2.0
+# Copyright (c) 2025 OmniNode Team
+"""Unified Node Introspection Event Model.
+
+This module provides ModelNodeIntrospectionEvent for node introspection broadcasts
+in the ONEX registration and discovery patterns.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from omnibase_core.enums import EnumNodeKind
+from omnibase_core.models.capabilities import ModelContractCapabilities
+from omnibase_core.models.primitives.model_semver import ModelSemVer
+from omnibase_infra.enums import EnumIntrospectionReason
+from omnibase_infra.models.discovery.model_discovered_capabilities import (
+    ModelDiscoveredCapabilities,
+)
+from omnibase_infra.models.discovery.model_introspection_performance_metrics import (
+    ModelIntrospectionPerformanceMetrics,
+)
+from omnibase_infra.models.registration.model_node_capabilities import (
+    ModelNodeCapabilities,
+)
+from omnibase_infra.models.registration.model_node_event_bus_config import (
+    ModelNodeEventBusConfig,
+)
+from omnibase_infra.models.registration.model_node_metadata import ModelNodeMetadata
+from omnibase_infra.utils import (
+    validate_endpoint_urls_dict,
+    validate_timezone_aware_datetime,
+)
+
+
+class ModelNodeIntrospectionEvent(BaseModel):
+    """Unified event model for node introspection broadcasts.
+
+    Nodes publish this event to announce their presence, capabilities,
+    and endpoints to the cluster. Used by the Registry node to maintain
+    a live catalog of available nodes and by introspection for service discovery.
+
+    This model co-locates both declared capabilities (from contract) and
+    discovered capabilities (from reflection) - they are NOT unified as they
+    represent fundamentally different data.
+
+    Attributes:
+        node_id: Unique node identifier.
+        node_type: ONEX node type (EFFECT, COMPUTE, REDUCER, ORCHESTRATOR).
+        node_version: Semantic version of the node.
+        declared_capabilities: Contract-declared capabilities (feature flags).
+        discovered_capabilities: Runtime-discovered capabilities (reflection).
+        contract_capabilities: Contract-derived capabilities (design-time truth).
+            Populated from the node's contract when available, None otherwise.
+        endpoints: Dictionary of exposed endpoints (name -> URL).
+        current_state: Current FSM state if the node has state management.
+        reason: Why this introspection event was emitted.
+        correlation_id: Required correlation ID for tracing and idempotency.
+        timestamp: Event timestamp (must be timezone-aware).
+        node_role: Optional role descriptor (registry, adapter, etc).
+        metadata: Additional node metadata.
+        network_id: Network/cluster identifier.
+        deployment_id: Deployment/release identifier.
+        epoch: Registration epoch for ordering.
+        performance_metrics: Optional metrics from introspection operation.
+        event_bus: Resolved event bus topic configuration for registry-driven routing.
+            If None, node is NOT included in dynamic topic routing lookups.
+
+    Example:
+        >>> from uuid import uuid4
+        >>> from datetime import datetime, timezone
+        >>> from omnibase_core.enums import EnumNodeKind
+        >>> from omnibase_core.models.primitives.model_semver import ModelSemVer
+        >>> event = ModelNodeIntrospectionEvent(
+        ...     node_id=uuid4(),
+        ...     node_type=EnumNodeKind.EFFECT,
+        ...     node_version=ModelSemVer(major=1, minor=2, patch=3),
+        ...     correlation_id=uuid4(),
+        ...     timestamp=datetime.now(timezone.utc),
+        ... )
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    # Core identity (required, strongly typed)
+    node_id: UUID = Field(..., description="Unique node identifier")
+    node_type: EnumNodeKind = Field(..., description="ONEX node type")
+    node_version: ModelSemVer = Field(
+        default_factory=lambda: ModelSemVer(major=1, minor=0, patch=0),
+        description="Semantic version of the node",
+    )
+
+    # Co-located capabilities (different purposes, different structures)
+    declared_capabilities: ModelNodeCapabilities = Field(
+        default_factory=ModelNodeCapabilities,
+        description="Node-declared capabilities from contract (feature flags)",
+    )
+    discovered_capabilities: ModelDiscoveredCapabilities = Field(
+        default_factory=ModelDiscoveredCapabilities,
+        description="Capabilities discovered via runtime reflection",
+    )
+    contract_capabilities: ModelContractCapabilities | None = Field(
+        default=None,
+        description="Contract-derived capabilities (design-time truth, deterministic). "
+        "Populated by ContractCapabilityExtractor from the node's contract. "
+        "None when contract is not available or extraction fails.",
+    )
+
+    # Endpoints and state
+    endpoints: dict[str, str] = Field(
+        default_factory=dict,
+        description="Exposed endpoints (name -> URL)",
+    )
+
+    @field_validator("endpoints")
+    @classmethod
+    def validate_endpoint_urls(cls, v: dict[str, str]) -> dict[str, str]:
+        """Validate that all endpoint values are valid URLs.
+
+        Delegates to shared utility for consistent validation across all models.
+        """
+        return validate_endpoint_urls_dict(v)
+
+    current_state: str | None = Field(
+        default=None,
+        description="Current FSM state if node has state management",
+    )
+
+    # Event metadata (strongly typed)
+    reason: EnumIntrospectionReason = Field(
+        default=EnumIntrospectionReason.STARTUP,
+        description="Why this introspection event was emitted",
+    )
+    correlation_id: UUID = Field(
+        ...,
+        description="Request correlation ID for tracing (required for idempotency)",
+    )
+    timestamp: datetime = Field(
+        ...,
+        description="Event timestamp (must be timezone-aware)",
+    )
+
+    @field_validator("timestamp")
+    @classmethod
+    def validate_timestamp_timezone_aware(cls, v: datetime) -> datetime:
+        """Validate that timestamp is timezone-aware.
+
+        Delegates to shared utility for consistent validation across all models.
+        """
+        return validate_timezone_aware_datetime(v)
+
+    # Optional registration fields
+    node_role: str | None = Field(
+        default=None,
+        description="Node role (registry, adapter, etc)",
+    )
+    metadata: ModelNodeMetadata = Field(
+        default_factory=ModelNodeMetadata,
+        description="Additional node metadata",
+    )
+    network_id: str | None = Field(
+        default=None,
+        description="Network/cluster identifier",
+    )
+    deployment_id: str | None = Field(
+        default=None,
+        description="Deployment/release identifier",
+    )
+    epoch: int | None = Field(
+        default=None,
+        ge=0,
+        description="Registration epoch for ordering (monotonically increasing)",
+    )
+
+    # Optional discovery fields
+    performance_metrics: ModelIntrospectionPerformanceMetrics | None = Field(
+        default=None,
+        description="Performance metrics from introspection operation",
+    )
+    event_bus: ModelNodeEventBusConfig | None = Field(
+        default=None,
+        description="Resolved event bus topic configuration. "
+        "Contains environment-qualified topic strings for registry-driven routing. "
+        "If None, node is NOT included in dynamic topic routing lookups.",
+    )
+
+
+__all__ = ["ModelNodeIntrospectionEvent"]

omnibase_infra/models/registration/model_node_metadata.py

@@ -0,0 +1,79 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Node Metadata Model.
+
+This module provides ModelNodeMetadata for strongly-typed node metadata
+in the ONEX 2-way registration pattern.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelNodeMetadata(BaseModel):
+    """Strongly-typed node metadata model.
+
+    Replaces dict[str, Any] with explicit metadata fields.
+    Uses extra="allow" to support custom metadata while
+    providing type safety for known fields.
+
+    Known metadata fields are typed explicitly. Additional custom
+    metadata can be added via the extra="allow" config, and they
+    will be stored as model extra fields accessible via model_extra.
+
+    Attributes:
+        version: Software version string.
+        environment: Deployment environment (e.g., production, staging).
+        region: Geographic region identifier.
+        cluster: Cluster identifier.
+        description: Human-readable description (supports Unicode).
+        priority: Priority level for scheduling/routing.
+        key: Generic key field (used in tests).
+        key1: Generic key field (used in tests).
+        meta: Generic meta field (used in tests).
+
+    Example:
+        >>> meta = ModelNodeMetadata(
+        ...     version="1.0.0",
+        ...     environment="production",
+        ...     region="us-west-2",
+        ... )
+        >>> meta.environment
+        'production'
+
+        >>> # Unicode support
+        >>> meta = ModelNodeMetadata(description="Узел обработки")
+        >>> meta.description
+        'Узел обработки'
+    """
+
+    model_config = ConfigDict(
+        extra="allow",  # Accept additional fields not explicitly defined
+        frozen=False,  # Allow updates (ModelNodeRegistration is mutable)
+        from_attributes=True,
+    )
+
+    # Common metadata fields
+    version: str | None = Field(default=None, description="Software version string")
+    environment: str | None = Field(
+        default=None, description="Deployment environment (production, staging, etc.)"
+    )
+    region: str | None = Field(default=None, description="Geographic region identifier")
+    cluster: str | None = Field(default=None, description="Cluster identifier")
+    description: str | None = Field(
+        default=None, description="Human-readable description (supports Unicode)"
+    )
+
+    # Scheduling/routing metadata
+    priority: int | None = Field(
+        default=None, description="Priority level for scheduling/routing"
+    )
+
+    # Generic fields used in tests - using constrained types
+    key: str | None = Field(default=None, description="Generic key field")
+    key1: str | None = Field(default=None, description="Generic key1 field")
+    meta: str | None = Field(default=None, description="Generic meta field")
+
+
+__all__ = ["ModelNodeMetadata"]