@polymorphism-tech/morph-spec 8.38.0 → 8.41.0

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

@@ -3,84 +3,34 @@ using System.Text.Json.Serialization;
 
 namespace Morph.AiKit.Evals;
 
-/// <summary>O veredito de um carimbo de cache — quatro estados, nunca um booleano.</summary>
-/// <remarks>
-/// <c>Missing</c> e <c>PinMismatch</c> sao SEPARADOS de proposito: as duas situacoes pedem
-/// acoes diferentes. A primeira e "regrave"; a segunda e "regrave <b>porque o pacote
-/// mudou</b>". Colapsa-las num unico "carimbo invalido" devolve ao leitor a pergunta que o
-/// carimbo existia para responder.
-/// </remarks>
 public enum EvalStampVerdict
 {
-    /// <summary>Carimbo presente e de acordo com o pin corrente.</summary>
     Ok = 0,
 
-    /// <summary>Nao ha carimbo: cache anterior a esta feature, ou diretorio criado a mao.</summary>
     Missing = 1,
 
-    /// <summary>Ha um arquivo, mas ele nao e JSON legivel no formato do carimbo.</summary>
     Unreadable = 2,
 
-    /// <summary>As versoes gravadas divergem do pin corrente — a chave de cache pode ter mudado.</summary>
     PinMismatch = 3,
 
-    /// <summary>O <c>pinnedAt</c> do pin corrente esta no futuro. Erro de pin, jamais cache fresca.</summary>
     FuturePin = 4,
 }
 
-/// <summary>Resultado de <see cref="EvalCacheStamp.Check"/>: veredito mais a frase que o explica.</summary>
-/// <param name="Verdict">O estado apurado.</param>
-/// <param name="Reason">
-/// Frase pronta para o relatorio. Nos dois vereditos que nomeiam versoes, ela cita AS DUAS
-/// (a gravada e a do pin) — dizer so uma obriga o leitor a ir buscar a outra.
-/// </param>
 public sealed record EvalCacheStampCheck(EvalStampVerdict Verdict, string Reason)
 {
-    /// <summary>Atalho de leitura: o veredito unico que permite avaliar cenario.</summary>
     public bool IsOk => Verdict == EvalStampVerdict.Ok;
 }
 
-/// <summary>
-/// O pin, do jeito que o fixture o recebe: data de apuracao mais pacote-para-versao.
-/// </summary>
-/// <remarks>
-/// Achatado (nome para versao) e nao a forma completa de <c>framework/ai-pin.json</c>
-/// porque quem o produz e o CLI, na variavel <c>MORPH_EVAL_PIN</c>, e o kit nao le o pin do
-/// disco: um segundo parser de <c>ai-pin.json</c> e como as duas verdades comecam. Aqui
-/// entram apenas os pacotes que decidem o FORMATO da cache — a familia
-/// <c>Microsoft.Extensions.AI</c> e as tres de Evaluation. Subir o provider da OpenAI nao
-/// invalida uma arvore de cache, e um carimbo que reagisse a isso reprovaria por nada.
-/// </remarks>
-/// <param name="PinnedAt">Data ISO em que um humano conferiu as versoes.</param>
-/// <param name="Packages">Nome do pacote para versao exata.</param>
+// So os pacotes que decidem o formato da cache; o kit nunca le ai-pin.json do disco.
 public sealed record EvalPin(
     [property: JsonPropertyName("pinnedAt")] string PinnedAt,
     [property: JsonPropertyName("packages")] IReadOnlyDictionary<string, string> Packages);
 
