tempest-fastapi-sdk 0.82.0__tar.gz → 0.87.0__tar.gz

{tempest_fastapi_sdk-0.82.0 → tempest_fastapi_sdk-0.87.0}/CHANGELOG.md

@@ -5,6 +5,124 @@ 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.87.0] — 2026-07-02
+
+### Added
+
+- **Configurable token delivery for the auth router.** `make_auth_router`
+  now supports three ways of handing back the JWT pair, selected by
+  `AUTH_TOKEN_DELIVERY` (or the `token_delivery=` argument):
+  - `"bearer"` (default) — tokens in the JSON body only. Unchanged,
+    fully backward-compatible behaviour.
+  - `"cookie"` — `access_token` / `refresh_token` set as `HttpOnly`
+    cookies on `/auth/login`, `/auth/refresh`, `/auth/logout`; the body
+    omits the token values (safer against XSS). `POST /auth/refresh`
+    reads the refresh token from the cookie and rotates the pair;
+    `POST /auth/logout` clears the cookies (and revokes the refresh
+    family when a `refresh_token_model` is wired).
+  - `"both"` — the bearer endpoints stay at `/auth/*` and a parallel
+    cookie set is mounted at `/auth/cookie/*`, so one backend can serve
+    web (cookie) and mobile/API (bearer) clients.
+- New `AUTH_COOKIE_SECURE`, `AUTH_COOKIE_SAMESITE`, `AUTH_COOKIE_DOMAIN`,
+  `AUTH_ACCESS_COOKIE_NAME` and `AUTH_REFRESH_COOKIE_NAME` settings tune
+  the cookie security attributes.
+- New public exports: `TokenDelivery`, `AuthCookieConfig`,
+  `apply_auth_cookies`, `clear_auth_cookies`.
+- `make_bearer_token_dependency` / `make_jwt_user_dependency` gained a
+  `cookie_name=` argument: when set, the access token is read from that
+  cookie if the `Authorization` header is absent (header still wins), so
+  the same guarded routes work in cookie mode.
+
+### Notes
+
+- Activation, signup auto-login and the MFA-verify step still return the
+  JWT pair in the body regardless of `AUTH_TOKEN_DELIVERY` — cookie
+  delivery covers the login / refresh / logout session lifecycle.
+
+## [0.86.0] — 2026-06-28
+
+### Added
+
+- **Admin rich list filters.** `list_filter` fields now auto-pick a
+  widget by column type instead of rendering a useful dropdown only for
+  booleans: **enum** columns become a member dropdown, **foreign keys**
+  (whose target has a registered `AdminModel`) become a related-row
+  dropdown, **date/datetime** columns become an inclusive date-range
+  (two date inputs → `<field>__gte` / `<field>__lte`), and any other
+  column becomes a text input (equality). Booleans keep the Yes/No
+  dropdown. All filters preserve search / sort / pagination in the URL.
+
+## [0.85.0] — 2026-06-28
+
+### Added
+
+- **Admin file / image upload fields.** `AdminModel` gained
+  `upload_fields=[...]` + `upload_storage=...`: listed String columns
+  render as file inputs in the create/edit form (which auto-switches to
+  `multipart/form-data`), the posted file is streamed to the storage
+  backend (`LocalUploadStorage` / `MinIOUploadStorage`), and the returned
+  storage key is written to the column. On edit, omitting the file keeps
+  the current value; on create, a missing file for a non-nullable column
+  is a required-field error. Registering `upload_fields` without
+  `upload_storage` raises `ValueError`.
+
+## [0.84.0] — 2026-06-28
+
+### Added
+
+- **Admin custom actions (`@admin_action`).** Beyond the three hardcoded
+  bulk operations (activate / deactivate / delete), the admin now takes
+  user-defined actions: decorate an async function with `@admin_action`
+  and register it via `AdminModel(actions=[...])`. Each renders in the
+  list view's bulk dropdown (namespaced `custom:<name>` so it can't
+  collide with the built-ins), runs on the checked rows, and flashes a
+  banner from its `AdminActionResult`. The handler receives an
+  `AdminActionContext` (selected ids, a request-scoped repository, the DB
+  session, the request, the admin session, and the acting principal) and
+  stays directly callable/testable — the decorator only attaches
+  metadata. Exported from `tempest_fastapi_sdk` and
+  `tempest_fastapi_sdk.admin` (`admin_action`, `AdminAction`,
+  `AdminActionContext`, `AdminActionResult`).
+
+## [0.83.0] — 2026-06-28
+
+### Added
+
+- **Computer-vision integration via the `[vision]` extra
+  (`ort-vision-sdk`).** New `tempest_fastapi_sdk.vision` submodule wraps
+  the ONNX Runtime inference library with the FastAPI layer it lacks:
+  Pydantic response schemas (`DetectionSchema`, `ClassificationSchema`,
+  `SegmentationSchema`, `BoundingBoxSchema`, `ClassProbabilitySchema`)
+  and mappers (`to_detection_schemas`, `to_classification_schema`,
+  `to_segmentation_schemas`) that convert a model result into them. The
+  `Detector` / `Classifier` / `Segmenter` task classes are re-exported
+  **lazily** — accessing one without the extra raises a clear
+  `ImportError` pointing at `[vision]`; the schemas and mappers carry no
+  such dependency. Like `cache` / `queue` / `tasks`, vision is
+  submodule-only (`from tempest_fastapi_sdk.vision import Detector`).
+
+## [0.82.1] — 2026-06-28
+
+### Fixed
+
+- **Docs: removed code that the API never offered.** A doc audit
+  (cross-checking every `tempest_fastapi_sdk` import and example against
+  the package) found and fixed drift in the README:
+  - The brute-force throttling recipe invented `MemoryThrottleBackend` /
+    `RedisThrottleBackend`, `throttle.check()` returning a `ThrottleStatus`
+    enum, `record_failure()`, and `lock_seconds=` — none exist. Rewritten
+    to the real API (`AttemptThrottle(backend, max_attempts=, window_seconds=)`
+    with `raise_if_blocked` / `hit` / `reset` / `status`).
+  - The client-IP recipe used `trusted_proxies=` / `accept_private=` — the
+    real parameter is `trusted_header=`.
+  - The cookie recipe treated `SameSite` as a `BaseStrEnum` (`SameSite.LAX`)
+    with `same_site=` / `key=` kwargs and an auto-`Secure` claim; `SameSite`
+    is a `Literal` alias and `set_cookie` takes positional `name`/`value`
+    + `samesite=`.
+  - `AsyncRedisManager` was imported from the top level in several recipes
+    (cache / sessions / security) — it lives in `tempest_fastapi_sdk.cache`
+    (submodule-only, like `queue` / `tasks`). No code changes.
+
 ## [0.82.0] — 2026-06-28
 
 ### Added

