src/core/intelligence/runner_intelligence_snapshot.py

from dataclasses import dataclass, field
from datetime import date
from typing import Optional, Dict
import uuid

@dataclass
class RunnerIntelligenceSnapshot:
    """
    Central intelligence artifact representing the current state of a runner.
    
    This object serves as the canonical interface between the pipeline and:
    - UI (Gradio)
    - Integrations (Strava / WhatsApp)
    - Observability analytics
    
    It aggregates derived signals without altering pipeline logic.
    Fields are raw values rather than translated text, allowing i18n
    at the edge (e.g. UI).
    """
    id: Optional[uuid.UUID] = field(default_factory=uuid.uuid4)

    week_start: Optional[date] = None

    # Training state and health
    training_state: Optional[str] = None
    health_signal: Optional[str] = None

    # Positioning
    positioning_status: Optional[str] = None
    positioning_change: Optional[str] = None

    # Goals
    goal_trajectory: Optional[str] = None
    goal_progress_pct: Optional[float] = None

    # Advice / Future
    next_run: Optional[str] = None
    training_type: Optional[str] = None
    training_focus: Optional[str] = None
    training_why: Optional[str] = None

    # Insights
    key_insight: Optional[str] = None
    forward_focus: Optional[str] = None

    # Quantitative Metrics
    weekly_distance_km: float = 0.0
    num_runs: int = 0
    run_count: int = 0
    consistency_score: int = 0
    avg_pace: Optional[float] = None
    avg_hr: Optional[float] = None
    
    # Structure
    structure_status: Dict = field(default_factory=dict)

    # Performance
    performance_brief: Optional[str] = None
    performance_focus: Optional[str] = None
    
    # UI Presentation Ready Fields
    performance_story: Optional[str] = None
    delta_summary: Optional[Dict[str, str]] = None
    evidence_view: Optional[str] = None
    structure_view: Optional[str] = None
    goal_status_text: Optional[str] = None
    
    # Raw DTO data for UI transparency
    trend: Dict = field(default_factory=dict)
    weekly_trend: Dict = field(default_factory=dict)
    positioning: Dict = field(default_factory=dict)
    positioning_view: Dict = field(default_factory=dict)
    goal_trajectory_data: Dict = field(default_factory=dict)
    insights: Dict = field(default_factory=dict)
    plan: Optional[str] = None
    recommendation: Dict = field(default_factory=dict)
    charts: Dict = field(default_factory=dict)
    weekly_brief: Optional[str] = None
    weekly_focus: Optional[str] = None
    weekly_snapshot: Dict = field(default_factory=dict)
    active_goal: Dict = field(default_factory=dict)
    goal_view: Dict = field(default_factory=dict)