feat: orchestrate grounded recommendations

backend/app/pipeline/event.py

@@ -0,0 +1,62 @@
+"""Application-owned events emitted by the recommendation pipeline."""
+
+from dataclasses import dataclass, field
+from typing import Literal
+
+from app.domain.models import Track
+
+
+@dataclass(frozen=True)
+class PipelineMetadataEvent:
+    """Describe the interpreted request before track results."""
+
+    request_id: str
+    intent_summary: str
+    candidate_count: int
+    type: Literal["metadata"] = field(default="metadata", init=False)
+
+
+@dataclass(frozen=True)
+class PipelineTrackEvent:
+    """Carry one ranked, grounded recommendation."""
+
+    rank: int
+    track: Track
+    justification: str
+    type: Literal["track"] = field(default="track", init=False)
+
+
+@dataclass(frozen=True)
+class PipelineWarningEvent:
+    """Report a non-terminal degradation."""
+
+    code: str
+    message: str
+    type: Literal["warning"] = field(default="warning", init=False)
+
+
+@dataclass(frozen=True)
+class PipelineErrorEvent:
+    """Report a terminal recommendation failure."""
+
+    code: str
+    message: str
+    type: Literal["error"] = field(default="error", init=False)
+
+
+@dataclass(frozen=True)
+class PipelineDoneEvent:
+    """Report final track count and elapsed time."""
+
+    track_count: int
+    total_ms: int
+    type: Literal["done"] = field(default="done", init=False)
+
+
+type PipelineEvent = (
+    PipelineMetadataEvent
+    | PipelineTrackEvent
+    | PipelineWarningEvent
+    | PipelineErrorEvent
+    | PipelineDoneEvent
+)