Lars
a152218c45
All checks were successful
Deploy Development / deploy (push) Successful in 43s
Test Suite / pytest-backend (push) Successful in 44s
Test Suite / lint-backend (push) Successful in 0s
Test Suite / build-frontend (push) Successful in 14s
Test Suite / k6 /health Baseline (push) Successful in 34s
Test Suite / playwright-tests (push) Successful in 1m14s
- Introduced multistage path quality assurance (QA) functionality to improve exercise relevance and feedback through structured tiers and optimization hints. - Updated stage specifications to include `start_state` and `target_state` for better contextualization in roadmap matching. - Enhanced semantic brief construction with technique sibling exclusions to refine exercise selection based on primary topics. - Improved path retrieval logic to incorporate new parameters for nuanced matching against learning goals. - Incremented application version to reflect these updates.
369 lines
16 KiB
Markdown
369 lines
16 KiB
Markdown
# Progressionsgraph — KI-Planung (Ist-Stand)
|
||
|
||
**Stand:** 2026-05-22 (Dokumentation) · **App-Version:** **0.8.218** · **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. Roadmap-Match — Stufen-Qualität (0.8.218)
|
||
|
||
Pro Major Step gilt:
|
||
|
||
1. **Stufen-Brief** — `semantic_brief_for_stage()` ergänzt `must_phrases` um das Stufen-Lernziel.
|
||
2. **Stufen-Gate** — `exercise_passes_stage_learning_goal_gate()` prüft Lernziel-Text in Titel/Summary/Ziel oder Mindest-`semantic_score`.
|
||
3. **Kein Fallback** — Bei `roadmap_first` wird **nicht** auf die globale `goal_query` zurückgefallen; passt keine Übung → **Lücke** (`roadmap_unfilled`) statt themenfremder Übung.
|
||
4. **Retrieval** — Bonus/Strafe im Hybrid-Score je nach Stufen-Passung.
|
||
5. **QS** — `detect_off_topic_steps` erkennt `stage_mismatch` anhand `roadmap_learning_goal`.
|
||
|
||
Tests: `test_planning_roadmap_stage_match.py`
|
||
|
||
---
|
||
|
||
## 6. 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`).
|
||
|
||
---
|
||
|
||
## 7. 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.
|
||
|
||
---
|
||
|
||
## 8. Planungs-Intent (gemeinsam mit Trainingsplanung)
|
||
|
||
Modul: **`planning_intent_context.py`** — domänenneutral, wiederverwendbar in Phase G.
|
||
|
||
| Baustein | Progressionsgraph heute | Trainingsplanung (Phase G) |
|
||
|----------|-------------------------|----------------------------|
|
||
| `build_planning_intent_context` | Aus `goal_query`, Zielanalyse, Notizen | Aus `section_guidance`, Slot, Einheit |
|
||
| `explicit_exclusions` | Negationen (`ohne/kein/nicht …`) | gleich |
|
||
| `path_anti_patterns` | → jede `stage_spec.anti_patterns` | → Abschnitts-/Slot-Brief |
|
||
| `path_success_criteria` | → `success_criteria` + Matching | → Slot-Erwartung |
|
||
| `finalize_stage_specs_with_intent` | Nach heuristischer/LLM-Roadmap | Analog für Sektionen |
|
||
|
||
LLM: Migration **089** — Prompts `planning_progression_goal_analysis` + `planning_progression_stage_spec` erhalten `intent_context_json`; Ausschlüsse nicht erfinden, nur aus Anfrage übernehmen.
|
||
|
||
Matching: `anti_patterns` + `success_criteria` → `build_stage_match_brief` → Retrieval-Gate (Titel + Summary + Goal).
|
||
|
||
### Stufen im Gesamtziel (`planning_stage_context.py`)
|
||
|
||
| Feld | Bedeutung |
|
||
|------|-----------|
|
||
| `start_state` | Soll-Start der Stufe (= `target_state` der Vorstufe / Pfad-Start) |
|
||
| `target_state` | Ziel nach dieser Stufe (= Soll für den nächsten Schritt) |
|
||
| `build_contextualized_stage_goal()` | Lernziel + Start + Stufen-Ziel + Gesamtziel → Brief/Retrieval |
|
||
|
||
Deterministisch: `derive_stage_specs_transition_states()` nach Roadmap-Pipeline; LLM kann Felder überschreiben (Prompt **090**).
|
||
|
||
### Mehrstufige Pfad-QS (`planning_path_qa_pipeline.py`)
|
||
|
||
| Stufe | Inhalt | Ableitung |
|
||
|-------|--------|-----------|
|
||
| **tier1** | Deterministische Gates (Technik-Scope, Ausschlüsse, unfilled) | `optimization_hints` → `rematch_slot`, `refine_stage_spec` |
|
||
| **tier2** | Übergangs-Lücken zwischen Schritten | `bridge_or_gap_fill` |
|
||
| **tier3** | LLM-Ganzpfad + Empfehlungen | `review_roadmap` |
|
||
|
||
API: `path_qa.qa_tiers`, `path_qa.optimization_hints` — **kein** anfrage-spezifischer Patch, sondern strukturierte Rückkopplung. Auto-Rematch-Schleife: Backlog (QS → Aktion → erneutes Match).
|
||
|
||
Phase G: gleiche Tiers für Abschnitts-QS nach Einheits-Match.
|
||
|
||
## 9. 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`
|
||
|
||
---
|
||
|
||
## 10. 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`
|
||
|
||
---
|
||
|
||
## 11. 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 |
|
||
| F10 | Stufen-Lernziel-Gate beim Match (kein goal_query-Fallback) | ✅ | 0.8.218 |
|
||
| **G** | Trainingsplanung eigene Pipeline + Graph-Referenz | 🔲 | — |
|
||
| **UX** | Wizard/Stepper statt Scroll-Monolith | 🔲 | separater Chat |
|
||
|
||
---
|
||
|
||
## 12. 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.
|
||
|
||
---
|
||
|
||
## 13. 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_intent_context.py` | Intent-Kontext, finalize stage_specs |
|
||
| `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 |
|
||
|
||
---
|
||
|
||
## 14. 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.
|
||
|
||
---
|
||
|
||
## 15. Changelog (Dokument)
|
||
|
||
| Datum | Änderung |
|
||
|-------|----------|
|
||
| 2026-05-22 | Erstfassung Ist-Stand 0.8.217 — zentrale Referenz nach F5–F9 |
|