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

KI-gestützte Trainingsplanung – Zentrales Konzept

Version: 0.1
Datum: 2026-05-16
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.

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

---

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.

---

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:

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

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

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

Die Selektions‑Pipeline §3 bleibt über alle Stufen konsistent und wird nur parametrierbar erweitert.

---

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