@polymorphism-tech/morph-spec 7.8.1 → 7.9.0

package/framework/standards/ai-agents/modalities-vision.md

@@ -1,201 +1,201 @@
-# Modalities — Vision (Image to Text)
-
-> **Scope:** stacks=["dotnet"]
-> **Layer:** 2 (on-keyword)
-> **Keywords:** vision, image to text, OCR, image analysis, multimodal input, image agent, PDF analysis
-> **Read by Claude in:** implement (quando o agente recebe imagem ou PDF)
-
-**Verified against:** MAF 1.0 GA. Last-verified: 2026-05-19.
-
----
-
-## Quando usar vision
-
-Use vision quando o input real é uma imagem ou documento visual e o modelo precisa interpretar o conteúdo visual:
-
-- **OCR não-estruturado:** formulários digitalizados, notas escritas à mão, recibos
-- **Análise de imagem:** descrever screenshots, detectar objetos, moderar conteúdo visual
-- **Extração de dados de documentos:** invoices, laudos, contratos em PDF/imagem — combine com `RunAsync<T>` para saída tipada (ver §Exemplo)
-- **Multimodal Q&A:** usuário envia foto + pergunta
-
-**Não se aplica** quando o input já é texto extraído. Se você já tem o texto do documento (via OCR determinístico, parser de PDF, etc.), envie o texto diretamente para um agente de chat — vision é desnecessário e mais caro.
-
-**Escolha do modelo:** nem todo provider suporta visão. Use o alias `"vision"` no Model Registry — o projeto configura ali o modelo capaz (ex: `gpt-4o`, `gemini-2.5-flash`). Veja `ai-agents-providers-model-registry`.
-
----
-
-## A API
-
-Vision em MAF usa `ChatMessage` multimodal — a mesma abstração `IChatClient`/`AIAgent`, mas com conteúdo misto no payload da mensagem.
-
-```csharp
-using Microsoft.Extensions.AI;
-
-// Constrói um ChatMessage com texto + imagem
-ChatMessage message = new(ChatRole.User, [
-    new TextContent("O que aparece nesta imagem?"),
-    new UriContent(new Uri("https://example.com/foto.jpg"), "image/jpeg")
-]);
-
-AgentResponse response = await agent.RunAsync(message);
-```
-
-O `IChatClient` (e portanto `AIAgent`) aceita `IEnumerable<ChatMessage>` — você passa a lista diretamente para `RunAsync`.
-
-**Referência de tipos (namespace `Microsoft.Extensions.AI`):**
-
-| Tipo | Uso |
-|------|-----|
-| `TextContent` | Parte textual da mensagem |
-| `UriContent(uri, mediaType)` | Imagem referenciada por URL pública |
-| `DataContent.LoadFromAsync(path)` | Carrega imagem de arquivo/stream (helper canônico) |
-| `new DataContent(binaryData, mediaType)` | Imagem embutida a partir de bytes já em memória |
-
----
-
-## Exemplo C# completo
-
-Agente de visão que recebe URL de imagem e retorna descrição. Para extração de dados tipados de um documento, combine com `RunAsync<T>` (ver comentário inline).
-
-```csharp
-using Microsoft.Agents.AI;
-using Microsoft.Extensions.AI;
-
-public sealed class VisionAgent
-{
-    private readonly AIAgent _agent;
-
-    public VisionAgent(ModelRegistry modelRegistry)
-    {
-        _agent = modelRegistry.GetChatClient("vision").AsAIAgent(new ChatClientAgentOptions
-        {
-            Name = "VisionAgent",
-            ChatOptions = new()
-            {
-                Instructions = """
-                    You are an image analysis expert.
-                    Describe the image content clearly and extract any visible text or structured data.
-                    """
-            }
-        });
-    }
-
-    /// <summary>Analisa uma imagem por URL pública e retorna descrição em texto.</summary>
-    public async Task<string> AnalyzeImageUrlAsync(Uri imageUri, string question, CancellationToken ct = default)
-    {
-        ChatMessage message = new(ChatRole.User, [
-            new TextContent(question),
-            new UriContent(imageUri, "image/jpeg")
-        ]);
-
-        AgentResponse response = await _agent.RunAsync(message, cancellationToken: ct);
-        return response.Text;
-    }
-
-    /// <summary>
-    /// Analisa imagem a partir de um arquivo local ou caminho de upload.
-    /// Usa DataContent.LoadFromAsync — padrão canônico MAF para carregar imagem de arquivo.
-    /// Para extrair dados tipados, use RunAsync&lt;T&gt; em vez de RunAsync:
-    ///   AgentResponse&lt;InvoiceData&gt; r = await _agent.RunAsync&lt;InvoiceData&gt;(message);
-    ///   return r.Result;
-    /// Veja ai-agents-structured-output para o padrão completo.
-    /// </summary>
-    public async Task<string> AnalyzeImageFileAsync(string filePath, string question, CancellationToken ct = default)
-    {
-        DataContent imageContent = await DataContent.LoadFromAsync(filePath);
-        ChatMessage message = new(ChatRole.User, [
-            new TextContent(question),
-            imageContent
-        ]);
-
-        AgentResponse response = await _agent.RunAsync(message, cancellationToken: ct);
-        return response.Text;
-    }
-
-    /// <summary>
-    /// Analisa imagem a partir de bytes já em memória (ex: upload de usuário já lido).
-    /// Use AnalyzeImageFileAsync quando tiver o caminho do arquivo — é o padrão preferido.
-    /// </summary>
-    public async Task<string> AnalyzeImageBytesAsync(BinaryData imageData, string mediaType, string question, CancellationToken ct = default)
-    {
-        ChatMessage message = new(ChatRole.User, [
-            new TextContent(question),
-            new DataContent(imageData, mediaType)
-        ]);
-
-        AgentResponse response = await _agent.RunAsync(message, cancellationToken: ct);
-        return response.Text;
-    }
-}
-```
-
-**Consumo:**
-
-```csharp
-var agent = new VisionAgent(modelRegistry);
-
-// Por URL pública
-string desc = await agent.AnalyzeImageUrlAsync(
-    new Uri("https://cdn.example.com/invoice-2024.jpg"),
-    "Extraia os campos: número da nota, valor total e data de emissão.");
-
-// Por arquivo local — padrão canônico com DataContent.LoadFromAsync
-string desc2 = await agent.AnalyzeImageFileAsync(
-    "nota-fiscal.png",
-    "Liste todos os itens e valores desta nota fiscal.");
-
-// Por bytes em memória (ex: upload já lido de IFormFile)
-BinaryData data = await BinaryData.FromStreamAsync(formFile.OpenReadStream());
-string desc3 = await agent.AnalyzeImageBytesAsync(data, "image/png",
-    "Descreva o conteúdo da imagem enviada.");
-```
-
----
-
-## DataContent vs UriContent
-
-| Critério | `UriContent` | `DataContent` |
-|----------|-------------|---------------|
-| Imagem publicamente acessível | Sim — envie a URL | — |
-| Imagem privada / upload de usuário | — | Sim — bytes inline (base64 internamente) |
-| Payload de rede | Pequeno (só a URI) | Grande (bytes encodados) |
-| Disponibilidade | O modelo faz HTTP GET na URI; precisa estar acessível | Autossuficiente, sem dependência externa |
-| Formatos suportados | `image/jpeg`, `image/png`, `image/webp`, `image/gif` (por provider) | Idem |
-
-**Trade-off prático:** para imagens geradas internamente ou uploads de usuário, prefira `DataContent` — a URL temporária pode expirar antes do modelo fazer o GET. Para imagens em CDN estável, `UriContent` economiza largura de banda.
-
-**PDF:** o MAF Sample confirma que o OpenAI Chat Client suporta PDF via URI/Data content. Verifique se o provider configurado suporta `application/pdf` antes de usar.
-
----
-
-## Anti-patterns
-
-| Anti-pattern | Por quê é errado | Jeito certo |
-|--------------|-----------------|-------------|
-| Enviar imagem para modelo sem suporte a vision | A call falha em runtime com erro de provider | Use alias `"vision"` no Model Registry — aponte para modelo com suporte confirmado |
-| Enviar imagem em resolução original sem resize | Tokens de imagem são cobrados por resolução; imagens 4K em contextos que não precisam de detalhe desperdiçam custo e context window | Redimensione para resolução adequada à tarefa (ex: 800px para OCR de texto) |
-| Usar vision quando OCR determinístico bastaria | Vision é probabilístico e mais caro; para extração de texto de PDF com layout fixo, um parser PDF é mais confiável e barato | Só use vision quando o layout é variável ou a imagem é não-estruturada |
-| Retornar `response.Text` e parsear regex para dados estruturados | Não-determinístico; quebra com mudança de modelo | Combine com `RunAsync<T>` e um `sealed record` — veja `ai-agents-structured-output` |
-
----
-
-## Checklist (verifiable by morph-eval)
-
-- [ ] Alias `"vision"` existe em `model-registry.json` e aponta para modelo com suporte a visão confirmado
-- [ ] `ChatMessage` usa `UriContent` para imagens por URL ou `DataContent` para bytes — nenhum encoding manual de base64 no código do agente
-- [ ] Para extração de dados tipados, usa `RunAsync<T>` com `sealed record` (não parseia `response.Text`)
-- [ ] Imagens privadas / uploads de usuário usam `DataContent`, não `UriContent` com URL temporária
-- [ ] Validação de regras de negócio existe após `RunAsync<T>` quando aplicável
-
----
-
-## References
-
-- `ai-agents-setup` — packages, DI, e setup mínimo de agente
-- `ai-agents-providers-model-registry` — como registrar e resolver modelos por alias
-- `ai-agents-structured-output` — `RunAsync<T>` para extração tipada de dados de documentos
-- Microsoft Agent Framework multimodal sample: https://github.com/microsoft/agent-framework/blob/main/dotnet/samples/02-agents/Agents/Agent_Step10_UsingImages/README.md
-
----
-
-*MORPH-SPEC by Polymorphism Tech — ai-agents/modalities-vision.md v1.0 (2026-05-19)*
+# Modalities — Vision (Image to Text)
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 2 (on-keyword)
+> **Keywords:** vision, image to text, OCR, image analysis, multimodal input, image agent, PDF analysis
+> **Read by Claude in:** implement (quando o agente recebe imagem ou PDF)
+
+**Verified against:** MAF 1.0 GA. Last-verified: 2026-05-19.
+
+---
+
+## Quando usar vision
+
+Use vision quando o input real é uma imagem ou documento visual e o modelo precisa interpretar o conteúdo visual:
+
+- **OCR não-estruturado:** formulários digitalizados, notas escritas à mão, recibos
+- **Análise de imagem:** descrever screenshots, detectar objetos, moderar conteúdo visual
+- **Extração de dados de documentos:** invoices, laudos, contratos em PDF/imagem — combine com `RunAsync<T>` para saída tipada (ver §Exemplo)
+- **Multimodal Q&A:** usuário envia foto + pergunta
+
+**Não se aplica** quando o input já é texto extraído. Se você já tem o texto do documento (via OCR determinístico, parser de PDF, etc.), envie o texto diretamente para um agente de chat — vision é desnecessário e mais caro.
+
+**Escolha do modelo:** nem todo provider suporta visão. Use o alias `"vision"` no Model Registry — o projeto configura ali o modelo capaz (ex: `gpt-4o`, `gemini-2.5-flash`). Veja `ai-agents-providers-model-registry`.
+
+---
+
+## A API
+
+Vision em MAF usa `ChatMessage` multimodal — a mesma abstração `IChatClient`/`AIAgent`, mas com conteúdo misto no payload da mensagem.
+
+```csharp
+using Microsoft.Extensions.AI;
+
+// Constrói um ChatMessage com texto + imagem
+ChatMessage message = new(ChatRole.User, [
+    new TextContent("O que aparece nesta imagem?"),
+    new UriContent(new Uri("https://example.com/foto.jpg"), "image/jpeg")
+]);
+
+AgentResponse response = await agent.RunAsync(message);
+```
+
+O `IChatClient` (e portanto `AIAgent`) aceita `IEnumerable<ChatMessage>` — você passa a lista diretamente para `RunAsync`.
+
+**Referência de tipos (namespace `Microsoft.Extensions.AI`):**
+
+| Tipo | Uso |
+|------|-----|
+| `TextContent` | Parte textual da mensagem |
+| `UriContent(uri, mediaType)` | Imagem referenciada por URL pública |
+| `DataContent.LoadFromAsync(path)` | Carrega imagem de arquivo/stream (helper canônico) |
+| `new DataContent(binaryData, mediaType)` | Imagem embutida a partir de bytes já em memória |
+
+---
+
+## Exemplo C# completo
+
+Agente de visão que recebe URL de imagem e retorna descrição. Para extração de dados tipados de um documento, combine com `RunAsync<T>` (ver comentário inline).
+
+```csharp
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+public sealed class VisionAgent
+{
+    private readonly AIAgent _agent;
+
+    public VisionAgent(ModelRegistry modelRegistry)
+    {
+        _agent = modelRegistry.GetChatClient("vision").AsAIAgent(new ChatClientAgentOptions
+        {
+            Name = "VisionAgent",
+            ChatOptions = new()
+            {
+                Instructions = """
+                    You are an image analysis expert.
+                    Describe the image content clearly and extract any visible text or structured data.
+                    """
+            }
+        });
+    }
+
+    /// <summary>Analisa uma imagem por URL pública e retorna descrição em texto.</summary>
+    public async Task<string> AnalyzeImageUrlAsync(Uri imageUri, string question, CancellationToken ct = default)
+    {
+        ChatMessage message = new(ChatRole.User, [
+            new TextContent(question),
+            new UriContent(imageUri, "image/jpeg")
+        ]);
+
+        AgentResponse response = await _agent.RunAsync(message, cancellationToken: ct);
+        return response.Text;
+    }
+
+    /// <summary>
+    /// Analisa imagem a partir de um arquivo local ou caminho de upload.
+    /// Usa DataContent.LoadFromAsync — padrão canônico MAF para carregar imagem de arquivo.
+    /// Para extrair dados tipados, use RunAsync&lt;T&gt; em vez de RunAsync:
+    ///   AgentResponse&lt;InvoiceData&gt; r = await _agent.RunAsync&lt;InvoiceData&gt;(message);
+    ///   return r.Result;
+    /// Veja ai-agents-structured-output para o padrão completo.
+    /// </summary>
+    public async Task<string> AnalyzeImageFileAsync(string filePath, string question, CancellationToken ct = default)
+    {
+        DataContent imageContent = await DataContent.LoadFromAsync(filePath);
+        ChatMessage message = new(ChatRole.User, [
+            new TextContent(question),
+            imageContent
+        ]);
+
+        AgentResponse response = await _agent.RunAsync(message, cancellationToken: ct);
+        return response.Text;
+    }
+
+    /// <summary>
+    /// Analisa imagem a partir de bytes já em memória (ex: upload de usuário já lido).
+    /// Use AnalyzeImageFileAsync quando tiver o caminho do arquivo — é o padrão preferido.
+    /// </summary>
+    public async Task<string> AnalyzeImageBytesAsync(BinaryData imageData, string mediaType, string question, CancellationToken ct = default)
+    {
+        ChatMessage message = new(ChatRole.User, [
+            new TextContent(question),
+            new DataContent(imageData, mediaType)
+        ]);
+
+        AgentResponse response = await _agent.RunAsync(message, cancellationToken: ct);
+        return response.Text;
+    }
+}
+```
+
+**Consumo:**
+
+```csharp
+var agent = new VisionAgent(modelRegistry);
+
+// Por URL pública
+string desc = await agent.AnalyzeImageUrlAsync(
+    new Uri("https://cdn.example.com/invoice-2024.jpg"),
+    "Extraia os campos: número da nota, valor total e data de emissão.");
+
+// Por arquivo local — padrão canônico com DataContent.LoadFromAsync
+string desc2 = await agent.AnalyzeImageFileAsync(
+    "nota-fiscal.png",
+    "Liste todos os itens e valores desta nota fiscal.");
+
+// Por bytes em memória (ex: upload já lido de IFormFile)
+BinaryData data = await BinaryData.FromStreamAsync(formFile.OpenReadStream());
+string desc3 = await agent.AnalyzeImageBytesAsync(data, "image/png",
+    "Descreva o conteúdo da imagem enviada.");
+```
+
+---
+
+## DataContent vs UriContent
+
+| Critério | `UriContent` | `DataContent` |
+|----------|-------------|---------------|
+| Imagem publicamente acessível | Sim — envie a URL | — |
+| Imagem privada / upload de usuário | — | Sim — bytes inline (base64 internamente) |
+| Payload de rede | Pequeno (só a URI) | Grande (bytes encodados) |
+| Disponibilidade | O modelo faz HTTP GET na URI; precisa estar acessível | Autossuficiente, sem dependência externa |
+| Formatos suportados | `image/jpeg`, `image/png`, `image/webp`, `image/gif` (por provider) | Idem |
+
+**Trade-off prático:** para imagens geradas internamente ou uploads de usuário, prefira `DataContent` — a URL temporária pode expirar antes do modelo fazer o GET. Para imagens em CDN estável, `UriContent` economiza largura de banda.
+
+**PDF:** o MAF Sample confirma que o OpenAI Chat Client suporta PDF via URI/Data content. Verifique se o provider configurado suporta `application/pdf` antes de usar.
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Por quê é errado | Jeito certo |
+|--------------|-----------------|-------------|
+| Enviar imagem para modelo sem suporte a vision | A call falha em runtime com erro de provider | Use alias `"vision"` no Model Registry — aponte para modelo com suporte confirmado |
+| Enviar imagem em resolução original sem resize | Tokens de imagem são cobrados por resolução; imagens 4K em contextos que não precisam de detalhe desperdiçam custo e context window | Redimensione para resolução adequada à tarefa (ex: 800px para OCR de texto) |
+| Usar vision quando OCR determinístico bastaria | Vision é probabilístico e mais caro; para extração de texto de PDF com layout fixo, um parser PDF é mais confiável e barato | Só use vision quando o layout é variável ou a imagem é não-estruturada |
+| Retornar `response.Text` e parsear regex para dados estruturados | Não-determinístico; quebra com mudança de modelo | Combine com `RunAsync<T>` e um `sealed record` — veja `ai-agents-structured-output` |
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] Alias `"vision"` existe em `model-registry.json` e aponta para modelo com suporte a visão confirmado
+- [ ] `ChatMessage` usa `UriContent` para imagens por URL ou `DataContent` para bytes — nenhum encoding manual de base64 no código do agente
+- [ ] Para extração de dados tipados, usa `RunAsync<T>` com `sealed record` (não parseia `response.Text`)
+- [ ] Imagens privadas / uploads de usuário usam `DataContent`, não `UriContent` com URL temporária
+- [ ] Validação de regras de negócio existe após `RunAsync<T>` quando aplicável
+
+---
+
+## References
+
+- `ai-agents-setup` — packages, DI, e setup mínimo de agente
+- `ai-agents-providers-model-registry` — como registrar e resolver modelos por alias
+- `ai-agents-structured-output` — `RunAsync<T>` para extração tipada de dados de documentos
+- Microsoft Agent Framework multimodal sample: https://github.com/microsoft/agent-framework/blob/main/dotnet/samples/02-agents/Agents/Agent_Step10_UsingImages/README.md
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/modalities-vision.md v1.0 (2026-05-19)*