AI Integration¶

The API integrates with the Anthropic Claude API to provide AI coaching via two endpoints.

Model¶

claude-sonnet-4-6 — max 1024 output tokens per call.

Endpoints¶

One-shot coaching¶

POST /v1/ai/insights
Authorization: Bearer {jwt}

Generates a coaching summary from the analysis results of a session. Returns a structured list of coaching points.

Request body (AiInsightRequestDto):

{
  "GameId": "LmuRf2",
  "TrackName": "Spa-Francorchamps",
  "TrackLayout": "Full",
  "VehicleName": "Ferrari 499P",
  "RefLapMs": 107234,
  "CurLapMs": 108891,
  "Insights": [
    { "Code": "BrakeTooEarly", "Message": "...", "AtDistance": 3450.0 }
  ],
  "SegmentDeltas": [
    { "CornerOrdinal": 1, "DeltaMs": 280 }
  ]
}

Conversational coaching¶

POST /v1/ai/chat
Authorization: Bearer {jwt}

Multi-turn coaching conversation. Same SessionContext fields as above, plus a Messages array of the full conversation history:

{
  "GameId": "...",
  "TrackName": "...",
  "Messages": [
    { "role": "user", "content": "Where am I losing the most time?" },
    { "role": "assistant", "content": "..." },
    { "role": "user", "content": "How should I fix my braking at Raidillon?" }
  ]
}

System Prompt¶

You are ApexLab Coach, an expert sim-racing performance analyst.

The full session context (track, vehicle, lap times, top insights, segment deltas) is injected into the system prompt on every call.

Cost Tracking¶

Every ai_events row records cost_usd computed from the token counts returned by the Anthropic API. SafeWatch's CEO Dashboard surfaces the 30-day AI cost total.

Privacy¶

Raw telemetry is never sent to the AI. The client runs AnalysisEngine locally and sends only the computed findings (insight list, per-corner deltas) to the API.

Without an API Key¶

If Anthropic__ApiKey is not set, requests to /v1/ai/* return 503 Service Unavailable with message "AI coaching is not configured on this server.".