Abertura

Agora que você sabe medir, a gente começa a consertar. Primeiro, um smell que quase todo time que constrói com modelos tem, e quase ninguém percebe até o fechamento do mês.

Uma empresa extrai dados de contratos de fornecedores em duas etapas. A primeira lê o contrato e lista os dados principais. A segunda pega esse texto e preenche o cadastro no ERP da empresa.

E entre as duas etapas, tem isto. Uma expressão regular que procura a palavra Total, dois pontos e um número.

Funcionou por três meses. Aí um dia, o modelo começou a escrever valor total do contrato, em vez de só total. A expressão regular não achou nada. O total ficou vazio. E cento e quarenta contratos entraram no sistema sem valor, antes de alguém perceber.

Nada quebrou. Nenhuma exceção, nenhum alerta. O dado só estava vazio. Nesta aula, você vai aprender a reconhecer esse smell, por que ele é tão tentador, e a refatoração que elimina essa classe inteira de erros.

O diagnóstico

O formato é este. A primeira etapa produz um texto feito para uma pessoa ler.

E esse texto é a única interface entre as duas etapas.

O código, ou às vezes o próximo modelo, tenta adivinhar onde está cada dado.

Quando o palpite acerta, tudo funciona.

Quando o modelo muda o jeito de escrever, o dado some, sem alarme.

Como identificar? Uma etapa devolve prosa, e a próxima usa uma expressão regular, um split, ou procura a linha que começa com.

O código tolera vários nomes para o mesmo campo. Total, valor total, total geral.

A segunda etapa é outra chamada ao modelo, cujo único trabalho é entender o formato da primeira.

Mudar uma palavra num prompt quebra um parser em outro arquivo.

E campos que faltam viram vazio em silêncio, em vez de gerar um erro.

Por que acontece

Normalmente começa com um protótipo numa janela de chat. Alguém testou o prompt, gostou da resposta em texto e colou no código. No chat, texto é o produto. Num pipeline, texto é um fio desencapado.

Texto parece flexível. Você não precisa decidir nomes, tipos ou o que é obrigatório antes de começar. Um schema obriga você a decidir.

E funciona, por um tempo. Os modelos costumam repetir o formato, até o dia em que não repetem. O modelo mudou, o prompt mudou, ou só a entrada mudou. Um contrato que diz montante em vez de total.

E aqui está a armadilha de quem está começando. Pedir JSON no prompt, responda só com JSON, e achar que resolveu. Isso continua sendo texto. O modelo pode embrulhar em formatação, acrescentar uma vírgula ou esquecer uma chave.

Quanto custa

O pior custo é dado ruim em silêncio. Nada quebra. Cento e quarenta contratos sem total não geram exceção nenhuma. O financeiro só vê o buraco no fechamento do mês.

Depois, acoplamento escondido. O prompt da primeira etapa vira parte do contrato da segunda, e ninguém sabe disso. O parser mora em outro arquivo, outro repositório, talvez outro time.

Depois, medo. Qualquer ajuste de prompt ou troca de modelo vira risco. O time para de melhorar o extrator, porque a expressão regular do financeiro vai quebrar.

E tokens desperdiçados. Prosa feita para um parser gasta saída com palavras que ninguém lê. O valor total do contrato, impostos inclusos, é. Dezenas de tokens que um campo só não precisa.

Um desafio

Uma pergunta para você. O time pediu JSON no prompt, com as chaves total e data, e o código faz o parse. Uma vez por semana, a execução quebra por uma vírgula a mais, ou uma marcação de formatação em volta do objeto. Qual próximo passo elimina essa classe inteira de erro?

Usar a saída estruturada da API, com um schema, e validar os campos no código. O formato deixa de ser um pedido ao modelo e vira uma garantia da API.

Tentar de novo até o parse funcionar esconde a instabilidade. E no dia em que a variação for um texto onde devia haver um número, o parse funciona, e o dado ruim entra. Colocar três exemplos de JSON válido baixa a taxa, mas nunca zera. Você ainda dependeria do modelo obedecer uma instrução de formato.

O tratamento

O tratamento é uma refatoração chamada replace free text with structured output. O contrato entre as etapas fica explícito.

O CNPJ do fornecedor, a chave de acesso da nota, que pode faltar, o total, com tipo de dinheiro, e a lista de vencimentos.

A API garante a forma. O código lê o campo total, não uma frase. Valor total do contrato simplesmente não tem mais como existir. E um campo obrigatório que falta vira erro na hora. O documento vai para revisão humana, em vez de entrar no sistema como zero.

E muitas vezes tem um bônus. Se a segunda etapa só existia para transformar o texto em campos, ela pode sumir. A primeira chamada já devolve os campos.

Mas schema não substitui eval. Uma forma correta ainda pode trazer o CNPJ de uma empresa que não é a emissora. O eval mede se o valor está certo. O schema garante que o valor chegou como valor.

Quando ignorar

Quando dá para ignorar? Quando o destino é uma pessoa. Uma resposta de chat ou um e-mail para um cliente deve ser texto. O smell é texto entre máquinas.

Quando o texto é o produto. Uma etapa escreve o rascunho de um artigo, e outra revisa. Elas trocam texto de forma legítima. Estruture o que o código usa de fato, como a lista de problemas encontrados, ou se foi aprovado. Não o artigo em si.

E um protótipo descartável tudo bem. No dia em que o parser for para o sistema de verdade, o schema vai junto.

Um último caso, para afiar o olho. Um classificador de tickets responde com uma palavra só, cobrança, pedido ou outro, e o código compara o texto. Às vezes volta Cobrança com maiúscula e ponto final, e o ticket cai na fila errada. Isso é esse smell? É. Mesmo uma palavra é texto livre, se o seu código depende da forma exata dela. Um schema com uma lista fechada de valores resolve, com um campo só.

Fechamento

Então, a ideia para levar. Texto é para pessoas. Quando uma etapa entrega dado para o código, ou para outra etapa, o contrato precisa ser um schema, não uma frase. Senão o seu sistema funciona até o dia em que o modelo achar um jeito mais bonito de dizer total.

Na próxima aula, a gente faz a refatoração em si, passo a passo, com eval antes e depois: replace free text with structured output. Até lá.