gmail-llm-cleanup 1.1.2__py3-none-any.whl

gmail_cleanup/__init__.py

@@ -0,0 +1,2 @@
+"""gmail-cleanup-agent — LLM-driven Gmail triage."""
+__version__ = "0.1.0"

gmail_cleanup/__main__.py

@@ -0,0 +1,72 @@
+"""Entry point for `python -m gmail_cleanup ...` and the
+`gmail-cleanup` console script.
+
+Before dispatching to the Click CLI, we load runtime configuration from
+`config/backend.env` (if present). This is the preferred way to set the
+backend env vars (GCA_BACKEND, OLLAMA_*, OPENAI_*, CLAUDE_*, ANTHROPIC_*)
+without having to re-export them in every shell session.
+
+Precedence (highest wins):
+  1. Variables already exported in the current shell (or set inline:
+     `OPENAI_MODEL=foo python -m gmail_cleanup ...`).
+  2. Values in `config/backend.env`.
+  3. Defaults baked into each backend.
+
+Shell-exported values winning is intentional: it lets you keep a
+known-good `config/backend.env` checked in (locally) while doing
+one-off runs with overrides.
+
+`config/backend.env.example` is the template; copy it to
+`config/backend.env` and fill in the values for whichever backend you
+want to use.
+"""
+
+import os
+from pathlib import Path
+
+from dotenv import load_dotenv
+
+
+def _resolve_backend_env_path() -> Path:
+    """Where to look for the optional `backend.env` dotenv file.
+
+    Order (highest precedence first):
+      1. $GMAIL_CLEANUP_CONFIG_DIR/backend.env (explicit override; Docker uses this)
+      2. ./config/backend.env in the current working directory
+      3. <package-root>/config/backend.env — only meaningful for editable
+         installs (`pip install -e .`); harmless on wheel installs since
+         load_dotenv silently no-ops on missing files.
+    """
+    env = os.environ.get("GMAIL_CLEANUP_CONFIG_DIR")
+    if env:
+        return Path(env).expanduser() / "backend.env"
+    cwd_path = Path.cwd() / "config" / "backend.env"
+    if cwd_path.is_file():
+        return cwd_path
+    # Editable-install fallback: __file__ -> src/gmail_cleanup/__main__.py;
+    # parents[2] is the repo root next to its config/ dir.
+    return Path(__file__).resolve().parents[2] / "config" / "backend.env"
+
+
+def main():
+    """Console-script entry point used by both `python -m gmail_cleanup`
+    and the installed `gmail-cleanup` command. Loads backend.env, runs
+    the optional pre-run hook, then dispatches to the Click CLI."""
+    load_dotenv(_resolve_backend_env_path(), override=False)
+
+    # Import AFTER load_dotenv so the backend factory sees the loaded env
+    # vars when it inspects os.environ.
+    from .cli import main as cli_main
+    from .portforward import maybe_start_pre_run
+
+    # Optional: if PRE_RUN_COMMAND is configured (e.g., a kubectl
+    # port-forward to reach an in-cluster Ollama / llama.cpp), launch it
+    # in the background and wait for the port to open before main()
+    # runs. Cleanup happens via an atexit hook.
+    maybe_start_pre_run()
+
+    cli_main()
+
+
+if __name__ == "__main__":
+    main()

gmail_cleanup/applylog.py

