Instalação¶

Resumo¶

pip install tempest-fastapi-sdk

Requer Python 3.12+ (3.12, 3.13 e 3.14).

Use o uv

uv add tempest-fastapi-sdk é mais rápido e já escreve no pyproject.toml para você.

O comando tempest é o extra [cli]

Desde a 0.308.0 a CLI (tempest new, tempest check, tempest db, …) não vem no pacote base — ela traz o ruff, que não tem lugar na imagem de produção. Instale como ferramenta: uv tool install "tempest-fastapi-sdk[cli]", ou no grupo dev do projeto: uv add --dev "tempest-fastapi-sdk[cli]".

Primeira vez com Python moderno?

Esta página assume que você já tem um ambiente pronto. Se não tem, siga a trilha para iniciantes, que começa do zero absoluto: Instalar o uv » → Escolher a versão do Python » → Seu primeiro projeto » → Documentação oficial de referência ».

Extras opcionais¶

Os helpers mais ricos puxam dependências de terceiros que só são necessárias quando você de fato usa o helper. Escolha os extras que o seu serviço consome:

Extra	Puxa	Habilita
`[admin]`	`jinja2`, `itsdangerous`	`AdminSite`, `AdminModel`, `make_admin_router`
`[admin-sql]`	`sqlglot`	console SQL do admin: `SqlShellService` + `SqlShellPolicy` (capacidades, tabelas permitidas/negadas, teto de linhas), análise real do statement, auditoria de toda tentativa
`[auth]`	`bcrypt`, `PyJWT`	`PasswordUtils`, `JWTUtils`, fluxo bundled `UserAuthService` + `make_auth_router`
`[cache]`	`redis`	`AsyncRedisManager` + `@cached` + `RedisIdempotencyStore`
`[cli]`	`tempest-cli` (que exige `ruff`), `typer`, `click`	o comando `tempest` (`new`, `check`, `db`, …). Ferramenta de dev: `uv add --dev "tempest-fastapi-sdk[cli]"` ou `uv tool install "tempest-fastapi-sdk[cli]"`. Sem ele, o `tempest` imprime a instrução de instalação e sai com código 2. Entra no `[all]`. Receita
`[genai-onnx]`	`onnxruntime`, `tokenizers`	inferência de modelo local exportado para ONNX, sem PyTorch no runtime
`[genai-structured]`	`lm-format-enforcer`	saída estruturada garantida por gramática: o modelo local só consegue emitir JSON que casa com o schema
`[genai-vlm]`	`pillow`, `torchvision`	modelo de visão-linguagem local: descrever imagem, responder pergunta sobre imagem
`[openapi]`	`pyyaml`	ler spec OpenAPI em YAML para `tempest openapi-client` / `tempest openapi-errors`
`[pdf-read]`	`pypdf`	ler PDF (extrair texto/páginas); o `[pdf]` é para gerar
`[pdf-layout]`	`pdfplumber`	ler PDF com layout e tabelas (coluna recuperada, tabela como grade); mais lento que o `[pdf-read]`
`[spreadsheet]`	`openpyxl`	planilhas `.xlsx`: leitura tipada, escrita e import em massa
`[websocket]`	`websockets`	Driver de protocolo do `make_websocket_router` — sem ele o handshake devolve 404
`[email]`	`aiosmtplib`, `jinja2`, `email-validator`	`EmailUtils` (com `render_template` + templates Jinja2)
`[faces]`	`onnxruntime`, `pillow`, `numpy`	reconhecimento facial em ONNX Runtime, sem opencv e sem torch: `FaceRecognizer` (detectar/embutir/comparar), `compare_faces`. Modelos de 16 MB baixados por `ensure_models()`. Nenhuma biblioteca de sistema
`[firebase]`	`firebase-admin`	verificação de ID token do Firebase: `FirebaseAuth` (init idempotente, `get_identity` / `get_uid` / `get_optional_identity`), `FirebaseIdentity`, `FirebaseUserResolver`, `FirebaseSettings`. Pesado — 33 pacotes, 52 MB medidos com `firebase-admin` 7.5.0 — e por isso fora do `[all]`
`[genai]`	`transformers`, `torch`, `accelerate`, `safetensors`, `huggingface-hub`	GenAI local (pesado): `TextGenerator`, `Embedder`, `AIChatPipeline`, `make_genai_router` via HuggingFace/torch
`[genai-audio]`	`faster-whisper`, `coqui-tts`, `torch`, `torchaudio`, `torchcodec`, `transformers<5`	STT (Whisper) + TTS (Coqui) — o runtime do Coqui vem junto desde a v0.252.0. O teto `transformers<5` é intencional e rebaixa `huggingface-hub`, `tokenizers` e `diffusers`: veja o aviso abaixo da tabela
`[genai-chroma]`	`chromadb`	vector store Chroma pro RAG
`[genai-diarization]`	`sherpa-onnx`	diarização (quem falou quando) via `sherpa-onnx` em ONNX Runtime, sem PyTorch: `SpeakerDiarizer`, `ConversationTranscriber`. Modelos (46 MB) baixados por `ensure_models()`
`[genai-hosted]`	`httpx` (já vem no pacote base)	provedores hospedados: `AnthropicGenerator`, `OpenAICompatGenerator` (OpenAI, DeepSeek), `OpenAICompatEmbedder`, `HostedGenAISettings`. Nenhum SDK de fornecedor
`[genai-hub]`	`huggingface-hub`	ciclo de vida do peso: `resolve_revision` (fixar sha), `download_model` (baixar antes de servir, com preflight de disco), `list_cached_models`/`remove_cached_model`, `tempest model pull`/`cache-list`/`cache-rm`
`[genai-image]`	`diffusers`, `pillow`	geração de imagem local: `ImageGenerator` (`generate` texto→imagem, `edit` imagem→imagem), `ImageGenerationConfig`, rota `POST /image`
`[genai-ollama]`	`httpx`	backend Ollama: `OllamaGenerator`, `OllamaEmbedder`
`[genai-quant]`	`bitsandbytes`	quantização 4/8-bit dos modelos locais do `[genai]`
`[genai-rag]`	`trafilatura`, `pymupdf`, `pgvector`, `httpx`	ingestão RAG: scraping web, extração de PDF e embeddings em pgvector
`[geo]`	`httpx`	helpers geoespaciais: `haversine_km`, `estimate_travel`, `NominatimBackend`/`OSRMBackend` (geocoding + rotas), `GeoPointMixin`
`[http]`	`httpx` (já vem no pacote base)	`HTTPClient` + `RetryPolicy` + circuit-breaker. O extra é opcional: o `HTTPClient` funciona na instalação base, e declarar o extra só registra a intenção no `pyproject.toml` do serviço
`[metrics]`	`psutil`, `nvidia-ml-py`	`MetricsUtils`
`[mfa]`	`pyotp`	`TOTPHelper` + endpoints MFA/2FA (TOTP) do fluxo bundled de auth
`[minio]`	`minio`	`AsyncMinIOClient`, `MinIOUploadStorage`
`[modelops]`	`psutil`, `nvidia-ml-py`, `numpy`	benchmark de qualquer callable: latência, RAM, GPU e energia (`benchmark`, `NvmlPowerSampler`, `RaplEnergySampler`); monitoramento de deriva (`baseline_from_samples`, `PredictionMonitor`) e leitura do formato compacto (`read_compact`, `predict_compact`)
`[modelops-compose]`	`ort-vision-sdk[compose]`	fundir um detector e um classificador num único `.onnx`: `fuse_detect_classify`. Rodar o grafo fundido é `[vision]` (`DetectClassify`), que não puxa `onnx`
`[modelops-onnx]`	`onnx`, `onnxruntime`	análise estática, benchmark ONNX, `.onnx` → `.ort`, otimização de grafo e quantização — de grafos crus (`analyze_onnx`, `benchmark_onnx`, `export_onnx_to_ort`, `quantize_onnx_dynamic`) e de exports transformers (`optimize_hf_onnx`, `quantize_hf_onnx`)
`[modelops-sklearn]`	`skl2onnx`	exportar modelos scikit-learn para ONNX (borda): `export_sklearn_to_onnx`, `verify_sklearn_onnx`, `edge_bundle`
`[oidc]`	`PyJWT`, `cryptography`	verificação offline de access token de realm OIDC (Keycloak, Auth0, Okta …): `OIDCTokenVerifier`, e `OIDCProvider(token_verifier=...)` no login social
`[otel]`	`opentelemetry-sdk`, exporter OTLP + instrumentações FastAPI/SQLAlchemy/httpx	instrumentação OpenTelemetry via `setup_tracing`
`[pdf]`	`weasyprint`, `jinja2`, `segno`	geração de PDF a partir de templates HTML: `PdfRenderer`, cinco documentos prontos com schema tipado, `make_pdf_router`, `tempest pdf`. Exige Pango + fontconfig no sistema — veja a receita
`[postgres]`	`asyncpg`	driver async PostgreSQL para URLs `postgresql+asyncpg://` (produção)
`[prometheus]`	`prometheus-client`	`PrometheusMiddleware`, `make_prometheus_router`, `make_prometheus_registry`
`[queue]`	`faststream[rabbit]`	`AsyncBrokerManager`
`[sqlite]`	`aiosqlite`	driver async SQLite para URLs `sqlite+aiosqlite://` (default de dev)
`[ssr]`	`tempestweb`	SSR com HTMX: `build_web_app`, `make_htmx_router`, `Page`, helper `htmx`
`[tasks]`	`taskiq`, `taskiq-aio-pika`	`AsyncTaskBrokerManager`, `AsyncTaskScheduler`
`[tasks-redis]`	`taskiq`, `taskiq-redis`	`TaskQueue.redis` / `TaskQueue.from_settings` sobre Redis Streams, result backend e o lease do scheduler
`[tests]`	`pytest`, `pytest-asyncio`, `pytest-xdist`	a suíte do serviço e o `tempest test --fast` (suíte em paralelo, a partir do `tempest-cli` 0.4.0). Sem teto próprio; herda `pytest<10` do `pytest-asyncio` e `pluggy<2` do `pytest`. Ferramenta de teste, não helper — fica fora do `[all]`. Receita
`[upload]`	`aiofiles`, `python-multipart`	`UploadUtils`, `DownloadUtils`, `LocalUploadStorage`
`[vision]`	`ort-vision-sdk`	helpers de visão (`Detector`, `Classifier`, `Segmenter` + `to_detection_schemas`/`to_classification_schema`/`to_segmentation_schemas`)
`[webauthn]`	`fido2`	passkeys / chaves de segurança: `WebAuthnService`, `make_web_authn_credential_model`, rotas `/auth/webauthn/*` — login sem senha, resistente a phishing
`[webpush]`	`pywebpush`, `cryptography`	`WebPushDispatcher`
`[all]`	tudo acima exceto os 15 extras de stack pesado ou binário nativo: `[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]`	os helpers de aplicação — instale os 15 acima à parte (e o `[tests]`, que é ferramenta de teste, no grupo de dev)

