@polymorphism-tech/morph-spec 8.33.0 → 8.35.0

package/framework/standards/ai-agents/agent-spec.md

@@ -0,0 +1,196 @@
+# Agent Spec — o agente como dado, não como construção espalhada
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 1 (on-keyword)
+> **Keywords:** agent spec, AgentSpec, agent catalog, AgentCatalog, um agente por spec, defaults do agente, quantos agentes
+> **Read by Claude in:** implement (ao declarar ou alterar um agente) e plan (ao contar quantos agentes a feature cria)
+
+**Verified against:** Microsoft.Agents.AI 1.20.0 + Microsoft.Extensions.AI 10.9.0 (ai-pin 2026-09-08); provado por `templates/dotnet/ai-kit/src/Morph.AiKit/Agents/AgentSpec.cs`, `.../Agents/AgentSpecOptions.cs` e `.../Agents/AgentFactory.cs` — o record, o bag de opções e a materialização são exatamente o que o kit compila. Last-verified: 2026-09-08.
+
+---
+
+## O agente como dado
+
+**Este standard possui:** a **forma do record** que descreve um agente, o **catálogo** que os
+enumera, e a regra **"nulo = não envia"**. Ele **não** possui: timeout, retry, strict e temperatura
+como valores de runtime (`ai-agents-llm-runtime-defaults`), tarifa e teto de custo
+(`ai-agents-cost-and-budget`), a origem do texto de `Instructions`
+(`ai-agents-prompt-sources`), nem o **schema** do arquivo de registry
+(`ai-agents-providers-model-registry`, Layer 0). Os cinco descrevem **um** artefato; a fronteira
+está escrita nos cinco para que ninguém precise adivinhar onde um campo mora.
+
+A dor que este standard mata é de **contagem**. Quando o agente é construído inline em cada
+call-site, ninguém no projeto consegue responder três perguntas triviais:
+
+1. Quantos agentes existem?
+2. Cada um roda com que modelo, e com que esforço de raciocínio?
+3. Onde está o default que vale de verdade?
+
+Medição de campo que motiva a regra: num projeto do acervo o agente é construído em **cinco
+lugares distintos**, e os defaults **divergem do que roda** — um call-site diz um modelo, o
+`appsettings.json` diz outro, e a documentação de arquitetura do próprio projeto ainda registra o
+primeiro. No mesmo projeto, acrescentar um campo de spec exige **seis pontos de wiring, cinco dos
+quais falham em silêncio**.
+
+A forma que resolve: **um agente, uma spec**. A spec é um `record` imutável, sem comportamento de
+execução, que não abre conexão e não lê configuração — o que permite descrevê-lo em teste, em JSON
+ou em banco sem arrastar infraestrutura junto.
+
+---
+
+## AgentSpec
+
+Os campos, medidos no record que o kit compila:
+
+| Campo | Tipo | Regra |
+|---|---|---|
+| `Alias` | `string` **required** | Chave no registry, **nunca** um id de modelo. Vazio ou só espaço é rejeitado **na construção** |
+| `Instructions` | `string` **required** | Prompt de sistema. Vazio ou só espaço é rejeitado na construção |
+| `Api` | `AgentApi?` | Protocolo desta spec. **Nulo = usa o `api:` do alias**, que é o caso normal |
+| `Tools` | `IReadOnlyList<AITool>` | Vazio por padrão — **nunca nulo** |
+| `OutputSchema` | `JsonElement?` | Nulo = saída livre |
+| `Options` | `AgentSpecOptions` | Bag único de opções. Nunca nulo; o default não envia opção nenhuma |
+| `Name` | `string?` | Nome legível (telemetria, logs) |
+| `Description` | `string?` | Descrição legível |
+
+**Duas decisões de forma que valem mais que a lista.**
+
+**(1) Validar na construção, não no uso.** `Alias` e `Instructions` rejeitam branco no `init`. Um
+alias vazio que passa da construção vira uma falha de resolução ilegível várias camadas adiante,
+num stack trace que não menciona o agente.
+
+**(2) A precedência mora num lugar só.** Quando a spec traz `Api` e o alias traz outro, quem vence?
+A resposta é um método no próprio record — `ResolveApi(aliasApi) => Api ?? aliasApi` — e **não** uma
+condicional dentro da fábrica. O motivo é escrito no kit: divergência silenciosa entre spec e
+registry é exatamente o bug que o `api:` por alias existe para eliminar, e uma regra copiada em dois
+lugares é uma regra que já divergiu.
+
+### A regra que este standard torna doutrina: nulo = não envia
+
+**Propriedade nula significa "não envia ao provider" — nunca "envia o default do framework".**
+
+Sem essa regra, cada propriedade opcional carrega uma segunda pergunta invisível: *o framework
+preenche isso por mim?* Com ela, a leitura é local e total: o que está nulo não aparece na chamada,
+e o que aparece na chamada é o que alguém escreveu.
+
+O corolário incômodo, e ele é parte da regra: **dentro de `Options`, lista vazia não é tratada como
+nulo**. `[]` é enviado como veio — `StopSequences` é o exemplar: o kit testa `is not null`, não
+`Count > 0`.
+
+**E há exatamente uma exceção, que este standard nomeia em vez de esconder.** `Tools` não vive em
+`Options`: vive na própria `AgentSpec`, é `IReadOnlyList<AITool>` (nunca nulo, vazio por padrão), e o
+kit a copia sob `if (spec.Tools.Count > 0)` — medido em `AgentFactory.cs`. Consequência: um
+`Tools = []` **explícito** não chega ao `ChatOptions`, e o provider recebe a chamada sem lista de
+tools em vez de com uma lista vazia.
+
+Isso é defensável (uma lista vazia enviada muda o comportamento de alguns providers) e é **por isso**
+que precisa estar escrito: a regra "nulo não envia; não-nulo envia o que você escreveu" vale
+**dentro de `Options`**; em `Tools`, o vazio também não envia, porque ali não existe nulo para
+distinguir do vazio. Uma exceção nomeada é uma regra; uma exceção não nomeada é o tipo de coisa que
+só se descobre lendo a fatura.
+
+O segundo corolário: quando `Options` não traz o esforço de raciocínio, vale **o default do
+provider**, e o kit **não afirma saber qual é**. Não saber e dizer que não sabe é mais barato do que
+documentar um default que o provider muda sem avisar.
+
+---
+
+## AgentCatalog
+
+Um lugar que responde: *quantos agentes existem, com que alias, e com que opções*. É o que
+transforma "cinco call-sites" em "cinco linhas de uma lista".
+
+O catálogo é **enumerável** e **inerte**: ele não constrói agentes, ele os declara. Construir é da
+fábrica.
+
+> **Item de catálogo sem consumidor em runtime é letra morta.** Precedente medido: um agente
+> seedado por migration, com prompt versionado no banco, **sem nenhum consumidor em C#** —
+> aparecendo apenas como alias fictício num arquivo de teste. Ele custou uma migration, ocupa uma
+> linha na tabela de prompts e responde por zero comportamento.
+
+Por isso a regra é dupla: todo agente do catálogo **é referenciado por um caminho de execução**, e
+todo agente executado **está no catálogo**. Uma verificação barata é contar: quantidade de entradas
+no catálogo × quantidade de call-sites que resolvem uma entrada. Divergência é achado, não ruído.
+
+---
+
+## Defaults fora do código
+
+O default do agente mora **na configuração do registry**, não num literal. Um valor default escrito
+em C# é invisível para quem lê o JSON, e um valor no JSON é invisível para quem lê o C# — ter os
+dois é garantir que um deles esteja errado.
+
+Regras:
+
+- O alias default é declarado no documento do registry (`defaultAlias`), não escolhido por um `??`
+  em algum handler.
+- Um limite conhecido de um alias (por exemplo, "este modelo rejeita tool calling com esforço de
+  raciocínio diferente de `None`") é **campo do alias, com procedência escrita**, nunca uma regra
+  universal chumbada no código. O kit recusa carregar um limite sem procedência — justamente para
+  que ninguém consiga gravar um "todo mundo sabe que" sem dizer de onde tirou.
+- Quando um default do provider é desconhecido, o correto é **não enviar** e não documentar palpite.
+
+---
+
+## Higiene de publicação
+
+O documento do registry é **arquivo de produção**. Override de desenvolvimento não mora nele.
+
+Os dois lados foram medidos no acervo:
+
+| Prática | O que aconteceu |
+|---|---|
+| **Anti-padrão** | Um alias apontando para um modelo local foi **commitado** no registry, com o comentário `"OVERRIDE LOCAL (teste com Ollama) — NÃO COMMITAR"` ao lado. O comentário estava certo; o commit aconteceu do mesmo jeito |
+| **Padrão** | Outro projeto mantém deliberadamente o override de endpoint e de modelo **fora** do registry, em configuração de ambiente, com a razão escrita no código: *"o JSON também vale em produção"* |
+
+A regra: o que vale nas duas pontas vai no registry; o que vale só na sua máquina vai em
+configuração de ambiente ou em `appsettings.Development.json`, que não é publicado. Um comentário
+avisando para não commitar não é um mecanismo — é uma esperança.
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Por quê é problema | Solução |
+|---|---|---|
+| Agente construído inline em cada call-site | Ninguém consegue responder "quantos agentes existem" nem "com que modelo" | Uma `AgentSpec` por agente, num catálogo |
+| Id de modelo dentro da spec | Trocar de provider vira uma varredura; o registry deixa de ser fonte | `Alias`, sempre |
+| Default do agente escrito como literal em C# | Duas fontes para o mesmo valor, e uma delas está errada | Default no documento do registry |
+| Nulo interpretado como "manda o default do framework" | A chamada passa a carregar valores que ninguém escreveu | Nulo = não envia. Sem exceção |
+| Lista vazia tratada como nula **sem a exceção nomeada** | A regra deixa de ser local: quem lê não sabe que `Tools = []` não chega ao provider | `[]` é enviado como veio dentro de `Options`; a exceção de `Tools` fica escrita |
+| Precedência spec × alias resolvida dentro da fábrica | A regra copiada em dois lugares já divergiu | Um método no próprio record |
+| Entrada de catálogo sem consumidor em runtime | Migration paga, linha na tabela, zero comportamento | Toda entrada é referenciada por um caminho de execução |
+| Override de dev commitado no registry | O arquivo vale em produção; o override vaza | Override fora do arquivo publicado |
+| Validação de `Alias`/`Instructions` adiada para o uso | Falha ilegível várias camadas adiante | Rejeite branco no `init` |
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] Existe exatamente **uma** `AgentSpec` por agente, e nenhum agente é construído inline
+- [ ] Nenhuma spec contém id de modelo — só `Alias`
+- [ ] `Alias` e `Instructions` são validados na construção (branco é rejeitado ali)
+- [ ] A precedência entre o `api:` da spec e o do alias existe em **um** lugar
+- [ ] Toda propriedade opcional nula **não** é enviada ao provider; nenhum código preenche default
+      de framework por baixo
+- [ ] Toda exceção à regra "não-nulo envia o que você escreveu" está **nomeada** no standard do
+      projeto (no exemplar do kit há exatamente uma: `Tools = []` não é enviada)
+- [ ] O catálogo enumera todos os agentes, e toda entrada tem ao menos um consumidor em runtime
+- [ ] O `defaultAlias` está no documento do registry, não num `??` de handler
+- [ ] Nenhum override de desenvolvimento no arquivo de registry publicado
+
+---
+
+## References
+
+- `ai-agents-providers-model-registry` — Layer 0, dono do **schema** do documento, do `defaultAlias`,
+  do fallback e da tabela de providers. Este standard não repete nada disso
+- `ai-agents-setup` — pacotes e `Program.cs`; a construção provider a provider é lá
+- `ai-agents-agent-archetypes` — qual **forma** de agente a spec descreve
+- `ai-agents-llm-runtime-defaults` — timeout, retry, strict, temperatura e o pin de SDK
+- `ai-agents-cost-and-budget` — `pricing` por alias, cálculo e teto
+- `ai-agents-prompt-sources` — de onde vem o texto de `Instructions`, e como provar qual versão rodou
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/agent-spec.md v1.0 (2026-09-08)*

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