{tempest_fastapi_sdk-0.82.0 → tempest_fastapi_sdk-0.87.0}/CLAUDE.md

@@ -88,8 +88,32 @@ The SDK currently covers (Sep 2025+, post-v0.31.x):
 - **Pagination** — offset + cursor.
 - **Settings mixins** — every `*Settings` carries
   `title`/`description`/`examples` on every field.
-- **SSE** — `EventStream`, `sse_response`.
-- **Throttle** — `AttemptThrottle` (memory + Redis).
+- **SSE** — `EventStream`, `ServerSentEvent`, `sse_response`, and
+  `SSEBroker` (per-channel fan-out; in-memory single-process, or
+  multi-worker via an injected Redis pub/sub bridge — same call site).
+- **Throttle** — `AttemptThrottle` (any `ThrottleBackend`, e.g.
+  `redis.asyncio.Redis`; no in-memory backend bundled).
+- **Base CRUD layers** — `BaseService[Repo, Resp, UpdateT]` and
+  `BaseController[Service, Resp, UpdateT]` with
+  `get_by_id`/`get_or_none`/`list`/`paginate`/`count`/`exists`/`update`/
+  `delete`; `update` is partial-aware (PUT/PATCH) and `UpdateT` is an
+  optional 3rd generic (defaults to `BaseSchema`, PEP 696).
+- **Base enums** — `BaseStrEnum` / `BaseIntEnum` with
+  `values`/`keys`/`choices`/`to_dict`/`from_value`/`has_value`/`has_key`.
+- **Validated field types** — `tempest_fastapi_sdk.utils` Annotated
+  Pydantic types: `PositiveIntField`/`NonNegativeIntField`/`CentsField`/
+  `PortField`/`PositiveFloatField`/`NonNegativeFloatField`/`PercentField`/
+  `RatioField`/`LatitudeField`/`LongitudeField`/`PriceField`/
+  `NonEmptyStrField`/`SlugField`/`HexColorField`.
+- **Runtime typing** — `strict_types` / `typed` / `require_annotations`
+  decorators (over `pydantic.validate_call`); ruff `ANN` enabled in the
+  SDK and `tempest new` templates (ANN401 off — `Any` is valid); a
+  `[tool.tempest] typing_strictness` knob (`lenient`/`standard`/`strict`,
+  `--strictness` override) layered onto `tempest lint`/`fix`/`type`/`check`.
+- **Vision** (`[vision]` extra) — `tempest_fastapi_sdk.vision` wrapping
+  `ort-vision-sdk`: lazy `Detector`/`Classifier`/`Segmenter` + prediction
+  schemas + `to_detection_schemas`/`to_classification_schema`/
+  `to_segmentation_schemas` mappers.
 - **Upload** — `UploadUtils` with pluggable backends
   (`LocalUploadStorage`, `MinIOUploadStorage`), download helpers,
   presigned URLs.
