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

omnibase_infra/models/handlers/model_bootstrap_handler_descriptor.py

@@ -0,0 +1,162 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Bootstrap Handler Descriptor Model with Required handler_class.
+
+This module provides ModelBootstrapHandlerDescriptor, a specialized handler
+descriptor for bootstrap handlers that REQUIRES the handler_class field to be set.
+
+Bootstrap handlers are hardcoded handlers that must always specify their
+implementation class for dynamic import. Unlike contract-discovered handlers
+where handler_class may be optional (inferred from convention), bootstrap
+handlers have no contract file to derive the class from.
+
+Part of OMN-1087: Implement HandlerBootstrapSource descriptor-based validation.
+
+See Also:
+    - ModelHandlerDescriptor: Base descriptor with optional handler_class
+    - HandlerBootstrapSource: Source that uses this specialized descriptor
+    - BootstrapEffectDefinition: TypedDict for bootstrap handler definitions
+
+.. versionadded:: 0.6.4
+    Created as part of OMN-1087 bootstrap handler validation.
+"""
+
+from __future__ import annotations
+
+from pydantic import ConfigDict, Field
+
+from omnibase_infra.models.handlers.model_handler_descriptor import (
+    ModelHandlerDescriptor,
+)
+
+
+class ModelBootstrapHandlerDescriptor(ModelHandlerDescriptor):
+    """Handler descriptor for bootstrap handlers with required handler_class.
+
+    This specialized descriptor extends ModelHandlerDescriptor to enforce that
+    handler_class is always set. Bootstrap handlers are hardcoded and must
+    specify their implementation class since there is no contract file to
+    derive the class from.
+
+    The key difference from ModelHandlerDescriptor:
+    - handler_class: Required (str) instead of optional (str | None)
+
+    All other fields maintain the same constraints as the parent class.
+
+    Attributes:
+        handler_id: Unique identifier for the handler (e.g., "bootstrap.consul").
+        name: Human-readable name for the handler.
+        version: Semantic version (ModelSemVer). Accepts string, dict, or ModelSemVer.
+        handler_kind: Handler kind (compute, effect, reducer, orchestrator).
+        input_model: Fully qualified input model class path.
+        output_model: Fully qualified output model class path.
+        description: Optional description of the handler.
+        handler_class: REQUIRED fully qualified Python class path for dynamic import.
+        contract_path: Path to the source contract file (typically None for bootstrap).
+
+    Example:
+        Create a bootstrap handler descriptor:
+
+        >>> descriptor = ModelBootstrapHandlerDescriptor(
+        ...     handler_id="bootstrap.consul",
+        ...     name="Consul Handler",
+        ...     version="1.0.0",
+        ...     handler_kind="effect",
+        ...     input_model="omnibase_infra.models.types.JsonDict",
+        ...     output_model="omnibase_core.models.dispatch.ModelHandlerOutput",
+        ...     handler_class="omnibase_infra.handlers.handler_consul.HandlerConsul",
+        ... )
+        >>> descriptor.handler_class
+        'omnibase_infra.handlers.handler_consul.HandlerConsul'
+
+        Missing handler_class raises ValidationError:
+
+        >>> from pydantic import ValidationError
+        >>> try:
+        ...     ModelBootstrapHandlerDescriptor(
+        ...         handler_id="bootstrap.consul",
+        ...         name="Consul Handler",
+        ...         version="1.0.0",
+        ...         handler_kind="effect",
+        ...         input_model="omnibase_infra.models.types.JsonDict",
+        ...         output_model="omnibase_core.models.dispatch.ModelHandlerOutput",
+        ...         # handler_class omitted - will fail
+        ...     )
+        ... except ValidationError as e:
+        ...     print("Validation failed as expected")
+        Validation failed as expected
+
+    Raises:
+        ValidationError: If handler_class is not provided or is None.
+
+    .. versionadded:: 0.6.4
+        Created as part of OMN-1087 bootstrap handler validation.
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+    )
+
+    # Override handler_class to be required (no default, not optional)
+    # The Field() definition must include the pattern constraint from parent
+    handler_class: str = Field(
+        ...,
+        min_length=3,
+        pattern=r"^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)+$",
+        description=(
+            "REQUIRED: Fully qualified Python class path for dynamic handler import. "
+            "Bootstrap handlers must always specify this field since they have no "
+            "contract file to derive the class from. "
+            "Example: 'omnibase_infra.handlers.handler_consul.HandlerConsul'"
+        ),
+    )
+
+    def to_base_descriptor(self) -> ModelHandlerDescriptor:
+        """Convert to base ModelHandlerDescriptor for API compatibility.
+
+        This method allows bootstrap descriptors to be used where the base
+        ModelHandlerDescriptor type is expected, while maintaining the
+        validation benefits of the bootstrap-specific model.
+
+        Implementation Notes:
+            Uses ``model_dump()`` without ``exclude_unset=True`` because:
+
+            1. **Field parity**: This child class has NO extra fields beyond the
+               parent. The only difference is ``handler_class`` type constraint
+               (required ``str`` vs optional ``str | None``).
+
+            2. **Type compatibility**: A ``str`` value from child is valid where
+               parent expects ``str | None``.
+
+            3. **Complete copy**: ``model_dump()`` ensures all fields are copied,
+               including those set to their default values.
+
+            Using ``exclude_unset=True`` would risk excluding fields that have
+            defaults but were explicitly set to those defaults during construction.
+
+            If future versions add child-specific fields not in parent, this
+            method MUST be updated to use ``exclude={'new_field'}`` or refactored.
+
+        Returns:
+            ModelHandlerDescriptor instance with all fields copied.
+
+        Example:
+            >>> bootstrap_desc = ModelBootstrapHandlerDescriptor(
+            ...     handler_id="bootstrap.consul",
+            ...     name="Consul Handler",
+            ...     version="1.0.0",
+            ...     handler_kind="effect",
+            ...     input_model="omnibase_infra.models.types.JsonDict",
+            ...     output_model="omnibase_core.models.dispatch.ModelHandlerOutput",
+            ...     handler_class="omnibase_infra.handlers.handler_consul.HandlerConsul",
+            ... )
+            >>> base_desc = bootstrap_desc.to_base_descriptor()
+            >>> isinstance(base_desc, ModelHandlerDescriptor)
+            True
+        """
+        return ModelHandlerDescriptor(**self.model_dump())
+
+
+__all__ = ["ModelBootstrapHandlerDescriptor"]