@@ -0,0 +1,274 @@
+"""Replay decision-log entries to Gmail without re-classifying.
+
+Reads a decision log (e.g. dry-run.log), keeps the latest decision per
+thread ID, and replays each one via Gmail's batch HTTP endpoint:
+
+  - action="trash"            -> users().threads().trash(...)
+  - action="keep", label=X    -> users().threads().modify(addLabelIds=[X])
+  - action="keep", label=None -> no Gmail call (already kept)
+  - action="error"            -> skipped (never applied)
+
+Single-threaded — the existing GmailClient is not thread-safe (see
+cli._apply_decisions), and concurrent use can segfault httplib2.
+
+Resumable: applied IDs are checkpointed to a state file after each
+batch. Re-runs skip already-applied IDs. Two audit logs:
+  --dry-run -> replay-preview.log
+  --apply   -> applied.log
+
+429s from Gmail's per-user concurrent limit are retried per batch with
+exponential backoff; persistent failures fall through as errors.
+"""
+
+from __future__ import annotations
+
+import datetime as _dt
+import json
+import logging
+import time
+from collections import Counter
+from pathlib import Path
+
+from .gmail_client import GmailClient
+
+logger = logging.getLogger("gmail_cleanup.applylog")
+
+BATCH_SIZE = 20  # Sub-requests per batch. Gmail's batch endpoint accepts up
+                 # to 100 but per-user concurrent ceiling is ~20; larger
+                 # batches add 429s without improving the ~3.3 ops/sec ceiling.
+MAX_429_RETRIES = 5
+
+
+def load_latest_decisions(log_path: Path) -> dict[str, dict]:
+    """For each thread ID, return the LATEST decision record from the log."""
+    latest: dict[str, dict] = {}
+    with log_path.open() as fh:
+        for line in fh:
+            line = line.strip()
+            if not line.startswith('{"id":'):
+                continue
+            try:
+                r = json.loads(line)
+            except json.JSONDecodeError:
+                continue
+            latest[r["id"]] = r
+    return latest
+
+
+def _execute_with_retry(service, items, label_ids, audit_fh, counters,
+                        decisions_by_id, batch_idx):
+    """Execute a batch of trash/modify requests with 429-retry. Returns the
+    set of IDs that completed successfully. Persistent 429s after
+    MAX_429_RETRIES are logged as errors."""
+    successful: set[str] = set()
+    pending = list(items)
+    for attempt in range(MAX_429_RETRIES + 1):
+        if not pending:
+            break
+        retry: list[dict] = []
+
+        def cb(request_id, response, exception, _retry=retry):
+            if exception is None:
+                successful.add(request_id)
+                d = decisions_by_id[request_id]
+                if d["action"] == "trash":
+                    counters["trash"] += 1
+                    result = "trash"
+                else:
+                    counters["keep_labeled"] += 1
+                    result = "keep_labeled"
+                audit_fh.write(json.dumps({
+                    "id": request_id, "result": result,
+                    "label": d.get("label")}) + "\n")
+                return
+            err = str(exception)
+            if "429" in err or "rate" in err.lower() or "concurrent" in err.lower():
+                _retry.append(decisions_by_id[request_id])
+            else:
+                counters["error"] += 1
+                audit_fh.write(json.dumps({
+                    "id": request_id, "result": "error",
+                    "err": err[:200]}) + "\n")
+
+        batch = service.new_batch_http_request(callback=cb)
+        for d in pending:
+            tid = d["id"]
+            if d["action"] == "trash":
+                req = service.users().threads().trash(userId="me", id=tid)
+            else:
+                req = service.users().threads().modify(
+                    userId="me", id=tid,
+                    body={"addLabelIds": [label_ids[d["label"]]]})
+            batch.add(req, request_id=tid)
+        try:
+            batch.execute()
+        except Exception as e:  # noqa: BLE001
+            logger.error("batch %d transport failed on attempt %d: %s",
+                         batch_idx, attempt + 1, e)
+            retry = pending[:]
+
+        if retry:
+            sleep_for = 1.5 * (2 ** attempt)  # 1.5, 3, 6, 12, 24, 48
+            logger.warning("  batch %d: %d items hit 429 on attempt %d, "
+                           "backing off %.1fs", batch_idx, len(retry),
+                           attempt + 1, sleep_for)
+            time.sleep(sleep_for)
+        pending = retry
+
+    for d in pending:
+        counters["error"] += 1
+        audit_fh.write(json.dumps({
+            "id": d["id"], "result": "error",
+            "err": f"429 after {MAX_429_RETRIES} retries"}) + "\n")
+    return successful
+
+
+def run_apply_log(
+    *,
+    log_file: Path,
+    state_file: Path,
+    apply: bool,
+    limit: int | None,
+    batch_size: int,
+    batch_sleep: float,
+    credentials: Path,
+    token: Path,
+    audit_log: Path,
+) -> None:
+    """Replay decisions from `log_file` to Gmail.
+
+    `audit_log` receives one JSON record per replayed decision;
+    `state_file` tracks applied IDs across runs so an interrupted
+    apply can resume cleanly.
+    """
+    mode = "APPLY (mutating Gmail)" if apply else "dry-run (no mutations)"
+    logger.info("mode: %s", mode)
+    logger.info("log file: %s", log_file)
+    logger.info("audit log: %s", audit_log)
+
+    logger.info("loading decisions...")
+    decisions = load_latest_decisions(log_file)
+    actions = Counter(d["action"] for d in decisions.values())
+    logger.info("loaded %d unique thread decisions: %s",
+                len(decisions), dict(actions))
+
+    applied_ids: set[str] = set()
+    if state_file.exists():
+        try:
+            applied_ids = set(json.loads(state_file.read_text()).get("applied", []))
+            logger.info("resume: %d already applied per %s",
+                        len(applied_ids), state_file.name)
+        except Exception as e:  # noqa: BLE001
+            logger.warning("could not read %s; starting fresh: %s", state_file, e)
+
+    pending = [
+        d for tid, d in decisions.items()
+        if tid not in applied_ids and d["action"] in ("trash", "keep")
+    ]
+    if limit is not None:
+        pending = pending[:limit]
+    logger.info("pending actions: %d (after resume + --limit)", len(pending))
+
+    if not pending:
+        logger.info("nothing to do; exiting")
+        return
+
+    client = GmailClient(credentials, token)
+    client.authorize()
+    service = client._service  # noqa: SLF001
+    label_ids: dict[str, str] = client.list_labels()
+
+    needed_labels = {
+        d.get("label") for d in pending
+        if d["action"] == "keep" and d.get("label")
+    }
+    missing = sorted(needed_labels - set(label_ids.keys()))
+    if missing:
+        if apply:
+            for name in missing:
+                logger.info("creating label %r", name)
+                label_ids[name] = client.create_label(name)
+        else:
+            for name in missing:
+                label_ids[name] = f"<would-create:{name}>"
+            logger.info("[dry-run] would create %d new label(s): %s",
+                        len(missing), missing)
+
+    audit_fh = audit_log.open("a")
+    audit_fh.write(
+        f"\n=== {_dt.datetime.now(_dt.timezone.utc).isoformat()} "
+        f"apply-log starting (apply={apply}, limit={limit}) ===\n")
+    audit_fh.flush()
+
+    counters: Counter[str] = Counter()
+    start = time.time()
+    decisions_by_id = {d["id"]: d for d in pending}
+
+    chunks = [pending[i:i + batch_size] for i in range(0, len(pending), batch_size)]
+    total = len(pending)
+
+    try:
+        for batch_idx, chunk in enumerate(chunks, 1):
+            to_apply: list[dict] = []
+            for d in chunk:
+                tid = d["id"]
+                action = d["action"]
+                label = d.get("label")
+                if action == "keep" and not label:
+                    counters["keep_nolabel"] += 1
+                    audit_fh.write(json.dumps(
+                        {"id": tid, "result": "keep_nolabel", "label": None}) + "\n")
+                    if apply:
+                        applied_ids.add(tid)
+                    continue
+                if not apply:
+                    if action == "trash":
+                        counters["trash"] += 1
+                        audit_fh.write(json.dumps(
+                            {"id": tid, "result": "trash", "label": None}) + "\n")
+                    else:
+                        counters["keep_labeled"] += 1
+                        audit_fh.write(json.dumps(
+                            {"id": tid, "result": "keep_labeled", "label": label}) + "\n")
+                    continue
+                if action == "keep" and label and not label_ids.get(label):
+                    counters["error"] += 1
+                    audit_fh.write(json.dumps(
+                        {"id": tid, "result": "error",
+                         "err": f"label {label!r} not resolved"}) + "\n")
+                    continue
+                to_apply.append(d)
+
+            if to_apply:
+                successful = _execute_with_retry(
+                    service, to_apply, label_ids, audit_fh, counters,
+                    decisions_by_id, batch_idx)
+                if apply:
+                    applied_ids.update(successful)
+
+            audit_fh.flush()
+            if apply:
+                state_file.write_text(json.dumps({"applied": sorted(applied_ids)}))
+
+            done = min(batch_idx * batch_size, total)
+            elapsed = time.time() - start
+            rate = done / elapsed if elapsed > 0 else 0
+            eta_min = int((total - done) / rate / 60) if rate > 0 else 0
+            if batch_idx % 5 == 0 or batch_idx == len(chunks):
+                logger.info(
+                    "batch %d/%d (%d/%d, %.1f%%) | %.1f ops/sec | ETA %d min | %s",
+                    batch_idx, len(chunks), done, total,
+                    100 * done / total, rate, eta_min, dict(counters))
+
+            if apply and batch_idx < len(chunks):
+                time.sleep(batch_sleep)
+    finally:
+        audit_fh.flush()
+        audit_fh.close()
+        if apply:
+            state_file.write_text(json.dumps({"applied": sorted(applied_ids)}))
+
+    elapsed = time.time() - start
+    logger.info("DONE in %.1f min (%.1f ops/sec). mode=%s counters=%s",
+                elapsed / 60, total / elapsed if elapsed else 0,
+                mode, dict(counters))

