src/core/intelligence/runner_intelligence_snapshot.py

from dataclasses import dataclass
from datetime import date
from typing import Optional


@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).
    """

    week_start: Optional[date]

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

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

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

    # Advice / Future
    next_run: Optional[str]
    training_focus: Optional[str]

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

    # Quantitative Metrics
    weekly_distance_km: float
    run_count: int
    consistency_score: int