agenthub-python 0.4.4__tar.gz → 0.4.5__tar.gz

{agenthub_python-0.4.4 → agenthub_python-0.4.5}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: agenthub-python
-Version: 0.4.4
+Version: 0.4.5
 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
@@ -14,6 +14,7 @@ Requires-Dist: httpx[socks] ; extra == 'dev'
 Requires-Dist: pytest>=8.4.2 ; extra == 'dev'
 Requires-Dist: pytest-asyncio>=0.23.0 ; extra == 'dev'
 Requires-Dist: pytest-xdist>=3.6.0 ; extra == 'dev'
+Requires-Dist: pytest-rerunfailures>=15.0 ; extra == 'dev'
 Requires-Dist: ruff>=0.14.3 ; extra == 'dev'
 Requires-Dist: pillow>=10.0.0 ; extra == 'dev'
 Requires-Python: >=3.11

{agenthub_python-0.4.4 → agenthub_python-0.4.5}/agenthub/__init__.py

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

{agenthub_python-0.4.4 → agenthub_python-0.4.5}/agenthub/ant_messages/client.py

@@ -33,7 +33,7 @@ from ..types import (
     UniMessage,
     UsageMetadata,
 )
-from ..utils import fix_openrouter_usage_metadata
+from ..utils import fix_openrouter_usage_metadata, is_debug_enabled
 
 
 REDACTED_THINKING = "_REDACTED_THINKING"
@@ -42,14 +42,22 @@ REDACTED_THINKING = "_REDACTED_THINKING"
 class AntMessagesClient(LLMClient):
     """Anthropic Messages-compatible client implementation."""
 
-    def __init__(self, model: str, api_key: str | None = None, base_url: str | None = None):
+    def __init__(
+        self,
+        model: str,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        default_headers: dict[str, str] | None = None,
+    ):
         """Initialize Anthropic Messages-compatible client with model, API key, and base URL."""
         self._model = model
         api_key = api_key or os.getenv("ANTHROPIC_API_KEY")
         base_url = base_url or os.getenv("ANTHROPIC_BASE_URL")
         # send the credential through both header conventions: Anthropic and DeepSeek read
         # x-api-key while gateways such as OpenRouter and Z.AI read Authorization: Bearer
-        self._client = AsyncAnthropic(api_key=api_key, auth_token=api_key, base_url=base_url)
+        self._client = AsyncAnthropic(
+            api_key=api_key, auth_token=api_key, base_url=base_url, default_headers=default_headers
+        )
         self._history: list[UniMessage] = []
 
     def _convert_image_url_to_source(self, url: str) -> dict[str, Any]:
@@ -306,9 +314,14 @@ class AntMessagesClient(LLMClient):
             # gateways that relabel it onto another event
             event_type = "unused"
 
-        else:
+        elif is_debug_enabled():
             raise ValueError(f"Unknown output: {model_output}")
 
+        else:
+            # a gateway injects its own events (heartbeats, cost tickers) into the stream, and
+            # killing a long generation over one costs more than dropping it
+            event_type = "unused"
+
         return {
             "role": "assistant",
             "event_type": event_type,
@@ -412,3 +425,12 @@ class AntMessagesClient(LLMClient):
                         "finish_reason": event["finish_reason"],
                     }
                     partial_usage = {}
+
+    async def list_models(self) -> list[str]:
+        """
+        List the model ids the configured endpoint serves.
+
+        Returns:
+            list[str]: The model ids, in the order the endpoint returned them.
+        """
+        return [model.id async for model in self._client.models.list()]

{agenthub_python-0.4.4 → agenthub_python-0.4.5}/agenthub/auto_client.py

@@ -20,6 +20,10 @@ from .base_client import LLMClient
 from .types import UniConfig, UniEvent, UniMessage
 
 
