Lars
bef422a429
Saved presets keep URL and model per stage so detect can switch to Ollama without re-entering settings or sending plaintext to OpenRouter. Co-authored-by: Cursor <cursoragent@cursor.com>
237 lines
12 KiB
Markdown
237 lines
12 KiB
Markdown
---
|
||
title: "Kanshō – Plattformprinzipien: Registry, Prompt Engine, Konfiguration"
|
||
version: "0.1"
|
||
status: "Arbeitsstand"
|
||
date: "2026-08-19"
|
||
product_family: "Jinkendo"
|
||
document_role: "Technical Chapter / Extensibility / Registry / Prompt Engine / Configuration"
|
||
parent_document: "technische_zielarchitektur.md"
|
||
---
|
||
# Kanshō – Plattformprinzipien
|
||
|
||
Kanonisches Home für die aus Mitai übernommenen **Querschnittsmuster**: einheitliche Registrierung, Prompt- und Workflow-Engine, Konfigurierbarkeit, Modularisierung.
|
||
|
||
Quelle: `C:\dev\mitai\.claude\docs\jinkendo-foundation\design-principles/` (Dokumente 1–4, 7). Mitai-Pfade sind Beispiele, keine Kanshō-Dateinamen.
|
||
|
||
Der fachliche Dialog-/MVP-Stand bleibt **nicht final**. Datenschutz und Guardrails sind bindend: die Engine ruft Modelle nur über das Privacy Gateway auf. Dieses Kapitel legt die **Plattform** fest, auf der spätere Fachmodule registriert werden – nicht die Module selbst.
|
||
|
||
## 1. Leitentscheidung
|
||
|
||
**Status: entschieden** (Produktrahmen; Herkunft: Nutzeranforderung, Mitai-Foundation)
|
||
|
||
Kanshō übernimmt Mitais Erweiterungsarchitektur:
|
||
|
||
1. Neue Fähigkeiten kommen als **registrierte Komponenten** hinzu, nicht als Sonderpfade in Routern oder React.
|
||
2. KI läuft über **eine Prompt-/Workflow-Engine**, nicht über verstreute Provider-Calls.
|
||
3. Soweit fachlich sinnvoll, liegen Texte, Graphen, Sichtbarkeit und Limits in **administrierbarer Konfiguration**, nicht im Deploy-Code.
|
||
4. Berechnungen haben eine **Single Source of Truth** (Data Layer); UI und KI konsumieren dieselbe Schicht.
|
||
5. Jeder persönliche LLM-Aufruf der Engine geht durch das Privacy Gateway (`privacy_gateway.md`). Das ist fachliche Invariante, kein optionales Plugin. Konfiguration darf Prompts ändern, nicht den Egress-Pfad umgehen.
|
||
|
||
Nicht übernommen: Mitai-Domäne, parallele Legacy-Executoren, doppelte Registries, IDOR-Profilheader.
|
||
|
||
---
|
||
|
||
## 2. Registry- und Plugin-Muster
|
||
|
||
Mitai nutzt dasselbe Muster dreimal (Platzhalter, Dashboard-Widgets, CSV-Module). Kanshō übernimmt das **Meta-Muster** als einheitliches System für Modularisierung, Skalierung und Erweiterung.
|
||
|
||
### 2.1 Gemeinsames Schema
|
||
|
||
```text
|
||
REGISTRY (Kanon: ID + Metadaten + Policies)
|
||
├── Implementierung (Resolver, Komponente, Executor)
|
||
├── Validierung am Rand (unbekannte IDs ablehnen)
|
||
└── Konsumenten (GUI-Picker, API, Engine, Tests)
|
||
```
|
||
|
||
### 2.2 Verbindliche Prinzipien
|
||
|
||
| Prinzip | Kanshō |
|
||
|---|---|
|
||
| Eine autoritative ID-Liste pro Erweiterungstyp | Router und UI duplizieren keine Listen |
|
||
| IDs sind stabile Verträge | Rename = neuer Key + Deprecation |
|
||
| Metadaten getrennt von Implementierung | Admin/Export brauchen den Resolver nicht |
|
||
| Zwei Phasen: Kanon, dann Runtime-Binding | Auto-Registration per Package-Import |
|
||
| Validierung an der Registry-Grenze | unbekannte Keys scheitern früh |
|
||
| Konsumenten-agnostisch | dieselbe Registry für Engine, Admin, Diagnose |
|
||
| Erweiterungs-Checkliste | Katalog, Validierung, Test, Versions-Bump |
|
||
| Optional `requires_feature` | Entitlements nicht in der Registry auflösen |
|
||
| Eine Runtime, kein Spiegel | Mitai-Anti-Pattern `PLACEHOLDER_MAP` parallel zur Registry **nicht** nachbauen |
|
||
|
||
### 2.3 Erste erwartbare Registries (Rahmen, nicht Fachkatalog)
|
||
|
||
| Registry | Zweck | Status der *Inhalte* |
|
||
|---|---|---|
|
||
| Prompt-/Workflow-Definitionen | ausführbare KI-Bausteine | Engine entschieden; Kanshō-Prompts offen |
|
||
| Kontext-Platzhalter | `{{key}}` für Engine-Templates (Data Layer) | Muster entschieden; Key-Set offen |
|
||
| Privacy-Platzhalter | `[[SELF]]` usw. im External Model Context | getrennt von `{{key}}`; siehe `privacy_gateway.md` |
|
||
| Feature-IDs | limitierbare Fähigkeiten | Muster entschieden; Liste offen |
|
||
| UI-Katalog (Widgets/Karten/Nav-Beiträge) | konfigurierbare Oberflächenbausteine | Mechanik wie Mitai-Widgets; keine Health-Widgets |
|
||
| optionale Ingest-Module | später, falls Import nötig | Muster ja, Bedarf offen |
|
||
|
||
Neue erweiterbare IDs nur über den jeweiligen Kanon. Keine Ad-hoc-IDs in Prompt-Texten oder Layout-JSON.
|
||
|
||
---
|
||
|
||
## 3. Prompt- und Workflow-Engine
|
||
|
||
Mitai: `prompt_executor.py`, `workflow_executor.py`, Tabelle `ai_prompts`, Admin-CRUD, Preview, Import/Export.
|
||
|
||
### 3.1 Übernehmen
|
||
|
||
1. **Ein Executor** als einziger Einstieg für modellgebundene Ausführung (`base` / `pipeline` / `workflow`). Kein zweiter Pfad wie Mitais Legacy `insights.py`.
|
||
2. **Prompts und Workflows in der DB** (Name, Slug, Kategorie, aktiv, Template, Stages, Graph, Output-Format/Schema), nicht im Anwendungscode.
|
||
3. **Drei Typen:** `base` (Baustein), `pipeline` (Sequenz, Stages per Referenz), `workflow` (Graph, Verzweigung, Join).
|
||
4. **Platzhalter als Verträge** der Kontext-Registry; Templates enthalten `{{keys}}`, keine eingebettete Berechnung.
|
||
5. **Admin konfiguriert, Nutzer führt aus** (`require_admin` vs. `require_auth`).
|
||
6. **Preview ohne LLM**, Debug mit aufgelösten Platzhaltern (Ausgabe erst nach Gateway-Regeln; keine Klasse-A-Werte im Client-Debug).
|
||
7. **JSON Import/Export** Dev→Prod; System-Defaults mit Reset (`is_system_default` + `default_template`).
|
||
8. **LLM-Call nur als injizierte Callback-Funktion**, in Kanshō: Callback = Privacy Gateway, nicht Roh-OpenRouter.
|
||
|
||
### 3.2 Schichten in der Engine
|
||
|
||
| Schicht | Rolle |
|
||
|---|---|
|
||
| Templates / Graphen | Was konfiguriert ist (Admin) |
|
||
| Kontext-Platzhalter | Semantische Keys, Resolver |
|
||
| Data Layer | Werte für Keys (Layer 1) |
|
||
| Privacy Gateway | Minimierung, Pseudonymisierung, Egress, Demasking |
|
||
| Workflow-Executor | Reihenfolge, Verzweigung, Aggregation |
|
||
|
||
Fachliche Reflexions-Workflows (Tagesreflexion, Journal-Entwurf, …) werden **später als Konfiguration** in dieser Engine registriert, nicht als fest verdrahteter Python. Solange das Fachkonzept unfertig ist, bleibt die Bibliothek leer oder enthält nur technische Test-Prompts.
|
||
|
||
### 3.3 Nicht übernehmen
|
||
|
||
- Parallele Template-Engines und direkte LLM-Calls neben dem Executor.
|
||
- Doppelte Workflow-Speicher (`graph_data` und `workflow_definitions`).
|
||
- Frontend-Workflow-Editor ohne `RequireAdmin` (Mitai-Lücke).
|
||
- Unversioniertes Overwrite ohne Reset-Pfad.
|
||
- Debug-Responses mit Klarnamen oder vollem Internal Context.
|
||
- Vermischung von `{{key}}` (Kontext) und `[[ROLE]]` (Privacy).
|
||
|
||
Modellname und Endpoint-URL liegen in Admin-Konfiguration (`provider_settings`); Secrets bleiben Env. Routing-Policy später über Konfiguration, nicht über neue Executoren.
|
||
|
||
---
|
||
|
||
## 4. Weitgehende Konfigurierbarkeit
|
||
|
||
Ziel wie Mitai: **Einfachheit in der Nutzer-UX, Differenzierung in administrierbarer Konfiguration.**
|
||
|
||
### 4.1 Administrierbar (DB / Admin-UI)
|
||
|
||
- Prompt-Texte, Pipelines, Workflow-Graphen, Aktiv/Sortierung, Output-Schema
|
||
- Feature-Definitionen und Limits (wenn Entitlements genutzt werden)
|
||
- UI-Katalog: welche Karten/Nav-Beiträge sichtbar, Layout-Overrides
|
||
- System-Prompts vs. Instanz-Anpassungen (Reset auf Default)
|
||
- Provider-URL, Modell und ZDR/No-Train für Generate und Detect (`provider_settings`, Admin Schnittstellen)
|
||
- **Additiv 2026-09-08:** benannte LLM-Profile (`llm_profiles`); aktive Zuordnung je Stufe. Secrets bleiben Env.
|
||
- später: Privacy-Profile (Strict/Balanced), sobald fachlich konkret
|
||
|
||
### 4.2 Code / Env (nicht pro Klick im Admin)
|
||
|
||
- Registry-Schema und Resolver-Implementierungen
|
||
- Auth-Gates, Privacy-Pipeline-Schritte, Fail-Closed
|
||
- Breakpoint, Router-Zuschnitt, Migrationsmechanismus
|
||
- Provider-Secrets
|
||
|
||
### 4.3 Durchsetzung
|
||
|
||
Keine Sonderlogik „nur dieses eine Feature hardcodiert im Router“, wenn es ein Registry- oder Prompt-Fall ist. Lint/Konvention: neue KI-Aufrufe nur über den Executor.
|
||
|
||
**Nicht administrierbar:** Abschalten oder Umgehen des Privacy Gateway, Speichern voller Prompts beim Provider, Training-Freigabe für persönliche Kontexte, Fail-Open auf unsichere Endpoints.
|
||
|
||
---
|
||
|
||
## 5. Data Layer als SSoT
|
||
|
||
Mitai Layer 0 → 1 → 2a/2b. Kanshō übernimmt die **Trennung**, nicht die Körper-Metriken.
|
||
|
||
| Schicht | Kanshō-Rahmen |
|
||
|---|---|
|
||
| 0 Persistenz | PostgreSQL, profilbezogen |
|
||
| 1 Ableitung | eine Stelle für berechnete/verdichtete Werte, die mehrere Konsumenten brauchen |
|
||
| 2a KI | Platzhalter-Resolver liest Layer 1, formatiert für Templates |
|
||
| 2b UI | Chart/Listen-Payloads aus Layer 1, keine zweite Formel in React |
|
||
|
||
Router und React rechnen keine parallelen Scores. Welche Layer-1-Funktionen existieren, folgt dem späteren Fachstand (Summaries, Saturation, …) und wird dann **registriert**, nicht vorab erfunden.
|
||
|
||
---
|
||
|
||
## 6. Feature- und Entitlement-Muster
|
||
|
||
Mitai trennt Identität (Auth) von „darf Feature X wie oft?“. Kanshō übernimmt die **zentrale** `check_feature_access`-Idee an der API, nicht das Fitness-Abo als Produkt.
|
||
|
||
- Eine Feature-Registry.
|
||
- Enforcement in der API, nicht nur in der UI.
|
||
- Kataloge **referenzieren** Feature-IDs, lösen Tiers nicht selbst auf.
|
||
- Ob Tiers, Trials oder nur an/aus gebraucht werden, ist **offen** (Fach- und Produktstand). Die Erweiterungspunkte werden trotzdem so gebaut, dass Limits später ohne Router-Umbau möglich sind.
|
||
|
||
### 6.1 Verlustfreie spätere Ausprägung
|
||
|
||
Der Code enthält absichtlich **kein** fertiges Abo. Er enthält die Auflösungshierarchie, damit Tarif, Limit und Billing später Zeilen und Policies sind, keine neue Auth.
|
||
|
||
| Später | Wohin | Nicht wohin |
|
||
|---|---|---|
|
||
| Weitere Tiers / Limits | `tiers`, `tier_limits`, Seed/Admin | Router, React, `profiles.role` |
|
||
| Nutzer einem Tarif zuweisen | `profiles.tier_id` | neues Account-Modell |
|
||
| Usage nach erfolgreichem Call | `increment_feature_usage` (bereits vorhanden, noch nicht am Erfolgspfad) | Frontend-Zähler |
|
||
| User-Overrides | `user_feature_restrictions` | Hardcode in `check_feature_access` |
|
||
| Billing / Stripe / Familienabo | eigene Billing-Schicht oder zentrales Jinkendo-Abo | Kanshō-Auth, Prompt-Engine |
|
||
| Feinere Rechte (Prompts vs. Diagnose) | Permission-Gate **über** `require_admin`, Rolle bleibt grob | Feature-IDs als Pseudo-Rollen |
|
||
| Neue limitierbare Fähigkeit | Zeile in `features` + Check an der API | neue Spalte `max_*` am Profil |
|
||
|
||
Bestehende Sessions, Profile und Prompt-Rows bleiben gültig. Ein späteres Abo ist ein Fill-in dieser Tabellen plus Enforcement, kein Schnitt durch Login oder Gateway.
|
||
|
||
---
|
||
|
||
## 7. Konfigurierbare UI-Bausteine
|
||
|
||
Mitai-Dashboard-Widgets: Backend-Katalog, Frontend-Register, Config-Whitelist, `allowed`/Entitlement, graceful unknown ID.
|
||
|
||
Kanshō übernimmt diese **Mechanik** für spätere Oberflächenbausteine (z. B. Einstiegsimpulse, Diagnosekarten). Es werden keine Mitai-Gewichts-/Schlaf-Widgets kopiert. Solange die IA unfertig ist, kann der Katalog leer oder auf Shell-Platzhalter beschränkt sein.
|
||
|
||
---
|
||
|
||
## 8. Erweiterungs-Checkliste (neues Modul)
|
||
|
||
Analog Mitai-Übergabe, für Kanshō:
|
||
|
||
1. Registry-Kanon: ID, Metadaten, Tests auf Eindeutigkeit.
|
||
2. Implementierung registriert sich (Package-Import).
|
||
3. Validierung am Rand.
|
||
4. API-Router des Moduls; keine Business-Logik nur im Frontend.
|
||
5. Optional Prompt/Workflow in der Engine, Ausführung nur über Executor + Gateway.
|
||
6. Optional Feature-ID und Admin-Sichtbarkeit.
|
||
7. `MODULE_VERSIONS` / App-Version anpassen.
|
||
8. Kein zweiter Ausführungspfad.
|
||
|
||
---
|
||
|
||
## 9. Entscheidungsstand
|
||
|
||
| Thema | Stand | Status |
|
||
|---|---|---|
|
||
| Einheitliches Registry-Muster | ja | entschieden |
|
||
| Prompt-/Workflow-Engine mit DB-Konfiguration | ja | entschieden |
|
||
| Ein Executor, Callback = Privacy Gateway | ja | entschieden |
|
||
| Admin konfiguriert, User führt aus | ja | entschieden |
|
||
| Data Layer SSoT | ja | entschieden |
|
||
| Feature-Check an der API (Muster) | ja | entschieden |
|
||
| Konkrete Prompts, Keys, Features, Widgets | – | offen (Fachstand) |
|
||
| Mitai-Membership als Produkt | – | nicht übernehmen |
|
||
| Doppel-Registry / Legacy-Executor | – | verworfen |
|
||
|
||
## 10. Offene Fragen
|
||
|
||
Rahmen-Slice (User-Admin, Prompt-DB, Platzhalter-Registry, Feature-Check) ist im Code angelegt. Bleibt offen:
|
||
|
||
1. Liegen später fachliche System-Prompts zusätzlich als JSON im Git (`prompts.seed.json`) oder nur in der DB mit Export-Disziplin? Der Lade-Pfad existiert; die Datei ist bewusst leer.
|
||
2. Braucht Kanshō früh Limits ungleich unbegrenzt, oder bleibt `ai_calls` ohne Kontingent bis zur Produktentscheidung?
|
||
3. Selbst-Registrierung vs. nur Admin legt Nutzer an.
|
||
|
||
## 11. Querverweise
|
||
|
||
- Mitai: Foundation #1 Prompt Engine, #2 Data Layer, #3 Entitlements, #4 Registry, #7 Widgets
|
||
- Technisch: `ai_architecture.md`, `backend_and_api.md`, `admin_diagnostics.md`, `privacy_gateway.md`, `data_architecture.md`
|
||
- Fachlich: Arbeitsstand, nicht als Prompt-Inhalte vorwegnehmen
|