@@ -99,17 +123,26 @@ The SDK currently covers (Sep 2025+, post-v0.31.x):
 - **Email** — SMTP via `EmailUtils` + Jinja2 template rendering
   with bundled defaults (`activation.html`, `password_reset.html`)
   shadowable by the project's `template_dir`.
-- **WebPush** + webhook signatures.
+- **WebPush** — `WebPushDispatcher` (`send`/`send_many`, 404/410
+  pruning), subscription storage (`BaseWebPushSubscriptionModel` +
+  `make_web_push_subscription_model`) + `WebPushSubscriptionService`
+  (`subscribe`/`unsubscribe`/`list_for_user`/`notify_user` with
+  auto-prune of gone endpoints) + `make_web_push_router` (opt-in
+  `/subscribe` + `/unsubscribe`, aligned with `tempest-react-sdk`);
+  webhook signatures.
 - **Cache** — Redis manager + `@cached`.
 - **Queue / tasks** — FastStream + TaskIQ wrappers.
-- **BR validators** — CPF/CNPJ/CEP/phone.
+- **BR validators** — CPF/CNPJ/CEP/phone, with `*Field` Pydantic types
+  (`CPFField`/`CNPJField`/`CPFOrCNPJField`/`PhoneBRField`/`CEPField`;
+  pre-0.76 unsuffixed names kept as deprecated aliases).
 - **BR localities** — `UF` (StrEnum, 27 siglas) + `Region`
   (5 macro-regiões IBGE), `StateBR`/`CityBR` schemas, offline
   dataset of 27 states + 5606 municipalities (IBGE-derived,
   DF as 36 administrative regions), `list_states`/`get_state`/
   `cities_by_uf`/`states_by_region`, `is_valid_uf`/`normalize_uf`,
   `is_valid_city`/`normalize_city` (accent/case-insensitive),
-  `UFField`/`CityNameField`.
+  `UFField`/`CityNameField`, plus `ChoiceBR` + `uf_choices`/
+  `region_choices`/`city_choices` (frontend `<select>` choices).
 - **Rate limit** — `RateLimitMiddleware` (sliding window) with
   pluggable store (`MemoryRateLimitStore` / `RedisRateLimitStore`,
   atomic Lua) and per-principal key extractors (`key_by_ip`,
@@ -131,7 +164,11 @@ The SDK currently covers (Sep 2025+, post-v0.31.x):
 - **Admin panel** — Jinja + HTMX (`AdminSite`, `AdminModel`,
   `make_admin_router`), typed theming via `AdminTheme` (colors /
   logo / favicon / font / radius / footer / dark mode /
-  `custom_css_url`, injected as `:root` overrides).
+  `custom_css_url`, injected as `:root` overrides), custom bulk actions
+  (`@admin_action` + `AdminModel(actions=[...])`, `AdminActionContext` /
+  `AdminActionResult`), file/image upload fields (`AdminModel(
+  upload_fields=[...], upload_storage=...)`), rich list filters
+  (bool/enum/FK select, date-range, text — auto by column type).
 - **CLI** — `tempest new` (scaffolds layered service +
   docker-compose + multi-stage uv `Dockerfile`/`.dockerignore`),
   `tempest generate --docker` (regen compose) / `--dockerfile`
@@ -169,41 +206,46 @@ then move it up to the covers list.
 foundation the user asked for first; the functional Tier 1 items below
 inherit the look for free. Now in the covers list.
 
+**Shipped — custom actions (v0.84.0).** `@admin_action` decorator +
+`AdminModel(actions=[...])` + `AdminActionContext`/`AdminActionResult`;
+custom entries render in the bulk dropdown (namespaced `custom:<name>`),
+run on the checked rows, and flash a banner on the list view. Now in the
+covers list.
+
+**Shipped — file / image upload field (v0.85.0).** `AdminModel(
+upload_fields=[...], upload_storage=...)` renders String columns as file
+inputs, streams the upload to `LocalUploadStorage` / `MinIOUploadStorage`,
+and stores the returned key. Now in the covers list.
+
+**Shipped — rich filters (v0.86.0).** `list_filter` fields auto-pick a
+widget by column type: bool / enum / FK → select, date/datetime →
+inclusive date-range (two inputs → `__gte`/`__lte`), other → text.
+Now in the covers list.
+
 **Tier 1 — high value, reuses an existing engine (low effort):**
 
