Installation¶

TL;DR¶

pip install tempest-fastapi-sdk

Requires Python 3.12+ (3.12, 3.13 and 3.14).

Use uv instead

uv add tempest-fastapi-sdk is faster and writes to pyproject.toml for you.

The tempest command is the [cli] extra

Since 0.308.0 the CLI (tempest new, tempest check, tempest db, …) is not part of the base package — it brings ruff, which has no place in a production image. Install it as a tool: uv tool install "tempest-fastapi-sdk[cli]", or in the project's dev group: uv add --dev "tempest-fastapi-sdk[cli]".

First time with modern Python?

This page assumes you already have a working environment. If you do not, follow the beginner track, which starts from absolute zero: Install uv » → Pick your Python version » → Your first project » → Official reference docs ».

Optional extras¶

Feature-rich helpers pull in third-party dependencies that you only need when you actually use the helper. Pick the extras your service consumes:

Extra	Pulls in	Unlocks
`[admin]`	`jinja2`, `itsdangerous`	`AdminSite`, `AdminModel`, `make_admin_router`
`[admin-sql]`	`sqlglot`	admin SQL console: `SqlShellService` + `SqlShellPolicy` (capabilities, allowed/denied tables, row cap), real statement parsing, every attempt audited
`[auth]`	`bcrypt`, `PyJWT`	`PasswordUtils`, `JWTUtils`, bundled `UserAuthService` + `make_auth_router` flow
`[cache]`	`redis`	`AsyncRedisManager` + `@cached` + `RedisIdempotencyStore`
`[cli]`	`tempest-cli` (which requires `ruff`), `typer`, `click`	the `tempest` command (`new`, `check`, `db`, …). Dev tooling: `uv add --dev "tempest-fastapi-sdk[cli]"` or `uv tool install "tempest-fastapi-sdk[cli]"`. Without it, `tempest` prints the install line and exits with code 2. Included in `[all]`. Recipe
`[genai-onnx]`	`onnxruntime`, `tokenizers`	Local-model inference from an ONNX export, with no PyTorch at runtime
`[genai-structured]`	`lm-format-enforcer`	Grammar-enforced structured output: the local model can only emit JSON matching the schema
`[genai-vlm]`	`pillow`, `torchvision`	Local vision-language model: describe an image, answer a question about one
`[openapi]`	`pyyaml`	Read a YAML OpenAPI spec for `tempest openapi-client` / `tempest openapi-errors`
`[pdf-read]`	`pypdf`	Read PDFs (extract text/pages); `[pdf]` is for generating them
`[pdf-layout]`	`pdfplumber`	Read PDFs with layout and tables (columns recovered, tables as grids); slower than `[pdf-read]`
`[spreadsheet]`	`openpyxl`	`.xlsx` spreadsheets: typed reading, writing and bulk import
`[websocket]`	`websockets`	Protocol driver for `make_websocket_router` — without it the handshake 404s
`[email]`	`aiosmtplib`, `jinja2`, `email-validator`	`EmailUtils` (with `render_template` + Jinja2 templates)
`[faces]`	`onnxruntime`, `pillow`, `numpy`	Face recognition on ONNX Runtime, no opencv and no torch: `FaceRecognizer` (detect/embed/compare), `compare_faces`. 16 MB models fetched by `ensure_models()`. No system libraries
`[firebase]`	`firebase-admin`	Firebase ID token verification: `FirebaseAuth` (idempotent init, `get_identity` / `get_uid` / `get_optional_identity`), `FirebaseIdentity`, `FirebaseUserResolver`, `FirebaseSettings`. Heavy — 33 packages, 52 MB measured on `firebase-admin` 7.5.0 — and therefore out of `[all]`
`[genai]`	`transformers`, `torch`, `accelerate`, `safetensors`, `huggingface-hub`	local (heavy) GenAI: `TextGenerator`, `Embedder`, `AIChatPipeline`, `make_genai_router` via HuggingFace/torch
`[genai-audio]`	`faster-whisper`, `coqui-tts`, `torch`, `torchaudio`, `torchcodec`, `transformers<5`	STT (Whisper) + TTS (Coqui) — the Coqui runtime ships with it since v0.252.0. The `transformers<5` cap is intentional and holds back `huggingface-hub`, `tokenizers` and `diffusers`: see the warning below the table
`[genai-chroma]`	`chromadb`	Chroma vector store for RAG
`[genai-diarization]`	`sherpa-onnx`	Speaker diarization (who spoke when) via `sherpa-onnx` on ONNX Runtime, no PyTorch: `SpeakerDiarizer`, `ConversationTranscriber`. Models (46 MB) fetched by `ensure_models()`
`[genai-hosted]`	`httpx` (already in the base package)	hosted providers: `AnthropicGenerator`, `OpenAICompatGenerator` (OpenAI, DeepSeek), `OpenAICompatEmbedder`, `HostedGenAISettings`. No vendor SDK
`[genai-hub]`	`huggingface-hub`	weight lifecycle: `resolve_revision` (pin a sha), `download_model` (fetch before serving, with a disk preflight), `list_cached_models`/`remove_cached_model`, `tempest model pull`/`cache-list`/`cache-rm`
`[genai-image]`	`diffusers`, `pillow`	local image generation: `ImageGenerator` (`generate` text→image, `edit` image→image), `ImageGenerationConfig`, `POST /image` route
`[genai-ollama]`	`httpx`	Ollama backend: `OllamaGenerator`, `OllamaEmbedder`
`[genai-quant]`	`bitsandbytes`	4/8-bit quantization for the local `[genai]` models
`[genai-rag]`	`trafilatura`, `pymupdf`, `pgvector`, `httpx`	RAG ingestion: web scraping, PDF extraction, and pgvector embeddings
`[geo]`	`httpx`	geospatial helpers: `haversine_km`, `estimate_travel`, `NominatimBackend`/`OSRMBackend` (geocoding + routing), `GeoPointMixin`
`[http]`	`httpx` (already in the base package)	`HTTPClient` + `RetryPolicy` + circuit-breaker. The extra is optional: `HTTPClient` works on the base install, and declaring the extra only records the intent in the service's `pyproject.toml`
`[metrics]`	`psutil`, `nvidia-ml-py`	`MetricsUtils`
`[mfa]`	`pyotp`	`TOTPHelper` + MFA/2FA (TOTP) endpoints on the bundled auth flow
`[minio]`	`minio`	`AsyncMinIOClient`, `MinIOUploadStorage`
`[modelops]`	`psutil`, `nvidia-ml-py`, `numpy`	benchmark any callable: latency, RAM, GPU and energy (`benchmark`, `NvmlPowerSampler`, `RaplEnergySampler`); drift monitoring (`baseline_from_samples`, `PredictionMonitor`) and reading the compact format (`read_compact`, `predict_compact`)
`[modelops-compose]`	`ort-vision-sdk[compose]`	fuse a detector and a classifier into one `.onnx`: `fuse_detect_classify`. Running the fused graph is `[vision]` (`DetectClassify`), which pulls no `onnx`
`[modelops-onnx]`	`onnx`, `onnxruntime`	static analysis, ONNX benchmarking, `.onnx` → `.ort`, graph optimization and quantization — of raw graphs (`analyze_onnx`, `benchmark_onnx`, `export_onnx_to_ort`, `quantize_onnx_dynamic`) and of transformers exports (`optimize_hf_onnx`, `quantize_hf_onnx`)
`[modelops-sklearn]`	`skl2onnx`	export scikit-learn models to ONNX for the edge: `export_sklearn_to_onnx`, `verify_sklearn_onnx`, `edge_bundle`
`[oidc]`	`PyJWT`, `cryptography`	offline verification of OIDC realm access tokens (Keycloak, Auth0, Okta …): `OIDCTokenVerifier`, and `OIDCProvider(token_verifier=...)` for social login
`[otel]`	`opentelemetry-sdk`, OTLP exporter + FastAPI/SQLAlchemy/httpx instrumentations	OpenTelemetry instrumentation via `setup_tracing`
`[pdf]`	`weasyprint`, `jinja2`, `segno`	PDF generation from HTML templates: `PdfRenderer`, five bundled typed documents, `make_pdf_router`, `tempest pdf`. Needs Pango + fontconfig on the system — see the recipe
`[postgres]`	`asyncpg`	PostgreSQL async driver for `postgresql+asyncpg://` URLs (production)
`[prometheus]`	`prometheus-client`	`PrometheusMiddleware`, `make_prometheus_router`, `make_prometheus_registry`
`[queue]`	`faststream[rabbit]`	`AsyncBrokerManager`
`[sqlite]`	`aiosqlite`	SQLite async driver for `sqlite+aiosqlite://` URLs (dev default)
`[ssr]`	`tempestweb`	HTMX-based SSR: `build_web_app`, `make_htmx_router`, `Page`, the `htmx` helper
`[tasks]`	`taskiq`, `taskiq-aio-pika`	`AsyncTaskBrokerManager`, `AsyncTaskScheduler`
`[tasks-redis]`	`taskiq`, `taskiq-redis`	`TaskQueue.redis` / `TaskQueue.from_settings` over Redis Streams, the result backend and the scheduler lease
`[tests]`	`pytest`, `pytest-asyncio`, `pytest-xdist`	the service's suite and `tempest test --fast` (the suite in parallel, from `tempest-cli` 0.4.0 on). No bound of its own; inherits `pytest<10` from `pytest-asyncio` and `pluggy<2` from `pytest`. Test tooling, not a helper — kept out of `[all]`. Recipe
`[upload]`	`aiofiles`, `python-multipart`	`UploadUtils`, `DownloadUtils`, `LocalUploadStorage`
`[vision]`	`ort-vision-sdk`	vision helpers (`Detector`, `Classifier`, `Segmenter` + `to_detection_schemas`/`to_classification_schema`/`to_segmentation_schemas`)
`[webauthn]`	`fido2`	Passkeys / security keys: `WebAuthnService`, `make_web_authn_credential_model`, the `/auth/webauthn/*` routes — passwordless, phishing-resistant login
`[webpush]`	`pywebpush`, `cryptography`	`WebPushDispatcher`
`[all]`	everything above except the 15 extras that pull a heavy stack or a native binary: `[genai]`, `[genai-audio]`, `[genai-diarization]`, `[genai-hub]`, `[genai-image]`, `[genai-onnx]`, `[genai-quant]`, `[genai-rag]`, `[genai-structured]`, `[genai-vlm]`, `[faces]`, `[modelops-onnx]`, `[modelops-sklearn]`, `[admin-sql]`, `[firebase]`	the application helpers — install the 15 above separately (and `[tests]`, which is test tooling, in the dev group)

