@polymorphism-tech/morph-spec 8.34.2 → 8.35.0

package/framework/standards/ai-agents/media-video.md

@@ -0,0 +1,267 @@
+# Media — Video Generation (runtime, a partir de .NET)
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 2 (on-keyword)
+> **Keywords:** video generation, veo, seedance, kling, runway, image to video, text to video, media video
+> **Read by Claude in:** implement (quando o projeto precisa gerar vídeo em runtime)
+
+**Verified against:** Google.GenAI 1.21.0 + OpenAI 2.13.0 (ai-pin 2026-09-08); provado por `templates/dotnet/ai-kit/src/Morph.AiKit/Media/Providers/VeoVideoProvider.cs` — `Models.GenerateVideosAsync(model, GenerateVideosSource, GenerateVideosConfig, ct)`, o polling por `Operations.GetAsync` + `operation.Done` e o sinal de bloqueio `RaiMediaFilteredCount` COMPILAM ali. Preço, duração, retenção e data de desligamento são **verificação documental** contra as páginas listadas em §Como re-verificar este standard. Last-verified: 2026-09-08.
+
+---
+
+**A fronteira, primeiro.** Este standard é sobre **gerar vídeo em runtime a partir de .NET**: o
+backend cria uma tarefa paga, faz polling, baixa bytes e guarda. Footage de landing page
+scroll-driven, produzido por MCP em **tempo de autoria**, é
+`frontend/design-system/ai-video-generation.md` — loop × direcional, `endImage`, o contorno de
+moderação E005 e a escada de custo daquele fluxo. Os dois se citam e não se sobrepõem: lá o
+operador é um designer numa sessão; aqui é um worker no seu servidor.
+
+O pipeline (job, revisão, publicação, marcação) é `ai-agents/media-pipeline.md`. Imagem é
+`ai-agents/modalities-image-gen.md`.
+
+---
+
+## Quando usar
+
+| Caso | Nota |
+|---|---|
+| **Vídeo curto de produto** (reels, stories, até 8 s com áudio) | O caso que paga a conta |
+| **Animar render de cliente** | `img2vid` sobre a arte real, nunca recriação por IA |
+| **Variação de cena** sobre um herói aprovado | Depois da aprovação da imagem, nunca antes |
+
+**Nunca dentro de um turno de conversa.** A geração de vídeo leva de **11 s a 6 min** medidos na
+documentação do Veo, é assíncrona **por desenho em todos os provedores** — nenhum deles devolve o
+arquivo na resposta do POST — e custa por segundo de saída. Não existe forma de fazer isso caber num
+turno de WhatsApp; a tentativa é `ai-agents/media-pipeline.md` §A regra dura.
+
+---
+
+## O caminho com SDK
+
+`Google.GenAI` 1.21.0, `net8.0` + `netstandard2.0`. É o **único** caminho com SDK .NET oficial
+depois do desligamento listado em §Deprecações.
+
+```csharp
+using Google.GenAI.Types;
+
+// 1. Cria a operacao. Ela volta NAO-concluida: o video ainda nao existe.
+//    O prompt vai DENTRO de GenerateVideosSource — nao e um parametro solto.
+var operation = await client.Models.GenerateVideosAsync(
+    "veo-3.1-fast-generate-preview",
+    new GenerateVideosSource { Prompt = prompt },
+    new GenerateVideosConfig { DurationSeconds = 8, AspectRatio = "16:9" },
+    ct);
+
+// 2. Polling. ~10 s entre voltas e o intervalo que a doc do Veo usa; back-off e
+//    TETO DE TENTATIVAS — um laco sem saida e indistinguivel de um worker travado.
+//    `Done` e bool? : `!operation.Done` NAO compila; compare com true.
+for (var poll = 0; operation.Done != true && poll < 60; poll++)
+{
+    await Task.Delay(TimeSpan.FromSeconds(10), ct);
+    operation = await client.Operations.GetAsync(operation, new GetOperationConfig(), ct);
+}
+
+// 3. Bloqueio de moderacao NAO e erro tecnico, e o sinal e este:
+if (operation.Response?.RaiMediaFilteredCount is > 0) { /* rejected_by_policy, sem retry */ }
+
+// 4. BAIXE OS BYTES AGORA (operation.Response.GeneratedVideos[..].Video.VideoBytes).
+//    Ver a secao "O arquivo expira".
+```
+
+> **Assinaturas medidas contra `Google.GenAI` 1.21.0 por reflexão, não lidas em blog.** Três
+> detalhes derrubam o build de quem copia de uma página de terceiro: o prompt viaja em
+> `GenerateVideosSource`, `Operations.GetAsync` pede um `GetOperationConfig` (não só o token), e
+> `operation.Done` é `bool?` — `while (!operation.Done)` não compila. O exemplar que compila está
+> em `templates/dotnet/ai-kit/src/Morph.AiKit/Media/Providers/VeoVideoProvider.cs`.
+
+Três exigências de desenho que caem deste formato, e não são opcionais:
+
+1. **O `operation` é estado persistido**, não variável local. Se o worker reiniciar no meio, o id da
+   operação tem de estar no banco — senão você paga de novo por um vídeo que já está pronto.
+2. **O polling mora num job**, nunca numa request HTTP. Um `while` de 6 minutos dentro de um
+   controller é um thread pool derretido.
+3. **Timeout e teto de tentativas explícitos.** `Done` que nunca vira `true` é um caso real, e um
+   loop sem saída é indistinguível de um worker travado.
+
+---
+
+## O caminho sem SDK
+
+Seedance 2.0 (BytePlus ModelArk ou fal.ai), Kling 3.0 e Runway **não têm SDK .NET**. Sem exceção,
+sem "biblioteca da comunidade": `HttpClient` **tipado** via `IHttpClientFactory`, DTOs próprios,
+`System.Text.Json` com source generation, e Polly para 429/5xx/timeout.
+
+O contrato é o mesmo nos três, e é o que torna o adaptador escrevível:
+
+```
+POST criar tarefa  →  { id }        (202 / 200, NUNCA o arquivo)
+        ↓  persistir o id ANTES de qualquer outra coisa
+GET status(id)     →  queued | running | succeeded | failed
+        ↓  polling com back-off, OU webhook (fal.ai, Runway)
+GET resultado      →  URL temporaria  →  baixar  →  blob proprio
+```
+
+**Persistir o id antes de qualquer outra coisa** é a linha que separa "retry custa zero" de "retry
+custa outra geração". O resto do desenho — chave de idempotência, estados, storage — está em
+`ai-agents/media-pipeline.md`.
+
+Webhook, onde existe, é preferível a polling: menos chamada, menos latência de detecção. Mas o
+polling continua sendo o caminho de recuperação quando o webhook se perde — implemente os dois, e
+faça o handler de webhook idempotente.
+
+---
+
+## Sora: não planejar
+
+`sora-2`, `sora-2-pro` e o `VideoClient` do `openai-dotnet` (`CreateVideo`, `GetVideo`,
+`DownloadVideo`, `CreateVideoRemix`) **saem de circulação sem substituto** — a data está em
+§Deprecações. "Sem substituto" é literal: a OpenAI não anunciou modelo de vídeo sucessor.
+
+Consequência prática: **não escreva adaptador para Sora**, não pine alias de Sora, e se encontrar um
+num projeto existente, a migração é para o caminho com SDK do Google ou para um dos HTTP crus. Um
+adaptador escrito hoje para Sora nasce morto.
+
+---
+
+## Custo por segundo
+
+> **Toda a aritmética de dinheiro deste standard mora nesta seção, e em lugar nenhum mais.**
+
+Preço de **lista pública**, em USD por segundo de saída, sem desconto de contrato. Consultadas em
+**2026-09-07**: `https://ai.google.dev/gemini-api/docs/veo` com
+`https://ai.google.dev/gemini-api/docs/pricing`, `https://docs.byteplus.com/en/docs/ModelArk/1520757`,
+`https://fal.ai/models/bytedance/seedance-2.0/image-to-video`, `https://kling.ai/dev/pricing` e
+`https://docs.dev.runwayml.com/guides/pricing/`.
+
+| Modelo | Preço | Nota |
+|---|---|---|
+| Veo 3.1 **Lite** | $0,05 / s | Sem 4K |
+| Veo 3.1 **Fast** — 720p | $0,10 / s | O default recomendado; áudio incluso |
+| Veo 3.1 Standard — 720p/1080p | $0,40 / s | 4K: $0,60 / s |
+| Seedance 2.0 (BytePlus oficial) | $0,04 – $0,78 / s | Varia por modelo e resolução; pacote pré-pago mínimo de $30,10 |
+| Seedance 2.0 (fal.ai) | $0,3024 / s std 720p; $0,2419 / s fast | Mesmo modelo, agregador diferente, preço diferente |
+| Kling 3.0 std | ≈ $0,42 por 5 s | Sem SDK |
+| Runway gen4.5 | $0,12 / s | Créditos a $0,01; 12 cr/s |
+
+Três leituras que decidem projeto:
+
+1. **A faixa do Seedance é de 20× entre o piso oficial e o teto**, e o mesmo modelo custa preços
+   diferentes conforme o agregador. Por isso **nenhum alias default é pinado** para Seedance, Kling
+   ou Runway neste standard: escolher um seria escolher fornecedor por conveniência de escrita, e não
+   por evidência. Meça o seu caso antes de pinar.
+2. **Vídeo é caro por segundo e mínimo de 4 s.** Um rascunho de 4 s em Lite custa uma fração de um
+   final de 8 s em Standard — a escada de custo é a mesma disciplina de imagem, com números maiores.
+3. **Bloqueio de moderação no Veo não cobra.** Isso muda o desenho de retry: um bloqueio é
+   `rejected_by_policy` e não deve ser retentado; um erro técnico é `failed` e deve.
+
+---
+
+## Duração, resolução e referências
+
+Medido contra `https://ai.google.dev/gemini-api/docs/veo` (Veo 3.1) e a doc do BytePlus ModelArk
+(Seedance 2.0), ambas consultadas na data declarada em §Custo por segundo.
+
+| Parâmetro | Veo 3.1 | Seedance 2.0 |
+|---|---|---|
+| Duração | 4, 6 ou 8 s | 4 a 15 s |
+| **8 s é obrigatório** para | 1080p, 4K e uso de imagens de referência | — |
+| Aspect ratio | 16:9 ou 9:16 | 480p / 720p / 1080p |
+| Frame rate | 24 fps | — |
+| Áudio | nativo, incluso no preço | nativo |
+| Imagem inicial | sim (primeiro frame) | JPEG/PNG/WebP até 30 MB |
+| Interpolação | primeiro + último frame | imagem final opcional |
+| Referências | **até 3 imagens** (exige 8 s) | referências de vídeo e áudio |
+| Extensão | +7 s, até 20 vezes (720p) | — |
+
+"8 s obrigatório para referências" é a pegadinha cara: pedir 4 s **com** imagem de referência é uma
+requisição inválida, e descobrir isso em produção custa uma rodada de suporte.
+
+---
+
+## O arquivo expira
+
+O Veo retém o arquivo gerado por **2 dias**. Depois disso a URL devolve 404 e o vídeo pelo qual você
+pagou não existe mais em lugar nenhum.
+
+**Baixar e gravar no blob próprio é obrigação, não otimização.** O download entra no mesmo passo do
+worker que detectou `Done`, antes de qualquer outra coisa; o banco guarda caminho relativo + sha256,
+nunca a URL do provedor. O mesmo vale para todo agregador: URL de resultado é sempre temporária.
+
+Um job que marcou `generated` sem ter baixado os bytes está mentindo sobre o próprio estado. Ver
+`ai-agents/media-pipeline.md` §Storage.
+
+---
+
+## Moderação e pessoas
+
+- **Bloqueio não cobra** (Veo). Trate-o como `rejected_by_policy`: estado terminal, **sem retry**.
+  Retentar um bloqueio é gastar dinheiro para receber o mesmo "não" — e nos provedores que cobram o
+  bloqueio, é gastar duas vezes.
+- **`personGeneration` é restrito por região.** O mesmo prompt aprovado num mercado é recusado em
+  outro; a política tem de ser por tenant, não global.
+- **Rostos disparam moderação com frequência.** O motivo e o contorno operacional (enquadrar do
+  pescoço para baixo, mãos, produto; reservar rosto para imagem estática) estão escritos em
+  `frontend/design-system/ai-video-generation.md` §Section 3 — este standard cita e não repete.
+- **Nunca gere rosto de cliente real.** Além do risco jurídico, é o caso que a marcação obrigatória
+  do `media-pipeline.md` foi feita para cobrir.
+
+---
+
+## Deprecações
+
+> **Toda data de desligamento deste standard mora nesta seção, e em lugar nenhum mais.**
+
+Fonte, consultada em **2026-09-07**: `https://developers.openai.com/api/docs/deprecations`.
+
+| Alias / superfície | Situação | Data |
+|---|---|---|
+| `sora-2`, `sora-2-pro` e a Videos API | **desligam, sem substituto** (anunciado 2026-03-24) | 2026-09-24 |
+| `VideoClient` do `openai-dotnet` | morre junto com a API acima | 2026-09-24 |
+
+**Próximo desligamento conhecido: 2026-09-24.** Se esta data já passou quando você está lendo, este
+standard não está apenas velho — ele está **errado** em pelo menos uma afirmação, e a §Como
+re-verificar diz qual página conferir. É falsificável em segundos, sem pesquisa.
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] Nenhum código novo aponta para um alias de §Deprecações
+- [ ] O id da operação/tarefa é **persistido antes** do primeiro polling
+- [ ] O polling roda num job, com back-off e teto de tentativas — nunca numa request HTTP
+- [ ] Os bytes são baixados assim que a tarefa conclui, e gravados em blob próprio
+- [ ] O banco guarda caminho relativo + sha256, nunca a URL do provedor
+- [ ] Bloqueio de moderação é estado terminal `rejected_by_policy`, sem retry
+- [ ] Duração pedida respeita o mínimo do provedor (8 s no Veo quando há referência)
+- [ ] Custo estimado gravado antes da chamada, com a tarifa de §Custo por segundo
+- [ ] Nenhuma geração dentro de um turno de conversa
+- [ ] Nenhum teste toca API paga — provider fake, sempre
+
+---
+
+## Como re-verificar este standard
+
+| Página | O que conferir |
+|---|---|
+| `https://developers.openai.com/api/docs/deprecations` | A tabela de §Deprecações e a linha "próximo desligamento conhecido" |
+| `https://ai.google.dev/gemini-api/docs/veo` | Duração, resolução, limite de referências, retenção de 2 dias, `personGeneration` |
+| `https://ai.google.dev/gemini-api/docs/pricing` | As três linhas Veo de §Custo por segundo |
+| `https://docs.byteplus.com/en/docs/ModelArk/1520757` e `https://fal.ai/models/bytedance/seedance-2.0/image-to-video` | A faixa de preço do Seedance nos dois canais |
+| `https://www.nuget.org/packages/Google.GenAI` | Se `GenerateVideosAsync`/`Operations.GetAsync` mudaram de forma |
+
+Ao terminar, atualize `Last-verified` **e** o `ai-pin` citado no header.
+
+---
+
+## References
+
+- `ai-agents/media-pipeline.md` — o job, os estados, a idempotência, a marcação
+- `ai-agents/modalities-image-gen.md` — imagem em runtime, e a escada de custo irmã desta
+- `frontend/design-system/ai-video-generation.md` — footage direcional para scroll scrub via MCP:
+  loop × direcional, `endImage`, moderação E005. Consumidor diferente, tempo diferente
+- `ai-agents/providers/model-registry.md` — o alias por provedor, com `api: videos`
+- `backend/integrations/hangfire/hangfire-jobs.md` — o mecanismo de job que o polling usa
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/media-video.md v1.0*

