agenthub-python 0.3.3__tar.gz → 0.4.1__tar.gz

{agenthub_python-0.3.3 → agenthub_python-0.4.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agenthub-python
-Version: 0.3.3
+Version: 0.4.1
 Summary: AgentHub is the LLM API Hub for the Agent era, built for high-precision autonomous agents.
 Keywords: agent,llm,gemini,claude,gpt
 Author: PrismShadow
@@ -16,6 +16,9 @@ Requires-Dist: pytest-asyncio>=0.23.0 ; extra == 'dev'
 Requires-Dist: ruff>=0.14.3 ; extra == 'dev'
 Requires-Dist: pillow>=10.0.0 ; extra == 'dev'
 Requires-Python: >=3.11
+Project-URL: Homepage, https://github.com/Prism-Shadow/agenthub
+Project-URL: Repository, https://github.com/Prism-Shadow/agenthub
+Project-URL: Issues, https://github.com/Prism-Shadow/agenthub/issues
 Provides-Extra: dev
 Description-Content-Type: text/markdown
 

{agenthub_python-0.3.3 → agenthub_python-0.4.1}/agenthub/__init__.py

@@ -13,7 +13,22 @@
 # limitations under the License.
 
 from .auto_client import AutoLLMClient
+from .errors import AgentHubError, EmptyResponseError, ToolCallArgumentParseError, UnsupportedParameterError
+from .registry import Currency, Modality, ModelPricing, SupportedModel, list_supported_models
 from .types import PromptCaching, ThinkingLevel
 
 
-__all__ = ["AutoLLMClient", "PromptCaching", "ThinkingLevel"]
+__all__ = [
+    "AgentHubError",
+    "AutoLLMClient",
+    "Currency",
+    "EmptyResponseError",
+    "Modality",
+    "ModelPricing",
+    "PromptCaching",
+    "SupportedModel",
+    "ThinkingLevel",
+    "ToolCallArgumentParseError",
+    "UnsupportedParameterError",
+    "list_supported_models",
+]

{agenthub_python-0.3.3 → agenthub_python-0.4.1}/agenthub/auto_client.py

@@ -47,16 +47,25 @@ class AutoLLMClient(LLMClient):
     ) -> LLMClient:
         """Create the appropriate client for the given model."""
         client_type = (client_type or os.getenv("CLIENT_TYPE", model)).lower()
+        # gemini-3.6 must be matched before the broader gemini-3 prefix below
         if any(
+            prefix in client_type for prefix in ("gemini-3.6", "gemini-3.5-flash-lite")
+        ):  # e.g., gemini-3.6-flash; gemini-3.5-flash-lite shares the sampling-parameter deprecation
+            from .gemini3_6 import Gemini3_6Client
+
+            return Gemini3_6Client(model=model, api_key=api_key, base_url=base_url)
+        elif any(
             prefix in client_type for prefix in ("gemini-3", "gemini-embedding")
         ):  # e.g., gemini-3-flash-preview, gemini-embedding-2
             from .gemini3 import Gemini3Client
 
             return Gemini3Client(model=model, api_key=api_key, base_url=base_url)
-        elif "claude" in client_type and ("4-7" in client_type or "4-8" in client_type):  # e.g., claude-opus-4-7
-            from .claude4_8 import Claude4_8Client
+        elif "claude" in client_type and (
+            "4-7" in client_type or "4-8" in client_type or "-5" in client_type
+        ):  # e.g., claude-opus-4-7
+            from .claude5 import Claude5Client
 
-            return Claude4_8Client(model=model, api_key=api_key, base_url=base_url)
+            return Claude5Client(model=model, api_key=api_key, base_url=base_url)
         elif "claude" in client_type and "4-6" in client_type:  # e.g., claude-sonnet-4-6
             from .claude4_6 import Claude4_6Client
 
@@ -65,10 +74,18 @@ class AutoLLMClient(LLMClient):
             from .gpt5_5 import GPT5_5Client
 
             return GPT5_5Client(model=model, api_key=api_key, base_url=base_url)
+        elif "glm-5.2" in client_type:
+            from .glm5_2 import GLM5_2Client
+
+            return GLM5_2Client(model=model, api_key=api_key, base_url=base_url)
         elif "glm-5" in client_type or "glm-5.1" in client_type:
             from .glm5_1 import GLM5_1Client
 
             return GLM5_1Client(model=model, api_key=api_key, base_url=base_url)
