---
paths:
  - proof-of-work/lib/ai/**
  - proof-of-work/app/api/ai/**
---

# AI subsystem

Scoped guidance for the AI generation subsystem (`proof-of-work/lib/ai/**` and the
generate/generations route handlers). Whole-repo rules live in `AGENTS.md`.

## Architecture

- `generate/route.ts` kicks off a **detached background runner** (`generationRunner.ts`)
  and returns an id; the client attaches via SSE (`generations/[id]/stream`) and can also
  poll the row. Navigating away does NOT cancel generation.
- System prompt = `systemPromptBase.ts` (output contract: JSON-only, library
  `exerciseId`s only, suggested weights) + the template's coaching prompt +
  `PROGRAM_OUTPUT_SHAPE` + library + optional history block (`historyContext.ts`).
- Multi-config: `AIConfigProfile` rows per user; `UserPreferences.activeAIConfigId`
  points at the active one and is mirrored into the legacy `ai*` columns for back-compat.

## Provider abstraction

- Each provider yields an async iterable of `GenerateChunk` (`text` / `usage` / `done` /
  `error`); add new ones under `lib/ai/providers/` and register in `index.ts`.
  `openai.ts` exports both `openai` and `openai-compatible`, so the four provider files
  register **5** providers (`claude`, `openai`, `openai-compatible`, `gemini`, `ollama`).
- Streaming AI uses SSE; partial JSON is recovered with `lib/ai/lenientJson.ts`.
- Pricing/model menus live in `lib/ai/pricing.ts` (`PRICES`, `MODEL_MENU`) — keep them
  paired so every menu model has a price entry (there's a test enforcing this).