Kairo-Jinkendo/docs/sprints/Sprint0_AP0_4_Completion_Report_v0.1.md

AP0.4 – Abschlussbericht Workflow-ready Prompt, Feature & Config Registry

Status: abgeschlossen
Stand: 2026-07-04
Branch: develop · Schema 005 · Version 0.4.0-ap0.4

---

1. Scope und Einordnung

AP0.4 liefert die minimale, workflow-ready Grundlage für Feature-, Prompt-, Placeholder- und Configuration-Registry in Kairo — ohne LLM-Aufrufe, ohne Workflow Engine, ohne Billing.

Anforderung (AP0.4)	Status
Migration Feature/Prompt/Placeholder/Config/ExecutionLog	✓
Feature Registry + DB-Sync	✓
PromptDefinition / PromptVersion / PromptStep	✓
PlaceholderDefinition + Validation	✓
ConfigurationEntry + Config Service	✓
Single Prompt Rendering	✓
features-Block in Entitlements	✓
Capability-geschützte API	✓
Audit bei Sync/Config/Fehler-Render	✓
Tests	✓ (lokal; CI nach Push)

Bewusst nicht in AP0.4: Workflow/Pipeline-Ausführung, LLM, MCP, Tool Calling, Feature-Limits, Admin-UI, zentrale Jinkendo Prompt Engine.

---

2. Umgesetzte Dateien

Datei	Zweck
backend/migrations/005_prompt_feature_config_registry.sql	Tabellen Feature/Prompt/Placeholder/Config/ExecutionLog
backend/feature_registry.py	Feature-Registry + DB-Sync
backend/feature_registrations/	Initiale Features
backend/prompt_registry.py	Prompt-Registry + Version/Step-Sync
backend/prompt_registrations/	Smoke-Prompts
backend/placeholder_registry.py	Placeholder-Registry + Sync
backend/placeholder_registrations/	Tenant-/Actor-/Debug-Placeholder
backend/config_service.py	Config lesen/schreiben, Secret-Schutz
backend/prompt_validation.py	Placeholder-Extraktion + Validierung
backend/prompt_rendering.py	Single-Mode Render + ExecutionLog
backend/prompt_context.py	TenantContext → Placeholder-Werte
backend/sync_prompt_feature_config.py	Startup-Sync + Default-Configs
backend/rights_registrations/registry_ops.py	7 neue Capabilities
backend/routers/features.py	GET /api/features
backend/routers/prompts.py	Prompt-Liste, Detail, Render
backend/routers/config.py	Config GET/POST
backend/entitlements.py	features-Block aus DB
backend/capabilities.py	require_capability_ctx (ohne Tenant-Zwang)
backend/entrypoint.sh	Registry-Sync nach Rights-Sync
backend/version.py	0.4.0-ap0.4, Schema 005
backend/tests/test_feature_registry.py	Feature-Tests
backend/tests/test_prompt_registry.py	Prompt/Validation/Render-Tests
backend/tests/test_config_registry.py	Config-Tests
frontend/src/App.jsx	Header AP0.4
README.md	API-Doku AP0.4

---

3. Neue Migrationen

005_prompt_feature_config_registry.sql

Tabelle	Zweck
features	Feature-Metadatenkatalog
prompt_definitions	PromptDefinition inkl. execution_mode, active_version_id
prompt_versions	Versionierter Body + JSON-Schemas + model_policy_key
prompt_steps	Workflow-/Pipeline-Schritte (AP0.4: nur template genutzt)
placeholder_definitions	Typisierte Placeholder pro context_kind
configuration_entries	Global/tenant Config (kein Secret-Klartext)
prompt_execution_logs	Render-/Test-Läufe

---

4. Datenmodell

features
prompt_definitions ──< prompt_versions ──< prompt_steps
                  └── active_version_id → prompt_versions

placeholder_definitions (key + context_kind)

configuration_entries (global | tenant)

prompt_execution_logs → definition/version/user

ExecutionMode: single | pipeline | workflow (nur single ausführbar)
ContextKind: kairo.tenant_context, kairo.actor_context, kairo.debug_context
StepType: template, resolver, llm_call, postprocess, validation (nur template ausführbar)

---

5. Registry-Strukturen

Analog AP0.3 Rights Registry:

backend/
├── feature_registry.py + feature_registrations/
├── prompt_registry.py + prompt_registrations/
├── placeholder_registry.py + placeholder_registrations/
├── config_service.py
├── prompt_validation.py
├── prompt_rendering.py
└── sync_prompt_feature_config.py

