omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/models/mcp/__init__.py

@@ -0,0 +1,15 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""MCP models for Model Context Protocol integration."""
+
+from omnibase_infra.models.mcp.model_mcp_contract_config import ModelMCPContractConfig
+from omnibase_infra.models.mcp.model_mcp_server_config import ModelMCPServerConfig
+from omnibase_infra.models.mcp.model_mcp_tool_definition import ModelMCPToolDefinition
+from omnibase_infra.models.mcp.model_mcp_tool_parameter import ModelMCPToolParameter
+
+__all__ = [
+    "ModelMCPContractConfig",
+    "ModelMCPServerConfig",
+    "ModelMCPToolDefinition",
+    "ModelMCPToolParameter",
+]

omnibase_infra/models/mcp/model_mcp_contract_config.py

@@ -0,0 +1,80 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""MCP contract configuration model for enabling nodes as MCP tools.
+
+This model defines the `mcp` field that can be added to ONEX contracts to expose
+orchestrator nodes as MCP tools for AI agent integration.
+
+Example contract.yaml:
+    node_type: ORCHESTRATOR_GENERIC
+    mcp:
+      expose: true
+      tool_name: "workflow_execute"
+      description: "Execute a workflow"
+      timeout_seconds: 30
+
+Enforcement Rule:
+    The `mcp.expose` field is ONLY valid for ORCHESTRATOR_GENERIC nodes.
+    Non-orchestrator nodes with `mcp.expose: true` will be ignored during
+    registration - the MCP tags will not be added to Consul.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class ModelMCPContractConfig(BaseModel):
+    """MCP configuration for exposing a node as an MCP tool.
+
+    This configuration is embedded in a node's contract.yaml to enable
+    AI agents to discover and invoke the node as an MCP tool.
+
+    Attributes:
+        expose: Whether to expose this node as an MCP tool. When True and
+            the node is an orchestrator, it will be registered with Consul
+            using MCP-specific tags for tool discovery.
+        tool_name: Optional stable name for the MCP tool. If not provided,
+            defaults to the node's name. Use this to provide a consistent
+            tool name across node version changes.
+        description: Optional AI-friendly description of what this tool does.
+            If not provided, the node's description from the contract is used.
+        timeout_seconds: Optional execution timeout in seconds. Defaults to 30.
+            This is enforced when AI agents invoke the tool.
+
+    Example:
+        >>> config = ModelMCPContractConfig(
+        ...     expose=True,
+        ...     tool_name="my_workflow",
+        ...     description="Execute my custom workflow",
+        ...     timeout_seconds=60,
+        ... )
+        >>> config.expose
+        True
+    """
+
+    expose: bool = Field(
+        default=False,
+        description="Whether to expose this node as an MCP tool. "
+        "Only valid for ORCHESTRATOR_GENERIC nodes.",
+    )
+    tool_name: str | None = Field(
+        default=None,
+        description="Optional stable name for the MCP tool. "
+        "Defaults to the node's name if not specified.",
+    )
+    description: str | None = Field(
+        default=None,
+        description="Optional AI-friendly description of what this tool does. "
+        "If not provided, the node's description from the contract is used.",
+    )
+    timeout_seconds: int = Field(
+        default=30,
+        ge=1,
+        le=300,
+        description="Execution timeout in seconds for tool invocations. "
+        "Minimum: 1, Maximum: 300 (5 minutes).",
+    )
+
+
+__all__ = ["ModelMCPContractConfig"]

omnibase_infra/models/mcp/model_mcp_server_config.py

@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""MCP server configuration model.
+
+This model defines the configuration for the MCP server lifecycle,
+including Consul discovery, Kafka hot reload, and HTTP server settings.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class ModelMCPServerConfig(BaseModel):
+    """Configuration for the MCP server lifecycle.
+
+    This model captures all configuration needed for the MCP server:
+    - Consul connection settings for service discovery
+    - Kafka settings for hot reload
+    - HTTP server binding
+    - Execution defaults
+
+    Attributes:
+        consul_host: Consul server hostname for service discovery.
+        consul_port: Consul server port.
+        consul_scheme: HTTP scheme for Consul (http/https).
+        consul_token: Optional ACL token for Consul authentication.
+        kafka_enabled: Whether to enable Kafka for hot reload.
+        http_host: Host to bind the MCP HTTP server.
+        http_port: Port for the MCP HTTP server.
+        default_timeout: Default execution timeout for tools.
+        dev_mode: Whether to run in development mode (local contracts).
+        contracts_dir: Directory for contract scanning in dev mode.
+    """
+
+    consul_host: str = Field(default="localhost", description="Consul server hostname")
+    consul_port: int = Field(
+        default=8500, ge=1, le=65535, description="Consul server port"
+    )
+    consul_scheme: str = Field(
+        default="http", pattern="^https?$", description="HTTP scheme for Consul"
+    )
+    consul_token: str | None = Field(
+        default=None, description="Optional ACL token for Consul authentication"
+    )
+    kafka_enabled: bool = Field(
+        default=True, description="Whether to enable Kafka for hot reload"
+    )
+    http_host: str = Field(
+        default="0.0.0.0",  # noqa: S104 - Intentional bind-all for server
+        description="Host to bind the MCP HTTP server",
+    )
+    http_port: int = Field(
+        default=8090, ge=1, le=65535, description="Port for the MCP HTTP server"
+    )
+    default_timeout: float = Field(
+        default=30.0, gt=0, le=300, description="Default execution timeout for tools"
+    )
+    dev_mode: bool = Field(
+        default=False, description="Whether to run in development mode"
+    )
+    contracts_dir: str | None = Field(
+        default=None, description="Directory for contract scanning in dev mode"
+    )
+
+
+__all__ = ["ModelMCPServerConfig"]

omnibase_infra/models/mcp/model_mcp_tool_definition.py

@@ -0,0 +1,73 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""MCP tool definition model for representing ONEX nodes as MCP tools.
+
+This model is used by the MCP adapter layer to:
+1. Cache discovered tools in the registry
+2. Generate MCP tool schemas for AI agents
+3. Route tool invocations to ONEX orchestrators
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+from omnibase_infra.models.mcp.model_mcp_tool_parameter import ModelMCPToolParameter
+
+
+class ModelMCPToolDefinition(BaseModel):
+    """Complete MCP tool definition derived from an ONEX orchestrator node.
+
+    This model captures all information needed to:
+    - Expose the tool to AI agents via MCP protocol
+    - Route invocations to the correct ONEX orchestrator
+    - Enforce execution constraints (timeout, etc.)
+
+    Attributes:
+        name: Stable tool name for AI agent invocation. This is derived from
+            contract.mcp.tool_name or falls back to the node name.
+        description: AI-friendly description of tool functionality.
+        version: Tool version from the node contract.
+        parameters: List of input parameters with type information.
+        input_schema: JSON Schema for input validation.
+        orchestrator_node_id: UUID of the ONEX orchestrator node.
+        orchestrator_service_id: Consul service ID for routing.
+        endpoint: HTTP endpoint for direct invocation (if available).
+        timeout_seconds: Execution timeout for tool invocations.
+        metadata: Additional metadata for routing and observability.
+    """
+
+    name: str = Field(description="Stable tool name for MCP invocation")
+    description: str = Field(description="AI-friendly tool description")
+    version: str = Field(default="1.0.0", description="Tool version")
+    parameters: list[ModelMCPToolParameter] = Field(
+        default_factory=list, description="Input parameters"
+    )
+    input_schema: dict[str, object] = Field(
+        default_factory=lambda: dict[str, object]({"type": "object", "properties": {}}),
+        description="JSON Schema for input validation",
+    )
+    orchestrator_node_id: str | None = Field(
+        default=None, description="UUID of the source orchestrator node"
+    )
+    orchestrator_service_id: str | None = Field(
+        default=None, description="Consul service ID for routing"
+    )
+    endpoint: str | None = Field(
+        default=None, description="HTTP endpoint for direct invocation"
+    )
+    timeout_seconds: int = Field(
+        default=30, ge=1, le=300, description="Execution timeout in seconds"
+    )
+    metadata: dict[str, object] = Field(
+        default_factory=dict,
+        description="Additional metadata (tags, input_model module, etc.)",
+    )
+
+    @property
+    def tool_type(self) -> str:
+        """Return the MCP tool type. Always 'function' for ONEX nodes."""
+        return "function"
+
+
+__all__ = ["ModelMCPToolDefinition"]

omnibase_infra/models/mcp/model_mcp_tool_parameter.py

@@ -0,0 +1,35 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""MCP tool parameter model for representing tool input parameters."""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class ModelMCPToolParameter(BaseModel):
+    """Parameter definition for an MCP tool.
+
+    Represents a single parameter that can be passed to an MCP tool,
+    including its type, validation constraints, and documentation.
+    """
+
+    name: str = Field(description="Parameter name")
+    parameter_type: str = Field(
+        default="string",
+        description="JSON Schema type: string, number, boolean, array, object",
+    )
+    description: str = Field(default="", description="Human-readable description")
+    required: bool = Field(
+        default=True, description="Whether this parameter is required"
+    )
+    default_value: object | None = Field(
+        default=None, description="Default value if not provided"
+    )
+    json_schema: dict[str, object] | None = Field(
+        default=None,
+        description="Additional JSON Schema constraints (enum, format, etc.)",
+    )
+
+
+__all__ = ["ModelMCPToolParameter"]

