@polymorphism-tech/morph-spec 8.34.2 → 8.35.0

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

@@ -0,0 +1,474 @@
+using System.Text.Json;
+using Microsoft.Extensions.AI;
+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";
+
+    private static readonly string[] AllowedRootProperties = ["$schema", "version", "defaultAlias", "aliases"];
+
+    private static readonly string[] AllowedAliasProperties =
+        ["provider", "model", "api", "endpoint", "pricing", "pricingWaiver", "constraints"];
+
+    private static readonly string[] AllowedPricingProperties =
+        ["inputPerMTok", "outputPerMTok", "cachedInputPerMTok"];
+
+    private static readonly string[] AllowedConstraintProperties =
+        ["toolCallingRequiresReasoningEffortNone", "temperatureUnsupported", "provenance"];
+
+    private static readonly JsonDocumentOptions ParseOptions = new()
+    {
+        CommentHandling = JsonCommentHandling.Skip,
+        AllowTrailingCommas = true,
+    };
+
+    private readonly Dictionary<string, ModelAlias> _aliases;
+    private readonly Dictionary<string, IChatClient> _clients = new(StringComparer.Ordinal);
+    private readonly IProviderClientFactory _factory;
+    private readonly Lock _gate = new();
+    private bool _disposed;
+
+    private ModelRegistry(
+        Dictionary<string, ModelAlias> aliases,
+        string? defaultAlias,
+        IProviderClientFactory factory)
+    {
+        _aliases = aliases;
+        _factory = factory;
+        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);
+        ArgumentNullException.ThrowIfNull(factory);
+
+        JsonDocument document;
+        try
+        {
+            document = JsonDocument.Parse(json, ParseOptions);
+        }
+        catch (JsonException error)
+        {
+            throw ModelRegistryException.InvalidDocument(
+                $"model-registry: JSON invalido — {error.Message}",
+                error);
+        }
+
+        using (document)
+        {
+            var root = document.RootElement;
+
+            if (root.ValueKind != JsonValueKind.Object)
+            {
+                throw ModelRegistryException.InvalidDocument(
+                    $"model-registry: a raiz precisa ser um objeto, veio {root.ValueKind}.");
+            }
+
+            RejectUnknownProperties(root, AllowedRootProperties, "model-registry (raiz)");
+
+            if (root.TryGetProperty("version", out var version))
+            {
+                var declared = RequireString(version, "version", "model-registry (raiz)");
+                if (!string.Equals(declared, SupportedDocumentVersion, StringComparison.Ordinal))
+                {
+                    throw ModelRegistryException.InvalidDocument(
+                        $"model-registry: documento na versao '{declared}'. Este registry le a " +
+                        $"v{SupportedDocumentVersion}, que exige 'api' e a decisao de tarifa por alias — " +
+                        "campos que a v1 nao tem.");
+                }
+            }
+
+            if (!root.TryGetProperty("aliases", out var aliasesElement)
+                || aliasesElement.ValueKind != JsonValueKind.Object)
+            {
+                throw ModelRegistryException.InvalidDocument(
+                    "model-registry: falta o objeto 'aliases'.");
+            }
+
+            var aliases = new Dictionary<string, ModelAlias>(StringComparer.Ordinal);
+            foreach (var entry in aliasesElement.EnumerateObject())
+            {
+                aliases[entry.Name] = ReadAlias(entry.Name, entry.Value);
+            }
+
+            if (aliases.Count == 0)
+            {
+                throw ModelRegistryException.InvalidDocument(
+                    "model-registry: 'aliases' esta vazio. Um registry sem alias nao resolve nada.");
+            }
+
+            string? defaultAlias = null;
+            if (root.TryGetProperty("defaultAlias", out var defaultElement))
+            {
+                defaultAlias = RequireString(defaultElement, "defaultAlias", "model-registry (raiz)");
+
+                if (!aliases.ContainsKey(defaultAlias))
+                {
+                    throw ModelRegistryException.InvalidDocument(
+                        $"model-registry: 'defaultAlias' aponta para '{defaultAlias}', que nao esta " +
+                        $"em 'aliases'. Declarados: {string.Join(", ", aliases.Keys)}.");
+                }
+            }
+
+            return new ModelRegistry(aliases, defaultAlias, factory);
+        }
+    }
+
+    /// <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);
+
+        return _aliases.TryGetValue(alias, out var resolved)
+            ? resolved
+            : 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);
+
+        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);
+
+        lock (_gate)
+        {
+            ObjectDisposedException.ThrowIf(_disposed, this);
+
+            if (_clients.TryGetValue(alias, out var cached))
+            {
+                return cached;
+            }
+
+            var created = _factory.CreateChatClient(resolved)
+                ?? throw ModelRegistryException.InvalidDocument(
+                    $"alias '{alias}': a IProviderClientFactory devolveu nulo. Uma fabrica que nao " +
+                    "sabe construir o cliente precisa falhar dizendo o motivo, nao devolver nulo.");
+
+            _clients[alias] = created;
+            return created;
+        }
+    }
+
+    /// <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;
+
+        lock (_gate)
+        {
+            if (_disposed)
+            {
+                return;
+            }
+
+            _disposed = true;
+            toDispose = [.. _clients.Values];
+            _clients.Clear();
+        }
+
+        foreach (var client in toDispose)
+        {
+            client.Dispose();
+        }
+    }
+
+    private static ModelAlias ReadAlias(string name, JsonElement element)
+    {
+        if (element.ValueKind != JsonValueKind.Object)
+        {
+            throw ModelRegistryException.InvalidDocument(
+                $"alias '{name}': precisa ser um objeto, veio {element.ValueKind}.");
+        }
+
+        RejectUnknownProperties(element, AllowedAliasProperties, $"alias '{name}'");
+
+        var alias = new ModelAlias(
+            Provider: RequireString(RequireProperty(element, "provider", name), "provider", $"alias '{name}'"),
+            Model: RequireString(RequireProperty(element, "model", name), "model", $"alias '{name}'"),
+            Api: ReadApi(name, element),
+            Pricing: ReadPricing(name, element),
+            Endpoint: element.TryGetProperty("endpoint", out var endpoint)
+                ? RequireString(endpoint, "endpoint", $"alias '{name}'")
+                : null)
+        {
+            Name = name,
+            PricingWaiver = element.TryGetProperty("pricingWaiver", out var waiver)
+                ? RequireString(waiver, "pricingWaiver", $"alias '{name}'")
+                : null,
+            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);
+
+        return alias;
+    }
+
+    private static AgentApi ReadApi(string name, JsonElement element)
+    {
+        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;
+        }
+
+        var declared = RequireString(api, "api", $"alias '{name}'");
+
+        return declared.ToLowerInvariant() switch
+        {
+            "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(
+                $"alias '{name}': api '{declared}' nao existe. Valores validos: 'responses' (padrao " +
+                "quando o campo e omitido), 'chat', 'images' e 'videos'."),
+        };
+    }
+
+    private static ModelPricing? ReadPricing(string name, JsonElement element)
+    {
+        if (!element.TryGetProperty("pricing", out var pricing) || pricing.ValueKind == JsonValueKind.Null)
+        {
+            return null;
+        }
+
+        if (pricing.ValueKind != JsonValueKind.Object)
+        {
+            throw ModelRegistryException.InvalidDocument(
+                $"alias '{name}': 'pricing' precisa ser um objeto, veio {pricing.ValueKind}.");
+        }
+
+        RejectUnknownProperties(pricing, AllowedPricingProperties, $"alias '{name}' / pricing");
+
+        return new ModelPricing(
+            InputPerMTok: RequireTariff(name, pricing, "inputPerMTok"),
+            OutputPerMTok: RequireTariff(name, pricing, "outputPerMTok"),
+            CachedInputPerMTok:
+                pricing.TryGetProperty("cachedInputPerMTok", out var cached)
+                && cached.ValueKind != JsonValueKind.Null
+                    ? RequireTariff(name, pricing, "cachedInputPerMTok")
+                    : null);
+    }
+
+    private static ModelAliasConstraints ReadConstraints(string name, JsonElement element)
+    {
+        if (!element.TryGetProperty("constraints", out var constraints)
+            || constraints.ValueKind == JsonValueKind.Null)
+        {
+            return ModelAliasConstraints.None;
+        }
+
+        if (constraints.ValueKind != JsonValueKind.Object)
+        {
+            throw ModelRegistryException.InvalidDocument(
+                $"alias '{name}': 'constraints' precisa ser um objeto, veio {constraints.ValueKind}.");
+        }
+
+        RejectUnknownProperties(constraints, AllowedConstraintProperties, $"alias '{name}' / constraints");
+
+        return new ModelAliasConstraints
+        {
+            ToolCallingRequiresReasoningEffortNone =
+                ReadBool(name, constraints, "toolCallingRequiresReasoningEffortNone"),
+            TemperatureUnsupported = ReadBool(name, constraints, "temperatureUnsupported"),
+            Provenance = constraints.TryGetProperty("provenance", out var provenance)
+                ? RequireString(provenance, "provenance", $"alias '{name}' / constraints")
+                : null,
+        };
+    }
+
+    private static JsonElement RequireProperty(JsonElement element, string property, string aliasName)
+        => element.TryGetProperty(property, out var value)
+            ? value
+            : throw ModelRegistryException.InvalidDocument(
+                $"alias '{aliasName}': falta o campo obrigatorio '{property}'.");
+
+    private static string RequireString(JsonElement element, string property, string owner)
+    {
+        if (element.ValueKind != JsonValueKind.String)
+        {
+            throw ModelRegistryException.InvalidDocument(
+                $"{owner}: '{property}' precisa ser string, veio {element.ValueKind}.");
+        }
+
+        var value = element.GetString();
+
+        return string.IsNullOrWhiteSpace(value)
+            ? throw ModelRegistryException.InvalidDocument($"{owner}: '{property}' esta vazio.")
+            : value;
+    }
+
+    private static decimal RequireTariff(string aliasName, JsonElement pricing, string property)
+    {
+        var value = pricing.GetProperty(property);
+
+        if (value.ValueKind != JsonValueKind.Number || !value.TryGetDecimal(out var tariff))
+        {
+            throw ModelRegistryException.InvalidDocument(
+                $"alias '{aliasName}' / pricing: '{property}' precisa ser um numero em USD por 1M de " +
+                $"tokens, veio {value.ValueKind}.");
+        }
+
+        return tariff < 0
+            ? throw ModelRegistryException.InvalidDocument(
+                $"alias '{aliasName}' / pricing: '{property}' e negativo ({tariff}).")
+            : tariff;
+    }
+
+    private static bool ReadBool(string aliasName, JsonElement constraints, string property)
+    {
+        if (!constraints.TryGetProperty(property, out var value))
+        {
+            return false;
+        }
+
+        return value.ValueKind switch
+        {
+            JsonValueKind.True => true,
+            JsonValueKind.False => false,
+            _ => throw ModelRegistryException.InvalidDocument(
+                $"alias '{aliasName}' / constraints: '{property}' precisa ser booleano, veio {value.ValueKind}."),
+        };
+    }
+
+    private static void RejectUnknownProperties(JsonElement element, string[] allowed, string owner)
+    {
+        foreach (var property in element.EnumerateObject())
+        {
+            if (!allowed.Contains(property.Name, StringComparer.Ordinal))
+            {
+                throw ModelRegistryException.InvalidDocument(
+                    $"{owner}: campo '{property.Name}' nao e reconhecido. Aceitos: " +
+                    $"{string.Join(", ", allowed)}. (Um campo com erro de digitacao seria lido como " +
+                    "ausente, e ausencia silenciosa e o defeito que este registry existe para matar.)");
+            }
+        }
+    }
+}
+
+/// <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,
+            $"alias '{alias}': nao tem tarifa. Motivo declarado: " +
+            $"{waiver ?? "(nenhum — o alias nem passou pela validacao do registry)"}. " +
+            "Use HasPricing quando ausencia de tarifa e um caminho previsto.");
+}

