sessionwiki 2.0.0__py3-none-any.whl

sessionwiki/synth/ollama.py

@@ -0,0 +1,379 @@
+"""Ollama backend for local LLM synthesis (v1.1.0 · #35).
+
+Provides ``OllamaSynthesizer``, a stdlib-only HTTP client for Ollama's
+``/api/generate`` endpoint. The dependency is **optional**: the default
+sessionwiki install stays on stdlib + ``markdown``, and this module only
+touches ``urllib`` (also stdlib), so there is nothing extra to install.
+
+Ollama must be running locally — by default at ``http://127.0.0.1:11434``.
+This keeps synthesis private by default (no data ever leaves the box).
+
+Design notes
+------------
+- **Privacy by default**: ``base_url`` defaults to 127.0.0.1. If the user
+  points the backend at a remote host we log a warning once so they
+  know they've left the local-only path.
+- **Graceful fallback**: ``is_available()`` probes ``/api/tags`` with a
+  short timeout. If the server is down ``synthesize_source_page()`` raises
+  ``OllamaUnavailableError``; the caller (``pipeline.synthesize_new_sessions``)
+  catches that, logs a warning, and skips the file without crashing the
+  sync.
+- **Retries**: transient 5xx or ``socket.timeout`` errors retry with
+  exponential backoff (default 3 attempts, 0.5/1.0/2.0s). Connection
+  refused errors short-circuit — the server is simply not running.
+- **No streaming**: we send ``stream: false`` because callers want the
+  complete synthesised page back, not a token stream. Streaming can land
+  later if a use case for it appears.
+
+Configuration (``sessions_config.json`` / ``config.json``)::
+
+    "synthesis": {
+      "backend": "ollama",
+      "model":  "llama3.1:8b",
+      "base_url": "http://127.0.0.1:11434",
+      "timeout": 60,
+      "max_retries": 3
+    }
+
+Config parsing is done in :func:`load_ollama_config` so the CLI can
+surface readable errors instead of stack traces.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import socket
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from typing import Any, Optional
+
+from sessionwiki.synth.base import BaseSynthesizer
+
+# ─── Constants ─────────────────────────────────────────────────────────
+
+DEFAULT_BASE_URL = "http://127.0.0.1:11434"
+DEFAULT_MODEL = "llama3.1:8b"
+DEFAULT_TIMEOUT = 60           # seconds, per HTTP call
+DEFAULT_MAX_RETRIES = 3        # includes the first attempt
+DEFAULT_BACKOFF_BASE = 0.5     # seconds; doubles each retry
+
+LOCAL_HOSTS = {"127.0.0.1", "localhost", "::1"}
+
+logger = logging.getLogger(__name__)
+
+
+# ─── Exceptions ────────────────────────────────────────────────────────
+
+
+class OllamaError(RuntimeError):
+    """Base class for Ollama backend failures."""
+
+
+class OllamaUnavailableError(OllamaError):
+    """Raised when the Ollama server is unreachable (connection refused,
+    DNS failure, or health check fails)."""
+
+
+class OllamaHTTPError(OllamaError):
+    """Raised when the server returns a non-2xx after exhausting retries."""
+
+    def __init__(self, status: int, body: str):
+        super().__init__(f"Ollama returned HTTP {status}: {body[:200]}")
+        self.status = status
+        self.body = body
+
+
+# ─── Config ────────────────────────────────────────────────────────────
+
+
+@dataclass(frozen=True)
+class OllamaConfig:
+    """Resolved configuration for :class:`OllamaSynthesizer`."""
+
+    model: str = DEFAULT_MODEL
+    base_url: str = DEFAULT_BASE_URL
+    timeout: int = DEFAULT_TIMEOUT
+    max_retries: int = DEFAULT_MAX_RETRIES
+    backoff_base: float = DEFAULT_BACKOFF_BASE
+
+    @property
+    def generate_url(self) -> str:
+        return f"{self.base_url.rstrip('/')}/api/generate"
+
+    @property
+    def tags_url(self) -> str:
+        return f"{self.base_url.rstrip('/')}/api/tags"
+
+    @property
+    def is_local(self) -> bool:
+        """True if base_url resolves to localhost (privacy check)."""
+        try:
+            host = urllib.parse.urlparse(self.base_url).hostname or ""
+        except ValueError:
+            return False
+        return host in LOCAL_HOSTS
+
+
+def load_ollama_config(cfg: Optional[dict[str, Any]]) -> OllamaConfig:
+    """Build an :class:`OllamaConfig` from the ``synthesis`` block of
+    ``sessions_config.json``.
+
+    Missing keys fall back to the module-level defaults so first-time
+    users don't have to configure anything to try it out::
+
+        { "synthesis": { "backend": "ollama" } }
+
+    is enough to reach a working local default.
+    """
+    synth = (cfg or {}).get("synthesis", {}) or {}
+    # Use `in` checks (not `or`) so an explicit 0 fails validation instead
+    # of being silently swapped for the default.
+    model = synth.get("model") or DEFAULT_MODEL
+    base_url = synth.get("base_url") or DEFAULT_BASE_URL
+    timeout = int(synth["timeout"]) if "timeout" in synth else DEFAULT_TIMEOUT
+    max_retries = (
+        int(synth["max_retries"]) if "max_retries" in synth else DEFAULT_MAX_RETRIES
+    )
+    backoff_base = (
+        float(synth["backoff_base"])
+        if "backoff_base" in synth
+        else DEFAULT_BACKOFF_BASE
+    )
+
+    if timeout <= 0:
+        raise ValueError(f"synthesis.timeout must be positive, got {timeout}")
+    if max_retries < 1:
+        raise ValueError(
+            f"synthesis.max_retries must be >= 1, got {max_retries}"
+        )
+
+    resolved = OllamaConfig(
+        model=model,
+        base_url=base_url,
+        timeout=timeout,
+        max_retries=max_retries,
+        backoff_base=backoff_base,
+    )
+
+    if not resolved.is_local:
+        logger.warning(
+            "Ollama backend pointed at non-local host %s — transcript data "
+            "will leave this machine. Set synthesis.base_url to http://127.0.0.1:11434 "
+            "to restore privacy-by-default.",
+            resolved.base_url,
+        )
+
+    return resolved
+
+
+# ─── Synthesizer ───────────────────────────────────────────────────────
+
+
+class OllamaSynthesizer(BaseSynthesizer):
+    """Synthesize wiki source pages via a local Ollama HTTP server.
+
+    The implementation uses only ``urllib`` so no third-party HTTP client
+    is required. Test injection uses the ``http_post`` / ``http_get``
+    kwargs so ``unittest.mock`` or a hand-rolled fake can substitute the
+    transport layer without a real socket.
+    """
+
+    def __init__(
+        self,
+        config: Optional[OllamaConfig] = None,
+        *,
+        http_post: Optional[Any] = None,
+        http_get: Optional[Any] = None,
+    ):
+        self.config = config or OllamaConfig()
+        self._http_post = http_post or _urlopen_post
+        self._http_get = http_get or _urlopen_get
+
+    # ---- BaseSynthesizer interface --------------------------------
+
+    def is_available(self) -> bool:
+        """Probe ``/api/tags`` with a 2-second timeout.
+
+        Returns True iff the server responds 2xx. Any exception
+        (connection refused, DNS failure, HTTP 5xx, etc.) is swallowed
+        and returns False — callers should branch on this before calling
+        :meth:`synthesize_source_page`.
+        """
+        try:
+            status, _ = self._http_get(
+                self.config.tags_url, timeout=min(self.config.timeout, 2)
+            )
+            return 200 <= status < 300
+        except Exception as exc:  # noqa: BLE001 — probe must never raise
+            logger.debug("Ollama availability probe failed: %s", exc)
+            return False
+
+    def synthesize_source_page(
+        self,
+        raw_body: str,
+        meta: dict[str, Any],
+        prompt_template: str,
+    ) -> str:
+        """Render ``prompt_template`` with the session body + metadata
+        and send it to Ollama. Returns the model's raw completion text.
+
+        Raises
+        ------
+        OllamaUnavailableError
+            The server could not be reached at all (connection refused,
+            DNS failure, etc.). Callers should skip synthesis and move on.
+        OllamaHTTPError
+            The server returned a non-2xx response after all retries.
+        """
+        # #py-h7 (#585): pipeline used to pre-render the prompt for us
+        # (with `body[:8000]` truncation + a `key: value` meta format),
+        # but that violated the BaseSynthesizer contract. Now we own the
+        # render. Mirror the previous 8 KB body cap so very long sessions
+        # don't blow Ollama's context window — agent_delegate uses the
+        # same cap; centralise here so the limit lives next to the prompt.
+        truncated_body = raw_body[:8000] if raw_body else ""
+        prompt = _render_prompt(prompt_template, raw_body=truncated_body, meta=meta)
+        payload = {
+            "model": self.config.model,
+            "prompt": prompt,
+            "stream": False,
+        }
+
+        data = self._call_generate(payload)
+        response = data.get("response", "")
+        if not isinstance(response, str):
+            raise OllamaError(
+                f"Ollama returned non-string response: {type(response).__name__}"
+            )
+        return response.strip()
+
+    # ---- internals -----------------------------------------------
+
+    def _call_generate(self, payload: dict[str, Any]) -> dict[str, Any]:
+        """POST to /api/generate with retry + backoff."""
+        last_exc: Optional[Exception] = None
+        for attempt in range(1, self.config.max_retries + 1):
+            try:
+                status, body = self._http_post(
+                    self.config.generate_url,
+                    payload,
+                    timeout=self.config.timeout,
+                )
+            except OllamaUnavailableError:
+                # Connection refused / DNS failure — don't retry. The
+                # server simply isn't listening; retrying wastes time.
+                raise
+            except (socket.timeout, urllib.error.URLError) as exc:
+                last_exc = exc
+                logger.warning(
+                    "Ollama request attempt %d/%d failed: %s",
+                    attempt,
+                    self.config.max_retries,
+                    exc,
+                )
+                if attempt == self.config.max_retries:
+                    raise OllamaError(f"Ollama call failed: {exc}") from exc
+                time.sleep(self.config.backoff_base * (2 ** (attempt - 1)))
+                continue
+
+            if 200 <= status < 300:
+                try:
+                    return json.loads(body)
+                except ValueError as exc:
+                    raise OllamaError(
+                        f"Ollama returned non-JSON body: {exc}"
+                    ) from exc
+
+            if 500 <= status < 600 and attempt < self.config.max_retries:
+                logger.warning(
+                    "Ollama %s returned %d; retrying (%d/%d)",
+                    self.config.generate_url,
+                    status,
+                    attempt,
+                    self.config.max_retries,
+                )
+                time.sleep(self.config.backoff_base * (2 ** (attempt - 1)))
+                continue
+
+            raise OllamaHTTPError(status, body)
+
+        # Unreachable if max_retries >= 1, but keep the type checker honest
+        raise OllamaError(f"Ollama call failed after retries: {last_exc}")
+
+
+# ─── HTTP transport (stdlib) ──────────────────────────────────────────
+
+
+def _urlopen_post(
+    url: str, payload: dict[str, Any], *, timeout: float
+) -> tuple[int, str]:
+    """POST JSON and return (status, body) as text. Raises
+    :class:`OllamaUnavailableError` on connection refused / DNS failure."""
+    body = json.dumps(payload).encode("utf-8")
+    req = urllib.request.Request(
+        url,
+        data=body,
+        headers={"Content-Type": "application/json"},
+        method="POST",
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as resp:
+            return resp.status, resp.read().decode("utf-8", errors="replace")
+    except urllib.error.HTTPError as exc:
+        # Server responded, but with an error code — treat as protocol
+        # failure and return the status/body so retry logic can decide.
+        body = exc.read().decode("utf-8", errors="replace") if exc.fp else ""
+        return exc.code, body
+    except urllib.error.URLError as exc:
+        reason = exc.reason
+        if isinstance(reason, ConnectionRefusedError):
+            raise OllamaUnavailableError(
+                f"Ollama server refused connection at {url}. "
+                "Is `ollama serve` running?"
+            ) from exc
+        if isinstance(reason, socket.gaierror):
+            raise OllamaUnavailableError(
+                f"Ollama host DNS lookup failed for {url}: {reason}"
+            ) from exc
+        raise
+
+
+def _urlopen_get(url: str, *, timeout: float) -> tuple[int, str]:
+    """GET and return (status, body). Same error-mapping rules as POST."""
+    try:
+        with urllib.request.urlopen(url, timeout=timeout) as resp:
+            return resp.status, resp.read().decode("utf-8", errors="replace")
+    except urllib.error.HTTPError as exc:
+        body = exc.read().decode("utf-8", errors="replace") if exc.fp else ""
+        return exc.code, body
+    except urllib.error.URLError as exc:
+        reason = exc.reason
+        if isinstance(reason, ConnectionRefusedError):
+            raise OllamaUnavailableError(
+                f"Ollama server refused connection at {url}."
+            ) from exc
+        if isinstance(reason, socket.gaierror):
+            raise OllamaUnavailableError(
+                f"Ollama host DNS lookup failed for {url}: {reason}"
+            ) from exc
+        raise
+
+
+# ─── Prompt rendering ─────────────────────────────────────────────────
+
+
+def _render_prompt(
+    template: str, *, raw_body: str, meta: dict[str, Any]
+) -> str:
+    """Substitute ``{body}`` and ``{meta}`` placeholders in the template.
+
+    We deliberately use ``str.replace`` (not ``.format``) because session
+    bodies contain ``{}`` in code blocks — calling ``.format`` there would
+    raise ``KeyError``.
+    """
+    meta_dump = json.dumps(meta, indent=2, default=str, sort_keys=True)
+    return template.replace("{body}", raw_body).replace("{meta}", meta_dump)

sessionwiki/synth/openai_compat.py

@@ -0,0 +1,325 @@
+"""OpenAI-compatible backend for LLM synthesis.
+
+Talks to any server that exposes the OpenAI ``/v1`` chat-completions
+surface: vLLM, SGLang, LM Studio, LiteLLM, or a hosted provider. Stdlib
+only — the same ``urllib`` approach as the Ollama backend, no SDK.
+
+Configuration (``examples/sessions_config.json``)::
+
+    "synthesis": {
+      "backend": "openai",
+      "model": "qwen3.8",
+      "base_url": "http://127.0.0.1:8000/v1",
+      "api_key": "",
+      "timeout": 180,
+      "max_retries": 3,
+      "max_tokens": 1500,
+      "temperature": 0.1,
+      "max_concurrency": 10
+    }
+
+``base_url`` must include the API prefix (``/v1``). ``api_key`` is
+optional; when set it is sent as ``Authorization: Bearer``.
+
+Thinking models (Qwen3) are told to skip the reasoning phase with
+``chat_template_kwargs: {"enable_thinking": false}``. The flag can be
+disabled with ``"enable_thinking": true`` in config, in which case the
+backend falls back to ``reasoning_content`` when ``content`` is empty.
+A strict server that rejects ``chat_template_kwargs`` with HTTP 400 is
+retried once without the field.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+from dataclasses import dataclass
+from typing import Any
+
+from sessionwiki.synth.base import BaseSynthesizer
+
+logger = logging.getLogger(__name__)
+
+DEFAULT_BASE_URL = "http://127.0.0.1:8001/v1"
+DEFAULT_MODEL = "qwen3.8"
+DEFAULT_TIMEOUT = 180
+DEFAULT_MAX_RETRIES = 3
+DEFAULT_BACKOFF_BASE = 1.0
+DEFAULT_MAX_TOKENS = 1500
+DEFAULT_TEMPERATURE = 0.1
+
+
+class OpenAICompatError(RuntimeError):
+    """Base class for OpenAI-compatible backend failures."""
+
+
+class OpenAICompatUnavailableError(OpenAICompatError):
+    """Raised when the server is unreachable or the health probe fails."""
+
+
+class OpenAICompatHTTPError(OpenAICompatError):
+    """Raised when the server returns a non-2xx response.
+
+    Retryable statuses (429, 5xx) are retried by ``_post_chat``; other
+    statuses reach the caller immediately.
+    """
+
+    def __init__(self, status: int, body: str):
+        super().__init__(f"OpenAI-compatible server returned HTTP {status}: {body[:200]}")
+        self.status = status
+        self.body = body
+
+
+@dataclass(frozen=True)
+class OpenAICompatConfig:
+    base_url: str = DEFAULT_BASE_URL
+    model: str = DEFAULT_MODEL
+    api_key: str = ""
+    timeout: int = DEFAULT_TIMEOUT
+    max_retries: int = DEFAULT_MAX_RETRIES
+    backoff_base: float = DEFAULT_BACKOFF_BASE
+    max_tokens: int = DEFAULT_MAX_TOKENS
+    temperature: float = DEFAULT_TEMPERATURE
+    enable_thinking: bool = False
+
+    @property
+    def chat_url(self) -> str:
+        return f"{self.base_url.rstrip('/')}/chat/completions"
+
+    @property
+    def models_url(self) -> str:
+        return f"{self.base_url.rstrip('/')}/models"
+
+    @property
+    def is_local(self) -> bool:
+        host = urllib.parse.urlsplit(self.base_url).hostname or ""
+        return host in {"127.0.0.1", "localhost", "::1"}
+
+
+def load_openai_config(cfg: dict[str, Any] | None) -> OpenAICompatConfig:
+    synth = (cfg or {}).get("synthesis", {}) or {}
+    model = synth.get("model") or DEFAULT_MODEL
+    base_url = synth.get("base_url") or DEFAULT_BASE_URL
+    api_key = str(synth.get("api_key") or "")
+    timeout = int(synth["timeout"]) if "timeout" in synth else DEFAULT_TIMEOUT
+    max_retries = (
+        int(synth["max_retries"]) if "max_retries" in synth else DEFAULT_MAX_RETRIES
+    )
+    backoff_base = (
+        float(synth["backoff_base"])
+        if "backoff_base" in synth
+        else DEFAULT_BACKOFF_BASE
+    )
+    max_tokens = (
+        int(synth["max_tokens"]) if "max_tokens" in synth else DEFAULT_MAX_TOKENS
+    )
+    temperature = (
+        float(synth["temperature"])
+        if "temperature" in synth
+        else DEFAULT_TEMPERATURE
+    )
+    enable_thinking = bool(synth.get("enable_thinking", False))
+
+    if timeout <= 0:
+        raise ValueError(f"synthesis.timeout must be positive, got {timeout}")
+    if max_retries < 1:
+        raise ValueError(
+            f"synthesis.max_retries must be >= 1, got {max_retries}"
+        )
+    if max_tokens < 1:
+        raise ValueError(
+            f"synthesis.max_tokens must be >= 1, got {max_tokens}"
+        )
+    if backoff_base < 0:
+        raise ValueError(
+            f"synthesis.backoff_base must be >= 0, got {backoff_base}"
+        )
+    resolved = OpenAICompatConfig(
+        base_url=base_url,
+        model=model,
+        api_key=api_key,
+        timeout=timeout,
+        max_retries=max_retries,
+        backoff_base=backoff_base,
+        max_tokens=max_tokens,
+        temperature=temperature,
+        enable_thinking=enable_thinking,
+    )
+    if not resolved.is_local:
+        logger.warning(
+            "OpenAI-compatible backend pointed at non-local host %s — transcript "
+            "data will leave this machine. Set synthesis.base_url to a loopback "
+            "address to keep transcripts local.",
+            resolved.base_url,
+        )
+    return resolved
+
+
+def _render_prompt(template: str, *, raw_body: str, meta: dict[str, Any]) -> str:
+    meta_dump = json.dumps(meta, indent=2, default=str, sort_keys=True)
+    return template.replace("{body}", raw_body).replace("{meta}", meta_dump)
+
+
+def _truncate_body(body: str, limit: int = 12000) -> str:
+    """Keep the opening and the conclusion of a long transcript.
+
+    A pure head slice loses the outcome, which is the most valuable
+    part of a session. Two thirds head plus one third tail keeps both
+    the problem statement and the final result.
+    """
+    if not body or len(body) <= limit:
+        return body
+    head_len = (limit * 2) // 3
+    tail_len = limit - head_len
+    return (
+        body[:head_len]
+        + "\n\n...[middle of transcript truncated]...\n\n"
+        + body[-tail_len:]
+    )
+
+
+class OpenAICompatSynthesizer(BaseSynthesizer):
+    """Synthesize source pages through an OpenAI-compatible ``/v1`` API."""
+
+    def __init__(self, config: OpenAICompatConfig | None = None):
+        self.config = config or OpenAICompatConfig()
+
+    @property
+    def name(self) -> str:
+        return f"OpenAICompatSynthesizer({self.config.model})"
+
+    def is_available(self) -> bool:
+        try:
+            body = self._http("GET", self.config.models_url, None, timeout=10)
+        except Exception:
+            return False
+        try:
+            data = json.loads(body)
+        except json.JSONDecodeError:
+            return False
+        return isinstance(data, dict) and isinstance(data.get("data"), list)
+
+    def synthesize_source_page(
+        self,
+        raw_body: str,
+        meta: dict[str, Any],
+        prompt_template: str,
+    ) -> str:
+        # Cap the transcript like the Ollama backend: the page is a
+        # summary, and a 400 KB session would dominate the context.
+        truncated = _truncate_body(raw_body, limit=12000)
+        prompt = _render_prompt(prompt_template, raw_body=truncated, meta=meta)
+        payload: dict[str, Any] = {
+            "model": self.config.model,
+            "messages": [{"role": "user", "content": prompt}],
+            "temperature": self.config.temperature,
+            "max_tokens": self.config.max_tokens,
+            "stream": False,
+        }
+        if not self.config.enable_thinking:
+            payload["chat_template_kwargs"] = {"enable_thinking": False}
+
+        data = self._post_chat(payload)
+        choices = data.get("choices") or []
+        if not choices:
+            raise OpenAICompatError("response has no choices")
+        message = choices[0].get("message") or {}
+        content = message.get("content")
+        if not isinstance(content, str) or not content.strip():
+            # Some servers put the whole answer in reasoning_content
+            # when thinking is enabled. Use it rather than losing the
+            # generation, but only as a fallback.
+            reasoning = message.get("reasoning_content")
+            if isinstance(reasoning, str) and reasoning.strip():
+                content = reasoning
+        if not isinstance(content, str) or not content.strip():
+            raise OpenAICompatError("response content is empty")
+        return content.strip()
+
+    # ---- internals -----------------------------------------------
+
+    def _post_chat(self, payload: dict[str, Any]) -> dict[str, Any]:
+        last_exc: Exception | None = None
+        fallback_used = False
+        attempt = 1
+        while attempt <= self.config.max_retries:
+            try:
+                body = self._http(
+                    "POST", self.config.chat_url, payload, timeout=self.config.timeout
+                )
+                data = json.loads(body)
+                if not isinstance(data, dict):
+                    raise OpenAICompatError("response is not a JSON object")
+                return data
+            except OAIConnectionError:
+                raise
+            except OpenAICompatHTTPError as exc:
+                if (
+                    exc.status == 400
+                    and "chat_template_kwargs" in payload
+                    and not fallback_used
+                ):
+                    # vLLM understands chat_template_kwargs; a strict
+                    # OpenAI-compatible server rejects it with 400.
+                    # Retry once without the key.
+                    payload = {
+                        key: value
+                        for key, value in payload.items()
+                        if key != "chat_template_kwargs"
+                    }
+                    fallback_used = True
+                    continue
+                if 400 <= exc.status < 500 and exc.status != 429:
+                    raise OpenAICompatError(
+                        f"non-retryable HTTP {exc.status}: {exc.body[:200]}"
+                    ) from exc
+                last_exc = exc
+            except (OSError, TimeoutError, json.JSONDecodeError) as exc:
+                last_exc = exc
+
+            if attempt < self.config.max_retries:
+                logger.warning(
+                    "OpenAI-compatible request failed (attempt %d/%d): %s; retrying",
+                    attempt,
+                    self.config.max_retries,
+                    last_exc,
+                )
+                time.sleep(self.config.backoff_base * (2 ** (attempt - 1)))
+            attempt += 1
+
+        raise OpenAICompatError(
+            f"chat completion failed after retries: {last_exc}"
+        )
+
+    def _http(
+        self,
+        method: str,
+        url: str,
+        payload: dict[str, Any] | None,
+        *,
+        timeout: int,
+    ) -> str:
+        data = None
+        headers = {"Accept": "application/json"}
+        if payload is not None:
+            data = json.dumps(payload).encode("utf-8")
+            headers["Content-Type"] = "application/json"
+        if self.config.api_key:
+            headers["Authorization"] = f"Bearer {self.config.api_key}"
+        req = urllib.request.Request(url, data=data, headers=headers, method=method)
+        try:
+            with urllib.request.urlopen(req, timeout=timeout) as resp:
+                return resp.read().decode("utf-8", errors="replace")
+        except urllib.error.HTTPError as exc:
+            body = exc.read().decode("utf-8", errors="replace")
+            raise OpenAICompatHTTPError(exc.code, body) from exc
+        except urllib.error.URLError as exc:
+            raise OAIConnectionError(str(exc.reason)) from exc
+
+
+class OAIConnectionError(OpenAICompatUnavailableError):
+    """Raised when the server cannot be reached (no retry)."""