tempest-fastapi-sdk 0.331.0__tar.gz → 0.332.0__tar.gz

{tempest_fastapi_sdk-0.331.0 → tempest_fastapi_sdk-0.332.0}/CHANGELOG.md

@@ -7,6 +7,107 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.332.0] — 2026-10-27
+
+### Added
+
+- `API_DOCS_LOCALE` (`ServerSettings`, `en-US` por padrão ou `pt-BR`) e o
+  parâmetro `docs_locale=` nas factories de rota: o `summary` e a
+  `description` das operações, e a `description` dos parâmetros e respostas
+  declarados nelas, saem no idioma escolhido no `/docs`, no ReDoc e no
+  cliente gerado (#643). Cobertos: `make_auth_router` (as 33 rotas que
+  aparecem no schema), `make_sse_router` (e `UserAuthService.sse_router`, que
+  segue a variável), `make_push_router`, `make_web_push_router`,
+  `make_health_router`, `make_logs_router`, `make_tool_spec_router`,
+  `make_app_error_router`, `make_session_router`, `make_pdf_router` e
+  `make_voice_router`. Path, `operationId`, nome de campo, código de erro e
+  `title` de schema não mudam com o idioma, então o cliente gerado é o mesmo.
+  O documento em inglês sem a variável é idêntico byte a byte ao da 0.331.0
+  nos 11 routers, medido com todo grupo opcional de rota ligado. Língua fora do catálogo (`es-ES`, `pt-PT`) é recusada no
+  boot em vez de cair no inglês. O texto vive em
+  `tempest_fastapi_sdk.api.route_docs` (`RouteDocs`, `RouteDoc`,
+  `resolve_docs_locale`) e o guard `tests/test_route_docs_coverage_guard.py`
+  exige toda chave nas duas línguas, sem órfã. Chat, genai, agents,
+  modelops, reviews, vision, wallet e hostbridge seguem só em inglês.
+- `complete_structured(messages, schema, *, effort=None, cache_system=False,
+  max_tokens=None, config=None, **kwargs)` no `AnthropicGenerator` e no
+  `OpenAICompatGenerator`, devolvendo `StructuredCompletion`: a instância
+  validada (ou `None`), o texto, o `TokenUsage`, o `stop_reason` normalizado
+  (`end`, `max_tokens`, `refusal`, `tool_use`, `other`) com o valor original
+  em `provider_stop_reason`, e o erro de validação. Recusa, resposta cortada
+  e JSON fora do schema voltam no objeto **com o uso** — a chamada foi
+  cobrada —, em vez de virar exceção sem custo. Levantam só erro de
+  transporte/HTTP, `TypeError` por `output_config`/`response_format` passado
+  como keyword e `ValueError` por data URL de imagem que não é base64. O
+  parse só acontece depois de uma parada natural. `effort` vai
+  como `output_config.effort` na Anthropic e como `reasoning_effort` no
+  formato OpenAI (traduzido por `effort_values`, omitido com
+  `effort_field=None`); `cache_system=True` marca o `system` com
+  `cache_control` na Anthropic. Novos: `Effort`, `StopReason`,
+  `StructuredCompletionBackend`, `build_structured_completion`,
+  `ANTHROPIC_STOP_REASONS`, `OPENAI_FINISH_REASONS`.
+- `image_part(data, media_type)` e a tradução de partes `image_url`
+  (formato OpenAI) para o bloco `image` da Messages API
+  (`to_anthropic_image`): base64 por `data:` URL, ou `url`. Antes, o
+  `AnthropicGenerator` repassava a parte `image_url` como estava, num
+  formato que a Messages API não define.
+- `hosted_generator(model, *, api_key, provider=None, base_url=None, ...)`
+  e `resolve_provider(model)`: o provedor sai do prefixo do id
+  (`MODEL_PREFIXES`), com a configuração de cada um — OpenAI com
+  `max_completion_tokens` (`OPENAI_MAX_TOKENS_FIELD`), Gemini pelo endpoint
+  compatível com OpenAI (`DEFAULT_GOOGLE_OPENAI_URL`, `GOOGLE_EFFORT_VALUES`)
+  e DeepSeek com `json_object` e sem `reasoning_effort`. `provider=` fora
+  de `HOSTED_PROVIDERS` levanta `ValueError` em vez de cair no DeepSeek
+  (uma string lida de configuração não passa pela checagem do tipo).
+- `HostedGenAISettings`: `GOOGLE_API_KEY`, `GOOGLE_BASE_URL`,
+  `GOOGLE_MODEL`, `google_kwargs()` e `hosted_kwargs(model, *,
+  provider=None)`, que devolve os argumentos de `hosted_generator` com a
+  chave do provedor resolvido. `deepseek_kwargs()` passa a levar
+  `effort_field=None`, como o `hosted_generator`: o DeepSeek não documenta
+  `reasoning_effort`.
+- `TokenUsage.cache_write_tokens`: a parte da entrada gravada no cache
+  (`cache_creation_input_tokens` da Anthropic), somada no `+`.
+- `OpenAICompatGenerator(effort_field="reasoning_effort",
+  effort_values=None)`.
+
+Os testes novos rodam sobre `httpx.MockTransport`: fixam o request montado e
+a leitura da resposta documentada, não um provedor ao vivo.
+- `AUTH_SEND_EMAILS_IN_BACKGROUND` (`AuthSettings`, default `false`): as
+  rotas do `make_auth_router` mandam os e-mails de ativação, reset, troca e
+  verificação pelo `BackgroundTasks` da requisição (#644). A resposta não
+  espera o SMTP — medido com mailer de 1 s sobre uvicorn real: signup em
+  mais de 1 s no default e em menos de 0,5 s em background —, e o tempo do
+  `/password-reset/request` deixa de revelar se o endereço tem conta. Falha
+  de SMTP vira log em `ERROR` (só o domínio do destinatário), não `503`, e
+  não há rollback por falha de envio. Fora de uma requisição o envio
+  continua aguardado.
+- `AUTH_EMAIL_BRAND_NAME`, `AUTH_EMAIL_BRAND_COLOR`,
+  `AUTH_EMAIL_BRAND_LOGO_URL` e `AUTH_EMAIL_FOOTER_TEXT` (`AuthSettings`)
+  vestem os e-mails com a marca do projeto. Numa cor clara, o texto do botão
+  e o link escurecem sozinhos (luminância WCAG). Cor que não é `#rgb`/
+  `#rrggbb` e logo que não é URL absoluta `http(s)` derrubam o boot. O
+  contexto do template ganha `brand`.
+- `tempest_fastapi_sdk.utils.relative_luminance` e `is_light`, que o
+  `AdminTheme` passou a usar no lugar da cópia própria.
+
+### Changed
+
+- `MessageBroker.on`, `MessageBroker.register` e o `subscribe`/`Consumer`
+  ganharam `ack_policy` como parâmetro nomeado. Num `QueueSpec` com
+  dead-letter, `None` vira `REJECT_ON_ERROR` fixado no próprio assinante
+  (#642): o serviço não importa mais `faststream.AckPolicy` para a DLQ
+  valer, e um `ack_policy` no broker inteiro (ex.: `NACK_ON_ERROR`) não
+  desvia a falha da DLQ — medido contra RabbitMQ real. `ACK`, `ACK_FIRST` e
+  `NACK_ON_ERROR` num spec com dead-letter levantam `ValueError`, porque
+  nenhuma das três manda a falha para a DLQ. Consumidor sem dead-letter não
+  muda.
+- Os cinco e-mails de auth (ativação, reset, troca e verificação de e-mail,
+  aviso de e-mail alterado) ganharam visual novo sobre um layout comum,
+  `auth/templates/_email_layout.html` (#645): tabela com estilo inline,
+  cabeçalho com a marca, botão, link de reserva, nota de validade, rodapé,
+  preheader e `color-scheme` para modo escuro. O texto de cada e-mail foi
+  mantido. Template próprio com o mesmo nome continua vencendo o do SDK.
+
 ## [0.331.0] — 2026-10-26
 
 ### Added

{tempest_fastapi_sdk-0.331.0 → tempest_fastapi_sdk-0.332.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tempest-fastapi-sdk
-Version: 0.331.0
+Version: 0.332.0
 Summary: Shared FastAPI building blocks: base schemas, ORM model, async repository, exceptions, pagination and settings — the conventions used across Tempest projects.
 Project-URL: Homepage, https://github.com/mauriciobenjamin700/tempest-fastapi-sdk
 Project-URL: Repository, https://github.com/mauriciobenjamin700/tempest-fastapi-sdk
@@ -369,7 +369,7 @@ Feature-rich helpers pull in third-party dependencies that you only need when yo
 | `[genai-audio]` | `faster-whisper`, `coqui-tts`, `torch`, `torchaudio`, `torchcodec`, `transformers<5` | Self-hosted voice — `SpeechToText` (STT) + `TextToSpeech` (TTS) + `Language` presets (PT-BR/EN-US). The `transformers<5` cap is intentional (`coqui-tts` stops importing from transformers 5.1.0 on) and, through transformers 4.57.6, holds `huggingface-hub` below 1.0 (0.36.2), `tokenizers` at or below 0.23.0 (0.22.2) and, next to `[genai-image]`, `diffusers` at 0.39.0 — [details](https://mauriciobenjamin700.github.io/tempest-fastapi-sdk/en/installation/#genai-audio-transformers-bound) |
 | `[genai-diarization]` | `sherpa-onnx` | Speaker diarization on ONNX Runtime (no PyTorch) — `SpeakerDiarizer`, `ConversationTranscriber`, `ensure_models` |
 | `[faces]` | `onnxruntime`, `pillow`, `numpy` | Face detection and recognition on ONNX Runtime (no opencv, no torch, no system libraries) — `FaceRecognizer`, `compare_faces`, 16 MB default pack |
-| `[genai-hosted]` | `httpx` | Hosted providers — `AnthropicGenerator` (Messages API) and `OpenAICompatGenerator` (OpenAI, DeepSeek) behind the same `TextBackend` / `ToolCallingBackend` / `StructuredTextBackend` protocols as Ollama, `OpenAICompatEmbedder`, `HostedGenAISettings`, typed `HostedAPIError` family; no vendor SDK |
+| `[genai-hosted]` | `httpx` | Hosted providers — `AnthropicGenerator` (Messages API) and `OpenAICompatGenerator` (OpenAI, DeepSeek, Gemini) behind the same `TextBackend` / `ToolCallingBackend` / `StructuredTextBackend` protocols as Ollama, `complete_structured` → `StructuredCompletion` (output, usage and stop reason on every outcome; images via `image_part`), `hosted_generator` (provider from the model id), `OpenAICompatEmbedder`, `HostedGenAISettings` (+ `hosted_kwargs()`), typed `HostedAPIError` family; no vendor SDK |
 | `[genai-ollama]` | `httpx` | Ollama backend — `OllamaGenerator` / `OllamaEmbedder` run text + embeddings against a local Ollama daemon instead of loading torch weights; drop into `make_genai_router` / `Retriever` |
 | `[genai-chroma]` | `chromadb` | ChromaDB store — `ChromaVectorStore` (a `VectorStore`) + `ChatMemory` (recency-aware per-user long-term chat memory) |
 | `[genai-onnx]` | `onnxruntime`, `tokenizers` | Torch-free embeddings — `OnnxEmbedder` runs an ONNX-exported sentence model on CPU (attention-mask mean pooling), a `SupportsEmbed` drop-in for `Retriever` |
@@ -2680,7 +2680,7 @@ Each mixin owns its own env-var prefix — pick only the ones the service needs:
 | Mixin | Env vars |
 | --- | --- |
 | `EnvironmentSettings` | `ENV` (`development` / `test` / `production`) |
-| `ServerSettings` | `SERVER_HOST`, `SERVER_PORT`, `SERVER_RELOAD`, `SERVER_DEBUG`, `TRUSTED_IP_HEADER` |
+| `ServerSettings` | `SERVER_HOST`, `SERVER_PORT`, `SERVER_RELOAD`, `SERVER_DEBUG`, `TRUSTED_IP_HEADER`, `SERVER_PUBLIC_SCHEME`, `API_DOCS_LOCALE` |
 | `LogSettings` | `LOG_LEVEL`, `LOG_JSON`, `LOG_DIR` |
 | `DatabaseSettings` | `DATABASE_URL`, `DATABASE_ECHO`, `DATABASE_POOL_SIZE`, `DATABASE_MAX_OVERFLOW`, `DATABASE_POOL_RECYCLE` |
 | `RedisSettings` | `REDIS_URL`, `REDIS_DECODE_RESPONSES` |

{tempest_fastapi_sdk-0.331.0 → tempest_fastapi_sdk-0.332.0}/README.md

@@ -147,7 +147,7 @@ Feature-rich helpers pull in third-party dependencies that you only need when yo
 | `[genai-audio]` | `faster-whisper`, `coqui-tts`, `torch`, `torchaudio`, `torchcodec`, `transformers<5` | Self-hosted voice — `SpeechToText` (STT) + `TextToSpeech` (TTS) + `Language` presets (PT-BR/EN-US). The `transformers<5` cap is intentional (`coqui-tts` stops importing from transformers 5.1.0 on) and, through transformers 4.57.6, holds `huggingface-hub` below 1.0 (0.36.2), `tokenizers` at or below 0.23.0 (0.22.2) and, next to `[genai-image]`, `diffusers` at 0.39.0 — [details](https://mauriciobenjamin700.github.io/tempest-fastapi-sdk/en/installation/#genai-audio-transformers-bound) |
 | `[genai-diarization]` | `sherpa-onnx` | Speaker diarization on ONNX Runtime (no PyTorch) — `SpeakerDiarizer`, `ConversationTranscriber`, `ensure_models` |
 | `[faces]` | `onnxruntime`, `pillow`, `numpy` | Face detection and recognition on ONNX Runtime (no opencv, no torch, no system libraries) — `FaceRecognizer`, `compare_faces`, 16 MB default pack |
-| `[genai-hosted]` | `httpx` | Hosted providers — `AnthropicGenerator` (Messages API) and `OpenAICompatGenerator` (OpenAI, DeepSeek) behind the same `TextBackend` / `ToolCallingBackend` / `StructuredTextBackend` protocols as Ollama, `OpenAICompatEmbedder`, `HostedGenAISettings`, typed `HostedAPIError` family; no vendor SDK |
+| `[genai-hosted]` | `httpx` | Hosted providers — `AnthropicGenerator` (Messages API) and `OpenAICompatGenerator` (OpenAI, DeepSeek, Gemini) behind the same `TextBackend` / `ToolCallingBackend` / `StructuredTextBackend` protocols as Ollama, `complete_structured` → `StructuredCompletion` (output, usage and stop reason on every outcome; images via `image_part`), `hosted_generator` (provider from the model id), `OpenAICompatEmbedder`, `HostedGenAISettings` (+ `hosted_kwargs()`), typed `HostedAPIError` family; no vendor SDK |
 | `[genai-ollama]` | `httpx` | Ollama backend — `OllamaGenerator` / `OllamaEmbedder` run text + embeddings against a local Ollama daemon instead of loading torch weights; drop into `make_genai_router` / `Retriever` |
 | `[genai-chroma]` | `chromadb` | ChromaDB store — `ChromaVectorStore` (a `VectorStore`) + `ChatMemory` (recency-aware per-user long-term chat memory) |
 | `[genai-onnx]` | `onnxruntime`, `tokenizers` | Torch-free embeddings — `OnnxEmbedder` runs an ONNX-exported sentence model on CPU (attention-mask mean pooling), a `SupportsEmbed` drop-in for `Retriever` |
@@ -2458,7 +2458,7 @@ Each mixin owns its own env-var prefix — pick only the ones the service needs:
 | Mixin | Env vars |
 | --- | --- |
 | `EnvironmentSettings` | `ENV` (`development` / `test` / `production`) |
-| `ServerSettings` | `SERVER_HOST`, `SERVER_PORT`, `SERVER_RELOAD`, `SERVER_DEBUG`, `TRUSTED_IP_HEADER` |
+| `ServerSettings` | `SERVER_HOST`, `SERVER_PORT`, `SERVER_RELOAD`, `SERVER_DEBUG`, `TRUSTED_IP_HEADER`, `SERVER_PUBLIC_SCHEME`, `API_DOCS_LOCALE` |
 | `LogSettings` | `LOG_LEVEL`, `LOG_JSON`, `LOG_DIR` |
 | `DatabaseSettings` | `DATABASE_URL`, `DATABASE_ECHO`, `DATABASE_POOL_SIZE`, `DATABASE_MAX_OVERFLOW`, `DATABASE_POOL_RECYCLE` |
 | `RedisSettings` | `REDIS_URL`, `REDIS_DECODE_RESPONSES` |

{tempest_fastapi_sdk-0.331.0 → tempest_fastapi_sdk-0.332.0}/SHIPPED.md

@@ -854,6 +854,19 @@ The SDK currently covers (Sep 2025+, post-v0.31.x):
   Anthropic/DeepSeek fica fora: nenhum dos dois documenta endpoint. O
   "OpenAI-compatible client deliberately skipped" acima foi revertido por
   esta entrega. Receita: `docs/recipes/genai-hosted.md`.
+- **Resultado estruturado completo e provedor pelo id do modelo
+  (v0.332.0 (2026-10-27), extra `[genai-hosted]`)** — `complete_structured` nos dois
+  geradores hospedados devolve `StructuredCompletion` (saída, texto,
+  `TokenUsage`, `stop_reason` normalizado e o original, erro de validação)
+  sem levantar por recusa, `max_tokens` ou JSON inválido; `effort`,
+  `cache_system`, `max_tokens` por chamada. `image_part` + tradução de
+  `image_url` para o bloco `image` da Messages API. `TokenUsage` ganha
+  `cache_write_tokens`. `hosted_generator` / `resolve_provider`
+  (`MODEL_PREFIXES`) montam Anthropic, OpenAI, Gemini (endpoint compatível
+  com OpenAI, `GOOGLE_EFFORT_VALUES`) ou DeepSeek pelo id;
+  `HostedGenAISettings` ganha `GOOGLE_*`, `google_kwargs()` e
+  `hosted_kwargs(model)`. Receita: seção "Resultado completo" de
+  `docs/recipes/genai-hosted.md`.
 - **Reconhecimento facial (v0.223.0, extra `[faces]`)** —
   `tempest_fastapi_sdk.faces`: `FaceRecognizer` (`detect` sem biometria /
   `recognize` / `embed_face` que recusa entrada ruim), `compare_faces`,
@@ -3863,3 +3876,38 @@ cadastro pendente comum. Com `AUTH_AUTO_ACTIVATE=true` o cadastro não consulta
   entre `search_fields`, todas as palavras) via `where=` do `paginate`, em vez
   de `filters[field] = q` (igualdade com AND). Teste:
   `tests/admin/test_search.py` (8 dos 10 casos falham no código antigo).
+- **DLQ sem `AckPolicy` no serviço, v0.332.0 (2026-10-27) (#642)** — `ack_policy`
+  nomeado em `MessageBroker.on`/`register`, `subscribe` e `Consumer`; spec com
+  dead-letter fixa `REJECT_ON_ERROR` no assinante (vence o `ack_policy` do
+  broker) e recusa `ACK`/`ACK_FIRST`/`NACK_ON_ERROR`. O default do FastStream
+  0.7.5 já era `REJECT_ON_ERROR` (`rabbit/subscriber/config.py`), então o
+  ganho é a garantia, não o comportamento padrão. Testes:
+  `tests/queue/test_dead_letter_ack_policy.py`,
+  `tests/queue/test_fanout_live.py` (`test_a_broker_wide_nack_still_dead_letters`).
+- **Idioma da documentação das rotas, v0.332.0 (2026-10-27) (#643)** — `API_DOCS_LOCALE`
+  no `ServerSettings` (`en-US`/`pt-BR`, normalizado por
+  `normalize_docs_locale` em `core/docs_locale.py`, língua desconhecida
+  recusada) e `docs_locale=` nas factories. Catálogo em `api/route_docs/`
+  (`en_us/` e `pt_br/`, `auth.py` + `platform.py` cada), lido por
+  `RouteDocs.summary/description/text`; o inglês é o texto que estava inline,
+  movido sem mudar um byte. Cobre auth, SSE, push, web push, health, logs,
+  tool-spec, app errors, sessions, PDF e voz. Fora: chat, genai (inclusive o
+  pipeline), agents, modelops, reviews, vision, wallet, hostbridge, os
+  webhooks de integração e os assets do SSR. Receita:
+  `docs/recipes/auth-flow.md`. Testes: `tests/api/test_route_docs.py`,
+  `tests/test_route_docs_coverage_guard.py`.
+- **E-mail de auth em background, opt-in, v0.332.0 (2026-10-27) (#644)** —
+  `AUTH_SEND_EMAILS_IN_BACKGROUND`; `auth/email_delivery.py` liga o
+  `BackgroundTasks` do request a uma `ContextVar` por dependência async do
+  `make_auth_router`, e `UserAuthService._send_email` agenda nela (ou aguarda,
+  fora de request). Default síncrono mantido por decisão do usuário. Teste:
+  `tests/auth/test_email_background.py` (tempo medido com uvicorn real).
+- **E-mails de auth com visual novo e marca, v0.332.0 (2026-10-27) (#645)** —
+  `auth/templates/_email_layout.html` (tabela, estilo inline, preheader,
+  `color-scheme`) estendido pelos 5 e-mails nas duas línguas;
+  `UserAuthService._render_email` põe `brand` no contexto a partir de
+  `AUTH_EMAIL_BRAND_NAME`/`_COLOR`/`_LOGO_URL`/`AUTH_EMAIL_FOOTER_TEXT`;
+  `utils/color.py` (`relative_luminance`, `is_light`) compartilhado com o
+  `AdminTheme`. Validado em browser (800/375 px, claro/escuro, marca escura,
+  clara e ausente) — a cor clara expôs o link ilegível, que ganhou
+  `link_color`. Teste: `tests/auth/test_email_templates.py`.

{tempest_fastapi_sdk-0.331.0 → tempest_fastapi_sdk-0.332.0}/docs/migration.en.md

@@ -2,6 +2,23 @@
 
 Breaking-change walkthroughs grouped by minor release. Stick to the version that matches what you're upgrading **from**. The release sections are listed newest-first, so on a multi-version jump read and apply them bottom-up.
 
+## 0.332.0 — the DLQ pins the consumer's ack policy
+
+On a `QueueSpec` with a dead-letter, `MessageBroker.on` / `register` and
+`subscribe` / `Consumer` pin `REJECT_ON_ERROR` on the subscriber itself when
+`ack_policy` is `None` (#642). Passing `ACK`, `ACK_FIRST` or `NACK_ON_ERROR`
+on a dead-lettered spec now raises `ValueError` at registration: none of the
+three sends the failure to the DLQ. A consumer without a dead-letter is
+unchanged.
+
+### What to do
+
+1. Drop `ack_policy=AckPolicy.REJECT_ON_ERROR` from dead-lettered consumers
+   if you like: it is now the default. Keeping it still works.
+2. A dead-lettered consumer that passed `ACK`, `ACK_FIRST` or
+   `NACK_ON_ERROR` fails at boot: switch to `REJECT_ON_ERROR` (or omit it), or
+   drop the dead-letter from the spec if failures should not go to the DLQ.
+
 ## 0.331.0 — new admin look, capped storage uploads
 
 `admin.css` was rewritten on tokens and `AdminTheme` changed two defaults:

{tempest_fastapi_sdk-0.331.0 → tempest_fastapi_sdk-0.332.0}/docs/migration.md

@@ -2,6 +2,22 @@
 
 Passo a passo das mudanças que quebram compatibilidade, agrupadas por release minor. Siga a versão que casa com aquela **de onde** você está atualizando. As seções estão listadas da mais nova para a mais antiga, então num salto de várias versões leia e aplique-as de baixo para cima.
 
+## 0.332.0 — DLQ fixa a política de ack do consumidor
+
+Num `QueueSpec` com dead-letter, o `MessageBroker.on` / `register` e o
+`subscribe` / `Consumer` fixam `REJECT_ON_ERROR` no próprio assinante quando
+`ack_policy` fica `None` (#642). Passar `ACK`, `ACK_FIRST` ou `NACK_ON_ERROR`
+num spec com dead-letter agora levanta `ValueError` no registro: nenhuma das
+três manda a falha para a DLQ. Consumidor sem dead-letter não muda.
+
+### O que fazer
+
+1. Tire o `ack_policy=AckPolicy.REJECT_ON_ERROR` dos consumidores com DLQ, se
+   quiser: o default já é esse. Mantê-lo continua valendo.
+2. Consumidor com dead-letter que passava `ACK`, `ACK_FIRST` ou
+   `NACK_ON_ERROR` falha no boot: troque por `REJECT_ON_ERROR` (ou omita), ou
+   tire o dead-letter do spec se a falha não deve ir para a DLQ.
+
 ## 0.331.0 — visual novo do admin, upload com teto no storage
 
 O `admin.css` foi reescrito sobre tokens e o `AdminTheme` mudou dois

{tempest_fastapi_sdk-0.331.0 → tempest_fastapi_sdk-0.332.0}/docs/recipes/auth-flow.en.md

@@ -1496,6 +1496,7 @@ Decide **whether** and **how** the link reaches the user. They map directly to t
 |---------|------|---------|--------------|
 | `AUTH_AUTO_ACTIVATE` | `bool` | `false` | `true` = user is born active, skips activation, signup returns the JWT pair directly (Mode D). **Never in production.** |
 | `AUTH_RETURN_TOKEN_IN_RESPONSE` | `bool` | `false` | `true` = activation/reset link goes in the JSON body instead of the email (Mode C). |
+| `AUTH_SEND_EMAILS_IN_BACKGROUND` | `bool` | `false` | `true` = the auth routes' emails go out **after** the response (`BackgroundTasks`); an SMTP failure is logged, not a `503`. See [In the background](#in-the-background-auth_send_emails_in_background). |
 
 ### Group 4 — Account token TTL (`AuthSettings`)
 
@@ -1514,6 +1515,10 @@ Lifetime of the **single-use** tokens (activation / reset) — distinct from the
 | `AUTH_PASSWORD_RESET_URL_TEMPLATE` | `str` | `http://localhost:3000/reset-password?token={token}` | Same, for reset. |
 | `AUTH_ACTIVATION_TEMPLATE` | `str` | `activation.html` | Jinja2 filename of the activation **email HTML**, resolved against `EmailUtils.template_dir`. |
 | `AUTH_PASSWORD_RESET_TEMPLATE` | `str` | `password_reset.html` | Same, for reset. |
+| `AUTH_EMAIL_BRAND_NAME` | `str` | `""` | Name in the emails' header; empty leaves the header out. See [The brand in the emails](#the-brand-in-the-emails). |
+| `AUTH_EMAIL_BRAND_COLOR` | `str` | `#2563eb` | Color (`#rgb`/`#rrggbb`) of the button and accents; the button text darkens on its own on a light color. |
+| `AUTH_EMAIL_BRAND_LOGO_URL` | `str` | `""` | Absolute `http(s)` URL of the header logo, instead of the name. |
+| `AUTH_EMAIL_FOOTER_TEXT` | `str` | `""` | Extra footer line (company name, address). |
 
 #### Where `AUTH_ACTIVATION_URL_TEMPLATE` points
 
@@ -1810,6 +1815,51 @@ sequenceDiagram
 
 ---
 
+## The brand in the emails
+
+*(v0.332.0+)*
+
+The flow's five emails (activation, password reset, email change,
+verification and the email-changed notice) extend one layout,
+`_email_layout.html`: a brand header, a card, a button, a fallback link, an
+expiry note and a footer. It is built on tables with inline styles — what
+Gmail and Outlook honor — and carries `color-scheme` for clients with a
+dark mode.
+
+Four `AuthSettings` env vars dress the email in your brand, with no template
+copied:
+
+```bash
+# .env
+AUTH_EMAIL_BRAND_NAME=Acme
+AUTH_EMAIL_BRAND_COLOR=#7c3aed
+AUTH_EMAIL_BRAND_LOGO_URL=https://acme.com/logo.png
+AUTH_EMAIL_FOOTER_TEXT=Acme Inc · San Francisco, CA
+```
+
+- **With no name or logo**, the header is left out; the default is the blue
+  button (`#2563eb`) with no brand.
+- **A light color adjusts.** The button text and the link color are picked
+  from the color's luminance: with `#facc15` (yellow) the button gets dark
+  text and the link turns dark gray, because yellow on the white card does
+  not read.
+- **An invalid value fails the boot.** The color only takes `#rgb`/`#rrggbb`
+  and the logo only an absolute `http(s)` URL — both go into an HTML
+  attribute, and an email cannot load a relative path.
+
+!!! tip "Your own template still wins"
+    A `template_dir` with the same file name (`activation.html`, …) beats
+    the SDK's, as before. The context gained `brand` (`name`, `color`,
+    `text_color`, `link_color`, `logo_url`, `footer`); your template may use
+    it or ignore it. To keep the new layout and change only the text, extend
+    `_email_layout.html` and fill the `heading`, `content`, `note` and
+    `footer` blocks, with `action_url`, `action_label` and `fallback_label`
+    in `{% set %}`.
+
+Validated in a real browser in both languages, at 800 and 375 px, in light
+and dark mode, with a dark brand (`#7c3aed`), a light one (`#facc15`) and no
+brand.
+
 ## Email and page language (i18n)
 
 Since **v0.59.0**, the emails and HTML pages the SDK ships out of the box
@@ -1941,6 +1991,105 @@ in `{{ expires_at }}`.
 
 ---
 
+## Route documentation language (`/docs`) *(Unreleased, #643)*
+
+The email language does not change the `/docs` language. The `summary` and
+`description` that `make_auth_router` writes into the OpenAPI document — what
+shows up in Swagger, in ReDoc and in the comments of a generated client — are
+English by default. To have them in Brazilian Portuguese, one environment
+variable is enough:
+
+```env
+# .env
+API_DOCS_LOCALE=pt-BR   # default: en-US
+```
+
+The whole app, in one file, to check it:
+
+```python
+from collections.abc import AsyncIterator
+
+from fastapi import FastAPI
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from tempest_fastapi_sdk import (
+    BaseUserModel,
+    UserAuthService,
+    make_auth_router,
+    make_user_token_model,
+)
+from tempest_fastapi_sdk.settings.mixins import AuthSettings, JWTSettings
+
+
+class UserModel(BaseUserModel):
+    """The product's account."""
+
+    __tablename__ = "users"
+
+
+UserTokenModel = make_user_token_model(
+    user_table="users",
+    tablename="user_tokens",
+    class_name="UserTokenModel",
+)
+
+service: UserAuthService = UserAuthService(
+    user_model=UserModel,
+    token_model=UserTokenModel,
+    auth_settings=AuthSettings(),
+    jwt_settings=JWTSettings(),
+    email=None,
+)
+
+
+async def get_session() -> AsyncIterator[AsyncSession]:
+    """Request-scoped database session (use your service's own)."""
+    raise NotImplementedError
+    yield
+
+
+app: FastAPI = FastAPI()
+app.include_router(make_auth_router(service, session_factory=get_session))
+
+login: dict[str, str] = app.openapi()["paths"]["/auth/login"]["post"]
+print(login["summary"])
+```
+
+```console
+$ python app.py
+Log in with email + password → JWT pair
+$ API_DOCS_LOCALE=pt-BR python app.py
+Entrar com e-mail + senha → par JWT
+```
+
+Rather decide in code than in the environment? Every route factory accepts
+`docs_locale=`, and the argument wins over the variable — in the example
+above, `make_auth_router(service, session_factory=get_session, docs_locale="pt-BR")`
+prints the Portuguese summary with or without `API_DOCS_LOCALE`.
+
+!!! info "Only the prose changes — the contract stays"
+    Paths, `operationId`, parameter and field names, error codes and schema
+    `title`s are the same in both languages. A client generated from the
+    Portuguese document is the client generated from the English one; only
+    the comments differ.
+
+!!! tip "Case does not matter"
+    `pt-BR`, `pt_br` and `pt` become `pt-BR`; `en-US`, `EN-us` and `en`
+    become `en-US`. Unlike `AUTH_DEFAULT_LOCALE`, a language the catalog does
+    not carry (`es-ES`, `pt-PT`) does **not** fall back to the default: the
+    app refuses to start, naming `API_DOCS_LOCALE`. English documentation on
+    a deployment that asked for another language is the silent defect that
+    refusal prevents.
+
+**Which routers follow the variable today:** `make_auth_router` (every route
+that appears in the schema), `make_sse_router` (and
+`UserAuthService.sse_router`), `make_push_router`, `make_web_push_router`,
+`make_health_router`, `make_logs_router`, `make_tool_spec_router`,
+`make_app_error_router`, `make_session_router`, `make_pdf_router` and
+`make_voice_router`. The others (chat, genai, agents, modelops, reviews,
+vision, wallet, hostbridge) still document themselves in English. The
+variable lives on `ServerSettings`.
+
 ## Five operating modes
 
 | Mode | When to use | Flags | Where the link appears |
@@ -2430,6 +2579,50 @@ When you call `UserAuthService` outside `make_auth_router`, the rule is
 the one for any error after a flush: roll the session back before reusing
 it. The router does that on its own, because it never reaches the commit.
 
+### In the background (`AUTH_SEND_EMAILS_IN_BACKGROUND`)
+
+*(v0.332.0+)*
+
+By default the route waits for SMTP: a slow server makes signup and reset
+slow. With `AUTH_SEND_EMAILS_IN_BACKGROUND=true`, the `make_auth_router`
+routes hand the send to the request's `BackgroundTasks` — the response goes
+first and the email after. Measured in `tests/auth/test_email_background.py`,
+with a mailer taking 1 s per send served by real uvicorn: `POST /auth/signup`
+answered in over 1 s by default and in under 0.5 s in the background.
+
+```bash
+# .env
+AUTH_SEND_EMAILS_IN_BACKGROUND=true
+```
+
+What changes, and the price:
+
+- **The response time stops depending on the send.** A
+  `/password-reset/request` for a registered address no longer takes longer
+  than one for an unknown address, a difference you could measure from
+  outside.
+- **An SMTP failure does not answer `503`.** The response is gone; the
+  failure goes to `ERROR` on the `tempest_fastapi_sdk.auth.email_delivery`
+  logger, with the kind of email and only the recipient's **domain**.
+- **There is no rollback on a failed send.** The signup stays stored without
+  the activation email (the user asks for a resend), and on reset and
+  activation resend the new token has already replaced the pending one when
+  the send fails — the earlier link stops working and the new one never
+  arrived. Asking again fixes it.
+- **The email only goes out if the request succeeded.** `make_auth_router`
+  commits before answering, and an exception after scheduling swaps the
+  response for an error one, which does not carry the tasks: no link points
+  at a token that was not stored.
+
+Outside a request — `UserAuthService` called from a command, a task or a
+test — there is no `BackgroundTasks`, and the send is awaited as by default,
+with the same `EmailDeliveryException`.
+
+!!! tip "Shutdown"
+    Starlette runs a response's background tasks before the request ends, so
+    the server's graceful shutdown waits for them like any in-flight request.
+    A loose `asyncio.create_task` would not have that guarantee.
+
 ## Token delivery
 
 *(v0.87.0+)*