blablador 0.2.0__py3-none-any.whl

blablador/__init__.py

@@ -0,0 +1,29 @@
+"""Python client for JSC's Blablador LLM API."""
+
+from importlib.metadata import PackageNotFoundError, version
+
+from ._client import API_KEY_ENV, BASE_URL_ENV, DEFAULT_BASE_URL, AsyncBlablador, Blablador
+from ._errors import RateLimitError
+from ._models import BlabladorModel
+from ._reasoning import reasoning
+from ._rerank import RerankResponse, RerankResult, RerankUsage
+
+try:
+    __version__ = version("blablador")
+except PackageNotFoundError:  # running from a source tree that is not installed
+    __version__ = "0+unknown"
+
+__all__ = [
+    "API_KEY_ENV",
+    "BASE_URL_ENV",
+    "DEFAULT_BASE_URL",
+    "AsyncBlablador",
+    "Blablador",
+    "BlabladorModel",
+    "RateLimitError",
+    "RerankResponse",
+    "RerankResult",
+    "RerankUsage",
+    "__version__",
+    "reasoning",
+]

blablador/__main__.py

@@ -0,0 +1,7 @@
+"""`python -m blablador` runs the command-line tool."""
+
+import sys
+
+from .cli import main
+
+sys.exit(main())

blablador/_client.py

