omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/handlers/models/mcp/enum_mcp_operation_type.py

@@ -0,0 +1,24 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""MCP operation type enumeration."""
+
+from enum import Enum
+
+
+class EnumMcpOperationType(str, Enum):
+    """Operation types for MCP handler.
+
+    The MCP handler supports three primary operations:
+        - LIST_TOOLS: Discover available tools from registered ONEX nodes
+        - CALL_TOOL: Invoke a specific tool with parameters
+        - DESCRIBE: Return handler metadata and capabilities
+
+    These map to the MCP protocol's tools/list and tools/call methods.
+    """
+
+    LIST_TOOLS = "mcp.list_tools"
+    CALL_TOOL = "mcp.call_tool"
+    DESCRIBE = "mcp.describe"
+
+
+__all__ = ["EnumMcpOperationType"]

omnibase_infra/handlers/models/mcp/model_mcp_handler_config.py

@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+# ruff: noqa: S104
+# S104 disabled: Binding to 0.0.0.0 is intentional for container networking
+"""MCP handler configuration model."""
+
+from pydantic import BaseModel, Field
+
+
+class ModelMcpHandlerConfig(BaseModel):
+    """Configuration for MCP handler initialization.
+
+    Attributes:
+        host: Host to bind the MCP server to.
+        port: Port for the MCP streamable HTTP endpoint.
+        path: URL path for the MCP endpoint (default: "/mcp").
+        stateless: Enable stateless mode for horizontal scaling.
+        json_response: Return JSON responses instead of SSE streaming.
+        timeout_seconds: Default timeout for tool execution.
+        max_tools: Maximum number of tools to expose.
+    """
+
+    host: str = Field(default="0.0.0.0", description="Host to bind MCP server to")
+    port: int = Field(default=8090, description="Port for MCP streamable HTTP endpoint")
+    path: str = Field(default="/mcp", description="URL path for MCP endpoint")
+    stateless: bool = Field(
+        default=True, description="Enable stateless mode for horizontal scaling"
+    )
+    json_response: bool = Field(
+        default=True, description="Return JSON responses instead of SSE streaming"
+    )
+    timeout_seconds: float = Field(
+        default=30.0, description="Default timeout for tool execution"
+    )
+    max_tools: int = Field(default=100, description="Maximum number of tools to expose")
+
+    model_config = {"frozen": True}
+
+
+__all__ = ["ModelMcpHandlerConfig"]

omnibase_infra/handlers/models/mcp/model_mcp_tool_call.py

@@ -0,0 +1,32 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""MCP tool call request model."""
+
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+
+class ModelMcpToolCall(BaseModel):
+    """Request model for MCP tool invocation.
+
+    Represents an incoming tool call from an AI agent via MCP protocol.
+
+    Attributes:
+        tool_name: Name of the tool to invoke.
+        arguments: Tool parameters as key-value pairs.
+        correlation_id: Optional correlation ID for request tracing.
+    """
+
+    tool_name: str = Field(..., description="Name of the tool to invoke")
+    arguments: dict[str, object] = Field(
+        default_factory=dict, description="Tool parameters as key-value pairs"
+    )
+    correlation_id: UUID | None = Field(
+        default=None, description="Optional correlation ID for request tracing"
+    )
+
+    model_config = {"frozen": True}
+
+
+__all__ = ["ModelMcpToolCall"]

omnibase_infra/handlers/models/mcp/model_mcp_tool_result.py

