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

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

@@ -0,0 +1,87 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Observability Models for Agent Actions Consumer.
+
+This package contains Pydantic models for the agent_actions observability
+consumer. These models define the schema for events consumed from Kafka
+and persisted to PostgreSQL.
+
+Model Categories:
+    - Envelope (strict): ModelObservabilityEnvelope - common metadata fields
+    - Payload (flexible): All other models - required fields typed, extras allowed
+
+Design Decisions:
+    - Envelope uses extra="forbid" for strict schema compliance
+    - Payload models use extra="allow" for Phase 1 flexibility
+    - All models have created_at for TTL readiness
+    - ModelExecutionLog has updated_at for lifecycle tracking
+    - Zero dict[str, Any] - use dict[str, object] when needed
+
+Idempotency Keys (per table):
+    - agent_actions: id (UUID)
+    - agent_routing_decisions: id (UUID)
+    - agent_transformation_events: id (UUID)
+    - router_performance_metrics: id (UUID)
+    - agent_detection_failures: correlation_id (UUID)
+    - agent_execution_logs: execution_id (UUID)
+
+Example:
+    >>> from omnibase_infra.services.observability.agent_actions.models import (
+    ...     ModelObservabilityEnvelope,
+    ...     ModelAgentAction,
+    ...     ModelRoutingDecision,
+    ... )
+    >>> from datetime import datetime, UTC
+    >>> from uuid import uuid4
+    >>>
+    >>> # Strict envelope validation
+    >>> envelope = ModelObservabilityEnvelope(
+    ...     event_id=uuid4(),
+    ...     event_time=datetime.now(UTC),
+    ...     producer_id="agent-observability-postgres",
+    ...     schema_version="1.0.0",
+    ... )
+    >>>
+    >>> # Flexible payload - extras allowed
+    >>> action = ModelAgentAction(
+    ...     id=uuid4(),
+    ...     correlation_id=uuid4(),
+    ...     agent_name="polymorphic-agent",
+    ...     action_type="tool_call",
+    ...     action_name="Read",
+    ...     created_at=datetime.now(UTC),
+    ...     custom_field="allowed in Phase 1",  # extra field OK
+    ... )
+"""
+
+from omnibase_infra.services.observability.agent_actions.models.model_agent_action import (
+    ModelAgentAction,
+)
+from omnibase_infra.services.observability.agent_actions.models.model_detection_failure import (
+    ModelDetectionFailure,
+)
+from omnibase_infra.services.observability.agent_actions.models.model_envelope import (
+    ModelObservabilityEnvelope,
+)
+from omnibase_infra.services.observability.agent_actions.models.model_execution_log import (
+    ModelExecutionLog,
+)
+from omnibase_infra.services.observability.agent_actions.models.model_performance_metric import (
+    ModelPerformanceMetric,
+)
+from omnibase_infra.services.observability.agent_actions.models.model_routing_decision import (
+    ModelRoutingDecision,
+)
+from omnibase_infra.services.observability.agent_actions.models.model_transformation_event import (
+    ModelTransformationEvent,
+)
+
+__all__ = [
+    "ModelAgentAction",
+    "ModelDetectionFailure",
+    "ModelExecutionLog",
+    "ModelObservabilityEnvelope",
+    "ModelPerformanceMetric",
+    "ModelRoutingDecision",
+    "ModelTransformationEvent",
+]

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

@@ -0,0 +1,142 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Agent Action Model.
+
+This module defines the model for agent action events consumed from Kafka.
+Agent actions represent individual tool calls, decisions, errors, and
+successes recorded during agent execution.
+
+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_actions
+    Unique Key: id (UUID)
+    Conflict Action: DO NOTHING (append-only audit log)
+
+Example:
+    >>> from datetime import datetime, UTC
+    >>> from uuid import uuid4
+    >>> action = ModelAgentAction(
+    ...     id=uuid4(),
+    ...     correlation_id=uuid4(),
+    ...     agent_name="polymorphic-agent",
+    ...     action_type="tool_call",
+    ...     action_name="Bash",
+    ...     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 ModelAgentAction(BaseModel):
+    """Agent action event model.
+
+    Represents a single action performed by an agent, such as a tool call,
+    decision, error, or success. Uses extra="allow" for Phase 1 flexibility
+    while ensuring required fields are typed.
+
+    Attributes:
+        id: Unique identifier for this action (idempotency key).
+        correlation_id: Request correlation ID linking related actions.
+        agent_name: Name of the agent that performed this action.
+        action_type: Type of action (tool_call, decision, error, success).
+        action_name: Specific name of the action or tool.
+        created_at: Timestamp when the action was recorded (TTL key).
+        status: Optional status of the action (started, completed, failed).
+        duration_ms: Optional duration of the action in milliseconds.
+        result: Optional result summary or outcome.
+        error_message: Optional error message if action failed.
+        metadata: Optional additional metadata about the action.
+        raw_payload: Optional complete raw payload for Phase 2 schema tightening.
+
+    Example:
+        >>> action = ModelAgentAction(
+        ...     id=uuid4(),
+        ...     correlation_id=uuid4(),
+        ...     agent_name="code-reviewer",
+        ...     action_type="decision",
+        ...     action_name="approve_pr",
+        ...     created_at=datetime.now(UTC),
+        ...     status="completed",
+        ...     duration_ms=1234,
+        ... )
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        from_attributes=True,
+    )
+
+    # ---- Required Fields ----
+    id: UUID = Field(
+        ...,
+        description="Unique identifier for this action (idempotency key).",
+    )
+    correlation_id: UUID = Field(
+        ...,
+        description="Request correlation ID linking related actions.",
+    )
+    agent_name: str = Field(  # ONEX_EXCLUDE: entity_reference - external payload
+        ..., description="Name of the agent that performed this action."
+    )
+    action_type: str = Field(
+        ...,
+        description="Type of action (tool_call, decision, error, success).",
+    )
+    action_name: str = Field(  # ONEX_EXCLUDE: entity_reference - external payload
+        ..., description="Specific name of the action or tool."
+    )
+    created_at: datetime = Field(
+        ...,
+        description="Timestamp when the action was recorded (TTL key).",
+    )
+
+    # ---- Optional Fields ----
+    status: str | None = Field(
+        default=None,
+        description="Status of the action (started, completed, failed).",
+    )
+    duration_ms: int | None = Field(
+        default=None,
+        description="Duration of the action in milliseconds.",
+    )
+    result: str | None = Field(
+        default=None,
+        description="Result summary or outcome of the action.",
+    )
+    error_message: str | None = Field(
+        default=None,
+        description="Error message if the action failed.",
+    )
+    metadata: dict[str, JsonType] | None = Field(
+        default=None,
+        description="Additional metadata about the action.",
+    )
+    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]
+        status_part = f", status={self.status}" if self.status else ""
+        return (
+            f"AgentAction(id={id_short}, agent={self.agent_name}, "
+            f"type={self.action_type}, action={self.action_name}{status_part})"
+        )
+
+
+__all__ = ["ModelAgentAction"]

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