omnibase_infra/models/handlers/model_handler_descriptor.py

@@ -99,6 +99,7 @@ class ModelHandlerDescriptor(BaseModel):
         input_model: Fully qualified input model class path.
         output_model: Fully qualified output model class path.
         description: Optional description of the handler.
+        handler_class: Fully qualified Python class path for dynamic handler import.
         contract_path: Path to the source contract file.
 
     Example:
@@ -176,10 +177,24 @@ class ModelHandlerDescriptor(BaseModel):
         default=None,
         description="Optional description of the handler",
     )
+    handler_class: str | None = Field(
+        default=None,
+        min_length=3,
+        pattern=r"^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)+$",
+        description="Fully qualified Python class path for dynamic handler import (e.g., 'omnibase_infra.handlers.handler_consul.HandlerConsul')",
+    )
     contract_path: str | None = Field(
         default=None,
         description="Path to the source contract file",
     )
+    contract_config: dict[str, JsonType] | None = Field(
+        default=None,
+        description=(
+            "Parsed configuration from the handler contract file. "
+            "Contains extracted values like security settings, tags, and handler metadata. "
+            "Populated during handler discovery when contract_path is set."
+        ),
+    )
 
 
 __all__ = ["LiteralHandlerKind", "ModelHandlerDescriptor"]

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/registration/model_node_capabilities.py

@@ -12,9 +12,12 @@ Note:
     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):
@@ -94,6 +97,14 @@ class ModelNodeCapabilities(BaseModel):
         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.
 

