tempest-fastapi-sdk 0.293.0__tar.gz → 0.294.0__tar.gz

{tempest_fastapi_sdk-0.293.0 → tempest_fastapi_sdk-0.294.0}/CHANGELOG.md

@@ -5,6 +5,65 @@ 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.294.0] — 2026-09-19
+
+Um assistente local que roda dentro do WSL precisa agir na máquina que o
+hospeda — ler um arquivo em `C:\`, rodar PowerShell, desligar o computador.
+Isso vinha sendo um serviço separado, reescrito em cada projeto que precisava
+dele, com a parte perigosa (sandbox de caminho, auth, gate do lado
+destrutivo) reescrita junto.
+
+### Added
+
+- **`tempest_fastapi_sdk.hostbridge` — controle do host, sem extra nenhum.**
+  `HostBridge` cobre energia (`shutdown`/`restart`/`abort_shutdown`/`lock`/
+  `logoff`), identidade (`host_info`), arquivos (`read_text`/`write_text`/
+  `list_dir`/`delete`), PDF (`read_pdf`), comando arbitrário (`run_command`)
+  e o seletor nativo (`pick_file`). Tudo async, com o que toca disco ou
+  processo fora do event loop. Configuração é `HostBridgeConfig` — um value
+  object congelado — ou `HostBridgeSettings` vindo do ambiente, via
+  `hostbridge_kwargs()`.
+
+  **As duas decisões de segurança são estruturais, não avisos na doc.**
+  `allowed_base_paths` começa **vazio**, negando todo caminho até alguém
+  configurar, e o caminho é **resolvido antes de ser checado** — checar antes
+  de resolver deixa `.../../../etc/passwd` passar por começar dentro de uma
+  base permitida. `make_hostbridge_router` **exige** a lista de dependências
+  de auth na assinatura e recusa uma vazia, e o lado que escreve (comando,
+  escrita, remoção, energia) só é montado com `destructive=True`.
+
+  Onde não existe host para alcançar — container Linux puro, nem
+  `powershell.exe` nem `wslpath` — a chamada levanta `HostUnavailableError`
+  (503, `HOST_UNAVAILABLE`) em vez de uma falha genérica, então o chamador
+  degrada em vez de reportar que a ação falhou. Cada código
+  (`HOST_INVALID_PATH`, `HOST_FILE_NOT_FOUND`, `HOST_FILE_TOO_LARGE`,
+  `HOST_FILE_DECODE_FAILED`, `HOST_COMMAND_FAILED`, `HOST_COMMAND_TIMEOUT`,
+  `HOST_UNAVAILABLE`) ships frase PT-BR e en-US no `default_message_catalog`.
+
+- **`read_pdf_pages` + o extra `[pdf-layout]`.** O leitor que já existia
+  (`extract_pdf_text` / `extract_pdf_pages`, `[pdf-read]`) entrega prosa; um
+  documento com colunas sai intercalado linha a linha e uma tabela sai como
+  fluxo de células. `PdfExtractor.LAYOUT` roda `pdfplumber`, que recupera a
+  grade em `PdfPage.tables`, e o novo caminho aceita senha, distinguindo
+  documento cifrado (`PDF_DECRYPT_FAILED`) de arquivo corrompido
+  (`PDF_EXTRACT_FAILED`). Continua sem OCR: página escaneada volta com
+  `text=""` — a entrada `n` é sempre a página `n` — em vez de sumir.
+
+- **`HostBridgeSettings`**, mais um mixin de settings, com
+  `HOST_ALLOWED_BASE_PATHS`, `HOST_POWERSHELL_BINARY`, `HOST_CMD_BINARY`,
+  `HOST_COMMAND_TIMEOUT` e `HOST_MAX_FILE_READ_BYTES`.
+
+### Fixed
+
+- **Senha errada num PDF lido com `[pdf-layout]` dizia "arquivo
+  ilegível".** O `pdfplumber` embrulha todo erro de parse num único
+  `PdfminerException` construído a partir do original, então o
+  `except PDFPasswordIncorrect` nunca disparava e o caso — que o chamador
+  resolve digitando a senha certa — saía como `PDF_EXTRACT_FAILED`,
+  mandando quem lê procurar um documento quebrado que não existia. A cadeia
+  (argumentos, `__cause__`, `__context__`) agora é percorrida atrás da falha
+  de senha real.
+
 ## [0.293.0] — 2026-09-13
 
 A CLI sabia criar usuário e sabia promovê-lo, mas não sabia trocar a senha

{tempest_fastapi_sdk-0.293.0 → tempest_fastapi_sdk-0.294.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: tempest-fastapi-sdk
-Version: 0.293.0
+Version: 0.294.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
@@ -60,6 +60,7 @@ Requires-Dist: opentelemetry-instrumentation-httpx>=0.65b0; extra == 'all'
 Requires-Dist: opentelemetry-instrumentation-sqlalchemy>=0.65b0; extra == 'all'
 Requires-Dist: opentelemetry-sdk>=1.44.0; extra == 'all'
 Requires-Dist: ort-vision-sdk[compose]>=0.8.0; extra == 'all'
+Requires-Dist: pdfplumber>=0.11.7; extra == 'all'
 Requires-Dist: prometheus-client>=0.26.0; extra == 'all'
 Requires-Dist: psutil>=7.2.2; extra == 'all'
 Requires-Dist: pyjwt>=2.13.0; extra == 'all'
@@ -164,6 +165,8 @@ Requires-Dist: opentelemetry-sdk>=1.44.0; extra == 'otel'
 Provides-Extra: pdf
 Requires-Dist: jinja2>=3.1.6; extra == 'pdf'
 Requires-Dist: weasyprint>=69.0; extra == 'pdf'
+Provides-Extra: pdf-layout
+Requires-Dist: pdfplumber>=0.11.7; extra == 'pdf-layout'
 Provides-Extra: pdf-read
 Requires-Dist: pypdf>=6.16.2; extra == 'pdf-read'
 Provides-Extra: postgres
@@ -323,6 +326,7 @@ Feature-rich helpers pull in third-party dependencies that you only need when yo
 | `[mfa]` | `pyotp` | `TOTPHelper` + MFA/2FA endpoints on the bundled auth flow |
 | `[pdf]` | `weasyprint`, `jinja2` | PDF generation from HTML templates — `PdfRenderer`, five bundled typed documents (receipt/quote/report/contract/voucher), `make_pdf_router`, `tempest pdf`. Needs Pango + fontconfig on the system |
 | `[pdf-read]` | `pypdf` | Reading the text layer back out of a PDF — `extract_pdf_text` / `extract_pdf_pages`, page markers, honest truncation. Separate from `[pdf]` so a service that only reads carries no WeasyPrint and no system libraries |
+| `[pdf-layout]` | `pdfplumber` | Layout-aware reading — columns recovered instead of interleaved, tables recovered as grids, encrypted files opened with a password. Separate from `[pdf-read]` because it is markedly slower and pulls `pdfminer.six` |
 | `[spreadsheet]` | `openpyxl` | `.xlsx` generation — `SheetWriter` (row cursor, column specs, themed rows), `SheetStyle`, `BR_*` number formats pinned to pt-BR, `new_workbook` / `workbook_to_bytes` |
 | `[webauthn]` | `fido2` | Passkeys / security keys — `WebAuthnService`, `make_web_authn_credential_model`, `/auth/webauthn/*`: passwordless, phishing-resistant login |
 | `[firebase]` | `firebase-admin` | Firebase ID token verification — `FirebaseAuth` (idempotent app init, `get_identity` / `get_uid` / `get_optional_identity`), `FirebaseIdentity`, `FirebaseUserResolver`, `FirebaseSettings`; one error `code` per failure. Heavy (33 packages, 52 MB measured on firebase-admin 7.5.0), lazily imported, out of `[all]` |
@@ -383,6 +387,7 @@ Since `0.7.1` every optional dependency is imported lazily at first instantiatio
 | `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, `.inventory()` / `.unload_idle()`); **runtime inventory** — `describe_model` / `runtime_report` → `LoadedModel` / `ModelRuntimeReport` (what is resident now, loaded-first and longest-idle-first, next to the host memory picture; reads attributes only, never triggers a load) + `GET /models`; `make_genai_router` (opt-in endpoints — `/generate`+SSE, `/chat`, `/embed`, `/rag`, `/transcribe`, `/tts`, `/image`); **image generation** (`[genai-image]`) — `ImageGenerator` (`generate` / `edit`) + `ImageGenerationConfig` + `GeneratedImage`; `resolve_device`/`auto_dtype_name`; **weight lifecycle** (`[genai-hub]`) — `ModelRef` (`revision=`/`local_files_only=`/`trust_remote_code=` uniform across every loader), `resolve_revision` (pin a branch to a commit sha), `download_model` (fetch ahead of the first request, refusing what the disk cannot hold) + `model_disk_bytes`, `list_cached_models`/`cache_size_bytes`/`remove_cached_model`; **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=…)`); **hosted backend** (no extra) — `OpenAICompatGenerator` for any OpenAI-compatible `/chat/completions` (DeepSeek, Groq, OpenRouter, vLLM, TGI, Azure) behind the same `TextBackend`, `generate_with_usage` → `TokenUsage` (incl. `cache_hit_tokens`, read in both the DeepSeek and OpenAI spellings), `extra_body` for provider extensions; **JSON payloads** — `extract_json_list`/`extract_json_object`/`parse_structured_list` (balanced-span extraction, `None` instead of raising so a caller can retry) + `generate_structured_list` (retries at a rising temperature, `StructuredFormatError`); **usage accounting** — `BaseAIUsageModel` + `AIUsageStore` (one row per paid call: `record`/`record_duration`, `totals`/`by_service`/`per_day`/`top_subjects`, cost priced at read time, cached prefixes billed at `price_cache_hit_per_1k`); **`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.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`, plus `batch_size` for batched decoding, `cpu_threads`/`num_workers`, `condition_on_previous_text` and `transcribe(on_progress=)`) + `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.hostbridge` *(no extra; `[pdf-read]` / `[pdf-layout]` for PDFs)* | Control the machine the service runs on, from WSL or Windows itself — `HostBridge` (power actions, host info, text read/write/list/delete, PDF pages, arbitrary PowerShell/`cmd`, the native file picker), `HostBridgeConfig` / `HostBridgeSettings`, `make_hostbridge_router` (auth required by signature, write side behind `destructive=True`), WSL ↔ Windows path translation resolved before it is checked against `allowed_base_paths`, and `HOST_UNAVAILABLE` (503) where there is no host to reach |
 | `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.asyncapi` | `generate_stream`, `load_asyncapi_spec`, `parse_asyncapi`, `emit_stream`, `StreamGenerationResult`, `AsyncApiIR` / `StreamIR` / `ChannelIR` / `MessageIR` / `OperationIR` — backs `tempest asyncapi-client`, which generates a typed WebSocket client from an AsyncAPI 3 document: payload models plus two tagged unions, one for the frames you send and one for those you receive. OpenAPI cannot describe a socket, so this is a second document, not a second reader of the first. The document must declare `x-tempest-perspective` — `action` is relative to whoever published it, a client inverts every one, and a wrong inversion still compiles *(needs the `[websocket]` extra)* |
 | `tempest_fastapi_sdk.integrations.messaging.zap` | `ZapClient` + the in-house WhatsApp gateway's 28 schemas and 27 operations (generated from the vendored spec, checked in, loaded lazily). A send answers `202` with the enqueued row, not a delivery — pass one `idempotency_key` per message so a retry answers `deduped: true` instead of sending twice. The status webhook has no schema in the specification yet, so it is not modelled |

{tempest_fastapi_sdk-0.293.0 → tempest_fastapi_sdk-0.294.0}/README.md

@@ -123,6 +123,7 @@ Feature-rich helpers pull in third-party dependencies that you only need when yo
 | `[mfa]` | `pyotp` | `TOTPHelper` + MFA/2FA endpoints on the bundled auth flow |
 | `[pdf]` | `weasyprint`, `jinja2` | PDF generation from HTML templates — `PdfRenderer`, five bundled typed documents (receipt/quote/report/contract/voucher), `make_pdf_router`, `tempest pdf`. Needs Pango + fontconfig on the system |
 | `[pdf-read]` | `pypdf` | Reading the text layer back out of a PDF — `extract_pdf_text` / `extract_pdf_pages`, page markers, honest truncation. Separate from `[pdf]` so a service that only reads carries no WeasyPrint and no system libraries |
+| `[pdf-layout]` | `pdfplumber` | Layout-aware reading — columns recovered instead of interleaved, tables recovered as grids, encrypted files opened with a password. Separate from `[pdf-read]` because it is markedly slower and pulls `pdfminer.six` |
 | `[spreadsheet]` | `openpyxl` | `.xlsx` generation — `SheetWriter` (row cursor, column specs, themed rows), `SheetStyle`, `BR_*` number formats pinned to pt-BR, `new_workbook` / `workbook_to_bytes` |
 | `[webauthn]` | `fido2` | Passkeys / security keys — `WebAuthnService`, `make_web_authn_credential_model`, `/auth/webauthn/*`: passwordless, phishing-resistant login |
 | `[firebase]` | `firebase-admin` | Firebase ID token verification — `FirebaseAuth` (idempotent app init, `get_identity` / `get_uid` / `get_optional_identity`), `FirebaseIdentity`, `FirebaseUserResolver`, `FirebaseSettings`; one error `code` per failure. Heavy (33 packages, 52 MB measured on firebase-admin 7.5.0), lazily imported, out of `[all]` |
@@ -183,6 +184,7 @@ Since `0.7.1` every optional dependency is imported lazily at first instantiatio
 | `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, `.inventory()` / `.unload_idle()`); **runtime inventory** — `describe_model` / `runtime_report` → `LoadedModel` / `ModelRuntimeReport` (what is resident now, loaded-first and longest-idle-first, next to the host memory picture; reads attributes only, never triggers a load) + `GET /models`; `make_genai_router` (opt-in endpoints — `/generate`+SSE, `/chat`, `/embed`, `/rag`, `/transcribe`, `/tts`, `/image`); **image generation** (`[genai-image]`) — `ImageGenerator` (`generate` / `edit`) + `ImageGenerationConfig` + `GeneratedImage`; `resolve_device`/`auto_dtype_name`; **weight lifecycle** (`[genai-hub]`) — `ModelRef` (`revision=`/`local_files_only=`/`trust_remote_code=` uniform across every loader), `resolve_revision` (pin a branch to a commit sha), `download_model` (fetch ahead of the first request, refusing what the disk cannot hold) + `model_disk_bytes`, `list_cached_models`/`cache_size_bytes`/`remove_cached_model`; **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=…)`); **hosted backend** (no extra) — `OpenAICompatGenerator` for any OpenAI-compatible `/chat/completions` (DeepSeek, Groq, OpenRouter, vLLM, TGI, Azure) behind the same `TextBackend`, `generate_with_usage` → `TokenUsage` (incl. `cache_hit_tokens`, read in both the DeepSeek and OpenAI spellings), `extra_body` for provider extensions; **JSON payloads** — `extract_json_list`/`extract_json_object`/`parse_structured_list` (balanced-span extraction, `None` instead of raising so a caller can retry) + `generate_structured_list` (retries at a rising temperature, `StructuredFormatError`); **usage accounting** — `BaseAIUsageModel` + `AIUsageStore` (one row per paid call: `record`/`record_duration`, `totals`/`by_service`/`per_day`/`top_subjects`, cost priced at read time, cached prefixes billed at `price_cache_hit_per_1k`); **`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.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`, plus `batch_size` for batched decoding, `cpu_threads`/`num_workers`, `condition_on_previous_text` and `transcribe(on_progress=)`) + `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.hostbridge` *(no extra; `[pdf-read]` / `[pdf-layout]` for PDFs)* | Control the machine the service runs on, from WSL or Windows itself — `HostBridge` (power actions, host info, text read/write/list/delete, PDF pages, arbitrary PowerShell/`cmd`, the native file picker), `HostBridgeConfig` / `HostBridgeSettings`, `make_hostbridge_router` (auth required by signature, write side behind `destructive=True`), WSL ↔ Windows path translation resolved before it is checked against `allowed_base_paths`, and `HOST_UNAVAILABLE` (503) where there is no host to reach |
 | `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.asyncapi` | `generate_stream`, `load_asyncapi_spec`, `parse_asyncapi`, `emit_stream`, `StreamGenerationResult`, `AsyncApiIR` / `StreamIR` / `ChannelIR` / `MessageIR` / `OperationIR` — backs `tempest asyncapi-client`, which generates a typed WebSocket client from an AsyncAPI 3 document: payload models plus two tagged unions, one for the frames you send and one for those you receive. OpenAPI cannot describe a socket, so this is a second document, not a second reader of the first. The document must declare `x-tempest-perspective` — `action` is relative to whoever published it, a client inverts every one, and a wrong inversion still compiles *(needs the `[websocket]` extra)* |
 | `tempest_fastapi_sdk.integrations.messaging.zap` | `ZapClient` + the in-house WhatsApp gateway's 28 schemas and 27 operations (generated from the vendored spec, checked in, loaded lazily). A send answers `202` with the enqueued row, not a delivery — pass one `idempotency_key` per message so a retry answers `deduped: true` instead of sending twice. The status webhook has no schema in the specification yet, so it is not modelled |

{tempest_fastapi_sdk-0.293.0 → tempest_fastapi_sdk-0.294.0}/SHIPPED.md

@@ -2134,3 +2134,31 @@ escrito à mão (`len(password) < 8`): senha acima de 72 bytes saía como
 senha que o `signup` recusava — conta semeada cujo dono não conseguia
 trocar a senha depois. Os dois somem ao trocar o `if` por
 `check_password_policy`, que é a régua que o resto do SDK já usava.
+
+
+## O host vira superfície do SDK, v0.294.0 (2026-09-19)
+
+O assistente local já sabia controlar a máquina — só que por fora, como um
+serviço FastAPI separado que cada projeto reescrevia: sandbox de caminho,
+auth por `X-Token`, tradução WSL ↔ Windows, leitura de PDF. Isso agora é
+`tempest_fastapi_sdk.hostbridge`, sem extra nenhum para sistema, arquivos e
+comandos.
+
+O que a migração ensinou vale mais que o módulo: **as duas regras de
+segurança que a doc do serviço pedia ao leitor viraram assinatura**. O
+`allowed_base_paths` começa vazio (vazio nega tudo, em vez de um default
+permissivo que ninguém revisita) e `make_hostbridge_router` recebe as
+dependências de auth como argumento obrigatório, recusando lista vazia — um
+router que lê o disco e roda PowerShell não pode depender de o consumidor ter
+lido o `!!! danger`. O lado destrutivo é opt-in por `destructive=True`.
+
+A terceira lição é sobre falhar com precisão: num host sem `powershell.exe`
+nem `wslpath`, a resposta é `HOST_UNAVAILABLE` (503) e não um erro genérico,
+porque "esta máquina não tem host para controlar" e "a ação falhou" levam o
+chamador a caminhos diferentes.
+
+Junto veio `read_pdf_pages` e o extra `[pdf-layout]`: `pdfplumber` recupera
+coluna e tabela que o `[pdf-read]` entrega intercaladas, e o caminho com
+senha distingue documento cifrado de arquivo corrompido — o que só ficou
+verdade depois de descobrir que o `pdfplumber` embrulha `PDFPasswordIncorrect`
+num `PdfminerException`, fazendo o `except` específico nunca disparar.

{tempest_fastapi_sdk-0.293.0 → tempest_fastapi_sdk-0.294.0}/docs/installation.en.md

@@ -29,6 +29,7 @@ Feature-rich helpers pull in third-party dependencies that you only need when yo
 | `[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) |

{tempest_fastapi_sdk-0.293.0 → tempest_fastapi_sdk-0.294.0}/docs/installation.md

@@ -29,6 +29,7 @@ Os helpers mais ricos puxam dependências de terceiros que só são necessárias
 | `[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) |

{tempest_fastapi_sdk-0.293.0 → tempest_fastapi_sdk-0.294.0}/docs/recipes/auth-flow.en.md

@@ -48,24 +48,18 @@ Requires:
 uv add "tempest-fastapi-sdk[auth,email]>=0.151.1"
 ```
 
-```python
-# src/api/app.py
+Two files, and the direction between them matters. The shared objects —
+connection, email, service — live under `src/api/dependencies/`; the
+`src/api/app.py` **imports** from there and only assembles the application:
 
-from fastapi import FastAPI
+```python
+# src/api/dependencies/resources.py
 
-from tempest_fastapi_sdk import (
-    AsyncDatabaseManager,
-    EmailUtils,
-    UserAuthService,
-    make_auth_router,
-)
+from tempest_fastapi_sdk import AsyncDatabaseManager, EmailUtils, UserAuthService
 
 from src.core.settings import settings
 from src.db.models import UserModel, UserTokenModel
 
-app = FastAPI()
-
-
 db = AsyncDatabaseManager(settings.DATABASE_URL)
 
 # EmailUtils — only instantiate when [email] is installed AND you want real
@@ -87,6 +81,18 @@ auth_service = UserAuthService(
     jwt_settings=settings,    # mixes JWTSettings
     email=emails,             # or None — controls real send vs link in body
 )
+```
+
+```python
+# src/api/app.py
+
+from fastapi import FastAPI
+
+from tempest_fastapi_sdk import make_auth_router
+
+from src.api.dependencies.resources import auth_service, db
+
+app = FastAPI()
 
 app.include_router(
     make_auth_router(
@@ -96,6 +102,16 @@ app.include_router(
 )
 ```
 
+!!! warning "The service cannot live in `app.py`"
+    It is tempting to build the `UserAuthService` next to the `app` and
+    import it back from the dependencies — and that is an import cycle:
+    `app.py` imports the routers, the routers import `dependencies/`, and
+    that would import `app.py` again. The error lands far from its cause
+    (`ImportError: cannot import name 'auth_service' from partially
+    initialized module`), so the direction is fixed from the start:
+    **dependencies never import `app`**. It is also what keeps the service
+    testable without starting the application.
+
 !!! tip "Four-object TL;DR"
     `AsyncDatabaseManager` → connection. `EmailUtils` → SMTP + Jinja2. `UserAuthService` → business rules (5 methods). `make_auth_router` → glues it all into 5 HTTP endpoints.
 
@@ -1469,7 +1485,7 @@ The service already has `user_model`, `JWTUtils` and the session — so you don'
 
 ```python
 # src/api/dependencies/auth.py
-from src.api.app import auth_service
+from src.api.dependencies.resources import auth_service
 
 get_current_user = auth_service.current_user_dependency()
 get_current_user_or_none = auth_service.current_user_dependency(soft=True)
@@ -1490,7 +1506,7 @@ get_current_user_or_none = auth_service.current_user_dependency(soft=True)
 
     ```python
     # src/api/dependencies/auth.py
-    from src.api.app import auth_service
+    from src.api.dependencies.resources import auth_service
 
     get_current_user = auth_service.current_user_dependency(
         cookie_name="access_token",
@@ -1511,7 +1527,7 @@ get_current_user_or_none = auth_service.current_user_dependency(soft=True)
 
     from tempest_fastapi_sdk import JWTUtils, make_jwt_user_dependency
 
-    from src.api.app import db
+    from src.api.dependencies.resources import db
     from src.core.settings import settings
     from src.db.models import UserModel
     from src.db.repositories import UserRepository

{tempest_fastapi_sdk-0.293.0 → tempest_fastapi_sdk-0.294.0}/docs/recipes/auth-flow.md

@@ -48,24 +48,18 @@ Requer:
 uv add "tempest-fastapi-sdk[auth,email]>=0.151.1"
 ```
 
-```python
-# src/api/app.py
+São dois arquivos, e a ordem entre eles importa. Os objetos compartilhados
+— conexão, e-mail, service — moram em `src/api/dependencies/`; o
+`src/api/app.py` **importa** de lá e só monta a aplicação:
 
-from fastapi import FastAPI
+```python
+# src/api/dependencies/resources.py
 
-from tempest_fastapi_sdk import (
-    AsyncDatabaseManager,
-    EmailUtils,
-    UserAuthService,
-    make_auth_router,
-)
+from tempest_fastapi_sdk import AsyncDatabaseManager, EmailUtils, UserAuthService
 
 from src.core.settings import settings
 from src.db.models import UserModel, UserTokenModel
 
-app = FastAPI()
-
-
 db = AsyncDatabaseManager(settings.DATABASE_URL)
 
 # EmailUtils — só instancie se [email] estiver instalado E você quiser e-mail
@@ -87,6 +81,18 @@ auth_service = UserAuthService(
     jwt_settings=settings,    # mistura JWTSettings
     email=emails,             # ou None — controla envio real vs link no body
 )
+```
+
+```python
+# src/api/app.py
+
+from fastapi import FastAPI
+
+from tempest_fastapi_sdk import make_auth_router
+
+from src.api.dependencies.resources import auth_service, db
+
+app = FastAPI()
 
 app.include_router(
     make_auth_router(
@@ -96,6 +102,15 @@ app.include_router(
 )
 ```
 
+!!! warning "O service não pode morar no `app.py`"
+    É tentador criar o `UserAuthService` ao lado do `app` e importá-lo de
+    volta nas dependencies — e é um ciclo de import: `app.py` importa os
+    routers, os routers importam `dependencies/`, e esse importaria `app.py`
+    de novo. O erro sai longe da causa (`ImportError: cannot import name
+    'auth_service' from partially initialized module`), então a direção fica
+    fixa desde o começo: **dependencies não importa `app`**. É também o que
+    deixa o service testável sem subir a aplicação.
+
 !!! tip "TL;DR de quatro objetos"
     `AsyncDatabaseManager` → conexão. `EmailUtils` → SMTP + Jinja2. `UserAuthService` → regras de negócio (5 métodos). `make_auth_router` → cola tudo em 5 endpoints HTTP.
 
@@ -1461,7 +1476,7 @@ O service já tem `user_model`, `JWTUtils` e a sessão — então não precisa e
 
 ```python
 # src/api/dependencies/auth.py
-from src.api.app import auth_service
+from src.api.dependencies.resources import auth_service
 
 get_current_user = auth_service.current_user_dependency()
 get_current_user_or_none = auth_service.current_user_dependency(soft=True)
@@ -1482,7 +1497,7 @@ get_current_user_or_none = auth_service.current_user_dependency(soft=True)
 
     ```python
     # src/api/dependencies/auth.py
-    from src.api.app import auth_service
+    from src.api.dependencies.resources import auth_service
 
     get_current_user = auth_service.current_user_dependency(
         cookie_name="access_token",
@@ -1503,7 +1518,7 @@ get_current_user_or_none = auth_service.current_user_dependency(soft=True)
 
     from tempest_fastapi_sdk import JWTUtils, make_jwt_user_dependency
 
-    from src.api.app import db
+    from src.api.dependencies.resources import db
     from src.core.settings import settings
     from src.db.models import UserModel
     from src.db.repositories import UserRepository

tempest_fastapi_sdk-0.294.0/docs/recipes/hostbridge.en.md

@@ -0,0 +1,255 @@
+# Host control (files, commands, power)
+
+Your service runs inside WSL and needs to act on the **machine** hosting it:
+read a file under `C:\Users\...`, run a PowerShell command, open the native
+file picker, power the computer down at the end of the day.
+`tempest_fastapi_sdk.hostbridge` is that layer — the one that used to live
+as a separate service in every project that needed it.
+
+Nothing here mounts itself: `create_app` does not know this module, and the
+router exists because a service asked for it.
+
+```bash
+uv add "tempest-fastapi-sdk"
+```
+
+The system, file and command surface needs no extra at all — it is the
+standard library and FastAPI. Reading PDFs needs `[pdf-read]`, and reading
+them **with layout and tables** needs `[pdf-layout]`.
+
+!!! danger "This is a shell on that machine"
+    Whoever reaches these methods runs commands as the host user and powers
+    the machine off. Two things follow, and neither is optional:
+    `allowed_base_paths` starts **empty** — denying every path until someone
+    configures it — and `make_hostbridge_router` **requires** auth
+    dependencies, refusing an empty list. The write side (commands, writes,
+    deletes, power) is behind `destructive=True` and off by default.
+
+## The first read
+
+`HostBridge` takes a `HostBridgeConfig` and nothing else. Everything is
+`async`, and whatever touches the disk or a process runs off the event loop:
+
+```python
+import asyncio
+
+from tempest_fastapi_sdk.hostbridge import HostBridge, HostBridgeConfig
+
+
+async def main() -> None:
+    bridge = HostBridge(
+        HostBridgeConfig(allowed_base_paths=("/mnt/c/Users/me/Documents",)),
+    )
+
+    info = await bridge.host_info()
+    print(info.computer_name, info.os_version)
+
+    file = await bridge.read_text("C:\\Users\\me\\Documents\\notes.txt")
+    print(file.size_bytes, file.content[:80])
+
+
+asyncio.run(main())
+```
+
+Look at that path: it was written in **Windows** form and it worked. The
+bridge takes both — `C:\Users\me` and `/mnt/c/Users/me` — and normalizes
+before checking, through `wslpath` where it exists.
+
+!!! warning "Order matters: resolve first, check second"
+    The path is resolved (`..` collapsed, symlinks followed) **before** it is
+    compared against `allowed_base_paths`. Checking before resolving is the
+    classic bug: `/mnt/c/Users/me/../../../etc/passwd` starts inside an
+    allowed base and ends outside it.
+
+## Configuration from the environment
+
+In a service, these options belong on `Settings`. Compose the mixin and
+splat the mapper — the field → argument translation lives in one place:
+
+```python
+from tempest_fastapi_sdk.settings import HostBridgeSettings, ServerSettings
+from tempest_fastapi_sdk.hostbridge import HostBridge, HostBridgeConfig
+
+
+class Settings(HostBridgeSettings, ServerSettings):
+    """Only what is specific to this service is declared here."""
+
+
+settings = Settings()
+bridge = HostBridge(HostBridgeConfig(**settings.hostbridge_kwargs()))
+```
+
+The environment variables are the field names themselves:
+`HOST_ALLOWED_BASE_PATHS`, `HOST_POWERSHELL_BINARY`, `HOST_CMD_BINARY`,
+`HOST_COMMAND_TIMEOUT` and `HOST_MAX_FILE_READ_BYTES`.
+
+!!! info "`HOST_ALLOWED_BASE_PATHS` has no permissive default"
+    Empty denies everything. That is the safe direction to fail: a bridge
+    that can run PowerShell should not also be able to read the whole disk
+    because nobody remembered to configure it.
+
+## Exposing it over HTTP
+
+`make_hostbridge_router` returns an `APIRouter` ready for `include_router`.
+It **requires** the dependency list — the signature is what forces the auth
+decision, instead of a warning in the docs:
+
+```python
+from fastapi import Depends, FastAPI
+
+from tempest_fastapi_sdk import make_token_dependency, register_exception_handlers
+from tempest_fastapi_sdk.hostbridge import (
+    HostBridge,
+    HostBridgeConfig,
+    make_hostbridge_router,
+)
+
+app = FastAPI()
+register_exception_handlers(app)
+
+bridge = HostBridge(
+    HostBridgeConfig(allowed_base_paths=("/mnt/c/Users/me/Documents",)),
+)
+
+app.include_router(
+    make_hostbridge_router(
+        bridge,
+        dependencies=[Depends(make_token_dependency("a-long-secret"))],
+    )
+)
+```
+
+That mounts the side that **reads**:
+
+| Method | Route | What it does |
+| --- | --- | --- |
+| `GET` | `/system/info` | Machine name, user, OS, uptime |
+| `GET` | `/system/files` | Read a text file |
+| `GET` | `/system/files/list` | List a directory |
+| `GET` | `/system/files/pdf` | Extract a PDF, page by page |
+| `POST` | `/system/files/pick` | Open the native file picker |
+
+The side that **writes** — `POST /system/exec`, `POST`/`DELETE
+/system/files`, `POST /system/{shutdown,restart,abort,lock,logoff}` — only
+appears with `destructive=True`:
+
+```python
+from fastapi import Depends
+
+from tempest_fastapi_sdk import make_token_dependency
+from tempest_fastapi_sdk.hostbridge import (
+    HostBridge,
+    HostBridgeConfig,
+    make_hostbridge_router,
+)
+
+bridge = HostBridge(
+    HostBridgeConfig(allowed_base_paths=("/mnt/c/Users/me/Documents",)),
+)
+
+router = make_hostbridge_router(
+    bridge,
+    dependencies=[Depends(make_token_dependency("a-long-secret"))],
+    destructive=True,
+)
+```
+
+!!! tip "Turn the destructive side on only with someone there to confirm"
+    An assistant that runs commands without human confirmation is one that
+    deletes the wrong folder exactly once. The pattern that works is holding
+    the call until the user approves it, showing the exact arguments.
+
+## Errors, with a code
+
+Every failure raises one of the SDK's envelope exceptions, so a service that
+already calls `register_exception_handlers` answers `{detail, code, details}`
+with no extra wiring — in PT-BR or en-US, per `Accept-Language`:
+
+| Code | Status | When |
+| --- | --- | --- |
+| `HOST_INVALID_PATH` | 400 | Path outside the bases, or untranslatable |
+| `HOST_FILE_NOT_FOUND` | 404 | No file there |
+| `HOST_FILE_TOO_LARGE` | 413 | Over `max_file_read_bytes` |
+| `HOST_FILE_DECODE_FAILED` | 400 | Bytes do not decode — a PDF or an image |
+| `HOST_COMMAND_FAILED` | 500 | The command exited non-zero |
+| `HOST_COMMAND_TIMEOUT` | 504 | The command ran past its timeout and was killed |
+| `HOST_UNAVAILABLE` | 503 | Neither PowerShell nor `wslpath` exists here |
+
+`HOST_UNAVAILABLE` is what tells "this machine has no Windows host" apart
+from "the action failed": on a plain Linux container the caller degrades
+instead of reporting an error.
+
+## Reading a PDF from the host
+
+```python
+import asyncio
+
+from tempest_fastapi_sdk.hostbridge import HostBridge, HostBridgeConfig
+from tempest_fastapi_sdk.pdf import PdfExtractor
+
+
+async def main() -> None:
+    bridge = HostBridge(
+        HostBridgeConfig(allowed_base_paths=("/mnt/c/Users/me/Documents",)),
+    )
+    document = await bridge.read_pdf(
+        "C:\\Users\\me\\Documents\\contract.pdf",
+        extractor=PdfExtractor.LAYOUT,
+    )
+    for page in document.pages:
+        print(page.page_number, len(page.tables), page.text[:60])
+
+
+asyncio.run(main())
+```
+
+`PdfExtractor.TEXT` is `pypdf` — fast, plain prose, `[pdf-read]`.
+`PdfExtractor.LAYOUT` is `pdfplumber`, `[pdf-layout]`: slower, but it
+recovers columns and fills `page.tables`.
+
+!!! warning "There is no OCR here"
+    A scanned page is an image with no text layer: it comes back with
+    `text=""` rather than being dropped — entry `n` is always page `n`.
+    Check for it and route those files elsewhere; handing a model an empty
+    page is how a confident answer gets invented about something nobody read.
+
+## Running commands
+
+```python
+import asyncio
+
+from tempest_fastapi_sdk.hostbridge import (
+    CommandSchema,
+    HostBridge,
+    HostBridgeConfig,
+)
+
+
+async def main() -> None:
+    bridge = HostBridge(HostBridgeConfig())
+    result = await bridge.run_command(
+        CommandSchema(command="Get-Date -Format o", shell="powershell", timeout=10),
+    )
+    print(result.return_code, result.stdout.strip(), result.duration_seconds)
+
+
+asyncio.run(main())
+```
+
+!!! note "Elevation (UAC) does not happen from here"
+    A command that needs administrator rights fails. Wrap it through `gsudo`
+    or a pre-created Task Scheduler entry on the Windows side.
+
+## Recap
+
+- `HostBridge` + `HostBridgeConfig` give you the whole surface;
+  `HostBridgeSettings` is the same thing from the environment, via
+  `hostbridge_kwargs()`.
+- An empty `allowed_base_paths` denies everything, and a path is resolved
+  before it is checked.
+- `make_hostbridge_router` requires auth by signature, and only mounts the
+  write side with `destructive=True`.
+- Every failure carries a `code` — `HOST_UNAVAILABLE` says this machine has
+  no host to control.
+- PDFs: `[pdf-read]` for text, `[pdf-layout]` for columns and tables, no OCR
+  in either.