Small helpers for 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) asDecimal. - Typed errors parsed from Polza's error body, with
trace_idand 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
EmptyResponseErrorwhen thinking used upmax_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 asDecimaland a cost estimate.
uv add polza-extras # or: pip install polza-extrasPython 3.11+. Dependencies: openai, pydantic.
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: ...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 objectA 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.
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 thinkingThey are 0 when Polza does not report them. The last stream event carries the same usage.
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.
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 costErrors 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.
AsyncPolza has the same methods, awaited (async for for chat_stream):
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):
...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, ...)result = polza.generate_image(
"google/gemini-2.5-flash-image",
"Portrait of a woman, semi-realistic illustration",
aspect_ratio="3:4",
images=[portrait_bytes], # reference images: bytes, a file path or a URL (at most 8)
seed=7, # not every model takes one
)
result.data, result.mime, result.cost_rub, result.url # the file, its type, ₽, Polza's copyThe call starts an async job on /media and polls it every poll_interval seconds (default 4, Polza advises 3-5) until it is done, so no single HTTP request is long. timeout (default 300 s) is the time spent waiting; past it MediaTimeoutError carries the job id and polza.wait_image(id) picks the same job up, so it is never started twice. Starting and polling are retried like chat(). A job that ends failed/cancelled raises MediaFailedError (id, code, provider, retryable); a moderation block (guard_blocked, guard_no_route) raises MediaModeratedError. A failed job is never resent by the library: Polza does not say whether it is billed, so resending is your decision (retryable is True for timeout, bad gateway, unavailable and rate-limit codes). Polza deletes results after 7 days, so the file is downloaded by default (download=False keeps only url). AsyncPolza.generate_image and wait_image are the awaited twins.
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 |
image job failed / cancelled |
MediaFailedError (MediaModeratedError for moderation) |
no, the job is never resent |
| image job still running when the wait ends | MediaTimeoutError (id, status) |
no; resume with wait_image(id) |
Polza doesn't charge for failed requests, so retrying is safe. Tune with Polza(retry=RetryPolicy(max_retries=..., base_delay=..., max_wait=...)).
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.
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 commitMIT