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

omnibase_infra/services/observability/injection_effectiveness/models/__init__.py

@@ -0,0 +1,32 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Pydantic models for injection effectiveness events.
+
+These models correspond to the event payloads emitted by OMN-1889
+(omniclaude hooks) and consumed by OMN-1890 (this consumer).
+
+Event Types:
+    - ModelContextUtilizationEvent: Context utilization detection results
+    - ModelAgentMatchEvent: Agent routing accuracy metrics
+    - ModelLatencyBreakdownEvent: Per-prompt latency breakdowns
+"""
+
+from omnibase_infra.services.observability.injection_effectiveness.models.model_agent_match import (
+    ModelAgentMatchEvent,
+)
+from omnibase_infra.services.observability.injection_effectiveness.models.model_context_utilization import (
+    ModelContextUtilizationEvent,
+)
+from omnibase_infra.services.observability.injection_effectiveness.models.model_latency_breakdown import (
+    ModelLatencyBreakdownEvent,
+)
+from omnibase_infra.services.observability.injection_effectiveness.models.model_pattern_utilization import (
+    ModelPatternUtilization,
+)
+
+__all__ = [
+    "ModelAgentMatchEvent",
+    "ModelContextUtilizationEvent",
+    "ModelLatencyBreakdownEvent",
+    "ModelPatternUtilization",
+]

omnibase_infra/services/observability/injection_effectiveness/models/model_agent_match.py

@@ -0,0 +1,79 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Agent match event model.
+
+Represents the payload from onex.evt.omniclaude.agent-match.v1 topic.
+Tracks agent routing accuracy with graded scoring (replaces boolean match).
+
+Related Tickets:
+    - OMN-1889: Emit injection metrics + utilization signal (producer)
+    - OMN-1890: Store injection metrics with corrected schema (consumer)
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelAgentMatchEvent(BaseModel):
+    """Agent match event from omniclaude hooks.
+
+    Emitted to report how well the predicted agent matched the actual
+    agent used in the session. Uses graded scoring (0.0-1.0) instead
+    of simple boolean match for more nuanced analysis.
+
+    This event populates:
+        - injection_effectiveness table (agent match fields)
+
+    Scoring Logic:
+        - 1.0: Exact match (expected == actual)
+        - 0.5-0.9: Partial match (same category, different variant)
+        - 0.0: Complete mismatch (different category)
+
+    Attributes:
+        event_type: Event type discriminator.
+        session_id: Session identifier for correlation.
+        correlation_id: Request correlation ID for tracing.
+        agent_match_score: Graded match score (0.0-1.0).
+        expected_agent: Agent predicted by routing system.
+        actual_agent: Agent actually used in session.
+        created_at: Event timestamp.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    event_type: Literal["agent_match"] = Field(
+        default="agent_match",
+        description="Event type discriminator",
+    )
+    session_id: UUID = Field(..., description="Session identifier")
+    correlation_id: UUID = Field(
+        default_factory=uuid4,
+        description="Correlation ID for tracing",
+    )
+
+    # Agent matching (graded 0.0-1.0)
+    agent_match_score: float = Field(
+        ...,
+        ge=0.0,
+        le=1.0,
+        description="Graded match score 0.0-1.0",
+    )
+    expected_agent: str | None = Field(
+        default=None,
+        description="Agent predicted by routing system",
+    )
+    actual_agent: str | None = Field(
+        default=None,
+        description="Agent actually used in session",
+    )
+
+    # Timestamp
+    created_at: datetime = Field(
+        ...,
+        description="Event timestamp",
+    )

omnibase_infra/services/observability/injection_effectiveness/models/model_context_utilization.py