Subset (recommended)Everythinguv addpyproject.toml

pip install "tempest-fastapi-sdk[auth,upload,cache]"

pip install "tempest-fastapi-sdk[all]"

uv add "tempest-fastapi-sdk[auth,upload,postgres]>=0.171.0"

dependencies = [
    "tempest-fastapi-sdk[auth,upload,postgres]>=0.171.0",
]

[genai-audio] caps transformers<5 on purpose, and that holds other packages back

The cap is not an accidental pin. When loading TTS.api, coqui-tts imports isin_mps_friendly from transformers.pytorch_utils, and that symbol exists in transformers 5.0.0 and is gone from 5.1.0 on. Re-measured on 2026-10-09 with coqui-tts 0.27.5, transformers 5.19.0 and torch 2.14.0, the import still dies with ImportError: cannot import name 'isin_mps_friendly' from 'transformers.pytorch_utils'.

The cost comes from transformers 4.57.6 declaring huggingface-hub<1.0 and tokenizers<=0.23.0; and diffusers 0.40.0 already requires huggingface-hub>=1.23.0. Resolved with uv pip compile (Python 3.12) on 2026-10-09:

Extras	`transformers`	`huggingface-hub`	`tokenizers`	`diffusers`
`[genai-audio]`	4.57.6	0.36.2	0.22.2	—
`[genai-audio,genai-image]`	4.57.6	0.36.2	0.22.2	0.39.0
`[genai-image]` without `[genai-audio]`	—	1.33.0	—	0.41.0

