@polymorphism-tech/morph-spec 8.37.1 → 8.40.0

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

@@ -4,48 +4,8 @@ using Morph.AiKit.Agents;
 
 namespace Morph.AiKit.Observability;
 
-/// <summary>
-/// Liga as GenAI semantic conventions nos dois niveis do kit — agente e chat client — com
-/// <b>um guard contra span duplicado em cada um</b>.
-/// </summary>
-/// <remarks>
-/// <para>
-/// <b>O que foi medido no pin (Microsoft.Agents.AI 1.20.0), e nao suposto:</b>
-/// </para>
-/// <list type="bullet">
-///   <item>
-///     Uma invocacao instrumentada produz <c>invoke_agent</c> (raiz) e <c>chat</c> (filho).
-///     Duas camadas de instrumentacao no MESMO nivel produzem o span daquele nivel duas
-///     vezes: dois <c>OpenTelemetryChatClient</c> dao dois <c>chat</c>; dois
-///     <c>OpenTelemetryAgent</c> dao dois <c>invoke_agent</c>.
-///   </item>
-///   <item>
-///     <c>GetService</c> atravessa a cadeia de delegates nos dois niveis — e por isso que
-///     "ja existe instrumentacao aqui embaixo?" e uma pergunta respondivel, e nao um
-///     palpite. E o predicado dos dois guards.
-///   </item>
-///   <item>
-///     O MAF 1.20.0 tem um guard proprio, mas ele so alcanca o pipeline que o
-///     <c>ChatClientAgent</c> monta sozinho. A <c>AgentFactory</c> monta o proprio
-///     (<c>UseProvidedChatClientAsIs = true</c>) para poder posicionar o custo e ajustar o
-///     tool calling — e nesse arranjo o slot do MAF nao existe. Medido: agente
-///     instrumentado + pipeline proprio sem estas extensoes = <b>zero</b> spans de chat.
-///     O guard daqui nao duplica o do MAF; ele cobre o pipeline que o MAF nao ve.
-///   </item>
-/// </list>
-/// </remarks>
 public static class MorphOpenTelemetryExtensions
 {
-    /// <summary>
-    /// Instrumenta o pipeline de chat. Aplicado pela <c>AgentFactory</c> ABAIXO do
-    /// <c>FunctionInvokingChatClient</c>, que e onde o MAF 1.20.0 documenta que a
-    /// instrumentacao tem de ficar para o span de chat fechar antes das tools.
-    /// </summary>
-    /// <remarks>
-    /// O guard vive na decisao de <see cref="ShouldInstrument"/>: com
-    /// <see cref="MorphTelemetryOptions.InstrumentChatClient"/> nulo (o default), um
-    /// pipeline que ja carrega um <see cref="OpenTelemetryChatClient"/> e devolvido intacto.
-    /// </remarks>
     public static ChatClientBuilder UseMorphTelemetry(this ChatClientBuilder builder, MorphTelemetryOptions options)
     {
         ArgumentNullException.ThrowIfNull(builder);
@@ -59,10 +19,6 @@ public static class MorphOpenTelemetryExtensions
             : inner);
     }
 
-    /// <summary>
-    /// Instrumenta o agente — o span <c>invoke_agent</c>, o mais externo, que cobre a
-    /// invocacao inteira. Um agente que ja e instrumentado e devolvido intacto.
-    /// </summary>
     public static AIAgentBuilder UseMorphTelemetry(this AIAgentBuilder builder, MorphTelemetryOptions options)
     {
         ArgumentNullException.ThrowIfNull(builder);
@@ -76,20 +32,6 @@ public static class MorphOpenTelemetryExtensions
             });
     }
 
