taskiq-llm-queue 0.1.0a1__py3-none-any.whl

taskiq_llm_queue/providers/classify.py

@@ -0,0 +1,251 @@
+"""Map Bedrock and OpenAI SDK exceptions to `ErrorInfo` (throttle / retryable / fatal).
+
+Decisions use error *families*, not exact class names or codes, because real services and
+fakes spell the same failure differently (`ThrottlingException`, `Throttling`, `throttled`).
+Used by `BedrockProvider.classify` and `OpenAICompatProvider.classify`; never imports an SDK.
+"""
+
+from __future__ import annotations
+
+import re
+import sys
+import time
+from collections.abc import Mapping
+from email.utils import parsedate_to_datetime
+from typing import Any
+
+from taskiq_llm_queue.errors import ErrorInfo, ErrorKind
+
+# Prefixes of normalised codes (lower-case letters only, "exception"/"error" suffix dropped).
+_THROTTLE_PREFIXES = (
+    "throttl",
+    "toomanyrequests",
+    "modelnotready",
+    "servicequotaexceeded",
+    "requestlimitexceeded",
+    "provisionedthroughputexceeded",
+    "ratelimit",
+    "slowdown",
+)
+_RETRYABLE_PREFIXES = (
+    "serviceunavailable",
+    "internal",
+    "modeltimeout",
+    "modelerror",
+    "modelstreamerror",
+    "requesttimeout",
+    "timeout",
+    "serviceerror",
+    "unavailable",
+)
+_FATAL_PREFIXES = (
+    "validation",
+    "accessdenied",
+    "resourcenotfound",
+    "unrecognizedclient",
+    "notauthorized",
+    "unauthorized",
+    "expiredtoken",
+    "invalid",
+    "badrequest",
+)
+# Fatal families that name one target (model, profile, region, endpoint or the key for that
+# URL), not the request: the next target may serve it. Credentials errors are not here.
+_TARGET_FAMILIES = (
+    "resourcenotfound",
+    "accessdenied",
+    "permissiondenied",
+    "modelnotfound",
+    "notfound",
+    "endpointnotfound",
+    "unknownoperation",
+)
+# A validation / bad-request family counts as target-specific only when its message says so.
+_TARGET_MESSAGE = re.compile(
+    r"model identifier is invalid|invalid model identifier|on-demand throughput"
+    r"|inference profile|model_not_found|unknown model|no such model|end of (?:its )?life"
+    r"|not (?:available|supported|enabled|accessible) (?:in|for) (?:this|the|your) region"
+    r"|\b(?:model|endpoint)\b[^.]{0,80}?\b(?:not found|does not exist|doesn't exist"
+    r"|not available|unavailable|is not supported|isn't supported)",
+    re.IGNORECASE,
+)
+# Request-fatal however the code is spelled: a different target would refuse it the same way.
+_REQUEST_MESSAGE = re.compile(
+    r"too long|too large|too many (?:input )?tokens|context (?:length|window)"
+    r"|maximum (?:input|context|token)|malformed",
+    re.IGNORECASE,
+)
+# Built lazily from whichever modules are already imported; an SDK that was never imported
+# cannot have raised the exception being classified.
+_TRANSPORT_TYPES: dict[str, tuple[str, ...]] = {
+    "botocore.exceptions": (
+        "ReadTimeoutError",
+        "ConnectTimeoutError",
+        "EndpointConnectionError",
+        "ConnectionClosedError",
+        "HTTPClientError",
+    ),
+    "aiohttp": ("ClientError",),
+    "httpx": ("TransportError",),
+    "openai": ("APITimeoutError", "APIConnectionError"),
+}
+
+
+def error_family(code: str) -> str:
+    """Normalise a provider error code: letters only, lower case, no exception suffix.
+
+    `ThrottlingException`, `throttling_exception` and `Throttling` all become `throttling`.
+    """
+    family = re.sub(r"[^a-z]", "", code.lower())
+    for suffix in ("exception", "error", "fault"):
+        if family.endswith(suffix) and len(family) > len(suffix):
+            return family[: -len(suffix)]
+    return family
+
+
+def kind_for_code(code: str, status: int | None = None) -> ErrorKind | None:
+    """Classify a provider error code by family, falling back to the HTTP status.
+
+    Returns None when neither the code nor the status says anything.
+    """
+    family = error_family(code)
+    if family:
+        for prefixes, kind in (
+            (_THROTTLE_PREFIXES, ErrorKind.THROTTLE),
+            (_RETRYABLE_PREFIXES, ErrorKind.RETRYABLE),
+            (_FATAL_PREFIXES, ErrorKind.FATAL),
+        ):
+            if family.startswith(prefixes):
+                return kind
+    return kind_for_status(status)
+
+
+def kind_for_status(status: int | None) -> ErrorKind | None:
+    """Classify by HTTP status alone: 429 throttle, 408/409/5xx retryable, other 4xx fatal."""
+    if status is None:
+        return None
+    if status == 429:
+        return ErrorKind.THROTTLE
+    if status in (408, 409) or status >= 500:
+        return ErrorKind.RETRYABLE
+    if 400 <= status < 500:
+        return ErrorKind.FATAL
+    return None
+
+
+def parse_retry_after(
+    headers: Mapping[str, Any] | None, *, now: float | None = None
+) -> float | None:
+    """Seconds to wait from `retry-after-ms`, else `Retry-After` (seconds or an HTTP date).
+
+    Header names are matched case-blind; unparsable values are ignored and past dates give 0.
+    """
+    if not headers:
+        return None
+    lowered = {str(k).lower(): str(v).strip() for k, v in headers.items()}
+    if (raw_ms := lowered.get("retry-after-ms")) is not None:
+        try:
+            return max(float(raw_ms) / 1000.0, 0.0)
+        except ValueError:
+            pass
+    raw = lowered.get("retry-after")
+    if raw is None:
+        return None
+    try:
+        return max(float(raw), 0.0)
+    except ValueError:
+        pass
+    try:
+        when = parsedate_to_datetime(raw)
+    except (TypeError, ValueError, IndexError):
+        return None
+    current = time.time() if now is None else now
+    return max(when.timestamp() - current, 0.0)
+
+
+def is_transport_error(exc: BaseException) -> bool:
+    """True for timeouts and connection failures from asyncio, botocore, aiohttp, httpx, openai."""
+    if isinstance(exc, TimeoutError | ConnectionError):
+        return True
+    for module_name, names in _TRANSPORT_TYPES.items():
+        module = sys.modules.get(module_name)
+        if module is None:
+            continue
+        types = tuple(t for n in names if isinstance(t := getattr(module, n, None), type))
+        if types and isinstance(exc, types):
+            return True
+    return False
+
+
+def is_target_error(exc: BaseException, info: ErrorInfo) -> bool:
+    """True when a FATAL error is about the target, so `run_call` tries the next fallback step.
+
+    Model or profile not found / not in this region, access denied for the model, unknown
+    endpoint (404). Bad payloads, too-long input and credentials errors end the call.
+    """
+    if info.kind is not ErrorKind.FATAL:
+        return False
+    message = _error_message(exc)
+    if _REQUEST_MESSAGE.search(message):
+        return False
+    family = error_family(info.code)
+    if family.startswith(_TARGET_FAMILIES) or _error_status(exc) == 404:
+        return True
+    request_family = family.startswith(("validation", "badrequest", "invalid"))
+    return (request_family or _error_status(exc) == 400) and bool(_TARGET_MESSAGE.search(message))
+
+
+def _error_message(exc: BaseException) -> str:
+    """A botocore `Error.Message`, else the exception text (openai puts the body there)."""
+    response = getattr(exc, "response", None)
+    if isinstance(response, Mapping) and isinstance(response.get("Error"), Mapping):
+        return str(response["Error"].get("Message") or "")
+    return str(exc)
+
+
+def _error_status(exc: BaseException) -> int | None:
+    """HTTP status of a botocore `ClientError` or an openai `APIStatusError`, if any."""
+    status = getattr(exc, "status_code", None)
+    response = getattr(exc, "response", None)
+    if status is None and isinstance(response, Mapping):
+        status = (response.get("ResponseMetadata") or {}).get("HTTPStatusCode")
+    return status if isinstance(status, int) else None
+
+
+def classify_bedrock(exc: BaseException) -> ErrorInfo:
+    """Classify a botocore `ClientError` (or transport error) from a Bedrock runtime call.
+
+    Unknown codes fall back to the HTTP status; anything else that is not a transport error is
+    fatal, so a bug in the request never loops through retries.
+    """
+    response = getattr(exc, "response", None)
+    if isinstance(response, Mapping) and isinstance(response.get("Error"), Mapping):
+        code = str(response["Error"].get("Code") or "")
+        meta = response.get("ResponseMetadata") or {}
+        status = meta.get("HTTPStatusCode")
+        kind = kind_for_code(code, status if isinstance(status, int) else None)
+        retry_after = parse_retry_after(meta.get("HTTPHeaders"))
+        return ErrorInfo(kind=kind or ErrorKind.FATAL, code=code, retry_after_secs=retry_after)
+    if is_transport_error(exc):
+        return ErrorInfo(kind=ErrorKind.RETRYABLE, code=type(exc).__name__)
+    return ErrorInfo(kind=ErrorKind.FATAL, code=type(exc).__name__)
+
+
+def classify_openai(exc: BaseException) -> ErrorInfo:
+    """Classify an openai SDK exception (or transport error) from an OpenAI-compatible server.
+
+    429 is a throttle carrying the server's advised wait, except `insufficient_quota`, which
+    no wait fixes. 408/409/5xx, timeouts and connection errors are retryable; other 4xx fatal.
+    """
+    if is_transport_error(exc):
+        return ErrorInfo(kind=ErrorKind.RETRYABLE, code=type(exc).__name__)
+    status = getattr(exc, "status_code", None)
+    if not isinstance(status, int):
+        return ErrorInfo(kind=ErrorKind.FATAL, code=type(exc).__name__)
+    code = str(getattr(exc, "code", None) or getattr(exc, "type", None) or type(exc).__name__)
+    response = getattr(exc, "response", None)
+    retry_after = parse_retry_after(getattr(response, "headers", None))
+    kind = kind_for_status(status) or ErrorKind.FATAL
+    if kind is ErrorKind.THROTTLE and code == "insufficient_quota":
+        kind = ErrorKind.FATAL
+    return ErrorInfo(kind=kind, code=code, retry_after_secs=retry_after)