omnibase_infra/models/model_node_identity.py

@@ -0,0 +1,126 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Node Identity Model for ONEX Infrastructure.
+
+This module provides a typed Pydantic model for uniquely identifying ONEX nodes
+within the infrastructure. The identity encapsulates the environment, service,
+node name, and version - the four dimensions required to uniquely identify
+a node instance.
+
+The model is immutable (frozen) to ensure identity stability throughout a node's
+lifecycle. Once created, a node identity cannot be modified.
+
+.. versionadded:: 0.2.6
+    Created as part of OMN-1602 typed node identity for introspection.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationInfo, field_validator
+
+
+class ModelNodeIdentity(BaseModel):
+    """Typed identity for ONEX infrastructure nodes.
+
+    This model uniquely identifies a node within the ONEX infrastructure using
+    four dimensions: environment, service, node name, and version. The same
+    node identity can be used with different purposes (e.g., introspection,
+    registration, heartbeat) - purpose is passed separately to operations.
+
+    All fields are required and must be non-empty strings without whitespace-only
+    values. The model is frozen to ensure identity immutability.
+
+    Attributes:
+        env: Environment identifier (e.g., "dev", "staging", "prod").
+            Determines which infrastructure deployment the node belongs to.
+        service: Service name from the node's contract (e.g., "omniintelligence",
+            "omnibridge"). Groups related nodes under a common service boundary.
+        node_name: Node name from the contract (e.g., "claude_hook_event_effect",
+            "registration_orchestrator"). Uniquely identifies the node within
+            its service.
+        version: Version string for the node (e.g., "v1", "v2.0.0").
+            Enables version-aware routing and registration. While any non-empty
+            string is accepted, semver-style prefixed with 'v' is recommended
+            for consistency (e.g., 'v1', 'v1.0.0', 'v2.1.3').
+
+    Example:
+        >>> identity = ModelNodeIdentity(
+        ...     env="dev",
+        ...     service="omniintelligence",
+        ...     node_name="claude_hook_event_effect",
+        ...     version="v1",
+        ... )
+        >>> identity.env
+        'dev'
+        >>> identity.service
+        'omniintelligence'
+
+        The model is immutable - attempting to modify raises an error:
+
+        >>> identity.env = "prod"  # doctest: +SKIP
+        Traceback (most recent call last):
+            ...
+        pydantic_core._pydantic_core.ValidationError: ...
+
+        Empty or whitespace-only values are rejected:
+
+        >>> ModelNodeIdentity(env="", service="svc", node_name="node", version="v1")
+        Traceback (most recent call last):
+            ...
+        pydantic_core._pydantic_core.ValidationError: ...
+
+    Note:
+        The `purpose` field is intentionally NOT included in this model.
+        Purpose (e.g., "introspection", "registration") is passed separately
+        to operations because the same node identity can be used for multiple
+        purposes.
+
+    .. versionadded:: 0.2.6
+        Created as part of OMN-1602.
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+    )
+
+    env: str = Field(
+        description="Environment identifier (e.g., 'dev', 'staging', 'prod')",
+    )
+    service: str = Field(
+        description="Service name from the node's contract (e.g., 'omniintelligence')",
+    )
+    node_name: str = Field(  # pattern-ok: canonical identifier, not a foreign key reference
+        description="Node name from the contract (e.g., 'claude_hook_event_effect')",
+    )
+    version: str = Field(
+        description="Version string for the node (e.g., 'v1', 'v2.0.0')",
+    )
+
+    @field_validator("env", "service", "node_name", "version", mode="after")
+    @classmethod
+    def _validate_non_empty(cls, v: str, info: ValidationInfo) -> str:
+        """Validate that string fields are non-empty and not whitespace-only.
+
+        Args:
+            v: The string value to validate.
+            info: Pydantic validation context containing field name.
+
+        Returns:
+            The validated string value.
+
+        Raises:
+            ValueError: If the value is empty or contains only whitespace.
+        """
+        field_name = info.field_name
+        if not v:
+            msg = f"'{field_name}' must not be empty"
+            raise ValueError(msg)
+        if not v.strip():
+            msg = f"'{field_name}' must not contain only whitespace"
+            raise ValueError(msg)
+        return v
+
+
+__all__: list[str] = ["ModelNodeIdentity"]

omnibase_infra/models/model_retry_error_classification.py

@@ -0,0 +1,78 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Retry Error Classification Model.
+
+This module provides a Pydantic model for encapsulating the result of error
+classification during retry handling in infrastructure handlers.
+
+The model determines:
+- Whether to retry the operation
+- Whether to record circuit breaker failure
+- The appropriate error type to raise after retries exhausted
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.enums.enum_retry_error_category import EnumRetryErrorCategory
+
+
+class ModelRetryErrorClassification(BaseModel):
+    """Result of error classification for retry handling.
+
+    This model encapsulates the decision-making result when classifying
+    exceptions during retry loops in infrastructure handlers.
+
+    Attributes:
+        category: The error category for retry decision making.
+        should_retry: Whether the error is eligible for retry.
+        record_circuit_failure: Whether to record circuit breaker failure.
+        error_message: Sanitized error message for logging and retry state.
+
+    Example:
+        >>> from omnibase_infra.enums import EnumRetryErrorCategory
+        >>> classification = ModelRetryErrorClassification(
+        ...     category=EnumRetryErrorCategory.TIMEOUT,
+        ...     should_retry=True,
+        ...     record_circuit_failure=True,
+        ...     error_message="Operation timed out after 30s",
+        ... )
+        >>> classification.should_retry
+        True
+
+        The model is immutable (frozen=True) - attempting to modify raises an error:
+
+        >>> classification.should_retry = False  # doctest: +SKIP
+        Traceback (most recent call last):
+            ...
+        pydantic_core._pydantic_core.ValidationError: ...
+
+    Note:
+        The error_message field should contain SANITIZED error descriptions only.
+        Never include credentials, tokens, or other sensitive data in this field.
+        See CLAUDE.md "Error Sanitization Guidelines" for the security policy.
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    category: EnumRetryErrorCategory = Field(
+        description="The error category for retry decision making",
+    )
+    should_retry: bool = Field(
+        description="Whether the error is eligible for retry",
+    )
+    record_circuit_failure: bool = Field(
+        description="Whether to record circuit breaker failure",
+    )
+    error_message: str = Field(
+        description="Sanitized error message for logging and retry state",
+    )
+
+
+__all__: list[str] = ["ModelRetryErrorClassification"]

