shinkan-jinkendo/.claude/docs/technical/AI_TRAINING_PLANNING_CONCEPT.md

KI-gestützte Trainingsplanung – Zentrales Konzept

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.

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) · 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

---

1. Produktliche Leitlinien

• Nutzer: Trainer/Vereinskontext, Gruppenplanung – keine Pflicht zur individuellen Sportler-Verfolgung; Kontext soll primär aus Gruppe, bereits geplanten/durchgeführten Einheiten, Rahmen-/Zielen und berechtigtem Übungskorpus bestehen.
• 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.

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
Auftrag	z. B. Sektionstyp, Dauerbudget, Schwierigkeit, erlaubte Phasen/Streams
Hard Constraints	Gruppe, Termin/Zeitraum, Governance-Filter bereits angewendet
Komprimierte Historie	Letzte N Einheiten als Liste von Übungs-IDs + Kurzlabels (+ optional Haupt-Skills), keine vollen Fließtexte
Ziele / Rahmen	Kurztexte aus Rahmen-Slot/Zielblöcken oder Trainer-Prompt
Kandidaten-Top‑K	z. B. 30–120 Übungen, je Zeile gekürzt (Titel, summary, 2–5 Skill-Namen/Stufen); nie der gesamte Katalog
Strukturierte Kanten optional	Kleine Mengen Kanten aus Progressionsgraph: „Nachbarn von zuletzt genutzten Übungen“

Zahlen‑Richtwerte (überarbeitungsfähig):
Kandidaten vor dem LLM typischerweise 50–150 Einträge; im Prompt durch Token-Limit weiter truncate oder zweistufig (grober Ranking-Schritt ohne LLM, dann finer mit LLM auf Top‑40).

---

3. Pipeline: „Selektion vor dem Prompt“

Die „optimale“ Auswahl entsteht nicht, indem das Modell den Katalog „im Kopf“ hält, sondern über eine mehrstufige Pipeline:

Stufe 1 – Harte Filter (deterministisch, DB)

Synchron zur bestehenden Suche/List-API-Logik, z. B.:

• Sichtbarkeit / Verein / official‑Regeln
• Aktivitäts-/Archiv-Status der Übung
• Fokusbereich, Stil, Zielgruppe (wenn Trainings-/Gruppenkontext das vorgibt)
• Ausschluss bereits in dieser Einheit fester Übernutzung (optional)

Ergebnis: Menge M – kann noch sehr groß sein.

Stufe 2 – Kontext-Verankerung (deterministisch + Graph)

• Historie: aus letzten N Gruppeneinheiten extrahierte exercise_ids (optional Variant).
• Progressionsgraph: ausgehend davon Nachbarn (eingehend/ausgehend begrenzte Tiefe) – bereits im Produkt als unterstützend modelliert (CURR‑013).
• Rahmen/Slot-Ziele: Überlapp mit Skill-Tags oder Stichwortliste (falls formalisiert).
• Variantenketten: prerequisite_variant_id / progression_level nur innerhalb bereits gewählter Übung prüfen oder als Hint an den LLM-Block durchreichen.

Ergebnis: „Anker‑Menge“ + „Graph‑Nachbarschaft“ → priorisierte Kandidaten.

Stufe 3 – Weiches Ranking / Retrieval (halb-strukturiert)

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).
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.

Stufe 4 – LLM (optional zweistufig)

• Optional 1: LLM nur sortiert/rankted bereits vorgegebene IDs (Ranking mit kurzer Begründung).
• Optional 2: Zwei Calls: erst „welche drei Schwerpunkte“ / „Welche Constraints habe ich übersehen?“, zweiter Call nur mit gekürztem Top‑K – nur wenn UX den Mehraufwand rechtfertigt.

Ausgabe-Contract: Zurückkommen dürfen nur gültige exercise_ids aus der übergebenen Kandidatenliste (Server validiert gegen Set); Halluzinationsrisiko damit entschärft.

---

4. Antwort auf die konkrete Frage: „Alle Übungen in den Prompt?“

Nein. Workflow:

1. DB + Regeln + Graph + Historie reduzieren auf einige Hundert bis wenige tausend Rohzeilen höchstens intern – aber
2. in den LLM-Prompt gehen nur Top‑K kompakte Artefakte (siehe §2).

Das LLM löst dann Ranking, Reihenfolge, Timing-Hinweise, Trainer-sprachliche Kurzkommentare – nicht die Frage „gibt es diese Übung überhaupt im System?“.

---