@@ -0,0 +1,118 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Context utilization event model.
+
+Represents the payload from onex.evt.omniclaude.context-utilization.v1 topic.
+Tracks whether injected context was actually used in the Claude response.
+
+Related Tickets:
+    - OMN-1889: Emit injection metrics + utilization signal (producer)
+    - OMN-1890: Store injection metrics with corrected schema (consumer)
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_infra.services.observability.injection_effectiveness.models.model_pattern_utilization import (
+    ModelPatternUtilization,
+)
+
+
+class ModelContextUtilizationEvent(BaseModel):
+    """Context utilization event from omniclaude hooks.
+
+    Emitted at session end to report how much of the injected context
+    was actually utilized in Claude's responses.
+
+    This event populates:
+        - injection_effectiveness table (utilization fields)
+        - pattern_hit_rates table (per-pattern breakdown)
+
+    Attributes:
+        event_type: Event type discriminator.
+        session_id: Session identifier for correlation.
+        correlation_id: Request correlation ID for tracing.
+        cohort: A/B test cohort assignment.
+        cohort_identity_type: How cohort was assigned.
+        total_injected_tokens: Total tokens injected in session.
+        patterns_injected: Number of patterns injected.
+        utilization_score: Overall utilization score (0.0-1.0).
+        utilization_method: Detection method used.
+        injected_identifiers_count: Identifiers in injected context.
+        reused_identifiers_count: Identifiers found in response.
+        pattern_utilizations: Per-pattern utilization breakdown.
+        created_at: Event timestamp.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    event_type: Literal["context_utilization"] = Field(
+        default="context_utilization",
+        description="Event type discriminator",
+    )
+    session_id: UUID = Field(..., description="Session identifier")
+    correlation_id: UUID = Field(
+        default_factory=uuid4,
+        description="Correlation ID for tracing",
+    )
+
+    # A/B Testing
+    cohort: Literal["control", "treatment"] | None = Field(
+        default=None,
+        description="A/B test cohort",
+    )
+    cohort_identity_type: Literal["user_id", "repo_path", "session_id"] | None = Field(
+        default=None,
+        description="Identity type used for cohort assignment",
+    )
+
+    # Injection metrics
+    total_injected_tokens: int = Field(
+        default=0,
+        ge=0,
+        description="Total tokens injected in session",
+    )
+    patterns_injected: int = Field(
+        default=0,
+        ge=0,
+        description="Number of patterns injected",
+    )
+
+    # Utilization (heuristic-based, NOT token attribution)
+    utilization_score: float = Field(
+        ...,
+        ge=0.0,
+        le=1.0,
+        description="Overall utilization score 0.0-1.0",
+    )
+    utilization_method: str = Field(
+        ...,
+        description="Detection method: identifier_match, semantic, or timeout",
+    )
+    injected_identifiers_count: int = Field(
+        default=0,
+        ge=0,
+        description="Number of identifiers in injected context",
+    )
+    reused_identifiers_count: int = Field(
+        default=0,
+        ge=0,
+        description="Number of identifiers found in response",
+    )
+
+    # Per-pattern breakdown
+    pattern_utilizations: tuple[ModelPatternUtilization, ...] = Field(
+        default_factory=tuple,
+        description="Per-pattern utilization metrics",
+    )
+
+    # Timestamp
+    created_at: datetime = Field(
+        ...,
+        description="Event timestamp",
+    )

omnibase_infra/services/observability/injection_effectiveness/models/model_latency_breakdown.py

@@ -0,0 +1,107 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Latency breakdown event model.
+
+Represents the payload from onex.evt.omniclaude.latency-breakdown.v1 topic.
+Tracks detailed timing including user-perceived latency per prompt.
+
+Related Tickets:
+    - OMN-1889: Emit injection metrics + utilization signal (producer)
+    - OMN-1890: Store injection metrics with corrected schema (consumer)
+"""
+
+from __future__ import annotations
+
+from datetime import datetime
+from typing import Literal
+from uuid import UUID, uuid4
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelLatencyBreakdownEvent(BaseModel):
+    """Latency breakdown event from omniclaude hooks.
+
+    Emitted per-prompt to report detailed latency breakdowns including
+    internal timings and user-perceived latency.
+
+    This event populates:
+        - latency_breakdowns table (per-prompt row)
+        - injection_effectiveness table (MAX aggregation for user_visible_latency_ms)
+
+    Attributes:
+        event_type: Event type discriminator.
+        session_id: Session identifier for correlation.
+        correlation_id: Request correlation ID for tracing.
+        prompt_id: Unique prompt identifier from emitter.
+        cohort: A/B test cohort assignment.
+        cache_hit: Whether this prompt benefited from cache.
+        routing_latency_ms: Time spent in agent routing.
+        retrieval_latency_ms: Time spent retrieving context.
+        injection_latency_ms: Time spent injecting context.
+        user_latency_ms: User-perceived latency for this prompt.
+        emitted_at: Event timestamp from producer.
+        created_at: Event timestamp (ingest time).
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    event_type: Literal["latency_breakdown"] = Field(
+        default="latency_breakdown",
+        description="Event type discriminator",
+    )
+    session_id: UUID = Field(..., description="Session identifier")
+    correlation_id: UUID = Field(
+        default_factory=uuid4,
+        description="Correlation ID for tracing",
+    )
+
+    # Prompt identification (UUID instead of index for uniqueness)
+    prompt_id: UUID = Field(
+        ...,
+        description="Unique prompt identifier from emitter",
+    )
+
+    # A/B Testing (denormalized for fast queries)
+    cohort: Literal["control", "treatment"] | None = Field(
+        default=None,
+        description="A/B test cohort",
+    )
+    cache_hit: bool = Field(
+        default=False,
+        description="Whether this prompt benefited from cached context",
+    )
+
+    # Internal timings (ms) - nullable as not all prompts have all timings
+    routing_latency_ms: int | None = Field(
+        default=None,
+        ge=0,
+        description="Time spent in agent routing (ms)",
+    )
+    retrieval_latency_ms: int | None = Field(
+        default=None,
+        ge=0,
+        description="Time spent retrieving context (ms)",
+    )
+    injection_latency_ms: int | None = Field(
+        default=None,
+        ge=0,
+        description="Time spent injecting context (ms)",
+    )
+
+    # User-perceived latency (required)
+    user_latency_ms: int = Field(
+        ...,
+        ge=0,
+        description="User-perceived latency for this prompt (ms)",
+    )
+
+    # Timestamps
+    emitted_at: datetime | None = Field(
+        default=None,
+        description="Event timestamp from producer (for drift analysis)",
+    )
+    created_at: datetime = Field(
+        ...,
+        description="Event timestamp (ingest time)",
+    )

omnibase_infra/services/observability/injection_effectiveness/models/model_pattern_utilization.py

@@ -0,0 +1,46 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Pattern utilization model.
+
+Represents per-pattern utilization metrics within a context utilization event.
+
+Related Tickets:
+    - OMN-1889: Emit injection metrics + utilization signal (producer)
+    - OMN-1890: Store injection metrics with corrected schema (consumer)
+"""
+
+from __future__ import annotations
+
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelPatternUtilization(BaseModel):
+    """Per-pattern utilization metrics.
+
+    Represents utilization data for a single injected pattern, enabling
+    pattern-level effectiveness analysis.
+
+    Attributes:
+        pattern_id: UUID identifier for the injected pattern.
+        utilization_score: How much of the pattern was used (0.0-1.0).
+        utilization_method: Detection method used for this pattern.
+    """
+
+    model_config = ConfigDict(frozen=True, extra="forbid", from_attributes=True)
+
+    pattern_id: UUID = Field(
+        ...,
+        description="Pattern UUID identifier from injection system",
+    )
+    utilization_score: float = Field(
+        ...,
+        ge=0.0,
+        le=1.0,
+        description="Pattern utilization score 0.0-1.0",
+    )
+    utilization_method: str = Field(
+        ...,
+        description="Method: identifier_match, semantic, or timeout",
+    )