taskiq_llm_queue/providers/embeddings.py

@@ -0,0 +1,87 @@
+"""Embedding batching limits and Bedrock request-body builders (Titan, Cohere).
+
+An embed call is split into tasks of at most `max_batch_size` texts: Titan takes one
+text per request, Cohere v3 up to 96, OpenAI `chunk_size` (2048 by default).
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterator, Mapping, Sequence
+from typing import Any, Literal, TypeVar
+
+_T = TypeVar("_T")  # PEP 695 syntax needs 3.12; the package supports 3.11
+
+TITAN_MAX_BATCH = 1
+COHERE_MAX_BATCH = 96
+OPENAI_DEFAULT_CHUNK_SIZE = 2048
+
+CohereInputType = Literal["search_document", "search_query", "classification", "clustering"]
+
+
+def max_batch_size(provider: str, model_id: str, *, chunk_size: int | None = None) -> int:
+    """Largest number of texts one embedding request may carry for this provider and model.
+
+    Bedrock models other than Cohere are treated like Titan (one text per request).
+    """
+    if provider == "openai":
+        return chunk_size or OPENAI_DEFAULT_CHUNK_SIZE
+    return COHERE_MAX_BATCH if "cohere" in model_id.lower() else TITAN_MAX_BATCH
+
+
+def batches(items: Sequence[_T], size: int) -> Iterator[list[_T]]:
+    """Yield consecutive slices of at most `size` items, preserving order."""
+    if size < 1:
+        raise ValueError("batch size must be >= 1")
+    for start in range(0, len(items), size):
+        yield list(items[start : start + size])
+
+
+def titan_body(
+    text: str, *, dimensions: int | None = None, normalize: bool | None = None
+) -> dict[str, Any]:
+    """InvokeModel body for Amazon Titan text embeddings (v2 accepts dimensions/normalize)."""
+    body: dict[str, Any] = {"inputText": text}
+    if dimensions is not None:
+        body["dimensions"] = dimensions
+    if normalize is not None:
+        body["normalize"] = normalize
+    return body
+
+
+def cohere_body(
+    texts: Sequence[str],
+    *,
+    input_type: CohereInputType = "search_document",
+    truncate: Literal["NONE", "START", "END"] | None = None,
+) -> dict[str, Any]:
+    """InvokeModel body for Cohere embed v3 on Bedrock (at most 96 texts)."""
+    if len(texts) > COHERE_MAX_BATCH:
+        raise ValueError(f"Cohere takes at most {COHERE_MAX_BATCH} texts, got {len(texts)}")
+    body: dict[str, Any] = {"texts": list(texts), "input_type": input_type}
+    if truncate is not None:
+        body["truncate"] = truncate
+    return body
+
+
+def embedding_body(model_id: str, texts: Sequence[str], **options: Any) -> dict[str, Any]:
+    """Pick the Titan or Cohere body builder by model id; Titan takes exactly one text."""
+    if "cohere" in model_id.lower():
+        return cohere_body(texts, **options)
+    if len(texts) != TITAN_MAX_BATCH:
+        raise ValueError(f"Titan takes exactly one text per request, got {len(texts)}")
+    return titan_body(texts[0], **options)
+
+
+def parse_embeddings(decoded: Mapping[str, Any]) -> list[list[float]]:
+    """Vectors from a decoded Titan (`embedding`) or Cohere (`embeddings`) response body.
+
+    Cohere's typed form (`{"embeddings": {"float": [...]}}`) is accepted too.
+    """
+    if "embedding" in decoded:
+        return [list(decoded["embedding"])]
+    vectors = decoded.get("embeddings")
+    if isinstance(vectors, Mapping):
+        vectors = vectors.get("float")
+    if not isinstance(vectors, list):
+        raise ValueError("response has no 'embedding' or 'embeddings'")
+    return [list(v) for v in vectors]

taskiq_llm_queue/providers/hosts.py

@@ -0,0 +1,34 @@
+"""Host deny-list checks for provider endpoints (`QueueConfig.denied_hosts`).
+
+Patterns are shell globs on the URL's host name (`*.openai.azure.com`), matched case-blind.
+Providers run the check before they create a client, so a denied endpoint is never contacted.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+from fnmatch import fnmatchcase
+from urllib.parse import urlsplit
+
+from taskiq_llm_queue.errors import ConfigError
+
+
+def denied_pattern(url: str, denied_hosts: Iterable[str]) -> str | None:
+    """Return the first deny pattern matching `url`'s host, or None when the host is allowed.
+
+    A bare host (`api.example.com`) is accepted as well as a full URL.
+    """
+    host = (urlsplit(url if "//" in url else f"//{url}").hostname or "").lower()
+    for pattern in denied_hosts:
+        if host and fnmatchcase(host, pattern.strip().lower()):
+            return pattern
+    return None
+
+
+def check_url(url: str | None, denied_hosts: Iterable[str]) -> None:
+    """Raise `ConfigError` when `url` points at a denied host; None (SDK default) passes."""
+    if url is None:
+        return
+    pattern = denied_pattern(url, denied_hosts)
+    if pattern is not None:
+        raise ConfigError(f"endpoint {url!r} matches denied host pattern {pattern!r}")