gmail_cleanup/backends/__init__.py

@@ -0,0 +1,18 @@
+"""LLM backends — pluggable via GCA_BACKEND env var."""
+
+import os
+
+from .ollama import OllamaBackend
+
+
+def get_backend():
+    name = os.environ.get("GCA_BACKEND", "ollama").lower()
+    if name == "ollama":
+        return OllamaBackend()
+    if name == "claude":
+        from .claude import ClaudeBackend
+        return ClaudeBackend()
+    if name == "openai":
+        from .openai import OpenAIBackend
+        return OpenAIBackend()
+    raise ValueError(f"Unknown GCA_BACKEND: {name!r}")

gmail_cleanup/backends/claude.py

@@ -0,0 +1,39 @@
+"""Claude API backend. Uses the Anthropic SDK; requires ANTHROPIC_API_KEY."""
+
+from __future__ import annotations
+
+import os
+
+
+class ClaudeBackend:
+    """Claude backend. Configure via env:
+      ANTHROPIC_API_KEY   required
+      CLAUDE_MODEL        default claude-haiku-4-5-20251001
+      CLAUDE_MAX_TOKENS   default 4000
+    """
+
+    def __init__(self):
+        try:
+            import anthropic
+        except ImportError as e:
+            raise ImportError(
+                "Install anthropic: `pip install anthropic`"
+            ) from e
+        api_key = os.environ.get("ANTHROPIC_API_KEY")
+        if not api_key:
+            raise RuntimeError("ANTHROPIC_API_KEY is not set")
+        self.client = anthropic.Anthropic(api_key=api_key)
+        self.model = os.environ.get("CLAUDE_MODEL", "claude-haiku-4-5-20251001")
+        self.max_tokens = int(os.environ.get("CLAUDE_MAX_TOKENS", "4000"))
+
+    def classify_batch(self, prompt: str) -> str:
+        msg = self.client.messages.create(
+            model=self.model,
+            max_tokens=self.max_tokens,
+            messages=[{"role": "user", "content": prompt}],
+        )
+        # Concatenate all text blocks (Haiku usually returns one)
+        return "".join(b.text for b in msg.content if hasattr(b, "text"))
+
+    def __repr__(self):
+        return f"ClaudeBackend(model={self.model})"