-1. **Custom actions (NEXT)** — `@admin_action` decorator on `AdminModel`
-   for user-defined row / bulk operations (Django `actions`, Nova
-   actions). Today only 3 are hardcoded (activate / deactivate /
-   delete). This is the foundation the rest build on.
-2. **File / image upload field** — a new form widget wired to the
-   existing `UploadUtils` (`LocalUploadStorage` / `MinIOUploadStorage`).
-   Engine is already shipped; admin just needs the widget + storage
-   binding.
-3. **Rich filters** — enum / choice / FK / date-range filters in the
-   list view (today only boolean fields auto-render a filter dropdown).
-   Quick UX win.
-4. **Audit history viewer** — a per-row change timeline wired to the
+1. **Audit history viewer (NEXT)** — a per-row change timeline wired to the
    existing `BaseAuditLogModel` + `diff_snapshots`. Today the detail
    view only shows `created_by` / `updated_by` stamps, not full history.
    Engine is already shipped.
 
 **Tier 2 — high value, medium effort:**
 
-5. **Autocomplete FK fields** — HTMX search endpoint backing FK inputs,
+2. **Autocomplete FK fields** — HTMX search endpoint backing FK inputs,
    removing the 1000-row `<select>` cap and the plain-UUID fallback
    (Django `autocomplete_fields`, Nova search).
-6. **Inlines / nested relations** — edit child rows inside the parent's
+3. **Inlines / nested relations** — edit child rows inside the parent's
    detail / edit view (Django `StackedInline` / `TabularInline`).
-7. **Dashboard business metrics / charts** — value / trend / partition
+4. **Dashboard business metrics / charts** — value / trend / partition
    cards (Nova metrics), wired to the existing metrics module. Distinct
    from today's system CPU/RAM/disk panel.
 
 **Tier 3 — nice-to-have:**
 
-8. **RBAC granular** — per-model / per-action admin permissions beyond
+5. **RBAC granular** — per-model / per-action admin permissions beyond
    today's `is_admin` + `can_create` / `can_edit` / `can_delete`.
-9. **CSV import** — bulk upload counterpart to the existing export.
-10. **Lenses** — saved alternate views / queries per model (Nova).
+6. **CSV import** — bulk upload counterpart to the existing export.
+7. **Lenses** — saved alternate views / queries per model (Nova).
 
 Origin: competitor gap analysis (Django Admin, Laravel Nova, SQLAdmin,
 Starlette-Admin) run 2026-06-26. Do **not** treat the tiers as locked —

{tempest_fastapi_sdk-0.82.0 → tempest_fastapi_sdk-0.87.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tempest-fastapi-sdk
-Version: 0.82.0
+Version: 0.87.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
@@ -49,6 +49,7 @@ Requires-Dist: opentelemetry-instrumentation-fastapi>=0.48b0; extra == 'all'
 Requires-Dist: opentelemetry-instrumentation-httpx>=0.48b0; extra == 'all'
 Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.48b0; extra == 'all'
 Requires-Dist: opentelemetry-sdk>=1.27.0; extra == 'all'
+Requires-Dist: ort-vision-sdk>=0.4.0; extra == 'all'
 Requires-Dist: prometheus-client>=0.20.0; extra == 'all'
 Requires-Dist: psutil>=6.0.0; extra == 'all'
 Requires-Dist: pyjwt>=2.12.1; extra == 'all'
@@ -96,6 +97,8 @@ Requires-Dist: taskiq>=0.11.0; extra == 'tasks'
 Provides-Extra: upload
 Requires-Dist: aiofiles>=24.1.0; extra == 'upload'
 Requires-Dist: python-multipart>=0.0.12; extra == 'upload'
+Provides-Extra: vision
+Requires-Dist: ort-vision-sdk>=0.4.0; extra == 'vision'
 Provides-Extra: webpush
 Requires-Dist: cryptography>=42.0.0; extra == 'webpush'
 Requires-Dist: pywebpush>=2.0.0; extra == 'webpush'
@@ -219,6 +222,7 @@ Feature-rich helpers pull in third-party dependencies that you only need when yo
 | `[http]` | `httpx` | `HTTPClient`, `RetryPolicy`, `CircuitOpenError`, OAuth2 / OIDC providers |
 | `[prometheus]` | `prometheus-client` | `PrometheusMiddleware`, `make_prometheus_router`, `make_prometheus_registry` |
 | `[mfa]` | `pyotp` | `TOTPHelper` + MFA/2FA endpoints on the bundled auth flow |
+| `[vision]` | `ort-vision-sdk` | `Detector` / `Classifier` / `Segmenter` (ONNX) + prediction schemas |
 | `[otel]` | `opentelemetry-sdk` + OTLP/gRPC exporter + FastAPI/SQLAlchemy/httpx instrumentors | `setup_tracing` — distributed tracing |
 | `[sqlite]` | `aiosqlite` | SQLite async driver for `sqlite+aiosqlite://` URLs (dev default) |
 | `[postgres]` | `asyncpg` | PostgreSQL async driver for `postgresql+asyncpg://` URLs (production) |
@@ -259,10 +263,11 @@ Since `0.7.1` every optional dependency is imported lazily at first instantiatio
 | `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]`)* | `AsyncTaskBrokerManager` (TaskIQ lifecycle wrapper), `AsyncTaskScheduler` (periodic / cron tasks) |