omnibase_infra/nodes/architecture_validator/contract_architecture_validator.yaml

@@ -11,11 +11,6 @@
 name: "architecture_validator"
 contract_name: "architecture_validator"
 node_name: "architecture_validator"
-# Version (semantic versioning)
-version:
-  major: 1
-  minor: 0
-  patch: 0
 contract_version:
   major: 1
   minor: 0

omnibase_infra/nodes/architecture_validator/registry/registry_infra_architecture_validator.py

@@ -39,7 +39,7 @@ class RegistryInfraArchitectureValidator:
 
     This registry provides a static method to register the NodeArchitectureValidator
     with the ONEX dependency injection container. The validator is registered as
-    a factory, allowing lazy instantiation when first resolved.
+    an instance after being created with the container reference.
 
     Thread Safety:
         Registration is typically done at startup before the container is frozen.
@@ -53,17 +53,17 @@ class RegistryInfraArchitectureValidator:
         )
 
         container = ModelONEXContainer()
-        RegistryInfraArchitectureValidator.register(container)
+        await RegistryInfraArchitectureValidator.register(container)
         ```
     """
 
     @staticmethod
-    def register(container: ModelONEXContainer) -> None:
+    async def register(container: ModelONEXContainer) -> None:
         """Register architecture validator with container.
 
         Registers the NodeArchitectureValidator as a service in the ONEX
-        dependency injection container. The validator is registered with
-        a factory function that creates a new instance on demand.
+        dependency injection container. The validator is created immediately
+        and registered as a singleton instance.
 
         Args:
             container: The DI container to register with.
@@ -77,22 +77,29 @@ class RegistryInfraArchitectureValidator:
         Example:
             ```python
             container = ModelONEXContainer()
-            RegistryInfraArchitectureValidator.register(container)
+            await RegistryInfraArchitectureValidator.register(container)
 
             # Resolve when needed
-            validator = container.get_service(NodeArchitectureValidator)
+            validator = await container.service_registry.resolve_service(
+                NodeArchitectureValidator
+            )
             result = await validator.compute(request)
             ```
         """
+        from omnibase_core.enums import EnumInjectionScope
+
         # Check if service_registry is available
         if container.service_registry is None:
             # Container doesn't have full DI support - skip registration
             # This allows the code to work with minimal container configurations
             return
 
-        container.service_registry.register(
-            NodeArchitectureValidator,
-            lambda c: NodeArchitectureValidator(c),
+        # Create instance and register (factory registration not supported in v1.0)
+        validator_instance = NodeArchitectureValidator(container)
+        await container.service_registry.register_instance(
+            interface=NodeArchitectureValidator,
+            instance=validator_instance,
+            scope=EnumInjectionScope.GLOBAL,
         )
 
 

omnibase_infra/nodes/effects/contract.yaml

@@ -10,11 +10,6 @@
 name: "registry_effect"
 contract_name: "registry_effect"
 node_name: "registry_effect"
-# Version (semantic versioning)
-version:
-  major: 1
-  minor: 0
-  patch: 0
 contract_version:
   major: 1
   minor: 0

omnibase_infra/nodes/node_registration_orchestrator/contract.yaml

@@ -36,6 +36,13 @@ node_version: "1.0.0"
 name: "node_registration_orchestrator"
 node_type: "ORCHESTRATOR_GENERIC"
 description: "Registration workflow orchestrator that coordinates node lifecycle by calling reducer for intents and effect for execution."
+# MCP (Model Context Protocol) Configuration
+# Exposes this orchestrator as an AI-invocable tool via MCP server
+mcp:
+  expose: true
+  tool_name: "register_node"
+  description: "Register a new ONEX node with the cluster. Handles Consul service registration and PostgreSQL metadata storage. Returns registration status and assigned service ID."
+  timeout_seconds: 30
 input_model:
   name: "ModelOrchestratorInput"
   module: "omnibase_infra.nodes.node_registration_orchestrator.models"