@@ -0,0 +1,125 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Detection Failure Model.
+
+This module defines the model for agent detection failure events consumed
+from Kafka. Detection failures occur when the routing system cannot
+determine an appropriate agent for a request.
+
+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_detection_failures
+    Unique Key: correlation_id (UUID) - one failure per correlation
+    Conflict Action: DO NOTHING
+
+Example:
+    >>> from datetime import datetime, UTC
+    >>> from uuid import uuid4
+    >>> failure = ModelDetectionFailure(
+    ...     correlation_id=uuid4(),
+    ...     failure_reason="No matching agent pattern",
+    ...     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 ModelDetectionFailure(BaseModel):
+    """Agent detection failure event model.
+
+    Represents a failure to detect or route to an appropriate agent.
+    Used for analyzing routing coverage gaps and improving agent matching.
+
+    Attributes:
+        correlation_id: Request correlation ID (idempotency key - one per correlation).
+        failure_reason: Reason the detection failed.
+        created_at: Timestamp when the failure was recorded (TTL key).
+        request_summary: Optional summary of the request that failed routing.
+        attempted_patterns: Optional list of patterns attempted during detection.
+        fallback_used: Optional name of fallback agent if one was used.
+        error_code: Optional error code for categorization.
+        metadata: Optional additional metadata about the failure.
+        raw_payload: Optional complete raw payload for Phase 2 schema tightening.
+
+    Example:
+        >>> failure = ModelDetectionFailure(
+        ...     correlation_id=uuid4(),
+        ...     failure_reason="Confidence below threshold (0.3 < 0.5)",
+        ...     created_at=datetime.now(UTC),
+        ...     attempted_patterns=["code-review", "testing", "infrastructure"],
+        ...     fallback_used="polymorphic-agent",
+        ... )
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        from_attributes=True,
+    )
+
+    # ---- Required Fields ----
+    correlation_id: UUID = Field(
+        ...,
+        description="Request correlation ID (idempotency key - one per correlation).",
+    )
+    failure_reason: str = Field(
+        ...,
+        description="Reason the detection failed.",
+    )
+    created_at: datetime = Field(
+        ...,
+        description="Timestamp when the failure was recorded (TTL key).",
+    )
+
+    # ---- Optional Fields ----
+    request_summary: str | None = Field(
+        default=None,
+        description="Summary of the request that failed routing.",
+    )
+    attempted_patterns: list[str] | None = Field(
+        default=None,
+        description="List of patterns attempted during detection.",
+    )
+    fallback_used: str | None = Field(
+        default=None,
+        description="Name of fallback agent if one was used.",
+    )
+    error_code: str | None = Field(
+        default=None,
+        description="Error code for categorization.",
+    )
+    metadata: dict[str, JsonType] | None = Field(
+        default=None,
+        description="Additional metadata about the failure.",
+    )
+    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.
+        """
+        corr_short = str(self.correlation_id)[:8]
+        fallback_part = f", fallback={self.fallback_used}" if self.fallback_used else ""
+        # Truncate failure_reason to 50 chars for log readability
+        reason = (
+            self.failure_reason[:47] + "..."
+            if len(self.failure_reason) > 50
+            else self.failure_reason
+        )
+        return f"DetectionFailure(corr={corr_short}, reason={reason!r}{fallback_part})"
+
+
+__all__ = ["ModelDetectionFailure"]

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

@@ -0,0 +1,85 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Observability Envelope Model.
+
+This module defines the strict envelope model for all observability events.
+The envelope contains common metadata fields that must be present on every
+event consumed by the agent_actions observability consumer.
+
+Design Decisions:
+    - extra="forbid": Strict validation ensures envelope schema compliance
+    - All fields are required or have explicit defaults
+    - correlation_id is optional (some events may not have request context)
+
+Thread Safety:
+    ModelObservabilityEnvelope is immutable (frozen=True) after creation,
+    making it thread-safe for concurrent read access.
+
+Example:
+    >>> from datetime import datetime, UTC
+    >>> from uuid import uuid4
+    >>> envelope = ModelObservabilityEnvelope(
+    ...     event_id=uuid4(),
+    ...     event_time=datetime.now(UTC),
+    ...     producer_id="agent-observability-postgres",
+    ...     schema_version="1.0.0",
+    ...     correlation_id=uuid4(),
+    ... )
+"""
+
+from datetime import datetime
+from uuid import UUID
+
+from pydantic import BaseModel, ConfigDict, Field
+
+
+class ModelObservabilityEnvelope(BaseModel):
+    """Strict envelope for observability events.
+
+    All events must have these fields. The envelope is validated with
+    extra="forbid" to ensure no unexpected fields are present.
+
+    Attributes:
+        event_id: Unique identifier for this specific event instance.
+        event_time: Timestamp when the event was produced.
+        producer_id: Identifier of the service/component that produced the event.
+        schema_version: Version of the event schema for evolution tracking.
+        correlation_id: Optional request correlation ID for distributed tracing.
+
+    Example:
+        >>> envelope = ModelObservabilityEnvelope(
+        ...     event_id=uuid4(),
+        ...     event_time=datetime.now(UTC),
+        ...     producer_id="claude-code-agent",
+        ...     schema_version="1.0.0",
+        ... )
+    """
+
+    model_config = ConfigDict(
+        frozen=True,
+        extra="forbid",
+        from_attributes=True,
+    )
+
+    event_id: UUID = Field(
+        ...,
+        description="Unique identifier for this specific event instance.",
+    )
+    event_time: datetime = Field(
+        ...,
+        description="Timestamp when the event was produced.",
+    )
+    producer_id: str = Field(  # ONEX_EXCLUDE: string_id - external service identifier
+        ..., description="Identifier of the service/component that produced the event."
+    )
+    schema_version: str = Field(
+        ...,
+        description="Version of the event schema for evolution tracking.",
+    )
+    correlation_id: UUID | None = Field(
+        default=None,
+        description="Optional request correlation ID for distributed tracing.",
+    )
+
+
+__all__ = ["ModelObservabilityEnvelope"]

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

@@ -0,0 +1,159 @@
+# SPDX-License-Identifier: MIT
+# Copyright (c) 2025 OmniNode Team
+"""Execution Log Model.
+
+This module defines the model for agent execution log events consumed
+from Kafka. Execution logs track the full lifecycle of an agent execution,
+from start to completion (or failure).
+
+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 AND updated_at: Both required for lifecycle tracking and TTL
+    - TTL keys off updated_at (not created_at) to avoid deleting in-flight executions
+
+Idempotency:
+    Table: agent_execution_logs
+    Unique Key: execution_id (UUID)
+    Conflict Action: DO UPDATE (lifecycle record - started -> completed)
+
+Example:
+    >>> from datetime import datetime, UTC
+    >>> from uuid import uuid4
+    >>> log = ModelExecutionLog(
+    ...     execution_id=uuid4(),
+    ...     correlation_id=uuid4(),
+    ...     agent_name="api-architect",
+    ...     status="completed",
+    ...     created_at=datetime.now(UTC),
+    ...     updated_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 ModelExecutionLog(BaseModel):
+    """Agent execution log event model.
+
+    Represents the lifecycle of an agent execution, from start to completion.
+    Unlike other observability models, this supports upsert semantics to track
+    status transitions (started -> running -> completed/failed).
+
+    Attributes:
+        execution_id: Unique identifier for this execution (idempotency key).
+        correlation_id: Request correlation ID linking related events.
+        agent_name: Name of the agent being executed.
+        status: Current status of the execution (started, running, completed, failed).
+        created_at: Timestamp when the execution started.
+        updated_at: Timestamp of last status update (TTL key for lifecycle records).
+        started_at: Optional explicit start timestamp.
+        completed_at: Optional completion timestamp.
+        duration_ms: Optional total duration in milliseconds.
+        exit_code: Optional exit code if execution completed.
+        error_message: Optional error message if execution failed.
+        input_summary: Optional summary of execution input.
+        output_summary: Optional summary of execution output.
+        metadata: Optional additional metadata about the execution.
+        raw_payload: Optional complete raw payload for Phase 2 schema tightening.
+
+    Example:
+        >>> log = ModelExecutionLog(
+        ...     execution_id=uuid4(),
+        ...     correlation_id=uuid4(),
+        ...     agent_name="testing",
+        ...     status="completed",
+        ...     created_at=datetime.now(UTC),
+        ...     updated_at=datetime.now(UTC),
+        ...     duration_ms=5432,
+        ...     exit_code=0,
+        ... )
+    """
+
+    model_config = ConfigDict(
+        extra="allow",
+        from_attributes=True,
+    )
+
+    # ---- Required Fields ----
+    execution_id: UUID = Field(
+        ...,
+        description="Unique identifier for this execution (idempotency key).",
+    )
+    correlation_id: UUID = Field(
+        ...,
+        description="Request correlation ID linking related events.",
+    )
+    agent_name: str = Field(  # ONEX_EXCLUDE: entity_reference - external payload
+        ..., description="Name of the agent being executed."
+    )
+    status: str = Field(  # ONEX_EXCLUDE: string_status - external payload
+        ..., description="Current status (started, running, completed, failed)."
+    )
+    created_at: datetime = Field(
+        ...,
+        description="Timestamp when the execution started.",
+    )
+    updated_at: datetime = Field(
+        ...,
+        description="Timestamp of last status update (TTL key for lifecycle records).",
+    )
+
+    # ---- Optional Fields ----
+    started_at: datetime | None = Field(
+        default=None,
+        description="Explicit start timestamp.",
+    )
+    completed_at: datetime | None = Field(
+        default=None,
+        description="Completion timestamp.",
+    )
+    duration_ms: int | None = Field(
+        default=None,
+        description="Total duration in milliseconds.",
+    )
+    exit_code: int | None = Field(
+        default=None,
+        description="Exit code if execution completed.",
+    )
+    error_message: str | None = Field(
+        default=None,
+        description="Error message if execution failed.",
+    )
+    input_summary: str | None = Field(
+        default=None,
+        description="Summary of execution input.",
+    )
+    output_summary: str | None = Field(
+        default=None,
+        description="Summary of execution output.",
+    )
+    metadata: dict[str, JsonType] | None = Field(
+        default=None,
+        description="Additional metadata about the execution.",
+    )
+    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.
+        """
+        exec_short = str(self.execution_id)[:8]
+        duration_part = f", duration={self.duration_ms}ms" if self.duration_ms else ""
+        exit_part = f", exit={self.exit_code}" if self.exit_code is not None else ""
+        return (
+            f"ExecutionLog(id={exec_short}, agent={self.agent_name}, "
+            f"status={self.status}{duration_part}{exit_part})"
+        )
+
+
+__all__ = ["ModelExecutionLog"]