PyPI - tempest-fastapi-sdk - Versions diffs - 0.167.2__tar.gz → 0.168.1__tar.gz - Mend

tempest-fastapi-sdk 0.167.2tar.gz → 0.168.1tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (767) hide show

{tempest_fastapi_sdk-0.167.2 → tempest_fastapi_sdk-0.168.1}/CHANGELOG.md RENAMED Viewed

@@ -5,6 +5,91 @@ All notable changes to **tempest-fastapi-sdk** are listed below.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+## [0.168.1] — 2026-07-26
+Documentation navigation only — no code change, no API change.
+### Changed
+- **Everything a reader scans to find a page is alphabetical now.** The recipe
+  list had grown to 53 entries in insertion order, which turns a lookup into a
+  full pass over the list. Sorted, accent- and case-insensitively:
+    - the `Receitas` / `Recipes` nav section (including the
+      `Exemplos completos` / `Complete examples` sub-section, itself at its
+      alphabetical position);
+    - both tables on the Recipes landing (`Tema`/`Theme` with all 53 recipes,
+      and the complete-examples table), each sorted in its own language;
+    - the themed groups of `docs/reference.md`, with
+      `## Superfície de topo` pinned first;
+    - the module table in `README.md`;
+    - the extras table in `docs/installation.md` + `.en.md`, with `[all]` last
+      because it is the catch-all, not an entry to look up.
+- **English gets its own nav.** `mkdocs-static-i18n` translates labels but
+  cannot reorder a shared nav, so an alphabetical PT nav left the EN sidebar in
+  Portuguese order (`File in the service` before `Versioned artifacts` before
+  `Audit trail`). The `en` locale now declares a full `nav` of its own, sorted
+  in English. `nav_translations` stays for the labels the plugin still resolves.
+The top-level tabs and the learning-project pages are deliberately **not**
+alphabetical: they follow a reading order (install before tutorial, business
+rules before endpoint map), where sorting would be the regression.
+### Added
+- **`tests/test_nav_ordering.py`** — guards what the sweep above fixed: the two
+  navs cover the same pages (no page reachable in one language only), no page
+  is listed twice, the alphabetical sections are alphabetical in both
+  languages, and the Recipes landing tables are sorted. Eight tests; a swapped
+  entry fails them.
+## [0.168.0] — 2026-07-26
+Permission guards gain injected metadata: one generic guard, a specific check
+per call site.
+### Added
+- **A guard may declare a second parameter `meta: dict[str, Any]`.** That is
+  what turns `manager_only` / `auditor_only` / `admin_only` into one
+  `has_role(user, meta)` whose call sites declare
+  `@requires(has_role, meta={"role": "manager"})`. One-parameter guards are
+  untouched — the second argument is passed only to guards that declare it, so
+  both shapes mix freely in the same decoration.
+- **`requires(..., meta=...)`** — literal metadata, copied at decoration time,
+  so a later mutation of the passed mapping cannot change what the route
+  enforces. Must be a `Mapping[str, Any]`; anything else is a
+  `TempestPermissionError` at import.
+- **`requires(..., include_args=True)`** — merges the arguments the decorated
+  function was called with into the same mapping, so an ownership guard reads
+  `meta["order_id"]` without the route handing it over. The user parameter is
+  excluded (the guard already receives it), a parameter the caller omitted
+  contributes its default so the guard sees the values the body will run with,
+  a default that is a framework injection marker (`Depends(...)`) is dropped
+  rather than passed as a value, and a `meta=` literal wins a name clash with
+  an argument — the decoration is the explicit declaration. The mapping is
+  fresh per call and shared by that call's guards, so one guard may write a key
+  the next one reads without anything leaking into the next request.
+- **`guard_metadata(fn)`** — reads the `meta=` literals off a decorated
+  function, next to `declared_guards` / `guarded_user_param`. Exported from
+  `tempest_fastapi_sdk` and `tempest_fastapi_sdk.authz`.
+- **Four static checks in `tempest permissions`:** `meta-unused` (error — the
+  decoration passes `meta=` / `include_args=True` but no guard declares a
+  second parameter; held back when a guard in that decoration could not be
+  resolved, since it may be the consumer), `guard-meta-missing` (warning — a
+  two-parameter guard whose decoration supplies no metadata reads an empty
+  dict), `guard-meta-annotation` (warning — the metadata parameter is annotated
+  as something that cannot hold a `dict[str, Any]`) and `meta-key-collision`
+  (warning — a `meta=` key shadows a parameter name under `include_args=True`,
+  so that argument never reaches the guard).
+### Changed
+- **`guard-arity` accepts one or two required parameters.** A guard taking
+  `(user, meta)` used to be rejected at import (`expected 1 (user)`); the
+  contract is now one *or* two, and the message reads
+  `expected 1 (user) or 2 (user, meta)`. Three or more is still an error. No
+  existing single-parameter guard changes behavior.
 ## [0.167.2] — 2026-07-26
 Documentation layout only — no code change, no API change.

{tempest_fastapi_sdk-0.167.2 → tempest_fastapi_sdk-0.168.1}/CLAUDE.md RENAMED Viewed

@@ -92,7 +92,15 @@ The SDK currently covers (Sep 2025+, post-v0.31.x):
   `guard-unresolved` (ambiguous or out-of-scope guard reported, never guessed).
   `openapi-errors` follows the guards, so their exceptions land in
   `error_responses(...)`. `declared_guards`/`guarded_user_param` introspect a
-  route. Recipe: `docs/recipes/permission-guards.md`.
+  route. **Metadata (v0.168.0):** a guard may declare a 2nd param
+  `meta: dict[str, Any]` — `meta={...}` literals fixed at decoration plus
+  `include_args=True` merging the call's args (user excluded, omitted params
+  contribute defaults, `Depends(...)` markers dropped, `meta=` wins a name
+  clash); one-param guards untouched; `TempestPermissionError` when `meta=`
+  isn't a mapping or nothing consumes it; `guard_metadata(fn)` reads the
+  literals; new static codes `meta-unused` (error), `guard-meta-missing`/
+  `guard-meta-annotation`/`meta-key-collision` (warnings). Recipe:
+  `docs/recipes/permission-guards.md`.
 - **DB** — `AsyncDatabaseManager`, `BaseRepository[T]` with
   bulk ops (`bulk_create_values`, `bulk_upsert`, `bulk_update`,
   `add_all`, etc.), `AlembicHelper`, `BaseModel`, audit /
@@ -483,6 +491,18 @@ business need, not from a stale list. Keep this honest, not aspirational.
   the same PR — this drifts easily (it happened for both the admin
   tiers and the genai roadmap). Add `# docs-guard: skip` to a doc block
   only for an intentionally non-parseable fragment.
+- **Navegação e índices em ordem alfabética.** A seção `Receitas` do
+  `nav` (e a subseção `Exemplos completos`), as tabelas da landing de
+  receitas, os grupos temáticos de `docs/reference.md`, a tabela de
+  módulos do README e a de extras da instalação são ordenadas
+  alfabeticamente (case/acento-insensível; `[all]` fica por último por
+  ser catch-all). O `mkdocs-static-i18n` **não** reordena nav por
+  idioma, então o locale `en` declara um `nav` próprio já ordenado em
+  inglês — mexer em um nav exige mexer no outro.
+  `tests/test_nav_ordering.py` falha se algo sair de ordem, se um nav
+  ganhar página que o outro não tem, ou se uma página aparecer duas
+  vezes. Abas de topo e páginas de `learning/` seguem ordem didática,
+  não alfabética — de propósito.
 - **No emojis in code or docs** unless the user explicitly asks.
 - **Bilingual docs.** Every page lives twice: `docs/<page>.md`
   (PT-BR, default) and `docs/<page>.en.md` (EN-US). The MkDocs

{tempest_fastapi_sdk-0.167.2 → tempest_fastapi_sdk-0.168.1}/PKG-INFO RENAMED Viewed

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tempest-fastapi-sdk
-Version: 0.167.2
+Version: 0.168.1
 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
@@ -295,37 +295,37 @@ Since `0.7.1` every optional dependency is imported lazily at first instantiatio
 | Module | Exports |
 | --- | --- |