@@ -0,0 +1,45 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""MCP tool result model."""
+
+from uuid import UUID
+
+from pydantic import BaseModel, Field
+
+
+class ModelMcpToolResult(BaseModel):
+    """Result model for MCP tool invocation.
+
+    Represents the response from a tool invocation to be returned via MCP.
+
+    Attributes:
+        success: Whether the tool execution succeeded.
+        content: The result content (string or structured data).
+        is_error: Whether this result represents an error.
+        error_message: Error details if is_error is True.
+        correlation_id: Correlation ID from the original request.
+        execution_time_ms: Execution duration in milliseconds.
+    """
+
+    success: bool = Field(..., description="Whether the tool execution succeeded")
+    content: str | dict[str, object] | list[object] = Field(
+        ..., description="The result content (string or structured data)"
+    )
+    is_error: bool = Field(
+        default=False, description="Whether this result represents an error"
+    )
+    error_message: str | None = Field(
+        default=None, description="Error details if is_error is True"
+    )
+    correlation_id: UUID | None = Field(
+        default=None, description="Correlation ID from the original request"
+    )
+    execution_time_ms: float | None = Field(
+        default=None,
+        description="Execution duration in milliseconds (sub-ms precision)",
+    )
+
+    model_config = {"frozen": True}
+
+
+__all__ = ["ModelMcpToolResult"]

omnibase_infra/handlers/models/model_consul_handler_response.py

@@ -0,0 +1,96 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Consul Handler Response Model.
+
+This module provides the Pydantic model for Consul handler response envelopes
+used by the HandlerConsul.
+
+This model provides type consistency with ModelDbQueryResponse, ensuring
+both handlers return strongly-typed Pydantic models with consistent
+interfaces (status, payload, correlation_id).
+"""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.enums import EnumResponseStatus
+from omnibase_infra.handlers.models.consul import (
+    ModelConsulHandlerPayload,
+)
+
+
+class ModelConsulHandlerResponse(BaseModel):
+    """Full Consul handler response envelope.
+
+    Provides a standardized response format for Consul operations
+    with status, payload, and correlation tracking.
+
+    This model mirrors ModelDbQueryResponse to ensure consistent
+    interfaces across infrastructure handlers.
+
+    Attributes:
+        status: Operation status (EnumResponseStatus.SUCCESS or EnumResponseStatus.ERROR)
+        payload: Consul operation result payload containing operation-specific data
+        correlation_id: UUID for request/response correlation
+
+    Example:
+        >>> from uuid import uuid4
+        >>> from omnibase_infra.enums import EnumResponseStatus
+        >>> from omnibase_infra.handlers.models.consul import ModelConsulRegisterPayload
+        >>> response = ModelConsulHandlerResponse(
+        ...     status=EnumResponseStatus.SUCCESS,
+        ...     payload=ModelConsulHandlerPayload(
+        ...         data=ModelConsulRegisterPayload(
+        ...             registered=True,
+        ...             name="my-service",
+        ...             consul_service_id="my-service-1",
+        ...         ),
+        ...     ),
+        ...     correlation_id=uuid4(),
+        ... )
+        >>> print(response.status)
+        <EnumResponseStatus.SUCCESS: 'success'>
+        >>> print(response.payload.data.operation_type)
+        'register'
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,  # Support pytest-xdist compatibility
+    )
+
+    status: EnumResponseStatus = Field(
+        description="Operation status indicator",
+    )
+    payload: ModelConsulHandlerPayload = Field(
+        description="Consul operation result payload",
+    )
+    correlation_id: UUID = Field(
+        description="UUID for request/response correlation",
+    )
+
+    @property
+    def is_success(self) -> bool:
+        """Check if the response indicates a successful operation.
+
+        Returns:
+            True if status is SUCCESS, False otherwise.
+        """
+        return self.status == EnumResponseStatus.SUCCESS
+
+    @property
+    def is_error(self) -> bool:
+        """Check if the response indicates an error.
+
+        Returns:
+            True if status is ERROR, False otherwise.
+        """
+        return self.status == EnumResponseStatus.ERROR
+
+
+__all__: list[str] = ["ModelConsulHandlerResponse"]

omnibase_infra/handlers/models/model_db_describe_response.py

@@ -0,0 +1,83 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Database Describe Response Model.
+
+This module provides the Pydantic model for database handler metadata
+and capabilities responses.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_core.types import JsonType
+
+
+class ModelDbDescribeResponse(BaseModel):
+    """Database handler metadata and capabilities response.
+
+    Provides handler metadata including supported operations,
+    configuration, and version information.
+
+    Attributes:
+        handler_type: Architectural role of handler (e.g., "infra_handler")
+        handler_category: Behavioral classification (e.g., "effect")
+        supported_operations: List of supported operation types
+        pool_size: Connection pool size
+        timeout_seconds: Query timeout in seconds
+        initialized: Whether the handler has been initialized
+        version: Handler version string
+        circuit_breaker: Circuit breaker state information (optional)
+
+    Example:
+        >>> describe = ModelDbDescribeResponse(
+        ...     handler_type="infra_handler",
+        ...     handler_category="effect",
+        ...     supported_operations=["db.query", "db.execute"],
+        ...     pool_size=5,
+        ...     timeout_seconds=30.0,
+        ...     initialized=True,
+        ...     version="0.1.0-mvp",
+        ...     circuit_breaker={"state": "closed", "failures": 0},
+        ... )
+        >>> print(describe.supported_operations)
+        ['db.query', 'db.execute']
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,  # Support pytest-xdist compatibility
+    )
+
+    handler_type: str = Field(
+        description="Architectural role of handler (e.g., 'infra_handler')",
+    )
+    handler_category: str = Field(
+        description="Behavioral classification (e.g., 'effect')",
+    )
+    supported_operations: list[str] = Field(
+        description="List of supported operation types",
+    )
+    pool_size: int = Field(
+        ge=1,
+        description="Connection pool size",
+    )
+    timeout_seconds: float = Field(
+        gt=0,
+        description="Query timeout in seconds",
+    )
+    initialized: bool = Field(
+        description="Whether the handler has been initialized",
+    )
+    version: str = Field(
+        description="Handler version string",
+    )
+    circuit_breaker: dict[str, JsonType] | None = Field(
+        default=None,
+        description="Circuit breaker state information (state, failures, threshold, etc.)",
+    )
+
+
+__all__: list[str] = ["ModelDbDescribeResponse"]