5. Vector DB (z. B. Qdrant) – wann nötig, wann nicht?

5.1 Ziel embeddings

Semantic Retrieval: „wie springt Coordinative Belastung ohne das Wort ‚Koordination‘ im Titel zu stehen.“ Das ist über reine Filtersuche und oft über stumpfe Volltextsuche erreichbar.

5.2 Option A – ohne separate Vector DB

• PostgreSQL + pgvector (Extension): Embeddings-Spalte an exercises (oder an „Search Document“-Zeilen), Indices, Abfrage zusammen mit SQL-Filtern in einer Transaktions-DB.
• Größenordnung einige 10 k–100 k Zeilen für Übungen: für Shinkan oft ausreichend.
• Vorteile: ein Betriebspfad, Mandanten-/Governance weiter in SQL lösen; Backup wie heute.

5.3 Option B – Qdrant (oder anderer Dediz-Vektorstore)

Sinnvoller zeitlicher Punkt oder technische Auslöser:

• sehr hohe Latenz-Anforderung mit Hybrid-Filter über viele kombinierte Metadaten in nahezu Echtzeit,
• Entkopplung: Embedding-Pipeline läuft asynchron und soll die Operational DB nicht beschweren,
• später mehrsprachig oder mehrere Embedding-Versionen/Re-Index ohne großen Migrationstress,
• Team bevorzugt Dedicated Vector-Ops gegenüber Postgres-Ops.

5.4 Empfehlung für diese Codebasis (überarbeitungsfähig)

1. Phase 1: Harte Filter + Graph + Historie + PostgreSQL-Volltext + Top‑K; LLM erst auf komprimierten Kandidaten → hoher Nutzen ohne neuen Infrastructure-Typen.
2. Phase 2: Bei nachweisbaren „Recall-Lücken“ (Trainer findet nichts Passendes trotz großem Korpus) pgvector in Postgres evaluieren – vor zusätzlicher Infrastruktur wie Qdrant.
3. Phase 3: Qdrant (o. ä.) wenn Größenordnung, Betrieb oder Produkt-Anforderungen pgvector sprengen oder klar eine embedding-first Produktstraße geplant wird.

Fazit: Eine dedizierte Vector DB ist nicht zwingende Voraussetzung für vernünftige Selektion; sie ist eine Ausbaustufe, wenn semantische Lücke und Skalierung es rechtfertigen. Selektion ist immer „Filter + Ranking + kleines Top‑K“, unabhängig vom Speicherort der Vektoren.

---

6. Datenpflege für gutes Retrieval (fachlicher Hebel)

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); 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.

Das fachliche Konzept sollte entscheiden: wie viel automatische Pflege vs. Trainer-Pflichtfelder.

---

7. Produkt-/Release-Stufen (Anknüpfung)

Priorität jetzt: Übungsanlage, danach Planung.

Stufe	Nutzen	Technik-Schwerpunkt
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)	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 für Planungs-KI konsistent und wird parametrierbar erweitert; §1.1 spiegelt den aktuellen Implementierungs-Vorsprung (Skill-Scoring ohne LLM) wider.

---

8. Compliance & Datenschutz (Kurzhinweis)

• Datenminimierung: keine Teilnehmerliste ohne expliziten Scope; Kontext über Einheiten-Metadaten und Übungen.
• OpenRouter/Modellwahl: Organisation intern klären (AV/Verarbeitungsvertrag, Datenflüsse außerhalb EU – siehe Repo-Compliance-Dokumente).
• Logging: Prompts keine unnötigen personenbezogenen Daten; wenn Debug: Retention definieren.

---

9. Offene Punkte für die fachliche Verfeinerung

• Gewichtung „Wiederholung vs. Progression vs. Motivation“ (domänenspezifisch).
• Umgang mit Kombinationsübungen und Coach-Stufen B/C in der Datenübergabe.
• Soll das System „Lücken“ aus der Matrix-Auflösung aktiv quantifizieren oder nur Narrative verwenden?
• Akzeptierte Übersetzungen: nur Deutsch oder mehrsprachige Embeddings erforderlich?

---

10. Glossar

Begriff	Bedeutung
Top‑K	Feste kleine Obergrenze Übungen pro LLM-Anfrage
Hard filter	Deterministische SQL-/Policy-Einschränkung vor KI
Kontext-Paket	Zusammengesetztes, tokenlimitiertes Eingabeobjekt für den Prompt
Retrieval	algorithmischer Schritt ohne Generierung („wer kommt überhaupt in Frage“)