polza-extras 0.2.0__tar.gz

polza_extras-0.2.0/.gitignore

@@ -0,0 +1,9 @@
+.venv/
+__pycache__/
+*.pyc
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+dist/
+.env
+.coverage

polza_extras-0.2.0/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+## 0.2.0 — 2026-10-24
+
+First release on PyPI: `uv add polza-extras`.
+
+- Tool calls: `ChatResult.tool_calls` (`ToolCall` with `id`, `name`, `arguments` and `parsed_arguments()`). A reply with tool calls and no text no longer raises `EmptyResponseError`.
+- Streaming tool calls: `StreamEvent.tool_calls` passes `ToolCallDelta` pieces (`index`, `id`, `name`, `arguments` fragment) through as they arrive.
+- Usage details: `Usage.cached_tokens`, `Usage.cache_write_tokens`, `Usage.reasoning_tokens` (0 when Polza does not send them), in `chat()` and in the last stream event.
+- Structured output: `chat(..., json_schema=..., schema_name="response")` and the same in `chat_stream()`; takes a JSON Schema dict or a pydantic model class and sends a strict `json_schema` response format. Combining it with `json=True` or `response_format` raises `ValueError`.
+- CI runs on Python 3.11–3.14, plus 3.15 pre-releases as experimental.
+- Release workflow: tags `v*` are built with `uv build` and published to PyPI with Trusted Publishing.
+
+## 0.1.0 — 2026-10-24
+
+First release. Not on PyPI yet; install from GitHub.
+
+- `Polza` / `AsyncPolza` on top of the `openai` SDK, with `close()` and context managers.
+- `chat()`: ruble cost (`cost_rub` as `Decimal`), reasoning text, JSON mode, Polza retry rules.
+- `chat_stream()`: text and reasoning deltas, final usage and cost, `StreamError` for in-stream errors; abandoned streams are closed.
+- Typed errors from Polza's error body (`AuthError`, `InsufficientFundsError`, `RateLimitError`, `NotFoundError`, …) with `trace_id` and the provider's real reason.
+- `EmptyResponseError` when thinking used up `max_tokens`; it keeps usage, the raw response and the billed cost.
+- Catalog: `models()`, `model()`, ruble pricing as `Decimal`, `Pricing.estimate`.
+- Account: `balance()`, `key_info()`.

polza_extras-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 polza-extras contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

polza_extras-0.2.0/PKG-INFO