Startup-Reihenfolge: Migrationen → Seeds → Rights-Sync → Registry-Sync → Uvicorn.

---

6. Feature Registry

Registrierte Features:

Feature Key	Modul
kairo.feature.registry	platform
kairo.config.registry	config
kairo.prompt.registry	prompt

Keine Limits, Quotas oder Billing — reiner Metadatenkatalog im Entitlements-Snapshot (enabled: true).

---

7. Prompt-Modell

Kernel-Konzepte (lokal in Kairo, extrahierbar):

Konzept	Umsetzung
PromptDefinition	prompt_definitions + PromptRegistration
PromptVersion	prompt_versions
PromptStep	prompt_steps
PlaceholderDefinition	placeholder_definitions
ContextKind	Code-Konstanten + Spalte context_kind
ExecutionMode	Spalte execution_mode
InputSchema / OutputSchema	JSONB auf Version
ModelPolicyKey	Spalte (Vorbereitung, kein LLM)
PromptRenderService	prompt_rendering.render_prompt_single
PromptValidationService	prompt_validation.validate_placeholder_input
PromptExecutionLog	prompt_execution_logs

Smoke-Prompts:

• kairo.system.health_summary — Debug-Context, Template via PromptStep
• kairo.context.debug_summary — TenantContext-Placeholder
• kairo.actor.debug_summary — Actor-Context
• kairo.pipeline.placeholder — execution_mode=pipeline (strukturell, nicht ausführbar)

---

8. Workflow-/Pipeline-Fähigkeit

Vorbereitet	AP0.4 Verhalten
execution_mode=pipeline/workflow	In DB/Registry akzeptiert; Render → HTTP 501 / mode_not_implemented
prompt_steps mit diversen step_type	Gespeichert; Single-Render nutzt ersten aktiven template-Step oder version.body
input_mapping / output_mapping	JSONB-Spalten, noch nicht ausgewertet

Spätere Pipeline: Schritte der aktiven Version in step_order ausführen; pro step_type Handler registrieren (analog Rights-Registrations).
Spätere Workflow: execution_mode=workflow + Step-Graph/Orchestrator oberhalb des Render-Services — Tabellen müssen nicht migriert werden.

---

9. Placeholder Validation

• Mustache-Style: {{placeholder_key}}
• Required Placeholder aus Registry → kontrollierter PlaceholderValidationError
• Optionale Placeholder fehlen → kein Fehler
• Unbekannte Keys im Template → in validation.unknown_placeholders dokumentiert
• Typ-Prüfung basic (string, number, boolean, object, array, json)
• Template und Kontext getrennt (use_context + prompt_context.py)

Initial-Placeholder (Tenant): tenant_name, tenant_id, actor_*, portal_role, tenant_role, capabilities.

---

10. Configuration Registry

Default-Configs beim Sync:

Key	Wert
prompt.default_execution_mode	single
prompt.render_logging_enabled	true
features.registry_sync_enabled	true

• Scopes: global, tenant
• is_secret=true → kein Klartext; nur {"ref": "env"} erlaubt
• Zugriff zentral über config_service.py

---

11. Entitlements-Erweiterung

/api/me/entitlements liefert nun features auf Root-, Account- und Tenant-Ebene:

{
  "features": {
    "kairo.prompt.registry": {
      "enabled": true,
      "module": "prompt",
      "name": "Prompt Registry"
    }
  }
}

Keine Usage-Zähler. Feature-Enforcement bleibt probe.

---

12. Neue/geänderte API-Endpunkte

Endpoint	Auth	Capability
GET /api/features	Session	kairo.feature.registry.read
GET /api/prompts	Session	kairo.prompt.registry.read
GET /api/prompts/{key}	Session	kairo.prompt.registry.read
POST /api/prompts/{key}/render	Session	kairo.prompt.render
GET /api/config	Session	kairo.config.registry.read
POST /api/config	Session	kairo.config.registry.manage

require_capability_ctx erlaubt Lese-Endpunkte ohne aktiven Tenant (Portal-Admin/User).

---

13. Audit

Aktion	Event
Registry-Sync Startup	registry.sync.completed
Config geändert	config.entry.changed
Render fehlgeschlagen	prompt.render.failed
Capability verweigert	capability.denied (bestehend)

