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

KI-Prompt-System — Zielarchitektur (Shinkan Jinkendo)

Version: 1.0
Datum: 2026-05-30
Status: VERBINDLICHE ZIELRICHTUNG (Roadmap — nicht alles bereits umgesetzt)
Ergänzt: AI_PROMPT_SYSTEM_SPEC.md (aktueller Ist-Stand APIs/DB/UI), Mitai-Anleihen aus gleichnamigen Konzepten (Admin-Prompts, Platzhalter)

---

1. Zweck

Dieses Dokument beschreibt das Zielbild, damit spätere Arbeiten (Trainingsplanung, mehrstufige Rahmenprogramme, Phasen/Streams, weitere KI-Artefakte) nicht zu wiederholten Refaktoren von Übungs-KI oder OpenRouter-Anbindung zwingen.

Leitkriterien: wenige stabile Schnittflächen, Kontext pro Domäne, komponierbare Prompts, gültige Ausgaben, Betrieb ohne Code-Deploy für kleine Tweaks.

---

2. Leitprinzipien

2.1 Eine stabile Ausführungsschicht

Alle produktiven KI-Aufrufe sollten mittelfristig über eine einheitliche Fassade laufen:

• Eingabe: slug (+ optional Kontext-Arten-Enum), serialisierter Domän-Kontext (Pydantic pro Kind), Konfiguration (Modell, Temperatur, … aus Env/DB).
• Ausgabe: Text oder validiertes JSON, Metadaten (model, slug, ggf. prompt_version/Hash), strukturierte Fehler.

Router und Frontend rufen diese Schicht oder schmale Orchestratoren — nicht direkt httpx/OpenRouter an jeder Ecke verteilt.

Frühere Konkretisierung (Umsetzung gestartet): Modul backend/ai_prompt_runtime.py (load_ai_prompt_row, load_and_render_ai_prompt, Kontext-Arten) sowie backend/ai_prompt_job.py (Pydantic ExerciseFormAiPromptContext fuer Uebungs-Prompts — Admin-Vorschau + erweiterbare Router-Nutzung); exercise_ai orchestriert OpenRouter nach dem Rendern.

2.2 Trennung: Semantik vs. Transport

• Semantik: Was soll das Modell liefern? Das hängt an Prompt-Definition, Ausgabeformat (text/json) und nachvollziehbarer Validierung — nicht am HTTP-Client.
• Transport: OpenRouter, Modellwahl, Retry, Timeouts bleiben in einem oder wenigen Hilfsmodulen.

2.3 Kontext-Namespaces für Platzhalter

Platzhalter und erlaubte Keys sind pro logischer Kontext-Art definiert, z. B.:

• exercise_form_ai — heute: Übungsformular-Vorschläge.
• später: training_unit, framework_program_slot, import_wiki, …

Damit kann der Katalog wachsen, ohne dass alle Keys in einen globalen Soup-Namespace müssen (exercise_* vs. framework_* ohne Kollisionen). Optional später präfixierte Keys (exercise.title, slot.index).

2.4 Komposition / Kaskade explizit

Ziel: Mehrteilige Prompts („System“–„Nutzer“–Anhänge) und Einbindung anderer Vorlagen als Daten (Kompositionsmodell), nicht nur als unbearbeiteter Freitext mit {{include}}.

Skizzen (noch nicht vollständig umgesetzt):

• Tabelle oder JSON-Spalte composition/ai_prompt_segments: geordnete Segmente mit role (system | user | äquivalent zum jeweiligen API-Shape), Quelle (inline, ref_slug), optional ref_slug, Schema-Version.
• Einbindungen mit Maximaltiefe und Zykluserkennung — keine unbegrenzten Makro-Ketten.

Bis dahin bleiben zusammenhängende Anweisungen in einem DB-Template pro Slug tragbar (exercise_skill_suggestions + {{skills_catalog}} bleiben gültig).

---

3. Zieldatenmodell (Schichten)

3.1 Definition (ai_prompts — bereits vorhanden, evolviert)

Konzept	Bedeutung
slug, category, output_format, active	Adressierung & Schalter
template	aktueller Inhalt
default_template	Referenz zum Zurücksetzen (Migration 069)
output_schema (JSONB)	optional: JSON-Outputs validieren

Ausbaustufen:

1. Nur template-Text (heute, plus Mustache über prompt_resolver).
2. Zusätzlich Versionierung: Historie oder template_version/Audit (wer hat wann geändert).
3. Segmentierte Composition wie in Abschnitt 2.4.

3.2 Kontext-Builder pro Domäne

Pro Kontext-Art eine klar genannte Routine (Pattern: registrierbare Builder):

Kontext-Art	Beispiel-Input aus der App	Beispiel-Platzhalter / Daten
exercise_form_ai	Titel, Ziel/Durchführung (HTML→Plain), Fokuskontext, Retrieval-Profil-Influenza	exercise_*, skills_catalog
training_unit (geplant)	Sektionen, Zeiten, Phasen/Streams, verknüpfte Übungs-IDs	unit_*, sections_summary_*
framework_program (geplant)	Ziele pro Woche/Schicht, Slots, bereits geplante Einheiten, Skill-Scores	framework_*, slot_*, aggregierte KPIs

