Lars
294b09a5d9
- Introduced migration 068 for `ai_skill_retrieval_profiles`, enabling configurable weights and quotes for skill catalog prioritization in exercise AI suggestions. - Updated the `POST /api/exercises/ai/suggest` endpoint to include an optional `focus_areas_context` field, allowing for enhanced context in AI-generated suggestions. - Enhanced the `exercise_ai` module to utilize context-based skill selection, incorporating scoring, category caps, and keyword patches for improved AI responses. - Updated the ExerciseFormPageRoot component to pass focus area context to the AI suggestion API, streamlining user interaction with AI-generated content. - Incremented version numbers in `backend/version.py` to reflect the latest changes and ensure accurate tracking in the changelog.
5.3 KiB
Umsetzungsplan – KI bei Übungen (stufenweise, Driftschutz)
Version: 0.2
Datum: 2026-05-29
Bezüge: functional/AI_EXERCISE_ASSISTANT_VISION.md · working/AI_SKILL_RETRIEVAL_PROFILES_SPEC.md · technical/KI_FEATURES_SPEC.md · technical/AI_PROMPT_SYSTEM_SPEC.md · technical/AI_TRAINING_PLANNING_CONCEPT.md (§1.1 Ist-Stand)
1. Drift vermeiden – verbindliche Regeln
- Spec vor Code: Request/Response-Felder und Statuscodes an
KI_FEATURES_SPEC.mdausrichten; Abweichungen zuerst Spec oder dieses Dokument anpassen. - Prompts in der DB: Keine produktionskritischen Prompt-Langtexte nur im Code; Defaults per Migration in
ai_prompts, Anpassung durch Admins über vorgesehene Oberfläche (später) oder SQL. - Skill-Retrieval-Profile: Gewichte/Quotes in
ai_skill_retrieval_profiles.config— Spezifikationworking/AI_SKILL_RETRIEVAL_PROFILES_SPEC.md; kein zweites gleichzeitiges Truth-Repo im Sourcecode außer defensiver Fallback_FALLBACK_RETRIEVAL_CONFIGinexercise_ai.py. - Stufen-Slugs & Intensität: Nur kanonische Werte wie in
exercises.py(basis…optimierung,niedrig|mittel|hoch); LLM-Ausgaben normalisieren, ungültigeskill_idverwerfen. - Kein stiller DB-Write: KI liefert Vorschläge; Persistenz nur über bestehende PUT/POST exercises inkl. Trainer-Aktion (und optional
summary_ai_generated/ai_suggestedwie Spec). - Mandant: Übungsbezogene KI-Endpunkte nutzen
Depends(get_tenant_context); keine Ausnahme ohne Eintrag inACCESS_LAYER_ENDPOINT_AUDIT.md. - Schema: Neue DB-Objekte nur nummerierte Migration
backend/migrations/(aktuell bis 068) undDB_SCHEMA_VERSIONanheben.
2. Stufen (Releases)
| Stufe | Inhalt | Exit-Kriterium |
|---|---|---|
| S0 | Dieses Dokument + Verweise konsistent | Review abgehakt |
| S1 | Migration ai_prompts + Defaults exercise_summary, exercise_skill_suggestions; exercises.summary_ai_generated |
Migrierte DB, App startet |
| S2 | httpx-Client OpenRouter; Modul lädt Prompt, ersetzt Platzhalter, parst Antwort |
Unit-/Smoke: 503 ohne Key |
| S3 | POST /api/exercises/ai/suggest, POST /api/exercises/{id}/ai/regenerate |
OpenAPI/Handtest mit Key |
| S4 | Frontend: KI-Vorschlag, Änderungsdialog (Vorschau, Kurzfassung wählbar, Fähigkeiten pro Zeile an-/abwählbar), dann Übernahme ins Formular | Manuelle UX-Prüfung |
| S4b | Skill-Retrieval: Migration ai_skill_retrieval_profiles, focus_areas_context am POST …/ai/suggest, exercise_ai kontextbezogener Katalog (Gewichte, Caps, Keyword-Patches) |
Migration 068 angelegt; Smoke mit Gewaltschutz / ohne Fokus |
| S5 | (später) Auto-Fallback beim Speichern laut KI_FEATURES_SPEC §7 |
Feature-Flag / Config |
| S6 | (später) Zielausbau, Anleitung-only, Varianten, Admin-Masse laut Vision | Separate Epics |
Aktueller Implementierungsstand: S4 + S4b im Code (exercise_ai + Formular übermittelt focus_areas_context).
3. Implementierungs-Checkliste (Technik)
OPENROUTER_API_KEY/OPENROUTER_MODELin.env.exampledokumentiert (bereits teils vorhanden – prüfen).- Fehlerbilder:
400zu wenig Inhalt,503KI nicht konfiguriert,502Upstream-Fehler mit kurzer Message. - Logging: keine vollständigen Prompts mit personenbezogenen Daten in Prod-Logs (optional DEBUG).
- Optional: Rate-Limit KI-Endpunkte (
slowapi) – nach Bedarf. MODULE_VERSIONS["exercises"]/ Changelog bei API-Erweiterung setzen.
4. Changelog dieses Plans
- 2026-05-22: Initial; S1–S4 als erster Umsetzungspfad.
- 2026-05-22: S1–S4 im Code umgesetzt (Migration 067,
exercise_ai+ Router, Übungsformular); S5 weiter offen. - 2026-05-29: S4b: Migration 068,
ai_skill_retrieval_profiles; suggestfocus_areas_context; Frontend sendet gesetzte Fokusbereiche; Specworking/AI_SKILL_RETRIEVAL_PROFILES_SPEC.md.
5. Umsetzungsstand (Zwischencheckpoint)
Erledigt (2026-05-22): Migration 067_ai_prompts_exercise_assistant, openrouter_chat, exercise_ai, POST /api/exercises/ai/suggest und POST /api/exercises/{id}/ai/regenerate, Formular-Schaltflächen (Kurzfassung / Fähigkeiten / kombiniert).
Erledigt (2026-05-29): Migration 068 / Profil ai_skill_retrieval_profiles (Standard + Profil Gewaltschutz wenn focus_areas.name vorhanden); exercise_ai — Score/Kategorie-Zapfen/Text-Overlap/Keyword-Zuschläge; API: ExerciseAiSuggestBody.focus_areas_context; Regenerate nutzt DB-Fokuszeilen.
Nacharbeit S4 UX: Übernahmedialog ExerciseFormPageRoot: keine sofortige Überschreibung; Kurzfassung mit Vergleich + Checkbox; Fähigkeiten mit Neu/Aktualisierung, Checkboxen, „Alle auswählen/abwählen“; Escape schließt; KI-Schaltflächen blockiert solange Dialog offen.
Offen nächste Schritte Pflege/Umsetzung: weitere Retrieval-Profile (z. B. Karate-/Fitness-Schwerpunkt) per SQL später Admin-UI; optionales Feld skills.ai_context Kurzbeschreibung für KI; automatische KI beim Speichern (S5); Prompt-/Profil-Admin-UI ohne SQL; Rate-Limits.
Bewusst noch nicht (summary_ai_generated): zurücksetzen bei manueller Kurzfassung im UI; Admin-Pflege ai_skill_retrieval_profiles.