-/// <summary>
-/// O carimbo que fica na raiz da arvore de cache commitada, e a regra que o julga.
-/// </summary>
-/// <remarks>
-/// <para>
-/// <b>Por que existe.</b> A funcao de hash que produz a chave de cache nao promete ser
-/// estavel entre versoes da biblioteca — a propria biblioteca carrega um numero de versao
-/// de cache interno, para invalidar tudo quando o formato muda. Ou seja: SUBIR O PIN PODE
-/// INVALIDAR A ARVORE INTEIRA. Sem carimbo isso chega como N misses inexplicaveis num dia
-/// em que ninguem mexeu em nada. Com carimbo, chega como uma frase que nomeia as duas
-/// versoes e o comando de regravacao.
-/// </para>
-/// <para>
-/// <b>Ele nao substitui a leitura da cache</b> — a chave continua sendo computada pela
-/// biblioteca. Ele responde antes, e de graca, a pergunta cuja resposta cara seria "rodou a
-/// suite inteira para descobrir que a cache nao servia".
-/// </para>
-/// </remarks>
+// A chave de cache da biblioteca nao e estavel entre versoes: subir o pin pode invalidar a arvore inteira.
 public sealed record EvalCacheStamp
 {
-    /// <summary>Nome do arquivo, na raiz de <c>cachePath</c>. Uma unica grafia.</summary>
     public const string FileName = ".morph-eval-cache.json";
 
-    /// <summary>Quem grava. Um carimbo de outra origem e um carimbo que ninguem mantem.</summary>
     public const string Writer = "morph-eval-fixture";
 
     private static readonly JsonSerializerOptions Json = new()
@@ -89,34 +39,27 @@ public sealed record EvalCacheStamp
         PropertyNamingPolicy = JsonNamingPolicy.CamelCase,
     };
 
-    /// <summary>O <c>pinnedAt</c> vigente quando a arvore foi gravada.</summary>
     [JsonPropertyName("pinnedAt")]
     public required string PinnedAt { get; init; }
 
-    /// <summary>As versoes de pacote sob as quais a arvore foi gravada.</summary>
     [JsonPropertyName("packages")]
     public required IReadOnlyDictionary<string, string> Packages { get; init; }
 
-    /// <summary>O <c>ProviderName</c> que entrou na chave.</summary>
     [JsonPropertyName("provider")]
     public required string Provider { get; init; }
 
-    /// <summary>O <c>DefaultModelId</c> que entrou na chave. Nulo e um valor, nao um erro.</summary>
     [JsonPropertyName("model")]
     public string? Model { get; init; }
 
-    /// <summary>Quem gravou o carimbo.</summary>
     [JsonPropertyName("writtenBy")]
     public string WrittenBy { get; init; } = Writer;
 
-    /// <summary>Caminho do arquivo de carimbo dentro de uma raiz de cache.</summary>
     public static string PathFor(string cacheRoot)
     {
         ArgumentException.ThrowIfNullOrWhiteSpace(cacheRoot);
         return Path.Combine(cacheRoot, FileName);
     }
 
-    /// <summary>Grava o carimbo. Cria a raiz se ela ainda nao existe.</summary>
     public static void Write(string cacheRoot, EvalCacheStamp stamp)
     {
         ArgumentException.ThrowIfNullOrWhiteSpace(cacheRoot);
@@ -124,17 +67,10 @@ public sealed record EvalCacheStamp
 
         Directory.CreateDirectory(cacheRoot);
 
-        // Quebras de linha normalizadas para LF e uma quebra final: o carimbo e um arquivo
-        // COMMITADO. Sem isso ele produziria diff que nao e diff — CRLF numa maquina, LF
-        // noutra, e nenhuma quebra no fim em lugar nenhum.
         var json = JsonSerializer.Serialize(stamp, Json).ReplaceLineEndings("\n");
         File.WriteAllText(PathFor(cacheRoot), json + "\n");
     }
 
-    /// <summary>
-    /// Le o carimbo. Devolve <c>null</c> quando o arquivo nao existe OU nao parseia —
-    /// <see cref="Check"/> e quem distingue os dois casos, porque so ela tem as palavras.
-    /// </summary>
     public static EvalCacheStamp? Read(string cacheRoot)
     {
         ArgumentException.ThrowIfNullOrWhiteSpace(cacheRoot);
@@ -155,24 +91,13 @@ public sealed record EvalCacheStamp
         }
     }
 
