omnibase_infra 0.2.6__py3-none-any.whl

omnibase_infra/runtime/models/model_optional_string.py

@@ -0,0 +1,94 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Model for optional string values in runtime module.
+
+This module provides a strongly-typed Pydantic model for optional string
+values, replacing `str | None` union types to comply with ONEX standards.
+"""
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelOptionalString(BaseModel):
+    """Strongly-typed model for optional string values.
+
+    Replaces `str | None` to comply with ONEX standards requiring specific
+    typed models instead of generic union types.
+
+    This wrapper provides a consistent API for working with optional strings,
+    including presence checking, default value handling, and functional
+    transformation methods.
+
+    Attributes:
+        value: The optional string value, defaults to None.
+
+    Example:
+        >>> opt = ModelOptionalString(value="hello")
+        >>> opt.has_value()
+        True
+        >>> opt.get_or_default("default")
+        'hello'
+        >>> empty = ModelOptionalString()
+        >>> empty.get_or_default("default")
+        'default'
+    """
+
+    model_config = ConfigDict(frozen=True, from_attributes=True, extra="forbid")
+
+    value: str | None = Field(default=None, description="Optional string value")
+
+    def get(self) -> str | None:
+        """Get the optional value.
+
+        Returns:
+            The string value if present, None otherwise.
+        """
+        return self.value
+
+    def has_value(self) -> bool:
+        """Check if value is present.
+
+        Returns:
+            True if value is not None, False otherwise.
+        """
+        return self.value is not None
+
+    def get_or_default(self, default: str) -> str:
+        """Get value or return default if None.
+
+        Args:
+            default: The default value to return if None.
+
+        Returns:
+            The stored value if present, otherwise the default.
+        """
+        return self.value if self.value is not None else default
+
+    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 value is present. This differs from typical
+            Pydantic model behavior where ``bool(model)`` always returns ``True`` for
+            any valid model instance.
+
+            This design enables idiomatic presence checks::
+
+                if opt_string:
+                    # Value is present - use it
+                    process(opt_string.value)
+                else:
+                    # No value - use fallback
+                    use_default()
+
+            Use ``opt_string.has_value()`` for explicit, self-documenting code.
+            Use ``opt_string is not None`` if you need to check model existence.
+
+        Returns:
+            True if value is present, False otherwise.
+        """
+        return self.has_value()
+
+
+__all__ = ["ModelOptionalString"]

omnibase_infra/runtime/models/model_optional_uuid.py

@@ -0,0 +1,110 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Model for optional UUID values in runtime module.
+
+This module provides a strongly-typed Pydantic model for optional UUID
+values, replacing `UUID | None` union types to comply with ONEX standards.
+
+Design Note - Code Duplication:
+    The optional wrapper models (ModelOptionalUUID, ModelOptionalString,
+    ModelOptionalCorrelationId) contain similar methods (get(), has_value(),
+    get_or_default(), __bool__()). This duplication is intentional to comply
+    with ONEX principles:
+
+    1. Each model is self-contained and independently testable
+    2. No inheritance or mixin dependencies (composition over inheritance)
+    3. Explicit behavior for each type without generic base classes
+    4. Each model can evolve independently without breaking others
+    5. Clear type signatures without generic type parameters
+
+    While this creates some duplication, it provides stronger type safety,
+    better testability, and clearer semantics for each optional type.
+"""
+
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelOptionalUUID(BaseModel):
+    """Strongly-typed model for optional UUID values.
+
+    Replaces `UUID | None` to comply with ONEX standards requiring specific
+    typed models instead of generic union types.
+
+    This wrapper provides a consistent API for working with optional UUIDs,
+    including presence checking, default value handling, and functional
+    transformation methods.
+
+    Attributes:
+        value: The optional UUID value, defaults to None.
+
+    Example:
+        >>> from uuid import UUID
+        >>> opt = ModelOptionalUUID(value=UUID("12345678-1234-5678-1234-567812345678"))
+        >>> opt.has_value()
+        True
+        >>> empty = ModelOptionalUUID()
+        >>> empty.has_value()
+        False
+    """
+
+    model_config = ConfigDict(frozen=True, from_attributes=True, extra="forbid")
+
+    value: UUID | None = Field(default=None, description="Optional UUID value")
+
+    def get(self) -> UUID | None:
+        """Get the optional value.
+
+        Returns:
+            The UUID value if present, None otherwise.
+        """
+        return self.value
+
+    def has_value(self) -> bool:
+        """Check if value is present.
+
+        Returns:
+            True if value is not None, False otherwise.
+        """
+        return self.value is not None
+
+    def get_or_default(self, default: UUID) -> UUID:
+        """Get value or return default if None.
+
+        Args:
+            default: The default UUID to return if None.
+
+        Returns:
+            The stored value if present, otherwise the default.
+        """
+        return self.value if self.value is not None else default
+
+    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 value is present. This differs from typical
+            Pydantic model behavior where ``bool(model)`` always returns ``True`` for
+            any valid model instance.
+
+            This design enables idiomatic presence checks::
+
+                if opt_uuid:
+                    # Value is present - use it
+                    process(opt_uuid.value)
+                else:
+                    # No value - use fallback
+                    use_default()
+
+            Use ``opt_uuid.has_value()`` for explicit, self-documenting code.
+            Use ``opt_uuid is not None`` if you need to check model existence.
+
+        Returns:
+            True if value is present, False otherwise.
+        """
+        return self.has_value()
+
+
+__all__ = ["ModelOptionalUUID"]

omnibase_infra/runtime/models/model_policy_context.py

