omnibase_infra 0.3.1__py3-none-any.whl → 0.4.0__py3-none-any.whl

omnibase_infra/schemas/schema_latency_baseline.sql

@@ -0,0 +1,135 @@
+-- Materialized View: latency_baseline
+-- Description: Hourly latency baseline for A/B comparison (OMN-1890)
+-- Created: 2026-02-04
+--
+-- Purpose: Pre-computes hourly latency statistics per cohort for dashboard queries.
+-- Refreshed hourly (not daily) to catch intra-day drift. Dashboard queries use
+-- COALESCE with 7-day rolling fallback when sample_count is insufficient.
+--
+-- Refresh Strategy:
+--   - Scheduled via pg_cron: REFRESH MATERIALIZED VIEW CONCURRENTLY latency_baseline;
+--   - Recommended schedule: Every hour at :05 (e.g., 00:05, 01:05, ...)
+--   - CONCURRENTLY allows queries during refresh (requires UNIQUE index)
+--
+-- Usage in Dashboard Queries:
+--   SELECT
+--     ie.session_id,
+--     ie.cohort,
+--     ie.user_visible_latency_ms,
+--     ie.user_visible_latency_ms - COALESCE(
+--       lb.avg_latency_ms,
+--       (SELECT AVG(avg_latency_ms) FROM latency_baseline
+--        WHERE cohort = ie.cohort AND hour > NOW() - INTERVAL '7 days')
+--     ) AS latency_delta_ms
+--   FROM injection_effectiveness ie
+--   LEFT JOIN latency_baseline lb
+--     ON DATE_TRUNC('hour', ie.created_at) = lb.hour
+--     AND ie.cohort = lb.cohort;
+--
+-- Related Tickets:
+--   - OMN-1890: Store injection metrics with corrected schema
+
+-- ============================================================================
+-- MATERIALIZED VIEW
+-- ============================================================================
+
+CREATE MATERIALIZED VIEW IF NOT EXISTS latency_baseline AS
+SELECT
+    DATE_TRUNC('hour', created_at) AS hour,
+    cohort,
+    AVG(user_visible_latency_ms) AS avg_latency_ms,
+    PERCENTILE_CONT(0.5) WITHIN GROUP (ORDER BY user_visible_latency_ms) AS p50_latency_ms,
+    PERCENTILE_CONT(0.95) WITHIN GROUP (ORDER BY user_visible_latency_ms) AS p95_latency_ms,
+    PERCENTILE_CONT(0.99) WITHIN GROUP (ORDER BY user_visible_latency_ms) AS p99_latency_ms,
+    MIN(user_visible_latency_ms) AS min_latency_ms,
+    MAX(user_visible_latency_ms) AS max_latency_ms,
+    STDDEV(user_visible_latency_ms) AS stddev_latency_ms,
+    COUNT(*) AS sample_count
+FROM injection_effectiveness
+WHERE user_visible_latency_ms IS NOT NULL
+  AND cohort IS NOT NULL
+GROUP BY DATE_TRUNC('hour', created_at), cohort;
+
+-- ============================================================================
+-- INDEXES FOR MATERIALIZED VIEW
+-- ============================================================================
+
+-- Required for REFRESH CONCURRENTLY
+CREATE UNIQUE INDEX IF NOT EXISTS idx_latency_baseline_hour_cohort
+    ON latency_baseline (hour, cohort);
+
+-- Fast lookups by cohort
+CREATE INDEX IF NOT EXISTS idx_latency_baseline_cohort
+    ON latency_baseline (cohort);
+
+-- Recent hour queries
+CREATE INDEX IF NOT EXISTS idx_latency_baseline_hour_desc
+    ON latency_baseline (hour DESC);
+
+-- ============================================================================
+-- COMMENTS
+-- ============================================================================
+
+COMMENT ON MATERIALIZED VIEW latency_baseline IS
+    'Hourly latency baseline per cohort for A/B testing comparison (OMN-1890). '
+    'Refresh hourly via pg_cron. Use COALESCE with 7-day rolling fallback for '
+    'hours with insufficient sample_count.';
+
+COMMENT ON COLUMN latency_baseline.hour IS
+    'Truncated hour timestamp for aggregation';
+COMMENT ON COLUMN latency_baseline.cohort IS
+    'A/B test cohort: control or treatment';
+COMMENT ON COLUMN latency_baseline.avg_latency_ms IS
+    'Average user-visible latency in milliseconds';
+COMMENT ON COLUMN latency_baseline.p50_latency_ms IS
+    'Median (50th percentile) latency';
+COMMENT ON COLUMN latency_baseline.p95_latency_ms IS
+    '95th percentile latency for tail analysis';
+COMMENT ON COLUMN latency_baseline.p99_latency_ms IS
+    '99th percentile latency for extreme tail analysis';
+COMMENT ON COLUMN latency_baseline.sample_count IS
+    'Number of sessions in this hour/cohort. Check for reliability (recommended N>=20).';
+
+-- ============================================================================
+-- HELPER FUNCTION: Refresh with logging
+-- ============================================================================
+
+-- Note: REFRESH MATERIALIZED VIEW CONCURRENTLY cannot be used inside PL/pgSQL
+-- functions due to transaction context restrictions. Use regular REFRESH here.
+-- For concurrent refresh (allowing queries during refresh), call directly via
+-- pg_cron: REFRESH MATERIALIZED VIEW CONCURRENTLY latency_baseline;
+
+CREATE OR REPLACE FUNCTION refresh_latency_baseline()
+RETURNS void AS $$
+DECLARE
+    start_time TIMESTAMPTZ;
+    end_time TIMESTAMPTZ;
+    duration_ms NUMERIC;
+    row_count INTEGER;
+BEGIN
+    start_time := clock_timestamp();
+
+    -- Use regular REFRESH (not CONCURRENTLY) inside PL/pgSQL function.
+    -- CONCURRENTLY is not allowed inside PL/pgSQL transaction context.
+    REFRESH MATERIALIZED VIEW latency_baseline;
+
+    end_time := clock_timestamp();
+
+    -- Get row count for logging
+    SELECT COUNT(*) INTO row_count FROM latency_baseline;
+
+    -- Calculate total duration in milliseconds using EPOCH (handles any duration).
+    -- Note: EXTRACT(MILLISECONDS FROM interval) only returns the ms component,
+    -- not total ms. EXTRACT(EPOCH FROM ...) returns total seconds as decimal.
+    duration_ms := EXTRACT(EPOCH FROM (end_time - start_time)) * 1000;
+
+    RAISE NOTICE 'latency_baseline refreshed: % rows in % ms',
+        row_count,
+        ROUND(duration_ms)::INTEGER;
+END;
+$$ LANGUAGE plpgsql;
+
+COMMENT ON FUNCTION refresh_latency_baseline() IS
+    'Refresh latency_baseline materialized view with timing log. '
+    'Uses regular REFRESH (not CONCURRENTLY) due to PL/pgSQL transaction restrictions. '
+    'For concurrent refresh, call directly: REFRESH MATERIALIZED VIEW CONCURRENTLY latency_baseline;';