omnibase_infra/handlers/models/model_db_query_payload.py

@@ -0,0 +1,95 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Database Query Payload Model.
+
+This module provides the Pydantic model for database query result payloads.
+
+Note on row typing:
+    Database rows are typed as ``list[dict[str, object]]`` because:
+
+    1. Column names are dynamic (determined by SQL query)
+    2. Column types are heterogeneous (str, int, float, datetime, etc.)
+    3. The handler returns generic rows that callers must interpret
+
+    For strongly-typed domain models, callers should map these generic
+    rows to their specific Pydantic models after retrieval.
+
+JsonType Recursion Fix (OMN-1274):
+    This module uses ``dict[str, object]`` instead of the recursive ``JsonType``
+    type alias from omnibase_core. Here is why:
+
+    **The Original Problem:**
+    ``JsonType`` was defined as a recursive type alias::
+
+        JsonType = dict[str, "JsonType"] | list["JsonType"] | str | int | float | bool | None
+
+    Pydantic 2.x processes model fields at **class definition time** (not runtime).
+    When building JSON schemas for validation, it recursively expands type aliases::
+
+        JsonType -> dict[str, JsonType] | list[JsonType] | ...
+                 -> dict[str, dict[str, JsonType] | list[JsonType] | ...] | ...
+                 -> ... (infinite expansion)
+
+    This causes ``RecursionError: maximum recursion depth exceeded`` during
+    Pydantic's schema generation in ``_generate_schema.py``.
+
+    **Why dict[str, object] is Correct Here:**
+    For database rows, we specifically need dictionaries with string keys and
+    heterogeneous values. We do NOT need to support arrays or primitives at the
+    root level (unlike HTTP response bodies which can be any JSON value).
+
+    Using ``dict[str, object]`` provides:
+    - Correct semantics: DB rows are always dictionaries
+    - Type safety: Pydantic validates the structure
+    - No recursion: ``object`` is not a recursive type alias
+
+    **Caveats:**
+    - ``object`` provides no static type checking on values (use runtime validation)
+    - Callers should map to strongly-typed models for domain logic
+    - For fields needing full JSON support (any JSON value), use ``JsonType``
+      from ``omnibase_core.types`` (now fixed via TypeAlias pattern)
+
+See Also:
+    - ADR: ``docs/decisions/adr-any-type-pydantic-workaround.md`` (historical)
+    - Pydantic issue: https://github.com/pydantic/pydantic/issues/3278
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelDbQueryPayload(BaseModel):
+    """Payload containing database query results.
+
+    Attributes:
+        rows: List of result rows as column->value dictionaries.
+            Column types are preserved from database (str, int, float, etc.).
+        row_count: Number of rows returned or affected.
+
+    Example:
+        >>> payload = ModelDbQueryPayload(
+        ...     rows=[{"id": 1, "name": "test"}, {"id": 2, "name": "example"}],
+        ...     row_count=2,
+        ... )
+        >>> print(len(payload.rows))
+        2
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,  # Support pytest-xdist compatibility
+    )
+
+    rows: list[dict[str, object]] = Field(
+        description="Result rows as column->value dictionaries",
+    )
+    row_count: int = Field(
+        ge=0,
+        description="Number of rows returned or affected",
+    )
+
+
+__all__: list[str] = ["ModelDbQueryPayload"]

omnibase_infra/handlers/models/model_db_query_response.py

@@ -0,0 +1,60 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Database Query Response Model.
+
+This module provides the Pydantic model for database query response envelopes
+used by the HandlerDb.
+"""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.enums import EnumResponseStatus
+from omnibase_infra.handlers.models.model_db_query_payload import ModelDbQueryPayload
+
+
+class ModelDbQueryResponse(BaseModel):
+    """Full database query response envelope.
+
+    Provides a standardized response format for database operations
+    with status, payload, and correlation tracking.
+
+    Attributes:
+        status: Operation status (EnumResponseStatus.SUCCESS or EnumResponseStatus.ERROR)
+        payload: Query result payload containing rows and count
+        correlation_id: UUID for request/response correlation
+
+    Example:
+        >>> from uuid import uuid4
+        >>> from omnibase_infra.enums import EnumResponseStatus
+        >>> response = ModelDbQueryResponse(
+        ...     status=EnumResponseStatus.SUCCESS,
+        ...     payload=ModelDbQueryPayload(rows=[], row_count=0),
+        ...     correlation_id=uuid4(),
+        ... )
+        >>> print(response.status)
+        <EnumResponseStatus.SUCCESS: 'success'>
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,  # Support pytest-xdist compatibility
+    )
+
+    status: EnumResponseStatus = Field(
+        description="Operation status indicator",
+    )
+    payload: ModelDbQueryPayload = Field(
+        description="Query result payload",
+    )
+    correlation_id: UUID = Field(
+        description="UUID for request/response correlation",
+    )
+
+
+__all__: list[str] = ["ModelDbQueryResponse"]

omnibase_infra/handlers/models/model_filesystem_config.py

@@ -0,0 +1,98 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Filesystem Handler Configuration Model.
+
+This module provides the Pydantic model for HandlerFileSystem initialization
+configuration, replacing the untyped dict[str, object] pattern.
+
+Security:
+    The allowed_paths field defines the whitelist of directories that the
+    filesystem handler can access. This is a critical security boundary.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Sequence
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+
+class ModelFileSystemConfig(BaseModel):
+    """Configuration for HandlerFileSystem initialization.
+
+    This model defines the configuration parameters required to initialize
+    the filesystem handler, including the security-critical path whitelist
+    and optional size limits.
+
+    Attributes:
+        allowed_paths: Immutable tuple of directory paths that the handler is
+            allowed to access. This is a required security boundary - operations
+            on paths outside these directories will be rejected. Uses tuple
+            instead of list to prevent runtime mutation of the whitelist.
+        max_read_size: Maximum file size in bytes for read operations.
+            If None, the default from environment or code will be used.
+        max_write_size: Maximum content size in bytes for write operations.
+            If None, the default from environment or code will be used.
+        correlation_id: Optional correlation ID for initialization tracing.
+
+    Example:
+        >>> config = ModelFileSystemConfig(
+        ...     allowed_paths=["/tmp/test", "/data/output"],
+        ...     max_read_size=10 * 1024 * 1024,  # 10 MB
+        ... )
+        >>> print(config.allowed_paths)
+        ('/tmp/test', '/data/output')
+        >>> # List input is automatically coerced to immutable tuple
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    allowed_paths: tuple[str, ...] = Field(
+        min_length=1,
+        description="Immutable tuple of allowed directory paths for filesystem operations. "
+        "Required for security - must not be empty. List inputs are coerced to tuple.",
+    )
+
+    @field_validator("allowed_paths", mode="before")
+    @classmethod
+    def coerce_to_tuple(cls, v: Sequence[str]) -> tuple[str, ...]:
+        """Coerce list inputs to immutable tuple for security.
+
+        This ensures the allowed_paths whitelist cannot be mutated after
+        model construction, even though Python's frozen=True only prevents
+        reassignment of the attribute, not mutation of mutable objects.
+
+        Args:
+            v: Input value, either a list or tuple of strings.
+
+        Returns:
+            Immutable tuple of path strings.
+        """
+        # Always return tuple to satisfy return type
+        return tuple(v)
+
+    max_read_size: int | None = Field(
+        default=None,
+        gt=0,
+        description="Maximum file size in bytes for read operations. "
+        "If None, uses default (100 MB from env or code).",
+    )
+    max_write_size: int | None = Field(
+        default=None,
+        gt=0,
+        description="Maximum content size in bytes for write operations. "
+        "If None, uses default (50 MB from env or code).",
+    )
+    correlation_id: UUID | str | None = Field(
+        default=None,
+        description="Optional correlation ID for initialization tracing.",
+    )
+
+
+__all__: list[str] = ["ModelFileSystemConfig"]