-| `tempest_fastapi_sdk.openapi` | `generate_integration`, `load_spec`, `parse_spec`, `emit_schemas`, `emit_client`, `GenerationResult`, `default_output_dir`, `SpecError`, `SpecIR` / `SchemaIR` / `FieldIR` / `ClientIR` / `OperationIR` / `ParameterIR` — backs `tempest openapi-client`, which generates Pydantic schemas + a typed HTTP client from a third party's OpenAPI spec *(YAML needs the `[openapi]` extra)* |
-| `tempest_fastapi_sdk.schemas` | `BaseSchema`, `BaseResponseSchema`, `ErrorResponseSchema`, `BasePaginationFilterSchema`, `BasePaginationSchema[T]`, `CursorPaginationFilterSchema`, `CursorPaginationSchema`, `LogEntrySchema`, `encode_cursor`, `decode_cursor`, `build_pagination_link_header` |
-| `tempest_fastapi_sdk.db` | `BaseModel`, `BaseUserModel`, `BaseUserTokenModel`, `BaseUserRecoveryCodeModel`, `make_user_recovery_code_model`, `UserTokenPurpose`, `BaseRepository[ModelType]`, `TenantScopedRepository[ModelType]`, `AsyncDatabaseManager`, `AlembicHelper` (+ `safe_upgrade`), `DestructiveMigrationError`, `NAMING_CONVENTION`, `AuditMixin`, `SoftDeleteMixin`, `MFAMixin`, `LocaleColumnMixin`, `BASE_COLUMN_ORDER`, `reorder_base_columns_first`, `compose_hooks`, `SlowQueryLogger`, `BaseOutboxModel`, `OutboxRelay`, `OutboxStatus`, `BaseRepository.save_with_outbox`, audit trail (`BaseAuditLogModel`, `AuditAction`, `snapshot_model`, `diff_snapshots`, `BaseRepository.add_audited` / `update_audited` / `delete_audited`), eager-loading (`get`/`get_or_none`/`get_by_id`/`first`/`list` accept `with_=[...]`, dotted for nested), lifecycle signals (`RepositorySignal`, `connect` / `on_signal` / `disconnect`, `PRE_SAVE`/`POST_SAVE`/`PRE_DELETE`/`POST_DELETE`), `F` / `Q` expression wrappers (`F("stock") - 1` atomic updates; `Q(...) | Q(...)` OR/NOT via `where=`), `BaseWebPushSubscriptionModel` + `make_web_push_subscription_model` |
-| `tempest_fastapi_sdk.exceptions` | `AppException`, `NotFoundException`, `ConflictException`, `ValidationException`, `UnauthorizedException`, `ForbiddenException`, `InvalidTokenException`, `ExpiredTokenException`, `FileTooLargeException`, `InvalidFileTypeException`, `TooManyRequestsException`, `InheritedErrorCodeWarning`, i18n (`MessageCatalog`, `default_message_catalog`, `parse_accept_language`, `DEFAULT_LOCALE`) |
-| `tempest_fastapi_sdk.settings` | `BaseAppSettings` (+ `AppSettingsMeta`), `ServerSettings`, `LogSettings`, `DatabaseSettings`, `RedisSettings`, `RabbitMQSettings`, `JWTSettings`, `CORSSettings`, `EmailSettings`, `UploadSettings`, `TokenSettings`, `WebPushSettings`, `TaskIQSettings`, `MinIOSettings`, `AuthSettings` |
+| `tempest_fastapi_sdk.admin` *(extra: `[admin]`)* | `AdminSite`, `AdminModel` (incl. `audit_model=...` for a per-row audit-history timeline, `autocomplete_fields=[...]` for HTMX-searched FK inputs, `inlines=[Inline(...)]` for 1-N children on the detail view, `Inline(editable=True, can_delete=True)` for in-place formset editing of those children), `Inline`, dashboard business-metric cards (`AdminSite(dashboard_cards=[...])`: `MetricCard` + `MetricValue` / `MetricTrend` / `MetricPartition`), CSV import (`AdminModel(can_import=True)`), granular RBAC (`make_admin_router(access_policy=...)` + `AdminPermission`), lenses (`AdminModel(lenses=[Lens(...)])` saved list presets), JSON + time field widgets, `make_admin_router`, `AdminAuthBackend`, `UserModelAuthBackend`, `AdminAuthError` |
 | `tempest_fastapi_sdk.api` | `register_exception_handlers`, `app_exception_handler`, OpenAPI error docs (`error_responses`, `raises`, `TempestAPIRouter`, `RaisesSpec`, `declared_raises`), `apply_cors`, `make_health_router`, `make_logs_router`, `make_prometheus_router`, `make_prometheus_registry`, `PrometheusMiddleware`, `BusinessMetrics`, `LogSource`, `make_tool_spec_router`, `make_token_dependency`, `make_bearer_token_dependency`, `make_jwt_user_dependency`, `make_role_dependency`, `make_permission_dependency`, `require_x_token`, `run_server`, `RequestIDMiddleware`, `RateLimitMiddleware` (+ `RateLimitStore`/`MemoryRateLimitStore`/`RedisRateLimitStore`/`RateLimitResult` and `key_by_ip`/`key_by_jwt_subject`/`key_by_jwt_claim`/`key_by_header`), `IdempotencyMiddleware`, `MemoryIdempotencyStore`, `RedisIdempotencyStore`, `BodySizeLimitMiddleware`, `CSRFMiddleware`, `make_csrf_token_dependency`, `GracefulShutdownMiddleware`, `WebhookSignatureVerifier`, `RSAWebhookSignatureVerifier`, outbound `WebhookSender` (+ `WebhookDelivery`), OAuth2 (`GoogleOAuthClient`, `GitHubOAuthClient`, `OIDCProvider`), `HardenedStaticFiles`, `DEFAULT_STATIC_SECURITY_HEADERS`, `make_spa_router` (serve a compiled React/Vite SPA with a client-side fallback), `set_cookie`, `clear_cookie`, `SameSite`, `HealthCheck`, `setup_tracing` *(extra: `[otel]`)* |
 | `tempest_fastapi_sdk.auth` *(extra: `[auth]`, opcional `[email]`, `[mfa]`)* | `UserAuthService`, `make_auth_router`, `SignupSchema` / `LoginSchema` / `RefreshSchema` / `PasswordResetRequestSchema` / `PasswordResetConfirmSchema` + responses, `ActivationToken`, `PasswordResetToken`, email change/verify/recovery (`EmailChangeRequestSchema` / `EmailChangeConfirmSchema` / `EmailRecoveryRequestSchema` / `EmailChangeToken` / `EmailVerificationToken`, old-email security notice, opt-in `AUTH_EMAIL_RECOVERY_ENABLED`), MFA schemas (`MFAEnrollResponseSchema` / `MFAConfirmSchema` / `MFAVerifySchema` / `MFADisableSchema`), opt-in DB-backed refresh tokens (`BaseUserRefreshTokenModel` / `make_user_refresh_token_model` / `LogoutSchema`) with rotation + reuse detection + `POST /auth/logout`, bilingual emails + backend pages (`AUTH_DEFAULT_LOCALE`, `normalize_locale` / `negotiate_locale`) — signup/activate/login/refresh/logout/reset + email change/recovery + TOTP 2FA out of the box |
-| `tempest_fastapi_sdk.authz` | Object-level permissions: `permission` (rule decorator), `has_perm` / `check_permission`, `PermissionRegistry` (injectable superuser bypass + static-permission fallback, `order.*`/`*` wildcards), `make_permission_checker` (FastAPI route guard), `PermissionMixin` (`await user.has_perm(perm, obj=...)`), `default_registry`, `requires` (guard decorator `(user) -> user | None`, checked at import time + by `tempest permissions`), `declared_guards` / `guarded_user_param`, `TempestPermissionError`, `GuardContractWarning` |
+| `tempest_fastapi_sdk.authz` | Object-level permissions: `permission` (rule decorator), `has_perm` / `check_permission`, `PermissionRegistry` (injectable superuser bypass + static-permission fallback, `order.*`/`*` wildcards), `make_permission_checker` (FastAPI route guard), `PermissionMixin` (`await user.has_perm(perm, obj=...)`), `default_registry`, `requires` (guard decorator `(user) -> user | None`, optional `meta: dict[str, Any]` second parameter via `meta=` / `include_args=`, checked at import time + by `tempest permissions`), `declared_guards` / `guarded_user_param` / `guard_metadata`, `TempestPermissionError`, `GuardContractWarning` |
+| `tempest_fastapi_sdk.cache` *(extra: `[cache]`)* | `AsyncRedisManager`, `cached` (with `namespace` / `tags`), `CacheInvalidator`, `namespace_registry_key`, `tag_registry_key` |
+| `tempest_fastapi_sdk.chat` | Threaded chat: abstract tables `BaseConversationModel`/`BaseConversationParticipantModel`/`BaseMessageModel` (+ `make_*` factories), `ChatService` (`start_conversation`/`post_message`/`list_messages`/`list_conversations`), `make_chat_router` (opt-in), real-time fan-out via an injected `SSEBroker` |
 | `tempest_fastapi_sdk.checks` | System checks (Django-style config validation): `check` (register decorator), `run_checks` / `run_system_checks` (raises `SystemCheckError` on ERROR+), `CheckMessage` / `CheckLevel` + `debug`/`info`/`warning`/`error`/`critical`, `CheckRegistry` / `default_registry`; built-in settings checks + the `tempest check-config` CLI (auto-detects settings, `--tag` / `--fail-level`) |
+| `tempest_fastapi_sdk.cli` | `tempest` console script — `new <name>` (scaffold layered service), `lint` / `format` / `fmt-check` / `type` / `test` / `check` (run preferred quality gates), `check-config` (validate settings via the system-check framework), `version` / `--version`; plus project-registered management commands (`tempest <cmd>` from `src/commands.py` or `[tool.tempest] commands`) |
 | `tempest_fastapi_sdk.controllers` | `BaseController` |
-| `tempest_fastapi_sdk.services` | `BaseService` |
 | `tempest_fastapi_sdk.core` | `configure_logging`, `JSONFormatter`, `get_request_id`/`set_request_id`/`clear_request_id`, `request_id_ctx`, `BaseStrEnum`, `BaseIntEnum`, `Locale` (BCP-47 locale enum), `strict_types`/`typed`/`require_annotations` |
-| `tempest_fastapi_sdk.admin` *(extra: `[admin]`)* | `AdminSite`, `AdminModel` (incl. `audit_model=...` for a per-row audit-history timeline, `autocomplete_fields=[...]` for HTMX-searched FK inputs, `inlines=[Inline(...)]` for 1-N children on the detail view, `Inline(editable=True, can_delete=True)` for in-place formset editing of those children), `Inline`, dashboard business-metric cards (`AdminSite(dashboard_cards=[...])`: `MetricCard` + `MetricValue` / `MetricTrend` / `MetricPartition`), CSV import (`AdminModel(can_import=True)`), granular RBAC (`make_admin_router(access_policy=...)` + `AdminPermission`), lenses (`AdminModel(lenses=[Lens(...)])` saved list presets), JSON + time field widgets, `make_admin_router`, `AdminAuthBackend`, `UserModelAuthBackend`, `AdminAuthError` |
-| `tempest_fastapi_sdk.sse` | `EventStream` (bounded queue + `overflow` backpressure), `SSEBroker` (multi-worker fan-out via Redis, `.response()` lifecycle helper), `ServerSentEvent`, `sse_response` (`on_disconnect=` cleanup) |
-| `tempest_fastapi_sdk.cache` *(extra: `[cache]`)* | `AsyncRedisManager`, `cached` (with `namespace` / `tags`), `CacheInvalidator`, `namespace_registry_key`, `tag_registry_key` |
+| `tempest_fastapi_sdk.db` | `BaseModel`, `BaseUserModel`, `BaseUserTokenModel`, `BaseUserRecoveryCodeModel`, `make_user_recovery_code_model`, `UserTokenPurpose`, `BaseRepository[ModelType]`, `TenantScopedRepository[ModelType]`, `AsyncDatabaseManager`, `AlembicHelper` (+ `safe_upgrade`), `DestructiveMigrationError`, `NAMING_CONVENTION`, `AuditMixin`, `SoftDeleteMixin`, `MFAMixin`, `LocaleColumnMixin`, `BASE_COLUMN_ORDER`, `reorder_base_columns_first`, `compose_hooks`, `SlowQueryLogger`, `BaseOutboxModel`, `OutboxRelay`, `OutboxStatus`, `BaseRepository.save_with_outbox`, audit trail (`BaseAuditLogModel`, `AuditAction`, `snapshot_model`, `diff_snapshots`, `BaseRepository.add_audited` / `update_audited` / `delete_audited`), eager-loading (`get`/`get_or_none`/`get_by_id`/`first`/`list` accept `with_=[...]`, dotted for nested), lifecycle signals (`RepositorySignal`, `connect` / `on_signal` / `disconnect`, `PRE_SAVE`/`POST_SAVE`/`PRE_DELETE`/`POST_DELETE`), `F` / `Q` expression wrappers (`F("stock") - 1` atomic updates; `Q(...) | Q(...)` OR/NOT via `where=`), `BaseWebPushSubscriptionModel` + `make_web_push_subscription_model` |
+| `tempest_fastapi_sdk.exceptions` | `AppException`, `NotFoundException`, `ConflictException`, `ValidationException`, `UnauthorizedException`, `ForbiddenException`, `InvalidTokenException`, `ExpiredTokenException`, `FileTooLargeException`, `InvalidFileTypeException`, `TooManyRequestsException`, `InheritedErrorCodeWarning`, i18n (`MessageCatalog`, `default_message_catalog`, `parse_accept_language`, `DEFAULT_LOCALE`) |
 | `tempest_fastapi_sdk.flags` | `FeatureFlags`, `FeatureFlagBackend`, `MemoryFeatureFlagBackend`, `EnvFeatureFlagBackend`, `RedisFeatureFlagBackend`, `CompositeFeatureFlagBackend`, `make_flag_dependency`, `coerce_flag` |