omnibase_infra/services/contract_publisher/config.py

@@ -58,7 +58,7 @@ class ModelContractPublisherConfig(BaseModel):
         package_module: Module name for package resource discovery
         fail_fast: If True, raise immediately on infrastructure errors
         allow_zero_contracts: If True, allow empty publish results
-        environment: Environment prefix for topics (defaults via resolve_environment)
+        environment: Environment identifier (used for consumer groups, not topic naming)
 
     Example:
         >>> config = ModelContractPublisherConfig(
@@ -67,8 +67,8 @@ class ModelContractPublisherConfig(BaseModel):
         ...     fail_fast=True,
         ...     allow_zero_contracts=False,
         ... )
-        >>> env = config.resolve_environment()
-        >>> print(f"Publishing to {env}.onex.evt.contract-registered.v1")
+        >>> # Topics are realm-agnostic (no environment prefix)
+        >>> print("Publishing to onex.evt.contract-registered.v1")
 
     .. versionadded:: 0.3.0
     """
@@ -96,7 +96,7 @@ class ModelContractPublisherConfig(BaseModel):
     )
     environment: str | None = Field(
         default=None,
-        description="Environment prefix for topics (resolved via resolve_environment)",
+        description="Environment identifier for consumer groups (resolved via resolve_environment)",
     )
 
     @model_validator(mode="after")

omnibase_infra/services/contract_publisher/service.py

@@ -26,7 +26,6 @@ from uuid import uuid4
 import yaml
 from pydantic import ValidationError
 
-from omnibase_core.constants import TOPIC_SUFFIX_CONTRACT_REGISTERED
 from omnibase_core.models.contracts.model_handler_contract import ModelHandlerContract
 from omnibase_core.models.events import ModelContractRegisteredEvent
 from omnibase_core.protocols.event_bus import ProtocolEventBusPublisher
@@ -35,6 +34,9 @@ from omnibase_infra.errors import (
     InfraTimeoutError,
     InfraUnavailableError,
 )
+from omnibase_infra.runtime.contract_registration_event_router import (
+    TOPIC_SUFFIX_CONTRACT_REGISTERED,
+)
 from omnibase_infra.services.contract_publisher.config import (
     ModelContractPublisherConfig,
 )
@@ -214,17 +216,18 @@ class ServiceContractPublisher:
                 )
 
     def resolve_topic(self, topic_suffix: str) -> str:
-        """Resolve topic suffix to full topic name with environment prefix.
+        """Resolve topic suffix to topic name (realm-agnostic, no environment prefix).
 
-        Uses the same pattern as EventBusSubcontractWiring.
+        Topics are realm-agnostic in ONEX. The environment/realm is enforced via
+        envelope identity, not topic naming.
 
         Args:
             topic_suffix: Topic suffix (e.g., "onex.evt.contract-registered.v1")
 
         Returns:
-            Full topic name (e.g., "dev.onex.evt.contract-registered.v1")
+            Topic name (same as suffix, no environment prefix)
         """
