LLM Coaching Reports — Architecture & Design

# LLM Coaching Reports — Architecture & Design

> **Parent note:** [Sim Racing Telemetry Analysis Platform — Project Plan](joplin://6c0dcb2a567348fd9796f50c790082e4)
> **Related:** [Commercial Deployment Architecture](joplin://052dec863e0948868304e44628986973)
> **Created:** 2026-06-25
> **Context:** Using LLMs to generate natural language coaching reports from structured telemetry analysis.

---

## Core Concept

**Analysis engine does the math → LLM writes the report.**

The LLM is NOT asked to interpret raw telemetry (unreliable and expensive). Instead, the existing analysis pipeline produces structured data, and the LLM converts that into personalized, actionable coaching text.

```
Driver's laps (telemetry)
    │
    ├── Vehicle characteristics DB (grip envelope, shift points)
    │         "This car can sustain 1.4G lateral, driver peaked at 1.1G"
    │
    ├── Other drivers' data (sector times, braking points)
    │         "Fastest driver brakes at 80m marker, you brake at 95m"
    │
    └── Structured analysis (corner-by-corner delta, time loss attribution)
              "T3: -0.4s, braking 12m too early, carrying 7 km/h less"
                        │
                        ▼
              ┌─────────────────────┐
              │  LLM (local or API) │
              │  Structured prompt  │
              └─────────┬───────────┘
                        │
                        ▼
              Coaching report (natural language)

  "Your biggest time loss is in Turn 3. You're braking 12m earlier
   than the fastest reference and only using 1.1G where the car can
   do 1.4G. Try braking at the 80m board and trust the grip — you
   have 0.3G of cornering capacity you're not using."
```

---

## Why This Works

1. **Charts don't coach.** A scatter chart of G-forces doesn't tell a driver what to change. "Brake later, you have grip to spare" does.
2. **The analysis already exists.** Grip envelope, shift points, corner analysis, car characteristics — all computed already. The LLM layer is thin.
3. **Personalized at scale.** 50 drivers at a karting venue each get a unique report tailored to their data, automatically.
4. **Comparative coaching.** "You were 3rd fastest today. The gap to P1 is entirely in Sector 2." — this requires multi-driver data, which the venue platform provides.

---

## Input Data for the LLM Prompt

The coaching endpoint collects structured context from existing analysis:

| Source | Data Provided | Already Computed? |
|---|---|---|
| **Session analysis** | Corner-by-corner speed, braking zones, lap times, grip envelope | ✅ `analyze_car_grip()`, `analyze_shift_points()` |
| **Vehicle characteristics DB** | Max lateral G, max accel/brake G, RPM ranges, shift points | ✅ `characteristics.rs` |
| **Other drivers (venue)** | Sector times, braking points, reference lap | ✅ (with multi-tenancy) |
| **Track model** | Corner locations, apex points, sector boundaries | ✅ `TrackModel` |

---

## LLM Integration Options

| Option | Cost | Privacy | Latency | For pilot? |
|---|---|---|---|---|
| **OpenAI API (GPT-4o-mini)** | ~$0.01-0.05/report | Data sent to cloud | 2-5s | Yes — fastest to ship |
| **Anthropic API (Claude Haiku)** | ~$0.01-0.03/report | Data sent to cloud | 2-5s | Yes |
| **Local model (Ollama, Llama 3)** | Free (hardware cost) | Full privacy | 5-15s (depends on GPU) | Later — privacy selling point |
| **Hybrid** | API for pilot → local for production | Configurable | Varies | Best long-term |

**Privacy angle for venues:** "Your drivers' data never leaves your server" — local LLM as a premium feature.

---

## Implementation Sketch

New endpoint: `POST /api/sessions/{id}/coaching-report`

```rust
// 1. Collect structured analysis data
let analysis = session.analysis;           // existing grip/shift/corner analysis
let characteristics = car_profile(mgr, car); // vehicle limits
let venue_comparison = compare_to_others(mgr, venue_id, track); // other drivers

// 2. Build structured prompt
let prompt = format_coaching_prompt(
    analysis,
    characteristics,
    venue_comparison,
    driver_name,
    track_name,
);

// 3. Call LLM (API or local)
let report = llm_client.generate(prompt).await?;

// 4. Store + return
session.coaching_report = Some(report);
```

Estimated effort: ~2-3 days (prompt engineering + API client + endpoint).

---

## Example Prompt Structure

```
SYSTEM: You are a professional racing driver coach. Generate a concise,
actionable coaching report based on the telemetry data provided.
Focus on the 2-3 biggest areas for improvement. Be specific with
numbers. Be encouraging but direct.

USER:
Driver: Jan M.
Track: Styria Karting Le Mans (1,260m)
Car: Rental kart 200cc 6.5PS
Session: 8 laps, best lap 52.341s

Vehicle limits: max lateral G: 1.4, max brake G: 1.2
Driver achieved: max lateral G: 1.1, max brake G: 0.9

Corner analysis:
- T1 (hairpin): entry 45 km/h, lost 0.3s vs reference (braked 8m early)
- T2 (sweeper): entry 62 km/h, on pace
- T3 (chicane): entry 38 km/h, lost 0.4s (carried 5 km/h less than reference)
- T4 (long straight exit): lost 0.1s (late on throttle)

Venue comparison: 4th of 12 drivers today. Gap to P1: 0.8s (60% in T3).
```

Expected output:

> *"Your best lap was solid, but T3 is where you're losing most of your time — 0.4s there alone. You're braking about 8m too early and carrying 5 km/h less than the reference through the chicane. The kart has 1.4G of cornering grip available but you're only using 1.1G, so there's plenty of margin to trust. Try braking later at the cone and committing to the apex — you have 0.3G of unused grip. Also work on your T4 throttle application; getting on power 10m earlier would gain another 0.1s on the straight."*

---

## Value Proposition for Customers

| Customer | What They Get |
|---|---|
| **Karting venue** | "Every driver gets a personalized coaching report after their session — something no other karting track offers" |
| **Sim racing center** | "Your coaching sessions now include AI-generated analysis reports — sell premium coaching packages" |
| **Racing school** | "Instructors get data-backed coaching notes for every student" |
| **Individual driver** | "Understand exactly why you're slow and what to change — no more guessing" |

---

## "AI" Framing

The analysis is algorithmic (envelope extraction, corner detection, etc.). The "AI" is the LLM that turns structured deltas into natural language. Frame it as:
- ✅ "Automated coaching insights"
- ✅ "Personalized driving feedback after every session"
- ❌ Don't overpromise "AI-powered" without the LLM layer

The LLM coaching report IS the killer feature that differentiates from Aim/MoTeC (charts only, no coaching).

---

*Created: 2026-06-25*

id: ddb8739b673c4ab7a996b951c3a47524
parent_id: 0e8e00b432a840628faa4df5bc2068bc
created_time: 2026-06-25T10:26:52.698Z
updated_time: 2026-06-25T10:26:52.698Z
is_conflict: 0
latitude: 0.00000000
longitude: 0.00000000
altitude: 0.0000
author: 
source_url: 
is_todo: 0
todo_due: 0
todo_completed: 0
source: joplin-desktop
source_application: net.cozic.joplin-desktop
application_data: 
order: 1782383212698
user_created_time: 2026-06-25T10:26:52.698Z
user_updated_time: 2026-06-25T10:26:52.698Z
encryption_cipher_text: 
encryption_applied: 0
markup_language: 1
is_shared: 0
share_id: 
conflict_original_id: 
master_key_id: 
user_data: 
deleted_time: 0
type_: 1