omnibase_infra 0.2.2__py3-none-any.whl → 0.2.3__py3-none-any.whl

omnibase_infra/enums/__init__.py

@@ -23,11 +23,13 @@ Exports:
     EnumHandlerErrorType: Handler error types for validation and lifecycle
     EnumHandlerLoaderError: Handler loader error codes for plugin loading
     EnumResponseStatus: Handler response status (SUCCESS, ERROR)
+    EnumHandlerSourceMode: Handler source modes for loading strategy (BOOTSTRAP, CONTRACT, HYBRID)
     EnumHandlerSourceType: Handler validation error source types
     EnumHandlerType: Handler architectural roles (INFRA_HANDLER, NODE_HANDLER)
     EnumHandlerTypeCategory: Behavioral classification (COMPUTE, EFFECT)
     EnumInfraTransportType: Infrastructure transport type enumeration
     EnumIntrospectionReason: Introspection event reasons (STARTUP, SHUTDOWN, etc.)
+    EnumKafkaAcks: Kafka producer acknowledgment policy (ALL, NONE, LEADER, ALL_REPLICAS)
     EnumMessageCategory: Message categories (EVENT, COMMAND, INTENT)
     EnumNodeArchetype: 4-node architecture (EFFECT, COMPUTE, REDUCER, ORCHESTRATOR)
     EnumNodeOutputType: Node output types for execution shape validation
@@ -61,11 +63,13 @@ from omnibase_infra.enums.enum_execution_shape_violation import (
 )
 from omnibase_infra.enums.enum_handler_error_type import EnumHandlerErrorType
 from omnibase_infra.enums.enum_handler_loader_error import EnumHandlerLoaderError
+from omnibase_infra.enums.enum_handler_source_mode import EnumHandlerSourceMode
 from omnibase_infra.enums.enum_handler_source_type import EnumHandlerSourceType
 from omnibase_infra.enums.enum_handler_type import EnumHandlerType
 from omnibase_infra.enums.enum_handler_type_category import EnumHandlerTypeCategory
 from omnibase_infra.enums.enum_infra_transport_type import EnumInfraTransportType
 from omnibase_infra.enums.enum_introspection_reason import EnumIntrospectionReason
+from omnibase_infra.enums.enum_kafka_acks import EnumKafkaAcks
 from omnibase_infra.enums.enum_message_category import EnumMessageCategory
 from omnibase_infra.enums.enum_node_archetype import EnumNodeArchetype
 from omnibase_infra.enums.enum_node_output_type import EnumNodeOutputType
