omnibase_infra 0.2.8__py3-none-any.whl → 0.2.9__py3-none-any.whl

omnibase_infra/services/observability/agent_actions/models/model_performance_metric.py

@@ -0,0 +1,130 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Performance Metric Model.
+
+This module defines the model for router performance metrics consumed
+from Kafka. Performance metrics capture timing and throughput data
+for the agent routing system.
+
+Design Decisions:
+    - extra="allow": Phase 1 flexibility - required fields typed, extras preserved
+    - raw_payload: Optional field to preserve complete payload for schema tightening
+    - created_at: Required for TTL cleanup job (Phase 2)
+
+Idempotency:
+    Table: router_performance_metrics
+    Unique Key: id (UUID)
+    Conflict Action: DO NOTHING (append-only time-series)
+
+Example:
+    >>> from datetime import datetime, UTC
+    >>> from uuid import uuid4
+    >>> metric = ModelPerformanceMetric(
+    ...     id=uuid4(),
+    ...     metric_name="routing_latency_ms",
+    ...     metric_value=45.2,
+    ...     created_at=datetime.now(UTC),
+    ... )
+"""
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_core.types import JsonType
+
+
+class ModelPerformanceMetric(BaseModel):
+    """Router performance metric model.
+
+    Represents a single performance metric data point for the routing
+    system. Used for monitoring latency, throughput, and resource usage.
+
+    Attributes:
+        id: Unique identifier for this metric (idempotency key).
+        metric_name: Name of the metric being recorded.
+        metric_value: Numeric value of the metric.
+        created_at: Timestamp when the metric was recorded (TTL key).
+        correlation_id: Optional request correlation ID for trace-specific metrics.
+        unit: Optional unit of measurement (ms, bytes, count, etc.).
+        agent_name: Optional agent name if metric is agent-specific.
+        labels: Optional key-value labels for metric dimensionality.
+        metadata: Optional additional metadata about the metric.
+        raw_payload: Optional complete raw payload for Phase 2 schema tightening.
+
+    Example:
+        >>> metric = ModelPerformanceMetric(
+        ...     id=uuid4(),
+        ...     metric_name="agent_selection_time_ms",
+        ...     metric_value=12.5,
+        ...     created_at=datetime.now(UTC),
+        ...     unit="ms",
+        ...     agent_name="polymorphic-agent",
+        ...     labels={"operation": "route", "status": "success"},
+        ... )
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        from_attributes=True,
+    )
+
+    # ---- Required Fields ----
+    id: UUID = Field(
+        ...,
+        description="Unique identifier for this metric (idempotency key).",
+    )
+    metric_name: str = Field(  # ONEX_EXCLUDE: entity_reference - external payload
+        ..., description="Name of the metric being recorded."
+    )
+    metric_value: float = Field(
+        ...,
+        description="Numeric value of the metric.",
+    )
+    created_at: datetime = Field(
+        ...,
+        description="Timestamp when the metric was recorded (TTL key).",
+    )
+
+    # ---- Optional Fields ----
+    correlation_id: UUID | None = Field(
+        default=None,
+        description="Request correlation ID for trace-specific metrics.",
+    )
+    unit: str | None = Field(
+        default=None,
+        description="Unit of measurement (ms, bytes, count, etc.).",
+    )
+    agent_name: str | None = Field(
+        default=None,
+        description="Agent name if metric is agent-specific.",
+    )
+    labels: dict[str, str] | None = Field(
+        default=None,
+        description="Key-value labels for metric dimensionality.",
+    )
+    metadata: dict[str, JsonType] | None = Field(
+        default=None,
+        description="Additional metadata about the metric.",
+    )
+    raw_payload: dict[str, JsonType] | None = Field(
+        default=None,
+        description="Complete raw payload for Phase 2 schema tightening.",
+    )
+
+    def __str__(self) -> str:
+        """Return concise string representation for logging.
+
+        Includes key identifying fields but excludes metadata and raw_payload.
+        """
+        id_short = str(self.id)[:8]
+        unit_part = f" {self.unit}" if self.unit else ""
+        agent_part = f", agent={self.agent_name}" if self.agent_name else ""
+        return (
+            f"PerformanceMetric(id={id_short}, "
+            f"{self.metric_name}={self.metric_value}{unit_part}{agent_part})"
+        )
+
+
+__all__ = ["ModelPerformanceMetric"]

omnibase_infra/services/observability/agent_actions/models/model_routing_decision.py

