@polymorphism-tech/morph-spec 8.34.2 → 8.35.1

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/Evals/EvalFixture.cs

@@ -0,0 +1,463 @@
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.AI.Evaluation;
+using Microsoft.Extensions.AI.Evaluation.Reporting;
+using Microsoft.Extensions.AI.Evaluation.Reporting.Storage;
+
+namespace Morph.AiKit.Evals;
+
+/// <summary>O que uma execucao de cenario produziu.</summary>
+/// <param name="Scenario">A chave do cenario na cache (<c>{agente}/{tenant}/{nome}</c>).</param>
+/// <param name="Passed">Se TODAS as assercoes deterministicas se sustentaram.</param>
+/// <param name="Outcomes">Um veredito por assercao, na ordem do dataset.</param>
+/// <param name="Result">O resultado completo da biblioteca, com as metricas de juizo junto.</param>
+public sealed record EvalScenarioResult(
+    string Scenario,
+    bool Passed,
+    IReadOnlyList<EvalAssertionOutcome> Outcomes,
+    EvaluationResult Result);
+
+/// <summary>
+/// Monta a configuracao de eval com cache em disco de TTL explicito, roda os cenarios do
+/// dataset versionado e escreve o sumario que o CLI le.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <b>A montagem inteira existe para uma frase: com a cache quente, o eval roda sem
+/// credencial e sem rede.</b> O caminho e este — a biblioteca embrulha o cliente interno num
+/// cliente de cache; no HIT o interno nunca e invocado; em modo offline o interno e o
+/// <see cref="OfflineChatClient"/>, que recusa. Logo, ou tudo resolve pela cache, ou a suite
+/// fica vermelha nomeando o cenario que faltou. Nunca <c>skip</c>: gate verde sobre
+/// verificacao que nao aconteceu e o modo de falha que este harness mais paga para evitar.
+/// </para>
+/// <para>
+/// <b>Cache e resultados vivem em raizes DIFERENTES</b>, e isso e uma decisao, nao um
+/// detalhe: os resultados carregam latencia, uso de tokens e o flag de cache hit, todos
+/// nao-deterministicos. Numa raiz so, commitar a cache arrastaria os resultados junto e
+/// produziria diff em toda rodada, sem sinal nenhum. Separar por CONSTRUCAO (duas raizes) e
+/// mais forte que separar por <c>.gitignore</c>: uma regra de ignore dentro de um diretorio
+/// commitado e uma regra que a proxima pessoa remove sem entender.
+/// </para>
+/// <para>
+/// <b>Uma <c>ReportingConfiguration</c> por cenario</b>, e nao uma para a suite, porque as
+/// assercoes deterministicas SAO os avaliadores e elas mudam a cada cenario. A alternativa
+/// seria um avaliador com estado mutavel entre cenarios — barato de escrever e caro de
+/// depurar no dia em que dois cenarios rodarem fora de ordem.
+/// </para>
+/// </remarks>
+public sealed class EvalFixture : IAsyncDisposable
+{
+    /// <summary>
+    /// O nome do cenario em execucao, por indirecao.
+    /// </summary>
+    /// <remarks>
+    /// O <see cref="OfflineChatClient"/> e construido ANTES do fixture (ele e o cliente
+    /// interno dele) e precisa nomear, na mensagem de miss, o cenario que esta rodando
+    /// AGORA. Um nome capturado na construcao nomearia sempre o primeiro cenario, e a
+    /// mensagem mandaria o leitor investigar o cenario errado.
+    /// </remarks>
+    private sealed class ScenarioCursor
+    {
+        public string Name { get; set; } = "(nenhum)";
+    }
+
+    private readonly List<EvalScenarioResult> _results = [];
+    private readonly ScenarioCursor _cursor;
+    private readonly IChatClient _inner;
+    private readonly OfflineChatClient? _offline;
+    private readonly CountingChatClient? _counting;
+    private readonly IReadOnlyList<IEvaluator> _quality;
+    private readonly DiskBasedResultStore _resultStore;
+
+    private EvalFixture(
+        EvalCacheOptions options,
+        EvalCacheStampCheck stampCheck,
+        ScenarioCursor cursor,
+        IChatClient inner,
+        OfflineChatClient? offline,
+        CountingChatClient? counting,
+        IReadOnlyList<IEvaluator> quality)
+    {
+        Options = options;
+        StampCheck = stampCheck;
+        _cursor = cursor;
+        _inner = inner;
+        _offline = offline;
+        _counting = counting;
+        _quality = quality;
+        _resultStore = new DiskBasedResultStore(options.ResultsRoot);
+    }
+
+    /// <summary>Nome da execucao no store de resultados. Estavel, porque os resultados nao se commitam.</summary>
+    public const string ExecutionName = "morph-eval";
+
+    /// <summary>A configuracao efetiva desta execucao.</summary>
+    public EvalCacheOptions Options { get; }
+
+    /// <summary>
+    /// O veredito do carimbo, apurado UMA vez na construcao — antes de avaliar qualquer
+    /// cenario. Nao faz sentido pagar o relogio de uma suite para descobrir no fim que a
+    /// cache nao servia.
+    /// </summary>
+    public EvalCacheStampCheck StampCheck { get; }
+
+    /// <summary>
+    /// O cliente offline, quando o modo e <see cref="EvalMode.Offline"/>. E por ele que se
+    /// mede "zero invocacoes do cliente interno" — a prova de que nenhuma chamada paga foi
+    /// feita.
+    /// </summary>
+    public OfflineChatClient? Offline => _offline;
+
+    /// <summary>Quantas vezes a cache falhou e a chamada desceu ao cliente interno.</summary>
+    public int Misses => _offline?.Invocations ?? _counting?.Calls ?? 0;
+
+    /// <summary>Os resultados acumulados, na ordem em que os cenarios rodaram.</summary>
+    public IReadOnlyList<EvalScenarioResult> Results => _results;
+
+    /// <summary>O sumario do que rodou ate agora.</summary>
+    public EvalRunSummary Summary => new()
+    {
+        Scenarios = _results.Count,
+        Passed = _results.Count(r => r.Passed),
+        Failed = _results.Count(r => !r.Passed),
+        Cache = Misses == 0 ? EvalCacheState.Warm : EvalCacheState.Cold,
+        Stamp = StampCheck.Verdict.ToString().ToLowerInvariant(),
+        Misses = Misses,
+        Provider = Options.ProviderName,
+        Model = Options.DefaultModelId,
+        Quality = CollectQuality(),
+        Failures = CollectFailures(),
+    };
+
+    /// <summary>
+    /// Uma entrada por assercao REPROVADA, com o cenario que a carregava.
+    /// </summary>
+    /// <remarks>
+    /// Percorre as assercoes reprovadas, e nao os cenarios reprovados: o cenario diz ONDE, a
+    /// assercao diz O QUE. Um sumario que so contasse cenarios obrigaria quem le a reabrir o
+    /// dataset para descobrir qual regua quebrou — que e exatamente a investigacao que a
+    /// mensagem existe para dispensar.
+    /// </remarks>
+    private IReadOnlyList<EvalFailureDetail> CollectFailures()
+    {
+        var failures = new List<EvalFailureDetail>();
+
+        foreach (var result in _results.Where(r => !r.Passed))
+        {
+            var reproved = result.Outcomes.Where(o => !o.Passed).ToList();
+
+            // O cenario SEM assercao nenhuma reprova por vacuidade (ele nao cobra nada), e
+            // nesse caso nao existe outcome reprovado para nomear. Sem esta linha ele seria
+            // contado em `Failed` e invisivel em `Failures` — um numero sem frase, que e a
+            // metade exata do defeito que este tipo existe para fechar.
+            if (reproved.Count == 0)
+            {
+                failures.Add(new EvalFailureDetail(
+                    result.Scenario,
+                    "(nenhuma)",
+                    "(nenhuma)",
+                    "FALHOU: cenario sem assercao deterministica — ele nao cobra nada"));
+                continue;
+            }
+
+            failures.AddRange(reproved.Select(o => new EvalFailureDetail(
+                result.Scenario,
+                o.Assertion ?? "(assercao sem nome)",
+                o.Kind?.ToString() ?? "(regua desconhecida)",
+                o.Reason)));
+        }
+
+        return failures;
+    }
+
+    /// <summary>
+    /// Constroi o fixture a partir das variaveis que o CLI DITA.
+    /// </summary>
+    /// <remarks>
+    /// Fora do CLI um projeto pode montar <see cref="EvalCacheOptions"/> a mao e chamar
+    /// <see cref="Create"/>; as variaveis existem para que a MESMA suite seja executavel pelo
+    /// <c>verify</c> sem um segundo caminho de configuracao.
+    /// </remarks>
+    /// <param name="liveClient">
+    /// O cliente real. Obrigatorio em <see cref="EvalMode.Refresh"/> e
+    /// <see cref="EvalMode.Online"/>; ignorado em <see cref="EvalMode.Offline"/>.
+    /// </param>
+    /// <param name="qualityEvaluators">Avaliadores de juizo. Reportados, nunca decisivos.</param>
+    /// <param name="timeProvider">Relogio, para a checagem de pin no futuro.</param>
+    public static EvalFixture FromEnvironment(
+        IChatClient? liveClient = null,
+        IEnumerable<IEvaluator>? qualityEvaluators = null,
+        TimeProvider? timeProvider = null)
+    {
+        var cacheRoot = Required("MORPH_EVAL_CACHE");
+        var beside = Path.GetDirectoryName(Path.GetFullPath(cacheRoot))
+            ?? throw new InvalidOperationException($"eval-cache-path-invalid: \"{cacheRoot}\" nao tem diretorio pai.");
+
+        var options = new EvalCacheOptions
+        {
+            CacheRoot = cacheRoot,
+            DatasetRoot = Environment.GetEnvironmentVariable("MORPH_EVAL_DATASET") ?? Path.Combine(beside, "eval-datasets"),
+            ResultsRoot = Environment.GetEnvironmentVariable("MORPH_EVAL_RESULTS") ?? Path.Combine(beside, "eval-results"),
+            Mode = ParseMode(Environment.GetEnvironmentVariable("MORPH_EVAL_MODE")),
+            // Explicito e longo: o default da biblioteca (14 dias) apagaria a arvore
+            // commitada durante uma leitura. Ver EvalCacheOptions.
+            TimeToLive = TimeSpan.FromDays(3650),
+            ProviderName = Environment.GetEnvironmentVariable("MORPH_EVAL_PROVIDER") ?? "morph-eval",
+            DefaultModelId = Environment.GetEnvironmentVariable("MORPH_EVAL_MODEL"),
+            SummaryPath = Environment.GetEnvironmentVariable("MORPH_EVAL_SUMMARY"),
+            EnvFile = Environment.GetEnvironmentVariable("MORPH_EVAL_ENVFILE") ?? ".env.evals",
+            Pin = ParsePin(Environment.GetEnvironmentVariable("MORPH_EVAL_PIN")),
+        };
+
+        return Create(options, liveClient, qualityEvaluators, timeProvider);
+    }
+
+    /// <summary>Constroi o fixture a partir de opcoes explicitas.</summary>
+    /// <exception cref="ArgumentOutOfRangeException">TTL abaixo do piso — ver <see cref="EvalCacheOptions.MinimumTimeToLive"/>.</exception>
+    /// <exception cref="InvalidOperationException">Carimbo ausente ou divergente em modo de leitura; ou modo de escrita sem cliente real.</exception>
+    public static EvalFixture Create(
+        EvalCacheOptions options,
+        IChatClient? liveClient = null,
+        IEnumerable<IEvaluator>? qualityEvaluators = null,
+        TimeProvider? timeProvider = null)
+    {
+        ArgumentNullException.ThrowIfNull(options);
+
+        if (options.TimeToLive < EvalCacheOptions.MinimumTimeToLive)
+        {
+            throw new ArgumentOutOfRangeException(
+                nameof(options),
+                options.TimeToLive,
+                $"eval-cache-ttl-too-short: o tempo de vida das entradas e {options.TimeToLive.TotalDays:0} dias, "
+              + $"abaixo do piso de {EvalCacheOptions.MinimumTimeToLive.TotalDays:0}. "
+              + "A expiracao da cache e DESTRUTIVA NA LEITURA: uma entrada vencida faz o provedor apagar o "
+              + "diretorio da chave antes de devolver nulo. Numa arvore commitada isso significa miss em massa "
+              + "(e git status sujo) num dia em que ninguem mexeu em nada.");
+        }
+
+        var clock = timeProvider ?? TimeProvider.System;
+        IReadOnlyList<IEvaluator> quality = qualityEvaluators is null ? [] : [.. qualityEvaluators];
+
+        // O carimbo so e COBRADO nos modos que LEEM a cache. Em Refresh a arvore esta sendo
+        // (re)escrita — cobrar carimbo ali tornaria impossivel criar a primeira cache.
+        var stampCheck = options.Mode == EvalMode.Refresh || options.Pin is null
+            ? new EvalCacheStampCheck(
+                EvalStampVerdict.Ok,
+                options.Pin is null ? "sem pin declarado" : "modo refresh: o carimbo sera reescrito")
+            : EvalCacheStamp.Check(options.CacheRoot, options.Pin, clock);
+
+        if (!stampCheck.IsOk)
+        {
+            throw new InvalidOperationException(stampCheck.Reason);
+        }
+
+        var cursor = new ScenarioCursor();
+        OfflineChatClient? offline = null;
+        CountingChatClient? counting = null;
+        IChatClient inner;
+
+        if (options.Mode == EvalMode.Offline)
+        {
+            offline = new OfflineChatClient(
+                options.ProviderName,
+                options.DefaultModelId,
+                options.CacheRoot,
+                options.EnvFile,
+                () => cursor.Name);
+            inner = offline;
+        }
+        else
+        {
+            counting = new CountingChatClient(
+                liveClient ?? throw new InvalidOperationException(
+                    $"eval-live-client-missing: o modo {options.Mode} exige um IChatClient real. "
+                  + "Sem ele nao ha o que gravar na cache — e inventar um cliente aqui produziria uma arvore "
+                  + "de cache que nao corresponde a provider nenhum."));
+            inner = counting;
+        }
+
+        return new EvalFixture(options, stampCheck, cursor, inner, offline, counting, quality);
+    }
+
+    /// <summary>
+    /// Roda TODOS os cenarios do dataset e escreve o sumario, quando ha caminho para ele.
+    /// </summary>
+    /// <exception cref="InvalidOperationException">Dataset sem nenhum cenario — uma suite de eval que avalia zero cenarios e sai verde e um guardrail inerte.</exception>
+    public async Task<EvalRunSummary> RunAllAsync(CancellationToken cancellationToken = default)
+    {
+        var scenarios = EvalScenario.LoadAll(Options.DatasetRoot);
+        if (scenarios.Count == 0)
+        {
+            throw new InvalidOperationException(
+                $"eval-empty-run: o dataset em \"{Options.DatasetRoot}\" nao tem nenhum cenario. "
+              + "Uma suite de eval que avalia zero cenarios e sai verde e exatamente o guardrail inerte "
+              + "que este kit existe para nao produzir.");
+        }
+
+        // Em Refresh a arvore inteira e zerada antes de regravar: uma regravacao parcial
+        // deixaria entradas de uma versao antiga convivendo com entradas novas, e a proxima
+        // leitura offline nao teria como saber quais sao quais.
+        if (Options.Mode == EvalMode.Refresh)
+        {
+            try
+            {
+                await new ShortPathResponseCacheProvider(Options.CacheRoot, Options.TimeToLive)
+                    .ResetAsync(cancellationToken).ConfigureAwait(false);
+            }
+            catch (DirectoryNotFoundException)
+            {
+                // MEDIDO na v10.9.0: ResetAsync chama Directory.Delete no subdiretorio de
+                // cache e LANCA quando ele ainda nao existe — o caso da PRIMEIRA gravacao.
+                // "Nao ha o que zerar" e sucesso, nao falha. Capturado aqui, e nao evitado
+                // com um Directory.Exists sobre o layout interno da biblioteca: repetir o
+                // nome do subdiretorio dela aqui seria uma segunda verdade sobre onde a
+                // cache mora.
+            }
+        }
+
+        foreach (var scenario in scenarios)
+        {
+            await RunAsync(scenario, cancellationToken).ConfigureAwait(false);
+        }
+
+        if (Options.Mode == EvalMode.Refresh && Options.Pin is not null)
+        {
+            EvalCacheStamp.Write(Options.CacheRoot, new EvalCacheStamp
+            {
+                PinnedAt = Options.Pin.PinnedAt,
+                Packages = Options.Pin.Packages,
+                Provider = Options.ProviderName,
+                Model = Options.DefaultModelId,
+            });
+        }
+
+        var summary = Summary;
+        if (!string.IsNullOrWhiteSpace(Options.SummaryPath))
+        {
+            summary.WriteTo(Options.SummaryPath);
+        }
+
+        return summary;
+    }
+
+    /// <summary>Roda UM cenario: resolve a resposta (cache ou cliente interno) e aplica os avaliadores.</summary>
+    public async Task<EvalScenarioResult> RunAsync(EvalScenario scenario, CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(scenario);
+
+        _cursor.Name = scenario.CacheKey;
+
+        var evaluators = new List<IEvaluator>(scenario.Assertions);
+        evaluators.AddRange(_quality);
+
+        var configuration = new ReportingConfiguration(
+            evaluators: evaluators,
+            resultStore: _resultStore,
+            chatConfiguration: new ChatConfiguration(_inner),
+            responseCacheProvider: new ShortPathResponseCacheProvider(Options.CacheRoot, Options.TimeToLive),
+            executionName: ExecutionName);
+
+        await using var run = await configuration
+            .CreateScenarioRunAsync(scenario.CacheKey, Defaults.DefaultIterationName, cancellationToken: cancellationToken)
+            .ConfigureAwait(false);
+
+        var chatClient = run.ChatConfiguration?.ChatClient
+            ?? throw new InvalidOperationException(
+                "eval-chat-client-missing: o ScenarioRun nao expos um chat client — sem ele nao ha camada de cache.");
+
+        var response = await chatClient
+            .GetResponseAsync(scenario.Messages, cancellationToken: cancellationToken)
+            .ConfigureAwait(false);
+
+        var result = await run
+            .EvaluateAsync(scenario.Messages, response, cancellationToken: cancellationToken)
+            .ConfigureAwait(false);
+
+        var outcomes = new List<EvalAssertionOutcome>(scenario.Assertions.Count);
+        foreach (var assertion in scenario.Assertions)
+        {
+            outcomes.Add(assertion.Evaluate(response));
+        }
+
+        // Um cenario SEM assercao deterministica nao passa: ele nao cobra nada. Deixa-lo
+        // verde por vacuidade e o mesmo defeito de um teste vazio — e aqui ele seria pior,
+        // porque o cenario apareceria na contagem como se tivesse verificado algo.
+        var scenarioResult = new EvalScenarioResult(
+            scenario.CacheKey,
+            outcomes.Count > 0 && outcomes.All(o => o.Passed),
+            outcomes,
+            result);
+
+        _results.Add(scenarioResult);
+        return scenarioResult;
+    }
+
+    /// <inheritdoc />
+    public ValueTask DisposeAsync()
+    {
+        _inner.Dispose();
+        return ValueTask.CompletedTask;
+    }
+
+    private IReadOnlyDictionary<string, double> CollectQuality()
+    {
+        var names = new HashSet<string>(_quality.SelectMany(q => q.EvaluationMetricNames), StringComparer.Ordinal);
+        var acc = new Dictionary<string, double>(StringComparer.Ordinal);
+        if (names.Count == 0 || _results.Count == 0)
+        {
+            return acc;
+        }
+
+        foreach (var result in _results)
+        {
+            foreach (var (name, metric) in result.Result.Metrics)
+            {
+                if (names.Contains(name) && metric is NumericMetric { Value: not null } numeric)
+                {
+                    acc[name] = acc.TryGetValue(name, out var sum) ? sum + numeric.Value.Value : numeric.Value.Value;
+                }
+            }
+        }
+
+        foreach (var name in acc.Keys.ToList())
+        {
+            acc[name] = Math.Round(acc[name] / _results.Count, 3);
+        }
+
+        return acc;
+    }
+
+    private static string Required(string variable)
+        => Environment.GetEnvironmentVariable(variable)
+        ?? throw new InvalidOperationException(
+            $"eval-env-missing: a variavel {variable} nao esta definida. "
+          + "Ela e DITADA pelo CLI (morph-spec verify); rodar a suite de eval a mao exige defini-la.");
+
+    private static EvalMode ParseMode(string? raw) => (raw ?? "offline").ToLowerInvariant() switch
+    {
+        "offline" => EvalMode.Offline,
+        "refresh" => EvalMode.Refresh,
+        "online" => EvalMode.Online,
+        _ => throw new InvalidOperationException(
+            $"eval-mode-unknown: MORPH_EVAL_MODE=\"{raw}\". Conhecidos: offline, refresh, online."),
+    };
+
+    private static EvalPin? ParsePin(string? raw)
+    {
+        if (string.IsNullOrWhiteSpace(raw))
+        {
+            return null;
+        }
+
+        try
+        {
+            return System.Text.Json.JsonSerializer.Deserialize<EvalPin>(raw);
+        }
+        catch (System.Text.Json.JsonException e)
+        {
+            throw new InvalidOperationException(
+                $"eval-pin-unreadable: MORPH_EVAL_PIN nao parseia ({e.Message}). "
+              + "Ela e escrita pelo CLI a partir de framework/ai-pin.json — um valor ilegivel aqui e defeito do CLI, "
+              + "e trata-lo como 'sem pin' desligaria a checagem de carimbo em silencio.");
+        }
+    }
+}

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/Evals/EvalMode.cs

