From 4d36bbf634d7dbddfd246e95b775790d87ae77d6 Mon Sep 17 00:00:00 2001 From: Lars Date: Fri, 22 May 2026 07:56:56 +0200 Subject: [PATCH] Update AI Training Planning Document and Versioning - Incremented the version number from 0.2 to 0.3 in the AI Training Planning document to reflect the latest changes. - Added a new reference to the `working/AI_PLANNING_KI_MULTISTAGE_FORECAST.md` document, outlining the architecture preview for the planning AI. - Updated the changelog in `backend/version.py` to include the latest version entry, ensuring accurate tracking of changes. --- .../technical/AI_TRAINING_PLANNING_CONCEPT.md | 6 +- .../AI_PLANNING_KI_MULTISTAGE_FORECAST.md | 112 ++++++++++++++++++ backend/version.py | 1 + 3 files changed, 117 insertions(+), 2 deletions(-) create mode 100644 .claude/docs/working/AI_PLANNING_KI_MULTISTAGE_FORECAST.md diff --git a/.claude/docs/technical/AI_TRAINING_PLANNING_CONCEPT.md b/.claude/docs/technical/AI_TRAINING_PLANNING_CONCEPT.md index a8a76a0..c28fdd5 100644 --- a/.claude/docs/technical/AI_TRAINING_PLANNING_CONCEPT.md +++ b/.claude/docs/technical/AI_TRAINING_PLANNING_CONCEPT.md @@ -1,6 +1,6 @@ # KI-gestützte Trainingsplanung – Zentrales Konzept -**Version:** 0.2 +**Version:** 0.3 **Datum:** 2026-05-22 **Status:** Arbeitsdokument (Verfeinerung durch fachliche Konzept-Agentur vorgesehen) **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. @@ -8,7 +8,7 @@ **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/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) · `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` +`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` --- @@ -31,6 +31,8 @@ **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 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/backend/version.py b/backend/version.py index 30fabb1..70d9a29 100644 --- a/backend/version.py +++ b/backend/version.py @@ -44,6 +44,7 @@ CHANGELOG = [ "KI bei Uebungen: Migration 067 ai_prompts + summary_ai_generated; OpenRouter-Hilfsmodul; POST /api/exercises/ai/suggest und POST /api/exercises/{id}/ai/regenerate", "Uebungsformular: Buttons KI Kurzfassung / Fähigkeiten; exercise_skills is_primary wird aus Payload gespeichert", ], + }, { "version": "0.8.151", "date": "2026-05-20",