@polymorphism-tech/morph-spec 8.34.2 → 8.35.0

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

@@ -0,0 +1,208 @@
+using System.Runtime.CompilerServices;
+using Microsoft.Extensions.AI;
+using Morph.AiKit.Providers;
+
+namespace Morph.AiKit.Middleware;
+
+/// <summary>
+/// Middleware de <see cref="IChatClient"/> que le o <c>Usage</c> da resposta, aplica a
+/// tarifa do alias e publica uma linha de custo em <see cref="IUsageCostSink"/>.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <b>Onde ele entra no pipeline:</b> <b>ACIMA</b> da invocacao de funcoes, com a
+/// telemetria de chat abaixo dela (<c>usage-cost -&gt; function-invocation -&gt;
+/// OpenTelemetry -&gt; cliente do provider</c>). Na pratica: a
+/// <c>AgentFactory.BuildChatPipeline</c> registra o encaixe de custo <b>antes</b> de
+/// <c>UseFunctionInvocation</c>, e no <c>ChatClientBuilder</c> o primeiro registrado e o
+/// mais <b>externo</b>. A ordem nao e estetica, e o motivo e o
+/// <c>FunctionInvokingChatClient</c> (FICC): acima dele o middleware ve <b>uma</b> resposta
+/// cujo <c>Usage</c> ja vem com o total de todas as voltas de tool (medido: duas voltas de
+/// 10/4 e 30/6 chegam como <c>in=40, out=10</c>) e publica <b>uma</b> linha por chamada.
+/// Abaixo dele veria as respostas parciais — e leria o mesmo objeto <c>UsageDetails</c> que
+/// o proprio FICC <b>muta</b> para acumular, o que faria a mesma conta dar resultado
+/// diferente conforme a hora de ler. Isso e medido, nao argumentado, em
+/// <c>AgentFactoryTests.ThePipelineOrderIsUsageCostAboveFunctionInvocationAndTelemetryBelowIt</c>
+/// (sequencia <c>usage-cost:enter -&gt; telemetry:enter/exit x2 -&gt; usage-cost:exit</c>) e
+/// em <c>AgentFactoryTests.UsageCostAboveFunctionInvocationSeesTheUsageOfEveryToolRoundSummedOnce</c>.
+/// A montagem do pipeline e da <c>AgentFactory</c> (T10); daqui so depende a extensao
+/// <see cref="UsageCostChatClientBuilderExtensions.UseUsageCost"/>.
+/// </para>
+/// <para>
+/// <b>Nota de errata:</b> o <c>spec.md</c> sec. 3.1 desta feature prescrevia a seta
+/// literal <c>function-invocation -&gt; usage-cost -&gt; OpenTelemetry</c>, que se le ao
+/// contrario do que esta implementado aqui. A divergencia foi medida na T10 sec. 3.2 e esta
+/// registrada como <b>Errata E9</b> no proprio <c>spec.md</c> — o corpo do plano e
+/// append-only e continua com a seta antiga; a verdade e esta.
+/// </para>
+/// <para>
+/// <b>A conta e a do <see cref="ModelPricing.ComputeCostUsd"/>, nao uma segunda.</b> Este
+/// tipo nao contem aritmetica de tarifa: ele converte <c>Usage</c> em argumentos, chama a
+/// conta que ja existe e carimba o resultado. Reescrever a formula aqui daria dois numeros
+/// para o mesmo custo — que e literalmente a dor no nome desta epica (em ProspectPRO a
+/// conta esta repetida em cinco agentes).
+/// </para>
+/// <para>
+/// <b>Nunca lanca por causa de tarifa.</b> Alias sem tarifa e caminho previsto: sai
+/// <c>CostUsd = 0</c> com <see cref="UsageCostStatus.Waived"/> e o motivo escrito no
+/// record. Inventar tarifa e pior que nao ter. E resposta sem <c>Usage</c> sai como
+/// <see cref="UsageCostStatus.UsageMissing"/> — visivel, em vez de silenciosa.
+/// </para>
+/// </remarks>
+public sealed class UsageCostMiddleware : DelegatingChatClient
+{
+    private readonly ModelAlias _alias;
+    private readonly IUsageCostSink _sink;
+    private readonly TimeProvider _timeProvider;
+
+    /// <summary>Monta o middleware sobre um cliente interno.</summary>
+    /// <param name="innerClient">O proximo elo do pipeline.</param>
+    /// <param name="alias">
+    /// O alias que atende este cliente — de onde vem a tarifa e o nome que vai no record.
+    /// </param>
+    /// <param name="sink">Para onde as linhas de custo vao.</param>
+    /// <param name="timeProvider">
+    /// Relogio. Nulo usa <see cref="TimeProvider.System"/>. Injetavel porque o standard
+    /// <c>backend-dotnet-testing</c> proibe <c>DateTimeOffset.UtcNow</c> direto num tipo
+    /// testavel — sem isso, o instante do record e intestavel.
+    /// </param>
+    public UsageCostMiddleware(
+        IChatClient innerClient,
+        ModelAlias alias,
+        IUsageCostSink sink,
+        TimeProvider? timeProvider = null)
+        : base(innerClient)
+    {
+        ArgumentNullException.ThrowIfNull(alias);
+        ArgumentNullException.ThrowIfNull(sink);
+
+        _alias = alias;
+        _sink = sink;
+        _timeProvider = timeProvider ?? TimeProvider.System;
+    }
+
+    /// <inheritdoc />
+    public override async Task<ChatResponse> GetResponseAsync(
+        IEnumerable<ChatMessage> messages,
+        ChatOptions? options = null,
+        CancellationToken cancellationToken = default)
+    {
+        var response = await base.GetResponseAsync(messages, options, cancellationToken)
+            .ConfigureAwait(false);
+
+        Publish(response.Usage);
+
+        return response;
+    }
+
+    /// <inheritdoc />
+    /// <remarks>
+    /// No streaming o <c>Usage</c> chega como <see cref="UsageContent"/> avulso, tipicamente
+    /// no ultimo update — e pode chegar em mais de um pedaco. Os pedacos sao somados e a
+    /// linha de custo sai <b>uma unica vez</b>, ao fim da enumeracao: emitir por update daria
+    /// N linhas para uma volta so.
+    /// </remarks>
+    public override async IAsyncEnumerable<ChatResponseUpdate> GetStreamingResponseAsync(
+        IEnumerable<ChatMessage> messages,
+        ChatOptions? options = null,
+        [EnumeratorCancellation] CancellationToken cancellationToken = default)
+    {
+        UsageDetails? accumulated = null;
+
+        await foreach (var update in base.GetStreamingResponseAsync(messages, options, cancellationToken)
+            .ConfigureAwait(false))
+        {
+            foreach (var content in update.Contents)
+            {
+                if (content is UsageContent usage)
+                {
+                    (accumulated ??= new UsageDetails()).Add(usage.Details);
+                }
+            }
+
+            yield return update;
+        }
+
+        Publish(accumulated);
+    }
+
+    private void Publish(UsageDetails? usage)
+    {
+        var at = _timeProvider.GetUtcNow();
+
+        if (usage is null || (usage.InputTokenCount is null && usage.OutputTokenCount is null))
+        {
+            // Sem relato de uso nao ha o que tarifar. A linha sai assim mesmo, marcada: um
+            // custo que ninguem consegue medir precisa aparecer, nao sumir.
+            _sink.Record(new UsageCostRecord(_alias.Name, 0, 0, null, 0m, at)
+            {
+                Status = UsageCostStatus.UsageMissing,
+            });
+            return;
+        }
+
+        var input = usage.InputTokenCount ?? 0L;
+        var output = usage.OutputTokenCount ?? 0L;
+        var cached = usage.CachedInputTokenCount;
+
+        if (_alias.Pricing is not { } pricing)
+        {
+            // Caminho previsto, nunca excecao: o alias declarou por escrito que nao tem
+            // tarifa (o registry recusa a carga de um alias sem tarifa E sem dispensa).
+            _sink.Record(new UsageCostRecord(_alias.Name, input, output, cached, 0m, at)
+            {
+                Status = UsageCostStatus.Waived,
+                PricingWaiver = _alias.PricingWaiver,
+            });
+            return;
+        }
+
+        // Um provider que reporte 'cached' maior que 'input' esta se contradizendo; a conta
+        // do T8 recusa esse par. Aqui o dado inconsistente vira lacuna declarada, e nao uma
+        // excecao que derruba a resposta do usuario por causa de um contador.
+        if (cached > input)
+        {
+            _sink.Record(new UsageCostRecord(_alias.Name, input, output, cached, 0m, at)
+            {
+                Status = UsageCostStatus.UsageMissing,
+            });
+            return;
+        }
+
+        _sink.Record(new UsageCostRecord(
+            _alias.Name,
+            input,
+            output,
+            cached,
+            pricing.ComputeCostUsd(input, output, cached),
+            at)
+        {
+            Status = UsageCostStatus.Computed,
+        });
+    }
+}
+
+/// <summary>
+/// Registro do <see cref="UsageCostMiddleware"/> no pipeline de <see cref="IChatClient"/>.
+/// </summary>
+public static class UsageCostChatClientBuilderExtensions
+{
+    /// <summary>
+    /// Insere a contabilizacao de custo no pipeline, com a tarifa do alias dado.
+    /// </summary>
+    /// <param name="builder">O builder do pipeline.</param>
+    /// <param name="alias">Alias que atende este cliente.</param>
+    /// <param name="sink">Destino das linhas de custo.</param>
+    /// <param name="timeProvider">Relogio; nulo usa <see cref="TimeProvider.System"/>.</param>
+    /// <returns>O proprio builder, para encadear.</returns>
+    public static ChatClientBuilder UseUsageCost(
+        this ChatClientBuilder builder,
+        ModelAlias alias,
+        IUsageCostSink sink,
+        TimeProvider? timeProvider = null)
+    {
+        ArgumentNullException.ThrowIfNull(builder);
+
+        return builder.Use(inner => new UsageCostMiddleware(inner, alias, sink, timeProvider));
+    }
+}

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

