@polymorphism-tech/morph-spec 8.34.2 → 8.35.1

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

@@ -0,0 +1,214 @@
+using System.Text.Json;
+using System.Text.Json.Serialization;
+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>
+    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);
+
+        if (!Directory.Exists(datasetRoot))
+        {
+            throw new DirectoryNotFoundException(
+                $"eval-dataset-missing: nao existe dataset em \"{datasetRoot}\". "
+              + "Um dataset ausente e erro de configuracao — uma suite de eval que avalia zero cenarios "
+              + "e sai verde e o guardrail inerte que este kit existe para nao produzir.");
+        }
+
+        var files = Directory
+            .EnumerateFiles(datasetRoot, "*.json", SearchOption.AllDirectories)
+            .OrderBy(p => p.Replace('\\', '/'), StringComparer.Ordinal)
+            .ToList();
+
+        var scenarios = new List<EvalScenario>(files.Count);
+        foreach (var file in files)
+        {
+            scenarios.Add(Load(datasetRoot, file));
+        }
+
+        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);
+        ArgumentException.ThrowIfNullOrWhiteSpace(file);
+
+        var relative = Path.GetRelativePath(datasetRoot, file).Replace('\\', '/');
+        var segments = relative.Split('/');
+        if (segments.Length != 3)
+        {
+            throw new InvalidOperationException(
+                $"eval-dataset-shape: \"{relative}\" nao esta em {{agente}}/{{tenant}}/{{cenario}}.json. "
+              + "O caminho E a identidade do cenario: aceitar outra forma tornaria a chave de cache ambigua.");
+        }
+
+        var dto = JsonSerializer.Deserialize<ScenarioDto>(File.ReadAllText(file), JsonOptions)
+            ?? throw new InvalidOperationException($"eval-dataset-shape: \"{relative}\" nao parseia como cenario.");
+
+        if (dto.Messages is null || dto.Messages.Count == 0)
+        {
+            throw new InvalidOperationException(
+                $"eval-dataset-shape: \"{relative}\" nao declara nenhuma mensagem — um cenario sem pergunta nao avalia nada.");
+        }
+
+        var assertions = new List<EvalAssertion>();
+        var used = new HashSet<string>(StringComparer.Ordinal);
+        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))
+            {
+                throw new InvalidOperationException(
+                    $"eval-dataset-shape: \"{relative}\" repete o nome de assercao \"{name}\" — "
+                  + "nomes de metrica sao unicos por cenario, senao uma assercao apaga a outra.");
+            }
+
+            assertions.Add(new EvalAssertion
+            {
+                Name = name,
+                Kind = ParseKind(raw.Kind, relative),
+                Target = raw.Target,
+                Value = raw.Value,
+            });
+        }
+
+        return new EvalScenario
+        {
+            Agent = segments[0],
+            Tenant = segments[1],
+            Name = Path.GetFileNameWithoutExtension(segments[2]),
+            Messages = [.. dto.Messages.Select(m => new ChatMessage(RoleOf(m.Role, relative), m.Text ?? string.Empty))],
+            Assertions = assertions,
+        };
+    }
+
+    private static readonly JsonSerializerOptions JsonOptions = new()
+    {
+        PropertyNameCaseInsensitive = true,
+        ReadCommentHandling = JsonCommentHandling.Skip,
+    };
+
+    private static ChatRole RoleOf(string? role, string relative) => role?.ToLowerInvariant() switch
+    {
+        "system" => ChatRole.System,
+        "user" => ChatRole.User,
+        "assistant" => ChatRole.Assistant,
+        "tool" => ChatRole.Tool,
+        _ => throw new InvalidOperationException(
+            $"eval-dataset-shape: \"{relative}\" usa o papel de mensagem \"{role}\", que nao existe."),
+    };
+
+    private static EvalAssertionKind ParseKind(string? kind, string relative)
+        => Enum.TryParse<EvalAssertionKind>((kind ?? string.Empty).Replace("-", string.Empty, StringComparison.Ordinal), ignoreCase: true, out var parsed)
+            ? parsed
+            : throw new InvalidOperationException(
+                $"eval-dataset-shape: \"{relative}\" declara a assercao \"{kind}\", que nao existe. "
+              + $"Conhecidas: {string.Join(", ", Enum.GetNames<EvalAssertionKind>())}.");
+
+    private sealed record ScenarioDto
+    {
+        [JsonPropertyName("messages")]
+        public IReadOnlyList<MessageDto>? Messages { get; init; }
+
+        [JsonPropertyName("assertions")]
+        public IReadOnlyList<AssertionDto>? Assertions { get; init; }
+    }
+
+    private sealed record MessageDto
+    {
+        [JsonPropertyName("role")]
+        public string? Role { get; init; }
+
+        [JsonPropertyName("text")]
+        public string? Text { get; init; }
+    }
+
+    private sealed record AssertionDto
+    {
+        [JsonPropertyName("name")]
+        public string? Name { get; init; }
+
+        [JsonPropertyName("kind")]
+        public string? Kind { get; init; }
+
+        [JsonPropertyName("target")]
+        public string? Target { get; init; }
+
+        [JsonPropertyName("value")]
+        public string? Value { get; init; }
+    }
+}

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