+| `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` |
 | `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)*, `MetricsUtils`/`CPUMetrics`/`MemoryMetrics`/`DiskMetrics`/`GPUMetrics`/`SystemMetrics` *(extra: `[metrics]`)*, validated field types (`PositiveIntField`, `NonNegativeIntField`, `CentsField`, `PortField`, `PositiveFloatField`, `NonNegativeFloatField`, `PercentField`, `RatioField`, `LatitudeField`, `LongitudeField`, `PriceField`, `NonEmptyStrField`, `SlugField`, `HexColorField`), BR regex helpers (`CPFField`, `CNPJField`, `CPFOrCNPJField`, `PhoneBRField`, `CEPField` — old names without the suffix kept as deprecated aliases — `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), `version` / `--version` |
 
-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` and `tempest_fastapi_sdk.tasks` must be imported from their own submodule (`from tempest_fastapi_sdk.queue import AsyncBrokerManager`).
+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` and `tempest_fastapi_sdk.vision` must be imported from their own submodule (`from tempest_fastapi_sdk.queue import AsyncBrokerManager`).
 
 ---
 
@@ -3314,62 +3319,66 @@ app.mount(
 )
 ```
 
-For cookie-based session flows, `set_cookie` / `clear_cookie` write headers that already include the safe combo (`HttpOnly`, `Secure`, `SameSite=Lax`) so the caller only picks the bits they want to deviate from. `SameSite` is a `BaseStrEnum` (`SameSite.LAX` / `STRICT` / `NONE`) — using `SameSite.NONE` forces `Secure=True` to honor the browser requirement.
+For cookie-based session flows, `set_cookie` / `clear_cookie` write headers that already include the safe combo (`HttpOnly`, `Secure`, `SameSite=Lax`) so the caller only picks the bits they want to deviate from. `SameSite` is a **type alias** `Literal["lax", "strict", "none"]` — pass the literal string, not an enum. The SDK does **not** auto-force `Secure` for `samesite="none"`: pass `samesite="none", secure=True` yourself in cross-site scenarios (the browser rejects `SameSite=None` without `Secure`).
 
 ```python
 from fastapi import Response
 
-from tempest_fastapi_sdk import SameSite, clear_cookie, set_cookie
+from tempest_fastapi_sdk import clear_cookie, set_cookie
 
 
 def login(response: Response, token: str) -> None:
     set_cookie(
         response,
-        key="session",
-        value=token,
+        "session",                 # name (positional)
+        token,                     # value (positional)
         max_age=3600,
-        same_site=SameSite.LAX,         # default
-        # secure=True,                  # auto-enabled for SameSite.NONE
-        # http_only=True,               # default
+        samesite="lax",            # "lax" (default), "strict" or "none"
+        # secure=True,             # default — set False only for local HTTP
+        # http_only=True,          # default
         path="/",
     )
 
 
 def logout(response: Response) -> None:
-    clear_cookie(response, key="session", path="/")
+    clear_cookie(response, "session", path="/")
 ```
 
 ### Brute-force throttling recipe
 
-`AttemptThrottle` counts failed attempts per key (typically `<endpoint>:<identifier>` — login email, password-reset target, etc.) and either yields a free attempt, locks the caller for a cooldown, or signals "back off" once the threshold is crossed. Two backends ship: `MemoryThrottleBackend` (defaults — process-local, perfect for tests and single-process services) and `RedisThrottleBackend` (multi-process / multi-host deployments).
+`AttemptThrottle` counts failed attempts per key (typically `<endpoint>:<identifier>` — login email, password-reset target, IP, etc.). The constructor takes a `backend` — any object matching the `ThrottleBackend` Protocol (`get`/`incr`/`expire`/`ttl`/`delete`), which `redis.asyncio.Redis` satisfies out of the box — plus `max_attempts` + `window_seconds`. No in-memory backend is bundled: pass the Redis client from `AsyncRedisManager` (or a [fakeredis](https://github.com/cunla/fakeredis-py) double in tests).
 
 ```python
-from tempest_fastapi_sdk import AttemptThrottle, ThrottleStatus, TooManyRequestsException
-from tempest_fastapi_sdk.utils.throttle import RedisThrottleBackend
+from tempest_fastapi_sdk import AttemptThrottle, UnauthorizedException
+from tempest_fastapi_sdk.cache import AsyncRedisManager
+
+from src.core.settings import settings
 