Regel: Planungs-UI baut keine Prompt-Strings; sie liefert Domän-DTOs → Builder erzeugen Platzhalter-Map + ggf. Anhänge.

3.3 Skill-Retrieval und Prompts

ai_skill_retrieval_profiles steuert Katalog‑Zusammenstellung vor dem Platzhalter {{skills_catalog}} — das bleibt orthogonal zur Prompt-Verwaltung: Prompt ändert Anweisung, Profil ändert welche Skills im Kontextfenster sind.

---

4. Trainingsplanung & Rahmen — erwartete Komplexität

Risiken: sehr große Kontexte (viele Slots, Streams, Bibliotheken), wiederholte KI-Anfragen, Token-Limits.

Vorbereitende Strategien:

1. Gestufte Kontexte: Rohdaten → interne Kurzfassungen (optional zweiter Prompt oder heuristisch) → finale Generator-Prompt nur mit komprimierten Summaries.
2. Slug-Pro-Use-Case: z. B. training_unit_trainer_notes, framework_slot_coach_hint — jeweils schmaler Vertrag statt „ein Prompt für alles“.
3. Output-Verträge: JSON-Schema + Server-Validierung vor UI; Fehlermeldungen mit Referenz auf Slug/Version.
4. Feature-Flags / Modell-Overrides pro Slug (optional in DB oder Env) für Dev/Prod ohne große Codepfade.

---

5. Mitai (Jinkendo)

Konzeptionell gleiche Bausteine (admin-konfigurierbare Prompts, Platzhalter, Preview), andere Kontext-Builder und ggf. andere Mandanten/Overlays. Eine gemeinsame Resolver-/Mustache-Ebene ist wünschenswert; Shinkan-spezifische Planungs- und Rahmenkontexte bleiben in Shinkan gekapselt.

---

6. Betrieb, Sicherheit, Observability

• Audit: updated_by / Änderungshistorie für Templates (Backlog), heute: Timestamps.
• Prompt-Injection: System-/User-Segmente trennen; sensible Regeln in system/developer-äquivalenten Blöcken (wenn API das hergibt).
• Logging: weiter SHINKAN_AI_DEBUG; langfristig Hash/Länge des aufgelösten Prompts pro Request (ohne Secrets).
• Kosten/Latenz: Timeouts, max. Token-Hinweise pro Slug-Konfiguration.

---

7. Phasenplan (empfohlen, ohne Big-Bang)

flowchart LR
  subgraph laufzeit
    A[ai_prompts DB]
    B[prompt_resolver Mustache]
    C[ai_prompt_runtime]
    J[ai_prompt_job Pydantic]
    D[exercise_ai OpenRouter]
  end
  A --> C
  C --> B
  J --> D
  C --> D
  B --> D

Phase	Inhalt
P0	AiPromptContextKind, load_ai_prompt_row zentral; Übungs-KI über Laufzeit.
P1	load_and_render_ai_prompt, AiPromptUnavailableError, render_ai_prompt_template_for_row; ExerciseFormAiPromptContext in ai_prompt_context.py; run_exercise_form_ai_suggestion; Übungs-API und Admin-Vorschau nutzen denselben Kontext.
P2	Versionierung oder Audit-Spalten; teilweise: optionales OpenRouter-Modell pro Zeile (openrouter_model, Migration 070, Fallback OPENROUTER_MODEL); weitere Overrides (Temperatur) offen.
P3	Composition/Segmente (JSON Schema Version 1) + UI nur für komplexe Slugs.
P4	Erste Planungs-/Rahmen-Slugs mit dedizierten Buildern und Token-Budget-Strategien.

---

8. Was bewusst vermieden werden soll

• Vollständige „Workflow-Engine“ mit beliebigen Graphen, bevor 2–3 konkrete Planungs-Anwendungsfälle live sind.
• Pro-Verein-Prompt-Kopien vor klar definierter Produkt-Anforderung (sonst Daten- und Pflege-Spirale).
• Unbegrenzte include-rekursive Textmakros ohne Tiefenschutz.

---

9. Querverweise

• Ist-Implementierung Prompts/UI: AI_PROMPT_SYSTEM_SPEC.md
• Zugriffsrecht Admin-Prompts: ACCESS_LAYER_ENDPOINT_AUDIT.md
• Retrieval-Profile: .claude/docs/working/AI_SKILL_RETRIEVAL_PROFILES_SPEC.md
• Übungs-KI-Codepfad: backend/exercise_ai.py, backend/prompt_resolver.py, backend/ai_prompt_runtime.py, backend/ai_prompt_context.py, backend/ai_prompt_job.py

---

Version: 1.0 · Datum: 2026-05-30