@@ -0,0 +1,326 @@
+"""Preconfigured OpenAI SDK clients for Blablador."""
+
+# TASK(20261031-134631): preconfigured Blablador / AsyncBlablador clients
+
+from __future__ import annotations
+
+import os
+import time
+from collections.abc import Awaitable, Callable, Mapping
+from functools import cached_property
+from typing import Any
+
+import anyio
+import httpx2
+import openai
+from openai import DEFAULT_MAX_RETRIES, APIStatusError, AuthenticationError, NotGiven, not_given
+from openai._base_client import _RequestBodyReplay
+from openai._models import FinalRequestOptions
+from typing_extensions import Self
+
+from ._errors import RateLimitError
+from ._models import AsyncBlabladorModels, BlabladorModels
+from ._rerank import AsyncRerank, Rerank
+from ._retry import DEFAULT_MAX_WAIT, RateLimitGate, RateLimitPolicy
+from ._tools import prepare_tool_descriptions
+
+DEFAULT_BASE_URL = "https://api.blablador.fz-juelich.de/v1"
+API_KEY_ENV = "BLABLADOR_API_KEY"
+BASE_URL_ENV = "BLABLADOR_BASE_URL"
+TOKEN_URL = "https://codebase.helmholtz.cloud/-/user_settings/personal_access_tokens"
+
+_KEY_HELP = (
+    f"Create a token with the `read_user` scope at {TOKEN_URL} "
+    f"and pass it as `api_key` or set {API_KEY_ENV}."
+)
+_AUTH_HINT = (
+    "Blablador rejected the API key. Helmholtz Codebase tokens are valid for at most "
+    f"one year, so it may have expired. {_KEY_HELP}"
+)
+
+
+def _resolve(api_key: Any, base_url: Any) -> tuple[Any, Any]:
+    """Fill in the API key and base URL from BLABLADOR_* variables; explicit arguments win."""
+    if api_key is None:
+        api_key = os.environ.get(API_KEY_ENV)
+    if not api_key:
+        raise openai.OpenAIError(f"Missing Blablador API key. {_KEY_HELP}")
+    if base_url is None or isinstance(base_url, NotGiven):
+        base_url = os.environ.get(BASE_URL_ENV) or DEFAULT_BASE_URL
+    return api_key, base_url
+
+
+class _BlabladorMixin:
+    """Behaviour shared by the sync and async clients.
+
+    The OpenAI constructor reads OPENAI_* variables for anything not passed explicitly
+    (organization, project, admin key, extra headers). Those belong to OpenAI, not to
+    Blablador, so `_drop_openai_env` undoes them after construction: an OpenAI setup in
+    the user's shell must not send its headers or credentials to Blablador. `copy()` /
+    `with_options()` build new instances through `__init__`, so they get the same treatment.
+    """
+
+    organization: str | None
+    project: str | None
+    admin_api_key: str | None
+    webhook_secret: str | None
+    _custom_headers: Mapping[str, str]
+    _ambient_authorizations: frozenset[str]
+    _rate_limit: RateLimitPolicy
+
+    @property
+    def rate_limit_retries(self) -> int:
+        """How often a request is retried after a 429 that states how long to wait."""
+        return self._rate_limit.retries
+
+    @property
+    def max_rate_limit_wait(self) -> float:
+        """The longest stated wait, in seconds, that is waited out rather than raised."""
+        return self._rate_limit.max_wait
+
+    def copy(
+        self,
+        *,
+        rate_limit_retries: int | None = None,
+        max_rate_limit_wait: float | None = None,
+        _extra_kwargs: Mapping[str, Any] = {},
+        **kwargs: Any,
+    ) -> Self:
+        """`openai.OpenAI.copy`, plus the rate-limit settings. A copy that keeps the API key
+        and base URL also shares the record of the key's current block."""
+        base_url = kwargs.get("base_url")
+        same_key = kwargs.get("api_key") is None and (
+            base_url is None or isinstance(base_url, NotGiven)
+        )
+        rate_limit = {
+            "rate_limit_retries": (
+                self.rate_limit_retries if rate_limit_retries is None else rate_limit_retries
+            ),
+            "max_rate_limit_wait": (
+                self.max_rate_limit_wait if max_rate_limit_wait is None else max_rate_limit_wait
+            ),
+            "_rate_limit_gate": self._rate_limit.gate if same_key else None,
+        }
+        return super().copy(  # type: ignore[misc]
+            _extra_kwargs={**rate_limit, **_extra_kwargs}, **kwargs
+        )
+
+    with_options = copy
+
+    def _drop_openai_env(
+        self,
+        *,
+        organization: str | None,
+        project: str | None,
+        admin_api_key: str | None,
+        webhook_secret: str | None,
+        default_headers: Mapping[str, str] | None,
+    ) -> None:
+        self.organization = organization
+        self.project = project
+        self.admin_api_key = admin_api_key
+        self.webhook_secret = webhook_secret
+        # OPENAI_CUSTOM_HEADERS is merged into the custom headers; keep only explicit ones.
+        self._custom_headers = dict(default_headers or {})
+        self._ambient_authorizations = frozenset()
+
+    def _make_status_error(
+        self, err_msg: str, *, body: object, response: httpx2.Response
+    ) -> APIStatusError:
+        err: APIStatusError = super()._make_status_error(  # type: ignore[misc]
+            err_msg, body=body, response=response
+        )
+        if isinstance(err, AuthenticationError):
+            return AuthenticationError(f"{err_msg}\n{_AUTH_HINT}", response=response, body=err.body)
+        if isinstance(err, openai.RateLimitError):
+            return RateLimitError(err_msg, response=response, body=err.body)
+        return err
+
+    def _should_retry(self, response: httpx2.Response) -> bool:
+        # TASK(20261031-134636): never retry 429. Blablador blocks a key for 60 s and doubles
+        # the block with each further violation, and the SDK's quick retries (or a short
+        # Retry-After) could count as violations. Timeouts, 409 and 5xx still retry. The
+        # opt-in `rate_limit_retries` waits out a stated block in `request` instead.
+        if response.status_code == 429:
+            return False
+        return super()._should_retry(response)  # type: ignore[misc]
+
+
+class Blablador(_BlabladorMixin, openai.OpenAI):
+    """`openai.OpenAI` preconfigured for Blablador.
+
+    The API key comes from `api_key` or BLABLADOR_API_KEY, the base URL from `base_url`,
+    BLABLADOR_BASE_URL or the public endpoint. OPENAI_* variables are ignored. Function
+    tools without a description get `description: ""`, which the gateway requires.
+
+    429 responses raise `blablador.RateLimitError` and are not retried, unless
+    `rate_limit_retries` is set: then a request waits out a 429 that states how long to wait
+    (and at most `max_rate_limit_wait` seconds) and is sent again, up to that many times. While
+    the key is known to be blocked, other requests through this client and its copies with
+    `rate_limit_retries` set wait too, or raise if the wait would be longer than
+    `max_rate_limit_wait`. All other arguments are those of `openai.OpenAI`.
+    """
+
+    def __init__(
+        self,
+        *,
+        api_key: str | Callable[[], str] | None = None,
+        base_url: str | httpx2.URL | None = None,
+        organization: str | None = None,
+        project: str | None = None,
+        admin_api_key: str | None = None,
+        webhook_secret: str | None = None,
+        timeout: float | httpx2.Timeout | None | NotGiven = not_given,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        default_headers: Mapping[str, str] | None = None,
+        default_query: Mapping[str, object] | None = None,
+        http_client: httpx2.Client | None = None,
+        rate_limit_retries: int = 0,
+        max_rate_limit_wait: float = DEFAULT_MAX_WAIT,
+        _rate_limit_gate: RateLimitGate | None = None,
+        **kwargs: Any,
+    ) -> None:
+        api_key, base_url = _resolve(api_key, base_url)
+        self._rate_limit = RateLimitPolicy(
+            rate_limit_retries, max_rate_limit_wait, _rate_limit_gate
+        )
+        super().__init__(
+            api_key=api_key,
+            base_url=base_url,
+            organization=organization,
+            project=project,
+            admin_api_key=admin_api_key,
+            webhook_secret=webhook_secret,
+            timeout=timeout,
+            max_retries=max_retries,
+            default_headers=default_headers,
+            default_query=default_query,
+            http_client=http_client,
+            **kwargs,
+        )
+        self._drop_openai_env(
+            organization=organization,
+            project=project,
+            admin_api_key=admin_api_key,
+            webhook_secret=webhook_secret,
+            default_headers=default_headers,
+        )
+
+    def _prepare_options(self, options: FinalRequestOptions) -> FinalRequestOptions:
+        return super()._prepare_options(prepare_tool_descriptions(options))
+
+    def request(  # type: ignore[override]
+        self, cast_to: Any, options: FinalRequestOptions, *, stream: bool = False, **kwargs: Any
+    ) -> Any:
+        if not self.rate_limit_retries:
+            return super().request(cast_to, options, stream=stream, **kwargs)
+        body = _RequestBodyReplay(options)
+        retries_taken = 0
+        while True:
+            # Re-check after sleeping: another thread may have recorded a longer block.
+            while (wait := self._rate_limit.wait_before_send()) > 0:
+                time.sleep(wait)
+            try:
+                return super().request(cast_to, options, stream=stream, **kwargs)
+            except RateLimitError as err:
+                replayable = body.rewind()
+                if (
+                    self._rate_limit.wait_before_retry(err, retries_taken, replayable=replayable)
+                    is None
+                ):
+                    raise
+                retries_taken += 1
+
+    @cached_property
+    def models(self) -> BlabladorModels:
+        """`list()` returns `BlabladorModel`s with Blablador's fields; `aliases()` maps
+        alias names to models. `retrieve()` is not supported by Blablador (404)."""
+        return BlabladorModels(self)
+
+    @cached_property
+    def rerank(self) -> Rerank:
+        """Order documents by relevance to a query (`/v1/rerank`, not in the OpenAI API)."""
+        return Rerank(self)
+
+
+class AsyncBlablador(_BlabladorMixin, openai.AsyncOpenAI):
+    """`openai.AsyncOpenAI` preconfigured for Blablador; configured like `Blablador`."""
+
+    def __init__(
+        self,
+        *,
+        api_key: str | Callable[[], Awaitable[str]] | None = None,
+        base_url: str | httpx2.URL | None = None,
+        organization: str | None = None,
+        project: str | None = None,
+        admin_api_key: str | None = None,
+        webhook_secret: str | None = None,
+        timeout: float | httpx2.Timeout | None | NotGiven = not_given,
+        max_retries: int = DEFAULT_MAX_RETRIES,
+        default_headers: Mapping[str, str] | None = None,
+        default_query: Mapping[str, object] | None = None,
+        http_client: httpx2.AsyncClient | None = None,
+        rate_limit_retries: int = 0,
+        max_rate_limit_wait: float = DEFAULT_MAX_WAIT,
+        _rate_limit_gate: RateLimitGate | None = None,
+        **kwargs: Any,
+    ) -> None:
+        api_key, base_url = _resolve(api_key, base_url)
+        self._rate_limit = RateLimitPolicy(
+            rate_limit_retries, max_rate_limit_wait, _rate_limit_gate
+        )
+        super().__init__(
+            api_key=api_key,
+            base_url=base_url,
+            organization=organization,
+            project=project,
+            admin_api_key=admin_api_key,
+            webhook_secret=webhook_secret,
+            timeout=timeout,
+            max_retries=max_retries,
+            default_headers=default_headers,
+            default_query=default_query,
+            http_client=http_client,
+            **kwargs,
+        )
+        self._drop_openai_env(
+            organization=organization,
+            project=project,
+            admin_api_key=admin_api_key,
+            webhook_secret=webhook_secret,
+            default_headers=default_headers,
+        )
+
+    async def _prepare_options(self, options: FinalRequestOptions) -> FinalRequestOptions:
+        return await super()._prepare_options(prepare_tool_descriptions(options))
+
+    async def request(  # type: ignore[override]
+        self, cast_to: Any, options: FinalRequestOptions, *, stream: bool = False, **kwargs: Any
+    ) -> Any:
+        if not self.rate_limit_retries:
+            return await super().request(cast_to, options, stream=stream, **kwargs)
+        body = _RequestBodyReplay(options)
+        retries_taken = 0
+        while True:
+            while (wait := self._rate_limit.wait_before_send()) > 0:
+                await anyio.sleep(wait)
+            try:
+                return await super().request(cast_to, options, stream=stream, **kwargs)
+            except RateLimitError as err:
+                replayable = body.rewind()
+                if (
+                    self._rate_limit.wait_before_retry(err, retries_taken, replayable=replayable)
+                    is None
+                ):
+                    raise
+                retries_taken += 1
+
+    @cached_property
+    def models(self) -> AsyncBlabladorModels:
+        """See `Blablador.models`."""
+        return AsyncBlabladorModels(self)
+
+    @cached_property
+    def rerank(self) -> AsyncRerank:
+        """See `Blablador.rerank`."""
+        return AsyncRerank(self)