+        elif "kimi-k3" in client_type:
+            from .kimi_k3 import KimiK3Client
+
+            return KimiK3Client(model=model, api_key=api_key, base_url=base_url)
         elif "kimi-k2.5" in client_type or "kimi-k2.6" in client_type:
             from .kimi_k2_6 import KimiK2_6Client
 
@@ -81,14 +98,14 @@ class AutoLLMClient(LLMClient):
             from .openai_embedding import OpenaiEmbeddingClient
 
             return OpenaiEmbeddingClient(model=model, api_key=api_key, base_url=base_url)
-        elif "openai" in client_type:
+        elif "openai" in client_type and "embedding" not in client_type:
             from .openai import OpenaiClient
 
             return OpenaiClient(model=model, api_key=api_key, base_url=base_url)
         else:
             raise ValueError(
                 f"{client_type} is not supported. "
-                "Supported client types: gemini-3, claude-4-8, claude-4-7, claude-4-6, gpt-5.5, gpt-5.4, glm-5.1, kimi-k2.6, kimi-k2.5, deepseek-v4, openai-embedding, openai."
+                "Supported client types: gemini-3.6, gemini-3, claude-5, claude-4-8, claude-4-7, claude-4-6, gpt-5.5, gpt-5.4, glm-5.2, glm-5.1, kimi-k3, kimi-k2.6, kimi-k2.5, deepseek-v4, openai-embedding, openai."
             )
 
     def transform_uni_config_to_model_config(self, config: UniConfig) -> Any:

{agenthub_python-0.3.3 → agenthub_python-0.4.1}/agenthub/base_client.py

@@ -19,6 +19,7 @@ from contextlib import suppress
 from typing import Any, AsyncIterator
 
 from .abort_signal import AbortSignal