@@ -0,0 +1,32 @@
+namespace Morph.AiKit.Evals;
+
+/// <summary>
+/// De onde a resposta do modelo pode vir nesta execucao de eval.
+/// </summary>
+/// <remarks>
+/// A distincao existe porque as tres situacoes tem custos diferentes em DINHEIRO e em
+/// confianca, e um enum de dois valores ("usa cache" / "nao usa") esconderia a do meio.
+/// </remarks>
+public enum EvalMode
+{
+    /// <summary>
+    /// So a cache. Um miss e falha nomeada, nunca uma chamada de rede — e nunca um
+    /// <c>skip</c>: gate verde sobre verificacao que nao aconteceu e o modo de falha que
+    /// este harness mais paga para evitar. E o modo do CI.
+    /// </summary>
+    Offline = 0,
+
+    /// <summary>
+    /// Reexecuta TODOS os cenarios contra o provider e regrava a arvore de cache. Exige
+    /// credencial e nunca acontece implicitamente: uma regravacao automatica e uma chamada
+    /// paga que ninguem pediu.
+    /// </summary>
+    Refresh = 1,
+
+    /// <summary>
+    /// Cache primeiro, provider no miss. E o modo de quem esta escrevendo cenario novo na
+    /// propria maquina: paga so pelo que falta, e o resultado sai marcado como
+    /// <c>cold</c> com aviso de que a arvore mudou e precisa ser commitada.
+    /// </summary>
+    Online = 2,
+}

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/Evals/EvalQualityEvaluators.cs

