omnibase_infra 0.2.1__py3-none-any.whl

omnibase_infra/runtime/models/model_logging_config.py

@@ -0,0 +1,42 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Logging Configuration Model.
+
+This module provides the Pydantic model for logging configuration.
+"""
+
+from __future__ import annotations
+
+from typing import Literal
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelLoggingConfig(BaseModel):
+    """Logging configuration model.
+
+    Defines logging level and format for the runtime.
+
+    Attributes:
+        level: Logging level (DEBUG, INFO, WARNING, ERROR, CRITICAL)
+        format: Log message format string
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,  # Support pytest-xdist compatibility
+    )
+
+    level: Literal["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"] = Field(
+        default="INFO",
+        description="Logging level",
+    )
+    format: str = Field(
+        default="%(asctime)s [%(levelname)s] %(name)s: %(message)s",
+        description="Log message format string",
+    )
+
+
+__all__: list[str] = ["ModelLoggingConfig"]

omnibase_infra/runtime/models/model_optional_correlation_id.py

@@ -0,0 +1,167 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Model for optional correlation ID values in runtime module.
+
+This module provides a strongly-typed Pydantic model for optional
+correlation ID values (UUIDs), replacing `UUID | None` union types
+to comply with ONEX standards.
+
+Correlation IDs are used throughout the runtime for request tracing,
+logging, and distributed system observability.
+
+Design Decision (PR #47 Review):
+    This model intentionally duplicates patterns from ModelOptionalUUID rather than
+    using inheritance or generics. This design choice provides:
+
+    1. **Self-contained model**: No dependencies on base classes or mixins
+    2. **Correlation-specific methods**: `get_or_generate()` is specific to correlation IDs
+    3. **ONEX compliance**: Follows "composition over inheritance" principle
+    4. **Future-ready**: Available for strongly-typed correlation ID handling
+       in RuntimeHostProcess and event envelope processing
+
+    While currently not actively used, this model is pre-built for consistent
+    correlation ID handling as the codebase evolves. The trade-off of code
+    duplication vs. generic abstractions was intentionally chosen for clarity
+    and type safety.
+
+    See Also:
+        - ModelOptionalUUID: Similar pattern for generic optional UUIDs
+        - docs/patterns/correlation_id_tracking.md: Correlation ID best practices
+"""
+
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelOptionalCorrelationId(BaseModel):
+    """Strongly-typed model for optional correlation ID values.
+
+    Replaces `UUID | None` for correlation IDs to comply with ONEX
+    standards requiring specific typed models instead of generic union types.
+
+    This specialized wrapper is designed for correlation ID use cases,
+    providing factory methods to generate new UUIDs when needed and
+    ensuring consistent handling across the runtime module.
+
+    Attributes:
+        value: The optional correlation ID (UUID), defaults to None.
+
+    Example:
+        >>> corr = ModelOptionalCorrelationId.generate()
+        >>> corr.has_value()
+        True
+        >>> empty = ModelOptionalCorrelationId()
+        >>> filled = empty.get_or_generate()
+        >>> filled.has_value()
+        True
+    """
+
+    model_config = ConfigDict(frozen=True, from_attributes=True, extra="forbid")
+
+    value: UUID | None = Field(
+        default=None, description="Optional correlation ID (UUID)"
+    )
+
+    @classmethod
+    def generate(cls) -> "ModelOptionalCorrelationId":
+        """Create a new correlation ID with a generated UUID.
+
+        Factory method that creates a ModelOptionalCorrelationId with
+        a newly generated UUID4 value.
+
+        Returns:
+            A new ModelOptionalCorrelationId with a generated UUID.
+        """
+        return cls(value=uuid4())
+
+    @classmethod
+    def from_uuid(cls, value: UUID) -> "ModelOptionalCorrelationId":
+        """Create a correlation ID from an existing UUID.
+
+        Args:
+            value: An existing UUID to wrap.
+
+        Returns:
+            A new ModelOptionalCorrelationId with the given UUID.
+        """
+        return cls(value=value)
+
+    @classmethod
+    def none(cls) -> "ModelOptionalCorrelationId":
+        """Create an empty correlation ID.
+
+        Returns:
+            A new ModelOptionalCorrelationId with no value.
+        """
+        return cls()
+
+    def get(self) -> UUID | None:
+        """Get the optional correlation ID.
+
+        Returns:
+            The UUID value if present, None otherwise.
+        """
+        return self.value
+
+    def has_value(self) -> bool:
+        """Check if correlation ID 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 correlation ID 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 get_or_generate(self) -> "ModelOptionalCorrelationId":
+        """Get this correlation ID or generate a new one if None.
+
+        Returns a new ModelOptionalCorrelationId with either:
+        - The existing UUID if present
+        - A newly generated UUID if None
+
+        Returns:
+            A ModelOptionalCorrelationId that always has a value.
+        """
+        if self.value is not None:
+            return self
+        return ModelOptionalCorrelationId.generate()
+
+    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 correlation ID 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 corr_id:
+                    # Correlation ID is present - propagate it
+                    context.set_correlation_id(corr_id.value)
+                else:
+                    # No correlation ID - generate new one
+                    corr_id = corr_id.get_or_generate()
+
+            Use ``corr_id.has_value()`` for explicit, self-documenting code.
+            Use ``corr_id is not None`` if you need to check model existence.
+
+        Returns:
+            True if correlation ID is present, False otherwise.
+        """
+        return self.has_value()
+
+
+__all__ = ["ModelOptionalCorrelationId"]

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],
+        )