+from .errors import EmptyResponseError
 from .types import (
     ContentItem,
     FinishReason,
@@ -100,28 +101,40 @@ class LLMClient(ABC):
         for event in events:
             # Merge content_items from all events
             for item in event["content_items"]:
+                last_fidelity = (content_items[-1].get("fidelity") or {}) if content_items else {}
+                item_fidelity = item.get("fidelity") or {}
                 if item["type"] == "text":
+                    # a delta announcing a different phase starts a new item; same-phase and
+                    # phaseless deltas merge until a signature finishes the item
                     if (
                         content_items
                         and content_items[-1]["type"] == "text"
-                        and content_items[-1].get("signature") is None  # no signature yet
-                        and item.get("phase") is None  # no new phase
+                        and last_fidelity.get("signature") is None  # not finished by a signature yet
+                        and (
+                            item_fidelity.get("phase") is None  # phaseless deltas continue the item
+                            or item_fidelity.get("phase") == last_fidelity.get("phase")  # same phase merges
+                        )
                     ):
                         content_items[-1]["text"] += item["text"]
-                        if "signature" in item:  # finish the current item if signature is not None
-                            content_items[-1]["signature"] = item["signature"]
-                    elif item["text"] or item.get("phase") is not None:  # text or new phase starts an item
+                        if item_fidelity:  # a signature finishes the current item
+                            content_items[-1]["fidelity"] = {**last_fidelity, **item_fidelity}
+                    elif item["text"] or item_fidelity.get("phase") is not None:  # text or new phase starts an item
                         content_items.append(item.copy())
                 elif item["type"] == "thinking":
+                    # a new item starts only when the open item's fidelity is non-empty and
+                    # differs from the incoming delta's; everything else merges into it
                     if (
                         content_items
                         and content_items[-1]["type"] == "thinking"
-                        and content_items[-1].get("signature") is None  # no signature yet
+                        and (
+                            not last_fidelity  # not finished by fidelity yet
+                            or last_fidelity == item_fidelity  # a run of equal fidelity is one item
+                        )
                     ):
                         content_items[-1]["thinking"] += item["thinking"]
-                        if "signature" in item:  # finish the current item if signature is not None
-                            content_items[-1]["signature"] = item["signature"]
-                    elif item["thinking"] or item.get("signature"):  # omit empty thinking items
+                        if item_fidelity:  # fidelity finishes the current item
+                            content_items[-1]["fidelity"] = item_fidelity
+                    elif item["thinking"] or item_fidelity:  # omit empty thinking items
                         content_items.append(item.copy())
                 elif item["type"] == "partial_tool_call":
                     # Skip partial_tool_call items - they should already be converted to tool_call
@@ -244,6 +257,7 @@ class LLMClient(ABC):
             await stream.aclose()
 
         self._validate_last_event(last_event)
+        self._validate_non_thinking_output(events)
 
         # Save history to file if trace_id is specified
         if config.get("trace_id") and events:
@@ -312,6 +326,25 @@ class LLMClient(ABC):
         if last_event["finish_reason"] is None:
             raise ValueError(f"Last event must carry finish_reason, got: {last_event}")
 
+    def _validate_non_thinking_output(self, events: list[UniEvent]) -> None:
+        """Validate that the completed response carries content other than thinking.
+
+        Replaying a thinking-only assistant message on the next turn fails with a 400
+        error, so the response is rejected as soon as the stream completes.
+
+        Args:
+            events: All events yielded by streaming_response
+
+        Raises:
+            EmptyResponseError: If every content item in the response is thinking
+        """
+        thinking_only = all(
+            item["type"] in ("thinking", "inline_thinking") for event in events for item in event["content_items"]
+        )
+        if thinking_only:
+            finish_reason = events[-1]["finish_reason"] if events else None
+            raise EmptyResponseError(self.__class__.__name__, finish_reason)
+
     def clear_history(self) -> None:
         """Clear the message history."""
         self._history.clear()

{agenthub_python-0.3.3 → agenthub_python-0.4.1}/agenthub/claude4_6/client.py

@@ -13,7 +13,6 @@
 # limitations under the License.
 
 import base64
-import json
 import mimetypes
 import os
 import re
@@ -24,6 +23,7 @@ from anthropic import AsyncAnthropic, AsyncAnthropicBedrock
 from anthropic.types.beta import BetaMessageParam, BetaRawMessageStreamEvent
 
 from ..base_client import LLMClient
+from ..errors import UnsupportedParameterError, parse_tool_call_arguments
 from ..types import (
     EventType,
     FinishReason,
@@ -118,7 +118,9 @@ class Claude4_6Client(LLMClient):
         """Convert ToolChoice to Claude's tool_choice format."""
         if isinstance(tool_choice, list):
             if len(tool_choice) > 1:
-                raise ValueError("Claude supports only one tool choice.")
+                raise UnsupportedParameterError(
+                    self.__class__.__name__, "tool_choice", "Claude supports only one tool choice."
+                )
 
             return {"type": "any", "name": tool_choice[0]}
         elif tool_choice == "none":
@@ -204,10 +206,14 @@ class Claude4_6Client(LLMClient):
                     content_blocks.append(await self._convert_image_url_to_source(item["image_url"]))
                 elif item["type"] == "thinking":
                     if item["thinking"] == REDACTED_THINKING:
-                        content_blocks.append({"type": "redacted_thinking", "data": item["signature"]})
+                        content_blocks.append({"type": "redacted_thinking", "data": item["fidelity"]["signature"]})
                     else:
                         content_blocks.append(
-                            {"type": "thinking", "thinking": item["thinking"], "signature": item["signature"]}
+                            {
+                                "type": "thinking",
+                                "thinking": item["thinking"],
+                                "signature": item["fidelity"]["signature"],
+                            }
                         )
                 elif item["type"] == "tool_call":
                     content_blocks.append(
@@ -263,7 +269,9 @@ class Claude4_6Client(LLMClient):
                     {"type": "partial_tool_call", "name": block.name, "arguments": "", "tool_call_id": block.id}
                 )
             elif block.type == "redacted_thinking":
-                content_items.append({"type": "thinking", "thinking": REDACTED_THINKING, "signature": block.data})
+                content_items.append(
+                    {"type": "thinking", "thinking": REDACTED_THINKING, "fidelity": {"signature": block.data}}
+                )
 
         elif claude_event_type == "content_block_delta":
             event_type = "delta"
@@ -277,7 +285,7 @@ class Claude4_6Client(LLMClient):
                     {"type": "partial_tool_call", "name": "", "arguments": delta.partial_json, "tool_call_id": ""}
                 )
             elif delta.type == "signature_delta":
-                content_items.append({"type": "thinking", "thinking": "", "signature": delta.signature})
+                content_items.append({"type": "thinking", "thinking": "", "fidelity": {"signature": delta.signature}})
 
         elif claude_event_type == "content_block_stop":
             event_type = "stop"
@@ -403,7 +411,12 @@ class Claude4_6Client(LLMClient):
                             {
                                 "type": "tool_call",
                                 "name": partial_tool_call["name"],
-                                "arguments": json.loads(partial_tool_call["arguments"]),
+                                "arguments": parse_tool_call_arguments(
+                                    partial_tool_call["arguments"],
+                                    self.__class__.__name__,
+                                    partial_tool_call["name"],
+                                    partial_tool_call["tool_call_id"],
+                                ),
                                 "tool_call_id": partial_tool_call["tool_call_id"],
                             }
                         ],

