Lars
cdeddc7cec
All checks were successful
Deploy Development / deploy (push) Successful in 41s
Test Suite / pytest-backend (push) Successful in 42s
Test Suite / lint-backend (push) Successful in 0s
Test Suite / build-frontend (push) Successful in 12s
Test Suite / k6 /health Baseline (push) Successful in 33s
Test Suite / playwright-tests (push) Successful in 1m18s
- Added a new target architecture document for the AI Prompt System, detailing context types, composition, and planning phases. - Refactored the backend to utilize a shared function for loading AI prompt rows, reducing SQL duplication in the `exercise_ai` module. - Incremented the application version to 0.8.159 and updated the changelog to reflect these changes, including enhancements to the AI prompt management and documentation links.
165 lines
7.9 KiB
Markdown
165 lines
7.9 KiB
Markdown
# 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` mit **Kontext-Arten** und **gemeinsamen DB-Ladeschritten** für `ai_prompts`; Übungs-KI konsumiert diese Schicht ohne Zirkelschluss zu Domänlogik (`exercise_ai`).
|
||
|
||
### 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)
|
||
|
||
```mermaid
|
||
flowchart LR
|
||
subgraph heute
|
||
A[ai_prompts DB]
|
||
B[prompt_resolver Mustache]
|
||
C[ai_prompt_runtime Loader + ContextKind]
|
||
D[exercise_ai]
|
||
end
|
||
A --> B
|
||
A --> C
|
||
C --> D
|
||
B --> D
|
||
```
|
||
|
||
| Phase | Inhalt |
|
||
|-------|--------|
|
||
| **P0 (gestartet)** | `AiPromptContextKind`, `load_ai_prompt_row` zentral; Übungs-KI nutzt Laufzeit; Platzhalter-Katalog pro Kontext erweiterbar. |
|
||
| **P1** | Einheitliche `run_ai_job`-Fassade (Slug + Kind + Pydantic-Payload + Validierung); Router nur noch dünne Adapter. |
|
||
| **P2** | Versionierung oder Audit-Spalten; optionale Modell-/Temperatur-Overrides pro Slug in DB oder Config-Tabelle. |
|
||
| **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`
|
||
|
||
---
|
||
|
||
**Version:** 1.0 · **Datum:** 2026-05-30
|