+# The generic protocol clients are named explicitly rather than deduced from a model id.
+_PROTOCOL_CLIENT_TYPES = ("openai-chat", "openai-responses", "ant-messages", "openai-embedding")
+
+
 class AutoLLMClient(LLMClient):
     """
     Auto-routing LLM client that dispatches to appropriate model-specific client.
@@ -29,7 +33,12 @@ class AutoLLMClient(LLMClient):
     """
 
     def __init__(
-        self, model: str, api_key: str | None = None, base_url: str | None = None, client_type: str | None = None
+        self,
+        model: str,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        client_type: str | None = None,
+        default_headers: dict[str, str] | None = None,
     ):
         """
         Initialize AutoLLMClient with a specific model.
@@ -39,14 +48,22 @@ class AutoLLMClient(LLMClient):
             api_key: Optional API key
             base_url: Optional base URL for API requests
             client_type: Optional client type override
+            default_headers: Optional headers sent with every request, for endpoints that demand their own
         """
-        self._client = self._create_client_for_model(model, api_key, base_url, client_type)
+        self._client_type = (client_type or os.getenv("CLIENT_TYPE") or model).lower()
+        self._client = self._create_client_for_model(model, api_key, base_url, self._client_type, default_headers)
 
-    def _create_client_for_model(
-        self, model: str, api_key: str | None = None, base_url: str | None = None, client_type: str | None = None
-    ) -> LLMClient:
-        """Create the appropriate client for the given model."""
-        client_type = (client_type or os.getenv("CLIENT_TYPE") or model).lower()
+    @staticmethod
+    def _client_class_for_model(client_type: str) -> type[LLMClient] | None:
+        """
+        Resolve which client a resolved (lowercased) client type routes to.
+
+        Args:
+            client_type: The resolved client type, which is the model id when none was given.
+
+        Returns:
+            type[LLMClient] | None: The client class, or None when no client claims the type.
+        """
         # every Gemini generation shares the unified client ("gemini-3" also matches the
         # gemini-3.7/gemini-3.6/gemini-3.5-flash-lite client types)
         if any(
@@ -54,51 +71,64 @@ class AutoLLMClient(LLMClient):
         ):  # e.g., gemini-3.7-flash, gemini-3-flash-preview, gemini-embedding-2
             from .gemini3_7 import Gemini3_7Client
 
-            return Gemini3_7Client(model=model, api_key=api_key, base_url=base_url)
+            return Gemini3_7Client
         elif "claude" in client_type and (
             "4-6" in client_type or "4-7" in client_type or "4-8" in client_type or "-5" in client_type
         ):  # the whole Claude 4.6+ series shares the unified client, e.g., claude-sonnet-4-6
             from .claude5 import Claude5Client
 
-            return Claude5Client(model=model, api_key=api_key, base_url=base_url)
+            return Claude5Client
         elif "gpt-5.4" in client_type or "gpt-5.5" in client_type or "gpt-5.6" in client_type:  # e.g., gpt-5.6
             from .gpt5_6 import GPT5_6Client
 
-            return GPT5_6Client(model=model, api_key=api_key, base_url=base_url)
+            return GPT5_6Client
         elif "glm-5" in client_type:  # the whole GLM series shares the unified client
             from .glm5_3 import GLM5_3Client
 
-            return GLM5_3Client(model=model, api_key=api_key, base_url=base_url)
+            return GLM5_3Client
         elif "kimi-k3" in client_type or "kimi-k2.5" in client_type or "kimi-k2.6" in client_type:
             # the whole Kimi K2.5+ series shares the unified client
             from .kimi_k3 import KimiK3Client
 
-            return KimiK3Client(model=model, api_key=api_key, base_url=base_url)
+            return KimiK3Client
         elif client_type == "minimax-m3":
             from .minimax_m3 import MiniMaxM3Client
 
-            return MiniMaxM3Client(model=model, api_key=api_key, base_url=base_url)
+            return MiniMaxM3Client
         elif "deepseek-v4" in client_type:
             from .deepseek_v4 import DeepSeekV4Client
 
