@polymorphism-tech/morph-spec 8.33.0 → 8.35.0

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

@@ -0,0 +1,267 @@
+using Microsoft.Extensions.AI;
+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,
+    AgentApi Api,
+    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);
+
+        var hasWaiver = !string.IsNullOrWhiteSpace(alias.PricingWaiver);
+
+        if (alias.Pricing is null && !hasWaiver)
+        {
+            throw new ModelRegistryException(
+                $"alias '{alias.Name}': sem 'pricing' e sem 'pricingWaiver'. O custo em USD nao " +
+                "pode ser calculado nem declarado ausente, e um custo nulo silencioso e " +
+                "exatamente a dor que este registry existe para acabar. Declare a tarifa em " +
+                "'pricing' ou escreva o motivo em 'pricingWaiver'.");
+        }
+
+        if (alias.Pricing is not null && hasWaiver)
+        {
+            throw new ModelRegistryException(
+                $"alias '{alias.Name}': tem 'pricing' E 'pricingWaiver'. As duas coisas juntas " +
+                "nao dizem qual vale. Deixe exatamente uma.");
+        }
+    }
+
+    /// <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,
+        ReasoningEffort? reasoningEffort,
+        bool temperatureIsSet)
+    {
+        List<string>? violations = null;
+
+        if (Constraints.ToolCallingRequiresReasoningEffortNone
+            && effectiveApi == AgentApi.Chat
+            && hasTools
+            && reasoningEffort is { } effort
+            && effort != ReasoningEffort.None)
+        {
+            (violations ??= []).Add(
+                $"alias '{Name}': na Chat Completions este modelo nao suporta tool calling com " +
+                $"reasoning effort diferente de 'none' (pedido: '{effort}'). Use api 'responses', " +
+                $"envie reasoning effort 'none', ou tire as tools. Procedencia: {Constraints.Provenance}");
+        }
+
+        if (Constraints.TemperatureUnsupported && temperatureIsSet)
+        {
+            (violations ??= []).Add(
+                $"alias '{Name}': este modelo foi declarado sem suporte a temperatura. " +
+                $"Procedencia: {Constraints.Provenance}");
+        }
+
+        return violations is null
+            ? AliasRequestCheck.Satisfied
+            : new AliasRequestCheck(false, violations);
+    }
+}
+
+/// <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);
+        ArgumentOutOfRangeException.ThrowIfNegative(outputTokens);
+
+        if (cachedInputTokens is { } cached)
+        {
+            ArgumentOutOfRangeException.ThrowIfNegative(cached);
+
+            if (cached > inputTokens)
+            {
+                throw new ArgumentException(
+                    $"tokens cacheados ({cached}) nao podem exceder os de entrada ({inputTokens}): " +
+                    "o cacheado e um subconjunto da entrada, nao uma parcela a mais.",
+                    nameof(cachedInputTokens));
+            }
+        }
+
+        var cachedCount = CachedInputPerMTok is null ? 0L : cachedInputTokens ?? 0L;
+        var fullPriceInput = inputTokens - cachedCount;
+
+        var cost = (fullPriceInput * InputPerMTok)
+            + (cachedCount * (CachedInputPerMTok ?? InputPerMTok))
+            + (outputTokens * OutputPerMTok);
+
+        return cost / TokensPerTariffUnit;
+    }
+}
+
+/// <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))
+        {
+            throw new ModelRegistryException(
+                $"alias '{aliasName}': ha limite declarado em 'constraints' sem 'provenance'. " +
+                "Um limite sem fonte e folclore com forca de codigo — escreva o documento e a " +
+                "data de onde ele saiu.");
+        }
+    }
+}
+
+/// <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, []);
+}