blablador/_errors.py

@@ -0,0 +1,104 @@
+"""Blablador-specific errors."""
+
+# TASK(20261031-134636): rate-limit-safe retries
+
+from __future__ import annotations
+
+import email.utils
+import math
+import re
+import time
+
+import httpx2
+import openai
+
+RATE_LIMIT_HINT = (
+    "Blablador blocks a key that exceeds its rate limit: 60 s for the first violation, doubling "
+    "with each further one up to 1 h. The client does not retry 429 responses unless "
+    "`rate_limit_retries` is set, since a retry may extend the block; wait before sending more "
+    "requests."
+)
+
+_UNIT_SECONDS = {"ms": 0.001, "s": 1.0, "m": 60.0, "h": 3600.0}
+# A number with a unit, after a phrase that says it is a wait ("try again in 57 seconds",
+# "remaining time: 42s", "blocked for 2 minutes"). Bare "in" or "for" are not enough: they
+# also introduce the limit's window ("100 requests in 1 hour", "requests for user 12345 in
+# the last 60 seconds"), which is not how long to wait. Longer unit spellings come first.
+_WAIT_IN_TEXT = re.compile(
+    r"\b(?:(?:try\s+again|retry|resets?)\s+(?:in|after)|retry-after|wait(?:\s+for)?"
+    r"|remaining|blocked\s+for)\b\D{0,30}?"
+    r"(\d+(?:\.\d+)?)\s*"
+    r"(milliseconds?|ms|seconds?|secs?|s|minutes?|mins?|m|hours?|hrs?|h)\b",
+    re.IGNORECASE,
+)
+
+
+def parse_retry_after(headers: httpx2.Headers) -> float | None:
+    """Seconds to wait according to `retry-after-ms` or `retry-after`, or None if not given."""
+    for name, divisor in (("retry-after-ms", 1000), ("retry-after", 1)):
+        value = headers.get(name)
+        if value is None:
+            continue
+        try:
+            seconds = float(value) / divisor
+        except ValueError:
+            continue
+        # "nan" or "inf" would pass every comparison or never end; treat them as not given.
+        if math.isfinite(seconds):
+            return max(seconds, 0.0)
+    date = email.utils.parsedate_tz(headers.get("retry-after") or "")
+    if date is None:
+        return None
+    try:
+        return max(email.utils.mktime_tz(date) - time.time(), 0.0)
+    except (OverflowError, ValueError):
+        return None
+
+
+def parse_wait_in_text(text: str) -> float | None:
+    """Seconds to wait stated in an error message, or None. With several, the longest wins:
+    waiting too long costs time, waiting too little may extend the block."""
+    waits = []
+    for number, unit in _WAIT_IN_TEXT.findall(text):
+        unit = unit.lower()
+        key = "ms" if unit.startswith("milli") or unit == "ms" else unit[0]
+        waits.append(float(number) * _UNIT_SECONDS[key])
+    return max(waits) if waits else None
+
+
+def _response_text(response: httpx2.Response) -> str:
+    try:
+        return response.text
+    except httpx2.ResponseNotRead:
+        return ""
+
+
+class RateLimitError(openai.RateLimitError):
+    """HTTP 429 from Blablador. Also an `openai.RateLimitError`.
+
+    `retry_after` is the wait in seconds the server asked for, from a `Retry-After` /
+    `retry-after-ms` header or else from the message text, or None if it did not say.
+    """
+
+    retry_after: float | None
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        response: httpx2.Response,
+        body: object | None,
+        retry_after: float | None = None,
+    ) -> None:
+        # `retry_after` is passed when the client raises a block it already knows about
+        # (the remaining time) instead of sending the request.
+        self.server_message = message
+        if retry_after is None:
+            retry_after = parse_retry_after(response.headers)
+        if retry_after is None:
+            retry_after = parse_wait_in_text(_response_text(response))
+        self.retry_after = retry_after
+        hint = RATE_LIMIT_HINT
+        if self.retry_after is not None:
+            hint += f" The server asks to wait {self.retry_after:.0f} s."
+        super().__init__(f"{message}\n{hint}", response=response, body=body)