-            return DeepSeekV4Client(model=model, api_key=api_key, base_url=base_url)
+            return DeepSeekV4Client
         elif "ant-messages" in client_type:
             from .ant_messages import AntMessagesClient
 
-            return AntMessagesClient(model=model, api_key=api_key, base_url=base_url)
+            return AntMessagesClient
         elif "openai-responses" in client_type:
             from .openai_responses import OpenaiResponsesClient
 
-            return OpenaiResponsesClient(model=model, api_key=api_key, base_url=base_url)
+            return OpenaiResponsesClient
         elif "openai" in client_type and "embedding" in client_type:
             from .openai_embedding import OpenaiEmbeddingClient
 
-            return OpenaiEmbeddingClient(model=model, api_key=api_key, base_url=base_url)
+            return OpenaiEmbeddingClient
         elif "openai" in client_type and "embedding" not in client_type:  # openai-chat, plus bare "openai" as alias
             from .openai_chat import OpenaiChatClient
 
-            return OpenaiChatClient(model=model, api_key=api_key, base_url=base_url)
+            return OpenaiChatClient
         else:
+            return None
+
+    def _create_client_for_model(
+        self,
+        model: str,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        client_type: str | None = None,
+        default_headers: dict[str, str] | None = None,
+    ) -> LLMClient:
+        """Create the appropriate client for the given model."""
+        client_class = self._client_class_for_model(client_type or model.lower())
+        if client_class is None:
             raise ValueError(
                 f"{client_type} is not supported. "
                 "Supported client types: minimax-m3, gemini-3.7, gemini-3.6, gemini-3, "
@@ -107,6 +137,8 @@ class AutoLLMClient(LLMClient):
                 "openai-embedding, ant-messages, openai-responses, openai-chat."
             )
 
+        return client_class(model=model, api_key=api_key, base_url=base_url, default_headers=default_headers)
+
     def transform_uni_config_to_model_config(self, config: UniConfig) -> Any:
         """Delegate to underlying client's transform_uni_config_to_model_config."""
         return self._client.transform_uni_config_to_model_config(config)
@@ -165,3 +197,22 @@ class AutoLLMClient(LLMClient):
     def set_history(self, history: list[UniMessage]) -> None:
         """Set history in the underlying client."""
         self._client.set_history(history)
+
+    async def list_models(self) -> list[str]:
+        """
+        List the model ids the endpoint serves that the routed client can be used for.
+
+        A protocol client is chosen explicitly and speaks for whatever the endpoint serves, so its
+        listing is returned whole. A client deduced from a model id serves only the ids that deduce
+        back to it, so a gateway fronting many vendors is filtered down to that client's own models.
+
+        Returns:
+            list[str]: The model ids, in the order the endpoint returned them.
+        """
+        model_ids = await self._client.list_models()
+        protocol_classes = {self._client_class_for_model(name) for name in _PROTOCOL_CLIENT_TYPES}
+        if type(self._client) in protocol_classes:
+            return model_ids
+
+        client_class = type(self._client)
+        return [model_id for model_id in model_ids if self._client_class_for_model(model_id.lower()) is client_class]

{agenthub_python-0.4.4 → agenthub_python-0.4.5}/agenthub/base_client.py