package/framework/templates/dotnet/ai-kit/src/Morph.AiKit/Providers/model-registry.v2.json

@@ -0,0 +1,87 @@
+// EXEMPLAR: model-registry.v2.json — copie para config/model-registry.json no projeto.
+// LIDO POR: Morph.AiKit.Providers.ModelRegistry.FromJson
+// STANDARD:  ai-agents-providers-model-registry
+//
+// O que a v2 acrescenta a v1 (templates/code/dotnet/ai-agents/model-registry.json.template):
+//
+//   api:            protocolo POR ALIAS. Omitido = "responses" (a decisao da casa).
+//                   "chat" e opt-in explicito: alguem tem de escrever, e assumir.
+//   pricing:        tarifa em USD por 1M de tokens. Insumo do UsageCostMiddleware.
+//   pricingWaiver:  o motivo, por extenso, de NAO haver tarifa.
+//   constraints:    limites conhecidos DESTE alias, com procedencia obrigatoria.
+//
+// REGRA DURA: todo alias declara "pricing" OU "pricingWaiver" — nunca os dois, nunca
+// nenhum. E o que impede cost_usd de sair nulo tres camadas adiante. Faltando a decisao,
+// o registry recusa carregar dizendo o nome do alias.
+//
+// AS TARIFAS ABAIXO SAO ILUSTRATIVAS. Nenhuma foi verificada contra tabela de preco de
+// provider — sao numeros redondos para o exemplo compilar e os testes terem o que somar.
+// Um projeto que copiar este arquivo troca CADA valor pela tarifa apurada, na data em que
+// apurou. Copiar preco de exemplo para producao e faturar em cima de folclore.
+{
+  "version": "2.0",
+  "defaultAlias": "text-default",
+
+  "aliases": {
+    // 'api' omitido de proposito: cai em "responses", o padrao da casa.
+    "text-default": {
+      "provider": "openai",
+      "model": "gpt-5.4-mini",
+      "pricing": {
+        "inputPerMTok": 0.25,
+        "outputPerMTok": 2.0,
+        "cachedInputPerMTok": 0.025
+      }
+    },
+
+    "text-heavy": {
+      "provider": "openai",
+      "model": "gpt-5.4",
+      "api": "responses",
+      "pricing": {
+        "inputPerMTok": 1.25,
+        "outputPerMTok": 10.0,
+        "cachedInputPerMTok": 0.125
+      }
+    },
+
+    // O alias que existe para mostrar POR QUE 'api' e por alias: mesmo modelo do
+    // 'text-heavy', outro protocolo — e com o protocolo vem um limite que a Responses API
+    // nao tem. O limite modelado e o da documentacao, e nada alem dele.
+    "text-heavy-chat": {
+      "provider": "openai",
+      "model": "gpt-5.4",
+      "api": "chat",
+      "pricing": {
+        "inputPerMTok": 1.25,
+        "outputPerMTok": 10.0,
+        "cachedInputPerMTok": 0.125
+      },
+      "constraints": {
+        "toolCallingRequiresReasoningEffortNone": true,
+        "provenance": "Documentacao OpenAI, citada na issue #93: 'Starting with GPT-5.4, Chat Completions does not support tool calling with reasoning_effort values other than none'. Nao e 'modelo de raciocinio rejeita tool' — o limite e mais estreito: vale na Chat Completions, com tools, e so quando um reasoning_effort diferente de none e enviado."
+      }
+    },
+
+    // Provider de protocolo unico: 'api' omitido porque escrever 'chat' aqui sugeriria uma
+    // escolha que na API do Google nao existe.
+    "vision": {
+      "provider": "google",
+      "model": "gemini-2.5-flash",
+      "pricing": {
+        "inputPerMTok": 0.3,
+        "outputPerMTok": 2.5,
+        "cachedInputPerMTok": null
+      }
+    },
+
+    // Sem tarifa — e a ausencia esta ESCRITA, nao esquecida. E assim que um alias sem
+    // preco atravessa a validacao sem virar custo nulo silencioso.
+    "local-dev": {
+      "provider": "ollama",
+      "model": "llama3.2:3b",
+      "endpoint": "http://localhost:11434/v1",
+      "pricingWaiver": "modelo local: nao ha tarifa por token. O custo e a maquina que roda o Ollama, e ele nao e atribuivel por requisicao."
+    }
+  }
+}