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

KI-Funktionen Specification – Exercises

Version: 1.1 Datum: 2026-04-24 Status: DRAFT Autor: Claude Code Änderungen v1.1: Prompts sind nicht hardcoded – sie werden aus der DB geladen (AI_PROMPT_SYSTEM_SPEC.md) Verwandte Specs: AI_PROMPT_SYSTEM_SPEC.md (Prompt-DB + Platzhalter), SKILLS_MATRIX_SPEC.md (Fähigkeitsmatrix)

Übergeordnete Produkt-Vision (breiter Scope: Zielausbau, bereichsweise vs. Gesamtüberarbeitung, Varianten, Planungs-/Nachbereitungskontext, Admin-Masse):
functional/AI_EXERCISE_ASSISTANT_VISION.md

---

1. Übersicht

KI-gestützte Assistenzfunktionen beim Anlegen und Bearbeiten von Übungen (Mindestpaket dieser Spec):

Hinweis: Die beiden folgenden Zeilen entsprechen P0 der Phasierung in AI_EXERCISE_ASSISTANT_VISION.md; spätere Funkteile sind dort beschrieben.

Funktion	Ziel
KI-Zusammenfassung	Generiert summary aus goal + execution (für Listen + Trainingspläne)
KI-Skill-Empfehlung	Schlägt passende Fähigkeiten + Stufen vor (reduziert manuelle Zuordungsarbeit)

Abhängigkeit: OpenRouter API (OPENROUTER_API_KEY in .env). Ist der Key nicht gesetzt, sind alle KI-Funktionen deaktiviert – Formular funktioniert ohne KI normal.

---

2. UX-Prinzip: Manual First, Auto als Fallback

Trainer gibt goal + execution ein
        │
        ├─► [KI-Vorschlag]-Button sichtbar
        │          │
        │          ▼ (Klick)
        │   KI generiert sofort Vorschlag
        │   → Trainer sieht Vorschlag inline
        │   → Kann akzeptieren / bearbeiten / ablehnen
        │
        └─► Kein Klick bis zum Speichern?
                   │
                   ▼ (automatisch beim POST/PUT)
            KI läuft im Hintergrund
            → summary + skill_suggestions werden gesetzt
            → Trainer kann danach noch bearbeiten

Regel: Manuell generierte Werte (wo Trainer aktiv bestätigt hat) werden beim Auto-Fallback NICHT überschrieben. Auto-generierte Werte werden als ai_generated: true markiert und können jederzeit neu generiert oder überschrieben werden.

---

3. KI-Zusammenfassung (summary)

3.1 Was wird generiert

Aus title + goal + execution generiert die KI eine kurze Zusammenfassung (2-4 Sätze, max. 200 Zeichen) für:

• Übungslisten (Karten-Ansicht)
• Trainingsplan-Darstellung (kompakte Anzeige)
• Export-Berichte

3.2 Prompt-Logik (Backend)

Prompt ist NICHT hardcoded – er wird aus der ai_prompts Tabelle geladen (Slug: exercise_summary). Admins können das Template anpassen.

# Aufruf via zentralem AI-Service (siehe AI_PROMPT_SYSTEM_SPEC.md)
result = await ai_service.run_ai_prompt(
    slug="exercise_summary",
    context_data={"exercise": exercise_data},
    db=db,
    openrouter_key=settings.openrouter_api_key
)

Default-Template (in Migration 020 als default_template gespeichert): Siehe AI_PROMPT_SYSTEM_SPEC.md §2.1 – Prompt exercise_summary.

3.3 DB-Feld

Kein neues Feld nötig – exercises.summary nimmt den generierten Text auf. Zusätzliches Tracking-Feld: summary_ai_generated BOOLEAN DEFAULT false

---

4. KI-Skill-Empfehlung

4.1 Was wird empfohlen

Aus title + goal + execution + Katalog aller verfügbaren Skills empfiehlt die KI:

• Welche Skills relevant sind (aus dem bestehenden Skill-Katalog)
• Erforderliche Stufe (required_level) – was der Trainierende mitbringen muss
• Ziel-Stufe (target_level) – was durch regelmäßige Ausführung erreicht wird
• Intensität (intensity) – wie stark diese Fähigkeit trainiert wird

4.2 Prompt-Logik (Backend)

Prompt ist NICHT hardcoded – Slug: exercise_skill_suggestions. Der {{skills_catalog}}-Platzhalter wird vom Backend automatisch mit der aktuellen Skill-Liste aus der DB aufgelöst.

Admins können den Prompt anpassen (z.B. die Anweisung zur Auswahl verschärfen oder fachliche Hinweise ergänzen). Siehe AI_PROMPT_SYSTEM_SPEC.md.

4.3 Bestätigungsflow (UX)