@@ -175,6 +175,15 @@ class LLMClient(ABC):
         """
         pass
 
+    @abstractmethod
+    async def list_models(self) -> list[str]:
+        """
+        List the model ids the configured endpoint serves.
+
+        Returns:
+            list[str]: The model ids, in the order the endpoint returned them.
+        """
+
     async def streaming_response(
         self,
         messages: list[UniMessage],

{agenthub_python-0.4.4 → agenthub_python-0.4.5}/agenthub/claude5/client.py

@@ -23,7 +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 ..errors import UnsupportedOperationError, UnsupportedParameterError, parse_tool_call_arguments
 from ..types import (
     EventType,
     FinishReason,
@@ -36,6 +36,7 @@ from ..types import (
     UniMessage,
     UsageMetadata,
 )
+from ..utils import is_debug_enabled
 
 
 REDACTED_THINKING = "_REDACTED_THINKING"
@@ -44,7 +45,13 @@ REDACTED_THINKING = "_REDACTED_THINKING"
 class Claude5Client(LLMClient):
     """Claude 5-specific LLM client implementation (also serves Claude 4.6 through 4.8)."""
 
-    def __init__(self, model: str, api_key: str | None = None, base_url: str | None = None):
+    def __init__(
+        self,
+        model: str,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        default_headers: dict[str, str] | None = None,
+    ):
         """Initialize Claude 5 client with model and API key."""
         self._model = model
         api_key = api_key or os.getenv("ANTHROPIC_API_KEY")
@@ -53,11 +60,14 @@ class Claude5Client(LLMClient):
             region = base_url.replace("bedrock://", "")
             access_key, secret_key = api_key.split(",")
             self._client = AsyncAnthropicBedrock(
-                aws_secret_key=secret_key, aws_access_key=access_key, aws_region=region
+                aws_secret_key=secret_key,
+                aws_access_key=access_key,
+                aws_region=region,
+                default_headers=default_headers,
             )
             self._use_bedrock = True
         else:
-            self._client = AsyncAnthropic(api_key=api_key, base_url=base_url)
+            self._client = AsyncAnthropic(api_key=api_key, base_url=base_url, default_headers=default_headers)
             self._use_bedrock = False
 
         self._history: list[UniMessage] = []
@@ -356,9 +366,14 @@ class Claude5Client(LLMClient):
             # gateways that relabel it onto another event
             event_type = "unused"
 
-        else:
+        elif is_debug_enabled():
             raise ValueError(f"Unknown output: {model_output}")
 
+        else:
+            # a gateway injects its own events (heartbeats, cost tickers) into the stream, and
+            # killing a long generation over one costs more than dropping it
+            event_type = "unused"
+
         return {
             "role": "assistant",
             "event_type": event_type,
@@ -467,3 +482,17 @@ class Claude5Client(LLMClient):
                         "finish_reason": event["finish_reason"],
                     }
                     partial_usage = {}
+
+    async def list_models(self) -> list[str]:
+        """
+        List the model ids the configured endpoint serves.
+
+        Returns:
+            list[str]: The model ids, in the order the endpoint returned them.
+        """
+        if self._use_bedrock:
+            raise UnsupportedOperationError(
+                self.__class__.__name__, "list_models", "Bedrock does not support listing models."
+            )
+
+        return [model.id async for model in self._client.models.list()]

{agenthub_python-0.4.4 → agenthub_python-0.4.5}/agenthub/deepseek_v4/client.py

@@ -38,12 +38,18 @@ from ..types import (
 class DeepSeekV4Client(LLMClient):
     """DeepSeek V4-specific LLM client implementation using OpenAI-compatible Chat Completions."""
 
-    def __init__(self, model: str, api_key: str | None = None, base_url: str | None = None):
+    def __init__(
+        self,
+        model: str,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        default_headers: dict[str, str] | None = None,
+    ):
         """Initialize DeepSeek client with model, API key, and base URL."""
         self._model = model
         api_key = api_key or os.getenv("DEEPSEEK_API_KEY")
         base_url = base_url or os.getenv("DEEPSEEK_BASE_URL") or "https://api.deepseek.com"
-        self._client = AsyncOpenAI(api_key=api_key, base_url=base_url)
+        self._client = AsyncOpenAI(api_key=api_key, base_url=base_url, default_headers=default_headers)
         self._history: list[UniMessage] = []
 
     def _convert_thinking_level_to_config(self, thinking_level: ThinkingLevel) -> dict[str, str]:
@@ -374,3 +380,12 @@ class DeepSeekV4Client(LLMClient):
                         "finish_reason": partial_usage["finish_reason"],
                     }
                     partial_usage = {}
+
+    async def list_models(self) -> list[str]:
+        """
+        List the model ids the configured endpoint serves.
+
+        Returns:
+            list[str]: The model ids, in the order the endpoint returned them.
+        """
+        return [model.id async for model in self._client.models.list()]

{agenthub_python-0.4.4 → agenthub_python-0.4.5}/agenthub/errors.py

@@ -43,6 +43,20 @@ class UnsupportedParameterError(AgentHubError):
         super().__init__(message)
 
 
+class UnsupportedOperationError(AgentHubError):
+    """Raised when a client cannot perform an operation at all, whatever it is passed.
+
+    Distinct from UnsupportedParameterError, which rejects a UniConfig parameter value:
+    this one reports a capability the routed client does not have, such as listing models
+    through an SDK client that carries no models endpoint.
+    """
+
+    def __init__(self, client: str, operation: str, message: str) -> None:
+        self.client = client
+        self.operation = operation
+        super().__init__(message)
+
+
 class EmptyResponseError(AgentHubError):
     """Raised when a completed response carries no non-thinking content and no tool calls.
 

