@polymorphism-tech/morph-spec 7.7.3 → 7.8.1

package/framework/standards/ai-agents/batching.md

@@ -1,193 +1,193 @@
-# Batching — Bulk prompt processing
-
-> **Scope:** stacks=["dotnet"]
-> **Layer:** 2 (on-keyword)
-> **Keywords:** batching, batch api, bulk prompts, batch processing, async batch
-> **Read by Claude in:** plan/implement
-
-**Verified against:** MAF 1.0 GA + OpenAI .NET SDK 2.* (fluxo da Batch API confirmado pela REST API; nomes de tipos/métodos .NET marcados `// VERIFY:` — ver seção A API). Last-verified: 2026-05-19.
-
----
-
-## Quando usar batch
-
-Use a Batch API quando você tem **N prompts independentes sem necessidade de resposta imediata**:
-
-- Relatório mensal que agrega análise de N documentos/itens
-- Reprocessamento de dados históricos com LLM (re-classificação, re-extração)
-- Geração em massa de sumários, traduções ou avaliações offline
-- Pipeline noturno de enriquecimento de dados
-
-**Vantagens:**
-- **Desconto de custo significativo** — OpenAI Batch API custa 50% menos que completions síncronas
-- **SLA relaxado** — resultados em até 24 h; adequado para trabalho assíncrono
-- **Rate limits separados** — não compete com a cota síncrona da aplicação
-
-> Regra prática: se o usuário não está esperando o resultado na tela, considere batch.
-
----
-
-## A API
-
-> **AVISO:** Batch API é **OpenAI-specific**. O `IChatClient` do MAF não expõe batch.
-> Obtenha o `OpenAIClient` direto via configuração (mesma chave/modelo que o Model Registry usa)
-> em vez de `_modelRegistry.GetChatClient(alias)`.
-
-O fluxo tem 4 etapas: **upload do arquivo JSONL → submissão do batch → poll de status → download dos resultados**.
-
-> ### ⚠️ Status de verificação da API .NET
->
-> O fluxo abaixo é o **padrão correto da OpenAI Batch API** (confirmado pela REST API e pelos
-> docs oficiais). O que **não** foi confirmável via context7 são os nomes exatos de tipos/métodos
-> do **OpenAI .NET SDK 2.\*** para batch — o context7 retornou apenas as APIs de Assistants/Files.
->
-> **Confirmado:** `openAIClient.GetOpenAIFileClient()` → `OpenAIFileClient`; upload de arquivo
-> via `UploadFileAsync(stream, filename, FileUploadPurpose.*)`.
->
-> **A confirmar contra o pacote `OpenAI` 2.\* instalado** (todos marcados `// VERIFY:` no código):
-> nome do método que retorna o batch client (`GetBatchClient()`), namespace do batch
-> (`OpenAI.Batch`), assinatura de `CreateBatchAsync`, nomes de `GetBatchAsync`/`DownloadFileAsync`,
-> tipo/valores do status, e o valor de `FileUploadPurpose` para batch.
-> **Antes de codar:** abra o pacote no IntelliSense ou no [openai-dotnet](https://github.com/openai/openai-dotnet) e confirme cada `// VERIFY:`.
-
----
-
-## Exemplo C# completo
-
-```csharp
-using OpenAI;
-using OpenAI.Batch;   // VERIFY namespace — confirme contra o pacote OpenAI 2.* instalado
-using OpenAI.Files;
-using System.ClientModel;
-using System.Text;
-using System.Text.Json;
-
-// ── 1. Construir o cliente OpenAI direto (mesma config que o Model Registry usa) ──
-var apiKey = configuration["OpenAI:ApiKey"]!;
-var openAIClient = new OpenAIClient(new ApiKeyCredential(apiKey));
-var fileClient = openAIClient.GetOpenAIFileClient();   // confirmado
-var batchClient = openAIClient.GetBatchClient();   // VERIFY método — pode ser GetOpenAIBatchClient()
-
-// ── 2. Montar o arquivo JSONL com N requests independentes ──
-var items = new[] { "Item A", "Item B", "Item C" }; // substitua pela sua coleção
-var jsonlBuilder = new StringBuilder();
-foreach (var item in items)
-{
-    var request = new
-    {
-        custom_id = $"req-{Guid.CreateVersion7()}",
-        method = "POST",
-        url = "/v1/chat/completions",
-        body = new
-        {
-            model = configuration["OpenAI:Model"] ?? "gpt-4o-mini",
-            messages = new[]
-            {
-                new { role = "user", content = $"Analyze this item and return a JSON summary: {item}" }
-            },
-            max_tokens = 256
-        }
-    };
-    jsonlBuilder.AppendLine(JsonSerializer.Serialize(request));
-}
-
-// ── 3. Upload do arquivo JSONL ──
-var jsonlBytes = Encoding.UTF8.GetBytes(jsonlBuilder.ToString());
-using var jsonlStream = new MemoryStream(jsonlBytes);
-// VERIFY valor do enum — FileUploadPurpose.Batch (confirme; o SDK 2.* expõe outros purposes)
-OpenAIFile batchFile = await fileClient.UploadFileAsync(
-    jsonlStream, "batch_requests.jsonl", FileUploadPurpose.Batch);
-
-// ── 4. Submeter o batch ──
-// VERIFY assinatura de CreateBatchAsync — provável (fileId, endpoint, completionWindow)
-var batch = await batchClient.CreateBatchAsync(
-    batchFile.Id,
-    endpoint: "/v1/chat/completions",
-    completionWindow: "24h");
-
-// ── 5. Poll de status (em background job / Hangfire / Worker) ──
-OpenAIBatch? completedBatch = null;   // VERIFY nome do tipo de retorno
-do
-{
-    await Task.Delay(TimeSpan.FromSeconds(30)); // poll interval para batch — não interativo
-    completedBatch = await batchClient.GetBatchAsync(batch.Id);   // VERIFY nome do método
-} while (completedBatch?.Status is not ("completed" or "failed" or "cancelled"));   // VERIFY tipo/valores do Status
-
-// ── 6. Recuperar e processar resultados ──
-if (completedBatch?.OutputFileId is { } outputFileId)
-{
-    var resultFile = await fileClient.DownloadFileAsync(outputFileId);   // VERIFY nome do método
-    using var reader = new StreamReader(resultFile.Value.ToStream());
-    string? line;
-    while ((line = await reader.ReadLineAsync()) is not null)
-    {
-        using var doc = JsonDocument.Parse(line);
-        var customId = doc.RootElement.GetProperty("custom_id").GetString();
-        var content = doc.RootElement
-            .GetProperty("response")
-            .GetProperty("body")
-            .GetProperty("choices")[0]
-            .GetProperty("message")
-            .GetProperty("content")
-            .GetString();
-        // processe content...
-    }
-}
-
-// ── 7. Tratar falhas de itens individuais ──
-if (completedBatch?.ErrorFileId is { } errorFileId)
-{
-    var errorFile = await fileClient.DownloadFileAsync(errorFileId);   // VERIFY nome do método
-    // log itens que falharam; retente individualmente se necessário
-}
-```
-
-> O poll de status (`do...while`) deve rodar num **background job** (Hangfire, Worker Service),
-> não em uma requisição HTTP. O usuário não espera; o resultado é entregue via event/webhook/DB.
-
----
-
-## Quando NÃO usar
-
-| Situação | Por quê não usar batch |
-|----------|------------------------|
-| Resposta interativa — usuário aguarda na tela | Latência de batch (minutos a horas) é inaceitável |
-| Volume baixo (< ~20 requests/dia) | Overhead de JSONL + poll não compensa |
-| Requests com dependência entre si | Batch é para prompts **independentes** |
-| Provider não-OpenAI (Anthropic, Google) | Batch API é OpenAI-specific; use completions síncronas |
-
----
-
-## Anti-patterns
-
-| Anti-pattern | Problema |
-|-------------|----------|
-| Usar batch para requests síncronos de usuário | Alta latência — batch pode demorar horas |
-| Não tratar `error_file_id` | Itens que falharam são silenciados; reprocessamento nunca acontece |
-| Poll com `Task.Delay(1s)` em loop | Abuso de rate limits; use intervalo ≥ 30 s para batch |
-| Assumir que todos os itens do batch concluem | Batch pode ter falhas parciais; itere o arquivo de erros |
-| Incluir prompt com dados do usuário sem sanitização | Prompt injection em batch; aplique `ai-agents-middleware-patterns` |
-
----
-
-## Checklist (verifiable by morph-eval)
-
-- [ ] Batch é usado somente para prompts independentes, sem usuário aguardando resposta
-- [ ] O poll de status roda em background job (Worker/Hangfire), não em request HTTP
-- [ ] `error_file_id` é verificado e erros de itens individuais são logados/retentados
-- [ ] Nenhum `Guid.NewGuid()` — custom_id usa `Guid.CreateVersion7()`
-- [ ] Provider é OpenAI; cada `// VERIFY:` da API .NET de batch confirmado contra o pacote instalado antes de codar
-
----
-
-## References
-
-- `ai-agents-setup` — setup do agente MAF e packages
-- `ai-agents-service-tier-flex` — otimização de custo para jobs async
-- `ai-agents-providers-model-registry` — configuração provider-agnostic
-- OpenAI Batch API: https://platform.openai.com/docs/guides/batch
-- OpenAI .NET SDK `OpenAI.Batch`: https://github.com/openai/openai-dotnet
-
----
-
-*MORPH-SPEC by Polymorphism Tech — ai-agents/batching.md v1.0 (2026-05-19)*
+# Batching — Bulk prompt processing
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 2 (on-keyword)
+> **Keywords:** batching, batch api, bulk prompts, batch processing, async batch
+> **Read by Claude in:** plan/implement
+
+**Verified against:** MAF 1.0 GA + OpenAI .NET SDK 2.* (fluxo da Batch API confirmado pela REST API; nomes de tipos/métodos .NET marcados `// VERIFY:` — ver seção A API). Last-verified: 2026-05-19.
+
+---
+
+## Quando usar batch
+
+Use a Batch API quando você tem **N prompts independentes sem necessidade de resposta imediata**:
+
+- Relatório mensal que agrega análise de N documentos/itens
+- Reprocessamento de dados históricos com LLM (re-classificação, re-extração)
+- Geração em massa de sumários, traduções ou avaliações offline
+- Pipeline noturno de enriquecimento de dados
+
+**Vantagens:**
+- **Desconto de custo significativo** — OpenAI Batch API custa 50% menos que completions síncronas
+- **SLA relaxado** — resultados em até 24 h; adequado para trabalho assíncrono
+- **Rate limits separados** — não compete com a cota síncrona da aplicação
+
+> Regra prática: se o usuário não está esperando o resultado na tela, considere batch.
+
+---
+
+## A API
+
+> **AVISO:** Batch API é **OpenAI-specific**. O `IChatClient` do MAF não expõe batch.
+> Obtenha o `OpenAIClient` direto via configuração (mesma chave/modelo que o Model Registry usa)
+> em vez de `_modelRegistry.GetChatClient(alias)`.
+
+O fluxo tem 4 etapas: **upload do arquivo JSONL → submissão do batch → poll de status → download dos resultados**.
+
+> ### ⚠️ Status de verificação da API .NET
+>
+> O fluxo abaixo é o **padrão correto da OpenAI Batch API** (confirmado pela REST API e pelos
+> docs oficiais). O que **não** foi confirmável via context7 são os nomes exatos de tipos/métodos
+> do **OpenAI .NET SDK 2.\*** para batch — o context7 retornou apenas as APIs de Assistants/Files.
+>
+> **Confirmado:** `openAIClient.GetOpenAIFileClient()` → `OpenAIFileClient`; upload de arquivo
+> via `UploadFileAsync(stream, filename, FileUploadPurpose.*)`.
+>
+> **A confirmar contra o pacote `OpenAI` 2.\* instalado** (todos marcados `// VERIFY:` no código):
+> nome do método que retorna o batch client (`GetBatchClient()`), namespace do batch
+> (`OpenAI.Batch`), assinatura de `CreateBatchAsync`, nomes de `GetBatchAsync`/`DownloadFileAsync`,
+> tipo/valores do status, e o valor de `FileUploadPurpose` para batch.
+> **Antes de codar:** abra o pacote no IntelliSense ou no [openai-dotnet](https://github.com/openai/openai-dotnet) e confirme cada `// VERIFY:`.
+
+---
+
+## Exemplo C# completo
+
+```csharp
+using OpenAI;
+using OpenAI.Batch;   // VERIFY namespace — confirme contra o pacote OpenAI 2.* instalado
+using OpenAI.Files;
+using System.ClientModel;
+using System.Text;
+using System.Text.Json;
+
+// ── 1. Construir o cliente OpenAI direto (mesma config que o Model Registry usa) ──
+var apiKey = configuration["OpenAI:ApiKey"]!;
+var openAIClient = new OpenAIClient(new ApiKeyCredential(apiKey));
+var fileClient = openAIClient.GetOpenAIFileClient();   // confirmado
+var batchClient = openAIClient.GetBatchClient();   // VERIFY método — pode ser GetOpenAIBatchClient()
+
+// ── 2. Montar o arquivo JSONL com N requests independentes ──
+var items = new[] { "Item A", "Item B", "Item C" }; // substitua pela sua coleção
+var jsonlBuilder = new StringBuilder();
+foreach (var item in items)
+{
+    var request = new
+    {
+        custom_id = $"req-{Guid.CreateVersion7()}",
+        method = "POST",
+        url = "/v1/chat/completions",
+        body = new
+        {
+            model = configuration["OpenAI:Model"] ?? "gpt-4o-mini",
+            messages = new[]
+            {
+                new { role = "user", content = $"Analyze this item and return a JSON summary: {item}" }
+            },
+            max_tokens = 256
+        }
+    };
+    jsonlBuilder.AppendLine(JsonSerializer.Serialize(request));
+}
+
+// ── 3. Upload do arquivo JSONL ──
+var jsonlBytes = Encoding.UTF8.GetBytes(jsonlBuilder.ToString());
+using var jsonlStream = new MemoryStream(jsonlBytes);
+// VERIFY valor do enum — FileUploadPurpose.Batch (confirme; o SDK 2.* expõe outros purposes)
+OpenAIFile batchFile = await fileClient.UploadFileAsync(
+    jsonlStream, "batch_requests.jsonl", FileUploadPurpose.Batch);
+
+// ── 4. Submeter o batch ──
+// VERIFY assinatura de CreateBatchAsync — provável (fileId, endpoint, completionWindow)
+var batch = await batchClient.CreateBatchAsync(
+    batchFile.Id,
+    endpoint: "/v1/chat/completions",
+    completionWindow: "24h");
+
+// ── 5. Poll de status (em background job / Hangfire / Worker) ──
+OpenAIBatch? completedBatch = null;   // VERIFY nome do tipo de retorno
+do
+{
+    await Task.Delay(TimeSpan.FromSeconds(30)); // poll interval para batch — não interativo
+    completedBatch = await batchClient.GetBatchAsync(batch.Id);   // VERIFY nome do método
+} while (completedBatch?.Status is not ("completed" or "failed" or "cancelled"));   // VERIFY tipo/valores do Status
+
+// ── 6. Recuperar e processar resultados ──
+if (completedBatch?.OutputFileId is { } outputFileId)
+{
+    var resultFile = await fileClient.DownloadFileAsync(outputFileId);   // VERIFY nome do método
+    using var reader = new StreamReader(resultFile.Value.ToStream());
+    string? line;
+    while ((line = await reader.ReadLineAsync()) is not null)
+    {
+        using var doc = JsonDocument.Parse(line);
+        var customId = doc.RootElement.GetProperty("custom_id").GetString();
+        var content = doc.RootElement
+            .GetProperty("response")
+            .GetProperty("body")
+            .GetProperty("choices")[0]
+            .GetProperty("message")
+            .GetProperty("content")
+            .GetString();
+        // processe content...
+    }
+}
+
+// ── 7. Tratar falhas de itens individuais ──
+if (completedBatch?.ErrorFileId is { } errorFileId)
+{
+    var errorFile = await fileClient.DownloadFileAsync(errorFileId);   // VERIFY nome do método
+    // log itens que falharam; retente individualmente se necessário
+}
+```
+
+> O poll de status (`do...while`) deve rodar num **background job** (Hangfire, Worker Service),
+> não em uma requisição HTTP. O usuário não espera; o resultado é entregue via event/webhook/DB.
+
+---
+
+## Quando NÃO usar
+
+| Situação | Por quê não usar batch |
+|----------|------------------------|
+| Resposta interativa — usuário aguarda na tela | Latência de batch (minutos a horas) é inaceitável |
+| Volume baixo (< ~20 requests/dia) | Overhead de JSONL + poll não compensa |
+| Requests com dependência entre si | Batch é para prompts **independentes** |
+| Provider não-OpenAI (Anthropic, Google) | Batch API é OpenAI-specific; use completions síncronas |
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Problema |
+|-------------|----------|
+| Usar batch para requests síncronos de usuário | Alta latência — batch pode demorar horas |
+| Não tratar `error_file_id` | Itens que falharam são silenciados; reprocessamento nunca acontece |
+| Poll com `Task.Delay(1s)` em loop | Abuso de rate limits; use intervalo ≥ 30 s para batch |
+| Assumir que todos os itens do batch concluem | Batch pode ter falhas parciais; itere o arquivo de erros |
+| Incluir prompt com dados do usuário sem sanitização | Prompt injection em batch; aplique `ai-agents-middleware-patterns` |
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] Batch é usado somente para prompts independentes, sem usuário aguardando resposta
+- [ ] O poll de status roda em background job (Worker/Hangfire), não em request HTTP
+- [ ] `error_file_id` é verificado e erros de itens individuais são logados/retentados
+- [ ] Nenhum `Guid.NewGuid()` — custom_id usa `Guid.CreateVersion7()`
+- [ ] Provider é OpenAI; cada `// VERIFY:` da API .NET de batch confirmado contra o pacote instalado antes de codar
+
+---
+
+## References
+
+- `ai-agents-setup` — setup do agente MAF e packages
+- `ai-agents-service-tier-flex` — otimização de custo para jobs async
+- `ai-agents-providers-model-registry` — configuração provider-agnostic
+- OpenAI Batch API: https://platform.openai.com/docs/guides/batch
+- OpenAI .NET SDK `OpenAI.Batch`: https://github.com/openai/openai-dotnet
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/batching.md v1.0 (2026-05-19)*