omnibase_infra/handlers/models/model_filesystem_delete_payload.py

@@ -0,0 +1,54 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Filesystem Delete File Payload Model.
+
+This module provides the Pydantic model for the filesystem.delete_file operation
+payload, replacing untyped dict[str, object] patterns.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelDeleteFilePayload(BaseModel):
+    """Payload for filesystem.delete_file operation.
+
+    Specifies the file to delete and options.
+
+    Attributes:
+        path: Absolute or relative path to the file to delete.
+            The path will be validated against the allowed_paths whitelist.
+            Note: This operation only deletes files, not directories.
+        missing_ok: If True, don't raise an error if the file doesn't exist.
+            If False (default), raise an error if the file is missing.
+
+    Example:
+        >>> payload = ModelDeleteFilePayload(path="/data/temp.txt")
+        >>> print(payload.missing_ok)
+        False
+
+        >>> safe_payload = ModelDeleteFilePayload(
+        ...     path="/data/maybe_exists.txt",
+        ...     missing_ok=True,
+        ... )
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    path: str = Field(
+        min_length=1,
+        description="Path to the file to delete. Validated against allowed_paths.",
+    )
+    missing_ok: bool = Field(
+        default=False,
+        description="If True, don't error if file doesn't exist.",
+    )
+
+
+__all__: list[str] = ["ModelDeleteFilePayload"]