Nexttag.Ai.Evals 0.1.0

Nexttag.Ai.Evals

Avalia a qualidade das saídas de LLMs/agentes (estilo LangSmith evals): datasets, evaluators determinísticos e LLM-as-judge, com relatório agregado. É a medição de qualidade que o tracing (Langfuse) não cobre.

O que é e quando usar

Tracing (Langfuse) responde "o que aconteceu nesta chamada?" — tokens, custo, latência, prompt/resposta. Evals responde uma pergunta diferente: "o quão BOA é a saída?" — de forma sistemática, sobre muitos casos, com um número comparável.

Use quando precisar:

• medir a qualidade de um agente/grafo/prompt sobre um conjunto de casos representativos;
• evitar regressão: provar que a versão nova de um prompt não piorou antes de subir (gate de CI);
• comparar alternativas (modelo A vs B, prompt V1 vs V2) com o mesmo critério.

A ideia central, igual ao LangSmith/ragas: você tem um dataset de casos, roda seu alvo sobre eles, e um conjunto de evaluators dá uma nota de 0 a 1 para cada saída. O relatório agrega tudo.

Conceitos

Como funciona (o fluxo)

dataset (casos)  ──►  EvalRunner  ──►  para cada caso:
                                         output = alvo(caso)
                                         para cada evaluator: EvalResult { score 0..1, passed, reason }
                                       ──►  EvalReport agregado

Modelo de pontuação:

• Cada EvalResult traz um Score de 0 a 1 e um Passed (aprovado segundo o limiar daquele evaluator).
• Um caso (EvalCaseResult) tem Score = média dos evaluators e Passed = todos aprovaram.
• O relatório (EvalReport) traz MeanScore (média geral), PassRate (fração aprovada), MeanScoreByEvaluator (para comparar critérios) e Failures (casos reprovados, com a saída produzida).

Evaluators determinísticos (ExactMatch/Contains/Regex) dão 0 ou 1. O LLM-judge dá uma nota contínua (ex.: 0.8) pedindo a um modelo que pontue segundo um critério em linguagem natural — útil quando não há um gabarito exato (resumos, respostas abertas, tom).

Instalar

dotnet add package Nexttag.Ai.Evals

Requer .NET 10. Depende de Microsoft.Extensions.AI (para o LLM-judge). Sem dependência do Agent Framework.

Registrar (Program.cs)

Sem registro de DI — instancie EvalRunner direto. Para o LLM-judge, passe um IChatClient (o mesmo que você já usa, ex.: apontando para o gateway litellm).

Configurar

Sem configuração obrigatória. O LLM-judge usa o IChatClient que você fornecer.

Usar

1. Monte um dataset

using Nexttag.Ai.Evals;

// Em memória
var dataset = EvalDataset.FromCases(
    new EvalCase("c1", input: "Capital da França?", expected: "Paris"),
    new EvalCase("c2", input: "Capital do Brasil?", expected: "Brasília"));

// Ou de um arquivo JSONL (uma linha por caso: {"id"?,"input","expected"?,"metadata"?})
var deArquivo = EvalDataset.FromJsonl("casos.jsonl");

2. Escolha evaluators

// Determinísticos (sem LLM) — dão 0 ou 1
Evaluators.ExactMatch();              // saída == expected (ignora caixa/espaços)
Evaluators.Contains();                // saída contém o expected
Evaluators.Regex(@"\d{5}-?\d{3}");    // saída casa com o padrão
Evaluators.Custom("tamanho", (caso, saida) =>
    new EvalResult("tamanho", saida.Length <= 280 ? 1 : 0, saida.Length <= 280, null));

// LLM-as-judge: pontua 0..1 segundo um critério em linguagem natural
var juiz = new LlmJudgeEvaluator(chatClient,
    criterio: "A resposta responde à pergunta de forma correta e completa?",
    limiarAprovacao: 0.7);

3. Rode sobre um alvo e leia o relatório

// O alvo é qualquer função caso → saída (seu agente, grafo, prompt, endpoint...)
EvalTarget alvo = async (caso, ct) => await meuAgente.ResponderAsync(caso.Input, ct);

var report = await new EvalRunner().RunAsync(
    dataset, alvo,
    evaluators: [Evaluators.Contains(), juiz]);   // o caso passa se TODOS aprovarem

Console.WriteLine($"Score médio: {report.MeanScore:P0} | Aprovação: {report.PassRate:P0}");
foreach (var falha in report.Failures)
    Console.WriteLine($"  ✗ {falha.Case.Id}: {falha.Output}");

Receitas

Regressão de prompt (compare duas versões):

var antigo = await runner.RunAsync(dataset, AlvoComPromptV1, evals);
var novo   = await runner.RunAsync(dataset, AlvoComPromptV2, evals);
if (novo.MeanScore < antigo.MeanScore)
    throw new Exception($"Regressão: {novo.MeanScore:P0} < {antigo.MeanScore:P0}");

Avaliar um grafo do Nexttag.Ai.Graph:

EvalTarget alvo = async (caso, ct) =>
{
    var final = await grafo.RunAsync(new RagState { Pergunta = caso.Input }, ct);
    return final.Resposta ?? "";
};
var report = await new EvalRunner().RunAsync(dataset, alvo, [juiz]);

Logar cada caso (ex.: progresso ou score no Langfuse):

var opts = new EvalRunOptions(
    MaxConcurrency: 8,
    OnCaseEvaluated: cr => Console.WriteLine($"{cr.Case.Id}: {cr.Score:P0}"));
await runner.RunAsync(dataset, alvo, evals, opts);

Notas

• EvalCaseResult.Passed = todos os evaluators aprovaram; Score = média dos scores (0..1).
• O LLM-judge instrui o modelo a devolver só {"score":0..1,"reason":"..."}; se vier sem JSON válido, o caso recebe score 0 com o motivo (não quebra a execução). Usa Temperature 0 por padrão.
• MaxConcurrency controla o paralelismo dos casos (padrão 4) — cuidado com rate limit do provedor.
• Para rastrear tokens/custo do juiz, use um IChatClient apontando para o gateway litellm (cai no Langfuse automaticamente).
• A ordem do relatório segue a ordem do dataset.