IA Builder: mapeamento e contratos com grounding

Mapear um sistema no BIAN é um problema de classificação com catálogo fechado. A v14 tem um conjunto finito de Service Domains, cada um com papel, resumo e funções descritos em texto. O trabalho do mapeador é olhar uma capacidade do sistema ("calcula o limite rotativo do cartão") e apontar o domínio que a contém. Não há domínio novo a inventar: se o nome não está no catálogo, a resposta está errada.

Isso muda como se usa o modelo. Em vez de perguntar "qual Service Domain cuida de X?" e aceitar o que vier, o pipeline faz RAG sobre as definições oficiais da versão escolhida: cada domínio vira um documento (papel, resumo, funções, action terms), indexado por embedding. Para cada capacidade, recuperam-se os candidatos mais próximos, e só então o modelo entra, com uma instrução estreita: escolha entre estes candidatos, cite o trecho da definição que justifica a escolha e, se nenhum serve, responda "nenhum".

A última defesa é mecânica: um validador com lista fechada, os nomes exatos da v14. Qualquer saída fora da lista é rejeitada antes de chegar ao humano. O ponto é não depender da obediência do modelo. Modelo bem instruído erra pouco; validador não erra. Em sistemas financeiros, é esse o padrão que vale a pena: a regra que importa mora fora do prompt, em código pequeno e testável.

Quatro erros aparecem em todo mapeamento assistido, e três deles passam em revisão visual porque parecem corretos.

Nome inventado: o modelo responde "Card Limit Management" porque soa como BIAN. Não existe na v14. Sem lista fechada, o nome entra no heatmap e vira caixa num diagrama que ninguém vai conferir.

Versão velha: "Payment Execution" aparece em muito material público sobre BIAN e, portanto, no treinamento de qualquer modelo. Na v14 ele é obsoleto, junto com Payment Order e Payment Instruction; o fluxo de pagamento hoje passa por Payment Order Initiation, Payment Orchestration, Payment Confirmation, Payment Settlement e Payment Rail. Um modelo sem grounding responde a versão que leu mais vezes, não a que você escolheu.

Rename perdido: "Credit Card Position Keeping" virou Card Transaction Tracking. O nome antigo é plausível, descreve bem a função e está errado. O mesmo vale para Payment Initiation (hoje Payment Order Initiation) e Payment Rail Operations (hoje Payment Rail).

Vizinhos confundidos: Fraud Evaluation dá um veredito pontual sobre uma transação; Fraud Diagnosis analisa um caso suspeito ao longo do tempo. Os dois existem, os dois passam no validador, e a escolha errada coloca a fronteira do serviço no lugar errado. Esse é o erro que só a citação da definição e o revisor humano pegam. É por isso que o pipeline exige o trecho citado, não só o nome: a citação é o que permite ao revisor discordar em um minuto, em vez de reabrir o catálogo.

O mesmo princípio vale para contratos. Quando um time rascunha a API de um serviço mapeado em Payment Order Initiation, a referência é o YAML oficial da Semantic API v14 desse domínio, não a memória do modelo. Um script simples carrega o contrato rascunhado e o oficial, alinha as operações pelo action term e compara os campos: no Payment Order Initiation, PayerReference, PayeeReference, Amount e Currency precisam estar lá, com o mesmo nome e no mesmo lugar. Campo renomeado, campo faltando, tipo diferente: o script aponta a divergência linha a linha, e o revisor decide se foi desvio proposital ou descuido.

Desvio proposital existe e é legítimo. A Semantic API define semântica, não a sua implementação: ela não diz qual é a chave de idempotência do seu endpoint. No Pix, quem define isso é o catálogo de serviços do SPI, por mensagem; a Semantic API não entra nesse detalhe. Então idempotência é decisão sua, registrada como extensão documentada do contrato, não como campo "que o BIAN pediu". O script deve conhecer essas extensões declaradas para não marcar como erro o que foi decidido.

Sobre a infraestrutura: a opção gerenciada de RAG na AWS é o Amazon Bedrock Knowledge Bases, que cuida de ingestão, chunking, embedding e recuperação. Use quando a equipe não quer operar índice vetorial próprio e as definições cabem em um fluxo de ingestão simples. O validador de lista fechada e o script de contratos continuam sendo código seu, pequeno e testável. É a parte que menos muda quando você troca de modelo, e a que mais protege o mapa.