@polymorphism-tech/morph-spec 8.37.1 → 8.40.0

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/Agents/AgentSpecOptions.cs

@@ -2,135 +2,37 @@ using Microsoft.Extensions.AI;
 
 namespace Morph.AiKit.Agents;
 
-/// <summary>
-/// UM UNICO bag de opcoes do agente — a forma copiada do <c>AgentFrameworkToolkit</c>
-/// sem o pacote (decisao D2). Em vez de N objetos de configuracao espalhados por
-/// camadas, tudo o que um agente pode ajustar vive aqui, como dado.
-/// </summary>
-/// <remarks>
-/// <para>
-/// <b>Regra estrutural, e a razao de o tipo existir:</b> toda propriedade e nula por
-/// padrao, e <b>nulo significa "nao envia ao provider"</b> — nunca "envia o default do
-/// framework". E isso que impede o kit de mudar, por omissao, o comportamento de um
-/// modelo. O canario da regra e
-/// <c>AgentSpecTests.FreshOptionsProduceChatOptionsIndistinguishableFromPristine</c>:
-/// uma <see cref="AgentSpecOptions"/> recem-construida produz um <see cref="ChatOptions"/>
-/// indistinguivel de <c>new ChatOptions()</c>, propriedade por propriedade, por reflexao.
-/// </para>
-/// <para><b>Duas familias de opcao convivem aqui, e a fronteira e explicita:</b></para>
-/// <list type="table">
-///   <listheader><term>Familia</term><description>Para onde vai</description></listheader>
-///   <item>
-///     <term>Nivel de requisicao</term>
-///     <description>
-///       <see cref="Temperature"/>, <see cref="TopP"/>, <see cref="MaxOutputTokens"/>,
-///       <see cref="Seed"/>, <see cref="StopSequences"/>, <see cref="ToolMode"/>,
-///       <see cref="ReasoningEffort"/> e <see cref="ServiceTier"/> viram
-///       <see cref="ChatOptions"/> em <see cref="ApplyTo"/>.
-///     </description>
-///   </item>
-///   <item>
-///     <term>Nivel de agente / pipeline</term>
-///     <description>
-///       <see cref="MaxToolIterations"/>, <see cref="AllowConcurrentToolInvocation"/>,
-///       <see cref="TimeoutSeconds"/> e <see cref="EnableSensitiveTelemetry"/> NAO existem
-///       em <see cref="ChatOptions"/>. Sao lidas diretamente pela <c>AgentFactory</c> (T10)
-///       ao montar o pipeline e pela telemetria (T12). O teste
-///       <c>AgentLevelKnobsNeverLeakIntoChatOptions</c> pina essa fronteira.
-///     </description>
-///   </item>
-/// </list>
-/// </remarks>
+// Nulo significa "nao envia ao provider", nunca "envia o default do framework".
 public sealed record AgentSpecOptions
 {
-    /// <summary>
-    /// Chave usada em <see cref="ChatOptions.AdditionalProperties"/> para transportar
-    /// <see cref="ServiceTier"/>. Ver a nota de fato em <see cref="ServiceTier"/>.
-    /// </summary>
     public const string ServiceTierPropertyName = "service_tier";
 
-    /// <summary>Amostragem. Nulo = o provider decide.</summary>
     public float? Temperature { get; init; }
 
-    /// <summary>Nucleus sampling. Nulo = o provider decide.</summary>
     public float? TopP { get; init; }
 
-    /// <summary>Teto de tokens de saida. Nulo = o provider decide.</summary>
     public int? MaxOutputTokens { get; init; }
 
-    /// <summary>Semente de amostragem, quando o provider suporta. Nulo = nao envia.</summary>
     public long? Seed { get; init; }
 
-    /// <summary>
-    /// Sequencias de parada. Nulo = nao envia. Lista vazia NAO e tratada como nulo: e
-    /// enviada como veio. "Nulo nao envia; nao-nulo envia o que voce escreveu" e a regra
-    /// inteira, sem excecao escondida.
-    /// </summary>
     public IReadOnlyList<string>? StopSequences { get; init; }
 
-    /// <summary>Modo de tool calling (<c>Auto</c>, <c>None</c>, <c>RequireAny</c>...). Nulo = nao envia.</summary>
     public ChatToolMode? ToolMode { get; init; }
 
-    /// <summary>
-    /// Esforco de raciocinio. Tipado com o enum de primeira classe do
-    /// <c>Microsoft.Extensions.AI</c> 10.9.0 (<c>None/Low/Medium/High/ExtraHigh</c>) em vez
-    /// de string, porque e exatamente esse valor que o limite de tool calling da Chat
-    /// Completions cita — ver <c>ModelAliasConstraints.ToolCallingRequiresReasoningEffortNone</c>.
-    /// Nulo = nao envia: vale o default do provider, e qual e ele o kit NAO afirma saber.
-    /// </summary>
     public Microsoft.Extensions.AI.ReasoningEffort? ReasoningEffort { get; init; }
 
-    /// <summary>
-    /// Tier de servico (ex.: <c>"flex"</c>, <c>"priority"</c>).
-    /// <b>Nota de fato, nao de gosto:</b> o <see cref="ChatOptions"/> do
-    /// <c>Microsoft.Extensions.AI</c> 10.9.0 NAO tem propriedade de service tier — apurado
-    /// por reflexao sobre o assembly do pin, nao por memoria. Quando definido, o valor
-    /// viaja em <see cref="ChatOptions.AdditionalProperties"/> sob a chave
-    /// <see cref="ServiceTierPropertyName"/>, e so chega ao fio se o adaptador do provider
-    /// ler dali ou se a <c>AgentFactory</c> montar um
-    /// <see cref="ChatOptions.RawRepresentationFactory"/>. Nulo = nao envia.
-    /// </summary>
     public string? ServiceTier { get; init; }
 
-    /// <summary>
-    /// Teto de voltas de tool calling. <b>Nivel de agente</b>: vira
-    /// <c>FunctionInvokingChatClient.MaximumIterationsPerRequest</c> na T10, nunca
-    /// <see cref="ChatOptions"/>. Nulo = default do pipeline.
-    /// </summary>
     public int? MaxToolIterations { get; init; }
 
-    /// <summary>
-    /// Permite invocar tools concorrentemente numa mesma volta. <b>Nivel de agente</b>
-    /// (<c>FunctionInvokingChatClient.AllowConcurrentInvocation</c>). Nulo = default do pipeline.
-    /// </summary>
     public bool? AllowConcurrentToolInvocation { get; init; }
 
-    /// <summary>
-    /// Timeout da invocacao, em segundos. <b>Nivel de agente</b>: vira
-    /// <c>CancellationToken</c> na T10. Nulo = sem timeout proprio.
-    /// </summary>
     public int? TimeoutSeconds { get; init; }
 
-    /// <summary>
-    /// Liga a captura de conteudo sensivel (prompt e resposta) nos spans.
-    /// <b>Nivel de agente</b> — insumo da T12. A diferenca entre nulo e <c>false</c> e
-    /// preservada de proposito: nulo e "nao opinei", <c>false</c> e "decidi que nao".
-    /// </summary>
     public bool? EnableSensitiveTelemetry { get; init; }
 
-    /// <summary>
-    /// Produz um <see cref="ChatOptions"/> novo com — e SOMENTE com — as opcoes de nivel
-    /// de requisicao que foram definidas.
-    /// </summary>
     public ChatOptions ToChatOptions() => ApplyTo(new ChatOptions());
 
-    /// <summary>
-    /// Aplica as opcoes de nivel de requisicao sobre um <see cref="ChatOptions"/> existente.
-    /// Propriedade nula aqui NAO toca no destino, o que permite a <c>AgentFactory</c>
-    /// preencher <c>Tools</c> e <c>ResponseFormat</c> antes ou depois sem risco de perde-los.
-    /// </summary>
-    /// <param name="options">Destino. Nao pode ser nulo.</param>
-    /// <returns>O proprio <paramref name="options"/>, para encadeamento.</returns>
     public ChatOptions ApplyTo(ChatOptions options)
     {
         ArgumentNullException.ThrowIfNull(options);
@@ -170,6 +72,7 @@ public sealed record AgentSpecOptions
             options.Reasoning = new ReasoningOptions { Effort = effort };
         }
 
+        // ChatOptions do Microsoft.Extensions.AI 10.9.0 nao tem service tier (apurado por reflexao).
         if (ServiceTier is not null)
         {
             options.AdditionalProperties ??= new AdditionalPropertiesDictionary();

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

@@ -1,11 +1,5 @@
 namespace Morph.AiKit;
 
-/// <summary>
-/// Ancora de tipo do assembly. Existe para que o esqueleto tenha uma superficie
-/// publica verificavel antes das tasks T7-T14 — e para que qualquer consumidor
-/// (teste, DI, reflexao) tenha um <c>typeof</c> estavel para apontar ao assembly
-/// sem depender de um tipo de dominio que ainda nao existe.
-/// </summary>
 public sealed class AiKitAssemblyMarker
 {
     private AiKitAssemblyMarker()

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/Conversation/ConversationStore.cs

@@ -3,54 +3,15 @@ using Microsoft.Extensions.AI;
 
 namespace Morph.AiKit.Conversation;
 
-/// <summary>
-/// O <see cref="ChatHistoryProvider"/> da casa: o historico de conversa vive no acervo
-/// <b>do projeto</b> (<see cref="IConversationStore"/>), nao dentro da
-/// <see cref="AgentSession"/>.
-/// </summary>
-/// <remarks>
-/// <para>
-/// <b>A decisao que este arquivo torna compilavel.</b> O caminho embutido do MAF
-/// (<c>InMemoryChatHistoryProvider</c>) guarda a conversa no estado da sessao, o que resolve
-/// um chat de demonstracao e nao resolve um CRM multi-tenant: a conversa precisa sobreviver
-/// ao restart, ser lida por relatorio, ser filtrada por tenant e ser apagada a pedido do
-/// titular. Aqui a <see cref="AgentSession"/> guarda apenas <b>a chave</b> da conversa; o
-/// conteudo mora onde o projeto puder consulta-lo — tipicamente uma coluna <c>jsonb</c>.
-/// </para>
-/// <para>
-/// <b>A invariante que o teste cobra:</b> o provider e <b>uma instancia compartilhada por
-/// todas as sessoes</b>. Por isso este tipo <b>nao tem campo de estado por conversa</b> — o
-/// unico estado por sessao vive em <see cref="ProviderSessionState{TState}"/>, dentro da
-/// propria <see cref="AgentSession"/>. Um campo de instancia guardando "a conversa atual"
-/// e como o historico de um usuario aparece na tela de outro, e a falha nao aparece em teste
-/// de uma sessao so: aparece em producao, sob concorrencia, como vazamento de dado alheio.
-/// </para>
-/// <para>
-/// <b>De onde vem a chave da conversa</b>, nesta ordem:
-/// <list type="number">
-/// <item>o que o projeto amarrou com <see cref="BindConversation"/> — o caso do CRM, em que
-/// a conversa ja existe como registro antes de o agente entrar;</item>
-/// <item>o <c>ConversationId</c> da sessao, quando o proprio provider de modelo gerencia a
-/// conversa (<see cref="ChatClientAgentSession"/>);</item>
-/// <item>um id novo, <see cref="Guid.CreateVersion7"/> — ordenavel no tempo, ao contrario de
-/// <c>Guid.NewGuid</c>, que fragmenta indice de banco.</item>
-/// </list>
-/// </para>
-/// </remarks>
+// Uma instancia atende todas as sessoes: estado por conversa so em ProviderSessionState, nunca em campo.
 public sealed class ConversationStore : ChatHistoryProvider
 {
-    /// <summary>
-    /// Chave sob a qual a identidade da conversa e guardada no estado da sessao. Fixa e
-    /// publica porque ela viaja na serializacao da sessao: mudar esta string quebra a
-    /// retomada de toda conversa ja persistida.
-    /// </summary>
+    // Viaja na serializacao da sessao: mudar a string quebra a retomada das conversas ja persistidas.
     public const string ConversationIdStateKey = "morph.conversation.id";
 
     private readonly IConversationStore _store;
     private readonly ProviderSessionState<string> _conversationId;
 
-    /// <summary>Monta o provider sobre um acervo.</summary>
-    /// <param name="store">Onde o historico e lido e gravado. Nunca nulo.</param>
     public ConversationStore(IConversationStore store)
     {
         ArgumentNullException.ThrowIfNull(store);
@@ -59,23 +20,8 @@ public sealed class ConversationStore : ChatHistoryProvider
         _conversationId = new ProviderSessionState<string>(NewConversationId, ConversationIdStateKey);
     }
 
-    /// <inheritdoc />
-    /// <remarks>
-    /// Declara a chave que este provider ocupa no estado da sessao — e o que permite ao MAF
-    /// serializar e retomar uma sessao sem adivinhar o que e de quem.
-    /// </remarks>
     public override IReadOnlyList<string> StateKeys => [ConversationIdStateKey];
 
-    /// <summary>
-    /// Amarra a sessao a uma conversa que <b>ja existe</b> no acervo do projeto. E o caminho
-    /// do CRM: a conversa nasce como registro de negocio, e o agente entra nela.
-    /// </summary>
-    /// <remarks>
-    /// Chamar isto depois de a sessao ja ter carregado historico troca a conversa sob os pes
-    /// da sessao. Amarre logo apos <c>CreateSessionAsync</c>.
-    /// </remarks>
-    /// <param name="session">A sessao.</param>
-    /// <param name="conversationId">A chave da conversa no acervo.</param>
     public void BindConversation(AgentSession session, string conversationId)
     {
         ArgumentNullException.ThrowIfNull(session);
@@ -84,10 +30,6 @@ public sealed class ConversationStore : ChatHistoryProvider
         _conversationId.SaveState(session, conversationId);
     }
 
-    /// <summary>
-    /// A chave da conversa desta sessao, criando-a se ainda nao houver. Le e escreve
-    /// <b>na sessao</b>, jamais num campo deste objeto.
-    /// </summary>
     public string GetConversationId(AgentSession session)
     {
         ArgumentNullException.ThrowIfNull(session);
@@ -95,11 +37,7 @@ public sealed class ConversationStore : ChatHistoryProvider
         return _conversationId.GetOrInitializeState(session);
     }
 
-    /// <inheritdoc />
-    /// <remarks>
-    /// Devolve o historico guardado; as mensagens desta volta sao acrescentadas pelo agente
-    /// depois. Repetir aqui as mensagens do pedido duplicaria o turno corrente no prompt.
-    /// </remarks>
+    // O MAF acrescenta as mensagens desta volta depois; devolve-las aqui duplicaria o turno no prompt.
     protected override async ValueTask<IEnumerable<ChatMessage>> ProvideChatHistoryAsync(
         InvokingContext context,
         CancellationToken cancellationToken = default)
@@ -111,19 +49,6 @@ public sealed class ConversationStore : ChatHistoryProvider
             .ConfigureAwait(false);
     }
 
-    /// <inheritdoc />
-    /// <remarks>
-    /// <para>
-    /// Grava o pedido e a resposta <b>desta</b> volta, nessa ordem — e so eles. Regravar o
-    /// historico inteiro a cada volta faria a conversa crescer em progressao geometrica.
-    /// </para>
-    /// <para>
-    /// <b>Volta que falhou nao e gravada.</b> Com <c>InvokeException</c> preenchida nao ha
-    /// resposta; persistir o pedido sozinho deixaria a conversa terminando numa pergunta que
-    /// o modelo nunca respondeu, e a proxima volta a mandaria de novo — o usuario veria a si
-    /// mesmo repetido.
-    /// </para>
-    /// </remarks>
     protected override async ValueTask StoreChatHistoryAsync(
         InvokedContext context,
         CancellationToken cancellationToken = default)
@@ -135,9 +60,6 @@ public sealed class ConversationStore : ChatHistoryProvider
             return;
         }
 
-        // Os dois lados sao anulaveis no contrato do MAF (a resposta some quando a volta
-        // falhou, e o pedido pode vir vazio numa continuacao). Tratados como ausencia, nunca
-        // desreferenciados.
         List<ChatMessage> round =
         [
             .. context.RequestMessages ?? [],
@@ -154,13 +76,6 @@ public sealed class ConversationStore : ChatHistoryProvider
             .ConfigureAwait(false);
     }
 
-    /// <summary>
-    /// O MAF declara <c>InvokingContext.Session</c> como anulavel, e uma invocacao sem
-    /// sessao nao tem onde guardar a identidade da conversa. As duas saidas silenciosas sao
-    /// piores que a recusa: inventar um id grava uma linha orfa que ninguem consegue ler de
-    /// novo, e usar uma chave fixa junta conversas de tenants diferentes no mesmo balde —
-    /// que e o vazamento que este provider existe para impedir.
-    /// </summary>
     private static AgentSession RequireSession(AgentSession? session)
         => session ?? throw new InvalidOperationException(
             "ConversationStore foi invocado sem AgentSession. Sem sessao nao ha identidade de " +

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/Conversation/IConversationStore.cs

@@ -2,51 +2,11 @@ using Microsoft.Extensions.AI;
 
 namespace Morph.AiKit.Conversation;
 
-/// <summary>
-/// Onde o historico de conversa fica guardado. <b>A costura entre o kit e o banco do
-/// projeto</b> — e o unico ponto do <see cref="ConversationStore"/> que um projeto precisa
-/// implementar para trocar memoria por tabela.
-/// </summary>
-/// <remarks>
-/// <para>
-/// <b>A decisao da casa que este tipo torna compilavel:</b> a conversa vive no armazenamento
-/// <b>do projeto</b>, nao dentro da <c>AgentSession</c>. Num CRM multi-tenant a conversa e
-/// um registro de negocio — ela precisa sobreviver ao restart do processo, ser lida por
-/// relatorio, ser filtrada por tenant e ser apagada a pedido do titular. Nada disso e
-/// possivel quando o historico so existe na memoria de uma sessao.
-/// </para>
-/// <para>
-/// <b>O kit nao conhece banco.</b> Esta interface e deliberadamente pequena e sem tipo de
-/// infraestrutura na assinatura: nenhum <c>DbContext</c>, nenhuma conexao, nenhum
-/// <c>jsonb</c>. A implementacao de producao vive no projeto (handler falando com o
-/// <c>ApplicationDbContext</c> direto, sem camada de service e sem repository generico);
-/// a implementacao de teste e <see cref="InMemoryConversationStore"/>.
-/// </para>
-/// <para>
-/// <b>Contrato de identidade:</b> <c>conversationId</c> e a chave do acervo, opaca para o
-/// kit. Num CRM ela costuma ser o id da linha de conversa — e por isso
-/// <see cref="ConversationStore.BindConversation"/> existe: e como o projeto amarra uma
-/// sessao a uma conversa que ja existe, em vez de deixar o kit inventar um id.
-/// </para>
-/// <para>
-/// <b>Contrato de concorrencia:</b> uma unica instancia atende todas as sessoes ao mesmo
-/// tempo. A implementacao precisa ser segura para uso concorrente e, acima de tudo,
-/// <b>nunca deixar mensagem de uma conversa aparecer em outra</b> — a chave e o unico
-/// isolamento que existe aqui.
-/// </para>
-/// </remarks>
+// Uma instancia atende todas as sessoes ao mesmo tempo: a implementacao precisa ser segura sob concorrencia.
 public interface IConversationStore
 {
-    /// <summary>
-    /// O historico da conversa, na ordem cronologica. Conversa inexistente devolve lista
-    /// <b>vazia</b>, nunca nulo e nunca excecao: uma primeira volta e o caso normal.
-    /// </summary>
     ValueTask<IReadOnlyList<ChatMessage>> LoadAsync(string conversationId, CancellationToken cancellationToken);
 
-    /// <summary>
-    /// Acrescenta as mensagens de uma volta ao fim da conversa. Chamado uma vez por volta,
-    /// com o pedido e a resposta daquela volta — nunca com o historico inteiro.
-    /// </summary>
     ValueTask AppendAsync(
         string conversationId,
         IReadOnlyList<ChatMessage> messages,

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/Conversation/InMemoryConversationStore.cs

@@ -3,33 +3,13 @@ using Microsoft.Extensions.AI;
 
 namespace Morph.AiKit.Conversation;
 
-/// <summary>
-/// <see cref="IConversationStore"/> em memoria. <b>Para teste e para prototipo</b> — nao
-/// para producao: o historico morre com o processo, e um CRM que perde a conversa no deploy
-/// nao tem conversa.
-/// </summary>
-/// <remarks>
-/// <para>
-/// Existe para que a suite do kit prove o <see cref="ConversationStore"/> <b>sem banco</b>,
-/// e para que um projeto tenha um exemplar de referencia do contrato antes de escrever a
-/// versao com <c>jsonb</c>.
-/// </para>
-/// <para>
-/// <b>Seguro sob concorrencia por construcao</b>, e nao por acidente: uma
-/// <see cref="ConcurrentDictionary{TKey, TValue}"/> por conversa, e a lista de cada conversa
-/// sempre mutada sob o lock daquela conversa. Sem isso, o teste de duas sessoes concorrentes
-/// mediria a falta de trava aqui em vez do isolamento do provider.
-/// </para>
-/// </remarks>
 public sealed class InMemoryConversationStore : IConversationStore
 {
     private readonly ConcurrentDictionary<string, List<ChatMessage>> _conversations =
         new(StringComparer.Ordinal);
 
-    /// <summary>As conversas que existem no acervo, para inspecao em teste.</summary>
     public IReadOnlyCollection<string> ConversationIds => _conversations.Keys.ToArray();
 
-    /// <inheritdoc />
     public ValueTask<IReadOnlyList<ChatMessage>> LoadAsync(
         string conversationId,
         CancellationToken cancellationToken)
@@ -48,7 +28,6 @@ public sealed class InMemoryConversationStore : IConversationStore
         }
     }
 
-    /// <inheritdoc />
     public ValueTask AppendAsync(
         string conversationId,
         IReadOnlyList<ChatMessage> messages,

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

@@ -2,39 +2,17 @@ using Microsoft.Extensions.AI;
 
 namespace Morph.AiKit.Evals;
 
-/// <summary>
-/// Conta quantas vezes o cliente interno foi realmente invocado, e repassa tudo o mais
-/// intacto.
-/// </summary>
-/// <remarks>
-/// <para>
-/// <b>Por que existe.</b> Nos modos que TEM cliente real (<see cref="EvalMode.Refresh"/> e
-/// <see cref="EvalMode.Online"/>) nao ha <see cref="OfflineChatClient"/> para contar, e sem
-/// contador o sumario nao consegue dizer se a arvore de cache mudou. "A cache esta fria" e
-/// uma afirmacao com consequencia (a arvore precisa ser commitada), e afirmacao com
-/// consequencia se mede.
-/// </para>
-/// <para>
-/// <b><see cref="GetService"/> repassa VERBATIM</b>, e isso e load-bearing: e por ele que o
-/// <c>ChatClientMetadata</c> — com o <c>ProviderName</c> e o <c>DefaultModelId</c> que
-/// entram na CHAVE de cache — chega a camada de cache. Um wrapper que respondesse por conta
-/// propria aqui gravaria a arvore sob uma identidade diferente da que a leitura offline
-/// replica, e todo cenario daria miss.
-/// </para>
-/// </remarks>
 public sealed class CountingChatClient(IChatClient inner) : IChatClient
 {
     private readonly IChatClient _inner = inner ?? throw new ArgumentNullException(nameof(inner));
     private readonly Lock _gate = new();
     private int _calls;
 
-    /// <summary>Quantas chamadas atravessaram ate o cliente real.</summary>
     public int Calls
     {
         get { lock (_gate) { return _calls; } }
     }
 
-    /// <inheritdoc />
     public Task<ChatResponse> GetResponseAsync(
         IEnumerable<ChatMessage> messages,
         ChatOptions? options = null,
@@ -44,7 +22,6 @@ public sealed class CountingChatClient(IChatClient inner) : IChatClient
         return _inner.GetResponseAsync(messages, options, cancellationToken);
     }
 
-    /// <inheritdoc />
     public IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(
         IEnumerable<ChatMessage> messages,
         ChatOptions? options = null,
@@ -54,11 +31,10 @@ public sealed class CountingChatClient(IChatClient inner) : IChatClient
         return _inner.GetStreamingResponseAsync(messages, options, cancellationToken);
     }
 
-    /// <inheritdoc />
+    // Repassa verbatim: o ChatClientMetadata daqui entra na chave de cache.
     public object? GetService(Type serviceType, object? serviceKey = null)
         => _inner.GetService(serviceType, serviceKey);
 
-    /// <inheritdoc />
     public void Dispose() => _inner.Dispose();
 
     private void Count()

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)