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

omnibase_infra/__init__.py

@@ -76,7 +76,7 @@ See Also
 - Runtime kernel: omnibase_infra.runtime.service_kernel
 """
 
-__version__ = "0.2.1"
+__version__ = "0.2.3"
 
 from . import (
     enums,

omnibase_infra/adapters/adapter_onex_tool_execution.py

@@ -0,0 +1,451 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""ONEX Tool Execution Adapter - Bridges MCP tool calls to ONEX orchestrator execution.
+
+This adapter handles the execution of MCP tool invocations by:
+1. Validating input arguments against the tool's input schema
+2. Building an ONEX envelope with the input payload
+3. Dispatching to the orchestrator endpoint via HTTP
+4. Transforming the response to MCP format
+
+Routing:
+    The adapter uses the tool definition's endpoint or service_id to locate
+    the target orchestrator. It supports both direct HTTP dispatch and
+    service discovery via Consul.
+
+Timeout Handling:
+    Each tool definition includes a timeout_seconds value. The adapter
+    enforces this timeout when dispatching to the orchestrator, raising
+    InfraTimeoutError if exceeded.
+"""
+
+from __future__ import annotations
+
+import asyncio
+import logging
+from typing import TYPE_CHECKING
+from uuid import UUID, uuid4
+
+import httpx
+
+from omnibase_core.container import ModelONEXContainer
+from omnibase_infra.enums import EnumInfraTransportType
+from omnibase_infra.errors import (
+    InfraConnectionError,
+    InfraTimeoutError,
+    InfraUnavailableError,
+    ModelInfraErrorContext,
+    ModelTimeoutErrorContext,
+)
+from omnibase_infra.mixins import MixinAsyncCircuitBreaker
+
+if TYPE_CHECKING:
+    from omnibase_infra.models.mcp.model_mcp_tool_definition import (
+        ModelMCPToolDefinition,
+    )
+
+logger = logging.getLogger(__name__)
+
+
+class AdapterONEXToolExecution(MixinAsyncCircuitBreaker):
+    """Bridges MCP tool calls to ONEX orchestrator execution.
+
+    This adapter handles the dispatch of MCP tool invocations to the
+    appropriate ONEX orchestrator node. It supports:
+    - Direct HTTP dispatch to orchestrator endpoint
+    - Input validation against JSON Schema
+    - Timeout enforcement
+    - Error transformation to MCP format
+    - Circuit breaker protection for external HTTP calls
+
+    Attributes:
+        _container: ONEX container for dependency injection.
+        _http_client: HTTP client for orchestrator dispatch.
+        _default_timeout: Default timeout if tool definition doesn't specify one.
+
+    Example:
+        >>> adapter = AdapterONEXToolExecution(container=container)
+        >>> result = await adapter.execute(
+        ...     tool=tool_definition,
+        ...     arguments={"input_data": "test"},
+        ...     correlation_id=uuid4(),
+        ... )
+        >>> print(result["success"])
+        True
+    """
+
+    def __init__(
+        self,
+        container: ModelONEXContainer,
+        http_client: httpx.AsyncClient | None = None,
+        default_timeout: float = 30.0,
+        circuit_breaker_threshold: int = 5,
+        circuit_breaker_reset_timeout: float = 60.0,
+    ) -> None:
+        """Initialize the execution adapter.
+
+        Args:
+            container: ONEX container for dependency injection.
+            http_client: Optional HTTP client. If not provided, one will be
+                created during execute() calls.
+            default_timeout: Default timeout in seconds for orchestrator calls.
+            circuit_breaker_threshold: Max failures before opening circuit (default: 5).
+            circuit_breaker_reset_timeout: Seconds before automatic reset (default: 60.0).
+        """
+        self._container = container
+        self._http_client = http_client
+        self._default_timeout = default_timeout
+        self._owns_client = http_client is None
+
+        # Initialize circuit breaker for HTTP dispatch resilience
+        self._init_circuit_breaker(
+            threshold=circuit_breaker_threshold,
+            reset_timeout=circuit_breaker_reset_timeout,
+            service_name="onex-tool-execution",
+            transport_type=EnumInfraTransportType.HTTP,
+        )
+
+        logger.debug(
+            "AdapterONEXToolExecution initialized",
+            extra={
+                "default_timeout": default_timeout,
+                "circuit_breaker_threshold": circuit_breaker_threshold,
+                "circuit_breaker_reset_timeout": circuit_breaker_reset_timeout,
+            },
+        )
+
+    async def execute(
+        self,
+        tool: ModelMCPToolDefinition,
+        arguments: dict[str, object],
+        correlation_id: UUID,
+    ) -> dict[str, object]:
+        """Execute an MCP tool call by dispatching to the ONEX orchestrator.
+
+        Args:
+            tool: Tool definition containing endpoint, timeout, and metadata.
+            arguments: Input arguments from the MCP tool call.
+            correlation_id: Correlation ID for tracing.
+
+        Returns:
+            Dictionary with execution result:
+                - success: True if execution succeeded
+                - result: Orchestrator response (if successful)
+                - error: Error message (if failed)
+
+        Raises:
+            InfraUnavailableError: If tool endpoint is not configured.
+            InfraTimeoutError: If execution times out.
+            InfraConnectionError: If connection to orchestrator fails.
+        """
+        logger.info(
+            "Executing MCP tool",
+            extra={
+                "tool_name": tool.name,
+                "correlation_id": str(correlation_id),
+            },
+        )
+
+        # Validate endpoint
+        endpoint = tool.endpoint
+        if not endpoint:
+            ctx = ModelInfraErrorContext.with_correlation(
+                correlation_id=correlation_id,
+                transport_type=EnumInfraTransportType.HTTP,
+                operation="execute_tool",
+                target_name=tool.name,
+            )
+            raise InfraUnavailableError(
+                f"Tool '{tool.name}' has no endpoint configured",
+                context=ctx,
+            )
+
+        # Build envelope payload
+        envelope = self._build_envelope(tool, arguments, correlation_id)
+
+        # Determine timeout
+        timeout = tool.timeout_seconds or self._default_timeout
+
+        # Check circuit breaker before dispatch
+        try:
+            async with self._circuit_breaker_lock:
+                await self._check_circuit_breaker(
+                    operation="execute_tool",
+                    correlation_id=correlation_id,
+                )
+        except InfraUnavailableError:
+            logger.warning(
+                "MCP tool execution blocked - circuit breaker open",
+                extra={
+                    "tool_name": tool.name,
+                    "correlation_id": str(correlation_id),
+                },
+            )
+            return {
+                "success": False,
+                "error": "Service temporarily unavailable - circuit breaker open",
+            }
+
+        # Dispatch to orchestrator
+        try:
+            result = await self._http_dispatch(
+                endpoint=endpoint,
+                envelope=envelope,
+                timeout=timeout,
+                correlation_id=correlation_id,
+            )
+
+            # Record success to reset circuit breaker
+            async with self._circuit_breaker_lock:
+                await self._reset_circuit_breaker()
+
+            logger.info(
+                "MCP tool execution succeeded",
+                extra={
+                    "tool_name": tool.name,
+                    "correlation_id": str(correlation_id),
+                },
+            )
+
+            return {
+                "success": True,
+                "result": result,
+            }
+
+        except InfraTimeoutError:
+            # Record failure to potentially open circuit breaker
+            async with self._circuit_breaker_lock:
+                await self._record_circuit_failure(
+                    operation="execute_tool",
+                    correlation_id=correlation_id,
+                )
+            logger.warning(
+                "MCP tool execution timed out",
+                extra={
+                    "tool_name": tool.name,
+                    "timeout": timeout,
+                    "correlation_id": str(correlation_id),
+                },
+            )
+            return {
+                "success": False,
+                "error": f"Tool execution timed out after {timeout} seconds",
+            }
+
+        except InfraConnectionError as e:
+            # Record failure to potentially open circuit breaker
+            async with self._circuit_breaker_lock:
+                await self._record_circuit_failure(
+                    operation="execute_tool",
+                    correlation_id=correlation_id,
+                )
+            logger.warning(
+                "MCP tool execution failed - connection error",
+                extra={
+                    "tool_name": tool.name,
+                    "error": str(e),
+                    "correlation_id": str(correlation_id),
+                },
+            )
+            return {
+                "success": False,
+                "error": f"Connection error: {e}",
+            }
+
+        except Exception as e:
+            # Record failure to potentially open circuit breaker
+            async with self._circuit_breaker_lock:
+                await self._record_circuit_failure(
+                    operation="execute_tool",
+                    correlation_id=correlation_id,
+                )
+            logger.exception(
+                "MCP tool execution failed - unexpected error",
+                extra={
+                    "tool_name": tool.name,
+                    "error": str(e),
+                    "correlation_id": str(correlation_id),
+                },
+            )
+            return {
+                "success": False,
+                "error": f"Unexpected error: {e}",
+            }
+
+    def _build_envelope(
+        self,
+        tool: ModelMCPToolDefinition,
+        arguments: dict[str, object],
+        correlation_id: UUID,
+    ) -> dict[str, object]:
+        """Build an ONEX envelope for the orchestrator.
+
+        Args:
+            tool: Tool definition.
+            arguments: Input arguments from MCP.
+            correlation_id: Correlation ID.
+
+        Returns:
+            Envelope dict for the orchestrator.
+        """
+        return {
+            "envelope_id": str(uuid4()),
+            "correlation_id": str(correlation_id),
+            "source": "mcp-adapter",
+            "payload": arguments,
+            "metadata": {
+                "tool_name": tool.name,
+                "tool_version": tool.version,
+            },
+        }
+
+    async def _http_dispatch(
+        self,
+        endpoint: str,
+        envelope: dict[str, object],
+        timeout: float,
+        correlation_id: UUID,
+    ) -> dict[str, object]:
+        """Dispatch envelope to orchestrator endpoint via HTTP.
+
+        Args:
+            endpoint: Target endpoint URL.
+            envelope: Request envelope.
+            timeout: Request timeout in seconds.
+            correlation_id: Correlation ID.
+
+        Returns:
+            Response from orchestrator.
+
+        Raises:
+            InfraTimeoutError: If request times out.
+            InfraConnectionError: If connection fails.
+        """
+        # Use provided client or create one
+        if self._http_client is not None:
+            return await self._dispatch_with_client(
+                self._http_client,
+                endpoint,
+                envelope,
+                timeout,
+                correlation_id,
+            )
+        else:
+            # Create temporary client
+            async with httpx.AsyncClient() as client:
+                return await self._dispatch_with_client(
+                    client,
+                    endpoint,
+                    envelope,
+                    timeout,
+                    correlation_id,
+                )
+
+    async def _dispatch_with_client(
+        self,
+        client: httpx.AsyncClient,
+        endpoint: str,
+        envelope: dict[str, object],
+        timeout: float,
+        correlation_id: UUID,
+    ) -> dict[str, object]:
+        """Dispatch using the provided HTTP client.
+
+        Args:
+            client: HTTP client.
+            endpoint: Target endpoint URL.
+            envelope: Request envelope.
+            timeout: Request timeout in seconds.
+            correlation_id: Correlation ID.
+
+        Returns:
+            Response from orchestrator.
+
+        Raises:
+            InfraTimeoutError: If request times out.
+            InfraConnectionError: If connection fails.
+        """
+        try:
+            response = await asyncio.wait_for(
+                client.post(
+                    endpoint,
+                    json=envelope,
+                    headers={
+                        "X-Correlation-ID": str(correlation_id),
+                        "Content-Type": "application/json",
+                    },
+                    timeout=timeout,
+                ),
+                timeout=timeout,
+            )
+
+            response.raise_for_status()
+            result: dict[str, object] = response.json()
+            return result
+
+        except TimeoutError as e:
+            timeout_ctx = ModelTimeoutErrorContext(
+                transport_type=EnumInfraTransportType.HTTP,
+                operation="http_dispatch",
+                target_name=endpoint,
+                correlation_id=correlation_id,
+                timeout_seconds=timeout,
+            )
+            raise InfraTimeoutError(
+                f"Timeout dispatching to {endpoint} after {timeout}s",
+                context=timeout_ctx,
+            ) from e
+
+        except httpx.ConnectError as e:
+            ctx = ModelInfraErrorContext.with_correlation(
+                correlation_id=correlation_id,
+                transport_type=EnumInfraTransportType.HTTP,
+                operation="http_dispatch",
+                target_name=endpoint,
+            )
+            raise InfraConnectionError(
+                f"Connection failed to {endpoint}: {e}",
+                context=ctx,
+            ) from e
+
+        except httpx.HTTPStatusError as e:
+            ctx = ModelInfraErrorContext.with_correlation(
+                correlation_id=correlation_id,
+                transport_type=EnumInfraTransportType.HTTP,
+                operation="http_dispatch",
+                target_name=endpoint,
+            )
+            raise InfraConnectionError(
+                f"HTTP error from {endpoint}: {e.response.status_code}",
+                context=ctx,
+            ) from e
+
+        except Exception as e:
+            ctx = ModelInfraErrorContext.with_correlation(
+                correlation_id=correlation_id,
+                transport_type=EnumInfraTransportType.HTTP,
+                operation="http_dispatch",
+                target_name=endpoint,
+            )
+            raise InfraConnectionError(
+                f"Request to {endpoint} failed: {e}",
+                context=ctx,
+            ) from e
+
+    async def close(self) -> None:
+        """Close the HTTP client if owned by this adapter."""
+        if self._owns_client and self._http_client is not None:
+            await self._http_client.aclose()
+            self._http_client = None
+
+    def describe(self) -> dict[str, object]:
+        """Return adapter metadata for observability."""
+        return {
+            "adapter_name": "AdapterONEXToolExecution",
+            "default_timeout": self._default_timeout,
+            "owns_client": self._owns_client,
+            "circuit_breaker": self._get_circuit_breaker_state(),
+        }
+
+
+__all__ = ["AdapterONEXToolExecution"]