+cache = AsyncRedisManager(settings.REDIS_URL)
+# cache.client is redis.asyncio.Redis — matches the ThrottleBackend Protocol
 throttle = AttemptThrottle(
-    backend=RedisThrottleBackend(redis_manager=cache),
+    cache.client,
     max_attempts=5,
-    window_seconds=300,           # rolling window
-    lock_seconds=900,             # cooldown applied when threshold trips
+    window_seconds=300,         # fixed window; also the TTL on the first failure
+    namespace="login",          # key prefix so multiple throttles can coexist
+    fail_open=True,             # a Redis outage degrades to "allow", never locks everyone out
 )
 
 
 async def login(email: str, password: str) -> User:
-    status = await throttle.check(f"login:{email}")
-    if status is ThrottleStatus.LOCKED:
-        raise TooManyRequestsException(message="Too many attempts; try again later.")
+    key = f"login:{email}"
+    await throttle.raise_if_blocked(key)            # raises 429 when over budget
 
-    user = await users_repo.get_by_email(email)
-    if not password_utils.verify(password, user.password_hash):
-        await throttle.record_failure(f"login:{email}")
+    user = await users_repo.get_or_none({"email": email})
+    if user is None or not password_utils.verify(password, user.hashed_password):
+        await throttle.hit(key)                     # +1 failure, applies the TTL
         raise UnauthorizedException(message="Invalid credentials.")
 
-    await throttle.reset(f"login:{email}")
+    await throttle.reset(key)                       # success clears the counter
     return user
 ```
 
-`check()` returns a `ThrottleStatus` enum (`ALLOWED` / `LOCKED`); inspecting `.attempts_left` and `.retry_after_seconds` on the result lets you surface friendly error payloads. Pair with `TooManyRequestsException` so the SDK exception handler emits the canonical `{detail, code, details}` envelope with HTTP 429 and a `Retry-After` header.
+`throttle.status(key)` (peek without incrementing) and `throttle.hit(key)` (increment) both return a frozen `ThrottleStatus` dataclass — `attempts: int`, `blocked: bool`, `retry_after_seconds: int` — to build friendly error payloads. `raise_if_blocked` already raises `TooManyRequestsException`, which the SDK exception handler turns into the canonical `{detail, code, details}` envelope with HTTP 429 and a `Retry-After` header.
 
 ### Opaque tokens recipe
 
@@ -3408,7 +3417,7 @@ async def consume_reset_token(plain: str, user_id: UUID) -> bool:
 
 ### Client IP extraction recipe
 
-`get_client_ip(request)` and `get_client_ip_from_scope(scope)` return the real client IP behind an arbitrary chain of proxies. They inspect `Forwarded` (RFC 7239) first, fall back to `X-Forwarded-For` honoring an explicit `trusted_proxies` allowlist, and finally use the raw socket address — never naively trusting an inbound header.
+`get_client_ip(request)` and `get_client_ip_from_scope(scope)` return the real client IP behind a proxy. By design they accept **one** trusted header name (`trusted_header=`) that your edge proxy is known to set (e.g. `"x-real-ip"` on Nginx) — without it, they use the direct peer address. Anti-spoofing belongs at the proxy (which overwrites the header with the real peer), not in Python, so the SDK only reads the header you declare trusted.
 
 ```python
 from fastapi import Request
@@ -3418,15 +3427,13 @@ from tempest_fastapi_sdk import get_client_ip
 
 @router.post("/login")
 async def login(request: Request, payload: LoginIn) -> LoginOut:
-    ip = get_client_ip(
-        request,
-        trusted_proxies={"10.0.0.0/8", "192.168.0.0/16"},
-    )
-    await throttle.check(f"login:{ip}")
+    # Behind Nginx that overwrites X-Real-IP with the real peer:
+    ip = get_client_ip(request, trusted_header="x-real-ip")
+    await throttle.raise_if_blocked(f"login:{ip}")
     ...
 ```
 
-Use `get_client_ip_from_scope(scope)` from middleware or websocket handlers where only the ASGI scope is in reach. Both helpers normalize IPv6 brackets and refuse to return private addresses when `accept_private=False` is passed — handy when only public traffic should ever populate audit logs.
+Use `get_client_ip_from_scope(scope, trusted_header=...)` from middleware or websocket handlers where only the ASGI scope is in reach. If you expose the app directly to the internet, omit `trusted_header=` so the peer address is used.
 
 ### Command-line interface recipe
 

{tempest_fastapi_sdk-0.82.0 → tempest_fastapi_sdk-0.87.0}/README.md

@@ -116,6 +116,7 @@ Feature-rich helpers pull in third-party dependencies that you only need when yo
 | `[http]` | `httpx` | `HTTPClient`, `RetryPolicy`, `CircuitOpenError`, OAuth2 / OIDC providers |
 | `[prometheus]` | `prometheus-client` | `PrometheusMiddleware`, `make_prometheus_router`, `make_prometheus_registry` |
 | `[mfa]` | `pyotp` | `TOTPHelper` + MFA/2FA endpoints on the bundled auth flow |
+| `[vision]` | `ort-vision-sdk` | `Detector` / `Classifier` / `Segmenter` (ONNX) + prediction schemas |
 | `[otel]` | `opentelemetry-sdk` + OTLP/gRPC exporter + FastAPI/SQLAlchemy/httpx instrumentors | `setup_tracing` — distributed tracing |
 | `[sqlite]` | `aiosqlite` | SQLite async driver for `sqlite+aiosqlite://` URLs (dev default) |
 | `[postgres]` | `asyncpg` | PostgreSQL async driver for `postgresql+asyncpg://` URLs (production) |
