@polymorphism-tech/morph-spec 7.0.0 → 7.1.0

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

@@ -0,0 +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)*

package/framework/standards/ai-agents/modalities-speech-to-text.md

@@ -0,0 +1,171 @@
+# Modalities — Speech to Text (Audio to Text)
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 2 (on-keyword)
+> **Keywords:** speech to text, transcription, whisper, audio to text, voice transcription
+> **Read by Claude in:** implement (quando o projeto precisa transcrever áudio para texto)
+
+**Verified against:** MAF 1.0 GA + OpenAI .NET SDK 2.x. Last-verified: 2026-05-19.
+
+---
+
+## Quando usar STT
+
+Use quando o input real do usuário é áudio e você precisa de texto para processamento downstream:
+
+- **Transcrição de reuniões:** gravar áudio da reunião → transcrever → alimentar um Status Agent que extrai ações, decisões e responsáveis
+- **Notas de voz:** usuário fala → transcreve → salva como nota textual ou input para outro agente
+- **Suporte por voz:** áudio do cliente → transcreve → agente de roteamento classifica e responde
+
+**Fluxo típico:** `áudio (bytes/arquivo)` → `TranscriptionService` → `texto` → `AIAgent` downstream
+
+Transcrição é uma **chamada de serviço**, não um agente conversacional. Use `AudioClient` diretamente via DI — não crie `AIAgent` para isso.
+
+**Não se aplica** quando o input já é texto. Se o áudio foi transcrito por outra ferramenta, use o texto diretamente.
+
+---
+
+## A API
+
+No OpenAI SDK (.NET 2.x), o caminho é `AudioClient.TranscribeAudio`:
+
+```csharp
+using OpenAI.Audio;
+
+AudioClient client = new("whisper-1", apiKey);
+AudioTranscription transcription = await client.TranscribeAudioAsync(audioFilePath);
+string text = transcription.Text;
+```
+
+O projeto injeta `AudioClient` via DI. Para transcrição com timestamps (ex: sincronização de legenda), use `AudioTranscriptionOptions` com `ResponseFormat = AudioTranscriptionFormat.Verbose`.
+
+---
+
+## Exemplo C# completo
+
+```csharp
+using OpenAI.Audio;
+using Microsoft.Extensions.Configuration;
+
+public sealed class TranscriptionService
+{
+    private readonly AudioClient _client;
+
+    public TranscriptionService(IConfiguration config)
+    {
+        var model = config["Transcription:Model"] ?? "whisper-1";
+        var apiKey = config["OpenAI:ApiKey"]!;
+        _client = new AudioClient(model, apiKey);
+    }
+
+    /// <summary>
+    /// Transcreve áudio a partir de um arquivo e retorna texto simples.
+    /// O transcript retornado pode ser passado diretamente como input para um AIAgent downstream.
+    /// </summary>
+    public async Task<string> TranscribeAsync(string audioFilePath, CancellationToken ct = default)
+    {
+        AudioTranscription transcription = await _client.TranscribeAudioAsync(audioFilePath, cancellationToken: ct);
+        return transcription.Text;
+    }
+
+    /// <summary>
+    /// Transcreve áudio a partir de bytes (ex: upload do usuário) e retorna texto simples.
+    /// </summary>
+    public async Task<string> TranscribeBytesAsync(
+        Stream audioStream,
+        string fileName,
+        string mediaType = "audio/mpeg",
+        CancellationToken ct = default)
+    {
+        var options = new AudioTranscriptionOptions
+        {
+            ResponseFormat = AudioTranscriptionFormat.Simple
+        };
+
+        AudioTranscription transcription = await _client.TranscribeAudioAsync(
+            audioStream, fileName, options, cancellationToken: ct);
+        return transcription.Text;
+    }
+
+    /// <summary>
+    /// Transcreve com timestamps por palavra e segmento (útil para legendas ou busca por trecho).
+    /// </summary>
+    public async Task<AudioTranscription> TranscribeVerboseAsync(string audioFilePath, CancellationToken ct = default)
+    {
+        var options = new AudioTranscriptionOptions
+        {
+            ResponseFormat         = AudioTranscriptionFormat.Verbose,
+            TimestampGranularities = { AudioTimestampGranularity.Word, AudioTimestampGranularity.Segment }
+        };
+
+        return await _client.TranscribeAudioAsync(audioFilePath, options, cancellationToken: ct);
+    }
+}
+```
+
+**Alimentando um agente downstream com o transcript:**
+
+```csharp
+// O transcript é texto puro — basta passar como input para qualquer AIAgent
+string transcript = await _transcription.TranscribeAsync("meeting-2024-05-19.mp3");
+
+// Ex: Status Agent que extrai ações da reunião
+AgentResponse<MeetingActions> actions = await _statusAgent.RunAsync<MeetingActions>(
+    $"Extraia ações, decisões e responsáveis desta transcrição:\n\n{transcript}");
+```
+
+**Registro DI:**
+
+```csharp
+// Program.cs
+builder.Services.AddSingleton<TranscriptionService>();
+```
+
+---
+
+## Formatos e limites
+
+> Valores verificados contra OpenAI Whisper API (2026-05-19). Confirme limites atuais na documentação do provider ao fazer deploy.
+
+| Aspecto | Detalhe |
+|---------|---------|
+| Formatos suportados | `mp3`, `mp4`, `mpeg`, `mpga`, `m4a`, `wav`, `webm` |
+| Limite por request | **25 MB** por arquivo (OpenAI Whisper) |
+| Duração aproximada | ~1h de áudio ≈ 25MB em MP3 128kbps |
+| Áudio longo | Pré-processe client-side: divida em chunks antes de enviar (ffmpeg, NAudio, etc.) — não há API de chunking automático no SDK |
+| Idiomas | Whisper suporta 99 idiomas; especifique `Language = "pt"` em `AudioTranscriptionOptions` para melhor acurácia em português |
+
+**Chunking de áudio longo:** para arquivos acima de 25MB, divida o arquivo em segmentos de ~20MB antes de enviar. Concatene os textos retornados. Não há sobreposição automática — adicione alguns segundos de overlap entre chunks se a precisão nos cortes for crítica.
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Por quê é errado | Jeito certo |
+|--------------|-----------------|-------------|
+| Transcrever quando o input já é texto | Custo e latência desnecessários | Use o texto diretamente como input do agente downstream |
+| Enviar áudio longo (>25MB) sem chunking | O provider rejeita a request com erro 413 | Divida client-side em chunks ≤20MB antes de enviar |
+| Criar `AIAgent` para transcrição | `AudioClient` não é `IChatClient`; o pipeline é simples (bytes → texto) | Injete `TranscriptionService` via DI — é um serviço, não um agente |
+| Ignorar o idioma do áudio | Whisper infere o idioma, mas pode errar em áudios com muita sigla ou sotaque | Especifique `Language` em `AudioTranscriptionOptions` quando o idioma for conhecido |
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] `AudioClient` injetado via DI — não instanciado inline
+- [ ] Áudio longo (>25MB) tratado com chunking antes de enviar ao provider
+- [ ] Transcript retornado como `string` e passado como input ao agente downstream — sem re-formatação manual
+- [ ] `Language` especificado em `AudioTranscriptionOptions` quando o idioma do áudio é conhecido
+- [ ] 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 `AudioClient` por provider
+- OpenAI .NET SDK — `AudioClient`: https://github.com/openai/openai-dotnet
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/modalities-speech-to-text.md v1.0 (2026-05-19)*

