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

omnibase_infra/runtime/util_wiring.py

@@ -121,14 +121,18 @@ from omnibase_infra.errors import ModelInfraErrorContext, ProtocolConfigurationE
 from omnibase_infra.event_bus.event_bus_inmemory import EventBusInmemory
 from omnibase_infra.handlers.handler_consul import HandlerConsul
 from omnibase_infra.handlers.handler_db import HandlerDb
+from omnibase_infra.handlers.handler_graph import HandlerGraph
 from omnibase_infra.handlers.handler_http import HandlerHttpRest
+from omnibase_infra.handlers.handler_intent import HandlerIntent
 from omnibase_infra.handlers.handler_mcp import HandlerMCP
 from omnibase_infra.handlers.handler_vault import HandlerVault
 from omnibase_infra.runtime.handler_registry import (
     EVENT_BUS_INMEMORY,
     HANDLER_TYPE_CONSUL,
     HANDLER_TYPE_DATABASE,
+    HANDLER_TYPE_GRAPH,
     HANDLER_TYPE_HTTP,
+    HANDLER_TYPE_INTENT,
     HANDLER_TYPE_MCP,
     HANDLER_TYPE_VAULT,
     RegistryEventBusBinding,
@@ -139,7 +143,7 @@ from omnibase_infra.runtime.handler_registry import (
 
 if TYPE_CHECKING:
     from omnibase_core.protocol.protocol_event_bus import ProtocolEventBus
-    from omnibase_spi.protocols.handlers.protocol_handler import ProtocolHandler
+    from omnibase_infra.protocols import ProtocolContainerAware
 
 logger = logging.getLogger(__name__)
 
@@ -166,11 +170,14 @@ logger = logging.getLogger(__name__)
 # NOTE: HandlerHttpRest and HandlerDb use legacy execute(envelope: dict) signature.
 # They will be migrated to ProtocolHandler.execute(request, operation_config) in future.
 # Type ignore comments suppress MyPy errors during MVP phase.
-_KNOWN_HANDLERS: dict[str, tuple[type[ProtocolHandler], str]] = {
+_KNOWN_HANDLERS: dict[str, tuple[type[ProtocolContainerAware], str]] = {
     # NOTE: Handlers implement ProtocolHandler structurally but concrete types differ from protocol.
     HANDLER_TYPE_CONSUL: (HandlerConsul, "HashiCorp Consul service discovery handler"),  # type: ignore[dict-item]  # NOTE: structural subtyping
     HANDLER_TYPE_DATABASE: (HandlerDb, "PostgreSQL database handler"),  # type: ignore[dict-item]  # NOTE: structural subtyping
+    HANDLER_TYPE_GRAPH: (HandlerGraph, "Graph database (Memgraph/Neo4j) handler"),  # type: ignore[dict-item]  # NOTE: structural subtyping
     HANDLER_TYPE_HTTP: (HandlerHttpRest, "HTTP REST protocol handler"),  # type: ignore[dict-item]  # NOTE: structural subtyping
+    # DEMO: Temporary registration - remove when contract-driven (OMN-1515)
+    HANDLER_TYPE_INTENT: (HandlerIntent, "Intent storage and query handler for demo"),  # type: ignore[dict-item]  # NOTE: structural subtyping
     HANDLER_TYPE_MCP: (HandlerMCP, "Model Context Protocol handler for AI agents"),  # type: ignore[dict-item]  # NOTE: structural subtyping
     HANDLER_TYPE_VAULT: (HandlerVault, "HashiCorp Vault secret management handler"),  # type: ignore[dict-item]  # NOTE: structural subtyping
 }
@@ -197,7 +204,9 @@ def wire_default_handlers() -> dict[str, list[str]]:
     Registered Handlers:
         - CONSUL: HandlerConsul for HashiCorp Consul service discovery
         - DB: HandlerDb for PostgreSQL database operations
+        - GRAPH: HandlerGraph for graph database (Memgraph/Neo4j) operations
         - HTTP: HandlerHttpRest for HTTP/REST protocol operations
+        - INTENT: HandlerIntent for intent storage and query (demo)
         - MCP: HandlerMCP for Model Context Protocol AI agent integration
         - VAULT: HandlerVault for HashiCorp Vault secret management
 
@@ -487,7 +496,7 @@ def get_known_event_bus_kinds() -> list[str]:
 
 def wire_custom_handler(
     handler_type: str,
-    handler_cls: type[ProtocolHandler],
+    handler_cls: type[ProtocolContainerAware],
     registry: RegistryProtocolBinding | None = None,
 ) -> None:
     """Register a custom handler class with the registry.

omnibase_infra/services/__init__.py

@@ -39,6 +39,18 @@ from omnibase_infra.services.service_timeout_scanner import (
     ModelTimeoutQueryResult,
     ServiceTimeoutScanner,
 )
+
+# Session services (moved from omniclaude in OMN-1526)
+from omnibase_infra.services.session import (
+    ConfigSessionConsumer,
+    ConfigSessionStorage,
+    ConsumerMetrics,
+    EnumCircuitState,
+    ProtocolSessionAggregator,
+    SessionEventConsumer,
+    SessionSnapshotStore,
+    SessionStoreNotInitializedError,
+)
 from omnibase_infra.services.snapshot import (
     ServiceSnapshot,
     StoreSnapshotInMemory,
@@ -65,4 +77,13 @@ __all__ = [
     "StoreSnapshotPostgres",
     "TimeoutEmitter",
     "TimeoutScanner",
+    # Session services (OMN-1526)
+    "ConfigSessionConsumer",
+    "ConfigSessionStorage",
+    "ConsumerMetrics",
+    "EnumCircuitState",
+    "ProtocolSessionAggregator",
+    "SessionEventConsumer",
+    "SessionSnapshotStore",
+    "SessionStoreNotInitializedError",
 ]

omnibase_infra/services/corpus_capture.py

@@ -22,6 +22,7 @@ from datetime import UTC, datetime
 from typing import Protocol
 from uuid import UUID
 
+from omnibase_core.container import ModelONEXContainer
 from omnibase_core.enums import EnumCoreErrorCode
 from omnibase_core.errors import OnexError
 from omnibase_core.models.manifest.model_execution_manifest import (
@@ -226,13 +227,15 @@ class CorpusCapture:
     - Max executions enforcement with automatic state transitions
 
     Example:
+        >>> from omnibase_core.container import ModelONEXContainer
+        >>> container = ModelONEXContainer(...)  # Configure as needed
         >>> config = ModelCaptureConfig(
         ...     corpus_display_name="regression-suite-v1",
         ...     max_executions=50,
         ...     sample_rate=0.5,
         ...     handler_filter=("compute-handler",),
         ... )
-        >>> service = CorpusCapture()
+        >>> service = CorpusCapture(container)
         >>> service.create_corpus(config)
         >>> service.start_capture()
         >>>
@@ -249,17 +252,20 @@ class CorpusCapture:
 
     def __init__(
         self,
+        container: ModelONEXContainer,
         persistence: ProtocolManifestPersistence | None = None,
     ) -> None:
         """
         Initialize the corpus capture service.
 
         Args:
+            container: ONEX container for dependency injection.
             persistence: Optional persistence handler for flushing manifests.
                 If provided, manifests can be persisted via flush_to_persistence()
                 or by calling close_corpus_async(flush=True). The synchronous
                 close_corpus() does NOT automatically flush.
         """
+        self._container = container
         self._state_machine = CaptureLifecycleFSM()
         self._config: ModelCaptureConfig | None = None
         self._corpus: ModelExecutionCorpus | None = None

omnibase_infra/services/mcp/mcp_server_lifecycle.py

@@ -15,7 +15,7 @@ Architecture:
 
 Usage:
     ```python
-    lifecycle = MCPServerLifecycle(config)
+    lifecycle = MCPServerLifecycle(container=container, config=config)
     await lifecycle.start()
     # ... server is running ...
     await lifecycle.shutdown()
@@ -28,6 +28,7 @@ import logging
 from typing import TYPE_CHECKING
 from uuid import UUID, uuid4
 
+from omnibase_core.container import ModelONEXContainer
 from omnibase_infra.adapters.adapter_onex_tool_execution import (
     AdapterONEXToolExecution,
 )
@@ -68,6 +69,7 @@ class MCPServerLifecycle:
         3. shutdown(): Clean up all resources
 
     Attributes:
+        _container: ONEX container for dependency injection.
         _config: Server configuration.
         _registry: Tool registry instance.
         _discovery: Consul discovery service.
@@ -80,25 +82,28 @@ class MCPServerLifecycle:
         ...     consul_host="consul.local",
         ...     http_port=8090,
         ... )
-        >>> lifecycle = MCPServerLifecycle(config)
+        >>> lifecycle = MCPServerLifecycle(container=container, config=config)
         >>> await lifecycle.start()
-        >>> handler = lifecycle.get_handler(container)
+        >>> handler = lifecycle.get_handler()
         >>> # Use handler with uvicorn/transport
         >>> await lifecycle.shutdown()
     """
 
     def __init__(
         self,
+        container: ModelONEXContainer,
         config: ModelMCPServerConfig,
         bus: EventBusKafka | None = None,
     ) -> None:
         """Initialize the lifecycle manager.
 
         Args:
+            container: ONEX container for dependency injection.
             config: Server configuration.
             bus: Optional Kafka event bus for hot reload. If not provided,
                 Kafka subscription is skipped even if kafka_enabled=True.
         """
+        self._container = container
         self._config = config
         self._bus = bus
 
@@ -162,6 +167,7 @@ class MCPServerLifecycle:
         # Create services
         self._registry = ServiceMCPToolRegistry()
         self._executor = AdapterONEXToolExecution(
+            container=self._container,
             default_timeout=self._config.default_timeout,
         )
 

omnibase_infra/services/registry_api/main.py

@@ -7,13 +7,18 @@ Provides factory function for flexible instantiation with different
 backend configurations.
 
 Usage:
-    # Create app with default settings (no backends)
-    app = create_app()
+    # Create app with container (required)
+    from omnibase_core.container import ModelONEXContainer
+
+    container = ModelONEXContainer()
+    app = create_app(container=container, cors_origins=["http://localhost:3000"])
 
     # Create app with full backends
     app = create_app(
+        container=container,
         projection_reader=reader,
         consul_handler=handler,
+        cors_origins=["http://localhost:3000"],
     )
 
     # Run with uvicorn
@@ -35,6 +40,7 @@ from typing import TYPE_CHECKING
 from fastapi import FastAPI
 from fastapi.middleware.cors import CORSMiddleware
 
+from omnibase_core.container import ModelONEXContainer
 from omnibase_infra.enums import EnumInfraTransportType
 from omnibase_infra.errors import ModelInfraErrorContext, ProtocolConfigurationError
 from omnibase_infra.services.registry_api.routes import router
@@ -117,6 +123,7 @@ async def lifespan(app: FastAPI) -> AsyncIterator[None]:
 
 
 def create_app(
+    container: ModelONEXContainer,
     projection_reader: ProjectionReaderRegistration | None = None,
     consul_handler: HandlerServiceDiscoveryConsul | None = None,
     widget_mapping_path: Path | None = None,
@@ -129,6 +136,8 @@ def create_app(
     return partial data with warnings when backends are unavailable.
 
     Args:
+        container: ONEX container for dependency injection. Required for
+            ONEX DI pattern compliance.
         projection_reader: Optional projection reader for node registrations.
         consul_handler: Optional Consul handler for live instances.
         widget_mapping_path: Optional path to widget mapping YAML.
@@ -145,7 +154,9 @@ def create_app(
 
     Example:
         >>> from omnibase_infra.services.registry_api import create_app
-        >>> app = create_app()
+        >>> from omnibase_core.container import ModelONEXContainer
+        >>> container = ModelONEXContainer()
+        >>> app = create_app(container=container)
         >>> # Run with: uvicorn module:app --host 0.0.0.0 --port 8000
     """
     app = FastAPI(
@@ -195,6 +206,7 @@ def create_app(
 
     # Create and attach service
     service = ServiceRegistryDiscovery(
+        container=container,
         projection_reader=projection_reader,
         consul_handler=consul_handler,
         widget_mapping_path=widget_mapping_path,
@@ -226,18 +238,24 @@ def create_app(
     return app
 
 
-# Default app instance for direct uvicorn usage
-# Example: uvicorn omnibase_infra.services.registry_api.main:app --host 0.0.0.0 --port 8000
-# Note: This creates an app with no backends configured. For production,
-# use create_app() directly with proper backend configuration (projection_reader,
-# consul_handler). Tests should also use create_app() for controlled app creation.
+# Module-level app instance is not supported since container is required.
+# For production usage, use create_app() with proper configuration:
+#
+# Example:
+#     from omnibase_core.container import ModelONEXContainer
+#     from omnibase_infra.services.registry_api import create_app
+#
+#     container = ModelONEXContainer()
+#     app = create_app(
+#         container=container,
+#         projection_reader=reader,
+#         consul_handler=handler,
+#         cors_origins=["http://localhost:3000"],
+#     )
+#     uvicorn.run(app, host="0.0.0.0", port=8000)
 #
-# IMPORTANT: CORS_ORIGINS environment variable MUST be set for module-level app creation.
-# If CORS_ORIGINS is not set, the module can still be imported but `app` will be None.
-# Use create_app(cors_origins=["..."]) directly for programmatic usage.
+# For uvicorn CLI usage, create a launcher module that instantiates the container.
 app: FastAPI | None = None
-if os.environ.get("CORS_ORIGINS") is not None:
-    app = create_app()
 
 
 __all__ = ["app", "create_app"]

omnibase_infra/services/registry_api/service.py

@@ -77,11 +77,9 @@ class ServiceRegistryDiscovery:
         showing complete errors.
 
     Dependency Injection:
-        This service accepts a ModelONEXContainer for ONEX-style dependency
+        This service requires a ModelONEXContainer for ONEX-style dependency
         injection. Dependencies can also be provided directly via constructor
-        parameters for testing or when the container is not available.
-
-        Priority: Direct parameters > Container resolution > None (with warnings)
+        parameters for testing flexibility.
 
     Thread Safety:
         This service is coroutine-safe. All methods are async and
@@ -89,12 +87,13 @@ class ServiceRegistryDiscovery:
         concurrency requirements.
 
     Example:
-        >>> # Using container for DI
+        >>> # Using container for DI (container is required)
         >>> service = ServiceRegistryDiscovery(container=container)
         >>> response = await service.get_discovery()
         >>>
-        >>> # Using direct dependencies (for testing)
+        >>> # With explicit dependencies (for testing)
         >>> service = ServiceRegistryDiscovery(
+        ...     container=container,
         ...     projection_reader=reader,
         ...     consul_handler=handler,
         ... )
@@ -110,7 +109,7 @@ class ServiceRegistryDiscovery:
 
     def __init__(
         self,
-        container: ModelONEXContainer | None = None,
+        container: ModelONEXContainer,
         projection_reader: ProjectionReaderRegistration | None = None,
         consul_handler: HandlerServiceDiscoveryConsul | None = None,
         widget_mapping_path: Path | None = None,
@@ -118,21 +117,14 @@ class ServiceRegistryDiscovery:
         """Initialize the registry discovery service.
 
         Args:
-            container: Optional ONEX container for dependency injection.
-                When provided, dependencies will be resolved from the container
-                if not explicitly passed via other parameters.
+            container: ONEX container for dependency injection. Required for
+                ONEX DI pattern compliance.
             projection_reader: Optional projection reader for node registrations.
-                If not provided, will attempt to resolve from container.
-                If still None, node queries will return empty results with warnings.
+                If not provided, node queries will return empty results with warnings.
             consul_handler: Optional Consul handler for live instances.
-                If not provided, will attempt to resolve from container.
-                If still None, instance queries will return empty results with warnings.
+                If not provided, instance queries will return empty results with warnings.
             widget_mapping_path: Path to widget mapping YAML file.
                 Defaults to configs/widget_mapping.yaml relative to package.
-
-        Note:
-            Direct dependency parameters take precedence over container resolution.
-            This allows easy mocking in tests while supporting full DI in production.
         """
         self._container = container
 
@@ -157,7 +149,6 @@ class ServiceRegistryDiscovery:
         logger.info(
             "ServiceRegistryDiscovery initialized",
             extra={
-                "has_container": container is not None,
                 "has_projection_reader": self._projection_reader is not None,
                 "has_consul_handler": self._consul_handler is not None,
                 "widget_mapping_path": str(self._widget_mapping_path),

omnibase_infra/services/service_timeout_emitter.py

@@ -36,6 +36,7 @@ from uuid import UUID
 
 from pydantic import BaseModel, ConfigDict, Field, field_validator
 
+from omnibase_core.container import ModelONEXContainer
 from omnibase_core.models.events.model_event_envelope import ModelEventEnvelope
 from omnibase_infra.enums import EnumInfraTransportType
 from omnibase_infra.errors import ModelInfraErrorContext, ProtocolConfigurationError
@@ -217,6 +218,7 @@ class ServiceTimeoutEmitter:
 
     Usage:
         >>> emitter = ServiceTimeoutEmitter(
+        ...     container=container,
         ...     timeout_query=timeout_scanner,
         ...     event_bus=event_bus,
         ...     projector=projector,
@@ -262,6 +264,7 @@ class ServiceTimeoutEmitter:
 
     def __init__(
         self,
+        container: ModelONEXContainer,
         timeout_query: ServiceTimeoutScanner,
         event_bus: ProtocolEventBus,
         projector: ProjectorShell,
@@ -270,6 +273,7 @@ class ServiceTimeoutEmitter:
         """Initialize with required dependencies.
 
         Args:
+            container: ONEX container for dependency injection.
             timeout_query: Scanner for querying overdue entities.
                 Must be initialized with a ProjectionReaderRegistration.
             event_bus: Event bus for publishing timeout events.
@@ -281,16 +285,18 @@ class ServiceTimeoutEmitter:
 
         Example:
             >>> reader = ProjectionReaderRegistration(pool)
-            >>> timeout_query = ServiceTimeoutScanner(reader)
+            >>> timeout_query = ServiceTimeoutScanner(container, reader)
             >>> bus = EventBusKafka.default()
             >>> projector = projector_loader.load("registration_projector")
             >>> emitter = ServiceTimeoutEmitter(
+            ...     container=container,
             ...     timeout_query=timeout_query,
             ...     event_bus=bus,
             ...     projector=projector,
             ...     config=ModelTimeoutEmissionConfig(environment="dev"),
             ... )
         """
+        self._container = container
         self._timeout_query = timeout_query
         self._event_bus = event_bus
         self._projector = projector

omnibase_infra/services/service_timeout_scanner.py

@@ -31,6 +31,7 @@ from uuid import UUID, uuid4
 
 from pydantic import BaseModel, ConfigDict, Field
 
+from omnibase_core.container import ModelONEXContainer
 from omnibase_infra.models.projection import ModelRegistrationProjection
 from omnibase_infra.projectors.projection_reader_registration import (
     ProjectionReaderRegistration,
@@ -126,7 +127,7 @@ class ServiceTimeoutScanner:
 
     Usage:
         >>> reader = ProjectionReaderRegistration(pool)
-        >>> scanner = ServiceTimeoutScanner(reader)
+        >>> scanner = ServiceTimeoutScanner(container, reader)
         >>> result = await scanner.find_overdue_entities(now=tick.now)
         >>>
         >>> for projection in result.ack_timeouts:
@@ -152,12 +153,14 @@ class ServiceTimeoutScanner:
 
     def __init__(
         self,
+        container: ModelONEXContainer,
         projection_reader: ProjectionReaderRegistration,
         batch_size: int | None = None,
     ) -> None:
-        """Initialize with projection reader dependency.
+        """Initialize the timeout scanner service.
 
         Args:
+            container: ONEX container for dependency injection.
             projection_reader: The projection reader for database queries.
                 Must be initialized with an asyncpg connection pool.
             batch_size: Maximum entities to return per query type.
@@ -166,8 +169,9 @@ class ServiceTimeoutScanner:
         Example:
             >>> pool = await asyncpg.create_pool(dsn)
             >>> reader = ProjectionReaderRegistration(pool)
-            >>> scanner = ServiceTimeoutScanner(reader)
+            >>> scanner = ServiceTimeoutScanner(container, reader)
         """
+        self._container = container
         self._reader = projection_reader
         self._batch_size = batch_size or self.DEFAULT_BATCH_SIZE
 

omnibase_infra/services/session/__init__.py

@@ -0,0 +1,56 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Session storage and event consumer services.
+
+This module provides infrastructure for persisting Claude Code session
+snapshots and consuming session events from Kafka.
+
+Moved from omniclaude as part of OMN-1526 architectural cleanup.
+
+Components:
+    - SessionSnapshotStore: PostgreSQL storage for session snapshots
+    - SessionEventConsumer: Kafka consumer for session events
+    - ConfigSessionStorage: Storage configuration
+    - ConfigSessionConsumer: Consumer configuration
+    - ConsumerMetrics: Metrics for consumer observability
+    - EnumCircuitState: Circuit breaker states
+
+Example:
+    >>> from omnibase_infra.services.session import (
+    ...     SessionSnapshotStore,
+    ...     ConfigSessionStorage,
+    ... )
+    >>> from pydantic import SecretStr
+    >>>
+    >>> config = ConfigSessionStorage(postgres_password=SecretStr("secret"))
+    >>> store = SessionSnapshotStore(config)
+    >>> await store.initialize()
+"""
+
+from omnibase_infra.services.session.config_consumer import ConfigSessionConsumer
+from omnibase_infra.services.session.config_store import ConfigSessionStorage
+from omnibase_infra.services.session.consumer import (
+    ConsumerMetrics,
+    EnumCircuitState,
+    SessionEventConsumer,
+)
+from omnibase_infra.services.session.protocol_session_aggregator import (
+    ProtocolSessionAggregator,
+)
+from omnibase_infra.services.session.store import (
+    SessionSnapshotStore,
+    SessionStoreNotInitializedError,
+)
+
+__all__ = [
+    # Storage
+    "SessionSnapshotStore",
+    "SessionStoreNotInitializedError",
+    "ConfigSessionStorage",
+    # Consumer
+    "SessionEventConsumer",
+    "ConfigSessionConsumer",
+    "ConsumerMetrics",
+    "EnumCircuitState",
+    "ProtocolSessionAggregator",
+]

omnibase_infra/services/session/config_consumer.py

@@ -0,0 +1,120 @@
+"""Configuration for session event consumers.
+
+Loads from environment variables with OMNIBASE_INFRA_SESSION_CONSUMER_ prefix.
+
+Moved from omniclaude as part of OMN-1526 architectural cleanup.
+"""
+
+from __future__ import annotations
+
+import logging
+
+from pydantic import Field, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+logger = logging.getLogger(__name__)
+
+
+class ConfigSessionConsumer(BaseSettings):
+    """Configuration for the Claude session event Kafka consumer.
+
+    Environment variables use the OMNIBASE_INFRA_SESSION_CONSUMER_ prefix.
+    Example: OMNIBASE_INFRA_SESSION_CONSUMER_BOOTSTRAP_SERVERS=kafka.example.com:9092
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="OMNIBASE_INFRA_SESSION_CONSUMER_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    # Kafka connection
+    bootstrap_servers: str = Field(
+        default="localhost:9092",
+        description="Kafka bootstrap servers. Set via OMNIBASE_INFRA_SESSION_CONSUMER_BOOTSTRAP_SERVERS env var for production.",
+    )
+    group_id: str = Field(
+        default="omnibase-infra-session-consumer",
+        description="Consumer group ID",
+    )
+
+    # Topics to subscribe
+    topics: list[str] = Field(
+        default=[
+            "dev.omniclaude.session.started.v1",
+            "dev.omniclaude.session.ended.v1",
+            "dev.omniclaude.prompt.submitted.v1",
+            "dev.omniclaude.tool.executed.v1",
+        ],
+        description="Kafka topics to consume",
+    )
+
+    # Consumer behavior
+    auto_offset_reset: str = Field(
+        default="earliest",
+        description="Where to start consuming if no offset exists",
+    )
+    enable_auto_commit: bool = Field(
+        default=False,
+        description="Disable auto-commit for at-least-once delivery",
+    )
+    max_poll_records: int = Field(
+        default=100,
+        ge=1,
+        le=10000,
+        description="Maximum records per poll",
+    )
+
+    # Processing
+    batch_timeout_ms: int = Field(
+        default=5000,
+        ge=100,
+        le=60000,
+        description="Timeout for batch processing in milliseconds",
+    )
+
+    # Circuit breaker
+    circuit_breaker_threshold: int = Field(
+        default=5,
+        ge=1,
+        le=100,
+        description="Failures before circuit opens",
+    )
+    circuit_breaker_timeout_seconds: int = Field(
+        default=60,
+        ge=1,
+        le=3600,
+        description="Time before circuit half-opens",
+    )
+    circuit_breaker_half_open_successes: int = Field(
+        default=1,
+        ge=1,
+        le=10,
+        description="Number of successful requests required to close circuit from half-open state",
+    )
+
+    @model_validator(mode="after")
+    def validate_timing_relationships(self) -> ConfigSessionConsumer:
+        """Validate timing relationships between configuration values.
+
+        Warns if circuit breaker timeout is very short relative to batch processing,
+        which could cause premature circuit opens during normal batch operations.
+
+        Returns:
+            Self if validation passes.
+        """
+        batch_timeout_seconds = self.batch_timeout_ms / 1000
+        min_recommended_circuit_timeout = batch_timeout_seconds * 2
+
+        if self.circuit_breaker_timeout_seconds < min_recommended_circuit_timeout:
+            logger.warning(
+                "Circuit breaker timeout (%ds) is less than 2x batch timeout (%.1fs). "
+                "This may cause premature circuit opens during normal batch processing. "
+                "Recommended minimum: %ds",
+                self.circuit_breaker_timeout_seconds,
+                batch_timeout_seconds,
+                int(min_recommended_circuit_timeout),
+            )
+        return self