@@ -1,193 +1,217 @@
-# 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:** OpenAI 2.13.0 (ai-pin 2026-09-08) + Microsoft.Extensions.AI 10.9.0. **Verificação documental** do fluxo da Batch API (platform.openai.com/docs/guides/batch, lido 2026-09-08), sem cláusula `provado por`: o ai-kit **referencia** o pacote `OpenAI` no `.csproj` — contrato de versão, régua = restore (`NU1102`) — mas **não o exercita**; não existe um único `using OpenAI` em `src/` (medido 2026-09-08), logo um rename de API não reprova a PR. Ver a tabela "Dois níveis de garantia" no README do kit. **Todos os nomes de tipo e assinaturas .NET foram medidos por reflexão sobre a assembly `OpenAI` 2.13.0 em 2026-09-08**, e os 9 marcadores `// VERIFY` desta página foram RESOLVIDOS por essa medição. Last-verified: 2026-09-08.
+
+---
+
+## 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**.
+
+### A superfície real do SDK 2.13.0 — medida, não suposta
+
+A versão anterior deste standard marcava sete nomes como "a confirmar". Foram conferidos por reflexão sobre a assembly do pin em 2026-09-08. O resultado corrige mais do que confirma:
+
+| O que estava escrito | O que a assembly 2.13.0 diz |
+|---|---|
+| `openAIClient.GetBatchClient()` (talvez `GetOpenAIBatchClient()`) | **`GetBatchClient()`** ✔ — devolve `OpenAI.Batch.BatchClient` |
+| namespace `OpenAI.Batch` | ✔ existe (`BatchClient`, `BatchJob`, `CreateBatchOperation`, `BatchCollectionOptions`) |
+| `FileUploadPurpose.Batch` | ✔ existe (ao lado de `Assistants`, `FineTune`, `Vision`, `UserData`, `Evaluations`) |
+| `fileClient.UploadFileAsync(stream, filename, purpose)` | ✔ existe, com essa exata assinatura |
+| `fileClient.DownloadFileAsync(fileId)` | ✔ existe — devolve `ClientResult<BinaryData>` |
+| `CreateBatchAsync(fileId, endpoint, completionWindow)` | ✘ **NÃO EXISTE.** A assinatura real é `CreateBatchAsync(BinaryContent content, bool waitUntilCompleted, RequestOptions options)` — método de **protocolo**: o corpo do request é montado por você |
+| tipo de retorno `OpenAIBatch` | ✘ **não existe.** O modelo é **`BatchJob`**; e `CreateBatchAsync` devolve **`CreateBatchOperation`** |
+| `GetBatchAsync(id)` com `Status` tipado | ✘ **`GetBatchAsync(string batchId, RequestOptions options)` devolve `ClientResult` cru.** Além disso `BatchJob.Status` é do tipo **`InternalBatchStatus`**, que **não é exportado**: mesmo desserializando o `BatchJob`, o consumidor não consegue nomear o tipo do status |
+
+**A conclusão que muda o código:** no `OpenAI` 2.13.0, **Batch é uma API de protocolo, não de modelo**. Você monta o corpo do request e lê o status do **JSON da resposta**. Um exemplo escrito com opções fortemente tipadas não compila — e essa era exatamente a dúvida que os `// VERIFY` marcavam.
+
+`CreateBatchOperation` traz `BatchId`, `GetBatchAsync()`, `CancelAsync()` e `RehydrationToken` — este último é o que permite **retomar o acompanhamento depois de um restart** sem guardar estado próprio: guarde o token, reidrate com `CreateBatchOperation.RehydrateAsync(client, token)`.
+
+---
+
+## Exemplo C# completo
+
+```csharp
+using OpenAI;
+using OpenAI.Batch;
+using OpenAI.Files;
+using System.ClientModel;
+using System.ClientModel.Primitives;
+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));
+OpenAIFileClient fileClient  = openAIClient.GetOpenAIFileClient();
+BatchClient      batchClient = openAIClient.GetBatchClient();
+
+// ── 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 ──
+using var jsonlStream = new MemoryStream(Encoding.UTF8.GetBytes(jsonlBuilder.ToString()));
+OpenAIFile batchFile = await fileClient.UploadFileAsync(
+    jsonlStream, "batch_requests.jsonl", FileUploadPurpose.Batch);
+
+// ── 4. Submeter o batch ──
+// CreateBatchAsync é método de PROTOCOLO: o corpo vai como BinaryContent.
+// waitUntilCompleted: false → devolve a operação imediatamente (o poll é seu, no §5).
+using var createBody = BinaryContent.Create(BinaryData.FromObjectAsJson(new
+{
+    input_file_id    = batchFile.Id,
+    endpoint         = "/v1/chat/completions",
+    completion_window = "24h",
+}));
+
+CreateBatchOperation operation =
+    await batchClient.CreateBatchAsync(createBody, waitUntilCompleted: false);
+
+string batchId = operation.BatchId;
+// Guarde operation.RehydrationToken se o poll roda em OUTRO processo/depois de um restart.
+
+// ── 5. Poll de status (em background job / Hangfire / Worker) ──
+// GetBatchAsync devolve ClientResult cru, e BatchJob.Status é de um tipo NÃO EXPORTADO
+// (InternalBatchStatus). O status se lê do JSON — não há caminho tipado no 2.13.0.
+string status;
+JsonElement batchDoc;
+do
+{
+    await Task.Delay(TimeSpan.FromSeconds(30)); // poll interval para batch — não interativo
+    ClientResult raw = await batchClient.GetBatchAsync(batchId, options: null);
+    batchDoc = JsonDocument.Parse(raw.GetRawResponse().Content.ToMemory()).RootElement;
+    status = batchDoc.GetProperty("status").GetString()!;
+} while (status is not ("completed" or "failed" or "cancelled" or "expired"));
+
+// ── 6. Recuperar e processar resultados ──
+if (batchDoc.TryGetProperty("output_file_id", out var outEl) && outEl.GetString() is { } outputFileId)
+{
+    BinaryData resultFile = await fileClient.DownloadFileAsync(outputFileId);
+    using var reader = new StreamReader(resultFile.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 (batchDoc.TryGetProperty("error_file_id", out var errEl) && errEl.GetString() is { } errorFileId)
+{
+    BinaryData errorFile = await fileClient.DownloadFileAsync(errorFileId);
+    // 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.
+> Se o job pode reiniciar, persista `operation.RehydrationToken` e retome com
+> `CreateBatchOperation.RehydrateAsync(batchClient, token)` em vez de guardar só o `batchId`.
+
+---
+
+## 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 |
+| Escrever `CreateBatchAsync(fileId, endpoint, completionWindow)` | Essa sobrecarga não existe no `OpenAI` 2.13.0 — o método é de protocolo e recebe `BinaryContent` |
+| Tipar o status como `OpenAIBatch.Status` | `OpenAIBatch` não existe; `BatchJob.Status` é de um tipo não exportado. Leia o status do JSON |
+| Guardar só o `batchId` num job que pode reiniciar | Perde o acompanhamento da operação | 
+| 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, com `PackageReference Include="OpenAI" Version="2.13.0"` (versão exata)
+- [ ] O status do batch é lido do JSON da resposta — nenhum código tenta tipar `Status` ou usar `OpenAIBatch`
+- [ ] `waitUntilCompleted: false` + poll próprio, ou `RehydrationToken` persistido se o poll pode reiniciar
+
+---
+
+## 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 (superfície medida na assembly 2.13.0 em 2026-09-08)
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/batching.md v2.0 (2026-09-08)*