Prompt (Prompt Registry): foundations

accepted

Status

accepted — ratificada 2026-05-09 (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)

Self-hosted-first analysis (5 gates)

  • G1 Feature parity: zero
  • G2 Performance: N/A
  • G3 Stability: N/A
  • G4 Capability: embedded em qualquer DB
  • G5 Critical-path readiness: destrava qualidade de prompt cross-produto

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.