@@ -0,0 +1,95 @@
+using Morph.AiKit.Providers;
+
+namespace Morph.AiKit.Middleware;
+
+/// <summary>
+/// Como o custo de uma volta ao modelo ficou conhecido. Existe para que
+/// <see cref="UsageCostRecord.CostUsd"/> possa ser um <see cref="decimal"/> nao-anulavel
+/// <b>sem que zero passe a significar tres coisas diferentes</b>.
+/// </summary>
+/// <remarks>
+/// A dor que esta feature nomeia e <c>cost_usd</c> saindo nulo. Trocar o nulo por um zero
+/// mudo seria trocar um defeito por outro pior — zero soma, nulo nao. Aqui o valor e sempre
+/// um numero e o status diz se aquele numero e uma medicao, uma decisao ou uma lacuna.
+/// </remarks>
+public enum UsageCostStatus
+{
+    /// <summary>
+    /// Tarifa do alias aplicada sobre uso reportado pelo provider. O unico status em que
+    /// <see cref="UsageCostRecord.CostUsd"/> e uma <b>medicao</b> — e o unico que pode
+    /// entrar numa soma de fatura sem ressalva.
+    /// </summary>
+    Computed = 0,
+
+    /// <summary>
+    /// O alias nao tem tarifa e <b>tem dispensa escrita</b>
+    /// (<c>ModelAlias.PricingWaiver</c>). Custo zero por decisao registrada — modelo local,
+    /// por exemplo, onde a conta e a maquina e nao o token. O motivo viaja em
+    /// <see cref="UsageCostRecord.PricingWaiver"/>: um zero aqui nunca e anonimo.
+    /// </summary>
+    Waived = 1,
+
+    /// <summary>
+    /// O provider <b>nao reportou</b> <c>Usage</c> nesta volta. Os tokens sao desconhecidos,
+    /// logo o custo tambem e: o zero em <see cref="UsageCostRecord.CostUsd"/> e ausencia de
+    /// medicao, <b>nao</b> gratuidade. Some com <see cref="Computed"/> apenas ciente disso.
+    /// </summary>
+    UsageMissing = 2,
+}
+
+/// <summary>
+/// O custo de uma volta ao modelo, ja calculado. <b>Uma linha por resposta</b>, pronta para
+/// virar registro de banco, metrica ou linha de fatura.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <b><see cref="CostUsd"/> nunca e nulo — por construcao do tipo.</b> Esse e o ponto
+/// inteiro: a dor catalogada na issue e um <c>cost_usd</c> nulo atravessando tres camadas
+/// e aparecendo como buraco no relatorio. A ausencia de tarifa deixou de poder chegar ate
+/// aqui por esquecimento: o <c>ModelRegistry</c> (T8) <b>recusa a carga</b> de um alias que
+/// nao declare <c>pricing</c> nem <c>pricingWaiver</c>. Logo, quando este record sai com
+/// <see cref="UsageCostStatus.Waived"/>, existe necessariamente um motivo escrito em
+/// <see cref="PricingWaiver"/>.
+/// </para>
+/// <para>
+/// <b>A conta nao mora aqui.</b> Ela mora em <see cref="ModelPricing.ComputeCostUsd"/>
+/// (T8), e o <see cref="UsageCostMiddleware"/> apenas a chama. Uma segunda aritmetica do
+/// mesmo custo e o defeito que esta epica tem no nome: em ProspectPRO ela esta repetida
+/// literalmente em cinco agentes, e duas copias da mesma conta divergem — a divergencia
+/// aparece na fatura.
+/// </para>
+/// </remarks>
+/// <param name="Alias">O alias do <c>ModelRegistry</c> que atendeu a volta.</param>
+/// <param name="InputTokens">Tokens de entrada reportados. Zero quando nao houve relato.</param>
+/// <param name="OutputTokens">Tokens de saida reportados. Zero quando nao houve relato.</param>
+/// <param name="CachedInputTokens">
+/// Tokens de entrada servidos do cache do provider, ou nulo quando o provider nao reporta.
+/// E <b>subconjunto</b> de <paramref name="InputTokens"/>, nunca uma parcela a mais.
+/// </param>
+/// <param name="CostUsd">
+/// Custo em USD. Nunca nulo; leia <see cref="Status"/> antes de somar.
+/// </param>
+/// <param name="At">Instante da volta, vindo do <see cref="TimeProvider"/> injetado.</param>
+public sealed record UsageCostRecord(
+    string Alias,
+    long InputTokens,
+    long OutputTokens,
+    long? CachedInputTokens,
+    decimal CostUsd,
+    DateTimeOffset At)
+{
+    /// <summary>Como o custo ficou conhecido. Ver <see cref="UsageCostStatus"/>.</summary>
+    public required UsageCostStatus Status { get; init; }
+
+    /// <summary>
+    /// O motivo escrito de o alias nao ter tarifa, copiado de
+    /// <c>ModelAlias.PricingWaiver</c>. Preenchido <b>somente</b> com
+    /// <see cref="UsageCostStatus.Waived"/>.
+    /// </summary>
+    public string? PricingWaiver { get; init; }
+
+    /// <summary>
+    /// Se <see cref="CostUsd"/> e uma medicao — o unico caso em que somar e honesto.
+    /// </summary>
+    public bool IsMeasuredCost => Status == UsageCostStatus.Computed;
+}

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

