@polymorphism-tech/morph-spec 7.0.0 → 7.1.0

package/framework/standards/ai-agents/service-tier-flex.md

@@ -0,0 +1,135 @@
+# Service Tier Flex — Cost-optimized tier for async work
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 2 (on-keyword)
+> **Keywords:** service tier, flex tier, cost optimization, async tier, priority tier
+> **Read by Claude in:** implement
+
+**Verified against:** MAF 1.0 GA + OpenAI .NET SDK 2.* (campo `service_tier` confirmado pela REST API; nome da propriedade C# marcado `// VERIFY:` — ver seção A API). Last-verified: 2026-05-19.
+
+---
+
+## Quando usar tier flex
+
+Use o service tier **flex** quando o agente roda em background, sem usuário aguardando resposta:
+
+- Relatório mensal gerado overnight (briefing, sumário financeiro, newsletter)
+- Job de enriquecimento de dados disparado por evento (upload de arquivo, fim de período)
+- Análise on-demand que pode demorar segundos a mais sem impacto na UX
+- Qualquer completion dentro de um Worker Service / Hangfire job
+
+**Por que usar:** tier flex troca velocidade de resposta por **custo menor**. A OpenAI processa requests flex com menor prioridade — SLA mais relaxado, desconto de custo.
+
+> Regra: se o resultado vai para um banco de dados ou fila (não direto ao usuário), use flex.
+
+---
+
+## A API
+
+> **AVISO:** service tier é **OpenAI-specific** — não é exposto no `Microsoft.Extensions.AI.ChatOptions`.
+> Para setar service tier, use o `ChatClient` direto (obtido do Model Registry ou da configuração).
+
+> ### ⚠️ Status de verificação da API .NET
+>
+> **Confirmado pela REST API da OpenAI:** o campo é `service_tier`, com valores `"auto"`,
+> `"default"` e `"flex"`.
+>
+> **A confirmar contra o pacote `OpenAI` 2.\* instalado** (marcado `// VERIFY:` no código):
+> o nome exato da propriedade C# em `ChatCompletionOptions` e se os valores são `string`
+> constants ou membros de um enum (ex.: `ChatServiceTier.Flex`). O context7 não retornou a
+> superfície de `ChatCompletionOptions` para batch/tier — confirme no IntelliSense antes de codar.
+
+---
+
+## Exemplo C#
+
+```csharp
+using OpenAI;
+using OpenAI.Chat;
+using System.ClientModel;
+using Microsoft.Agents.AI;
+using Microsoft.Extensions.AI;
+
+// ── Opção A: usando ChatClient direto (para um job async simples) ──
+var apiKey = configuration["OpenAI:ApiKey"]!;
+var model  = configuration["OpenAI:Model"] ?? "gpt-4o-mini";
+
+ChatClient chatClient = new(model, new ApiKeyCredential(apiKey));
+
+ChatCompletionOptions flexOptions = new()
+{
+    // VERIFY nome da propriedade e tipo do valor — string "flex" ou enum (ChatServiceTier.Flex).
+    // Ver "Status de verificação da API .NET" acima.
+    ServiceTier = "flex",
+};
+
+ChatCompletion result = await chatClient.CompleteChatAsync(
+    messages: [new UserChatMessage(prompt)],
+    options: flexOptions);
+
+string responseText = result.Content[0].Text;
+
+// ── Opção B: dentro de um AIAgent MAF ──
+// O agente MAF usa o IChatClient abstrato — ServiceTier (OpenAI-specific) não é exposto
+// pelo Microsoft.Extensions.AI.ChatOptions, então não passa direto pelo AgentRunOptions.
+// Para flex tier num agente, injete-o num middleware de IChatClient que monta
+// ChatCompletionOptions com ServiceTier (ver ai-agents-middleware-patterns).
+// Recomendação: para jobs async simples que precisam de flex tier, prefira a Opção A
+// (ChatClient direto) — é o caminho confirmado e sem indireção.
+
+// Exemplo Worker Service — dispara o job async e não bloqueia o caller:
+// services.AddHostedService<MonthlyReportWorker>();
+// MonthlyReportWorker usa chatClient com flexOptions para cada completion.
+```
+
+> Para jobs que rodam no contexto de um MAF agent mas precisam de flex tier:
+> o agent pode ser construído sobre um `IChatClient` wrappado em middleware que injeta
+> `ServiceTier = "flex"` via `ChatCompletionOptions` — veja `ai-agents-middleware-patterns`.
+
+---
+
+## Decision
+
+| Cenário | Service tier recomendado |
+|---------|--------------------------|
+| Chat com usuário aguardando na tela | `default` (ou `auto`) |
+| Job async — relatório, enriquecimento, briefing | `flex` |
+| Job de alta prioridade com SLA apertado | `priority` (disponibilidade depende do plano OpenAI da conta) |
+| Batch API (24 h) | Não se aplica — Batch tem custo próprio |
+
+> `auto` (padrão da API): OpenAI decide o tier baseado na carga. Use `flex` explícito
+> quando você quer garantir o menor custo para trabalho assíncrono.
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Problema |
+|-------------|----------|
+| Usar `flex` em completion interativa | Latência imprevisível — usuário percebe lentidão |
+| Usar `priority` (ou `default`) em batch noturno | Paga mais sem necessidade |
+| Espalhar `ServiceTier = "flex"` por vários handlers | Usar middleware de ChatOptions para centralizar |
+| Combinar flex tier com Batch API | São mecanismos distintos; não se somam |
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] Tier flex usado somente em jobs assíncronos (Worker Service / Hangfire), nunca em handlers de request HTTP síncrono
+- [ ] `ServiceTier` confirmado como string `"flex"` ou enum correto na versão do SDK instalada no projeto
+- [ ] Jobs com flex tier não têm SLA de latência definido no contrato com o usuário final
+- [ ] Se o agente usa `IChatClient` abstrato, o `ServiceTier` foi validado que é passado corretamente
+
+---
+
+## References
+
+- `ai-agents-setup` — packages e configuração do cliente OpenAI
+- `ai-agents-batching` — alternativa de custo para volume alto de prompts independentes
+- `ai-agents-middleware-patterns` (Onda 2) — middleware para injetar `ChatOptions` globalmente
+- `ai-agents-providers-model-registry` — configuração provider-agnostic
+- OpenAI Service Tiers: https://platform.openai.com/docs/guides/service-tiers
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/service-tier-flex.md v1.0 (2026-05-19)*