npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@precisa-saude/medbench-harness

v2.7.0

Published

Harness reproduzível de avaliação de LLMs em provas médicas brasileiras

Readme

@precisa-saude/medbench-harness

Harness reproduzível de avaliação de LLMs em provas médicas brasileiras.


Sobre

Pipeline de avaliação que roda uma questão por requisição HTTP, três execuções por modelo, sem ferramentas, sem few-shot, com log bruto (raw.jsonl) persistido para re-scoring determinístico. Acompanha providers para Anthropic, OpenAI, Google e qualquer backend compatível com a API do OpenAI (Ollama local, Maritaca, Together, OpenRouter).

É o pipeline por trás do leaderboard em medbench-brasil.ia.br. Depende de @precisa-saude/medbench-dataset.

Garantias de integridade

Seguem literalmente o ADR-0002 — alterar qualquer uma exige novo ADR e aprovação do mantenedor:

  1. System prompt literal e fixo: Responda a seguinte questão de múltipla escolha selecionando a letra correta (A, B, C ou D).
  2. Single-turn absoluto — uma questão por requisição, sem histórico, sem few-shot, sem contexto de outras questões.
  3. Zero tools, zero connectors, zero web search, zero code interpreter, zero RAG em qualquer provider.
  4. Três execuções independentes por modelo; intervalo de confiança 95% pelo método de Wilson.
  5. Todos os parâmetros de API registrados em results/<edition>/<model>.raw.jsonl (uma linha por requisição).
  6. Modelos locais em completion puro, sem scaffolding de ferramentas.

Instalação

pnpm add @precisa-saude/medbench-harness
# ou
npm install @precisa-saude/medbench-harness

A CLI fica disponível como o binário medbench. Requer Node ≥ 20.

Uso como CLI

Compatibilidade dos novos candidatos

Os IDs exatos gpt-6.1-terra, claude-haiku-5-5 e gemini-4-argon possuem parâmetros específicos de raciocínio alto, sem sampling. Terra e Haiku usam limite de 8.192 tokens; Argon usa 32.768 e timeout de 15 minutos. Essas regras não alteram os requests dos modelos anteriores. OpenAI e Google também registram o motivo de parada quando declarado pela API.

O piloto operacional separado da CLI está documentado em plano-shortlist-pilots.md. Ele não publica scores e interrompe cada modelo na primeira falha, sem retry. O argumento final openrouter seleciona somente Terra e Argon nessa rota, com OPENROUTER_API_KEY, logs separados e fallback desabilitado:

node packages/eval-harness/scripts/shortlist-pilots.mjs /caminho/.env.local openrouter

Execute a partir da raiz após o build. O script recusa repetir um piloto cujos arquivos de saída já existem, preservando as tentativas anteriores.

A avaliação completa das duas novas edições está especificada em plano-shortlist-evaluations.md. O executor operacional não reutiliza pilotos nem sobrescreve resultados:

node packages/eval-harness/scripts/shortlist-evaluations.mjs --dry-run
node packages/eval-harness/scripts/shortlist-evaluations.mjs /caminho/.env.local

São seis combinações, 1.494 respostas esperadas e três runs por questão. Falhas transitórias seguem o retry canônico, com cada tentativa no ledger. Parsing inválido ou parada anormal interrompem a combinação sem publicar um score parcial. Uma retomada após interrupção exige revisar os logs primeiro.

A retomada específica autorizada de Argon 2026/1 usa scripts/resume-argon.mjs. Ela preserva cópias dos arquivos interrompidos, registra hashes e a exclusão operacional em um manifesto, reutiliza 44 respostas e limita a continuação a 208 chamadas sem retries. Não é um comando genérico de restart e recusa repetir uma retomada já iniciada.

Dois subcomandos: smoke (pré-flight, ~8 amostras estratificadas) e eval (run completo).

medbench smoke — validação de provider e parser

Sempre rode antes de queimar créditos num modelo novo: valida que o provider responde e que o parser reconhece o formato emitido. Aborta com código não-zero se a taxa de parse correto fica abaixo do threshold.

medbench smoke \
  --backend anthropic \
  --model claude-opus-4-7 \
  --edition revalida-2025-1 \
  --samples 8 \
  --threshold 0.7

medbench eval — avaliação completa

medbench eval \
  --backend openrouter \
  --model google/gemini-3.1-pro-preview \
  --cutoff 2025-11-01 \
  --edition revalida-2025-1 \
  --runs 3

Flags

Comuns a smoke e eval:

| Flag | Valor | Padrão | | --------------- | ------------------------------------------------------------------------------------------- | --------------------- | | --backend | anthropic | openai | google | ollama | maritaca | together | openrouter | obrigatório | | --model | identificador do modelo (ex.: claude-opus-4-7, gpt-5, google/gemini-3.1-pro-preview) | obrigatório | | --edition | revalida-2025-1, revalida-2024-2, etc. | revalida-2025-1 | | --label | nome legível exibido no site | derivado do modelo | | --cutoff | data de corte de treino do modelo (YYYY-MM-DD) | — | | --concurrency | requisições simultâneas | 10 (APIs), 1 (ollama) | | --apiKey | chave explícita (sobrescreve variável de ambiente) | — | | --baseUrl | endpoint custom (ollama, maritaca, together, openrouter) | padrão do backend |