agenthub_python-0.4.1/agenthub/claude5/__init__.py

@@ -0,0 +1,18 @@
+# Copyright 2025 Prism Shadow. and/or its affiliates
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+from .client import Claude5Client
+
+
+__all__ = ["Claude5Client"]

{agenthub_python-0.3.3/agenthub/claude4_8 → agenthub_python-0.4.1/agenthub/claude5}/client.py

@@ -13,7 +13,6 @@
 # limitations under the License.
 
 import base64
-import json
 import mimetypes
 import os
 import re
@@ -24,6 +23,7 @@ from anthropic import AsyncAnthropic, AsyncAnthropicBedrock
 from anthropic.types.beta import BetaMessageParam, BetaRawMessageStreamEvent
 
 from ..base_client import LLMClient
+from ..errors import UnsupportedParameterError, parse_tool_call_arguments
 from ..types import (
     EventType,
     FinishReason,
@@ -41,11 +41,11 @@ from ..types import (
 REDACTED_THINKING = "_REDACTED_THINKING"
 
 
-class Claude4_8Client(LLMClient):
-    """Claude 4.8-specific LLM client implementation."""
+class Claude5Client(LLMClient):
+    """Claude 5-specific LLM client implementation."""
 
     def __init__(self, model: str, api_key: str | None = None, base_url: str | None = None):
-        """Initialize Claude 4.8 client with model and API key."""
+        """Initialize Claude 5 client with model and API key."""
         self._model = model
         api_key = api_key or os.getenv("ANTHROPIC_API_KEY")
         base_url = base_url or os.getenv("ANTHROPIC_BASE_URL")
@@ -118,7 +118,9 @@ class Claude4_8Client(LLMClient):
         """Convert ToolChoice to Claude's tool_choice format."""
         if isinstance(tool_choice, list):
             if len(tool_choice) > 1:
-                raise ValueError("Claude supports only one tool choice.")
+                raise UnsupportedParameterError(
+                    self.__class__.__name__, "tool_choice", "Claude supports only one tool choice."
+                )
 
             return {"type": "any", "name": tool_choice[0]}
         elif tool_choice == "none":
@@ -149,7 +151,9 @@ class Claude4_8Client(LLMClient):
             claude_config["max_tokens"] = 64000  # Claude requires max_tokens to be specified
 
         if config.get("temperature") is not None and config["temperature"] != 1.0:
-            raise ValueError("Claude 4.8 does not support setting temperature.")
+            raise UnsupportedParameterError(
+                self.__class__.__name__, "temperature", "Claude 4.8 does not support setting temperature."
+            )
 
         if config.get("thinking_level") is not None:
             claude_config.update(self._convert_thinking_level_to_thinking_config(config["thinking_level"]))
@@ -204,10 +208,14 @@ class Claude4_8Client(LLMClient):
                     content_blocks.append(await self._convert_image_url_to_source(item["image_url"]))
                 elif item["type"] == "thinking":
                     if item["thinking"] == REDACTED_THINKING:
-                        content_blocks.append({"type": "redacted_thinking", "data": item["signature"]})
+                        content_blocks.append({"type": "redacted_thinking", "data": item["fidelity"]["signature"]})
                     else:
                         content_blocks.append(
-                            {"type": "thinking", "thinking": item["thinking"], "signature": item["signature"]}
+                            {
+                                "type": "thinking",
+                                "thinking": item["thinking"],
+                                "signature": item["fidelity"]["signature"],
+                            }
                         )
                 elif item["type"] == "tool_call":
                     content_blocks.append(
@@ -263,7 +271,9 @@ class Claude4_8Client(LLMClient):
                     {"type": "partial_tool_call", "name": block.name, "arguments": "", "tool_call_id": block.id}
                 )
             elif block.type == "redacted_thinking":
-                content_items.append({"type": "thinking", "thinking": REDACTED_THINKING, "signature": block.data})
+                content_items.append(
+                    {"type": "thinking", "thinking": REDACTED_THINKING, "fidelity": {"signature": block.data}}
+                )
 
         elif claude_event_type == "content_block_delta":
             event_type = "delta"
@@ -277,7 +287,7 @@ class Claude4_8Client(LLMClient):
                     {"type": "partial_tool_call", "name": "", "arguments": delta.partial_json, "tool_call_id": ""}
                 )
             elif delta.type == "signature_delta":
-                content_items.append({"type": "thinking", "thinking": "", "signature": delta.signature})
+                content_items.append({"type": "thinking", "thinking": "", "fidelity": {"signature": delta.signature}})
 
         elif claude_event_type == "content_block_stop":
             event_type = "stop"
@@ -403,7 +413,12 @@ class Claude4_8Client(LLMClient):
                             {
                                 "type": "tool_call",
                                 "name": partial_tool_call["name"],
-                                "arguments": json.loads(partial_tool_call["arguments"]),
+                                "arguments": parse_tool_call_arguments(
+                                    partial_tool_call["arguments"],
+                                    self.__class__.__name__,
+                                    partial_tool_call["name"],
+                                    partial_tool_call["tool_call_id"],
+                                ),
                                 "tool_call_id": partial_tool_call["tool_call_id"],
                             }
                         ],

