codebase-receipts-cli 1.0.0__py3-none-any.whl

receipts/llm/gemini_provider.py

@@ -0,0 +1,205 @@
+"""SECONDARY provider — Google Gemini via a free-tier Google AI Studio key.
+
+API facts verified against the installed google-genai 2.10.0 package:
+``client.models.generate_content`` takes keyword-only params with the system
+prompt in ``config.system_instruction``; ``response.text`` is Optional (None
+on safety blocks); real token usage lives in ``response.usage_metadata``
+(``prompt_token_count`` / ``candidates_token_count`` / ``thoughts_token_count``,
+all Optional). We read GEMINI_API_KEY from our own config and pass it
+explicitly, because the SDK would otherwise let a stray GOOGLE_API_KEY env var
+silently take precedence.
+"""
+
+from __future__ import annotations
+
+import sys
+import time
+from collections.abc import Callable
+from typing import TypeVar
+
+from google import genai
+from google.genai import errors as genai_errors
+from google.genai import types as genai_types
+
+from receipts.errors import ProviderConfigError, ProviderUnavailableError
+from receipts.llm.provider import CompletionResult, LLMProvider
+
+_T = TypeVar("_T")
+
+# Free-tier quotas reset on a one-minute window, so waiting out the window
+# and retrying almost always succeeds. Waits are cumulative per call.
+_RATE_LIMIT_BACKOFF_S = (20, 30, 45, 60, 60)
+
+# 429 = quota window exhausted; 503 = model temporarily overloaded
+# ("high demand"). Both are transient and clear on their own.
+_TRANSIENT_CODES = {429, 503}
+
+_MISSING_KEY_HELP = """\
+No Gemini API key configured.
+  Get a free key at https://aistudio.google.com/apikey and set
+  GEMINI_API_KEY=<your key> in your environment or local .env file."""
+
+_BAD_KEY_HELP = """\
+Gemini rejected your API key (HTTP {code}).
+  Check that GEMINI_API_KEY is set to a valid key from
+  https://aistudio.google.com/apikey (no quotes, no extra spaces)."""
+
+_RATE_LIMIT_HELP = """\
+Gemini free-tier rate limit hit (HTTP 429) and did not clear after several
+retries. Wait a few minutes and re-run, or switch back to local Ollama:
+  set RECEIPTS_PROVIDER=ollama (the default)."""
+
+_DAILY_QUOTA_HELP = """\
+Gemini free-tier DAILY quota exhausted for this model (HTTP 429, per-day
+limit) — retrying won't help until the quota resets at midnight Pacific.
+Options:
+  - switch to local Ollama for now: set RECEIPTS_PROVIDER=ollama
+  - try a model with a separate quota: set GEMINI_CHAT_MODEL=gemini-3.5-flash-lite
+  - wait for the daily reset."""
+
+
+class GeminiProvider(LLMProvider):
+    name = "gemini"
+
+    def __init__(
+        self, *, api_key: str | None, chat_model: str, embed_model: str
+    ) -> None:
+        if not api_key:
+            raise ProviderConfigError(_MISSING_KEY_HELP)
+        self.chat_model = chat_model
+        self.embed_model = embed_model
+        self._client = genai.Client(api_key=api_key)
+        # Optional hook so TUIs can surface retry waits in their status bar;
+        # when unset, waits are announced on stderr (fine for plain CLI runs).
+        self.wait_callback: Callable[[str, int], None] | None = None
+
+    def check_available(self) -> None:
+        """Validate the API key and chat model id up front (no tokens).
+
+        A wrong model id otherwise fails on every one of dozens of calls
+        mid-run; ``models.get`` is a free metadata call that catches it
+        before any real work starts.
+        """
+        try:
+            self._client.models.get(model=self.chat_model)
+        except genai_errors.APIError as exc:
+            raise self._translate_api_error(exc, model=self.chat_model) from exc
+
+    def _notify_wait(self, reason: str, wait: int) -> None:
+        if self.wait_callback is not None:
+            try:
+                self.wait_callback(reason, wait)
+                return
+            except Exception:
+                pass
+        print(
+            f"[gemini] {reason} — waiting {wait}s before retrying...",
+            file=sys.stderr,
+        )
+
+    def _with_rate_limit_retry(self, fn: Callable[[], _T]) -> _T:
+        """Run an API call, waiting out transient 429/503s before giving up.
+
+        Free-tier quotas (requests + tokens) reset every minute and
+        "high demand" 503s clear on their own, so a paced retry converts
+        a hard failure into a slower-but-successful run.
+        """
+        for wait in _RATE_LIMIT_BACKOFF_S:
+            try:
+                return fn()
+            except genai_errors.APIError as exc:
+                code = exc.code or 0
+                if code not in _TRANSIENT_CODES:
+                    raise
+                # A per-DAY quota 429 won't clear until midnight Pacific —
+                # waiting is pointless, so fail fast with a clear message.
+                if code == 429 and "perday" in str(exc).lower():
+                    raise ProviderUnavailableError(_DAILY_QUOTA_HELP) from exc
+                reason = (
+                    "free-tier rate limit hit"
+                    if code == 429
+                    else "model overloaded (503)"
+                )
+                self._notify_wait(reason, wait)
+                time.sleep(wait)
+        return fn()
+
+    def complete(
+        self, system: str, user: str, *, json_mode: bool = False
+    ) -> CompletionResult:
+        config: dict = {"system_instruction": system}
+        if json_mode:
+            config["response_mime_type"] = "application/json"
+        try:
+            response = self._with_rate_limit_retry(
+                lambda: self._client.models.generate_content(
+                    model=self.chat_model, contents=user, config=config
+                )
+            )
+        except genai_errors.APIError as exc:
+            raise self._translate_api_error(exc, model=self.chat_model) from exc
+
+        # response.text is None when the prompt was blocked or no text part
+        # came back — surface an empty string, never invent content.
+        text = response.text or ""
+        usage = response.usage_metadata
+        input_tokens = (usage.prompt_token_count or 0) if usage else 0
+        output_tokens = 0
+        if usage:
+            # Thinking tokens are billed as output, so the ledger counts them.
+            output_tokens = (usage.candidates_token_count or 0) + (
+                usage.thoughts_token_count or 0
+            )
+        return CompletionResult(
+            text=text,
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            provider=self.name,
+            model=self.chat_model,
+            tokens_estimated=usage is None,
+        )
+
+    def embed(self, texts: list[str]) -> list[list[float]]:
+        if not texts:
+            return []
+        # A plain list[str] gets merged into ONE Content (each string becomes
+        # a part of a single input), so the API returns a single embedding for
+        # the whole batch. Wrapping each text in its own Content makes it a
+        # true batch — verified against google-genai 2.10.0 + gemini-embedding-2.
+        contents = [
+            genai_types.Content(parts=[genai_types.Part(text=t)]) for t in texts
+        ]
+        try:
+            response = self._with_rate_limit_retry(
+                lambda: self._client.models.embed_content(
+                    model=self.embed_model, contents=contents
+                )
+            )
+        except genai_errors.APIError as exc:
+            raise self._translate_api_error(exc, model=self.embed_model) from exc
+        embeddings = [
+            list(embedding.values or []) for embedding in response.embeddings or []
+        ]
+        if len(embeddings) != len(texts):
+            raise ProviderUnavailableError(
+                f"Gemini returned {len(embeddings)} embedding(s) for"
+                f" {len(texts)} input(s). The embedding model"
+                f" '{self.embed_model}' may not support batching — try a"
+                " different GEMINI_EMBED_MODEL."
+            )
+        return embeddings
+
+    @staticmethod
+    def _translate_api_error(exc: genai_errors.APIError, *, model: str) -> Exception:
+        code = exc.code or 0
+        if code in (401, 403):
+            return ProviderConfigError(_BAD_KEY_HELP.format(code=code))
+        if code == 404:
+            return ProviderConfigError(
+                f"Gemini model '{model}' was not found. Set GEMINI_CHAT_MODEL /"
+                " GEMINI_EMBED_MODEL to a current model id"
+                " (see https://ai.google.dev/gemini-api/docs/models)."
+            )
+        if code == 429:
+            return ProviderUnavailableError(_RATE_LIMIT_HELP)
+        return ProviderUnavailableError(f"Gemini API error {code}: {exc.message}")