@@ -0,0 +1,138 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Routing Decision Model.
+
+This module defines the model for agent routing decision events consumed
+from Kafka. Routing decisions capture the selection logic when an agent
+is chosen to handle a request, including confidence scores and alternatives.
+
+Design Decisions:
+    - extra="allow": Phase 1 flexibility - required fields typed, extras preserved
+    - raw_payload: Optional field to preserve complete payload for schema tightening
+    - created_at: Required for TTL cleanup job (Phase 2)
+
+Idempotency:
+    Table: agent_routing_decisions
+    Unique Key: id (UUID)
+    Conflict Action: DO NOTHING (append-only audit log)
+
+Example:
+    >>> from datetime import datetime, UTC
+    >>> from uuid import uuid4
+    >>> decision = ModelRoutingDecision(
+    ...     id=uuid4(),
+    ...     correlation_id=uuid4(),
+    ...     selected_agent="api-architect",
+    ...     confidence_score=0.95,
+    ...     created_at=datetime.now(UTC),
+    ... )
+"""
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_core.types import JsonType
+
+
+class ModelRoutingDecision(BaseModel):
+    """Agent routing decision event model.
+
+    Represents the routing decision made when selecting an agent to handle
+    a request. Captures the selected agent, confidence score, and alternatives
+    considered during routing.
+
+    Attributes:
+        id: Unique identifier for this decision (idempotency key).
+        correlation_id: Request correlation ID linking related events.
+        selected_agent: Name of the agent selected to handle the request.
+        confidence_score: Confidence score (0.0-1.0) for the selection.
+        created_at: Timestamp when the decision was made (TTL key).
+        request_type: Optional type of request being routed.
+        alternatives: Optional list of alternative agents considered.
+        routing_reason: Optional explanation for the routing decision.
+        domain: Optional domain classification for the request.
+        metadata: Optional additional metadata about the decision.
+        raw_payload: Optional complete raw payload for Phase 2 schema tightening.
+
+    Example:
+        >>> decision = ModelRoutingDecision(
+        ...     id=uuid4(),
+        ...     correlation_id=uuid4(),
+        ...     selected_agent="polymorphic-agent",
+        ...     confidence_score=0.87,
+        ...     created_at=datetime.now(UTC),
+        ...     routing_reason="Matched domain pattern for infrastructure tasks",
+        ... )
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        from_attributes=True,
+    )
+
+    # ---- Required Fields ----
+    id: UUID = Field(
+        ...,
+        description="Unique identifier for this decision (idempotency key).",
+    )
+    correlation_id: UUID = Field(
+        ...,
+        description="Request correlation ID linking related events.",
+    )
+    selected_agent: str = Field(
+        ...,
+        description="Name of the agent selected to handle the request.",
+    )
+    confidence_score: float = Field(
+        ...,
+        ge=0.0,
+        le=1.0,
+        description="Confidence score for the selection. Must be between 0.0 (no confidence) and 1.0 (full confidence).",
+    )
+    created_at: datetime = Field(
+        ...,
+        description="Timestamp when the decision was made (TTL key).",
+    )
+
+    # ---- Optional Fields ----
+    request_type: str | None = Field(
+        default=None,
+        description="Type of request being routed.",
+    )
+    alternatives: list[str] | None = Field(
+        default=None,
+        description="List of alternative agents considered.",
+    )
+    routing_reason: str | None = Field(
+        default=None,
+        description="Explanation for the routing decision.",
+    )
+    domain: str | None = Field(
+        default=None,
+        description="Domain classification for the request.",
+    )
+    metadata: dict[str, JsonType] | None = Field(
+        default=None,
+        description="Additional metadata about the decision.",
+    )
+    raw_payload: dict[str, JsonType] | None = Field(
+        default=None,
+        description="Complete raw payload for Phase 2 schema tightening.",
+    )
+
+    def __str__(self) -> str:
+        """Return concise string representation for logging.
+
+        Includes key identifying fields but excludes metadata and raw_payload.
+        """
+        id_short = str(self.id)[:8]
+        domain_part = f", domain={self.domain}" if self.domain else ""
+        return (
+            f"RoutingDecision(id={id_short}, agent={self.selected_agent}, "
+            f"confidence={self.confidence_score:.2f}{domain_part})"
+        )
+
+
+__all__ = ["ModelRoutingDecision"]

omnibase_infra/services/observability/agent_actions/models/model_transformation_event.py