Prompt-Definition-CRUD über API ist in AP0.4 nicht exponiert (nur Code-Registry + Sync) — Audit bei manuellem DB-Write wäre Lücke; AP0.5 Admin-Routen können CRUD + Audit ergänzen.

---

14. Tests und Verifikation

Testdatei	Abdeckung
test_feature_registry.py	Registrierung, Sync, Entitlements, Auth
test_prompt_registry.py	Sync, Validation, Render, Pipeline-Ablehnung, API
test_config_registry.py	Global Config, Secret-Schutz, API
test_entitlements.py	Features im Snapshot
test_migrations.py	Migration 005
test_rights_registry.py	12 Capabilities

docker compose -f docker-compose.dev-env.yml exec backend python -m pytest tests -ra -vv

---

15. Übernommene Muster aus Mitai

Muster	Kairo
Prompt Template + Version	PromptRegistration / prompt_versions
Placeholder-Handling	Registry + Validation
Feature Registry Metadaten	features + Entitlements
Entitlements zentrale Schicht	features-Block ergänzt
Registry-Sync	Startup-Sync analog Rights
Preview/Testbarkeit	Render-Endpoint + ExecutionLog

Nicht übernommen: Pipeline-Graphen, Gesundheits-Prompts, Tier/Billing, Usage-Zähler.

---

16. Übernommene Muster aus Shinkan

Muster	Kairo
Mustache-Template-Prinzip	{{key}}-Rendering
Kontextarten	context_kind
Registry-first	Code → DB-Sync
Schlanke Runtime ohne Overengineering	nur Single-Render
Capability-Gates	require_capability*

Nicht übernommen: Trainings-Prompts, Club-Logik, Übungsrechte.

---

17. Bewusst nicht übernommene Muster

• Vollständige Mitai Prompt Engine / Workflow-Graphen
• LLM Provider Routing, Tool Calling, MCP
• Shinkan-/Mitai-Domänenprompts
• Feature-Limits, Billing, Coupons
• Produktive Admin-UI
• Secrets in configuration_entries

---

18. Abweichungen von Designprinzipien

Thema	Abweichung	Begründung
Prompt-CRUD API	nur Code-Registry + Sync	Sprint-0-Minimal; Swagger-Read/Render reicht
Feature-Enforcement	immer probe	Limits erst später
Output-Validation	nicht implementiert	Spec: nicht erforderlich in AP0.4
ContextKind	Code-Konstanten, keine eigene Tabelle	Ausreichend für 3 Kindes

---

19. Offene Entscheidungen

1. Wann Prompt/Feature-CRUD über Admin-API (AP0.5)?
2. Extraktion jinkendo_prompt_kernel — Package-Grenze und Migrations-Ownership
3. Pipeline-Executor — Step-Handler-Registry vs. feste Kette
4. Feature-Enforcement — wann über reine Metadaten hinaus?
5. Render-Logging in Prod — prompt.render_logging_enabled Default?

---

20. Empfehlung für AP0.5

Laut Foundation AP0.5 – Audit und minimale Admin-Prüfbarkeit:

• AuditLog für Registry-/Prompt-Änderungen erweitern
• Minimale Admin-Routen oder Admin-Seite
• Optional: Entitlements-/Feature-Panel in GUI
• Prod-pytest-Cleanup (*@example.com)

---

Extraktion jinkendo_prompt_kernel — Einschätzung

Realistisch: Die Module prompt_registry, placeholder_registry, prompt_validation, prompt_rendering und die Tabellen prompt_* / placeholder_definitions sind produktneutral genug (kairo.*-Keys nur in Registrations). Extraktion als Shared Python-Package mit injizierbarem DB-Layer und Audit-Hook ist ohne Schema-Bruch möglich.

Risiken im aktuellen Zuschnitt:

• Config und Feature Registry noch eng an Kairo-Entitlements gekoppelt
• Kein generischer Step-Executor — Pipeline-Integration erfordert noch Designarbeit
• require_capability_ctx vs. require_capability — zwei Patterns für Tenant-Pflicht

---

Referenzen

• docs/sprints/Jinkendo_Kairo_04_Sprint0_Foundation_v0.3.md § AP0.4
• Vorgänger: docs/sprints/Sprint0_AP0_3_Completion_Report_v0.3.md
• Designprinzipien: Mitai Prompt/Registry/Feature, Shinkan AI Prompt Runtime

---

Abgeschlossen im Rahmen Sprint 0 – AP0.4.