-        return f"{self._environment}.{topic_suffix}"
+        return topic_suffix
 
     async def publish_all(self) -> ModelPublishResult:
         """Discover and publish all contracts from configured source.

omnibase_infra/services/observability/injection_effectiveness/__init__.py

@@ -0,0 +1,67 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Injection Effectiveness Observability Service.
+
+This module provides Kafka consumers and PostgreSQL writers for injection
+effectiveness metrics collected from omniclaude hooks.
+
+Topics consumed:
+    - onex.evt.omniclaude.context-utilization.v1
+    - onex.evt.omniclaude.agent-match.v1
+    - onex.evt.omniclaude.latency-breakdown.v1
+
+Related Tickets:
+    - OMN-1890: Store injection metrics with corrected schema
+    - OMN-1889: Emit injection metrics + utilization signal (producer)
+
+Example:
+    >>> from omnibase_infra.services.observability.injection_effectiveness import (
+    ...     InjectionEffectivenessConsumer,
+    ...     ConfigInjectionEffectivenessConsumer,
+    ... )
+    >>>
+    >>> config = ConfigInjectionEffectivenessConsumer(
+    ...     kafka_bootstrap_servers="localhost:9092",
+    ...     postgres_dsn="postgresql://postgres:secret@localhost:5432/omninode_bridge",
+    ... )
+    >>> consumer = InjectionEffectivenessConsumer(config)
+    >>>
+    >>> await consumer.start()
+    >>> await consumer.run()
+"""
+
+from omnibase_infra.services.observability.injection_effectiveness.config import (
+    ConfigInjectionEffectivenessConsumer,
+)
+from omnibase_infra.services.observability.injection_effectiveness.consumer import (
+    TOPIC_TO_MODEL,
+    TOPIC_TO_WRITER_METHOD,
+    ConsumerMetrics,
+    EnumHealthStatus,
+    InjectionEffectivenessConsumer,
+    mask_dsn_password,
+)
+from omnibase_infra.services.observability.injection_effectiveness.models import (
+    ModelAgentMatchEvent,
+    ModelContextUtilizationEvent,
+    ModelLatencyBreakdownEvent,
+    ModelPatternUtilization,
+)
+from omnibase_infra.services.observability.injection_effectiveness.writer_postgres import (
+    WriterInjectionEffectivenessPostgres,
+)
+
+__all__ = [
+    "ConfigInjectionEffectivenessConsumer",
+    "ConsumerMetrics",
+    "EnumHealthStatus",
+    "InjectionEffectivenessConsumer",
+    "ModelAgentMatchEvent",
+    "ModelContextUtilizationEvent",
+    "ModelLatencyBreakdownEvent",
+    "ModelPatternUtilization",
+    "TOPIC_TO_MODEL",
+    "TOPIC_TO_WRITER_METHOD",
+    "WriterInjectionEffectivenessPostgres",
+    "mask_dsn_password",
+]

omnibase_infra/services/observability/injection_effectiveness/config.py

