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:

```json
{
  "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 |

```bash
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.*