raciocinio-br-mcp

A pergunta

Por que medir raciocínio clínico em português brasileiro

Resultados da avaliação

Rodada de 2026-09-20, modelo Qwen3.5-9B-Q4_K_M.gguf

O relatório de 2026-09-20 registrou 'local-model', que é o nome do .env, não o modelo. O modelo servido pelo endpoint local é Qwen3.5-9B-Q4_K_M.gguf (id de /v1/models). A partir da v0.1.0 o relatório grava esse id.

Dados extraídos de resultados/avaliacao-2026-09-20.md do projeto (repositório privado). Reproduza com uv run raciocinio-cli avaliar.

Onde ele falha

Os erros, com a hipótese da causa

Registrar onde erra é parte do projeto, não uma fraqueza a esconder. Vem do FALHAS-CONHECIDAS.md do projeto, que acompanha cada rodada de avaliação.

Continuam falhando na rodada publicada. Nenhuma das duas é falha do modelo.

Erros de rodadas anteriores, já explicados

Acertam na rodada publicada. Ficam aqui porque a causa deles diz muito sobre a métrica.

O léxico brasileiro

Um artefato de valor próprio, versionado

O mapeamento curado de termos (dados/lexico-br.yaml, versão 0.1.0, 12 entradas, revisão clínica pendente) pode ser usado independentemente do resto do projeto. Termo ambíguo nunca é normalizado em silêncio: o normalizador devolve as leituras e deixa a escolha para quem usa.

- termo_popular: pressão
  termo_tecnico: AMBIGUO
  tipo: sintoma
  observacao: >-
    Ambíguo de propósito: pode ser pressão arterial, sensação de aperto no peito
    ou peso na cabeça. O normalizador devolve as leituras, não escolhe.
  leituras:
    - pressão arterial
    - sensação de aperto torácico
    - cefaleia em peso
  revisado: false

Escopo coberto

Seis condições de medicina de família, e só

Cada uma com a diretriz de referência da Conitec. Fora deste escopo o sistema deve responder "fora do escopo": isso é decisão de design, não limitação temporária. O CID-10 principal fica pendente de decisão clínica.

A base, em números

Lidos em 2026-10-12. O repositório é privado até passar por revisão clínica.

O que ele não diz

Como funciona

Do texto livre à hipótese com procedência

1. 01 →

   Léxico

   Normaliza o vocabulário brasileiro do caso. Termo ambíguo é devolvido com as leituras, sem escolher.

2. 02 →

   Recuperação

   Busca full-text (DuckDB) na base de evidência dos PCDTs, com um piso de cobertura que decide se a pergunta está no escopo.

3. 03 →

   LLM local

   O modelo raciocina sobre os trechos recuperados, na sua máquina.

4. 04

   Estruturação com procedência

   Cada hipótese sai com citação literal, se a citação confere no documento, a confiança, e a lista do que ficou indeterminado.

As três tools

Exemplo: explicar_cobertura("DM2")

coletado_em é a data em que o PDF foi baixado da Conitec, não a da última reindexação. cids_no_texto são candidatos extraídos da seção de classificação CID-10 do próprio PCDT; o CID principal continua PENDENTE de decisão clínica.

{
  "consulta": "DM2",
  "no_escopo": true,
  "total_condicoes": 1,
  "condicoes": [
    {
      "condicao": "Diabete Melito Tipo 2",
      "slug": "diabete-melito-tipo-2",
      "cid10": "PENDENTE",
      "cids_no_texto": ["E11", "E11.2", "E11.3", "E11.4", "E11.5",
                        "E11.6", "E11.7", "E11.8", "E11.9"],
      "documento": "PCDT Diabete Melito Tipo 2",
      "portaria": "Portaria SCTIE/MS nº 13/2026 - 21/02/2026",
      "data_documento": "2026-02-21",
      "url": "https://www.gov.br/conitec/pt-br/midias/protocolos/2026/pcdt-diabete-melito-tipo-2/@@display-file/file",
      "status_conitec": "em atualização",
      "trechos_indexados": 208,
      "coletado_em": "2026-09-20 21:19:43.053156"
    }
  ],
  "aviso": "'DM2' casou com Diabete Melito Tipo 2 por sinônimo ou pelo léxico, não pelo nome da condição. Confira se é a condição que você procura: o escopo cobre só o que está listado aqui.",
  "revisao_clinica": "NÃO REVISADO CLINICAMENTE: gabaritos de avaliação, léxico e CID-10 deste experimento ainda não passaram por revisão clínica."
}

Numa base indexada antes da v0.1.0, os candidatos antigos (que traziam códigos de tabelas e referências) não vazam: cids_no_texto volta vazio e o aviso de reindexação se soma ao de sinônimo.

"cids_no_texto": [],
"aviso": "'DM2' casou com Diabete Melito Tipo 2 por sinônimo ou pelo léxico, não pelo nome da condição. Confira se é a condição que você procura: o escopo cobre só o que está listado aqui. A base foi indexada por uma versão antiga da extração de CID-10, que pegava códigos de tabelas e referências; os candidatos de Diabete Melito Tipo 2 foram omitidos. Rode 'raciocinio-cli coletar' para reindexar."

Como rodar

Reproduza a avaliação, não só use a ferramenta

Quem tem o código deveria conseguir rodar o mesmo harness de avaliação que gerou os números acima, não apenas ligar o servidor. Precisa de Python 3.12+, uv e um LLM local com API compatível com a da OpenAI.

# 1. na pasta do projeto: instalar e configurar
uv sync
cp .env.example .env

# 2. apontar o .env para o seu LLM local e conferir
uv run raciocinio-cli llm

# 3. montar a base de evidência (baixa e indexa as diretrizes, ~1 min)
uv run raciocinio-cli coletar

# 4. reproduzir a AVALIAÇÃO (roda os casos e gera o relatório)
uv run raciocinio-cli avaliar

# 5. registrar o servidor MCP (stdio) no Claude Code
claude mcp add raciocinio-br -- uv --directory /caminho/do/raciocinio-br-mcp run raciocinio-br-mcp

Atualizar a base (manual)

Não há timer: a base só muda quando alguém roda a coleta. Numa base indexada antes da v0.1.0, explicar_cobertura devolve cids_no_texto vazio e avisa para reindexar. A data em coletado_em é a do download do PDF, então reindexar sem --atualizar não a muda.

# base montada antes da v0.1.0: reindexar uma vez (sem rede, usa data/pdfs/)
uv run raciocinio-cli coletar

# versão nova de um PCDT na Conitec: baixar de novo e reavaliar
uv run raciocinio-cli coletar --atualizar
uv run raciocinio-cli avaliar