-    /// <summary>
-    /// Preenche os dois encaixes de telemetria da <see cref="AgentFactoryOptions"/> de uma
-    /// vez, respeitando <see cref="AgentSpecOptions.EnableSensitiveTelemetry"/> quando a
-    /// spec opinou.
-    /// </summary>
-    /// <remarks>
-    /// A fabrica e dona da POSICAO de cada encaixe; esta extensao so diz o que ocupa cada
-    /// um. E por aqui que a T10 e a T12 se encontram sem uma referenciar a outra.
-    /// <para>
-    /// <c>EnableSensitiveTelemetry</c> nulo na spec significa "nao opinei" e mantem o valor
-    /// destas opcoes; <c>false</c> significa "decidi que nao" e vence. A diferenca entre os
-    /// dois e preservada de proposito desde a T7.
-    /// </para>
-    /// </remarks>
     public static AgentFactoryOptions WithMorphTelemetry(
         this AgentFactoryOptions factoryOptions,
         MorphTelemetryOptions options)
@@ -109,10 +51,7 @@ public static class MorphOpenTelemetryExtensions
             ? options with { EnableSensitiveData = sensitive }
             : options;
 
-    /// <summary>
-    /// <b>O guard.</b> Nulo = instrumenta so o que ainda nao esta instrumentado;
-    /// <c>true</c> = instrumenta sempre (e duplica, quando ja havia); <c>false</c> = nunca.
-    /// </summary>
+    // GetService atravessa a cadeia de delegates (MAF 1.20.0), entao detecta instrumentacao ja aplicada abaixo.
     private static bool ShouldInstrument(IChatClient inner, MorphTelemetryOptions options)
         => options.InstrumentChatClient
             ?? inner.GetService(typeof(OpenTelemetryChatClient)) is null;

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

@@ -1,31 +1,10 @@
 namespace Morph.AiKit.Observability;
 
-/// <summary>
-/// O que o kit precisa saber para emitir telemetria GenAI: sob que <c>ActivitySource</c>,
-/// com ou sem conteudo sensivel, e — a decisao que este tipo existe para carregar — se a
-/// instrumentacao do chat client deve ser aplicada.
-/// </summary>
-/// <remarks>
-/// <para>
-/// <b>Por que <see cref="SourceName"/> e obrigatorio.</b> O standard
-/// <c>ai-agents-observability-patterns</c> manda usar
-/// <c>AgentOpenTelemetryConsts.DefaultSourceName</c>. No <c>Microsoft.Agents.AI</c> 1.20.0
-/// esse tipo <b>nao e publico</b> (apurado por reflexao sobre o assembly do pin: a classe
-/// se chama <c>OpenTelemetryConsts</c> e e <c>internal</c>). Um kit que quisesse "usar a
-/// constante do MAF" so poderia repetir o texto dela — e um literal copiado envelhece em
-/// silencio na primeira vez que o pacote o mudar. Entao o nome e do projeto: e a MESMA
-/// string que ele passa para <c>AddSource(...)</c> na configuracao do OpenTelemetry, e o
-/// span do agente e o span de chat nascem sob ela, juntos.
-/// </para>
-/// </remarks>
 public sealed record MorphTelemetryOptions
 {
     private readonly string _sourceName = string.Empty;
 
-    /// <summary>
-    /// Nome do <c>ActivitySource</c> dos spans deste kit. Branco e rejeitado na construcao:
-    /// um source sem nome e telemetria que ninguem consegue registrar nem coletar.
-    /// </summary>
+    // AgentOpenTelemetryConsts e internal no Microsoft.Agents.AI 1.20.0, entao o nome e do projeto.
     public required string SourceName
     {
         get => _sourceName;
@@ -36,47 +15,8 @@ public sealed record MorphTelemetryOptions
         }
     }
 
-    /// <summary>
-    /// Se prompt, resposta, argumentos e resultados de tool entram nos spans. <c>false</c>
-    /// por padrao — e o standard exige <c>false</c> fora de dev/staging, porque esse
-    /// conteudo e PII do cliente.
-    /// </summary>
     public bool EnableSensitiveData { get; init; }
 
