@polymorphism-tech/morph-spec 8.38.0 → 8.40.0

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

@@ -6,79 +6,31 @@ using Microsoft.Extensions.AI.Evaluation;
 
 namespace Morph.AiKit.Evals;
 
-/// <summary>O que uma assercao deterministica pergunta a uma resposta.</summary>
-/// <remarks>
-/// A lista e curta de proposito. Toda entrada aqui e uma propriedade que se decide sem
-/// julgamento: ou o texto contem, ou nao contem; ou a ferramenta foi escolhida, ou nao foi.
-/// Uma "assercao" que precisasse de um modelo para decidir seria juizo, e juizo nao reprova
-/// sozinho neste kit.
-/// </remarks>
 public enum EvalAssertionKind
 {
-    /// <summary>O texto da resposta contem o valor (ignorando caixa).</summary>
     Contains = 0,
 
-    /// <summary>O texto da resposta NAO contem o valor (ignorando caixa).</summary>
     NotContains = 1,
 
-    /// <summary>A resposta e um objeto JSON e tem a chave de topo indicada em <c>Target</c>.</summary>
     JsonHasKey = 2,
 
-    /// <summary>A resposta nao carrega dado pessoal nas formas que o kit sabe reconhecer.</summary>
     NoPii = 3,
 
-    /// <summary>A resposta escolheu a ferramenta nomeada em <c>Target</c>.</summary>
     ToolCalled = 4,
 
-    /// <summary>A ferramenta <c>Target</c> foi chamada com o argumento <c>Value</c> no formato <c>chave=valor</c>.</summary>
     ToolArgument = 5,
 }
 
-/// <summary>Veredito de uma assercao: o booleano e a frase que o explica.</summary>
-/// <param name="Passed">Se a propriedade se sustentou.</param>
-/// <param name="Reason">Por que — nomeando o que foi procurado, para nao mandar o leitor adivinhar.</param>
 public sealed record EvalAssertionOutcome(bool Passed, string Reason)
 {
-    /// <summary>Nome da assercao que produziu este veredito.</summary>
-    /// <remarks>
-    /// Carimbado por <see cref="EvalAssertion.Evaluate"/>. Existe porque uma falha que chega a
-    /// jusante como contador ("Expected 0, Actual 1") nao diz O QUE quebrou: quem le precisa
-    /// abrir o dataset e adivinhar. Um eval que morde anonimamente obriga a investigacao que
-    /// ele deveria dispensar.
-    /// </remarks>
     public string? Assertion { get; init; }
 
-    /// <summary>O tipo da assercao que julgou — a REGUA, nao so o nome dela.</summary>
     public EvalAssertionKind? Kind { get; init; }
 }
 
-/// <summary>
-/// A assercao deterministica: o unico tipo de avaliador que REPROVA neste kit.
-/// </summary>
-/// <remarks>
-/// <para>
-/// <b>Por que so ela decide.</b> Os avaliadores de qualidade da biblioteca sao juizo de LLM,
-/// e juizo de LLM varia. Um gate que reprovasse por variancia de juiz reintroduziria o
-/// FLAKY que faz suites de eval serem desligadas do CI — e um no de eval desligado nao
-/// verifica nada. Entao a divisao e explicita: assercao deterministica decide; qualidade e
-/// numero reportado.
-/// </para>
-/// <para>
-/// <b>Ela e um <see cref="IEvaluator"/> de verdade</b>, e nao um predicado aplicado por
-/// fora, para que a metrica caia no MESMO relatorio que as de qualidade. Um resultado que
-/// vivesse fora do relatorio precisaria de um segundo lugar para ser lido, e o segundo lugar
-/// e onde as duas verdades comecam.
-/// </para>
-/// </remarks>
 public sealed record EvalAssertion : IEvaluator
 {
-    /// <summary>
-    /// Formas de dado pessoal que o kit reconhece. Deliberadamente poucas e literais: um
-    /// detector de PII abrangente e um projeto proprio, e prometer mais do que se mede seria
-    /// pior do que nao prometer. Sem <c>\b</c> em nenhum padrao — a fronteira de palavra do
-    /// .NET tambem nao trata acento como letra em toda cultura, e um padrao que nao casa e
-    /// pior que um padrao que nao existe.
-    /// </summary>
+    // Sem \b: a fronteira de palavra do .NET nao trata acento como letra em toda cultura.
     private static readonly (string Label, Regex Pattern)[] PiiPatterns =
     [
         ("e-mail", new Regex("[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+[.][A-Za-z]{2,}", RegexOptions.CultureInvariant)),
@@ -86,26 +38,17 @@ public sealed record EvalAssertion : IEvaluator
         ("telefone", new Regex("[(][0-9]{2}[)] ?[0-9]{4,5}-[0-9]{4}", RegexOptions.CultureInvariant)),
     ];
 
-    /// <summary>
-    /// Nome da metrica. UNICO dentro de um cenario: a biblioteca indexa metricas por nome, e
-    /// duas assercoes homonimas fariam a segunda sobrescrever a primeira em silencio — um
-    /// cenario que parece cobrar duas propriedades e cobra uma.
-    /// </summary>
+    // Unico por cenario: a biblioteca indexa metricas por nome e a homonima sobrescreve em silencio.
     public required string Name { get; init; }
 
-    /// <summary>O que esta assercao pergunta.</summary>
     public required EvalAssertionKind Kind { get; init; }
 
-    /// <summary>Chave JSON ou nome de ferramenta, conforme o <see cref="Kind"/>.</summary>
     public string? Target { get; init; }
 
-    /// <summary>Texto procurado, ou <c>chave=valor</c> em <see cref="EvalAssertionKind.ToolArgument"/>.</summary>
     public string? Value { get; init; }
 
-    /// <inheritdoc />
     public IReadOnlyCollection<string> EvaluationMetricNames => [Name];
 
-    /// <summary>Aplica a assercao a uma resposta. Puro: nao le disco, nao le ambiente, nao chama rede.</summary>
     public EvalAssertionOutcome Evaluate(ChatResponse response)
     {
         ArgumentNullException.ThrowIfNull(response);
@@ -135,12 +78,9 @@ public sealed record EvalAssertion : IEvaluator
             _ => new EvalAssertionOutcome(false, $"tipo de assercao desconhecido: {Kind}"),
         };
 
-        // Carimba QUEM julgou. O veredito sozinho e um booleano; com o nome e a regua ele vira
-        // uma frase que nomeia o defeito sem obrigar ninguem a abrir o dataset.
         return outcome with { Assertion = Name, Kind = this.Kind };
     }
 