@@ -0,0 +1,189 @@
+Metadata-Version: 2.5
+Name: polza-extras
+Version: 0.2.0
+Summary: Polza.ai helpers on top of the OpenAI SDK: ruble cost, typed errors, retry rules, model catalog, balance
+Project-URL: Homepage, https://github.com/still-coding/polza-extras
+Project-URL: Issues, https://github.com/still-coding/polza-extras/issues
+Project-URL: Changelog, https://github.com/still-coding/polza-extras/blob/main/CHANGELOG.md
+Author: still-coding
+License-Expression: MIT
+License-File: LICENSE
+Keywords: llm,openai,polza,polza.ai,rubles,russia
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: httpx>=0.27
+Requires-Dist: openai>=1.50
+Requires-Dist: pydantic>=2.7
+Description-Content-Type: text/markdown
+
+# polza-extras
+
+Small helpers for [Polza.ai](https://polza.ai) on top of the official `openai` SDK.
+
+Polza is OpenAI-compatible, so for chat you can use the `openai` SDK directly. This library covers what the SDK doesn't know about:
+
+- **Ruble cost** of each call (`usage.cost_rub`) as `Decimal`.
+- **Typed errors** parsed from Polza's error body, with `trace_id` and the provider's real reason (`metadata.raw`), which is often hidden behind a generic «Некорректный запрос».
+- **Polza's retry rules** (which statuses to retry, `Retry-After`, own vs provider rate limits).
+- **Reasoning models**: a clear `EmptyResponseError` when thinking used up `max_tokens`, instead of an empty string.
+- **Tool calls, usage details, structured output**: parsed `tool_calls`, cached/reasoning token counts, `json_schema=` with a dict or a pydantic model.
+- **Catalog, balance and key info**: `models()`, `model()`, `balance()`, `key_info()`, with ruble prices as `Decimal` and a cost estimate.
+
+## Install
+
+```bash
+uv add polza-extras     # or: pip install polza-extras
+```
+
+Python 3.11+. Dependencies: `openai`, `pydantic`.
+
+## Quickstart
+
+```python
+from polza_extras import Polza
+
+polza = Polza()  # reads POLZA_AI_API_KEY; base URL https://polza.ai/api/v1
+
+result = polza.chat(
+    "anthropic/claude-haiku-5.5",          # always provider/model; a bare name is a 404
+    [{"role": "user", "content": "Привет!"}],
+    max_tokens=200,
+    reasoning={"type": "disabled"},        # any extra Polza field goes into the request body
+)
+print(result.text, result.cost_rub)       # 'Привет! …' Decimal('0.0123')
+
+data = polza.chat(model, messages, json=True)   # response_format={"type": "json_object"}
+
+polza.openai                               # the configured openai.OpenAI client, for anything else
+polza.close()                              # or: with Polza() as polza: ...
+```
+
+### Tool calls
+
+```python
+result = polza.chat(model, messages, tools=[weather_tool])   # tools pass through as is
+for call in result.tool_calls:                # [] for a plain text reply
+    call.id, call.name, call.arguments        # arguments: the JSON string from the model
+    args = call.parsed_arguments()            # dict; ValueError if not a JSON object
+```
+
+A reply with tool calls usually has no text: `result.text == ""` and `finish_reason == "tool_calls"`. `EmptyResponseError` is raised only when there is neither text nor tool calls.
+
+In a stream, `event.tool_calls` holds the raw `ToolCallDelta` pieces: the first piece of a call has `index`, `id` and `name`; join the `arguments` fragments of one `index` to get the full JSON.
+
+### Usage details
+
+```python
+u = result.usage
+u.prompt_tokens, u.completion_tokens, u.total_tokens
+u.cached_tokens        # prompt tokens read from the prompt cache
+u.cache_write_tokens   # prompt tokens written to the prompt cache
+u.reasoning_tokens     # completion tokens spent on thinking
+```
+
+They are 0 when Polza does not report them. The last stream event carries the same `usage`.
+
+### Structured output
+
+```python
+from pydantic import BaseModel
+
+class City(BaseModel):
+    name: str
+    population_millions: float
+
+result = polza.chat(model, messages, json_schema=City, schema_name="city")
+city = City.model_validate_json(result.text)
+```
+
+`json_schema` takes a pydantic model class or a JSON Schema dict and sends `response_format={"type": "json_schema", "json_schema": {"name": schema_name, "schema": ..., "strict": True}}`. Not every provider supports it: check `json_schema_strict` in the model's provider capabilities. Strict mode on some providers also wants `"additionalProperties": false` and every property in `required`; pass a dict when you need full control. Use either `json=True` (any JSON object) or `json_schema`, not both.
+
+### Streaming
+
+```python
+for event in polza.chat_stream("anthropic/claude-haiku-5.5", messages, max_tokens=200):
+    print(event.delta, end="", flush=True)   # event.reasoning holds thinking deltas, if any
+print(event.cost_rub)                        # the last event carries usage and cost
+```
+
+Errors before the first chunk are retried like `chat()`. An error event inside the stream raises `StreamError`; text already yielded stays yielded, and the request is not retried. Stopping early (`break`) closes the connection.
+
+### Async
+
+`AsyncPolza` has the same methods, awaited (`async for` for `chat_stream`):
+
+```python
+from polza_extras import AsyncPolza
+
+polza = AsyncPolza()
+result = await polza.chat("anthropic/claude-haiku-5.5", messages)
+async for event in polza.chat_stream("anthropic/claude-haiku-5.5", messages):
+    ...
+```
+
+### Catalog, balance, key
+
+```python
+page = polza.models(search="claude", type="chat", limit=10)   # one catalog page
+for m in page.items:
+    print(m.id, m.pricing.prompt_per_million, m.reasoning.mandatory)
+
+sonnet = polza.model("anthropic/claude-sonnet-5.5")            # NotFoundError for unknown ids
+sonnet.pricing.estimate(prompt_tokens=1500, completion_tokens=80)  # Decimal rubles
+
+polza.balance()    # Balance(amount, available, reserved, spent, updated_at)
+polza.key_info()   # KeyInfo(label, limit, limit_remaining, limit_reset, usage, usage_daily, ...)
+```
+
+## Errors
+
+All errors subclass `PolzaError` (`status`, `code`, `message`, `trace_id`, `metadata`, `details`, `retry_after`).
+
+| Status | Class | Retried by default |
+|---|---|---|
+| 401 | `AuthError` | no |
+| 402 | `InsufficientFundsError` | no (opt-in `retry_402` for parallel-load reserve conflicts) |
+| 403 | `ForbiddenError` | no |
+| 404 | `NotFoundError` | no |
+| 400, 413, other 4xx | `RequestError` | no |
+| 429 with `Retry-After` | `RateLimitError(scope="own")` | yes, waits `Retry-After` (fails fast if above `max_wait`) |
+| 429 without `Retry-After` | `RateLimitError(scope="provider")` | yes, backoff 1, 2, 4, 8 s |
+| 408, 502 | `ServerError` | yes, backoff |
+| 503 | `ServerError` | yes, honors `Retry-After` |
+| connection failure | `PolzaConnectionError` | yes, backoff |
+| 200 with no text and no tool calls | `EmptyResponseError` | no; carries `finish_reason`, `reasoning`, `usage`, `cost_rub` (still billed), `raw` |
+| error event inside a stream | `StreamError` | no |
+
+Polza doesn't charge for failed requests, so retrying is safe. Tune with `Polza(retry=RetryPolicy(max_retries=..., base_delay=..., max_wait=...))`.
+
+### Reasoning models
+
+Thinking tokens count against `max_tokens`. If the model spends them all on thinking, `content` comes back empty and `chat()` raises `EmptyResponseError` with `finish_reason="length"`. Fixes:
+
+- turn thinking off: `reasoning={"type": "disabled"}` (where allowed),
+- lower it: `reasoning={"effort": "low"}`,
+- raise `max_tokens`.
+
+Some models (e.g. `anthropic/claude-sonnet-5.5`) make thinking mandatory; `model(id).reasoning.mandatory` tells you.
+
+## Development
+
+```bash
+uv sync
+uv run pytest                 # offline, against an in-process fake server; fails below 95% coverage
+POLZA_AI_API_KEY=... uv run pytest -m live --no-cov   # real API smoke tests, costs ~0.1 ₽
+uv run ruff check src tests && uv run ruff format --check src tests && uv run pyright
+ln -sf ../../scripts/pre-commit .git/hooks/pre-commit   # all of the above before each commit
+```
+
+## License
+
+MIT

polza_extras-0.2.0/README.md

@@ -0,0 +1,163 @@
+# polza-extras
+
+Small helpers for [Polza.ai](https://polza.ai) on top of the official `openai` SDK.
+
+Polza is OpenAI-compatible, so for chat you can use the `openai` SDK directly. This library covers what the SDK doesn't know about:
+
+- **Ruble cost** of each call (`usage.cost_rub`) as `Decimal`.
+- **Typed errors** parsed from Polza's error body, with `trace_id` and the provider's real reason (`metadata.raw`), which is often hidden behind a generic «Некорректный запрос».
+- **Polza's retry rules** (which statuses to retry, `Retry-After`, own vs provider rate limits).
+- **Reasoning models**: a clear `EmptyResponseError` when thinking used up `max_tokens`, instead of an empty string.
+- **Tool calls, usage details, structured output**: parsed `tool_calls`, cached/reasoning token counts, `json_schema=` with a dict or a pydantic model.
+- **Catalog, balance and key info**: `models()`, `model()`, `balance()`, `key_info()`, with ruble prices as `Decimal` and a cost estimate.
+
+## Install
+
+```bash
+uv add polza-extras     # or: pip install polza-extras
+```
+
+Python 3.11+. Dependencies: `openai`, `pydantic`.
+
+## Quickstart
+
+```python
+from polza_extras import Polza
+
+polza = Polza()  # reads POLZA_AI_API_KEY; base URL https://polza.ai/api/v1
+
+result = polza.chat(
+    "anthropic/claude-haiku-5.5",          # always provider/model; a bare name is a 404
+    [{"role": "user", "content": "Привет!"}],
+    max_tokens=200,
+    reasoning={"type": "disabled"},        # any extra Polza field goes into the request body
+)
+print(result.text, result.cost_rub)       # 'Привет! …' Decimal('0.0123')
+
+data = polza.chat(model, messages, json=True)   # response_format={"type": "json_object"}
+
+polza.openai                               # the configured openai.OpenAI client, for anything else
+polza.close()                              # or: with Polza() as polza: ...
+```
+
+### Tool calls
+
+```python
+result = polza.chat(model, messages, tools=[weather_tool])   # tools pass through as is
+for call in result.tool_calls:                # [] for a plain text reply
+    call.id, call.name, call.arguments        # arguments: the JSON string from the model
+    args = call.parsed_arguments()            # dict; ValueError if not a JSON object
+```
+
+A reply with tool calls usually has no text: `result.text == ""` and `finish_reason == "tool_calls"`. `EmptyResponseError` is raised only when there is neither text nor tool calls.
+
+In a stream, `event.tool_calls` holds the raw `ToolCallDelta` pieces: the first piece of a call has `index`, `id` and `name`; join the `arguments` fragments of one `index` to get the full JSON.
+
+### Usage details
+
+```python
+u = result.usage
+u.prompt_tokens, u.completion_tokens, u.total_tokens
+u.cached_tokens        # prompt tokens read from the prompt cache
+u.cache_write_tokens   # prompt tokens written to the prompt cache
+u.reasoning_tokens     # completion tokens spent on thinking
+```
+
+They are 0 when Polza does not report them. The last stream event carries the same `usage`.
+
+### Structured output
+
+```python
+from pydantic import BaseModel
+
+class City(BaseModel):
+    name: str
+    population_millions: float
+
+result = polza.chat(model, messages, json_schema=City, schema_name="city")
+city = City.model_validate_json(result.text)
+```
+
+`json_schema` takes a pydantic model class or a JSON Schema dict and sends `response_format={"type": "json_schema", "json_schema": {"name": schema_name, "schema": ..., "strict": True}}`. Not every provider supports it: check `json_schema_strict` in the model's provider capabilities. Strict mode on some providers also wants `"additionalProperties": false` and every property in `required`; pass a dict when you need full control. Use either `json=True` (any JSON object) or `json_schema`, not both.
+
+### Streaming
+
+```python
+for event in polza.chat_stream("anthropic/claude-haiku-5.5", messages, max_tokens=200):
+    print(event.delta, end="", flush=True)   # event.reasoning holds thinking deltas, if any
+print(event.cost_rub)                        # the last event carries usage and cost
+```
+
+Errors before the first chunk are retried like `chat()`. An error event inside the stream raises `StreamError`; text already yielded stays yielded, and the request is not retried. Stopping early (`break`) closes the connection.
+
+### Async
+
+`AsyncPolza` has the same methods, awaited (`async for` for `chat_stream`):
+
+```python
+from polza_extras import AsyncPolza
+
+polza = AsyncPolza()
+result = await polza.chat("anthropic/claude-haiku-5.5", messages)
+async for event in polza.chat_stream("anthropic/claude-haiku-5.5", messages):
+    ...
+```
+
+### Catalog, balance, key
+
+```python
+page = polza.models(search="claude", type="chat", limit=10)   # one catalog page
+for m in page.items:
+    print(m.id, m.pricing.prompt_per_million, m.reasoning.mandatory)
+
+sonnet = polza.model("anthropic/claude-sonnet-5.5")            # NotFoundError for unknown ids
+sonnet.pricing.estimate(prompt_tokens=1500, completion_tokens=80)  # Decimal rubles
+
+polza.balance()    # Balance(amount, available, reserved, spent, updated_at)
+polza.key_info()   # KeyInfo(label, limit, limit_remaining, limit_reset, usage, usage_daily, ...)
+```
+
+## Errors
+
+All errors subclass `PolzaError` (`status`, `code`, `message`, `trace_id`, `metadata`, `details`, `retry_after`).
+
+| Status | Class | Retried by default |
+|---|---|---|
+| 401 | `AuthError` | no |
+| 402 | `InsufficientFundsError` | no (opt-in `retry_402` for parallel-load reserve conflicts) |
+| 403 | `ForbiddenError` | no |
+| 404 | `NotFoundError` | no |
+| 400, 413, other 4xx | `RequestError` | no |
+| 429 with `Retry-After` | `RateLimitError(scope="own")` | yes, waits `Retry-After` (fails fast if above `max_wait`) |
+| 429 without `Retry-After` | `RateLimitError(scope="provider")` | yes, backoff 1, 2, 4, 8 s |
+| 408, 502 | `ServerError` | yes, backoff |
+| 503 | `ServerError` | yes, honors `Retry-After` |
+| connection failure | `PolzaConnectionError` | yes, backoff |
+| 200 with no text and no tool calls | `EmptyResponseError` | no; carries `finish_reason`, `reasoning`, `usage`, `cost_rub` (still billed), `raw` |
+| error event inside a stream | `StreamError` | no |
+
+Polza doesn't charge for failed requests, so retrying is safe. Tune with `Polza(retry=RetryPolicy(max_retries=..., base_delay=..., max_wait=...))`.
+
+### Reasoning models
+
+Thinking tokens count against `max_tokens`. If the model spends them all on thinking, `content` comes back empty and `chat()` raises `EmptyResponseError` with `finish_reason="length"`. Fixes:
+
+- turn thinking off: `reasoning={"type": "disabled"}` (where allowed),
+- lower it: `reasoning={"effort": "low"}`,
+- raise `max_tokens`.
+
+Some models (e.g. `anthropic/claude-sonnet-5.5`) make thinking mandatory; `model(id).reasoning.mandatory` tells you.
+
+## Development
+
+```bash
+uv sync
+uv run pytest                 # offline, against an in-process fake server; fails below 95% coverage
+POLZA_AI_API_KEY=... uv run pytest -m live --no-cov   # real API smoke tests, costs ~0.1 ₽
+uv run ruff check src tests && uv run ruff format --check src tests && uv run pyright
+ln -sf ../../scripts/pre-commit .git/hooks/pre-commit   # all of the above before each commit
+```
+
+## License
+
+MIT

polza_extras-0.2.0/pyproject.toml

@@ -0,0 +1,80 @@
+[project]
+name = "polza-extras"
+version = "0.2.0"
+description = "Polza.ai helpers on top of the OpenAI SDK: ruble cost, typed errors, retry rules, model catalog, balance"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.11"
+authors = [{ name = "still-coding" }]
+keywords = ["polza", "polza.ai", "openai", "llm", "russia", "rubles"]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Typing :: Typed",
+]
+dependencies = [
+    "openai>=1.50",
+    "httpx>=0.27",
+    "pydantic>=2.7",
+]
+
+[dependency-groups]
+dev = [
+    "pytest>=8",
+    "pytest-asyncio>=0.23",
+    "ruff>=0.6",
+    "pytest-cov>=7.1.0",
+    "pyright>=1.1.414",
+]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project.urls]
+Homepage = "https://github.com/still-coding/polza-extras"
+Issues = "https://github.com/still-coding/polza-extras/issues"
+Changelog = "https://github.com/still-coding/polza-extras/blob/main/CHANGELOG.md"
+
+[tool.hatch.build.targets.sdist]
+include = ["src", "tests", "README.md", "LICENSE", "CHANGELOG.md"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/polza_extras"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+asyncio_mode = "auto"
+markers = ["live: hits the real Polza API (needs POLZA_AI_API_KEY)"]
+# Coverage is gated: plain `uv run pytest` (and CI) fails below fail_under.
+# Live smoke tests cover little on purpose; run them with `--no-cov`.
+addopts = "-m 'not live' --cov=polza_extras --cov-branch --cov-report=term-missing:skip-covered"
+
+[tool.coverage.report]
+fail_under = 95
+
+# ruff replaces flake8 (E, W, F + bugbear B), isort (I) and black (`ruff format`).
+[tool.ruff]
+line-length = 100
+target-version = "py311"
+src = ["src", "tests"]
+
+[tool.ruff.format]
+exclude = ["*.md"]  # README examples keep their aligned comments
+
+[tool.ruff.lint]
+select = ["E", "W", "F", "I", "B", "UP", "C4", "SIM"]
+
+[tool.ruff.lint.isort]
+known-first-party = ["polza_extras", "tests"]
+
+[tool.pyright]
+include = ["src"]
+pythonVersion = "3.11"
+typeCheckingMode = "strict"

polza_extras-0.2.0/src/polza_extras/__init__.py

@@ -0,0 +1,57 @@
+from ._models import (
+    Balance,
+    ChatResult,
+    KeyInfo,
+    ModelInfo,
+    ModelPage,
+    Pricing,
+    ReasoningInfo,
+    StreamEvent,
+    ToolCall,
+    ToolCallDelta,
+    Usage,
+)
+from .client import DEFAULT_BASE_URL, AsyncPolza, Polza
+from .errors import (
+    AuthError,
+    EmptyResponseError,
+    ForbiddenError,
+    InsufficientFundsError,
+    NotFoundError,
+    PolzaConnectionError,
+    PolzaError,
+    RateLimitError,
+    RequestError,
+    ServerError,
+    StreamError,
+)
+from .retry import RetryPolicy
+
+__all__ = [
+    "DEFAULT_BASE_URL",
+    "AsyncPolza",
+    "AuthError",
+    "Balance",
+    "ChatResult",
+    "EmptyResponseError",
+    "ForbiddenError",
+    "InsufficientFundsError",
+    "KeyInfo",
+    "ModelInfo",
+    "ModelPage",
+    "NotFoundError",
+    "Polza",
+    "PolzaConnectionError",
+    "PolzaError",
+    "Pricing",
+    "RateLimitError",
+    "ReasoningInfo",
+    "RequestError",
+    "RetryPolicy",
+    "ServerError",
+    "StreamError",
+    "StreamEvent",
+    "ToolCall",
+    "ToolCallDelta",
+    "Usage",
+]

polza_extras-0.2.0/src/polza_extras/_json.py

@@ -0,0 +1,13 @@
+"""Typed access to parsed JSON: containers get a known shape; a missing or wrong one is empty."""
+
+from __future__ import annotations
+
+from typing import Any, cast
+
+
+def obj(value: Any) -> dict[str, Any]:
+    return cast("dict[str, Any]", value) if isinstance(value, dict) else {}
+
+
+def arr(value: Any) -> list[Any]:
+    return cast("list[Any]", value) if isinstance(value, list) else []