receipts/llm/json_utils.py

@@ -0,0 +1,46 @@
+"""Tolerant JSON parsing for LLM responses.
+
+Small models (and rate-limited lite tiers) frequently wrap valid JSON in
+markdown fences, prepend prose, or use slightly-off shapes. This module
+recovers the JSON when it's genuinely there — and raises when it isn't.
+It never invents content: if nothing parseable exists, the caller keeps
+its honest fallback (e.g. "plausible — response could not be parsed").
+"""
+
+from __future__ import annotations
+
+import json
+import re
+
+_FENCE_RE = re.compile(r"^```(?:json)?\s*(.*?)\s*```\s*$", re.DOTALL)
+
+
+def parse_json_loose(text: str):
+    """``json.loads`` with markdown fences and surrounding prose stripped.
+
+    Raises ``ValueError`` (or ``json.JSONDecodeError``) when no JSON value
+    can be recovered.
+    """
+    if not text or not text.strip():
+        raise ValueError("empty response")
+
+    t = text.strip()
+
+    fenced = _FENCE_RE.match(t)
+    if fenced:
+        t = fenced.group(1).strip()
+
+    try:
+        return json.loads(t)
+    except json.JSONDecodeError:
+        pass
+
+    # Fall back to the outermost {...} or [...] block inside the text.
+    starts = [i for i in (t.find("{"), t.find("[")) if i != -1]
+    if not starts:
+        raise ValueError("no JSON object or array found")
+    start = min(starts)
+    end = max(t.rfind("}"), t.rfind("]"))
+    if end <= start:
+        raise ValueError("no JSON object or array found")
+    return json.loads(t[start : end + 1])