{agenthub_python-0.4.4 → agenthub_python-0.4.5}/agenthub/gemini3_7/client.py

@@ -17,7 +17,7 @@ import json
 import mimetypes
 import os
 import re
-from typing import AsyncIterator
+from typing import Any, AsyncIterator
 
 import httpx
 from google import genai
@@ -40,6 +40,7 @@ from ..types import (
     UniMessage,
     UsageMetadata,
 )
+from ..utils import is_debug_enabled
 
 
 class Gemini3_7Client(LLMClient):
@@ -52,12 +53,23 @@ class Gemini3_7Client(LLMClient):
     applies that contract to the whole family: temperature is rejected everywhere.
     """
 
-    def __init__(self, model: str, api_key: str | None = None, base_url: str | None = None):
+    def __init__(
+        self,
+        model: str,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        default_headers: dict[str, str] | None = None,
+    ):
         """Initialize Gemini 3.7 client with model and API key."""
         self._model = model
         api_key = api_key or os.getenv("GEMINI_API_KEY")
         base_url = base_url or os.getenv("GEMINI_BASE_URL")
-        http_options = {"base_url": base_url} if base_url else None
+        # the Gemini SDK carries connection headers inside http_options rather than its own argument
+        http_options: dict[str, Any] = {}
+        if base_url:
+            http_options["base_url"] = base_url
+        if default_headers:
+            http_options["headers"] = default_headers
         if api_key and api_key.startswith("{"):
             service_account_info = json.loads(api_key)
             credentials = service_account.Credentials.from_service_account_info(
@@ -68,10 +80,10 @@ class Gemini3_7Client(LLMClient):
                 credentials=credentials,
                 project=service_account_info["project_id"],
                 location="global",
-                http_options=http_options,
+                http_options=http_options or None,
             )
         else:
-            self._client = genai.Client(api_key=api_key, http_options=http_options)
+            self._client = genai.Client(api_key=api_key, http_options=http_options or None)
 
         self._history: list[UniMessage] = []
 
@@ -417,7 +429,7 @@ class Gemini3_7Client(LLMClient):
                     )
                 elif part.text is not None:
                     content_items.append({"type": "text", "text": part.text, **self._part_fidelity(part)})
-                else:
+                elif is_debug_enabled():
                     raise ValueError(f"Unknown output: {part}")
 
             if candidate.finish_reason:
@@ -543,3 +555,13 @@ class Gemini3_7Client(LLMClient):
                     }
 
             yield event
+
+    async def list_models(self) -> list[str]:
+        """
+        List the model ids the configured endpoint serves.
+
+        Returns:
+            list[str]: The model ids, in the order the endpoint returned them.
+        """
+        # the API returns path-qualified names: models/gemini-3.7-flash, publishers/google/models/...
+        return [model.name.split("/")[-1] async for model in await self._client.aio.models.list() if model.name]

{agenthub_python-0.4.4 → agenthub_python-0.4.5}/agenthub/glm5_3/client.py

@@ -43,12 +43,18 @@ class GLM5_3Client(LLMClient):
     contract differs per generation, handled model-by-model below.
     """
 
