@baimingtao/lbs-agent 1.0.0

package/runtime/core/llm/client/__init__.py

@@ -0,0 +1,699 @@
+"""
+LLM 客户端 —— 支持工具调用的完整客户端。
+
+关键能力：
+  1. OpenAI Chat Completions API（含 tool calling）
+  2. Anthropic Messages API（含 tool use）
+  3. 解析 tool_calls 并返回结构化结果
+  4. 把 tool 结果以正确的消息格式回灌给 LLM
+
+这是 Agent Loop 自循环的底层通道。
+没有 tool calling，Agent 就只能一问一答，不能自己干活。
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import urllib.request
+import urllib.error
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+from runtime.core.llm.credential import Credential
+from runtime.core.llm.provider import ProviderProfile, OMIT_TEMPERATURE
+
+logger = logging.getLogger(__name__)
+
+
+def _is_cjk(ch: str) -> bool:
+    """判断字符是否为 CJK 统一表意文字。"""
+    cp = ord(ch)
+    return (0x4E00 <= cp <= 0x9FFF) or (0x3400 <= cp <= 0x4DBF) or (0x20000 <= cp <= 0x2A6DF)
+
+
+def _collapse_systematic_pair_duplication(text: str) -> str:
+    """修复兼容网关偶发的逐词重复。
+
+    仅针对中文（CJK）词级重复，避免误伤英文双字母（如 hello → helo）。
+    支持 2-8 字符宽度的连续重复词检测。
+
+    模式：
+      ABAB:   "我是我是" → "我是"（2 字词重复）
+      ABCABC: "好奇心好奇心" → "好奇心"（3 字词重复）
+      长词:   "需要帮忙的？需要帮忙的？" → "需要帮忙的？"
+    """
+    if len(text) < 6:
+        return text
+
+    # 通用滑窗去重：从长到短尝试，只对 CJK 文本生效
+    for word_len in range(8, 1, -1):
+        if len(text) < word_len * 2:
+            continue
+        # 至少 2 个完整重复词才触发（12 字符以上）
+        result = []
+        i = 0
+        total_dup = 0
+        while i < len(text):
+            if i + word_len * 2 <= len(text) and text[i:i+word_len] == text[i+word_len:i+word_len*2]:
+                # 检查这段词是否含 CJK（避免英文误伤）
+                word = text[i:i+word_len]
+                if any(_is_cjk(c) for c in word):
+                    result.append(word)
+                    i += word_len * 2
+                    total_dup += word_len
+                    continue
+            result.append(text[i])
+            i += 1
+        deduped = "".join(result)
+        if deduped != text and len(deduped) < len(text):
+            text = deduped
+
+    # 高置信度 AABB 快速路径：仅当 CJK 占比高时触发
+    cjk_count = sum(1 for c in text if _is_cjk(c))
+    if cjk_count > len(text) * 0.5:
+        pairs = len(text) // 2
+        matched = sum(text[index] == text[index + 1] for index in range(0, pairs * 2, 2))
+        if pairs and matched / pairs >= 0.72:
+            collapsed = [text[index] for index in range(0, pairs * 2, 2)]
+            if len(text) % 2:
+                collapsed.append(text[-1])
+            return "".join(collapsed)
+
+    return text
+
+
+def _normalize_tool_name(name: str) -> str:
+    """Normalize gateway duplication without changing ordinary tool names."""
+    collapsed = _collapse_systematic_pair_duplication(name)
+    parts: list[str] = []
+    for part in collapsed.split("_"):
+        half = len(part) // 2
+        if half and len(part) % 2 == 0 and part[:half] == part[half:]:
+            part = part[:half]
+        if not parts or parts[-1] != part:
+            parts.append(part)
+    return "_".join(parts)
+
+
+@dataclass
+class ToolCallRequest:
+
+    id: str = ""           # tool_call_id（OpenAI）或 tool_use_id（Anthropic）
+    name: str = ""
+    arguments: dict[str, Any] = field(default_factory=dict)
+
+
+def _normalize_tool_arguments(value: Any) -> dict[str, Any]:
+    if isinstance(value, dict) and set(value) == {"_raw"}:
+        value = value["_raw"]
+    if isinstance(value, dict):
+        return value
+    if not isinstance(value, str):
+        return {"_raw": str(value)}
+    text = _collapse_systematic_pair_duplication(value).strip()
+    decoder = json.JSONDecoder()
+    decoded = []
+    pos = 0
+    try:
+        while pos < len(text):
+            item, pos = decoder.raw_decode(text, pos)
+            decoded.append(item)
+            while pos < len(text) and text[pos].isspace():
+                pos += 1
+    except (json.JSONDecodeError, TypeError):
+        return {"_raw": text}
+    if decoded and all(item == decoded[0] for item in decoded) and isinstance(decoded[0], dict):
+        return decoded[0]
+    return decoded[0] if len(decoded) == 1 and isinstance(decoded[0], dict) else {"_raw": text}
+
+
+def normalize_tool_calls(calls: list[Any]) -> list[ToolCallRequest]:
+    result = []
+    seen = set()
+    for raw in calls:
+        if isinstance(raw, ToolCallRequest):
+            call_id, name, arguments = raw.id, raw.name, raw.arguments
+        else:
+            call_id, name, arguments = str(raw.get("id", "")), str(raw.get("name", "")), raw.get("arguments", {})
+        args = _normalize_tool_arguments(arguments)
+        key = (call_id, name, json.dumps(args, ensure_ascii=False, sort_keys=True))
+        if key not in seen:
+            seen.add(key)
+            result.append(ToolCallRequest(id=call_id, name=_normalize_tool_name(name), arguments=args))
+    return result
+
+
+@dataclass
+class CompletionResult:
+    """一次 LLM 调用的完整结果。"""
+    content: str = ""
+    role: str = "assistant"
+    finish_reason: str = "stop"
+    model: str = ""
+    usage: dict[str, int] = field(default_factory=dict)
+    tool_calls: list[ToolCallRequest] = field(default_factory=list)
+    raw: Any = None
+
+    @property
+    def has_tool_calls(self) -> bool:
+        return len(self.tool_calls) > 0
+
+
+class LLMClient:
+    """LLM 客户端，支持工具调用。"""
+
+    def __init__(self, profile: ProviderProfile, credential: Credential):
+        self.profile = profile
+        self.credential = credential
+
+        if not credential.is_valid:
+            raise ValueError(f"No valid credential for provider {profile.name}")
+
+        self.base_url = credential.base_url or profile.base_url
+        if not self.base_url:
+            raise ValueError(f"No base_url for provider {profile.name}")
+
+    # ── 主入口 ─────────────────────────────────────
+
+    def chat(
+        self,
+        messages: list[dict[str, str]],
+        *,
+        model: str = "",
+        system: str = "",
+        temperature: float = 0.7,
+        max_tokens: int | None = None,
+        tools: list[dict] | None = None,
+        **kwargs,
+    ) -> CompletionResult:
+        if isinstance(messages, str):
+            messages = [{"role": "user", "content": messages}]
+
+        # 模型解析
+        model = model or (self.profile.fallback_models[0] if self.profile.fallback_models else "")
+
+        # 温度解析
+        temp = self.profile.fixed_temperature
+        if temp is None:
+            temp = temperature
+        if temp is OMIT_TEMPERATURE:
+            temp = None
+
+        # max_tokens 解析
+        if max_tokens is None:
+            max_tokens = self.profile.get_max_tokens(model)
+
+        if self.profile.api_mode == "anthropic_messages":
+            return self._call_anthropic(messages, model, system, temp, max_tokens, tools, **kwargs)
+        else:
+            return self._call_openai(messages, model, system, temp, max_tokens, tools, **kwargs)
+
+    # ── OpenAI Chat Completions ────────────────────
+
+    def _call_openai(
+        self,
+        messages: list,
+        model: str,
+        system: str,
+        temp: float | None,
+        max_tokens: int | None,
+        tools: list[dict] | None,
+        **kwargs,
+    ) -> CompletionResult:
+        url = self.base_url.rstrip("/") + "/chat/completions"
+
+        msg_list = list(messages)
+        if system and not any(m.get("role") == "system" for m in msg_list):
+            msg_list = [{"role": "system", "content": system}] + msg_list
+
+        msg_list = self.profile.prepare_messages(msg_list)
+
+        payload: dict[str, Any] = {
+            "model": model,
+            "messages": msg_list,
+        }
+        if temp is not None:
+            payload["temperature"] = temp
+        if max_tokens:
+            payload["max_tokens"] = max_tokens
+        if tools:
+            payload["tools"] = tools
+            payload["tool_choice"] = "auto"
+
+        extra_body, top_level = self.profile.build_api_kwargs_extras(**kwargs)
+        if extra_body:
+            payload["extra_body"] = extra_body
+        payload.update(top_level)
+
+        data = self._http_post(url, json.dumps(payload).encode("utf-8"), kwargs.get("request_timeout"))
+        return self._parse_openai(data, model)
+
+    def _parse_openai(self, data: dict, model: str) -> CompletionResult:
+        choices = data.get("choices", [])
+        if not choices:
+            raise ValueError(f"API returned no choices: {json.dumps(data, ensure_ascii=False)[:500]}")
+        choice = choices[0]
+        msg = choice.get("message", {})
+
+        tool_calls = []
+        for tc in (msg.get("tool_calls") or []):
+            func = tc.get("function", {})
+            args_str = func.get("arguments", "{}")
+            try:
+                args = json.loads(args_str) if args_str else {}
+            except json.JSONDecodeError:
+                args = {"_raw": args_str}
+            tool_calls.append(ToolCallRequest(
+                id=tc.get("id", ""),
+                name=func.get("name", ""),
+                arguments=args,
+            ))
+
+        return CompletionResult(
+            content=msg.get("content", "") or "",
+            role=msg.get("role", "assistant"),
+            finish_reason=choice.get("finish_reason", "stop"),
+            model=data.get("model", model),
+            usage=data.get("usage", {}),
+            tool_calls=normalize_tool_calls(tool_calls),
+            raw=data,
+        )
+
+    # ── Anthropic Messages API ─────────────────────
+
+    def _anthropic_sdk_client(self, timeout=None):
+        """构造 Anthropic-compatible client；第三方 endpoint 仍使用原始 API key。"""
+        try:
+            from anthropic import Anthropic
+        except ImportError:
+            return None
+        kwargs = {
+            "api_key": self.credential.api_key,
+            "base_url": self.base_url.rstrip("/"),
+            "max_retries": 0,
+        }
+        if timeout:
+            kwargs["timeout"] = timeout
+        return Anthropic(**kwargs)
+
+    def _call_anthropic(
+        self,
+        messages: list,
+        model: str,
+        system: str,
+        temp: float | None,
+        max_tokens: int | None,
+        tools: list[dict] | None,
+        **kwargs,
+    ) -> CompletionResult:
+        sdk = self._anthropic_sdk_client(kwargs.get("request_timeout") or 120) if self.profile.base_url else None
+        if sdk is None:
+            return self._call_anthropic_http(messages, model, system, temp, max_tokens, tools, **kwargs)
+        system_text, api_messages = self._anthropic_messages(messages, system)
+        params = {
+            "model": model,
+            "messages": api_messages,
+            "max_tokens": max_tokens or 4096,
+        }
+        if system_text:
+            params["system"] = system_text
+        if temp is not None:
+            params["temperature"] = temp
+        if tools:
+            params["tools"] = tools
+        response = sdk.messages.create(**params)
+        data = response.model_dump() if hasattr(response, "model_dump") else response
+        return self._parse_anthropic(data, model)
+
+    def _anthropic_messages(self, messages, system):
+        system_text = system or ""
+        api_messages = []
+        for message in messages:
+            if message.get("role") == "system":
+                system_text += "\n" + str(message.get("content", ""))
+            else:
+                api_messages.append(message)
+        return system_text.strip(), api_messages
+
+    def _call_anthropic_http(self, messages, model, system, temp, max_tokens, tools, **kwargs):
+        """Anthropic SDK 不可用时的兼容 HTTP fallback。"""
+        system_text, api_messages = self._anthropic_messages(messages, system)
+        payload = {"model": model, "messages": api_messages, "max_tokens": max_tokens or 4096}
+        if system_text:
+            payload["system"] = system_text
+        if temp is not None:
+            payload["temperature"] = temp
+        if tools:
+            payload["tools"] = tools
+        data = self._http_post(
+            self.base_url.rstrip("/") + "/v1/messages",
+            json.dumps(payload).encode("utf-8"),
+            kwargs.get("request_timeout"),
+        )
+        return self._parse_anthropic(data, model)
+
+    def _parse_anthropic(self, data: dict, model: str) -> CompletionResult:
+        content_blocks = data.get("content", [])
+
+        text_parts = []
+        tool_calls = []
+
+        for block in content_blocks:
+            btype = block.get("type")
+            if btype == "text":
+                text_parts.append(block.get("text", ""))
+            elif btype == "tool_use":
+                # 对 tool_use 的 input 也做去重（网关偶发重复 arguments）
+                raw_input = block.get("input", {})
+                if isinstance(raw_input, str):
+                    raw_input = _collapse_systematic_pair_duplication(raw_input)
+                tool_calls.append(ToolCallRequest(
+                    id=block.get("id", ""),
+                    name=_normalize_tool_name(block.get("name", "")) if block.get("name") else "",
+                    arguments=raw_input if isinstance(raw_input, dict) else {"_raw": str(raw_input)},
+                ))
+
+        return CompletionResult(
+            content=_collapse_systematic_pair_duplication("".join(text_parts)),
+            finish_reason=data.get("stop_reason", "stop"),
+            model=data.get("model", model),
+            usage={
+                "prompt_tokens": data.get("usage", {}).get("input_tokens", 0),
+                "completion_tokens": data.get("usage", {}).get("output_tokens", 0),
+            },
+            tool_calls=normalize_tool_calls(tool_calls),
+            raw=data,
+        )
+
+
+    # ── 流式输出 ───────────────────────────────────
+
+    def chat_stream(
+        self,
+        messages: list[dict[str, str]],
+        *,
+        model: str = "",
+        system: str = "",
+        temperature: float = 0.7,
+        max_tokens: int | None = None,
+        tools: list[dict] | None = None,
+        on_chunk: Any = None,
+        **kwargs,
+    ):
+        """流式调用 LLM，逐 token 返回。
+
+        yields (delta_text: str, tool_calls_so_far: list[ToolCallRequest], done: bool)
+
+        当 on_chunk 回调存在时，也会同步调用 on_chunk(delta_text)。
+        """
+        if isinstance(messages, str):
+            messages = [{"role": "user", "content": messages}]
+
+        model = model or (self.profile.fallback_models[0] if self.profile.fallback_models else "")
+        temp = self.profile.fixed_temperature
+        if temp is None:
+            temp = temperature
+        if temp is OMIT_TEMPERATURE:
+            temp = None
+        if max_tokens is None:
+            max_tokens = self.profile.get_max_tokens(model)
+
+        if self.profile.api_mode == "anthropic_messages":
+            yield from self._stream_anthropic(messages, model, system, temp, max_tokens, tools, on_chunk, **kwargs)
+        else:
+            yield from self._stream_openai(messages, model, system, temp, max_tokens, tools, on_chunk, **kwargs)
+
+    def _stream_openai(self, messages, model, system, temp, max_tokens, tools, on_chunk, **kwargs):
+        """OpenAI SSE streaming."""
+        url = self.base_url.rstrip("/") + "/chat/completions"
+
+        msg_list = list(messages)
+        if system and not any(m.get("role") == "system" for m in msg_list):
+            msg_list = [{"role": "system", "content": system}] + msg_list
+        msg_list = self.profile.prepare_messages(msg_list)
+
+        payload: dict[str, Any] = {
+            "model": model,
+            "messages": msg_list,
+            "stream": True,
+        }
+        if temp is not None:
+            payload["temperature"] = temp
+        if max_tokens:
+            payload["max_tokens"] = max_tokens
+        if tools:
+            payload["tools"] = tools
+            payload["tool_choice"] = "auto"
+
+        extra_body, top_level = self.profile.build_api_kwargs_extras(**kwargs)
+        if extra_body:
+            payload["extra_body"] = extra_body
+        payload.update(top_level)
+
+        import urllib.request, urllib.error
+        data = json.dumps(payload).encode("utf-8")
+        is_anthropic = False
+        headers = self._build_headers(anthropic=False)
+        req = urllib.request.Request(url, data=data, headers=headers, method="POST")
+
+        request_timeout = kwargs.get("request_timeout") or 120
+        accumulated_text = ""
+        tool_calls_map: dict[int, dict] = {}
+
+        try:
+            resp = urllib.request.urlopen(req, timeout=request_timeout)
+            while True:
+                raw_line = resp.readline()
+                if not raw_line:
+                    break
+                line = raw_line.decode("utf-8").strip()
+                if not line or not line.startswith("data: "):
+                    continue
+                data_str = line[6:]
+                if data_str == "[DONE]":
+                    break
+                try:
+                    chunk = json.loads(data_str)
+                except json.JSONDecodeError:
+                    continue
+                choices = chunk.get("choices", [])
+                if not choices:
+                    continue
+                delta = choices[0].get("delta", {})
+
+                # reasoning delta (DeepSeek/GLM/Qwen thinking)
+                reasoning_delta = delta.get("reasoning_content") or delta.get("reasoning") or ""
+                if reasoning_delta:
+                    if on_chunk:
+                        on_chunk(reasoning_delta, "thinking")
+                    yield (reasoning_delta, [], False)
+
+                # text delta
+                text_delta = delta.get("content") or ""
+                if text_delta:
+                    accumulated_text += text_delta
+                    if on_chunk:
+                        on_chunk(text_delta)
+                    yield (text_delta, [], False)
+
+                # tool_calls delta (streaming accumulation)
+                for tc_delta in (delta.get("tool_calls") or []):
+                    idx = tc_delta.get("index", 0)
+                    if idx not in tool_calls_map:
+                        tool_calls_map[idx] = {"id": "", "name": "", "arguments": ""}
+                    if tc_delta.get("id"):
+                        tool_calls_map[idx]["id"] = tc_delta["id"]
+                    func = tc_delta.get("function", {})
+                    if func.get("name"):
+                        tool_calls_map[idx]["name"] = func["name"]
+                    if func.get("arguments"):
+                        tool_calls_map[idx]["arguments"] += func["arguments"]
+
+            # Final yield with complete tool_calls
+            final_tool_calls = []
+            for idx in sorted(tool_calls_map):
+                tc = tool_calls_map[idx]
+                try:
+                    args = json.loads(tc["arguments"]) if tc["arguments"] else {}
+                except json.JSONDecodeError:
+                    args = {"_raw": tc["arguments"]}
+                final_tool_calls.append(ToolCallRequest(
+                    id=tc["id"], name=tc["name"], arguments=args,
+                ))
+
+            yield ("", normalize_tool_calls(final_tool_calls), True)
+
+        except urllib.error.HTTPError as e:
+            error_body = ""
+            try:
+                error_body = e.read().decode("utf-8")
+            except Exception:
+                pass
+            raise ValueError(
+                f"API error {e.code} from {self.profile.name}: {error_body[:500]}"
+            ) from e
+
+    def _stream_anthropic(self, messages, model, system, temp, max_tokens, tools, on_chunk, **kwargs):
+        """Anthropic SSE streaming via raw HTTP.
+
+        The Anthropic SDK's ``stream.get_final_message()`` is unreliable with
+        non-canonical gateways (e.g. seeyon): ``text_stream`` succeeds and
+        yields chunks, but ``get_final_message()`` throws ``IndexError``.
+        The previous fallback to ``_stream_anthropic_http`` then fired a
+        *second* HTTP request, causing the first response's text to be lost
+        and the second (often empty) response to trigger
+        ``LLM returned empty response`` → router cooldown → exhausted.
+
+        Fix: always use the raw HTTP SSE parser, which correctly handles
+        ``text_delta``, ``tool_use``, and ``thinking`` blocks in a single
+        request.
+        """
+        yield from self._stream_anthropic_http(messages, model, system, temp, max_tokens, tools, on_chunk, **kwargs)
+
+    def _stream_anthropic_http(self, messages, model, system, temp, max_tokens, tools, on_chunk, **kwargs):
+        """Anthropic SSE fallback，保持标准 /v1/messages 协议。"""
+        url = self.base_url.rstrip("/") + "/v1/messages"
+
+        system_text = system or ""
+        api_messages = []
+        for m in messages:
+            if m["role"] == "system":
+                system_text += "\n" + m["content"]
+            else:
+                api_messages.append(m)
+
+        payload: dict[str, Any] = {
+            "model": model,
+            "messages": api_messages,
+            "max_tokens": max_tokens or 4096,
+            "stream": True,
+        }
+        if system_text.strip():
+            payload["system"] = system_text.strip()
+        if temp is not None:
+            payload["temperature"] = temp
+        if tools:
+            payload["tools"] = tools
+
+        extra_body, top_level = self.profile.build_api_kwargs_extras(**kwargs)
+        if extra_body:
+            payload.update(extra_body)
+        payload.update(top_level)
+
+        import urllib.request, urllib.error
+        data = json.dumps(payload).encode("utf-8")
+        headers = self._build_headers(anthropic=True)
+        req = urllib.request.Request(url, data=data, headers=headers, method="POST")
+
+        request_timeout = kwargs.get("request_timeout") or 120
+        accumulated_text = ""
+        tool_calls: list[ToolCallRequest] = []
+        current_tool_use_id = ""
+        current_tool_use_name = ""
+        current_tool_input = ""
+
+        try:
+            resp = urllib.request.urlopen(req, timeout=request_timeout)
+            while True:
+                raw_line = resp.readline()
+                if not raw_line:
+                    break
+                line = raw_line.decode("utf-8").strip()
+                if not line or not line.startswith("data: "):
+                    continue
+                data_str = line[6:]
+                try:
+                    event = json.loads(data_str)
+                except json.JSONDecodeError:
+                    continue
+
+                etype = event.get("type", "")
+
+                if etype == "content_block_start":
+                    block = event.get("content_block", {})
+                    if block.get("type") == "thinking":
+                        # Signal thinking block start
+                        pass
+                    elif block.get("type") == "tool_use":
+                        current_tool_use_id = block.get("id", "")
+                        current_tool_use_name = _normalize_tool_name(block.get("name", ""))
+
+                elif etype == "content_block_delta":
+                    delta = event.get("delta", {})
+                    dtype = delta.get("type", "")
+                    if dtype == "text_delta":
+                        text_delta = delta.get("text", "")
+                        if text_delta:
+                            accumulated_text += text_delta
+                            if on_chunk:
+                                on_chunk(text_delta)
+                            yield (text_delta, [], False)
+                    elif dtype == "thinking_delta":
+                        # Extended thinking — send as "thinking" chunk_type
+                        think_delta = delta.get("thinking", "")
+                        if think_delta and on_chunk:
+                            on_chunk(think_delta, "thinking")
+                        yield (think_delta, [], False)
+                    elif dtype == "input_json_delta":
+                        current_tool_input += delta.get("partial_json", "")
+
+                elif etype == "content_block_stop":
+                    if current_tool_use_id:
+                        try:
+                            args = json.loads(current_tool_input) if current_tool_input else {}
+                        except json.JSONDecodeError:
+                            args = {"_raw": current_tool_input}
+                        tool_calls.append(ToolCallRequest(
+                            id=current_tool_use_id,
+                            name=current_tool_use_name,
+                            arguments=args,
+                        ))
+                        current_tool_use_id = ""
+                        current_tool_use_name = ""
+                        current_tool_input = ""
+
+                elif etype == "message_stop":
+                    break
+
+            # 最终去重后 yield
+            final_text = _collapse_systematic_pair_duplication(accumulated_text)
+            yield (final_text, normalize_tool_calls(tool_calls), True)
+
+        except urllib.error.HTTPError as e:
+            error_body = ""
+            try:
+                error_body = e.read().decode("utf-8")
+            except Exception:
+                pass
+            raise ValueError(
+                f"API error {e.code} from {self.profile.name}: {error_body[:500]}"
+            ) from e
+
+    def _build_headers(self, anthropic: bool = False) -> dict[str, str]:
+        headers = {"Content-Type": "application/json"}
+        if anthropic:
+            headers["x-api-key"] = self.credential.api_key
+            headers["anthropic-version"] = "2023-06-01"
+        else:
+            headers["Authorization"] = f"Bearer {self.credential.api_key}"
+        headers.update(self.profile.default_headers)
+        return headers
+
+    def _http_post(self, url: str, body: bytes, timeout: int | float | None = None) -> dict:
+        is_anthropic = self.profile.api_mode == "anthropic_messages"
+        headers = self._build_headers(anthropic=is_anthropic)
+        req = urllib.request.Request(url, data=body, headers=headers, method="POST")
+        try:
+            request_timeout = timeout or 120
+            with urllib.request.urlopen(req, timeout=request_timeout) as resp:
+                return json.loads(resp.read().decode("utf-8"))
+        except urllib.error.HTTPError as e:
+            error_body = ""
+            try:
+                error_body = e.read().decode("utf-8")
+            except Exception:
+                pass
+            raise ValueError(
+                f"API error {e.code} from {self.profile.name}: {error_body[:500]}"
+            ) from e