@polymorphism-tech/morph-spec 8.1.0 → 8.1.2

package/framework/standards/ai-agents/modalities-image-gen.md

@@ -1,173 +1,173 @@
-# Modalities — Image Generation (Text to Image)
-
-> **Scope:** stacks=["dotnet"]
-> **Layer:** 2 (on-keyword)
-> **Keywords:** image generation, text to image, dall-e, gpt-image, mockup generation, image synthesis
-> **Read by Claude in:** implement (quando o projeto precisa gerar imagens a partir de texto)
-
-**Verified against:** MAF 1.0 GA + OpenAI .NET SDK 2.x. Last-verified: 2026-05-19.
-
----
-
-## Quando usar geração de imagem
-
-Use quando o produto precisa criar imagens em runtime a partir de um prompt textual:
-
-- **Mockups e protótipos visuais:** gerar capa de produto, banner de campanha, layout de tela
-- **Conteúdo para social media:** imagens para posts geradas a partir de briefing do usuário
-- **Visualizações:** diagramas, ilustrações ou thumbnails dinâmicos
-
-**Nota importante:** geração de imagem é uma **chamada de serviço ao provider**, não um agente conversacional. Não crie um `AIAgent` para isso — use `ImageClient` diretamente via DI.
-
-**Não use** quando um asset estático resolve o problema. Geração de imagem tem custo por chamada e latência de vários segundos. Se a imagem não muda por usuário/contexto, sirva de CDN.
-
----
-
-## A API
-
-O projeto resolve o `ImageClient` para o provider configurado. No OpenAI SDK (.NET 2.x), o caminho é:
-
-```csharp
-using OpenAI.Images;
-
-ImageClient client = new("dall-e-3", apiKey);
-GeneratedImage image = await client.GenerateImageAsync(prompt, options);
-```
-
-O projeto injeta `ImageClient` via DI (ver §Exemplo). A resolução pode ser feita via factory ou diretamente por configuração — não há um `GetImageClient("alias")` no `ModelRegistry` padrão; registre o `ImageClient` como serviço nomeado ou use uma factory simples que lê `model-registry.json`.
-
----
-
-## Exemplo C# completo
-
-```csharp
-using OpenAI.Images;
-using Microsoft.Extensions.Configuration;
-
-public sealed class ImageGenerationService
-{
-    private readonly ImageClient _client;
-
-    public ImageGenerationService(IConfiguration config)
-    {
-        // O projeto configura o modelo e a chave via config/model-registry.json ou appsettings
-        var model = config["ImageGen:Model"] ?? "dall-e-3";
-        var apiKey = config["OpenAI:ApiKey"]!;
-        _client = new ImageClient(model, apiKey);
-    }
-
-    /// <summary>
-    /// Gera uma imagem a partir de um prompt e retorna os bytes PNG.
-    /// Prefira armazenar os bytes; URLs retornadas pelo provider são efêmeras (expiram em ~1h).
-    /// </summary>
-    public async Task<BinaryData> GenerateImageBytesAsync(
-        string prompt,
-        GeneratedImageSize? size = null,
-        GeneratedImageQuality? quality = null,
-        CancellationToken ct = default)
-    {
-        var resolvedSize    = size    ?? GeneratedImageSize.W1024xH1024;
-        var resolvedQuality = quality ?? GeneratedImageQuality.Standard;
-
-        var options = new ImageGenerationOptions
-        {
-            Size           = resolvedSize,
-            Quality        = resolvedQuality,
-            ResponseFormat = GeneratedImageFormat.Bytes
-        };
-
-        GeneratedImage image = await _client.GenerateImageAsync(prompt, options, ct);
-        return image.ImageBytes;
-    }
-
-    /// <summary>
-    /// Gera uma imagem e retorna a URI. Use apenas quando precisar da URL diretamente
-    /// e souber que o downstream vai consumir a URL antes de ela expirar (~1h no OpenAI).
-    /// </summary>
-    public async Task<Uri> GenerateImageUriAsync(string prompt, CancellationToken ct = default)
-    {
-        var options = new ImageGenerationOptions
-        {
-            Size           = GeneratedImageSize.W1024xH1024,
-            Quality        = GeneratedImageQuality.Standard,
-            ResponseFormat = GeneratedImageFormat.Uri
-        };
-
-        GeneratedImage image = await _client.GenerateImageAsync(prompt, options, ct);
-        return image.ImageUri!;
-    }
-}
-```
-
-**Registro DI:**
-
-```csharp
-// Program.cs
-builder.Services.AddSingleton<ImageGenerationService>();
-```
-
-**Consumo:**
-
-```csharp
-public class CampaignController(ImageGenerationService imageGen, IBlobStorage storage) : ControllerBase
-{
-    [HttpPost("generate-banner")]
-    public async Task<IActionResult> GenerateBanner([FromBody] BannerRequest req)
-    {
-        BinaryData bytes = await imageGen.GenerateImageBytesAsync(
-            prompt: req.Briefing,
-            size: GeneratedImageSize.W1792xH1024,
-            quality: GeneratedImageQuality.High);
-
-        // Persista no storage do projeto antes de retornar
-        string storedUrl = await storage.UploadAsync(bytes, "image/png");
-        return Ok(new { url = storedUrl });
-    }
-}
-```
-
----
-
-## Parâmetros
-
-> Valores verificados contra OpenAI .NET SDK 2.x / DALL-E 3 (2026-05-19). Outros providers podem variar.
-
-| Parâmetro | Tipo | Opções | Nota |
-|-----------|------|--------|------|
-| `Size` | `GeneratedImageSize` | `W1024xH1024`, `W1792xH1024`, `W1024xH1792` | DALL-E 3 suporta os três; DALL-E 2 tem conjunto diferente |
-| `Quality` | `GeneratedImageQuality` | `Standard`, `High` | `High` = mais detalhe, mais custo e latência |
-| `Style` | `GeneratedImageStyle` | `Natural`, `Vivid` | `Vivid` = mais saturado/dramático; `Natural` = realista |
-| `ResponseFormat` | `GeneratedImageFormat` | `Bytes`, `Uri` | Prefira `Bytes` — URLs expiram em ~1h |
-
----
-
-## Anti-patterns
-
-| Anti-pattern | Por quê é errado | Jeito certo |
-|--------------|-----------------|-------------|
-| Gerar imagem quando asset estático resolve | Custo por chamada + latência sem ganho | Sirva de CDN; só gere quando o conteúdo é dinâmico por usuário/contexto |
-| Não moderar o prompt antes de enviar | Prompts maliciosos podem gerar conteúdo impróprio; o provider rejeitará e você terá erro 400 sem log útil | Aplique validação/moderação de prompt antes de chamar `GenerateImageAsync`; veja `ai-agents-middleware-patterns` |
-| Armazenar a URI retornada sem baixar | URLs do provider são efêmeras (~1h no OpenAI); links quebram depois | Use `ResponseFormat = Bytes`, persista no storage do projeto e sirva sua própria URL |
-| Criar `AIAgent` para geração de imagem | `ImageClient` não é `IChatClient`; não há sentido em wrappear como agente | Injete `ImageGenerationService` diretamente — é um serviço, não um agente |
-
----
-
-## Checklist (verifiable by morph-eval)
-
-- [ ] `ImageClient` injetado via DI — não instanciado inline nos controllers
-- [ ] `ResponseFormat = GeneratedImageFormat.Bytes` na maioria dos casos; URLs armazenadas no storage do projeto
-- [ ] Prompt passa por validação/moderação antes de ir ao provider
-- [ ] Não usa `AIAgent`/`AsAIAgent` para geração de imagem — é um `ImageGenerationService`
-- [ ] Model e API key vêm de config, não hardcoded
-
----
-
-## References
-
-- `ai-agents-setup` — packages, DI, e providers disponíveis
-- `ai-agents-providers-model-registry` — padrão de alias; adapte para resolver `ImageClient` por provider
-- OpenAI .NET SDK — `ImageClient`: https://github.com/openai/openai-dotnet
-
----
-
-*MORPH-SPEC by Polymorphism Tech — ai-agents/modalities-image-gen.md v1.0 (2026-05-19)*
+# Modalities — Image Generation (Text to Image)
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 2 (on-keyword)
+> **Keywords:** image generation, text to image, dall-e, gpt-image, mockup generation, image synthesis
+> **Read by Claude in:** implement (quando o projeto precisa gerar imagens a partir de texto)
+
+**Verified against:** MAF 1.0 GA + OpenAI .NET SDK 2.x. Last-verified: 2026-05-19.
+
+---
+
+## Quando usar geração de imagem
+
+Use quando o produto precisa criar imagens em runtime a partir de um prompt textual:
+
+- **Mockups e protótipos visuais:** gerar capa de produto, banner de campanha, layout de tela
+- **Conteúdo para social media:** imagens para posts geradas a partir de briefing do usuário
+- **Visualizações:** diagramas, ilustrações ou thumbnails dinâmicos
+
+**Nota importante:** geração de imagem é uma **chamada de serviço ao provider**, não um agente conversacional. Não crie um `AIAgent` para isso — use `ImageClient` diretamente via DI.
+
+**Não use** quando um asset estático resolve o problema. Geração de imagem tem custo por chamada e latência de vários segundos. Se a imagem não muda por usuário/contexto, sirva de CDN.
+
+---
+
+## A API
+
+O projeto resolve o `ImageClient` para o provider configurado. No OpenAI SDK (.NET 2.x), o caminho é:
+
+```csharp
+using OpenAI.Images;
+
+ImageClient client = new("dall-e-3", apiKey);
+GeneratedImage image = await client.GenerateImageAsync(prompt, options);
+```
+
+O projeto injeta `ImageClient` via DI (ver §Exemplo). A resolução pode ser feita via factory ou diretamente por configuração — não há um `GetImageClient("alias")` no `ModelRegistry` padrão; registre o `ImageClient` como serviço nomeado ou use uma factory simples que lê `model-registry.json`.
+
+---
+
+## Exemplo C# completo
+
+```csharp
+using OpenAI.Images;
+using Microsoft.Extensions.Configuration;
+
+public sealed class ImageGenerationService
+{
+    private readonly ImageClient _client;
+
+    public ImageGenerationService(IConfiguration config)
+    {
+        // O projeto configura o modelo e a chave via config/model-registry.json ou appsettings
+        var model = config["ImageGen:Model"] ?? "dall-e-3";
+        var apiKey = config["OpenAI:ApiKey"]!;
+        _client = new ImageClient(model, apiKey);
+    }
+
+    /// <summary>
+    /// Gera uma imagem a partir de um prompt e retorna os bytes PNG.
+    /// Prefira armazenar os bytes; URLs retornadas pelo provider são efêmeras (expiram em ~1h).
+    /// </summary>
+    public async Task<BinaryData> GenerateImageBytesAsync(
+        string prompt,
+        GeneratedImageSize? size = null,
+        GeneratedImageQuality? quality = null,
+        CancellationToken ct = default)
+    {
+        var resolvedSize    = size    ?? GeneratedImageSize.W1024xH1024;
+        var resolvedQuality = quality ?? GeneratedImageQuality.Standard;
+
+        var options = new ImageGenerationOptions
+        {
+            Size           = resolvedSize,
+            Quality        = resolvedQuality,
+            ResponseFormat = GeneratedImageFormat.Bytes
+        };
+
+        GeneratedImage image = await _client.GenerateImageAsync(prompt, options, ct);
+        return image.ImageBytes;
+    }
+
+    /// <summary>
+    /// Gera uma imagem e retorna a URI. Use apenas quando precisar da URL diretamente
+    /// e souber que o downstream vai consumir a URL antes de ela expirar (~1h no OpenAI).
+    /// </summary>
+    public async Task<Uri> GenerateImageUriAsync(string prompt, CancellationToken ct = default)
+    {
+        var options = new ImageGenerationOptions
+        {
+            Size           = GeneratedImageSize.W1024xH1024,
+            Quality        = GeneratedImageQuality.Standard,
+            ResponseFormat = GeneratedImageFormat.Uri
+        };
+
+        GeneratedImage image = await _client.GenerateImageAsync(prompt, options, ct);
+        return image.ImageUri!;
+    }
+}
+```
+
+**Registro DI:**
+
+```csharp
+// Program.cs
+builder.Services.AddSingleton<ImageGenerationService>();
+```
+
+**Consumo:**
+
+```csharp
+public class CampaignController(ImageGenerationService imageGen, IBlobStorage storage) : ControllerBase
+{
+    [HttpPost("generate-banner")]
+    public async Task<IActionResult> GenerateBanner([FromBody] BannerRequest req)
+    {
+        BinaryData bytes = await imageGen.GenerateImageBytesAsync(
+            prompt: req.Briefing,
+            size: GeneratedImageSize.W1792xH1024,
+            quality: GeneratedImageQuality.High);
+
+        // Persista no storage do projeto antes de retornar
+        string storedUrl = await storage.UploadAsync(bytes, "image/png");
+        return Ok(new { url = storedUrl });
+    }
+}
+```
+
+---
+
+## Parâmetros
+
+> Valores verificados contra OpenAI .NET SDK 2.x / DALL-E 3 (2026-05-19). Outros providers podem variar.
+
+| Parâmetro | Tipo | Opções | Nota |
+|-----------|------|--------|------|
+| `Size` | `GeneratedImageSize` | `W1024xH1024`, `W1792xH1024`, `W1024xH1792` | DALL-E 3 suporta os três; DALL-E 2 tem conjunto diferente |
+| `Quality` | `GeneratedImageQuality` | `Standard`, `High` | `High` = mais detalhe, mais custo e latência |
+| `Style` | `GeneratedImageStyle` | `Natural`, `Vivid` | `Vivid` = mais saturado/dramático; `Natural` = realista |
+| `ResponseFormat` | `GeneratedImageFormat` | `Bytes`, `Uri` | Prefira `Bytes` — URLs expiram em ~1h |
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Por quê é errado | Jeito certo |
+|--------------|-----------------|-------------|
+| Gerar imagem quando asset estático resolve | Custo por chamada + latência sem ganho | Sirva de CDN; só gere quando o conteúdo é dinâmico por usuário/contexto |
+| Não moderar o prompt antes de enviar | Prompts maliciosos podem gerar conteúdo impróprio; o provider rejeitará e você terá erro 400 sem log útil | Aplique validação/moderação de prompt antes de chamar `GenerateImageAsync`; veja `ai-agents-middleware-patterns` |
+| Armazenar a URI retornada sem baixar | URLs do provider são efêmeras (~1h no OpenAI); links quebram depois | Use `ResponseFormat = Bytes`, persista no storage do projeto e sirva sua própria URL |
+| Criar `AIAgent` para geração de imagem | `ImageClient` não é `IChatClient`; não há sentido em wrappear como agente | Injete `ImageGenerationService` diretamente — é um serviço, não um agente |
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] `ImageClient` injetado via DI — não instanciado inline nos controllers
+- [ ] `ResponseFormat = GeneratedImageFormat.Bytes` na maioria dos casos; URLs armazenadas no storage do projeto
+- [ ] Prompt passa por validação/moderação antes de ir ao provider
+- [ ] Não usa `AIAgent`/`AsAIAgent` para geração de imagem — é um `ImageGenerationService`
+- [ ] Model e API key vêm de config, não hardcoded
+
+---
+
+## References
+
+- `ai-agents-setup` — packages, DI, e providers disponíveis
+- `ai-agents-providers-model-registry` — padrão de alias; adapte para resolver `ImageClient` por provider
+- OpenAI .NET SDK — `ImageClient`: https://github.com/openai/openai-dotnet
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/modalities-image-gen.md v1.0 (2026-05-19)*