Padrões de arquitetura para sistemas com o Jev

Um padrão de arquitetura responde a uma pergunta anterior ao código: onde entra o julgamento do modelo, quem manda no fluxo e o que acontece quando a resposta vem incerta. As primitivas dizem o que você pode perguntar. Esta seção diz como organizar o sistema em volta das respostas.

A documentação oficial nomeia quatro padrões. Nós acrescentamos três que aparecem nas receitas oficiais e na página de confiança, e deixamos claro quais são quais — os quatro primeiros são vocabulário da TypeSafe, os três últimos são leitura nossa do material dela.

Os quatro padrões oficiais

Fan-out especulativo. Mande numa única chamada todas as perguntas que o código pode precisar, inclusive as que talvez não sejam usadas. O state entra uma vez e cada pergunta é avaliada em paralelo contra ele, então a pergunta extra custa apenas os tokens dela. O cookbook oficial de perguntas paralelas mediu o efeito em uma tarefa de 13 perguntas sobre um artigo longo: 12,2 vezes mais barato e 10,0 vezes mais rápido que 13 chamadas separadas, sem mudança nas respostas. A consequência prática é estranha no começo: perguntar algo que você vai jogar fora é quase gratuito, e vale a pena.

Roteamento por confiança. A resposta diz o quê; a confiança diz se você deve agir. A documentação sugere três faixas — confiança alta age sozinha, média segue com cautela (confirmar, sinalizar, buscar mais informação) e baixa não age, vai para uma pessoa ou para outro caminho. O detalhe que mais gente erra: o limiar não é um número único do sistema, ele acompanha o risco da ação. O exemplo oficial usa piso de 0,5 para não agir e 0,9 para operação destrutiva sem confirmação.

Pontuação composta. Em vez de uma pergunta grande (“qual a prioridade deste ticket?”), várias perguntas pequenas e a combinação no seu código, com pesos que você controla. Quando a prioridade sai errada, você muda um coeficiente e roda de novo, em vez de reescrever um texto e torcer. Os pesos ficam visíveis no repositório, com histórico e revisão.

Roteamento de intenção. Classificar o que chegou e mandar cada caso para o melhor executor: uma regra determinística quando a decisão é simples, um LLM quando precisa escrever, uma pessoa quando o risco é alto. O Jev faz o desvio, e o desvio é a parte mais barata do fluxo.

Os três que vêm da prática

Cascata. Duas etapas em vez de uma: uma pergunta barata resolve a maioria dos casos, e só o resto sobe para um caminho mais caro. A receita oficial de extração estruturada monta essa cascata para ficar perto da qualidade de um modelo grande de raciocínio pagando uma fração do custo.

Beam search sobre probabilidades. Quando a classificação é hierárquica, uma pergunta por nível, mantendo os melhores caminhos abertos em vez de fechar no primeiro nível. A receita oficial de classificação hierárquica faz isso em taxonomias profundas usando as probabilidades de Choice.

Revisão humana no lugar certo. Não é “alguém confere no final”: é decidir, no desenho, qual faixa de confiança vai para fila humana, e registrar probabilidade e confiança junto com a decisão. No Brasil isso tem um motivo extra: o artigo 20 da Lei 13.709/2018 dá ao titular o direito de pedir revisão de decisão tomada unicamente por tratamento automatizado que afete seus interesses. Guardar a distribuição é o que torna essa revisão possível.

Como ler esta seção

Os sete padrões têm página própria, e os cartões abaixo levam a cada uma. Cada página segue a mesma estrutura: o que o padrão decide de verdade, o que ele obriga a arquitetura a ter e uma seção de quando não usar — porque padrão aplicado no lugar errado custa mais que padrão nenhum.

Comece pelo fan-out se o seu problema é custo ou latência; comece pelo roteamento por confiança se o seu problema é confiar no resultado. Os dois se apoiam em um conceito só, e ele tem página própria em confiança.

Quando você quiser ver esses padrões aplicados a uma tarefa concreta, as receitas traduzem os cookbooks oficiais, e os casos de uso mostram o desenho completo de um fluxo. O índice geral dos guias fica em guias.