package/framework/standards/ai-agents/middleware-patterns.md

@@ -5,7 +5,7 @@
 > **Keywords:** middleware, agent middleware, function calling middleware, retry, anti-hallucination, resilience, telemetry middleware, agent run middleware
 > **Read by Claude in:** implement (when wiring cross-cutting behavior into an agent)
 
-**Verified against:** MAF 1.0 GA. Last-verified: 2026-05-19.
+**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/AgentFactory.cs` para a **ordem do pipeline** — a fábrica do kit é o único lugar que conhece essa ordem, e ela é medida por teste, não herdada de folclore. As assinaturas de `Use(...)` foram **medidas por reflexão sobre `AIAgentBuilder` e `ChatClientBuilder`** em 2026-09-08. Last-verified: 2026-09-08.
 
 ---
 
@@ -47,7 +47,36 @@ AIAgent agent = instrumentedClient
     .Build();
 ```
 
-> Se apenas middleware não-streaming for fornecido, chamadas streaming rodam em modo não-streaming.
+### As assinaturas, medidas
+
+Ambas as sobrecargas de dois delegates existem no pin (reflexão em 2026-09-08):
+
+- `AIAgentBuilder.Use(Func<...> runFunc, Func<...> runStreamingFunc)`
+- `ChatClientBuilder.Use(Func<...> getResponseFunc, Func<...> getStreamingResponseFunc)`
+
+Cada builder tem ainda `Use(factory)` (um delegate que embrulha o inner) e `Use(sharedFunc)` (**um** delegate que atende os dois modos). O `Use(sharedFunc)` é a resposta certa quando o middleware não se importa com streaming: escreve-se uma vez e vale para os dois caminhos.
+
+> **Fornecer só `runFunc`/`getResponseFunc` faz o caminho de streaming rodar NÃO-streaming.** Não é erro de compilação e não há aviso: a chamada streaming é atendida pelo delegate não-streaming e o consumidor recebe a resposta inteira de uma vez, tarde. Numa UI de chat isso aparece como "o streaming parou de funcionar depois que adicionamos telemetria". Se o middleware não precisa distinguir os modos, use `Use(sharedFunc)`; se precisa, forneça **os dois**.
+
+### A ordem do pipeline, medida
+
+A posição de cada elo não é estética. A ordem que o ai-kit compila e testa, de fora para dentro:
+
+```
+OpenTelemetryAgent            span invoke_agent — cobre a invocação inteira
+ └─ ChatClientAgent           (UseProvidedChatClientAsIs = true: o pipeline abaixo é seu)
+     ├─ timeout               TimeoutSeconds vira CancellationToken
+     ├─ usage-cost            vê UMA resposta com o uso já somado das voltas
+     ├─ FunctionInvoking      MaxToolIterations / AllowConcurrentToolInvocation
+     ├─ telemetria de chat    span chat, ABAIXO do FICC
+     └─ cliente do provider   memoizado pelo ModelRegistry
+```
+
+**Por que o middleware de custo fica ACIMA do `FunctionInvokingChatClient` (FICC):** acima dele, o middleware vê **uma** resposta cujo `Usage` já traz o total de todas as voltas de tool (medido: duas voltas de 10/4 e 30/6 chegam como `in=40, out=10`) e publica **uma** linha por chamada. Abaixo dele veria respostas parciais — e leria o mesmo objeto `UsageDetails` que o **próprio FICC muta** para acumular, o que faz a mesma conta dar resultado diferente conforme a hora de ler.
+
+**Por que a telemetria de chat fica ABAIXO do FICC:** só assim o span `chat` fecha antes das tools e o `invoke_agent` fica sendo a raiz.
+
+> No `ChatClientBuilder`, **o primeiro registrado é o mais externo**. Registrar o custo antes de `UseFunctionInvocation` é o que o coloca acima do FICC.
 
 ---
 
