@polymorphism-tech/morph-spec 8.34.2 → 8.35.0

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

@@ -0,0 +1,288 @@
+using Microsoft.Extensions.AI;
+using OpenAI.Images;
+
+namespace Morph.AiKit.Media.Providers;
+
+/// <summary>
+/// Adaptador de imagem da OpenAI. <b><c>internal</c></b> — ver <see cref="IMediaProvider"/>.
+/// </summary>
+/// <remarks>
+/// <para>
+/// A chamada passa pela abstracao <see cref="IImageGenerator"/> de
+/// <c>Microsoft.Extensions.AI</c>, e nao pelo <c>ImageClient</c> cru, para que o pipeline
+/// nao fique acoplado ao SDK de um provider. A ponte oficial
+/// (<c>Microsoft.Extensions.AI.OpenAI.AsIImageGenerator()</c>) <b>nao esta no pin deste
+/// kit</b>, entao o adaptador <see cref="OpenAIImageGenerator"/> vive aqui, escrito a mao
+/// sobre o <c>ImageClient</c>. Trocar por <c>AsIImageGenerator()</c> e uma linha, no dia em
+/// que o pacote entrar em <c>framework/ai-pin.json</c>.
+/// </para>
+/// <para>
+/// <b>Medido contra o pin em 2026-09-08, nao suposto:</b>
+/// <c>Microsoft.Extensions.AI.IImageGenerator</c> carrega <c>[Experimental("MEAI001")]</c>
+/// e herda <c>IDisposable</c>; <c>ImageGenerationRequest</c> tem <c>Prompt</c> e
+/// <c>OriginalImages</c> (<c>IEnumerable&lt;AIContent&gt;</c>), e tambem e experimental;
+/// <c>ImageGenerationOptions</c> <b>nao</b> tem propriedade tipada para
+/// <c>quality</c>/<c>background</c>/<c>input_fidelity</c> — por isso a qualidade viaja em
+/// <c>AdditionalProperties</c> e e este adaptador que a traduz para o SDK.
+/// </para>
+/// </remarks>
+internal sealed class OpenAIImageProvider : IMediaProvider
+{
+    /// <summary>A chave sob a qual a qualidade viaja em <c>AdditionalProperties</c>.</summary>
+    internal const string QualityKey = "quality";
+
+    private readonly IMediaClientFactory _clients;
+
+    public OpenAIImageProvider(IMediaClientFactory clients)
+    {
+        ArgumentNullException.ThrowIfNull(clients);
+        _clients = clients;
+    }
+
+    /// <inheritdoc />
+    public string Provider => "openai";
+
+    /// <inheritdoc />
+    public bool Supports(MediaKind kind) => kind == MediaKind.Image;
+
+    /// <inheritdoc />
+    public async Task<MediaResult<MediaArtifact>> ProduceAsync(
+        MediaRequest request,
+        MediaAliasBinding binding,
+        CancellationToken cancellationToken)
+    {
+        ArgumentNullException.ThrowIfNull(request);
+        ArgumentNullException.ThrowIfNull(binding);
+
+        var client = _clients.CreateOpenAiImageClient(binding);
+        if (client is null)
+        {
+            return MediaResult<MediaArtifact>.Fail(
+                MediaErrorCode.ProviderFailure,
+                $"alias '{binding.Alias}': a fabrica de clientes nao construiu um ImageClient para o provider 'openai'.");
+        }
+
+#pragma warning disable MEAI001 // IImageGenerator/ImageGenerationRequest sao experimentais: a superficie pode mudar entre menores. Risco assumido por escrito.
+        using IImageGenerator generator = new OpenAIImageGenerator(client);
+
+        var generationRequest = new ImageGenerationRequest { Prompt = request.Prompt };
+
+        if (request.References.Count > 0)
+        {
+            // OriginalImages e o gancho de EDICAO: preserva o produto real em vez de
+            // recria-lo. Gerar do zero quando a foto existe inventa material, medida ou cor
+            // que o produto nao tem — o claim visual falso que o AI Act art. 50 mira.
+            generationRequest.OriginalImages =
+                [.. request.References.Select(r => new DataContent(r.Bytes, r.MediaType))];
+        }
+
+        var options = new Microsoft.Extensions.AI.ImageGenerationOptions
+        {
+            ModelId = binding.Model,
+            MediaType = request.Options.MediaType,
+            Count = request.Options.Count,
+        };
+
+        if (request.Options is { Width: { } width, Height: { } height })
+        {
+            options.ImageSize = new System.Drawing.Size(width, height);
+        }
+
+        if (request.Options.Quality is { } quality)
+        {
+            // Nao ha propriedade tipada na 10.9.0 — medido. Vai por AdditionalProperties, e
+            // o adaptador acima e quem traduz para o SDK.
+            options.AdditionalProperties = new AdditionalPropertiesDictionary
+            {
+                [QualityKey] = quality.ToString(),
+            };
+        }
+
+        try
+        {
+            var response = await generator
+                .GenerateAsync(generationRequest, options, cancellationToken)
+                .ConfigureAwait(false);
+
+            var data = response.Contents.OfType<DataContent>().FirstOrDefault();
+            if (data is null)
+            {
+                return MediaResult<MediaArtifact>.Fail(
+                    MediaErrorCode.ProviderFailure,
+                    $"alias '{binding.Alias}': a resposta nao trouxe DataContent. Uma resposta so com URL " +
+                    "seria um arquivo que expira, e este pipeline guarda BYTES.");
+            }
+
+            return MediaResult<MediaArtifact>.Ok(new MediaArtifact(
+                MediaKind.Image,
+                data.MediaType,
+                data.Data,
+                RevisedPrompt: (response.RawRepresentation as GeneratedImage)?.RevisedPrompt,
+                ResponseId: null,
+                // Os bytes chegam como o provider os produziu: nenhum re-encode entre a
+                // resposta e o blob. E o que mantem a credencial C2PA viva.
+                C2paPreserved: true));
+        }
+#pragma warning restore MEAI001
+        catch (System.ClientModel.ClientResultException ex)
+        {
+            // Bloqueio de moderacao e resposta DEFINITIVA, nunca erro tecnico: retentar
+            // gasta para receber o mesmo "nao". A distincao mora aqui, no unico ponto que
+            // ve o codigo HTTP.
+            return ex.Status == 400
+                ? MediaResult<MediaArtifact>.Fail(
+                    MediaErrorCode.PolicyBlocked,
+                    $"alias '{binding.Alias}': o provider recusou o pedido (HTTP 400): {ex.Message}")
+                : MediaResult<MediaArtifact>.Fail(
+                    MediaErrorCode.ProviderFailure,
+                    $"alias '{binding.Alias}': falha tecnica (HTTP {ex.Status}): {ex.Message}");
+        }
+    }
+}
+
+/// <summary>
+/// <see cref="IImageGenerator"/> escrito a mao sobre o <c>ImageClient</c> do SDK da OpenAI.
+/// </summary>
+/// <remarks>
+/// Existe porque <c>Microsoft.Extensions.AI.OpenAI</c> — que traz
+/// <c>AsIImageGenerator()</c> — nao esta em <c>framework/ai-pin.json</c>, e acrescentar
+/// pacote e mexer no pin. O contrato imitado e o mesmo: <c>OriginalImages</c> vazio vira
+/// <c>GenerateImageAsync</c>; com referencia, vira <c>GenerateImageEditAsync</c>, que e o
+/// caminho que PRESERVA o produto real.
+/// </remarks>
+// OPENAI001 entra junto, e nao por preguica: GeneratedImageQuality.{Low,Medium,High}Quality
+// e ImageEditOptions.Quality carregam o diagnostico de "evaluation only" no OpenAI 2.13.0 —
+// medido pelo compilador, nao suposto. Suprimir os dois com o motivo escrito e o item 3 do
+// checklist de ai-agents/modalities-image-gen.md.
+#pragma warning disable MEAI001, OPENAI001
+internal sealed class OpenAIImageGenerator : IImageGenerator
+{
+    private readonly ImageClient _client;
+
+    public OpenAIImageGenerator(ImageClient client)
+    {
+        ArgumentNullException.ThrowIfNull(client);
+        _client = client;
+    }
+
+    public async Task<ImageGenerationResponse> GenerateAsync(
+        ImageGenerationRequest request,
+        Microsoft.Extensions.AI.ImageGenerationOptions? options,
+        CancellationToken cancellationToken = default)
+    {
+        ArgumentNullException.ThrowIfNull(request);
+
+        var reference = request.OriginalImages?.OfType<DataContent>().FirstOrDefault();
+
+        GeneratedImage image = reference is null
+            ? (await _client
+                .GenerateImageAsync(request.Prompt ?? string.Empty, BuildGenerationOptions(options), cancellationToken)
+                .ConfigureAwait(false)).Value
+            : (await _client
+                .GenerateImageEditAsync(
+                    new MemoryStream(reference.Data.ToArray()),
+                    FileNameFor(reference.MediaType),
+                    request.Prompt ?? string.Empty,
+                    BuildEditOptions(options),
+                    cancellationToken)
+                .ConfigureAwait(false)).Value;
+
+        var mediaType = options?.MediaType ?? "image/png";
+
+        return new ImageGenerationResponse([new DataContent(image.ImageBytes.ToMemory(), mediaType)])
+        {
+            RawRepresentation = image,
+        };
+    }
+
+    public object? GetService(Type serviceType, object? serviceKey = null)
+    {
+        ArgumentNullException.ThrowIfNull(serviceType);
+
+        if (serviceKey is not null)
+        {
+            return null;
+        }
+
+        return serviceType.IsInstanceOfType(_client) ? _client
+            : serviceType.IsInstanceOfType(this) ? this
+            : null;
+    }
+
+    public void Dispose()
+    {
+        // O ImageClient nao e IDisposable e o seu tempo de vida e do projeto: a fabrica de
+        // clientes cria, o projeto descarta. Descartar aqui seria uma segunda dona do mesmo
+        // recurso — foi assim que um cliente vazou de um teste, uma vez.
+    }
+
+    private static OpenAI.Images.ImageGenerationOptions BuildGenerationOptions(
+        Microsoft.Extensions.AI.ImageGenerationOptions? options)
+    {
+        var sdk = new OpenAI.Images.ImageGenerationOptions
+        {
+            // Bytes, sempre. Uma URL de provider expira, e um caminho quebrado depois e um
+            // arquivo pelo qual se pagou e que nao existe mais.
+            ResponseFormat = GeneratedImageFormat.Bytes,
+        };
+
+        if (options?.ImageSize is { } size)
+        {
+            sdk.Size = new GeneratedImageSize(size.Width, size.Height);
+        }
+
+        if (QualityOf(options) is { } quality)
+        {
+            sdk.Quality = quality;
+        }
+
+        return sdk;
+    }
+
+    private static ImageEditOptions BuildEditOptions(Microsoft.Extensions.AI.ImageGenerationOptions? options)
+    {
+        var sdk = new ImageEditOptions { ResponseFormat = GeneratedImageFormat.Bytes };
+
+        if (options?.ImageSize is { } size)
+        {
+            sdk.Size = new GeneratedImageSize(size.Width, size.Height);
+        }
+
+        if (QualityOf(options) is { } quality)
+        {
+            sdk.Quality = quality;
+        }
+
+        return sdk;
+    }
+
+    /// <summary>
+    /// Traduz a qualidade que viajou em <c>AdditionalProperties</c>. Chave ausente devolve
+    /// nulo — e nulo significa "nao envia ao provider", nunca "manda o default do kit".
+    /// </summary>
+    private static GeneratedImageQuality? QualityOf(Microsoft.Extensions.AI.ImageGenerationOptions? options)
+    {
+        if (options?.AdditionalProperties is not { } extra
+            || !extra.TryGetValue(OpenAIImageProvider.QualityKey, out var raw)
+            || raw is null)
+        {
+            return null;
+        }
+
+        return raw.ToString() switch
+        {
+            nameof(MediaQuality.Low) => GeneratedImageQuality.LowQuality,
+            nameof(MediaQuality.Medium) => GeneratedImageQuality.MediumQuality,
+            nameof(MediaQuality.High) => GeneratedImageQuality.HighQuality,
+            _ => null,
+        };
+    }
+
+    private static string FileNameFor(string? mediaType) => mediaType switch
+    {
+        "image/jpeg" or "image/jpg" => "reference.jpg",
+        "image/webp" => "reference.webp",
+        _ => "reference.png",
+    };
+}
+#pragma warning restore MEAI001

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