@@ -0,0 +1,100 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Pydantic model for policy evaluation context.
+
+This module provides the ModelPolicyContext Pydantic BaseModel for passing
+structured context to 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 usage in ProtocolPolicy.evaluate()
+and ProtocolPolicy.decide() method signatures, providing type safety while
+maintaining flexibility for diverse policy contexts.
+"""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.mixins import MixinDictLikeAccessors
+
+
+class ModelPolicyContext(MixinDictLikeAccessors, BaseModel):
+    """Base Pydantic model for policy evaluation context.
+
+    This model provides structured context for policy evaluation including
+    correlation IDs, attempt counts, and policy-specific parameters.
+
+    Common Fields:
+        correlation_id: UUID for distributed tracing
+        attempt: Current retry/evaluation attempt number
+        timestamp_ms: Evaluation timestamp in milliseconds
+        metadata: Additional metadata for observability
+
+    Configuration:
+        - extra="allow": Accepts arbitrary additional fields for policy-specific data
+        - frozen=False: Allows mutation (though policies should not mutate context)
+        - populate_by_name=True: Allows field access by alias
+
+    Example:
+        ```python
+        from uuid import uuid4
+
+        # Create with known fields
+        context = ModelPolicyContext(
+            correlation_id=uuid4(),
+            attempt=3,
+            base_delay_seconds=1.0,
+            max_delay_seconds=60.0,
+        )
+
+        # Access with get (dict-like API)
+        attempt = context.get("attempt", 0)
+
+        # Access as attribute
+        corr_id = context.correlation_id
+
+        # Create from dict
+        context = ModelPolicyContext.model_validate({"attempt": 3, "error_type": "timeout"})
+        ```
+
+    Policy-Specific Fields:
+        For orchestrator policies:
+            - attempt: Current retry attempt number
+            - error_type: Type of error that triggered evaluation
+            - elapsed_ms: Time elapsed since operation started
+            - base_delay_seconds: Base delay for backoff calculations
+            - max_delay_seconds: Maximum delay cap
+
+        For reducer policies:
+            - current_state: Current aggregated state
+            - event: Event to process
+            - timestamp: Event timestamp
+            - sequence_number: Event sequence for ordering
+
+    Note:
+        All fields are optional due to extra="allow". Specific policies should
+        document which context fields they require for proper evaluation.
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        frozen=False,
+        populate_by_name=True,
+        from_attributes=True,
+    )
+
+    # Common context fields - all optional with defaults
+    correlation_id: UUID | None = None
+    attempt: int = 0
+    timestamp_ms: int = 0
+    metadata: dict[str, object] = Field(default_factory=dict)
+
+
+__all__: list[str] = ["ModelPolicyContext"]

omnibase_infra/runtime/models/model_policy_key.py

@@ -0,0 +1,138 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""ModelPolicyKey - Strongly-typed PolicyRegistry key.
+
+Defines ModelPolicyKey for PolicyRegistry dict operations.
+Replaces primitive tuple[str, str, str] pattern with named fields.
+"""
+
+from __future__ import annotations
+
+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.
+
+
+class ModelPolicyKey(BaseModel):
+    """Strongly-typed policy registry key.
+
+    Replaces tuple[str, str, str] pattern with named fields,
+    validation, and self-documenting structure.
+
+    Attributes:
+        policy_id: Unique identifier for the policy (e.g., 'exponential_backoff')
+        policy_type: Policy category (EnumPolicyType or 'orchestrator'/'reducer' string)
+        version: Semantic version string (e.g., '1.0.0')
+
+    Example:
+        >>> from omnibase_infra.enums import EnumPolicyType
+        >>> key = ModelPolicyKey(
+        ...     policy_id="retry_backoff",
+        ...     policy_type=EnumPolicyType.ORCHESTRATOR,
+        ...     version="1.0.0"
+        ... )
+        >>> print(key.policy_id)
+        retry_backoff
+        >>> # Also accepts string policy_type
+        >>> key2 = ModelPolicyKey(
+        ...     policy_id="state_merger",
+        ...     policy_type="reducer",
+        ...     version="1.0.0"
+        ... )
+    """
+
+    policy_id: str = Field(..., description="Unique policy identifier")
+    # 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")
+
+    model_config = ConfigDict(
+        frozen=True,  # Make hashable for dict keys
+        from_attributes=True,
+        str_strip_whitespace=True,
+        extra="forbid",
+    )
+
+    @field_validator("version", mode="before")
+    @classmethod
+    def validate_and_normalize_version(cls, v: str) -> str:
+        """Normalize version string for consistent lookups.
+
+        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 consistent
+        version handling across all ONEX components, preventing lookup mismatches
+        where "1.0.0" and "1.0" might be treated as different versions.
+
+        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
+
+        Examples:
+            >>> ModelPolicyKey(policy_id="test", policy_type="orchestrator", version="1.0")
+            ModelPolicyKey(policy_id='test', policy_type='orchestrator', version='1.0.0')
+            >>> ModelPolicyKey(policy_id="test", policy_type="orchestrator", version="v2.1")
+            ModelPolicyKey(policy_id='test', policy_type='orchestrator', version='2.1.0')
+        """
+        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)
+
+    def to_tuple(self) -> tuple[str, str, str]:
+        """Convert to tuple representation.
+
+        Returns:
+            Tuple of (policy_id, policy_type, version)
+        """
+        # policy_type is always EnumPolicyType after validation coercion
+        return (self.policy_id, self.policy_type.value, self.version)
+
+    @classmethod
+    def from_tuple(cls, key_tuple: tuple[str, str, str]) -> ModelPolicyKey:
+        """Create from tuple representation.
+
+        Args:
+            key_tuple: Tuple of (policy_id, policy_type, version)
+
+        Returns:
+            ModelPolicyKey instance
+        """
+        return cls(
+            policy_id=key_tuple[0],
+            policy_type=key_tuple[1],
+            version=key_tuple[2],
+        )

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"]