-    /// <summary>
-    /// Se o pipeline de chat deve receber instrumentacao propria. <b>Tres valores, e o
-    /// default e o guard.</b>
-    /// </summary>
-    /// <remarks>
-    /// <list type="table">
-    ///   <listheader><term>Valor</term><description>O que faz</description></listheader>
-    ///   <item>
-    ///     <term><c>null</c> (default)</term>
-    ///     <description>
-    ///       <b>Instrumenta somente se ainda nao houver instrumentacao no pipeline.</b> A
-    ///       deteccao e <c>GetService(typeof(OpenTelemetryChatClient))</c>, que atravessa a
-    ///       cadeia de delegates (medido). E este ramo, e so ele, que impede o span de chat
-    ///       duplicado.
-    ///     </description>
-    ///   </item>
-    ///   <item>
-    ///     <term><c>true</c></term>
-    ///     <description>
-    ///       Instrumenta sempre. Sobre um pipeline ja instrumentado, produz <b>dois</b>
-    ///       spans <c>chat</c> por invocacao — medido, e pinado por teste. Existe para
-    ///       documentar o risco, nao para ser ligado.
-    ///     </description>
-    ///   </item>
-    ///   <item>
-    ///     <term><c>false</c></term>
-    ///     <description>
-    ///       Nunca instrumenta. Com a <c>AgentFactory</c>, que monta o proprio pipeline
-    ///       (<c>UseProvidedChatClientAsIs = true</c>), isso significa <b>nenhum</b> span de
-    ///       <c>chat</c>: o slot que o MAF reservaria e ativaria sozinho nao existe nesse
-    ///       arranjo. Escolha consciente, nao default.
-    ///     </description>
-    ///   </item>
-    /// </list>
-    /// </remarks>
+    // null instrumenta so se o pipeline ainda nao tem OpenTelemetryChatClient; true duplica o span de chat.
     public bool? InstrumentChatClient { get; init; }
 }

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

@@ -2,32 +2,8 @@ using Microsoft.Extensions.AI;
 
 namespace Morph.AiKit.Providers;
 
-/// <summary>
-/// Constroi o <see cref="IChatClient"/> de um alias. E <b>a</b> costura do kit: o unico
-/// ponto em que o codigo toca um provider de verdade.
-/// </summary>
-/// <remarks>
-/// <para>
-/// O <see cref="ModelRegistry"/> nao sabe construir cliente de provider nenhum — de
-/// proposito. Quem sabe e uma implementacao desta interface, e e por isso que a suite do
-/// kit roda sem rede e sem chave de API: em teste, a fabrica devolve
-/// <c>FakeChatClient</c>. Num projeto, ela e o <c>switch</c> por
-/// <see cref="ModelAlias.Provider"/> descrito no standard
-/// <c>ai-agents-providers-model-registry</c> (<c>openai</c> e <c>ollama</c> de saida,
-/// os demais como branch nova).
-/// </para>
-/// <para>
-/// <b>Quem descarta o cliente:</b> o <see cref="ModelRegistry"/>. A fabrica cria; o
-/// registry memoiza por alias e descarta no proprio <c>Dispose</c>. Uma fabrica que
-/// guardasse e reaproveitasse clientes por fora criaria uma segunda cache, e duas caches
-/// da mesma coisa e como um cliente vazado sobrevive a um teste.
-/// </para>
-/// </remarks>
+// O ModelRegistry memoiza e descarta o que a fabrica cria; a fabrica nao guarda cliente.
 public interface IProviderClientFactory
 {
-    /// <summary>
-    /// Cria o cliente do alias dado. Chamado <b>uma vez por alias</b> pelo
-    /// <see cref="ModelRegistry"/>; o resultado e memoizado.
-    /// </summary>
     IChatClient CreateChatClient(ModelAlias alias);
 }

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

@@ -3,31 +3,6 @@ using Morph.AiKit.Agents;
 
 namespace Morph.AiKit.Providers;
 
