omnibase_infra 0.2.6__py3-none-any.whl

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_notification_config.py

@@ -0,0 +1,171 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Projector Notification Configuration Model.
+
+Defines configuration for state transition notification publishing from projectors.
+When configured, the projector will publish notifications to the event bus after
+successful state transitions are committed.
+
+This enables the Observer pattern for orchestrator coordination without tight
+coupling between reducers and workflow coordinators.
+
+Architecture Overview:
+    1. ProjectorShell processes events and persists state changes
+    2. Before commit, the previous state is fetched (if state tracking enabled)
+    3. After successful commit, a notification is published with from_state/to_state
+    4. Orchestrators subscribe to notifications and coordinate downstream workflows
+
+Configuration Fields:
+    - expected_topic: Expected event bus topic for validation/documentation (required).
+        NOTE: The actual publishing topic is determined by TransitionNotificationPublisher.
+        This field accepts "topic" as an alias for backwards compatibility.
+    - state_column: Column name containing the FSM state (required)
+    - aggregate_id_column: Column name containing the aggregate ID (required)
+    - version_column: Column name containing the projection version (optional)
+    - enabled: Whether notifications are enabled (default: True)
+
+Example Usage:
+    >>> from omnibase_infra.runtime.models import ModelProjectorNotificationConfig
+    >>>
+    >>> # Using the preferred field name
+    >>> config = ModelProjectorNotificationConfig(
+    ...     expected_topic="onex.fsm.state.transitions.v1",
+    ...     state_column="current_state",
+    ...     aggregate_id_column="entity_id",
+    ...     version_column="version",
+    ...     enabled=True,
+    ... )
+    >>>
+    >>> # Using the backwards-compatible alias
+    >>> config = ModelProjectorNotificationConfig(
+    ...     topic="onex.fsm.state.transitions.v1",  # alias for expected_topic
+    ...     state_column="current_state",
+    ...     aggregate_id_column="entity_id",
+    ... )
+
+Related Tickets:
+    - OMN-1139: Implement TransitionNotificationPublisher integration with ProjectorShell
+
+Thread Safety:
+    This model is immutable (frozen=True) after creation, making it thread-safe
+    for concurrent read access.
+
+.. versionadded:: 0.8.0
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelProjectorNotificationConfig(BaseModel):
+    """Configuration for state transition notification publishing.
+
+    When attached to a ProjectorShell via the notification_config parameter,
+    enables automatic publishing of state transition notifications after
+    successful projection commits.
+
+    Attributes:
+        expected_topic: Expected event bus topic for state transition notifications.
+            This field is for documentation and validation purposes only - the actual
+            publishing topic is determined by TransitionNotificationPublisher's
+            configuration. ProjectorShell will log a warning if this value differs
+            from the publisher's configured topic. Example topics:
+            - "onex.fsm.state.transitions.v1"
+            - "registration.state.transitions.v1"
+            Accepts "topic" as an alias for backwards compatibility.
+        state_column: Name of the column that contains the FSM state value.
+            This column must exist in the projection schema and contain string
+            values representing the current state.
+        aggregate_id_column: Name of the column that contains the aggregate ID.
+            This column must exist in the projection schema and typically contains
+            a UUID identifying the aggregate instance.
+        version_column: Optional name of the column that contains the projection
+            version. If specified, the version value will be included in
+            notifications for ordering and idempotency detection.
+        enabled: Whether notification publishing is enabled. Defaults to True.
+            Set to False to disable notifications without removing configuration.
+
+    Example:
+        >>> config = ModelProjectorNotificationConfig(
+        ...     expected_topic="onex.fsm.state.transitions.v1",
+        ...     state_column="current_state",
+        ...     aggregate_id_column="entity_id",
+        ...     version_column="version",
+        ... )
+        >>> config.expected_topic
+        'onex.fsm.state.transitions.v1'
+        >>> config.state_column
+        'current_state'
+        >>> config.enabled
+        True
+
+    Note:
+        The column names specified must match columns defined in the projector's
+        contract schema. The ProjectorShell will validate these column names
+        against the schema at initialization time.
+
+        Important: The expected_topic field does NOT control where notifications
+        are published. The actual topic is determined by TransitionNotificationPublisher.
+        This field exists so ProjectorShell can warn when there's a mismatch between
+        the expected and actual topics, helping catch configuration errors early.
+
+    See Also:
+        - ProjectorShell: Uses this config for notification integration
+        - TransitionNotificationPublisher: Publishes the notifications
+        - ModelStateTransitionNotification: The notification payload model
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+        populate_by_name=True,  # Allow both "expected_topic" and "topic" (alias)
+    )
+
+    expected_topic: str = Field(
+        ...,
+        alias="topic",  # Backwards compatibility
+        min_length=1,
+        max_length=256,
+        pattern=r"^[a-zA-Z][a-zA-Z0-9]*([._-][a-zA-Z0-9]+)*$",
+        description=(
+            "Expected event bus topic for state transition notifications. "
+            "Must start with a letter (a-zA-Z), end with an alphanumeric character, "
+            "and contain only alphanumeric characters with single dots, underscores, "
+            "or hyphens as separators. Consecutive separators (e.g., '..', '--', '__', '.-') "
+            "and trailing separators are not allowed. "
+            "NOTE: This field is for documentation and validation purposes only. "
+            "The actual publishing topic is determined by TransitionNotificationPublisher. "
+            "ProjectorShell will warn if this value differs from the publisher's topic."
+        ),
+    )
+
+    state_column: str = Field(
+        ...,
+        min_length=1,
+        max_length=128,
+        description="Column name containing the FSM state value",
+    )
+
+    aggregate_id_column: str = Field(
+        ...,
+        min_length=1,
+        max_length=128,
+        description="Column name containing the aggregate ID",
+    )
+
+    version_column: str | None = Field(
+        default=None,
+        min_length=1,
+        max_length=128,
+        description="Optional column name containing the projection version",
+    )
+
+    enabled: bool = Field(
+        default=True,
+        description="Whether notification publishing is enabled",
+    )
+
+
+__all__: list[str] = ["ModelProjectorNotificationConfig"]

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

omnibase_infra/runtime/models/model_runtime_config.py

@@ -0,0 +1,150 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Runtime Configuration Model.
+
+This module provides the top-level Pydantic model for ONEX runtime kernel configuration.
+All fields are strongly typed to eliminate Any usage and enable proper validation.
+
+Configuration Priority (highest to lowest):
+    1. Environment variables (ONEX_* prefixed)
+    2. Contract values (runtime_config.yaml)
+    3. Model defaults (defined in Field() declarations)
+
+Currently Used by kernel.py:
+    - input_topic: Used for RuntimeHostProcess.input_topic
+    - output_topic: Used for RuntimeHostProcess.output_topic
+    - consumer_group (alias: group_id): Used for EventBusInmemory.group
+    - event_bus.environment: Used for EventBusInmemory.environment
+    - shutdown.grace_period_seconds: Used for graceful shutdown timeout
+
+Reserved for Future Use:
+    - contract_version, name, description: Metadata fields for contract versioning
+    - event_bus.type: Reserved for Kafka/other event bus implementations
+    - event_bus.max_history: Reserved for event history buffer sizing
+    - event_bus.circuit_breaker_threshold: Reserved for fault tolerance configuration
+    - protocols.enabled (alias: handlers.enabled): Reserved for dynamic protocol loading
+    - logging.level, logging.format: Reserved for contract-driven logging
+      (currently kernel.py uses ONEX_LOG_LEVEL env var directly)
+
+Environment Variable Overrides:
+    ONEX_INPUT_TOPIC  - Overrides input_topic
+    ONEX_OUTPUT_TOPIC - Overrides output_topic
+    ONEX_GROUP_ID     - Overrides group_id/consumer_group
+    ONEX_ENVIRONMENT  - Overrides event_bus.environment
+    ONEX_LOG_LEVEL    - Used directly by kernel (not via this model)
+
+Example:
+    >>> config = ModelRuntimeConfig(
+    ...     input_topic="requests",
+    ...     output_topic="responses",
+    ...     consumer_group="onex-runtime",
+    ... )
+    >>> print(config.event_bus.type)
+    'inmemory'
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.runtime.models.model_enabled_protocols_config import (
+    ModelEnabledProtocolsConfig,
+)
+from omnibase_infra.runtime.models.model_event_bus_config import ModelEventBusConfig
+from omnibase_infra.runtime.models.model_logging_config import ModelLoggingConfig
+from omnibase_infra.runtime.models.model_shutdown_config import ModelShutdownConfig
+
+
+class ModelRuntimeConfig(BaseModel):
+    """Runtime configuration model.
+
+    Top-level configuration model for the ONEX runtime kernel.
+    Aggregates all sub-configurations with proper typing and defaults.
+
+    Attributes:
+        contract_version: Version of the configuration contract [RESERVED]
+        name: Configuration name identifier [RESERVED]
+        description: Human-readable description [RESERVED]
+        input_topic: Topic for incoming messages [ACTIVE]
+        output_topic: Topic for outgoing messages [ACTIVE]
+        consumer_group: Consumer group identifier for message consumption [ACTIVE]
+        event_bus: Event bus configuration [PARTIAL - only environment field used]
+        protocols: Enabled protocols configuration [RESERVED]
+        logging: Logging configuration [RESERVED]
+        shutdown: Shutdown configuration [ACTIVE - grace_period_seconds used]
+
+    Field Status Legend:
+        [ACTIVE]   - Currently used by kernel.py
+        [PARTIAL]  - Some nested fields used, others reserved
+        [RESERVED] - Defined for forward compatibility, not yet used
+
+    Example:
+        >>> from pathlib import Path
+        >>> import yaml
+        >>> with Path("contracts/runtime/runtime_config.yaml").open(encoding="utf-8") as f:
+        ...     data = yaml.safe_load(f)
+        >>> config = ModelRuntimeConfig.model_validate(data)
+        >>> print(config.input_topic)
+        'requests'
+    """
+
+    model_config = ConfigDict(
+        strict=True,
+        frozen=True,
+        extra="ignore",  # Allow extra fields for forward compatibility
+        populate_by_name=True,  # Allow both alias and field name for population
+        from_attributes=True,  # Support pytest-xdist compatibility
+    )
+
+    # Contract metadata (optional, may not be present in minimal configs)
+    contract_version: str | None = Field(
+        default=None,
+        description="Version of the configuration contract",
+    )
+    name: str | None = Field(
+        default=None,
+        description="Configuration name identifier",
+    )
+    description: str | None = Field(
+        default=None,
+        description="Human-readable description",
+    )
+
+    # Topic configuration
+    input_topic: str = Field(
+        default="requests",
+        description="Topic for incoming messages",
+    )
+    output_topic: str = Field(
+        default="responses",
+        description="Topic for outgoing messages",
+    )
+    # Note: Using consumer_group instead of group_id to avoid ONEX pattern validator
+    # false positive (group_id triggers UUID check, but this is a string identifier)
+    consumer_group: str = Field(
+        default="onex-runtime",
+        alias="group_id",
+        description="Consumer group identifier for message consumption",
+    )
+
+    # Nested configurations
+    event_bus: ModelEventBusConfig = Field(
+        default_factory=ModelEventBusConfig,
+        description="Event bus configuration",
+    )
+    protocols: ModelEnabledProtocolsConfig = Field(
+        default_factory=ModelEnabledProtocolsConfig,
+        alias="handlers",
+        description="Enabled protocols configuration",
+    )
+    logging: ModelLoggingConfig = Field(
+        default_factory=ModelLoggingConfig,
+        description="Logging configuration",
+    )
+    shutdown: ModelShutdownConfig = Field(
+        default_factory=ModelShutdownConfig,
+        description="Shutdown configuration",
+    )
+
+
+__all__: list[str] = ["ModelRuntimeConfig"]