@@ -0,0 +1,168 @@
+using System.Text.Json;
+using System.Text.Json.Serialization;
+
+namespace Morph.AiKit.Evals;
+
+/// <summary>Estado da arvore de cache nesta execucao, como o sumario o reporta.</summary>
+public static class EvalCacheState
+{
+    /// <summary>Todos os cenarios resolveram pela cache. Nenhuma chamada ao provider.</summary>
+    public const string Warm = "warm";
+
+    /// <summary>Ao menos um cenario foi ao provider — a arvore mudou e precisa ser commitada.</summary>
+    public const string Cold = "cold";
+}
+
+/// <summary>Uma falha de eval, com nome — cenario, assercao e o motivo literal.</summary>
+/// <remarks>
+/// <para>
+/// <b>Por que o sumario carrega isto, e nao so contadores.</b> Medido: degradar a resposta em
+/// cache deixava a suite vermelha (correto) com a mensagem <c>Expected 0, Actual 1</c> —
+/// verdadeira e inutil. Nada a jusante conseguia dizer QUAL cenario caiu nem por que, porque a
+/// informacao morria dentro do fixture.
+/// </para>
+/// <para>
+/// A rubrica <c>eval-de-modelo.md</c> exige, na banda 9-10, "derrubando o cenario e
+/// NOMEANDO-O", e da como exemplo <c>eval-fail: triagem.acme.a-saudacao</c>. Sem este tipo a
+/// propria rubrica seria inexequivel — o que e pior do que nao ter rubrica, porque parece
+/// coberto.
+/// </para>
+/// </remarks>
+/// <param name="Scenario">A chave do cenario (<c>{agente}.{tenant}.{nome}</c>).</param>
+/// <param name="Assertion">O nome da assercao que reprovou.</param>
+/// <param name="Kind">A regua usada, para distinguir duas assercoes homonimas de tipos distintos.</param>
+/// <param name="Reason">O motivo literal produzido pela assercao.</param>
+public sealed record EvalFailureDetail(
+    [property: JsonPropertyName("scenario")] string Scenario,
+    [property: JsonPropertyName("assertion")] string Assertion,
+    [property: JsonPropertyName("kind")] string Kind,
+    [property: JsonPropertyName("reason")] string Reason)
+{
+    /// <summary>Uma linha legivel, no formato que a rubrica cita.</summary>
+    public override string ToString()
+        => $"eval-fail: {Scenario} — {Assertion} ({Kind}): {Reason}";
+}
+
+/// <summary>
+/// O sumario que o fixture escreve no fim da suite, e que o CLI le.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <b>Por que ARQUIVO e nao uma linha marcada no stdout.</b> O runner de teste captura a
+/// saida de console por teste, e o que chega ao stdout do processo depende da configuracao
+/// do runner e do logger. Um contrato que quebra quando alguem liga um logger e um contrato
+/// ruim — e a falha seria SILENCIOSA (sumario ausente, contagem desconhecida, no verde pelo
+/// codigo de saida). O arquivo tem outra virtude: quem escolhe o caminho e o CLI, entao dois
+/// nos de eval no mesmo <c>verify</c> nao colidem.
+/// </para>
+/// <para>
+/// <b>Do outro lado, o leitor trata sumario ausente ou ilegivel como DESCONHECIDO, jamais
+/// como zero.</b> Um sumario que nao parseia nao pode fabricar <c>scenarios: 0</c> e
+/// transformar uma baseline em queda inventada.
+/// </para>
+/// </remarks>
+public sealed record EvalRunSummary
+{
+    /// <summary>Quantos cenarios foram avaliados.</summary>
+    [JsonPropertyName("scenarios")]
+    public required int Scenarios { get; init; }
+
+    /// <summary>Quantos passaram em TODAS as suas assercoes deterministicas.</summary>
+    [JsonPropertyName("passed")]
+    public required int Passed { get; init; }
+
+    /// <summary>Quantos falharam em ao menos uma assercao deterministica.</summary>
+    [JsonPropertyName("failed")]
+    public required int Failed { get; init; }
+
+    /// <summary><see cref="EvalCacheState.Warm"/> ou <see cref="EvalCacheState.Cold"/>.</summary>
+    [JsonPropertyName("cache")]
+    public required string Cache { get; init; }
+
+    /// <summary>Veredito do carimbo, em minusculas (<c>ok</c>, <c>missing</c>, ...).</summary>
+    [JsonPropertyName("stamp")]
+    public required string Stamp { get; init; }
+
+    /// <summary>
+    /// Quantas vezes a cache falhou e a chamada desceu ao cliente interno. Em modo offline
+    /// com cache quente e ZERO — e esse zero e a prova de que nenhuma chamada paga foi feita.
+    /// </summary>
+    [JsonPropertyName("misses")]
+    public required int Misses { get; init; }
+
+    /// <summary>O <c>ProviderName</c> usado, o mesmo que entrou na chave.</summary>
+    [JsonPropertyName("provider")]
+    public required string Provider { get; init; }
+
+    /// <summary>O <c>DefaultModelId</c> usado, o mesmo que entrou na chave.</summary>
+    [JsonPropertyName("model")]
+    public string? Model { get; init; }
+
+    /// <summary>
+    /// Metricas de JUIZO (avaliadores de qualidade), nome para valor. Reportadas, nunca
+    /// decisivas: com a cache quente elas sao deterministicas, mas a variancia volta na
+    /// regravacao, e um gate que dependesse disso nasceria destinado a ser desligado.
+    /// </summary>
+    [JsonPropertyName("quality")]
+    public IReadOnlyDictionary<string, double> Quality { get; init; } = new Dictionary<string, double>(StringComparer.Ordinal);
+
+    /// <summary>
+    /// As falhas, uma por assercao reprovada, com nome. Vazia num run verde.
+    /// </summary>
+    /// <remarks>
+    /// Lista, e nao um booleano ou um contador, porque um cenario pode quebrar em mais de uma
+    /// assercao e as duas informam coisas diferentes: uma resposta vazia derruba
+    /// <c>Contains</c> E <c>JsonHasKey</c>, e saber disso e a diferenca entre "o prompt mudou"
+    /// e "o modelo parou de responder".
+    /// </remarks>
+    [JsonPropertyName("failures")]
+    public IReadOnlyList<EvalFailureDetail> Failures { get; init; } = [];
+
+    /// <summary>
+    /// As falhas em texto, uma por linha — a mensagem que um teste ou o CLI mostra.
+    /// </summary>
+    /// <remarks>
+    /// Devolve frase propria quando nao ha falha alguma, em vez de string vazia: uma mensagem
+    /// de assercao vazia e indistinguivel de uma mensagem que ninguem preencheu.
+    /// </remarks>
+    public string DescribeFailures()
+        => Failures.Count == 0
+            ? "nenhuma falha de eval registrada"
+            : string.Join(Environment.NewLine, Failures.Select(f => f.ToString()));
+
+    private static readonly JsonSerializerOptions Json = new() { WriteIndented = true };
+
+    /// <summary>Grava o sumario. Cria o diretorio se preciso; sobrescreve se ja existe.</summary>
+    public void WriteTo(string path)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(path);
+
+        var dir = Path.GetDirectoryName(Path.GetFullPath(path));
+        if (!string.IsNullOrEmpty(dir))
+        {
+            Directory.CreateDirectory(dir);
+        }
+
+        File.WriteAllText(path, JsonSerializer.Serialize(this, Json));
+    }
+
+    /// <summary>Le um sumario gravado. Devolve nulo para arquivo ausente ou ilegivel — DESCONHECIDO, jamais zero.</summary>
+    public static EvalRunSummary? ReadFrom(string path)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(path);
+
+        if (!File.Exists(path))
+        {
+            return null;
+        }
+
+        try
+        {
+            return JsonSerializer.Deserialize<EvalRunSummary>(File.ReadAllText(path), Json);
+        }
+        catch (JsonException)
+        {
+            return null;
+        }
+    }
+}

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