-/// <summary>
-/// Um alias do <c>model-registry.v2.json</c>: o apelido estavel que os agentes citam, com
-/// tudo o que e preciso saber para alcancar o modelo e para contabilizar o que ele custa.
-/// </summary>
-/// <remarks>
-/// <para>
-/// Estende a forma de <c>templates/code/dotnet/ai-agents/ModelRegistry.cs.template</c>
-/// (provider + model + options) com os dois campos que a issue #92 exige e que o template
-/// v1 nao tinha: <see cref="Api"/> — o protocolo, por alias — e a decisao de tarifa
-/// (<see cref="Pricing"/> ou <see cref="PricingWaiver"/>).
-/// </para>
-/// <para>
-/// <b>Invariante do tipo:</b> ou existe <see cref="Pricing"/>, ou existe
-/// <see cref="PricingWaiver"/> — nunca os dois, nunca nenhum. E o que impede
-/// <c>cost_usd</c> de sair nulo la na frente: a ausencia de tarifa passa a ser uma decisao
-/// escrita por alguem, com motivo, e nao um campo que ninguem preencheu.
-/// <see cref="ValidatePricingDecision"/> e o guardiao dessa invariante e e chamado pelo
-/// <see cref="ModelRegistry"/> em toda carga.
-/// </para>
-/// </remarks>
-/// <param name="Provider">Familia de SDK: <c>openai</c>, <c>google</c>, <c>ollama</c>...</param>
-/// <param name="Model">Id do modelo no provider.</param>
-/// <param name="Api">Protocolo deste alias. Ver <see cref="AgentApi"/>.</param>
-/// <param name="Pricing">Tarifa por 1M de tokens, ou nulo se houver <see cref="PricingWaiver"/>.</param>
-/// <param name="Endpoint">Endpoint alternativo (Ollama, gateway). Nulo = o padrao do SDK.</param>
 public sealed record ModelAlias(
     string Provider,
     string Model,
@@ -35,35 +10,17 @@ public sealed record ModelAlias(
     ModelPricing? Pricing,
     string? Endpoint)
 {
-    /// <summary>A chave do alias no documento — <c>text-default</c>, <c>reasoning</c>...</summary>
     public required string Name { get; init; }
 
-    /// <summary>
-    /// Motivo, por extenso, de este alias nao ter tarifa. Preenchido <b>somente</b> quando
-    /// <see cref="Pricing"/> e nulo. Exemplo real: modelo local, onde a conta e a maquina e
-    /// nao o token.
-    /// </summary>
     public string? PricingWaiver { get; init; }
 
-    /// <summary>Limites conhecidos deste alias. Ver <see cref="ModelAliasConstraints"/>.</summary>
     public ModelAliasConstraints Constraints { get; init; } = ModelAliasConstraints.None;
 
-    /// <summary>Se ha tarifa. Quando falso, <see cref="PricingWaiver"/> explica por que.</summary>
     public bool HasPricing => Pricing is not null;
 
-    /// <summary>
-    /// A tarifa, ou uma falha que diz o nome do alias e o motivo declarado da ausencia.
-    /// Use quando o custo e obrigatorio; use <see cref="HasPricing"/> quando ausencia de
-    /// tarifa e um caminho previsto (e o caso do <c>UsageCostMiddleware</c>, que registra
-    /// tokens com custo zero e sinaliza a ausencia — nunca inventa tarifa).
-    /// </summary>
     public ModelPricing RequirePricing()
         => Pricing ?? throw ModelRegistryException.MissingPricing(Name, PricingWaiver);
 
-    /// <summary>
-    /// Cobra a invariante "tarifa OU dispensa, nunca ambas, nunca nenhuma".
-    /// </summary>
-    /// <exception cref="ModelRegistryException">Quando a decisao de tarifa nao foi tomada.</exception>
     public static void ValidatePricingDecision(ModelAlias alias)
     {
         ArgumentNullException.ThrowIfNull(alias);
@@ -87,21 +44,6 @@ public sealed record ModelAlias(
         }
     }
 
-    /// <summary>
-    /// Confronta uma requisicao com os limites declarados deste alias, <b>sem lancar</b> —
-    /// a decisao de abortar, avisar ou seguir e de quem chama (a <c>AgentFactory</c>).
-    /// </summary>
-    /// <param name="effectiveApi">
-    /// O protocolo que vai valer de fato: <c>spec.Api ?? alias.Api</c>. Veja
-    /// <see cref="AgentSpec.ResolveApi"/> — a precedencia mora la, nao aqui.
-    /// </param>
-    /// <param name="hasTools">Se a requisicao leva tools.</param>
-    /// <param name="reasoningEffort">
-    /// O esforco que sera enviado, ou nulo quando nada sera enviado. <b>Nulo nao e
-    /// violacao</b>: nesse caso vale o default do provider, e qual e ele o kit nao afirma
-    /// saber — modelar o contrario seria trocar um fato por folclore.
-    /// </param>
-    /// <param name="temperatureIsSet">Se a requisicao envia temperatura.</param>
     public AliasRequestCheck CheckRequest(
         AgentApi effectiveApi,
         bool hasTools,
@@ -135,38 +77,13 @@ public sealed record ModelAlias(
     }
 }
 
-/// <summary>
-/// Tarifa de um alias, em USD por 1 milhao de tokens. Vive junto do alias porque a conta
-/// so faz sentido com a tarifa daquele modelo — e porque a matematica do custo, escrita
-/// uma vez aqui, nao pode divergir entre o middleware (T11) e um relatorio qualquer.
-/// </summary>
-/// <param name="InputPerMTok">USD por 1M de tokens de entrada.</param>
-/// <param name="OutputPerMTok">USD por 1M de tokens de saida.</param>
-/// <param name="CachedInputPerMTok">
-/// USD por 1M de tokens de entrada servidos do cache do provider. Nulo = <b>nao ha desconto
-/// declarado</b>, e entao token cacheado e cobrado como entrada normal. Nulo NUNCA significa
-/// "de graca": inventar desconto e tao errado quanto inventar tarifa.
-/// </param>
 public sealed record ModelPricing(
     decimal InputPerMTok,
     decimal OutputPerMTok,
     decimal? CachedInputPerMTok)
 {
-    /// <summary>Tokens a que a tarifa se refere: 1 milhao.</summary>
     public const decimal TokensPerTariffUnit = 1_000_000m;
 
-    /// <summary>
-    /// Custo em USD de uma volta, a partir das contagens de token da resposta.
-    /// </summary>
-    /// <remarks>
-    /// <paramref name="cachedInputTokens"/> e um <b>subconjunto</b> de
-    /// <paramref name="inputTokens"/> — e assim que o provider reporta e assim que
-    /// <c>UsageDetails.CachedInputTokenCount</c> espelha. A parte cacheada so e cobrada a
-    /// parte quando <see cref="CachedInputPerMTok"/> existe; sem tarifa de cache, toda a
-    /// entrada e cobrada pela tarifa de entrada.
-    /// </remarks>
-    /// <exception cref="ArgumentOutOfRangeException">Contagem negativa.</exception>
-    /// <exception cref="ArgumentException">Tokens cacheados maiores que os de entrada.</exception>
     public decimal ComputeCostUsd(long inputTokens, long outputTokens, long? cachedInputTokens = null)
     {
         ArgumentOutOfRangeException.ThrowIfNegative(inputTokens);
@@ -196,52 +113,18 @@ public sealed record ModelPricing(
     }
 }
 
-/// <summary>
-/// Limites conhecidos de um alias. <b>Por alias, com procedencia escrita</b> — nunca uma
-/// regra universal chumbada no codigo.
-/// </summary>
-/// <remarks>
-/// A diferenca importa: "modelo de raciocinio rejeita tool" e folclore; o que a
-/// documentacao diz e mais estreito e cabe num campo. Um limite sem
-/// <see cref="Provenance"/> e recusado na carga do registry, justamente para que ninguem
-/// consiga gravar um "todo mundo sabe que" sem dizer de onde tirou.
-/// </remarks>
 public sealed record ModelAliasConstraints
 {
-    /// <summary>Nenhum limite declarado.</summary>
     public static readonly ModelAliasConstraints None = new();
 
-    /// <summary>
-    /// Na <b>Chat Completions</b>, este modelo so aceita tool calling com reasoning effort
-    /// <c>none</c>. E o limite exato descrito pela documentacao — mais estreito que
-    /// "modelo de raciocinio nao aceita tool" — e por isso e verificado com os quatro fatos
-    /// juntos em <see cref="ModelAlias.CheckRequest"/>: protocolo Chat, tools presentes,
-    /// effort enviado, e effort diferente de <c>none</c>.
-    /// </summary>
     public bool ToolCallingRequiresReasoningEffortNone { get; init; }
 
-    /// <summary>
-    /// Este modelo nao aceita <c>temperature</c>.
-    /// <b>Existe como flag por alias exatamente porque a afirmacao generica
-    /// ("temperatura e obsoleta para modelos de raciocinio") NAO foi confirmada em fonte
-    /// primaria.</b> Quem ligar isto assume a afirmacao para um modelo especifico e escreve
-    /// de onde tirou em <see cref="Provenance"/>.
-    /// </summary>
     public bool TemperatureUnsupported { get; init; }
 
-    /// <summary>
-    /// De onde veio o limite: documento, data, citacao. Obrigatorio quando qualquer flag
-    /// esta ligada.
-    /// </summary>
     public string? Provenance { get; init; }
 
-    /// <summary>Se ha qualquer limite declarado.</summary>
     public bool AnyFlagSet => ToolCallingRequiresReasoningEffortNone || TemperatureUnsupported;
 
-    /// <summary>
-    /// Cobra "limite ligado exige procedencia".
-    /// </summary>
-    /// <exception cref="ModelRegistryException">Flag ligada sem procedencia.</exception>
     public void ValidateProvenance(string aliasName)
     {
         if (AnyFlagSet && string.IsNullOrWhiteSpace(Provenance))
@@ -254,14 +137,7 @@ public sealed record ModelAliasConstraints
     }
 }
 
-/// <summary>
-/// Resultado de <see cref="ModelAlias.CheckRequest"/>. Result, nao excecao: um limite
-/// violado e informacao para quem chama decidir, nao fluxo de controle.
-/// </summary>
-/// <param name="IsSatisfied">Se a requisicao respeita todos os limites do alias.</param>
-/// <param name="Violations">Uma frase por limite violado, ja com a procedencia.</param>
 public sealed record AliasRequestCheck(bool IsSatisfied, IReadOnlyList<string> Violations)
 {
-    /// <summary>Nenhuma violacao.</summary>
     public static readonly AliasRequestCheck Satisfied = new(true, []);
 }

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

@@ -4,28 +4,6 @@ using Morph.AiKit.Agents;
 
 namespace Morph.AiKit.Providers;
 
-/// <summary>
-/// Fonte unica de "que modelo e esse apelido": le o documento
-/// <c>model-registry.v2.json</c>, resolve alias e memoiza um <see cref="IChatClient"/> por
-/// alias.
-/// </summary>
-/// <remarks>
-/// <para>
-/// Estende a forma de <c>templates/code/dotnet/ai-agents/ModelRegistry.cs.template</c> —
-/// documento JSON como fonte unica, cache de cliente por alias — e acrescenta as duas
-/// coisas que a issue #92 cobra: <b><c>api:</c> por alias</b> e <b>tarifa por alias</b>.
-/// A construcao do cliente saiu de dentro da classe e virou
-/// <see cref="IProviderClientFactory"/>: e essa mudanca que torna o kit testavel em CI sem
-/// rede e sem chave de API.
-/// </para>
-/// <para>
-/// <b>Toda falha aqui e falha de carga, nao fluxo de controle.</b> Documento invalido,
-/// alias sem decisao de tarifa, limite sem procedencia: tudo estoura em
-/// <see cref="FromJson"/>, na composicao, com o nome do alias e o motivo — nunca vira um
-/// nulo que atravessa tres camadas e aparece como custo zerado num relatorio. Para o
-/// caminho quente ha <see cref="TryResolve"/>, que nao lanca.
-/// </para>
-/// </remarks>
 public sealed class ModelRegistry : IDisposable
 {
     private const string SupportedDocumentVersion = "2.0";
@@ -48,6 +26,7 @@ public sealed class ModelRegistry : IDisposable
     };
 
     private readonly Dictionary<string, ModelAlias> _aliases;
+    // Um cliente por alias: cliente de provider carrega pool de conexao, e recria-lo por chamada vaza socket.
     private readonly Dictionary<string, IChatClient> _clients = new(StringComparer.Ordinal);
     private readonly IProviderClientFactory _factory;
     private readonly Lock _gate = new();
@@ -63,21 +42,10 @@ public sealed class ModelRegistry : IDisposable
         DefaultAlias = defaultAlias;
     }
 
-    /// <summary>Alias usado quando quem chama nao escolhe um. Nulo se o documento nao declara.</summary>
     public string? DefaultAlias { get; }
 
-    /// <summary>Os aliases do documento, na ordem em que foram declarados.</summary>
     public IReadOnlyCollection<string> Aliases => _aliases.Keys;
 
-    /// <summary>
-    /// Le o documento e valida tudo o que pode ser validado antes de a primeira requisicao
-    /// existir.
-    /// </summary>
-    /// <exception cref="ModelRegistryException">
-    /// JSON invalido, campo obrigatorio faltando, <c>api</c> desconhecida, chave nao
-    /// reconhecida, tarifa negativa, alias sem decisao de tarifa, ou limite sem procedencia.
-    /// A mensagem sempre nomeia o alias e o campo.
-    /// </exception>
     public static ModelRegistry FromJson(string json, IProviderClientFactory factory)
     {
         ArgumentException.ThrowIfNullOrWhiteSpace(json);
@@ -155,12 +123,6 @@ public sealed class ModelRegistry : IDisposable
         }
     }
 
-    /// <summary>
-    /// O alias, ou falha nomeando os aliases que existem.
-    /// <b>Nunca devolve nulo</b> — alias desconhecido e erro de configuracao, e um nulo
-    /// silencioso aqui vira um <c>NullReferenceException</c> em outro arquivo.
-    /// </summary>
-    /// <exception cref="ModelRegistryException">Alias desconhecido.</exception>
     public ModelAlias Resolve(string alias)
     {
         ArgumentException.ThrowIfNullOrWhiteSpace(alias);
@@ -170,7 +132,6 @@ public sealed class ModelRegistry : IDisposable
             : throw ModelRegistryException.UnknownAlias(alias, _aliases.Keys);
     }
 
-    /// <summary>Versao sem excecao de <see cref="Resolve"/>, para caminho quente.</summary>
     public bool TryResolve(string alias, out ModelAlias? resolved)
     {
         ArgumentException.ThrowIfNullOrWhiteSpace(alias);
@@ -178,14 +139,6 @@ public sealed class ModelRegistry : IDisposable
         return _aliases.TryGetValue(alias, out resolved);
     }
 
-    /// <summary>
-    /// O <see cref="IChatClient"/> do alias, <b>memoizado</b>: a fabrica e chamada uma unica
-    /// vez por alias, e as chamadas seguintes devolvem a mesma instancia. Cliente de provider
-    /// carrega pool de conexao e handler; recria-lo por chamada e como o vazamento de socket
-    /// costuma nascer.
-    /// </summary>
-    /// <exception cref="ModelRegistryException">Alias desconhecido, ou fabrica devolvendo nulo.</exception>
-    /// <exception cref="ObjectDisposedException">O registry ja foi descartado.</exception>
     public IChatClient GetChatClient(string alias)
     {
         var resolved = Resolve(alias);
@@ -209,10 +162,6 @@ public sealed class ModelRegistry : IDisposable
         }
     }
 