blablador/_models.py

@@ -0,0 +1,127 @@
+"""Model listing with Blablador's extra fields.
+
+TASK(20261031-134634): `GET /v1/models` entries carry fields the OpenAI API does not have
+(`root`, `max_model_len`, `client_count`, ...), which the SDK keeps only in `model_extra`.
+`client.models.list()` returns `BlabladorModel`s that declare them, and
+`client.models.aliases()` maps each `alias-*` name to the model behind it.
+
+Observed 2026-10-31 (63 entries): `root` is a Hugging Face name, an absolute path on the
+server, or null (7 entries); `max_model_len` is missing on 10 (image, audio, anonymizer);
+`parent` is always null. `GET /v1/models/{id}` answers 404, so `retrieve()` does not work.
+`capabilities` appears on only 2 entries, in two different shapes, so what a model can do
+(chat, embeddings, rerank, ...) cannot be read from the listing.
+"""
+
+from __future__ import annotations
+
+import httpx2
+from openai._base_client import AsyncPaginator, make_request_options
+from openai._types import Body, Headers, NotGiven, Query, not_given
+from openai.pagination import AsyncPage, SyncPage
+from openai.resources.models import AsyncModels, Models
+from openai.types import Model
+
+ALIAS_PREFIX = "alias-"
+
+
+class BlabladorModel(Model):
+    """A model as Blablador lists it: `openai.types.Model` plus the gateway's fields.
+
+    Fields the gateway adds beyond these (`router_instances`, `backend_instances`,
+    `permission`, ...) stay available in `model_extra`.
+    """
+
+    root: str | None = None
+    """The underlying model: a Hugging Face name such as `openai/gpt-oss-120b`, a path on
+    the server's filesystem, or None. Aliases and display names of one model share it."""
+
+    parent: str | None = None
+
+    max_model_len: int | None = None
+    """Context length in tokens, if the backend reports one."""
+
+    client_count: int | None = None
+    """Number of backend servers currently serving the model, if reported."""
+
+    @property
+    def is_alias(self) -> bool:
+        """True for the `alias-*` names, which keep pointing at a current model."""
+        return self.id.startswith(ALIAS_PREFIX)
+
+
+class BlabladorModels(Models):
+    """`client.models` with typed Blablador fields and `aliases()`."""
+
+    def list(  # pyright: ignore[reportIncompatibleMethodOverride]
+        self,
+        *,
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx2.Timeout | None | NotGiven = not_given,
+    ) -> SyncPage[BlabladorModel]:
+        """List the available models, including the `alias-*` names."""
+        return self._get_api_list(
+            "/models",
+            page=SyncPage[BlabladorModel],
+            options=make_request_options(
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                security={"bearer_auth": True},
+            ),
+            model=BlabladorModel,
+        )
+
+    def aliases(
+        self,
+        *,
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        timeout: float | httpx2.Timeout | None | NotGiven = not_given,
+    ) -> dict[str, str | None]:
+        """Map each `alias-*` name to the `root` of the model behind it right now (one request).
+
+        Aliases are re-pointed as models are replaced, so read this at runtime rather than
+        hardcoding it. The value is None for models whose backend reports no root.
+        """
+        models = self.list(extra_headers=extra_headers, extra_query=extra_query, timeout=timeout)
+        return {model.id: model.root for model in models if model.is_alias}
+
+
+class AsyncBlabladorModels(AsyncModels):
+    """`client.models` of `AsyncBlablador`; see `BlabladorModels`."""
+
+    def list(  # pyright: ignore[reportIncompatibleMethodOverride]
+        self,
+        *,
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        extra_body: Body | None = None,
+        timeout: float | httpx2.Timeout | None | NotGiven = not_given,
+    ) -> AsyncPaginator[BlabladorModel, AsyncPage[BlabladorModel]]:
+        """List the available models, including the `alias-*` names."""
+        return self._get_api_list(
+            "/models",
+            page=AsyncPage[BlabladorModel],
+            options=make_request_options(
+                extra_headers=extra_headers,
+                extra_query=extra_query,
+                extra_body=extra_body,
+                timeout=timeout,
+                security={"bearer_auth": True},
+            ),
+            model=BlabladorModel,
+        )
+
+    async def aliases(
+        self,
+        *,
+        extra_headers: Headers | None = None,
+        extra_query: Query | None = None,
+        timeout: float | httpx2.Timeout | None | NotGiven = not_given,
+    ) -> dict[str, str | None]:
+        """Map each `alias-*` name to the `root` of the model behind it right now (one request)."""
+        models = self.list(extra_headers=extra_headers, extra_query=extra_query, timeout=timeout)
+        return {model.id: model.root async for model in models if model.is_alias}