@@ -156,10 +157,11 @@ Since `0.7.1` every optional dependency is imported lazily at first instantiatio
 | `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]`)* | `AsyncTaskBrokerManager` (TaskIQ lifecycle wrapper), `AsyncTaskScheduler` (periodic / cron tasks) |
+| `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` |
 | `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)*, `MetricsUtils`/`CPUMetrics`/`MemoryMetrics`/`DiskMetrics`/`GPUMetrics`/`SystemMetrics` *(extra: `[metrics]`)*, validated field types (`PositiveIntField`, `NonNegativeIntField`, `CentsField`, `PortField`, `PositiveFloatField`, `NonNegativeFloatField`, `PercentField`, `RatioField`, `LatitudeField`, `LongitudeField`, `PriceField`, `NonEmptyStrField`, `SlugField`, `HexColorField`), BR regex helpers (`CPFField`, `CNPJField`, `CPFOrCNPJField`, `PhoneBRField`, `CEPField` — old names without the suffix kept as deprecated aliases — `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), `version` / `--version` |
 
-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` and `tempest_fastapi_sdk.tasks` must be imported from their own submodule (`from tempest_fastapi_sdk.queue import AsyncBrokerManager`).
+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` and `tempest_fastapi_sdk.vision` must be imported from their own submodule (`from tempest_fastapi_sdk.queue import AsyncBrokerManager`).
 
 ---
 
@@ -3211,62 +3213,66 @@ app.mount(
 )
 ```
 
-For cookie-based session flows, `set_cookie` / `clear_cookie` write headers that already include the safe combo (`HttpOnly`, `Secure`, `SameSite=Lax`) so the caller only picks the bits they want to deviate from. `SameSite` is a `BaseStrEnum` (`SameSite.LAX` / `STRICT` / `NONE`) — using `SameSite.NONE` forces `Secure=True` to honor the browser requirement.
+For cookie-based session flows, `set_cookie` / `clear_cookie` write headers that already include the safe combo (`HttpOnly`, `Secure`, `SameSite=Lax`) so the caller only picks the bits they want to deviate from. `SameSite` is a **type alias** `Literal["lax", "strict", "none"]` — pass the literal string, not an enum. The SDK does **not** auto-force `Secure` for `samesite="none"`: pass `samesite="none", secure=True` yourself in cross-site scenarios (the browser rejects `SameSite=None` without `Secure`).
 
 ```python
 from fastapi import Response
 
-from tempest_fastapi_sdk import SameSite, clear_cookie, set_cookie
+from tempest_fastapi_sdk import clear_cookie, set_cookie
 
 
 def login(response: Response, token: str) -> None:
     set_cookie(
         response,
-        key="session",
-        value=token,
+        "session",                 # name (positional)
+        token,                     # value (positional)
         max_age=3600,
-        same_site=SameSite.LAX,         # default
-        # secure=True,                  # auto-enabled for SameSite.NONE
-        # http_only=True,               # default
+        samesite="lax",            # "lax" (default), "strict" or "none"
+        # secure=True,             # default — set False only for local HTTP
+        # http_only=True,          # default
         path="/",
     )
 
 
 def logout(response: Response) -> None:
-    clear_cookie(response, key="session", path="/")
+    clear_cookie(response, "session", path="/")
 ```
 
 ### Brute-force throttling recipe
 
-`AttemptThrottle` counts failed attempts per key (typically `<endpoint>:<identifier>` — login email, password-reset target, etc.) and either yields a free attempt, locks the caller for a cooldown, or signals "back off" once the threshold is crossed. Two backends ship: `MemoryThrottleBackend` (defaults — process-local, perfect for tests and single-process services) and `RedisThrottleBackend` (multi-process / multi-host deployments).
+`AttemptThrottle` counts failed attempts per key (typically `<endpoint>:<identifier>` — login email, password-reset target, IP, etc.). The constructor takes a `backend` — any object matching the `ThrottleBackend` Protocol (`get`/`incr`/`expire`/`ttl`/`delete`), which `redis.asyncio.Redis` satisfies out of the box — plus `max_attempts` + `window_seconds`. No in-memory backend is bundled: pass the Redis client from `AsyncRedisManager` (or a [fakeredis](https://github.com/cunla/fakeredis-py) double in tests).
 
 ```python