@@ -0,0 +1,49 @@
+using Microsoft.Extensions.AI.Evaluation;
+using Microsoft.Extensions.AI.Evaluation.Quality;
+
+namespace Morph.AiKit.Evals;
+
+/// <summary>
+/// Os avaliadores de JUIZO que o kit considera utilizaveis, e a fronteira que os separa dos
+/// experimentais.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <b>Eles nunca decidem.</b> O veredito de um cenario sai das <see cref="EvalAssertion"/>
+/// deterministicas; o que sai daqui e METRICA REPORTADA. Um juizo de LLM que reprovasse
+/// sozinho reintroduziria a variancia que faz suites de eval serem desligadas do CI — e um
+/// no de eval desligado nao verifica nada.
+/// </para>
+/// <para>
+/// <b>Por que a lista e curta.</b> Dois dos quatro avaliadores que o plano desta feature
+/// listava como estaveis carregam <c>[Experimental("AIEVAL001")]</c> na versao pinada:
+/// <c>TaskAdherenceEvaluator</c> e <c>ToolCallAccuracyEvaluator</c>. Sob
+/// <c>TreatWarningsAsErrors</c>, usa-los exige suprimir um diagnostico — uma decisao
+/// consciente de quem adota o kit, jamais um efeito colateral de chamar um metodo chamado
+/// "Stable". Medido por reflexao sobre <c>Microsoft.Extensions.AI.Evaluation.Quality</c>
+/// 10.9.0, e pinado pelo teste <c>WhichQualityEvaluatorsAreExperimentalIsMEASURED</c>.
+/// </para>
+/// <para>
+/// <b>E por que este tipo existe.</b> Sem uma unica referencia em <c>src/</c>, o pacote
+/// <c>.Quality</c> teria apenas contrato de VERSAO (o restore, NU1102) e um rename de API
+/// nele nao reprovaria PR nenhuma. Com o <c>using</c> real acima, ele passa a ter cobertura
+/// de compilacao — que e o nivel de garantia que o kit promete para a familia de Evaluation.
+/// </para>
+/// </remarks>
+public static class EvalQualityEvaluators
+{
+    /// <summary>
+    /// Os avaliadores de qualidade NAO experimentais da versao pinada, prontos para
+    /// <see cref="EvalFixture.Create"/>.
+    /// </summary>
+    /// <remarks>
+    /// Uma lista nova a cada chamada: os avaliadores sao passados adiante e guardados por uma
+    /// <c>ReportingConfiguration</c>, e um array compartilhado seria estado global disfarcado
+    /// de conveniencia.
+    /// </remarks>
+    public static IReadOnlyList<IEvaluator> Stable() =>
+    [
+        new RelevanceEvaluator(),
+        new CompletenessEvaluator(),
+    ];
+}