klyuchora 0.2.0__py3-none-any.whl

klyuchora/__init__.py

@@ -0,0 +1,22 @@
+"""Klyuchora SDK: one client for chat, responses, embeddings, images, audio, models, key limits and balance."""
+from ._client import Klyuchora
+from ._errors import (APIError, AuthenticationError, BadRequestError, ConnectionFailed,
+                      InsufficientBalanceError, KlyuchoraError, NotFoundError, PermissionDeniedError,
+                      RateLimitError, RequestTimeout, ServerError)
+from ._obj import Obj
+from ._stream import ChatStream, Stream
+from ._version import __version__
+
+__all__ = [
+    "Klyuchora", "AsyncKlyuchora", "Stream", "ChatStream", "Obj", "__version__",
+    "KlyuchoraError", "APIError", "AuthenticationError", "BadRequestError", "ConnectionFailed",
+    "InsufficientBalanceError", "NotFoundError", "PermissionDeniedError", "RateLimitError",
+    "RequestTimeout", "ServerError",
+]
+
+
+def __getattr__(name):  # lazy: asyncio is only imported when needed
+    if name == "AsyncKlyuchora":
+        from ._async import AsyncKlyuchora
+        return AsyncKlyuchora
+    raise AttributeError(name)

klyuchora/__main__.py

@@ -0,0 +1,3 @@
+import sys
+from .cli import main
+sys.exit(main())

klyuchora/_async.py

@@ -0,0 +1,99 @@
+"""Async interface. Calls run in worker threads, so it works on any asyncio loop with no extra packages."""
+import asyncio
+import functools
+from typing import Any, AsyncIterator, Optional
+
+from ._client import Klyuchora
+from ._stream import ChatStream, Stream
+
+
+async def _run(fn, *args, **kwargs):
+    loop = asyncio.get_running_loop()
+    return await loop.run_in_executor(None, functools.partial(fn, *args, **kwargs))
+
+
+class AsyncStream:
+    """``async for`` over a :class:`Stream`."""
+
+    def __init__(self, stream: Stream):
+        self._stream = stream
+        self.request_id = stream.request_id
+
+    def __aiter__(self) -> "AsyncStream":
+        return self
+
+    async def __anext__(self) -> Any:
+        def step():
+            try:
+                return next(self._stream), False
+            except StopIteration:
+                return None, True
+        item, done = await _run(step)
+        if done:
+            raise StopAsyncIteration
+        return item
+
+    async def text_deltas(self) -> AsyncIterator[str]:
+        async for chunk in self:
+            for choice in chunk.get("choices") or []:
+                piece = (choice.get("delta") or {}).get("content")
+                if piece:
+                    yield piece
+
+    async def collect(self) -> Any:
+        if isinstance(self._stream, ChatStream):
+            return await _run(self._stream.collect)
+        return [event async for event in self]
+
+    async def aclose(self) -> None:
+        await _run(self._stream.close)
+
+    async def __aenter__(self) -> "AsyncStream":
+        return self
+
+    async def __aexit__(self, *exc: Any) -> None:
+        await self.aclose()
+
+
+class _AsyncProxy:
+    def __init__(self, target: Any):
+        self._target = target
+
+    def __getattr__(self, name: str) -> Any:
+        attr = getattr(self._target, name)
+        if callable(attr):
+            @functools.wraps(attr)
+            async def call(*args: Any, **kwargs: Any) -> Any:
+                result = await _run(attr, *args, **kwargs)
+                return AsyncStream(result) if isinstance(result, Stream) else result
+            return call
+        if hasattr(attr, "__dict__") and not isinstance(attr, (str, int, float, bool, list, dict)):
+            return _AsyncProxy(attr)
+        return attr
+
+
+class AsyncKlyuchora:
+    """Same API as :class:`Klyuchora`, every method is awaited:
+
+        client = AsyncKlyuchora()
+        reply = await client.chat.completions.create(model="...", messages=[...])
+        stream = await client.chat.completions.create(model="...", messages=[...], stream=True)
+        async for text in stream.text_deltas(): ...
+    """
+
+    def __init__(self, *args: Any, **kwargs: Any):
+        self._sync = Klyuchora(*args, **kwargs)
+        for name in ("chat", "completions", "responses", "messages", "embeddings", "images", "audio",
+                     "rerank", "moderations", "models", "key", "account", "rates"):
+            setattr(self, name, _AsyncProxy(getattr(self._sync, name)))
+
+    @property
+    def base_url(self) -> str:
+        return self._sync.base_url
+
+    async def estimate_cost(self, *args: Any, **kwargs: Any) -> Any:
+        return await _run(self._sync.estimate_cost, *args, **kwargs)
+
+    async def request(self, *args: Any, **kwargs: Any) -> Any:
+        result = await _run(self._sync.request, *args, **kwargs)
+        return AsyncStream(result) if isinstance(result, Stream) else result