-from tempest_fastapi_sdk import AttemptThrottle, ThrottleStatus, TooManyRequestsException
-from tempest_fastapi_sdk.utils.throttle import RedisThrottleBackend
+from tempest_fastapi_sdk import AttemptThrottle, UnauthorizedException
+from tempest_fastapi_sdk.cache import AsyncRedisManager
+
+from src.core.settings import settings
 
+cache = AsyncRedisManager(settings.REDIS_URL)
+# cache.client is redis.asyncio.Redis — matches the ThrottleBackend Protocol
 throttle = AttemptThrottle(
-    backend=RedisThrottleBackend(redis_manager=cache),
+    cache.client,
     max_attempts=5,
-    window_seconds=300,           # rolling window
-    lock_seconds=900,             # cooldown applied when threshold trips
+    window_seconds=300,         # fixed window; also the TTL on the first failure
+    namespace="login",          # key prefix so multiple throttles can coexist
+    fail_open=True,             # a Redis outage degrades to "allow", never locks everyone out
 )
 
 
 async def login(email: str, password: str) -> User:
-    status = await throttle.check(f"login:{email}")
-    if status is ThrottleStatus.LOCKED:
-        raise TooManyRequestsException(message="Too many attempts; try again later.")
+    key = f"login:{email}"
+    await throttle.raise_if_blocked(key)            # raises 429 when over budget
 
-    user = await users_repo.get_by_email(email)
-    if not password_utils.verify(password, user.password_hash):
-        await throttle.record_failure(f"login:{email}")
+    user = await users_repo.get_or_none({"email": email})
+    if user is None or not password_utils.verify(password, user.hashed_password):
+        await throttle.hit(key)                     # +1 failure, applies the TTL
         raise UnauthorizedException(message="Invalid credentials.")
 
-    await throttle.reset(f"login:{email}")
+    await throttle.reset(key)                       # success clears the counter
     return user
 ```
 
-`check()` returns a `ThrottleStatus` enum (`ALLOWED` / `LOCKED`); inspecting `.attempts_left` and `.retry_after_seconds` on the result lets you surface friendly error payloads. Pair with `TooManyRequestsException` so the SDK exception handler emits the canonical `{detail, code, details}` envelope with HTTP 429 and a `Retry-After` header.
+`throttle.status(key)` (peek without incrementing) and `throttle.hit(key)` (increment) both return a frozen `ThrottleStatus` dataclass — `attempts: int`, `blocked: bool`, `retry_after_seconds: int` — to build friendly error payloads. `raise_if_blocked` already raises `TooManyRequestsException`, which the SDK exception handler turns into the canonical `{detail, code, details}` envelope with HTTP 429 and a `Retry-After` header.
 
 ### Opaque tokens recipe
 
@@ -3305,7 +3311,7 @@ async def consume_reset_token(plain: str, user_id: UUID) -> bool:
 
 ### Client IP extraction recipe
 
-`get_client_ip(request)` and `get_client_ip_from_scope(scope)` return the real client IP behind an arbitrary chain of proxies. They inspect `Forwarded` (RFC 7239) first, fall back to `X-Forwarded-For` honoring an explicit `trusted_proxies` allowlist, and finally use the raw socket address — never naively trusting an inbound header.
+`get_client_ip(request)` and `get_client_ip_from_scope(scope)` return the real client IP behind a proxy. By design they accept **one** trusted header name (`trusted_header=`) that your edge proxy is known to set (e.g. `"x-real-ip"` on Nginx) — without it, they use the direct peer address. Anti-spoofing belongs at the proxy (which overwrites the header with the real peer), not in Python, so the SDK only reads the header you declare trusted.
 
 ```python
 from fastapi import Request
@@ -3315,15 +3321,13 @@ from tempest_fastapi_sdk import get_client_ip
 
 @router.post("/login")
 async def login(request: Request, payload: LoginIn) -> LoginOut:
-    ip = get_client_ip(
-        request,
-        trusted_proxies={"10.0.0.0/8", "192.168.0.0/16"},
-    )
-    await throttle.check(f"login:{ip}")
+    # Behind Nginx that overwrites X-Real-IP with the real peer:
+    ip = get_client_ip(request, trusted_header="x-real-ip")
+    await throttle.raise_if_blocked(f"login:{ip}")
     ...
 ```
 
-Use `get_client_ip_from_scope(scope)` from middleware or websocket handlers where only the ASGI scope is in reach. Both helpers normalize IPv6 brackets and refuse to return private addresses when `accept_private=False` is passed — handy when only public traffic should ever populate audit logs.
+Use `get_client_ip_from_scope(scope, trusted_header=...)` from middleware or websocket handlers where only the ASGI scope is in reach. If you expose the app directly to the internet, omit `trusted_header=` so the peer address is used.
 
 ### Command-line interface recipe