@polymorphism-tech/morph-spec 8.0.0 → 8.1.1

package/framework/standards/ai-agents/providers/model-registry.md

@@ -1,158 +1,158 @@
-# Model Registry — Provider-agnostic agent configuration
-
-> **Scope:** stacks=["dotnet"]
-> **Layer:** 0 (always-load via persona maf-expert)
-> **Keywords:** model registry, provider agnostic, model alias, IChatClient factory, multi-model, model selection, model config
-> **Read by Claude in:** plan (cita este standard quando feature menciona >1 modelo ou multi-provider) + implement (copia o template ModelRegistry.cs e gera config no projeto)
-
-**Verified against:** MAF 1.0 GA + tier list research (2026-05-18). Last-verified: 2026-05-19.
-
----
-
-## Pattern
-
-The project consuming morph-spec maintains a **single JSON file** mapping aliases (`text-default`, `vision`, `reasoning`, etc.) to `{ provider, model, options }`. Agents reference aliases — never hardcoded model strings. Switching provider or model is a one-file change.
-
-```
-Standard (this file, in framework) — explains the pattern + canonical schema
-        │ Claude reads + copies template
-        ▼
-Project (consumer) — config/model-registry.json + src/.../ModelRegistry.cs
-```
-
----
-
-## Schema (canonical)
-
-```jsonc
-// config/model-registry.json — IN THE PROJECT (not in framework)
-{
-  "$schema": "./model-registry.schema.json",
-  "version": "1.0",
-  "defaultAlias": "text-default",
-  "aliases": {
-    "text-default":  { "provider": "openai",    "model": "gpt-4o-mini",             "options": { "temperature": 0.7 } },
-    "text-heavy":    { "provider": "openai",    "model": "gpt-4o",                  "options": { "temperature": 0.5 } },
-    "reasoning":     { "provider": "openai",    "model": "o3-mini",                 "options": { "reasoningEffort": "medium" } },
-    "long-form":     { "provider": "anthropic", "model": "claude-sonnet-4-6",       "options": {} },
-    "vision":        { "provider": "google",    "model": "gemini-2.5-flash",        "options": {} },
-    "embeddings":    { "provider": "openai",    "model": "text-embedding-3-small",  "options": { "dimensions": 1536 } },
-    "transcription": { "provider": "openai",    "model": "whisper-1",               "options": {} },
-    "local-dev":     { "provider": "ollama",    "model": "llama3.2:3b",             "options": { "endpoint": "http://localhost:11434/v1" } }
-  },
-  "fallback": {
-    "text-default": "anthropic/claude-haiku-4-5",
-    "text-heavy":   "anthropic/claude-sonnet-4-6"
-  }
-}
-```
-
-> The aliases above are an **example**. Each project defines its own — provider choices vary per feature.
-
-**Field semantics:**
-- `provider`: SDK family — one of `openai`, `google`, `anthropic`, `ollama` (first-class). `azure-openai` is supported as an opt-in branch (see §providers).
-- `model`: model id for that provider.
-- `options`: provider-specific extras (temperature, reasoning effort, `endpoint` for Ollama, etc.).
-- `fallback`: when the primary provider fails (rate limit, outage), switch to this alias. Format `provider/model`.
-
----
-
-## Providers (first-class)
-
-> **This section is the single source of truth for provider SDKs.** Provider SDKs change names/versions often — keep this section verified with a date; templates stay stable.
-
-| Provider | `provider` value | NuGet SDK (LAST-VERIFIED 2026-05-19) | Notes |
-|----------|------------------|--------------------------------------|-------|
-| **OpenAI** | `openai` | `OpenAI` 2.* | `new ChatClient(model, apiKey).AsIChatClient()` |
-| **Ollama** | `ollama` | `OpenAI` 2.* (OpenAI-compatible endpoint) | Same `ChatClient` with custom `Endpoint` + dummy key |
-| **Google Gemini** | `google` | Confirm current SDK on NuGet before use | Adapt provider client to `IChatClient` |
-| **Anthropic Claude** | `anthropic` | Confirm current SDK on NuGet before use | Adapt provider client to `IChatClient` |
-| **Azure OpenAI** (opt-in, not default) | `azure-openai` | `Azure.AI.OpenAI` 2.* + `Azure.Identity` | Add only when a client requires data residency |
-
-**Adding a provider branch:** the `ModelRegistry.cs` template implements `openai` + `ollama`. To add `google`, `anthropic`, or `azure-openai`:
-1. Confirm the current NuGet SDK — community SDKs evolve; check NuGet/context7 before coding.
-2. Add a `case "<provider>":` branch in `ModelRegistry.GetChatClient`'s switch, following the `openai`/`ollama` pattern.
-3. Add the SDK `PackageReference` to the project's `.csproj`.
-4. The branch returns an `IChatClient`. If the SDK doesn't expose `IChatClient` natively, wrap it with an adapter.
-
-**Direct models only:** never use a hosted agent service. Every provider above is reached as a direct model.
-
----
-
-## Implementation pattern
-
-```csharp
-// WRONG — hardcoded model + provider
-var agent = new ChatClient("gpt-4o-mini", apiKey)
-    .AsIChatClient()
-    .AsAIAgent(instructions: prompt);
-
-// RIGHT — alias-based, provider-agnostic
-var agent = _modelRegistry.GetChatClient("text-default")
-    .AsAIAgent(instructions: prompt);
-```
-
-The `ModelRegistry` class in the project owns the mapping. See template `templates/code/dotnet/ai-agents/ModelRegistry.cs.template`.
-
----
-
-## How Claude implements this in a project
-
-When a task says "register the X agent" and the project has >1 model or >1 provider, Claude:
-
-1. Read this standard.
-2. Copy `templates/code/dotnet/ai-agents/ModelRegistry.cs.template` to `src/.../ModelRegistry.cs` in the project. Substitute placeholders.
-3. Copy `templates/code/dotnet/ai-agents/model-registry.json.template` to `config/model-registry.json`. Adjust aliases to project needs.
-4. Wire `ModelRegistry` into DI (see `AgentBootstrap.cs.template`).
-5. Future agents reference `_modelRegistry.GetChatClient(alias)`.
-
----
-
-## Recommended aliases & models (orientativo — maio/2026)
-
-> Tabela orientativa. Actual values live in the project's `model-registry.json`. Models evolve fast.
-
-| Alias | Provider sugerido | Modelo (maio/2026) | Use case |
-|-------|-------------------|--------------------|----------|
-| `text-default` | openai | gpt-4o-mini | Geração padrão de texto |
-| `text-heavy` | openai / anthropic | gpt-4o / claude-sonnet-4-6 | Análise complexa |
-| `reasoning` | openai | o3-mini | Decisões, planejamento, math |
-| `long-form` | anthropic | claude-sonnet-4-6 | Escrita longa, análise de documento |
-| `vision` | google / openai | gemini-2.5-flash / gpt-4o | Image → Text |
-| `embeddings` | openai | text-embedding-3-small | RAG, similarity |
-| `transcription` | openai | whisper-1 | Audio → Text |
-| `local-dev` | ollama | llama3.2:3b | Dev local, sem custo |
-
----
-
-## Anti-patterns
-
-| Anti-pattern | Why | Right way |
-|--------------|-----|-----------|
-| Hardcode `"gpt-4o-mini"` in agent code | Switching model = grep + replace | Use `_modelRegistry.GetChatClient("text-default")` |
-| Put `model-registry.json` in `.morph/` | `.morph/framework` is framework-only; `.morph/config/config.json` is reserved for morph-spec metadata | Put it in `config/` of the project |
-| Different `ModelRegistry` class per agent | Defeats the purpose | One class per project, singleton in DI |
-| Use a hosted agent service to "simplify" | Hosted lags 6-9 months, removes control | Always direct models |
-| Mix providers without a `fallback` block | Hard to diagnose outages | Declare `fallback` in `model-registry.json` |
-
----
-
-## Checklist (verifiable by morph-eval)
-
-- [ ] Project has `config/model-registry.json` (or declared equivalent).
-- [ ] Project has a `ModelRegistry` class registered as singleton in DI.
-- [ ] No agent code has hardcoded model strings — `grep -rE 'gpt-[0-9]|claude-|gemini-|whisper-' src/` matches only `ModelRegistry.cs`.
-- [ ] Aliases used in agent code exist in `model-registry.json`.
-
----
-
-## References
-
-- `ai-agents-setup` — provider SDKs
-- Template: `templates/code/dotnet/ai-agents/ModelRegistry.cs.template`
-- Template: `templates/code/dotnet/ai-agents/model-registry.json.template`
-- Template: `templates/code/dotnet/ai-agents/AgentBootstrap.cs.template`
-
----
-
-*MORPH-SPEC by Polymorphism Tech — ai-agents/providers/model-registry.md v1.0 (2026-05-19)*
+# Model Registry — Provider-agnostic agent configuration
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 0 (always-load via persona maf-expert)
+> **Keywords:** model registry, provider agnostic, model alias, IChatClient factory, multi-model, model selection, model config
+> **Read by Claude in:** plan (cita este standard quando feature menciona >1 modelo ou multi-provider) + implement (copia o template ModelRegistry.cs e gera config no projeto)
+
+**Verified against:** MAF 1.0 GA + tier list research (2026-05-18). Last-verified: 2026-05-19.
+
+---
+
+## Pattern
+
+The project consuming morph-spec maintains a **single JSON file** mapping aliases (`text-default`, `vision`, `reasoning`, etc.) to `{ provider, model, options }`. Agents reference aliases — never hardcoded model strings. Switching provider or model is a one-file change.
+
+```
+Standard (this file, in framework) — explains the pattern + canonical schema
+        │ Claude reads + copies template
+        ▼
+Project (consumer) — config/model-registry.json + src/.../ModelRegistry.cs
+```
+
+---
+
+## Schema (canonical)
+
+```jsonc
+// config/model-registry.json — IN THE PROJECT (not in framework)
+{
+  "$schema": "./model-registry.schema.json",
+  "version": "1.0",
+  "defaultAlias": "text-default",
+  "aliases": {
+    "text-default":  { "provider": "openai",    "model": "gpt-4o-mini",             "options": { "temperature": 0.7 } },
+    "text-heavy":    { "provider": "openai",    "model": "gpt-4o",                  "options": { "temperature": 0.5 } },
+    "reasoning":     { "provider": "openai",    "model": "o3-mini",                 "options": { "reasoningEffort": "medium" } },
+    "long-form":     { "provider": "anthropic", "model": "claude-sonnet-4-6",       "options": {} },
+    "vision":        { "provider": "google",    "model": "gemini-2.5-flash",        "options": {} },
+    "embeddings":    { "provider": "openai",    "model": "text-embedding-3-small",  "options": { "dimensions": 1536 } },
+    "transcription": { "provider": "openai",    "model": "whisper-1",               "options": {} },
+    "local-dev":     { "provider": "ollama",    "model": "llama3.2:3b",             "options": { "endpoint": "http://localhost:11434/v1" } }
+  },
+  "fallback": {
+    "text-default": "anthropic/claude-haiku-4-5",
+    "text-heavy":   "anthropic/claude-sonnet-4-6"
+  }
+}
+```
+
+> The aliases above are an **example**. Each project defines its own — provider choices vary per feature.
+
+**Field semantics:**
+- `provider`: SDK family — one of `openai`, `google`, `anthropic`, `ollama` (first-class). `azure-openai` is supported as an opt-in branch (see §providers).
+- `model`: model id for that provider.
+- `options`: provider-specific extras (temperature, reasoning effort, `endpoint` for Ollama, etc.).
+- `fallback`: when the primary provider fails (rate limit, outage), switch to this alias. Format `provider/model`.
+
+---
+
+## Providers (first-class)
+
+> **This section is the single source of truth for provider SDKs.** Provider SDKs change names/versions often — keep this section verified with a date; templates stay stable.
+
+| Provider | `provider` value | NuGet SDK (LAST-VERIFIED 2026-05-19) | Notes |
+|----------|------------------|--------------------------------------|-------|
+| **OpenAI** | `openai` | `OpenAI` 2.* | `new ChatClient(model, apiKey).AsIChatClient()` |
+| **Ollama** | `ollama` | `OpenAI` 2.* (OpenAI-compatible endpoint) | Same `ChatClient` with custom `Endpoint` + dummy key |
+| **Google Gemini** | `google` | Confirm current SDK on NuGet before use | Adapt provider client to `IChatClient` |
+| **Anthropic Claude** | `anthropic` | Confirm current SDK on NuGet before use | Adapt provider client to `IChatClient` |
+| **Azure OpenAI** (opt-in, not default) | `azure-openai` | `Azure.AI.OpenAI` 2.* + `Azure.Identity` | Add only when a client requires data residency |
+
+**Adding a provider branch:** the `ModelRegistry.cs` template implements `openai` + `ollama`. To add `google`, `anthropic`, or `azure-openai`:
+1. Confirm the current NuGet SDK — community SDKs evolve; check NuGet/context7 before coding.
+2. Add a `case "<provider>":` branch in `ModelRegistry.GetChatClient`'s switch, following the `openai`/`ollama` pattern.
+3. Add the SDK `PackageReference` to the project's `.csproj`.
+4. The branch returns an `IChatClient`. If the SDK doesn't expose `IChatClient` natively, wrap it with an adapter.
+
+**Direct models only:** never use a hosted agent service. Every provider above is reached as a direct model.
+
+---
+
+## Implementation pattern
+
+```csharp
+// WRONG — hardcoded model + provider
+var agent = new ChatClient("gpt-4o-mini", apiKey)
+    .AsIChatClient()
+    .AsAIAgent(instructions: prompt);
+
+// RIGHT — alias-based, provider-agnostic
+var agent = _modelRegistry.GetChatClient("text-default")
+    .AsAIAgent(instructions: prompt);
+```
+
+The `ModelRegistry` class in the project owns the mapping. See template `templates/code/dotnet/ai-agents/ModelRegistry.cs.template`.
+
+---
+
+## How Claude implements this in a project
+
+When a task says "register the X agent" and the project has >1 model or >1 provider, Claude:
+
+1. Read this standard.
+2. Copy `templates/code/dotnet/ai-agents/ModelRegistry.cs.template` to `src/.../ModelRegistry.cs` in the project. Substitute placeholders.
+3. Copy `templates/code/dotnet/ai-agents/model-registry.json.template` to `config/model-registry.json`. Adjust aliases to project needs.
+4. Wire `ModelRegistry` into DI (see `AgentBootstrap.cs.template`).
+5. Future agents reference `_modelRegistry.GetChatClient(alias)`.
+
+---
+
+## Recommended aliases & models (orientativo — maio/2026)
+
+> Tabela orientativa. Actual values live in the project's `model-registry.json`. Models evolve fast.
+
+| Alias | Provider sugerido | Modelo (maio/2026) | Use case |
+|-------|-------------------|--------------------|----------|
+| `text-default` | openai | gpt-4o-mini | Geração padrão de texto |
+| `text-heavy` | openai / anthropic | gpt-4o / claude-sonnet-4-6 | Análise complexa |
+| `reasoning` | openai | o3-mini | Decisões, planejamento, math |
+| `long-form` | anthropic | claude-sonnet-4-6 | Escrita longa, análise de documento |
+| `vision` | google / openai | gemini-2.5-flash / gpt-4o | Image → Text |
+| `embeddings` | openai | text-embedding-3-small | RAG, similarity |
+| `transcription` | openai | whisper-1 | Audio → Text |
+| `local-dev` | ollama | llama3.2:3b | Dev local, sem custo |
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Why | Right way |
+|--------------|-----|-----------|
+| Hardcode `"gpt-4o-mini"` in agent code | Switching model = grep + replace | Use `_modelRegistry.GetChatClient("text-default")` |
+| Put `model-registry.json` in `.morph/` | `.morph/framework` is framework-only; `.morph/config/config.json` is reserved for morph-spec metadata | Put it in `config/` of the project |
+| Different `ModelRegistry` class per agent | Defeats the purpose | One class per project, singleton in DI |
+| Use a hosted agent service to "simplify" | Hosted lags 6-9 months, removes control | Always direct models |
+| Mix providers without a `fallback` block | Hard to diagnose outages | Declare `fallback` in `model-registry.json` |
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] Project has `config/model-registry.json` (or declared equivalent).
+- [ ] Project has a `ModelRegistry` class registered as singleton in DI.
+- [ ] No agent code has hardcoded model strings — `grep -rE 'gpt-[0-9]|claude-|gemini-|whisper-' src/` matches only `ModelRegistry.cs`.
+- [ ] Aliases used in agent code exist in `model-registry.json`.
+
+---
+
+## References
+
+- `ai-agents-setup` — provider SDKs
+- Template: `templates/code/dotnet/ai-agents/ModelRegistry.cs.template`
+- Template: `templates/code/dotnet/ai-agents/model-registry.json.template`
+- Template: `templates/code/dotnet/ai-agents/AgentBootstrap.cs.template`
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/providers/model-registry.md v1.0 (2026-05-19)*

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

@@ -1,135 +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)*
+# 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)*