gmail_cleanup/backends/ollama.py

@@ -0,0 +1,114 @@
+"""Ollama backend. Calls /api/chat with `format: json` so the model is
+constrained to emit JSON output."""
+
+from __future__ import annotations
+
+import logging
+import os
+import time
+
+import httpx
+
+
+logger = logging.getLogger(__name__)
+
+
+# Errors worth retrying — transient network issues from `kubectl port-forward`
+# dying mid-stream, or from intermittent server-side hiccups. We do NOT
+# retry on HTTPStatusError (semantic errors should fail loud).
+_RETRYABLE_EXCEPTIONS = (
+    httpx.RemoteProtocolError,    # peer closed connection mid-response
+    httpx.ConnectError,            # couldn't establish connection
+    httpx.ReadError,               # read failed mid-stream
+    httpx.WriteError,              # write failed
+    httpx.ConnectTimeout,          # connect timeout
+    httpx.ReadTimeout,             # read timeout (rare for fast LLM)
+    OSError,                       # ECONNRESET, EPIPE etc. surface as OSError
+)
+
+
+class OllamaBackend:
+    """Ollama backend. Configure via env:
+      OLLAMA_HOST       default http://localhost:11434
+      OLLAMA_MODEL      default qwen3.6:35b-a3b-iq3_xxs-fixed
+      OLLAMA_NUM_CTX    default 8192
+      OLLAMA_KEEP_ALIVE default 60m (keep model warm between batches)
+      OLLAMA_TIMEOUT    default 300 (per-call read timeout, seconds)
+      OLLAMA_RETRIES    default 5  (transient retries on connection errors)
+    """
+
+    def __init__(self):
+        self.host = os.environ.get("OLLAMA_HOST", "http://localhost:11434").rstrip("/")
+        self.model = os.environ.get("OLLAMA_MODEL", "qwen3.6:35b-a3b-iq3_xxs-fixed")
+        self.num_ctx = int(os.environ.get("OLLAMA_NUM_CTX", "8192"))
+        self.keep_alive = os.environ.get("OLLAMA_KEEP_ALIVE", "60m")
+        self.timeout = float(os.environ.get("OLLAMA_TIMEOUT", "300"))
+        self.retries = int(os.environ.get("OLLAMA_RETRIES", "5"))
+        # Single httpx client reused across calls — keepalive saves the
+        # TCP+TLS handshake, and means a `kubectl port-forward` blip
+        # surfaces as a single retryable error rather than a slow stream
+        # of fresh-connection failures.
+        self._client = httpx.Client(timeout=self.timeout, http2=False)
+
+    def classify_batch(self, prompt: str) -> str:
+        """Send the prompt to Ollama, return the raw `message.content`
+        string. Retries up to OLLAMA_RETRIES times on transient network
+        errors (connection reset, timeout, peer closed)."""
+        body = {
+            "model": self.model,
+            "stream": False,
+            "format": "json",
+            "keep_alive": self.keep_alive,
+            "messages": [{"role": "user", "content": prompt}],
+            "options": {
+                "temperature": 0.1,
+                "num_ctx": self.num_ctx,
+            },
+        }
+        last_exc: Exception | None = None
+        for attempt in range(self.retries + 1):
+            try:
+                r = self._client.post(f"{self.host}/api/chat", json=body)
+                r.raise_for_status()
+                data = r.json()
+                return data.get("message", {}).get("content", "")
+            except _RETRYABLE_EXCEPTIONS as e:
+                last_exc = e
+                if attempt < self.retries:
+                    # Exponential backoff with a small floor + ceiling so
+                    # a flapping port-forward doesn't get retried for hours.
+                    delay = min(2 ** attempt, 30)
+                    logger.warning(
+                        "ollama transient error (%s: %s) — retrying in %ds (attempt %d/%d)",
+                        type(e).__name__, e, delay, attempt + 1, self.retries
+                    )
+                    # Do NOT close/recreate the shared client here. It is
+                    # shared across all concurrent classify_batch() workers;
+                    # closing it from one task makes sibling tasks raise
+                    # RuntimeError("Cannot send a request, as the client has
+                    # been closed.") on their in-flight .post() calls.
+                    # RuntimeError isn't retryable, so each sibling fails out
+                    # as a "backend error" instead of retrying its own
+                    # transient. httpx.Client is documented thread-safe and
+                    # its connection pool prunes failed connections on its
+                    # own, so the sleep-and-retry alone is sufficient.
+                    time.sleep(delay)
+                    continue
+                break
+        # Out of retries — surface to caller with the original exception
+        raise RuntimeError(
+            f"ollama call failed after {self.retries + 1} attempts: "
+            f"{type(last_exc).__name__}: {last_exc}"
+        ) from last_exc
+
+    def close(self):
+        try:
+            self._client.close()
+        except Exception:
+            pass
+
+    def __del__(self):
+        self.close()
+
+    def __repr__(self):
+        return f"OllamaBackend(model={self.model}, host={self.host})"