@@ -0,0 +1,295 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Configuration for injection effectiveness observability consumer.
+
+This module provides Pydantic Settings configuration for the injection
+effectiveness Kafka consumer service. Configuration is loaded from environment
+variables with the ``OMNIBASE_INFRA_INJECTION_EFFECTIVENESS_`` prefix.
+
+Configuration Groups:
+    - **Kafka**: Bootstrap servers, consumer group, topics, auto-offset reset
+    - **PostgreSQL**: DSN connection string, pool sizing
+    - **Batch Processing**: Batch size, timeout, poll buffer
+    - **Circuit Breaker**: Threshold, reset timeout, half-open successes
+    - **Health Check**: Port, host, staleness thresholds, startup grace period
+    - **Pattern Analytics**: Minimum support threshold for statistical confidence
+
+Environment Variables:
+    All configuration values can be set via environment variables with the
+    ``OMNIBASE_INFRA_INJECTION_EFFECTIVENESS_`` prefix. For example:
+
+    - ``OMNIBASE_INFRA_INJECTION_EFFECTIVENESS_KAFKA_BOOTSTRAP_SERVERS``
+    - ``OMNIBASE_INFRA_INJECTION_EFFECTIVENESS_POSTGRES_DSN``
+    - ``OMNIBASE_INFRA_INJECTION_EFFECTIVENESS_BATCH_SIZE``
+    - ``OMNIBASE_INFRA_INJECTION_EFFECTIVENESS_CIRCUIT_BREAKER_THRESHOLD``
+
+Validation:
+    The configuration validates:
+    - At least one topic must be configured
+    - Pool min size must be <= pool max size
+    - Timing relationships (warns if circuit breaker timeout < 2x batch timeout)
+
+Related Tickets:
+    - OMN-1890: Store injection metrics with corrected schema
+    - OMN-1889: Emit injection metrics from omniclaude hooks (producer)
+
+Example:
+    >>> from omnibase_infra.services.observability.injection_effectiveness.config import (
+    ...     ConfigInjectionEffectivenessConsumer,
+    ... )
+    >>>
+    >>> # Load from environment (default)
+    >>> config = ConfigInjectionEffectivenessConsumer()
+    >>>
+    >>> # Or with explicit values
+    >>> config = ConfigInjectionEffectivenessConsumer(
+    ...     kafka_bootstrap_servers="kafka.example.com:9092",
+    ...     postgres_dsn="postgresql://user:pass@host:5432/db",
+    ...     batch_size=200,
+    ... )
+    >>>
+    >>> print(config.topics)
+    ['onex.evt.omniclaude.context-utilization.v1', ...]
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Self
+
+from pydantic import Field, model_validator
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from omnibase_infra.enums import EnumInfraTransportType
+from omnibase_infra.errors import ModelInfraErrorContext, ProtocolConfigurationError
+
+logger = logging.getLogger(__name__)
+
+
+class ConfigInjectionEffectivenessConsumer(BaseSettings):
+    """Configuration for the injection effectiveness Kafka consumer.
+
+    Environment variables use the OMNIBASE_INFRA_INJECTION_EFFECTIVENESS_ prefix.
+    Example: OMNIBASE_INFRA_INJECTION_EFFECTIVENESS_KAFKA_BOOTSTRAP_SERVERS=kafka.example.com:9092
+
+    This consumer subscribes to injection effectiveness topics and
+    persists events to PostgreSQL for A/B testing analytics.
+    """
+
+    model_config = SettingsConfigDict(
+        env_prefix="OMNIBASE_INFRA_INJECTION_EFFECTIVENESS_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        case_sensitive=False,
+        extra="ignore",
+    )
+
+    # Kafka connection
+    kafka_bootstrap_servers: str = Field(
+        default="localhost:9092",
+        description=(
+            "Kafka bootstrap servers. Set via "
+            "OMNIBASE_INFRA_INJECTION_EFFECTIVENESS_KAFKA_BOOTSTRAP_SERVERS env var."
+        ),
+    )
+    kafka_group_id: str = Field(
+        default="injection-effectiveness-postgres",
+        description="Consumer group ID for offset tracking",
+    )
+
+    # Topics to subscribe (3 injection effectiveness topics from OMN-1889)
+    topics: list[str] = Field(
+        default_factory=lambda: [
+            "onex.evt.omniclaude.context-utilization.v1",
+            "onex.evt.omniclaude.agent-match.v1",
+            "onex.evt.omniclaude.latency-breakdown.v1",
+        ],
+        description="Kafka topics to consume for injection effectiveness",
+    )
+
+    # 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",
+    )
+
+    # PostgreSQL connection
+    postgres_dsn: str = Field(
+        description=(
+            "PostgreSQL connection string. Set via "
+            "OMNIBASE_INFRA_INJECTION_EFFECTIVENESS_POSTGRES_DSN env var."
+        ),
+    )
+
+    # Batch processing
+    batch_size: int = Field(
+        default=100,
+        ge=1,
+        le=1000,
+        description="Maximum records per batch write",
+    )
+    batch_timeout_ms: int = Field(
+        default=1000,
+        ge=100,
+        le=60000,
+        description="Timeout for batch accumulation in milliseconds",
+    )
+    poll_timeout_buffer_seconds: float = Field(
+        default=5.0,
+        ge=1.0,
+        le=30.0,
+        description=(
+            "Additional buffer time added to batch_timeout_ms for asyncio.wait_for."
+        ),
+    )
+
+    # Circuit breaker
+    circuit_breaker_threshold: int = Field(
+        default=5,
+        ge=1,
+        le=100,
+        description="Failures before circuit opens",
+    )
+    circuit_breaker_reset_timeout: float = Field(
+        default=60.0,
+        ge=1.0,
+        le=3600.0,
+        description="Seconds before circuit half-opens for retry",
+    )
+    circuit_breaker_half_open_successes: int = Field(
+        default=1,
+        ge=1,
+        le=10,
+        description="Successful requests required to close circuit from half-open state",
+    )
+
+    # Minimum support gating for pattern confidence (R3 requirement)
+    min_pattern_support: int = Field(
+        default=20,
+        ge=1,
+        le=1000,
+        description=(
+            "Minimum number of sessions required before pattern utilization "
+            "metrics are considered statistically reliable (N=20 default)."
+        ),
+    )
+
+    # PostgreSQL pool settings
+    pool_min_size: int = Field(
+        default=2,
+        ge=1,
+        le=20,
+        description="Minimum number of connections in the PostgreSQL connection pool.",
+    )
+    pool_max_size: int = Field(
+        default=10,
+        ge=2,
+        le=100,
+        description="Maximum number of connections in the PostgreSQL connection pool.",
+    )
+
+    # Health check
+    health_check_port: int = Field(
+        default=8088,
+        ge=1024,
+        le=65535,
+        description="Port for HTTP health check endpoint",
+    )
+    health_check_host: str = Field(
+        default="0.0.0.0",  # noqa: S104 - Configurable for container access
+        description="Host/IP for health check server binding.",
+    )
+    health_check_staleness_seconds: int = Field(
+        default=300,
+        ge=60,
+        le=3600,
+        description="Maximum age for last successful write before DEGRADED status.",
+    )
+    health_check_poll_staleness_seconds: int = Field(
+        default=60,
+        ge=10,
+        le=300,
+        description="Maximum age for last poll before DEGRADED status.",
+    )
+    startup_grace_period_seconds: float = Field(
+        default=60.0,
+        ge=10.0,
+        le=300.0,
+        description=(
+            "Grace period in seconds after startup during which the consumer is "
+            "considered healthy even without successful writes. Allows time for "
+            "initial Kafka partition assignment and first message processing."
+        ),
+    )
+
+    @model_validator(mode="after")
+    def validate_topic_configuration(self) -> Self:
+        """Ensure topics are configured.
+
+        Returns:
+            Self if validation passes.
+
+        Raises:
+            ProtocolConfigurationError: If no topics are configured.
+        """
+        if not self.topics:
+            # Auto-generate correlation_id for configuration errors
+            # (no request context available during model validation)
+            context = ModelInfraErrorContext.with_correlation(
+                transport_type=EnumInfraTransportType.RUNTIME,
+                operation="validate_topic_configuration",
+                target_name="ConfigInjectionEffectivenessConsumer",
+            )
+            raise ProtocolConfigurationError(
+                "No topics configured for injection effectiveness consumer.",
+                context=context,
+            )
+        return self
+
+    @model_validator(mode="after")
+    def validate_timing_relationships(self) -> Self:
+        """Validate timing relationships between configuration values.
+
+        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_reset_timeout < min_recommended_circuit_timeout:
+            logger.warning(
+                "Circuit breaker timeout (%.1fs) is less than 2x batch timeout (%.1fs).",
+                self.circuit_breaker_reset_timeout,
+                batch_timeout_seconds,
+            )
+        return self
+
+    @model_validator(mode="after")
+    def validate_pool_size_relationship(self) -> Self:
+        """Validate pool size relationship (min <= max).
+
+        Returns:
+            Self if validation passes.
+
+        Raises:
+            ProtocolConfigurationError: If pool_min_size > pool_max_size.
+        """
+        if self.pool_min_size > self.pool_max_size:
+            context = ModelInfraErrorContext.with_correlation(
+                transport_type=EnumInfraTransportType.RUNTIME,
+                operation="validate_pool_size_relationship",
+                target_name="ConfigInjectionEffectivenessConsumer",
+            )
+            raise ProtocolConfigurationError(
+                f"pool_min_size ({self.pool_min_size}) must be <= pool_max_size "
+                f"({self.pool_max_size}).",
+                context=context,
+            )
+        return self
+
+
+__all__ = ["ConfigInjectionEffectivenessConsumer"]