@@ -100,11 +104,13 @@ __all__: list[str] = [
     "EnumExecutionShapeViolation",
     "EnumHandlerErrorType",
     "EnumHandlerLoaderError",
+    "EnumHandlerSourceMode",
     "EnumHandlerSourceType",
     "EnumHandlerType",
     "EnumHandlerTypeCategory",
     "EnumInfraTransportType",
     "EnumIntrospectionReason",
+    "EnumKafkaAcks",
     "EnumMessageCategory",
     "EnumNodeArchetype",
     "EnumNodeOutputType",

omnibase_infra/enums/enum_handler_error_type.py

@@ -43,6 +43,13 @@ class EnumHandlerErrorType(str, Enum):
             The parsed contract contains invalid field values or violates
             schema constraints defined in the ONEX contract specification.
 
+    Discovery Errors:
+        DISCOVERY_ERROR: Handler discovery failed due to infrastructure issues.
+            The handler could not be discovered due to connection failures,
+            timeouts, or other infrastructure problems (e.g., Consul unavailable,
+            network errors). This is distinct from parse/validation errors which
+            occur AFTER the contract is successfully retrieved.
+
     Validation Errors:
         DESCRIPTOR_VALIDATION_ERROR: Handler descriptor validation failed.
             The handler descriptor (metadata, annotations, signature) does not
@@ -80,6 +87,9 @@ class EnumHandlerErrorType(str, Enum):
     CONTRACT_PARSE_ERROR = "contract_parse_error"
     CONTRACT_VALIDATION_ERROR = "contract_validation_error"
 
+    # Discovery errors
+    DISCOVERY_ERROR = "discovery_error"
+
     # Validation errors
     DESCRIPTOR_VALIDATION_ERROR = "descriptor_validation_error"
     SECURITY_VALIDATION_ERROR = "security_validation_error"

omnibase_infra/enums/enum_handler_source_mode.py

@@ -0,0 +1,72 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Handler Source Mode Enumeration for Handler Loading Strategy.
+
+Defines the canonical source modes for handler loading in the ONEX runtime.
+Each mode determines where handlers are discovered and loaded from, enabling
+flexible deployment configurations and migration strategies.
+
+Handler loading can operate in three modes:
+    - BOOTSTRAP: Only use hardcoded bootstrap handlers.
+                 Uses the legacy hardcoded handler registry. No YAML contract
+                 discovery. Useful for minimal deployments or testing.
+    - CONTRACT: Only use YAML contract-discovered handlers.
+                All handlers must be defined in contract.yaml files. No
+                hardcoded handlers are loaded. Enables fully declarative
+                handler configuration.
+    - HYBRID: Per-handler resolution with contract precedence.
+              When a handler identity matches both bootstrap and contract,
+              the contract-defined handler wins. Bootstrap handlers serve
+              as fallback for handlers not defined in contracts.
+
+The HYBRID mode supports gradual migration from hardcoded to contract-based
+handlers by allowing both sources to coexist with deterministic resolution.
+
+See Also:
+    - EnumHandlerSourceType: Defines validation error source types (different purpose)
+    - HandlerPluginLoader: Uses this enum to determine loading strategy
+    - ModelRuntimeConfig: Configuration model that holds the source mode setting
+"""
+
+from enum import Enum
+
+
+class EnumHandlerSourceMode(str, Enum):
+    """Handler source modes for handler loading strategy selection.
+
+    These represent the different strategies for discovering and loading
+    handlers at runtime. The mode determines whether handlers come from
+    hardcoded registries, YAML contracts, or a combination of both.
+
+    Attributes:
+        BOOTSTRAP: Only use hardcoded bootstrap handlers.
+            The runtime loads handlers from the legacy hardcoded registry only.
+            No YAML contract discovery is performed. Use cases:
+            - Minimal deployments without contract infrastructure
+            - Testing with known handler set
+            - Backwards compatibility during migration
+            - Environments where contract files are not available
+        CONTRACT: Only use YAML contract-discovered handlers.
+            All handlers must be defined in contract.yaml files. The hardcoded
+            bootstrap registry is ignored. Use cases:
+            - Fully declarative handler configuration
+            - Dynamic handler deployment via contracts
+            - Environments requiring audit trail of handler changes
+            - Production deployments with contract validation
+        HYBRID: Per-handler resolution with contract precedence.
+            Both bootstrap and contract sources are used. When a handler
+            identity (module + class) matches in both sources, the contract-
+            defined handler takes precedence. Bootstrap handlers serve as
+            fallback for handlers not defined in contracts. Use cases:
+            - Gradual migration from bootstrap to contract
+            - Core handlers in bootstrap, extensions in contracts
+            - Development environments with mixed configurations
+            - A/B testing of handler implementations
+    """
+
+    BOOTSTRAP = "bootstrap"
+    CONTRACT = "contract"
+    HYBRID = "hybrid"
+
+
+__all__ = ["EnumHandlerSourceMode"]

omnibase_infra/enums/enum_kafka_acks.py

@@ -0,0 +1,99 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Kafka producer acknowledgment configuration enumeration.
+
+This module defines the acknowledgment policy enumeration for Kafka producers,
+with a conversion method to produce aiokafka-compatible types.
+
+The `acks` configuration controls how many partition replicas must acknowledge
+receipt before the producer considers a request complete:
+    - ALL ("all"): Wait for all in-sync replicas to acknowledge (most durable)
+    - LEADER ("1"): Wait only for the leader to acknowledge (balanced)
+    - NONE ("0"): Don't wait for any acknowledgment (fastest, least durable)
+    - ALL_REPLICAS ("-1"): Explicit numeric form of ALL (equivalent to "all")
+
+See Also:
+    - EventBusKafka: Uses this enum for producer configuration
+    - ModelKafkaEventBusConfig: Config model that stores the acks setting
+    - https://kafka.apache.org/documentation/#producerconfigs_acks
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+# Explicit mapping for aiokafka type conversion.
+# Defined at module level because str-based enums don't support ClassVar attributes
+# (attribute lookup on str enum members uses string indexing, not class attribute lookup).
+_AIOKAFKA_MAP: dict[str, int | str] = {
+    "all": "all",
+    "0": 0,
+    "1": 1,
+    "-1": -1,
+}
+
+
+class EnumKafkaAcks(str, Enum):
+    """Kafka producer acknowledgment policy.
+
+    Defines the acknowledgment behavior for Kafka producers. The aiokafka
+    library expects specific types for the `acks` parameter:
+    - "all" must be passed as a string
+    - Numeric values (0, 1, -1) must be passed as integers
+
+    Use the `to_aiokafka()` method to get the correctly-typed value for
+    passing to AIOKafkaProducer.
+
+    Attributes:
+        ALL: Wait for all in-sync replicas (string "all")
+        NONE: Fire and forget, no acknowledgment (string "0" -> int 0)
+        LEADER: Wait for leader acknowledgment only (string "1" -> int 1)
+        ALL_REPLICAS: Explicit numeric form of ALL (string "-1" -> int -1)
+
+    Note:
+        ALL ("all") and ALL_REPLICAS (-1) are semantically equivalent in Kafka.
+        ALL_REPLICAS is provided for explicit numeric configuration compatibility
+        when migrating from systems that use the numeric form.
+
+    Example:
+        >>> acks = EnumKafkaAcks.ALL
+        >>> acks.to_aiokafka()
+        'all'
+        >>> acks = EnumKafkaAcks.LEADER
+        >>> acks.to_aiokafka()
+        1
+    """
+
+    ALL = "all"
+    NONE = "0"
+    LEADER = "1"
+    ALL_REPLICAS = "-1"
+
+    def to_aiokafka(self) -> int | str:
+        """Convert to aiokafka-compatible type.
+
+        aiokafka's AIOKafkaProducer expects:
+        - The string "all" for all-replica acknowledgment
+        - Integer values (0, 1, -1) for numeric ack levels
+
+        Returns:
+            The acks value in the format expected by aiokafka:
+            - "all" (str) for ALL
+            - 0 (int) for NONE
+            - 1 (int) for LEADER
+            - -1 (int) for ALL_REPLICAS
+
+        Example:
+            >>> EnumKafkaAcks.ALL.to_aiokafka()
+            'all'
+            >>> EnumKafkaAcks.NONE.to_aiokafka()
+            0
+            >>> EnumKafkaAcks.LEADER.to_aiokafka()
+            1
+            >>> EnumKafkaAcks.ALL_REPLICAS.to_aiokafka()
+            -1
+        """
+        return _AIOKAFKA_MAP[self.value]
+
+
+__all__: list[str] = ["EnumKafkaAcks"]

omnibase_infra/event_bus/event_bus_kafka.py

@@ -491,7 +491,7 @@ class EventBusKafka(MixinKafkaBroadcast, MixinKafkaDlq, MixinAsyncCircuitBreaker
                 # Apply producer configuration from config model
                 self._producer = AIOKafkaProducer(
                     bootstrap_servers=self._bootstrap_servers,
-                    acks=self._config.acks,
+                    acks=self._config.acks_aiokafka,
                     enable_idempotence=self._config.enable_idempotence,
                 )
 

omnibase_infra/event_bus/models/config/model_kafka_event_bus_config.py

@@ -106,9 +106,9 @@ from pathlib import Path
 from uuid import uuid4
 
 import yaml
-from pydantic import BaseModel, ConfigDict, Field, field_validator
+from pydantic import BaseModel, ConfigDict, Field, computed_field, field_validator
 
-from omnibase_infra.enums import EnumInfraTransportType
+from omnibase_infra.enums import EnumInfraTransportType, EnumKafkaAcks
 from omnibase_infra.errors import ModelInfraErrorContext, ProtocolConfigurationError
 
 logger = logging.getLogger(__name__)
@@ -131,7 +131,7 @@ class ModelKafkaEventBusConfig(BaseModel):
         circuit_breaker_threshold: Number of consecutive failures before circuit opens
         circuit_breaker_reset_timeout: Seconds before circuit breaker resets to half-open
         consumer_sleep_interval: Sleep interval in seconds for consumer loop polling
-        acks: Producer acknowledgment policy ("all", "1", "0")
+        acks: Producer acknowledgment policy (EnumKafkaAcks.ALL, LEADER, NONE, ALL_REPLICAS)
         enable_idempotence: Enable producer idempotence for exactly-once semantics
         auto_offset_reset: Consumer offset reset policy ("earliest", "latest")
         enable_auto_commit: Enable auto-commit for consumer offsets
@@ -216,10 +216,9 @@ class ModelKafkaEventBusConfig(BaseModel):
     )
 
     # Kafka producer settings
-    acks: str = Field(
-        default="all",
-        description="Producer acknowledgment policy ('all', '1', '0')",
-        pattern=r"^(all|0|1)$",
+    acks: EnumKafkaAcks = Field(
+        default=EnumKafkaAcks.ALL,
+        description="Producer acknowledgment policy (ALL, LEADER, NONE, ALL_REPLICAS)",
     )
     enable_idempotence: bool = Field(
         default=True,
@@ -248,6 +247,32 @@ class ModelKafkaEventBusConfig(BaseModel):
         ),
     )
 
+    # NOTE: mypy reports "prop-decorator" error because it doesn't understand that
+    # Pydantic's @computed_field transforms the @property into a computed field.
+    # This is a known mypy/Pydantic v2 interaction - the code works correctly at runtime.
+    @computed_field  # type: ignore[prop-decorator]
+    @property
+    def acks_aiokafka(self) -> int | str:
+        """Get acks value in aiokafka-compatible format.
+
+        aiokafka's AIOKafkaProducer expects:
+        - The string "all" for all-replica acknowledgment
+        - Integer values (0, 1, -1) for numeric ack levels
+
+        Returns:
+            The acks value converted to the format expected by aiokafka:
+            - "all" (str) for EnumKafkaAcks.ALL
+            - 0 (int) for EnumKafkaAcks.NONE
+            - 1 (int) for EnumKafkaAcks.LEADER
+            - -1 (int) for EnumKafkaAcks.ALL_REPLICAS
+
+        Example:
+            >>> config = ModelKafkaEventBusConfig(acks=EnumKafkaAcks.LEADER)
+            >>> config.acks_aiokafka
+            1
+        """
+        return self.acks.to_aiokafka()
+
     @field_validator("bootstrap_servers", mode="before")
     @classmethod
     def validate_bootstrap_servers(cls, v: object) -> str:
@@ -503,10 +528,33 @@ class ModelKafkaEventBusConfig(BaseModel):
             "enable_auto_commit",
         }
 
+        # Enum fields with their valid values mapping
+        # Maps field_name -> (enum_class, value_to_enum_mapping)
+        acks_mapping = {
+            "all": EnumKafkaAcks.ALL,
+            "0": EnumKafkaAcks.NONE,
+            "1": EnumKafkaAcks.LEADER,
+            "-1": EnumKafkaAcks.ALL_REPLICAS,
+        }
+
         for env_var, field_name in env_mappings.items():
             env_value = os.environ.get(env_var)
             if env_value is not None:
-                if field_name in int_fields:
+                if field_name == "acks":
+                    # Special handling for acks enum - fail-fast on invalid values
+                    if env_value in acks_mapping:
+                        overrides[field_name] = acks_mapping[env_value]
+                    else:
+                        valid_values = ", ".join(acks_mapping.keys())
+                        raise ProtocolConfigurationError(
+                            f"Invalid value for environment variable {env_var}='{env_value}'. "
+                            f"Valid values are: {valid_values}",
+                            context=ModelInfraErrorContext.with_correlation(
+                                transport_type=EnumInfraTransportType.KAFKA,
+                                operation="apply_environment_overrides",
+                            ),
+                        )
+                elif field_name in int_fields:
                     try:
                         overrides[field_name] = int(env_value)
                     except ValueError:
@@ -557,7 +605,8 @@ class ModelKafkaEventBusConfig(BaseModel):
                     overrides[field_name] = env_value
 
         if overrides:
-            current_data = self.model_dump()
+            # Exclude computed field to avoid validation error
+            current_data = self.model_dump(exclude={"acks_aiokafka"})
             current_data.update(overrides)
             return ModelKafkaEventBusConfig(**current_data)
 
@@ -583,7 +632,7 @@ class ModelKafkaEventBusConfig(BaseModel):
             circuit_breaker_threshold=5,
             circuit_breaker_reset_timeout=30.0,
             consumer_sleep_interval=0.1,
-            acks="all",
+            acks=EnumKafkaAcks.ALL,
             enable_idempotence=True,
             auto_offset_reset="latest",
             enable_auto_commit=True,

omnibase_infra/handlers/__init__.py

@@ -18,6 +18,7 @@ Available Handlers:
 - HandlerFileSystem: Filesystem handler with path whitelisting and size limits
 - HandlerManifestPersistence: Execution manifest persistence with filesystem storage
 - HandlerGraph: Graph database handler (Memgraph/Neo4j via Bolt protocol)
+- HandlerIntent: Intent storage and query handler wrapping HandlerGraph (demo wiring)
 - HandlerQdrant: Qdrant vector database handler (MVP: create, upsert, search, delete)
 
 Response Models:
@@ -35,6 +36,10 @@ from omnibase_infra.handlers.handler_db import HandlerDb
 from omnibase_infra.handlers.handler_filesystem import HandlerFileSystem
 from omnibase_infra.handlers.handler_graph import HandlerGraph
 from omnibase_infra.handlers.handler_http import HandlerHttpRest
+from omnibase_infra.handlers.handler_intent import (  # DEMO: Temporary intent handler wiring (OMN-1515)
+    HANDLER_ID_INTENT,
+    HandlerIntent,
+)
 from omnibase_infra.handlers.handler_manifest_persistence import (
     HandlerManifestPersistence,
 )
@@ -56,15 +61,17 @@ from omnibase_infra.handlers.models.model_qdrant_handler_response import (
 )
 
 __all__: list[str] = [
+    "HANDLER_ID_INTENT",
     "HandlerConsul",
     "HandlerDb",
     "HandlerFileSystem",
     "HandlerGraph",
+    "HandlerHttpRest",
+    "HandlerIntent",
     "HandlerManifestPersistence",
     "HandlerMCP",
     "HandlerQdrant",
     "HandlerVault",
-    "HandlerHttpRest",
     "ModelConsulHandlerPayload",
     "ModelConsulHandlerResponse",
     "ModelDbDescribeResponse",

omnibase_infra/handlers/handler_consul.py

@@ -33,6 +33,7 @@ from uuid import UUID, uuid4
 
 import consul
 
+from omnibase_core.container import ModelONEXContainer
 from omnibase_core.models.dispatch import ModelHandlerOutput
 from omnibase_infra.enums import (
     EnumHandlerType,
@@ -190,13 +191,18 @@ class HandlerConsul(
         target_name=f"consul.{self._config.datacenter or 'default'}"
     """
 
-    def __init__(self) -> None:
+    def __init__(self, container: ModelONEXContainer) -> None:
         """Initialize HandlerConsul in uninitialized state.
 
+        Args:
+            container: ONEX container for dependency injection. Required for
+                consistent handler initialization pattern across all handlers.
+
         Note: Circuit breaker is initialized during initialize() call when
         configuration is available. The mixin's _init_circuit_breaker() method
         is called there with the actual config values.
         """
+        self._container = container
         self._client: consul.Consul | None = None
         self._config: ModelConsulHandlerConfig | None = None
         self._initialized: bool = False

omnibase_infra/handlers/handler_db.py

@@ -75,6 +75,7 @@ from uuid import UUID, uuid4
 
 import asyncpg
 
+from omnibase_core.container import ModelONEXContainer
 from omnibase_core.models.dispatch import ModelHandlerOutput
 from omnibase_core.types import JsonType
 from omnibase_infra.enums import (
@@ -222,8 +223,13 @@ class HandlerDb(MixinAsyncCircuitBreaker, MixinEnvelopeExtraction):
         - HALF_OPEN: Testing recovery after reset timeout, limited requests allowed
     """
 
-    def __init__(self) -> None:
-        """Initialize HandlerDb in uninitialized state."""
+    def __init__(self, container: ModelONEXContainer) -> None:
+        """Initialize HandlerDb with ONEX container for dependency injection.
+
+        Args:
+            container: ONEX container for dependency injection.
+        """
+        self._container = container
         self._pool: asyncpg.Pool | None = None
         self._pool_size: int = _DEFAULT_POOL_SIZE
         self._timeout: float = _DEFAULT_TIMEOUT_SECONDS

omnibase_infra/handlers/handler_http.py

@@ -24,6 +24,7 @@ from uuid import UUID, uuid4
 
 import httpx
 
+from omnibase_core.container import ModelONEXContainer
 from omnibase_core.models.dispatch import ModelHandlerOutput
 from omnibase_infra.enums import (
     EnumHandlerType,
@@ -114,8 +115,13 @@ class HandlerHttpRest(MixinEnvelopeExtraction):
         - Streaming body validation for chunked transfer encoding
     """
 
-    def __init__(self) -> None:
-        """Initialize HandlerHttpRest in uninitialized state."""
+    def __init__(self, container: ModelONEXContainer) -> None:
+        """Initialize HandlerHttpRest with ONEX container for dependency injection.
+
+        Args:
+            container: ONEX container for dependency injection.
+        """
+        self._container = container
         self._client: httpx.AsyncClient | None = None
         self._timeout: float = _DEFAULT_TIMEOUT_SECONDS
         self._max_request_size: int = _DEFAULT_MAX_REQUEST_SIZE