-| `tempest_fastapi_sdk.webpush` *(extra: `[webpush]`)* | `WebPushDispatcher`, `WebPushSubscriptionService`, `make_web_push_router`, `WebPushError`, `WebPushGoneError`, `WebPushSubscriptionSchema`, `WebPushKeysSchema`, `WebPushPayloadSchema` |
-| `tempest_fastapi_sdk.queue` *(extra: `[queue]`)* | `MessageBroker` (typed, transport-agnostic FastStream facade — `.rabbitmq`/`.redis`/`.kafka`/`.nats`, `@mq.on(channel)`, channel-first `publish`); class-based consumers (`Consumer` + `@subscribe` + `MessageBroker.register`); `AsyncQueueManager` (thin lifecycle wrapper, formerly `AsyncBrokerManager`) |
-| `tempest_fastapi_sdk.storage` *(extra: `[minio]`)* | `AsyncMinIOClient` (+ batch `presigned_get_urls` / `put_objects` / `get_objects_bytes`), `ObjectStat`, `PutObjectItem` — async MinIO/S3 facade |
-| `tempest_fastapi_sdk.utils.http_client` *(extra: `[http]`)* | `HTTPClient`, `RetryPolicy`, `CircuitOpenError`, `REQUEST_ID_HEADER` — typed httpx wrapper |
-| `tempest_fastapi_sdk.utils.storage_backends` *(extra: `[upload]`)* | `UploadStorage` protocol, `LocalUploadStorage`, `MinIOUploadStorage`, `UploadResult`, `ContentValidator` |
-| `tempest_fastapi_sdk.tasks` *(extra: `[tasks]`)* | `TaskQueue` (typed TaskIQ facade — `.rabbitmq`/`.redis`/`.memory`, `@tq.task` → `Task.enqueue`/`.run`, `@tq.cron`/`@tq.interval`, `start_scheduler`), `Task`; class-based tasks (`TaskDef` + `@task_method` + `TaskQueue.register`); cron helpers (`Cron` / `CronOffset` / `Weekday` + `daily`/`weekdays`/`every_n_minutes`/… builders); `AsyncTaskBrokerManager` / `AsyncTaskScheduler` (legacy wrappers) |
-| `tempest_fastapi_sdk.vision` *(extra: `[vision]`)* | `Detector`, `Classifier`, `Segmenter` (ONNX, lazy), `DetectionSchema`/`ClassificationSchema`/`SegmentationSchema`/`BoundingBoxSchema`/`ClassProbabilitySchema`, `to_detection_schemas`/`to_classification_schema`/`to_segmentation_schemas`, `make_vision_router` (opt-in `POST /classify` / `/detect` / `/segment`) |
 | `tempest_fastapi_sdk.genai` *(extra: `[genai]`; capacity check imports without it)* | Self-hosted GenAI: capacity check (`probe_hardware`/`HardwareInfo`, `can_run`/`recommend`/`CapacityReport`, `estimate_model_bytes`/`fetch_num_params`, `ModelDtype`); local LLM `TextGenerator` (`generate`/`chat`/`stream`, typed `GenerationConfig`, int4/int8 quant, lazy load + idle unload); `Embedder` (+ `EmbeddingCache`/`InMemoryEmbeddingCache`/`RedisEmbeddingCache`/`AsyncEmbeddingCache`, `normalize=`) + `cosine_similarity`, `BatchScheduler` (coalesce concurrent calls), `ModelRegistry` (LRU model sharing); `make_genai_router` (opt-in endpoints — `/generate`+SSE, `/chat`, `/embed`, `/rag`, `/transcribe`, `/tts`); `resolve_device`/`auto_dtype_name`; **tool calling** (`TextGenerator.chat_with_tools` / `OllamaGenerator.chat_with_tools`) + **structured output** (`generate_structured` — Ollama `format=`, transformers `lm-format-enforcer` via `[genai-structured]`; `parse_structured`); **`VisionTextGenerator`** (local VLM, `[genai-vlm]`); **`OnnxEmbedder`** (torch-free embeddings, `[genai-onnx]`); **generation cache** (`InMemoryGenerationCache`/`RedisGenerationCache`, deterministic-only) via `generation_cache=`; **token/context** (`count_tokens`/`count_message_tokens`/`truncate_messages`); **`GenAIMetrics`** (Prometheus request/latency/token metrics, `[prometheus]`); **moderation** (`RuleModerator`/`ClassifierModerator` + `ModerationResult`); Ollama backend (`[genai-ollama]`) — `OllamaGenerator`/`OllamaEmbedder` (HTTP, no torch) behind the `TextBackend` protocol, drop-in for `make_genai_router`/`Retriever`, plus vision (`generate(images=…)`); **`AIChatPipeline`** (memory recall → web-search augment → generate w/ bounded tool-calling loop → TTS → memory index) + `Tool` + `make_ai_chat_router` (`POST /chat` + `/chat/stream` SSE) |
-| `tempest_fastapi_sdk.chat` | Threaded chat: abstract tables `BaseConversationModel`/`BaseConversationParticipantModel`/`BaseMessageModel` (+ `make_*` factories), `ChatService` (`start_conversation`/`post_message`/`list_messages`/`list_conversations`), `make_chat_router` (opt-in), real-time fan-out via an injected `SSEBroker` |
-| `tempest_fastapi_sdk.reviews` | Comments + 0–5 star ratings on any polymorphic target: `BaseCommentModel`/`BaseRatingModel` (+ `make_*`), `ReviewService` (`add_comment`/`list_comments`/`rate` upsert/`get_user_rating`/`aggregate`), `make_reviews_router` (opt-in), `RatingField` |
 | `tempest_fastapi_sdk.genai.rag` *(extra: `[genai-rag]`)* | RAG context for local LLMs: `WebSearch` (`.retrieve` one-shot search→extract→context) / `SearxngBackend` / `WebSearchBackend` + `SearchResult`, `ContentExtractor` (trafilatura, `.extract_many` concurrent), `PdfReader` (PyMuPDF) + `Document`/`Chunk`/`PdfPage`, `chunk_text`, `build_context`; corpus RAG — `Retriever` + `VectorStore`/`InMemoryVectorStore`/`PgVectorStore` (pgvector)/`ChromaVectorStore` (`[genai-chroma]`); **`Reranker`** (cross-encoder second stage) + **`HybridRetriever`** (BM25 + dense, `reciprocal_rank_fusion`, `rank-bm25`); long-term chat memory — `ChatMemory` (recency-aware, per-user, Chroma-backed) + `MemoryHit`; audio (`[genai-audio]`) — `SpeechToText` (faster-whisper, `beam_size`/`vad_filter`/`language_probability`) + `TextToSpeech` (Coqui TTS) + `Transcription` |
 | `tempest_fastapi_sdk.geo` *(extra: `[geo]`; offline layers import without it)* | Geolocation without a paid API: `haversine_km`, `estimate_travel` (offline road distance + per-mode time), offline geometry (`bounding_box`, `within_radius`, `nearest`, `initial_bearing`, `destination_point`, `point_in_polygon`, `polygon_area_km2`, `path_length_km`), DB radius search (`GeoPointMixin` + `GeoRepositoryMixin`/`PostGISRepositoryMixin`, `make_geo_point_model`), routing (`OSRMBackend`/`RoutingBackend` — `route` + `route(with_geometry=True)` + `matrix`, per-mode profiles), geocoding (`NominatimBackend`/`GeocodingBackend`), polyline codec (`encode_polyline`/`decode_polyline`), Brazil (`uf_centroid`/`UF_CENTROIDS`, `cep_to_coordinate`); `Coordinate`/`TravelEstimate`/`TravelMode` (car/motorcycle/bus/bicycle/pedestrian)/`BoundingBox`/`GeocodeResult`/`DistanceMatrix` |
+| `tempest_fastapi_sdk.openapi` | `generate_integration`, `load_spec`, `parse_spec`, `emit_schemas`, `emit_client`, `GenerationResult`, `default_output_dir`, `SpecError`, `SpecIR` / `SchemaIR` / `FieldIR` / `ClientIR` / `OperationIR` / `ParameterIR` — backs `tempest openapi-client`, which generates Pydantic schemas + a typed HTTP client from a third party's OpenAPI spec *(YAML needs the `[openapi]` extra)* |
+| `tempest_fastapi_sdk.queue` *(extra: `[queue]`)* | `MessageBroker` (typed, transport-agnostic FastStream facade — `.rabbitmq`/`.redis`/`.kafka`/`.nats`, `@mq.on(channel)`, channel-first `publish`); class-based consumers (`Consumer` + `@subscribe` + `MessageBroker.register`); `AsyncQueueManager` (thin lifecycle wrapper, formerly `AsyncBrokerManager`) |
+| `tempest_fastapi_sdk.reviews` | Comments + 0–5 star ratings on any polymorphic target: `BaseCommentModel`/`BaseRatingModel` (+ `make_*`), `ReviewService` (`add_comment`/`list_comments`/`rate` upsert/`get_user_rating`/`aggregate`), `make_reviews_router` (opt-in), `RatingField` |
+| `tempest_fastapi_sdk.schemas` | `BaseSchema`, `BaseResponseSchema`, `ErrorResponseSchema`, `BasePaginationFilterSchema`, `BasePaginationSchema[T]`, `CursorPaginationFilterSchema`, `CursorPaginationSchema`, `LogEntrySchema`, `encode_cursor`, `decode_cursor`, `build_pagination_link_header` |
+| `tempest_fastapi_sdk.services` | `BaseService` |
+| `tempest_fastapi_sdk.settings` | `BaseAppSettings` (+ `AppSettingsMeta`), `ServerSettings`, `LogSettings`, `DatabaseSettings`, `RedisSettings`, `RabbitMQSettings`, `JWTSettings`, `CORSSettings`, `EmailSettings`, `UploadSettings`, `TokenSettings`, `WebPushSettings`, `TaskIQSettings`, `MinIOSettings`, `AuthSettings` |
+| `tempest_fastapi_sdk.sse` | `EventStream` (bounded queue + `overflow` backpressure), `SSEBroker` (multi-worker fan-out via Redis, `.response()` lifecycle helper), `ServerSentEvent`, `sse_response` (`on_disconnect=` cleanup) |
 | `tempest_fastapi_sdk.ssr` *(extra: `[ssr]`)* | `Page` (typed component base), `html_response` (widget tree → `HTMLResponse`, full document or HTMX fragment), `make_htmx_router` (serves bundled HTMX locally, no CDN); `htmx()` / `aria()` / `data()` (typed builders for the `hx-*` / `aria-*` / `data-*` `attrs` map); `make_web_app_router` (serve a compiled static/wasm `tempestweb build` as a router, SPA history fallback), `build_web_app` (host a server-mode build as a WS/SSE sub-app), `detect_build_mode` |