@@ -0,0 +1,38 @@
+<Project Sdk="Microsoft.NET.Sdk">
+
+  <PropertyGroup>
+    <RootNamespace>Morph.AiKit</RootNamespace>
+    <AssemblyName>Morph.AiKit</AssemblyName>
+  </PropertyGroup>
+
+  <!--
+    A REGRA DURA DE ai-agents/media-pipeline.md, presa por acessibilidade.
+
+    Morph.AiKit.Media.IMediaProvider e os tres adaptadores de provider sao `internal`: um
+    handler do projeto consumidor NAO consegue nomear o tipo que produz bytes, e o codigo
+    nao compila. A unica superficie publica e IMediaGenerator.EnqueueAsync, que devolve um
+    id de job.
+
+    Esta linha e a UNICA excecao, e ela existe para que a suite possa asserir a
+    acessibilidade por reflexao e exercitar o worker com um provider fake. Acrescentar um
+    segundo InternalsVisibleTo aqui — para o projeto consumidor, "so para testar" — desfaz
+    o mecanismo inteiro; o teste MediaAccessibilityTests grita se os tipos virarem publicos,
+    mas nao consegue ver quem mais foi convidado para dentro.
+  -->
+  <ItemGroup>
+    <InternalsVisibleTo Include="Morph.AiKit.Tests" />
+  </ItemGroup>
+
+  <!-- Sem atributo Version: as versoes vem de Directory.Packages.props (gerado do pin). -->
+  <ItemGroup>
+    <PackageReference Include="Microsoft.Agents.AI" />
+    <PackageReference Include="Microsoft.Extensions.AI" />
+    <PackageReference Include="OpenAI" />
+    <PackageReference Include="Google.GenAI" />
+    <PackageReference Include="ModelContextProtocol" />
+    <PackageReference Include="Microsoft.Extensions.AI.Evaluation" />
+    <PackageReference Include="Microsoft.Extensions.AI.Evaluation.Quality" />
+    <PackageReference Include="Microsoft.Extensions.AI.Evaluation.Reporting" />
+  </ItemGroup>
+
+</Project>

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