@@ -0,0 +1,158 @@
+using Google.GenAI.Types;
+
+namespace Morph.AiKit.Media.Providers;
+
+/// <summary>
+/// Adaptador de video do Veo. <b><c>internal</c></b> — ver <see cref="IMediaProvider"/>.
+/// </summary>
+/// <remarks>
+/// <para>
+/// <b>E o unico caminho de video com SDK .NET oficial</b> depois do desligamento da Sora
+/// (data em <c>ai-agents/media-video.md</c>, secao Deprecacoes). Seedance, Kling e Runway
+/// exigem <c>HttpClient</c> tipado com DTOs proprios, e por isso nao tem adaptador aqui.
+/// </para>
+/// <para>
+/// <b>Assinatura medida contra Google.GenAI 1.21.0, nao lida em blog:</b>
+/// <c>Models.GenerateVideosAsync(string model, GenerateVideosSource source,
+/// GenerateVideosConfig config, CancellationToken)</c> devolve
+/// <c>GenerateVideosOperation</c> — o prompt vai DENTRO de <c>GenerateVideosSource</c>, e
+/// nao como parametro solto. O polling e
+/// <c>Operations.GetAsync(operation, config, ct)</c>, e o veredito e
+/// <c>operation.Done</c>.
+/// </para>
+/// <para>
+/// <b>Os bytes sao baixados AQUI.</b> O Veo retem o arquivo por 2 dias; devolver a URL e
+/// entregar um link que morre. Quando a resposta so traz <c>Uri</c>, este adaptador recusa
+/// com motivo em vez de guardar a URL fingindo que e permanente.
+/// </para>
+/// </remarks>
+internal sealed class VeoVideoProvider : IMediaProvider
+{
+    /// <summary>Intervalo entre voltas do polling. ~10 s e o intervalo que a doc do Veo usa.</summary>
+    internal static readonly TimeSpan PollInterval = TimeSpan.FromSeconds(10);
+
+    /// <summary>
+    /// Teto de voltas. Existe porque <c>Done</c> que nunca vira <c>true</c> e um caso real,
+    /// e um laco sem saida e indistinguivel de um worker travado. 60 voltas cobrem os 6 min
+    /// documentados como pior caso, com folga.
+    /// </summary>
+    internal const int MaxPolls = 60;
+
+    private readonly IMediaClientFactory _clients;
+    private readonly Func<TimeSpan, CancellationToken, Task> _delay;
+
+    public VeoVideoProvider(IMediaClientFactory clients, Func<TimeSpan, CancellationToken, Task>? delay = null)
+    {
+        ArgumentNullException.ThrowIfNull(clients);
+        _clients = clients;
+        _delay = delay ?? Task.Delay;
+    }
+
+    /// <inheritdoc />
+    public string Provider => "google";
+
+    /// <inheritdoc />
+    public bool Supports(MediaKind kind) => kind == MediaKind.Video;
+
+    /// <inheritdoc />
+    public async Task<MediaResult<MediaArtifact>> ProduceAsync(
+        MediaRequest request,
+        MediaAliasBinding binding,
+        CancellationToken cancellationToken)
+    {
+        ArgumentNullException.ThrowIfNull(request);
+        ArgumentNullException.ThrowIfNull(binding);
+
+        var client = _clients.CreateGoogleClient(binding);
+        if (client is null)
+        {
+            return MediaResult<MediaArtifact>.Fail(
+                MediaErrorCode.ProviderFailure,
+                $"alias '{binding.Alias}': a fabrica de clientes nao construiu um Google.GenAI.Client.");
+        }
+
+        var config = new GenerateVideosConfig
+        {
+            DurationSeconds = request.Options.DurationSeconds,
+            AspectRatio = request.Options.AspectRatio,
+            NumberOfVideos = request.Options.Count,
+        };
+
+        if (request.References.Count > 0)
+        {
+            // O Veo exige 8 s quando ha imagens de referencia. Pedir 4 s COM referencia e
+            // requisicao invalida, e descobrir isso em producao custa uma rodada de suporte.
+            config.ReferenceImages =
+            [
+                .. request.References.Select(r => new VideoGenerationReferenceImage
+                {
+                    Image = new Image { ImageBytes = r.Bytes.ToArray(), MimeType = r.MediaType },
+                }),
+            ];
+        }
+
+        var operation = await client.Models
+            .GenerateVideosAsync(
+                binding.Model,
+                new GenerateVideosSource { Prompt = request.Prompt },
+                config,
+                cancellationToken)
+            .ConfigureAwait(false);
+
+        for (var poll = 0; operation.Done != true && poll < MaxPolls; poll++)
+        {
+            await _delay(PollInterval, cancellationToken).ConfigureAwait(false);
+            operation = await client.Operations
+                .GetAsync(operation, new GetOperationConfig(), cancellationToken)
+                .ConfigureAwait(false);
+        }
+
+        if (operation.Done != true)
+        {
+            return MediaResult<MediaArtifact>.Fail(
+                MediaErrorCode.ProviderFailure,
+                $"alias '{binding.Alias}': a operacao '{operation.Name}' nao concluiu em {MaxPolls} voltas. " +
+                "O id ficou gravado no job: retomar o polling nao paga de novo.");
+        }
+
+        if (operation.Error is { Count: > 0 })
+        {
+            return MediaResult<MediaArtifact>.Fail(
+                MediaErrorCode.ProviderFailure,
+                $"alias '{binding.Alias}': a operacao terminou com erro: " +
+                string.Join("; ", operation.Error.Select(e => $"{e.Key}={e.Value}")));
+        }
+
+        var response = operation.Response;
+
+        if (response?.RaiMediaFilteredCount is > 0)
+        {
+            // Bloqueio de moderacao. No Veo ele NAO cobra — e nao vira retry, porque
+            // retentar recebe o mesmo "nao".
+            return MediaResult<MediaArtifact>.Fail(
+                MediaErrorCode.PolicyBlocked,
+                $"alias '{binding.Alias}': {response.RaiMediaFilteredCount} saida(s) bloqueada(s) por politica: " +
+                string.Join("; ", response.RaiMediaFilteredReasons ?? []));
+        }
+
+        var video = response?.GeneratedVideos?.Select(g => g.Video).FirstOrDefault(v => v is not null);
+
+        if (video?.VideoBytes is not { Length: > 0 } bytes)
+        {
+            return MediaResult<MediaArtifact>.Fail(
+                MediaErrorCode.ProviderFailure,
+                $"alias '{binding.Alias}': a operacao concluiu sem bytes de video" +
+                (video?.Uri is { Length: > 0 } uri
+                    ? $" (so a URI '{uri}', que o Veo apaga em 2 dias). Baixe os bytes antes de marcar Generated."
+                    : "."));
+        }
+
+        return MediaResult<MediaArtifact>.Ok(new MediaArtifact(
+            MediaKind.Video,
+            video.MimeType ?? "video/mp4",
+            bytes,
+            RevisedPrompt: null,
+            ResponseId: operation.Name,
+            C2paPreserved: true));
+    }
+}

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

