Prompt (Prompt Registry) — foundations RFC

Status

*ccepted*— ratificada 20260509 (mesmo dia da abertura) como parte da onda piloto de bootstrap servicesai. Implementação iniciada em `servicesaiprompt; tickets em servicesaipromptbacklogpending/{001..005}`.

Summary

Registry central de promptstemplates versionados — análogo LangSmithPromptLayer/Anthropic Prompt Library.

Motivation

Cada produto inlina prompts no código. Sem registry: zero A/B test, zero versioning, zero auditoria, zero reuse cross-produto. Bloqueia eval mais rigoroso.

Scope

In

• Registry CRUD
• Versioning
• A/B testing
• ICU-like templating
• Ratings
• Search por uso

Out (yet)

• Prompt engineering UI completa (escopo de playground)

Initial design

Surfaces

• backend/ — Go API + DB
• app/ — não aplicável v1 (UI fica em playground)

Key APIs

• POST /v1/prompts — criar prompt
• GET /v1/prompts/{slug} — fetch latest
• GET /v1/prompts/{slug}/versions — histórico
• POST /v1/prompts/{slug}/render — render com variáveis

Dependencies

• infra/data/kdb-doc — storage
• services/ai/eval — consumer (avalia prompts)
• services/ai/trace — consumer (link runtime spans → prompt version)

Relation to existing sectors

• Pré-requisito de eval significativo
• Consumido por gateway opcionalmente (server-side render)

Selfhostedfirst analysis (5 gates)

• *1 Feature parity* zero
• *2 Performance* N/A
• *3 Stability* N/A
• *4 Capability* embedded em qualquer DB
• *5 Criticalpath readiness* destrava qualidade de prompt crossproduto

Open questions

• Q1: Format — Mustache, Jinja, ICU, ou próprio?
• Q2: Ratings — quem rate (auto via eval ou manual)?

Next steps

1. Ratificar esta RFC (1 round de comments).
2. Criar sector dir services/ai/prompt/ com koder.toml, README.md, skeleton.
3. Abrir tickets de implementação em services/ai/prompt/backlog/pending/.
4. Registrar em meta/docs/stack/registries/self-hosted-pairs.md se substituir externo.