Subconjunto (recomendado)Tudouv 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",
]

O [genai-audio] fixa transformers<5 de propósito, e isso rebaixa outros pacotes

O teto não é um pino acidental. Ao carregar TTS.api, o coqui-tts importa isin_mps_friendly de transformers.pytorch_utils, e esse símbolo existe na transformers 5.0.0 e some da 5.1.0 em diante. Remedido em 2026-10-09 com coqui-tts 0.27.5, transformers 5.19.0 e torch 2.14.0, o import ainda morre com ImportError: cannot import name 'isin_mps_friendly' from 'transformers.pytorch_utils'.

O custo vem de a transformers 4.57.6 declarar huggingface-hub<1.0 e tokenizers<=0.23.0; e o diffusers 0.40.0 já exige huggingface-hub>=1.23.0. Resolvido com uv pip compile (Python 3.12) em 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]` sem o `[genai-audio]`	—	1.33.0	—	0.41.0

O teto mora só no [genai-audio]: sem esse extra, ele não entra na sua resolução. Precisa de huggingface-hub 1.x ou de um diffusers mais novo no mesmo ambiente do [genai-audio]? Não relaxe o teto localmente: o SDK não testa essa combinação, e o TTS deixa de importar. Abra uma issue com a versão de que você precisa.

O SDK não traz driver de banco por padrão

sqlalchemy[asyncio] é dependência core, mas o DBAPI async é escolha do seu deploy: instale [sqlite] (aiosqlite, default de dev) ou [postgres] (asyncpg, produção). Sem nenhum, o engine levanta ModuleNotFoundError do driver na primeira conexão. Serviços criados com tempest new já pinam aiosqlite e asyncpg no pyproject.toml — o segundo é o que o profile prod do docker-compose.yaml gerado usa.

Imports preguiçosos

Desde a 0.7.1 toda dependência opcional é importada de forma preguiçosa na primeira instanciação, então import tempest_fastapi_sdk funciona mesmo quando só um subconjunto de extras está instalado. Instanciar um helper cujo extra está faltando levanta ImportError com uma dica clara apontando para o extra certo.

CLI¶

A CLI tempest vem na instalação base (sem extra):

tempest --version              # mostra a versão instalada do SDK
tempest new                    # gera um serviço em camadas no diretório atual
tempest new myproject          # gera dentro de ./myproject
tempest generate --docker      # regenera docker-compose.yaml a partir dos extras já escolhidos
tempest db init                # bootstrapa diretório alembic (alembic.ini sem credenciais)
tempest db revision -m "msg"   # autogenerate revision aplicando o reorder hook
tempest db upgrade             # roda upgrade até head (lê DATABASE_URL do .env)
tempest db downgrade -1        # volta uma revisão
tempest db current             # mostra revisão atual
tempest db history             # log de revisões
tempest user create --email admin@local --admin   # `--email` obrigatório; senha pedida interativamente
tempest user list --admin      # lista somente os admins (omita `--admin` pra listar todos)
tempest fix                    # ruff check --fix-only . + ruff format . + ruff check .
tempest check                  # lint + fmt-check + mypy + pytest

Veja Receitas → CLI » para o detalhamento completo.

Verifique a instalação¶

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

Política de versões do Python¶

Python	Status
3.14	Suportado
3.13	Suportado — a versão do `.python-version` do repositório
3.12	Suportado (mínimo)
3.11	Não suportado desde a 0.314.0 — fica na 0.313.x (migração)
3.10 e anteriores	Não suportado (usa a sintaxe `X \| None` do PEP 604)