-    def __init__(self, model: str, api_key: str | None = None, base_url: str | None = None):
+    def __init__(
+        self,
+        model: str,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        default_headers: dict[str, str] | None = None,
+    ):
         """Initialize GLM client with model and API key."""
         self._model = model
         api_key = api_key or os.getenv("ZAI_API_KEY")
         base_url = base_url or os.getenv("ZAI_BASE_URL") or "https://api.z.ai/api/paas/v4/"
-        self._client = AsyncOpenAI(api_key=api_key, base_url=base_url)
+        self._client = AsyncOpenAI(api_key=api_key, base_url=base_url, default_headers=default_headers)
         self._history: list[UniMessage] = []
 
     def _convert_thinking_level_to_config(self, thinking_level: ThinkingLevel) -> dict[str, str | bool]:
@@ -437,3 +443,12 @@ class GLM5_3Client(LLMClient):
                         "finish_reason": partial_usage["finish_reason"],
                     }
                     partial_usage = {}
+
+    async def list_models(self) -> list[str]:
+        """
+        List the model ids the configured endpoint serves.
+
+        Returns:
+            list[str]: The model ids, in the order the endpoint returned them.
+        """
+        return [model.id async for model in self._client.models.list()]

{agenthub_python-0.4.4 → agenthub_python-0.4.5}/agenthub/gpt5_6/client.py

@@ -33,17 +33,24 @@ from ..types import (
     UniMessage,
     UsageMetadata,
 )
+from ..utils import is_debug_enabled
 
 
 class GPT5_6Client(LLMClient):
     """GPT-5.6-specific LLM client implementation (also serves GPT-5.4 and GPT-5.5)."""
 
-    def __init__(self, model: str, api_key: str | None = None, base_url: str | None = None):
+    def __init__(
+        self,
+        model: str,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        default_headers: dict[str, str] | None = None,
+    ):
         """Initialize GPT-5.6 client with model and API key."""
         self._model = model
         api_key = api_key or os.getenv("OPENAI_API_KEY")
         base_url = base_url or os.getenv("OPENAI_BASE_URL")
-        self._client = AsyncOpenAI(api_key=api_key, base_url=base_url)
+        self._client = AsyncOpenAI(api_key=api_key, base_url=base_url, default_headers=default_headers)
         self._history: list[UniMessage] = []
 
     def _convert_thinking_level_to_effort(self, thinking_level: ThinkingLevel) -> str:
@@ -306,9 +313,14 @@ class GPT5_6Client(LLMClient):
         ]:
             event_type = "unused"
 
-        else:
+        elif is_debug_enabled():
             raise ValueError(f"Unknown output: {model_output}")
 
+        else:
+            # a gateway injects its own events (heartbeats, cost tickers) into the stream, and
+            # killing a long generation over one costs more than dropping it
+            event_type = "unused"
+
         return {
             "role": "assistant",
             "event_type": event_type,
@@ -377,3 +389,12 @@ class GPT5_6Client(LLMClient):
 
                 if event["finish_reason"] or event["usage_metadata"]:
                     yield event
+
+    async def list_models(self) -> list[str]:
+        """
+        List the model ids the configured endpoint serves.
+
+        Returns:
+            list[str]: The model ids, in the order the endpoint returned them.
+        """
+        return [model.id async for model in self._client.models.list()]