KI gibt Vorschläge
       │
       ▼
┌─────────────────────────────────────────┐
│ KI-Vorschläge (3 Fähigkeiten)          │
│ ─────────────────────────────────────── │
│ ✓ Distanzgefühl                        │
│   Voraussetzung: Grundlagen             │
│   Ziel: Aufbau · Intensität: Hoch       │
│   [✓ Übernehmen] [Stufe ändern ▼] [✕]  │
│ ─────────────────────────────────────── │
│ ✓ Reaktionsschnelligkeit               │
│   Voraussetzung: Einsteiger             │
│   Ziel: Grundlagen · Intensität: Mittel │
│   [✓ Übernehmen] [Stufe ändern ▼] [✕]  │
│ ─────────────────────────────────────── │
│ ◦ Gleichgewicht (optional)             │
│   Voraussetzung: Grundlagen             │
│   Ziel: Grundlagen · Intensität: Niedrig│
│   [✓ Übernehmen] [Stufe ändern ▼] [✕]  │
│ ─────────────────────────────────────── │
│ [Alle übernehmen]      [Verwerfen]      │
└─────────────────────────────────────────┘

• Jeder Vorschlag kann einzeln übernommen, angepasst oder abgelehnt werden
• „Alle übernehmen" nimmt alle aktuell angezeigten Vorschläge
• Stufen können per Dropdown direkt angepasst werden bevor sie übernommen werden
• Abgelehnte Vorschläge werden nicht gespeichert

---

5. API-Endpoints

5.1 Endpoints Overview

Method	Endpoint	Beschreibung
POST	/exercises/ai/suggest	Vorschläge für neue Übung (vor dem Speichern)
POST	/exercises/{id}/ai/regenerate	Neu generieren für bestehende Übung

---

5.2 POST /exercises/ai/suggest

Liefert KI-Vorschläge auf Basis von Eingabe-Text, bevor die Übung gespeichert wurde. Wird beim Klick auf „KI-Vorschlag" im Formular aufgerufen.

Required Fields: mindestens goal ODER execution

Optional – Skill-Katalogpriorisierung (Stand 068):

{
  "focus_areas_context": [
    { "focus_area_id": 3, "is_primary": true },
    { "focus_area_id": 1, "is_primary": false }
  ],
  "focus_area_hint": "Karate, Kumite…"
}

• focus_areas_context: IDs aus Stammdatum Fokusbereiche; Primär soll zuerst stehen (is_primary). Ohne Feld oder leere Liste gilt das DB-Profil is_default (ai_skill_retrieval_profiles).
• focus_area_hint: bleibt lesbarer Text für den Prompt (bestehende Prompts).

Minimal-Beispiel (Mit Fokus für Retrieval):

{
  "title": "Maai - Distanzübung",
  "goal": "…",
  "execution": "…",
  "focus_areas_context": [ { "focus_area_id": 1, "is_primary": true } ]
}

Minimal-Beispiel ( ohne Fokus — nur Texts):

{
  "title": "Maai - Distanzübung",
  "goal": "Distanzgefühl entwickeln durch Partnerübungen...",
  "execution": "1. Partnerwahl\n2. Ausgangsstellung..."
}

Response: 200 OK

{
  "summary": {
    "text": "Partnerübung zur Entwicklung des Distanzgefühls. Trainiert werden räumliche Wahrnehmung und reaktives Verhalten in der Kumite-Distanz.",
    "ai_generated": true,
    "model": "anthropic/claude-sonnet-4"
  },
  "skills": [
    {
      "skill_id": 10,
      "skill_name": "Distanzgefühl",
      "skill_category": "Kumite",
      "required_level": "grundlagen",
      "target_level": "aufbau",
      "intensity": "hoch",
      "confidence": 0.92
    },
    {
      "skill_id": 15,
      "skill_name": "Reaktionsschnelligkeit",
      "skill_category": "Athletik",
      "required_level": "einsteiger",
      "target_level": "grundlagen",
      "intensity": "mittel",
      "confidence": 0.74
    }
  ]
}

Errors:

• 400 - Zu wenig Text (goal und execution leer)
• 503 - KI nicht verfügbar (OPENROUTER_API_KEY fehlt)

---

5.3 POST /exercises/{id}/ai/regenerate

Generiert summary und/oder skill-Empfehlungen für eine bestehende Übung neu. Verwendet die aktuellen gespeicherten Felder als Input.

Request Body:

{
  "regenerate": ["summary", "skills"]
}

Werte: "summary" | "skills" (oder beide)

Response: 200 OK (gleiche Struktur wie /ai/suggest)

Hinweis: Regenerieren überschreibt NICHT Felder, die manuell gesetzt wurden (summary_ai_generated = false). Es wird nur der Vorschlag zurückgegeben, Trainer muss aktiv übernehmen.