The cap lives only in [genai-audio]: if you do not install that extra, it never enters your resolution. Need huggingface-hub 1.x or a newer diffusers in the same environment as [genai-audio]? Do not relax the cap locally: the SDK does not test that combination, and the TTS stops importing. Open an issue with the version you need.

The SDK ships no database driver by default

sqlalchemy[asyncio] is core, but the async DBAPI is your deploy choice: install [sqlite] (aiosqlite, dev default) or [postgres] (asyncpg, production). Without one, the engine raises ModuleNotFoundError for the driver on first connection. Services scaffolded with tempest new already pin both aiosqlite and asyncpg in pyproject.toml — the latter is what the generated docker-compose.yaml's prod profile uses.

Lazy imports

Since 0.7.1 every optional dependency is imported lazily at first instantiation, so import tempest_fastapi_sdk works even when only a subset of extras is installed. Instantiating a helper whose extra is missing raises ImportError with a clear hint pointing at the right extra.

CLI¶

The tempest CLI ships in the base install (no extra needed):

tempest --version              # show installed SDK version
tempest new                    # scaffold a layered service in cwd
tempest new myproject          # scaffold inside ./myproject
tempest generate --docker      # regenerate docker-compose.yaml from chosen extras
tempest db init                # bootstrap alembic dir (alembic.ini with no credentials)
tempest db revision -m "msg"   # autogenerate revision with the reorder hook applied
tempest db upgrade             # run upgrade to head (reads DATABASE_URL from .env)
tempest db downgrade -1        # roll back one revision
tempest db current             # show current revision
tempest db history             # revision log
tempest user create --email admin@local --admin   # `--email` required; password prompted interactively
tempest user list --admin      # list admins only (drop `--admin` to list everyone)
tempest fix                    # ruff check --fix-only . + ruff format . + ruff check .
tempest check                  # lint + fmt-check + mypy + pytest

See Recipes → CLI » for the full breakdown.

Verify the install¶

python -c "import tempest_fastapi_sdk; print(tempest_fastapi_sdk.__version__)"

Python version policy¶

Python	Status
3.14	Supported
3.13	Supported — the version the repository's `.python-version` pins
3.12	Supported (minimum)
3.11	Not supported since 0.314.0 — stays on 0.313.x (migration)
3.10 and older	Not supported (uses `X \| None` PEP 604 syntax)