@@ -74,7 +103,9 @@ async Task<ChatResponse> TelemetryMiddleware(
 }
 ```
 
-Para o setup completo de OpenTelemetry (traces, métricas, Aspire Dashboard, `AgentOpenTelemetryConsts.DefaultSourceName`), consulte `ai-agents-production` §Observability. Não duplique aqui — este middleware é um ponto de entrada, não a solução completa.
+Para o setup completo de OpenTelemetry (traces, métricas, Aspire Dashboard, os **dois** nomes de `ActivitySource`), consulte `ai-agents-observability-patterns`, que é o dono canônico. Não duplique aqui — este middleware é um ponto de entrada, não a solução completa.
+
+> **Correção de 2026-09-08:** `AgentOpenTelemetryConsts` **não existe** em `Microsoft.Agents.AI` 1.20.0 (medido). As fontes reais são `Experimental.Microsoft.Agents.AI` e `Experimental.Microsoft.Extensions.AI`.
 
 ---
 
@@ -191,7 +222,8 @@ Precisa de middleware no agent?
 - [ ] Function Calling middleware retorna string descritiva em vez de lançar exceção
 - [ ] Anti-hallucination: argumentos validados antes de chamar `next()`
 - [ ] Nenhum middleware com `using Microsoft.SemanticKernel` — MAF 1.0 GA não usa SK
-- [ ] Streaming: se nenhum middleware streaming for fornecido, downgrade documentado como decisão consciente
+- [ ] Streaming: se nenhum middleware streaming for fornecido, o downgrade para não-streaming está documentado como decisão consciente — ou o middleware usa `Use(sharedFunc)`
+- [ ] A posição de cada elo é intencional: custo **acima** do `FunctionInvokingChatClient`, telemetria de chat **abaixo** dele
 - [ ] Middleware que chama serviços externos tem timeout configurado
 
 ---
@@ -201,7 +233,9 @@ Precisa de middleware no agent?
 - `ai-agents-setup` — pacotes, DI, quick start
 - `ai-agents-production` — panorama completo: observability, A2A, MCP, caching, middleware-as-one-of-many-concerns
 - `ai-agents-providers-model-registry` — `_modelRegistry.GetChatClient(alias)`, provider-agnostic pattern
+- `ai-agents-observability-patterns` — dono canônico de spans, fontes e duplicação
+- Reference implementation da ordem do pipeline (compila e é testada contra o pin): `templates/dotnet/ai-kit/src/Morph.AiKit/Agents/AgentFactory.cs` + `Middleware/UsageCostMiddleware.cs`
 
 ---
 
-*MORPH-SPEC by Polymorphism Tech — ai-agents/middleware-patterns.md v1.0 (2026-05-19)*
+*MORPH-SPEC by Polymorphism Tech — ai-agents/middleware-patterns.md v2.0 (2026-09-08)*