klyuchora/_client.py

@@ -0,0 +1,471 @@
+"""The Klyuchora client."""
+import json
+import mimetypes
+import os
+from typing import Any, Dict, Iterable, Iterator, List, Optional, Union
+
+from ._errors import (APIError, AuthenticationError, KlyuchoraError)
+from ._http import DEFAULT_BASE_URL, Transport, encode_multipart, env
+from ._obj import Obj, wrap
+from ._pricing import QUOTA_PER_USD, estimate, group_prices, quota_to_usd
+from ._stream import ChatStream, Stream
+from ._version import __version__
+
+FileInput = Union[str, bytes, "os.PathLike[str]", Any]
+
+
+_MAGIC = [
+    (b"RIFF", "wav", 8, b"WAVE"), (b"RIFF", "webp", 8, b"WEBP"), (b"\x89PNG", "png", 0, b""), (b"\xff\xd8\xff", "jpg", 0, b""),
+    (b"fLaC", "flac", 0, b""), (b"OggS", "ogg", 0, b""), (b"ID3", "mp3", 0, b""), (b"\x1a\x45\xdf\xa3", "webm", 0, b""),
+    (b"GIF8", "gif", 0, b""),
+]
+
+
+def _sniff_name(content: bytes, default_name: str) -> str:
+    """Name for bytes without a name: the gateway picks the decoder by the file extension."""
+    for magic, ext, off, extra in _MAGIC:
+        if content.startswith(magic) and (not extra or content[off:off + len(extra)] == extra):
+            return "file." + ext
+    if len(content) > 2 and content[0] == 0xFF and content[1] & 0xE0 == 0xE0:
+        return "file.mp3"
+    if content[4:8] == b"ftyp":
+        return "file.m4a"
+    return default_name
+
+
+def _file_part(value: FileInput, default_name: str = "file") -> tuple:
+    if hasattr(value, "read"):
+        content = value.read()
+        raw_name = getattr(value, "name", None)
+        name = os.path.basename(raw_name) if isinstance(raw_name, str) and raw_name else _sniff_name(content, default_name)
+    elif isinstance(value, (bytes, bytearray)):
+        content = bytes(value)
+        name = _sniff_name(content, default_name)
+    else:
+        with open(value, "rb") as fh:
+            content = fh.read()
+        name = os.path.basename(str(value))
+    ctype = mimetypes.guess_type(name)[0] or "application/octet-stream"
+    return name, content, ctype
+
+
+def _clean_secret(value: Optional[str], name: str) -> Optional[str]:
+    if value is None:
+        return None
+    value = str(value).strip()
+    if any(ch in value for ch in "\r\n\x00") or any(ord(ch) > 126 for ch in value):
+        raise KlyuchoraError("%s contains characters that cannot be sent in a header" % name)
+    return value or None
+
+
+class KeyList(list):
+    """List of keys; ``.total`` is the number of keys in the account (there may be more than one page)."""
+
+    total: int = 0
+
+
+class _Resource:
+    def __init__(self, client: "Klyuchora"):
+        self._c = client
+
+
+class _ChatCompletions(_Resource):
+    def create(self, *, model: str, messages: List[Dict[str, Any]], stream: bool = False,
+               timeout: Optional[float] = None, **params: Any) -> Union[Obj, ChatStream]:
+        """POST /v1/chat/completions. Extra keyword arguments go to the gateway unchanged."""
+        body = dict(params, model=model, messages=messages)
+        if stream:
+            body["stream"] = True
+            opts = dict(body.get("stream_options") or {})
+            opts.setdefault("include_usage", True)
+            body["stream_options"] = opts
+            resp = self._c._relay("POST", "/v1/chat/completions", json_body=body, stream=True, timeout=timeout)
+            return ChatStream(resp)
+        return self._c._relay_json("POST", "/v1/chat/completions", body, timeout=timeout)
+
+
+class _Chat(_Resource):
+    def __init__(self, client: "Klyuchora"):
+        super().__init__(client)
+        self.completions = _ChatCompletions(client)
+
+
+class _Completions(_Resource):
+    def create(self, *, model: str, prompt: Any, timeout: Optional[float] = None, **params: Any) -> Obj:
+        """POST /v1/completions (legacy text completion)."""
+        return self._c._relay_json("POST", "/v1/completions", dict(params, model=model, prompt=prompt), timeout=timeout)
+
+
+class _Responses(_Resource):
+    def create(self, *, model: str, stream: bool = False, timeout: Optional[float] = None, **params: Any) -> Union[Obj, Stream]:
+        """POST /v1/responses. Pass ``input=...``."""
+        body = dict(params, model=model)
+        if stream:
+            body["stream"] = True
+            return Stream(self._c._relay("POST", "/v1/responses", json_body=body, stream=True, timeout=timeout))
+        return self._c._relay_json("POST", "/v1/responses", body, timeout=timeout)
+
+
+class _Messages(_Resource):
+    def create(self, *, model: str, messages: List[Dict[str, Any]], max_tokens: int, stream: bool = False,
+               timeout: Optional[float] = None, api_version: str = "2023-06-01", **params: Any) -> Union[Obj, Stream]:
+        """POST /v1/messages (Claude message format)."""
+        body = dict(params, model=model, messages=messages, max_tokens=max_tokens)
+        headers = {"anthropic-version": api_version}
+        if stream:
+            body["stream"] = True
+            return Stream(self._c._relay("POST", "/v1/messages", json_body=body, stream=True, timeout=timeout, headers=headers))
+        return self._c._relay_json("POST", "/v1/messages", body, timeout=timeout, headers=headers)
+
+
+class _Embeddings(_Resource):
+    def create(self, *, model: str, input: Any, timeout: Optional[float] = None, **params: Any) -> Obj:
+        """POST /v1/embeddings."""
+        return self._c._relay_json("POST", "/v1/embeddings", dict(params, model=model, input=input), timeout=timeout)
+
+
+class _Images(_Resource):
+    def generate(self, *, model: str, prompt: str, timeout: Optional[float] = None, **params: Any) -> Obj:
+        """POST /v1/images/generations."""
+        return self._c._relay_json("POST", "/v1/images/generations", dict(params, model=model, prompt=prompt), timeout=timeout)
+
+    def edit(self, *, model: str, image: FileInput, prompt: str, mask: Optional[FileInput] = None,
+             timeout: Optional[float] = None, **params: Any) -> Obj:
+        """POST /v1/images/edits (multipart upload)."""
+        images = list(image) if isinstance(image, (list, tuple)) else [image]
+        files = [("image[]" if len(images) > 1 else "image", _file_part(img, "image.png")) for img in images]
+        if mask is not None:
+            files.append(("mask", _file_part(mask, "mask.png")))
+        fields = dict(params, model=model, prompt=prompt)
+        data, ctype = encode_multipart(fields, files)
+        resp = self._c._relay("POST", "/v1/images/edits", data=data, headers={"Content-Type": ctype}, timeout=timeout)
+        return wrap(resp.json())
+
+
+class _Speech(_Resource):
+    def create(self, *, model: str, input: str, voice: str, timeout: Optional[float] = None, **params: Any) -> bytes:
+        """POST /v1/audio/speech. Returns the audio bytes."""
+        body = dict(params, model=model, input=input, voice=voice)
+        resp = self._c._relay("POST", "/v1/audio/speech", json_body=body, timeout=timeout, headers={"Accept": "*/*"})
+        return resp.read()
+
+
+class _Transcriptions(_Resource):
+    def create(self, *, model: str, file: FileInput, timeout: Optional[float] = None, **params: Any) -> Obj:
+        """POST /v1/audio/transcriptions (multipart upload)."""
+        data, ctype = encode_multipart(dict(params, model=model), {"file": _file_part(file, "audio.mp3")})
+        resp = self._c._relay("POST", "/v1/audio/transcriptions", data=data, headers={"Content-Type": ctype}, timeout=timeout)
+        return _json_or_text(resp)
+
+
+class _Translations(_Resource):
+    def create(self, *, model: str, file: FileInput, timeout: Optional[float] = None, **params: Any) -> Obj:
+        """POST /v1/audio/translations (multipart upload)."""
+        data, ctype = encode_multipart(dict(params, model=model), {"file": _file_part(file, "audio.mp3")})
+        resp = self._c._relay("POST", "/v1/audio/translations", data=data, headers={"Content-Type": ctype}, timeout=timeout)
+        return _json_or_text(resp)
+
+
+class _Audio(_Resource):
+    def __init__(self, client: "Klyuchora"):
+        super().__init__(client)
+        self.speech = _Speech(client)
+        self.transcriptions = _Transcriptions(client)
+        self.translations = _Translations(client)
+
+
+class _Rerank(_Resource):
+    def create(self, *, model: str, query: str, documents: List[Any], timeout: Optional[float] = None, **params: Any) -> Obj:
+        """POST /v1/rerank."""
+        return self._c._relay_json("POST", "/v1/rerank", dict(params, model=model, query=query, documents=documents), timeout=timeout)
+
+
+class _Moderations(_Resource):
+    def create(self, *, input: Any, model: Optional[str] = None, timeout: Optional[float] = None, **params: Any) -> Obj:
+        """POST /v1/moderations."""
+        body = dict(params, input=input)
+        if model:
+            body["model"] = model
+        return self._c._relay_json("POST", "/v1/moderations", body, timeout=timeout)
+
+
+def _json_or_text(resp: Any) -> Obj:
+    raw = resp.read()
+    try:
+        return wrap(json.loads(raw.decode("utf-8")))
+    except ValueError:
+        return wrap({"text": raw.decode("utf-8", "replace")})
+
+
+class _Models(_Resource):
+    def list(self) -> List[Obj]:
+        """Models this key may call right now (GET /v1/models)."""
+        data = self._c._relay_json("GET", "/v1/models", None)
+        return data.get("data", []) if isinstance(data, dict) else []
+
+    def ids(self) -> List[str]:
+        """Just the model names, sorted."""
+        return sorted(m["id"] for m in self.list() if "id" in m)
+
+    def retrieve(self, model: str) -> Obj:
+        """GET /v1/models/{model}."""
+        from urllib.parse import quote
+        return self._c._relay_json("GET", "/v1/models/" + quote(model, safe="/:"), None)
+
+    def catalog(self, *, search: Optional[str] = None, endpoint: Optional[str] = None,
+                group: Optional[str] = None, refresh: bool = False) -> List[Obj]:
+        """Public price list (GET /api/pricing, no key needed).
+
+        Each item has ``name``, ``endpoint_types``, ``groups`` and ``prices``: one row per
+        group that can serve the model, USD per 1M tokens (``input_per_1m_usd``,
+        ``output_per_1m_usd``, ``cached_input_per_1m_usd``) or ``per_request_usd``.
+        The prices are final: nothing is added on top.
+        """
+        data = self._c._catalog(refresh)
+        gr = data.get("group_ratio") or {}
+        if isinstance(gr, dict):
+            ratios = {k: v for k, v in gr.items()}
+        else:
+            ratios = {r["key"]: r["value"] for r in gr if isinstance(r, dict)}
+        out = []
+        needle = search.lower() if search else None
+        for m in data.get("data", []):
+            name = m.get("model_name")
+            if not name:
+                continue
+            if needle and needle not in name.lower():
+                continue
+            if endpoint and endpoint not in (m.get("supported_endpoint_types") or []):
+                continue
+            if group and group not in (m.get("enable_groups") or []):
+                continue
+            out.append(wrap({
+                "name": name,
+                "endpoint_types": m.get("supported_endpoint_types") or [],
+                "groups": m.get("enable_groups") or [],
+                "billing": "per_request" if m.get("quota_type") == 1 else "per_token",
+                "prices": group_prices(m, ratios),
+            }))
+        out.sort(key=lambda x: x["name"])
+        return out
+
+    def price(self, model: str) -> Obj:
+        """Price rows of one model; raises ``KeyError`` for an unknown name."""
+        for item in self.catalog(search=model):
+            if item["name"] == model:
+                return item
+        raise KeyError("model %r is not in the catalog" % model)
+
+
+class _Key(_Resource):
+    def usage(self) -> Obj:
+        """Limits and spend of the key in use (GET /api/usage/token/).
+
+        Returns ``name``, ``unlimited``, ``granted_usd``, ``used_usd``, ``remaining_usd``,
+        ``model_limits`` (list of allowed models, or empty), ``model_limits_enabled`` and
+        ``expires_at`` (unix seconds, ``0`` means never). When ``unlimited`` is true the
+        key has no own limit and spends from the account balance.
+        """
+        raw = self._c._relay_json("GET", "/api/usage/token/", None)
+        data = raw.get("data", raw) if isinstance(raw, dict) else {}
+        per = self._c._quota_per_unit()
+        limits = data.get("model_limits") or {}
+        if isinstance(limits, dict):
+            limits = sorted(limits.keys())
+        return wrap({
+            "name": data.get("name"),
+            "unlimited": bool(data.get("unlimited_quota")),
+            "granted_usd": quota_to_usd(data.get("total_granted"), per),
+            "used_usd": quota_to_usd(data.get("total_used"), per),
+            "remaining_usd": quota_to_usd(data.get("total_available"), per),
+            "model_limits_enabled": bool(data.get("model_limits_enabled")),
+            "model_limits": limits,
+            "expires_at": data.get("expires_at") or 0,
+            "raw": data,
+        })
+
+
+class _Account(_Resource):
+    def _need_token(self) -> None:
+        if not self._c.access_token:
+            raise KlyuchoraError("this call needs an access token: create one in the cabinet (Profile, Security) "
+                                 "and pass access_token=... or set KLYUCHORA_ACCESS_TOKEN")
+
+    def profile(self) -> Obj:
+        """Account data (GET /api/user/self)."""
+        self._need_token()
+        raw = self._c._manage_json("GET", "/api/user/self")
+        return wrap(raw.get("data", {}))
+
+    def balance(self) -> Obj:
+        """Cabinet balance in USD and, if the rate is available, in rubles."""
+        self._need_token()
+        data = self._c._manage_json("GET", "/api/user/self").get("data", {})
+        per = self._c._quota_per_unit()
+        balance = quota_to_usd(data.get("quota"), per)
+        out = {
+            "balance_usd": balance,
+            "spent_usd": quota_to_usd(data.get("used_quota"), per),
+            "requests": data.get("request_count"),
+            "group": data.get("group"),
+            "username": data.get("username"),
+        }
+        try:
+            rate = self._c.rates.usd_rub()
+            out["rub_per_usd"] = rate["rub_per_usd"]
+            out["rate_date"] = rate["date"]
+            out["balance_rub_approx"] = round(balance * rate["rub_per_usd"], 2) if balance is not None else None
+        except KlyuchoraError:
+            pass
+        return wrap(out)
+
+    def keys(self, *, page: int = 1, page_size: int = 100) -> Obj:
+        """Your API keys with their limits (keys are masked). Returns ``items`` and ``total``."""
+        self._need_token()
+        data = self._c._manage_json("GET", "/api/token/", query={"p": page, "page_size": page_size}).get("data", {})
+        per = self._c._quota_per_unit()
+        items = []
+        for it in data.get("items") or []:
+            unlimited = bool(it.get("unlimited_quota"))
+            limits = it.get("model_limits") or ""
+            if isinstance(limits, str):
+                limits = [x for x in limits.split(",") if x]
+            allow_ips = it.get("allow_ips") or ""
+            ips = [x for x in str(allow_ips).replace("\n", ",").split(",") if x.strip()]
+            items.append({
+                "id": it.get("id"), "name": it.get("name"), "key": it.get("key"),
+                "status": {1: "enabled", 2: "disabled", 3: "expired", 4: "exhausted"}.get(it.get("status"), it.get("status")),
+                "unlimited": unlimited,
+                "remaining_usd": None if unlimited else quota_to_usd(it.get("remain_quota"), per),
+                "used_usd": quota_to_usd(it.get("used_quota"), per),
+                "model_limits_enabled": bool(it.get("model_limits_enabled")),
+                "model_limits": limits,
+                "allow_ips": ips,
+                "group": it.get("group"),
+                "expires_at": 0 if it.get("expired_time") in (None, -1) else it.get("expired_time"),
+                "created_at": it.get("created_time"),
+                "last_used_at": it.get("accessed_time"),
+            })
+        result = KeyList(wrap(items))
+        result.total = data.get("total", len(items))
+        return result
+
+
+class _Rates(_Resource):
+    def usd_rub(self) -> Obj:
+        """Bank of Russia rate used for top-ups: ``rub_per_usd`` and ``date`` (GET /api/access/usd-rate)."""
+        raw = self._c._public_json("/api/access/usd-rate")
+        data = raw.get("data", {})
+        return wrap({"rub_per_usd": float(data["rub_per_usd"]), "date": data.get("date"), "source": data.get("source")})
+
+
+class Klyuchora:
+    """Client for the Klyuchora gateway.
+
+    ``api_key`` (``sk-...``) is needed for model calls, ``/models`` and ``key.usage()``.
+    ``access_token`` is needed only for the ``account`` methods (balance, key list).
+    Both can come from ``KLYUCHORA_API_KEY`` and ``KLYUCHORA_ACCESS_TOKEN``.
+    """
+
+    def __init__(self, api_key: Optional[str] = None, *, access_token: Optional[str] = None,
+                 base_url: Optional[str] = None, timeout: float = 600.0, max_retries: int = 2,
+                 default_headers: Optional[Dict[str, str]] = None):
+        self.api_key = _clean_secret(api_key or env("KLYUCHORA_API_KEY"), "api_key")
+        self.access_token = _clean_secret(access_token or env("KLYUCHORA_ACCESS_TOKEN"), "access_token")
+        root = (base_url or env("KLYUCHORA_BASE_URL") or DEFAULT_BASE_URL).rstrip("/")
+        if root.endswith("/v1"):
+            root = root[:-3]
+        self.base_url = root
+        self._http = Transport(base_url=root, timeout=timeout, max_retries=max_retries, default_headers=default_headers)
+        self._catalog_cache: Optional[Dict[str, Any]] = None
+        self._per_unit: Optional[float] = None
+        self.chat = _Chat(self)
+        self.completions = _Completions(self)
+        self.responses = _Responses(self)
+        self.messages = _Messages(self)
+        self.embeddings = _Embeddings(self)
+        self.images = _Images(self)
+        self.audio = _Audio(self)
+        self.rerank = _Rerank(self)
+        self.moderations = _Moderations(self)
+        self.models = _Models(self)
+        self.key = _Key(self)
+        self.account = _Account(self)
+        self.rates = _Rates(self)
+
+    def with_options(self, **kw: Any) -> "Klyuchora":
+        """Copy of this client with some settings changed (``timeout``, ``max_retries``, ...)."""
+        base = dict(api_key=self.api_key, access_token=self.access_token, base_url=self.base_url,
+                    timeout=self._http.timeout, max_retries=self._http.max_retries,
+                    default_headers=self._http.default_headers)
+        base.update(kw)
+        return Klyuchora(**base)
+
+    # --- plumbing -----------------------------------------------------------------
+    def _relay(self, method: str, path: str, *, json_body: Any = None, data: Optional[bytes] = None,
+               stream: bool = False, timeout: Optional[float] = None, headers: Optional[Dict[str, str]] = None):
+        if not self.api_key:
+            raise AuthenticationError("no API key: pass api_key=... or set KLYUCHORA_API_KEY", status=401, code="no_api_key")
+        hdrs = {"Authorization": "Bearer " + self.api_key}
+        hdrs.update(headers or {})
+        return self._http.request(method, path, headers=hdrs, json_body=json_body, data=data, stream=stream, timeout=timeout)
+
+    def _relay_json(self, method: str, path: str, body: Any, *, timeout: Optional[float] = None,
+                    headers: Optional[Dict[str, str]] = None) -> Obj:
+        resp = self._relay(method, path, json_body=body, timeout=timeout, headers=headers)
+        return wrap(resp.json())
+
+    def _manage_json(self, method: str, path: str, *, query: Optional[Dict[str, Any]] = None) -> Dict[str, Any]:
+        if not self.access_token:
+            raise AuthenticationError("no access token: pass access_token=... or set KLYUCHORA_ACCESS_TOKEN",
+                                      status=401, code="no_access_token")
+        resp = self._http.request(method, path, headers={"Authorization": "Bearer " + self.access_token}, query=query)
+        raw = resp.json()
+        if isinstance(raw, dict) and raw.get("success") is False:
+            raise APIError(str(raw.get("message") or "request failed"), status=resp.status, code=raw.get("code"), body=wrap(raw))
+        return raw
+
+    def _public_json(self, path: str) -> Dict[str, Any]:
+        return self._http.request("GET", path).json()
+
+    def _catalog(self, refresh: bool = False) -> Dict[str, Any]:
+        if self._catalog_cache is None or refresh:
+            self._catalog_cache = self._public_json("/api/pricing")
+        return self._catalog_cache
+
+    def _quota_per_unit(self) -> float:
+        if self._per_unit is None:
+            try:
+                data = self._public_json("/api/status").get("data", {})
+                self._per_unit = float(data.get("quota_per_unit") or QUOTA_PER_USD)
+            except (KlyuchoraError, ValueError, TypeError):
+                self._per_unit = float(QUOTA_PER_USD)
+        return self._per_unit
+
+    # --- helpers --------------------------------------------------------------------
+    def estimate_cost(self, model: str, *, input_tokens: int = 0, output_tokens: int = 0,
+                      cached_tokens: int = 0, requests: int = 1) -> Obj:
+        """Estimate the price of a call from the public catalog.
+
+        The gateway bills by the group that actually serves the request, so the answer is
+        a range: ``min_usd`` for the cheapest group and ``max_usd`` for the most expensive one.
+        With the rate available ``min_rub`` / ``max_rub`` are added (Bank of Russia rate).
+        """
+        item = self.models.price(model)
+        result = estimate(item["prices"], input_tokens, output_tokens, cached_tokens, requests)
+        try:
+            rate = self.rates.usd_rub()["rub_per_usd"]
+            result["min_rub"] = round(result["min_usd"] * rate, 4)
+            result["max_rub"] = round(result["max_usd"] * rate, 4)
+            result["rub_per_usd"] = rate
+        except KlyuchoraError:
+            pass
+        return wrap(result)
+
+    def request(self, method: str, path: str, *, json: Any = None, stream: bool = False,
+                timeout: Optional[float] = None) -> Any:
+        """Call any gateway route that has no helper yet. Returns the decoded JSON, or a :class:`Stream`."""
+        resp = self._relay(method.upper(), path, json_body=json, stream=stream, timeout=timeout)
+        if stream:
+            return Stream(resp)
+        return wrap(resp.json())