package/framework/standards/ai-agents/modalities-text-to-speech.md

@@ -0,0 +1,181 @@
+# Modalities — Text to Speech (Text to Audio)
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 2 (on-keyword)
+> **Keywords:** text to speech, TTS, voice synthesis, audio generation, speech synthesis
+> **Read by Claude in:** implement (quando o projeto precisa gerar áudio a partir de texto)
+
+**Verified against:** MAF 1.0 GA + OpenAI .NET SDK 2.x. Last-verified: 2026-05-19.
+
+---
+
+## Quando usar TTS
+
+TTS converte texto em áudio narrado. É um caso de uso **raro** — só adicione quando há demanda real e comprovada:
+
+- **Acessibilidade:** leitura em voz alta para usuários com deficiência visual ou dificuldade de leitura
+- **Notificações em áudio:** resumos falados de alertas ou relatórios em contextos hands-free (painel industrial, carro)
+- **Resumos falados:** o usuário quer ouvir um digest em vez de ler (ex: podcast personalizado gerado on-demand)
+
+**Nota honesta:** TTS tem custo por caractere e latência perceptível. Se o caso de uso não é explicitamente solicitado pelo usuário final ou pelo cliente, não adicione — um botão "copiar texto" ou um leitor de tela nativo do SO resolve a maioria dos casos de acessibilidade sem custo de API.
+
+TTS é uma **chamada de serviço**, não um agente conversacional. Use `AudioClient` diretamente via DI — não crie `AIAgent` para isso.
+
+---
+
+## A API
+
+No OpenAI SDK (.NET 2.x), o caminho é `AudioClient.GenerateSpeech`:
+
+```csharp
+using OpenAI.Audio;
+
+AudioClient client = new("tts-1", apiKey);
+BinaryData speech = await client.GenerateSpeechAsync(text, GeneratedSpeechVoice.Alloy);
+```
+
+Retorna `BinaryData` (bytes de áudio) que você persiste ou serve via stream. Para controlar formato e velocidade, use `SpeechGenerationOptions`.
+
+---
+
+## Exemplo C# completo
+
+```csharp
+using OpenAI.Audio;
+using Microsoft.Extensions.Configuration;
+
+public sealed class TextToSpeechService
+{
+    private readonly AudioClient _client;
+
+    public TextToSpeechService(IConfiguration config)
+    {
+        // tts-1: mais rápido, menor qualidade. tts-1-hd: mais lento, maior qualidade.
+        var model = config["TTS:Model"] ?? "tts-1";
+        var apiKey = config["OpenAI:ApiKey"]!;
+        _client = new AudioClient(model, apiKey);
+    }
+
+    /// <summary>
+    /// Converte texto em áudio e retorna bytes MP3.
+    /// Cachear o resultado é altamente recomendado para textos repetitivos — gerar o mesmo texto
+    /// duas vezes é desperdício de custo e latência.
+    /// </summary>
+    public async Task<BinaryData> SynthesizeAsync(
+        string text,
+        GeneratedSpeechVoice? voice = null,
+        GeneratedSpeechFormat? format = null,
+        float speedRatio = 1.0f,
+        CancellationToken ct = default)
+    {
+        var resolvedVoice  = voice  ?? GeneratedSpeechVoice.Alloy;
+        var resolvedFormat = format ?? GeneratedSpeechFormat.Mp3;
+
+        var options = new SpeechGenerationOptions
+        {
+            ResponseFormat = resolvedFormat,
+            SpeedRatio     = speedRatio
+        };
+
+        BinaryData speech = await _client.GenerateSpeechAsync(text, resolvedVoice, options, ct);
+        return speech;
+    }
+}
+```
+
+**Registro DI:**
+
+```csharp
+// Program.cs
+builder.Services.AddSingleton<TextToSpeechService>();
+```
+
+**Servindo como download ou stream:**
+
+```csharp
+public class AudioController(TextToSpeechService tts) : ControllerBase
+{
+    [HttpPost("synthesize")]
+    public async Task<IActionResult> Synthesize([FromBody] SynthesizeRequest req)
+    {
+        // Verificar cache antes de gerar (ver Anti-patterns)
+        BinaryData audio = await tts.SynthesizeAsync(
+            text:       req.Text,
+            voice:      GeneratedSpeechVoice.Nova,
+            format:     GeneratedSpeechFormat.Mp3,
+            speedRatio: 1.1f);
+
+        // the storage layer may assign the final name; use a timestamp-based name here
+        var fileName = $"tts-{DateTime.UtcNow:yyyyMMddHHmmss}.mp3";
+        return File(audio.ToStream(), "audio/mpeg", fileName);
+    }
+}
+```
+
+---
+
+## Parâmetros
+
+> Valores verificados contra OpenAI TTS API + OpenAI .NET SDK 2.x (2026-05-19).
+
+**Vozes disponíveis (`GeneratedSpeechVoice`):**
+
+| Voz | Característica |
+|-----|---------------|
+| `Alloy` | Neutra, versátil — boa escolha padrão |
+| `Echo` | Masculina, suave |
+| `Fable` | Britânica, expressiva |
+| `Onyx` | Masculina, grave |
+| `Nova` | Feminina, amigável |
+| `Shimmer` | Feminina, suave |
+
+**Formatos de saída (`GeneratedSpeechFormat`):**
+
+| Formato | Caso de uso |
+|---------|-------------|
+| `Mp3` | Default — compatibilidade universal |
+| `Opus` | Streaming de baixa latência |
+| `Aac` | Dispositivos Apple / YouTube |
+| `Flac` | Arquivo sem perda |
+| `Wav` | Processamento de áudio downstream |
+| `Pcm` | Raw bytes sem container |
+
+**`SpeedRatio`:** `0.25` (muito lento) a `4.0` (muito rápido). Padrão `1.0`.
+
+**Modelos:**
+- `tts-1` — rápido, custo menor, qualidade suficiente para a maioria dos casos
+- `tts-1-hd` — maior qualidade, mais lento e mais caro — use apenas quando a clareza de voz é crítica
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Por quê é errado | Jeito certo |
+|--------------|-----------------|-------------|
+| Adicionar TTS sem caso de uso real | Custo por caractere + latência sem benefício ao usuário | Só adicione com demanda explícita; leitores de tela nativos cobrem acessibilidade básica |
+| Gerar o mesmo texto repetidamente sem cache | Textos fixos (intro, disclaimers, respostas FAQ) custam o mesmo toda vez | Cachear bytes de áudio para textos invariantes — CDN ou Redis com key baseada em hash do texto + voz + formato |
+| Criar `AIAgent` para TTS | `AudioClient.GenerateSpeech` não é conversacional; não há raciocínio LLM envolvido | Injete `TextToSpeechService` via DI — é um serviço de síntese, não um agente |
+| Gerar texto longo de uma vez sem segmentar | Providers têm limite de caracteres por request (OpenAI: ~4096 tokens / ~4000 chars); textos muito longos falham | Divida em parágrafos, gere áudio por segmento, concatene os bytes |
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] `AudioClient` injetado via DI — não instanciado inline
+- [ ] Cache implementado para textos invariantes (não gera o mesmo áudio duas vezes)
+- [ ] Textos longos segmentados antes de enviar ao provider
+- [ ] `GeneratedSpeechVoice` e `GeneratedSpeechFormat` escolhidos adequados ao contexto (não só defaults)
+- [ ] Model e API key vêm de config, não hardcoded
+- [ ] Não usa `AIAgent`/`AsAIAgent` para TTS — é um `TextToSpeechService`
+
+---
+
+## References
+
+- `ai-agents-setup` — packages, DI, e providers disponíveis
+- `ai-agents-providers-model-registry` — padrão de alias; adapte para resolver `AudioClient` por provider
+- OpenAI .NET SDK — `AudioClient`: https://github.com/openai/openai-dotnet
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/modalities-text-to-speech.md v1.0 (2026-05-19)*