Subir um nível quando a confiança cai

Você precisa classificar dez mil empresas em um código de atividade — CNAE, setor interno, categoria de fornecedor. A maioria é fácil: um banco regional é um banco regional. Algumas não são: a empresa que acabou de vender um dos dois braços do negócio, a startup que descreve a atividade que pretende exercer.

O problema é que a resposta difícil chega com a mesma cara da resposta fácil. O modelo escolhe uma categoria de todo jeito, e nada no formato distingue as duas.

Por que a solução ingênua falha

Três caminhos comuns, três custos.

Aceitar todas as respostas. Você fica com uma base em que uma fração das classificações está errada e você não sabe qual. É o pior dos mundos, porque a base parece completa.

Mandar as difíceis para revisão humana. Certo em tese, caro na prática: se um terço dos casos vira fila, a automação economizou pouco. E a fila costuma crescer mais rápido do que se esvazia.

Chamar um modelo maior para as difíceis. Funciona e custa uma segunda chamada, com outra integração para manter.

Nenhum dos três usa o que já está na resposta: a informação de que o modelo não tinha certeza.

O desenho das perguntas

Uma pergunta só. Um Choice com as categorias específicas como opções, cada uma descrita pelo que contém. E então a decisão em código lê a confiança da resposta:

CONFIANTE = 0.9

def classificar(documento: str) -> dict:
    resposta = cliente.system_one(
        state=documento,
        questions={"grupo": Choice(instructions=PERGUNTA, criteria=CRITERIOS)},
    ).answers["grupo"]

    seguro = resposta.confidence >= CONFIANTE
    return {
        "nivel": "grupo" if seguro else "divisao",
        "rotulo": resposta.choice if seguro else divisao_de(resposta.choice),
        "confianca": resposta.confidence,
    }

O truque que faz a receita ser barata: a categoria ampla se deduz da específica. Se o modelo respondeu “fabricação de produtos químicos” com confiança baixa, você já sabe que aquilo pertence à indústria de transformação — e reportar “indústria de transformação” não custa chamada nova, porque a hierarquia é sua e está em código.

Duas escolhas de projeto valem registro. A primeira: ler confidence e não a probabilidade da opção vencedora. Uma vencedora com 0,45 tendo a segunda em 0,44 é uma situação; uma vencedora com 0,45 e o resto espalhado fino é outra. A confiança resume a forma da distribuição e separa as duas, como explica confiança.

A segunda: descrever cada opção pelo que ela contém, e não pelo nome. No experimento, boa parte dos grupos não tem nome próprio útil, então cada um é descrito pelas atividades que existem dentro dele — que é justamente o que uma pessoa lendo o documento compararia.

O que o experimento oficial mediu

O cookbook classifica 60 relatórios anuais da SEC, usando só a seção em que a empresa descreve o próprio negócio (de 700 a 2.200 palavras, 1.438 em média, entre 1993 e 2024). A taxonomia é o SIC: 444 códigos que se agrupam em 75 grupos maiores e 10 divisões. A pergunta tem os 75 grupos como opções. Corte de confiança em 0,90. Números publicados pela TypeSafe, com o jev-1.12, em 12 de agosto de 2026:

O corte de 0,90 partiu os 60 documentos quase exatamente no meio. Na metade confiante, o grupo específico acerta nove de cada dez. Na metade insegura, nomear o grupo erra mais do que acerta — e as mesmas respostas, reportadas uma camada acima, chegam a cerca de 70%.

O mais interessante é por que os casos difíceis eram difíceis, e isso o cookbook mostra: as três confianças mais baixas eram duas empresas em estágio inicial descrevendo um negócio que pretendiam começar e uma que havia vendido um de dois segmentos semanas antes de declarar. Não é ruído do modelo: é ambiguidade real no documento, e a confiança a detectou.

Uma ressalva de método que o próprio cookbook registra: o código SIC é autodeclarado por quem preenche a declaração e envelhece quando a empresa muda de atividade e mantém o código. O conjunto foi filtrado para declarações cujo texto sustenta o código, para medir a receita e não a qualidade do cadastro.

O que muda em português

A receita encaixa bem no Brasil porque as nossas taxonomias são hierárquicas de nascença. O CNAE tem seção, divisão, grupo, classe e subclasse — cinco níveis para subir ou descer. A ideia se aplica direto: classifique na classe, e quando a confiança cair, responda o grupo.

Dois cuidados. Primeiro, o número de opções: uma pergunta com todas as classes do CNAE passa do teto de 255 opções de um Choice, e o cookbook sugere que a confiabilidade já cai perto de 240. A saída é classificar em dois passos — seção primeiro, classe dentro dela — o que é a mesma técnica da classificação hierárquica.

Segundo, a descrição das opções. Descrições oficiais de CNAE são jurídicas e cheias de “exceto”. Vale reescrever cada opção pelo que a empresa faz, com exemplos, como discutido em critérios que separam. E, como a TypeSafe declara que o inglês é a língua principal de treino, calibre o corte com os seus próprios documentos em vez de copiar o 0,90.

Onde isso quebra

• Sem hierarquia, não há para onde subir. Aí a confiança baixa volta a significar fila humana ou segundo estágio, como em padrões.
• Divisão grossa demais para agir. Se a categoria ampla não permite nenhuma decisão de negócio, a receita só adiou o problema; nesse caso, o ramo de confiança baixa deve ir para uma pessoa mesmo.
• Muitas opções. Acima de algumas centenas, classifique em passos.
• Documento longo. O relatório inteiro no state infla a entrada e derruba acurácia; o experimento usa só a seção que descreve o negócio, e esse recorte é parte da receita. Ver state.

Quando a incerteza deve virar fila de curador em vez de resposta mais ampla, veja alinhar entidades. O índice está em receitas.