Versionamento de Prompts — studyAI

Registo e rastreabilidade de prompts. Como alterar sem perder histórico.

---

Índice

1. Conceito
2. Prompts críticos por agente
3. Estratégia de versionamento
4. Integração com LangSmith
5. Fluxo de alteração

---

Conceito

• Problema: Alterar prompt pode quebrar comportamento. Sem versionamento, difícil reverter ou comparar.
• Solução: Prompts como código, com versões e traceability.

---

Prompts críticos por agente

---

Estratégia de versionamento

Opção A: Ficheiros + git

api/app/prompts/
├── router/
│   ├── classify_intent_v1.txt
│   └── classify_intent_v2.txt
├── planner/
│   └── plan_structure_v1.txt
├── writer/
│   ├── write_section_strict_v1.txt
│   └── write_section_hybrid_v1.txt
├── evaluator/
│   └── evaluate_answer_v1.txt
└── rag_qa/
    └── answer_with_citations_v1.txt

• Versão no nome do ficheiro ou em comentário no topo
• Git guarda histórico
• Código carrega por key: get_prompt("router.classify_intent", version=2)

Opção B: LangSmith Prompts

• LangSmith tem Prompts com versionamento
• Cada alteração cria nova versão
• Run usa prompt version específica
• Ver Integração com LangSmith

Opção C: DB (prompts table)

Decisão: Opção A para MVP (simples, git). Migrar para LangSmith Prompts ou DB se precisar de A/B ou rollback dinâmico.

---

Integração com LangSmith

• Trace: Cada run tem prompt_version ou prompt_id nos metadata
• Prompts UI: Se usar LangSmith Prompts, versões visíveis na UI
• Eval: Dataset pode especificar prompt_version para comparar

---

Fluxo de alteração

1. Copiar prompt atual → _v2.txt ou nova versão
2. Alterar conteúdo
3. Testar com golden set
4. Deploy com nova versão como default
5. Se regressão: reverter para versão anterior no código ou config

---

Registro mínimo

Em cada ficheiro de prompt, header:

# router.classify_intent v2
# Changed: added "expand" intent
# Date: 2025-03-20