smevals: framework leve para rodar evals em modelos de qualquer tamanho
O que é
smevals é um framework open-source (licença MIT, 145 estrelas no GitHub) criado pela Prime Radiant Inc. para rodar avaliações (evals) contra modelos de linguagem de qualquer tamanho. A instalação é feita via uv tool install smevals, pip install smevals ou diretamente com uvx smevals --help.
Conceitos principais
O framework organiza o trabalho em uma hierarquia clara:
- Eval: coleção de Tasks que mede uma capacidade específica do modelo (ex.: text-to-SQL, gerar SVG, validar código contra especificação).
- Suite: agrupamento opcional de Evals relacionados.
- Task: exercício individual que o modelo deve completar.
- Config: descreve o setup - modelo, parâmetros, system prompt, tools e o Runner a usar.
- Run: registro imutável da execução de um Task contra um Config. É possível rodar o mesmo par múltiplas vezes (
-n 5completa até 5 runs bem-sucedidos). - Grader: sequência configurada de Checks aplicada a cada Run para produzir um Grade.
- Checker: operação ou programa executável que implementa um tipo de verificação (ex.:
contains,xml-valid, ou scripts customizados como renderizar SVG e pedir a um LLM que avalie a imagem). - Grade: resultado final com score (0.0–1.0), outcome (pass/fail), métricas, tags e notas.
Estrutura de um Eval
Um Eval é qualquer diretório com um eval.yaml e subdiretórios tasks/, configs/, graders/ e checkers/. O README traz um exemplo completo: pedir que o modelo escreva um haiku e verificar se a resposta tem exatamente três linhas não vazias.
Contrato do Runner e do Checker
O Runner é um executável que recebe tudo via variáveis de ambiente (SMEVALS_MODEL, SMEVALS_PROMPT, SMEVALS_RUN_DIR, etc.) e escreve a resposta do modelo na saída padrão. Exit code zero significa sucesso; non-zero indica erro de infraestrutura (não é nota sobre o modelo).
O Checker segue contrato semelhante: recebe o diretório do Run e a configuração do Check via variáveis de ambiente, sinaliza pass/fail pelo exit code e pode emitir um JSON com score, metrics, tags, notes e details.
Comandos CLI
| Comando | Função |
|---|---|
smevals run |
Executa tasks contra modelos, com opção de grading automático (-g) e amostragem repetida (-n). |
smevals grade |
Aplica um Grader a runs ainda não avaliados; --regrade descarta e recria grades. |
smevals report |
Gera relatório markdown com leaderboard (média ± erro padrão, contagem de falhas, tags). |
smevals serve |
Sobe uma UI web ao vivo (porta 7001 por padrão) que atualiza conforme novos runs chegam. |
smevals build |
Gera um site estático autocontido com os resultados, agregável de múltiplos repositórios. |
Design decisions
- Runs são imutáveis; grading apenas adiciona arquivos sob
grades/. - Cada Grade guarda um snapshot byte-a-byte do Grader usado, garantindo reprodutibilidade.
- Runs falhos (erro de rede, crash do harness) nunca são avaliados nem contam para metas de amostragem.
- Múltiplos Graders podem coexistir no mesmo Eval (ex.: um determinístico barato e um baseado em LLM-judge).