omnibase_infra/capabilities/__init__.py

@@ -0,0 +1,15 @@
+"""Capability extraction and inference for ONEX contracts."""
+
+from omnibase_infra.capabilities.capability_inference_rules import (
+    CapabilityInferenceRules,
+)
+from omnibase_infra.capabilities.contract_capability_extractor import (
+    ContractCapabilityExtractor,
+)
+from omnibase_infra.capabilities.intent_type_extractor import IntentTypeExtractor
+
+__all__ = [
+    "CapabilityInferenceRules",
+    "ContractCapabilityExtractor",
+    "IntentTypeExtractor",
+]

omnibase_infra/capabilities/capability_inference_rules.py

@@ -0,0 +1,211 @@
+"""Capability inference rules for deriving tags from contract structure.
+
+This module provides deterministic pattern matching to infer capability tags
+from contract fields like intent_types and protocols. Rules are injectable
+via constructor for extensibility while providing sensible defaults.
+"""
+
+from __future__ import annotations
+
+
+class CapabilityInferenceRules:
+    """Code-driven capability inference rules with injectable patterns.
+
+    Deterministic pattern matching for inferring capability_tags from
+    contract structure. All rule mappings are injectable via constructor
+    while providing sensible defaults.
+
+    Args:
+        intent_patterns: Custom/additional intent patterns (merged with defaults).
+        protocol_tags: Custom/additional protocol tags (merged with defaults).
+        node_type_tags: Custom/additional node type tags (merged with defaults).
+
+    Example:
+        # Use defaults
+        rules = CapabilityInferenceRules()
+
+        # Override specific pattern
+        rules = CapabilityInferenceRules(
+            intent_patterns={"redis.": "redis.caching"}
+        )
+
+        # Override existing pattern
+        rules = CapabilityInferenceRules(
+            intent_patterns={"postgres.": "custom.database"}
+        )
+    """
+
+    # Default intent pattern -> capability tag mappings
+    DEFAULT_INTENT_PATTERNS: dict[str, str] = {
+        "postgres.": "postgres.storage",
+        "consul.": "consul.registration",
+        "kafka.": "kafka.messaging",
+        "vault.": "vault.secrets",
+        "valkey.": "valkey.caching",
+        "http.": "http.transport",
+    }
+
+    # Default protocol -> capability tag mappings
+    DEFAULT_PROTOCOL_TAGS: dict[str, str] = {
+        "ProtocolReducer": "state.reducer",
+        "ProtocolDatabaseAdapter": "database.adapter",
+        "ProtocolEventBus": "event.bus",
+        "ProtocolCacheAdapter": "cache.adapter",
+        "ProtocolServiceDiscovery": "service.discovery",
+    }
+
+    # Default node type -> base capability tag
+    DEFAULT_NODE_TYPE_TAGS: dict[str, str] = {
+        "effect": "node.effect",
+        "compute": "node.compute",
+        "reducer": "node.reducer",
+        "orchestrator": "node.orchestrator",
+    }
+
+    def __init__(
+        self,
+        intent_patterns: dict[str, str] | None = None,
+        protocol_tags: dict[str, str] | None = None,
+        node_type_tags: dict[str, str] | None = None,
+    ) -> None:
+        """Initialize with optional custom rules.
+
+        Custom rules are merged with defaults. If a custom rule has the same
+        key as a default rule, the custom rule takes precedence (override).
+
+        Args:
+            intent_patterns: Custom/additional intent patterns (merged with defaults).
+            protocol_tags: Custom/additional protocol tags (merged with defaults).
+            node_type_tags: Custom/additional node type tags (merged with defaults).
+        """
+        self._intent_patterns = {
+            **self.DEFAULT_INTENT_PATTERNS,
+            **(intent_patterns or {}),
+        }
+        self._protocol_tags = {
+            **self.DEFAULT_PROTOCOL_TAGS,
+            **(protocol_tags or {}),
+        }
+        self._node_type_tags = {
+            **self.DEFAULT_NODE_TYPE_TAGS,
+            **(node_type_tags or {}),
+        }
+
+    def infer_from_intent_types(self, intent_types: list[str]) -> list[str]:
+        """Infer capability tags from intent type patterns.
+
+        Pattern matching uses first-match-wins semantics: each intent is matched
+        against patterns in iteration order, and only the FIRST matching pattern
+        is used (early exit via break). This is intentional because intents should
+        belong to a single capability category.
+
+        Example:
+            - "postgres.upsert" matches "postgres." -> "postgres.storage"
+            - "postgres.kafka.hybrid" matches "postgres." only (NOT both postgres and kafka)
+
+        Args:
+            intent_types: List of intent type strings (e.g., ["postgres.upsert", "consul.register"])
+
+        Returns:
+            Sorted list of inferred capability tags (deduplicated)
+        """
+        tags: set[str] = set()
+        for intent in intent_types:
+            if intent is None:  # Skip None values
+                continue
+            for pattern, tag in self._intent_patterns.items():
+                if intent.startswith(pattern):
+                    tags.add(tag)
+                    break
+        return sorted(tags)
+
+    def infer_from_protocols(self, protocols: list[str]) -> list[str]:
+        """Infer capability tags from protocol names.
+
+        Matching behavior:
+            - Exact match: "ProtocolReducer" matches DEFAULT_PROTOCOL_TAGS["ProtocolReducer"]
+            - Suffix match: "MyCustomProtocolReducer" also matches because it ends with "ProtocolReducer"
+            - No match: "ProtocolReducerExtended" does NOT match (doesn't end with known protocol)
+
+        This allows custom-prefixed protocol implementations to inherit base capability tags.
+
+        Warning:
+            Suffix matching can cause unexpected over-matching if your protocol name
+            accidentally ends with a known protocol name. The matching is strict:
+            the protocol name must END with the exact known protocol string.
+
+        Examples:
+            Protocols that MATCH (suffix ends with known protocol)::
+
+                "ProtocolReducer" -> matches "ProtocolReducer" (exact match)
+                "MyCustomProtocolReducer" -> matches "ProtocolReducer" (suffix match)
+                "InfraProtocolDatabaseAdapter" -> matches "ProtocolDatabaseAdapter"
+                "V2ProtocolEventBus" -> matches "ProtocolEventBus"
+
+            Protocols that DO NOT MATCH (suffix has additional characters)::
+
+                "ProtocolReducerV2" -> NO match (ends with "V2", not "ProtocolReducer")
+                "ProtocolReducerExtended" -> NO match (ends with "Extended")
+                "ProtocolReducerExtendedVersion" -> NO match (ends with "Version")
+                "MyReducer" -> NO match (must end with full "ProtocolReducer")
+                "ProtocolReducerImpl" -> NO match (ends with "Impl")
+
+        Args:
+            protocols: List of protocol class names
+
+        Returns:
+            Sorted list of inferred capability tags (deduplicated)
+        """
+        tags: set[str] = set()
+        for protocol in protocols:
+            if protocol is None:  # Skip None values
+                continue
+            # Check exact match
+            if protocol in self._protocol_tags:
+                tags.add(self._protocol_tags[protocol])
+            # Also check if protocol name ends with known suffix
+            for known_protocol, tag in self._protocol_tags.items():
+                if protocol.endswith(known_protocol):
+                    tags.add(tag)
+        return sorted(tags)
+
+    def infer_from_node_type(self, node_type: str) -> list[str]:
+        """Infer base capability tag from node type.
+
+        Args:
+            node_type: Node type string (effect, compute, reducer, orchestrator)
+
+        Returns:
+            List with single node type capability tag, or empty if unknown
+        """
+        normalized = node_type.lower().replace("_generic", "")
+        if normalized in self._node_type_tags:
+            return [self._node_type_tags[normalized]]
+        return []
+
+    def infer_all(
+        self,
+        intent_types: list[str] | None = None,
+        protocols: list[str] | None = None,
+        node_type: str | None = None,
+    ) -> list[str]:
+        """Infer all capability tags from available contract data.
+
+        Args:
+            intent_types: Optional list of intent types
+            protocols: Optional list of protocol names
+            node_type: Optional node type string
+
+        Returns:
+            Sorted, deduplicated list of all inferred capability tags
+        """
+        tags: set[str] = set()
+
+        if intent_types:
+            tags.update(self.infer_from_intent_types(intent_types))
+        if protocols:
+            tags.update(self.infer_from_protocols(protocols))
+        if node_type:
+            tags.update(self.infer_from_node_type(node_type))
+
+        return sorted(tags)