omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/models/handlers/model_handler_descriptor.py

@@ -0,0 +1,200 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Handler Descriptor Model for Filesystem Discovery.
+
+This module provides ModelHandlerDescriptor, which represents a discovered handler
+from a contract file. Part of OMN-1097 HandlerContractSource filesystem discovery.
+
+The descriptor captures essential metadata about a handler discovered from a
+handler_contract.yaml file, suitable for registration and validation.
+
+See Also:
+    - HandlerContractSource: Source that discovers these descriptors
+    - ModelHandlerContract: Contract model from omnibase_core
+    - ModelContractDiscoveryResult: Result model with graceful error handling
+
+.. versionadded:: 0.6.2
+    Created as part of OMN-1097 filesystem handler discovery.
+
+.. versionchanged:: 0.6.3
+    Changed version field from str to ModelSemVer for better type safety
+    and consistency with rest of codebase.
+"""
+
+from __future__ import annotations
+
+from typing import Annotated, Literal
+
+from pydantic import BaseModel, BeforeValidator, ConfigDict, Field
+
+from omnibase_core.models.primitives.model_semver import ModelSemVer
+from omnibase_core.types import JsonType
+
+
+def _parse_version(v: ModelSemVer | str | dict[str, JsonType]) -> ModelSemVer:
+    """Parse version input to ModelSemVer.
+
+    Accepts ModelSemVer instance, string (e.g., "1.0.0"), or dict
+    (e.g., {"major": 1, "minor": 0, "patch": 0}).
+
+    This validator enables flexible input while maintaining ModelSemVer
+    as the canonical type, supporting:
+    - Direct ModelSemVer instances (programmatic use)
+    - String versions (from YAML contract files)
+    - Dict representations (from JSON/dict sources)
+
+    Dict Validation:
+        When a dict is provided, the validator explicitly checks for:
+        1. Required keys ("major", "minor", "patch") are present
+        2. Required key values are integers (not strings or other types)
+
+        This provides clearer error messages before delegating to model_validate(),
+        rather than relying on Pydantic's generic validation errors.
+
+    Raises:
+        ValueError: If dict input is missing required keys (major, minor, patch),
+            or if required key values are not integers.
+    """
+    if isinstance(v, ModelSemVer):
+        return v
+    if isinstance(v, str):
+        return ModelSemVer.parse(v)
+    if isinstance(v, dict):
+        required_keys = {"major", "minor", "patch"}
+        if not required_keys.issubset(v.keys()):
+            missing = required_keys - v.keys()
+            raise ValueError(f"Version dict missing required keys: {missing}")
+        # Validate value types before delegating to model_validate()
+        for key in required_keys:
+            value = v[key]
+            if not isinstance(value, int):
+                raise ValueError(
+                    f"Version '{key}' must be an integer, "
+                    f"got {type(value).__name__}: {value!r}"
+                )
+        return ModelSemVer.model_validate(v)
+    # NOTE: Return as-is for unhandled types and let Pydantic's own
+    # validation raise an appropriate error with type information.
+    return v  # type: ignore[return-value]  # NOTE: Pydantic validation handles unknown types
+
+
+# Annotated type for version field that accepts string, dict, or ModelSemVer
+_VersionField = Annotated[ModelSemVer, BeforeValidator(_parse_version)]
+
+# Type alias for valid ONEX handler kinds
+LiteralHandlerKind = Literal["compute", "effect", "reducer", "orchestrator"]
+
+
+class ModelHandlerDescriptor(BaseModel):
+    """Handler descriptor model representing a discovered handler.
+
+    This model captures the essential metadata about a handler discovered
+    from a contract file, suitable for registration and validation.
+
+    Attributes:
+        handler_id: Unique identifier for the handler.
+        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: Fully qualified Python class path for dynamic handler import.
+        contract_path: Path to the source contract file.
+
+    Example:
+        Create with string version (common when loading from YAML):
+
+        >>> descriptor = ModelHandlerDescriptor(
+        ...     handler_id="auth.handler",
+        ...     name="Auth Handler",
+        ...     version="1.0.0",
+        ...     handler_kind="compute",
+        ...     input_model="auth.models.AuthInput",
+        ...     output_model="auth.models.AuthOutput",
+        ... )
+        >>> descriptor.version.major
+        1
+
+        Create with ModelSemVer instance:
+
+        >>> from omnibase_core.models.primitives.model_semver import ModelSemVer
+        >>> descriptor = ModelHandlerDescriptor(
+        ...     handler_id="auth.handler",
+        ...     name="Auth Handler",
+        ...     version=ModelSemVer(major=2, minor=1, patch=0, prerelease=("beta", 1)),
+        ...     handler_kind="compute",
+        ...     input_model="auth.models.AuthInput",
+        ...     output_model="auth.models.AuthOutput",
+        ... )
+        >>> str(descriptor.version)
+        '2.1.0-beta.1'
+
+    .. versionadded:: 0.6.2
+        Created as part of OMN-1097 filesystem handler discovery.
+
+    .. versionchanged:: 0.6.3
+        Changed version field from str to ModelSemVer for better type safety.
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+    )
+
+    handler_id: str = Field(
+        ...,
+        min_length=1,
+        description="Unique identifier for the handler",
+    )
+    name: str = Field(
+        ...,
+        min_length=1,
+        description="Human-readable name for the handler",
+    )
+    version: _VersionField = Field(
+        ...,
+        description="Semantic version (accepts string, dict, or ModelSemVer instance)",
+    )
+    handler_kind: LiteralHandlerKind = Field(
+        ...,
+        description="Handler architectural kind (compute, effect, reducer, orchestrator)",
+    )
+    input_model: str = Field(
+        ...,
+        min_length=3,
+        pattern=r"^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)+$",
+        description="Fully qualified input model class path (e.g., 'myapp.models.User')",
+    )
+    output_model: str = Field(
+        ...,
+        min_length=3,
+        pattern=r"^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)+$",
+        description="Fully qualified output model class path (e.g., 'myapp.models.Result')",
+    )
+    description: str | None = Field(
+        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/handlers/model_handler_identifier.py

@@ -0,0 +1,215 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Handler Identifier Model for Validation Error Reporting.
+
+This module provides ModelHandlerIdentifier for uniquely identifying handlers
+in validation error contexts. Part of OMN-1091 structured validation and error
+reporting for handlers.
+
+The identifier supports multiple construction patterns:
+- From handler_id alone (minimal identification)
+- From node_path and handler_type (structured identification)
+- Full context with human-readable name
+
+This model enables precise error reporting by capturing handler identity
+information at validation failure points.
+"""
+
+from __future__ import annotations
+
+from typing import Self
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.enums import EnumHandlerType
+
+
+class ModelHandlerIdentifier(BaseModel):
+    """Identifies a handler for validation error reporting.
+
+    This model captures the identity and context of a handler when validation
+    errors occur, enabling precise error reporting and debugging. It supports
+    multiple levels of detail, from minimal handler_id-only identification to
+    full context with node paths and types.
+
+    Attributes:
+        handler_id: Unique identifier for the handler (e.g., "http-handler", "db-handler").
+            This is the minimal required field for handler identification.
+        handler_type: Type of handler (EFFECT, COMPUTE, REDUCER, ORCHESTRATOR).
+            Optional, provides architectural context for the handler.
+        handler_name: Human-readable name for the handler.
+            Optional, used for display purposes in error messages.
+        node_path: Path to the node containing this handler.
+            Optional, provides location context for debugging.
+
+    Example:
+        >>> # Minimal identification
+        >>> identifier = ModelHandlerIdentifier.from_handler_id("http-handler")
+        >>> identifier.handler_id
+        'http-handler'
+
+        >>> # Structured identification with type
+        >>> identifier = ModelHandlerIdentifier.from_node(
+        ...     node_path="nodes/registration/node.py",
+        ...     handler_type=EnumHandlerType.ORCHESTRATOR,
+        ... )
+        >>> identifier.handler_type
+        <EnumHandlerType.ORCHESTRATOR: 'orchestrator'>
+
+        >>> # Full context
+        >>> identifier = ModelHandlerIdentifier(
+        ...     handler_id="registration-orchestrator",
+        ...     handler_type=EnumHandlerType.ORCHESTRATOR,
+        ...     handler_name="Registration Orchestrator",
+        ...     node_path="nodes/registration/node.py",
+        ... )
+
+    Note:
+        This model is frozen to ensure immutability in error contexts.
+        Use factory methods for common construction patterns.
+
+    .. versionadded:: 0.6.1
+        Created as part of OMN-1091 structured validation and error reporting.
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+    )
+
+    handler_id: str = Field(
+        description="Unique identifier for the handler (e.g., 'http-handler', 'db-handler')",
+    )
+    handler_type: EnumHandlerType | None = Field(
+        default=None,
+        description="Type of handler (EFFECT, COMPUTE, REDUCER, ORCHESTRATOR)",
+    )
+    handler_name: str | None = Field(
+        default=None,
+        description="Human-readable name for the handler",
+    )
+    node_path: str | None = Field(
+        default=None,
+        description="Path to the node containing this handler",
+    )
+
+    @classmethod
+    def from_handler_id(cls, handler_id: str) -> Self:
+        """Create identifier from handler_id alone (minimal identification).
+
+        Use this factory method when only the handler_id is available,
+        typically in contexts where detailed handler metadata is not
+        readily accessible.
+
+        Args:
+            handler_id: Unique identifier for the handler.
+
+        Returns:
+            ModelHandlerIdentifier with only handler_id set.
+
+        Example:
+            >>> identifier = ModelHandlerIdentifier.from_handler_id("http-handler")
+            >>> identifier.handler_id
+            'http-handler'
+            >>> identifier.handler_type is None
+            True
+
+        .. versionadded:: 0.6.1
+        """
+        return cls(handler_id=handler_id)
+
+    @classmethod
+    def from_node(
+        cls,
+        node_path: str,
+        handler_type: EnumHandlerType,
+        handler_name: str | None = None,
+    ) -> Self:
+        """Create identifier from node path and handler type (structured identification).
+
+        Use this factory method when constructing identifiers from node context,
+        typically during contract validation or handler registration. The handler_id
+        is derived from the node path and handler type.
+
+        Args:
+            node_path: Path to the node containing the handler.
+            handler_type: Type of handler (EFFECT, COMPUTE, REDUCER, ORCHESTRATOR).
+            handler_name: Optional human-readable name for the handler.
+
+        Returns:
+            ModelHandlerIdentifier with full context.
+
+        Example:
+            >>> identifier = ModelHandlerIdentifier.from_node(
+            ...     node_path="nodes/registration/node.py",
+            ...     handler_type=EnumHandlerType.ORCHESTRATOR,
+            ...     handler_name="Registration Orchestrator",
+            ... )
+            >>> identifier.handler_id
+            'nodes/registration/node.py::orchestrator'
+            >>> identifier.handler_type
+            <EnumHandlerType.ORCHESTRATOR: 'orchestrator'>
+
+        Note:
+            The handler_id is constructed as "{node_path}::{handler_type.value}"
+            to provide a unique identifier that combines location and type.
+
+        .. versionadded:: 0.6.1
+        """
+        # Derive handler_id from node_path and handler_type
+        handler_id = f"{node_path}::{handler_type.value}"
+
+        return cls(
+            handler_id=handler_id,
+            handler_type=handler_type,
+            handler_name=handler_name,
+            node_path=node_path,
+        )
+
+    def format_for_error(self) -> str:
+        """Format identifier for inclusion in error messages.
+
+        Produces a human-readable string representation suitable for
+        error messages and logs. The format varies based on available
+        information, prioritizing readability.
+
+        Returns:
+            Formatted string representation of the handler identifier.
+
+        Example:
+            >>> # Minimal format
+            >>> ModelHandlerIdentifier.from_handler_id("http-handler").format_for_error()
+            'handler_id=http-handler'
+
+            >>> # Full format
+            >>> identifier = ModelHandlerIdentifier(
+            ...     handler_id="registration-orchestrator",
+            ...     handler_type=EnumHandlerType.ORCHESTRATOR,
+            ...     handler_name="Registration Orchestrator",
+            ...     node_path="nodes/registration/node.py",
+            ... )
+            >>> identifier.format_for_error()
+            'Registration Orchestrator (orchestrator) at nodes/registration/node.py'
+
+        .. versionadded:: 0.6.1
+        """
+        # If we have a human-readable name, use it as the primary identifier
+        if self.handler_name:
+            parts = [self.handler_name]
+            if self.handler_type:
+                parts.append(f"({self.handler_type.value})")
+            if self.node_path:
+                parts.append(f"at {self.node_path}")
+            return " ".join(parts)
+
+        # Fall back to handler_id if no name is available
+        parts = [f"handler_id={self.handler_id}"]
+        if self.handler_type:
+            parts.append(f"type={self.handler_type.value}")
+        if self.node_path:
+            parts.append(f"path={self.node_path}")
+        return ", ".join(parts)
+
+
+__all__ = ["ModelHandlerIdentifier"]