-    /// <inheritdoc />
     public ValueTask<EvaluationResult> EvaluateAsync(
         IEnumerable<ChatMessage> messages,
         ChatResponse modelResponse,
@@ -156,7 +96,6 @@ public sealed record EvalAssertion : IEvaluator
         return ValueTask.FromResult(new EvaluationResult(metric));
     }
 
-    /// <summary>Texto concatenado da resposta — a superficie que as assercoes de texto leem.</summary>
     internal static string TextOf(ChatResponse response)
     {
         var sb = new StringBuilder();

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

@@ -1,36 +1,9 @@
 namespace Morph.AiKit.Evals;
 
-/// <summary>
-/// Lancada quando um cenario de eval NAO estava na cache e o modo corrente e
-/// <see cref="EvalMode.Offline"/> — o unico caminho pelo qual a suite tocaria a rede.
-/// </summary>
-/// <remarks>
-/// <para>
-/// <b>Por que uma excecao, e nao um resultado.</b> A regra do kit e "excecao nunca como
-/// fluxo de controle"; esta e a excecao de CONTRATO que a propria regra admite. O ponto de
-/// deteccao e o <see cref="OfflineChatClient"/>, que implementa <c>IChatClient</c> — uma
-/// interface de terceiro cuja assinatura devolve <c>Task&lt;ChatResponse&gt;</c> e nao tem
-/// onde carregar um veredito. Devolver uma resposta vazia ali seria pior do que lancar:
-/// o eval ficaria VERDE sobre um cenario que ninguem avaliou, que e exatamente o defeito
-/// (gate verde sobre verificacao que nao aconteceu) que esta feature existe para fechar.
-/// </para>
-/// <para>
-/// <b>A mensagem e o produto.</b> Em CI, com a cache commitada, um miss significa uma coisa
-/// so: o prompt ou o modelo mudou e ninguem regravou. Entao a mensagem nomeia as quatro
-/// coisas que o leitor precisa para agir sem abrir o codigo — o cenario, o caminho da
-/// cache, o comando de regravacao e o arquivo de credencial esperado. Um "cache miss"
-/// seco mandaria o leitor procurar as quatro.
-/// </para>
-/// </remarks>
 public sealed class EvalCacheMissException : Exception
 {
-    /// <summary>Comando literal que regrava a arvore de cache. Nunca implicito, nunca automatico.</summary>
     public const string RefreshCommand = "morph-spec verify {feature} --refresh-cache";
 
-    /// <summary>Cria a excecao com todos os dados que a mensagem precisa nomear.</summary>
-    /// <param name="scenarioName">O cenario que faltou na cache.</param>
-    /// <param name="cachePath">Raiz da arvore de cache consultada.</param>
-    /// <param name="envFile">Arquivo (gitignored) de onde a credencial viria numa regravacao.</param>
     public EvalCacheMissException(string scenarioName, string cachePath, string envFile)
         : base(BuildMessage(scenarioName, cachePath, envFile))
     {
@@ -39,13 +12,10 @@ public sealed class EvalCacheMissException : Exception
         EnvFile = envFile;
     }
 
-    /// <summary>O cenario que faltou na cache.</summary>
     public string ScenarioName { get; }
 
-    /// <summary>Raiz da arvore de cache consultada.</summary>
     public string CachePath { get; }
 
-    /// <summary>Arquivo de credencial esperado por uma regravacao.</summary>
     public string EnvFile { get; }
 
     private static string BuildMessage(string scenarioName, string cachePath, string envFile)

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

@@ -1,78 +1,27 @@
 namespace Morph.AiKit.Evals;
 
-/// <summary>
-/// Tudo o que o <see cref="EvalFixture"/> precisa saber, e nada que ele possa adivinhar.
-/// </summary>
-/// <remarks>
-/// <para>
-/// <b><see cref="TimeToLive"/> nao tem valor default, e isso e o item mais importante deste
-/// tipo.</b> O default da biblioteca e de 14 dias E A EXPIRACAO E DESTRUTIVA NA LEITURA: ao
-/// achar uma entrada vencida, o provedor APAGA o diretorio da chave e devolve nulo. Uma
-/// cache commitada com o default se apaga sozinha ao ser lida, duas semanas depois de
-/// gravada — e o sintoma chega como miss em massa (e arvore suja no <c>git status</c>) num
-/// dia em que ninguem mexeu em nada. Por isso o valor e obrigatorio aqui e o fixture recusa
-/// qualquer coisa abaixo de <see cref="MinimumTimeToLive"/>.
-/// </para>
-/// <para>
-/// <b><see cref="ProviderName"/> e <see cref="DefaultModelId"/> entram na chave de cache</b>
-/// e por isso viajam como configuracao, nao como constante: eles precisam reproduzir o run
-/// que GRAVOU a arvore. O endpoint nao entra na chave (medido na v10.9.0), que e o que
-/// permite ao cliente offline nao ter endpoint algum.
-/// </para>
-/// </remarks>
 public sealed record EvalCacheOptions
 {
-    /// <summary>
-    /// Piso do tempo de vida das entradas. Um ano nao e um numero bonito: e o menor prazo
-    /// que garante que uma cache commitada sobreviva a um ciclo de release sem se apagar
-    /// durante uma leitura.
-    /// </summary>
     public static readonly TimeSpan MinimumTimeToLive = TimeSpan.FromDays(365);
 
-    /// <summary>Raiz da arvore de cache. COMMITADA.</summary>
     public required string CacheRoot { get; init; }
 
-    /// <summary>
-    /// Raiz dos resultados de execucao. FORA da arvore commitada — por construcao, e nao por
-    /// um <c>.gitignore</c> dentro de um diretorio commitado (regra de ignore ali e regra que
-    /// a proxima pessoa remove sem entender). Os resultados carregam latencia medida por
-    /// cronometro, uso de tokens e o flag de cache hit: commita-los e diff garantido em toda
-    /// rodada, sem sinal nenhum.
-    /// </summary>
     public required string ResultsRoot { get; init; }
 
-    /// <summary>Raiz do dataset versionado, em <c>{agente}/{tenant}/{cenario}.json</c>.</summary>
     public required string DatasetRoot { get; init; }
 
-    /// <summary>Tempo de vida das entradas. Obrigatorio, sempre — ver as observacoes do tipo.</summary>
+    // Sem default: o da biblioteca (14 dias) apaga a entrada vencida durante a leitura da arvore commitada.
     public required TimeSpan TimeToLive { get; init; }
 
-    /// <summary>O <c>ProviderName</c> que entra na chave de cache.</summary>
     public required string ProviderName { get; init; }
 
-    /// <summary>O <c>DefaultModelId</c> que entra na chave de cache. Nulo e um valor.</summary>
     public string? DefaultModelId { get; init; }
 
-    /// <summary>De onde a resposta pode vir nesta execucao.</summary>
     public required EvalMode Mode { get; init; }
 
-    /// <summary>
-    /// Onde o sumario JSON e escrito. O CAMINHO E DITADO PELO CHAMADOR (o CLI escolhe um
-    /// arquivo temporario) para que dois nos de eval no mesmo <c>verify</c> nao colidam.
-    /// Nulo quando ninguem quer sumario — rodar sem sumario e legitimo, inventar um caminho
-    /// nao e.
-    /// </summary>
     public string? SummaryPath { get; init; }
 
-    /// <summary>
-    /// Arquivo (gitignored) de onde a credencial viria numa regravacao. So aparece em
-    /// mensagem de erro; o fixture nunca o le.
-    /// </summary>
     public string EnvFile { get; init; } = ".env.evals";
 
-    /// <summary>
-    /// O pin corrente, como o CLI o entregou. Nulo desliga a checagem de carimbo — util para
-    /// um projeto que constroi o fixture a mao, e explicitamente NAO o caminho do CLI.
-    /// </summary>
     public EvalPin? Pin { get; init; }
 }

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)
         {