HF Space deploy snapshot (minimal allow-list)

Dockerfile

@@ -0,0 +1,27 @@
+FROM python:3.12-slim
+
+ENV PYTHONDONTWRITEBYTECODE=1 \
+    PYTHONUNBUFFERED=1 \
+    PIP_NO_CACHE_DIR=1 \
+    HF_SPACE=true \
+    STORAGE_ENABLED=false
+
+WORKDIR /app
+
+# System deps (keep minimal; add build-essential only if you need wheels compiled)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    git \
+    && rm -rf /var/lib/apt/lists/*
+
+# Copy code
+COPY . /app
+
+# Install dependencies
+# Prefer requirements.txt if you have it; otherwise generate one from pyproject for Docker usage.
+RUN pip install --upgrade pip \
+    && pip install -r requirements.txt
+
+# HuggingFace Spaces uses port 7860
+EXPOSE 7860
+
+CMD ["python", "app.py"]

README.md

@@ -0,0 +1,19 @@
+---
+title: Runner Agentic Intelligence
+emoji: 🏃‍♂️
+colorFrom: blue
+colorTo: green
+sdk: docker
+pinned: false
+---
+
+# Runner Agentic Intelligence (Public Preview)
+
+Upload your Strava exports (TCX / FIT / FIT.GZ) to generate insights and a weekly plan.
+
+**Notes**
+- This is an experimental demo
+- Session data is temporary
+- Not medical advice
+
+For local installation and full project docs, see the GitHub repository.

app.py

@@ -0,0 +1,13 @@
+"""Docker / HuggingFace Spaces entrypoint.
+
+This file intentionally does NOT force demo-mode defaults.
+
+- In HuggingFace Spaces / Docker, set env vars (e.g., HF_SPACE=true, STORAGE_ENABLED=false)
+  via Space Settings or Dockerfile ENV.
+- For local development, you can run `python src/app/gradio_app.py` directly.
+"""
+
+from src._app.gradio_app import launch_app
+
+if __name__ == "__main__":
+    launch_app()

configs/prompt_templates.json

@@ -0,0 +1,76 @@
+{
+    "templates": [
+        {
+            "id": "insights_latest",
+            "category": "Insights",
+            "label": "Latest Run Insights",
+            "description": "Summarise the most recent run with actionable coaching insights.",
+            "templateBody": "Based on the most recent uploaded run(s), provide:\n- key observations that materially affect training decisions,\n- any elevated risk signals,\n- the single primary lever I should focus on next.",
+            "example": "Latest Run Insights — key observations, risk signal, primary lever"
+        },
+        {
+            "id": "insights_trends",
+            "category": "Insights",
+            "label": "Training Trends",
+            "description": "Identify performance and fatigue trends across recent runs.",
+            "templateBody": "Look at my recent runs and identify trends in pace, consistency, and fatigue. Highlight anything that should influence my next training decisions.",
+            "example": "Training Trends — how my pacing and fatigue have changed recently"
+        },
+        {
+            "id": "insights_risk",
+            "category": "Insights",
+            "label": "Risk Assessment",
+            "description": "Check for injury or fatigue risk based on recent data.",
+            "templateBody": "Based on my recent runs, assess whether there are any injury, fatigue, or stagnation risks. If none, explicitly state that no elevated risk is detected.",
+            "example": "Risk Assessment — is there any elevated injury or fatigue risk?"
+        },
+        {
+            "id": "plan_weekly_standard",
+            "category": "Weekly Plan",
+            "label": "Standard Weekly Plan",
+            "description": "Generate a balanced 7-day running plan based on recent data.",
+            "templateBody": "Using my recent runs and current fitness, generate a 7-day running plan (Monday–Sunday) with a brief summary, daily sessions, and one focus reminder for the week.",
+            "example": "Weekly Plan — generate a full week plan from my recent runs"
+        },
+        {
+            "id": "plan_weekly_constraints",
+            "category": "Weekly Plan",
+            "label": "Weekly Plan with Constraints",
+            "description": "Generate a weekly plan with explicit constraints.",
+            "templateBody": "Generate a weekly running plan with the following constraints:\n- no hard runs on weekdays,\n- limited total training time,\n- prioritise injury risk reduction.\nExplain any trade-offs made.",
+            "example": "Plan with Constraints — no hard runs on weekdays, limited time"
+        },
+        {
+            "id": "history_recent_insights",
+            "category": "History",
+            "label": "Recent Stored Insights",
+            "description": "Retrieve and summarise recently persisted insights.",
+            "templateBody": "Retrieve the most recent stored insights and summarise them with timestamps and key messages.",
+            "example": "Recent Stored Insights — show the last 4 insights"
+        },
+        {
+            "id": "history_insights_by_date",
+            "category": "History",
+            "label": "Insights by Date",
+            "description": "Retrieve stored insights for a specific date or range.",
+            "templateBody": "Retrieve stored insights for the specified date or date range and summarise the key coaching messages.",
+            "example": "Insights by Date — show insights from last week"
+        },
+        {
+            "id": "system_router_decision",
+            "category": "System",
+            "label": "Router Decision Explanation",
+            "description": "Explain how the system routed the last request.",
+            "templateBody": "For the most recent analysis, explain which route was chosen (chat or chart) and why. Include any fallback reason if applicable.",
+            "example": "Router Decision — what route was chosen and why?"
+        },
+        {
+            "id": "chat_load_prior_insights",
+            "category": "Chat",
+            "label": "Load Prior Insights",
+            "description": "Force the assistant to include recent stored insights in its reasoning.",
+            "templateBody": "Before answering, load my recent stored insights and include them explicitly in your reasoning.",
+            "example": "Load prior insights before answering my question"
+        }
+    ]
+}

docs/readme_hf.md

@@ -0,0 +1,19 @@
+---
+title: Runner Agentic Intelligence
+emoji: 🏃‍♂️
+colorFrom: blue
+colorTo: green
+sdk: docker
+pinned: false
+---
+
+# Runner Agentic Intelligence (Public Preview)
+
+Upload your Strava exports (TCX / FIT / FIT.GZ) to generate insights and a weekly plan.
+
+**Notes**
+- This is an experimental demo
+- Session data is temporary
+- Not medical advice
+
+For local installation and full project docs, see the GitHub repository.

pyproject.toml

@@ -0,0 +1,56 @@
+[project]
+name = "runner-agentic-intelligence"
+version = "0.1.0"
+description = "Agentic Intelligence for Runners MVP — Strava/Apple Health ingestion + insights + weekly plans powered by multi-agent system."
+authors = [
+    { name = "Alexandre Franco" }
+]
+readme = "README.md"
+requires-python = ">=3.10"
+
+# Runtime dependencies
+dependencies = [
+    "gradio",
+    "matplotlib",
+    "lxml",
+    "gpxpy",
+    "pandas", # useful for aggregations if needed
+    "numpy", # lightweight processing
+    "google-adk>=1.18.0",
+    "opentelemetry-instrumentation-google-genai>=0.4b0",
+    "vertexai>=1.43.0",
+    "black>=25.11.0",
+    "flake8>=7.3.0",
+    "litellm",
+    "pydantic>=2.11.10",
+    "fitdecode>=0.10.0",
+    "jsonschema>=4.21.0",
+]
+
+[project.optional-dependencies]
+dev = [
+    "black",
+    "flake8",
+    "pytest",
+    "pytest-asyncio",
+]
+
+[tool.black]
+line-length = 100
+target-version = ["py310"]
+
+[tool.flake8]
+max-line-length = 100
+extend-ignore = ["E203"]
+exclude = [
+    ".venv",
+    "build",
+    "dist",
+    "__pycache__",
+]
+
+[tool.uv]
+# ensures uv uses a dedicated .venv folder inside project
+# (HF Spaces ignores local venvs but uv handles it seamlessly)
+index-strategy = "first-index"
+cache-dir = ".uv-cache"

requirements.txt

@@ -0,0 +1,150 @@
+aiofiles==24.1.0
+aiohappyeyeballs==2.6.1
+aiohttp==3.13.3
+aiosignal==1.4.0
+alembic==1.17.2
+annotated-doc==0.0.4
+annotated-types==0.7.0
+anyio==4.11.0
+attrs==25.4.0
+authlib==1.6.5
+black==25.11.0
+brotli==1.2.0
+cachetools==6.2.2
+certifi==2025.11.12
+cffi==2.0.0
+charset-normalizer==3.4.4
+click==8.3.1
+cloudpickle==3.1.2
+contourpy==1.3.3
+cryptography==46.0.3
+cycler==0.12.1
+distro==1.9.0
+docstring-parser==0.17.0
+fastapi==0.121.2
+fastuuid==0.14.0
+ffmpy==1.0.0
+filelock==3.20.0
+fitdecode==0.11.0
+flake8==7.3.0
+fonttools==4.60.1
+frozenlist==1.8.0
+fsspec==2025.10.0
+googleapis-common-protos==1.72.0
+gpxpy==1.6.2
+gradio==5.49.1
+gradio-client==1.13.3
+graphviz==0.21
+greenlet==3.2.4
+groovy==0.1.2
+grpc-interceptor==0.15.4
+grpcio==1.76.0
+grpcio-status==1.76.0
+h11==0.16.0
+hf-xet==1.2.0
+httpcore==1.0.9
+httplib2==0.31.0
+httpx==0.28.1
+httpx-sse==0.4.3
+huggingface-hub==1.1.4
+idna==3.11
+importlib-metadata==8.7.0
+iniconfig==2.3.0
+jinja2==3.1.6
+jiter==0.12.0
+jsonschema==4.25.1
+jsonschema-specifications==2025.9.1
+kiwisolver==1.4.9
+litellm==1.81.3
+lxml==6.0.2
+mako==1.3.10
+markdown-it-py==4.0.0
+markupsafe==3.0.3
+matplotlib==3.10.7
+mccabe==0.7.0
+mcp==1.21.2
+mdurl==0.1.2
+multidict==6.7.1
+mypy-extensions==1.1.0
+numpy==2.3.5
+openai==2.15.0
+opentelemetry-api==1.37.0
+opentelemetry-exporter-gcp-logging==1.11.0a0
+opentelemetry-exporter-gcp-monitoring==1.11.0a0
+opentelemetry-exporter-gcp-trace==1.11.0
+opentelemetry-exporter-otlp-proto-common==1.37.0
+opentelemetry-exporter-otlp-proto-http==1.37.0
+opentelemetry-instrumentation==0.58b0
+opentelemetry-proto==1.37.0
+opentelemetry-resourcedetector-gcp==1.11.0a0
+opentelemetry-sdk==1.37.0
+opentelemetry-semantic-conventions==0.58b0
+opentelemetry-util-genai==0.2b0
+orjson==3.11.4
+packaging==25.0
+pandas==2.3.3
+pathspec==0.12.1
+pillow==11.3.0
+platformdirs==4.5.0
+pluggy==1.6.0
+propcache==0.4.1
+proto-plus==1.26.1
+protobuf==6.33.1
+pyasn1==0.6.1
+pyasn1-modules==0.4.2
+pycodestyle==2.14.0
+pycparser==2.23
+pydantic==2.11.10
+pydantic-core==2.33.2
+pydantic-settings==2.12.0
+pydub==0.25.1
+pyflakes==3.4.0
+pygments==2.19.2
+pyjwt==2.10.1
+pyparsing==3.2.5
+pytest==9.0.2
+pytest-asyncio==1.3.0
+python-dateutil==2.9.0.post0
+python-dotenv==1.2.1
+python-multipart==0.0.20
+pytokens==0.3.0
+pytz==2025.2
+pyyaml==6.0.3
+referencing==0.37.0
+regex==2026.1.15
+requests==2.32.5
+rich==14.2.0
+rpds-py==0.29.0
+rsa==4.9.1
+ruff==0.14.5
+safehttpx==0.1.7
+semantic-version==2.10.0
+shapely==2.1.2
+shellingham==1.5.4
+six==1.17.0
+sniffio==1.3.1
+sqlalchemy==2.0.44
+sqlalchemy-spanner==1.17.1
+sqlparse==0.5.3
+sse-starlette==3.0.3
+starlette==0.49.3
+tenacity==9.1.2
+tiktoken==0.12.0
+tokenizers==0.22.2
+tomlkit==0.13.3
+tqdm==4.67.1
+typer==0.20.0
+typer-slim==0.20.0
+typing-extensions==4.15.0
+typing-inspection==0.4.2
+tzdata==2025.2
+tzlocal==5.3.1
+uritemplate==4.2.0
+urllib3==2.5.0
+uvicorn==0.38.0
+vertexai==1.43.0
+watchdog==6.0.0
+websockets==15.0.1
+wrapt==1.17.3
+yarl==1.22.0
+zipp==3.23.0

schemas/prompt_templates.schema.json

@@ -0,0 +1,44 @@
+{
+    "$schema": "http://json-schema.org/draft-07/schema#",
+    "title": "PromptTemplatesConfig",
+    "type": "object",
+    "properties": {
+        "templates": {
+            "type": "array",
+            "items": {
+                "type": "object",
+                "properties": {
+                    "id": {
+                        "type": "string"
+                    },
+                    "category": {
+                        "type": "string"
+                    },
+                    "label": {
+                        "type": "string"
+                    },
+                    "description": {
+                        "type": "string"
+                    },
+                    "templateBody": {
+                        "type": "string"
+                    },
+                    "example": {
+                        "type": "string"
+                    }
+                },
+                "required": [
+                    "id",
+                    "category",
+                    "label",
+                    "templateBody"
+                ],
+                "additionalProperties": false
+            }
+        }
+    },
+    "required": [
+        "templates"
+    ],
+    "additionalProperties": false
+}

src/_app/__main__.py

@@ -0,0 +1,53 @@
+# src/app/__main__.py
+import argparse
+import sys
+import json
+import dataclasses
+
+# Deferred import
+# from .gradio_app import main
+from prompts.store import get_template_store
+
+
+def handle_prompts(args):
+    try:
+        store = get_template_store()
+    except Exception as e:
+        print(json.dumps({"error": f"Failed to load templates: {str(e)}"}), file=sys.stderr)
+        sys.exit(1)
+
+    if args.list_prompts:
+        templates = []
+        if args.category:
+            templates = store.list_by_category(args.category)
+        else:
+            templates = store.list_templates()
+
+        output = {"count": len(templates), "templates": [dataclasses.asdict(t) for t in templates]}
+        print(json.dumps(output, indent=2))
+        sys.exit(0)
+
+    if args.get_prompt:
+        template = store.get_template(args.get_prompt)
+        if not template:
+            print(json.dumps({"error": f"Template not found: {args.get_prompt}"}), file=sys.stderr)
+            sys.exit(1)
+        print(json.dumps(dataclasses.asdict(template), indent=2))
+        sys.exit(0)
+
+
+if __name__ == "__main__":
+    parser = argparse.ArgumentParser(description="Runner Agentic Intelligence")
+    parser.add_argument("--list-prompts", action="store_true", help="List all prompt templates")
+    parser.add_argument("--category", type=str, help="Filter templates by category")
+    parser.add_argument("--get-prompt", type=str, help="Get a specific prompt template by ID")
+
+    # Parse known args to avoid conflict with Gradio or other potential subcommands
+    args, unknown = parser.parse_known_args()
+
+    if args.list_prompts or args.get_prompt:
+        handle_prompts(args)
+    else:
+        from .gradio_app import launch_app
+
+        launch_app()

src/_app/presentation/ui_text.py

@@ -0,0 +1,659 @@
+# src/domain/i18n.py
+from typing import Dict, Any
+
+# UI Localization Text
+UI_TEXT = {
+    "en": {
+        "welcome": "Welcome to Runner Intelligence. Upload your first run and the system will begin building your training baseline and generating insights.",
+        "title": "# 🏃 Runner Agentic Intelligence (Experimental)",
+        "subtitle": '<span class="muted">Personalized coaching from your training data.</span>',
+        "workflow": '<span class="muted"><b>Workflow:</b> Upload runs ➔ Get Insights ➔ Review Weekly Plan ➔ Chat with Coach</span><br/><span class="muted"><i>Supported formats: .fit, .fit.gz, .tcx, .tcx.gz, .gpx (max 50MB per file)</i></span><br/><span class="muted">Feedback: <a href="https://github.com/ideas-to-life/runner-agentic-intelligence/issues" target="_blank">GitHub Issues</a> or DM me</span>',
+        "evolution_workflow": '<span class="muted">Track your evolution. Review your weekly check-in and progress vs last month.</span><br/><span class="muted">Upload new runs anytime — your dashboard updates automatically.</span><br/><span class="muted">Feedback: <a href="https://github.com/ideas-to-life/runner-agentic-intelligence/issues" target="_blank">GitHub Issues</a> or DM me</span>',
+        "tab_analyse": "Analyse",
+        "tab_results": "Results",
+        "tab_coach": "Coach",
+        "tab_home": "Home",
+        "tab_intelligence": "Intelligence",
+        "tab_positioning": "Positioning",
+        "lbl_your_week": "Your Week",
+        "lbl_current_state": "Current State",
+        "lbl_key_insight": "Key Insight",
+        "lbl_forward_focus": "This week's Focus",
+        "lbl_details": "Details",
+        "lbl_coach_brief": "Coach Brief",
+        "lbl_parsed": "Parsed",
+        "unit_weeks": "weeks",
+        "lbl_across": "across",
+        "lbl_current": "Current",
+        "lbl_previous": "Previous",
+        "lbl_distance": "Distance",
+        "lbl_runs": "Runs",
+        "lbl_avg_pace": "Avg Pace",
+        "lbl_consistency": "Consistency",
+        "goal_status_template": "Your goal trajectory is **{val}**.",
+        "home_story_template": "You ran **{count}** {unit} this week for a {of} **{dist:.1f} km**.",
+        "sec_evolution": "📈 Progress vs Last Month",
+        "sec_checkin": "## 🧠 Weekly Check-In",
+        "lbl_goal_traj_inline": "**🎯 Trajectory:**",
+        "lbl_focus_inline": "**🎯 Focus:**",
+        "sec_snapshot": "## 📅 Current Week Snapshot",
+        "sec_upload": "🗂️ Upload your training data",
+        "upload_hints": '<div class="muted" style="margin-bottom: 12px; font-size: 0.9rem;"><ul><li>Best results: upload 4–12 recent runs (or ~2–6 weeks).</li><li>Include HR data if you have it (helps fatigue/risk signals).</li><li>Then click ‘Analyse Data’ to populate Results + Coach context.</li></ul></div>',
+        "upload_label": "Drag and drop or click to upload",
+        "btn_analyse": "🚀 Analyse Data",
+        "btn_reset": "Reset",
+        "sec_insights": "Coaching Insights",
+        "lbl_risk": "Safety/Risk Assessment",
+        "lbl_lever": "Primary Lever",
+        "sec_plan": "Weekly Training Plan",
+        "sec_charts": "Trends & Analytics",
+        "sec_chat": "Ask about your training",
+        "chat_indicator_no": "⚠️ *Upload and analyze runs to enable chat context.*",
+        "chat_indicator_yes": "✅ *Chat context enabled.*",
+        "chat_tip": "Tip: try ‘Plot my pace’ or ‘Show HR chart’ to visualize your data.",
+        "chat_placeholder": "e.g., How was my pace last week?",
+        "btn_send": "Send",
+        "btn_clear": "Clear History",
+        "lang_label": "Language / Idioma",
+        "starter_limiter": "Biggest limiter?",
+        "starter_why": "Why this focus?",
+        "starter_fatigue": "Fatigue risk?",
+        "starter_keep": "What to keep doing?",
+        "chat_starter_limiter": "What is my biggest training limiter?",
+        "chat_starter_why": "Why did you suggest this training focus?",
+        "chat_starter_fatigue": "Do you see any signs of overtraining or fatigue?",
+        "chat_starter_keep": "What aspects of my training should I keep doing?",
+        "analyse_progress": "Analysing training data...",
+        "insights_primary_lever_heading": "Primary Lever",
+        "insights_risk_signal_heading": "Risk Signal",
+        "insights_key_observations_heading": "Key Observations",
+        "insights_evidence_label": "Evidence",
+        "insights_constraint_label": "Constraint",
+        "insights_no_primary_lever": "No primary lever identified.",
+        "insights_no_risk": "No elevated risk detected.",
+        "insights_no_observations": "*No observations provided.*",
+        "insights_analysis_failed": "*Analysis Failed*",
+        "insights_analysis_pending": "*Analysis pending...*",
+        "insights_raw_default": "Raw insights will appear here.",
+        "plan_week_summary_label": "Week summary:",
+        "plan_focus_label": "This week's focus:",
+        "plan_pending": "*Plan will appear here after analysis.*",
+        "progress_extracting": "Extracting features from run data...",
+        "progress_generating": "Generating insights and training plan...",
+        "pipeline_stage_1": "🏃 Uploading runs",
+        "pipeline_stage_2": "📊 Building weekly snapshot",
+        "pipeline_stage_3": "📈 Analyzing training trends",
+        "pipeline_stage_4": "🧠 Generating coach insights",
+        "pipeline_stage_5": "📋 Preparing training recommendation",
+        "init_stage_1": "⚙️ Initializing services...",
+        "init_stage_2": "👤 Loading runner profile...",
+        "init_stage_3": "📂 Loading training history...",
+        "init_stage_4": "🏠 Building dashboard...",
+        "week_stage_1": "📅 Switching week...",
+        "week_stage_2": "📊 Building weekly snapshot...",
+        "week_stage_3": "🏠 Updating dashboard...",
+        "chat_context_indicator": "🧠 **Using your training insights as context**",
+        "error_no_runs": "No runs to process.",
+        "lbl_details": "Details (Risk & Observations)",
+        "banner_title": "⚠️ Public Preview Information",
+        "banner_session": "**Session Data**: All uploaded data and chat history are temporary and destroyed after the session.",
+        "banner_persistence_disabled": "🟡 **Public Preview Mode** — No data is persisted. All uploads and derived metrics are temporary.",
+        "banner_persistence_enabled": "🟢 **Training History Persistence Enabled** — Weekly snapshots and trends are stored locally.",
+        "banner_medical": "**Medical Advice**: This system provides coaching insights, NOT medical advice. Consult a professional before starting any training plan.",
+        "banner_full": "**Full Experience**: For full persistence and local storage, run the app locally from [GitHub](https://github.com/avfranco/runner-agentic-intelligence).",
+        "insights_timestamp_label": "Insights generated on",
+        "risk_level_low": "LOW",
+        "risk_level_medium": "MEDIUM",
+        "risk_level_high": "HIGH",
+        "chat_error": "I'm sorry, I'm having trouble processing your request right now.",
+        "plan_error": "Could not generate plan at this time.",
+        "tab_profile": "Profile",
+        "sec_profile": "## Runner Profile (Digital Twin v1)",
+        "lbl_display_name": "Display Name",
+        "lbl_age": "Age",
+        "lbl_experience": "Experience Level",
+        "lbl_injury_notes": "Injury History / Notes",
+        "btn_save_profile": "Save Profile",
+        "profile_saved": "Profile saved successfully!",
+        "profile_save_error": "Error saving profile.",
+        "lbl_baseline": "Baseline Weekly Distance (km)",
+        "lbl_gender": "Gender",
+        "sec_goal": "Active Goal",
+        "lbl_goal_type": "Goal Type",
+        "lbl_target": "Target Value",
+        "lbl_unit": "Unit",
+        "lbl_date": "Target Date",
+        "btn_save_goal": "Set Goal",
+        "goal_saved": "Goal updated!",
+        "lbl_progress": "Progress",
+        "lbl_total_distance": "Distance",
+        "lbl_distance": "Distance",
+        "lbl_avg_pace": "Avg Pace",
+        "lbl_avg_hr": "Avg HR",
+        "lbl_runs_count": "Runs",
+        "goal_trajectory_title": "Goal Trajectory",
+        "goal_status": "Status",
+        "goal_progress": "Progress",
+        "goal_next_milestone": "Next Milestone",
+        "goal_status_ahead": "Ahead",
+        "goal_status_on_track": "On Track",
+        "goal_status_behind": "Behind",
+        "lbl_latest_data": "Latest Data Found",
+        "lbl_consistency": "Consistency",
+        "lbl_metric": "Metric",
+        "lbl_interpreted_delta": "Interpreted Δ",
+        "performance_first_week_title": "This Week in Running",
+        "performance_first_week_body": "This is your first recorded week. You’re building your performance baseline. As you log more runs, your trends will become clearer.",
+        "performance_first_week_focus": "Keep logging your sessions to establish a consistent rhythm.",
+        "error_insufficient_data": "*Not enough history for period comparison (8 weeks required).*",
+        "goal_status_on_track": "On Track",
+        "goal_status_slightly_behind": "Slightly Behind",
+        "goal_status_behind": "Closing the Gap",
+        "goal_type_race": "Race/Event",
+        "goal_type_volume": "Weekly Volume",
+        "goal_type_pace": "Target Pace",
+        "unit_km": "km",
+        "unit_runs": "run(s)",
+        "unit_bpm": "bpm",
+        "unit_pts": "pts",
+        "unit_spkm": "s/km",
+        "na": "N/A",
+        "sec_structure": "Weekly Structure",
+        "lbl_weekday_runs": "Weekday Runs",
+        "lbl_long_run": "Long Run",
+        "lbl_structure_status": "Structure Status",
+        "lbl_km_remaining": "km remaining",
+        "lbl_km_remaining_subtext": "{val} km",
+        "coaching_advice": "Stay consistent this week to close the gap.",
+        "strong_week": "Strong Week",
+        "structured_but_light": "Structured but Imcomplete Volume",
+        "rebuild_week": "Rebuild Week",
+        "reset_week": "Reset Week",
+        "status_pending": "Pending",
+        "status_completed": "Completed",
+        "current_week_label": "Current Week",
+        "last_week_label": "Last Week",
+        "lbl_snapshot_title": "Weekly Snapshot",
+        "no_data_available": "*No runs logged yet this week.*",
+        "home_no_goal_banner": "No active goal set. Set a goal to generate your weekly training plan.",
+        "performance_card_header": "This Week in Running",
+        "delta_vs_4w": "Δ vs 4W avg",
+        "focus_label": "Forward Focus",
+        "no_runs_message": "No runs recorded yet. Looking forward to your first activity!",
+        "btn_download_card": "Download Performance Card",
+        "next_run.title": "Next Recommended Run",
+        "next_run.focus": "Focus",
+        "next_run.session": "Suggested Session",
+        "next_run.why": "Why",
+        "next_run.upload_runs_prompt": "### 🏃 Next Run\n*Upload and analyze runs to see your next recommended session.*",
+        "next_run.set_goal_prompt": "### 🏃 Next Run\n*Set a goal in your Profile to receive personalized training recommendations.*",
+        "insights_risk_signal_heading": "Risk Signal",
+        "insights_key_observations_heading": "Key Observations",
+        "lbl_home_week_range": "Current Week",
+        "lbl_health_signal": "Health Signal",
+        "lbl_goal_trajectory": "Goal Trajectory",
+        "lbl_this_week": "This Week",
+        "lbl_local_folder_path": "Local folder path (Server mode)",
+        "btn_analyse_folder": "Analyse Folder",
+        "btn_consult_coach": "Consult your Coach",
+        "btn_starter_limiter": "Biggest limiter?",
+        "btn_starter_why": "Why this focus?",
+        "btn_starter_fatigue": "Fatigue risk?",
+        "acc_knowledge_base": "Knowledge Base & Templates",
+        "lbl_category": "Category",
+        "lbl_template": "Template",
+        "lbl_preview": "Preview",
+        "btn_insert_message": "Insert into Message Box",
+        "acc_adjustments": "Adjustments & Notes",
+        "lbl_pace_trend": "Pace Trend Analysis",
+        "lbl_hr_trend": "Heart Rate Analysis",
+        "lbl_gender_male": "Male",
+        "lbl_gender_female": "Female",
+        "lbl_gender_pns": "Prefer not to say",
+        "lbl_gender_none": "None",
+        "lbl_exp_beginner": "Beginner",
+        "lbl_exp_intermediate": "Intermediate",
+        "lbl_exp_advanced": "Advanced",
+        "lbl_focus_inline": "**Focus:**",
+        "lbl_total_of": "total of",
+        "lbl_more": "more",
+        "lbl_less": "less",
+        "lbl_faster": "faster",
+        "lbl_slower": "slower",
+        "lbl_that_is": "That's",
+        "lbl_than_avg": "than your recent average.",
+        "lbl_pace_was": "Your pace was",
+        "runner_positioning_title": "Runner Positioning",
+        "positioning_insufficient_data": "Insufficient data to determine positioning yet.",
+        "positioning_no_data": "No training data available yet.",
+        "positioning_context_title": "4-Week Context",
+        "positioning_state_title": "Training State",
+        "positioning_summary_title": "Summary",
+        "positioning_focus_title": "Forward Focus",
+        "positioning_current_state": "Training State",
+        "positioning_health_signal": "Health Signal",
+        "positioning_goal_trajectory": "Goal Trajectory",
+        "analysis_pending": "Analysis pending...",
+        "analysis_failed": "Analysis failed.",
+        # Health signals
+        "health_stable": "Stable",
+        "health_overreaching": "Under High Load",
+        "health_strain": "Strain Detected",
+        # Position status
+        "position_advancing": "Advancing",
+        "position_stable": "Stable",
+        "position_drifting": "Drifting",
+        # Goal trajectory
+        "trajectory_improving": "Progressing",
+        "trajectory_maintaining": "Holding steady",
+        "trajectory_declining": "Losing ground",
+        # Focus guidance
+        "focus_recovery": "Prioritize recovery and absorb recent load.",
+        "focus_build": "Continue building volume gradually.",
+        "focus_maintenance": "Maintain current structure and protect consistency.",
+        "focus_reduce_load": "Reduce load to prevent strain.",
+        # Positioning v1 Status Names
+        "positioning_status_constructive_adaptation": "Constructive Adaptation",
+        "positioning_status_productive_load": "Productive Load",
+        "positioning_status_strain": "Compensatory Strain",
+        "positioning_status_plateau": "Plateau",
+        # Positioning v1 Headlines
+        "positioning_headline_building": "You’re rebuilding consistency with limited activity this week.",
+        "positioning_headline_constructive_adaptation": "Your training is driving clear constructive adaptation.",
+        "positioning_headline_productive_load": "You protected your baseline this week but did not drive new adaptation.",
+        "positioning_headline_strain": "Current load is exceeding your capacity to absorb it safely.",
+        "positioning_headline_plateau": "Training has stabilized after a reduction in volume and frequency. Intensity may now be insufficient to stimulate further adaptation.",
+        # Rationales
+        "positioning_rationale_building": "Establishing initial training consistency. Focus on building a stable aerobic foundation before progressing load.",        
+        "positioning_rationale_constructive_adaptation": "Load is increasing while maintaining consistency.",
+        "positioning_rationale_productive_load": "Maintaining load and protecting baseline.",
+        "positioning_rationale_strain": "Load increase is outpacing cardiovascular adaptation.",
+        "positioning_rationale_plateau": "Training has stabilized.",
+        # Forward Focus
+        "positioning_forward_focus_constructive_adaptation": "Maintain recent volume and allow adaptation to solidify.",
+        "positioning_forward_focus_productive_load": "Reinforce frequency consistency this week.",
+        "positioning_forward_focus_strain": "Prioritize active recovery and reduce non-essential session load.",
+        "positioning_forward_focus_plateau": "Introduce localized intensity spikes to challenge the baseline.",
+        "positioning_status_baseline_building": "Baseline Building",
+        "positioning_headline_baseline_building": "Your training baseline is being established.",
+        "positioning_rationale_building_building": "Initial week(s) of training detected. Collecting data to establish trends.",
+        "positioning_forward_focus_baseline_building": "Establish consistent easy runs this week.",
+        "positioning_trajectory_baseline_building": "Not enough history yet to assess training trends.",
+        "trajectory_no_goal": "No active goal",
+        "trajectory_establishing": "Establishing baseline",
+        # Trajectory
+        "positioning_trajectory_building": "Building: If this pattern continues, you are on track to exceed recent benchmarks.",
+        "positioning_trajectory_stable": "Stable: You are maintaining your level, ideal for long-term health.",
+        "positioning_trajectory_fatigue": "Fatigue Risk: If this pattern continues, performance may decline without recovery.",
+        "positioning_trajectory_plateau": "Training load has stabilized and adaptation appears to have plateaued.",
+        # Phases
+        "positioning_phase_title": "Training Phase",
+        "positioning_phase_base": "Base Phase",
+        "positioning_phase_build": "Build Phase",
+        "positioning_phase_peak": "Peak Phase",
+        "positioning_phase_recovery": "Recovery Phase",
+        "positioning_phase_plateau": "Plateau Phase",
+        # Coaching Narrative
+        "building_consistency": "You’ve started your week — focus on consistency.",
+        "so_far_this_week": "{val} so far this week",
+        "early_week_building": "You're early in the week, building your routine.",
+        "rebuild_phase": "Rebuilding consistency after a lower-volume week.",
+        "rebuilding_consistency_msg": "Rebuilding consistency after a lower-volume week.",
+        # Evidence
+        "positioning_evidence_title": "Evidence Breakdown",
+        "positioning_evidence_distance": "Distance",
+        "positioning_evidence_hr": "HR variance",
+        "positioning_evidence_frequency": "Frequency",
+        "positioning_evidence_consistency": "Consistency",
+        "positioning_not_enough_history": "Not enough training history to determine positioning yet.",
+        "positioning_evidence_pace_improved": "Pace improved",
+        "positioning_evidence_pace_worsened": "Pace worsened",
+        # Training Recommendations
+        "rec_title": "🎯 Training Recommendation",
+        "rec_lbl_focus": "**Focus:**",
+        "rec_lbl_session": "**Suggested Session:**",
+        "rec_lbl_explanation": "**Explanation:**",
+        "rec_focus_protect_recovery": "Protect Recovery",
+        "rec_focus_build_endurance": "Build Endurance",
+        "rec_focus_introduce_intensity": "Introduce Intensity",
+        "rec_focus_maintain_consistency": "Maintain Consistency",
+        "rec_session_easy_run": "Easy Recovery Run",
+        "rec_session_long_run": "Aerobic Long Run",
+        "rec_session_tempo_intervals": "Tempo Intervals",
+        "rec_session_steady_run": "20-minute easy run",
+        "rec_desc_protect_recovery": "Your indicators suggest accumulated fatigue. Prioritize low-intensity movement to allow cardiovascular and structural recovery.",
+        "rec_desc_build_endurance": "Stability in your recent markers shows you are ready to expand your aerobic base. Focus on extending duration at a comfortable effort.",
+        "rec_desc_introduce_intensity": "Your capacity for adaptation is high right now. Introducing controlled intensity will help break through current performance plateaus.",
+        "rec_desc_maintain_consistency": "Focus on protecting your current training rhythm. Consistency is your most powerful lever right now.",
+    },
+    "pt-BR": {
+        "welcome": "Bem-vindo ao Runner Intelligence. Envie sua primeira corrida e o sistema começará a construir sua base de treinamento e gerar insights.",
+        "title": "# ��� Runner Inteligência Agêntica (Experimental)",
+        "subtitle": '<span class="muted">Treinamento personalizado a partir dos seus dados.</span>',
+        "workflow": '<span class="muted"><b>Fluxo:</b> Enviar corridas ➔ Ver Insights ➔ Plano Semanal ➔ Chat com Treinador</span><br/><span class="muted"><i>Formatos: .fit, .fit.gz, .tcx, .tcx.gz, .gpx (max 50MB)</i></span><br/><span class="muted">Feedback: <a href="https://github.com/ideas-to-life/runner-agentic-intelligence/issues" target="_blank">GitHub Issues</a></span>',
+        "evolution_workflow": '<span class="muted">Acompanhe sua evolução. Revise seu check-in semanal e progresso vs mês passado.</span><br/><span class="muted">Envie novas corridas a qualquer momento — seu painel será atualizado automaticamente.</span><br/><span class="muted">Feedback: <a href="https://github.com/ideas-to-life/runner-agentic-intelligence/issues" target="_blank">GitHub Issues</a></span>',
+        "tab_analyse": "Analisar",
+        "tab_results": "Resultados",
+        "tab_coach": "Treinador",
+        "tab_home": "Início",
+        "tab_intelligence": "Inteligência",
+        "tab_positioning": "Posicionamento",
+        "lbl_your_week": "Sua Semana",
+        "lbl_coach_brief": "Resumo do Treinador",
+        "lbl_parsed": "Processadas",
+        "unit_weeks": "semanas",
+        "lbl_across": "ao longo de",
+        "lbl_current": "Atual",
+        "lbl_previous": "Passada",
+        "lbl_distance": "Distância",
+        "lbl_runs": "Corridas",
+        "lbl_avg_pace": "Ritmo Médio",
+        "lbl_consistency": "Consistência",
+        "goal_status_template": "Sua meta está **{val}**.",
+        "home_story_template": "Você correu **{count}** {unit} esta semana, em um {of} **{dist:.1f} km**.",
+        "lbl_current_state": "Estado Atual",
+        "lbl_key_insight": "Insight Principal",
+        "lbl_forward_focus": "Foco da Semana",
+        "lbl_details": "Detalhes",
+        "sec_evolution": "📈 Progresso vs Mês Passado",
+        "sec_checkin": "Check-In Semanal",
+        "lbl_goal_traj_inline": "**🎯 Trajetória:**",
+        "lbl_focus_inline": "**🎯 Foco:**",
+        "sec_snapshot": "Snapshot da Semana Atual",
+        "sec_upload": "🗂️ Envie seus dados de treino",
+        "upload_hints": '<div class="muted" style="margin-bottom: 12px; font-size: 0.9rem;"><ul><li>Melhores resultados: envie 4–12 corridas recentes (ou ~2–6 semanas).</li><li>Inclua dados de FC se tiver (ajuda com sinais de fadiga/risco).</li><li>Depois clique em ‘Analisar Dados’ para gerar Resultados e contexto.</li></ul></div>',
+        "upload_label": "Arraste e solte ou clique para enviar",
+        "btn_analyse": "🚀 Analisar Dados",
+        "btn_reset": "Reiniciar",
+        "sec_insights": "Insights do Treinador",
+        "lbl_risk": "Avaliação de Risco/Segurança",
+        "lbl_lever": "Alavanca Principal",
+        "sec_plan": "Plano de Treino Semanal",
+        "sec_charts": "Tendências e Análises",
+        "sec_chat": "Pergunte sobre seu treino",
+        "chat_indicator_no": "⚠️ *Envie e analise corridas para habilitar o contexto do chat.*",
+        "chat_indicator_yes": "✅ *Contexto do chat habilitado.*",
+        "chat_tip": "Dica: tente ‘Plotar meu ritmo’ ou ‘Mostrar gráfico de FC’ para visualizar seus dados.",
+        "chat_placeholder": "ex: Como foi meu ritmo semana passada?",
+        "btn_send": "Enviar",
+        "btn_clear": "Limpar Histórico",
+        "lang_label": "Language / Idioma",
+        "starter_limiter": "Maior limitador?",
+        "starter_why": "Por que este foco?",
+        "starter_fatigue": "Risco de fadiga?",
+        "starter_keep": "O que manter?",
+        "chat_starter_limiter": "Qual é o meu maior limitador de treino?",
+        "chat_starter_why": "Por que você sugeriu este foco de treinamento?",
+        "chat_starter_fatigue": "Você vê algum sinal de excesso de treino ou fadiga?",
+        "chat_starter_keep": "Quais aspectos do meu treino devo continuar fazendo?",
+        "analyse_progress": "Análise dos dados de treino em andamento...",
+        "insights_primary_lever_heading": "Alavanca Principal",
+        "insights_risk_signal_heading": "Sinal de Risco",
+        "insights_key_observations_heading": "Observações Principais",
+        "insights_evidence_label": "Evidências",
+        "insights_constraint_label": "Restrição",
+        "insights_no_primary_lever": "Nenhuma alavanca principal identificada.",
+        "insights_no_risk": "Nenhum risco elevado detectado.",
+        "insights_no_observations": "*Nenhuma observação fornecida.*",
+        "insights_analysis_failed": "*Falha na Análise*",
+        "insights_analysis_pending": "*Análise pendente...*",
+        "insights_raw_default": "Os insights brutos aparecerão aqui.",
+        "plan_week_summary_label": "Resumo da semana:",
+        "plan_focus_label": "Foco desta semana:",
+        "plan_pending": "*O plano aparecerá aqui após a análise.*",
+        "progress_extracting": "Extraindo características dos dados de corrida...",
+        "progress_generating": "Gerando insights e plano de treinamento...",
+        "pipeline_stage_1": "🏃 Enviando corridas",
+        "pipeline_stage_2": "📊 Construindo snapshot semanal",
+        "pipeline_stage_3": "📈 Analisando tendências de treino",
+        "pipeline_stage_4": "🧠 Gerando insights do treinador",
+        "pipeline_stage_5": "📋 Preparando recomendação de treino",
+        "init_stage_1": "⚙️ Inicializando serviços...",
+        "init_stage_2": "👤 Carregando perfil do corredor...",
+        "init_stage_3": "📂 Carregando histórico de treino...",
+        "init_stage_4": "🏠 Construindo dashboard...",
+        "week_stage_1": "📅 Alterando semana...",
+        "week_stage_2": "📊 Construindo snapshot semanal...",
+        "week_stage_3": "🏠 Atualizando dashboard...",
+        "chat_context_indicator": "🧠 **Usando seus insights de treinamento como contexto**",
+        "error_no_runs": "Nenhuma corrida para processar.",
+        "lbl_details": "Detalhes (Risco e Observações)",
+        "banner_title": "⚠️ Informações do Public Preview",
+        "banner_session": "**Dados da Sessão**: Todos os dados enviados e histórico de chat são temporários e apagados após a sessão.",
+        "banner_persistence_disabled": "🟡 **Modo Public Preview** — Nenhum dado é persistido. Todos os envios e métricas derivadas são temporários.",
+        "banner_persistence_enabled": "🟢 **Persistência de Histórico Ativada** — Snapshots semanais e tendências são armazenados localmente.",
+        "banner_medical": "**Aviso Médico**: Este sistema fornece insights de treinamento, NÃO aconselhamento médico. Consulte um profissional antes de iniciar qualquer plano de treino.",
+        "banner_full": "**Experiência Completa**: Para persistência total e armazenamento local, execute o app localmente a partir do [GitHub](https://github.com/avfranco/runner-agentic-intelligence).",
+        "insights_timestamp_label": "Insights gerados em",
+        "risk_level_low": "BAIXO",
+        "risk_level_medium": "MÉDIO",
+        "risk_level_high": "ALTO",
+        "chat_error": "Desculpe, estou com problemas para processar seu pedido agora.",
+        "plan_error": "Não foi possível gerar o plano neste momento.",
+        "tab_profile": "Perfil",
+        "sec_profile": "## Perfil do Corredor (Gêmeo Digital v1)",
+        "lbl_display_name": "Nome de Exibição",
+        "lbl_age": "Idade",
+        "lbl_experience": "Nível de Experiência",
+        "lbl_injury_notes": "Histórico de Lesões / Notas",
+        "btn_save_profile": "Salvar Perfil",
+        "profile_saved": "Perfil salvo com sucesso!",
+        "profile_save_error": "Erro ao salvar perfil.",
+        "lbl_baseline": "Distância Semanal Base (km)",
+        "lbl_gender": "Gênero",
+        "sec_goal": "Objetivo Atual",
+        "lbl_goal_type": "Tipo de Objetivo",
+        "lbl_target": "Valor Alvo",
+        "lbl_unit": "Unidade",
+        "lbl_date": "Data Alvo",
+        "btn_save_goal": "Definir Objetivo",
+        "goal_saved": "Objetivo atualizado!",
+        "lbl_progress": "Progresso",
+        "lbl_total_distance": "Distância",
+        "lbl_distance": "Distância",
+        "lbl_avg_pace": "Ritmo Médio",
+        "lbl_avg_hr": "FC Média",
+        "lbl_runs_count": "Corridas",
+        "goal_trajectory_title": "Trajetória da Meta",
+        "goal_status": "Status",
+        "goal_progress": "Progresso",
+        "goal_next_milestone": "Próximo Marco",
+        "goal_status_ahead": "Adiantado",
+        "goal_status_on_track": "No Caminho",
+        "goal_status_behind": "Atrasado",
+        "lbl_latest_data": "Últimos Dados Encontrados",
+        "lbl_consistency": "Consistência",
+        "lbl_metric": "Métrica",
+        "lbl_interpreted_delta": "Δ Interpretado",
+        "performance_first_week_title": "Esta Semana nas Corridas",
+        "performance_first_week_body": "Esta é a sua primeira semana registrada. Você está construindo sua base de performance. Conforme você registrar mais corridas, suas tendências ficarão mais claras.",
+        "performance_first_week_focus": "Continue registrando suas sessões para estabelecer um ritmo consistente.",
+        "error_insufficient_data": "*Histórico insuficiente para comparação (8 semanas necessárias).*",
+        "goal_status_on_track": "No Caminho",
+        "goal_status_slightly_behind": "Um Pouco Abaixo",
+        "goal_status_behind": "Em Progresso para a Meta",
+        "goal_type_race": "Prova/Evento",
+        "goal_type_volume": "Volume Semanal",
+        "goal_type_pace": "Ritmo Alvo",
+        "unit_km": "km",
+        "unit_runs": "corrida(s)",
+        "unit_bpm": "bpm",
+        "unit_pts": "pts",
+        "unit_spkm": "s/km",
+        "na": "N/A",
+        "sec_structure": "Estrutura Semanal",
+        "lbl_weekday_runs": "Corridas Semanais",
+        "lbl_long_run": "Longão",
+        "lbl_structure_status": "Status da Estrutura",
+        "lbl_km_remaining": "km restantes",
+        "lbl_km_remaining_subtext": "{val} km",
+        "coaching_advice": "Mantenha a consistência esta semana para fechar a meta.",
+        "strong_week": "Semana Forte",
+        "structured_but_light": "Estruturada, mas Leve",
+        "rebuild_week": "Reconstrução",
+        "reset_week": "Recuperação/Reset",
+        "status_pending": "Pendente",
+        "status_completed": "Concluído",
+        "current_week_label": "Semana Atual",
+        "last_week_label": "Semana Passada",
+        "lbl_snapshot_title": "Snapshot da Semana Atual",
+        "no_data_available": "*Nenhuma corrida registrada esta semana ainda.*",
+        "home_no_goal_banner": "Nenhum objetivo ativo definido. Defina um objetivo para gerar seu plano de treino semanal.",
+        "performance_card_header": "Esta Semana nas Corridas",
+        "delta_vs_4w": "Δ vs méd. 4s",
+        "focus_label": "Foco à Frente",
+        "no_runs_message": "Nenhuma corrida registrada ainda. No aguardo da sua primeira atividade!",
+        "btn_download_card": "Baixar Card de Performance",
+        "next_run.title": "Próxima Corrida Recomendada",
+        "next_run.focus": "Foco",
+        "next_run.session": "Sessão Sugerida",
+        "next_run.why": "Por quê",
+        "next_run.upload_runs_prompt": "### 🏃 Próxima Corrida\n*Envie e analise suas corridas para ver sua próxima sessão recomendada.*",
+        "next_run.set_goal_prompt": "### 🏃 Próxima Corrida\n*Defina um objetivo no seu Perfil para receber recomendações de treino personalizadas.*",
+        "insights_risk_signal_heading": "Sinal de Risco",
+        "insights_key_observations_heading": "Observações Principais",
+        "lbl_home_week_range": "Semana Atual",
+        "lbl_health_signal": "Sinal de Saúde",
+        "lbl_goal_trajectory": "Trajetória da Meta",
+        "lbl_this_week": "Esta Semana",
+        "lbl_local_folder_path": "Caminho da pasta local (Modo servidor)",
+        "btn_analyse_folder": "Analisar Pasta",
+        "btn_consult_coach": "Consultar seu Treinador",
+        "btn_starter_limiter": "Maior limitador?",
+        "btn_starter_why": "Por que este foco?",
+        "btn_starter_fatigue": "Risco de fadiga?",
+        "acc_knowledge_base": "Base de Conhecimento e Modelos",
+        "lbl_category": "Categoria",
+        "lbl_template": "Modelo",
+        "lbl_preview": "Pré-visualização",
+        "btn_insert_message": "Inserir na Caixa de Mensagem",
+        "acc_adjustments": "Ajustes e Notas",
+        "lbl_pace_trend": "Análise de Tendência de Ritmo",
+        "lbl_hr_trend": "Análise de Frequência Cardíaca",
+        "lbl_gender_male": "Masculino",
+        "lbl_gender_female": "Feminino",
+        "lbl_gender_pns": "Prefiro não dizer",
+        "lbl_gender_none": "Nenhum",
+        "lbl_exp_beginner": "Iniciante",
+        "lbl_exp_intermediate": "Intermediário",
+        "lbl_exp_advanced": "Avançado",
+        "lbl_focus_inline": "**Foco:**",
+        "lbl_total_of": "total de",
+        "lbl_more": "mais",
+        "lbl_less": "menos",
+        "lbl_faster": "mais rápido",
+        "lbl_slower": "mais lento",
+        "lbl_that_is": "Isso é",
+        "lbl_than_avg": "que sua média recente.",
+        "lbl_pace_was": "Seu ritmo foi",
+        "runner_positioning_title": "Posicionamento do Corredor",
+        "positioning_insufficient_data": "Dados insuficientes para determinar o posicionamento ainda.",
+        "positioning_no_data": "Nenhum dado de treino disponível ainda.",
+        "positioning_context_title": "Contexto de 4 Semanas",
+        "positioning_state_title": "Estado do Treino",
+        "positioning_summary_title": "Resumo",
+        "positioning_focus_title": "Foco Recomendado",
+        "positioning_current_state": "Estado do Treino",
+        "positioning_health_signal": "Sinal de Saúde",
+        "positioning_goal_trajectory": "Trajetória do Objetivo",
+        "positioning_trajectory": "Trajetória",
+        "positioning_insights": "Insights",
+        "analysis_pending": "Análise pendente...",
+        "analysis_failed": "Falha na análise.",
+        # Health signals
+        "health_stable": "Estável",
+        "health_overreaching": "Carga Elevada",
+        "health_strain": "Sinais de Sobrecarga",
+        # Position status
+        "position_advancing": "Avançando",
+        "position_stable": "Estável",
+        "position_drifting": "Perdendo Ritmo",
+        # Goal trajectory
+        "trajectory_improving": "Progredindo",
+        "trajectory_maintaining": "Mantendo",
+        "trajectory_declining": "Regredindo",
+        # Focus guidance
+        "focus_recovery": "Priorize a recuperação e absorva a carga recente.",
+        "focus_build": "Continue aumentando o volume gradualmente.",
+        "focus_maintenance": "Mantenha a estrutura atual e proteja a consistência.",
+        "focus_reduce_load": "Reduza a carga para evitar sobrecarga.",
+        # Positioning v1 Status Names
+        "positioning_status_constructive_adaptation": "Adaptação Construtiva",
+        "positioning_status_productive_load": "Carga Produtiva",
+        "positioning_status_strain": "Sobrecarga Compensatória",
+        "positioning_status_plateau": "Platô",
+        # Positioning v1 Headlines
+        "positioning_headline_building": "Você está reconstruindo consistência com quantidade de corridas limitada esta semana.",
+        "positioning_headline_constructive_adaptation": "Seu treino está gerando uma adaptação construtiva clara.",
+        "positioning_headline_productive_load": "Você protegeu sua base esta semana, mas não gerou nova adaptação.",
+        "positioning_headline_strain": "A carga atual está excedendo sua capacidade de absorção segura.",
+        "positioning_headline_plateau": "O treino estabilizou, mas a intensidade pode ser insuficiente para evolução.",
+        # Rationales
+        "positioning_rationale_building": "Construindo consistência inicial de treinamento. Foco em estabelecer uma base aeróbica estável antes de progredir a carga.",
+        "positioning_rationale_constructive_adaptation": "A carga está aumentando enquanto a consistência se mantém.",
+        "positioning_rationale_productive_load": "Mantendo a carga e protegendo a base.",
+        "positioning_rationale_strain": "O aumento da carga está superando a adaptação cardiovascular.",
+        "positioning_rationale_plateau": "O treinamento estabilizou.",
+        # Forward Focus
+        "positioning_forward_focus_constructive_adaptation": "Mantenha o volume recente e permita que a adaptação se consolide.",
+        "positioning_forward_focus_productive_load": "Reforce a consistência de frequência esta semana.",
+        "positioning_forward_focus_strain": "Priorize a recuperação ativa e reduza a carga de sessões não essenciais.",
+        "positioning_forward_focus_plateau": "Introduza picos de intensidade localizados para desafiar sua base.",
+        "positioning_status_baseline_building": "Construindo Base",
+        "positioning_headline_baseline_building": "Sua base de treinamento está sendo estabelecida.",
+        "positioning_rationale_building_building": "Semana(s) inicial(is) detectada(s). Coletando dados para estabelecer tendências.",
+        "positioning_forward_focus_baseline_building": "Estabeleça corridas leves consistentes esta semana.",
+        "positioning_trajectory_baseline_building": "Histórico insuficiente para avaliar tendências de treino.",
+        "trajectory_no_goal": "Sem objetivo ativo",
+        "trajectory_establishing": "Estabelecendo base",
+        # Trajectory
+        "positioning_trajectory_building": "Construção: Se este padrão continuar, você está no caminho para superar marcas recentes.",
+        "positioning_trajectory_stable": "Estável: Você está mantendo seu nível, ideal para a saúde de longo prazo.",
+        "positioning_trajectory_fatigue": "Risco de Fadiga: Se este padrão continuar, a performance pode cair sem recuperação.",
+        "positioning_trajectory_plateau": "A carga de treino estabilizou e a adaptação parece ter atingido um platô.",
+        # Phases
+        "positioning_phase_title": "Fase de Treino",
+        "positioning_phase_base": "Fase de Base",
+        "positioning_phase_build": "Fase de Construção",
+        "positioning_phase_peak": "Fase de Pico",
+        "positioning_phase_recovery": "Fase de Recuperação",
+        "positioning_phase_plateau": "Fase de Platô",
+        # Coaching Narrative
+        "building_consistency": "Você começou sua semana — foque na consistência.",
+        "so_far_this_week": "{val} até agora esta semana",
+        "early_week_building": "Você está no início da semana, construindo sua rotina.",
+        "rebuild_phase": "Reconstruindo a consistência após uma semana de menor volume.",
+        "rebuilding_consistency_msg": "Reconstruindo a consistência após uma semana de menor volume.",
+        # Evidence
+        "positioning_evidence_title": "Detalhamento de Evidências",
+        "positioning_evidence_distance": "Distância",
+        "positioning_evidence_hr": "Variância de FC",
+        "positioning_evidence_frequency": "Frequência",
+        "positioning_evidence_consistency": "Consistência",
+        "positioning_not_enough_history": "Histórico de treino insuficiente para determinar o posicionamento ainda.",
+        "positioning_evidence_pace_improved": "Pace melhorou",
+        "positioning_evidence_pace_worsened": "Pace piorou",
+        # Training Recommendations
+        "rec_title": "🎯 Recomendação de Treino",
+        "rec_lbl_focus": "**Foco:**",
+        "rec_lbl_session": "**Sessão Sugerida:**",
+        "rec_lbl_explanation": "**Explicação:**",
+        "rec_focus_protect_recovery": "Proteger Recuperação",
+        "rec_focus_build_endurance": "Construir Resistência",
+        "rec_focus_introduce_intensity": "Introduzir Intensidade",
+        "rec_focus_maintain_consistency": "Manter Consistência",
+        "rec_session_easy_run": "Corrida de Recuperação Leve",
+        "rec_session_long_run": "Longão Aeróbico",
+        "rec_session_tempo_intervals": "Intervalado de Tempo",
+        "rec_session_steady_run": "Corrida Leve de 20 minutos",
+        "rec_desc_protect_recovery": "Seus indicadores sugerem fadiga acumulada. Priorize movimentos de baixa intensidade para permitir a recuperação cardiovascular e estrutural.",
+        "rec_desc_build_endurance": "A estabilidade nos seus marcadores recentes mostra que você está pronto para expandir sua base aeróbica. Foque em estender a duração em um esforço confortável.",
+        "rec_desc_introduce_intensity": "Sua capacidade de adaptação está alta agora. Introduzir intensidade controlada ajudará a superar os patamares atuais de performance.",
+        "rec_desc_maintain_consistency": "Foque em proteger seu ritmo de treino atual. A consistência é sua alavanca mais poderosa agora.",
+    },
+}
+
+def get_text(key: str, language: str = "en") -> str:
+    """Retrieves localized text for a given key and language."""
+    lang_batch = UI_TEXT.get(language, UI_TEXT["en"])
+    return lang_batch.get(key, UI_TEXT["en"].get(key, key))

src/_app/ui/coaching_helpers.py

@@ -0,0 +1,157 @@
+from datetime import date, timedelta
+from typing import Optional, Dict, Any
+from _app.presentation.ui_text import get_text
+
+def _get_val(obj, key, default=None):
+    if obj is None:
+        return default
+    
+    # Mapping for new DTO keys against domain models
+    ATTR_MAP = {
+        "week_start": "week_start_date",
+        "num_runs": "run_count",
+        "weekly_distance_km": "total_distance_km"
+    }
+
+    def _extract(target, k):
+        if target is None:
+            return None, False
+        if isinstance(target, dict):
+            if k in target:
+                return target[k], True
+            return None, False
+        
+        from unittest.mock import MagicMock
+        if isinstance(target, MagicMock):
+            # Only return if specifically set (in __dict__)
+            if k in target.__dict__:
+                return getattr(target, k), True
+            return None, False
+        
+        # Regular object
+        if hasattr(target, k):
+            return getattr(target, k), True
+        return None, False
+
+    # 1. Try exact key
+    val, found = _extract(obj, key)
+    if found:
+        return val
+
+    # 2. Try mapped key
+    mapped = ATTR_MAP.get(key)
+    if mapped:
+        val, found = _extract(obj, mapped)
+        if found:
+            return val
+
+    # 3. Final fallback
+    if isinstance(obj, dict):
+        return obj.get(key, default)
+    
+    # For non-mocks, try getattr one last time
+    from unittest.mock import MagicMock
+    if not isinstance(obj, MagicMock):
+        return getattr(obj, key, default)
+        
+    return default
+
+def is_current_week(week_start) -> bool:
+    """Detect if the given week start date corresponds to the current week."""
+    if not week_start:
+        return False
+    
+    from datetime import date
+    if isinstance(week_start, str):
+        try:
+            week_start = date.fromisoformat(week_start)
+        except:
+            return False
+            
+    today = date.today()
+    # Monday of the current week
+    current_monday = today - timedelta(days=today.weekday())
+    return week_start == current_monday
+
+def format_positioning_metrics(snapshot, language: str = "en") -> Dict[str, Any]:
+    """
+    Returns absolute metrics for the current week to avoid misleading percentages.
+    Returns delta metrics for previous weeks.
+    """
+    if not snapshot:
+        return {}
+
+    w_start = _get_val(snapshot, "week_start")
+    is_current = is_current_week(w_start)
+
+    if is_current:
+        dist_val = _get_val(snapshot, "weekly_distance_km", 0.0)
+        dist_str = get_text("so_far_this_week", language).format(val=f"{dist_val:.1f} km")
+        runs_val = _get_val(snapshot, "num_runs", 0)
+        runs_str = f"{runs_val} " + (get_text("unit_runs", language) if runs_val != 1 else get_text("lbl_runs", language).lower()[:-1] if language == "en" else "corrida")
+        
+        # Add "building consistency" message if only 1 run
+        consistency_msg = ""
+        if runs_val <= 1:
+            consistency_msg = get_text("building_consistency", language)
+
+        return {
+            "distance": dist_str,
+            "runs": runs_str,
+            "consistency_msg": consistency_msg,
+            "mode": "absolute"
+        }
+
+    trend_val = _get_val(snapshot, "trend")
+    if trend_val:
+        dist_delta = _get_val(trend_val, "distance_delta_pct", 0.0)
+        run_delta = _get_val(trend_val, "frequency_delta", 0)
+    else:
+        # Fallback to direct attributes for domain models (WeeklySnapshot doesn't have trend attached usually)
+        dist_delta = _get_val(snapshot, "distance_delta_pct", 0.0)
+        run_delta = _get_val(snapshot, "run_delta", 0)
+
+    return {
+        "distance": f"{dist_delta:+.1f}%",
+        "runs": f"{run_delta:+d}",
+        "consistency_msg": "",
+        "mode": "delta"
+    }
+
+def get_baseline_aware_target(current_km: float, baseline: float) -> float:
+    """
+    Computes a safe target volume based on historical baseline.
+    Rule:
+    - If current < 60% of baseline -> Rebuild to 60%
+    - If current < 80% of baseline -> Rebuild to 80%
+    - Otherwise -> target baseline
+    - Minimum safety floor: 8.0 km
+    """
+    if not baseline or baseline <= 0:
+        return max(current_km, 8.0)
+
+    drop_ratio = current_km / baseline
+    
+    if drop_ratio < 0.6:
+        target_km = baseline * 0.6
+    elif drop_ratio < 0.8:
+        target_km = baseline * 0.8
+    else:
+        target_km = baseline
+        
+    return max(target_km, 8.0)
+
+def interpret_week(snapshot, baseline: Optional[float], language: str = "en") -> Optional[str]:
+    """Add simple interpretation rules for the narrative layer."""
+    if not snapshot:
+        return None
+
+    run_count = _get_val(snapshot, "num_runs", 0)
+    if run_count <= 1:
+        return get_text("early_week_building", language)
+
+    dist_km = _get_val(snapshot, "weekly_distance_km", 0.0)
+    if baseline and dist_km < baseline * 0.6:
+        return get_text("rebuild_phase", language)
+
+    return None

src/agents/base.py

@@ -0,0 +1,9 @@
+from abc import ABC, abstractmethod
+from typing import Dict, Any, Union
+from pydantic import BaseModel
+
+
+class BaseAgent(ABC):
+    @abstractmethod
+    def run(self, *args, **kwargs) -> Union[Dict[str, Any], BaseModel]:
+        pass

src/agents/chat_agent.py

@@ -0,0 +1,161 @@
+import logging
+import config
+import time
+from typing import Dict, Any, List, Optional
+from .base import BaseAgent
+from llm.base import LLMClient
+from observability import logger as obs_logger
+from observability import components as obs_components
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+class ChatAgent(BaseAgent):
+    """
+    Agent responsible for handling conversational interactions with the user.
+    It can answer questions about the run data, insights, and plan, and can also
+    delegate to other agents (like VisualizationAgent) for specific tasks.
+    """
+
+    def __init__(self, llm_client: LLMClient):
+        self.llm_client = llm_client
+        self.context = {}
+        self.instruction = self._load_instruction("en")
+
+    def _load_instruction(self, language: str = "en") -> str:
+        try:
+            # Resolve path relative to this file
+            base_path = Path(__file__).parent.parent / "prompts"
+            filename = f"chat_{language}.txt"
+            file_path = base_path / filename
+
+            if not file_path.exists():
+                logger.warning(f"Prompt file not found: {file_path}. Falling back to English.")
+                file_path = base_path / "chat_en.txt"
+
+            if not file_path.exists():
+                logger.error("English prompt file missing!")
+                return "You are a helpful running coach assistant."
+
+            return file_path.read_text(encoding="utf-8")
+        except Exception as e:
+            logger.error(f"Error loading prompt for language {language}: {e}")
+            return "You are a helpful running coach assistant."
+
+    async def run(self, message: str, context: Dict[str, Any], language: str = "en") -> str:
+        # Load language-specific instruction
+        self.instruction = self._load_instruction(language)
+        """
+        Process a user message with the given context.
+        """
+        self.context = context
+
+        # Construct a prompt with context
+        is_pt = language == "pt-BR"
+        if is_pt:
+            prompt = f"""
+            Contexto:
+            Características: {context.get('features', 'Não disponível')}
+            Insights: {context.get('insights', 'Não disponível')}
+            Plano: {context.get('plan', 'Não disponível')}
+            Resumo: {context.get('summary', 'Não disponível')}
+            
+            ### Contexto de Performance Histórica (Injetado automaticamente)
+            {self._format_auto_insights(context.get('auto_injected_insights', []), language=language)}
+            
+            Mensagem do Usuário: {message}
+            
+            Resposta:
+            """
+        else:
+            prompt = f"""
+            Context:
+            Features: {context.get('features', 'Not available')}
+            Insights: {context.get('insights', 'Not available')}
+            Plan: {context.get('plan', 'Not available')}
+            Summary: {context.get('summary', 'Not available')}
+            
+            ### Historical Performance Context (Auto-injected)
+            {self._format_auto_insights(context.get('auto_injected_insights', []))}
+            
+            User Message: {message}
+            
+            Answer:
+            """
+
+        with obs_logger.start_span("chat_agent.run", obs_components.AGENT):
+            start_time = time.time()
+            try:
+                response = await self.llm_client.generate(
+                    prompt, instruction=self.instruction, name="chat_agent"
+                )
+                duration_ms = (time.time() - start_time) * 1000
+                obs_logger.log_event(
+                    "info",
+                    "Chat response generated",
+                    component=obs_components.AGENT,
+                    fields={
+                        "duration_ms": duration_ms,
+                        "language": language,
+                        "message_length": len(message),
+                        "response_length": len(str(response)),
+                    },
+                )
+                return str(response)
+            except Exception as e:
+                duration_ms = (time.time() - start_time) * 1000
+                obs_logger.log_event(
+                    "error",
+                    f"Chat agent failed: {e}",
+                    component=obs_components.AGENT,
+                    fields={
+                        "duration_ms": duration_ms,
+                        "language": language,
+                        "error_type": type(e).__name__,
+                        "error_message": str(e),
+                    },
+                )
+                logger.error(f"Chat agent failed: {e}")
+                return (
+                    "Desculpe, estou com problemas para processar seu pedido agora."
+                    if language == "pt-BR"
+                    else "I'm sorry, I'm having trouble processing your request right now."
+                )
+
+    def _format_auto_insights(self, insights: List[Dict[str, Any]], language: str = "en") -> str:
+        is_pt = language == "pt-BR"
+        if not insights:
+            return (
+                "Nenhum insight anterior encontrado no histórico."
+                if is_pt
+                else "No previous insights found in history."
+            )
+
+        lines = []
+        unknown_date = "Data Desconhecida" if is_pt else "Unknown Date"
+        for item in insights:
+            date_str = item.get("date", unknown_date)
+            # Insights are stored as a dict of message strings
+            msgs = item.get("insights", {})
+            if isinstance(msgs, dict):
+                parts = []
+                for k, v in msgs.items():
+                    if isinstance(v, dict):
+                        m = v.get("message")
+                        if m:
+                            parts.append(m)
+                    elif isinstance(v, list):
+                        for sub_v in v:
+                            if isinstance(sub_v, dict):
+                                m = sub_v.get("message")
+                                if m:
+                                    parts.append(m)
+                    elif isinstance(v, str):
+                        parts.append(v)
+                content = " | ".join(parts)
+            else:
+                content = str(msgs)
+            lines.append(f"- [{date_str}]: {content}")
+
+        return "\n".join(lines)

src/agents/feature_engineering/agent.py

@@ -0,0 +1,44 @@
+import time
+import logging
+from observability import logger as obs_logger
+from observability import components as obs_components
+from ..base import BaseAgent
+from typing import List, Dict, Any
+
+from ingestion.features import running_features
+
+
+logger = logging.getLogger(__name__)
+
+
+class FeatureEngineeringAgent(BaseAgent):
+    """
+    Input: list of runs as returned by parser
+    Output: a features dict with:
+      - per_run summaries (pace_min_per_km, avg_hr)
+      - time series arrays for charts
+      - weekly aggregates (mileage)
+      - consistency score (0-100)
+    """
+
+    def run(self, runs: List[Dict[str, Any]]) -> Dict[str, Any]:
+        with obs_logger.start_span("feature_engineering_agent.run", obs_components.AGENT):
+            from ingestion.features import compute_features_batch
+            from ingestion.weekly_features import aggregate_runs_by_week, compute_trends
+
+            try:
+                # 1. Basic summary and charts
+                summary = running_features(runs)
+
+                # 2. Detailed per-run features
+                detailed_features = compute_features_batch(runs)
+
+                return {
+                    "summary": summary,
+                    "detailed_features": detailed_features,
+                    "weekly_stats": {},  # Deprecated in-memory
+                    "trends": {},  # Deprecated in-memory
+                }
+            except Exception as e:
+                logger.error(f"Feature engineering failed: {e}")
+                raise

src/agents/file_integrity/agent.py

@@ -0,0 +1,6 @@
+class FileIntegrityAgent:
+    def run(self, strava_data, apple_data):
+        if not strava_data and not apple_data:
+            return "No valid files provided."
+
+        return "Files loaded successfully. Basic integrity OK."

src/agents/guardrail_agent.py

@@ -0,0 +1,132 @@
+from typing import Dict, Any, List, Optional
+import logging
+import time
+from observability import logger as obs_logger
+from observability import components as obs_components
+from .base import BaseAgent
+from domain.training.agent_models import RiskAssessment, WeeklySummary
+from domain.runner.profile import RunnerProfile
+
+logger = logging.getLogger(__name__)
+
+
+class InjuryFatigueGuardrailAgent(BaseAgent):
+    """
+    Heuristic-based agent that assesses the risk of injury or fatigue.
+    """
+
+    def assess_risk(
+        self,
+        features: WeeklySummary,
+        pain_reported: bool = False,
+        profile: Optional[RunnerProfile] = None,
+    ) -> RiskAssessment:
+        """
+        Calculates risk level and reasons based on running features.
+        """
+        risk_level = "LOW"
+        reasons = []
+        adjustments = []
+        metrics = {}
+
+        # 1. Mileage Spike Heuristic
+        # summary often contains 'weekly_km'
+        weekly_km = features.weekly_km
+        if weekly_km:
+            weeks = sorted(weekly_km.items(), reverse=True)
+            if len(weeks) >= 2:
+                current_week_val = weeks[0][1]
+                prev_week_val = weeks[1][1]
+                metrics["current_week_km"] = current_week_val
+                metrics["prev_week_km"] = prev_week_val
+
+                if prev_week_val > 0:
+                    increase_pct = (current_week_val - prev_week_val) / prev_week_val
+                    metrics["wow_increase_pct"] = increase_pct
+
+                    if increase_pct > 0.5:
+                        risk_level = "HIGH"
+                        reasons.append(f"Major mileage spike: {increase_pct:.1%} increase Wow.")
+                        adjustments.append("Reduce volume significantly; include extra rest day.")
+                    elif increase_pct > 0.3:
+                        if risk_level != "HIGH":
+                            risk_level = "MEDIUM"
+                        reasons.append(
+                            f"Significant mileage increase: {increase_pct:.1%} increase WoW."
+                        )
+                        adjustments.append("Cap intensity; avoid two hard days in a row.")
+
+        # 1.5. Baseline Mileage Spike Heuristic
+        if (
+            profile
+            and isinstance(profile.baseline_weekly_km, (int, float))
+            and profile.baseline_weekly_km > 0
+        ):
+            current_week_val = 0.0
+            if weekly_km:
+                weeks = sorted(weekly_km.items(), reverse=True)
+                if weeks:
+                    current_week_val = weeks[0][1]
+
+            if current_week_val > 0:
+                baseline_increase_pct = (
+                    current_week_val - profile.baseline_weekly_km
+                ) / profile.baseline_weekly_km
+                metrics["baseline_increase_pct"] = baseline_increase_pct
+
+                if baseline_increase_pct > 0.6:
+                    if risk_level != "HIGH":
+                        risk_level = "HIGH"
+                    reasons.append(
+                        f"Major spike vs your baseline: {baseline_increase_pct:.1%} above baseline of {profile.baseline_weekly_km}km."
+                    )
+                    if "Reduce volume" not in " ".join(adjustments):
+                        adjustments.append("Reduce volume to closer to your baseline.")
+                elif baseline_increase_pct > 0.4:
+                    if risk_level == "LOW":
+                        risk_level = "MEDIUM"
+                    reasons.append(
+                        f"Significant increase vs your baseline: {baseline_increase_pct:.1%} above baseline."
+                    )
+                    if "Cap intensity" not in " ".join(adjustments):
+                        adjustments.append(
+                            "Be cautious with this increase; ensure adequate recovery."
+                        )
+
+        # 2. Consistency / Monotony Heuristic
+        # Feature Engineering agent provides consistency_score (0-100)
+        consistency = features.consistency_score
+        metrics["consistency_score"] = consistency
+        if consistency < 30:
+            if risk_level == "LOW":
+                risk_level = "MEDIUM"
+            reasons.append(
+                f"Low consistency score ({consistency}/100) increases injury risk during ramp-up."
+            )
+            adjustments.append("Build base gradually before adding intensity.")
+
+        # 3. Pain Reported Flag (from User or scenario)
+        metrics["pain_reported"] = pain_reported
+        if pain_reported:
+            risk_level = "HIGH"
+            reasons.append("User reported pain or discomfort.")
+            adjustments.append("Switch all remaining sessions this week to rest or cross-training.")
+
+        # 4. Fatigue markers (placeholder - heart rate drift trend if provided)
+        # In this PoC, we might have pace_trend from trends but it's simple.
+
+        return RiskAssessment(
+            risk_level=risk_level,
+            reasons=reasons,
+            recommended_adjustments=adjustments,
+            metrics_used=metrics,
+        )
+
+    def run(
+        self,
+        features: WeeklySummary,
+        pain_reported: bool = False,
+        profile: Optional[RunnerProfile] = None,
+    ) -> RiskAssessment:
+        with obs_logger.start_span("guardrail_agent.run", obs_components.AGENT):
+            return self.assess_risk(features, pain_reported, profile=profile)

src/agents/insights/agent.py

@@ -0,0 +1,204 @@
+from typing import Dict, Any, Union, Optional
+from datetime import datetime
+import logging
+import json
+import time
+from pathlib import Path
+from observability import logger as obs_logger
+from observability import components as obs_components
+
+from domain.training.agent_models import WeeklyTrends, Insight, InsightsOutput, RiskAssessment
+from domain.training.run import Run
+from domain.runner.profile import RunnerProfile
+from domain.runner.goal import Goal
+from llm.base import LLMClient
+
+logger = logging.getLogger(__name__)
+
+
+class InsightsAgent:
+    """
+    Generate actionable insights for a runner using an LLM via the provided LLMClient.
+    """
+
+    def __init__(self, llm_client: LLMClient):
+        self.llm_client = llm_client
+        self.instruction = self._load_instruction("en")
+
+    def _load_instruction(self, language: str = "en") -> str:
+        try:
+            # Resolve path relative to this file: src/agents/insights/../../prompts/
+            base_path = Path(__file__).parent.parent.parent / "prompts"
+            filename = f"insights_{language}.txt"
+            file_path = base_path / filename
+
+            if not file_path.exists():
+                logger.warning(f"Prompt file not found: {file_path}. Falling back to English.")
+                file_path = base_path / "insights_en.txt"
+
+            if not file_path.exists():
+                # Ultimate fallback if even English file is missing
+                logger.error("English prompt file missing!")
+                return "You are an expert running coach. Generate insights in JSON."
+
+            return file_path.read_text(encoding="utf-8")
+        except Exception as e:
+            logger.error(f"Error loading prompt for language {language}: {e}")
+            return "You are an expert running coach. Generate insights in JSON."
+
+    async def run(
+        self,
+        run_features: Run,
+        weekly_trends: WeeklyTrends,
+        risk_level: str = "LOW",
+        language: str = "en",
+        profile: Optional[RunnerProfile] = None,
+        goal: Optional[Goal] = None,
+    ) -> Dict[str, Any]:
+        with obs_logger.start_span("insights_agent.run", obs_components.AGENT):
+            start_time = time.time()
+
+            # Load language-specific instruction
+            self.instruction = self._load_instruction(language)
+
+            # Construct Prompt
+            prompt = self._construct_prompt(
+                run_features,
+                weekly_trends,
+                risk_level,
+                language=language,
+                profile=profile,
+                goal=goal,
+            )
+
+            try:
+                # Call LLM via Client
+                with obs_logger.start_span("insights_agent.llm", obs_components.AGENT):
+                    insights_output = await self.llm_client.generate(
+                        prompt, instruction=self.instruction, schema=InsightsOutput, name="insights_agent"
+                    )
+
+                if isinstance(insights_output, InsightsOutput):
+                    result = insights_output.model_dump()
+                else:
+                    # Handle unexpected response type
+                    logger.error(f"Unexpected response type from LLM: {type(insights_output)}")
+                    result = self._fallback_error(language)
+
+                return result
+
+            except Exception as e:
+                duration_ms = (time.time() - start_time) * 1000
+                obs_logger.log_event(
+                    "error",
+                    f"Failed to generate insights: {e}",
+                    event="error",
+                    component=obs_components.AGENT,
+                    duration_ms=duration_ms,
+                )
+                logger.error(f"Failed to generate insights with LLM: {e}", exc_info=True)
+                return self._fallback_error(language)
+
+    def _fallback_error(self, language: str = "en") -> Dict[str, Any]:
+        is_pt = language == "pt-BR"
+        if is_pt:
+            return {
+                "error": "Não foi possível gerar os insights neste momento.",
+                "primary_lever": {"message": "Não foi possível gerar insights."},
+                "risk_signal": {"message": "Avaliação de risco indisponível."},
+                "key_observations": [],
+                "summary": {"message": "Falha na geração de insights."},
+            }
+        return {
+            "error": "Could not generate insights at this time.",
+            "primary_lever": {"message": "Could not generate insights."},
+            "risk_signal": {"message": "Risk assessment unavailable."},
+            "key_observations": [],
+            "summary": {"message": "Insights generation failed."},
+        }
+
+    def _construct_prompt(
+        self,
+        run: Run,
+        trends: WeeklyTrends,
+        risk_level: str,
+        language: str = "en",
+        profile: Optional[RunnerProfile] = None,
+        goal: Optional[Goal] = None,
+    ) -> str:
+        is_pt = language == "pt-BR"
+        profile_context = ""
+        if profile:
+            profile_context = "\n**Runner Profile Context:**\n"
+            if profile.runner_display_name:
+                profile_context += f"- Display Name: {profile.runner_display_name}\n"
+            if profile.age:
+                profile_context += f"- Age: {profile.age}\n"
+            if profile.experience_level:
+                profile_context += f"- Experience Level: {profile.experience_level}\n"
+            if profile.baseline_weekly_km:
+                profile_context += f"- Baseline Weekly KM: {profile.baseline_weekly_km}\n"
+            if profile.injury_history_notes:
+                profile_context += f"- Injury Notes: {profile.injury_history_notes}\n"
+
+        if goal:
+            goal_type_label = goal.type.replace("_", " ").title()
+            date_str = goal.target_date.strftime("%Y-%m-%d") if goal.target_date else "N/A"
+            profile_context += f"\n**Current Active Goal:**\n"
+            profile_context += f"- Type: {goal_type_label}\n"
+            profile_context += f"- Target: {goal.target_value} {goal.unit}\n"
+            profile_context += f"- Target Date: {date_str}\n"
+
+        if is_pt:
+            return f"""
+                Analise os seguintes dados de corrida e tendências semanais.
+                Observe que nossa avaliação de risco heurística é atualmente: **{risk_level}**.
+                {profile_context}
+
+                **Dados da Corrida:**
+                - Distância: {run.total_distance_m} metros
+                - Duração: {run.total_duration_s} segundos
+                - Ritmo Médio: {run.avg_pace_min_per_km} min/km
+                - FC Média: {run.avg_hr_bpm} bpm
+                - FC Máxima: {run.max_hr_bpm} bpm
+                - Ganho de Elevação: {run.elevation_gain_m} metros
+
+                **Tendências Semanais:**
+                - Tendência de Ritmo: {trends.pace_trend_s_per_km} s/km (negativo significa mais rápido)
+                - Tendência de Distância: {trends.distance_trend_m} metros
+                - Média de Corridas/Semana: {trends.avg_runs_per_week}
+                - Monotonia: {trends.run_monotony}
+
+                Identifique:
+                1. A 'Alavanca Principal' (mudança de treino com maior prioridade).
+                2. 'Sinais de Risco' significativos (alinhados com nossa heurística de {risk_level}).
+                3. Duas 'Observações Principais' que importam para a tomada de decisão.
+                4. Um 'Resumo do Treinador' (uma frase final de encorajamento ou instrução).
+
+                IMPORTANTE: Todas as mensagens, evidências e justificativas DEVEM estar em Português do Brasil (pt-BR).
+                """
+
+        return f"""
+            Analyze the following run data and weekly trends. 
+            Note that our heuristic risk assessment is currently: **{risk_level}**.
+
+            **Run Data:**
+            - Distance: {run.total_distance_m} meters
+            - Duration: {run.total_duration_s} seconds
+            - Avg Pace: {run.avg_pace_min_per_km} min/km
+            - Avg HR: {run.avg_hr_bpm} bpm
+            - Max HR: {run.max_hr_bpm} bpm
+            - Elevation Gain: {run.elevation_gain_m} meters
+
+            **Weekly Trends:**
+            - Pace Trend: {trends.pace_trend_s_per_km} s/km (negative means faster)
+            - Distance Trend: {trends.distance_trend_m} meters
+            - Avg Runs/Week: {trends.avg_runs_per_week}
+            - Monotony: {trends.run_monotony}
+
+            Identify:
+            1. The 'Primary Lever' (top priority training change).
+            2. Significant 'Risk Signals' (aligned with our {risk_level} heuristic).
+            3. Two 'Key Observations' that matter for decision making.
+            4. A 'Coaching Summary' (one-sentence final encouraging or instructional takeaway).
+            """

src/agents/orchestrator.py

@@ -0,0 +1,1170 @@
+import logging
+import uuid
+import time
+from datetime import date, datetime, timedelta, timezone
+from ingestion.weekly_features import week_start
+from typing import List, Dict, Any, Optional, Set, Tuple
+from observability import logger as obs_logger
+from observability import components as obs_components
+
+
+# LLM imports
+from llm import get_llm_client
+from llm.model_registry import select_model_for_agent
+
+# Local Agent Imports
+from .feature_engineering.agent import FeatureEngineeringAgent
+from .insights.agent import InsightsAgent
+from .plan.agent import PlanAgent
+from .visualization.agent import VisualizationAgent
+from .chat_agent import ChatAgent
+from .guardrail_agent import InjuryFatigueGuardrailAgent
+
+from tools.stores import InMemoryFeatureStore, InMemoryPlanStore
+from tools.viz_executor import TemplateVisualizationExecutor
+
+from router.router import async_route
+from router.models import RouteDecision
+
+# New domain imports
+from domain.runner.profile import RunnerProfile
+from domain.training.run import Run
+from domain.training.weekly_snapshot import WeeklySnapshot
+from domain.training.weekly_trend import WeeklyTrend
+from domain.training.agent_models import AnalysisRecord, WeeklyTrends, RiskAssessment
+from domain.goals.goal_trajectory import GoalTrajectory
+from core.intelligence.runner_intelligence_snapshot import RunnerIntelligenceSnapshot
+
+# New persistence imports
+from persistence.db import Database
+from persistence.repositories.runner_repo import RunnerRepository
+from persistence.repositories.run_repo import RunRepository
+from persistence.repositories.weekly_repo import WeeklySnapshotRepository
+from persistence.repositories.trend_repo import TrendSnapshotRepository
+from persistence.repositories.analysis_repo import AnalysisRepository
+from persistence.repositories.goal_repo import SqlGoalRepository
+from persistence.repositories.null_goal_repo import NullGoalRepository
+from persistence.repositories.planned_session_repository import PlannedSessionRepository
+
+# New engine imports
+from engines.trend.trend_engine import TrendEngine
+
+# New stateless builders
+from domain.training.weekly_snapshot_builder import WeeklySnapshotBuilder
+from domain.training.weekly_trend_builder import WeeklyTrendBuilder
+from domain.training.weekly_trend import WeeklyTrend
+
+# New service imports
+from services.snapshot_service import SnapshotService
+from services.brief_service import BriefService
+from services.goal_service import GoalService
+from services.structure_service import StructureService
+from services.run_persistence_service import RunPersistenceService
+
+from application.runner_positioning_service import RunnerPositioningService
+from domain.runner_positioning import RunnerPositioning
+from application.positioning_service import WeeklyPositioning, PositioningEngine
+from application.recommendation_service import RecommendationService
+from services.guardrail_arbitration_service import GuardrailArbitrationService
+from services.positioning_change_service import PositioningChangeService
+from services.goal_progress_service import GoalProgressService
+from application.goal_trajectory_service import GoalTrajectoryService
+
+
+import config
+
+# Pipeline imports
+from core.pipeline.pipeline import RunnerPipeline
+from core.pipeline.context import PipelineContext
+from pipeline_steps.feature_engineering_step import FeatureEngineeringStep
+from pipeline_steps.persist_runs_step import PersistRunsStep
+from pipeline_steps.structure_step import StructureStep
+from pipeline_steps.snapshot_step import SnapshotStep
+from pipeline_steps.guardrail_step import GuardrailStep
+from pipeline_steps.positioning_step import PositioningStep
+from pipeline_steps.goal_trajectory_step import GoalTrajectoryStep
+from pipeline_steps.intelligence_step import IntelligenceStep
+from pipeline_steps.visualization_step import VisualizationStep
+from pipeline_steps.comparison_step import ComparisonStep
+from pipeline_steps.persist_analysis_step import PersistAnalysisStep
+
+from core.intelligence.intelligence_builder import build_intelligence_snapshot
+from application.dto.runner_api_response import RunnerAPIResponse
+from core.intelligence.intelligence_serializer import serialize_snapshot
+
+# Configure logging
+logger = logging.getLogger(__name__)
+
+class RunnerOrchestrator:
+    """
+    Central orchestration component for Runner Intelligence.
+
+    Coordinates pipeline execution, agents, and services using the
+    RunnerPipeline architecture.
+    """
+
+    def __init__(self, feature_store=None, plan_store=None, viz_executor=None, db=None):
+        logger.info("Initializing RunnerOrchestrator")
+        self.session_id = config.generate_session_id()
+
+        # Tool boundaries
+        self.feature_store = feature_store or InMemoryFeatureStore()
+        self.plan_store = plan_store or InMemoryPlanStore()
+        self.viz_executor = viz_executor or TemplateVisualizationExecutor()
+
+        # New persistence layer
+        self.db = db
+        self.runner_repo = None
+        self.run_repo = None
+        self.weekly_repo = None
+        self.trend_repo = None
+        self.analysis_repo = None
+        self.goal_repo = None
+        self.planned_repo = None
+        self.snapshot_service = None
+
+        # Mode Discipline: Resolve storage implementation at Orchestrator boundary
+        if not self.db:
+            if config.is_persistence_enabled():
+                self.db = Database(config.STORAGE_DB_PATH)
+            else:
+                # Fallback to volatile in-memory storage for HF Spaces/transient sessions
+                self.db = Database(":memory:")
+        
+        self.db.initialize_schema()
+        
+        # Inject dependencies
+        self.runner_repo = RunnerRepository(self.db)
+        self.run_repo = RunRepository(self.db)
+        self.weekly_repo = WeeklySnapshotRepository(self.db)
+        self.trend_repo = TrendSnapshotRepository(self.db)
+        self.analysis_repo = AnalysisRepository(self.db)
+        if config.is_persistence_enabled():
+            self.goal_repo = SqlGoalRepository(self.db)
+        else:
+            self.goal_repo = NullGoalRepository()
+        
+        self.planned_repo = PlannedSessionRepository(self.db)
+        self.intelligence_cache: Dict[str, bool] = {}
+        self.runs_cache: List[Dict[str, Any]] = []
+        
+        # Services receive resolved dependencies
+        self.structure_service = StructureService(
+            planned_repo=self.planned_repo,
+            goal_repo=self.goal_repo,
+            runner_repo=self.runner_repo,
+        )
+
+        self.trend_engine = TrendEngine()
+        self.run_persistence_service = RunPersistenceService(self.run_repo)
+        
+        # Stateless Builders
+        self.weekly_snapshot_builder = WeeklySnapshotBuilder()
+        self.weekly_trend_builder = WeeklyTrendBuilder()
+
+        self.snapshot_service = SnapshotService(
+            runner_repo=self.runner_repo,
+            run_repo=self.run_repo,
+            weekly_repo=self.weekly_repo,
+            trend_repo=self.trend_repo,
+            weekly_builder=self.weekly_snapshot_builder,
+            trend_engine=self.trend_engine,
+            structure_service=self.structure_service,
+            brief_service=None,  # Will be set after brief_service is initialized
+        )
+        self.goal_service = GoalService(goal_repo=self.goal_repo)
+        self.positioning_service = RunnerPositioningService()
+        self.positioning_engine = PositioningEngine()
+        self.recommendation_service = RecommendationService()
+
+        # New isolation services
+        self.guardrail_arbitration_service = GuardrailArbitrationService()
+        self.positioning_change_service = PositioningChangeService()
+        self.goal_progress_service = GoalProgressService()
+        self.goal_trajectory_service = GoalTrajectoryService()
+
+        # LLM Clients per Agent
+        def _get_agent_client(agent_name: str):
+            profile = select_model_for_agent(agent_name)
+            return get_llm_client(
+                provider=profile.provider,
+                model_name=profile.model_name,
+                temperature=config.LLM_TEMPERATURE,
+                max_tokens=config.LLM_MAX_TOKENS,
+                drop_params=getattr(config, "LLM_DROP_PARAMS", False),
+            )
+
+        # Instantiate agents
+        logger.info("Instantiating agents with specific model profiles")
+        self.feature_agent = FeatureEngineeringAgent()
+        self.insights_agent = InsightsAgent(llm_client=_get_agent_client("InsightsAgent"))
+        self.plan_agent = PlanAgent(llm_client=_get_agent_client("PlanAgent"))
+        self.visualization_agent = VisualizationAgent(
+            llm_client=_get_agent_client("VisualizationAgent")
+        )
+        self.chat_agent = ChatAgent(llm_client=_get_agent_client("ChatAgent"))
+
+        # We also need a client for the router
+        self.router_client = _get_agent_client("Router")
+        self.guardrail_agent = InjuryFatigueGuardrailAgent()
+
+        # Instantiate dedicated BriefService
+        self.brief_service = BriefService(llm_client=_get_agent_client("BriefService"))
+        self.snapshot_service.brief_service = self.brief_service
+
+        # Latest results state
+        self.latest_insights = {}
+        self.latest_plan = None
+        self.latest_summary = {}
+        self.latest_trends = {}
+        self.latest_risk_assessment = None
+        self.latest_goal_trajectory: Optional[GoalTrajectory] = None
+
+        # Session snapshot cache for stateless mode history
+        self.session_snapshots: Dict[date, WeeklySnapshot] = {}
+        self.session_runner_positioning: Dict[date, RunnerPositioning] = {}
+        self.session_view_positioning: Dict[date, WeeklyPositioning] = {}
+        self.session_goal_trajectory: Dict[date, GoalTrajectory] = {}
+
+        # State-driven intelligence cache (v1 optimization)
+        self._last_positioning: Optional[RunnerPositioning] = None
+        self._last_insights: Dict[str, Any] = {}
+        self._last_plan: Optional[str] = None
+        self._last_brief: str = ""
+        self._last_focus: str = ""
+        self._last_runner_positioning: Optional[RunnerPositioning] = None
+
+        # State-driven intelligence cache (v2 optimization)
+        # Keyed by (week_start, language) to prevent stale content on language switch
+        self.intelligence_snapshots: Dict[Tuple[date, str], RunnerIntelligenceSnapshot] = {}
+        if self.snapshot_service and hasattr(self.snapshot_service, "intelligence_snapshots"):
+            # Ensure we are not accidentally using a Mock from a test environment
+            actual_cache = self.snapshot_service.intelligence_snapshots
+            if isinstance(actual_cache, dict):
+                # We expect the cache to be empty or already Tuple-keyed if from a previous run in the same session.
+                # If it has date-only keys (from a previous version), they will be ignored/overwritten.
+                self.intelligence_snapshots = actual_cache
+
+        # DTO API Response
+        self.dto_response = RunnerAPIResponse(
+            num_runs=0,
+            weeks=0,
+            features=[],
+            insights={},
+            plan=None,
+            risk_assessment=None,
+            trends={},
+            period_comparison=None,
+            charts={},
+            profile=None,
+            goal_progress=None,
+            goal_trajectory=None,
+            positioning=None,
+            recommendation=None,
+            intelligence_snapshot=None,
+            active_goal=None,
+            mode="RunnerOrchestrator"
+        )
+
+        logger.info("RunnerOrchestrator initialized")
+
+    async def _initialize(self):
+        """Asynchronous initialization (RunnerOrchestrator session initialization removed)."""
+        logger.info("Orchestrator skipping RunnerOrchestrator session initialization")
+        pass
+
+    def _select_active_weeks(self, all_affected_weeks: List[date]) -> Set[date]:
+        """
+        Selects weeks for which full intelligence (LLM) should be generated.
+        Standard: Current week + Previous week.
+        """
+        if not all_affected_weeks:
+            return set()
+            
+        sorted_weeks = sorted(all_affected_weeks)
+        current_week = sorted_weeks[-1]
+        
+        active_weeks = {current_week}
+        if len(sorted_weeks) > 1:
+            active_weeks.add(sorted_weeks[-2])
+            
+        return active_weeks
+
+    def reset(self):
+        import config
+        """Resets the orchestrator state by clearing stores and results."""
+        logger.info("Resetting orchestrator state")
+        self.db = None
+        self.weekly_repo.delete_all_for_runner(config.DEFAULT_RUNNER_ID)
+        self.analysis_repo = None
+        self.feature_store.clear()
+        self.plan_store.clear()
+        self.session_snapshots = {}
+        self.runner_profile = None
+        self.intelligence_snapshots = {}
+        self.session_runner_positioning = {}
+        self.session_view_positioning = {}
+        self.session_goal_trajectory = {}
+        self.latest_goal_trajectory = None
+        self._last_positioning = None
+        self._last_insights = {}
+        self._last_plan = None
+        self._last_brief = ""
+        self._last_focus = ""
+        self._last_runner_positioning = None
+        self.latest_goal_trajectory = None
+        self.latest_positioning = None
+        self.latest_plan = None
+        self.latest_brief = ""
+        self.latest_focus = ""
+        self.latest_positioning = None
+        self.latest_goal_trajectory = None
+        self.latest_insights = {}
+        self.latest_plan = None
+        self.latest_summary = {}
+        self.latest_risk_assessment = None
+
+    async def run(
+        self, 
+        runs: List[Dict[str, Any]], 
+        language: str = "en",
+        target_monday: Optional[date] = None,
+        weeks: Optional[List[date]] = None,
+        mode: str = "default"
+        ):
+        obs_logger.bind_new_trace_id()
+        with obs_logger.start_span("orchestrator.run", obs_components.ORCHESTRATOR):
+            start_time = time.time()
+            logger.info(f"Starting orchestration run with trace_id: {obs_logger.get_trace_id()}")
+            print(f"DEBUG: Orchestrator.run called with {len(runs)} runs")
+            self.runs_cache = runs
+
+            # 1. Initialize Pipeline Context
+            context = PipelineContext(
+                runs=runs,
+                language=language,
+                target_monday=target_monday,
+            )
+            context.sessions = self.session_snapshots  # Link to session cache
+
+            # Restore state for intelligence reuse
+            context.last_positioning = self._last_positioning
+            context.last_insights = self._last_insights
+            context.last_plan = self._last_plan
+            context.last_brief = self._last_brief
+            context.last_focus = self._last_focus
+            context.last_runner_positioning = self._last_runner_positioning
+            #context.last_positioning = self._last_positioning
+
+            # Load or create profile
+            from datetime import datetime
+            if self.runner_repo:
+                profile = self.runner_repo.get_runner_profile(uuid.UUID(config.DEFAULT_RUNNER_ID))
+                if not profile:
+                    logger.info("No profile found, creating default")
+                    profile = RunnerProfile(
+                        runner_id=uuid.UUID(config.DEFAULT_RUNNER_ID),
+                        created_at=datetime.now(timezone.utc),
+                        updated_at=datetime.now(timezone.utc),
+                    )
+                    self.runner_repo.save(profile)
+                context.runner_profile = profile
+                self.runner_profile = profile
+
+            if self.goal_repo:
+                context.active_goal = self.goal_repo.get_active_goal(uuid.UUID(config.DEFAULT_RUNNER_ID))
+
+            # 2. Build Pipeline
+            pipeline = RunnerPipeline([
+                FeatureEngineeringStep(self.feature_agent),
+                PersistRunsStep(self.run_persistence_service),
+                StructureStep(self.structure_service),
+                SnapshotStep(self.snapshot_service, self.weekly_trend_builder),
+                GuardrailStep(self.guardrail_agent),
+                ComparisonStep(self.weekly_repo),
+                PersistAnalysisStep(self.analysis_repo)
+            ])
+
+            # 3. Execute Pipeline
+            try:
+                await pipeline.execute(context)
+
+                # --- MULTI-WEEK INTELLIGENCE GENERATION ---
+                # SnapshotStep populated context.sessions. We ensure each has a full intelligence snapshot.
+                affected_weeks = context.sessions.keys()
+                runner_id = str(uuid.UUID(config.DEFAULT_RUNNER_ID))
+                self.snapshot_service.invalidate_weeks(runner_id, list(affected_weeks))
+                
+                all_affected_weeks = sorted(affected_weeks)
+                
+                # Filter by requested weeks if provided (Lazy Intelligence)
+                if weeks:
+                    all_affected_weeks = [w for w in all_affected_weeks if w in weeks]
+                
+                active_weeks = self._select_active_weeks(all_affected_weeks)
+                
+                # Capture global state before loop splits context
+                full_runs = context.runs
+                risk_assessment = context.risk_assessment
+                active_goal = context.active_goal
+                language = context.language
+                
+                # EARLY OPTIMIZATION: If no sessions were affected (e.g. all data was clean and cached), we can skip the multi-week loop entirely.
+                # Preserve primary target (usually latest) for final context state
+                primary_week = getattr(context.weekly_snapshot,"week_start_date", None)
+                
+                for w_start in all_affected_weeks:
+                    # In on_demand mode (Lazy), we force intelligence for all requested weeks
+                    if mode == "on_demand":
+                        enable_intelligence = True
+                        logger.info(f"[Lazy Intelligence] Triggered for week {w_start}")
+                    else:
+                        enable_intelligence = w_start in active_weeks
+                    
+                    # NEW: Fetch ALL runs for this week from repository to ensure full scope for viz and intel
+                    # This fixes the issue where only newly uploaded runs were used for weekly charts.
+                    all_week_runs = []
+                    if self.run_repo:
+                        runner_id_str = str(uuid.UUID(config.DEFAULT_RUNNER_ID))
+                        all_week_runs = self.run_repo.get_runs_for_week(runner_id_str, w_start)
+                        
+                        # Fallback for tests/in-memory: if repo is empty, use uploaded runs from context
+                        if not all_week_runs and context.runs:
+                            all_week_runs = [r for r in context.runs if week_start(r.get("start_time") if isinstance(r, dict) else r.start_time).date() == w_start]
+                            logger.info(f"[Orchestrator] Week {w_start} repository empty, fallback to context.runs (found {len(all_week_runs)})")
+
+                        # Ensure chronological order for IntelligenceStep.runs[-1]
+                        def run_start_time(r):
+                            if isinstance(r, dict):
+                                return r.get('start_time') or datetime.min.replace(tzinfo=timezone.utc)
+                            return getattr(r, 'start_time', datetime.min.replace(tzinfo=timezone.utc))
+                        
+                        all_week_runs = sorted(all_week_runs, key=run_start_time)
+                    
+                    # Create a fresh context for each week to avoid leak but preserve sessions
+                    week_context = PipelineContext(
+                        runner_profile=self.runner_profile,
+                        sessions=context.sessions,
+                        runs=all_week_runs, # Use all runs for the week (needed for IntelligenceStep)
+                        risk_assessment=risk_assessment,
+                        active_goal=active_goal,
+                        language=language,
+                        enable_intelligence=enable_intelligence,
+                        visualization_scope="weekly",
+                        # Pass cache to per-week context
+                        last_runner_positioning=self._last_runner_positioning,
+                        last_positioning=self._last_positioning,
+                        last_insights=self._last_insights,
+                        last_plan=self._last_plan,
+                        last_brief=self._last_brief,
+                        last_focus=self._last_focus,
+                        intelligence_cache=self.intelligence_cache
+                    )
+                    # Keep week-specific runs separately for weekly metrics if needed
+                    week_context.week_runs = all_week_runs # Use all runs for VisualizationStep
+                    logger.info(f"[Orchestrator] Week {w_start} → total week_runs: {len(all_week_runs)}")
+                    
+                    # 1. Setup focus for this specific week
+                    week_context.weekly_snapshot = context.sessions[w_start]
+                    
+                    # Compute WeeklyTrend (UI/Agent model) with historical context
+                    all_history = self.snapshot_service.get_history(12)
+                    hist_before = [h for h in all_history if h.week_start_date < w_start]
+                    week_context.weekly_trend = self.weekly_trend_builder.build(week_context.weekly_snapshot, hist_before)
+                    
+                    # 2. Refresh Agent context (summary/trends) for this specific week
+                    summary, trends = self.snapshot_service.build_agent_context_for_week(w_start)
+                    week_context.summary = summary
+                    week_context.trends = trends
+                    
+                    # --- OPTIMIZATION: DIRTY CHECK ---
+                    is_dirty = self.snapshot_service.is_week_dirty(w_start, summary)
+                    if mode != "on_demand" and not is_dirty:
+                        logger.info(f"[Orchestrator] Multi-week: Week {w_start} is CLEAN. Reusing existing snapshot.")
+                        cached_snap = self.snapshot_service.get_snapshot(w_start, language=language)
+                        week_context.intelligence_snapshot = cached_snap
+                        
+                        # Restore context fields from snapshot for API response consistency
+                        if cached_snap:
+                            week_context.insights = cached_snap.insights
+                            week_context.plan = cached_snap.insights.get("plan") if isinstance(cached_snap.insights, dict) else getattr(cached_snap.insights, "plan", None)
+                            week_context.positioning = cached_snap.positioning
+                            week_context.positioning_view = cached_snap.positioning_view
+                            week_context.recommendation = cached_snap.recommendation
+                            week_context.trends = cached_snap.trend
+                            week_context.goal_trajectory = cached_snap.goal_trajectory_data
+                            week_context.charts = cached_snap.charts
+                        
+                        # Store in global intelligence_snapshots for later resolution
+                        if cached_snap:
+                            self.intelligence_snapshots[(w_start, language)] = cached_snap
+
+                        continue
+
+                    # --- LAZY INTELLIGENCE: SKIP IF ALREADY AVAILABLE ---
+                    existing_snapshot = self.snapshot_service.get_snapshot(w_start, language=language)
+                    if mode != "on_demand" and self.snapshot_service.has_intelligence(existing_snapshot) and not is_dirty:
+                        logger.info(f"[Lazy Intelligence] Skipped (already available) for week {w_start}")
+                        week_context.intelligence_snapshot = existing_snapshot
+                        # Restore context fields (brief already in snapshot)
+                        if existing_snapshot:
+                            week_context.insights = existing_snapshot.insights
+                            week_context.plan = existing_snapshot.insights.get("plan") if isinstance(existing_snapshot.insights, dict) else getattr(existing_snapshot.insights, "plan", None)
+                            week_context.positioning = existing_snapshot.positioning
+                            week_context.positioning_view = existing_snapshot.positioning_view
+                            week_context.recommendation = existing_snapshot.recommendation
+                            week_context.trends = existing_snapshot.trend
+                            week_context.goal_trajectory = existing_snapshot.goal_trajectory_data
+                            week_context.charts = existing_snapshot.charts
+                            
+                            self.intelligence_snapshots[(w_start, language)] = existing_snapshot
+
+                        continue
+
+                    logger.info(f"[Orchestrator] Multi-week: Week {w_start} is DIRTY or ON-DEMAND. Recomputing intelligence.")
+
+                    # NOT returning goal_trajectory / goal_progress data
+                    await self._run_intelligence_for_context(week_context, enable_intelligence=enable_intelligence)
+                    
+                    # 4. Produce and Store Intelligence Snapshot
+                    snapshot = build_intelligence_snapshot(week_context)
+                    self.snapshot_service.store_snapshot(w_start, snapshot, language=language)
+                    self.intelligence_snapshots[(w_start, language)] = snapshot  # Fixed: Must update cache for results
+                    
+                    if runs: # Only persist if there are new runs uploaded otherwise charts exists in the snapshot
+                        self.snapshot_service.persist_intelligence_snapshot(snapshot)
+                        logger.info(f"[DEBUG] Persist charts → snapshot_id={snapshot.id}")
+                    logger.debug(f"[Orchestrator] Multi-week: Generated and stored intelligence snapshot for {w_start} ({language})")
+
+                # Restore primary focus for the API response
+                if primary_week and primary_week in context.sessions:
+                    context.weekly_snapshot = context.sessions[primary_week]
+                    context.weekly_trend = self.trend_repo.get_by_week(primary_week) if self.trend_repo else None
+                    summary, trends = self.snapshot_service.build_agent_context_for_week(primary_week)
+                    context.summary = summary
+                    context.trends = trends
+                    snap = self.intelligence_snapshots.get((primary_week, language))
+                    context.intelligence_snapshot = snap
+                    if snap:
+                        context.insights = snap.insights
+                        context.plan = snap.plan
+                        context.recommendation = snap.recommendation
+                        context.positioning = snap.positioning
+                        context.goal_trajectory = snap.goal_trajectory_data
+                        context.charts = snap.charts  # PRESERVED: DO NOT RESTORE SNAPSHOT CHARTS TO MAIN CONTEXT
+                        context.weekly_brief = snap.weekly_brief
+                        context.weekly_focus = snap.weekly_focus
+                        context.goal_view = snap.goal_view
+
+                # --- GENERATE FULL SCOPE CHARTS ---
+                # These are aggregated across all uploaded runs and assigned to the top-level context.
+                if runs and len(all_affected_weeks) > 1:
+                    logger.info("[Orchestrator] Generating FULL SCOPE charts for top-level results")
+                    context.visualization_scope = "full"
+                    viz_step = VisualizationStep(self.visualization_agent, self.viz_executor)
+                    await viz_step.run(context)
+                
+                # Calculate num_runs and weeks for the response metadata
+                num_runs = len(runs)
+                weeks = 0
+                if runs:
+                    from datetime import datetime
+                    dates = []
+                    for r in runs:
+                        d = r.get("start_time")
+                        if isinstance(d, datetime):
+                            dates.append(d)
+                        elif isinstance(d, str):
+                            try:
+                                dates.append(datetime.fromisoformat(d.replace("Z", "+00:00")))
+                            except:
+                                pass
+                    if dates:
+                        delta = max(dates) - min(dates)
+                        weeks = max(1, (delta.days // 7) + 1)
+
+                # Update legacy stores for backward compatibility
+                detailed_features = [
+                    f.model_dump(mode="json") if hasattr(f, "model_dump") else f for f in context.runs
+                ]
+                for feat in detailed_features:
+                    run_id = feat.get("id") or str(uuid.uuid4())
+                    self.feature_store.put_features(run_id, feat)
+                
+                if context.summary:
+                    self.feature_store.put_weekly_summary("latest", context.summary)
+                
+                if context.plan:
+                    self.plan_store.save_plan("latest", context.plan)
+
+                # Store latest in orchestrator for chat consistency
+                self.latest_insights = context.insights
+                self.latest_plan = context.plan
+                self.latest_summary = context.summary
+                self.latest_risk_assessment = context.risk_assessment
+
+                # Update orchestrator cache from context
+                self._last_runner_positioning = context.last_runner_positioning
+                self._last_positioning = context.last_positioning
+                self._last_insights = context.last_insights
+                self._last_plan = context.last_plan
+                self._last_brief = context.last_brief
+                self._last_focus = context.last_focus
+                self.latest_goal_trajectory = getattr(context, "goal_trajectory", None)
+                if self.latest_goal_trajectory and context.weekly_snapshot:
+                    self.session_goal_trajectory[context.weekly_snapshot.week_start_date] = self.latest_goal_trajectory
+
+                logger.info("Orchestration run completed via Pipeline architecture")
+
+                # Helper for safe DTO dumping (handles both objects and dicts from cache)
+                def _safe_dump(obj):
+                    if obj is None: return None
+                    if isinstance(obj, dict): return obj
+                    if hasattr(obj, "model_dump"): return obj.model_dump()
+                    return obj
+
+                # 3. Construct DTO response
+                # Final pass ensure everything is JSON serializable
+                try:
+                    from tools.helpers import decode_chart
+                    self.dto_response = RunnerAPIResponse(
+                        num_runs=num_runs,
+                        weeks=weeks,
+                        features=detailed_features,
+                        insights=context.insights,
+                        plan=context.plan,
+                        risk_assessment=_safe_dump(context.risk_assessment),
+                        trends=context.trends, # Week specific trend
+                        period_comparison=context.period_comparison,
+                        charts=decode_chart(context.charts),
+                        profile=_safe_dump(context.runner_profile),
+                        goal_progress=_safe_dump(getattr(context.intelligence_snapshot, 'goal_view', {})),
+                        goal_trajectory=_safe_dump(context.goal_trajectory),
+                        positioning=_safe_dump(context.positioning),
+                        recommendation=_safe_dump(context.recommendation),
+                        # ✅ KEY CHANGE
+                        intelligence_snapshot=context.intelligence_snapshot_serialized if hasattr(context, 'intelligence_snapshot_serialized') else serialize_snapshot(context.intelligence_snapshot),
+                        active_goal=_safe_dump(context.active_goal),
+                    )
+                except Exception as ser_err:
+                    logger.error(f"Serialization failed in Orchestrator DTO layer: {ser_err}")
+                    # Fallback to minimal serializable DTO
+                    self.dto_response = RunnerAPIResponse(
+                        num_runs=num_runs,
+                        weeks=weeks,
+                        features=[],
+                        insights={"error": "Serialization failed"},
+                        plan=None,
+                        risk_assessment=None,
+                        trends=None,
+                        period_comparison=None,
+                        charts={},
+                        profile=None,
+                        goal_progress=None,
+                        goal_trajectory=None,
+                        positioning=None,
+                        recommendation=None,
+                        intelligence_snapshot=None
+                    )
+
+                return self.dto_response #.__dict__
+            except Exception as e:
+                obs_logger.log_event(
+                    "error",
+                    f"Orchestration pipeline failed: {e}",
+                    event="error",
+                    component=obs_components.ORCHESTRATOR,
+                    error_type=type(e).__name__,
+                    error_message=str(e),
+                    duration_ms=(time.time() - start_time) * 1000,
+                )
+                raise
+
+
+    def _persist_analysis(
+        self,
+        features: List[Dict],
+        insights: Any,
+        plan: str,
+        risk_assessment: RiskAssessment,
+        trends: WeeklyTrends,
+        ):
+        """Helper to persist analysis artefacts safely."""
+        if not self.analysis_repo:
+            return
+
+        try:
+            # Combine trends and risk assessment into run_summary
+            run_summary = trends.model_dump()
+            if risk_assessment:
+                run_summary["risk_assessment"] = risk_assessment.model_dump()
+
+            record = AnalysisRecord(
+                source_files=[],
+                formats=[],
+                run_summary=run_summary,
+                run_timeseries=features,
+                insights_json=(
+                    insights
+                    if isinstance(insights, dict)
+                    else (
+                        insights.model_dump()
+                        if hasattr(insights, "model_dump")
+                        else {"content": str(insights)}
+                    )
+                ),
+                plan_json={"content": plan},
+                route_json={},
+            )
+            self.analysis_repo.save(record)
+            logger.info(f"Analysis persisted with ID: {record.id}")
+        except Exception as e:
+            logger.warning(f"Failed to persist analysis: {e}")
+
+    async def chat(self, message: str, language: str = "en") -> Dict[str, Any]:
+        """
+        Handles a chat message from the user.
+        Returns a dictionary with 'response' (text) and optionally 'chart' (figure).
+        """
+        obs_logger.bind_new_trace_id()
+        with obs_logger.start_span("orchestrator.chat", obs_components.ORCHESTRATOR):
+            start_time = time.time()
+
+            logger.info(f"Starting chat handling with trace_id: {obs_logger.get_trace_id()}")
+
+            try:
+                session_features = self.feature_store.get_all_features()
+
+                # Load all historic features to provide a complete picture
+                historic_features = []
+                if self.run_repo:
+                    try:
+                        # Note: RunRepository needs mapping from analyses for now
+                        # but get_all_features usually returns all from all analyses
+                        historic_features = (
+                            self.analysis_repo.get_all_features()
+                            if hasattr(self.analysis_repo, "get_all_features")
+                            else []
+                        )
+                    except Exception as e:
+                        logger.warning(f"Failed to load historic features: {e}")
+
+                # Merge and deduplicate
+                all_features_map = {f.get("id") or f.get("start_time"): f for f in historic_features}
+                for f in session_features:
+                    key = f.get("id") or f.get("start_time")
+                    all_features_map[key] = f
+
+                all_features = list(all_features_map.values())
+
+                # Issue #30: Auto-inject last 4 insights if no new upload in this session
+                auto_injected_insights = []
+                is_no_upload = not session_features
+
+                if is_no_upload and self.analysis_repo:
+                    try:
+                        # Fetch exactly 4 per requirement
+                        auto_injected_insights = self.analysis_repo.get_recent_insights(limit=4)
+                        logger.info(
+                            f"Auto-injected {len(auto_injected_insights)} recent insights (no upload detected)"
+                        )
+                    except Exception as e:
+                        logger.warning(f"Failed to load auto-injected insights: {e}")
+
+                # Global "No Data" check
+                if not all_features and not auto_injected_insights:
+                    return {
+                        "response": "I don't have any running data from you yet. Please upload your .tcx / .fit files so I can help you!"
+                    }
+
+                # Sort features by date descending (most recent first)
+                def get_date(f):
+                    dt = f.get("start_time")
+                    if isinstance(dt, str):
+                        try:
+                            return datetime.fromisoformat(dt.replace("Z", "+00:00")).date()
+                        except:
+                            return date.min
+                    elif isinstance(dt, datetime):
+                        return dt.date()
+                    elif isinstance(dt, date):
+                        return dt
+                    return date.min
+
+                all_features = sorted(all_features, key=get_date, reverse=True)
+
+                # 1. Route the request using the new structured router
+                decision = await async_route(
+                    message, raw_context={"features": all_features}, llm_client=self.router_client
+                )
+                intent = decision.route
+                logger.info(f"[ORCH] Router: route={intent}, metric={decision.metric}, period={decision.period}, target_date={decision.target_date}")
+
+                if intent == "CHART":
+                    # 1. Handle explicit 'this month' or similar periods
+                    if decision.period and "month" in decision.period.lower():
+                        month_start = date.today().replace(day=1)
+                        all_features = [f for f in all_features if get_date(f) >= month_start]
+                        logger.info(f"[ORCH] Filtered to {len(all_features)} runs for current month (start: {month_start})")
+                    
+                    # 2. Handle default 30-day window for null/unrecognized periods
+                    elif not decision.period or decision.period in [None, "", "null", "none", "last_30_days"]:
+                        if not decision.target_date: # target_date overrides the 30-day default
+                            one_month_ago = date.today() - timedelta(days=30)
+                            all_features = [f for f in all_features if get_date(f) >= one_month_ago]
+                            logger.info(f"[ORCH] No specific period. Defaulted to 30-day filter (count: {len(all_features)})")
+                    
+                    # 3. 'all_time' remains unfiltered
+                    elif decision.period == "all_time":
+                        logger.info(f"[ORCH] 'all_time' requested. Using all {len(all_features)} runs.")
+
+                if intent == "CHART":
+                    # Smart retrieval: Check if it's a specific week matched by the router
+                    if decision.target_date:
+                        snapshot = self.get_intelligence_snapshot(decision.target_date, language=language)
+                        if snapshot and snapshot.charts:
+                            # Normalize metric name for snapshot lookup
+                            metric_map = {
+                                "heart_rate": "hr",
+                                "heartrate": "hr",
+                                "hr": "hr",
+                                "pace": "pace",
+                                "distance": "volume",
+                                "volume": "volume",
+                                "frequency": "frequency",
+                            }
+                            norm_metric = metric_map.get(decision.metric.lower(), "pace") if decision.metric else "pace"
+                            target_key = f"{norm_metric}_chart"
+                            fig = snapshot.charts.get(target_key) or snapshot.charts.get("pace_chart")
+                            
+                            if fig:
+                                obs_logger.log_event("info", "Snapshot chart cache hit", event="snapshot_cache_hit", week=str(decision.target_date))
+                                return {
+                                    "response": f"Here is the {decision.metric or 'pace'} chart from the week of {decision.target_date}.",
+                                    "chart": fig,
+                                }
+
+                    # Fallback to Visualization Agent for multi-week or custom charts
+                    chart_specs = await self.visualization_agent.run(all_features, query=message, intent=decision)
+
+                    if chart_specs:
+                        # Render the best match for the chat interface
+                        spec = chart_specs[0]
+                        fig = self.viz_executor.render_chart(spec, all_features)
+                        return {
+                            "response": f"I've generated a {spec.chart_type} chart based on your request.",
+                            "chart": fig,
+                        }
+                    else:
+                        return {
+                            "response": "I couldn't find a way to visualize those metrics with your current data. Could you try asking for a summary instead?"
+                        }
+
+                else:
+                    # Delegate to Chat Agent
+                    summary = self.latest_summary
+                    trends = self.latest_trends
+
+                    # If session state is raw dict (e.g. from previous run before refactor),
+                    # convert to model or fallback to building from snapshots
+                    if isinstance(summary, dict) or isinstance(trends, dict) or not summary:
+                        summary, trends = self.snapshot_service.build_agent_context()
+
+                    latest_plan = self.latest_plan or self.plan_store.get_latest_plan()
+                    current_insights = self.latest_insights
+
+                    # Maintain the 10-limit historic context for general memory if needed,
+                    # but we'll use auto_injected_insights specifically for the prompt injection.
+                    historic_insights = []
+                    if self.analysis_repo:
+                        try:
+                            historic_insights = self.analysis_repo.get_recent_insights(limit=10)
+                        except Exception as e:
+                            logger.warning(f"Failed to load historic insights: {e}")
+
+                    response_text = await self.chat_agent.run(
+                        message,
+                        context={
+                            "features": all_features,
+                            "insights": current_insights,
+                            "plan": latest_plan,
+                            "summary": summary,
+                            "historic_insights": historic_insights,
+                            "auto_injected_insights": auto_injected_insights,
+                            "is_no_upload": is_no_upload,
+                        },
+                        language=language,
+                    )
+                    return {"response": response_text}
+
+            except Exception as e:
+                return {"response": f"I encountered an error: {str(e)}"}
+
+    def load_last_analysis(self) -> Optional[AnalysisRecord]:
+        """Debug helper to load the last persisted analysis."""
+        if not self.analysis_repo:
+            return None
+        return self.analysis_repo.get_last_analysis()
+
+    async def generate_performance_card(
+        self, snapshot: Any, trend: Any, language: str = "en"
+     ) -> Any:
+        # Pydantic support for dict inputs from UI
+        if isinstance(snapshot, dict):
+            snapshot = WeeklySnapshot.model_validate(snapshot)
+        if isinstance(trend, dict):
+            trend = WeeklyTrend.model_validate(trend)
+
+        """
+        Centralized entry point for generating performance cards.
+        Enforces architecture boundary by keeping BriefService internal.
+        """
+        obs_logger.ensure_trace()
+        with obs_logger.start_span("orchestrator.performance_card", component=obs_components.ORCHESTRATOR):
+            from services.performance_card_service import PerformanceCardService
+
+            # Boundary Enforcement: Orchestrator owns the nested span and event emission
+            with obs_logger.start_span("performance_card.generate", component=obs_components.APPLICATION):
+                service = PerformanceCardService()
+                card = await service.generate(
+                    snapshot=snapshot,
+                    trend=trend,
+                    brief_service=self.brief_service,
+                    language=language,
+                )
+
+                obs_logger.log_event(
+                    "info",
+                    "Performance card generated successfully",
+                    event="performance_card_generated",
+                    component=obs_components.ORCHESTRATOR,
+                    **{
+                        "week_start": str(snapshot.week_start_date),
+                        "comparison_available": trend.comparison_available,
+                        "comparison_type": trend.comparison_type,
+                        "llm_used": card.llm_used,  # Use actual execution status
+                    },
+                )
+                return card
+
+    async def generate_runner_positioning(
+        self, snapshot: Any, trend: Any, language: str = "en"
+        ) -> Any:
+        # Pydantic support for dict inputs from UI
+        if isinstance(snapshot, dict):
+            snapshot = WeeklySnapshot.model_validate(snapshot)
+        if isinstance(trend, dict):
+            trend = WeeklyTrend.model_validate(trend)
+
+        """
+        Generates runner positioning assessment (v1).
+        Uses session memory to avoid recomputation if possible.
+        """
+        obs_logger.ensure_trace()
+        with obs_logger.start_span("positioning.generate", component=obs_components.APPLICATION):
+            # 1. Check View Cache
+            if snapshot.week_start_date in self.session_view_positioning:
+                return self.session_view_positioning[snapshot.week_start_date]
+
+            # 2. Recompute if missing (e.g. initial load without new analysis)
+            positioning = self.positioning_engine.compute(snapshot, trend)
+            self.session_view_positioning[snapshot.week_start_date] = positioning
+
+            # 3. Emit Event (STEP 10)
+            obs_logger.log_event(
+                "info",
+                "Runner positioning computed",
+                event="positioning_computed",
+                component=obs_components.APPLICATION,
+                week=str(snapshot.week_start_date),
+                status=positioning.status, # WeeklyPositioning has 'status'
+                signal_strength=str(positioning.signal_strength)
+            )
+
+            return positioning
+
+    def get_intelligence_snapshot(self, week_start: Optional[date] = None, language: str = "en") -> Optional[RunnerIntelligenceSnapshot]:
+        """
+        Retrieves the intelligence snapshot for a specific week and language.
+        If week_start is not provided or not found, falls back to the most recent snapshot for THAT language.
+        """
+        if not self.intelligence_snapshots:
+            logger.debug("[Orchestrator] No snapshots available in store.")
+            return None
+
+        # 1. Exact match (Week + Language)
+        if week_start and (week_start, language) in self.intelligence_snapshots:
+            logger.debug(f"[Orchestrator] Found exact snapshot match for {week_start} ({language})")
+            return self.intelligence_snapshots[(week_start, language)]
+
+        # 2. Defensive check: filter for valid tuple keys to avoid TypeError on legacy date-only keys
+        tuple_keys = [k for k in self.intelligence_snapshots.keys() if isinstance(k, tuple) and len(k) == 2]
+
+        # 3. If week_start exists but in different language, we return None 
+        # to force on-demand recomputation for the new language.
+        week_exists_other_lang = any(k[0] == week_start for k in tuple_keys)
+        if week_start and week_exists_other_lang:
+            logger.debug(f"[Orchestrator] Week {week_start} found but not in {language}. Returning None to trigger recompute.")
+            return None
+
+        # 4. Fallback to latest available for THIS language
+        lang_snapshots = {k[0]: v for k, v in self.intelligence_snapshots.items() 
+                         if isinstance(k, tuple) and len(k) == 2 and k[1] == language}
+        if lang_snapshots:
+            sorted_weeks = sorted(lang_snapshots.keys(), reverse=True)
+            latest_week = sorted_weeks[0]
+            logger.debug(f"[Orchestrator] Fallback to latest {language} snapshot [DISABLED]: {latest_week}")
+            return None #lang_snapshots[latest_week]
+
+        # 5. Global fallback if nothing found for this language
+        logger.debug(f"[Orchestrator] No snapshot found for {language}. Returning None.")
+        return None
+
+    def _is_snapshot_complete(self, snapshot) -> bool:
+        return all([
+            snapshot.weekly_snapshot is not None,
+            snapshot.weekly_trend is not None,
+            snapshot.positioning_view is not None,
+            snapshot.plan is not None,
+            snapshot.recommendation is not None,
+            snapshot.evidence_view is not None,
+            #snapshot.charts is not None, #TODO: re-enable when visualization is fixed
+        ])
+
+    async def get_or_build_intelligence_snapshot(
+        self,
+        week_start: date,
+        language: str = "en"
+    ) -> Optional[RunnerIntelligenceSnapshot]:
+        """
+        Lazy-load intelligence snapshot using cache-aside pattern.
+
+        - Returns cached snapshot if available
+        - Otherwise builds it on-demand for the requested week
+        """
+
+        # 1. Fast Path: Cache-Aside Lookup
+        # We only reuse if it actually HAS intelligence (not a shell snapshot)
+        existing = self.get_intelligence_snapshot(week_start, language=language)
+        if existing:
+            if not self._is_snapshot_complete(existing):
+                logger.debug(f"[Snapshot] Rebuilding week: {week_start} (incomplete snapshot)")
+            else:
+                obs_logger.log_event(
+                    "info", 
+                    "Intelligence snapshot cache hit (active)", 
+                    event="intelligence_cache_hit", 
+                    week=str(week_start), 
+                    language=language
+                )
+                logger.debug(f"[Snapshot] Using cached snapshot: {week_start}")
+                return existing
+        else:
+            logger.debug(f"[Snapshot] Rebuilding week: {week_start} (not found)")
+
+        # 2. Guardrail → no data, no intelligence
+        weekly = self.weekly_repo.get_by_week(week_start) if self.weekly_repo else None
+        if not weekly:
+            return None
+
+        # 3. Build agent context for this specific week
+        # We need to ensure we have the runner_id correctly
+        runner_id = weekly.runner_id if hasattr(weekly, "runner_id") else uuid.UUID(config.DEFAULT_RUNNER_ID)
+        
+        # 3.1 Fetch runs for this week
+        week_runs = []
+        if self.run_repo:
+            week_runs = self.run_repo.get_runs_for_week(str(runner_id), week_start)
+
+        summary, trends = self.snapshot_service.build_agent_context_for_week(target_date=week_start)
+
+        if not summary:
+            return None
+
+        # Create context specifically for this lazy orchestration
+        # 3. Prepare context for lazy built
+        active_goal = self.goal_service.get_active_goal(self.runner_profile.runner_id)
+        
+        # We reuse global state for consistency
+        context = PipelineContext(
+            runner_profile=self.runner_profile,
+            runs=week_runs,
+            sessions=self.session_snapshots, # Fallback to in-memory snapshots if persistent repo fails
+            language=language,
+            enable_intelligence=True,
+            target_monday=week_start,
+            summary=summary,
+            trends=trends,
+            active_goal=active_goal,
+            last_runner_positioning=self._last_runner_positioning,
+            last_positioning=self._last_positioning,
+            last_insights={},
+            last_plan=None,
+            last_focus=self._last_focus,
+            visualization_scope="weekly",
+            intelligence_cache={}
+        )
+        context.weekly_snapshot = weekly
+        
+        # Build WeeklyTrend for this week
+        all_history = self.snapshot_service.get_history(12)
+        hist_before = [h for h in all_history if h.week_start_date < week_start]
+        context.weekly_trend = self.weekly_trend_builder.build(weekly, hist_before)
+
+        obs_logger.log_event(
+            "info",
+            f"Lazy intelligence generation triggered for {week_start}",
+            component=obs_components.APPLICATION,
+            week=str(week_start),
+            cached=False
+        )
+
+        # 4. Run Intelligence-related steps
+        await self._run_intelligence_for_context(context, enable_intelligence=True)
+
+        # 5. Build snapshot
+        snapshot = build_intelligence_snapshot(context)
+
+        # 6. Store in cache and persistence
+        self.snapshot_service.store_snapshot(week_start, snapshot, language=language)
+        self.intelligence_snapshots[(week_start, language)] = snapshot
+
+        return snapshot
+
+    async def _run_intelligence_for_context(self, context, enable_intelligence: bool = True):
+        """
+        Runs only intelligence-related steps for a prepared context.
+        This avoids re-running full ingestion pipeline.
+        """
+        # Reproduce EXACT dependency injection logic from run()
+        intelligence_steps = [
+            GuardrailStep(self.guardrail_agent),
+            ComparisonStep(self.weekly_repo),
+            PersistAnalysisStep(self.analysis_repo),
+            PositioningStep(self.positioning_service, self.recommendation_service, self.goal_progress_service, self.goal_service),
+            GoalTrajectoryStep(self.goal_service, self.goal_trajectory_service),
+        ]
+        
+        if enable_intelligence:
+            intelligence_steps.extend([
+                IntelligenceStep(
+                    self.insights_agent, 
+                    self.plan_agent, 
+                    self.brief_service, 
+                    self.weekly_repo, 
+                    self.guardrail_arbitration_service, 
+                    self.positioning_change_service, 
+                    self.goal_progress_service, 
+                    self.goal_service
+                ),
+                VisualizationStep(self.visualization_agent, self.viz_executor)
+            ])
+            
+        for step in intelligence_steps:
+            await step.run(context)
+
+
+async def get_orchestrator(use_RunnerOrchestrator: bool = True):
+    orchestrator = RunnerOrchestrator()
+    await orchestrator._initialize()
+    return orchestrator

src/agents/plan/agent.py

@@ -0,0 +1,165 @@
+from typing import Dict, Any, Optional
+import logging
+import json
+import time
+from observability import logger as obs_logger
+from observability import components as obs_components
+
+from domain.training.agent_models import PlanOutput, WeeklySummary
+from domain.runner.profile import RunnerProfile
+from domain.runner.goal import Goal
+from llm.base import LLMClient
+from pathlib import Path
+
+logger = logging.getLogger(__name__)
+
+
+class PlanAgent:
+    """
+    Generates a weekly plan using an LLM based on recent mileage and consistency via the provided LLMClient.
+    """
+
+    def __init__(self, llm_client: LLMClient):
+        self.llm_client = llm_client
+        self.instruction = self._load_instruction("en")
+
+    def _load_instruction(self, language: str = "en") -> str:
+        try:
+            # Resolve path relative to this file: src/agents/plan/../../prompts/
+            base_path = Path(__file__).parent.parent.parent / "prompts"
+            filename = f"plan_{language}.txt"
+            file_path = base_path / filename
+
+            if not file_path.exists():
+                logger.warning(f"Prompt file not found: {file_path}. Falling back to English.")
+                file_path = base_path / "plan_en.txt"
+
+            if not file_path.exists():
+                logger.error("English prompt file missing!")
+                return "You are generating a weekly running plan. Output JSON."
+
+            return file_path.read_text(encoding="utf-8")
+        except Exception as e:
+            logger.error(f"Error loading prompt for language {language}: {e}")
+            return "You are generating a weekly running plan. Output JSON."
+
+    async def run(
+        self,
+        features: WeeklySummary,
+        language: str = "en",
+        profile: Optional[RunnerProfile] = None,
+        goal: Optional[Goal] = None,
+    ) -> Dict[str, Any]:
+        with obs_logger.start_span("plan_agent.run", obs_components.AGENT):
+            start_time = time.time()
+            # Load language-specific instruction
+            self.instruction = self._load_instruction(language)
+
+            # Take most recent week from WeeklySummary
+            if features.weekly_km:
+                # take most recent week by sorting keys (YYYY-WW)
+                weeks = sorted(features.weekly_km.items(), reverse=True)
+                recent_km = weeks[0][1]
+            else:
+                recent_km = 0.0
+
+            cons = features.consistency_score
+
+            # Construct Prompt
+            prompt = self._construct_prompt(
+                recent_km, cons, language=language, profile=profile, goal=goal
+            )
+
+            try:
+                # Call LLM via Client
+                with obs_logger.start_span("plan_agent.llm", obs_components.AGENT):
+                    plan_output = await self.llm_client.generate(
+                        prompt, instruction=self.instruction, schema=None, name="plan_agent"
+                    )
+
+                result = None
+                if isinstance(plan_output, PlanOutput):
+                    result = {"plan": plan_output.plan}
+                elif isinstance(plan_output, dict):
+                    if "plan" in plan_output:
+                        if isinstance(plan_output["plan"], str):
+                            result = {"plan": plan_output["plan"]}
+                        else:
+                            result = {"plan": json.dumps(plan_output)}
+                    else:
+                        result = {"plan": json.dumps({"plan": plan_output})}
+                elif isinstance(plan_output, str):
+                    raw = plan_output.strip()
+                    result = {"plan": raw}
+                else:
+                    logger.error(f"Unexpected response type from LLM: {type(plan_output)}")
+                    fail_msg = (
+                        "Não foi possível gerar o plano neste momento."
+                        if language == "pt-BR"
+                        else "Could not generate plan at this time."
+                    )
+                    result = {"plan": fail_msg}
+
+                return result
+
+            except Exception as e:
+                duration_ms = (time.time() - start_time) * 1000
+                obs_logger.log_event(
+                    "error",
+                    f"Failed to generate plan: {e}",
+                    event="error",
+                    component=obs_components.AGENT,
+                    duration_ms=duration_ms,
+                )
+                logger.error(f"Failed to generate plan with LLM: {e}", exc_info=True)
+                fail_msg = (
+                    "Não foi possível gerar o plano neste momento devido a um erro."
+                    if language == "pt-BR"
+                    else "Could not generate plan at this time due to an error."
+                )
+                return {"plan": fail_msg}
+
+    def _construct_prompt(
+        self,
+        recent_km: float,
+        consistency: int,
+        language: str = "en",
+        profile: Optional[RunnerProfile] = None,
+        goal: Optional[Goal] = None,
+    ) -> str:
+        is_pt = language == "pt-BR"
+        profile_context = ""
+        if profile:
+            profile_context = "\n**Runner Profile Context:**\n"
+            if profile.runner_display_name:
+                profile_context += f"- Display Name: {profile.runner_display_name}\n"
+            if profile.age:
+                profile_context += f"- Age: {profile.age}\n"
+            if profile.experience_level:
+                profile_context += f"- Experience Level: {profile.experience_level}\n"
+            if profile.baseline_weekly_km:
+                profile_context += f"- Baseline Weekly KM: {profile.baseline_weekly_km}\n"
+            if profile.injury_history_notes:
+                profile_context += f"- Injury Notes: {profile.injury_history_notes}\n"
+
+        if goal:
+            goal_type_label = goal.type.replace("_", " ").title()
+            date_str = goal.target_date.strftime("%Y-%m-%d") if goal.target_date else "N/A"
+            profile_context += f"\n**Current Active Goal:**\n"
+            profile_context += f"- Type: {goal_type_label}\n"
+            profile_context += f"- Target: {goal.target_value} {goal.unit}\n"
+            profile_context += f"- Target Date: {date_str}\n"
+
+        if is_pt:
+            return f"""
+**Perfil do Corredor:**
+{profile_context}
+- Quilometragem Semanal Recente: {recent_km:.1f} km
+- Score de Consistência: {consistency}/100
+"""
+        return f"""
+**Runner Profile:**
+{profile_context}
+- Recent Weekly Mileage: {recent_km:.1f} km
+- Consistency Score: {consistency}/100
+"""

src/agents/visualization/__init__.py

@@ -0,0 +1,3 @@
+from .agent import VisualizationAgent
+
+__all__ = ["VisualizationAgent"]

src/agents/visualization/agent.py

@@ -0,0 +1,114 @@
+from typing import List, Dict, Any, Optional
+import logging
+import json
+import time
+from observability import logger as obs_logger
+from observability import components as obs_components
+from agents.base import BaseAgent
+from domain.training.charts import ChartSpec, ChartType
+from llm.base import LLMClient
+from router.models import RouteDecision
+from router.compact import compact_raw_context
+
+from pydantic import BaseModel, Field
+
+logger = logging.getLogger(__name__)
+
+
+class VisualizationAgentOutput(BaseModel):
+    """The structured output from the VisualizationAgent."""
+    charts: List[ChartSpec] = Field(description="The list of charts to generate.")
+
+
+class VisualizationAgent(BaseAgent):
+    """
+    Agent responsible for specifying visualizations from run data using LLM.
+    Returns ChartSpec objects instead of executing code.
+    """
+
+    def __init__(self, llm_client: LLMClient):
+        self.llm_client = llm_client
+        self.instruction = """You are a data visualization expert. Your goal is to specify charts to visualize run data.
+            
+            Return a JSON object containing a 'charts' list. Each chart in the list must have:
+            - 'chart_type': One of ['pace', 'heart_rate', 'volume', 'frequency', 'zones', 'dynamic']
+            - 'title': A descriptive title for the chart.
+            - 'params': (Optional) A dictionary of parameters.
+            
+            Chart Types:
+            - 'pace': Pace vs Date
+            - 'heart_rate': Heart Rate vs Date
+            - 'volume': Weekly mileage (distance)
+            - 'frequency': Number of runs per week
+            - 'zones': Distribution of Effort/HR zones
+            - 'dynamic': Custom chart with provided 'labels', 'values', and 'type' (bar/pie/line) in params.
+            
+            When asked to generate charts:
+            1. If you need a custom chart (not pace/hr/volume/freq/zones), use 'dynamic' and specify labels and values in 'params'.
+               Example params for dynamic: {"labels": ["Mon", "Tue"], "values": [5, 10], "type": "bar"}
+            2. Consider the 'periods' (n_weeks, etc.) provided in the extracted intent.
+            3. Default to showing the last 4 weeks of data unless 'all_time' or a specific range is requested.
+            4. Always include 'pace' and 'heart_rate' charts by default if no specific query is provided.
+            """
+
+
+    async def run(
+        self,
+        features: List[Dict[str, Any]],
+        query: str = "",
+        intent: Optional[RouteDecision] = None
+    ) -> List[ChartSpec]:
+        with obs_logger.start_span("visualization_agent.run", obs_components.AGENT):
+            """
+            Generates chart specifications using the LLM.
+            """
+            intent_info = ""
+            if intent:
+                intent_info = f"\nExtracted Intent: Metric={intent.metric}, Period={intent.period}, Target Date={intent.target_date}"
+
+            if query:
+                # Use compact_raw_context for prompt injection as per user feedback
+                compacted_features = compact_raw_context({"features": features}, max_elements=25).get("features", [])
+                
+                prompt = f"""
+                The user has requested a specific visualization: "{query}"{intent_info}
+                There are {len(features)} runs available in history.
+                
+                **Relevant Data Context (Compacted):**
+                {json.dumps(compacted_features, default=str, indent=2)}
+                
+                ACTION: Please specify the most appropriate chart(s) according to the schema.
+                If they ask for frequency or "by day", use 'frequency'.
+                """
+            else:
+                prompt = f"""
+                Generate default visualizations for the provided {len(features)} runs.
+                Please request:
+                1. A pace chart ('pace')
+                2. A heart rate chart ('heart_rate')
+                """
+
+            try:
+                res = await self.llm_client.generate(
+                    prompt,
+                    instruction=self.instruction,
+                    schema=VisualizationAgentOutput,
+                    name="visualization_agent",
+                )
+                logger.info(f"[VIZ DEBUG] LLM raw response type: {type(res)}")
+                if isinstance(res, VisualizationAgentOutput):
+                    logger.info(f"[VIZ DEBUG] Specs generated: {len(res.charts)}")
+                    return res.charts
+                
+                logger.warning(f"[VIZ DEBUG] LLM returned non-schema response: {res}")
+                return []
+            except Exception as e:
+                logger.error(f"LLM specification failed: {e}")
+                
+                # Fallback if no specs were generated
+                if not query:
+                    return [
+                        ChartSpec(chart_type=ChartType.PACE, title="Pace Chart"),
+                        ChartSpec(chart_type=ChartType.HEART_RATE, title="Heart Rate Chart"),
+                    ]
+                return []

src/application/dto/runner_api_response.py

@@ -0,0 +1,25 @@
+from dataclasses import dataclass
+from typing import Any, Dict, Optional
+
+
+@dataclass
+class RunnerAPIResponse:
+    num_runs: int
+    weeks: int
+    features: list
+    insights: Any
+    plan: Optional[str]
+    risk_assessment: Optional[Dict]
+    trends: Any
+    period_comparison: Any
+    charts: Any
+    profile: Optional[Dict]
+    goal_progress: Optional[Dict]
+    goal_trajectory: Optional[Any]
+    positioning: Optional[Dict]
+    recommendation: Optional[Dict]
+    active_goal: Optional[Dict]
+
+    # ✅ New product surface
+    intelligence_snapshot: Optional[Dict]
+    mode: str = "RunnerOrchestrator"

src/application/goal_trajectory_service.py

@@ -0,0 +1,10 @@
+from domain.goals.goal_trajectory_engine import GoalTrajectoryEngine
+
+
+class GoalTrajectoryService:
+
+    def __init__(self):
+        self.engine = GoalTrajectoryEngine()
+
+    def compute(self, goal, snapshot, trend, runner_profile=None):
+        return self.engine.compute(goal, snapshot, trend, runner_profile)

src/application/positioning_service.py

@@ -0,0 +1,187 @@
+from typing import Optional, Dict, List, Literal
+from pydantic import BaseModel, Field
+from datetime import date
+from domain.training.weekly_snapshot import WeeklySnapshot
+from domain.training.weekly_trend import WeeklyTrend
+from domain.runner_positioning import TrainingPhase
+from _app.presentation.ui_text import get_text
+
+class WeeklyPositioning(BaseModel):
+    """
+    Application-layer model for Positioning Intelligence v1.
+    Narrative-focused assessment of the runner's current standing.
+    """
+    status: Literal["CONSTRUCTIVE_ADAPTATION", "PRODUCTIVE_LOAD", "STRAIN", "PLATEAU", "BASELINE_BUILDING"]
+    signal_strength: float = 1.0 # 0.0 to 1.0
+    rationale: str
+    training_phase: TrainingPhase = TrainingPhase.BASE
+    
+    @property
+    def status_value(self) -> str:
+        return self.status
+
+class PositioningEngine:
+    """
+    Engine to compute high-level positioning status from snapshots and trends.
+    """
+    def detect_training_phase(self, snapshot: WeeklySnapshot, trend: WeeklyTrend) -> TrainingPhase:
+        """
+        Infer training phase from workload and trend signals.
+        """
+        distance_delta = trend.distance_delta_pct or 0
+        pace_delta = trend.pace_delta_s_per_km or 0
+        run_count = snapshot.run_count
+        # consistency = snapshot.consistency_score or 0
+
+        # Recovery phase (very low activity and sharp drop in load)
+        if run_count <= 1 and distance_delta < -80:
+            return TrainingPhase.RECOVERY
+
+        # Plateau phase (load dropped or adaptation stalled)
+        if distance_delta < -20:
+            return TrainingPhase.PLATEAU
+
+        # Build phase (clear volume increase)
+        if distance_delta > 5:
+            return TrainingPhase.BUILD
+
+        # Peak phase (performance improving without load reduction)
+        if pace_delta < -5 and distance_delta >= 0:
+            return TrainingPhase.PEAK
+
+        # Default: base training
+        return TrainingPhase.BASE
+
+    def compute(self, snapshot: WeeklySnapshot, trend: WeeklyTrend) -> WeeklyPositioning:
+        if not trend or not trend.comparison_available:
+            return WeeklyPositioning(
+                status="BASELINE_BUILDING",
+                rationale="positioning_rationale_building",
+                signal_strength=0.1,
+                training_phase=TrainingPhase.BASE
+            )
+
+        # 1. Logic to determine status
+        # This is a v1 heuristic mapping
+        status = "PLATEAU"
+        rationale_key = "positioning_rationale_plateau"
+        
+        if trend.comparison_available:
+            # Constructive Adaptation: Increasing load with positive/stable consistency
+            if trend.distance_delta_pct > 5.0 and trend.consistency_delta >= -5.0:
+                 status = "CONSTRUCTIVE_ADAPTATION"
+                 rationale_key = "positioning_rationale_constructive_adaptation"
+            # Strain: High load increase or high HR increase
+            elif trend.distance_delta_pct > 20.0 or (trend.hr_delta and trend.hr_delta > 5.0):
+                status = "STRAIN"
+                rationale_key = "positioning_rationale_strain"
+            # Productive Load: Stable or slightly increasing load
+            elif trend.distance_delta_pct >= -5.0:
+                status = "PRODUCTIVE_LOAD"
+                rationale_key = "positioning_rationale_productive_load"
+            else:
+                status = "BASELINE_BUILDING"
+                rationale_key = "positioning_rationale_building"
+        
+        training_phase = self.detect_training_phase(snapshot, trend)
+
+        return WeeklyPositioning(
+            status=status,
+            rationale=rationale_key, # Store key here
+            signal_strength=1.0 if trend.comparison_available else 0.5,
+            training_phase=training_phase
+        )
+
+def build_positioning_view(
+    snapshot: WeeklySnapshot,
+    trend: WeeklyTrend,
+    positioning: WeeklyPositioning,
+    goal_progress: Optional[dict] = None,
+    language: str = "en"
+    ) -> dict:
+    """
+    Builds a UI-ready positioning view using BOTH absolute state (snapshot)
+    and relative changes (trend). This restores coaching-quality output.
+    """
+
+    positioning = PositioningEngine().compute(snapshot, trend)
+
+    # --- Absolute context (snapshot) ---
+    total_distance = snapshot.total_distance_km or 0
+    run_count = snapshot.run_count or 0
+    avg_pace = snapshot.avg_pace_sec_per_km
+    avg_hr = snapshot.avg_hr
+
+    # --- Relative context (trend) ---
+    distance_delta = trend.distance_delta_pct or 0
+    pace_delta = trend.pace_delta_s_per_km or 0
+    hr_delta = trend.hr_delta or 0
+    freq_delta = int(trend.frequency_delta or 0)
+    consistency_delta = trend.consistency_delta or 0
+
+    # --- Headline (context-aware) ---
+    if run_count <= 1:
+        headline = get_text("positioning_headline_building", language)
+    elif total_distance < 5:
+        headline = f"Your training volume is currently low at {total_distance:.1f} km."
+    else:
+        status_lower = positioning.status.lower()
+        headline = get_text(f"positioning_headline_{status_lower}", language)
+
+    # --- State ---
+    status_icons = {
+        "CONSTRUCTIVE_ADAPTATION": "🟢",
+        "PRODUCTIVE_LOAD": "🟡",
+        "STRAIN": "🔴",
+        "PLATEAU": "⚪",
+        "BASELINE_BUILDING": "⚪",
+    }
+    status_icon = status_icons.get(positioning.status, "⚪")
+    status_name = get_text(f"positioning_status_{positioning.status.lower()}", language)
+
+    # --- Health ---
+    if hr_delta > 5:
+        health_signal = f"🔴 {get_text('health_strain', language)}"
+    else:
+        health_signal = f"🟢 {get_text('health_stable', language)}"
+
+    # --- Goal trajectory ---
+    if goal_progress:
+        if positioning.status == "BASELINE_BUILDING":
+            goal_trajectory = get_text("trajectory_establishing", language)
+        elif positioning.status == "CONSTRUCTIVE_ADAPTATION":
+            goal_trajectory = f"🎯 {get_text('trajectory_improving', language)}"
+        else:
+            goal_trajectory = f"🎯 {get_text('trajectory_maintaining', language)}"
+    else:
+        goal_trajectory = get_text("trajectory_no_goal", language)
+
+    # --- Forward focus ---
+    forward_focus = get_text(f"positioning_forward_focus_{positioning.status.lower()}", language)
+
+    # --- Narrative insight ---
+    insight = get_text(positioning.rationale, language)
+
+    # --- Evidence (enriched with absolute + relative) ---
+    evidence = {
+        "distance": f"{total_distance:.1f} km ({distance_delta:+.1f}%)",
+        "pace": f"{pace_delta:+.1f} sec/km" if pace_delta else None,
+        "hr": f"{hr_delta:+.1f} bpm" if hr_delta else None,
+        "frequency": f"{run_count} runs ({freq_delta:+d})",
+        "consistency": f"{int(consistency_delta):+d}",
+    }
+
+    # Remove empty evidence fields
+    evidence = {k: v for k, v in evidence.items() if v is not None}
+
+    return {
+        "headline": headline,
+        "state": f"{status_icon} {status_name}",
+        "health_signal": health_signal,
+        "goal_trajectory": goal_trajectory,
+        "training_phase": positioning.training_phase.value if hasattr(positioning.training_phase, "value") else positioning.training_phase,
+        "forward_focus": forward_focus,
+        "trajectory": get_text(f"positioning_trajectory_{positioning.status.lower()}", language),
+        "insight": insight,
+        "evidence": evidence if positioning.status != "BASELINE_BUILDING" else None,
+    }

src/application/recommendation_service.py

@@ -0,0 +1,82 @@
+from typing import Optional, Any
+from domain.training.weekly_snapshot import WeeklySnapshot
+from domain.training.weekly_trend import WeeklyTrend
+from domain.runner_positioning import RunnerPositioning, TrainingPhase
+from domain.training.training_recommendation import TrainingRecommendation
+from _app.presentation.ui_text import get_text
+
+class RecommendationService:
+    """
+    Stateless service to generate training recommendations based on positioning.
+    """
+
+    def generate(
+        self,
+        snapshot: WeeklySnapshot,
+        trend: WeeklyTrend,
+        positioning: Any, # Can be RunnerPositioning or WeeklyPositioning
+        language: str = "en"
+    ) -> TrainingRecommendation:
+        """
+        Pure rule-based logic to map positioning to training focus and session types.
+        """
+        # Mapping from positioning focus or status
+        # Handle both Domain (RunnerPositioning) and Application (WeeklyPositioning) models
+        if hasattr(positioning, "recommended_focus"):
+            focus_val = positioning.recommended_focus
+        else:
+            # Fallback for WeeklyPositioning (Application Layer)
+            status_map = {
+                "CONSTRUCTIVE_ADAPTATION": "INTENSITY",
+                "PRODUCTIVE_LOAD": "CONSISTENCY",
+                "STRAIN": "RECOVERY",
+                "PLATEAU": "MAINTENANCE"
+            }
+            focus_val = status_map.get(getattr(positioning, "status", ""), "MAINTENANCE")
+
+        focus_key = focus_val.lower()
+        
+        # Initial recommendation mapping as per requirements:
+        # Building Momentum (CONSTRUCTIVE_ADAPTATION) -> introduce_intensity / tempo_intervals
+        # Maintaining Consistency (PRODUCTIVE_LOAD) -> build_endurance / long_run
+        # Recovery (STRAIN) -> protect_recovery / easy_run
+        # Default -> maintain_consistency
+        
+        mapping = {
+            "RECOVERY": {
+                "focus": "protect_recovery",
+                "session_type": "easy_run",
+                "confidence": 0.9
+            },
+            "CONSISTENCY": {
+                "focus": "build_endurance",
+                "session_type": "long_run",
+                "confidence": 0.8
+            },
+            "INTENSITY": {
+                "focus": "introduce_intensity",
+                "session_type": "tempo_intervals",
+                "confidence": 0.85
+            },
+            "MAINTENANCE": {
+                "focus": "maintain_consistency",
+                "session_type": "steady_run",
+                "confidence": 0.75
+            }
+        }
+        
+        rec_data = mapping.get(focus_val, {
+            "focus": "maintain_consistency",
+            "session_type": "steady_run",
+            "confidence": 0.5
+        })
+        
+        # Resolve localized description
+        description = get_text(f"rec_desc_{rec_data['focus']}", language)
+        
+        return TrainingRecommendation(
+            focus=get_text(f"rec_focus_{rec_data['focus']}", language),
+            session_type=get_text(f"rec_session_{rec_data['session_type']}", language),
+            description=description,
+            confidence=rec_data["confidence"]
+        )

src/application/runner_positioning_service.py

@@ -0,0 +1,43 @@
+from typing import Optional, Dict, Any
+from domain.runner_positioning import RunnerPositioning
+from domain.training.weekly_snapshot import WeeklySnapshot
+from domain.training.weekly_trend import WeeklyTrend
+from application.positioning_service import PositioningEngine
+
+class RunnerPositioningService:
+    """
+    Application service for Runner Positioning.
+    Enforces architectural boundaries: no LLM, no persistence, no observability here.
+    """
+
+    def generate(
+        self,
+        snapshot: WeeklySnapshot,
+        trend: WeeklyTrend,
+        goal_progress: Optional[Dict[str, Any]] = None
+    ) -> RunnerPositioning:
+        """
+        Aggregates domain data into a RunnerPositioning assessment.
+        """
+        # Extract necessary values for deterministic logic
+        target_distance = None
+        if goal_progress:
+            # goal_service.compute_goal_progress returns a dict
+            # We assume it has a 'target_value' if applicable
+            target_distance = goal_progress.get("target_value")
+
+        # Call domain logic
+        engine = PositioningEngine()
+        training_phase = engine.detect_training_phase(snapshot, trend)
+
+        return RunnerPositioning.compute(
+            week_start=snapshot.week_start_date,
+            total_distance=snapshot.total_distance_km,
+            target_distance=target_distance,
+            consistency_score=snapshot.consistency_score,
+            pace_delta=trend.pace_delta_s_per_km,
+            hr_delta=trend.hr_delta,
+            distance_delta_pct=trend.distance_delta_pct,
+            comparison_available=trend.comparison_available,
+            training_phase=training_phase
+        )

src/config.py

@@ -0,0 +1,109 @@
+import os
+import uuid
+
+# Application Constants
+APP_NAME = "agents"
+USER_ID = "default_user"
+DEFAULT_RUNNER_ID = "00000000-0000-0000-0000-000000000000"
+
+# Environment Flags
+HF_SPACE = os.getenv("HF_SPACE", "false").lower() == "true"
+
+
+def is_hf_space() -> bool:
+    """Helper to check if running in HuggingFace Spaces."""
+    return HF_SPACE
+
+
+# Ingestion Limits
+_DEFAULT_MAX_FILES = "12" if is_hf_space() else "100"
+_DEFAULT_MAX_FILE_SIZE = "10" if is_hf_space() else "50"
+_DEFAULT_MAX_TOTAL_SIZE = "20" if is_hf_space() else "250"
+
+def _safe_int(value: str, default: int) -> int:
+    """Safely convert string to int, stripping common corrupted characters like '§'."""
+    if not value:
+        return default
+    try:
+        # Strip common non-numeric suffixes that might appear due to env corruption
+        clean_val = ""
+        for char in str(value):
+            if char.isdigit():
+                clean_val += char
+            else:
+                break
+        return int(clean_val) if clean_val else default
+    except (ValueError, TypeError):
+        return default
+
+
+MAX_UPLOAD_FILES = _safe_int(os.getenv("MAX_UPLOAD_FILES"), int(_DEFAULT_MAX_FILES))
+MAX_UPLOAD_FILE_SIZE_MB = _safe_int(os.getenv("MAX_UPLOAD_FILE_SIZE_MB"), int(_DEFAULT_MAX_FILE_SIZE))
+MAX_UPLOAD_TOTAL_SIZE_MB = _safe_int(os.getenv("MAX_UPLOAD_TOTAL_SIZE_MB"), int(_DEFAULT_MAX_TOTAL_SIZE))
+MAX_GZIP_DECOMPRESSED_SIZE_MB = _safe_int(os.getenv("MAX_GZIP_DECOMPRESSED_SIZE_MB"), 200)
+ALLOWED_UPLOAD_EXTENSIONS = os.getenv(
+    "ALLOWED_UPLOAD_EXTENSIONS", ".gpx,.tcx.gz,.tcx,.fit,.fit.gz"
+).split(",")
+
+# Storage Configuration
+_DEFAULT_STORAGE_ENABLED = "false" if is_hf_space() else "true"
+STORAGE_ENABLED = os.getenv("STORAGE_ENABLED", _DEFAULT_STORAGE_ENABLED).lower() == "true"
+STORAGE_DB_PATH = os.getenv("STORAGE_DB_PATH", ".data/runner_agentic_intelligence.db")
+
+
+def is_storage_enabled() -> bool:
+    """Helper to check if persistence is enabled."""
+    return STORAGE_ENABLED
+
+
+def is_persistence_enabled() -> bool:
+    """
+    Returns True only when storage is enabled AND not running in HF public preview.
+    """
+    return is_storage_enabled() and not is_hf_space()
+
+
+def generate_session_id() -> str:
+    """Generate a unique session ID."""
+    return str(uuid.uuid4())
+
+
+# LLM Configuration
+LLM_PROVIDER = os.getenv("LLM_PROVIDER", "gemini")  # "gemini", "mock", "litellm"
+LLM_MODEL_ID = os.getenv("LLM_MODEL", "")
+LLM_API_BASE = os.getenv("LLM_API_BASE", None)
+LLM_TEMPERATURE = float(os.getenv("LLM_TEMPERATURE", "1.0"))
+LLM_MAX_TOKENS = int(os.getenv("LLM_MAX_TOKENS", "8192"))
+LLM_DROP_PARAMS = True
+LLM_SCHEMA_GUARD_STRICT = os.getenv("LLM_SCHEMA_GUARD_STRICT", "false").lower() == "true"
+AI_INSIGHTS_ENABLED = os.getenv("AI_INSIGHTS_ENABLED", "true").lower() == "true"
+
+# LiteLLM / OpenAI compatible settings
+# All specific providers are now handled by the LiteLLM client layer.
+if LLM_PROVIDER.lower() == "litellm":
+    # Ensure we use LLM_MODEL env var if provided first
+    ENV_MODEL = os.getenv("LLM_MODEL")
+    if ENV_MODEL:
+        LLM_MODEL_ID = ENV_MODEL
+
+    if not LLM_MODEL_ID:
+        # Default model if not provided
+        LLM_MODEL_ID = "openai/gpt-4o-mini"
+
+    # Simple heuristic to distinguish between OpenAI proper and others (like HF Router)
+    is_real_openai = LLM_MODEL_ID.startswith("openai/") and "gpt-oss" not in LLM_MODEL_ID
+
+    if is_real_openai:
+        if "gpt-5" in LLM_MODEL_ID:
+            LLM_TEMPERATURE = 1.0
+    else:
+        # Default to HuggingFace Router for other LiteLLM models unless api_base is set
+        if not LLM_API_BASE:
+            LLM_API_BASE = "https://router.huggingface.co/v1"
+else:
+    # Default fallback for Gemini or other non-explicit LiteLLM provider
+    LLM_MODEL_ID = os.getenv("LLM_MODEL") or os.getenv("GEMINI_MODEL", "gemini-3-flash-preview")
+
+# Deprecated: do not use global LLM_API_KEY for multi-provider setup.
+# LLM clients now resolve their own credentials from environment variables.
+LLM_API_KEY = os.getenv("LLM_API_KEY")

src/core/intelligence/intelligence_builder.py

@@ -0,0 +1,308 @@
+import math
+from typing import Dict, Optional, Any
+from .runner_intelligence_snapshot import RunnerIntelligenceSnapshot
+from _app.presentation.ui_text import UI_TEXT
+from tools.helpers import decode_chart
+
+def _format_pace(seconds_per_km: float) -> str:
+    if not seconds_per_km or seconds_per_km <= 0:
+        return "N/A"
+    minutes = int(seconds_per_km // 60)
+    seconds = int(seconds_per_km % 60)
+    return f"{minutes}:{seconds:02d} /km"
+
+def _build_performance_story(snapshot: RunnerIntelligenceSnapshot, trend_dict: Dict, language: str) -> str:
+    t = UI_TEXT.get(language, UI_TEXT["en"])
+    runs_word = t.get("unit_runs")
+    dist_word = t.get("lbl_total_of")
+    
+    story_tpl = t.get("home_story_template", "")
+    story = story_tpl.format(count=snapshot.run_count, unit=runs_word, of=dist_word, dist=snapshot.weekly_distance_km)
+    
+    comparison = trend_dict.get("comparison_available", False) if trend_dict else False
+    if comparison:
+        dist_delta = trend_dict.get("distance_delta_pct", 0)
+        pace_delta = trend_dict.get("pace_delta_s_per_km", 0)
+        
+        dist_trend = t.get("lbl_more" if dist_delta > 0 else "lbl_less", "more" if dist_delta > 0 else "less")
+        pace_trend = t.get("lbl_faster" if pace_delta < 0 else "lbl_slower", "faster" if pace_delta < 0 else "slower")
+        
+        that_is = t.get("lbl_that_is")
+        than_avg = t.get("lbl_than_avg")
+        pace_was = t.get("lbl_pace_was")
+
+        if abs(dist_delta) > 5:
+            story += f" {that_is} **{abs(dist_delta):.1f}% {dist_trend}** {than_avg}"
+        
+        if abs(pace_delta) > 2:
+            formatted_delta = _format_pace(abs(pace_delta)).replace(" /km", "")
+            story += f" {pace_was} **{formatted_delta} {pace_trend}**."
+
+    return story
+
+def _build_delta_summary(trend_dict: Dict, language: str) -> Dict[str, str]:
+    if not trend_dict or not trend_dict.get("comparison_available"):
+        return {}
+        
+    t = UI_TEXT.get(language, UI_TEXT["en"])
+    
+    def format_val(metric_name, delta_val):
+        if delta_val is None:
+            return t.get("na", "N/A")
+            
+        is_positive_good = metric_name in ["distance", "frequency", "consistency"]
+        icon = "⚪"
+        if delta_val > 0:
+            icon = "🟢" if is_positive_good else "🔴"
+        elif delta_val < 0:
+            icon = "🔴" if is_positive_good else "🟢"
+            
+        formatted = f"{delta_val:+.1f}"
+        if metric_name == "distance":
+            formatted = f"{delta_val:+.1f}%"
+        elif metric_name == "pace":
+            unit = t.get("unit_spkm", "s/km")
+            formatted = f"{delta_val:+.1f} {unit}"
+        elif metric_name == "frequency":
+            unit = t.get("unit_runs", "runs")
+            formatted = f"{int(delta_val):+d} {unit}"
+        elif metric_name == "hr":
+            unit = t.get("unit_bpm", "bpm")
+            formatted = f"{delta_val:+.1f} {unit}"
+        elif metric_name == "consistency":
+            unit = t.get("unit_pts", "pts")
+            formatted = f"{int(delta_val):+d} {unit}"
+            
+        return f"{icon} {formatted}"
+
+    return {
+        "distance": format_val("distance", trend_dict.get("distance_delta_pct")),
+        "pace": format_val("pace", trend_dict.get("pace_delta_s_per_km")),
+        "frequency": format_val("frequency", trend_dict.get("frequency_delta")),
+        "hr": format_val("hr", trend_dict.get("hr_delta")),
+        "consistency": format_val("consistency", trend_dict.get("consistency_delta"))
+    }
+
+def _build_evidence_view(positioning_view: Dict, trend: Dict, language: str) -> str:
+    t = UI_TEXT.get(language, UI_TEXT["en"])
+    evidence = positioning_view.get("evidence", "")
+    if evidence and isinstance(evidence, dict):
+        pace_delta = trend.get('pace_trend_s_per_km') if trend else 0
+        if pace_delta is None: pace_delta = 0
+        pace_word = t.get('positioning_evidence_pace_improved', 'Improved') if pace_delta <= 0 else t.get('positioning_evidence_pace_worsened', 'Worsened')
+                
+        return f"""
+📈 {t.get('positioning_evidence_distance', 'Dist')}: {evidence.get('distance', 0)} <br>
+⚡ {pace_word}: {evidence.get("pace")} <br>
+🫀 {t.get('positioning_evidence_hr', 'HR')}: {evidence.get('hr', 0)} <br>
+🏃 {t.get('lbl_runs_count', 'Runs')}: {evidence.get("frequency")} <br>
+🎯 {t.get('positioning_evidence_consistency', 'Consistency')}: {evidence.get('consistency', 0)}
+""".strip()
+    else:
+        return f"{positioning_view.get('trajectory', '')}\n".strip()
+
+def _build_structure_view(structure_status: Dict, recommendation: Dict, language: str) -> str:
+    if not structure_status:
+        return ""
+    
+    t = UI_TEXT.get(language, UI_TEXT["en"])
+    wd_comp = structure_status.get("weekday_completed", 0)
+    wd_total = structure_status.get("weekday_total", 0)
+    lr_comp = "✅" if structure_status.get("long_run_completed") else "⏳"
+    classif = structure_status.get("classification", "reset_week")
+    classif_lbl = t.get(classif, classif)
+    km_rem = structure_status.get("km_remaining", 0.0)
+
+    km_rem_subtext = ""
+    if km_rem > 0:
+        subtext_tpl = t.get("lbl_km_remaining_subtext", "{val} km")
+        km_rem_subtext = f'<span class="subtext">{subtext_tpl.format(val=f"{km_rem:.1f}")}</span>'
+
+    advice = recommendation.get('description', "") if recommendation else t.get("coaching_advice", "")
+    advice_html = f'<div class="coaching-tip">{advice}</div>' if advice else ""
+
+    return f"""
+<div class="metric-row"><span class="metric-label">{t.get('lbl_weekday_runs', 'Weekday')}:</span> <span class="metric-value">{wd_comp} / {wd_total}</span></div>
+<div class="metric-row"><span class="metric-label">{t.get('lbl_long_run', 'Long Run')}:</span> <span class="metric-value">{lr_comp}</span></div>
+<div class="metric-row"><span class="metric-label">{t.get('lbl_structure_status', 'Status')}:</span> <span class="metric-value">{classif_lbl}</span></div>
+<div class="metric-row"><span class="metric-label">{t.get('lbl_km_remaining', 'Remaining') + ': ' if km_rem > 0 else ''}</span> {km_rem_subtext}</div>
+{advice_html}
+""".strip()
+
+def _build_goal_status_text(active_goal: Dict, language: str) -> str:
+    if not active_goal:
+        return ""
+        
+    t = UI_TEXT.get(language, UI_TEXT["en"])
+    status_key = active_goal.get("status", "unknown")
+    status_lbl = t.get(f"goal_status_{status_key}", status_key)
+    tpl = t.get("goal_status_template", "Goal status: {val}")
+    return tpl.format(val=status_lbl)
+
+def build_intelligence_snapshot(context) -> RunnerIntelligenceSnapshot:
+    """
+    Builds a RunnerIntelligenceSnapshot from a PipelineContext.
+    
+    This is an aggregation layer only. It uses safe accessors (`getattr`) 
+    to extract already-computed values without introducing new business logic.
+    """
+    summary = context.summary
+    
+    # Helper to safely extract depending on whether summary is a dict, WeeklySnapshot, or WeeklySummary
+    def _extract_summary_val(dict_key, attr_names, default, transform=None):
+        if not summary:
+            return default
+        
+        val = default
+        if isinstance(summary, dict):
+            val = summary.get(dict_key, default)
+        else:
+            for attr in attr_names:
+                if hasattr(summary, attr):
+                    val = getattr(summary, attr, default)
+                    break
+                    
+        return transform(val) if transform and val != default else val
+
+    # --- Extract signals from domain objects (projection layer) ---
+    recommendation_obj = context.recommendation
+    insights_obj = context.insights or {}
+
+    training_state = None
+    health_signal = None
+    positioning_status = None
+    positioning_change = None
+
+    next_run = None
+    training_focus = None
+    training_type = None
+    training_why = None
+
+    performance_brief = None
+    performance_focus = None
+    
+    if recommendation_obj:
+        training_focus = getattr(recommendation_obj, "focus", None)
+        training_type = getattr(recommendation_obj, "session_type", None)
+        training_why = getattr(recommendation_obj, "description", None)
+    
+    if not next_run: next_run = getattr(context, "next_run", None)
+    if not training_focus: training_focus = getattr(context, "training_focus", None)
+
+    key_insight = None
+    forward_focus = None
+    goal_trajectory = None
+    goal_progress_pct = None
+    positioning_view = None
+    active_goal = None
+    goal_view = None
+
+    if getattr(context, "positioning_view", None):
+        positioning_view = context.positioning_view
+        training_state = positioning_view.get("training_phase", None)
+        health_signal = positioning_view.get("health_signal", None)
+        positioning_status = positioning_view.get("state", None)
+        positioning_change = positioning_view.get("change", None)
+        forward_focus = positioning_view.get("forward_focus", None)
+        key_insight = positioning_view.get("insight", None)
+        goal_trajectory = positioning_view.get("goal_trajectory", None)
+        goal_progress_pct = positioning_view.get("goal_progress_pct", None)
+
+    if hasattr(context, "weekly_snapshot"):
+        weekly_snapshot = context.weekly_snapshot
+        performance_brief = getattr(weekly_snapshot, "performance_brief", None)
+        performance_focus = getattr(weekly_snapshot, "performance_focus", None)
+    else:
+        performance_brief = getattr(context, "weekly_brief", None)
+        performance_focus = getattr(context, "weekly_focus", None)
+
+    # Fallbacks for scalar signals directly on context (useful for tests/minimal contexts)
+    # This aligns with the "aggregation layer" philosophy of the builder.
+    if not key_insight: key_insight = getattr(context, "key_insight", None)
+    if not forward_focus: forward_focus = getattr(context, "forward_focus", None)
+    if not training_state: training_state = getattr(context, "training_state", None)
+    if not health_signal: health_signal = getattr(context, "health_signal", None)
+    if not positioning_status: positioning_status = getattr(context, "positioning_status", None)
+    if not positioning_change: positioning_change = getattr(context, "positioning_change", None)
+    
+    pos_view_safe = getattr(context, "positioning_view", None) or {}
+    if not goal_trajectory: 
+        goal_trajectory = pos_view_safe.get("goal_trajectory") if isinstance(pos_view_safe, dict) else getattr(pos_view_safe, "goal_trajectory", None)
+    if not goal_trajectory: 
+        goal_trajectory = getattr(context, "goal_trajectory", "NO_GOAL")
+    
+    goal_prog_safe = getattr(context, "goal_progress", None) or {}
+    if goal_progress_pct is None:
+        goal_progress_pct = getattr(context, "goal_progress_pct", None)
+    if goal_progress_pct is None: 
+        goal_progress_pct = goal_prog_safe.get("progress_percentage", 0) if isinstance(goal_prog_safe, dict) else getattr(goal_prog_safe, "progress_percentage", 0)
+
+
+    week_charts = getattr(context, "charts", {}) or getattr(context.weekly_snapshot, "charts", {})
+    
+    snapshot = RunnerIntelligenceSnapshot(
+        id=getattr(context.weekly_snapshot, "id", None),
+        week_start=_extract_summary_val("week_start", ["week_start_date", "week_start"], None),
+
+        training_state=training_state,
+        health_signal=health_signal,
+
+        positioning_status=positioning_status,
+        positioning_change=positioning_change,
+
+        goal_trajectory=goal_trajectory,
+        goal_progress_pct=goal_progress_pct,
+
+        next_run=next_run,
+        training_focus=training_focus,
+        training_type=training_type,
+        training_why=training_why,
+
+        key_insight=key_insight,
+        forward_focus=forward_focus,
+
+        performance_brief=performance_brief,
+        performance_focus=performance_focus,
+
+        weekly_distance_km=_extract_summary_val(
+            "total_distance_m", 
+            ["total_distance_km", "total_distance_m"], 
+            0.0,
+            transform=lambda x: x / 1000.0 if not hasattr(summary, "total_distance_km") else x
+        ),
+        num_runs=_extract_summary_val("num_runs", ["run_count", "num_runs"], 0),
+        run_count=_extract_summary_val("num_runs", ["run_count", "num_runs"], 0),
+        consistency_score=_extract_summary_val("consistency_score", ["consistency_score"], 0),
+        avg_pace=_extract_summary_val("avg_pace_s_per_km", ["avg_pace_sec_per_km", "avg_pace_s_per_km"], 0.0),
+        avg_hr=_extract_summary_val("avg_hr_bpm", ["avg_hr", "avg_hr_bpm"], 0.0),
+        structure_status=getattr(context.weekly_snapshot, "structure_status", {}) if context.weekly_snapshot else {},
+       
+        # Detailed DTO components for UI transparency
+        # Week specific trend
+        trend=context.trends.model_dump() if getattr(context, "trends", None) and hasattr(context.trends, "model_dump") else (context.trends if getattr(context, "trends", None) else {}),
+        # Week over Weeks trend
+        weekly_trend=context.weekly_trend.model_dump() if getattr(context, "weekly_trend", None) and hasattr(context.weekly_trend, "model_dump") else (context.weekly_trend if getattr(context, "weekly_trend", None) else {}),
+        positioning=context.positioning.model_dump() if getattr(context, "positioning", None) and hasattr(context.positioning, "model_dump") else (context.positioning if getattr(context, "positioning", None) else {}),
+        positioning_view=context.positioning_view.model_dump() if getattr(context, "positioning_view", None) and hasattr(context.positioning_view, "model_dump") else (context.positioning_view if getattr(context, "positioning_view", None) else {}),
+        goal_trajectory_data=context.goal_trajectory.model_dump() if getattr(context, "goal_trajectory", None) and hasattr(context.goal_trajectory, "model_dump") else (context.goal_trajectory if getattr(context, "goal_trajectory", None) else {}),
+        insights=context.insights.model_dump() if getattr(context, "insights", None) and hasattr(context.insights, "model_dump") else (context.insights if getattr(context, "insights", None) else {}),
+        plan=getattr(context, "plan", None),
+        recommendation=context.recommendation.model_dump() if getattr(context, "recommendation", None) and hasattr(context.recommendation, "model_dump") else (context.recommendation if getattr(context, "recommendation", None) else {}),
+        charts=decode_chart(week_charts),
+        weekly_brief=performance_brief,
+        weekly_focus=performance_focus,
+        weekly_snapshot = context.weekly_snapshot if getattr(context, "weekly_snapshot", None) and hasattr(context.weekly_snapshot, "model_dump") else (context.weekly_snapshot if getattr(context, "weekly_snapshot", None) else {}),
+        active_goal = context.active_goal.model_dump() if getattr(context, "active_goal", None) and hasattr(context.active_goal, "model_dump") else (context.active_goal if getattr(context, "active_goal", None) else {}),
+        goal_view=context.goal_progress.model_dump() if getattr(context, "goal_progress", None) and hasattr(context.goal_progress, "model_dump") else (context.goal_progress if getattr(context, "goal_progress", None) else {}),
+    )
+
+    language = getattr(context, "language", "en")
+    
+    snapshot.performance_story = _build_performance_story(snapshot, snapshot.weekly_trend, language)
+    snapshot.delta_summary = _build_delta_summary(snapshot.weekly_trend, language)
+    snapshot.evidence_view = _build_evidence_view(snapshot.positioning_view, snapshot.trend, language)
+    snapshot.structure_view = _build_structure_view(snapshot.structure_status, snapshot.recommendation, language)
+    snapshot.goal_status_text = _build_goal_status_text(snapshot.active_goal, language)
+
+    return snapshot
+

src/core/intelligence/intelligence_serializer.py

@@ -0,0 +1,49 @@
+from tools.helpers import serialize_charts
+
+def serialize_snapshot(snapshot):
+    if not snapshot:
+        return None
+        
+    def _safe_dump(obj):
+        if obj is None: return None
+        if isinstance(obj, dict): return obj
+        if hasattr(obj, "model_dump"): return obj.model_dump()
+        return str(obj)
+
+    return {
+        "id": str(snapshot.id) if snapshot.id else None,
+        "week_start": str(snapshot.week_start) if snapshot.week_start else None,
+        "training_state": snapshot.training_state,
+        "health_signal": snapshot.health_signal,
+        "positioning_status": snapshot.positioning_status,
+        "positioning_change": snapshot.positioning_change,
+        "goal_trajectory": snapshot.goal_trajectory,
+        "goal_progress_pct": snapshot.goal_progress_pct,
+        "next_run": snapshot.next_run,
+        "training_focus": snapshot.training_focus,
+        "training_why": snapshot.training_why,
+        "key_insight": snapshot.key_insight,
+        "forward_focus": snapshot.forward_focus,
+        "weekly_distance_km": snapshot.weekly_distance_km,
+        "num_runs": snapshot.num_runs,
+        "run_count": snapshot.run_count,
+        "consistency_score": snapshot.consistency_score,
+        "avg_pace": snapshot.avg_pace,
+        "avg_hr": snapshot.avg_hr,
+        "structure_status": _safe_dump(snapshot.structure_status),
+        "performance_brief": snapshot.performance_brief,
+        "performance_focus": snapshot.performance_focus,
+        "trend": _safe_dump(snapshot.trend),
+        "weekly_trend": _safe_dump(snapshot.weekly_trend),
+        "positioning": _safe_dump(snapshot.positioning),
+        "positioning_view": _safe_dump(snapshot.positioning_view),
+        "goal_trajectory_data": _safe_dump(snapshot.goal_trajectory_data),
+        "insights": _safe_dump(snapshot.insights),
+        "plan": snapshot.plan,
+        "recommendation": _safe_dump(snapshot.recommendation),
+        "charts": serialize_charts(snapshot.charts),
+        "weekly_brief": snapshot.weekly_brief,
+        "weekly_focus": snapshot.weekly_focus,
+        "active_goal": _safe_dump(snapshot.active_goal),
+        "goal_view": _safe_dump(snapshot.goal_view),
+    }

src/core/intelligence/runner_intelligence_snapshot.py

@@ -0,0 +1,82 @@
+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)

src/core/pipeline/context.py

@@ -0,0 +1,76 @@
+from dataclasses import dataclass, field
+from typing import List, Dict, Any, Optional
+
+from domain.training.run import Run
+from domain.training.weekly_snapshot import WeeklySnapshot
+from domain.training.weekly_trend import WeeklyTrend
+from domain.runner.profile import RunnerProfile
+from domain.training.training_recommendation import TrainingRecommendation
+from domain.goals.goal_trajectory import GoalTrajectory
+from ..intelligence.runner_intelligence_snapshot import RunnerIntelligenceSnapshot
+
+from domain.runner_positioning import RunnerPositioning
+from application.positioning_service import WeeklyPositioning
+
+
+@dataclass
+class PipelineContext:
+    """
+    Explicit, typed data contract for the Runner pipeline.
+    Eliminates dynamic field attachments and implicit state.
+    """
+
+    # Inputs
+    runs: List[Any] = field(default_factory=list)
+    week_runs: List[Any] = field(default_factory=list)
+    language: str = "en"
+    target_monday: Optional[Any] = None # date
+    runner_profile: Optional[RunnerProfile] = None
+    active_goal: Optional[Any] = None
+
+    # Session state
+    sessions: Dict[Any, WeeklySnapshot] = field(default_factory=dict)
+
+    # Computed training data
+    weekly_snapshot: Optional[WeeklySnapshot] = None
+    weekly_trend: Optional[WeeklyTrend] = None
+
+    # Positioning layer
+
+    runner_positioning: Optional[RunnerPositioning] = None
+    positioning: Optional[WeeklyPositioning] = None
+    positioning_view: Optional[Any] = None 
+    recommendation: Optional[TrainingRecommendation] = None
+    goal_trajectory: Optional[GoalTrajectory] = None
+
+    # Intelligence outputs
+    insights: Optional[Dict[str, Any]] = None
+    plan: Optional[str] = None
+    summary: Optional[Dict[str, Any]] = None
+    trends: Optional[Any] = None
+    risk_assessment: Optional[Any] = None
+    intelligence_snapshot: Optional[RunnerIntelligenceSnapshot] = None
+
+    # Intelligence Cache (for reuse)
+    last_runner_positioning: Optional[Any] = None
+    last_positioning: Optional[Any] = None
+    last_insights: Dict[str, Any] = field(default_factory=dict)
+    last_plan: Optional[str] = None
+    last_brief: Optional[str] = None
+    last_focus: Optional[str] = None
+
+    # Visualization
+    visualization_scope: str = "weekly" # "full" | "weekly"
+    charts: Dict[str, Any] = field(default_factory=dict)
+
+    # Context control
+    enable_intelligence: bool = True
+    intelligence_cache: Dict[str, bool] = field(default_factory=dict)
+    
+    # Comparison
+    period_comparison: Optional[Any] = None
+
+    # Goal progress
+    goal_progress: Optional[Dict[str, Any]] = None
+    goal_view: Optional[Dict[str, Any]] = None
+    

src/core/pipeline/pipeline.py

@@ -0,0 +1,43 @@
+import asyncio
+
+class RunnerPipeline:
+    def __init__(self, steps):
+        self.steps = steps
+
+    async def execute(self, context):
+        i = 0
+        while i < len(self.steps):
+            step = self.steps[i]
+
+            # Detect parallel block: IntelligenceStep followed by VisualizationStep
+            if (
+                step.__class__.__name__ == "IntelligenceStep"
+                and i + 1 < len(self.steps)
+                and self.steps[i + 1].__class__.__name__ == "VisualizationStep"
+            ):
+                intelligence_step = step
+                visualization_step = self.steps[i + 1]
+
+                # 1. Parallelize InsightsAgent + PlanAgent + VisualizationAgent
+                tasks = []
+                
+                # Extract parallel tasks from intelligence step (Insights + Plan)
+                if hasattr(intelligence_step, "run_parallel_agents"):
+                    tasks.extend(intelligence_step.run_parallel_agents(context))
+                
+                # Add visualization task
+                tasks.append(visualization_step.execute(context))
+
+                # Execute all independent agent tasks in parallel
+                if tasks:
+                    await asyncio.gather(*tasks)
+
+                # 2. Run IntelligenceStep's remaining sequential logic (Brief + Cache)
+                # This will skip the already-completed agents due to checks in IntelligenceStep.run
+                await intelligence_step.execute(context)
+
+                i += 2
+                continue
+
+            await step.execute(context)
+            i += 1

src/core/pipeline/step.py

@@ -0,0 +1,12 @@
+from observability import logger as obs_logger
+from observability import components as obs_components
+
+class PipelineStep:
+    name = "pipeline_step"
+
+    async def execute(self, context):
+        with obs_logger.start_span(self.name, obs_components.ORCHESTRATOR):
+            await self.run(context)
+
+    async def run(self, context):
+        raise NotImplementedError

src/domain/goals/goal_trajectory.py

@@ -0,0 +1,13 @@
+from dataclasses import dataclass
+from datetime import date
+
+
+@dataclass
+class GoalTrajectory:
+    goal_name: str
+    target_date: date
+    status: str              # on_track | ahead | behind | unknown
+    progress_pct: float
+    expected_weekly_km: float
+    current_weekly_km: float
+    next_milestone: str

src/domain/goals/goal_trajectory_engine.py

@@ -0,0 +1,81 @@
+from domain.goals.goal_trajectory import GoalTrajectory
+
+
+class GoalTrajectoryEngine:
+
+    def compute(
+        self, goal, weekly_snapshot, weekly_trend=None, runner_profile=None
+    ):
+
+        if not goal or not weekly_snapshot:
+            return None
+
+        current_km = weekly_snapshot.total_distance_km or 0
+
+        target_val = getattr(goal, "target_value", 0)
+        unit = getattr(goal, "unit", "km")
+        goal_type = getattr(goal, "type", "goal")
+        name = f"{goal_type} {target_val} {unit}"
+        # ---- Weekly Volume Goal ----
+        if getattr(goal, "type", None) == "volume":
+
+            target_km = goal.target_value
+            progress_pct = (current_km / target_km) * 100 if target_km else 0
+
+            if current_km >= target_km * 1.1:
+                status = "ahead"
+            elif current_km >= target_km * 0.9:
+                status = "on_track"
+            else:
+                status = "behind"
+
+            milestone = f"Maintain ≥{target_km:.1f} km/week"
+
+            return GoalTrajectory(
+                goal_name=name,
+                target_date=getattr(goal, "target_date", None),
+                status=status,
+                progress_pct=progress_pct,
+                expected_weekly_km=target_km,
+                current_weekly_km=current_km,
+                next_milestone=milestone
+            )
+
+        # ---- Race Goal ----
+
+        if getattr(goal, "type", None) == "race":
+
+            target_km = goal.target_value
+            baseline = None
+
+            if runner_profile and runner_profile.baseline_weekly_km:
+                baseline = runner_profile.baseline_weekly_km
+            else:
+                baseline = current_km
+
+            expected_weekly_km = max(baseline, target_km * 1.5)
+
+            progress_pct = (
+                (current_km / expected_weekly_km) * 100 if expected_weekly_km else 0
+            )
+
+            if current_km >= expected_weekly_km * 1.1:
+                status = "ahead"
+            elif current_km >= expected_weekly_km * 0.9:
+                status = "on_track"
+            else:
+                status = "behind"
+
+            milestone = f"Reach ~{expected_weekly_km:.1f} km/week"
+
+            return GoalTrajectory(
+                goal_name=name,
+                target_date=getattr(goal, "target_date", None),
+                status=status,
+                progress_pct=progress_pct / 100.0,
+                expected_weekly_km=expected_weekly_km,
+                current_weekly_km=current_km,
+                next_milestone=milestone
+            )
+
+        return None

src/domain/runner/goal.py

@@ -0,0 +1,30 @@
+import uuid
+from dataclasses import dataclass, field
+from datetime import datetime
+from typing import Optional, Literal
+
+
+@dataclass
+class Goal:
+    id: uuid.UUID
+    runner_id: uuid.UUID
+    type: str  # "race", "volume", "pace"
+    target_value: float
+    unit: str  # "km", "min", "sec_per_km"
+    target_date: Optional[datetime] = None
+    status: Literal["active", "completed", "archived"] = "active"
+    created_at: datetime = field(default_factory=datetime.now)
+    achieved_at: Optional[datetime] = None
+
+    def model_dump(self):
+        return {
+            "id": str(self.id),
+            "runner_id": str(self.runner_id),
+            "type": self.type,
+            "target_value": self.target_value,
+            "unit": self.unit,
+            "target_date": self.target_date.isoformat() if self.target_date else None,
+            "status": self.status,
+            "created_at": self.created_at.isoformat(),
+            "achieved_at": self.achieved_at.isoformat() if self.achieved_at else None,
+        }

src/domain/runner/profile.py

@@ -0,0 +1,31 @@
+from typing import Optional, Literal
+from pydantic import BaseModel, Field, field_validator
+from datetime import datetime
+import uuid
+
+
+class RunnerProfile(BaseModel):
+    """Digital Twin model for persistent runner data."""
+
+    runner_id: uuid.UUID
+    runner_display_name: Optional[str] = None
+
+    age: Optional[int] = None
+    sex: Optional[Literal["male", "female", "other"]] = None
+
+    experience_level: Optional[Literal["beginner", "intermediate", "advanced"]] = None
+
+    baseline_weekly_km: Optional[float] = None
+    gender: Optional[str] = Field(default=None)
+
+    injury_history_notes: Optional[str] = None
+
+    created_at: datetime = Field(default_factory=datetime.now)
+    updated_at: datetime = Field(default_factory=datetime.now)
+
+    @field_validator("gender")
+    @classmethod
+    def normalize_gender(cls, v: Optional[str]) -> Optional[str]:
+        if v not in ["male", "female", "other", "prefer_not_to_say"]:
+            return None
+        return v

src/domain/runner_positioning.py

@@ -0,0 +1,101 @@
+from typing import Optional, Literal
+from pydantic import BaseModel
+from datetime import date
+from enum import Enum
+
+class TrainingPhase(str, Enum):
+    BASE = "base"
+    BUILD = "build"
+    PEAK = "peak"
+    RECOVERY = "recovery"
+    PLATEAU = "plateau"
+
+class RunnerPositioning(BaseModel):
+    """
+    Domain model for representing a runner's positioning assessment.
+    This is a deterministic interpretation of snapshots, trends, and goals.
+    """
+    week_start_date: date
+    
+    # Core signals
+    health_signal: Literal["RECOVERING", "OPTIMAL", "OVERREACHING", "UNKNOWN"]
+    position_status: Literal["AHEAD", "ON_TRACK", "FALLING_BEHIND", "UNKNOWN"]
+    goal_trajectory: Literal["IMPROVING", "STABLE", "DECLINING", "UNKNOWN"]
+    recommended_focus: Literal["RECOVERY", "CONSISTENCY", "INTENSITY", "MAINTENANCE"]
+    training_phase: TrainingPhase
+    
+    # Metadata
+    comparison_available: bool = False
+    signal_strength: float = 1.0
+    llm_used: bool = False
+    summary: Optional[str] = None
+
+    @classmethod
+    def compute(
+        cls,
+        week_start: date,
+        total_distance: float,
+        target_distance: Optional[float],
+        consistency_score: float,
+        pace_delta: float,
+        hr_delta: Optional[float],
+        distance_delta_pct: float,
+        comparison_available: bool,
+        training_phase: TrainingPhase = TrainingPhase.BASE
+    ) -> "RunnerPositioning":
+        """
+        Pure deterministic logic to compute positioning signals.
+        No imports from outside the domain layer allowed.
+        """
+        # ... (logic remains same, passed as arg from service)
+        # 1. Health Signal
+        if distance_delta_pct > 20.0 or (hr_delta is not None and hr_delta > 5.0):
+            health_signal = "OVERREACHING"
+        elif consistency_score < 0.6:
+            health_signal = "RECOVERING"
+        elif consistency_score > 0.8 and (hr_delta is None or hr_delta <= 0):
+            health_signal = "OPTIMAL"
+        else:
+            health_signal = "UNKNOWN"
+
+        # 2. Position Status (relative to goal distance)
+        if target_distance and target_distance > 0:
+            diff_pct = (total_distance - target_distance) / target_distance
+            if diff_pct > 0.1:
+                position_status = "AHEAD"
+            elif diff_pct < -0.1:
+                position_status = "FALLING_BEHIND"
+            else:
+                position_status = "ON_TRACK"
+        else:
+            position_status = "UNKNOWN"
+
+        # 3. Goal Trajectory
+        if pace_delta < -5.0 and consistency_score > 0.7:
+            goal_trajectory = "IMPROVING"
+        elif abs(pace_delta) <= 5.0 and consistency_score > 0.6:
+            goal_trajectory = "STABLE"
+        elif pace_delta > 5.0 or consistency_score < 0.5:
+            goal_trajectory = "DECLINING"
+        else:
+            goal_trajectory = "UNKNOWN"
+
+        # 4. Recommended Focus
+        if health_signal == "OVERREACHING":
+            recommended_focus = "RECOVERY"
+        elif consistency_score < 0.7:
+            recommended_focus = "CONSISTENCY"
+        elif health_signal == "OPTIMAL" and goal_trajectory != "DECLINING":
+            recommended_focus = "INTENSITY"
+        else:
+            recommended_focus = "MAINTENANCE"
+
+        return cls(
+            week_start_date=week_start,
+            health_signal=health_signal,
+            position_status=position_status,
+            goal_trajectory=goal_trajectory,
+            recommended_focus=recommended_focus,
+            comparison_available=comparison_available,
+            training_phase=training_phase
+        )

src/domain/training/agent_models.py

@@ -0,0 +1,79 @@
+import uuid
+from datetime import datetime, date
+from typing import Dict, Any, Optional, Union, List, Literal
+from pydantic import BaseModel, Field
+
+
+class Insight(BaseModel):
+    """A single insight generated by the agent."""
+
+    message: str
+    value: Optional[Union[float, int, str]] = None
+    raw_data: Dict[str, Any] = Field(default_factory=dict)
+    evidence: Optional[List[str]] = None
+    constraint: Optional[str] = None
+
+
+class InsightsOutput(BaseModel):
+    """Output from the InsightsAgent."""
+
+    primary_lever: Insight
+    risk_signal: Insight
+    key_observations: List[Insight]
+    summary: Optional[Insight] = None
+
+
+class PlanOutput(BaseModel):
+    """Output from the PlanAgent."""
+
+    plan: str
+
+
+class RiskAssessment(BaseModel):
+    """Assessment of injury or fatigue risk based on heuristics."""
+
+    risk_level: Literal["LOW", "MEDIUM", "HIGH"]
+    reasons: List[str] = Field(default_factory=list)
+    recommended_adjustments: List[str] = Field(default_factory=list)
+    metrics_used: Dict[str, Any] = Field(default_factory=dict)
+
+
+class WeeklyTrends(BaseModel):
+    """Weekly trend metrics used for analysis."""
+
+    pace_trend_s_per_km: Optional[float] = None
+    distance_trend_m: Optional[float] = None
+    avg_runs_per_week: Optional[float] = None
+    run_monotony: Optional[float] = None
+
+
+class WeeklySummary(BaseModel):
+    """Aggregated metrics for the current coaching session."""
+
+    week_start: Optional[date] = None
+    weekly_km: Dict[str, float] = Field(default_factory=dict)
+    consistency_score: int = 50
+    num_runs: int = 0
+    total_distance_m: float = 0.0
+    avg_hr_bpm: Optional[float] = None
+    avg_pace_s_per_km: float = 0.0
+    total_duration_s: int = 0
+    performance_brief: Optional[str] = None
+    performance_focus: Optional[str] = None
+    structure_status: Optional[dict] = None
+    brief_source_hash: Optional[str] = None
+    brief_generated_at: Optional[datetime] = None
+
+
+class AnalysisRecord(BaseModel):
+    """Full record of an analysis run."""
+
+    id: str = Field(default_factory=lambda: str(uuid.uuid4()))
+    created_at: datetime = Field(default_factory=datetime.now)
+    source_files: List[str] = Field(default_factory=list)
+    formats: List[str] = Field(default_factory=list)
+    run_summary: Dict[str, Any] = Field(default_factory=dict)
+    run_timeseries: List[Dict[str, Any]] = Field(default_factory=list)
+    insights_json: Dict[str, Any] = Field(default_factory=dict)
+    plan_json: Dict[str, Any] = Field(default_factory=dict)
+    route_json: Dict[str, Any] = Field(default_factory=dict)

src/domain/training/charts.py

@@ -0,0 +1,22 @@
+from enum import Enum
+from typing import Optional, Dict, Any
+from pydantic import BaseModel, Field
+
+
+class ChartType(str, Enum):
+    """Supported chart types."""
+
+    PACE = "pace"
+    HEART_RATE = "heart_rate"
+    VOLUME = "volume"
+    FREQUENCY = "frequency"
+    ZONES = "zones"
+    DYNAMIC = "dynamic"
+
+
+class ChartSpec(BaseModel):
+    """A specification for a chart to be rendered."""
+
+    chart_type: ChartType
+    title: Optional[str] = None
+    params: Dict[str, Any] = Field(default_factory=dict)

src/domain/training/period_comparison.py

@@ -0,0 +1,12 @@
+from dataclasses import dataclass
+
+
+@dataclass
+class PeriodComparison:
+    period_a_label: str
+    period_b_label: str
+    distance_delta_pct: float
+    avg_pace_delta_s_per_km: float
+    frequency_delta: int
+    avg_hr_delta: float
+    consistency_delta: float

src/domain/training/planned_session.py

@@ -0,0 +1,23 @@
+from typing import Literal, Optional
+from pydantic import BaseModel, Field
+from datetime import datetime, date
+import uuid
+
+
+class PlannedSession(BaseModel):
+    """
+    Represents a planned running session for a specific week.
+    Goal-informed and editable.
+    """
+
+    id: uuid.UUID = Field(default_factory=uuid.uuid4)
+    runner_id: uuid.UUID
+    week_start_date: date
+    session_type: Literal["weekday", "long_run"]
+    planned_date: date
+    target_distance_km: float
+    completed_run_id: Optional[str] = None
+    created_at: datetime = Field(default_factory=datetime.now)
+
+    class Config:
+        frozen = False  # Allow mutation for completed_run_id

src/domain/training/run.py

@@ -0,0 +1,23 @@
+from typing import Optional, Dict, Any, List
+from pydantic import BaseModel
+from datetime import datetime
+
+
+class Run(BaseModel):
+    """Domain model for a single run."""
+
+    id: Optional[str] = None
+    start_time: Optional[datetime] = None
+    total_distance_m: float = 0.0
+    total_duration_s: float = 0.0
+    avg_pace_min_per_km: Optional[str] = None
+    avg_hr_bpm: Optional[float] = None
+    max_hr_bpm: Optional[float] = None
+    elevation_gain_m: float = 0.0
+    source_path: Optional[str] = None
+
+    # Raw records if needed for further processing
+    records: List[Dict[str, Any]] = []
+
+    class Config:
+        extra = "ignore"

src/domain/training/training_recommendation.py

@@ -0,0 +1,12 @@
+from typing import Optional
+from pydantic import BaseModel
+
+class TrainingRecommendation(BaseModel):
+    """
+    Domain model for training recommendations.
+    Deterministic suggestion based on positioning and performance trends.
+    """
+    focus: str
+    session_type: Optional[str] = None
+    description: str
+    confidence: float

src/domain/training/trend_snapshot.py

@@ -0,0 +1,48 @@
+from typing import Optional
+from pydantic import BaseModel, Field
+import uuid
+from datetime import datetime, UTC, date
+
+class TrendSnapshot(BaseModel):
+    """
+    Represents calculated deltas between weekly snapshots.
+    Used for longitudinal trend analysis.
+    """
+
+    id: uuid.UUID = Field(default_factory=uuid.uuid4)
+    runner_id: uuid.UUID
+    week_start_date: date
+    comparison_type: str = "week_over_week"
+    reference_week_start_date: Optional[date] = None
+    
+    @property
+    def comparison_available(self) -> bool:
+        """Returns True if a reference week is available for comparison."""
+        return self.reference_week_start_date is not None
+
+
+    distance_delta_km: Optional[float] = None
+    avg_pace_delta_s_per_km: Optional[float] = None
+    avg_hr_delta: Optional[float] = None
+    runs_count_delta: Optional[int] = None
+    consistency_delta: Optional[float] = None
+
+    engine_version: str
+    computed_at: datetime = Field(default_factory=lambda: datetime.now(UTC))
+
+    @classmethod
+    def empty(cls, runner_id: uuid.UUID, week_start_date: date) -> "TrendSnapshot":
+        """Returns a null trend snapshot with all numeric fields set to None."""
+        return cls(
+            runner_id=runner_id,
+            week_start_date=week_start_date,
+            comparison_type="week_over_week",
+            reference_week_start_date=None,
+            distance_delta_km=None,
+            avg_pace_delta_s_per_km=None,
+            avg_hr_delta=None,
+            runs_count_delta=None,
+            consistency_delta=None,
+            engine_version="null",
+            computed_at=datetime.now(UTC),
+        )

src/domain/training/weekly_snapshot.py

@@ -0,0 +1,62 @@
+from typing import Optional
+from pydantic import BaseModel, Field
+from datetime import datetime, date
+import uuid
+
+
+class WeeklySnapshot(BaseModel):
+    """Aggregated weekly snapshot for long-term tracking."""
+
+    id: uuid.UUID = Field(default_factory=uuid.uuid4)
+    runner_id: uuid.UUID
+    week_start_date: date
+    total_distance_km: float
+    avg_pace_sec_per_km: float
+    avg_hr: Optional[float] = None
+    max_hr: Optional[float] = None
+    total_time_sec: int
+    run_count: int
+    consistency_score: float
+    performance_brief: Optional[str] = None
+    performance_focus: Optional[str] = None
+    brief_generated_at: Optional[datetime] = None
+    brief_source_hash: Optional[str] = None
+    structure_status: Optional[dict] = None
+    charts: Optional[dict] = None
+    created_at: datetime = Field(default_factory=datetime.now)
+
+    @classmethod
+    def from_metrics(
+        cls,
+        runner_id: uuid.UUID,
+        week_start_date: date,
+        total_distance_km: float,
+        avg_pace_sec_per_km: float,
+        total_time_sec: int,
+        run_count: int,
+        consistency_score: float,
+        avg_hr: Optional[float] = None,
+        max_hr: Optional[float] = None,
+        performance_brief: Optional[str] = None,
+        brief_generated_at: Optional[datetime] = None,
+        brief_source_hash: Optional[str] = None,
+        structure_status: Optional[dict] = None,
+        charts: Optional[dict] = None,
+    ) -> "WeeklySnapshot":
+        """Construct a snapshot from aggregated weekly metrics."""
+        return cls(
+            runner_id=runner_id,
+            week_start_date=week_start_date,
+            total_distance_km=total_distance_km,
+            avg_pace_sec_per_km=avg_pace_sec_per_km,
+            total_time_sec=total_time_sec,
+            run_count=run_count,
+            consistency_score=consistency_score,
+            avg_hr=avg_hr,
+            max_hr=max_hr,
+            performance_brief=performance_brief,
+            brief_generated_at=brief_generated_at,
+            brief_source_hash=brief_source_hash,
+            structure_status=structure_status,
+            charts=charts,
+        )

src/domain/training/weekly_snapshot_builder.py

@@ -0,0 +1,60 @@
+from typing import List, Optional
+from datetime import date
+import uuid
+from domain.training.run import Run
+from domain.training.weekly_snapshot import WeeklySnapshot
+
+class WeeklySnapshotBuilder:
+    """
+    Pure domain component to build WeeklySnapshot objects from raw runs.
+    Deterministic, no side effects, no repository dependencies.
+    """
+
+    def build(
+        self, 
+        runner_id: uuid.UUID, 
+        week_start_date: date, 
+        runs: List[Run]
+    ) -> WeeklySnapshot:
+        """
+        Aggregates a list of runs into a weekly snapshot for a specific week.
+        """
+        if not runs:
+            return WeeklySnapshot.from_metrics(
+                runner_id=runner_id,
+                week_start_date=week_start_date,
+                total_distance_km=0.0,
+                avg_pace_sec_per_km=0.0,
+                total_time_sec=0,
+                run_count=0,
+                consistency_score=0.0,
+            )
+
+        total_distance_m = sum(run.total_distance_m for run in runs)
+        total_duration_s = sum(run.total_duration_s for run in runs)
+        total_distance_km = total_distance_m / 1000.0
+
+        avg_pace_sec_per_km = 0.0
+        if total_distance_km > 0:
+            avg_pace_sec_per_km = total_duration_s / total_distance_km
+
+        hr_values = [run.avg_hr_bpm for run in runs if run.avg_hr_bpm is not None]
+        avg_hr = sum(hr_values) / len(hr_values) if hr_values else None
+
+        max_hr_values = [run.max_hr_bpm for run in runs if run.max_hr_bpm is not None]
+        max_hr = max(max_hr_values) if max_hr_values else None
+
+        # Simple consistency metric: 5 runs = 100% (min 1, max 5)
+        consistency_score = float(min(len(runs) * 20, 100))
+
+        return WeeklySnapshot.from_metrics(
+            runner_id=runner_id,
+            week_start_date=week_start_date,
+            total_distance_km=total_distance_km,
+            avg_pace_sec_per_km=avg_pace_sec_per_km,
+            total_time_sec=int(total_duration_s),
+            run_count=len(runs),
+            consistency_score=consistency_score,
+            avg_hr=avg_hr,
+            max_hr=max_hr,
+        )