omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/models/runtime/model_discovery_result.py

@@ -0,0 +1,162 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Discovery Result Model for Handler Discovery Operations.
+
+This module provides the ModelDiscoveryResult model for aggregating the results
+of handler discovery operations, including counts and any errors or warnings.
+
+See Also:
+    - ModelDiscoveryError: Individual discovery errors
+    - ModelDiscoveryWarning: Non-fatal warnings
+
+.. versionadded:: 0.7.0
+    Created as part of OMN-1133 contract-based handler discovery.
+"""
+
+from __future__ import annotations
+
+from datetime import UTC, datetime
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.models.runtime.model_discovery_error import ModelDiscoveryError
+from omnibase_infra.models.runtime.model_discovery_warning import ModelDiscoveryWarning
+
+
+class ModelDiscoveryResult(BaseModel):
+    """Result of a handler discovery operation.
+
+    Aggregates the results of a discovery operation including counts of
+    discovered and registered handlers, any errors or warnings encountered,
+    and the timestamp of completion.
+
+    Attributes:
+        handlers_discovered: Number of handlers found during discovery.
+        handlers_registered: Number of handlers successfully registered.
+        errors: List of errors encountered during discovery.
+        warnings: List of non-fatal warnings encountered during discovery.
+        discovered_at: Timestamp when discovery completed.
+
+    Example:
+        >>> result = ModelDiscoveryResult(
+        ...     handlers_discovered=5,
+        ...     handlers_registered=4,
+        ...     errors=[ModelDiscoveryError(
+        ...         error_code="MODULE_NOT_FOUND",
+        ...         message="Module not found",
+        ...     )],
+        ... )
+        >>> result.has_errors
+        True
+        >>> bool(result)  # False because there are errors
+        False
+
+    .. versionadded:: 0.7.0
+    """
+
+    model_config = ConfigDict(
+        extra="forbid",
+        strict=True,
+    )
+
+    handlers_discovered: int = Field(
+        default=0,
+        ge=0,
+        description="Number of handlers found during discovery",
+    )
+    handlers_registered: int = Field(
+        default=0,
+        ge=0,
+        description="Number of handlers successfully registered",
+    )
+    errors: list[ModelDiscoveryError] = Field(
+        default_factory=list,
+        description="List of errors encountered during discovery",
+    )
+    warnings: list[ModelDiscoveryWarning] = Field(
+        default_factory=list,
+        description="List of non-fatal warnings encountered during discovery",
+    )
+    discovered_at: datetime = Field(
+        default_factory=lambda: datetime.now(UTC),
+        description="Timestamp when discovery completed",
+    )
+
+    @property
+    def has_errors(self) -> bool:
+        """Check if any errors occurred during discovery.
+
+        Returns:
+            True if errors list is non-empty, False otherwise.
+
+        Example:
+            >>> ModelDiscoveryResult().has_errors
+            False
+
+        .. versionadded:: 0.7.0
+        """
+        return len(self.errors) > 0
+
+    @property
+    def has_warnings(self) -> bool:
+        """Check if any warnings occurred during discovery.
+
+        Returns:
+            True if warnings list is non-empty, False otherwise.
+
+        Example:
+            >>> ModelDiscoveryResult().has_warnings
+            False
+
+        .. versionadded:: 0.7.0
+        """
+        return len(self.warnings) > 0
+
+    def __bool__(self) -> bool:
+        """Allow using result in boolean context for success checking.
+
+        Warning:
+            **Non-standard __bool__ behavior**: This model overrides ``__bool__`` to
+            return ``True`` only when no errors occurred during discovery. This differs
+            from typical Pydantic model behavior where ``bool(model)`` always returns
+            ``True`` for any valid model instance.
+
+            This design enables idiomatic conditional checks for discovery results::
+
+                result = loader.discover_handlers(path)
+                if result:
+                    # Discovery succeeded - use handlers
+                    process_handlers(result.handlers_registered)
+                else:
+                    # Discovery had errors - handle failures
+                    for error in result.errors:
+                        log_error(error)
+
+            If you need to check model validity instead, use explicit attribute access::
+
+                # Check for discovery success (uses __bool__)
+                if result:
+                    ...
+
+                # Check model exists (always True for constructed instance)
+                if result is not None:
+                    ...
+
+                # Explicit error check (preferred for clarity)
+                if not result.has_errors:
+                    ...
+
+        Returns:
+            True if discovery was successful (no errors), False otherwise.
+
+        Example:
+            >>> if ModelDiscoveryResult(handlers_discovered=5, handlers_registered=5):
+            ...     print("Success!")
+            Success!
+
+        .. versionadded:: 0.7.0
+        """
+        return len(self.errors) == 0
+
+
+__all__ = ["ModelDiscoveryResult"]

omnibase_infra/models/runtime/model_discovery_warning.py

@@ -0,0 +1,74 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Discovery Warning Model for Handler Discovery Operations.
+
+This module provides the ModelDiscoveryWarning model for tracking non-fatal
+warnings encountered during handler discovery operations.
+
+See Also:
+    - ModelDiscoveryResult: Aggregate discovery results
+    - ModelDiscoveryError: Fatal discovery errors
+
+.. versionadded:: 0.7.0
+    Created as part of OMN-1133 contract-based handler discovery.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelDiscoveryWarning(BaseModel):
+    """Represents a non-fatal warning during handler discovery.
+
+    Captures warnings that don't prevent discovery from completing but
+    indicate potential issues that should be addressed.
+
+    Attributes:
+        warning_code: Structured warning code for categorization.
+        message: Human-readable warning description.
+        contract_path: Path to the contract file that triggered the warning.
+        handler_name: Name of the handler related to the warning.
+
+    Example:
+        >>> from pathlib import Path
+        >>> warning = ModelDiscoveryWarning(
+        ...     warning_code="DEPRECATED_FIELD",
+        ...     message="Contract uses deprecated 'handler_class' field",
+        ...     contract_path=Path("/app/handlers/legacy/contract.yaml"),
+        ... )
+        >>> warning.warning_code
+        'DEPRECATED_FIELD'
+
+    .. versionadded:: 0.7.0
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+    )
+
+    warning_code: str = Field(
+        ...,
+        min_length=1,
+        description="Structured warning code for categorization",
+    )
+    message: str = Field(
+        ...,
+        min_length=1,
+        description="Human-readable warning description",
+    )
+    contract_path: Path | None = Field(
+        default=None,
+        description="Path to the contract file that triggered the warning",
+    )
+    handler_name: str | None = Field(
+        default=None,
+        description="Name of the handler related to the warning",
+    )
+
+
+__all__ = ["ModelDiscoveryWarning"]

