@polymorphism-tech/morph-spec 8.33.0 → 8.35.0

package/framework/standards/ai-agents/llm-runtime-defaults.md

@@ -0,0 +1,226 @@
+# LLM Runtime Defaults — timeout, retry, strict, amostragem e o pin do SDK
+
+> **Scope:** stacks=["dotnet"]
+> **Layer:** 1 (on-keyword)
+> **Keywords:** llm defaults, runtime defaults, timeout llm, retry llm, strict json schema, temperature reasoning, capability por alias, network timeout, pin de sdk
+> **Read by Claude in:** implement (ao configurar cliente, alias ou opções de chamada) e troubleshoot (chamada pendurada, 400 recorrente, quebra binária)
+
+**Verified against:** Microsoft.Extensions.AI 10.9.0 + Microsoft.Agents.AI 1.20.0 + OpenAI 2.13.0 (ai-pin 2026-09-08); provado por `templates/dotnet/ai-kit/src/Morph.AiKit/Providers/ModelAlias.cs` e `.../Providers/ModelRegistry.cs` (alias, `api:`, e limite por alias com procedência obrigatória). A superfície do SDK citada aqui — `ChatOptions`, `ChatResponseFormatJson`, `ReasoningEffort`, `OpenAIClientOptions` — foi **medida por reflexão sobre as assemblies do pin** em 2026-09-08. O timeout é **provado por** `.../Agents/AgentSpecOptions.cs` e `.../Agents/AgentFactory.cs`, que o kit compila **por spec** (`TimeoutSeconds` vira um cliente de timeout no pipeline) — e **não** por alias: a allowlist de alias do registry não tem chave de timeout (medido). Os valores default do retry do `System.ClientModel` 1.15.0 são **verificação documental** — essa assembly está fora do conjunto que o probe carrega. Last-verified: 2026-09-08.
+
+---
+
+## Fronteira com o Model Registry
+
+`ai-agents-providers-model-registry` é **Layer 0** (sempre carregado) e continua dono do **schema**:
+o formato do documento, `defaultAlias`, o fallback e a tabela de providers. **Este** standard é dono
+dos **valores e dos botões de runtime**: timeout, retry, strict, amostragem, esforço de raciocínio e
+o pin de versão do SDK.
+
+Sem esta fronteira escrita, o par vira **duas verdades sobre o mesmo JSON** — e a segunda verdade é
+sempre a que alguém encontra primeiro.
+
+Complemento: `ai-agents-agent-spec` é dono da **forma** do agente e da regra "nulo = não envia";
+`ai-agents-cost-and-budget` é dono de `pricing`. Aqui não se repete nenhum dos três.
+
+---
+
+## Retry herdado
+
+**Não escreva um loop de retry sobre chamada de LLM.** A pilha do `System.ClientModel` — a base dos
+clientes gerados da OpenAI — já traz uma política de retry, e ela é aplicada por padrão.
+
+O que a assembly `System.ClientModel` 1.15.0 (a restaurada junto com o pin) carrega nos metadados,
+**medido por leitura de literal em 2026-09-08**: `ClientRetryPolicy`, `ClientPipelineOptions`,
+`RetryPolicy`, `MaxRetries`, `DefaultMaxRetries`, `DefaultInitialDelay`, `ShouldRetry`,
+`GetNextDelay`. Isto prova que os pontos de extensão existem e como se chamam.
+
+**Verificação documental** (fonte primária: o fonte de `ClientRetryPolicy` em
+`Azure/azure-sdk-for-net`, lido em 2026-09-08), e por isso escrita como valor a **conferir** antes de
+depender dela: 3 tentativas de retry, atraso inicial de 0,8 s, backoff exponencial na forma
+`(1 << (tryCount - 1)) * initialDelay`, e o cabeçalho de espera do servidor respeitado quando ele
+pede mais tempo do que o backoff calculado.
+
+**A regra:** herde. Se precisar de outro número, **substitua a política** (`RetryPolicy` nas opções
+do cliente), não empilhe um `for` por cima. Duas camadas de retry multiplicam: 3 × 3 = 9 chamadas
+pagas para um incidente que o operador vê como "uma".
+
+Prática de campo alinhada, com a razão escrita no próprio código: *"não adicionamos loop próprio"*.
+
+---
+
+## Timeout explícito
+
+**Retry sobre uma chamada que nunca expira é o pior dos dois mundos.** A política tenta de novo o
+que ainda não desistiu, e o incidente aparece como latência infinita em vez de erro.
+
+Dois fatos medidos por reflexão sobre as assemblies do pin, em 2026-09-08:
+
+1. **`Microsoft.Extensions.AI.ChatOptions` não tem propriedade de timeout.** As 20 propriedades
+   declaradas são de conteúdo da chamada (`Temperature`, `TopP`, `TopK`, `MaxOutputTokens`,
+   `ResponseFormat`, `Tools`, `ToolMode`, `Reasoning`, `Seed`, `StopSequences`, `Instructions`,
+   `ModelId`, `ConversationId`, `AdditionalProperties`, …). A abstração **não sabe expressar**
+   timeout — logo, ele não é um botão por chamada nesse nível.
+2. **`OpenAI.OpenAIClientOptions` (OpenAI 2.13.0) declara apenas** `Endpoint`, `OrganizationId`,
+   `ProjectId` e `UserAgentApplicationId`. O botão de timeout **não é dele**: ele vem da base,
+   `System.ClientModel.Primitives.ClientPipelineOptions`, cuja assembly carrega os nomes
+   `NetworkTimeout` e `get_NetworkTimeout` (medido por literal na mesma data). A declaração está
+   fora do conjunto de assemblies que o probe carrega, então este ponto é **documental**.
+
+**A regra, em três partes:**
+
+- **Configure o timeout explicitamente**, e escolha conscientemente a camada. O exemplar do kit o faz **por spec de agente** (`AgentSpecOptions.TimeoutSeconds` → um cliente de timeout no pipeline), porque a allowlist de alias do registry **não tem** chave de timeout — medido. Por alias exige abrir essa allowlist, o que é mudança de `.cs`. Alias
+  de raciocínio pesado e alias de resposta curta não têm o mesmo tempo aceitável.
+- **`CancellationToken` de turno não é timeout de chamada.** Ele cancela quando *alguém* desiste
+  (o usuário fechou a aba, o job foi abortado). Uma chamada pendurada sem ninguém para desistir
+  fica pendurada.
+- **Timeout curto sem retry é fragilidade; retry sem timeout é vazamento.** Os dois andam juntos.
+
+Medições que motivam a regra: um projeto do acervo tem **apenas** o `CancellationToken` do turno,
+sem nenhum timeout de chamada. Outro tem uma biblioteca de resiliência declarada no `.csproj`
+**sem aplicá-la à camada de IA**, e nenhum timeout de `HttpClient` nem handler de resiliência
+padrão registrado.
+
+> **Correção explícita de premissa.** A formulação "timeout é herdado do SDK, como o retry" é
+> **falsa** nas duas pontas medidas: o retry é herdado, o timeout precisa ser **decidido**. Herdar
+> o que não existe é como se descobre que uma chamada roda até o processo morrer.
+
+---
+
+## Strict JSON schema por alias
+
+O identificador **`StrictJsonSchema` não existe**. Medição, 2026-09-08: uma varredura por reflexão
+sobre as **14 assemblies** dos pacotes do pin e das pontes (`Microsoft.Agents.AI` e derivados,
+`Microsoft.Extensions.AI` e derivados, `OpenAI`, `Google.GenAI`, `ModelContextProtocol` e derivados,
+`Microsoft.Extensions.VectorData.Abstractions`) devolve **zero** tipos exportados cujo nome contenha
+`Strict`.
+
+E `Microsoft.Extensions.AI.ChatResponseFormatJson` declara exatamente três propriedades — `Schema`,
+`SchemaDescription`, `SchemaName` — e **nenhum campo `strict`**, também medido por reflexão. A
+abstração não sabe expressar strict.
+
+O mecanismo real é **uma chave em `ChatOptions.AdditionalProperties`**, lida pela ponte do provider,
+que transforma o schema antes de enviá-lo (proibir propriedades adicionais, converter schemas
+booleanos). Isso significa três coisas para o desenho:
+
+- **Strict é decisão por chamada / por alias**, porque é onde `ChatOptions` vive.
+- **Suporte a strict é capacidade do modelo**, e o registry já sabe o provider e o modelo de cada
+  alias. Logo o lugar do "este alias suporta strict" é o **alias**.
+- **Nunca uma flag global de processo.**
+
+### O anti-padrão, com o nome real do campo
+
+Medido em produção no acervo: um par `StrictJsonSchemaSupported` (propriedade de configuração) +
+`volatile bool _strictUnsupported` (campo estático de processo). Ao receber um `400` de qualquer
+chamada, o campo é ligado e **todas as chamadas seguintes do processo** passam a ser enviadas sem
+strict. A frase do próprio diagnóstico do projeto: *"um 400 em qualquer ponto degrada todas as
+chamadas seguintes"*.
+
+O efeito prático: um modelo local em desenvolvimento, que legitimamente não suporta strict, rebaixa
+as chamadas de **produção** do mesmo processo. Capacidade é do alias; degradação global é um bug
+disfarçado de resiliência.
+
+O kit compila a forma correta dessa ideia: limites conhecidos de um alias vivem num record de
+`Constraints` **por alias**, e um limite **sem procedência escrita é recusado na carga do
+registry** — para que ninguém consiga gravar um "todo mundo sabe que" sem dizer de onde tirou.
+
+---
+
+## Temperature e reasoning
+
+**Modelo de raciocínio e amostragem não se misturam.** A regra prática: `Temperature` só faz sentido
+em modelo sem raciocínio; em modelo de raciocínio o botão é o **esforço**.
+
+O que está **medido por reflexão** sobre `Microsoft.Extensions.AI.Abstractions` 10.9.0, em
+2026-09-08:
+
+- `ChatOptions.Temperature` (`float?`) e `ChatOptions.Reasoning` (`ReasoningOptions`) são
+  propriedades **distintas** e independentes.
+- `ReasoningOptions` declara `Effort` e `Output`.
+- `ReasoningEffort` é um **enum de primeira classe** com exatamente cinco valores:
+  `None = 0`, `Low = 1`, `Medium = 2`, `High = 3`, `ExtraHigh = 4`.
+
+Esforço de raciocínio, portanto, é **tipado** — não é string, e não precisa de convenção de projeto.
+
+A **medição de campo** que sustenta o limite prático (dois modelos de raciocínio que rejeitam
+`Temperature != 1` quando há tools na chamada) é de `ai-agents-providers-model-registry` — Layer 0,
+sempre carregado, e dono dela desde a re-verificação anterior. **Não é repetida aqui**: uma segunda
+cópia da mesma medição é a segunda verdade que a seção de fronteira acima existe para evitar. O que
+este standard acrescenta é onde o limite mora e o que ele governa.
+
+**Contra-evidência, e ela é instrutiva:** outro projeto do acervo **não configura parâmetro de
+amostragem nenhum** e roda no default do SDK. Não configurar é uma escolha válida, e mais honesta
+que configurar errado. A regra final é: **configure quando você mediu que precisa; caso contrário,
+não envie** (`ai-agents-agent-spec`, "nulo = não envia").
+
+Onde o limite mora: no **alias**, como `Constraints` com procedência — a mesma forma que o kit
+compila para `ToolCallingRequiresReasoningEffortNone` e `TemperatureUnsupported`. Um limite por
+alias é verificável antes da chamada; um limite espalhado em `if`s só é verificável depois do 400.
+
+---
+
+## Pin de SDK e compatibilidade binária
+
+**Faixa flutuante em SDK de IA custa dinheiro.** Não é uma preferência de estilo: é um incidente
+medido.
+
+O caso, do acervo: um projeto referenciava o SDK da OpenAI numa faixa `2.*`. O NuGet resolveu para
+uma versão menor mais nova, um membro de conteúdo de resposta **mudou de assinatura**, e a chamada
+estourou `MissingMethodException` **depois de a requisição já ter sido paga** — o dinheiro saiu, a
+resposta não chegou ao domínio. A correção foi pinar a versão exata, com oito linhas de comentário
+explicando por quê.
+
+**As três regras:**
+
+1. **Pin exato** (`[2.13.0]`, não `2.*`) para todo pacote de IA. Neste framework a fonte única é
+   `framework/ai-pin.json`, e nenhum standard escreve versão à mão.
+2. **A faixa e o pacote de ponte andam juntos.** `Microsoft.Extensions.AI.OpenAI` referencia uma
+   versão do `OpenAI`; carregar outra em runtime é uma quebra binária esperando um caminho de código
+   pouco exercitado.
+3. **Teste de compatibilidade binária como rede de segurança** — comparar a versão do assembly
+   carregado com a que a ponte referencia, e conferir a **assinatura** do membro que já quebrou uma
+   vez. A técnica está em `ai-agents-testing-ai`.
+
+---
+
+## Anti-patterns
+
+| Anti-pattern | Por quê é problema | Solução |
+|---|---|---|
+| Loop de retry próprio sobre a chamada de LLM | Multiplica com o retry do SDK: 3 × 3 = 9 chamadas pagas por incidente | Herde; para outro número, substitua a política |
+| Chamada de LLM sem timeout | Retry sobre o que nunca expira; o incidente vira latência infinita | Timeout explícito — por spec de agente (o exemplar do kit) ou por alias, se a allowlist foi aberta |
+| `CancellationToken` de turno usado como timeout | Só cancela quando alguém desiste; ninguém desiste de um job noturno | Timeout explícito, além do token |
+| Flag global de processo para strict | Um 400 em dev rebaixa produção no mesmo processo | Capacidade por alias, em `Constraints` com procedência |
+| `Temperature` em modelo de raciocínio | Erro do provider, ou pior: silenciosamente ignorado | Esforço tipado (`ReasoningEffort`) para raciocínio; amostragem só sem raciocínio |
+| Parâmetro de amostragem configurado "por garantia" | Envia valor que ninguém mediu, e some no default do provider | Nulo = não envia |
+| Faixa flutuante (`2.*`) em pacote de IA | Quebra binária depois da chamada paga | Pin exato, a partir de `framework/ai-pin.json` |
+| Limite de alias escrito como regra universal em C# | Vira folclore sem procedência, e ninguém sabe revogá-lo | Campo do alias, com procedência obrigatória |
+
+---
+
+## Checklist (verifiable by morph-eval)
+
+- [ ] Nenhum loop de retry escrito à mão em volta de uma chamada de LLM
+- [ ] Há timeout explícito (por spec de agente, como o exemplar do kit, ou por alias se a allowlist foi aberta), e ele **não** é o `CancellationToken` do turno
+- [ ] Nenhuma flag estática de processo governa strict ou qualquer outra capacidade
+- [ ] Capacidade e limite são campos do **alias**, com procedência escrita
+- [ ] Nenhuma ocorrência de um tipo chamado `StrictJsonSchema` (ele não existe em nenhum pacote do pin)
+- [ ] Esforço de raciocínio usa o enum `ReasoningEffort`, não string
+- [ ] `Temperature` não é enviada junto com esforço de raciocínio
+- [ ] Todo pacote de IA está pinado em versão exata, derivada de `framework/ai-pin.json`
+- [ ] Existe um teste de compatibilidade binária cobrindo o par SDK × ponte
+
+---
+
+## References
+
+- `ai-agents-providers-model-registry` — Layer 0: o **schema** do documento, `defaultAlias`, fallback
+  e a tabela de providers. Este standard não repete nada disso
+- `ai-agents-agent-spec` — a forma do agente e a regra "nulo = não envia"
+- `ai-agents-cost-and-budget` — `pricing` por alias, cálculo e teto de gasto
+- `ai-agents-testing-ai` — o teste de compatibilidade binária, e como exercitar opções sem rede
+- `ai-agents-structured-output` — o schema da saída, cujo strict este standard governa
+- `framework/ai-pin.json` — a fonte única das versões; nenhuma versão é digitada num standard
+
+---
+
+*MORPH-SPEC by Polymorphism Tech — ai-agents/llm-runtime-defaults.md v1.0 (2026-09-08)*