omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/runtime/models/model_policy_registration.py

@@ -0,0 +1,139 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Policy Registration Model.
+
+This module provides the Pydantic model for policy registration parameters,
+used to register policy plugins with the RegistryPolicy.
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from pydantic import BaseModel, ConfigDict, Field, field_validator
+
+from omnibase_infra.enums import EnumPolicyType
+from omnibase_infra.runtime.util_version import normalize_version
+from omnibase_infra.types import PolicyTypeInput
+from omnibase_infra.utils import validate_policy_type_value
+
+# NOTE: PolicyTypeInput is the INPUT type (str | EnumPolicyType) for API flexibility.
+# The validator coerces strings to EnumPolicyType, so the actual stored value is
+# always an enum. This ensures type-safe access after model instantiation.
+
+if TYPE_CHECKING:
+    from omnibase_infra.runtime.protocol_policy import ProtocolPolicy
+
+    # Type alias for policy class - uses TYPE_CHECKING to avoid circular import
+    PolicyClass = type[ProtocolPolicy]
+else:
+    # NOTE: At runtime we use generic type to avoid circular import.
+    # Type checkers see proper protocol type via TYPE_CHECKING block.
+    PolicyClass = type  # type: ignore[assignment,misc]
+
+
+class ModelPolicyRegistration(BaseModel):
+    """Model for policy registration parameters.
+
+    Encapsulates all parameters needed to register a policy plugin with
+    the RegistryPolicy. This model reduces the number of parameters in
+    the register() method signature.
+
+    Attributes:
+        policy_id: Unique identifier for the policy (e.g., 'exponential_backoff')
+        policy_class: Policy implementation class that implements ProtocolPolicy
+        policy_type: Policy type - either orchestrator or reducer
+        version: Semantic version string (default: "1.0.0")
+        description: Human-readable description of the policy
+        allow_async: If True, allows async interface (must be explicit)
+
+    Example:
+        >>> from omnibase_infra.runtime.models import ModelPolicyRegistration
+        >>> from omnibase_infra.enums import EnumPolicyType
+        >>> registration = ModelPolicyRegistration(
+        ...     policy_id="exponential_backoff",
+        ...     policy_class=ExponentialBackoffPolicy,
+        ...     policy_type=EnumPolicyType.ORCHESTRATOR,
+        ...     version="1.0.0",
+        ...     description="Calculates exponential backoff delays for retries",
+        ... )
+    """
+
+    model_config = ConfigDict(
+        strict=False,  # Allow type coercion for policy_class
+        frozen=True,
+        extra="forbid",
+        arbitrary_types_allowed=True,  # Required for type[ProtocolPolicy]
+    )
+
+    policy_id: str = Field(
+        ...,
+        description="Unique policy identifier (e.g., 'exponential_backoff')",
+    )
+    policy_class: PolicyClass = Field(
+        ...,
+        description="Policy implementation class that implements ProtocolPolicy",
+    )
+    # NOTE: Field accepts PolicyTypeInput (str | EnumPolicyType) via mode="before" coercion,
+    # but the validator always coerces to EnumPolicyType. We annotate with the coerced type.
+    policy_type: EnumPolicyType = Field(
+        ...,
+        description="Policy type (accepts string or enum, always stored as EnumPolicyType)",
+    )
+    version: str = Field(
+        default="1.0.0",
+        description="Semantic version string",
+    )
+    description: str = Field(
+        default="",
+        description="Human-readable description of the policy",
+    )
+    allow_async: bool = Field(
+        default=False,
+        description="If True, allows async interface (must be explicit for async policies)",
+    )
+
+    @field_validator("version", mode="before")
+    @classmethod
+    def validate_and_normalize_version(cls, v: str) -> str:
+        """Normalize version string for consistent storage.
+
+        Delegates to the shared normalize_version utility which is the
+        SINGLE SOURCE OF TRUTH for version normalization in omnibase_infra.
+
+        Converts version strings to canonical x.y.z format. This ensures version
+        strings are consistent across the registry, preventing storage/lookup
+        mismatches.
+
+        Normalization rules:
+            1. Strip leading/trailing whitespace
+            2. Strip leading 'v' or 'V' prefix
+            3. Expand partial versions (1 -> 1.0.0, 1.0 -> 1.0.0)
+            4. Parse with ModelSemVer.parse() for validation
+            5. Preserve prerelease suffix if present
+
+        Args:
+            v: The version string to normalize
+
+        Returns:
+            Normalized version string in "x.y.z" or "x.y.z-prerelease" format
+
+        Raises:
+            ValueError: If the version string is invalid and cannot be parsed
+        """
+        return normalize_version(v)
+
+    @field_validator("policy_type", mode="before")
+    @classmethod
+    def validate_policy_type(cls, v: PolicyTypeInput) -> EnumPolicyType:
+        """Validate and coerce policy_type to EnumPolicyType.
+
+        Delegates to shared utility for consistent validation across all models.
+        String values are coerced to EnumPolicyType, ensuring type-safe access.
+
+        Note: mode="before" allows accepting str input before Pydantic validation.
+        """
+        return validate_policy_type_value(v)
+
+
+__all__: list[str] = ["ModelPolicyRegistration"]