blablador/_reasoning.py

@@ -0,0 +1,33 @@
+"""Typed access to the reasoning text of chat completions.
+
+TASK(20261031-134633): reasoning models on Blablador return their reasoning next to the
+answer, in a field the OpenAI API does not define, so the SDK keeps it only in
+`model_extra`. The name depends on the backend (checked 2026-10-31): vLLM sends
+`reasoning` (alias-fast, alias-code, alias-deepseek-v41-flash-booster), sglang sends
+`reasoning_content` (alias-mistral-large).
+"""
+
+from __future__ import annotations
+
+from openai.types.chat import ChatCompletionMessage
+from openai.types.chat.chat_completion_chunk import ChoiceDelta
+
+REASONING_FIELDS = ("reasoning", "reasoning_content")
+
+
+def reasoning(message: ChatCompletionMessage | ChoiceDelta) -> str | None:
+    """The reasoning text of a chat message or a streamed delta, or None if it has none.
+
+    completion = client.chat.completions.create(...)
+    print(blablador.reasoning(completion.choices[0].message))
+
+    for chunk in client.chat.completions.create(..., stream=True):
+        if chunk.choices:
+            print(blablador.reasoning(chunk.choices[0].delta) or "", end="")
+    """
+    for name in REASONING_FIELDS:
+        # getattr finds the field in `model_extra` and also once a later SDK declares it.
+        value = getattr(message, name, None)
+        if isinstance(value, str):
+            return value
+    return None