+| `tempest_fastapi_sdk.storage` *(extra: `[minio]`)* | `AsyncMinIOClient` (+ batch `presigned_get_urls` / `put_objects` / `get_objects_bytes`), `ObjectStat`, `PutObjectItem` — async MinIO/S3 facade |
+| `tempest_fastapi_sdk.tasks` *(extra: `[tasks]`)* | `TaskQueue` (typed TaskIQ facade — `.rabbitmq`/`.redis`/`.memory`, `@tq.task` → `Task.enqueue`/`.run`, `@tq.cron`/`@tq.interval`, `start_scheduler`), `Task`; class-based tasks (`TaskDef` + `@task_method` + `TaskQueue.register`); cron helpers (`Cron` / `CronOffset` / `Weekday` + `daily`/`weekdays`/`every_n_minutes`/… builders); `AsyncTaskBrokerManager` / `AsyncTaskScheduler` (legacy wrappers) |
 | `tempest_fastapi_sdk.utils` | `to_utc`, `utcnow`, `modify_dict`, `LogUtils`, `AttemptThrottle`/`ThrottleBackend`/`ThrottleStatus`, `generate_opaque_token`/`hash_opaque_token`/`verify_opaque_token`, `get_client_ip`/`get_client_ip_from_scope`, `PasswordUtils` *(extra: `[auth]`)*, `JWTUtils` *(extra: `[auth]`)*, `TOTPHelper` *(extra: `[mfa]`)*, `EmailUtils` *(extra: `[email]`)*, `UploadUtils`/`sniff_mime` *(extra: `[upload]`)*, `DownloadUtils`/`build_content_disposition` *(no extra)*, `FileStoreUtils` — unified upload+download+presign facade *(extra: `[upload]` local / `[minio]` MinIO)*, `MetricsUtils`/`CPUMetrics`/`MemoryMetrics`/`DiskMetrics`/`GPUMetrics`/`SystemMetrics` *(extra: `[metrics]`)*, validated field types (`PositiveIntField`, `NonNegativeIntField`, `CentsField`, `PortField`, `PositiveFloatField`, `NonNegativeFloatField`, `PercentField`, `RatingField`, `RatioField`, `LatitudeField`, `LongitudeField`, `PriceField`, `NonEmptyStrField`, `SlugField`, `HexColorField`, `LocaleField`), BR regex helpers (`CPFField`, `CNPJField`, `CPFOrCNPJField`, `PhoneBRField`, `CEPField`, `PixKeyField` — old names without the suffix kept as deprecated aliases — `PixKeyType`/`detect_pix_key_type`/`is_valid_pix_key`, `is_valid_*`, `normalize_*`, `only_digits`, `*_PATTERN`), BR states/cities (`UF`, `Region`, `StateBR`, `CityBR`, `ChoiceBR`, `UFField`, `CityNameField`, `list_states`, `get_state`, `cities_by_uf`, `states_by_region`, `uf_choices`/`region_choices`/`city_choices`, `is_valid_uf`/`normalize_uf`, `is_valid_city`/`normalize_city`) |
-| `tempest_fastapi_sdk.cli` | `tempest` console script — `new <name>` (scaffold layered service), `lint` / `format` / `fmt-check` / `type` / `test` / `check` (run preferred quality gates), `check-config` (validate settings via the system-check framework), `version` / `--version`; plus project-registered management commands (`tempest <cmd>` from `src/commands.py` or `[tool.tempest] commands`) |
+| `tempest_fastapi_sdk.utils.http_client` *(extra: `[http]`)* | `HTTPClient`, `RetryPolicy`, `CircuitOpenError`, `REQUEST_ID_HEADER` — typed httpx wrapper |
+| `tempest_fastapi_sdk.utils.storage_backends` *(extra: `[upload]`)* | `UploadStorage` protocol, `LocalUploadStorage`, `MinIOUploadStorage`, `UploadResult`, `ContentValidator` |
+| `tempest_fastapi_sdk.vision` *(extra: `[vision]`)* | `Detector`, `Classifier`, `Segmenter` (ONNX, lazy), `DetectionSchema`/`ClassificationSchema`/`SegmentationSchema`/`BoundingBoxSchema`/`ClassProbabilitySchema`, `to_detection_schemas`/`to_classification_schema`/`to_segmentation_schemas`, `make_vision_router` (opt-in `POST /classify` / `/detect` / `/segment`) |
+| `tempest_fastapi_sdk.webpush` *(extra: `[webpush]`)* | `WebPushDispatcher`, `WebPushSubscriptionService`, `make_web_push_router`, `WebPushError`, `WebPushGoneError`, `WebPushSubscriptionSchema`, `WebPushKeysSchema`, `WebPushPayloadSchema` |
 Core primitives are re-exported from `tempest_fastapi_sdk` at the top level — `from tempest_fastapi_sdk import BaseModel, BaseRepository, AppException` always works. The extras-gated managers in `tempest_fastapi_sdk.cache`, `tempest_fastapi_sdk.queue`, `tempest_fastapi_sdk.tasks`, `tempest_fastapi_sdk.vision`, `tempest_fastapi_sdk.genai` and `tempest_fastapi_sdk.ssr` — plus the domain modules `tempest_fastapi_sdk.chat` and `tempest_fastapi_sdk.reviews` — must be imported from their own submodule (`from tempest_fastapi_sdk.queue import MessageBroker`).
