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

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/errors/error_compute_registry.py

@@ -5,6 +5,8 @@
 This module defines the ComputeRegistryError for compute registry operations.
 """
 
+from typing import Any, cast
+
 from omnibase_infra.errors.error_infra import RuntimeHostError
 from omnibase_infra.models.errors.model_infra_error_context import (
     ModelInfraErrorContext,
@@ -82,10 +84,11 @@ class ComputeRegistryError(RuntimeHostError):
         if registered_plugins is not None:
             extra_context["registered_plugins"] = registered_plugins
 
+        # NOTE: Cast required for mypy - **dict[str, object] doesn't satisfy **context: Any
         super().__init__(
             message=message,
             context=context,
-            **extra_context,
+            **cast("dict[str, Any]", extra_context),
         )
 
 

omnibase_infra/errors/error_event_bus_registry.py

@@ -5,6 +5,8 @@
 This module defines the EventBusRegistryError for event bus registry operations.
 """
 
+from typing import Any, cast
+
 from omnibase_infra.errors.error_infra import RuntimeHostError
 from omnibase_infra.models.errors.model_infra_error_context import (
     ModelInfraErrorContext,
@@ -92,10 +94,11 @@ class EventBusRegistryError(RuntimeHostError):
         if existing_class is not None:
             extra_context["existing_class"] = existing_class
 
+        # NOTE: Cast required for mypy - **dict[str, object] doesn't satisfy **context: Any
         super().__init__(
             message=message,
             context=context,
-            **extra_context,
+            **cast("dict[str, Any]", extra_context),
         )
 
 

omnibase_infra/errors/error_infra.py

@@ -68,6 +68,7 @@ NOT_FOUND Classification Patterns:
     - Optional keys, cache lookups: Use discriminated union responses
 """
 
+from typing import Any, cast
 from uuid import uuid4
 
 from omnibase_core.enums import EnumCoreErrorCode
@@ -145,11 +146,12 @@ class RuntimeHostError(ModelOnexError):
             correlation_id = uuid4()
 
         # Initialize base error with default error code
+        # NOTE: Cast required for mypy - **dict[str, object] doesn't satisfy **context: Any
         super().__init__(
             message=message,
             error_code=error_code or EnumCoreErrorCode.OPERATION_FAILED,
             correlation_id=correlation_id,
-            **structured_context,
+            **cast("dict[str, Any]", structured_context),
         )
 
 

omnibase_infra/errors/error_policy_registry.py

@@ -5,6 +5,8 @@
 This module defines the PolicyRegistryError for policy registry operations.
 """
 
+from typing import Any, cast
+
 from omnibase_infra.enums import EnumPolicyType
 from omnibase_infra.errors.error_infra import RuntimeHostError
 from omnibase_infra.models.errors.model_infra_error_context import (
@@ -102,10 +104,11 @@ class PolicyRegistryError(RuntimeHostError):
                 else policy_type
             )
 
+        # NOTE: Cast required for mypy - **dict[str, object] doesn't satisfy **context: Any
         super().__init__(
             message=message,
             context=context,
-            **extra_context,
+            **cast("dict[str, Any]", extra_context),
         )
 
 

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,7 +75,9 @@ 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 (
     EnumHandlerType,
     EnumHandlerTypeCategory,
@@ -221,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
@@ -1020,7 +1027,7 @@ class HandlerDb(MixinAsyncCircuitBreaker, MixinEnvelopeExtraction):
             - docs/architecture/HANDLER_PROTOCOL_DRIVEN_ARCHITECTURE.md
         """
         # Get circuit breaker state if initialized
-        cb_state: dict[str, object] | None = None
+        cb_state: dict[str, JsonType] | None = None
         if self._circuit_breaker_initialized:
             cb_state = self._get_circuit_breaker_state()
 

omnibase_infra/handlers/handler_graph.py

@@ -464,9 +464,11 @@ class HandlerGraph(MixinAsyncCircuitBreaker, ProtocolGraphDatabaseHandler):
                     try:
                         for query, params in queries:
                             query_start = time.perf_counter()
-                            result = await tx.run(query, dict(params) if params else {})
-                            records_data = await result.data()
-                            summary = await result.consume()
+                            tx_result = await tx.run(
+                                query, dict(params) if params else {}
+                            )
+                            records_data = await tx_result.data()
+                            summary = await tx_result.consume()
                             query_time_ms = (time.perf_counter() - query_start) * 1000
 
                             results.append(
@@ -497,8 +499,11 @@ class HandlerGraph(MixinAsyncCircuitBreaker, ProtocolGraphDatabaseHandler):
             else:
                 # Execute queries individually without transaction
                 for query, params in queries:
-                    result = await self.execute_query(query, params)
-                    results.append(result)
+                    # Type assertion: execute_query returns ModelGraphQueryResult in this handler
+                    query_result: ModelGraphQueryResult = await self.execute_query(
+                        query, params
+                    )  # type: ignore[assignment]
+                    results.append(query_result)
 
             return ModelGraphBatchResult(
                 results=results,

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