@@ -0,0 +1,29 @@
+namespace Morph.AiKit.Middleware;
+
+/// <summary>
+/// Para onde vai o custo de cada volta ao modelo. <b>A costura de saida do
+/// <see cref="UsageCostMiddleware"/></b>: o kit calcula, o projeto decide onde guardar
+/// (tabela, metrica, log estruturado, fila).
+/// </summary>
+/// <remarks>
+/// <para>
+/// <b>Por que uma interface de um metodo so e nao um evento nem um logger:</b> custo e
+/// dado de negocio, nao diagnostico. Um projeto multi-tenant precisa somar por conta e por
+/// mes; um <c>ILogger</c> nao devolve soma. A interface e minima de proposito — quem quiser
+/// um logger implementa um sink de duas linhas.
+/// </para>
+/// <para>
+/// <b>Contrato de execucao:</b> <see cref="Record"/> e chamado no caminho da resposta,
+/// <b>sincronamente</b>, uma vez por volta ao modelo. Uma implementacao que faca I/O
+/// bloqueante aqui paga esse custo na latencia de cada resposta — enfileire e persista fora
+/// do caminho quente. E ela pode ser chamada de varias threads ao mesmo tempo (um mesmo
+/// pipeline atende varias conversas): a implementacao e responsavel pela propria seguranca
+/// sob concorrencia.
+/// </para>
+/// </remarks>
+public interface IUsageCostSink
+{
+    /// <summary>Publica o custo de uma volta ao modelo.</summary>
+    /// <param name="record">O registro ja calculado. Nunca nulo.</param>
+    void Record(UsageCostRecord record);
+}