taskiq_llm_queue/providers/openai_compat.py

@@ -0,0 +1,142 @@
+"""OpenAI-compatible provider: chat completions and embeddings against any base URL.
+
+Request bodies are OpenAI-native and pass through unchanged (streaming forced off). SDK
+retries are off (`max_retries=0`) so a 429 and its `Retry-After` reach the limiter.
+"""
+
+from __future__ import annotations
+
+import os
+from collections.abc import Iterable, Mapping
+from typing import TYPE_CHECKING, Any
+
+from taskiq_llm_queue.errors import ConfigError, ErrorInfo
+from taskiq_llm_queue.providers.classify import classify_openai
+from taskiq_llm_queue.providers.hosts import check_url
+
+if TYPE_CHECKING:
+    from openai import AsyncOpenAI
+
+    from taskiq_llm_queue.config import QueueConfig, Target
+    from taskiq_llm_queue.envelope import Op
+
+DEFAULT_TIMEOUT_SECS = 300.0  # unverified; long completions on slow self-hosted servers
+DEFAULT_CONNECT_TIMEOUT_SECS = 10.0
+
+
+class OpenAICompatProvider:
+    """`Provider` for OpenAI-compatible servers: ops `chat` and `embeddings`.
+
+    One `AsyncOpenAI` client per base URL (`Target.base_url`, else the provider default),
+    each with the API key configured for that URL. Responses are `model_dump()` dicts.
+    """
+
+    name = "openai"
+
+    def __init__(
+        self,
+        *,
+        base_url: str | None = None,
+        api_keys: Mapping[str | None, str | None] | None = None,
+        denied_hosts: Iterable[str] = (),
+        timeout_secs: float = DEFAULT_TIMEOUT_SECS,
+        connect_timeout_secs: float = DEFAULT_CONNECT_TIMEOUT_SECS,
+        client_kwargs: Mapping[str, Any] | None = None,
+    ) -> None:
+        """Keep settings only; the openai SDK is imported on the first call.
+
+        `api_keys` maps a base URL (None = the default URL) to its key; a missing key lets
+        the SDK fall back to `OPENAI_API_KEY`. `timeout_secs` is the httpx read (and write /
+        pool) timeout, `connect_timeout_secs` its connect timeout.
+        """
+        self._denied_hosts = tuple(denied_hosts)
+        check_url(base_url, self._denied_hosts)
+        self._base_url = base_url
+        self._api_keys = dict(api_keys or {})
+        self._timeout_secs = timeout_secs
+        self._connect_timeout_secs = connect_timeout_secs
+        self._client_kwargs = dict(client_kwargs or {})
+        self._clients: dict[str | None, AsyncOpenAI] = {}
+
+    @classmethod
+    def from_config(
+        cls, config: QueueConfig, *, environ: Mapping[str, str] | None = None, **kwargs: Any
+    ) -> OpenAICompatProvider:
+        """Build from `QueueConfig`: deny-list every OpenAI target and read keys at boot.
+
+        Each target's `base_url` gets its model's `api_key_env`. A missing variable or two
+        models sharing a URL with different key variables is a `ConfigError` (all reported).
+        """
+        env = os.environ if environ is None else environ
+        key_envs: dict[str | None, str | None] = {}
+        errors: list[str] = []
+        for alias, model in config.models.items():
+            if model.provider != "openai":
+                continue
+            for target in model.targets.values():
+                check_url(target.base_url, config.denied_hosts)
+                url = target.base_url
+                if url in key_envs and key_envs[url] != model.api_key_env:
+                    errors.append(f"{alias}: base_url {url!r} already uses {key_envs[url]!r}")
+                key_envs.setdefault(url, model.api_key_env)
+        api_keys: dict[str | None, str | None] = {}
+        for url, name in key_envs.items():
+            if name is None:
+                continue
+            if not env.get(name):
+                errors.append(f"api_key_env {name!r} (for {url or 'default URL'}) is not set")
+            api_keys[url] = env.get(name)
+        if errors:
+            raise ConfigError("; ".join(errors))
+        kwargs.setdefault("timeout_secs", config.provider_read_timeout_secs)
+        kwargs.setdefault("connect_timeout_secs", config.provider_connect_timeout_secs)
+        return cls(api_keys=api_keys, denied_hosts=config.denied_hosts, **kwargs)
+
+    async def call(self, op: Op, params: Mapping[str, Any], target: Target) -> dict[str, Any]:
+        """Run one chat-completions or embeddings attempt and return the response as a dict."""
+        client = self._client(target.base_url)
+        if op == "chat":
+            response: Any = await client.chat.completions.create(**{**params, "stream": False})
+        elif op == "embeddings":
+            response = await client.embeddings.create(**params)
+        else:
+            raise ValueError(f"OpenAI-compatible provider does not support op {op!r}")
+        result: dict[str, Any] = response.model_dump(mode="json", exclude_unset=True)
+        return result
+
+    def classify(self, exc: BaseException) -> ErrorInfo:
+        """Throttle (with Retry-After) / retryable / fatal by status (see `classify_openai`)."""
+        return classify_openai(exc)
+
+    async def aclose(self) -> None:
+        """Close every client this provider created; safe to call more than once."""
+        clients = list(self._clients.values())
+        self._clients.clear()
+        for client in clients:
+            await client.close()
+
+    def _client(self, target_url: str | None) -> AsyncOpenAI:
+        """Return the cached client for a target URL (None = default), deny-listing it first.
+
+        Keys are looked up by the target URL only, so one host's key never goes to another.
+        """
+        if (client := self._clients.get(target_url)) is not None:
+            return client
+        base_url = target_url or self._base_url
+        check_url(base_url, self._denied_hosts)
+        try:
+            import httpx
+            from openai import AsyncOpenAI
+        except ImportError as exc:
+            raise ConfigError(
+                "OpenAICompatProvider needs the openai SDK: pip install 'taskiq-llm-queue[openai]'"
+            ) from exc
+        client = AsyncOpenAI(
+            api_key=self._api_keys.get(target_url),
+            base_url=base_url,
+            max_retries=0,
+            timeout=httpx.Timeout(self._timeout_secs, connect=self._connect_timeout_secs),
+            **self._client_kwargs,
+        )
+        self._clients[target_url] = client
+        return client