@@ -0,0 +1,119 @@
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+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);
+        ArgumentNullException.ThrowIfNull(options);
+
+        return builder.Use(inner => ShouldInstrument(inner, options)
+            ? new OpenTelemetryChatClient(inner, logger: null, sourceName: options.SourceName)
+            {
+                EnableSensitiveData = options.EnableSensitiveData,
+            }
+            : 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);
+        ArgumentNullException.ThrowIfNull(options);
+
+        return builder.Use(inner => inner.GetService(typeof(OpenTelemetryAgent)) is not null
+            ? inner
+            : new OpenTelemetryAgent(inner, options.SourceName)
+            {
+                EnableSensitiveData = options.EnableSensitiveData,
+            });
+    }
+
+    /// <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)
+    {
+        ArgumentNullException.ThrowIfNull(factoryOptions);
+        ArgumentNullException.ThrowIfNull(options);
+
+        return factoryOptions with
+        {
+            ConfigureChatTelemetry = (builder, spec, _) => builder.UseMorphTelemetry(ForSpec(options, spec)),
+            ConfigureAgentTelemetry = (builder, spec, _) => builder.UseMorphTelemetry(ForSpec(options, spec)),
+        };
+    }
+
+    private static MorphTelemetryOptions ForSpec(MorphTelemetryOptions options, AgentSpec spec)
+        => spec.Options.EnableSensitiveTelemetry is { } sensitive
+            ? 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>
+    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

@@ -0,0 +1,82 @@
+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>
+    public required string SourceName
+    {
+        get => _sourceName;
+        init
+        {
+            ArgumentException.ThrowIfNullOrWhiteSpace(value, nameof(SourceName));
+            _sourceName = value;
+        }
+    }
+
+    /// <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>
+    public bool? InstrumentChatClient { get; init; }
+}

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

@@ -0,0 +1,33 @@
+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>
+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);
+}