Específicas de eval:

| Flag | Valor | Padrão | | -------------- | ---------------------------------------- | ---------- | | --runs | execuções por questão | 3 | | --out | diretório de saída | results/ | | --no-raw-log | desabilita JSONL bruto | ativado | | --restart | descarta JSONL prévio e recomeça do zero | retoma |

Específicas de smoke:

| Flag | Valor | Padrão | | ------------- | ------------------------------------------- | ------ | | --samples | número de questões estratificadas | 8 | | --threshold | taxa mínima de parses corretos para aprovar | 0.7 |

Uso como biblioteca

Consumo e auditoria de chamadas

Novas respostas incluem usage quando a API informa tokens válidos: inputTokens inclui cache e outputTokens inclui raciocínio. Nunca somar reasoningTokens novamente à saída. O score inclui o agregado e a cobertura callsWithUsage/totalCalls; ausência significa desconhecido, não gratuito. Raws antigos continuam legíveis e não recebem estimativas de tokens.

Com cobertura completa, o agregado também inclui maxInputTokensPerCall, calculado dos tokens de entrada observados por chamada (incluindo cache). Ele permite confirmar a faixa de preço por tamanho do prompt. Em cobertura parcial, fica ausente. rescore --from-raw o deriva offline de raws com usage, sem nova inferência; rescore de scored JSON apenas preserva o que já existe.

eval e smoke registram cada tentativa em results/<edition>/<model>.<eval|smoke>.requests.jsonl, inclusive retries e erros. O ledger não é truncado por --restart e permanece ativo com --no-raw-log. Use --out DIR para mudar o destino. A CLI imprime somente o consumo novo da invocação; o agregado do score também inclui respostas reutilizadas por resume. rescore preserva consumo sem criar gasto novo.

Para a biblioteca, persista RunConfig.onRequestAttempt além de onRawResponse; o primeiro recebe um evento por tentativa. observeRequest permite instrumentar chamadas individuais, como pilotos. UUIDs de tentativa ligam o ledger aos raws. Falha ao persistir auditoria interrompe o lote.

O ledger mede consumo observado, não faturamento completo: tentativas sem usage, respostas perdidas ou processos interrompidos podem ter sido cobrados. Não somar raw e ledger. Para concatenar ledgers copiados, deduplicar por attemptId. Preços e custos em USD não são gravados nos resultados; estimativa por tabela e cobrança conciliada são conceitos distintos. Ver ADR 0005.

import { runEvaluation, anthropicProvider, SYSTEM_PROMPT } from '@precisa-saude/medbench-harness';
import type { Provider, RunConfig } from '@precisa-saude/medbench-harness';

const provider = anthropicProvider({
  model: 'claude-opus-4-7',
  trainingCutoff: '2025-03-01',
});

const result = await runEvaluation(provider, {
  editions: ['revalida-2025-1'],
  runsPerQuestion: 3,
  concurrency: 10,
  excludeImages: true,
  excludeTables: true,
  onRawResponse: (record) => {
    // persista `record` onde quiser — ele tem requestParams, rawResponse, parsed, correct
  },
});

console.log(result.accuracy, result.ci95, result.contaminationSplit);

Se você só quer o system prompt literal (por exemplo, para citar no seu próprio site de metodologia), use a export secundária:

import { SYSTEM_PROMPT } from '@precisa-saude/medbench-harness/prompt';

Exports

Funções: runEvaluation, scoreRun, parseLetter. Providers: anthropicProvider, openAiProvider, googleProvider, openAiCompatProvider (usado por ollama, maritaca, together, openrouter). Constante: SYSTEM_PROMPT. Tipos: Provider, ProviderResponse, RunConfig, EvaluationResult, RawResponseRecord.

Formato de saída

Cada medbench eval produz, em results/<edition>/<model-slug>.*:

  • <model>.json — agregado com accuracy, ci95, perQuestion[], perSpecialty, contaminationSplit: { clean, contaminated }, parâmetros da run.
  • <model>.raw.jsonl — uma linha por requisição, com requestParams (inclusive system prompt verbatim), rawResponse, modelId, editionId, questionId, run, elapsedMs, parsed, correct. Re-scoring determinístico a partir deste arquivo.

Variáveis de ambiente

Conforme o --backend escolhido:

| Backend | Variável | | ------------ | -------------------- | | anthropic | ANTHROPIC_API_KEY | | openai | OPENAI_API_KEY | | google | GOOGLE_API_KEY | | openrouter | OPENROUTER_API_KEY | | maritaca | MARITACA_API_KEY | | together | TOGETHER_API_KEY | | ollama | — (roda local) |

Carregadas automaticamente via dotenv a partir de .env.local (preferido) ou .env no cwd — não é preciso export no shell. Para começar, copie o .env.example da raiz do repo para .env.local e preencha as chaves dos backends que vai usar.

Licença

Apache-2.0.

Links