-    /// <summary>
-    /// O carimbo desta arvore contra o pin corrente.
-    /// </summary>
-    /// <param name="cacheRoot">Raiz da arvore de cache.</param>
-    /// <param name="pin">O pin corrente, como o CLI o entregou.</param>
-    /// <param name="timeProvider">
-    /// Relogio injetado — a comparacao de <c>pinnedAt</c> com hoje e uma leitura de relogio,
-    /// e um teste que dependesse do relogio da maquina mudaria de veredito na virada do dia.
-    /// </param>
     public static EvalCacheStampCheck Check(string cacheRoot, EvalPin pin, TimeProvider timeProvider)
     {
         ArgumentException.ThrowIfNullOrWhiteSpace(cacheRoot);
         ArgumentNullException.ThrowIfNull(pin);
         ArgumentNullException.ThrowIfNull(timeProvider);
 
-        // O pin vem ANTES do carimbo: um pin com data no futuro renova sozinho qualquer
-        // janela medida contra ele, e comparar um carimbo contra uma regua adulterada
-        // produziria um "ok" que nao significa nada.
+        // O pin vem antes do carimbo: um pin com data no futuro renovaria qualquer janela medida contra ele.
         var today = timeProvider.GetUtcNow().UtcDateTime.ToString("yyyy-MM-dd", System.Globalization.CultureInfo.InvariantCulture);
         if (string.CompareOrdinal(pin.PinnedAt, today) > 0)
         {

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

@@ -5,56 +5,14 @@ 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)";
@@ -87,33 +45,18 @@ public sealed class EvalFixture : IAsyncDisposable
         _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,
@@ -128,15 +71,6 @@ public sealed class EvalFixture : IAsyncDisposable
         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>();
@@ -145,10 +79,6 @@ public sealed class EvalFixture : IAsyncDisposable
         {
             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(
@@ -169,20 +99,6 @@ public sealed class EvalFixture : IAsyncDisposable
         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,
@@ -198,8 +114,6 @@ public sealed class EvalFixture : IAsyncDisposable
             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"),
@@ -211,9 +125,6 @@ public sealed class EvalFixture : IAsyncDisposable
         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,
@@ -237,8 +148,7 @@ public sealed class EvalFixture : IAsyncDisposable
         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.
+        // Em Refresh a arvore esta sendo reescrita: cobrar carimbo impediria gravar a primeira cache.
         var stampCheck = options.Mode == EvalMode.Refresh || options.Pin is null
             ? new EvalCacheStampCheck(
                 EvalStampVerdict.Ok,
@@ -278,10 +188,6 @@ public sealed class EvalFixture : IAsyncDisposable
         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);
@@ -293,9 +199,7 @@ public sealed class EvalFixture : IAsyncDisposable
               + "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.
+        // Zera antes de regravar: entradas de versoes diferentes nao podem conviver na arvore.
         if (Options.Mode == EvalMode.Refresh)
         {
             try
@@ -305,12 +209,7 @@ public sealed class EvalFixture : IAsyncDisposable
             }
             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.
+                // Raiz ausente na primeira gravacao: nada a zerar.
             }
         }
 
@@ -339,7 +238,6 @@ public sealed class EvalFixture : IAsyncDisposable
         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);
@@ -378,11 +276,9 @@ public sealed class EvalFixture : IAsyncDisposable
             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,
+            // Sem assercao o cenario reprova: verde por vacuidade contaria como verificado.
             outcomes.Count > 0 && outcomes.All(o => o.Passed),
             outcomes,
             result);
@@ -391,7 +287,6 @@ public sealed class EvalFixture : IAsyncDisposable
         return scenarioResult;
     }
 