@@ -0,0 +1,124 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Transformation Event Model.
+
+This module defines the model for agent transformation events consumed
+from Kafka. Transformation events capture when an agent transforms into
+a specialized form (e.g., polymorphic agent becoming api-architect).
+
+Design Decisions:
+    - extra="allow": Phase 1 flexibility - required fields typed, extras preserved
+    - raw_payload: Optional field to preserve complete payload for schema tightening
+    - created_at: Required for TTL cleanup job (Phase 2)
+
+Idempotency:
+    Table: agent_transformation_events
+    Unique Key: id (UUID)
+    Conflict Action: DO NOTHING (append-only audit log)
+
+Example:
+    >>> from datetime import datetime, UTC
+    >>> from uuid import uuid4
+    >>> event = ModelTransformationEvent(
+    ...     id=uuid4(),
+    ...     correlation_id=uuid4(),
+    ...     source_agent="polymorphic-agent",
+    ...     target_agent="api-architect",
+    ...     created_at=datetime.now(UTC),
+    ... )
+"""
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+from omnibase_core.types import JsonType
+
+
+class ModelTransformationEvent(BaseModel):
+    """Agent transformation event model.
+
+    Represents a transformation from one agent type to another, typically
+    when a polymorphic agent specializes into a domain-specific agent.
+
+    Attributes:
+        id: Unique identifier for this event (idempotency key).
+        correlation_id: Request correlation ID linking related events.
+        source_agent: Name of the original agent before transformation.
+        target_agent: Name of the agent after transformation.
+        created_at: Timestamp when the transformation occurred (TTL key).
+        trigger: Optional trigger that caused the transformation.
+        context: Optional context information about the transformation.
+        metadata: Optional additional metadata about the transformation.
+        raw_payload: Optional complete raw payload for Phase 2 schema tightening.
+
+    Example:
+        >>> event = ModelTransformationEvent(
+        ...     id=uuid4(),
+        ...     correlation_id=uuid4(),
+        ...     source_agent="polymorphic-agent",
+        ...     target_agent="debug-database",
+        ...     created_at=datetime.now(UTC),
+        ...     trigger="User requested database debugging",
+        ... )
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        from_attributes=True,
+    )
+
+    # ---- Required Fields ----
+    id: UUID = Field(
+        ...,
+        description="Unique identifier for this event (idempotency key).",
+    )
+    correlation_id: UUID = Field(
+        ...,
+        description="Request correlation ID linking related events.",
+    )
+    source_agent: str = Field(
+        ...,
+        description="Name of the original agent before transformation.",
+    )
+    target_agent: str = Field(
+        ...,
+        description="Name of the agent after transformation.",
+    )
+    created_at: datetime = Field(
+        ...,
+        description="Timestamp when the transformation occurred (TTL key).",
+    )
+
+    # ---- Optional Fields ----
+    trigger: str | None = Field(
+        default=None,
+        description="Trigger that caused the transformation.",
+    )
+    context: str | None = Field(
+        default=None,
+        description="Context information about the transformation.",
+    )
+    metadata: dict[str, JsonType] | None = Field(
+        default=None,
+        description="Additional metadata about the transformation.",
+    )
+    raw_payload: dict[str, JsonType] | None = Field(
+        default=None,
+        description="Complete raw payload for Phase 2 schema tightening.",
+    )
+
+    def __str__(self) -> str:
+        """Return concise string representation for logging.
+
+        Includes key identifying fields but excludes metadata and raw_payload.
+        """
+        id_short = str(self.id)[:8]
+        return (
+            f"TransformationEvent(id={id_short}, "
+            f"source={self.source_agent}, target={self.target_agent})"
+        )
+
+
+__all__ = ["ModelTransformationEvent"]

omnibase_infra/services/observability/agent_actions/tests/__init__.py

@@ -0,0 +1,20 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Unit tests for agent_actions observability consumer.
+
+This package contains unit tests for the agent_actions observability
+consumer, including model validation, PostgreSQL writer, and Kafka consumer.
+
+Test Categories:
+    - test_models: Model validation (strict envelope, flexible payloads)
+    - test_writer: PostgreSQL writer with idempotency and circuit breaker
+    - test_consumer: Kafka consumer with offset tracking and health checks
+
+Running Tests:
+    pytest src/omnibase_infra/services/observability/agent_actions/tests/
+
+Related Tickets:
+    - OMN-1743: Migrate agent_actions_consumer to omnibase_infra
+"""
+
+__all__: list[str] = []