From 3be7606d90d3f0af80e95fa16a1e1dca3446694f Mon Sep 17 00:00:00 2001 From: Lars Date: Wed, 10 Jun 2026 07:50:29 +0200 Subject: [PATCH] Update documentation and enhance planning features in Progression Graph - Updated the `CLAUDE.md` to reflect changes in the Progression Graph, including the new Ist-Stand and roadmap specifications. - Enhanced `PLANNING_EXERCISE_SUGGEST_CONTEXT.md` with detailed descriptions of the current state and features of the planning exercise. - Revised `PLANNING_PROGRESSION_ROADMAP_SPEC.md` to document the implementation status of various phases and their corresponding migrations. - Incremented application version to 0.8.217 to incorporate recent updates and improvements in the planning context and roadmap functionalities. --- .../PLANNING_EXERCISE_SUGGEST_CONTEXT.md | 24 +- .../PLANNING_PROGRESSION_ROADMAP_SPEC.md | 25 +- CLAUDE.md | 2 +- backend/version.py | 44 ++- docs/HANDOVER.md | 47 +-- docs/architecture/PLANNING_KI_ROADMAP.md | 46 ++- .../PLANNING_PROGRESSION_GRAPH_KI.md | 314 ++++++++++++++++++ docs/architecture/README.md | 3 +- 8 files changed, 462 insertions(+), 43 deletions(-) create mode 100644 docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md diff --git a/.claude/docs/working/PLANNING_EXERCISE_SUGGEST_CONTEXT.md b/.claude/docs/working/PLANNING_EXERCISE_SUGGEST_CONTEXT.md index bbce56c..a8c1ccd 100644 --- a/.claude/docs/working/PLANNING_EXERCISE_SUGGEST_CONTEXT.md +++ b/.claude/docs/working/PLANNING_EXERCISE_SUGGEST_CONTEXT.md @@ -493,23 +493,37 @@ Nach Pfad-Bildung: --- -## 24. Phase F — Roadmap-first Progressionsgraph (0.8.204+) 🔄 +## 24. Phase F — Roadmap-first Progressionsgraph (0.8.204–217) ✅ **Entscheidung:** Progressionsgraph plant **vom Ziel rückwärts** (Roadmap → Stufenspezifikation → Bibliothek/KI). **Keine Gruppenanalyse** — die gehört zur Trainingsplanung. +**Ist-Stand (vollständig):** `docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md` **Spec:** `working/PLANNING_PROGRESSION_ROADMAP_SPEC.md` · **Roadmap:** `docs/architecture/PLANNING_KI_ROADMAP.md` | Teil | Modul / API | |------|-------------| | Pipeline | `planning_progression_roadmap.py` (Workflow-lite) | -| API | `include_roadmap_preview`, `include_llm_roadmap`, `roadmap_first` auf `progression-path-suggest` | -| Prompts | Migration **078/079** — Slugs in `ai_prompts` (Admin), **kein** Template im Python-Code | -| UI | `ExerciseProgressionPathBuilder` — Roadmap-Box (Major Steps) | +| Match | `planning_exercise_path_builder.py` — `roadmap_first`, `roadmap_override` | +| Skills | `planning_skill_expectations.py` — pro Stufe + Pfad | +| Gap-KI | `planning_exercise_form_context.py`, `planning_exercise_path_ai_fill.py` | +| Persistenz | `planning_roadmap` JSONB (Migration **088**) | +| API | `progression-path-suggest`, `PUT` Graph, `POST …/edges/sequence` | +| Prompts | **078/079/087** — Slugs nur in `ai_prompts` | +| UI | `ExerciseProgressionPathBuilder`, `ExerciseGapFillPrepModal` | -**F3 (0.8.206):** `roadmap_first=true` (Default im UI) — Retrieval pro `stage_spec`/Major Step; `roadmap_unfilled` Gap-Angebote. Ohne Flag: retrieval-first wie bisher, Roadmap nur Preview. +**Graph-Bias:** `progression_graph_id` bevorzugt **bestehende Nachfolger** ab Schritt 2 (Gewicht ~4–10 %), baut aber **keinen** Pfad aus vorhandenen Knoten — siehe Ist-Doku §5. **Mitai Workflow-Engine:** bewusst **nicht** jetzt — Pipeline workflow-ready für spätere Anbindung. --- ## 25. Backlog (offen) + +Siehe priorisierte Liste in **`docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md`** §10: + +1. UI-Wizard (Progressionsgraph) — separater Chat +2. Graph-Erweiterungsmodus (Start ab Knoten) +3. Trainingsplanung Phase G (Gruppenkontext, `planning_skill_expectations`) +4. Kontext auf allen Pfad-Schritten in der UI +5. Enrichment / Prompt-Feintuning +6. Mitai Workflow-Engine (langfristig) diff --git a/.claude/docs/working/PLANNING_PROGRESSION_ROADMAP_SPEC.md b/.claude/docs/working/PLANNING_PROGRESSION_ROADMAP_SPEC.md index 6e0eadb..b6d7307 100644 --- a/.claude/docs/working/PLANNING_PROGRESSION_ROADMAP_SPEC.md +++ b/.claude/docs/working/PLANNING_PROGRESSION_ROADMAP_SPEC.md @@ -2,9 +2,11 @@ **Version:** 0.1 **Datum:** 2026-06-07 -**Status:** VERBINDLICHE ZIELARCHITEKTUR — Umsetzung gestartet (0.8.204+) +**Status:** VERBINDLICHE ZIELARCHITEKTUR — **F0–F9 umgesetzt** (0.8.217) **Geltungsbereich:** **Progressionsgraph** (`exercise_progression_graphs`) — **ohne** Gruppenanalyse +**Ist-Stand (Module, API, Graph-Verhalten, Persistenz):** `docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md` + **Bezüge:** `working/PLANNING_EXERCISE_SUGGEST_CONTEXT.md` · `working/AI_PLANNING_KI_MULTISTAGE_FORECAST.md` · `technical/AI_TRAINING_PLANNING_CONCEPT.md` · `technical/AI_PROMPT_TARGET_ARCHITECTURE.md` · `docs/architecture/PLANNING_KI_ROADMAP.md` · `docs/HANDOVER.md` @@ -152,6 +154,7 @@ Jede Phase: `(ctx) → ctx`, Zwischenergebnisse in API-Response für **Human-in- | Slug | Phase | Migration | |------|-------|-----------| +| `planning_progression_start_target` | Start/Ziel | **087** | | `planning_progression_goal_analysis` | A | **078** | | `planning_progression_roadmap` | B | **078** | | `planning_progression_stage_spec` | C | **079** | @@ -184,15 +187,23 @@ Jede Phase: `(ctx) → ctx`, Zwischenergebnisse in API-Response für **Human-in- | ID | Inhalt | Status | |----|--------|--------| -| **F0** | Spec + Doku + `planning_progression_roadmap.py` Scaffold | 🔄 0.8.204 | -| **F1** | `include_roadmap_preview` in API + deterministische A/B | 🔄 0.8.204 | -| **F2** | LLM Phase A/B/C über `ai_prompts` (078/079), `include_llm_roadmap` | 🔄 0.8.205 | -| **F3** | Retrieval aus `stage_specs` (roadmap_first) | ✅ 0.8.206 | -| **F4** | UI Roadmap-Review | ✅ 0.8.207 | -| **F5** | Trainingsplanung: eigene Pipeline + ggf. Workflow-Engine | 🔲 | +| **F0** | Spec + Doku + `planning_progression_roadmap.py` Scaffold | ✅ 0.8.204 | +| **F1** | `include_roadmap_preview` in API + deterministische A/B | ✅ 0.8.204 | +| **F2** | LLM Phase A/B/C über `ai_prompts` (078/079), `include_llm_roadmap` | ✅ 0.8.205 | +| **F3** | Retrieval aus `stage_specs` (roadmap_first) | ✅ 0.8.206–209 | +| **F4** | UI Roadmap-Review + `roadmap_override` | ✅ 0.8.207 | +| **F5** | Start/Ziel strukturiert + Prompt **087** + Zwei-Schritt-UI | ✅ 0.8.210–214 | +| **F6** | Gap-Prep + `planning_context` an Übungs-KI | ✅ 0.8.212–214 | +| **F7** | `planning_skill_expectations` | ✅ 0.8.215–216 | +| **F8** | Editierbare `stage_specs` in UI | ✅ 0.8.216 | +| **F9** | `planning_roadmap` JSONB (Migration **088**) | ✅ 0.8.217 | +| **G** | Trainingsplanung: eigene Pipeline + Workflow-Engine | 🔲 | + +Details: `docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md` --- ## 9. Changelog +- **2026-05-22:** Ist-Stand F5–F9 dokumentiert; Verweis auf `PLANNING_PROGRESSION_GRAPH_KI.md`. - **2026-06-07:** Erstfassung — Roadmap-first Entscheidung, Abgrenzung Graphen vs. Planung, Workflow-lite. diff --git a/CLAUDE.md b/CLAUDE.md index f8d36f2..03e9f8a 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -18,7 +18,7 @@ > | Architektur-Zielbild, Refaktor-Roadmap, verbindliche Shinkan-Regeln | **`docs/architecture/README.md`** | > | Performance-Baseline (Phase 0) | **`docs/architecture/BASELINE_SNAPSHOT.md`** | > | KI-Prompt-System — Zielarchitektur | `.claude/docs/technical/AI_PROMPT_TARGET_ARCHITECTURE.md` | -> | Planungs-KI Progressions-Roadmap (Phase F) | **`.claude/docs/working/PLANNING_PROGRESSION_ROADMAP_SPEC.md`** · **`docs/architecture/PLANNING_KI_ROADMAP.md`** | +> | Planungs-KI Progressionsgraph (Ist-Stand) | **`docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md`** · Spec **`.claude/docs/working/PLANNING_PROGRESSION_ROADMAP_SPEC.md`** · Roadmap **`docs/architecture/PLANNING_KI_ROADMAP.md`** | ## Projekt-Übersicht diff --git a/backend/version.py b/backend/version.py index 742ae6b..d3ab790 100644 --- a/backend/version.py +++ b/backend/version.py @@ -38,7 +38,7 @@ MODULE_VERSIONS = { "skill_profiles": "1.0.0", # Phase 3: gewichtetes Fähigkeiten-Profil + skill-discovery/suggestions "methods": "0.1.0", "exercises": "2.37.1", # KI-Endpoints: feature_usage nach ai_calls consume - "planning_exercise_suggest": "0.21.1", # start_target_only + reicher gap-fill planning_context + "planning_exercise_suggest": "0.22.0", # skill_expectations, planning_roadmap persist (088), stage_specs override "training_units": "0.4.0", # POST .../publish-to-framework: Ablauf aus geplanter Einheit → Rahmen-Slot-Blueprint "training_programs": "0.1.0", "planning": "0.15.0", # Vorlagen: Strukturvorschau, Bearbeiten inkl. Split-Sessions + Beschreibung @@ -53,6 +53,48 @@ MODULE_VERSIONS = { } CHANGELOG = [ + { + "version": "0.8.217", + "date": "2026-06-07", + "changes": [ + "F9: planning_roadmap JSONB am Progressionsgraph (Migration 088).", + "PUT Graph + POST edges/sequence speichern Planungs-Artefakt; Laden beim Graph-Wechsel.", + "Roadmap-Vorschlag: include_llm_intent=true für reicheren Semantic Brief.", + "Doku: docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md als zentrale Ist-Referenz.", + ], + }, + { + "version": "0.8.216", + "date": "2026-06-07", + "changes": [ + "F8: Editierbare stage_specs in UI (Belastung, Erfolgskriterien) → roadmap_override.", + "Erwartete Fähigkeiten als Tags pro Pfadschritt und auf Pfad-Ebene.", + ], + }, + { + "version": "0.8.215", + "date": "2026-06-07", + "changes": [ + "F7: planning_skill_expectations — pro Stufe Retrieval, path_skill_expectations, Gap-Kontext.", + "Wiederverwendbare Scopes für spätere Trainingsplanung (training_section, framework_slot).", + ], + }, + { + "version": "0.8.214", + "date": "2026-06-07", + "changes": [ + "F6: ExerciseGapFillPrepModal — Trainer-Ergänzungen vor KI-Entwurf.", + "context_preview und reicher goal_for_ai aus Roadmap-Snapshot.", + ], + }, + { + "version": "0.8.210", + "date": "2026-06-07", + "changes": [ + "F5: Strukturierte Start/Ziel-Felder, Prompt 087, Zwei-Schritt-UI (start_target_only).", + "Priorität Trainer-Eingabe > KI > Regex; heuristische Start→Ziel-Roadmap.", + ], + }, { "version": "0.8.209", "date": "2026-06-07", diff --git a/docs/HANDOVER.md b/docs/HANDOVER.md index 869ba42..06e5daf 100644 --- a/docs/HANDOVER.md +++ b/docs/HANDOVER.md @@ -89,38 +89,39 @@ Das Schema ist gegenüber dem Code zurück: Migration **`022_skills_schema_compl - **Varianten:** Speichern in der **Aktionsleiste** persistiert zuerst geänderte Varianten (`persistPendingVariantChanges`), dann Übungs-Stammdaten; „Variante anlegen“ als `type="button"` ohne verschachteltes Formular (`createVariantFromDraft`) - **Governance (Übungen):** Owner = `created_by`; Bearbeiten = Ersteller, Plattform-Admin oder `can_plan_in_club` bei `visibility=club`; Löschen `club` = nur `club_admin`; Details **`FEATURES_DELIVERED_2026-Q2.md`** §16, **`EXERCISES_API_SPEC.md`** Permissions -### 2.8 KI Assistenz Übungen & Planungs-KI Übungssuche (Stand **0.8.183**) +### 2.8 KI Assistenz Übungen & Planungs-KI (Stand **0.8.217**) -**Spec / Pipeline:** `.claude/docs/working/PLANNING_EXERCISE_SUGGEST_CONTEXT.md` +**Zentrale Ist-Doku (Progressionsgraph-KI):** **`docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md`** — bei Drift zuerst dort pflegen. + +**Retrieval / Scoring:** `.claude/docs/working/PLANNING_EXERCISE_SUGGEST_CONTEXT.md` +**Zielarchitektur Roadmap:** `.claude/docs/working/PLANNING_PROGRESSION_ROADMAP_SPEC.md` +**Produkt-Roadmap Phase G+:** `docs/architecture/PLANNING_KI_ROADMAP.md` | Phase | Inhalt | Status | |-------|--------|--------| -| **P0** | Kontext-Pack, Hybrid-Score, Planungs-Picker | ✅ | -| **P0.1** | `ExerciseMatchProfile` / `PlanningTargetProfile`, `profile_v1` | ✅ | -| **P1** | Szenario-Pipeline + LLM Intent (`073`) + Erwartungsprofil (`074`) | ✅ | -| **P2 / B2** | LLM-Rerank (`072`) bei engem Top-Feld, max. 2 LLM-Calls | ✅ **0.8.182** | -| **A** | Voll-Library deterministisch ranken (kein OR-Profil-Pool) | ✅ **0.8.177** | -| **B** | Text-Signale aus guidance/Rahmen-Zielen (`planning_text_signals`) | ✅ **0.8.181** | -| **C1** | Progressionsgraph auto-match + variantenbewusste Nachfolger | ✅ **0.8.183** | -| **C2** | Varianten in Trefferliste / Picker-Auswahl | ✅ **0.8.184** | -| **C3** | Graph-Builder: Ziel → Pfad vorschlagen → in Graph speichern | ✅ **0.8.185** | -| **E** | Semantik-Schicht (Brief, Phrasen-Score) + Pfad-QA (Lücken, Brücken, LLM-QS) | ✅ **0.8.186** | -| **E2** | Pfad-Neuordnung (LLM) + KI-Neuanlage bei unüberbrückbaren Lücken | ✅ **0.8.187** | -| **E3** | `gap_fill_offers`, Off-Topic-Strip, voller KI-Call bei Lücken | ✅ **0.8.203** | -| **F0–F2** | Roadmap-Pipeline + LLM-Prompts (078/079) | ✅ **0.8.205** | -| **F3** | `roadmap_first` — Retrieval + QA lite (keine Brücken/Reorder) | ✅ **0.8.209** | -| **F4** | Roadmap-Review UI + `roadmap_override` | ✅ **0.8.207** | -| **D** | `planning_context` an `suggestExerciseAi` (Neu-Anlage) | ✅ **0.8.208** | +| **P0–P2, A–C2** | Übungssuche, Voll-Library, Graph-Bias, Varianten | ✅ bis **0.8.184** | +| **C3, E–E3** | Pfad-Builder, Semantik, QA, Gap-Offers | ✅ bis **0.8.203** | +| **D** | `planning_context` an `suggestExerciseAi` | ✅ **0.8.208** | +| **F0–F4** | Roadmap-Pipeline, LLM 078/079, `roadmap_first`, UI-Review | ✅ **0.8.205–209** | +| **F5** | Start/Ziel strukturiert, LLM **087**, Zwei-Schritt-UI | ✅ **0.8.210–214** | +| **F6** | Gap-Prep-Modal, reicher KI-Kontext (`planning_exercise_form_context`) | ✅ **0.8.212–214** | +| **F7** | `planning_skill_expectations` — Retrieval + UI + Gap | ✅ **0.8.215–216** | +| **F8** | Editierbare `stage_specs` (Belastung, Erfolgskriterien) | ✅ **0.8.216** | +| **F9** | `planning_roadmap` JSONB am Graph (Migration **088**) | ✅ **0.8.217** | -**Architektur-Entscheidung (2026-06-07):** Progressionsgraph = **Roadmap-first** (Ziel → Major Steps → Übungs-Match). **Keine Gruppenanalyse** im Graphen. Mitai Workflow-Engine **später** — jetzt `planning_progression_roadmap.py`. Spec: **`.claude/docs/working/PLANNING_PROGRESSION_ROADMAP_SPEC.md`** · Roadmap: **`docs/architecture/PLANNING_KI_ROADMAP.md`** +**Architektur (verbindlich):** Progressionsgraph = **Roadmap-first**, **keine Gruppenanalyse**. Bestehender Graph = **leichter Nachfolger-Bias** ab Schritt 2, **kein** automatisches Erweitern ab letztem Knoten (siehe Ist-Doku §5). Trainingsplanung = **eigene Pipeline** (Phase G), wiederverwendet `planning_skill_expectations`. -**Backend:** `planning_exercise_suggest.py`, `planning_exercise_retrieval.py`, `planning_exercise_path_builder.py`, **`planning_progression_roadmap.py`** · Router `POST /api/planning/exercise-suggest`, `POST /api/planning/progression-path-suggest` (`roadmap_first`, `include_roadmap_preview`) +**Backend-Kern:** `planning_progression_roadmap.py`, `planning_exercise_path_builder.py`, `planning_skill_expectations.py`, `planning_exercise_form_context.py`, `planning_exercise_path_ai_fill.py`, `progression_graph_planning_artifact.py` -**Frontend:** `ExerciseProgressionPathBuilder` — Roadmap-Box + Pfad je Major Step (`roadmap_first`) · `ExercisePickerModal` (Planung) +**API:** `POST /api/planning/progression-path-suggest` · `PUT /api/exercise-progression-graphs/:id` (`planning_roadmap`) · `POST …/edges/sequence` -**Superadmin:** Übungs-Anreicherung (Skills) — `exercise_enrichment_admin` (**0.8.178+**), separater Admin-Flow +**Frontend:** `ExerciseProgressionPathBuilder`, `ExerciseGapFillPrepModal`, `planningContextForExerciseAi.js` -**Offen (F4+):** Roadmap-UI editierbar; Trainingsplanung eigene Pipeline (Gruppenkontext); Enrichment +**Offen (priorisiert):** +1. UI-Wizard (Scroll-Monolith → 4 Schritte) — **separater UI-Chat** +2. Graph-Erweiterungsmodus (Start ab Knoten) +3. Trainingsplanung Phase G (Gruppenkontext) +4. Kontext-Anzeige auf allen Pfad-Schritten #### Übungs-KI Formular / Schnellanlage (Stand **0.8.171**) diff --git a/docs/architecture/PLANNING_KI_ROADMAP.md b/docs/architecture/PLANNING_KI_ROADMAP.md index 8f0cda3..ee16d23 100644 --- a/docs/architecture/PLANNING_KI_ROADMAP.md +++ b/docs/architecture/PLANNING_KI_ROADMAP.md @@ -1,10 +1,11 @@ # Planungs-KI — Produkt-Roadmap -**Stand:** 2026-06-07 -**App-Version:** ab **0.8.204** — maßgeblich `backend/version.py` +**Stand:** 2026-05-22 +**App-Version:** **0.8.217** — maßgeblich `backend/version.py` Diese Roadmap ergänzt die **Architektur-Refaktor-Roadmap** (`UMSETZUNGSPLAN_ROADMAP.md`) und gilt **nur für KI-gestützte Trainingsplanungsunterstützung**. +**Ist-Stand Progressionsgraph (detailliert):** `PLANNING_PROGRESSION_GRAPH_KI.md` **Leit-Spec:** `.claude/docs/working/PLANNING_PROGRESSION_ROADMAP_SPEC.md` --- @@ -26,9 +27,10 @@ Diese Roadmap ergänzt die **Architektur-Refaktor-Roadmap** (`UMSETZUNGSPLAN_ROA | A–C2 | Übungssuche | Voll-Library, Graph, Varianten | ✅ | | C3 | Progressionsgraph | Pfad-Builder (retrieval-first) | ✅ | | E–E3 | Progressionsgraph | Semantik, QA, Lücken-Angebote | ✅ | -| **F0–F1** | Progressionsgraph | Roadmap-Pipeline Scaffold + API-Preview | 🔄 **0.8.204** | -| **F2–F4** | Progressionsgraph | LLM Roadmap, roadmap-first Retrieval, UI Review | 🔲 | +| **F0–F4** | Progressionsgraph | Roadmap-Pipeline, LLM, roadmap-first, UI Review | ✅ **0.8.204–209** | +| **F5–F9** | Progressionsgraph | Start/Ziel, Gap-Prep, Skill-Expectations, Persistenz | ✅ **0.8.210–217** | | D | Übungs-Neuanlage | `planning_context` an `suggestExerciseAi` | ✅ **0.8.208** | +| **UX** | Progressionsgraph | Wizard/Stepper statt Scroll-UI | 🔲 | | G | Trainingsplanung | Kontext-Pack Gruppe/Historie, S0–S4 | 🔲 | | H | Plattform | Mitai-Workflow-Engine (optional) | 🔲 Backlog | @@ -70,6 +72,40 @@ Diese Roadmap ergänzt die **Architektur-Refaktor-Roadmap** (`UMSETZUNGSPLAN_ROA - [x] Major Steps editierbar (Phase, Lernziel, Reihenfolge) vor Übungs-Match - [x] API `roadmap_only` + `roadmap_override` +### F5 — Start/Ziel (0.8.210–214) + +- [x] Strukturierte Felder `start_situation`, `target_state`, `roadmap_notes` +- [x] Prompt **087** `planning_progression_start_target` +- [x] Priorität: Trainer > KI > Regex (`resolve_roadmap_structured_input`) +- [x] Zwei-Schritt-UI: „Start/Ziel analysieren“ / „Roadmap vorschlagen“ + +### F6 — Gap-KI-Kontext (0.8.212–214) + +- [x] `ExerciseGapFillPrepModal` vor KI-Call +- [x] `planning_exercise_form_context.py` — Gap-Snapshot, `context_preview` +- [x] Migration **085** — `planning_context` in Übungs-Prompts + +### F7 — Fähigkeiten-Scoring (0.8.215–216) + +- [x] `planning_skill_expectations.py` (Scopes: `progression_stage`, `progression_path`) +- [x] Pro-Stufe-Retrieval + `path_skill_expectations` + UI-Tags +- [x] `expected_skills` in Gap-Fill + +### F8 — Stufen-Details UI (0.8.216) + +- [x] Editierbare `stage_specs` in `roadmap_override` (Belastung, Erfolgskriterien, Vermeiden) + +### F9 — Persistenz (0.8.217) + +- [x] Migration **088** — `planning_roadmap` JSONB am Graph +- [x] Laden/Speichern über `GET/PUT` Graph + Sequenz-Endpoint + +### UX — UI-Überarbeitung (offen) + +- [ ] Wizard mit 4 Schritten (Ziel → Roadmap → Match → Lücken) +- [ ] Progressive disclosure — Details in Panels, nicht alles gleichzeitig +- [ ] Briefing: `PLANNING_PROGRESSION_GRAPH_KI.md` §10 + --- ## Abhängigkeiten @@ -85,4 +121,4 @@ Diese Roadmap ergänzt die **Architektur-Refaktor-Roadmap** (`UMSETZUNGSPLAN_ROA ## Pflege -Bei Abschluss einer Teilphase: diese Datei, `HANDOVER.md` §2.8, `PLANNING_EXERCISE_SUGGEST_CONTEXT.md` §24, Changelog in `version.py`. +Bei Abschluss einer Teilphase: **`PLANNING_PROGRESSION_GRAPH_KI.md`** (Ist-Stand), diese Datei, `HANDOVER.md` §2.8, `PLANNING_EXERCISE_SUGGEST_CONTEXT.md` §24, Changelog in `version.py`. diff --git a/docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md b/docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md new file mode 100644 index 0000000..246493a --- /dev/null +++ b/docs/architecture/PLANNING_PROGRESSION_GRAPH_KI.md @@ -0,0 +1,314 @@ +# Progressionsgraph — KI-Planung (Ist-Stand) + +**Stand:** 2026-05-22 (Dokumentation) · **App-Version:** **0.8.217** · **DB:** Migration **088** +**Maßgeblich für Code:** `backend/version.py` (`APP_VERSION`, `DB_SCHEMA_VERSION`) + +> **Diese Datei ist die zentrale Referenz** für die KI-gestützte Planung im Progressionsgraph. +> Ältere Abschnitte in `HANDOVER.md` §2.8 und `PLANNING_KI_ROADMAP.md` verweisen hierher. + +**Bezüge:** +`.claude/docs/working/PLANNING_PROGRESSION_ROADMAP_SPEC.md` (Zielarchitektur) · +`.claude/docs/working/PLANNING_EXERCISE_SUGGEST_CONTEXT.md` (Retrieval/Scoring) · +`.claude/docs/technical/SKILL_SCORING_SPEC.md` (Fähigkeiten-Scoring) · +`docs/architecture/PLANNING_KI_ROADMAP.md` (Produkt-Roadmap Phase G+) + +--- + +## 1. Fachliche Abgrenzung + +| Thema | Progressionsgraph (dieses Feature) | Trainingsplanung (Phase G, später) | +|--------|-------------------------------------|-------------------------------------| +| Ziel | Curriculum / Technikpfad über Übungen | Konkrete Trainingseinheit für Gruppe | +| Kontext | Zieltext, Start/Ziel, Roadmap, optional Graph-Kanten | Gruppe, Historie, Termin, Rahmen | +| Pipeline | `planning_progression_roadmap.py` → Path-Builder | Eigene Pipeline (noch offen) | +| Gruppenanalyse | **Nein** | **Ja** | +| Wiederverwendung | `planning_skill_expectations.py`, `planning_exercise_form_context.py` | Gleiche Bausteine, andere Scopes | + +**Shinkan-Regel:** Der Progressionsgraph ist **keine** persönliche Tracking-App und plant **nicht** für einzelne Sportler. + +--- + +## 2. Trainer-Workflow (UI) + +Aktuell in `ExerciseProgressionPathBuilder.jsx` (eingebettet in `ExerciseProgressionGraphPanel.jsx`): + +``` +① Ziel eingeben (+ optional Start/Ziel-Felder manuell) +② „Start/Ziel analysieren“ (optional, start_target_only) +③ „Roadmap vorschlagen“ (roadmap_only, LLM-Roadmap) +④ Roadmap bearbeiten (Major Steps + Stufen-Details) +⑤ „Übungen matchen“ (roadmap_first + roadmap_override) +⑥ Lücken mit KI schließen (gap_fill_offers + Vorbereitungs-Dialog) +⑦ „Pfad in Graph speichern“ (Sequenz-Kanten) +``` + +**Bekannte UX-Schuld:** Alle Schritte liegen auf **einer langen Scroll-Seite** — Überarbeitung als Wizard/Stepper ist geplant (separater UI-Chat). Briefing-Vorlage siehe unten §10. + +--- + +## 3. Architektur (Module) + +```mermaid +flowchart TB + subgraph ui [Frontend] + EPB[ExerciseProgressionPathBuilder] + GFM[ExerciseGapFillPrepModal] + PCtx[planningContextForExerciseAi.js] + end + + subgraph api [API] + PPS[POST /api/planning/progression-path-suggest] + EAI[POST /api/exercises/ai/suggest] + SEQ[POST /api/exercise-progression-graphs/:id/edges/sequence] + PUT[PUT /api/exercise-progression-graphs/:id] + end + + subgraph roadmap [Roadmap-Pipeline] + PR[planning_progression_roadmap.py] + ST087[Prompt 087 start_target] + ST078[Prompts 078/079 roadmap + stage_spec] + end + + subgraph match [Match + QA] + PB[planning_exercise_path_builder.py] + RET[planning_exercise_retrieval.py] + PG[planning_exercise_progression.py] + SEM[planning_exercise_semantics.py] + end + + subgraph skills [Fähigkeiten — wiederverwendbar] + PSE[planning_skill_expectations.py] + PEFC[planning_exercise_form_context.py] + AIF[planning_exercise_path_ai_fill.py] + end + + subgraph persist [Persistenz Graph] + G088[(planning_roadmap JSONB — Migration 088)] + EDGES[(exercise_progression_edges)] + end + + EPB --> PPS + EPB --> SEQ + EPB --> PUT + GFM --> EAI + PPS --> PR + PPS --> PB + PB --> RET + PB --> PG + PB --> PSE + AIF --> PEFC + PSE --> RET + SEQ --> EDGES + PUT --> G088 + SEQ --> G088 +``` + +### 3.1 Verantwortlichkeiten + +| Modul | Aufgabe | +|--------|---------| +| `planning_progression_roadmap.py` | Phasen A–C: Zielanalyse, Roadmap, `stage_specs`; Start/Ziel-Auflösung (Trainer > KI > Regex) | +| `planning_exercise_path_builder.py` | `suggest_progression_path`: roadmap_first Match, QA, Gap-Offers | +| `planning_exercise_progression.py` | Graph auflösen, Nachfolger-Kanten für Retrieval-Bias | +| `planning_skill_expectations.py` | Skill-Erwartungen pro Scope (`progression_stage`, `progression_path`, später `training_section`) | +| `planning_exercise_form_context.py` | `planning_context` / Gap-Snapshot für Übungs-KI | +| `planning_exercise_path_ai_fill.py` | Gap-Fill-Angebote, `goal_for_ai`, `context_preview` | +| `progression_graph_planning_artifact.py` | Validierung `planning_roadmap` JSON (Schema v1, max. 64 KB) | + +--- + +## 4. API — `POST /api/planning/progression-path-suggest` + +### 4.1 Wichtige Request-Flags + +| Feld | Typ | Bedeutung | +|------|-----|-----------| +| `query` | string | Ziel / Entwicklungsrichtung (min. 3 Zeichen) | +| `max_steps` | int | Anzahl Major Steps (2–10) | +| `progression_graph_id` | int? | Gewählter Graph — siehe §5 | +| `roadmap_first` | bool | Match pro `stage_spec` statt iterativem Pfad | +| `roadmap_only` | bool | Nur Roadmap, keine Übungen | +| `start_target_only` | bool | Nur Start/Ziel-Analyse | +| `roadmap_override` | object | Trainer-bearbeitete `major_steps` + `stage_specs` | +| `start_situation`, `target_state`, `roadmap_notes` | string? | Strukturierte Eingabe (Priorität vor KI) | +| `include_llm_start_target` | bool | LLM-Extraktion Start/Ziel (Prompt **087**) | +| `include_llm_roadmap` | bool | LLM Roadmap (Prompts **078/079**) | +| `include_llm_intent` | bool | LLM Intent für Semantic Brief (Roadmap-Vorschlag: **true** seit 0.8.217) | +| `include_path_qa`, `include_ai_gap_fill` | bool | QS, Lücken-Angebote | + +### 4.2 Wichtige Response-Felder + +| Feld | Bedeutung | +|------|-----------| +| `progression_roadmap` | Artefakte A/B/C inkl. `resolved_structured`, `stage_specs`, `prompt_slugs` | +| `steps[]` | Gematchte Übungen; pro Schritt u. a. `roadmap_*`, `skill_expectations` | +| `path_skill_expectations` | Pfadweite Skill-Erwartungen | +| `gap_fill_offers[]` | Lücken mit `context_preview`, `goal_for_ai` | +| `path_qa` | QS inkl. `roadmap_qa_mode: roadmap_first_lite` | + +### 4.3 Prompt-Slugs (nur in `ai_prompts`, nie Hardcoding) + +| Slug | Migration | Phase | +|------|-----------|-------| +| `planning_progression_start_target` | **087** | Start/Ziel-Extraktion | +| `planning_progression_goal_analysis` | **078** | Zielanalyse | +| `planning_progression_roadmap` | **078** | Roadmap (micro → major) | +| `planning_progression_stage_spec` | **079** | Stufenspezifikation | + +--- + +## 5. Rolle des bestehenden Graphs + +**Wichtig — häufiges Missverständnis:** + +| Aspekt | Verhalten | +|--------|-----------| +| **KI-Pfadvorschlag** | Baut einen **neuen** Übungspfad aus der **Bibliothek** (Roadmap-first), nicht aus vorhandenen Graph-Knoten als Start | +| **Schritt 1** | Kein Anker → **kein** Graph-Bias | +| **Ab Schritt 2** | Anker = vorherige Übung im Vorschlag → ausgehende Kanten im Graph werden geladen | +| **Scoring** | Nachfolger im Graph: Bonus `progression` (ca. **4–10 %** Gewicht, Semantik/Profil dominieren) | +| **Speichern** | `POST …/edges/sequence` **fügt Kanten hinzu** — ersetzt den Graph nicht | +| **Nicht implementiert** | „Ab letztem Graph-Knoten erweitern“, bestehende Sequenz als Pfad-Start | + +Code: `planning_exercise_progression.py` → `apply_progression_context_to_pack` → `planning_exercise_retrieval.py` (`prog_hit`). + +--- + +## 6. Persistenz + +### 6.1 Kanten (`exercise_progression_edges`) + +- Übungsfolge als gerichtete Kanten `next_exercise` +- Varianten-aware (Migration **034**) +- Kanten-Notizen aus Pfad-Begründungen oder Fallback-`segment_notes` + +### 6.2 Planungs-Artefakt (`planning_roadmap` JSONB, Migration **088**) + +Gespeichert am **Graph-Container** (`exercise_progression_graphs`), Schema v1: + +```json +{ + "schema_version": 1, + "goal_query": "…", + "start_situation": "…", + "target_state": "…", + "roadmap_notes": "…", + "max_steps": 5, + "progression_roadmap": { }, + "path_skill_expectations": { } +} +``` + +| Aktion | API | +|--------|-----| +| Speichern (Roadmap/Match) | `PUT /api/exercise-progression-graphs/:id` | +| Speichern (mit Pfad) | `POST …/edges/sequence` (optional `planning_roadmap` im Body) | +| Laden | `GET /api/exercise-progression-graphs/:id` → Frontend stellt Workflow-Felder wieder her | + +Validierung: `progression_graph_planning_artifact.py` · Tests: `test_progression_graph_planning_artifact.py` + +**`planning_roadmap` ≠ Graph-Kanten:** Metadaten für Wiederaufnahme der KI-Planung, nicht der Übungsgraph selbst. + +--- + +## 7. Fähigkeiten-Scoring-Anbindung + +Modul: `planning_skill_expectations.py` + +| Scope | Verwendung heute | Phase G (vorbereitet) | +|-------|------------------|------------------------| +| `progression_path` | Einmaliges Pfad-Profil (`path_skill_expectations`) | — | +| `progression_stage` | Pro Roadmap-Stufe vor Retrieval + in Gap-Kontext | — | +| `training_section` | — | Trainingsabschnitt | +| `framework_slot` | — | Rahmen-Slot | + +Quellen: `semantic_topic`, `text_match`, `load_profile` (aus `stage_spec`). + +Integration: +- Retrieval: `apply_expectations_to_target` → Hybrid-Score +- UI: Tags pro Pfadschritt + Pfad-Header; Gap-Kontext „Erwartete Fähigkeiten“ +- KI-Neuanlage: `expected_skills` in `context_preview` / `goal_for_ai` + +--- + +## 8. KI-Lücken (Gap-Fill) + +Flow: +1. `roadmap_unfilled` / QA-Lücken → `gap_fill_offers` +2. Trainer: **„Vorbereiten & KI anlegen“** → `ExerciseGapFillPrepModal` (Titel, Stufen-Lernziel, Ergänzungen) +3. `POST /api/exercises/ai/suggest` mit `planning_context` +4. Vorschau → Übung anlegen → in Pfad einfügen + +Kontext-Helfer: `frontend/src/utils/planningContextForExerciseAi.js` + +--- + +## 9. Implementierungsstände (Phasen) + +| Phase | Inhalt | Status | Version | +|-------|--------|--------|---------| +| F0–F2 | Roadmap-Pipeline + LLM-Prompts 078/079 | ✅ | 0.8.204–205 | +| F3 | `roadmap_first` Match pro Stufe | ✅ | 0.8.206–209 | +| F4 | Roadmap-Review UI + `roadmap_override` | ✅ | 0.8.207 | +| F5 | Start/Ziel strukturiert + LLM **087** + Zwei-Schritt-UI | ✅ | 0.8.210–214 | +| F6 | Gap-Prep-Modal + reicher `planning_context` | ✅ | 0.8.212–214 | +| F7 | `planning_skill_expectations` (Retrieval + UI + Gap) | ✅ | 0.8.215–216 | +| F8 | Editierbare `stage_specs` in UI | ✅ | 0.8.216 | +| F9 | `planning_roadmap` Persistenz (Migration **088**) | ✅ | 0.8.217 | +| **G** | Trainingsplanung eigene Pipeline + Graph-Referenz | 🔲 | — | +| **UX** | Wizard/Stepper statt Scroll-Monolith | 🔲 | separater Chat | + +--- + +## 10. Offenes Backlog (priorisiert) + +1. **UI-Überarbeitung** — Wizard mit 4 Schritten, progressive disclosure (Briefing unten) +2. **Graph-Erweiterungsmodus** — Start ab gewähltem Knoten / letzter Sequenz +3. **Kontext auf allen Pfad-Schritten** in UI (nicht nur Lücken) +4. **Trainingsplanung Phase G** — Pipeline mit Gruppenkontext, Wiederverwendung `planning_skill_expectations` +5. Enrichment / Prompt-Feintuning +6. Mitai Workflow-Engine (langfristig) + +### Briefing-Vorlage UI-Chat (Copy-Paste) + +Siehe Nutzer-Chat 2026-05-22 oder `HANDOVER.md` §2.8 — Abschnitt „UI-Überarbeitung“. + +Kern: Wizard ① Ziel & Start/Ziel → ② Roadmap → ③ Match → ④ Lücken & Speichern; Backend-Pipeline unverändert lassen. + +--- + +## 11. Tests + +| Datei | Abdeckung | +|-------|-----------| +| `test_planning_progression_roadmap.py` | Roadmap-Pipeline, Override, Start/Ziel | +| `test_planning_exercise_path_builder.py` | Pfad-Annotierung, Skill-Expectations auf Steps | +| `test_planning_skill_expectations.py` | Skill-Erwartungen, Scopes | +| `test_planning_exercise_path_ai_fill.py` | Gap-Fill, `expected_skills` in goal text | +| `test_planning_exercise_form_context.py` | `planning_context`, Gap-Snapshot | +| `test_progression_graph_planning_artifact.py` | JSONB-Artefakt-Validierung | +| `test_planning_exercise_progression.py` | Graph-Auflösung, Nachfolger | + +--- + +## 12. Dokumenten-Index (Drift vermeiden) + +| Frage | Primäre Quelle | +|-------|----------------| +| Was ist der aktuelle Ist-Stand? | **Diese Datei** | +| Zielarchitektur / JSON-Artefakte | `PLANNING_PROGRESSION_ROADMAP_SPEC.md` | +| Retrieval, Hybrid-Score, Intents | `PLANNING_EXERCISE_SUGGEST_CONTEXT.md` | +| Produkt-Roadmap Phase G+ | `PLANNING_KI_ROADMAP.md` | +| Session-Handover / nächste Schritte | `docs/HANDOVER.md` §2.8 | +| Fähigkeiten-Scoring allgemein | `SKILL_SCORING_SPEC.md` | +| Versionen / Changelog | `backend/version.py` | + +**Pflege-Regel:** Bei jeder abgeschlossenen Teilphase diese Datei + `HANDOVER.md` §2.8 + `version.py` CHANGELOG aktualisieren. + +--- + +## 13. Changelog (Dokument) + +| Datum | Änderung | +|-------|----------| +| 2026-05-22 | Erstfassung Ist-Stand 0.8.217 — zentrale Referenz nach F5–F9 | diff --git a/docs/architecture/README.md b/docs/architecture/README.md index 40061f6..a3a4c40 100644 --- a/docs/architecture/README.md +++ b/docs/architecture/README.md @@ -14,7 +14,8 @@ Dieses Bündel ist die **Leitlinie für die große Refaktorierung** nach dem MVP | [`frontend/src/api/planning.js`](../../frontend/src/api/planning.js) | Phase 4: Trainingsplanung (Einheiten, Vorlagen, Module, Rahmen, KPIs) | | [BASELINE_SNAPSHOT.md](./BASELINE_SNAPSHOT.md) | Phase 0: Bundle-, API- und Last-Baseline (Messvorlagen, Vergleich nach Phase 2) | | [KI-Prompt-Zielarchitektur](../../.claude/docs/technical/AI_PROMPT_TARGET_ARCHITECTURE.md) | Roadmap: Kontext-Arten, Composition, Planung/Rahmen, Phasenplan (verbindliche Zielrichtung) | -| [PLANNING_KI_ROADMAP.md](./PLANNING_KI_ROADMAP.md) | **Planungs-KI Produkt-Roadmap** (Phase F Roadmap-first, Abgrenzung Trainingsplanung) | +| [PLANNING_PROGRESSION_GRAPH_KI.md](./PLANNING_PROGRESSION_GRAPH_KI.md) | **Progressionsgraph-KI Ist-Stand** (Module, API, Graph-Verhalten, Persistenz — zentrale Referenz) | +| [PLANNING_KI_ROADMAP.md](./PLANNING_KI_ROADMAP.md) | **Planungs-KI Produkt-Roadmap** (Phase F–G, Abgrenzung Trainingsplanung) | | [Progressions-Roadmap Spec](../../.claude/docs/working/PLANNING_PROGRESSION_ROADMAP_SPEC.md) | Phase F: Artefakte A→B→C, API, Workflow-lite | ## Tests (E2E / Refaktor-Budget)