omnibase_infra/runtime/models/model_policy_result.py

@@ -0,0 +1,103 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Pydantic model for policy evaluation result.
+
+This module provides the ModelPolicyResult Pydantic BaseModel for returning
+structured results from policy evaluation methods.
+
+Design Notes:
+    - Uses ConfigDict(extra="allow") to support arbitrary policy-specific fields
+    - Supports dict-like access via __getitem__ for flexible API usage
+    - Can be instantiated from dicts using model_validate()
+    - Follows ONEX naming convention: Model<Name>
+
+This model replaces the former JsonType return type in ProtocolPolicy.evaluate()
+and ProtocolPolicy.decide() method signatures, providing type safety while
+maintaining flexibility for diverse policy results.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.mixins import MixinDictLikeAccessors
+
+
+class ModelPolicyResult(MixinDictLikeAccessors, BaseModel):
+    """Base Pydantic model for policy evaluation results.
+
+    This model provides structured results from policy evaluation including
+    decisions, computed values, and metadata.
+
+    Common Fields:
+        success: Whether the policy evaluation succeeded
+        reason: Human-readable explanation of the decision
+        metadata: Additional metadata for observability
+
+    Configuration:
+        - extra="allow": Accepts arbitrary additional fields for policy-specific results
+        - frozen=False: Allows mutation
+        - populate_by_name=True: Allows field access by alias
+
+    Example:
+        ```python
+        # Return from orchestrator policy (retry decision)
+        result = ModelPolicyResult(
+            should_retry=True,
+            delay_seconds=4.0,
+            reason="Attempt 2 of 10, exponential backoff",
+        )
+
+        # Return from reducer policy (merge decision)
+        result = ModelPolicyResult(
+            merged_state={"count": 5, "sum": 100},
+            conflicts=[],
+            success=True,
+        )
+
+        # Access with get (dict-like, backwards compatible)
+        should_retry = result.get("should_retry", False)
+
+        # Access as attribute
+        delay = result.delay_seconds
+        ```
+
+    Policy-Specific Fields:
+        For orchestrator retry policies:
+            - should_retry: Whether to retry the operation
+            - delay_seconds: Delay before retry
+            - max_retries_reached: Whether max retries exceeded
+
+        For orchestrator routing policies:
+            - target_handler: Handler to route to
+            - priority: Routing priority
+            - fallback_handlers: Alternative handlers if primary fails
+
+        For reducer merge policies:
+            - merged_state: Result of state merge
+            - conflicts: List of detected conflicts
+            - resolution_strategy: How conflicts were resolved
+
+        For reducer projection policies:
+            - projection: Projected view of state
+            - projection_type: Type of projection applied
+
+    Note:
+        All fields are optional due to extra="allow". Specific policies should
+        document which result fields they return.
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        frozen=False,
+        populate_by_name=True,
+        from_attributes=True,
+    )
+
+    # Common result fields - all optional with defaults
+    success: bool = True
+    reason: str = ""
+    metadata: dict[str, object] = Field(default_factory=dict)
+
+
+__all__: list[str] = ["ModelPolicyResult"]

omnibase_infra/runtime/models/model_policy_type_filter.py

@@ -0,0 +1,157 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Model for policy type filter values in runtime module.
+
+This module provides a strongly-typed Pydantic model for policy type
+filter values, replacing `str | EnumPolicyType | None` union types
+to comply with ONEX standards.
+"""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.enums import EnumPolicyType
+
+
+class ModelPolicyTypeFilter(BaseModel):
+    """Strongly-typed model for policy type filter values.
+
+    Replaces `str | EnumPolicyType | None` to comply with ONEX standards
+    requiring specific typed models instead of generic union types.
+
+    This model is used in PolicyRegistry filtering operations where the
+    policy type can be specified as:
+    - A string literal (e.g., "orchestrator", "reducer")
+    - An EnumPolicyType enum value
+    - None (no filter, match all types)
+
+    The model provides normalization methods to convert any input format
+    to a consistent string representation for internal use.
+
+    Attributes:
+        string_value: The policy type as a string, if provided as string.
+        enum_value: The policy type as an enum, if provided as enum.
+
+    Example:
+        >>> filter1 = ModelPolicyTypeFilter(string_value="orchestrator")
+        >>> filter1.normalize()
+        'orchestrator'
+        >>> filter2 = ModelPolicyTypeFilter(enum_value=EnumPolicyType.REDUCER)
+        >>> filter2.normalize()
+        'reducer'
+        >>> filter3 = ModelPolicyTypeFilter()
+        >>> filter3.normalize() is None
+        True
+    """
+
+    string_value: str | None = Field(
+        default=None, description="Policy type as string literal"
+    )
+    enum_value: EnumPolicyType | None = Field(
+        default=None, description="Policy type as EnumPolicyType enum"
+    )
+
+    model_config = ConfigDict(
+        frozen=True,  # Make immutable like ModelPolicyKey
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    @classmethod
+    def from_string(cls, value: str) -> "ModelPolicyTypeFilter":
+        """Create filter from a string value.
+
+        Args:
+            value: The policy type as a string.
+
+        Returns:
+            A new ModelPolicyTypeFilter with string_value set.
+        """
+        return cls(string_value=value)
+
+    @classmethod
+    def from_enum(cls, value: EnumPolicyType) -> "ModelPolicyTypeFilter":
+        """Create filter from an EnumPolicyType value.
+
+        Args:
+            value: The policy type as an enum.
+
+        Returns:
+            A new ModelPolicyTypeFilter with enum_value set.
+        """
+        return cls(enum_value=value)
+
+    @classmethod
+    def none(cls) -> "ModelPolicyTypeFilter":
+        """Create an empty filter (matches all types).
+
+        Returns:
+            A new ModelPolicyTypeFilter with no value set.
+        """
+        return cls()
+
+    def normalize(self) -> str | None:
+        """Normalize the filter value to a string or None.
+
+        Converts the internal representation to a consistent string
+        format for use in filtering operations.
+
+        Returns:
+            The policy type as a string if set, None otherwise.
+            Enum values are converted to their string representation.
+        """
+        if self.enum_value is not None:
+            return self.enum_value.value
+        return self.string_value
+
+    def has_value(self) -> bool:
+        """Check if a filter value is present.
+
+        Returns:
+            True if either string_value or enum_value is set.
+        """
+        return self.string_value is not None or self.enum_value is not None
+
+    def matches(self, policy_type: str) -> bool:
+        """Check if this filter matches a given policy type.
+
+        Args:
+            policy_type: The policy type string to check against.
+
+        Returns:
+            True if:
+            - This filter has no value (matches all types)
+            - The normalized filter value equals the given policy type
+        """
+        normalized = self.normalize()
+        if normalized is None:
+            return True
+        return normalized == policy_type
+
+    def __bool__(self) -> bool:
+        """Boolean representation based on value presence.
+
+        Warning:
+            **Non-standard __bool__ behavior**: This model overrides ``__bool__`` to
+            return ``True`` only when a filter value is set. This differs from typical
+            Pydantic model behavior where ``bool(model)`` always returns ``True`` for
+            any valid model instance.
+
+            This design enables idiomatic filter checks::
+
+                if policy_filter:
+                    # Filter is active - apply it
+                    filtered = [p for p in policies if policy_filter.matches(p.type)]
+                else:
+                    # No filter - return all
+                    filtered = policies
+
+            Use ``policy_filter.has_value()`` for explicit, self-documenting code.
+            Use ``policy_filter is not None`` if you need to check model existence.
+
+        Returns:
+            True if a filter value is set, False otherwise.
+        """
+        return self.has_value()
+
+
+__all__ = ["ModelPolicyTypeFilter"]

omnibase_infra/runtime/models/model_projector_plugin_loader_config.py

@@ -0,0 +1,47 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Projector Plugin Loader Configuration Model.
+
+This module provides the Pydantic model for projector plugin loader configuration.
+All fields are strongly typed to eliminate Any usage and enable proper validation.
+
+Example:
+    >>> config = ModelProjectorPluginLoaderConfig(
+    ...     graceful_mode=True,
+    ...     base_paths=[Path("/workspace/projectors")],
+    ... )
+    >>> loader = ProjectorPluginLoader(config=config)
+"""
+
+from pathlib import Path
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelProjectorPluginLoaderConfig(BaseModel):
+    """Configuration model for ProjectorPluginLoader.
+
+    This model encapsulates the configuration parameters for the projector
+    plugin loader, separating config from runtime dependencies (container,
+    schema_manager, pool).
+
+    Attributes:
+        graceful_mode: If True, collect errors and continue discovery.
+            If False (default), raise on first error.
+        base_paths: Optional list of base paths for security validation.
+            Symlinks are only allowed if they resolve within these paths.
+            If None, uses the paths provided to discovery methods.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    graceful_mode: bool = Field(
+        default=False,
+        description="If True, collect errors and continue discovery. "
+        "If False (default), raise on first error.",
+    )
+    base_paths: list[Path] | None = Field(
+        default=None,
+        description="Optional list of base paths for security validation. "
+        "Symlinks are only allowed if they resolve within these paths.",
+    )

omnibase_infra/runtime/models/model_protocol_registration_config.py

@@ -0,0 +1,65 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Protocol Registration Configuration Model.
+
+This module provides the Pydantic model for individual protocol registration
+configuration within contract-driven runtime setup.
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.runtime.models.model_enabled_protocols_config import ProtocolName
+
+
+class ModelProtocolRegistrationConfig(BaseModel):
+    """Protocol registration configuration model.
+
+    Defines configuration for a single protocol registration as specified
+    in runtime contracts.
+
+    Attributes:
+        type: Protocol type identifier (e.g., "http", "db", "kafka")
+        protocol_class: Fully qualified protocol class name for instantiation
+        enabled: Whether this protocol is enabled for registration
+        options: Additional protocol-specific configuration options
+
+    Example:
+        >>> config = ModelProtocolRegistrationConfig(
+        ...     type="http",
+        ...     protocol_class="omnibase_infra.handlers.handler_http.HttpHandler",
+        ...     enabled=True,
+        ...     options={"timeout": "30"},
+        ... )
+        >>> print(config.type)
+        'http'
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        populate_by_name=True,  # Allow both alias and field name
+        from_attributes=True,  # Support pytest-xdist compatibility
+    )
+
+    type: ProtocolName = Field(
+        description="Protocol type identifier (e.g., 'http', 'db', 'kafka')",
+    )
+    protocol_class: str | None = Field(
+        default=None,
+        alias="class",
+        description="Fully qualified protocol class name for instantiation",
+    )
+    enabled: bool = Field(
+        default=True,
+        description="Whether this protocol is enabled for registration",
+    )
+    options: dict[str, str] = Field(
+        default_factory=dict,
+        description="Additional protocol-specific configuration options",
+    )
+
+
+__all__: list[str] = ["ModelProtocolRegistrationConfig"]

omnibase_infra/runtime/models/model_retry_policy.py

@@ -0,0 +1,105 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Retry policy configuration model.
+
+.. versionadded:: 0.8.0
+    Initial implementation for OMN-765.
+
+This module provides the retry policy model used by binding configurations.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field, ValidationInfo, field_validator
+
+
+class ModelRetryPolicy(BaseModel):
+    """Retry policy configuration for handler operations.
+
+    Defines how failed handler operations should be retried, including
+    the maximum number of attempts and the backoff strategy.
+
+    Attributes:
+        max_retries: Maximum number of retry attempts (0 means no retries).
+        backoff_strategy: Strategy for calculating delays between retries.
+            - "fixed": Same delay between each retry.
+            - "exponential": Delay doubles with each retry.
+        base_delay_ms: Initial delay in milliseconds before first retry.
+        max_delay_ms: Maximum delay in milliseconds (caps exponential growth).
+
+    Example:
+        >>> policy = ModelRetryPolicy(
+        ...     max_retries=5,
+        ...     backoff_strategy="exponential",
+        ...     base_delay_ms=100,
+        ...     max_delay_ms=10000,
+        ... )
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    max_retries: int = Field(
+        default=3,
+        ge=0,
+        le=10,
+        description="Maximum number of retry attempts (0-10). "
+        "0 means no retries; operation fails immediately on first error.",
+    )
+
+    backoff_strategy: Literal["fixed", "exponential"] = Field(
+        default="exponential",
+        description="Backoff strategy: 'fixed' uses constant delay, "
+        "'exponential' doubles delay on each retry.",
+    )
+
+    base_delay_ms: int = Field(
+        default=100,
+        ge=10,
+        le=60000,
+        description="Base delay in milliseconds before first retry (10-60000). "
+        "For exponential backoff, subsequent delays are base_delay * 2^attempt.",
+    )
+
+    max_delay_ms: int = Field(
+        default=5000,
+        ge=100,
+        le=300000,
+        description="Maximum delay in milliseconds between retries (100-300000). "
+        "Caps exponential backoff growth to prevent excessive waits.",
+    )
+
+    @field_validator("max_delay_ms")
+    @classmethod
+    def validate_max_delay_greater_than_base(cls, v: int, info: ValidationInfo) -> int:
+        """Ensure max_delay_ms is at least as large as base_delay_ms.
+
+        Args:
+            v: The max_delay_ms value to validate.
+            info: Pydantic validation info containing other field values.
+
+        Returns:
+            The validated max_delay_ms value.
+
+        Raises:
+            ValueError: If max_delay_ms is less than base_delay_ms.
+        """
+        # Access data from validation info
+        data = info.data if info.data else {}
+        base_delay = data.get("base_delay_ms", 100)
+        if v < base_delay:
+            raise ValueError(
+                f"max_delay_ms ({v}) must be >= base_delay_ms ({base_delay})"
+            )
+        return v
+
+
+__all__: list[str] = [
+    "ModelRetryPolicy",
+]