taskiq_llm_queue/providers/registry.py

@@ -0,0 +1,173 @@
+"""Provider registry: built-ins, import-path overrides and entry-point plugins.
+
+Resolution order per provider name: `QueueConfig.providers` (`"pkg.mod:Class"`), then the
+`taskiq_llm_queue.providers` entry-point group, then the built-ins. Every check
+(`allowed_providers`, `denied_hosts`, importability) runs at construction, i.e. at boot.
+"""
+
+from __future__ import annotations
+
+import importlib
+import inspect
+from collections.abc import Callable, Mapping
+from importlib.metadata import entry_points
+from typing import TYPE_CHECKING, Any
+
+from taskiq_llm_queue.errors import ConfigError
+from taskiq_llm_queue.protocols import Provider
+from taskiq_llm_queue.providers.hosts import denied_pattern
+
+if TYPE_CHECKING:
+    from aiobotocore.session import AioSession
+
+    from taskiq_llm_queue.config import QueueConfig
+
+ENTRY_POINT_GROUP = "taskiq_llm_queue.providers"
+BUILTIN_PROVIDERS: Mapping[str, str] = {
+    "bedrock": "taskiq_llm_queue.providers.bedrock:BedrockProvider",
+    "openai": "taskiq_llm_queue.providers.openai_compat:OpenAICompatProvider",
+}
+
+ProviderFactory = Callable[["QueueConfig"], Provider]
+
+
+def load_object(path: str) -> Any:
+    """Import `"pkg.mod:attr.sub"` (or `"pkg.mod.attr"`); failures raise `ConfigError`."""
+    module_name, sep, attr_path = path.partition(":")
+    if not sep:
+        module_name, _, attr_path = path.rpartition(".")
+    if not module_name or not attr_path:
+        raise ConfigError(f"invalid import path {path!r}; expected 'pkg.module:Name'")
+    try:
+        obj: Any = importlib.import_module(module_name)
+        for attr in attr_path.split("."):
+            obj = getattr(obj, attr)
+    except (ImportError, AttributeError) as exc:
+        raise ConfigError(f"cannot load provider {path!r}: {exc}") from exc
+    return obj
+
+
+def as_factory(obj: Any) -> ProviderFactory:
+    """Turn a provider class or callable into a factory taking `QueueConfig`.
+
+    Classes with a `from_config` classmethod use it; anything else is called with the config.
+    """
+    from_config = getattr(obj, "from_config", None)
+    factory = from_config if callable(from_config) else obj
+    if not callable(factory):
+        raise ConfigError(f"provider {obj!r} is not callable")
+    return factory  # type: ignore[no-any-return]
+
+
+class ProviderRegistry:
+    """Builds and caches one `Provider` per name for a `QueueConfig`, enforcing policy.
+
+    Used by workers to find the provider for a model alias; `aclose()` closes them all.
+    `factories` injects ready factories. `aws_session` (set by `LLMQueue.start`) goes to every
+    factory with a `session` keyword, so AWS providers share one credential chain.
+    """
+
+    def __init__(
+        self,
+        config: QueueConfig,
+        *,
+        factories: Mapping[str, ProviderFactory] | None = None,
+        use_entry_points: bool = True,
+    ) -> None:
+        """Validate every provider the config needs and resolve its factory; collect errors."""
+        self._config = config
+        self.aws_session: AioSession | None = None
+        self._providers: dict[str, Provider] = {}
+        self._factories: dict[str, ProviderFactory] = {}
+        injected = dict(factories or {})
+        plugins = (
+            {ep.name: ep for ep in entry_points(group=ENTRY_POINT_GROUP)}
+            if use_entry_points
+            else {}
+        )
+        errors: list[str] = []
+        names = {m.provider for m in config.models.values()} | set(config.providers)
+        for name in sorted(names):
+            if name not in config.allowed_providers:
+                errors.append(f"provider {name!r} is not in allowed_providers")
+                continue
+            try:
+                if name in injected:
+                    self._factories[name] = injected[name]
+                elif name in config.providers:
+                    self._factories[name] = as_factory(load_object(config.providers[name]))
+                elif name in plugins:
+                    self._factories[name] = as_factory(plugins[name].load())
+                elif name in BUILTIN_PROVIDERS:
+                    self._factories[name] = as_factory(load_object(BUILTIN_PROVIDERS[name]))
+                else:
+                    errors.append(f"no provider registered under {name!r}")
+            except ConfigError as exc:
+                errors.append(str(exc))
+            except Exception as exc:  # a broken plugin must fail boot with its name
+                errors.append(f"cannot load provider {name!r}: {exc!r}")
+        errors.extend(_host_errors(config))
+        if errors:
+            raise ConfigError("; ".join(errors))
+
+    def get(self, name: str) -> Provider:
+        """Return the provider registered under `name`, building it on first use."""
+        if (provider := self._providers.get(name)) is not None:
+            return provider
+        factory = self._factories.get(name)
+        if factory is None:
+            raise ConfigError(f"provider {name!r} is not configured or not allowed")
+        try:
+            if self.aws_session is not None and _takes_session(factory):
+                provider = factory(self._config, session=self.aws_session)  # type: ignore[call-arg]  # checked by _takes_session
+            else:
+                provider = factory(self._config)
+        except ConfigError:
+            raise
+        except Exception as exc:  # name the provider: a bare TypeError from a plugin is opaque
+            raise ConfigError(f"provider {name!r} failed to build: {exc!r}") from exc
+        if not isinstance(provider, Provider):
+            raise ConfigError(f"provider {name!r} does not implement the Provider protocol")
+        self._providers[name] = provider
+        return provider
+
+    def for_model(self, model: str) -> Provider:
+        """Return the provider serving `alias[@target]`."""
+        _, cfg, _ = self._config.resolve(model)
+        return self.get(cfg.provider)
+
+    async def aclose(self) -> None:
+        """Close every built provider that has an `aclose()`; safe to call more than once."""
+        providers = list(self._providers.values())
+        self._providers.clear()
+        for provider in providers:
+            close = getattr(provider, "aclose", None)
+            if callable(close):
+                await close()
+
+
+def _takes_session(factory: ProviderFactory) -> bool:
+    """True when the factory names a `session` keyword (e.g. `BedrockProvider.from_config`)."""
+    try:
+        parameters = inspect.signature(factory).parameters
+    except (TypeError, ValueError):  # callables without a signature
+        return False
+    param = parameters.get("session")
+    return param is not None and param.kind in (param.KEYWORD_ONLY, param.POSITIONAL_OR_KEYWORD)
+
+
+def _host_errors(config: QueueConfig) -> list[str]:
+    """Every configured endpoint (model targets, Bedrock endpoint) that hits `denied_hosts`."""
+    if not config.denied_hosts:
+        return []
+    urls = [
+        (f"{alias}@{name}", t.base_url)
+        for alias, m in config.models.items()
+        for name, t in m.targets.items()
+    ]
+    urls.append(("bedrock_endpoint_url", config.bedrock_endpoint_url))
+    errors = []
+    for where, url in urls:
+        if url and (pattern := denied_pattern(url, config.denied_hosts)) is not None:
+            errors.append(f"{where}: endpoint {url!r} matches denied host {pattern!r}")
+    return errors