---

6. Datenbank

6.1 Neues Feld: summary_ai_generated

-- Als Teil von Migration 014 ergänzen:
ALTER TABLE exercises
ADD COLUMN IF NOT EXISTS summary_ai_generated BOOLEAN DEFAULT false;

Semantik:

• false (default) = Zusammenfassung manuell geschrieben oder noch leer
• true = Zuletzt von KI generiert (kann überschrieben werden)

Beim manuellen Überschreiben durch den Trainer: summary_ai_generated = false setzen.

6.2 Kein Feld für Skill-Empfehlungen

Skill-Vorschläge der KI werden nicht persistent gespeichert – sie erscheinen nur im Formular-UI und werden erst bei expliziter Bestätigung als reguläre exercise_skills-Einträge gespeichert.

---

7. Integration in Speicher-Flow

7.1 Auto-Fallback beim Speichern (POST/PUT exercises)

# In backend/routers/exercises.py
async def create_exercise(data, session):
    # 1. Übung normal speichern
    exercise_id = db.insert_exercise(data)

    # 2. Auto-KI nur wenn:
    #    - OPENROUTER_API_KEY gesetzt
    #    - summary noch leer
    #    - goal oder execution vorhanden
    if settings.openrouter_api_key and not data.summary and (data.goal or data.execution):
        # Background Task (non-blocking)
        background_tasks.add_task(
            auto_generate_summary,
            exercise_id=exercise_id,
            title=data.title,
            goal=data.goal,
            execution=data.execution
        )

    return exercise_id

7.2 Skill-Auto-Suggestion

Skill-Empfehlungen werden beim Auto-Fallback NICHT automatisch gespeichert (wegen Bestätigungs-Pflicht). Sie werden nur beim manuellen Trigger angeboten.

---

8. Frontend-Integration

8.1 ExerciseFormPage – KI-Buttons

┌──────────────────────────────────────┐
│ Ziel der Übung *                     │
│ ┌────────────────────────────────┐   │
│ │ Distanzgefühl entwickeln...    │   │
│ └────────────────────────────────┘   │
│                                      │
│ Durchführung *                       │
│ ┌────────────────────────────────┐   │
│ │ 1. Partnerwahl...              │   │
│ └────────────────────────────────┘   │
│                              ↓       │
│ Zusammenfassung (für Listen)         │
│ ┌────────────────────────────────┐   │
│ │ [Leer]                         │   │
│ └────────────────────────────────┘   │
│ [✨ KI-Vorschlag]  ← Button          │
│                                      │
│ ─────────────────────────────────── │
│ Fähigkeiten                          │
│ [Keine zugeordnet]                   │
│ [+ Manuell hinzufügen]               │
│ [✨ KI-Empfehlungen]  ← Button      │
└──────────────────────────────────────┘

8.2 KI-Vorschlag für Summary (Inline)

Beim Klick auf „✨ KI-Vorschlag":

┌──────────────────────────────────────┐
│ ✨ KI-Vorschlag                      │
│ ─────────────────────────────────── │
│ "Partnerübung zur Entwicklung des    │
│  Distanzgefühls. Trainiert räumliche │
│  Wahrnehmung und reaktives Verhalten."│
│ ─────────────────────────────────── │
│ [✓ Übernehmen]    [✕ Verwerfen]     │
└──────────────────────────────────────┘

Nach „Übernehmen": Text landet im Summary-Feld, Button zeigt „↺ Neu generieren".

8.3 Anzeige KI-generierter Inhalte

Felder die KI-generiert sind, werden mit einem kleinen Badge markiert:

Zusammenfassung ✨ KI-generiert  [bearbeiten]

Nach manuellem Bearbeiten verschwindet der Badge.

---

9. Konfiguration

OPENROUTER_API_KEY=sk-or-...
OPENROUTER_MODEL=anthropic/claude-sonnet-4   # Für Zusammenfassung
OPENROUTER_MODEL_FAST=anthropic/claude-haiku-4-5  # Für Skill-Empfehlungen (billiger)

---

10. Fehlerbehandlung

Szenario	Verhalten
OPENROUTER_API_KEY nicht gesetzt	KI-Buttons nicht anzeigen, kein Auto-Fallback
API-Timeout (> 10s)	Fehlermeldung inline: "KI momentan nicht verfügbar. Bitte manuell ausfüllen."
API-Fehler (5xx)	Gleiche Meldung, kein Absturz
Unbekannte Skills in Empfehlung	Backend filtert Skills die nicht im Katalog sind heraus
Summary zu lang generiert	Backend kürzt auf 200 Zeichen

---

Version: 1.0 Datum: 2026-04-24 Status: DRAFT