omnibase_infra/models/projection/__init__.py

@@ -0,0 +1,43 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""ONEX Projection Models Module.
+
+Provides Pydantic models for projection storage, ordering, and snapshot
+topic configuration. Used by projectors to persist materialized state and
+by orchestrators to query current entity state.
+
+Exports:
+    ModelCapabilityFields: Container for capability fields in projection persistence
+    ModelRegistrationProjection: Registration projection for orchestrator state queries
+    ModelRegistrationSnapshot: Compacted snapshot for read optimization
+    ModelSequenceInfo: Sequence information for projection ordering and idempotency
+    ModelSnapshotTopicConfig: Kafka topic configuration for snapshot publishing
+
+Related Tickets:
+    - OMN-1134: Registry Projection Extensions for Capabilities
+    - OMN-947 (F2): Snapshot Publishing
+    - OMN-944 (F1): Implement Registration Projection Schema
+    - OMN-940 (F0): Define Projector Execution Model
+"""
+
+from omnibase_infra.models.projection.model_capability_fields import (
+    ModelCapabilityFields,
+)
+from omnibase_infra.models.projection.model_registration_projection import (
+    ModelRegistrationProjection,
+)
+from omnibase_infra.models.projection.model_registration_snapshot import (
+    ModelRegistrationSnapshot,
+)
+from omnibase_infra.models.projection.model_sequence_info import ModelSequenceInfo
+from omnibase_infra.models.projection.model_snapshot_topic_config import (
+    ModelSnapshotTopicConfig,
+)
+
+__all__ = [
+    "ModelCapabilityFields",
+    "ModelRegistrationProjection",
+    "ModelRegistrationSnapshot",
+    "ModelSequenceInfo",
+    "ModelSnapshotTopicConfig",
+]

omnibase_infra/models/projection/model_capability_fields.py

@@ -0,0 +1,112 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Capability Fields Model.
+
+Provides a structured container for capability-related fields used in
+projection persistence. Consolidates denormalized capability data that
+enables fast discovery queries via GIN-indexed columns.
+
+Related Tickets:
+    - OMN-1134: Registry Projection Extensions for Capabilities
+    - OMN-944 (F1): Implement Registration Projection Schema
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from omnibase_infra.models.projection.model_registration_projection import (
+    ContractTypeWithUnknown,
+)
+from omnibase_infra.utils import validate_contract_type_value
+
+
+class ModelCapabilityFields(BaseModel):
+    """Container for capability fields used in projection persistence.
+
+    Consolidates the denormalized capability fields that are stored in
+    registration projections for fast discovery queries. These fields
+    are indexed with GIN indexes for efficient containment queries.
+
+    Use Cases:
+        - Pass to persist_state_transition() for consolidated capability data
+        - Extract from ModelNodeIntrospectionEvent for persistence
+        - Build from ModelNodeCapabilities for denormalization
+
+    Design Notes:
+        - All fields are optional to support partial updates
+        - Lists default to None (not empty list) to distinguish "not set"
+          from "explicitly empty" in persistence logic
+        - contract_type is validated to be a valid node contract type
+
+    Attributes:
+        contract_type: Node contract type (effect, compute, reducer, orchestrator)
+        intent_types: List of intent types this node handles
+        protocols: List of protocols this node implements
+        capability_tags: Tags for capability-based discovery
+        contract_version: Semantic version of the node contract
+
+    Example:
+        >>> fields = ModelCapabilityFields(
+        ...     contract_type="effect",
+        ...     intent_types=["postgres.upsert", "postgres.query"],
+        ...     protocols=["ProtocolDatabaseAdapter"],
+        ...     capability_tags=["postgres.storage"],
+        ...     contract_version="1.0.0",
+        ... )
+        >>> await projector.persist_state_transition(
+        ...     entity_id=node_id,
+        ...     capability_fields=fields,
+        ...     ...
+        ... )
+    """
+
+    model_config = ConfigDict(
+        frozen=True,  # Immutable for safe passing
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    contract_type: ContractTypeWithUnknown | None = Field(
+        default=None,
+        description=(
+            "Contract type for the node. Valid values: 'effect', 'compute', "
+            "'reducer', 'orchestrator'. 'unknown' is allowed for backfill but "
+            "rejected at persistence unless explicitly permitted. None indicates "
+            "unspecified (never processed)."
+        ),
+    )
+
+    @field_validator("contract_type", mode="before")
+    @classmethod
+    def validate_contract_type(cls, v: str | None) -> str | None:
+        """Validate contract_type is a valid node contract type.
+
+        Delegates to shared utility for consistent validation across all models.
+
+        Note:
+            The 'unknown' value is accepted here to allow model construction for
+            backfill scenarios. However, `persist_state_transition()` will reject
+            'unknown' unless `allow_unknown_backfill=True` is explicitly passed.
+        """
+        return validate_contract_type_value(v)
+
+    intent_types: list[str] | None = Field(
+        default=None,
+        description="Intent types this node handles (None = not specified)",
+    )
+    protocols: list[str] | None = Field(
+        default=None,
+        description="Protocols this node implements (None = not specified)",
+    )
+    capability_tags: list[str] | None = Field(
+        default=None,
+        description="Capability tags for discovery (None = not specified)",
+    )
+    contract_version: str | None = Field(
+        default=None,
+        description="Contract version string",
+    )
+
+
+__all__: list[str] = ["ModelCapabilityFields"]