omnibase_infra/models/handlers/model_handler_source_config.py

@@ -0,0 +1,220 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Handler Source Configuration Model.
+
+This module provides ModelHandlerSourceConfig, a Pydantic model for
+configuring handler source mode selection at runtime.
+
+The configuration controls how handlers are discovered and loaded:
+    - BOOTSTRAP: Hardcoded handlers from _KNOWN_HANDLERS dict (MVP mode)
+    - CONTRACT: YAML contracts from handler_contract.yaml files (production)
+    - HYBRID: Contract-first with bootstrap fallback per-handler identity
+
+Production hardening features:
+    - Bootstrap expiry enforcement: If bootstrap_expires_at is set and now > expires_at,
+      the runtime will refuse to start in BOOTSTRAP mode (or force CONTRACT mode)
+    - Structured logging of expiry status at startup
+    - Override control for hybrid mode handler resolution
+
+.. versionadded:: 0.7.0
+    Created as part of OMN-1095 handler source mode configuration.
+
+See Also:
+    - HANDLER_PROTOCOL_DRIVEN_ARCHITECTURE.md: Full architecture documentation
+    - EnumHandlerSourceMode: Enum defining valid source modes
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from omnibase_infra.enums.enum_handler_source_mode import EnumHandlerSourceMode
+
+
+class ModelHandlerSourceConfig(BaseModel):
+    """Configuration for handler source mode selection.
+
+    Controls how handlers are discovered and loaded at runtime. This model
+    is used by RuntimeHostProcess and related components to determine the
+    handler loading strategy.
+
+    Configuration Options:
+        - handler_source_mode: Selects the loading strategy (BOOTSTRAP, CONTRACT, HYBRID)
+        - allow_bootstrap_override: Controls handler resolution in HYBRID mode
+        - bootstrap_expires_at: Production safety - forces CONTRACT after expiry
+
+    Production Hardening:
+        When bootstrap_expires_at is set and the current time exceeds it:
+        - BOOTSTRAP mode: Runtime refuses to start (safety mechanism)
+        - HYBRID mode: Bootstrap fallback disabled, contract-only resolution
+        - CONTRACT mode: No effect (already contract-only)
+
+        This prevents accidental deployment with hardcoded handlers in production.
+
+    Attributes:
+        handler_source_mode: Handler loading source mode.
+            - BOOTSTRAP: Load from hardcoded _KNOWN_HANDLERS dict (MVP)
+            - CONTRACT: Load from handler_contract.yaml files (production)
+            - HYBRID: Contract-first with bootstrap fallback per-handler identity
+            Defaults to HYBRID as recommended for gradual migration.
+
+        allow_bootstrap_override: If True, bootstrap handlers can override
+            contract handlers in HYBRID mode. Default is False, meaning
+            contract handlers take precedence (inverse of naive HYBRID).
+            Has no effect in BOOTSTRAP or CONTRACT modes.
+            When parsing from environment or config, string values "true",
+            "yes", "1", "on" (case-insensitive) are accepted as truthy.
+
+        bootstrap_expires_at: If set and expired, refuse BOOTSTRAP mode and
+            force CONTRACT. This is a production safety mechanism to ensure
+            hardcoded handlers are not accidentally deployed to production
+            after a migration deadline. Set to None to disable expiry checking.
+
+    Example:
+        >>> from datetime import datetime, timezone
+        >>> from omnibase_infra.models.handlers import ModelHandlerSourceConfig
+        >>> from omnibase_infra.enums import EnumHandlerSourceMode
+        >>>
+        >>> # Production configuration (recommended)
+        >>> config = ModelHandlerSourceConfig(
+        ...     handler_source_mode=EnumHandlerSourceMode.CONTRACT,
+        ... )
+        >>>
+        >>> # Migration configuration with safety expiry (must be timezone-aware)
+        >>> config = ModelHandlerSourceConfig(
+        ...     handler_source_mode=EnumHandlerSourceMode.HYBRID,
+        ...     bootstrap_expires_at=datetime(2025, 3, 1, 0, 0, 0, tzinfo=timezone.utc),
+        ... )
+        >>>
+        >>> # Check if bootstrap is expired
+        >>> if config.is_bootstrap_expired:
+        ...     print("Bootstrap mode has expired - must use CONTRACT")
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+    )
+
+    handler_source_mode: EnumHandlerSourceMode = Field(
+        default=EnumHandlerSourceMode.HYBRID,
+        description="Handler loading source mode: BOOTSTRAP, CONTRACT, or HYBRID. "
+        "Defaults to HYBRID (contract-first with bootstrap fallback).",
+    )
+
+    allow_bootstrap_override: bool = Field(
+        default=False,
+        description=(
+            "If True, bootstrap handlers can override contract handlers in HYBRID mode. "
+            "Default is False (contract handlers take precedence). "
+            "When parsing from config, string values 'true', 'yes', '1', 'on' "
+            "(case-insensitive) are accepted as truthy."
+        ),
+    )
+
+    bootstrap_expires_at: datetime | None = Field(
+        default=None,
+        description=(
+            "If set and expired, refuse BOOTSTRAP mode and force CONTRACT. "
+            "Production safety mechanism for migration deadlines. "
+            "Must be timezone-aware (UTC recommended); naive datetimes are rejected."
+        ),
+    )
+
+    @field_validator("allow_bootstrap_override", mode="before")
+    @classmethod
+    def _coerce_allow_bootstrap_override(cls, value: object) -> bool:
+        """Coerce string and numeric values to boolean for config file compatibility.
+
+        Environment variables and YAML/JSON config files often represent booleans
+        as strings. This validator handles common truthy string representations
+        before Pydantic's strict type validation.
+
+        Args:
+            value: The raw value to coerce (may be str, bool, int, float, None, or other).
+
+        Returns:
+            True if value is a truthy string ("true", "yes", "1", "on") or
+            a truthy boolean, False otherwise.
+
+        Type Handling:
+            - bool: Passed through unchanged.
+            - str: Case-insensitive check for "true", "yes", "1", "on".
+            - int/float: 0 and 0.0 are False, all other numbers are True.
+            - None: Returns False.
+            - Unknown types: Default to False for safety.
+        """
+        if isinstance(value, bool):
+            return value
+        if isinstance(value, str):
+            return value.lower() in ("true", "yes", "1", "on")
+        if isinstance(value, (int, float)):
+            # Explicit: 0/0.0 = False, any other number = True
+            return bool(value)
+        # Unknown types default to False for safety
+        return False
+
+    @field_validator("bootstrap_expires_at")
+    @classmethod
+    def _validate_expires_at_timezone(cls, value: datetime | None) -> datetime | None:
+        """Validate and normalize bootstrap_expires_at to UTC.
+
+        Args:
+            value: The datetime value to validate.
+
+        Returns:
+            None if value is None, otherwise the datetime normalized to UTC.
+
+        Raises:
+            ValueError: If the datetime is naive (no timezone info).
+        """
+        if value is None:
+            return None
+        if value.tzinfo is None:
+            raise ValueError(
+                "bootstrap_expires_at must be timezone-aware (UTC recommended). "
+                "Use datetime.now(timezone.utc) or datetime(..., tzinfo=timezone.utc)."
+            )
+        return value.astimezone(UTC)
+
+    @property
+    def is_bootstrap_expired(self) -> bool:
+        """Check if bootstrap mode has expired.
+
+        Returns:
+            True if bootstrap_expires_at is set and current time exceeds it,
+            False otherwise.
+
+        Note:
+            Uses UTC-aware comparison. The bootstrap_expires_at field is
+            validated and normalized to UTC at construction time.
+        """
+        if self.bootstrap_expires_at is None:
+            return False
+        return datetime.now(UTC) > self.bootstrap_expires_at
+
+    @property
+    def effective_mode(self) -> EnumHandlerSourceMode:
+        """Get the effective handler source mode after expiry check.
+
+        If bootstrap_expires_at is set and expired, returns CONTRACT
+        regardless of the configured handler_source_mode. Otherwise
+        returns the configured mode.
+
+        Returns:
+            The effective handler source mode to use at runtime.
+
+        Note:
+            This property should be used by runtime components instead of
+            directly accessing handler_source_mode to ensure expiry
+            enforcement is applied.
+        """
+        if self.is_bootstrap_expired:
+            return EnumHandlerSourceMode.CONTRACT
+        return self.handler_source_mode
+
+
+__all__ = ["ModelHandlerSourceConfig"]

omnibase_infra/models/health/__init__.py

@@ -0,0 +1,9 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Health check models for infrastructure components."""
+
+from omnibase_infra.models.health.model_health_check_result import (
+    ModelHealthCheckResult,
+)
+
+__all__ = ["ModelHealthCheckResult"]

omnibase_infra/models/health/model_health_check_result.py

@@ -0,0 +1,40 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Health Check Result Model for infrastructure components."""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelHealthCheckResult(BaseModel):
+    """Result of a health check operation on infrastructure components.
+
+    Provides standardized health check responses with typed fields
+    replacing loose dict[str, object] returns.
+
+    Attributes:
+        healthy: Whether the component is healthy and operational.
+        reason: Human-readable explanation of the health status.
+        error_type: Exception type name if health check failed.
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    healthy: bool = Field(
+        ...,
+        description="Whether the component is healthy and operational.",
+    )
+    reason: str = Field(
+        ...,
+        description="Human-readable explanation of the health status.",
+    )
+    error_type: str | None = Field(
+        default=None,
+        description="Exception type name if health check failed.",
+    )
+
+
+__all__ = ["ModelHealthCheckResult"]