@@ -4169,6 +4169,27 @@ async def delete_order(
 The user parameter is found by annotation (`user_param=` breaks a tie), and a guard's non-`None` return replaces the user the body sees — which is how `require_active` narrows `UserT | None` to `UserT`.
+A guard may declare a second parameter to receive a `dict[str, Any]` of metadata, which is what turns one generic guard into a specific check per call site — `meta=` carries literals fixed at decoration, `include_args=True` merges the call's own arguments:
+```python
+def has_role(user: UserModel, meta: dict[str, Any]) -> UserModel:
+    """Deny unless the user holds the role the route declared."""
+    if meta["role"] not in user.roles:
+        raise MissingRoleException(role=meta["role"])
+    return user
+@requires(has_role, meta={"role": "manager"})
+async def close_month(user: UserModel = Depends(get_current_user)) -> None: ...
+@requires(order_owner, include_args=True)      # guard reads meta["order_id"]
+async def delete_order(
+    order_id: UUID,
+    user: UserModel = Depends(get_current_user),
+) -> None: ...
+```
 Misuse is caught in three places: `TempestPermissionError` at import time (no guard, wrong arity, `async` guard on a sync function, no user parameter), `GuardContractWarning` at call time (a guard raising outside the `AppException` hierarchy, or returning `False` instead of denying), and `tempest permissions --check` in CI, which reads the same contract statically.
 ```bash

{tempest_fastapi_sdk-0.167.2 → tempest_fastapi_sdk-0.168.1}/README.md RENAMED Viewed

@@ -149,37 +149,37 @@ Since `0.7.1` every optional dependency is imported lazily at first instantiatio
 | Module | Exports |
 | --- | --- |
-| `tempest_fastapi_sdk.openapi` | `generate_integration`, `load_spec`, `parse_spec`, `emit_schemas`, `emit_client`, `GenerationResult`, `default_output_dir`, `SpecError`, `SpecIR` / `SchemaIR` / `FieldIR` / `ClientIR` / `OperationIR` / `ParameterIR` — backs `tempest openapi-client`, which generates Pydantic schemas + a typed HTTP client from a third party's OpenAPI spec *(YAML needs the `[openapi]` extra)* |
-| `tempest_fastapi_sdk.schemas` | `BaseSchema`, `BaseResponseSchema`, `ErrorResponseSchema`, `BasePaginationFilterSchema`, `BasePaginationSchema[T]`, `CursorPaginationFilterSchema`, `CursorPaginationSchema`, `LogEntrySchema`, `encode_cursor`, `decode_cursor`, `build_pagination_link_header` |
-| `tempest_fastapi_sdk.db` | `BaseModel`, `BaseUserModel`, `BaseUserTokenModel`, `BaseUserRecoveryCodeModel`, `make_user_recovery_code_model`, `UserTokenPurpose`, `BaseRepository[ModelType]`, `TenantScopedRepository[ModelType]`, `AsyncDatabaseManager`, `AlembicHelper` (+ `safe_upgrade`), `DestructiveMigrationError`, `NAMING_CONVENTION`, `AuditMixin`, `SoftDeleteMixin`, `MFAMixin`, `LocaleColumnMixin`, `BASE_COLUMN_ORDER`, `reorder_base_columns_first`, `compose_hooks`, `SlowQueryLogger`, `BaseOutboxModel`, `OutboxRelay`, `OutboxStatus`, `BaseRepository.save_with_outbox`, audit trail (`BaseAuditLogModel`, `AuditAction`, `snapshot_model`, `diff_snapshots`, `BaseRepository.add_audited` / `update_audited` / `delete_audited`), eager-loading (`get`/`get_or_none`/`get_by_id`/`first`/`list` accept `with_=[...]`, dotted for nested), lifecycle signals (`RepositorySignal`, `connect` / `on_signal` / `disconnect`, `PRE_SAVE`/`POST_SAVE`/`PRE_DELETE`/`POST_DELETE`), `F` / `Q` expression wrappers (`F("stock") - 1` atomic updates; `Q(...) | Q(...)` OR/NOT via `where=`), `BaseWebPushSubscriptionModel` + `make_web_push_subscription_model` |
-| `tempest_fastapi_sdk.exceptions` | `AppException`, `NotFoundException`, `ConflictException`, `ValidationException`, `UnauthorizedException`, `ForbiddenException`, `InvalidTokenException`, `ExpiredTokenException`, `FileTooLargeException`, `InvalidFileTypeException`, `TooManyRequestsException`, `InheritedErrorCodeWarning`, i18n (`MessageCatalog`, `default_message_catalog`, `parse_accept_language`, `DEFAULT_LOCALE`) |
-| `tempest_fastapi_sdk.settings` | `BaseAppSettings` (+ `AppSettingsMeta`), `ServerSettings`, `LogSettings`, `DatabaseSettings`, `RedisSettings`, `RabbitMQSettings`, `JWTSettings`, `CORSSettings`, `EmailSettings`, `UploadSettings`, `TokenSettings`, `WebPushSettings`, `TaskIQSettings`, `MinIOSettings`, `AuthSettings` |
+| `tempest_fastapi_sdk.admin` *(extra: `[admin]`)* | `AdminSite`, `AdminModel` (incl. `audit_model=...` for a per-row audit-history timeline, `autocomplete_fields=[...]` for HTMX-searched FK inputs, `inlines=[Inline(...)]` for 1-N children on the detail view, `Inline(editable=True, can_delete=True)` for in-place formset editing of those children), `Inline`, dashboard business-metric cards (`AdminSite(dashboard_cards=[...])`: `MetricCard` + `MetricValue` / `MetricTrend` / `MetricPartition`), CSV import (`AdminModel(can_import=True)`), granular RBAC (`make_admin_router(access_policy=...)` + `AdminPermission`), lenses (`AdminModel(lenses=[Lens(...)])` saved list presets), JSON + time field widgets, `make_admin_router`, `AdminAuthBackend`, `UserModelAuthBackend`, `AdminAuthError` |
 | `tempest_fastapi_sdk.api` | `register_exception_handlers`, `app_exception_handler`, OpenAPI error docs (`error_responses`, `raises`, `TempestAPIRouter`, `RaisesSpec`, `declared_raises`), `apply_cors`, `make_health_router`, `make_logs_router`, `make_prometheus_router`, `make_prometheus_registry`, `PrometheusMiddleware`, `BusinessMetrics`, `LogSource`, `make_tool_spec_router`, `make_token_dependency`, `make_bearer_token_dependency`, `make_jwt_user_dependency`, `make_role_dependency`, `make_permission_dependency`, `require_x_token`, `run_server`, `RequestIDMiddleware`, `RateLimitMiddleware` (+ `RateLimitStore`/`MemoryRateLimitStore`/`RedisRateLimitStore`/`RateLimitResult` and `key_by_ip`/`key_by_jwt_subject`/`key_by_jwt_claim`/`key_by_header`), `IdempotencyMiddleware`, `MemoryIdempotencyStore`, `RedisIdempotencyStore`, `BodySizeLimitMiddleware`, `CSRFMiddleware`, `make_csrf_token_dependency`, `GracefulShutdownMiddleware`, `WebhookSignatureVerifier`, `RSAWebhookSignatureVerifier`, outbound `WebhookSender` (+ `WebhookDelivery`), OAuth2 (`GoogleOAuthClient`, `GitHubOAuthClient`, `OIDCProvider`), `HardenedStaticFiles`, `DEFAULT_STATIC_SECURITY_HEADERS`, `make_spa_router` (serve a compiled React/Vite SPA with a client-side fallback), `set_cookie`, `clear_cookie`, `SameSite`, `HealthCheck`, `setup_tracing` *(extra: `[otel]`)* |
 | `tempest_fastapi_sdk.auth` *(extra: `[auth]`, opcional `[email]`, `[mfa]`)* | `UserAuthService`, `make_auth_router`, `SignupSchema` / `LoginSchema` / `RefreshSchema` / `PasswordResetRequestSchema` / `PasswordResetConfirmSchema` + responses, `ActivationToken`, `PasswordResetToken`, email change/verify/recovery (`EmailChangeRequestSchema` / `EmailChangeConfirmSchema` / `EmailRecoveryRequestSchema` / `EmailChangeToken` / `EmailVerificationToken`, old-email security notice, opt-in `AUTH_EMAIL_RECOVERY_ENABLED`), MFA schemas (`MFAEnrollResponseSchema` / `MFAConfirmSchema` / `MFAVerifySchema` / `MFADisableSchema`), opt-in DB-backed refresh tokens (`BaseUserRefreshTokenModel` / `make_user_refresh_token_model` / `LogoutSchema`) with rotation + reuse detection + `POST /auth/logout`, bilingual emails + backend pages (`AUTH_DEFAULT_LOCALE`, `normalize_locale` / `negotiate_locale`) — signup/activate/login/refresh/logout/reset + email change/recovery + TOTP 2FA out of the box |
-| `tempest_fastapi_sdk.authz` | Object-level permissions: `permission` (rule decorator), `has_perm` / `check_permission`, `PermissionRegistry` (injectable superuser bypass + static-permission fallback, `order.*`/`*` wildcards), `make_permission_checker` (FastAPI route guard), `PermissionMixin` (`await user.has_perm(perm, obj=...)`), `default_registry`, `requires` (guard decorator `(user) -> user | None`, checked at import time + by `tempest permissions`), `declared_guards` / `guarded_user_param`, `TempestPermissionError`, `GuardContractWarning` |
+| `tempest_fastapi_sdk.authz` | Object-level permissions: `permission` (rule decorator), `has_perm` / `check_permission`, `PermissionRegistry` (injectable superuser bypass + static-permission fallback, `order.*`/`*` wildcards), `make_permission_checker` (FastAPI route guard), `PermissionMixin` (`await user.has_perm(perm, obj=...)`), `default_registry`, `requires` (guard decorator `(user) -> user | None`, optional `meta: dict[str, Any]` second parameter via `meta=` / `include_args=`, checked at import time + by `tempest permissions`), `declared_guards` / `guarded_user_param` / `guard_metadata`, `TempestPermissionError`, `GuardContractWarning` |
+| `tempest_fastapi_sdk.cache` *(extra: `[cache]`)* | `AsyncRedisManager`, `cached` (with `namespace` / `tags`), `CacheInvalidator`, `namespace_registry_key`, `tag_registry_key` |
+| `tempest_fastapi_sdk.chat` | Threaded chat: abstract tables `BaseConversationModel`/`BaseConversationParticipantModel`/`BaseMessageModel` (+ `make_*` factories), `ChatService` (`start_conversation`/`post_message`/`list_messages`/`list_conversations`), `make_chat_router` (opt-in), real-time fan-out via an injected `SSEBroker` |
 | `tempest_fastapi_sdk.checks` | System checks (Django-style config validation): `check` (register decorator), `run_checks` / `run_system_checks` (raises `SystemCheckError` on ERROR+), `CheckMessage` / `CheckLevel` + `debug`/`info`/`warning`/`error`/`critical`, `CheckRegistry` / `default_registry`; built-in settings checks + the `tempest check-config` CLI (auto-detects settings, `--tag` / `--fail-level`) |
+| `tempest_fastapi_sdk.cli` | `tempest` console script — `new <name>` (scaffold layered service), `lint` / `format` / `fmt-check` / `type` / `test` / `check` (run preferred quality gates), `check-config` (validate settings via the system-check framework), `version` / `--version`; plus project-registered management commands (`tempest <cmd>` from `src/commands.py` or `[tool.tempest] commands`) |
 | `tempest_fastapi_sdk.controllers` | `BaseController` |
-| `tempest_fastapi_sdk.services` | `BaseService` |
 | `tempest_fastapi_sdk.core` | `configure_logging`, `JSONFormatter`, `get_request_id`/`set_request_id`/`clear_request_id`, `request_id_ctx`, `BaseStrEnum`, `BaseIntEnum`, `Locale` (BCP-47 locale enum), `strict_types`/`typed`/`require_annotations` |
-| `tempest_fastapi_sdk.admin` *(extra: `[admin]`)* | `AdminSite`, `AdminModel` (incl. `audit_model=...` for a per-row audit-history timeline, `autocomplete_fields=[...]` for HTMX-searched FK inputs, `inlines=[Inline(...)]` for 1-N children on the detail view, `Inline(editable=True, can_delete=True)` for in-place formset editing of those children), `Inline`, dashboard business-metric cards (`AdminSite(dashboard_cards=[...])`: `MetricCard` + `MetricValue` / `MetricTrend` / `MetricPartition`), CSV import (`AdminModel(can_import=True)`), granular RBAC (`make_admin_router(access_policy=...)` + `AdminPermission`), lenses (`AdminModel(lenses=[Lens(...)])` saved list presets), JSON + time field widgets, `make_admin_router`, `AdminAuthBackend`, `UserModelAuthBackend`, `AdminAuthError` |
-| `tempest_fastapi_sdk.sse` | `EventStream` (bounded queue + `overflow` backpressure), `SSEBroker` (multi-worker fan-out via Redis, `.response()` lifecycle helper), `ServerSentEvent`, `sse_response` (`on_disconnect=` cleanup) |
-| `tempest_fastapi_sdk.cache` *(extra: `[cache]`)* | `AsyncRedisManager`, `cached` (with `namespace` / `tags`), `CacheInvalidator`, `namespace_registry_key`, `tag_registry_key` |
+| `tempest_fastapi_sdk.db` | `BaseModel`, `BaseUserModel`, `BaseUserTokenModel`, `BaseUserRecoveryCodeModel`, `make_user_recovery_code_model`, `UserTokenPurpose`, `BaseRepository[ModelType]`, `TenantScopedRepository[ModelType]`, `AsyncDatabaseManager`, `AlembicHelper` (+ `safe_upgrade`), `DestructiveMigrationError`, `NAMING_CONVENTION`, `AuditMixin`, `SoftDeleteMixin`, `MFAMixin`, `LocaleColumnMixin`, `BASE_COLUMN_ORDER`, `reorder_base_columns_first`, `compose_hooks`, `SlowQueryLogger`, `BaseOutboxModel`, `OutboxRelay`, `OutboxStatus`, `BaseRepository.save_with_outbox`, audit trail (`BaseAuditLogModel`, `AuditAction`, `snapshot_model`, `diff_snapshots`, `BaseRepository.add_audited` / `update_audited` / `delete_audited`), eager-loading (`get`/`get_or_none`/`get_by_id`/`first`/`list` accept `with_=[...]`, dotted for nested), lifecycle signals (`RepositorySignal`, `connect` / `on_signal` / `disconnect`, `PRE_SAVE`/`POST_SAVE`/`PRE_DELETE`/`POST_DELETE`), `F` / `Q` expression wrappers (`F("stock") - 1` atomic updates; `Q(...) | Q(...)` OR/NOT via `where=`), `BaseWebPushSubscriptionModel` + `make_web_push_subscription_model` |
+| `tempest_fastapi_sdk.exceptions` | `AppException`, `NotFoundException`, `ConflictException`, `ValidationException`, `UnauthorizedException`, `ForbiddenException`, `InvalidTokenException`, `ExpiredTokenException`, `FileTooLargeException`, `InvalidFileTypeException`, `TooManyRequestsException`, `InheritedErrorCodeWarning`, i18n (`MessageCatalog`, `default_message_catalog`, `parse_accept_language`, `DEFAULT_LOCALE`) |
 | `tempest_fastapi_sdk.flags` | `FeatureFlags`, `FeatureFlagBackend`, `MemoryFeatureFlagBackend`, `EnvFeatureFlagBackend`, `RedisFeatureFlagBackend`, `CompositeFeatureFlagBackend`, `make_flag_dependency`, `coerce_flag` |
-| `tempest_fastapi_sdk.webpush` *(extra: `[webpush]`)* | `WebPushDispatcher`, `WebPushSubscriptionService`, `make_web_push_router`, `WebPushError`, `WebPushGoneError`, `WebPushSubscriptionSchema`, `WebPushKeysSchema`, `WebPushPayloadSchema` |
-| `tempest_fastapi_sdk.queue` *(extra: `[queue]`)* | `MessageBroker` (typed, transport-agnostic FastStream facade — `.rabbitmq`/`.redis`/`.kafka`/`.nats`, `@mq.on(channel)`, channel-first `publish`); class-based consumers (`Consumer` + `@subscribe` + `MessageBroker.register`); `AsyncQueueManager` (thin lifecycle wrapper, formerly `AsyncBrokerManager`) |
-| `tempest_fastapi_sdk.storage` *(extra: `[minio]`)* | `AsyncMinIOClient` (+ batch `presigned_get_urls` / `put_objects` / `get_objects_bytes`), `ObjectStat`, `PutObjectItem` — async MinIO/S3 facade |
-| `tempest_fastapi_sdk.utils.http_client` *(extra: `[http]`)* | `HTTPClient`, `RetryPolicy`, `CircuitOpenError`, `REQUEST_ID_HEADER` — typed httpx wrapper |
-| `tempest_fastapi_sdk.utils.storage_backends` *(extra: `[upload]`)* | `UploadStorage` protocol, `LocalUploadStorage`, `MinIOUploadStorage`, `UploadResult`, `ContentValidator` |
-| `tempest_fastapi_sdk.tasks` *(extra: `[tasks]`)* | `TaskQueue` (typed TaskIQ facade — `.rabbitmq`/`.redis`/`.memory`, `@tq.task` → `Task.enqueue`/`.run`, `@tq.cron`/`@tq.interval`, `start_scheduler`), `Task`; class-based tasks (`TaskDef` + `@task_method` + `TaskQueue.register`); cron helpers (`Cron` / `CronOffset` / `Weekday` + `daily`/`weekdays`/`every_n_minutes`/… builders); `AsyncTaskBrokerManager` / `AsyncTaskScheduler` (legacy wrappers) |
-| `tempest_fastapi_sdk.vision` *(extra: `[vision]`)* | `Detector`, `Classifier`, `Segmenter` (ONNX, lazy), `DetectionSchema`/`ClassificationSchema`/`SegmentationSchema`/`BoundingBoxSchema`/`ClassProbabilitySchema`, `to_detection_schemas`/`to_classification_schema`/`to_segmentation_schemas`, `make_vision_router` (opt-in `POST /classify` / `/detect` / `/segment`) |
 | `tempest_fastapi_sdk.genai` *(extra: `[genai]`; capacity check imports without it)* | Self-hosted GenAI: capacity check (`probe_hardware`/`HardwareInfo`, `can_run`/`recommend`/`CapacityReport`, `estimate_model_bytes`/`fetch_num_params`, `ModelDtype`); local LLM `TextGenerator` (`generate`/`chat`/`stream`, typed `GenerationConfig`, int4/int8 quant, lazy load + idle unload); `Embedder` (+ `EmbeddingCache`/`InMemoryEmbeddingCache`/`RedisEmbeddingCache`/`AsyncEmbeddingCache`, `normalize=`) + `cosine_similarity`, `BatchScheduler` (coalesce concurrent calls), `ModelRegistry` (LRU model sharing); `make_genai_router` (opt-in endpoints — `/generate`+SSE, `/chat`, `/embed`, `/rag`, `/transcribe`, `/tts`); `resolve_device`/`auto_dtype_name`; **tool calling** (`TextGenerator.chat_with_tools` / `OllamaGenerator.chat_with_tools`) + **structured output** (`generate_structured` — Ollama `format=`, transformers `lm-format-enforcer` via `[genai-structured]`; `parse_structured`); **`VisionTextGenerator`** (local VLM, `[genai-vlm]`); **`OnnxEmbedder`** (torch-free embeddings, `[genai-onnx]`); **generation cache** (`InMemoryGenerationCache`/`RedisGenerationCache`, deterministic-only) via `generation_cache=`; **token/context** (`count_tokens`/`count_message_tokens`/`truncate_messages`); **`GenAIMetrics`** (Prometheus request/latency/token metrics, `[prometheus]`); **moderation** (`RuleModerator`/`ClassifierModerator` + `ModerationResult`); Ollama backend (`[genai-ollama]`) — `OllamaGenerator`/`OllamaEmbedder` (HTTP, no torch) behind the `TextBackend` protocol, drop-in for `make_genai_router`/`Retriever`, plus vision (`generate(images=…)`); **`AIChatPipeline`** (memory recall → web-search augment → generate w/ bounded tool-calling loop → TTS → memory index) + `Tool` + `make_ai_chat_router` (`POST /chat` + `/chat/stream` SSE) |
-| `tempest_fastapi_sdk.chat` | Threaded chat: abstract tables `BaseConversationModel`/`BaseConversationParticipantModel`/`BaseMessageModel` (+ `make_*` factories), `ChatService` (`start_conversation`/`post_message`/`list_messages`/`list_conversations`), `make_chat_router` (opt-in), real-time fan-out via an injected `SSEBroker` |
-| `tempest_fastapi_sdk.reviews` | Comments + 0–5 star ratings on any polymorphic target: `BaseCommentModel`/`BaseRatingModel` (+ `make_*`), `ReviewService` (`add_comment`/`list_comments`/`rate` upsert/`get_user_rating`/`aggregate`), `make_reviews_router` (opt-in), `RatingField` |
 | `tempest_fastapi_sdk.genai.rag` *(extra: `[genai-rag]`)* | RAG context for local LLMs: `WebSearch` (`.retrieve` one-shot search→extract→context) / `SearxngBackend` / `WebSearchBackend` + `SearchResult`, `ContentExtractor` (trafilatura, `.extract_many` concurrent), `PdfReader` (PyMuPDF) + `Document`/`Chunk`/`PdfPage`, `chunk_text`, `build_context`; corpus RAG — `Retriever` + `VectorStore`/`InMemoryVectorStore`/`PgVectorStore` (pgvector)/`ChromaVectorStore` (`[genai-chroma]`); **`Reranker`** (cross-encoder second stage) + **`HybridRetriever`** (BM25 + dense, `reciprocal_rank_fusion`, `rank-bm25`); long-term chat memory — `ChatMemory` (recency-aware, per-user, Chroma-backed) + `MemoryHit`; audio (`[genai-audio]`) — `SpeechToText` (faster-whisper, `beam_size`/`vad_filter`/`language_probability`) + `TextToSpeech` (Coqui TTS) + `Transcription` |
 | `tempest_fastapi_sdk.geo` *(extra: `[geo]`; offline layers import without it)* | Geolocation without a paid API: `haversine_km`, `estimate_travel` (offline road distance + per-mode time), offline geometry (`bounding_box`, `within_radius`, `nearest`, `initial_bearing`, `destination_point`, `point_in_polygon`, `polygon_area_km2`, `path_length_km`), DB radius search (`GeoPointMixin` + `GeoRepositoryMixin`/`PostGISRepositoryMixin`, `make_geo_point_model`), routing (`OSRMBackend`/`RoutingBackend` — `route` + `route(with_geometry=True)` + `matrix`, per-mode profiles), geocoding (`NominatimBackend`/`GeocodingBackend`), polyline codec (`encode_polyline`/`decode_polyline`), Brazil (`uf_centroid`/`UF_CENTROIDS`, `cep_to_coordinate`); `Coordinate`/`TravelEstimate`/`TravelMode` (car/motorcycle/bus/bicycle/pedestrian)/`BoundingBox`/`GeocodeResult`/`DistanceMatrix` |
+| `tempest_fastapi_sdk.openapi` | `generate_integration`, `load_spec`, `parse_spec`, `emit_schemas`, `emit_client`, `GenerationResult`, `default_output_dir`, `SpecError`, `SpecIR` / `SchemaIR` / `FieldIR` / `ClientIR` / `OperationIR` / `ParameterIR` — backs `tempest openapi-client`, which generates Pydantic schemas + a typed HTTP client from a third party's OpenAPI spec *(YAML needs the `[openapi]` extra)* |
+| `tempest_fastapi_sdk.queue` *(extra: `[queue]`)* | `MessageBroker` (typed, transport-agnostic FastStream facade — `.rabbitmq`/`.redis`/`.kafka`/`.nats`, `@mq.on(channel)`, channel-first `publish`); class-based consumers (`Consumer` + `@subscribe` + `MessageBroker.register`); `AsyncQueueManager` (thin lifecycle wrapper, formerly `AsyncBrokerManager`) |
+| `tempest_fastapi_sdk.reviews` | Comments + 0–5 star ratings on any polymorphic target: `BaseCommentModel`/`BaseRatingModel` (+ `make_*`), `ReviewService` (`add_comment`/`list_comments`/`rate` upsert/`get_user_rating`/`aggregate`), `make_reviews_router` (opt-in), `RatingField` |
+| `tempest_fastapi_sdk.schemas` | `BaseSchema`, `BaseResponseSchema`, `ErrorResponseSchema`, `BasePaginationFilterSchema`, `BasePaginationSchema[T]`, `CursorPaginationFilterSchema`, `CursorPaginationSchema`, `LogEntrySchema`, `encode_cursor`, `decode_cursor`, `build_pagination_link_header` |
+| `tempest_fastapi_sdk.services` | `BaseService` |
+| `tempest_fastapi_sdk.settings` | `BaseAppSettings` (+ `AppSettingsMeta`), `ServerSettings`, `LogSettings`, `DatabaseSettings`, `RedisSettings`, `RabbitMQSettings`, `JWTSettings`, `CORSSettings`, `EmailSettings`, `UploadSettings`, `TokenSettings`, `WebPushSettings`, `TaskIQSettings`, `MinIOSettings`, `AuthSettings` |
+| `tempest_fastapi_sdk.sse` | `EventStream` (bounded queue + `overflow` backpressure), `SSEBroker` (multi-worker fan-out via Redis, `.response()` lifecycle helper), `ServerSentEvent`, `sse_response` (`on_disconnect=` cleanup) |
 | `tempest_fastapi_sdk.ssr` *(extra: `[ssr]`)* | `Page` (typed component base), `html_response` (widget tree → `HTMLResponse`, full document or HTMX fragment), `make_htmx_router` (serves bundled HTMX locally, no CDN); `htmx()` / `aria()` / `data()` (typed builders for the `hx-*` / `aria-*` / `data-*` `attrs` map); `make_web_app_router` (serve a compiled static/wasm `tempestweb build` as a router, SPA history fallback), `build_web_app` (host a server-mode build as a WS/SSE sub-app), `detect_build_mode` |
+| `tempest_fastapi_sdk.storage` *(extra: `[minio]`)* | `AsyncMinIOClient` (+ batch `presigned_get_urls` / `put_objects` / `get_objects_bytes`), `ObjectStat`, `PutObjectItem` — async MinIO/S3 facade |
+| `tempest_fastapi_sdk.tasks` *(extra: `[tasks]`)* | `TaskQueue` (typed TaskIQ facade — `.rabbitmq`/`.redis`/`.memory`, `@tq.task` → `Task.enqueue`/`.run`, `@tq.cron`/`@tq.interval`, `start_scheduler`), `Task`; class-based tasks (`TaskDef` + `@task_method` + `TaskQueue.register`); cron helpers (`Cron` / `CronOffset` / `Weekday` + `daily`/`weekdays`/`every_n_minutes`/… builders); `AsyncTaskBrokerManager` / `AsyncTaskScheduler` (legacy wrappers) |
 | `tempest_fastapi_sdk.utils` | `to_utc`, `utcnow`, `modify_dict`, `LogUtils`, `AttemptThrottle`/`ThrottleBackend`/`ThrottleStatus`, `generate_opaque_token`/`hash_opaque_token`/`verify_opaque_token`, `get_client_ip`/`get_client_ip_from_scope`, `PasswordUtils` *(extra: `[auth]`)*, `JWTUtils` *(extra: `[auth]`)*, `TOTPHelper` *(extra: `[mfa]`)*, `EmailUtils` *(extra: `[email]`)*, `UploadUtils`/`sniff_mime` *(extra: `[upload]`)*, `DownloadUtils`/`build_content_disposition` *(no extra)*, `FileStoreUtils` — unified upload+download+presign facade *(extra: `[upload]` local / `[minio]` MinIO)*, `MetricsUtils`/`CPUMetrics`/`MemoryMetrics`/`DiskMetrics`/`GPUMetrics`/`SystemMetrics` *(extra: `[metrics]`)*, validated field types (`PositiveIntField`, `NonNegativeIntField`, `CentsField`, `PortField`, `PositiveFloatField`, `NonNegativeFloatField`, `PercentField`, `RatingField`, `RatioField`, `LatitudeField`, `LongitudeField`, `PriceField`, `NonEmptyStrField`, `SlugField`, `HexColorField`, `LocaleField`), BR regex helpers (`CPFField`, `CNPJField`, `CPFOrCNPJField`, `PhoneBRField`, `CEPField`, `PixKeyField` — old names without the suffix kept as deprecated aliases — `PixKeyType`/`detect_pix_key_type`/`is_valid_pix_key`, `is_valid_*`, `normalize_*`, `only_digits`, `*_PATTERN`), BR states/cities (`UF`, `Region`, `StateBR`, `CityBR`, `ChoiceBR`, `UFField`, `CityNameField`, `list_states`, `get_state`, `cities_by_uf`, `states_by_region`, `uf_choices`/`region_choices`/`city_choices`, `is_valid_uf`/`normalize_uf`, `is_valid_city`/`normalize_city`) |
-| `tempest_fastapi_sdk.cli` | `tempest` console script — `new <name>` (scaffold layered service), `lint` / `format` / `fmt-check` / `type` / `test` / `check` (run preferred quality gates), `check-config` (validate settings via the system-check framework), `version` / `--version`; plus project-registered management commands (`tempest <cmd>` from `src/commands.py` or `[tool.tempest] commands`) |
+| `tempest_fastapi_sdk.utils.http_client` *(extra: `[http]`)* | `HTTPClient`, `RetryPolicy`, `CircuitOpenError`, `REQUEST_ID_HEADER` — typed httpx wrapper |
+| `tempest_fastapi_sdk.utils.storage_backends` *(extra: `[upload]`)* | `UploadStorage` protocol, `LocalUploadStorage`, `MinIOUploadStorage`, `UploadResult`, `ContentValidator` |
+| `tempest_fastapi_sdk.vision` *(extra: `[vision]`)* | `Detector`, `Classifier`, `Segmenter` (ONNX, lazy), `DetectionSchema`/`ClassificationSchema`/`SegmentationSchema`/`BoundingBoxSchema`/`ClassProbabilitySchema`, `to_detection_schemas`/`to_classification_schema`/`to_segmentation_schemas`, `make_vision_router` (opt-in `POST /classify` / `/detect` / `/segment`) |
+| `tempest_fastapi_sdk.webpush` *(extra: `[webpush]`)* | `WebPushDispatcher`, `WebPushSubscriptionService`, `make_web_push_router`, `WebPushError`, `WebPushGoneError`, `WebPushSubscriptionSchema`, `WebPushKeysSchema`, `WebPushPayloadSchema` |
 Core primitives are re-exported from `tempest_fastapi_sdk` at the top level — `from tempest_fastapi_sdk import BaseModel, BaseRepository, AppException` always works. The extras-gated managers in `tempest_fastapi_sdk.cache`, `tempest_fastapi_sdk.queue`, `tempest_fastapi_sdk.tasks`, `tempest_fastapi_sdk.vision`, `tempest_fastapi_sdk.genai` and `tempest_fastapi_sdk.ssr` — plus the domain modules `tempest_fastapi_sdk.chat` and `tempest_fastapi_sdk.reviews` — must be imported from their own submodule (`from tempest_fastapi_sdk.queue import MessageBroker`).
@@ -4023,6 +4023,27 @@ async def delete_order(
 The user parameter is found by annotation (`user_param=` breaks a tie), and a guard's non-`None` return replaces the user the body sees — which is how `require_active` narrows `UserT | None` to `UserT`.
+A guard may declare a second parameter to receive a `dict[str, Any]` of metadata, which is what turns one generic guard into a specific check per call site — `meta=` carries literals fixed at decoration, `include_args=True` merges the call's own arguments:
+```python
+def has_role(user: UserModel, meta: dict[str, Any]) -> UserModel:
+    """Deny unless the user holds the role the route declared."""
+    if meta["role"] not in user.roles:
+        raise MissingRoleException(role=meta["role"])
+    return user
+@requires(has_role, meta={"role": "manager"})
+async def close_month(user: UserModel = Depends(get_current_user)) -> None: ...
+@requires(order_owner, include_args=True)      # guard reads meta["order_id"]
+async def delete_order(
+    order_id: UUID,
+    user: UserModel = Depends(get_current_user),
+) -> None: ...
+```
 Misuse is caught in three places: `TempestPermissionError` at import time (no guard, wrong arity, `async` guard on a sync function, no user parameter), `GuardContractWarning` at call time (a guard raising outside the `AppException` hierarchy, or returning `False` instead of denying), and `tempest permissions --check` in CI, which reads the same contract statically.
 ```bash

{tempest_fastapi_sdk-0.167.2 → tempest_fastapi_sdk-0.168.1}/docs/recipes/index.en.md RENAMED Viewed

@@ -279,59 +279,59 @@ come back here to plug in each capability as you need it.
 | Theme | Covers |
 | --- | --- |
-| **[Database »](database.md)** | `BaseModel`, `AsyncDatabaseManager`, `BaseRepository` (CRUD + filters + bulk), offset/cursor pagination, mixins, `AlembicHelper`, `SlowQueryLogger` |
-| **[Multi-tenant »](multi-tenant.md)** | `TenantScopedRepository` — `tenant_id` isolation on every query |
+| **[Admin site »](admin.md)** | `AdminSite`, `AdminModel`, `make_admin_router`, `BaseUserModel` |
 | **[Audit trail »](audit-trail.md)** | `BaseAuditLogModel`, `add_audited` / `update_audited` / `delete_audited`, `snapshot_model` / `diff_snapshots` |
-| **[Offline-first sync (delta) »](offline-sync.md)** | `BaseRepository.changes_since`, `SyncFilterSchema`, `SyncPaginationSchema`, cursor deltas + soft-delete |
-| **[HTTP layer »](http.md)** | `apply_cors`, `RequestIDMiddleware`, `RateLimitMiddleware`, `make_health_router`, JWT / role / permission dependencies, webhook signature verifier, pagination Link headers, tool-spec router |
-| **[HTTP client (outbound) »](http-client.md)** | `HTTPClient` — typed httpx with retry/backoff, circuit-breaker, X-Request-ID; `RetryPolicy`, `CircuitOpenError` |
-| **[Idempotency »](idempotency.md)** | `IdempotencyMiddleware`, `MemoryIdempotencyStore` / `IdempotencyStore` (Redis) — safe replay of POST/PUT/PATCH/DELETE |
-| **[Cache »](cache.md)** | `AsyncRedisManager`, `@cached` decorator, `CacheInvalidator` (tag/namespace) |
-| **[Feature flags »](feature-flags.md)** | `FeatureFlags`, env/Redis/composite backends, `make_flag_dependency` |
 | **[Auth flow (signup/reset) »](auth-flow.md)** | `UserAuthService`, `make_auth_router` — signup / activation / login / password reset, token delivery (bearer/cookie/both), `BaseUserModel` |
-| **[MFA (TOTP / 2FA) »](mfa.md)** | `MFAMixin`, `TOTPHelper`, enroll/confirm/verify/disable endpoints on `make_auth_router`, recovery codes |
-| **[Refresh tokens (rotation/revocation) »](refresh-tokens.md)** | `BaseUserRefreshTokenModel`, `make_user_refresh_token_model`, `issue_token_pair`, rotation + family reuse detection |
-| **[Server-side sessions »](sessions.md)** | `SessionMiddleware`, `SessionAuth`, `make_session_router`, `MemorySessionStore` / `RedisSessionStore` |
-| **[Real-time »](realtime.md)** | Overview — when to choose SSE, WebSocket or Web Push |
-| **[Server-Sent Events (SSE) »](sse.md)** | `EventStream`, `sse_response`, `ServerSentEvent`, `SSEBroker` (per-channel fan-out, Redis bridge) |
-| **[WebSocket router »](websocket.md)** | `WebSocketHub`, `make_websocket_router`, `broadcast` / `send_to`, heartbeat, bearer auth |
-| **[tempestweb frontend + SDK »](tempestweb-frontend.md)** | tempestweb frontend calling the SDK backend: `tempestweb.native.http`, `Idempotency-Key` + `IdempotencyMiddleware`, retry, same origin vs CORS |
-| **[Queue & Tasks »](queue-tasks.md)** | FastStream (`AsyncBrokerManager`), TaskIQ (`AsyncTaskBrokerManager`), `AsyncTaskScheduler`, transactional outbox |
-| **[Transactional outbox »](outbox.md)** | `BaseOutboxModel`, `OutboxRelay`, `save_with_outbox` — reliable events |
-| **[Transactional email »](email.md)** | `EmailUtils` — SMTP, text/HTML body, attachments, Jinja2 templates |
-| **[Web Push »](webpush.md)** | `WebPushDispatcher`, VAPID schemas, broadcast with pruning |
+| **[Brazilian helpers »](br-helpers.md)** | CPF / CNPJ / CEP / phone validation + normalization |
+| **[Cache »](cache.md)** | `AsyncRedisManager`, `@cached` decorator, `CacheInvalidator` (tag/namespace) |
 | **[Chat (conversations + messages) »](chat.md)** | `ChatService`, `make_chat_router`, base tables + real-time fan-out via `SSEBroker` |
+| **[CLI »](cli.md)** | `tempest new` / `db` (+ `seed`) / `user` / `secrets rotate` / `lint` / `fix` / `format` / `type` / `test` / `check` |
 | **[Comments + ratings »](reviews.md)** | `ReviewService`, `make_reviews_router`, 0–5 star scores with aggregation, threaded comments |
 | **[Computer vision (ONNX) »](vision.md)** | `Detector` / `Classifier` / `Segmenter` + prediction schemas |
+| **[Database »](database.md)** | `BaseModel`, `AsyncDatabaseManager`, `BaseRepository` (CRUD + filters + bulk), offset/cursor pagination, mixins, `AlembicHelper`, `SlowQueryLogger` |
+| **[Downloads »](downloads.md)** | `DownloadUtils` — `file_response`, `stream`, `build_content_disposition`, path-traversal safe |
+| **[Errors in OpenAPI (Swagger) »](openapi-errors.md)** | `error_responses`, `@raises`, `TempestAPIRouter`, `ErrorResponseSchema`, `tempest openapi-errors --fix` |
+| **[Feature flags »](feature-flags.md)** | `FeatureFlags`, env/Redis/composite backends, `make_flag_dependency` |
+| **[File store (unified) »](file-store.md)** | `FileStoreUtils` — upload + download + presign over a single backend |
+| **[Geolocation (distance + travel time) »](geo.md)** | `haversine_km`, `estimate_travel`, `OSRMBackend`, `NominatimBackend`, `GeoPointMixin` / `GeoRepositoryMixin` |
+| **[HTTP client (outbound) »](http-client.md)** | `HTTPClient` — typed httpx with retry/backoff, circuit-breaker, X-Request-ID; `RetryPolicy`, `CircuitOpenError` |
+| **[HTTP layer »](http.md)** | `apply_cors`, `RequestIDMiddleware`, `RateLimitMiddleware`, `make_health_router`, JWT / role / permission dependencies, webhook signature verifier, pagination Link headers, tool-spec router |
+| **[Idempotency »](idempotency.md)** | `IdempotencyMiddleware`, `MemoryIdempotencyStore` / `IdempotencyStore` (Redis) — safe replay of POST/PUT/PATCH/DELETE |
+| **[Integration client (OpenAPI) »](openapi-client.md)** | `tempest openapi-client` — Pydantic schemas + a typed client from a third party's spec |
+| **[Introspection auth (resource server) »](introspection-auth.md)** | `IntrospectionAuth` — validate an opaque bearer by asking the upstream identity provider |
 | **[Logging »](logging.md)** | `LogUtils`, structured JSON logging, request-ID propagation |
+| **[Management commands (tempest &lt;cmd&gt;) »](management-commands.md)** | register your own commands on the project's `tempest` CLI |
 | **[Metrics »](metrics.md)** | `MetricsUtils` — CPU / RAM / disk / GPU snapshots |
+| **[MFA (TOTP / 2FA) »](mfa.md)** | `MFAMixin`, `TOTPHelper`, enroll/confirm/verify/disable endpoints on `make_auth_router`, recovery codes |
+| **[Multi-tenant »](multi-tenant.md)** | `TenantScopedRepository` — `tenant_id` isolation on every query |
+| **[Object-level permissions »](authz.md)** | `permission` (rule decorator), `has_perm` / `check_permission`, `PermissionRegistry`, `make_permission_checker`, `PermissionMixin` |
 | **[Observability (tracing) »](observability.md)** | `setup_tracing` (OpenTelemetry), `SlowQueryLogger` |
-| **[Admin site »](admin.md)** | `AdminSite`, `AdminModel`, `make_admin_router`, `BaseUserModel` |
-| **[Downloads »](downloads.md)** | `DownloadUtils` — `file_response`, `stream`, `build_content_disposition`, path-traversal safe |
-| **[Uploads (backends) »](uploads.md)** | `UploadUtils`, extension/MIME validation (`sniff_mime`), local / MinIO backends |
+| **[Offline-first sync (delta) »](offline-sync.md)** | `BaseRepository.changes_since`, `SyncFilterSchema`, `SyncPaginationSchema`, cursor deltas + soft-delete |
+| **[Permission guards (@requires) »](permission-guards.md)** | `@requires` plus `(user) -> user` guards (with an optional `meta: dict[str, Any]` via `meta=` / `include_args=`), `TempestPermissionError`, `GuardContractWarning`, `tempest permissions --check` |
+| **[Queue & Tasks »](queue-tasks.md)** | FastStream (`AsyncBrokerManager`), TaskIQ (`AsyncTaskBrokerManager`), `AsyncTaskScheduler`, transactional outbox |
+| **[React SPA on FastAPI »](react-spa.md)** | `make_spa_router` — serve the Vite build from the same process, with history fallback |
+| **[Real-time »](realtime.md)** | Overview — when to choose SSE, WebSocket or Web Push |
+| **[Refresh tokens (rotation/revocation) »](refresh-tokens.md)** | `BaseUserRefreshTokenModel`, `make_user_refresh_token_model`, `issue_token_pair`, rotation + family reuse detection |
+| **[Safe deploys »](deploy-safety.md)** | `AlembicHelper.safe_upgrade` (blocks DROPs), `GracefulShutdownMiddleware` |
+| **[Security »](security.md)** | `AttemptThrottle`, opaque-token helpers, `HardenedStaticFiles`, security headers |
+| **[Self-hosted generative AI »](genai.md)** | `probe_hardware` / `can_run`, `TextGenerator`, `Embedder`, RAG (web + PDF), audio (STT/TTS), `make_genai_router` |
+| **[Server-Sent Events (SSE) »](sse.md)** | `EventStream`, `sse_response`, `ServerSentEvent`, `SSEBroker` (per-channel fan-out, Redis bridge) |
+| **[Server-side sessions »](sessions.md)** | `SessionMiddleware`, `SessionAuth`, `make_session_router`, `MemorySessionStore` / `RedisSessionStore` |
+| **[SSR (typed pages) »](../ssr.md)** | `Page`, `html_response`, `make_htmx_router`, hosting a `tempestweb` build |
 | **[Storage (MinIO/S3) »](storage.md)** | `AsyncMinIOClient`, `MinIOUploadStorage`, `presigned_get_url` / `presigned_put_url`, `list_objects` |
 | **[Stored file (service mixin) »](stored-files.md)** | `StoredFileServiceMixin` — `set_file` / `replace` / `clear_file` over `UploadUtils` |
-| **[Utilities »](utilities.md)** | `utcnow`/`to_utc`, `modify_dict`, `get_client_ip`, opaque tokens (`generate_opaque_token`) |
+| **[System checks (check-config) »](system-checks.md)** | `run_system_checks`, `@check`, `CheckMessage`, `tempest check-config` — validate settings before serving |
+| **[tempestweb frontend + SDK »](tempestweb-frontend.md)** | tempestweb frontend calling the SDK backend: `tempestweb.native.http`, `Idempotency-Key` + `IdempotencyMiddleware`, retry, same origin vs CORS |
+| **[Testing »](testing.md)** | `test_session`, `test_database`, in-memory SQLite, pytest fixtures |
+| **[Transactional email »](email.md)** | `EmailUtils` — SMTP, text/HTML body, attachments, Jinja2 templates |
+| **[Transactional outbox »](outbox.md)** | `BaseOutboxModel`, `OutboxRelay`, `save_with_outbox` — reliable events |
 | **[Typing (static + runtime) »](typing.md)** | `strict_types` / `typed` / `require_annotations`, `[tool.tempest] typing_strictness` knob, ruff `ANN` |
+| **[Uploads (backends) »](uploads.md)** | `UploadUtils`, extension/MIME validation (`sniff_mime`), local / MinIO backends |
+| **[Utilities »](utilities.md)** | `utcnow`/`to_utc`, `modify_dict`, `get_client_ip`, opaque tokens (`generate_opaque_token`) |
 | **[Validated fields (ready-made types) »](fields.md)** | Annotated Pydantic types — `PositiveIntField` / `CentsField` / `PriceField` / `SlugField` / `HexColorField` / `CPFField` / `UFField` |
-| **[Testing »](testing.md)** | `test_session`, `test_database`, in-memory SQLite, pytest fixtures |
-| **[Safe deploys »](deploy-safety.md)** | `AlembicHelper.safe_upgrade` (blocks DROPs), `GracefulShutdownMiddleware` |
-| **[CLI »](cli.md)** | `tempest new` / `db` (+ `seed`) / `user` / `secrets rotate` / `lint` / `fix` / `format` / `type` / `test` / `check` |
-| **[Security »](security.md)** | `AttemptThrottle`, opaque-token helpers, `HardenedStaticFiles`, security headers |
-| **[Brazilian helpers »](br-helpers.md)** | CPF / CNPJ / CEP / phone validation + normalization |
-| **[Object-level permissions »](authz.md)** | `permission` (rule decorator), `has_perm` / `check_permission`, `PermissionRegistry`, `make_permission_checker`, `PermissionMixin` |
-| **[Permission guards (@requires) »](permission-guards.md)** | `@requires` plus `(user) -> user` guards, `TempestPermissionError`, `GuardContractWarning`, `tempest permissions --check` |
-| **[Introspection auth (resource server) »](introspection-auth.md)** | `IntrospectionAuth` — validate an opaque bearer by asking the upstream identity provider |
-| **[Geolocation (distance + travel time) »](geo.md)** | `haversine_km`, `estimate_travel`, `OSRMBackend`, `NominatimBackend`, `GeoPointMixin` / `GeoRepositoryMixin` |
-| **[Self-hosted generative AI »](genai.md)** | `probe_hardware` / `can_run`, `TextGenerator`, `Embedder`, RAG (web + PDF), audio (STT/TTS), `make_genai_router` |
-| **[File store (unified) »](file-store.md)** | `FileStoreUtils` — upload + download + presign over a single backend |
 | **[Versioned artifacts (models) »](artifact-registry.md)** | `ArtifactRegistry`, `ArtifactVersionMixin`, `build_manifest_entries`, `file_digest` — swap the active version without a redeploy |
-| **[Errors in OpenAPI (Swagger) »](openapi-errors.md)** | `error_responses`, `@raises`, `TempestAPIRouter`, `ErrorResponseSchema`, `tempest openapi-errors --fix` |
-| **[Integration client (OpenAPI) »](openapi-client.md)** | `tempest openapi-client` — Pydantic schemas + a typed client from a third party's spec |
-| **[System checks (check-config) »](system-checks.md)** | `run_system_checks`, `@check`, `CheckMessage`, `tempest check-config` — validate settings before serving |
-| **[Management commands (tempest &lt;cmd&gt;) »](management-commands.md)** | register your own commands on the project's `tempest` CLI |
-| **[SSR (typed pages) »](../ssr.md)** | `Page`, `html_response`, `make_htmx_router`, hosting a `tempestweb` build |
-| **[React SPA on FastAPI »](react-spa.md)** | `make_spa_router` — serve the Vite build from the same process, with history fallback |
+| **[Web Push »](webpush.md)** | `WebPushDispatcher`, VAPID schemas, broadcast with pruning |
+| **[WebSocket router »](websocket.md)** | `WebSocketHub`, `make_websocket_router`, `broadcast` / `send_to`, heartbeat, bearer auth |
 ## Complete examples
@@ -339,11 +339,11 @@ The recipes show one piece at a time. These pages combine **several** into a flo
 | Example | What it combines |
 | --- | --- |
-| **[Pix checkout »](../integrated.md)** | JWT auth + validated fields (`PixKeyField`) + cache + transactional outbox + `MessageBroker` + `TaskQueue` + SSE + Web Push |
-| **[Neighborhood marketplace »](../marketplace-local.md)** | geo (nearby sellers, distance/time) + real-time chat + live notifications + star ratings |
 | **[Full store admin »](../admin-showcase.md)** | audit history + FK autocomplete + inlines + business cards + CSV import + granular RBAC + lenses |
 | **[Fullstack web (SSR, WASM, server) »](../fullstack-web.md)** | the three ways to talk to `tempestweb`: SSR + HTMX, WASM SPA and server-mode |
 | **[GenAI flows »](../genai-examples.md)** | hardware capacity → local LLM → embeddings/RAG → audio, self-hosted end to end |
+| **[Neighborhood marketplace »](../marketplace-local.md)** | geo (nearby sellers, distance/time) + real-time chat + live notifications + star ratings |
+| **[Pix checkout »](../integrated.md)** | JWT auth + validated fields (`PixKeyField`) + cache + transactional outbox + `MessageBroker` + `TaskQueue` + SSE + Web Push |
 ## Anatomy of a recipe

tempest-fastapi-sdk 0.167.2__tar.gz → 0.168.1__tar.gz

tempest-fastapi-sdk 0.167.2tar.gz → 0.168.1tar.gz