@@ -0,0 +1,142 @@
+using Microsoft.Extensions.AI;
+
+namespace Morph.AiKit.Evals;
+
+/// <summary>
+/// O <see cref="IChatClient"/> que RECUSA no miss: a peca que torna possivel rodar evals no
+/// CI sem uma unica credencial.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <b>Onde ele fica.</b> A biblioteca de Evaluation embrulha o cliente que recebe num
+/// cliente de cache. No HIT, o cliente interno nunca e invocado. No MISS, a chamada desce
+/// para o interno — e o interno, aqui, e este. Logo: com a cache quente ele nao e chamado
+/// nenhuma vez, e quando e chamado a resposta certa e "faltou cenario na cache", nao uma
+/// chamada de rede.
+/// </para>
+/// <para>
+/// <b>Por que ele replica <c>ProviderName</c> e <c>DefaultModelId</c>.</b> Esses dois
+/// campos do <see cref="ChatClientMetadata"/> entram na chave de cache. Se o cliente
+/// offline se apresentasse com outro nome, a chave computada na leitura seria outra e TODO
+/// cenario daria miss — uma cache quente indistinguivel de uma cache vazia. Eles sao
+/// parametros, e nao constantes, exatamente porque tem de reproduzir o run que GRAVOU.
+/// </para>
+/// <para>
+/// <b><see cref="ChatClientMetadata.ProviderUri"/> e deliberadamente nulo.</b> O endpoint
+/// NAO entra na chave — medido contra a v10.9.0, contra o que a documentacao afirma. E essa
+/// ausencia que permite ao cliente offline nao ter endpoint nenhum: ele nao tem para onde
+/// ligar, e nao precisa ter.
+/// </para>
+/// <para>
+/// <b><see cref="Invocations"/> e a prova, e ela e um contador, nao um sniffer.</b> "Zero
+/// chamadas de rede" nao se mede sem instrumentar a rede; "zero invocacoes do cliente
+/// interno" se mede aqui, e e suficiente porque o cliente interno e o UNICO caminho para a
+/// rede nesta montagem. O contador sobe ANTES do lancamento, para que uma tentativa
+/// interrompida ainda apareca.
+/// </para>
+/// </remarks>
+public sealed class OfflineChatClient : IChatClient
+{
+    private readonly Lock _gate = new();
+    private readonly Func<string> _currentScenario;
+    private readonly string _cachePath;
+    private readonly string _envFile;
+    private int _invocations;
+
+    /// <summary>
+    /// Cria o cliente offline replicando a identidade do run que gravou a cache.
+    /// </summary>
+    /// <param name="providerName">Mesmo <c>ProviderName</c> do run que gravou. Entra na chave.</param>
+    /// <param name="defaultModelId">Mesmo <c>DefaultModelId</c> do run que gravou. Entra na chave.</param>
+    /// <param name="cachePath">Raiz da arvore de cache, so para a mensagem de miss.</param>
+    /// <param name="envFile">Arquivo de credencial esperado, so para a mensagem de miss.</param>
+    /// <param name="currentScenario">
+    /// Le o nome do cenario em execucao no momento da chamada. E uma funcao, e nao um
+    /// valor, porque um fixture roda N cenarios com o MESMO cliente: um nome capturado na
+    /// construcao nomearia sempre o primeiro.
+    /// </param>
+    public OfflineChatClient(
+        string providerName,
+        string? defaultModelId,
+        string cachePath,
+        string envFile,
+        Func<string> currentScenario)
+    {
+        ArgumentException.ThrowIfNullOrWhiteSpace(providerName);
+        ArgumentException.ThrowIfNullOrWhiteSpace(cachePath);
+        ArgumentException.ThrowIfNullOrWhiteSpace(envFile);
+        ArgumentNullException.ThrowIfNull(currentScenario);
+
+        ProviderName = providerName;
+        DefaultModelId = defaultModelId;
+        _cachePath = cachePath;
+        _envFile = envFile;
+        _currentScenario = currentScenario;
+    }
+
+    /// <summary>O <c>ProviderName</c> replicado — o mesmo que gravou a cache.</summary>
+    public string ProviderName { get; }
+
+    /// <summary>O <c>DefaultModelId</c> replicado — o mesmo que gravou a cache.</summary>
+    public string? DefaultModelId { get; }
+
+    /// <summary>
+    /// Quantas vezes a cache falhou e a chamada desceu ate aqui. Num run com a cache quente
+    /// e ZERO, e essa e a prova de que nenhuma chamada paga foi feita.
+    /// </summary>
+    public int Invocations
+    {
+        get { lock (_gate) { return _invocations; } }
+    }
+
+    /// <inheritdoc />
+    public Task<ChatResponse> GetResponseAsync(
+        IEnumerable<ChatMessage> messages,
+        ChatOptions? options = null,
+        CancellationToken cancellationToken = default)
+        => throw Miss();
+
+    /// <inheritdoc />
+    public IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(
+        IEnumerable<ChatMessage> messages,
+        ChatOptions? options = null,
+        CancellationToken cancellationToken = default)
+        => throw Miss();
+
+    /// <inheritdoc />
+    public object? GetService(Type serviceType, object? serviceKey = null)
+    {
+        ArgumentNullException.ThrowIfNull(serviceType);
+
+        if (serviceKey is not null)
+        {
+            return null;
+        }
+
+        if (serviceType == typeof(ChatClientMetadata))
+        {
+            // providerUri nulo de proposito: o endpoint nao entra na chave de cache, e um
+            // cliente que nunca liga para lugar nenhum nao deve anunciar um destino.
+            return new ChatClientMetadata(ProviderName, providerUri: null, DefaultModelId);
+        }
+
+        return serviceType.IsInstanceOfType(this) ? this : null;
+    }
+
+    /// <inheritdoc />
+    public void Dispose()
+    {
+        // Nada a liberar: este cliente nao abre socket, nao le ambiente e nao guarda estado
+        // fora do contador. E o ponto.
+    }
+
+    private EvalCacheMissException Miss()
+    {
+        lock (_gate)
+        {
+            _invocations++;
+        }
+
+        return new EvalCacheMissException(_currentScenario(), _cachePath, _envFile);
+    }
+}