diff --git a/.claude/docs/PROJECT_STATUS.md b/.claude/docs/PROJECT_STATUS.md index e4a793f..3ab8915 100644 --- a/.claude/docs/PROJECT_STATUS.md +++ b/.claude/docs/PROJECT_STATUS.md @@ -83,7 +83,9 @@ Die exakten Zahlen hängen von der Umgebung ab (siehe Admin/DB). Die Skills/Übu - [x] **Varianten** (CRUD, Reorder, Voraussetzung) + Anzeige im Detail - [x] **Progressionsgraph zwischen Übungen** (Bibliotheks-Container, Kanten, Sequenz-Bulk, Varianten-Knoten — Zwischenstand, siehe TRAINING_FRAMEWORK_SPEC §4) - [x] Medien (Upload/Embed, rollenabhängige Größenlimits) -- [x] Suche & Filter (Multi-Filter, Chips, Fokus beim Suchen) +- [x] Suche & Filter (Multi-Filter, Chips, Fokus beim Suchen; **Freigabelevel** als UI-Begriff für `visibility`) +- [x] **Übungsformular:** Registerkarten (Stammdaten … Medien & Mehr), kompakte Chip-Editoren, Varianten-Speichern über Aktionsleiste +- [x] **Fähigkeiten-Intensität** ohne Primär-Flag (`niedrig`/`mittel`/`hoch`; Backend `is_primary` immer false) - [x] Exercise Blocks (Bausteine) - [x] Saved Searches (wo implementiert) diff --git a/.claude/docs/functional/AI_EXERCISE_ASSISTANT_VISION.md b/.claude/docs/functional/AI_EXERCISE_ASSISTANT_VISION.md new file mode 100644 index 0000000..4b786ba --- /dev/null +++ b/.claude/docs/functional/AI_EXERCISE_ASSISTANT_VISION.md @@ -0,0 +1,100 @@ +# KI-Unterstützung bei Übungen – Produkt-Vision + +**Version:** 0.1 +**Datum:** 2026-05-22 +**Status:** Zielbild / Anforderungsgrundlage (nicht gleich Ist-Spec – technische Schnittstellen: **`technical/KI_FEATURES_SPEC.md`**, **`technical/AI_PROMPT_SYSTEM_SPEC.md`**, **`technical/AI_TRAINING_PLANNING_CONCEPT.md` §1.1**) +**Zielgruppe:** Product, Trainer-UX, später Admin-Werkzeuge + +--- + +## 1. Übergeordnete Prinzipien + +1. **Immer Vorschlag, nie blind überschreiben** + Die KI liefert **Vorschläge** (Änderungen, Ergänzungen, Strukturen). Bestehende Inhalte werden **nicht** still ersetzt. Übernahme erfolgt durch den Nutzer: **teilweise** (Felder/Stellen/Blöcke) oder **komplett** („Vorschlag gesamt akzeptieren“). + +2. **Granulare Anforderung im Editor** + Innerhalb einer Übung soll KI-Unterstützung **feldbasiert oder bereichsbasiert** auslösbar sein (z. B. nur „Anleitung schärfen“, nur „Fähigkeiten“, nur „Variantenrahmen“) **oder** als **Komplettüberarbeitung** mit klarem Warnhinweis (Umfang/transparenter Diff). + +3. **Nachweisliche Herkunft** + Übernommene KI-Inhalte werden technisch dort abgebildet, wo bereits vorgesehen (z. B. **`summary_ai_generated`**, **`exercise_skills.ai_suggested`**) und um analogen Hinweis für weitergehende Textfelder/Varianten **erweitert**, sobald Implementierung konkret wird. + +--- + +## 2. Funktionsbereiche (Vision) + +### 2.1 Von der Idee zur kompletten Übung („Zielausbau“) + +**Einstieg minimal:** Kurzbeschreibung oder Stichwort, **Ziel** („was soll erreicht werden?“), wenige **Rahmenparameter** (z. B. Fokusbereich, Trainingszeit, Teilnehmerzahl, Alter, Platzausstattung, Sicherheitshinweise – konkrete Dropdowns/Freifelder in UX später festlegen). + +**KI-Aufgabe:** aus diesem dünnen Kontext einen **übernehmbaren Entwurf** einer **ganzen Übung** erzeugen: Titel‑Vorschlag, Ziel-/Durchführungstext, Sicherheit/Organisation, ggf. Trainerhinweise – **immer als Vorschlagspaket**, nicht als Speicher ohne Bestätigung. + +**Abgrenzung:** Kombinationsübungen / komplexe Methodenprofile können **phasenweise** später einbezogen werden (Verweis Fachspez Trainingsmodule). + +### 2.2 Anleitung (Durchführung / „Ausführung“) maximal hilfreich + +**Ziel:** Die **Ausführungs-/Anleitungsbereiche** sollen sich **didaktisch klar**, **teilbar** und **wieder verwendbar** lesen – ohne den Trainer zu entmindigen. + +**KI-Aufgabe:** Überarbeitungsvorschlag für Struktur (nummerierte Schritte, Zeiten pro Block, häufige Fehler, Progressionshinweise innerhalb der Übung wo sinnvoll). **Selektiver** Aufruf: nur diese Felder oder nur ein markierter Abschnitt (wenn UX Textauswahl unterstützt). + +### 2.3 Kurzbeschreibung (`summary`) + +**KI-Aufgabe:** Aus den **relevanten Übungstexten** eine **Liste-/Karte-taugliche** Kurzfassung generieren — wie in **`KI_FEATURES_SPEC.md`** beschrieben, mit **Ablehnen / Bearbeiten / Übernehmen**. + +### 2.4 Einordnung – primär **Fähigkeiten** + +**KI-Aufgabe:** automatische Erkennung und **Zuordnung** zum **globale Skills-Katalog** inklusive: + +- **Intensität** (`exercise_skills`) +- **Skill-Level**: `required_level` / `target_level` nach **kanonischen Slugs** (Backend-konform) +- **`is_primary`** / Priorisierung wo fachlich sinnvoll + +**Prompt-Kontext für Qualität:** Stammfelder wie `skills.description`, **`karate_relevance`**, **`relevance_level`**, **`focus_areas`**, optional **`skill_level_definitions`** nur für eine **kurze Kandidatenliste** (zweite Runde möglich) – keine vollständigen Romane für den gesamten Katalog auf einmal. + +### 2.5 Varianten (optional, später prioritär erwägenswert) + +**Vision:** Aus Ziel-/Durchführungstext **mehrere sinnvolle Ausprägungen** als **Übungsvarianten** vorschlagen oder einzelne erzeugen (**progression**, **Schwierigkeit**, andere Paararbeit, Gerätevariation) mit **übernehmbarem** Datenmodell gleich dem bestehenden `exercise_variants`. + +**Randbedingungen:** Validierung gegen Übungstyp (Kombinationsübungen ohne Varianten laut Produktstand), keine Halluzination fremder IDs. + +--- + +## 3. Kontextbezug später: Nachbearbeitung aus der Trainingsplanung + +**Vision:** Hinweise aus der **Nachbearbeitung** einer Trainingseinheit (Ist‑Minuten, Trainer-Notizen, Abweichungen „was lief nicht?“ – je nach Datenmodell) fließen **optional** als Kontext in eine **erneute KI-Überarbeitung der betroffenen Übung** ein („Übung aus den Erfahrungen der Gruppe verbessern“). + +**Konsequenz technisch später:** Zugriffsrechte, Mandant, keine unzulässige Verknüpfung personenbezogener Sportlerdaten; Aggregation auf **Einheit-/Gruppe** und **bereits dokumentierte Trainer-Insights**. + +--- + +## 4. Admin: Massenverarbeitung und Analyse + +**Vision für Plattform-/Vereins-Admins:** + +| Thema | Richtungsziel | +|-------|----------------| +| **Massenverarbeitung** | Batch: z. B. Zusammenfassungen nachziehen, fehlende Skills vorschlagen, einheitlicher Stil bei importiertem Bestand — immer mit **Review-Queue**, nicht ohne menschliche Freigabe skalierungskritisch. | +| **Analyse / Qualität** | Werkzeugkasten oder Berichte: **welche Übungen** sollten überarbeitet werden? z. B. leere/kurze `summary`, fehlende `goal`/`execution`, **fehlende oder widersprüchliche Skill-Zuordnung**, Import-Herkunft ohne Plausibilität, Kombi-Slots unvollständig, sehr alte Imports. | +| **Lückenkarten** | Z. B. Abgleich gegen **Skill-Discovery**/Profil-Analysen („keine Übung deckt Fähigkeit X ab“ auf gewähltem Korpus); Verbindung zu **`skill-discovery`** entscheidend später im Detail (kein automatischer Rewrite ohne Policy). | + +**Governance:** Sichtbarkeit (`official`, Verein), Rechte (**Superadmin** vs. Vereinsinhalt), Audit der KI-Anwendung bei Massenjobs. + +--- + +## 5. Phasierung (überarbeitungsfähig) + +| Phase | Inhalt | +|-------|--------| +| **P0** | KI-Service + Prompts aus DB + **Suggestion-only** UX; Kern: **Summary** + **Skills** (wie Spec-Minimum), **ein Feld / Komplettpaket mit Diff** nach UX. | +| **P1** | **Anleitung überarbeiten** + **„von Idee zur Übung“** (Zielausbau) mit Rahmenparameter-Form | +| **P2** | **Variantenvorschläge** mit strenger Validation | +| **P3** | **Planungs-/Nachbereitungskontext** | +| **P4** | **Admin** Massen-/Analyse (Queue + Reports + Governance) | + +--- + +## 6. Offene Produkt-/Fachfragen + +- Minimaler **Parameterbau** beim Zielausbau (Pflicht vs. optional). +- Umgang mit **Medien**/Inline-Verweisen beim KI-Text – nichts zerstören, Platzhalter erhalten (siehe Medien-Spec §11). +- **Kombinationsübungen:** welche Teilaspekte dürfen KI anfassen? +- Limits: **Tokens**, **Rate-Limits**, Kostenüberwachung pro Verein/global. diff --git a/.claude/docs/functional/DOMAIN_MODEL.md b/.claude/docs/functional/DOMAIN_MODEL.md index d512d08..158d784 100644 --- a/.claude/docs/functional/DOMAIN_MODEL.md +++ b/.claude/docs/functional/DOMAIN_MODEL.md @@ -57,7 +57,7 @@ Haupt-Kategorie (KARATE / ALLGEMEINE) - Selbstverteidigung ✓ - Gewaltschutz ✓ -**Technische Umsetzung:** M:N Beziehungen mit `is_primary` Flag. +**Technische Umsetzung:** M:N-Beziehungen mit optionalem `is_primary`-Flag bei **Fokusbereichen, Stilrichtungen, Trainingsstilen und Zielgruppen** — nicht bei `exercise_skills` (dort nur Intensität `niedrig|mittel|hoch`). ### 3. Hierarchischer Kontext (§8.1) diff --git a/.claude/docs/functional/SHINKAN_REQUIREMENTS.md b/.claude/docs/functional/SHINKAN_REQUIREMENTS.md index 84c44ba..9141e4f 100644 --- a/.claude/docs/functional/SHINKAN_REQUIREMENTS.md +++ b/.claude/docs/functional/SHINKAN_REQUIREMENTS.md @@ -12,6 +12,8 @@ Ausführliche fachliche Inhalte: | [**Trainingsmodule & Kombinationsübungen (Fachspez V3)**](./Shinkan%20Trainingsmodule%20Kombinationsuebungen%20Spezifikation%20V2.md) | Produktlogik Module/Kombinationen, **Methoden-Archetypen**, **Coaching-Stufen (§ 10.4)**, kanonische Archetyp-IDs **§ 10.2.1**, **Anhang A** Implementierungsabgleich | | [**Umsetzungsplan Trainingsmodule & Kombination**](../working/TRAINING_MODULES_IMPLEMENTATION_PLAN.md) | Phase 1–5, Coaching-Pakete 4a–4d, Verweis auf Code-Stand | | [**Technischer Entwurf Module/Kombination**](../technical/TRAINING_MODULES_AND_COMBINATION_EXERCISES_SPEC.md) | API/Daten-Ideen; aktueller Coach-/Archetyp-Abgleich im Kopfabschnitt | +| [**KI-Unterstützung Übungen (Vision)**](./AI_EXERCISE_ASSISTANT_VISION.md) | Zielbild Zielausbau, Vorschlags-UX (teilweise/komplett), Skills/Varianten, später Planungskontext, Admin-Masse/Qualität | +| [**KI Übungen – Umsetzungsplan**](../working/AI_EXERCISE_IMPLEMENTATION_PLAN.md) | Stufen S0–S6, Driftschutz-Regeln, Checkliste gegen Specs | **Lieferstand & Umsetzung (Stand Code):** [`../PROJECT_STATUS.md`](../PROJECT_STATUS.md), [`../library/FEATURES_DELIVERED_2026-Q2.md`](../library/FEATURES_DELIVERED_2026-Q2.md) (Abschnitt 12), Repo-Root **`docs/HANDOVER.md`**, **`docs/FACHLICHE_NUTZERFUNKTIONEN.md`**. diff --git a/.claude/docs/library/FEATURES_DELIVERED_2026-Q2.md b/.claude/docs/library/FEATURES_DELIVERED_2026-Q2.md index e6f1af9..df5e5cb 100644 --- a/.claude/docs/library/FEATURES_DELIVERED_2026-Q2.md +++ b/.claude/docs/library/FEATURES_DELIVERED_2026-Q2.md @@ -68,7 +68,7 @@ Logik: `_upload_limit_bytes(session)` vor `read()`-Prüfung. ## 5. Frontend – Übungsliste (`ExercisesListPage.jsx`) - Tabs **Liste** · **Progressionsgraphen** (`ExerciseProgressionGraphPanel`): Graphen anlegen/bearbeiten, Kanten inkl. Sequenz-Bulk und Tabellenansicht. -- **Filter-Modal** (Fokus, Stilrichtung, Trainingsstil, Zielgruppe, Fähigkeit + Stufen von/bis, Sichtbarkeit, Status). +- **Filter-Modal** (Fokus, Stilrichtung, Trainingsstil, Zielgruppe, Fähigkeit + Stufen von/bis, **Freigabelevel**, Status). - **Filter-Chips** unter der Suchleiste; Klick entfernt einen Filter; Badge am Filter-Button = Anzahl Chips. - **Kein Vollbild-Spinner** bei jeder Suche: nur noch **`listFetching`** — Suchfelder bleiben im DOM (**Fokus/Cursor** bleiben erhalten); Liste zeigt optional „Aktualisiere Treffer…“. - **``** mit Titeln der aktuellen Treffer; **`autoComplete="on"`** für Browser-Vorschläge. @@ -76,14 +76,47 @@ Logik: `_upload_limit_bytes(session)` vor `read()`-Prüfung. --- -## 6. Frontend – Übung bearbeiten (`ExerciseFormPage.jsx`) +## 6. Frontend – Übung bearbeiten (`ExerciseFormPageRoot.jsx`) + +**Routing:** `/exercises/new`, `/exercises/:id/edit` — keine separaten Varianten-Routen. + +### 6.1 Tab-Navigation (Registerkarten) + +Horizontale **`PageSectionNav`** über **`ExerciseFormTabBar`** / **`ExerciseFormPanel`** (`ExerciseFormLayout.jsx`); farbige linke Panel-Ränder (CSS `.exercise-form-edit`, `.exercise-form-panel--*`). + +| Tab | Inhalt | +|-----|--------| +| **Stammdaten** | Titel, Kurztext, Dauer/Gruppe, Equipment, **Freigabelevel** (`visibility`), Status, Verein | +| **Anleitung** | Ziel, Durchführung, Vorbereitung, Trainerhinweise (Rich-Text inkl. Inline-Medien) | +| **Einordnung** | Fokusbereiche, Stilrichtungen, Trainingsstile, Zielgruppen, Altersgruppen, **Fähigkeiten** (kompakte Chip-Editoren) | +| **Kombination** | nur bei `exercise_kind=combination`: Slots, Archetyp, `method_profile` | +| **Varianten** | nur nach erstem Speichern; **nicht** bei Kombinationsübungen | +| **Medien & Mehr** | Medien, Progressionsgraph, KI-Hilfen, Löschen — nach erstem Speichern | + +Neue Übungen: Tabs **Varianten** und **Medien & Mehr** deaktiviert bis zur ersten Speicherung. + +### 6.2 Freigabelevel (UI-Begriff) + +Feld **`exercises.visibility`** heißt in der UI durchgängig **Freigabelevel** (`frontend/src/constants/exerciseGovernanceLabels.js`) — Liste, Filter, Bulk, Picker, Formular. API/DB-Feldname **`visibility`** unverändert. + +### 6.3 Fähigkeiten am Übungsobjekt + +- Intensität je Fähigkeit: **`niedrig` \| `mittel` \| `hoch`**, Standard **`mittel`** (`exerciseSkillIntensity.js`). +- Kein „Primär“-Schalter mehr in der UI; **`is_primary`** bei `exercise_skills` ist Legacy — Backend speichert immer **`false`**, Scoring ignoriert das Feld. +- Kompakte **Chip-Editoren** für Katalog-Zuordnungen und Fähigkeiten (`ExerciseCatalogAssocEditor`, `ExerciseSkillsEditor`). + +### 6.4 Varianten-Editor + +- Tab **Varianten**: **eine Variante zur Zeit** (Dropdown oder „Erste Variante anlegen“); Felder über **`ExerciseVariantFields`**; Reihenfolge Nach oben/unten; Löschen pro Variante. +- **Speichern über Aktionsleiste:** `performSaveAttempt` ruft zuerst **`persistPendingVariantChanges()`** auf (geänderte Varianten per PUT, danach optional Entwurf **`createVariantFromDraft()`**). +- Button **„Variante anlegen“** (`type="button"`, kein verschachteltes `
`): legt Entwurf sofort per API an; alternativ mitgesichert über **Speichern** in der Aktionsleiste. +- Snapshot **`variantsSavedSnapshotRef`** für Dirty-Erkennung; Hinweis im Panel: Änderungen werden mit Speichern in der Aktionsleiste mitgesichert. + +### 6.5 Medien & Progressionsgraph -- **Varianten-Editor**: eingeklappter Bereich (`
`), **eine Variante zur Zeit** über Dropdown oder „Neue Variante“; Felder über **`ExerciseVariantFields`**; Reihenfolge Nach oben/unten; Speichern/Löschen pro Variante. - **Medien:** Upload/Embed, **Archiv verknüpfen** (`from-asset`), Medienliste mit Vorschau, Reaktivierung bei Archiv-Konflikt — Details **§12**. - Block **Progressionsgraph** (Edit): Kanten mit Bezug zur aktuellen Übung. -Hinweis: Es gibt **keine** separaten Routen `/exercises/:id/variants/...` — Bearbeitung erfolgt unter **`/exercises/:id/edit`** (Routing-Doku ggf. anpassen). - --- ## 7. Frontend – Übung Detail (`ExerciseDetailPage.jsx`) @@ -192,7 +225,21 @@ Norm: **`technical/SKILL_SCORING_SPEC.md`**. --- -## 16. Verweise +## 16. Übungen – Governance & Berechtigungen (Ist, Stand 2026-05-20) + +**Owner:** `exercises.created_by` (Ersteller). **Varianten** haben kein eigenes `created_by` — Rechte leiten sich von der Eltern-Übung ab. + +| Aktion | `private` | `club` | `official` | +|--------|-----------|--------|------------| +| **Lesen** | Ersteller; Plattform-Admin | Aktive Vereinsmitglieder des Objekt-`club_id`; Plattform-Admin ohne Mitgliedschaft (Audit) | Plattform-weit | +| **Bearbeiten** (Übung inkl. Varianten/Medien) | Ersteller; Plattform-Admin | Ersteller; Plattform-Admin; **`can_plan_in_club`** im Objekt-Verein (`trainer`, `content_editor`, `division_lead`, `club_admin`) | Plattform-Admin | +| **Löschen** | Ersteller; Vereins-Admin gemeinsamer Vereine mit Ersteller | Nur **`club_admin`** im Objekt-Verein | Nur Plattform-Admin | + +**Code:** `backend/club_tenancy.py` (`exercise_visible_to_profile`, `can_plan_in_club`), `backend/routers/exercises.py` (`_assert_can_edit_exercise`, `_assert_can_delete_exercise`). + +--- + +## 17. Verweise | Thema | Dokument | |--------|----------| diff --git a/.claude/docs/technical/ACCESS_LAYER_AND_GOVERNANCE_PLAN.md b/.claude/docs/technical/ACCESS_LAYER_AND_GOVERNANCE_PLAN.md index 2daf6d6..4225c87 100644 --- a/.claude/docs/technical/ACCESS_LAYER_AND_GOVERNANCE_PLAN.md +++ b/.claude/docs/technical/ACCESS_LAYER_AND_GOVERNANCE_PLAN.md @@ -119,8 +119,24 @@ Ausgangslage im Code: `private` \| `club` \| `official` (siehe `club_tenancy`). - `.claude/docs/technical/MULTI_TENANCY_RBAC_ARCHITECTURE.md` – übergeordnetes Zielbild & Begriffe. - `.claude/docs/technical/MEDIA_ASSETS_AND_ARCHIVE_SPEC.md` – verbindliche Domänenregeln für **Medien-Assets** (gleiche Sichtbarkeit wie Übungen, Promotion-Kopplung, Copyright, Papierkorb/Lebenszyklus, externer Speicher). Bei Widerspruch zur Sichtbarkeits-Tabelle in §3 dieses Dokuments: §3 für Enums/`library_content_*`-Semantik, Medien-Spez für Asset-spezifische Zusatzregeln. -- `backend/club_tenancy.py` – bestehende Bausteine (`assert_club_member`, `exercise_visible_to_profile`, …); Ziel ist Deren schrittweise Zusammenführung unter die neue Zugriffsschicht ohne Big-Bang. +- `backend/club_tenancy.py` – bestehende Bausteine (`assert_club_member`, `exercise_visible_to_profile`, `can_plan_in_club`, …); Ziel ist Deren schrittweise Zusammenführung unter die neue Zugriffsschicht ohne Big-Bang. --- -**Letzte Aktualisierung:** 2026-05-07 +## 8. Anhang – Übungen (Ist-Implementierung, Referenz) + +**Stand:** 2026-05-20 · **Detail:** `EXERCISES_API_SPEC.md` Permissions, `FEATURES_DELIVERED_2026-Q2.md` §16 + +| Feld / Konzept | Semantik | +|----------------|----------| +| `created_by` | Owner der Übung; Varianten erben Rechte | +| `visibility` | UI: **Freigabelevel** — `private` \| `club` \| `official` | +| Lesen | `exercise_visible_to_profile` — `official` global; `private` Ersteller + Plattform-Admin; `club` aktive Mitglieder (+ Plattform-Admin Audit) | +| Bearbeiten | Ersteller; Plattform-Admin; bei `club` zusätzlich `can_plan_in_club` (Trainer, Content-Editor, Spartenleitung, Vereins-Admin) | +| Löschen | `official` → Plattform-Admin; `club` → `club_admin` im Objekt-Verein; `private` → Ersteller oder Vereins-Admin mit gemeinsamem Verein | + +**Hinweis:** Dieser Anhang dokumentiert den **produktiven Code-Pfad** in `exercises.py`; die Roadmap in §4 bleibt für die langfristige Vereinheitlichung aller Bibliotheksartefakte maßgeblich. + +--- + +**Letzte Aktualisierung:** 2026-05-20 diff --git a/.claude/docs/technical/AI_PROMPT_SYSTEM_SPEC.md b/.claude/docs/technical/AI_PROMPT_SYSTEM_SPEC.md index b0b53bf..ba8b968 100644 --- a/.claude/docs/technical/AI_PROMPT_SYSTEM_SPEC.md +++ b/.claude/docs/technical/AI_PROMPT_SYSTEM_SPEC.md @@ -6,6 +6,8 @@ **Autor:** Claude Code **Vorbild:** Mitai Jinkendo Issue #53 + `backend/routers/prompts.py` + Placeholder-System +**Verwandt (Skill-Katalog in Übungs-KI):** `working/AI_SKILL_RETRIEVAL_PROFILES_SPEC.md` — Tabelle **`ai_skill_retrieval_profiles`** (`config`-JSON ergänzt inhaltliche Prompt-/Katalog-Steuerung neben Platzhaltern). + --- ## 1. Konzept @@ -174,10 +176,9 @@ Wähle maximal 5 passende Fähigkeiten. Für jede gib an: - required_level: Voraussetzung (einsteiger|grundlagen|aufbau|fortgeschritten|experte) - target_level: Ziel nach regelmäßigem Training (gleiche Werte) - intensity: Trainingsintensität (niedrig|mittel|hoch) -- is_primary: true wenn Hauptfähigkeit Antworte NUR als JSON-Array: -[{"skill_id": 1, "required_level": "grundlagen", "target_level": "aufbau", "intensity": "hoch", "is_primary": true}] +[{"skill_id": 1, "required_level": "grundlagen", "target_level": "aufbau", "intensity": "hoch"}] Wenn keine Fähigkeit passt, antworte mit [].$$, 'exercise', 'json', true, NULL, 2), diff --git a/.claude/docs/technical/AI_TRAINING_PLANNING_CONCEPT.md b/.claude/docs/technical/AI_TRAINING_PLANNING_CONCEPT.md index 372f92d..c28fdd5 100644 --- a/.claude/docs/technical/AI_TRAINING_PLANNING_CONCEPT.md +++ b/.claude/docs/technical/AI_TRAINING_PLANNING_CONCEPT.md @@ -1,12 +1,14 @@ # KI-gestützte Trainingsplanung – Zentrales Konzept -**Version:** 0.1 -**Datum:** 2026-05-16 +**Version:** 0.3 +**Datum:** 2026-05-22 **Status:** Arbeitsdokument (Verfeinerung durch fachliche Konzept-Agentur vorgesehen) -**Ziel:** Einheitlicher Rahmen für **stufenweise** KI-Unterstützung bei der Planung (Abschnitte, Einheiten, später mehrtägig/Rahmen) – ohne vollständigen Katalog im Prompt zu spiegeln. +**Ziel:** Einheitlicher Rahmen für **stufenweise** KI-Unterstützung – zuerst **Übungsanlage** (Zusammenfassung, Fähigkeiten, Texte), später **Planung** (Abschnitte, Einheiten, Rahmen) – ohne vollständigen Übungskatalog im Prompt. + +**Maßgebende Version zum Abgleich:** `backend/version.py` (`APP_VERSION`, `DB_SCHEMA_VERSION`, relevante Einträge in `MODULE_VERSIONS`). **Verwandte Dokumente:** -`functional/DOMAIN_MODEL.md` · `functional/TRAINING_CURRICULUM_AND_GOVERNANCE_CONCEPT.md` (u. a. CURR-003 zu Progressions-/KI-Automatik) · `technical/TRAINING_FRAMEWORK_SPEC.md` · `technical/KI_FEATURES_SPEC.md` · `technical/AI_PROMPT_SYSTEM_SPEC.md` · `docs/FACHLICHE_NUTZERFUNKTIONEN.md` · `docs/HANDOVER.md` +`functional/DOMAIN_MODEL.md` · **`functional/AI_EXERCISE_ASSISTANT_VISION.md`** (Übungs-KI: Zielbild vor Planungs-KI) · `functional/TRAINING_CURRICULUM_AND_GOVERNANCE_CONCEPT.md` (u. a. CURR-003 zu Progressions-/KI-Automatik) · **`working/AI_PLANNING_KI_MULTISTAGE_FORECAST.md`** (mehrstufige Planungs-KI: Daten-„Graph“, Pipeline-Stufen, Code-Schnitte – Vorschau gegen späteres Refactoring) · `technical/TRAINING_FRAMEWORK_SPEC.md` · **`technical/SKILL_SCORING_SPEC.md`** (Fähigkeits-Profilierung, Discovery) · `technical/KI_FEATURES_SPEC.md` · `technical/AI_PROMPT_SYSTEM_SPEC.md` · `technical/SKILLS_MATRIX_SPEC.md` · `docs/FACHLICHE_NUTZERFUNKTIONEN.md` · `docs/HANDOVER.md` --- @@ -16,13 +18,30 @@ - **Human-in-the-loop:** KI liefert **Vorschläge** (Liste, Reihenfolge, Begründung); schreibende Übernahme in Pläne nur nach **Trainer-Bestätigung** oder expliziter Aktion (analog „Manual First“ in `KI_FEATURES_SPEC.md`). - **Governance-first:** Nur Übungen, die die API bereits für den Mandanten/Kontext **sichtbar** freigibt, dürfen in Kandidatenlisten landen – **vor** Retrieval und **vor** jedem Prompt. +### 1.1 Abgleich: aktueller Code- und Schema-Stand (Stand Review 2026-05-22) + +| Thema | Ist im Repo | Konsequenz für dieses Konzept | +|--------|-------------|-------------------------------| +| **OpenRouter / LLM im Backend** | Produktiver Aufruf für Übungs‑Suggest in `openrouter_chat.py`, `exercise_ai.py`; Endpunkte **`POST …/exercises/ai/suggest`** und **`POST …/{id}/ai/regenerate`**; Migration **067** (`ai_prompts`, `summary_ai_generated`). **`db.py`**-Bootstrap nutzt **`display_name`**. | **Übungs-Assistent (P0)** vorhanden; generalisierter Service + **Planungs-KI** folgen. | +| **Übungs-KI laut Spec** | P0: Kurzfassung + Skill‑Vorschläge (`include_summary` / `include_skills`); **kein** Auto-KI beim Speichern (S5 im Umsetzungsplan). | Feinspez: `summary_ai_generated` bei manueller Kurzfassung zurücksetzen; Rate-Limits; Prompt-Admin-UI. | +| **Fähigkeiten-Stammdaten** | Migration **`065_skills_wiki_karate_relevance`:** `skills.karate_relevance` (Text), `skills.relevance_level` (1–3, optional); dazu weiterhin `description`, `focus_areas`, Kategorien, `skill_level_definitions` (Level 1–5 je Skill). | Diese Felder sind **expliziter Prompt-Kontext** für Skill-Vorschläge (Disambiguierung Karate vs. universal) – siehe §6. | +| **Skill-Scoring & Discovery (ohne LLM)** | Router `skill_profiles.py` + Modul `skill_scoring.py`: u. a. `GET …/skill-profile` für **Rahmenprogramm**, **Trainingsmodul**, **Progressionsgraph**; `POST /skill-profiles/batch-summaries`; **`GET /api/skill-discovery/suggestions`** (Match Bibliotheksartefakte ⇄ `skill_ids`, mit `library_content_visibility_sql`). | Ergänzt §3 **Stufe 3**: deterministische **Skill-Abdeckung / Artefakt-Discovery** ist **bereits vorhanden** und kann später die **Planungs-KI** speisen (Ziel-Skill-Mengen, Vergleich „Profil des Rahmens“) – ersetzt aber **nicht** die Top‑K-Selektion aus dem **Übungskatalog** für eine konkrete Session. | +| **Profil / Planungs-Präferenzen** | `profiles.training_planning_prefs` (JSONB, vgl. `MODULE_VERSIONS` → `profiles`), Planungsmodul mit u. a. **Vorlagen inkl. Split-Sessions** (`planning`), `training_units` mit **Publish in Rahmen-Slot-Blueprint**. | Zukünftige KI-Planung kann **Prefs** und **Vorlagen-Struktur** als weiche Constraints einbeziehen; Rahmen↔Einheit-Fluss ist produktiv erweitert – für KI nur relevant, sobald Planungs-Endpunkte angebunden werden. | +| **Übungsliste API** | Keyset-Pagination u. a. `cursor_updated_at` + Tie-break `id` (`exercises`-Modul laut `MODULE_VERSIONS`). | Retrieval-Pipelines sollten **cursorbasiert** paginieren, nicht „alle IDs auf einmal“ laden. | + +**Nächster produktiver Fokus:** Prompt-/Admin‑UI zur Pflege von `ai_prompts`, **Rate-Limits**, optional **Auto-KI beim Speichern**; danach Übergang zur **Planungs-KI** laut diesem Dokument. + +**Architektur-Vorschau (Planungs-KI):** Damit die **kleinere, starre** Übungs-Pipeline nicht zur stillen Vorlage für Planung wird, sind **eigenes Modul**, **stufenweise Outputs mit Validierung** und ein **kompaktes Kontext-DTO** vorgesehen — siehe **`working/AI_PLANNING_KI_MULTISTAGE_FORECAST.md`**. + --- ## 2. Kernproblem: Skalierung des Kontextes Aus einer **großen Übungssammlung** („>1000 Übungen“) können weder alle **Felder** (Ziele, Ablauf, Skills, Varianten …) noch alle **Zeilen** sinnvoll in einen LLM-Prompt. -**Festlegung:** Der LLM-Prompt erhält immer nur ein **begrenztes Kontext-Paket** mit: +**Abgrenzung Übungsanlage (aktueller Prioritätspfad):** Hier geht der Prompt typischerweise von **einzelnen** Freitexten (`title`, `goal`, `execution`, …) und einem **Skills-Katalog-Auszug** aus – nicht vom gesamten Übungsbestand. Trotzdem gilt: Aktive Skills **paginieren** oder **stufig** laden (Subset + zweite Runde nur für Kurzliste), keine vollständigen Romane aus `skill_level_definitions` für hunderte Fähigkeiten auf einmal. + +**Festlegung (Planungs-KI):** Der LLM-Prompt erhält immer nur ein **begrenztes Kontext-Paket** mit: | Paketteil | Zweck | |-----------|--------| @@ -69,7 +88,8 @@ Mindestens **eine** der folgenden Optionen – kombinierbar: 1. **Skill-/Facet-Overlap:** Punktezahl, wenn Übungs-Skills mit Ziel-/Matrix-Schwerpunkten übereinstimmen (bereits Daten in `exercise_skills`). 2. **Diversitäts-/Wiederholungsstrafe:** häufig in letzten Wochen geübte Übungen abwerten. 3. **Textsuche:** PostgreSQL **`tsvector`/Volltext** auf `title`, `summary`, ggf. gekürzte `goal` – für Trainer-Stichwort „Koordination Sprung“. -4. **Semantische Suche:** Embeddings + **Ähnlichkeitsuche** auf Kurztexte (siehe §5). +4. **Semantische Suche:** Embeddings + **Ähnlichkeitsuche** auf Kurztexte (siehe §5). +5. **Skill-Discovery über Planungs-Artefakte (bereits implementiert):** `GET /api/skill-discovery/suggestions` matching **Bibliotheksartefakte** (u. a. Rahmenprogramm, Trainingsmodul, Progressionsgraph) gegen gegebene `skill_ids`; `GET …/skill-profile` liefert **gewichtete Fähigkeitsprofile** aus den dort verknüpften Übungen (siehe `SKILL_SCORING_SPEC.md`). Das ist ein **deterministischer** Baustein für „welche Artefakte passen zu diesen Skills?“, **nicht** der Ersatz für **Top‑K-Übung**-Auswahl in einer konkreten Session – dort weiter Stufen 1–2 + Punkte 1–4/LLM. Ergebnis: sortierte Liste, **Top‑K** für den Prompt. @@ -128,7 +148,8 @@ Sinnvoller zeitlicher Punkt oder technische Auslöser: Retrieval‑Qualität hängt stärker an **Metadaten** als an der Embedding-Technologie allein: -- verlässliche **Skills** (`exercise_skills`, ggf. KI-geholfen bereits laut Spez beim Übungs-Anlegen); +- verlässliche **Skills** (`exercise_skills`, ggf. KI-geholfen bereits laut Spez beim Übungs-Anlegen); `exercise_skills.ai_suggested` und kanonische Stufen (`required_level` / `target_level` als Slugs) für Nachvollziehbarkeit. +- **`skills`-Stamm:** `description`, **`karate_relevance`**, **`relevance_level` (1–3)**, **`focus_areas`**, Kategorien/Keywords für **Prompt-Kontext** beim Skill-Mapping bei der Übungsanlage; optional **`skill_level_definitions`** für Stufen 1–5 **gezielt** in die zweite Prompt-Runde (nur Kurzliste Kandidaten). - sinnvolle **`summary`**-Felder für Karten/Liste/KI-Pack; - **Progressionsgraph** dort, wo pädagogische Ketten gefestigt sind; - konsistente **Fokusbereich/Stil**-Zuordnung. @@ -139,15 +160,18 @@ Das fachliche Konzept sollte entscheiden: **wie viel automatische Pflege vs. Tra ## 7. Produkt-/Release-Stufen (Anknüpfung) +Priorität **jetzt**: **Übungsanlage**, danach **Planung**. + | Stufe | Nutzen | Technik-Schwerpunkt | |-------|--------|---------------------| -| A | Backend-KI-Service + Prompt-Slugs unter `technical/AI_PROMPT_SYSTEM_SPEC.md` | OpenRouter, Timeouts, 503 ohne Key | -| B | „Übungen für Abschnitt vorschlagen“ | Pipeline §3 Stufen 1–3 + Prompt mit Top‑K | +| **A0** | **Zentraler KI-Service** (ein Modul/Hilfslayer), Prompts aus `ai_prompts` | OpenRouter oder vereinbarter Provider, Timeouts, `503` ohne Key, Parsing/Validation | +| **A1** | **Übungsanlage** (vgl. `KI_FEATURES_SPEC`): `summary`, Skill-Vorschläge inkl. Stufen/Intensität, optional Textglättung | `POST /api/exercises/ai/suggest`, `POST /api/exercises/{id}/ai/regenerate`; Prompt-Kontext: Skills mit `description`, `karate_relevance`, `relevance_level`, optional `skill_level_definitions` für Kurzliste; DB: `summary_ai_generated`, `exercise_skills.ai_suggested` | +| B | „Übungen für Abschnitt vorschlagen“ | Pipeline §3 Stufen 1–3 + Prompt mit Top‑K (Übungsliste **keyset-pagination** beachten) | | C | Reihenfolge / Zeitslots innerhalb bestehender Sektion | Graph + LLM Ranking | -| D | Ganze Einheit (inkl. Phasen/Streams vereinfacht) | strukturiertere JSON-Ausgabe, strikte Schema-Validation | -| E | Mehreinheiten / Rahmen‑Alignment | Ziele aus Rahmenprogramm, Serie von Slots | +| D | Ganze Einheit (inkl. Phasen/Streams vereinfacht) | strukturiertes JSON + strikte Schema-Validation gegen bestehende `PUT`-Payloads | +| E | Mehreinheiten / Rahmen‑Alignment | Ziele aus Rahmenprogramm, Serie von Slots; **Skill-Profile** (`…/skill-profile`) als Kontextuelle Verstärker | -Die **Selektions‑Pipeline §3 bleibt** über alle Stufen konsistent und wird nur parametrierbar erweitert. +Die **Selektions‑Pipeline §3** bleibt für **Planungs**-KI konsistent und wird parametrierbar erweitert; **§1.1** spiegelt den **aktuellen Implementierungs**-Vorsprung (Skill-Scoring ohne LLM) wider. --- diff --git a/.claude/docs/technical/EXERCISES_API_SPEC.md b/.claude/docs/technical/EXERCISES_API_SPEC.md index c99b779..29091f3 100644 --- a/.claude/docs/technical/EXERCISES_API_SPEC.md +++ b/.claude/docs/technical/EXERCISES_API_SPEC.md @@ -1,11 +1,12 @@ # Exercises API Specification -**Version:** 1.5 -**Datum:** 2026-05-08 +**Version:** 1.6 +**Datum:** 2026-05-20 **Status:** Teilweise implementiert (Liste mit Filtern + Varianten + Medienlimits + Progressionsgraphen siehe Code) **Autor:** Claude Code -**Änderungen v1.4:** Endpoints **`/exercise-progression-graphs`** inkl. Kanten, **`POST …/edges/sequence`**, **`POST …/edges/delete-batch`** — Detailtabellen siehe **`TRAINING_FRAMEWORK_SPEC.md`** §3.3 +**Änderungen v1.6:** Freigabelevel-UI-Hinweis; `exercise_skills` ohne `is_primary` in Requests (Legacy-Feld wird ignoriert/forciert false); Permissions-Bereich an Ist-Code angeglichen; Intensität kanonisch `niedrig|mittel|hoch` **Änderungen v1.5:** Medien-/Inline-Workflow aktualisiert (Modal-Picker, Drag&Drop UX im Frontend), Klarstellung zu `context` (legacy/optional), Hinweise zu Platzhaltern in Rich-Text-Feldern. +**Änderungen v1.4:** Endpoints **`/exercise-progression-graphs`** inkl. Kanten, **`POST …/edges/sequence`**, **`POST …/edges/delete-batch`** — Detailtabellen siehe **`TRAINING_FRAMEWORK_SPEC.md`** §3.3 **Änderungen v1.3:** `GET /exercises` erweiterte Query-Parameter (`include_variants`, Multi-Filter, `ai_search`-Platzhalter); Dokumentation angepasst **Änderungen v1.2:** KI-Assistenz Endpoints, Skill-Level-System (benannte Stufen), intensity als low/medium/high **Änderungen v1.1:** Exercise Blocks Endpoints, Permissions dokumentiert, age_groups korrigiert @@ -185,11 +186,11 @@ Lightweight-Liste; bei `include_variants=true` zusätzlich z. B.: "skill_id": 10, "skill_name": "Distanzgefühl", "skill_category": "Kumite", - "is_primary": true, "intensity": "hoch", "required_level": "grundlagen", "target_level": "aufbau", - "ai_suggested": false + "ai_suggested": false, + "is_primary": false } ], @@ -307,7 +308,6 @@ Lightweight-Liste; bei `include_variants=true` zusätzlich z. B.: "skills": [ { "skill_id": 10, - "is_primary": true, "intensity": "hoch", "required_level": "grundlagen", "target_level": "aufbau" @@ -578,7 +578,6 @@ Wird beim Klick auf „✨ KI-Vorschlag" im Formular aufgerufen. "required_level": "grundlagen", "target_level": "aufbau", "intensity": "hoch", - "is_primary": true, "confidence": 0.92 }, { @@ -588,7 +587,6 @@ Wird beim Klick auf „✨ KI-Vorschlag" im Formular aufgerufen. "required_level": "einsteiger", "target_level": "grundlagen", "intensity": "mittel", - "is_primary": false, "confidence": 0.74 } ] @@ -621,6 +619,38 @@ Trainer muss im Frontend aktiv übernehmen. ## Permissions +**UI-Hinweis:** Das Feld `visibility` heißt in der Oberfläche **Freigabelevel** (`exerciseGovernanceLabels.js`). + +### Lesen (`GET /exercises`, `GET /exercises/{id}`) + +| `visibility` | Wer darf lesen? | +|--------------|-----------------| +| `official` | Plattform-weit | +| `private` | Ersteller (`created_by`); Plattform-Admin | +| `club` | Aktive Mitglieder des Objekt-`club_id`; Plattform-Admin ohne Mitgliedschaft (Audit-Zugang) | + +Implementierung: `library_content_visible_to_profile` / `exercise_visible_to_profile` in `club_tenancy.py`. + +### Bearbeiten (`PUT`, Varianten-CRUD, Medien an Übung) + +| Bedingung | Wer darf bearbeiten? | +|-----------|----------------------| +| Ersteller | Immer (eigene Übung) | +| Plattform-Admin | Immer | +| `visibility=club` | Zusätzlich **`can_plan_in_club`** im Objekt-Verein: `club_admin`, `trainer`, `content_editor`, `division_lead` | + +Implementierung: `_assert_can_edit_exercise` in `exercises.py`. **Varianten** haben kein eigenes Owner-Feld — gleiche Prüfung wie Eltern-Übung. + +### Löschen (`DELETE /exercises/{id}`) + +| `visibility` | Wer darf löschen? | +|--------------|-------------------| +| `official` | Nur Plattform-Admin | +| `club` | Nur **`club_admin`** im Objekt-Verein | +| `private` | Ersteller; oder Vereins-Admin, der mit dem Ersteller einen gemeinsamen Verein teilt | + +Implementierung: `_assert_can_delete_exercise` in `exercises.py`. + ### Sichtbarkeits-Workflow | Von → Nach | Wer darf das? | @@ -638,11 +668,12 @@ Trainer muss im Frontend aktiv übernehmen. | `club → official` | Club-Admin, Super-Admin | | `official → club` | Super-Admin | -### Owner-Checks +### Owner-Checks (veraltet — siehe Tabellen oben) -- **Bearbeiten** (PUT): Nur Ersteller oder Club-Admin -- **Löschen** (DELETE): Nur Ersteller oder Super-Admin -- **Lesen** (`private`): Nur Ersteller +Die folgenden Kurzregeln sind durch die Ist-Implementierung ersetzt; nur zur historischen Einordnung: + +- ~~Bearbeiten (PUT): Nur Ersteller oder Club-Admin~~ → siehe **Bearbeiten**-Tabelle (`can_plan_in_club`) +- ~~Löschen (DELETE): Nur Ersteller oder Super-Admin~~ → siehe **Löschen**-Tabelle **403 Fehler-Beispiel:** ```json @@ -904,7 +935,8 @@ Trainer muss im Frontend aktiv übernehmen. ### Exercise Skills - `required_level`: enum – `einsteiger | grundlagen | aufbau | fortgeschritten | experte` (optional/nullable) - `target_level`: enum – gleiche Werte (optional/nullable) -- `intensity`: enum – `niedrig | mittel | hoch` (optional/nullable) +- `intensity`: enum – **`niedrig | mittel | hoch`** (optional/nullable; Default beim Speichern **`mittel`**) +- `is_primary`: **Legacy** — Spalte existiert in DB, wird bei POST/PUT **nicht ausgewertet** (immer `false` gespeichert); UI liefert/speichert kein Primär-Flag mehr; Scoring ignoriert das Feld - `target_level` sollte >= `required_level` sein (Warnung, kein Fehler) ### Exercise Block Item diff --git a/.claude/docs/technical/EXERCISES_ARCHITECTURE.md b/.claude/docs/technical/EXERCISES_ARCHITECTURE.md index 8ce3822..1ef2c9b 100644 --- a/.claude/docs/technical/EXERCISES_ARCHITECTURE.md +++ b/.claude/docs/technical/EXERCISES_ARCHITECTURE.md @@ -99,20 +99,21 @@ Exercise Block ──── (N) Block Items ──── (1) Exercise ### 1.3 M:N Beziehungen (Primary/Secondary Pattern) -**Regel:** Alle Katalog-Zuordnungen nutzen M:N mit `is_primary` Flag. +**Regel:** Katalog-Zuordnungen (Fokus, Stil, Zielgruppe, …) nutzen M:N mit optionalem `is_primary`-Flag. -**Betroffene Relationen:** +**Betroffene Relationen (mit `is_primary`):** - `exercise_focus_areas` (Übung ↔ Fokusbereiche) -- `exercise_styles` (Übung ↔ Trainingsstile) +- `exercise_styles` / `exercise_style_directions` (Übung ↔ Stilrichtungen) +- `exercise_training_types` (Übung ↔ Trainingsstile) - `exercise_target_groups` (Übung ↔ Zielgruppen) -- `exercise_training_characters` (Übung ↔ Trainingscharaktere) -- `exercise_skills` (Übung ↔ Fähigkeiten) -**Primary/Secondary Semantik:** +**Ausnahme — `exercise_skills`:** Kein Primär-Flag in UI/API mehr; stattdessen **`intensity`** (`niedrig` \| `mittel` \| `hoch`, Default `mittel`). Spalte `is_primary` bleibt Legacy (Backend speichert immer `false`). + +**Primary/Secondary Semantik (Katalog-Dimensionen):** - **Primary:** Hauptzuordnung, entscheidend für Filter/Suche - **Secondary:** Nebenzuordnung, zusätzlicher Kontext -- **Regel:** Genau EINE Primary-Zuordnung pro Dimension -- **UI:** Primary wird visuell hervorgehoben (z.B. fett, farbig) +- **Regel:** Genau EINE Primary-Zuordnung pro Dimension (wo UI das noch anbietet) +- **UI:** Primary wird visuell hervorgehoben (z. B. fett, farbig) — Fähigkeiten: Intensitäts-Segmente statt Primary **Legacy-Felder (DEPRECATED):** - `exercises.focus_area` → Ignorieren, nutze `exercise_focus_areas` diff --git a/.claude/docs/technical/EXERCISES_FRONTEND_ROUTING.md b/.claude/docs/technical/EXERCISES_FRONTEND_ROUTING.md index 9ef6f81..3af52ce 100644 --- a/.claude/docs/technical/EXERCISES_FRONTEND_ROUTING.md +++ b/.claude/docs/technical/EXERCISES_FRONTEND_ROUTING.md @@ -1,9 +1,10 @@ # Frontend Routing & Navigation Specification -**Version:** 1.2 -**Datum:** 2026-04-30 +**Version:** 1.3 +**Datum:** 2026-05-20 **Status:** DRAFT - Awaiting Review **Autor:** Claude Code +**Änderungen v1.3:** Übungsformular Tab-Navigation unter `/exercises/:id/edit` (Stammdaten … Medien & Mehr); Freigabelevel als UI-Begriff **Änderungen v1.2:** Übersicht **Übungen**: Tabs Liste \| Progressionsgraphen auf `/exercises`; Progressions-Editor ohne neue Routen (Panel + Formularblock unter `/exercises/:id/edit`) **Änderungen v1.1:** Übungsvarianten-Bearbeitung nur unter `/exercises/:id/edit` (keine VariantFormPage-Routen) @@ -17,7 +18,7 @@ /exercises → ExercisesListPage — Tabs: **Liste** \| **Progressionsgraphen** (`ExerciseProgressionGraphPanel`) /exercises/new → ExerciseFormPage (Create) /exercises/{id} → ExerciseDetailPage (Accordion-Layout) -/exercises/{id}/edit → ExerciseFormPage (Edit inkl. Varianten-Editor inline + Block Progressionsgraph) +/exercises/{id}/edit → ExerciseFormPage (Edit: Registerkarten + Varianten inline + Progressionsgraph) /exercise-blocks → ExerciseBlocksListPage (Meine Blocks) /exercise-blocks/new → ExerciseBlockFormPage (Create) @@ -35,6 +36,25 @@ - Pagination: `/exercises?limit=50&offset=100` - Sortierung: `/exercises?sort=created_at&order=desc` +### 1.2 Übungsformular – Registerkarten (`/exercises/new`, `/exercises/:id/edit`) + +**Implementierung:** `ExerciseFormPageRoot.jsx` + `ExerciseFormLayout.jsx` (`ExerciseFormTabBar`, `ExerciseFormPanel`). + +| Tab-ID | Label | Verfügbarkeit | +|--------|-------|---------------| +| `stammdaten` | Stammdaten | immer | +| `anleitung` | Anleitung | immer | +| `einordnung` | Einordnung | immer | +| `kombination` | Kombination | nur `exercise_kind=combination` | +| `varianten` | Varianten | Edit-Modus; nicht bei Kombination; disabled bei Neuanlage | +| `medien` | Medien & Mehr | Edit-Modus; disabled bei Neuanlage | + +**UX-Regeln:** +- Nur ein Panel sichtbar (`activeFormTab`); Navigation über `PageSectionNav`. +- **Freigabelevel** (Feld `visibility`) in Stammdaten — Konstante `EXERCISE_VISIBILITY_FIELD_LABEL`. +- Varianten-Änderungen werden mit **Speichern** in der Aktionsleiste persistiert (`persistPendingVariantChanges`); Button „Variante anlegen“ optional sofort. +- Kein URL-Hash pro Tab (Tab-State nur lokal). + --- ## 2. Navigation-Patterns @@ -673,7 +693,7 @@ function App() { --- -**Version:** 1.2 -**Letzte Änderung:** 2026-04-30 +**Version:** 1.3 +**Letzte Änderung:** 2026-05-20 **Status:** REVIEWED - Pending Implementation -**Review-Änderungen:** Progressionsgraphen-UI (Tabs, Formularblock); Exercise Blocks Routes + Navigation (früher) +**Review-Änderungen:** Formular-Registerkarten; Progressionsgraphen-UI (Tabs, Formularblock); Exercise Blocks Routes + Navigation (früher) diff --git a/.claude/docs/technical/KI_FEATURES_SPEC.md b/.claude/docs/technical/KI_FEATURES_SPEC.md index e3705c1..0ca3fb7 100644 --- a/.claude/docs/technical/KI_FEATURES_SPEC.md +++ b/.claude/docs/technical/KI_FEATURES_SPEC.md @@ -7,11 +7,16 @@ **Änderungen v1.1:** Prompts sind nicht hardcoded – sie werden aus der DB geladen (AI_PROMPT_SYSTEM_SPEC.md) **Verwandte Specs:** AI_PROMPT_SYSTEM_SPEC.md (Prompt-DB + Platzhalter), SKILLS_MATRIX_SPEC.md (Fähigkeitsmatrix) +**Übergeordnete Produkt-Vision** (breiter Scope: Zielausbau, bereichsweise vs. Gesamtüberarbeitung, Varianten, Planungs-/Nachbereitungskontext, Admin-Masse): +`functional/AI_EXERCISE_ASSISTANT_VISION.md` + --- ## 1. Übersicht -Zwei KI-gestützte Assistenzfunktionen beim Anlegen und Bearbeiten von Übungen: +KI-gestützte Assistenzfunktionen beim Anlegen und Bearbeiten von Übungen (Mindestpaket dieser Spec): + +**Hinweis:** Die beiden folgenden Zeilen entsprechen **P0** der Phasierung in **`AI_EXERCISE_ASSISTANT_VISION.md`**; spätere Funkteile sind dort beschrieben. | Funktion | Ziel | |---------|------| @@ -155,7 +160,38 @@ KI gibt Vorschläge Liefert KI-Vorschläge auf Basis von Eingabe-Text, **bevor** die Übung gespeichert wurde. Wird beim Klick auf „KI-Vorschlag" im Formular aufgerufen. -**Request Body:** +**Required Fields:** mindestens `goal` ODER `execution` + +**Optional – Skill-Katalogpriorisierung (Stand 068):** + +```json +{ + "focus_areas_context": [ + { "focus_area_id": 3, "is_primary": true }, + { "focus_area_id": 1, "is_primary": false } + ], + "focus_area_hint": "Karate, Kumite…" +} +``` + +- `focus_areas_context`: IDs aus Stammdatum **Fokusbereiche**; Primär soll zuerst stehen (`is_primary`). Ohne Feld oder leere Liste gilt das DB-Profil **`is_default`** (`ai_skill_retrieval_profiles`). +- `focus_area_hint`: bleibt lesbarer Text für den Prompt (bestehende Prompts). + + +**Minimal-Beispiel (Mit Fokus für Retrieval):** + +```json +{ + "title": "Maai - Distanzübung", + "goal": "…", + "execution": "…", + "focus_areas_context": [ { "focus_area_id": 1, "is_primary": true } ] +} +``` + + +**Minimal-Beispiel ( ohne Fokus — nur Texts):** + ```json { "title": "Maai - Distanzübung", @@ -164,8 +200,6 @@ Wird beim Klick auf „KI-Vorschlag" im Formular aufgerufen. } ``` -**Required Fields:** mindestens `goal` ODER `execution` (je länger, desto besser) - **Response:** `200 OK` ```json { @@ -182,7 +216,6 @@ Wird beim Klick auf „KI-Vorschlag" im Formular aufgerufen. "required_level": "grundlagen", "target_level": "aufbau", "intensity": "hoch", - "is_primary": true, "confidence": 0.92 }, { @@ -192,7 +225,6 @@ Wird beim Klick auf „KI-Vorschlag" im Formular aufgerufen. "required_level": "einsteiger", "target_level": "grundlagen", "intensity": "mittel", - "is_primary": false, "confidence": 0.74 } ] diff --git a/.claude/docs/working/ACCESS_LAYER_ENDPOINT_AUDIT.md b/.claude/docs/working/ACCESS_LAYER_ENDPOINT_AUDIT.md index 5bc6f55..1937e1d 100644 --- a/.claude/docs/working/ACCESS_LAYER_ENDPOINT_AUDIT.md +++ b/.claude/docs/working/ACCESS_LAYER_ENDPOINT_AUDIT.md @@ -13,6 +13,7 @@ Fortlaufend gemäß `ACCESS_LAYER_AND_GOVERNANCE_PLAN.md` Stufe A–C. | exercises | `PATCH /api/exercises/bulk-metadata` | ja | `get_tenant_context` | ja | Liste: UI-Mehrfachwahl; bis 500 IDs; nur Ersteller oder Plattform-Admin | | exercises | `GET .../media/{mid}/file` | ja | `get_tenant_context_flexible` | ja (wie Übung lesen) | Datei oder `?ssetoken`; kein anonymes `/media/` ohne ALLOW_PUBLIC_MEDIA_STATIC | | exercises | übrige geschützte `/api/exercises*` | ja | `get_tenant_context` | ja | PUT Einzelübung: bei Sichtbarkeit `official` Medien-§4.2 (422: Lifecycle/Promotion/Copyright) | +| exercises | POST `/api/exercises/ai/suggest`, POST `/api/exercises/{id}/ai/regenerate` | ja | `get_tenant_context` | nein | Nur Vorschlags-JSON; keine DB-Schreibung; OpenRouter — suggest optional `focus_areas_context` für Retrieval-Profile | | exercise_progression_graphs | `/api/exercise-progression-graphs*` | ja | `get_tenant_context` | Liste wie Bibliothek; Schreiben Ersteller/Plattform-Admin | Kanten: Lesen wenn Graph lesbar | | training_planning | alle geschützten Endpoints | ja | `get_tenant_context` | ja | Vorlagen-Liste wie Übungen; POST Vorlage Default club_id | | dashboard | `GET /api/dashboard/kpis` | ja | `get_tenant_context` | wie `GET /api/exercises` + `GET /api/training-units` | Aggregat für Dashboard-Kurzüberblick (ein Roundtrip) | @@ -33,17 +34,21 @@ Fortlaufend gemäß `ACCESS_LAYER_AND_GOVERNANCE_PLAN.md` Stufe A–C. | maturity_models | Admin-Matrix | nein (global) | `require_auth` | Admin für Schreiben; `GET …/{id}` nur Portal-Admin | EXEMPT | | matrix_stack_bundle | Export/Import Bundles | Plattform/Test | `require_auth` | Admin | EXEMPT | | import_wiki / import_wiki_admin | Wiki-Import | Werkzeug | `require_auth`/Admin | Admin | EXEMPT | +| ai_skill_retrieval_admin | `/api/admin/ai-skill-retrieval-profiles*` (CRUD) | Plattform | `require_auth` | nur `superadmin`; JSON `config` | EXEMPT wie `admin_users`; kein Vereinsbezug | **Legende:** Router auf der EXEMPT-Liste des Scripts sind globale oder Auth-only-Pfade; sobald ein Router Vereinsdaten oder Bibliotheks-Sichtbarkeit erhält, EXEMPT entfernen und `get_tenant_context` einführen. **Pflege / Drift:** Änderungen an Mandanten, Governance (`visibility`/`club_id`) oder neuen inhaltsbezogenen Endpoints → eine Zeile in dieser Tabelle anpassen und `PRODUCTION_READINESS_AUDIT_2026-05.md` prüfen. -Letzte Änderung: 2026-05-13 — `GET /api/dashboard/kpis` (Kurzüberblick-Aggregat). +Letzte Änderung: 2026-05-29 — Superadmin-CRUD `/api/admin/ai-skill-retrieval-profiles*` dokumentiert; `POST /api/exercises/ai/suggest` mit optionalem `focus_areas_context` (Migration 068). --- ### Changelog (Fortführung) +- **2026-05-29:** Superadmin-API `ai_skill_retrieval_admin` (Retrieval-Profile) dokumentiert. +- **2026-05-22:** Übungs-KI-Endpunkte (Suggest/Regenerate) dokumentiert. + - **2026-05-13:** Dashboard-KPI-Endpunkt dokumentiert. - **2026-05-07:** Legacy `GET/PUT /api/profile` auf Session-Profil gehärtet; OpenAPI/Health-Ready Produktionsdefaults; Security-Release-Tests + CI-Schritt `security_release_checks.py` — siehe `PRODUCTION_READINESS_AUDIT_2026-05.md`. - **2026-05-07 (Phase 3):** CSP SPA (nginx); API `nosniff`-Middleware — siehe `PRODUCTION_READINESS_AUDIT_2026-05.md`. diff --git a/.claude/docs/working/AI_EXERCISE_IMPLEMENTATION_PLAN.md b/.claude/docs/working/AI_EXERCISE_IMPLEMENTATION_PLAN.md new file mode 100644 index 0000000..1fbc161 --- /dev/null +++ b/.claude/docs/working/AI_EXERCISE_IMPLEMENTATION_PLAN.md @@ -0,0 +1,67 @@ +# 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 + +1. **Spec vor Code:** Request/Response-Felder und Statuscodes an `KI_FEATURES_SPEC.md` ausrichten; Abweichungen zuerst Spec oder dieses Dokument anpassen. +2. **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. +3. **Skill-Retrieval-Profile:** Gewichte/Quotes in **`ai_skill_retrieval_profiles.config`** — Spezifikation `working/AI_SKILL_RETRIEVAL_PROFILES_SPEC.md`; kein zweites gleichzeitiges Truth-Repo im Sourcecode außer defensiver Fallback `_FALLBACK_RETRIEVAL_CONFIG` in `exercise_ai.py`. +4. **Stufen-Slugs & Intensität:** Nur **kanonische** Werte wie in `exercises.py` (`basis` … `optimierung`, `niedrig|mittel|hoch`); LLM-Ausgaben **normalisieren**, ungültige `skill_id` verwerfen. +5. **Kein stiller DB-Write:** KI liefert **Vorschläge**; Persistenz nur über bestehende **PUT/POST exercises** inkl. Trainer-Aktion (und optional `summary_ai_generated` / `ai_suggested` wie Spec). +6. **Mandant:** Übungsbezogene KI-Endpunkte nutzen `Depends(get_tenant_context)`; keine Ausnahme ohne Eintrag in `ACCESS_LAYER_ENDPOINT_AUDIT.md`. +7. **Schema:** Neue DB-Objekte nur nummerierte Migration **`backend/migrations/`** (aktuell bis **068**) und `DB_SCHEMA_VERSION` anheben. + +--- + +## 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_MODEL` in `.env.example` dokumentiert (bereits teils vorhanden – prüfen). +- [ ] Fehlerbilder: `400` zu wenig Inhalt, `503` KI nicht konfiguriert, `502` Upstream-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`; suggest `focus_areas_context`; Frontend sendet gesetzte Fokusbereiche; Spec `working/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`. + diff --git a/.claude/docs/working/AI_PLANNING_KI_MULTISTAGE_FORECAST.md b/.claude/docs/working/AI_PLANNING_KI_MULTISTAGE_FORECAST.md new file mode 100644 index 0000000..a950e32 --- /dev/null +++ b/.claude/docs/working/AI_PLANNING_KI_MULTISTAGE_FORECAST.md @@ -0,0 +1,112 @@ +# Mehrstufige KI für Trainingsplanung – Architektur-Vorschau (Anti-Refactoring) + +**Version:** 0.1 +**Datum:** 2026-05-22 +**Status:** Planungs-/Architektur-Arbeitspapier (keine Implementierungspflicht) +**Ziel:** Für die **spätere** Planungs-KI bereits **Schnittstellen und Schichten** vorzeichnen, damit die **kleinere, starre** Übungs-KI nicht zur impliziten Vorlage für einen viel größeren Kopf wird — **ohne** jetzt eine Mitai-artige Workflow-Engine zu bauen. + +**Bezüge:** `technical/AI_TRAINING_PLANNING_CONCEPT.md` · `functional/AI_EXERCISE_ASSISTANT_VISION.md` · `technical/SKILL_SCORING_SPEC.md` · `functional/TRAINING_CURRICULUM_AND_GOVERNANCE_CONCEPT.md` (CURR-003) · Schwesterprojekt Mitai: `c:/dev/mitai-jinkendo` (Referenz: `prompt_executor`, `placeholder_resolver`, `workflow_*` — **nicht** Pflicht-Port). + +--- + +## 1. Zwei getrennte Produktlinien (bewusst entkoppelt) + +| Linie | Rolle | Orchestrator | +|--------|--------|----------------| +| **Übungs-KI** | wenige Eingaben → Kurzfassung / Skills; **starrer** Ablauf (1–2 Calls), kleines Kontextfenster | z. B. `exercise_ai.py` (heute) | +| **Planungs-KI** | Gruppe, Zeit, Ziele, Historie, Katalogausschnitt, Phasen/Streams → **strukturierte Planelemente** | **eigenes** Modul + **mehrstufig** (siehe §3) | + +**Regel:** Shared Library nur auf **niedriger Ebene** (`openrouter_chat`-Art: HTTP, Timeouts, Modellname, Fehler-Mapping) und **gemeinsame Prompt-Tabelle** `ai_prompts`. **Keine** Vermischung der Geschäftslogik „Übung erstellen“ mit „Einheit füllen“, um später keine Abhängigkeiten reißen zu müssen. + +--- + +## 2. Konzeptioneller „Planungs-Graph“ (Daten, nicht zwingend Graph-DB) + +Für die Planungs-KI ist ein **Graph als Denkmodell** hilfreich — technisch reicht meist **PostgreSQL + bestehende FKs** (+ optional `exercise_progression_graphs`): + +**Knoten-Typen (Auszug):** `training_groups`, `training_units`, `training_unit_sections` / Items, `exercises`, `skills`, `training_framework_programs` / Slots / Goals, ggf. Nachbearbeitungs-/Debrief-Metadaten. + +**Kanten-Typen (Auszug):** + +- **Zeitliche Folge:** Einheiten einer Gruppe nach `planned_date` / Reihenfolge +- **Inhalt:** Section-Item → `exercise_id` (± Variante) +- **Ziele:** Slot-/Framework-Ziele, Kopf-Notizen, Trainer-Zieltexte +- **Progression:** Kanten aus `exercise_progression_graphs` (optional erweitern um „empfohlene Folge im Gruppenkontext“, bleibt Spekulationsfeld) +- **Skills:** bereits über `exercise_skills`; aggregiert über `skill_scoring`-Pfad + +**Wichtig:** Für KI **nicht** einen Riesen-Graphen serialisieren, sondern **Projektionen** („letzte *N* Einheiten“, „Nachbarn im Progressionsgraph zu zuletzt verwendeten Übungen“, „Skill-Gap Heuristik“). + +--- + +## 3. Mehrstufiger Prozess (Pflichtidee für Planungs-KI) + +Statt einem Prompt „mach den ganzen Plan“ mehrere **Schritte mit kleinen, validierbaren Outputs**: + +| Stufe | Beispiel-Aufgabe | Deterministisch möglich? | Typischer LLM-Einsatz | +|-------|-------------------|--------------------------|------------------------| +| **S0** | Governance + Filter + Historie + Slot-Ziele zusammenstellen | Ja (SQL/API) | Nein | +| **S1** | Kandidaten-Übungen auf Top‑K schrumpfen (Skills, Volltext, Score, Wiederholungsstrafe) | Teilweise | Optional Ranking | +| **S2** | Reihenfolge je Section / Phase unter Constraints (Aufwärmen, Graphen-Nachbarn) | Teilweise | Ja (auf kleiner Liste) | +| **S3** | Zeiten auf Section/Item vorschlagen oder Plausibilisieren | Teilweise | Ja | +| **S4** | Trainer-sprachliche Kurzbegründung / Alternativen | Nein | Ja | + +**Zwischen jeder Stufe:** starkes **Schema / Validierung** (z. B. nur erlaubte `exercise_id`s, nur erlaubte Slot-Struktur zu Phasen/Streams). So bleibt das System auch bei Modell-Fehlern stabil. + +--- + +## 4. Schnittstellen-Vorsorge im Code (ohne Big-Bang) + +Minimal-Ausbaustufe später, die Refactoring vermeidet: + +1. **`PlanningContextPack` (internes DTO)** — reines Python-`dict`/`dataclass` oder Pydantic: aggregierte, **tokenbewusst gekürzte** Ansicht (Gruppe, nächste Einheit-Ziele, Historie-IDs, Top‑K-Kandidaten, Constraints). +2. **`planning_ai_steps` als rein **funktionale** Pipeline** — jede Stufe `(context) → context` oder `(context) → partial_suggestion`; keine globale „Prompt-String-Bastelei“ überall im Router. +3. **Prompt-Slugs pro Stufe** in `ai_prompts` (analog Übung), z. B. `planning_rank_section_items`, `planning_explain_sequence`, mit **eigenem** Platzhalter-Katalog (nicht `{{skills_catalog}}` aus Übungen recyclen). +4. **Router** `training_planning.py` (oder neuer `planning_ai.py`): nur **dünne** HTTP-Schicht, ruft Orchestrator. + +Optional **später**, wenn nötig: zweite Tabelle `ai_prompt_chains` oder externe Workflow-Definition — **erst** wenn 3–4 feste Stufen nicht mehr reichen. Mitai-Workflow-Engine dann **bewusste** Option, kein Default. + +--- + +## 5. Kontextfenster und „Kaskade“ + +**Kerngedanke:** Je Stufe nur **neue** Information hinzufügen, die vorherige Stufen **ersetzen** oder **verdichten**, nicht duplizieren. + +Beispiel: + +- Stufe A (LLM oder Heuristik): „Priorisierte Skill-Ziele für diese Session“ (kurz) +- Stufe B: Top‑40 Übungen mit **einer** Zeile pro Übung +- Stufe C: Reihenfolge für 8 IDs + 2-Satz-Begründung + +So bleibt dieselbe fachliche Tiefe erreichbar ohne Kontext-Explosion. + +--- + +## 6. Schnittstellen zu bereits vorhandenen Bausteinen + +- **`skill_profiles` / `skill-discovery`:** liefern **deterministische** Ziel-/Profil-Signale für S0/S1 (`SKILL_SCORING_SPEC.md`). +- **`training_planning_prefs`:** weiche Constraints (Tone, Dauer, Split-Vorlieben). +- **`exercise_progression_graphs`:** lokale Nachbarschaft um „zuletzt verwendet“. +- **Mitai-Referenz:** Platzhalter-Katalog + Preview-API als **Inspiration** für Admin-UX; Workflow-Graph nur wenn Shinkan **wirklich** viele verzweigte Pipelines braucht. + +--- + +## 7. Was wir **nicht** jetzt tun müssen + +- Keine zweite Graph-Datenbank nur für KI. +- Keine Workflow-UI-Kopie aus Mitai. +- Keine Vereinheitlichung der Übungs-KI mit Planungs-KI über einen „Mega-Orchestrator“. + +--- + +## 8. Kurz-Checkliste „Refactoring vermeiden“ vor erster Planungs-KI-Zeile Code + +- [ ] Eigenes Modulbaum-„Root“ für Planung (nicht `exercise_ai` erweitern). +- [ ] Prompt-Slugs mit **Planungs-**Präfix und **eigenem** Platzhalter-Set dokumentieren. +- [ ] Outputs pro Stufe **JSON-Schema** oder Pydantic validieren. +- [ ] Kandidatenlisten **immer** serverseitig auf erlaubte IDs begrenzen. + +--- + +## 9. Changelog + +- **2026-05-22:** Erstfassung als Vorschau-Dokument für mehrstufige Planungs-KI. diff --git a/.claude/docs/working/AI_SKILL_RETRIEVAL_PROFILES_SPEC.md b/.claude/docs/working/AI_SKILL_RETRIEVAL_PROFILES_SPEC.md new file mode 100644 index 0000000..bbe719a --- /dev/null +++ b/.claude/docs/working/AI_SKILL_RETRIEVAL_PROFILES_SPEC.md @@ -0,0 +1,121 @@ +# KI Skill-Retrieval-Profile (`ai_skill_retrieval_profiles`) + +**Version:** 0.1 +**Datum:** 2026-05-29 +**Status:** Umsetzung gestartet (Migration **068**) +**Ziel:** Für `POST /api/exercises/ai/suggest` (Skill-Katalogauszug) **Gewichte und Quoten** steuerbar machen: + +- gebunden an **Übungs-Fokusbereich** (`focus_areas.id`), +- ein **Standardprofil** ohne Fokus, +- **optional zusammengeführte** Profile bei mehreren Fokusbereichen, +- **optional Keyword-Übersteuerungen** aus Ziel/Durchführung (z. B. Rollenspiel vs. Befreiung). + +**Technische Basis:** Skills mit `skills.main_category_id` → `skill_main_categories.slug` (`karate` | `allgemeine`) und `skills.category_id` → `skill_categories.slug` (`kondition`, `selbstverteidigung`, …). + +**Bezüge:** `.claude/docs/working/AI_EXERCISE_IMPLEMENTATION_PLAN.md` · `backend/exercise_ai.py` + +--- + +## 1. Datenmodell + +### Tabelle `ai_skill_retrieval_profiles` + +| Spalte | Typ | Beschreibung | +|--------|-----|--------------| +| `id` | serial | Primärschlüssel | +| `focus_area_id` | int NULL FK → `focus_areas(id)` ON DELETE SET NULL | **`NULL`** nur für Standardeintrag möglich (siehe `is_default`) | +| `is_default` | boolean | Genau **eine** Zeile mit `true` | +| `name` | varchar | Kurzer Name (Admin später) | +| `description` | text | Hinweise für Pflege | +| `active` | boolean | Nur aktive werden geladen | +| `config` | jsonb | Siehe §2 | + +**Constraints / Indizes** + +- Eindeutig: `(focus_area_id)` WHERE `focus_area_id IS NOT NULL` +- Eindeutig: `(is_default)` WHERE `is_default = true` + +--- + +## 2. JSON-Konfiguration `config.version = 1` + +Alle Schlüssel **optional**; fehlende Werte fallen auf **einprogrammierten Fallback** in `exercise_ai.py` zurück (entspricht bisher grob „neutral“). + +### 2.1 Gewichtungen (Ranking) + +| Schlüssel | Typ | Bedeutung | +|-----------|-----|------------| +| `main_slug_weights` | `object[str, float]` | Multiplikator pro Hauptkategorie-Slug (`karate`, `allgemeine`) | +| `category_slug_weights` | `object[str, float]` | Multiplikator pro `skill_categories.slug` | + +Basis-Score (vereinfacht): +`(importance oder 3) × main_w × cat_w × text_overlap_bonus × importance_multiplier` + +### 2.2 Kapazitätsbegrenzung (Liste) + +`_MAX_SKILLS_CATALOG_LINES` (aktuell **240**) Zeilen Gesamt: + +| Schlüssel | Typ | Bedeutung | +|-----------|-----|------------| +| `category_max_share` | `object[str, float]` | Max. Anteil dieser **Unterkategorie** am Endergebnis (0–1), z. B. `{ "kondition": 0.25 }` | +| `main_min_share` | `object[str, float]` | Mindest-Zielanteil Hauptkategorie beim **Auswahl-Greedy** (weich; Rest nach Score aufgefüllt) | + +### 2.3 Text / Token-Sparen + +| Schlüssel | Typ | Standard | Bedeutung | +|-----------|-----|----------|------------| +| `description_plain_max_len` | int | 160 | Gekürzte Beschreibung pro Zeile | +| `karate_relevance_max_len` | int | **0** oder 80 | **`0`** = Feld `karate_relevance`/`relevance_level` in der Promptzeile **weglassen** | + +### 2.4 Keyword-Overrides (optional) + +Liste `keyword_overrides`: jedes Element: + +```json +{ + "keywords_any": ["befreiung", "haltegriff"], + "case_insensitive": true, + "patch": { + "category_slug_weights": { "selbstverteidigung": 2.5 }, + "category_max_share": { "koordination": 0.1 } + } +} +``` + +Textsuche in verkettetem Korpus **Titel, Ziel, Durchführung, Focus-Hint** (bereits plaintext). Reihenfolge: erst Basis-Profile zusammenmergen, dann **alle treffenden Overrides**‑`patch`‑Objekte **flach zusammenführen** (Gewichte multiplikativ übereinander, Caps den strengsten Wert nehmen – aktuelle Implementierung im Code dokumentiert). + +--- + +## 3. Mehrere Fokusbereiche auf der Übung + +Request-Body: `focus_areas_context: [{ "focus_area_id": n, "is_primary": bool }, …]` + +**Aktuelle Merge-Strategie (v1):** Profile laden → **gleichgewichtete Mittelwert-Bildung** der numerischen Gewichte / Caps (implementiert für `main_slug_weights`, `category_slug_weights`, `category_max_share`, `main_min_share`, `*_max_len`). Anschließend **Keyword-Overrides** anwenden. + +**Primär-Fokus:** Im Frontend soll die **primäre** Zeile aus `focus_areas_multi` **zuerst** in der Liste stehen; die Merge-Strategie kann später zu „Primär dominate“ erweitert werden. + +Ohne Kontext oder ohne Treffer auf aktive Profile: **nur Standardprofil** (`is_default`). + +--- + +## 4. Seed-Daten (Migration) + +- **`is_default=true`:** ausgewogene Standard-Gewichte, moderate Caps auf `kondition`/`koordination`, Karate-Relevanz gekürzt. +- **`Gewaltschutz`:** `focus_area_id` per `(SELECT id FROM focus_areas WHERE name = 'Gewaltschutz' LIMIT 1)` — höhere Gewichte für `kognition`, `psychische_faehigkeiten`, `soziale_faehigkeiten`, `selbstverteidigung`; gedrosseltes `kondition`/`koordination`; `karate_relevance_max_len`: 0; Keyword-Patches wie oben können nachgeschärft werden. + +Weitere Profile (Karate-Schwerpunkt etc.) später per Admin-SQL oder UI. + +--- + +## 5. API + +`ExerciseAiSuggestBody` erweitert um **`focus_areas_context`** (Liste). Feld **`focus_area_hint`** bleibt für den **Prompt-Kontext** (bestehende Prompts). + +`POST …/ai/regenerate` nutzt gespeicherte `exercise_focus_areas` zur gleichen Retrieval-Logik wie Suggest. + +**Pflege der Profile:** Superadmin ohne Mandantenwahl — **`GET|POST /api/admin/ai-skill-retrieval-profiles`**, **`GET|PUT|DELETE /api/admin/ai-skill-retrieval-profiles/{id}`** (`routers/ai_skill_retrieval_admin.py`); Web-UI Superadmin unter **`/admin/ai-skill-retrieval`**. + +## 6. Changelog + +- **2026-05-29:** Superadmin-Pflege-Endpoints + UI‑Route dokumentiert (`/admin/ai-skill-retrieval`). +- **2026-05-29:** Erstellt; gekoppelt an Migration **068** und erste `exercise_ai`-Integration. diff --git a/.env.example b/.env.example index 3c704b2..91f9c07 100644 --- a/.env.example +++ b/.env.example @@ -35,6 +35,10 @@ DB_PASSWORD=CHANGE_ME_SECURE_PASSWORD OPENROUTER_API_KEY=your_api_key_here OPENROUTER_MODEL=anthropic/claude-sonnet-4 +# Übungs-KI (Docker): ohne Eintrag im compose „environment:“ landet keine .env-Zeile im Container. +# Hier ist SHINKAN_AI_DEBUG in docker-compose*.yml angebunden — 1 = ausführliche WARN-Logs (exercise_ai, openrouter). +# SHINKAN_AI_DEBUG=1 + SMTP_HOST=smtp.example.com SMTP_PORT=587 SMTP_USER=noreply@jinkendo.de diff --git a/backend/db.py b/backend/db.py index 0b07348..76f2101 100644 --- a/backend/db.py +++ b/backend/db.py @@ -180,12 +180,17 @@ def init_db(): cur.execute("SELECT COUNT(*) as count FROM ai_prompts WHERE slug='pipeline'") if cur.fetchone()['count'] == 0: cur.execute(""" - INSERT INTO ai_prompts (slug, name, description, template, active, sort_order) + INSERT INTO ai_prompts ( + slug, display_name, description, template, + category, output_format, active, sort_order + ) VALUES ( 'pipeline', 'Mehrstufige Gesamtanalyse', - 'Master-Schalter für die gesamte Pipeline. Deaktiviere diese Analyse, um die Pipeline komplett zu verstecken.', + 'Master-Schalter fuer die gesamte Pipeline. Deaktiviere diese Zeile um die Pipeline zu verstecken.', 'PIPELINE_MASTER', + 'admin', + 'text', true, -10 ) diff --git a/backend/exercise_ai.py b/backend/exercise_ai.py new file mode 100644 index 0000000..bf7d714 --- /dev/null +++ b/backend/exercise_ai.py @@ -0,0 +1,813 @@ +""" +KI-Vorschlaege fuer Uebungsformular: Laedt Prompts aus ai_prompts, ruft OpenRouter auf. +Keine persistente Aenderung an exercises — nur Response-DTO fuer das Frontend. + +Skill-Katalog fuer Prompts: priorisierte Auswahl (ai_skill_retrieval_profiles, Fallback-Heuristik). +""" +from __future__ import annotations + +import copy +import json +import logging +import math +import os +import re +from typing import Any, Dict, List, Mapping, MutableMapping, Optional, Sequence, Tuple + +from fastapi import HTTPException + +from openrouter_chat import OpenRouterError, normalize_openrouter_env, openrouter_chat_completion + +_LOGGER = logging.getLogger("shinkan.exercise_ai") + + +def _ai_debug_on() -> bool: + return os.getenv("SHINKAN_AI_DEBUG", "").strip().lower() in ("1", "true", "yes", "full") + + +_CANONICAL_SKILL_LEVELS = frozenset({"basis", "grundlagen", "aufbau", "fortgeschritten", "optimierung"}) +_LEGACY_SKILL_LEVEL_SLUG = { + "einsteiger": "basis", + "experte": "optimierung", + "1": "basis", + "2": "grundlagen", + "3": "aufbau", + "4": "fortgeschritten", + "5": "optimierung", +} +_ALLOWED_SKILL_INTENSITY = frozenset({"niedrig", "mittel", "hoch"}) + +_TAG_RE = re.compile(r"<[^>]+>", re.IGNORECASE) +_TOKEN_FIND = re.compile(r"[a-zäöüß0-9]+", re.IGNORECASE) + +_MAX_PLAIN_FIELD = 28_000 +_MAX_SKILLS_CATALOG_LINES = 240 +_MAX_SUMMARY_CHARS = 220 +_MAX_SANITIZE_SKILL_INPUT_ROWS = 250 + +_FALLBACK_RETRIEVAL_CONFIG: Dict[str, Any] = { + "version": 1, + "importance_multiplier": 1.0, + "text_overlap_bonus": 2.0, + "main_slug_weights": {"karate": 1.0, "allgemeine": 1.0}, + "category_slug_weights": {}, + "category_max_share": {"kondition": 0.38, "koordination": 0.35}, + "main_min_share": {}, + "description_plain_max_len": 160, + "karate_relevance_max_len": 72, + "keyword_overrides": [], +} + + +def _normalize_exercise_skill_level(value) -> Optional[str]: + if value is None: + return None + s = str(value).strip().lower() + if not s: + return None + if s in _CANONICAL_SKILL_LEVELS: + return s + return _LEGACY_SKILL_LEVEL_SLUG.get(s) + + +def _normalize_exercise_skill_intensity(value) -> str: + if value is None: + return "mittel" + key = str(value).strip().lower() + if key in ("low",): + return "niedrig" + if key in ("medium",): + return "mittel" + if key in ("high",): + return "hoch" + if key in _ALLOWED_SKILL_INTENSITY: + return key + return "mittel" + + +def strip_html_to_plain(html: Optional[str], *, max_len: int = _MAX_PLAIN_FIELD) -> str: + if not html: + return "" + t = _TAG_RE.sub(" ", str(html)) + t = re.sub(r"\s+", " ", t).strip() + if len(t) > max_len: + t = t[: max_len - 1].rstrip() + "…" + return t + + +def _corpus_tokens(*parts: str) -> frozenset: + hay = " ".join(p.strip() for p in parts if p and p.strip()) + ws = {_m.group(0).lower() for _m in _TOKEN_FIND.finditer(hay)} + return frozenset(w for w in ws if len(w) > 1) + + +def _ai_profiles_table_ready(cur) -> bool: + cur.execute("SELECT to_regclass(%s)::text AS t", ("public.ai_skill_retrieval_profiles",)) + row = cur.fetchone() + if row is None: + return False + val = row["t"] if isinstance(row, dict) else row[0] + return val is not None and str(val).strip() != "" + + +def _average_float_dict(dicts: Sequence[Mapping[str, Any]], *, fallback: float) -> Dict[str, float]: + keys: set = set() + for d in dicts: + keys |= set(d.keys()) + out: Dict[str, float] = {} + for k in keys: + vals = [] + for d in dicts: + if k not in d or d[k] is None: + continue + try: + vals.append(float(d[k])) + except (TypeError, ValueError): + continue + out[k] = (sum(vals) / len(vals)) if vals else fallback + return out + + +def _merge_retrieval_configs(configs: Sequence[Dict[str, Any]]) -> Dict[str, Any]: + base = copy.deepcopy(_FALLBACK_RETRIEVAL_CONFIG) + if not configs: + return base + + base["main_slug_weights"] = _average_float_dict( + [c.get("main_slug_weights") or {} for c in configs], + fallback=1.0, + ) + for slug in ("karate", "allgemeine"): + base["main_slug_weights"].setdefault(slug, 1.0) + + base["category_slug_weights"] = _average_float_dict( + [c.get("category_slug_weights") or {} for c in configs], + fallback=1.0, + ) + base["category_max_share"] = _average_float_dict( + [c.get("category_max_share") or {} for c in configs], + fallback=1.0, + ) + base["main_min_share"] = _average_float_dict( + [c.get("main_min_share") or {} for c in configs], + fallback=0.0, + ) + + ims = [] + tbs = [] + dmx = [] + krm = [] + for c in configs: + try: + if c.get("importance_multiplier") is not None: + ims.append(float(c["importance_multiplier"])) + except (TypeError, ValueError): + continue + try: + if c.get("text_overlap_bonus") is not None: + tbs.append(float(c["text_overlap_bonus"])) + except (TypeError, ValueError): + continue + try: + if c.get("description_plain_max_len") is not None: + dmx.append(int(c["description_plain_max_len"])) + except (TypeError, ValueError): + continue + try: + if c.get("karate_relevance_max_len") is not None: + krm.append(int(c["karate_relevance_max_len"])) + except (TypeError, ValueError): + continue + if ims: + base["importance_multiplier"] = sum(ims) / len(ims) + if tbs: + base["text_overlap_bonus"] = sum(tbs) / len(tbs) + if dmx: + base["description_plain_max_len"] = int(round(sum(dmx) / len(dmx))) + if krm: + base["karate_relevance_max_len"] = int(round(sum(krm) / len(krm))) + + overrides: List[Any] = [] + for c in configs: + overrides.extend(c.get("keyword_overrides") or []) + base["keyword_overrides"] = overrides + return base + + +def _mul_weight_dict(target: MutableMapping[str, float], patch: Mapping[str, Any]) -> None: + for k, v in patch.items(): + try: + mul = float(v) + except (TypeError, ValueError): + continue + target[k] = float(target.get(k, 1.0)) * mul + + +def _apply_keyword_overrides(cfg: Dict[str, Any], corpus_lower: str) -> None: + caps = cfg.setdefault("category_max_share", {}) + for ov in cfg.get("keyword_overrides") or []: + keys_any = ov.get("keywords_any") or [] + if not keys_any or not corpus_lower.strip(): + continue + hay = corpus_lower.lower() if corpus_lower else "" + hit = False + for kw in keys_any: + ks = str(kw or "").strip() + if not ks: + continue + ks_l = ks.lower() + hit = ks_l in hay + if hit: + break + if not hit: + continue + patch = ov.get("patch") or {} + _mul_weight_dict(cfg.setdefault("category_slug_weights", {}), patch.get("category_slug_weights") or {}) + _mul_weight_dict(cfg.setdefault("main_slug_weights", {}), patch.get("main_slug_weights") or {}) + for slug, mx in (patch.get("category_max_share") or {}).items(): + try: + mx_f = float(mx) + except (TypeError, ValueError): + continue + cur = float(caps.get(slug, 1.0)) + caps[slug] = min(cur, mx_f) + + +def _ordered_focus_ids(focus_ctx: Optional[Sequence[Tuple[int, bool]]]) -> List[int]: + """Primär zuerst, dann stabil nach ID.""" + if not focus_ctx: + return [] + seen = set() + ordered: List[Tuple[int, bool]] = [] + for fid, isp in sorted(focus_ctx, key=lambda x: (not x[1], x[0])): + try: + i = int(fid) + except (TypeError, ValueError): + continue + if i < 1 or i in seen: + continue + seen.add(i) + ordered.append((i, bool(isp))) + return [fid for fid, _ in ordered] + + +def _load_merged_retrieval_config( + cur, focus_ctx: Optional[Sequence[Tuple[int, bool]]] +) -> Dict[str, Any]: + if not _ai_profiles_table_ready(cur): + return copy.deepcopy(_FALLBACK_RETRIEVAL_CONFIG) + + loaded: List[Dict[str, Any]] = [] + for fid in _ordered_focus_ids(focus_ctx): + cur.execute( + """ + SELECT config + FROM ai_skill_retrieval_profiles + WHERE active = true AND focus_area_id = %s + LIMIT 1 + """, + (fid,), + ) + rw = cur.fetchone() + if not rw: + continue + raw = rw["config"] if isinstance(rw, dict) else rw[0] + if isinstance(raw, str): + try: + raw = json.loads(raw) + except json.JSONDecodeError: + continue + if isinstance(raw, dict): + loaded.append(raw) + + if not loaded: + cur.execute( + """ + SELECT config + FROM ai_skill_retrieval_profiles + WHERE active = true AND is_default = true + LIMIT 1 + """ + ) + rw = cur.fetchone() + if rw: + raw = rw["config"] if isinstance(rw, dict) else rw[0] + if isinstance(raw, str): + try: + raw = json.loads(raw) + except json.JSONDecodeError: + raw = None + if isinstance(raw, dict): + loaded.append(raw) + + return _merge_retrieval_configs(loaded) + + +def _fetch_all_active_skills_for_catalog(cur) -> List[Dict[str, Any]]: + cur.execute( + """ + SELECT s.id, + s.name, + s.category, + s.description, + s.karate_relevance, + s.relevance_level, + s.importance, + COALESCE(m.slug, '') AS main_slug, + COALESCE(c.slug, '') AS category_slug, + c.name AS subcategory_name + FROM skills s + LEFT JOIN skill_main_categories m ON m.id = s.main_category_id + LEFT JOIN skill_categories c ON c.id = s.category_id + WHERE (s.status IS NULL OR s.status = 'active') + """ + ) + return [dict(r) for r in cur.fetchall()] + + +def _score_skill_row( + row: Mapping[str, Any], + cfg: Mapping[str, Any], + corpus_tokens: frozenset, +) -> float: + main_slug = str(row.get("main_slug") or "").strip().lower() + cat_slug = str(row.get("category_slug") or "").strip().lower() + main_w = float((cfg.get("main_slug_weights") or {}).get(main_slug, 1.0)) + cat_w = float((cfg.get("category_slug_weights") or {}).get(cat_slug, 1.0)) + try: + imp = int(row["importance"]) if row.get("importance") is not None else 3 + except (TypeError, ValueError): + imp = 3 + imp = max(1, min(5, imp)) + imp_mult = float(cfg.get("importance_multiplier") or 1.0) + base = float(imp) * imp_mult * max(main_w, 0.05) * max(cat_w, 0.05) + + name = strip_html_to_plain(row.get("name"), max_len=400) + dsc = strip_html_to_plain(row.get("description"), max_len=520) + search_blob = " ".join( + [ + name, + dsc, + cat_slug.replace("_", " "), + str(row.get("category") or ""), + str(row.get("subcategory_name") or ""), + ] + ).lower() + + overlaps = sum(1 for t in corpus_tokens if t and t in search_blob) + tob = float(cfg.get("text_overlap_bonus") or 0.0) + + return base + overlaps * tob + + +def _category_cap_limits(cfg: Mapping[str, Any], n_max: int) -> Dict[str, int]: + out: Dict[str, int] = {} + mx = cfg.get("category_max_share") or {} + if not isinstance(mx, dict): + return out + for slug, raw in mx.items(): + ks = str(slug or "").strip() + if not ks: + continue + try: + sh = float(raw) + except (TypeError, ValueError): + continue + if 0 < sh < 1.0: + out[ks] = max(1, int(math.floor(sh * n_max))) + elif sh >= 1.0: + out[ks] = n_max + 99999 + else: + continue + return out + + +def _pick_catalog_rows(rows_scored: List[Tuple[float, Dict[str, Any]]], cfg: Mapping[str, Any]) -> List[Dict[str, Any]]: + """rows_scored: (score, row_dict) ohne Sortierung-Anforderung.""" + cap_limits = _category_cap_limits(cfg, _MAX_SKILLS_CATALOG_LINES) + ordered = sorted(rows_scored, key=lambda x: (-x[0], str(x[1].get("name") or ""))) + picked: List[Dict[str, Any]] = [] + picked_ids: set = set() + cat_counts: Dict[str, int] = {} + + def under_cap(cat_slug: str) -> bool: + if not cat_slug or cat_slug not in cap_limits: + return True + return cat_counts.get(cat_slug, 0) < cap_limits[cat_slug] + + # Pass 1: Cap respektieren + for _sc, rw in ordered: + if len(picked) >= _MAX_SKILLS_CATALOG_LINES: + break + sid = rw["id"] + if sid in picked_ids: + continue + cslug = str(rw.get("category_slug") or "").strip().lower() + if cslug and not under_cap(cslug): + continue + picked.append(rw) + picked_ids.add(sid) + if cslug: + cat_counts[cslug] = cat_counts.get(cslug, 0) + 1 + + # Pass 2: auffüllen + if len(picked) < _MAX_SKILLS_CATALOG_LINES: + for _sc, rw in ordered: + if len(picked) >= _MAX_SKILLS_CATALOG_LINES: + break + sid = rw["id"] + if sid in picked_ids: + continue + picked.append(rw) + picked_ids.add(sid) + + return picked[:_MAX_SKILLS_CATALOG_LINES] + + +def _format_skill_catalog_line(row: Mapping[str, Any], cfg: Mapping[str, Any]) -> str: + rid = int(row["id"]) + nm = (row.get("name") or "").strip() or f"Skill #{rid}" + cat_legacy = str(row.get("category") or "").strip() + sub = str(row.get("subcategory_name") or "").strip() + main_slug = str(row.get("main_slug") or "").strip() + cats = " / ".join(x for x in (main_slug.upper() if main_slug else "", cat_legacy, sub) if x) + + dmax = int(cfg.get("description_plain_max_len") or 160) + dsc = strip_html_to_plain(row.get("description"), max_len=max(40, min(400, dmax))) + + krmax = int(cfg.get("karate_relevance_max_len") or 0) + kr = strip_html_to_plain(row.get("karate_relevance"), max_len=min(280, krmax)) if krmax > 0 else "" + rel = row.get("relevance_level") + rel_s = str(rel).strip() if rel is not None else "" + + parts = [ + f"- id={rid} | name={nm}", + f" | kategorie={cats or '-'}", + f" | beschreibung={dsc or '-'}", + ] + if krmax > 0 and (kr.strip() or rel_s): + parts.append(f" | karate_relevanz={kr or '-'} | relevanz_stufe={rel_s or '-'}") + return "".join(parts) + + +def _safe_int_importance(value: Any) -> int: + try: + iv = int(value) + except (TypeError, ValueError): + return 0 + return max(1, min(5, iv)) if iv else 0 + + +def build_contextual_skills_catalog_block( + cur, + *, + title: Optional[str], + goal_plain: str, + execution_plain: str, + focus_hint: Optional[str], + focus_ctx: Optional[Sequence[Tuple[int, bool]]], +) -> str: + cfg = _load_merged_retrieval_config(cur, focus_ctx) + corpus_lower = " ".join([title or "", goal_plain or "", execution_plain or "", focus_hint or ""]).lower() + _apply_keyword_overrides(cfg, corpus_lower) + + tok = _corpus_tokens(title or "", goal_plain, execution_plain, focus_hint or "") + skill_rows = _fetch_all_active_skills_for_catalog(cur) + scored: List[Tuple[float, Dict[str, Any]]] = [] + for r in skill_rows: + scored.append((_score_skill_row(r, cfg, tok), r)) + picked = _pick_catalog_rows(scored, cfg) + picked.sort( + key=lambda r: ( + -_safe_int_importance(r.get("importance")), + str(r.get("name") or "").lower(), + ) + ) + + lines = [_format_skill_catalog_line(row, cfg) for row in picked] + return "\n".join(lines) if lines else "(keine aktiven Skills im Katalog)" + + +def _load_prompt_row(cur, slug: str) -> Optional[Dict[str, Any]]: + cur.execute( + """ + SELECT slug, display_name, template, output_format, active + FROM ai_prompts + WHERE slug = %s + """, + (slug,), + ) + row = cur.fetchone() + if not row: + return None + d = dict(row) + if not d.get("active", True): + return None + return d + + +def _render_template(template: str, ctx: Dict[str, str]) -> str: + out = template or "" + for key, val in ctx.items(): + placeholder = "{{" + key + "}}" + out = out.replace(placeholder, val if val is not None else "") + return out + + +def _first_balanced_json_array(text: str) -> Optional[str]: + """Findet das erste vollständig geschlossene Top-Level-JSON-Array in beliebigem Fließtext.""" + i = text.find("[") + if i < 0: + return None + depth = 0 + in_str = False + esc = False + for j in range(i, len(text)): + ch = text[j] + if in_str: + if esc: + esc = False + elif ch == "\\": + esc = True + elif ch == '"': + in_str = False + continue + if ch == '"': + in_str = True + continue + if ch == "[": + depth += 1 + elif ch == "]": + depth -= 1 + if depth == 0: + return text[i : j + 1] + return None + + +def _extract_json_array(text: str) -> Any: + s = text.strip() + if s.startswith("```"): + s = re.sub(r"^```[a-zA-Z0-9]*\s*", "", s) + if s.endswith("```"): + s = s[:-3].strip() + if s.startswith("["): + end = s.rfind("]") + if end > 0: + s = s[: end + 1] + parsed = json.loads(s) + if isinstance(parsed, list) and len(parsed) > _MAX_SANITIZE_SKILL_INPUT_ROWS: + parsed = parsed[:_MAX_SANITIZE_SKILL_INPUT_ROWS] + return parsed + if s.startswith("{"): + obj = json.loads(s) + if isinstance(obj, dict): + for k in ("skills", "items", "data"): + v = obj.get(k) + if isinstance(v, list): + if len(v) > _MAX_SANITIZE_SKILL_INPUT_ROWS: + return v[:_MAX_SANITIZE_SKILL_INPUT_ROWS] + return v + raise ValueError("JSON-Objekt ohne Skills-Liste") + parsed_end = json.loads(s) + if isinstance(parsed_end, list) and len(parsed_end) > _MAX_SANITIZE_SKILL_INPUT_ROWS: + return parsed_end[:_MAX_SANITIZE_SKILL_INPUT_ROWS] + return parsed_end + + +def _sanitize_skill_entries(cur, rows: Any) -> List[Dict[str, Any]]: + if not isinstance(rows, list): + return [] + out: List[Dict[str, Any]] = [] + cap = rows[:_MAX_SANITIZE_SKILL_INPUT_ROWS] + for raw in cap: + if len(out) >= 5: + break + if not isinstance(raw, dict): + continue + sid = raw.get("skill_id") + try: + skill_id = int(sid) + except (TypeError, ValueError): + continue + cur.execute( + """ + SELECT s.id, s.name, s.category, + sc.name AS subcategory_name + FROM skills s + LEFT JOIN skill_categories sc ON s.category_id = sc.id + WHERE s.id = %s AND (s.status IS NULL OR s.status = 'active') + """, + (skill_id,), + ) + sk = cur.fetchone() + if not sk: + continue + + req = _normalize_exercise_skill_level(raw.get("required_level")) or "grundlagen" + tgt = _normalize_exercise_skill_level(raw.get("target_level")) or req + if req not in _CANONICAL_SKILL_LEVELS: + req = _LEGACY_SKILL_LEVEL_SLUG.get(str(raw.get("required_level") or "").strip().lower(), "grundlagen") + if req not in _CANONICAL_SKILL_LEVELS: + req = "grundlagen" + if tgt not in _CANONICAL_SKILL_LEVELS: + tgt = _LEGACY_SKILL_LEVEL_SLUG.get(str(raw.get("target_level") or "").strip().lower(), req) + if tgt not in _CANONICAL_SKILL_LEVELS: + tgt = req + + inten = _normalize_exercise_skill_intensity(raw.get("intensity")) + + is_primary = bool(raw.get("is_primary")) if raw.get("is_primary") is not None else len(out) == 0 + + cat = (sk.get("category") or "").strip() + sub = (sk.get("subcategory_name") or "").strip() + skill_category = " / ".join(x for x in (cat, sub) if x) or (cat or None) + + conf = raw.get("confidence") + try: + conf_f = float(conf) if conf is not None else None + except (TypeError, ValueError): + conf_f = None + + item: Dict[str, Any] = { + "skill_id": skill_id, + "skill_name": (sk.get("name") or "").strip() or f"Skill #{skill_id}", + "required_level": req, + "target_level": tgt, + "intensity": inten, + "is_primary": is_primary, + } + if skill_category: + item["skill_category"] = skill_category + if conf_f is not None: + item["confidence"] = conf_f + out.append(item) + + return out[:5] + + +def _require_openrouter() -> Tuple[str, str]: + key, model = normalize_openrouter_env() + if not key: + raise HTTPException( + status_code=503, + detail="KI nicht konfiguriert (OPENROUTER_API_KEY fehlt).", + ) + return key, model + + +def run_exercise_ai_suggestion( + cur, + *, + title: Optional[str], + goal: Optional[str], + execution: Optional[str], + focus_area_hint: Optional[str], + focus_areas_context: Optional[Sequence[Tuple[int, bool]]] = None, + want_summary: bool, + want_skills: bool, +) -> Dict[str, Any]: + key, model = _require_openrouter() + + g_plain = strip_html_to_plain(goal) + e_plain = strip_html_to_plain(execution) + if not (g_plain.strip() or e_plain.strip()): + raise HTTPException( + status_code=400, + detail="Mindestens Ziel oder Durchfuehrung muss Inhalt liefern (nach Entfernen von leerem HTML).", + ) + + t_title = (title or "").strip() + focus = (focus_area_hint or "").strip() + + result: Dict[str, Any] = {"model": model} + + if _ai_debug_on(): + fid_list = ",".join(str(x) for x in _ordered_focus_ids(focus_areas_context)) + _LOGGER.warning( + "AI_DEBUG exercise_ai suggest want_summary=%s want_skills=%s title_chars=%s goal_plain_chars=%s " + "exec_plain_chars=%s focus_hint_chars=%s focus_ctx_ids=[%s]", + want_summary, + want_skills, + len(t_title), + len(g_plain), + len(e_plain), + len(focus), + fid_list, + ) + + if want_summary: + prow = _load_prompt_row(cur, "exercise_summary") + if not prow: + raise HTTPException(status_code=503, detail="Prompt exercise_summary nicht aktiv oder fehlt in DB.") + ctx = { + "exercise_title": t_title or "-", + "exercise_focus_area": focus or "-", + "exercise_goal": g_plain or "-", + "exercise_execution": e_plain or "-", + } + prompt = _render_template(str(prow["template"]), ctx) + if _ai_debug_on(): + _LOGGER.warning( + "AI_DEBUG exercise_ai summary prompt_slug=exercise_summary prompt_chars=%s unreplaced_mustache_pairs=%s", + len(prompt), + prompt.count("{{"), + ) + try: + raw = openrouter_chat_completion(api_key=key, model=model, user_content=prompt) + except OpenRouterError as e: + raise HTTPException(status_code=502, detail=f"OpenRouter: {e}") from e + if _ai_debug_on(): + _LOGGER.warning("AI_DEBUG exercise_ai summary response_chars=%s", len(raw or "")) + text = (raw or "").strip() + if not text: + raise HTTPException( + status_code=502, + detail="OpenRouter/KI lieferte eine leere Kurzfassung (kein Modelltext).", + ) + if len(text) > _MAX_SUMMARY_CHARS: + text = text[: _MAX_SUMMARY_CHARS - 1].rstrip() + "…" + result["summary"] = {"text": text, "ai_generated": True, "model": model} + + if want_skills: + srow = _load_prompt_row(cur, "exercise_skill_suggestions") + if not srow: + raise HTTPException( + status_code=503, + detail="Prompt exercise_skill_suggestions nicht aktiv oder fehlt in DB.", + ) + catalog = build_contextual_skills_catalog_block( + cur, + title=t_title, + goal_plain=g_plain, + execution_plain=e_plain, + focus_hint=focus or None, + focus_ctx=focus_areas_context, + ) + ctx = { + "exercise_title": t_title or "-", + "exercise_focus_area": focus or "-", + "exercise_goal": g_plain or "-", + "exercise_execution": e_plain or "-", + "skills_catalog": catalog, + } + prompt = _render_template(str(srow["template"]), ctx) + if _ai_debug_on(): + _LOGGER.warning( + "AI_DEBUG exercise_ai skills prompt_slug=exercise_skill_suggestions catalog_chars=%s prompt_chars=%s " + "template_has_skills_placeholder=%s", + len(catalog), + len(prompt), + "{{skills_catalog}}" in str(srow.get("template") or ""), + ) + sys_hint = ( + "Du antwortest nur mit validem JSON (Array). Keine Kommentare, keine Erklaerungen ausserhalb des JSON." + ) + try: + raw = openrouter_chat_completion( + api_key=key, + model=model, + user_content=prompt, + system_content=sys_hint, + temperature=0.15, + ) + except OpenRouterError as e: + raise HTTPException(status_code=502, detail=f"OpenRouter: {e}") from e + if _ai_debug_on(): + _LOGGER.warning("AI_DEBUG exercise_ai skills response_chars=%s", len(raw or "")) + body = (raw or "").strip() + if not body: + raise HTTPException( + status_code=502, + detail="OpenRouter/KI lieferte leeren Inhalt für Skill-JSON.", + ) + frag = _first_balanced_json_array(body) + if frag: + body = frag + try: + parsed = _extract_json_array(body) + except (json.JSONDecodeError, ValueError) as e: + if _ai_debug_on(): + _LOGGER.warning( + "AI_DEBUG exercise_ai skills JSON parse_failed err=%s head=%s", + e, + (body.replace("\r", "").replace("\n", " ").strip())[:400], + ) + raise HTTPException( + status_code=502, + detail="KI lieferte kein verwertbares JSON fuer Skills.", + ) from e + skills = _sanitize_skill_entries(cur, parsed) + if _ai_debug_on(): + cand_n = len(parsed) if isinstance(parsed, list) else -1 + _LOGGER.warning("AI_DEBUG exercise_ai skills parsed_len=%s sanitized_kept=%s", cand_n, len(skills)) + + result["skills"] = skills + + return result + + +__all__ = [ + "build_contextual_skills_catalog_block", + "run_exercise_ai_suggestion", + "strip_html_to_plain", +] diff --git a/backend/main.py b/backend/main.py index d15db0b..32e5519 100644 --- a/backend/main.py +++ b/backend/main.py @@ -193,7 +193,7 @@ def read_root(): return out # Register routers -from routers import auth, profiles, exercises, exercise_progression_graphs, clubs, club_memberships, club_join_requests, admin_users, platform_media_storage, media_assets, skills, skill_profiles, training_planning, dashboard, training_modules, training_framework_programs, catalogs, maturity_models, matrix_stack_bundle, import_wiki, import_wiki_admin, legal_documents, content_reports +from routers import auth, profiles, exercises, exercise_progression_graphs, clubs, club_memberships, club_join_requests, admin_users, platform_media_storage, media_assets, skills, skill_profiles, training_planning, dashboard, training_modules, training_framework_programs, catalogs, maturity_models, matrix_stack_bundle, import_wiki, import_wiki_admin, legal_documents, content_reports, ai_skill_retrieval_admin app.include_router(auth.router) app.include_router(profiles.router) @@ -220,6 +220,7 @@ app.include_router(import_wiki.router) app.include_router(import_wiki_admin.router) app.include_router(legal_documents.router) app.include_router(content_reports.router) +app.include_router(ai_skill_retrieval_admin.router) # Lokale Übungs-Medien: standardmäßig nur über geschützten API-Pfad # GET /api/exercises/{id}/media/{mid}/file (?ssetoken für /