{agenthub_python-0.3.3 → agenthub_python-0.4.1}/agenthub/deepseek_v4/client.py

@@ -20,6 +20,7 @@ from openai import AsyncOpenAI
 from openai.types.chat import ChatCompletionChunk, ChatCompletionMessageParam
 
 from ..base_client import LLMClient
+from ..errors import UnsupportedParameterError, parse_tool_call_arguments
 from ..types import (
     EventType,
     FinishReason,
@@ -71,7 +72,9 @@ class DeepSeekV4Client(LLMClient):
         """Convert ToolChoice to DeepSeek's OpenAI-compatible tool_choice format."""
         if tool_choice in ["auto", "none"]:
             return tool_choice
-        raise ValueError("DeepSeek V4 only supports 'auto' and 'none' for tool_choice.")
+        raise UnsupportedParameterError(
+            self.__class__.__name__, "tool_choice", "DeepSeek V4 only supports 'auto' and 'none' for tool_choice."
+        )
 
     def transform_uni_config_to_model_config(self, config: UniConfig) -> dict[str, Any]:
         """
@@ -89,7 +92,9 @@ class DeepSeekV4Client(LLMClient):
             deepseek_config["max_tokens"] = config["max_tokens"]
 
         if config.get("temperature") is not None and config["temperature"] != 1.0:
-            raise ValueError("DeepSeek V4 does not support setting temperature.")
+            raise UnsupportedParameterError(
+                self.__class__.__name__, "temperature", "DeepSeek V4 does not support setting temperature."
+            )
 
         thinking_level = config.get("thinking_level")
         if thinking_level is not None:
@@ -105,7 +110,9 @@ class DeepSeekV4Client(LLMClient):
             deepseek_config["tool_choice"] = self._convert_tool_choice(config["tool_choice"])
 
         if config.get("prompt_caching") is not None and config["prompt_caching"] != PromptCaching.ENABLE:
-            raise ValueError("prompt_caching must be ENABLE for DeepSeek.")
+            raise UnsupportedParameterError(
+                self.__class__.__name__, "prompt_caching", "prompt_caching must be ENABLE for DeepSeek."
+            )
 
         return deepseek_config
 
@@ -200,7 +207,15 @@ class DeepSeekV4Client(LLMClient):
 
             if getattr(delta, "reasoning_content", None):
                 event_type = "delta"
-                content_items.append({"type": "thinking", "thinking": getattr(delta, "reasoning_content")})
+                # record the wire field so a replay through another OpenAI-compatible
+                # client reproduces the exact field DeepSeek produced
+                content_items.append(
+                    {
+                        "type": "thinking",
+                        "thinking": getattr(delta, "reasoning_content"),
+                        "fidelity": {"reasoning_field": "reasoning_content"},
+                    }
+                )
 
             if delta.content:
                 event_type = "delta"
@@ -289,7 +304,12 @@ class DeepSeekV4Client(LLMClient):
                                     {
                                         "type": "tool_call",
                                         "name": partial_tool_call["name"],
-                                        "arguments": json.loads(partial_tool_call["arguments"] or "{}"),
+                                        "arguments": parse_tool_call_arguments(
+                                            partial_tool_call["arguments"],
+                                            self.__class__.__name__,
+                                            partial_tool_call["name"],
+                                            partial_tool_call["tool_call_id"],
+                                        ),
                                         "tool_call_id": partial_tool_call["tool_call_id"],
                                     }
                                 ],
@@ -317,7 +337,12 @@ class DeepSeekV4Client(LLMClient):
                             {
                                 "type": "tool_call",
                                 "name": partial_tool_call["name"],
-                                "arguments": json.loads(partial_tool_call["arguments"] or "{}"),
+                                "arguments": parse_tool_call_arguments(
+                                    partial_tool_call["arguments"],
+                                    self.__class__.__name__,
+                                    partial_tool_call["name"],
+                                    partial_tool_call["tool_call_id"],
+                                ),
                                 "tool_call_id": partial_tool_call["tool_call_id"],
                             }
                         ],

agenthub_python-0.4.1/agenthub/errors.py

@@ -0,0 +1,89 @@
+# Copyright 2025 Prism Shadow. and/or its affiliates
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import json
+from typing import Any
+
+
+def _preview_tool_call_arguments(raw: str) -> str:
+    max_length = 160
+    if len(raw) <= max_length:
+        return raw
+
+    edge_length = 72
+    return f"{raw[:edge_length]}...[truncated]...{raw[-edge_length:]}"
+
+
+class AgentHubError(ValueError):
+    """Base class for errors raised by AgentHub clients."""
+
+
+class UnsupportedParameterError(AgentHubError):
+    """Raised when a UniConfig parameter value is not supported by the target model client.
+
+    Thinking levels never raise this by design: every client maps each ThinkingLevel
+    onto the closest level the model supports. Parameters such as temperature and
+    tool_choice may reject unsupported values with this error.
+    """
+
+    def __init__(self, client: str, parameter: str, message: str) -> None:
+        self.client = client
+        self.parameter = parameter
+        super().__init__(message)
+
+
+class EmptyResponseError(AgentHubError):
+    """Raised when a completed response carries no non-thinking content and no tool calls.
+
+    Models occasionally finish a turn with thinking output only (reasoning models in
+    particular); replaying such an assistant message on the next turn fails with a 400
+    error, so the response is rejected as soon as the stream completes.
+    """
+
+    def __init__(self, client: str, finish_reason: str | None) -> None:
+        self.client = client
+        self.finish_reason = finish_reason
+        super().__init__(f"{client} returned no content other than thinking (finish_reason={finish_reason!r}).")
+
+
+class ToolCallArgumentParseError(AgentHubError):
+    def __init__(self, client: str, tool_name: str, tool_call_id: str, raw_arguments: str, reason: str) -> None:
+        self.client = client
+        self.tool_name = tool_name
+        self.tool_call_id = tool_call_id
+        self.raw_arguments_length = len(raw_arguments)
+        self.raw_arguments_preview = _preview_tool_call_arguments(raw_arguments)
+        super().__init__(
+            f'Invalid streamed tool call arguments from {client} for tool "{tool_name}" '
+            f'(tool_call_id="{tool_call_id}", length={self.raw_arguments_length}, '
+            f"preview={self.raw_arguments_preview!r}): {reason}"
+        )
+
+
+def parse_tool_call_arguments(
+    raw_arguments: str | None,
+    client: str,
+    tool_name: str,
+    tool_call_id: str,
+) -> dict[str, Any]:
+    raw = raw_arguments or "{}"
+    try:
+        parsed = json.loads(raw)
+    except (TypeError, ValueError) as exc:
+        raise ToolCallArgumentParseError(client, tool_name, tool_call_id, raw, str(exc)) from exc
+
+    if not isinstance(parsed, dict):
+        raise ToolCallArgumentParseError(client, tool_name, tool_call_id, raw, "Expected a JSON object.")
+
+    return parsed