-    /// <inheritdoc />
     public ValueTask DisposeAsync()
     {
         _inner.Dispose();

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

@@ -1,32 +1,10 @@
 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

@@ -3,44 +3,9 @@ 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>
+    // TaskAdherence e ToolCallAccuracy ficam fora: sao [Experimental("AIEVAL001")] no Quality 10.9.0.
     public static IReadOnlyList<IEvaluator> Stable() =>
     [
         new RelevanceEvaluator(),

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

@@ -4,73 +4,21 @@ using Microsoft.Extensions.AI;
 
 namespace Morph.AiKit.Evals;
 
-/// <summary>
-/// Um cenario de eval: as mensagens que vao ao modelo e as propriedades que a resposta tem
-/// de ter.
-/// </summary>
-/// <remarks>
-/// <para>
-/// <b>O dataset e versionado e vive em disco</b>, organizado como
-/// <c>{agente}/{tenant}/{cenario}.json</c>. Os dois primeiros segmentos existem porque a
-/// pergunta util quase nunca e "o produto regrediu?", e sim "o agente X regrediu para o
-/// tenant Y?" — e um dataset plano nao consegue responder isso sem convencao de nome.
-/// </para>
-/// <para>
-/// <b>Dado real de tenant e proibido aqui.</b> A cache guarda mensagens INTEIRAS e e
-/// commitada: um segredo que entre no dataset entra no git. O fixture so le cenario deste
-/// diretorio versionado — nunca de banco, nunca de variavel de ambiente.
-/// </para>
-/// </remarks>
 public sealed record EvalScenario
 {
-    /// <summary>Primeiro segmento do caminho no dataset.</summary>
     public required string Agent { get; init; }
 
-    /// <summary>Segundo segmento do caminho no dataset.</summary>
     public required string Tenant { get; init; }
 
-    /// <summary>
-    /// Nome do arquivo, sem extensao. Vira o <c>scenarioName</c> da cache, e por isso e o
-    /// que aparece na mensagem de miss.
-    /// </summary>
     public required string Name { get; init; }
 
-    /// <summary>As mensagens enviadas ao modelo, na ordem.</summary>
     public required IReadOnlyList<ChatMessage> Messages { get; init; }
 
-    /// <summary>As assercoes deterministicas que decidem pass/fail deste cenario.</summary>
     public IReadOnlyList<EvalAssertion> Assertions { get; init; } = [];
 
-    /// <summary>
-    /// Identidade do cenario dentro da cache: <c>{agente}.{tenant}.{nome}</c>.
-    /// </summary>
-    /// <remarks>
-    /// <para>
-    /// Qualificado, e nao so <see cref="Name"/>, porque dois tenants tem cenarios com o
-    /// mesmo nome de proposito ("saudacao", "handoff") — e uma chave de cache que os
-    /// confundisse devolveria a resposta de um tenant para o outro.
-    /// </para>
-    /// <para>
-    /// <b>O separador e ponto, e nao barra, por uma MEDICAO.</b> A primeira versao usava
-    /// barra, na suposicao de que a biblioteca aninharia o nome do cenario em diretorios. Ela
-    /// nao aninha: <c>PathValidation.ValidatePathSegment</c> recusa o nome com
-    /// <c>ArgumentException: 'scenarioName' contains invalid path characters or directory
-    /// traversal sequences</c> — o nome do cenario e UM segmento de caminho, sempre. Medido
-    /// na v10.9.0 contra o SDK .NET 10.
-    /// </para>
-    /// </remarks>
+    // Ponto, nao barra: a biblioteca exige que o nome do cenario seja UM segmento de caminho (10.9.0).
     public string CacheKey => $"{Agent}.{Tenant}.{Name}";
 
-    /// <summary>
-    /// Le TODOS os cenarios de um dataset, em ordem estavel (ordinal por caminho).
-    /// </summary>
-    /// <remarks>
-    /// Ordem estavel importa mais do que parece: e ela que faz duas maquinas gravarem a
-    /// mesma arvore de cache e produzirem o mesmo diff. Uma enumeracao dependente do
-    /// sistema de arquivos e um diff que muda sozinho.
-    /// </remarks>
-    /// <param name="datasetRoot">Raiz do dataset versionado.</param>
-    /// <exception cref="DirectoryNotFoundException">Quando a raiz nao existe — declarar um dataset ausente e erro de config, nao um dataset vazio.</exception>
     public static IReadOnlyList<EvalScenario> LoadAll(string datasetRoot)
     {
         ArgumentException.ThrowIfNullOrWhiteSpace(datasetRoot);
@@ -85,6 +33,7 @@ public sealed record EvalScenario
 
         var files = Directory
             .EnumerateFiles(datasetRoot, "*.json", SearchOption.AllDirectories)
+            // Ordem ordinal: duas maquinas precisam gravar a mesma arvore de cache.
             .OrderBy(p => p.Replace('\\', '/'), StringComparer.Ordinal)
             .ToList();
 
@@ -97,7 +46,6 @@ public sealed record EvalScenario
         return scenarios;
     }
 
-    /// <summary>Le um cenario, derivando agente e tenant do caminho relativo a raiz.</summary>
     public static EvalScenario Load(string datasetRoot, string file)
     {
         ArgumentException.ThrowIfNullOrWhiteSpace(datasetRoot);
@@ -126,9 +74,6 @@ public sealed record EvalScenario
         for (var i = 0; i < (dto.Assertions?.Count ?? 0); i++)
         {
             var raw = dto.Assertions![i];
-            // Nome default derivado do indice, e unicidade COBRADA: a biblioteca indexa
-            // metricas por nome, e um nome repetido faria a segunda assercao sobrescrever a
-            // primeira — um cenario que parece cobrar duas propriedades cobrando uma.
             var name = string.IsNullOrWhiteSpace(raw.Name) ? $"{raw.Kind}-{i + 1}" : raw.Name!;
             if (!used.Add(name))
             {