omnibase_infra/models/runtime/model_failed_plugin_load.py

@@ -0,0 +1,63 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Failed Plugin Load Model for Observability Logging.
+
+This module provides ModelFailedPluginLoad which tracks plugin loading failures
+for observability purposes.
+
+See Also:
+    - PluginLoader: Uses this model for failure tracking
+    - ModelPluginLoadSummary: Summary model that includes failed loads
+
+.. versionadded:: 0.7.0
+    Created as part of OMN-1132 Plugin Loader observability logging.
+"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelFailedPluginLoad(BaseModel):
+    """Represents a plugin that failed to load.
+
+    Captures the contract path and error details for plugins that could not
+    be loaded during a batch operation. Used for diagnostics and debugging.
+
+    Attributes:
+        contract_path: Path to the contract file that failed to load.
+        error_message: Human-readable error description.
+        error_code: Structured error code (e.g., HANDLER_LOADER_002).
+
+    Example:
+        >>> failed = ModelFailedPluginLoad(
+        ...     contract_path=Path("/app/plugins/auth/contract.yaml"),
+        ...     error_message="Invalid YAML syntax",
+        ...     error_code="HANDLER_LOADER_002",
+        ... )
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+    )
+
+    contract_path: Path = Field(
+        ...,
+        description="Path to the contract file that failed to load",
+    )
+    error_message: str = Field(
+        ...,
+        min_length=1,
+        description="Human-readable error description",
+    )
+    error_code: str | None = Field(
+        default=None,
+        description="Structured error code (e.g., HANDLER_LOADER_002)",
+    )
+
+
+__all__ = ["ModelFailedPluginLoad"]

omnibase_infra/models/runtime/model_handler_contract.py

@@ -0,0 +1,280 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Handler Contract Model for Contract-Driven Discovery.
+
+This module provides ModelHandlerContract, a Pydantic model that represents the
+schema for handler contract YAML files. It replaces manual field extraction in
+HandlerPluginLoader with automatic validation and type coercion.
+
+The model supports dual field names for flexibility:
+- handler_name / name
+- capability_tags / tags
+
+See Also:
+    - HandlerPluginLoader: Uses this model to validate contracts
+    - ModelLoadedHandler: Output model after successful loading
+    - EnumHandlerTypeCategory: Handler behavioral classification
+
+.. versionadded:: 0.7.0
+    Created as part of OMN-1132 Handler Plugin Loader implementation.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
+
+logger = logging.getLogger(__name__)
+
+from omnibase_infra.enums.enum_handler_type_category import EnumHandlerTypeCategory
+from omnibase_infra.errors import ProtocolConfigurationError
+from omnibase_infra.models.runtime.model_contract_security_config import (
+    ModelContractSecurityConfig,
+)
+
+# Handler type category mapping from contract strings to enum
+_HANDLER_TYPE_CATEGORY_MAP: dict[str, EnumHandlerTypeCategory] = {
+    "compute": EnumHandlerTypeCategory.COMPUTE,
+    "effect": EnumHandlerTypeCategory.EFFECT,
+    "nondeterministic_compute": EnumHandlerTypeCategory.NONDETERMINISTIC_COMPUTE,
+}
+
+
+class ModelHandlerContract(BaseModel):
+    """Pydantic model for handler contract YAML schema.
+
+    Validates and parses handler contract YAML files with automatic type
+    coercion and field aliasing. Supports dual field names for flexibility
+    in contract authoring.
+
+    Field Aliases:
+        - handler_name: Also accepts 'name'
+        - capability_tags: Also accepts 'tags'
+
+    Handler Type Conversion:
+        The handler_type field accepts string values (e.g., 'compute', 'effect',
+        'nondeterministic_compute') and converts them to EnumHandlerTypeCategory
+        enum values. Case-insensitive matching is supported.
+
+    Attributes:
+        handler_name: Unique identifier for the handler. Required field
+            that accepts both 'handler_name' and 'name' keys in YAML.
+        handler_class: Fully qualified class path for the handler
+            (e.g., 'myapp.handlers.AuthHandler'). Required field.
+        handler_type: Behavioral classification of the handler. Required field
+            that accepts string values and converts to EnumHandlerTypeCategory.
+        capability_tags: List of tags for handler discovery and filtering.
+            Optional field that accepts both 'capability_tags' and 'tags' keys.
+
+    Example:
+        >>> from omnibase_infra.models.runtime import ModelHandlerContract
+        >>> # Parse from YAML dict with 'name' alias
+        >>> contract = ModelHandlerContract.model_validate({
+        ...     "name": "auth.handler",
+        ...     "handler_class": "myapp.handlers.AuthHandler",
+        ...     "handler_type": "compute",
+        ...     "tags": ["auth", "validation"],
+        ... })
+        >>> contract.handler_name
+        'auth.handler'
+        >>> contract.handler_type
+        <EnumHandlerTypeCategory.COMPUTE: 'compute'>
+
+        >>> # Parse with canonical field names
+        >>> contract = ModelHandlerContract.model_validate({
+        ...     "handler_name": "db.handler",
+        ...     "handler_class": "myapp.handlers.DbHandler",
+        ...     "handler_type": "effect",
+        ...     "capability_tags": ["database", "postgres"],
+        ... })
+
+    See Also:
+        - :class:`HandlerPluginLoader`: Uses this model for contract validation.
+        - :class:`ModelLoadedHandler`: Output model after successful loading.
+    """
+
+    model_config = ConfigDict(
+        extra="forbid",
+        populate_by_name=True,
+        str_strip_whitespace=True,
+    )
+
+    handler_name: str = Field(
+        ...,
+        min_length=1,
+        validation_alias="name",
+        description="Unique identifier for the handler (also accepts 'name')",
+    )
+    handler_class: str = Field(
+        ...,
+        min_length=1,
+        description="Fully qualified handler class path (e.g., 'myapp.handlers.AuthHandler')",
+    )
+    handler_type: EnumHandlerTypeCategory = Field(
+        ...,
+        description="Behavioral classification (compute, effect, nondeterministic_compute)",
+    )
+    capability_tags: list[str] = Field(
+        default_factory=list,
+        validation_alias="tags",
+        description="Tags for handler discovery and filtering (also accepts 'tags')",
+    )
+    protocol_type: str | None = Field(
+        default=None,
+        description=(
+            "Protocol type identifier for registry (e.g., 'db', 'http', 'consul'). "
+            "If not provided, defaults to handler_name with 'handler-' prefix stripped."
+        ),
+    )
+    security: ModelContractSecurityConfig | None = Field(
+        default=None,
+        description="Optional security configuration for the handler",
+    )
+
+    @field_validator("handler_type", mode="before")
+    @classmethod
+    def convert_handler_type(cls, value: object) -> EnumHandlerTypeCategory:
+        """Convert string handler_type to EnumHandlerTypeCategory.
+
+        Accepts case-insensitive string values and converts them to the
+        appropriate enum value. Also accepts EnumHandlerTypeCategory directly.
+
+        Args:
+            value: String handler type name or EnumHandlerTypeCategory.
+
+        Returns:
+            EnumHandlerTypeCategory enum value.
+
+        Raises:
+            ValueError: If the value is not a valid handler type.
+        """
+        # Already an enum
+        if isinstance(value, EnumHandlerTypeCategory):
+            return value
+
+        # Convert string to enum
+        if isinstance(value, str):
+            normalized = value.lower().strip()
+            if normalized in _HANDLER_TYPE_CATEGORY_MAP:
+                return _HANDLER_TYPE_CATEGORY_MAP[normalized]
+
+            valid_types = ", ".join(_HANDLER_TYPE_CATEGORY_MAP.keys())
+            raise ValueError(
+                f"Invalid handler_type '{value}'. Valid types: {valid_types}"
+            )
+
+        raise ValueError(
+            f"handler_type must be a string or EnumHandlerTypeCategory, got {type(value).__name__}"
+        )
+
+    @field_validator("capability_tags", mode="before")
+    @classmethod
+    def normalize_capability_tags(cls, value: object) -> list[str]:
+        """Normalize capability_tags to a list of strings.
+
+        Handles various input formats:
+        - None -> empty list
+        - Single string -> list with one element
+        - List with mixed types -> filter to strings only
+
+        Args:
+            value: Raw value from YAML (None, str, or list).
+
+        Returns:
+            List of string capability tags.
+        """
+        if value is None:
+            return []
+
+        if isinstance(value, str):
+            return [value]
+
+        if isinstance(value, list):
+            # Filter to only string tags, warn about invalid types
+            valid_tags: list[str] = []
+            for tag in value:
+                if isinstance(tag, str):
+                    valid_tags.append(tag)
+                else:
+                    logger.warning(
+                        "Non-string capability tag filtered out: value=%r, type=%s",
+                        tag,
+                        type(tag).__name__,
+                    )
+            return valid_tags
+
+        return []
+
+    @model_validator(mode="after")
+    def set_default_protocol_type(self) -> ModelHandlerContract:
+        """Set protocol_type from handler_name if not explicitly provided.
+
+        If protocol_type is None, derives it from handler_name by stripping
+        the 'handler-' prefix. If handler_name doesn't have that prefix,
+        uses the full handler_name as protocol_type.
+
+        Guards against empty derived protocol_type which would produce
+        invalid registry keys.
+
+        Returns:
+            Self with protocol_type populated.
+
+        Raises:
+            ValueError: If derived protocol_type would be empty (e.g., handler_name
+                is exactly "handler-" with nothing after the prefix).
+
+        Example:
+            >>> contract = ModelHandlerContract(
+            ...     handler_name="handler-db",
+            ...     handler_class="myapp.handlers.DbHandler",
+            ...     handler_type="effect",
+            ... )
+            >>> contract.protocol_type
+            'db'
+
+            >>> contract = ModelHandlerContract(
+            ...     handler_name="custom-handler",
+            ...     handler_class="myapp.handlers.Custom",
+            ...     handler_type="compute",
+            ... )
+            >>> contract.protocol_type
+            'custom-handler'
+        """
+        if self.protocol_type is None:
+            prefix = "handler-"
+            if self.handler_name.startswith(prefix):
+                derived = self.handler_name[len(prefix) :]
+                if not derived:
+                    raise ProtocolConfigurationError(
+                        f"Cannot derive protocol_type from handler_name '{self.handler_name}': "
+                        f"result would be empty. Either provide an explicit protocol_type "
+                        f"or use a handler_name with content after the 'handler-' prefix."
+                    )
+                self.protocol_type = derived
+            else:
+                self.protocol_type = self.handler_name
+
+        # Final guard: ensure protocol_type is never empty
+        if not self.protocol_type:
+            raise ProtocolConfigurationError(
+                f"protocol_type cannot be empty. handler_name='{self.handler_name}', "
+                f"derived protocol_type='{self.protocol_type}'. "
+                f"Provide a non-empty protocol_type or handler_name."
+            )
+
+        # Log successful protocol_type derivation for debugging
+        logger.debug(
+            "Handler contract validated successfully",
+            extra={
+                "handler_name": self.handler_name,
+                "handler_class": self.handler_class,
+                "protocol_type": self.protocol_type,
+                "handler_type": self.handler_type.value,
+            },
+        )
+
+        return self
+
+
+__all__ = ["ModelHandlerContract"]

omnibase_infra/models/runtime/model_loaded_handler.py

@@ -0,0 +1,120 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Loaded Handler Model for Handler Plugin Loader.
+
+This module provides ModelLoadedHandler, which represents a handler that has been
+successfully discovered, validated, and registered by the HandlerPluginLoader.
+
+The model captures essential metadata about loaded handlers for runtime tracking,
+discovery filtering, and diagnostic purposes.
+
+See Also:
+    - HandlerPluginLoader: Loader that creates these descriptors
+    - ModelHandlerDescriptor: Contract-level handler descriptor
+    - EnumHandlerTypeCategory: Handler behavioral classification
+
+.. versionadded:: 0.7.0
+    Created as part of OMN-1132 Handler Plugin Loader implementation.
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.enums.enum_handler_type_category import EnumHandlerTypeCategory
+
+
+class ModelLoadedHandler(BaseModel):
+    """Represents a handler loaded from a contract.
+
+    Tracks metadata about handlers that have been successfully discovered,
+    validated, and registered by the HandlerPluginLoader.
+
+    This model is used for:
+    - Runtime handler registry tracking
+    - Handler discovery and filtering by capability tags
+    - Diagnostics and introspection of loaded handlers
+    - Audit logging of handler loading events
+
+    Attributes:
+        handler_name: Unique identifier for the handler. Used as the primary
+            key for handler registry lookups.
+        handler_type: Behavioral classification of the handler (COMPUTE, EFFECT,
+            or NONDETERMINISTIC_COMPUTE). Determines policy envelope and runtime
+            behavior.
+        handler_class: Fully qualified class name of the handler implementation
+            (e.g., 'myapp.handlers.AuthHandler'). Used for dynamic instantiation.
+        contract_path: Absolute path to the contract YAML file from which this
+            handler was loaded. Used for reloading and validation.
+        capability_tags: List of tags for handler discovery and filtering.
+            Examples: ['auth', 'validation', 'http-client'].
+        loaded_at: Timestamp when the handler was successfully loaded.
+            Used for diagnostics and cache invalidation.
+
+    Example:
+        >>> from datetime import datetime, UTC
+        >>> from pathlib import Path
+        >>> from omnibase_infra.enums import EnumHandlerTypeCategory
+        >>> handler = ModelLoadedHandler(
+        ...     handler_name="auth.validate_token",
+        ...     handler_type=EnumHandlerTypeCategory.COMPUTE,
+        ...     handler_class="myapp.handlers.TokenValidator",
+        ...     contract_path=Path("/app/handlers/auth/handler_contract.yaml"),
+        ...     capability_tags=["auth", "validation", "jwt"],
+        ...     loaded_at=datetime.now(UTC),
+        ... )
+        >>> handler.handler_name
+        'auth.validate_token'
+
+    See Also:
+        - :class:`ModelHandlerDescriptor`: Contract-level handler metadata.
+        - :class:`EnumHandlerTypeCategory`: Handler behavioral classification.
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        strict=True,
+    )
+
+    handler_name: str = Field(
+        ...,
+        min_length=1,
+        description="Unique identifier for the handler",
+    )
+    protocol_type: str = Field(
+        ...,
+        min_length=1,
+        description=(
+            "Protocol type identifier for registry lookup (e.g., 'db', 'http'). "
+            "Used as the key for handler registry registration."
+        ),
+    )
+    handler_type: EnumHandlerTypeCategory = Field(
+        ...,
+        description="Behavioral classification (COMPUTE, EFFECT, NONDETERMINISTIC_COMPUTE)",
+    )
+    handler_class: str = Field(
+        ...,
+        min_length=3,
+        pattern=r"^[a-zA-Z_][a-zA-Z0-9_]*(\.[a-zA-Z_][a-zA-Z0-9_]*)+$",
+        description="Fully qualified handler class name (e.g., 'myapp.handlers.AuthHandler')",
+    )
+    contract_path: Path = Field(
+        ...,
+        description="Absolute path to the source contract YAML file",
+    )
+    capability_tags: list[str] = Field(
+        default_factory=list,
+        description="Tags for handler discovery and filtering",
+    )
+    loaded_at: datetime = Field(
+        ...,
+        description="Timestamp when the handler was successfully loaded",
+    )
+
+
+__all__ = ["ModelLoadedHandler"]