-    /// <summary>
-    /// Descarta os clientes memoizados. O registry e dono do que a fabrica criou — ver a
-    /// nota de ownership em <see cref="IProviderClientFactory"/>.
-    /// </summary>
     public void Dispose()
     {
         List<IChatClient> toDispose;
@@ -261,8 +210,6 @@ public sealed class ModelRegistry : IDisposable
             Constraints = ReadConstraints(name, element),
         };
 
-        // As duas invariantes que fazem este registry valer a pena: a decisao de tarifa e
-        // explicita, e todo limite declarado diz de onde veio.
         ModelAlias.ValidatePricingDecision(alias);
         alias.Constraints.ValidateProvenance(name);
 
@@ -273,8 +220,6 @@ public sealed class ModelRegistry : IDisposable
     {
         if (!element.TryGetProperty("api", out var api))
         {
-            // Omitir 'api' e cair na Responses API — a decisao da casa. Chat Completions
-            // exige alguem escrever "chat", ou seja, exige assumir a escolha.
             return AgentApi.Responses;
         }
 
@@ -284,9 +229,6 @@ public sealed class ModelRegistry : IDisposable
         {
             "responses" => AgentApi.Responses,
             "chat" => AgentApi.Chat,
-            // Midia entra no MESMO registry: um vocabulario so de alias, um lugar so onde
-            // se pergunta "que modelos este projeto usa". Um alias assim nao vira agente —
-            // a AgentFactory o recusa com erro nomeado.
             "images" => AgentApi.Images,
             "videos" => AgentApi.Videos,
             _ => throw ModelRegistryException.InvalidDocument(
@@ -416,55 +358,41 @@ public sealed class ModelRegistry : IDisposable
     }
 }
 
-/// <summary>Motivo de uma falha do <see cref="ModelRegistry"/>. Discrimina sem exigir hierarquia de excecao.</summary>
 public enum ModelRegistryError
 {
-    /// <summary>Documento invalido: JSON quebrado, campo faltando, valor fora do contrato.</summary>
     InvalidDocument = 0,
 
-    /// <summary>Alias inexistente no documento carregado.</summary>
     UnknownAlias = 1,
 
-    /// <summary>Alias sem tarifa, com o motivo da ausencia declarado no <c>pricingWaiver</c>.</summary>
     MissingPricing = 2,
 }
 
-/// <summary>
-/// Falha de configuracao do registry. <c>sealed</c> com um <see cref="Reason"/> em vez de
-/// uma arvore de subclasses: quem trata precisa discriminar o motivo, nao herdar dele.
-/// </summary>
 public sealed class ModelRegistryException : InvalidOperationException
 {
     private ModelRegistryException(ModelRegistryError reason, string message, Exception? inner = null)
         : base(message, inner)
         => Reason = reason;
 
-    /// <summary>Cria a excecao sem motivo especifico. Prefira as fabricas nomeadas.</summary>
     public ModelRegistryException(string message)
         : this(ModelRegistryError.InvalidDocument, message)
     {
     }
 
-    /// <summary>Cria a excecao encadeando a causa.</summary>
     public ModelRegistryException(string message, Exception innerException)
         : this(ModelRegistryError.InvalidDocument, message, innerException)
     {
     }
 
-    /// <summary>Por que falhou.</summary>
     public ModelRegistryError Reason { get; }
 
-    /// <summary>Documento fora do contrato.</summary>
     public static ModelRegistryException InvalidDocument(string message, Exception? inner = null)
         => new(ModelRegistryError.InvalidDocument, message, inner);
 
-    /// <summary>Alias desconhecido — a mensagem lista os que existem.</summary>
     public static ModelRegistryException UnknownAlias(string alias, IEnumerable<string> known)
         => new(
             ModelRegistryError.UnknownAlias,
             $"alias desconhecido: '{alias}'. Declarados no model-registry: {string.Join(", ", known)}.");
 
-    /// <summary>Tarifa exigida de um alias que declarou dispensa.</summary>
     public static ModelRegistryException MissingPricing(string alias, string? waiver)
         => new(
             ModelRegistryError.MissingPricing,