receipts/llm/metered.py

@@ -0,0 +1,62 @@
+"""Transparent metering wrapper — logs every LLM call to the token ledger.
+
+Ground rule: every LLM call is metered and logged, even when the provider is
+free. The factory wraps real providers in this class so no pipeline code has
+to remember to log anything. Attribute access (``name``, ``wait_callback``,
+``embed_model``, ...) is forwarded to the wrapped provider, so callers can't
+tell the difference — and ledger failures never break an actual LLM call.
+"""
+
+from __future__ import annotations
+
+from receipts.ledger.token_ledger import TokenLedger
+from receipts.llm.provider import CompletionResult, LLMProvider
+
+
+class MeteredProvider(LLMProvider):
+    """Wraps any provider and records its calls in the SQLite token ledger."""
+
+    def __init__(self, inner: LLMProvider, ledger: TokenLedger | None = None):
+        object.__setattr__(self, "_inner", inner)
+        object.__setattr__(self, "_ledger", ledger or TokenLedger())
+
+    @property
+    def name(self) -> str:
+        return self._inner.name
+
+    def complete(
+        self, system: str, user: str, *, json_mode: bool = False
+    ) -> CompletionResult:
+        result = self._inner.complete(system, user, json_mode=json_mode)
+        try:
+            self._ledger.log(result)
+        except Exception:
+            pass  # metering must never break the actual call
+        return result
+
+    def embed(self, texts: list[str]) -> list[list[float]]:
+        vectors = self._inner.embed(texts)
+        try:
+            # Embedding APIs rarely report usage; estimate with chars/4 and
+            # label it estimated so the ledger stays honest.
+            est_tokens = max(1, sum(len(t) for t in texts) // 4)
+            self._ledger.log(
+                CompletionResult(
+                    text="",
+                    input_tokens=est_tokens,
+                    output_tokens=0,
+                    provider=self._inner.name,
+                    model=getattr(self._inner, "embed_model", "embedding"),
+                    tokens_estimated=True,
+                )
+            )
+        except Exception:
+            pass
+        return vectors
+
+    def __getattr__(self, item):
+        return getattr(object.__getattribute__(self, "_inner"), item)
+
+    def __setattr__(self, key, value):
+        # Forward attribute writes (e.g. wait_callback) to the real provider.
+        setattr(object.__getattribute__(self, "_inner"), key, value)

receipts/llm/ollama_provider.py

@@ -0,0 +1,117 @@
+"""PRIMARY provider — local Ollama. Free, private, no API key needed.
+
+API facts verified against the installed ollama 0.6.2 package:
+``chat()`` returns a ``ChatResponse`` whose ``prompt_eval_count`` /
+``eval_count`` are Optional and can be omitted (e.g. fully cached prompts),
+an unreachable daemon raises the built-in ``ConnectionError`` on non-streaming
+calls, and a missing model raises ``ollama.ResponseError`` with
+``status_code == 404``.
+"""
+
+from __future__ import annotations
+
+import httpx
+import ollama
+
+from receipts.errors import ProviderConfigError, ProviderUnavailableError
+from receipts.llm.provider import CompletionResult, LLMProvider
+from receipts.llm.token_estimate import estimate_tokens
+
+_UNREACHABLE_HELP = """\
+Could not reach Ollama at {host}.
+  - If Ollama isn't running, start it (open the Ollama app or run `ollama serve`).
+  - If it runs on a different address, set OLLAMA_HOST to the right URL.
+  - Or switch provider: set RECEIPTS_PROVIDER=gemini and
+    GEMINI_API_KEY=<your free key>."""
+
+_MISSING_MODEL_HELP = """\
+Ollama model '{model}' is not available locally.
+  Pull it first:  ollama pull {model}
+  Or point {env_var} at a model you already have (see `ollama list`)."""
+
+
+class OllamaProvider(LLMProvider):
+    name = "ollama"
+
+    def __init__(self, *, host: str, chat_model: str, embed_model: str) -> None:
+        self.host = host
+        self.chat_model = chat_model
+        self.embed_model = embed_model
+        self._client = ollama.Client(host=host)
+
+    def check_available(self) -> None:
+        """Cheap reachability probe; raises a friendly error if the daemon is down."""
+        try:
+            self._client.list()
+        except (ConnectionError, httpx.ConnectError) as exc:
+            raise ProviderUnavailableError(
+                _UNREACHABLE_HELP.format(host=self.host)
+            ) from exc
+
+    def complete(
+        self, system: str, user: str, *, json_mode: bool = False
+    ) -> CompletionResult:
+        messages = [
+            {"role": "system", "content": system},
+            {"role": "user", "content": user},
+        ]
+        try:
+            response = self._client.chat(
+                model=self.chat_model,
+                messages=messages,
+                format="json" if json_mode else None,
+            )
+        except (ConnectionError, httpx.ConnectError) as exc:
+            raise ProviderUnavailableError(
+                _UNREACHABLE_HELP.format(host=self.host)
+            ) from exc
+        except ollama.ResponseError as exc:
+            raise self._translate_response_error(
+                exc, model=self.chat_model, env_var="OLLAMA_CHAT_MODEL"
+            ) from exc
+
+        text = response.message.content or ""
+        input_tokens = response.prompt_eval_count
+        output_tokens = response.eval_count
+        # Ollama doesn't reliably report token counts; when either side is
+        # missing we estimate locally and label the result as an estimate.
+        estimated = input_tokens is None or output_tokens is None
+        if input_tokens is None:
+            input_tokens = estimate_tokens(system) + estimate_tokens(user)
+        if output_tokens is None:
+            output_tokens = estimate_tokens(text)
+        return CompletionResult(
+            text=text,
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            provider=self.name,
+            model=self.chat_model,
+            tokens_estimated=estimated,
+        )
+
+    def embed(self, texts: list[str]) -> list[list[float]]:
+        if not texts:
+            return []
+        try:
+            response = self._client.embed(model=self.embed_model, input=list(texts))
+        except (ConnectionError, httpx.ConnectError) as exc:
+            raise ProviderUnavailableError(
+                _UNREACHABLE_HELP.format(host=self.host)
+            ) from exc
+        except ollama.ResponseError as exc:
+            raise self._translate_response_error(
+                exc, model=self.embed_model, env_var="OLLAMA_EMBED_MODEL"
+            ) from exc
+        return [list(vector) for vector in response.embeddings]
+
+    @staticmethod
+    def _translate_response_error(
+        exc: ollama.ResponseError, *, model: str, env_var: str
+    ) -> Exception:
+        if exc.status_code == 404:
+            return ProviderConfigError(
+                _MISSING_MODEL_HELP.format(model=model, env_var=env_var)
+            )
+        return ProviderUnavailableError(
+            f"Ollama returned an error (status {exc.status_code}): {exc.error}"
+        )

receipts/llm/openai_provider.py

@@ -0,0 +1,118 @@
+"""OpenAI provider — BYOK adapter for end users with their own API key.
+
+Not used in the maintainer's own testing (no paid key). Exists so end users
+who prefer GPT can ``pip install codebase-receipts-cli[openai]`` and set
+``RECEIPTS_PROVIDER=openai`` with their own key.
+
+API facts verified against the installed openai 2.44.0 package:
+``client.chat.completions.create`` takes ``model``, ``messages`` (list of
+dicts with role/content), ``response_format``. Response has ``.choices[0]
+.message.content``, ``.usage`` with ``prompt_tokens`` / ``completion_tokens``.
+``client.embeddings.create`` takes ``model``, ``input`` (list of strings).
+Response has ``.data[i].embedding``.
+Errors: ``AuthenticationError``, ``RateLimitError``, ``NotFoundError``.
+"""
+
+from __future__ import annotations
+
+import openai
+
+from receipts.errors import ProviderConfigError, ProviderUnavailableError
+from receipts.llm.provider import CompletionResult, LLMProvider
+
+_MISSING_KEY_HELP = """\
+No OpenAI API key configured.
+  Set OPENAI_API_KEY=<your key> in your environment or local .env file.
+  This is a paid API — see https://platform.openai.com/ for pricing."""
+
+_BAD_KEY_HELP = """\
+OpenAI rejected your API key.
+  Check that OPENAI_API_KEY is set to a valid key from
+  https://platform.openai.com/ (no quotes, no extra spaces)."""
+
+_DEFAULT_CHAT_MODEL = "gpt-4o-mini"
+_DEFAULT_EMBED_MODEL = "text-embedding-3-small"
+
+
+class OpenAIProvider(LLMProvider):
+    name = "openai"
+
+    def __init__(
+        self,
+        *,
+        api_key: str | None,
+        chat_model: str = _DEFAULT_CHAT_MODEL,
+        embed_model: str = _DEFAULT_EMBED_MODEL,
+        base_url: str | None = None,
+    ) -> None:
+        if not api_key:
+            raise ProviderConfigError(_MISSING_KEY_HELP)
+        self.chat_model = chat_model
+        self.embed_model = embed_model
+        self.base_url = base_url
+        # base_url points at any OpenAI-compatible endpoint (Groq,
+        # OpenRouter, a local server). None = the official OpenAI API.
+        if base_url:
+            self._client = openai.OpenAI(api_key=api_key, base_url=base_url)
+        else:
+            self._client = openai.OpenAI(api_key=api_key)
+
+    def complete(
+        self, system: str, user: str, *, json_mode: bool = False
+    ) -> CompletionResult:
+        messages = [
+            {"role": "system", "content": system},
+            {"role": "user", "content": user},
+        ]
+        kwargs: dict = {"model": self.chat_model, "messages": messages}
+        if json_mode:
+            kwargs["response_format"] = {"type": "json_object"}
+
+        try:
+            response = self._client.chat.completions.create(**kwargs)
+        except openai.AuthenticationError as exc:
+            raise ProviderConfigError(_BAD_KEY_HELP) from exc
+        except openai.RateLimitError as exc:
+            raise ProviderUnavailableError(
+                "OpenAI rate limit hit. Wait and retry, or switch to a"
+                " local provider: set RECEIPTS_PROVIDER=ollama."
+            ) from exc
+        except openai.NotFoundError as exc:
+            raise ProviderConfigError(
+                f"OpenAI model '{self.chat_model}' was not found."
+                " Set OPENAI_CHAT_MODEL to a valid model id"
+                " (see https://platform.openai.com/docs/models)."
+            ) from exc
+        except openai.APIError as exc:
+            raise ProviderUnavailableError(f"OpenAI API error: {exc.message}") from exc
+
+        choice = response.choices[0] if response.choices else None
+        text = (choice.message.content or "") if choice else ""
+
+        usage = response.usage
+        input_tokens = usage.prompt_tokens if usage else 0
+        output_tokens = usage.completion_tokens if usage else 0
+
+        return CompletionResult(
+            text=text,
+            input_tokens=input_tokens,
+            output_tokens=output_tokens,
+            provider=self.name,
+            model=self.chat_model,
+            tokens_estimated=usage is None,
+        )
+
+    def embed(self, texts: list[str]) -> list[list[float]]:
+        if not texts:
+            return []
+        try:
+            response = self._client.embeddings.create(
+                model=self.embed_model, input=list(texts)
+            )
+        except openai.AuthenticationError as exc:
+            raise ProviderConfigError(_BAD_KEY_HELP) from exc
+        except openai.APIError as exc:
+            raise ProviderUnavailableError(f"OpenAI API error: {exc.message}") from exc
+
+        sorted_data = sorted(response.data, key=lambda e: e.index)
+        return [list(e.embedding) for e in sorted_data]

receipts/llm/provider.py

@@ -0,0 +1,42 @@
+"""Abstract LLM provider interface.
+
+Every concrete provider (Ollama, Gemini, Anthropic, OpenAI) implements this
+interface. Tool code only ever talks to ``LLMProvider`` and gets instances
+from :mod:`receipts.llm.factory` — never by importing a concrete provider
+directly.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class CompletionResult:
+    """A completed LLM call plus the usage numbers the ledger needs."""
+
+    text: str
+    input_tokens: int
+    output_tokens: int
+    provider: str
+    model: str
+    tokens_estimated: bool = False
+    """True when token counts were estimated locally (e.g. via tiktoken for
+    Ollama) rather than reported by the provider."""
+
+
+class LLMProvider(ABC):
+    """Interface every LLM backend implements."""
+
+    name: str
+
+    @abstractmethod
+    def complete(
+        self, system: str, user: str, *, json_mode: bool = False
+    ) -> CompletionResult:
+        """Return response text plus token usage (input/output) for the ledger."""
+
+    @abstractmethod
+    def embed(self, texts: list[str]) -> list[list[float]]:
+        """Return one embedding vector per input text, in order."""

receipts/llm/split.py

@@ -0,0 +1,78 @@
+"""Split provider — chat via one provider, embeddings via another.
+
+Exists for one big reason: Anthropic has no embeddings API, so Claude
+alone cannot run the verification pipeline (KB search embeds the query
+at verify time). With a split, chat goes to the configured provider and
+embeddings go to ``RECEIPTS_EMBED_PROVIDER``:
+
+    RECEIPTS_PROVIDER=anthropic
+    RECEIPTS_EMBED_PROVIDER=gemini
+
+The embed provider MUST match whatever embedded the knowledge base —
+vectors from different models are not comparable.
+"""
+
+from __future__ import annotations
+
+from receipts.llm.provider import CompletionResult, LLMProvider
+
+_OWN_ATTRS = {"_chat", "_embed"}
+
+
+class SplitProvider(LLMProvider):
+    """Composite provider: ``complete`` and ``embed`` go to different backends."""
+
+    def __init__(self, chat: LLMProvider, embed: LLMProvider) -> None:
+        object.__setattr__(self, "_chat", chat)
+        object.__setattr__(self, "_embed", embed)
+
+    @property
+    def name(self) -> str:
+        # The chat provider's name drives downstream behavior (e.g. the
+        # batching heuristic cares about the model answering prompts).
+        return self._chat.name
+
+    @property
+    def embed_provider_name(self) -> str:
+        return self._embed.name
+
+    @property
+    def chat_model(self) -> str | None:
+        return getattr(self._chat, "chat_model", None)
+
+    @property
+    def embed_model(self) -> str | None:
+        return getattr(self._embed, "embed_model", None)
+
+    def complete(
+        self, system: str, user: str, *, json_mode: bool = False
+    ) -> CompletionResult:
+        return self._chat.complete(system, user, json_mode=json_mode)
+
+    def embed(self, texts: list[str]) -> list[list[float]]:
+        return self._embed.embed(texts)
+
+    def check_available(self) -> None:
+        """Validate the chat backend up front when it supports probing."""
+        check = getattr(self._chat, "check_available", None)
+        if callable(check):
+            check()
+
+    def __getattr__(self, item):
+        chat = object.__getattribute__(self, "_chat")
+        try:
+            return getattr(chat, item)
+        except AttributeError:
+            return getattr(object.__getattribute__(self, "_embed"), item)
+
+    def __setattr__(self, key, value):
+        # Forward attribute writes (e.g. wait_callback) to whichever inner
+        # providers understand them, so retry-wait notifications still work.
+        forwarded = False
+        for inner_name in ("_chat", "_embed"):
+            inner = object.__getattribute__(self, inner_name)
+            if hasattr(inner, key):
+                setattr(inner, key, value)
+                forwarded = True
+        if not forwarded:
+            object.__setattr__(self, key, value)