gmail_cleanup/backends/openai.py

@@ -0,0 +1,129 @@
+"""OpenAI-compatible backend. Works with:
+
+  - real OpenAI (api.openai.com)
+  - LM Studio (http://localhost:1234/v1)
+  - llama.cpp server (http://localhost:8080/v1)
+  - vLLM, Ollama's /v1 OpenAI shim, and anything else that speaks the
+    OpenAI Chat Completions wire format.
+
+Selected via GCA_BACKEND=openai. Configure via env:
+  OPENAI_API_KEY      required for real OpenAI. For LM Studio / llama.cpp /
+                      vLLM any non-empty placeholder is fine ("not-needed").
+  OPENAI_BASE_URL     default https://api.openai.com/v1. Point at your
+                      local server (e.g. http://localhost:1234/v1) for
+                      LM Studio.
+  OPENAI_MODEL        default gpt-4o-mini. For local servers, the exact
+                      model name they advertise (LM Studio shows it in
+                      the Server tab; llama.cpp uses the file name).
+  OPENAI_MAX_TOKENS   default 4000
+  OPENAI_TEMPERATURE  default 0.1
+  OPENAI_JSON_MODE    default "1" — sends `response_format: json_object`.
+                      Set to "0" if your local server doesn't support it
+                      (older llama.cpp builds, some vLLM configs).
+  OPENAI_DISABLE_THINKING default "0" — set to "1" when running against a
+                      reasoning / thinking model (Qwen3, DeepSeek-R1, ...)
+                      on llama.cpp. Adds
+                      `extra_body.chat_template_kwargs.enable_thinking=false`
+                      to each request so the model emits its answer directly
+                      in `content` instead of burning the entire token
+                      budget on `reasoning_content` chain-of-thought.
+                      Real OpenAI ignores unknown extras; some other
+                      OpenAI-compatible servers (vLLM, older LM Studio
+                      builds) may reject them.
+                      See docs/llama-server-setup.md for details.
+  OPENAI_RETRIES      default 5 — retry transient connection / rate-limit
+                      errors with exponential backoff (1, 2, 4, 8, 16 s).
+"""
+
+from __future__ import annotations
+
+import logging
+import os
+import time
+
+
+logger = logging.getLogger(__name__)
+
+
+class OpenAIBackend:
+    def __init__(self):
+        try:
+            from openai import OpenAI
+        except ImportError as e:
+            raise ImportError(
+                "Install the OpenAI SDK: `pip install openai`"
+            ) from e
+        api_key = os.environ.get("OPENAI_API_KEY") or "not-needed"
+        base_url = os.environ.get("OPENAI_BASE_URL", "https://api.openai.com/v1")
+        # max_retries=0 — let our explicit retry loop below own the
+        # retry semantics so the logged attempt count is meaningful and
+        # the user-tunable OPENAI_RETRIES is actually authoritative.
+        self.client = OpenAI(api_key=api_key, base_url=base_url, max_retries=0)
+        self.model = os.environ.get("OPENAI_MODEL", "gpt-4o-mini")
+        self.max_tokens = int(os.environ.get("OPENAI_MAX_TOKENS", "4000"))
+        self.temperature = float(os.environ.get("OPENAI_TEMPERATURE", "0.1"))
+        self.json_mode = os.environ.get("OPENAI_JSON_MODE", "1") not in ("0", "false", "no")
+        self.retries = int(os.environ.get("OPENAI_RETRIES", "5"))
+        self.base_url = base_url
+
+    def _is_retryable(self, exc: Exception) -> bool:
+        """Connection-level or rate-limit errors that are worth retrying.
+        Semantic errors (bad request, unsupported model, auth) are NOT
+        retried — they'll just keep failing and we want to fail loud."""
+        # Import lazily so the module can be imported without the openai
+        # SDK installed (the constructor would have failed first anyway).
+        from openai import APIConnectionError, APITimeoutError, RateLimitError, InternalServerError
+        return isinstance(exc, (
+            APIConnectionError,
+            APITimeoutError,
+            RateLimitError,
+            InternalServerError,
+        ))
+
+    def classify_batch(self, prompt: str) -> str:
+        kwargs = dict(
+            model=self.model,
+            messages=[{"role": "user", "content": prompt}],
+            max_tokens=self.max_tokens,
+            temperature=self.temperature,
+        )
+        if self.json_mode:
+            kwargs["response_format"] = {"type": "json_object"}
+
+        # Reasoning/thinking-mode models (Qwen3, DeepSeek-R1, etc.) on
+        # llama.cpp servers split output between `reasoning_content`
+        # (chain-of-thought) and `content` (final answer). When the model
+        # spends its entire token budget on reasoning, `content` is empty
+        # and the classifier sees "0 decisions returned." Send
+        # `chat_template_kwargs.enable_thinking=false` as an OpenAI-API
+        # extra body parameter to force the model straight to the answer.
+        # Opt-in via env (default off) — real OpenAI ignores unknown
+        # extras, but some other OpenAI-compatible servers (vLLM,
+        # LM Studio older builds) may reject them.
+        if os.environ.get("OPENAI_DISABLE_THINKING", "0") in ("1", "true", "yes"):
+            kwargs["extra_body"] = {
+                "chat_template_kwargs": {"enable_thinking": False}
+            }
+
+        last_exc: Exception | None = None
+        for attempt in range(self.retries + 1):
+            try:
+                resp = self.client.chat.completions.create(**kwargs)
+                return resp.choices[0].message.content or ""
+            except Exception as e:
+                if not self._is_retryable(e) or attempt >= self.retries:
+                    raise
+                last_exc = e
+                delay = min(2 ** attempt, 30)
+                logger.warning(
+                    "openai transient error (%s: %s) — retrying in %ds (attempt %d/%d)",
+                    type(e).__name__, e, delay, attempt + 1, self.retries
+                )
+                time.sleep(delay)
+        # Unreachable in practice — loop either returns or raises
+        raise RuntimeError(
+            f"openai call failed after {self.retries + 1} attempts"
+        ) from last_exc
+
+    def __repr__(self):
+        return f"OpenAIBackend(model={self.model}, base_url={self.base_url})"