agenthub-python 0.1.0__py3-none-any.whl

agenthub/__init__.py

@@ -0,0 +1,20 @@
+# 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 .auto_client import AutoLLMClient
+from .tracer import Tracer
+from .types import ThinkingLevel
+
+
+__all__ = ["AutoLLMClient", "ThinkingLevel", "Tracer"]

agenthub/auto_client.py

@@ -0,0 +1,96 @@
+# 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 typing import Any, AsyncIterator
+
+from .base_client import LLMClient
+from .types import UniConfig, UniEvent, UniMessage
+
+
+class AutoLLMClient(LLMClient):
+    """
+    Auto-routing LLM client that dispatches to appropriate model-specific client.
+
+    This client is stateful - it knows the model name at initialization and maintains
+    conversation history for that specific model.
+    """
+
+    def __init__(self, model: str, api_key: str | None = None):
+        """
+        Initialize AutoLLMClient with a specific model.
+
+        Args:
+            model: Model identifier (determines which client to use)
+            api_key: Optional API key
+        """
+        self._client = self._create_client_for_model(model, api_key)
+
+    def _create_client_for_model(self, model: str, api_key: str | None = None) -> LLMClient:
+        """Create the appropriate client for the given model."""
+        if "gemini-3" in model.lower():  # e.g., gemini-3-flash-preview
+            from .gemini3 import Gemini3Client
+
+            return Gemini3Client(model=model, api_key=api_key)
+        elif "claude" in model.lower() and "4-5" in model.lower():  # e.g., claude-sonnet-4-5
+            from .claude4_5 import Claude4_5Client
+
+            return Claude4_5Client(model=model, api_key=api_key)
+        elif "gpt-5.2" in model.lower():  # e.g., gpt-5.2
+            raise NotImplementedError("GPT models not yet implemented.")
+        else:
+            raise ValueError(f"{model} is not supported.")
+
+    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)
+
+    def transform_uni_message_to_model_input(self, messages: list[UniMessage]) -> Any:
+        """Delegate to underlying client's transform_uni_message_to_model_input."""
+        return self._client.transform_uni_message_to_model_input(messages)
+
+    def transform_model_output_to_uni_event(self, model_output: Any) -> UniEvent:
+        """Delegate to underlying client's transform_model_output_to_uni_event."""
+        return self._client.transform_model_output_to_uni_event(model_output)
+
+    async def streaming_response(
+        self,
+        messages: list[UniMessage],
+        config: UniConfig,
+    ) -> AsyncIterator[UniEvent]:
+        """Route to underlying client's streaming_response."""
+        async for event in self._client.streaming_response(
+            messages=messages,
+            config=config,
+        ):
+            yield event
+
+    async def streaming_response_stateful(
+        self,
+        message: UniMessage,
+        config: UniConfig,
+    ) -> AsyncIterator[UniEvent]:
+        """Route to underlying client's streaming_response_stateful."""
+        async for event in self._client.streaming_response_stateful(
+            message=message,
+            config=config,
+        ):
+            yield event
+
+    def clear_history(self) -> None:
+        """Clear history in the underlying client."""
+        self._client.clear_history()
+
+    def get_history(self) -> list[UniMessage]:
+        """Get history from the underlying client."""
+        return self._client.get_history()

agenthub/base_client.py

@@ -0,0 +1,185 @@
+# 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 abc import ABC, abstractmethod
+from typing import Any, AsyncIterator
+
+from .types import ContentItem, FinishReason, UniConfig, UniEvent, UniMessage, UsageMetadata
+
+
+class LLMClient(ABC):
+    """
+    Abstract base class for LLM clients.
+
+    All model-specific clients must inherit from this class and implement
+    the required abstract methods for complete SDK abstraction.
+    """
+
+    _history: list[UniMessage] = []
+
+    @abstractmethod
+    def transform_uni_config_to_model_config(self, config: UniConfig) -> Any:
+        """
+        Transform universal configuration to model-specific configuration.
+
+        Args:
+            config: Universal configuration dict
+
+        Returns:
+            Model-specific configuration object
+        """
+        pass
+
+    @abstractmethod
+    def transform_uni_message_to_model_input(self, messages: list[UniMessage]) -> Any:
+        """
+        Transform universal message format to model-specific input format.
+
+        Args:
+            messages: List of universal message dictionaries
+
+        Returns:
+            Model-specific input format (e.g., Gemini's Content list, OpenAI's messages array)
+        """
+        pass
+
+    @abstractmethod
+    def transform_model_output_to_uni_event(self, model_output: Any) -> UniEvent:
+        """
+        Transform model output to universal event format.
+
+        Args:
+            model_output: Model-specific output object (streaming chunk)
+
+        Returns:
+            Universal event dictionary
+        """
+        pass
+
+    def concat_uni_events_to_uni_message(self, events: list[UniEvent]) -> UniMessage:
+        """
+        Concatenate a stream of universal events into a single universal message.
+
+        This is a concrete method implemented in the base class that can be reused
+        by all model clients. It accumulates events and builds a complete message.
+
+        Args:
+            events: List of universal events from streaming response
+
+        Returns:
+            Complete universal message dictionary
+        """
+        content_items: list[ContentItem] = []
+        usage_metadata: UsageMetadata | None = None
+        finish_reason: FinishReason | None = None
+
+        for event in events:
+            # Merge content_items from all events
+            for item in event["content_items"]:
+                if item["type"] == "text":
+                    if content_items and content_items[-1]["type"] == "text":
+                        content_items[-1]["text"] += item["text"]
+                        if "signature" in item:  # signature may appear at the last item
+                            content_items[-1]["signature"] = item["signature"]
+                    elif item["text"]:  # omit empty text items
+                        content_items.append(item.copy())
+                elif item["type"] == "thinking":
+                    if content_items and content_items[-1]["type"] == "thinking":
+                        content_items[-1]["thinking"] += item["thinking"]
+                        if "signature" in item:  # signature may appear at the last item
+                            content_items[-1]["signature"] = item["signature"]
+                    elif item["thinking"]:  # omit empty thinking items
+                        content_items.append(item.copy())
+                else:
+                    content_items.append(item.copy())
+
+            usage_metadata = event.get("usage_metadata")  # usage_metadata is taken from the last event
+            finish_reason = event.get("finish_reason")  # finish_reason is taken from the last event
+
+        return {
+            "role": "assistant",
+            "content_items": content_items,
+            "usage_metadata": usage_metadata,
+            "finish_reason": finish_reason,
+        }
+
+    @abstractmethod
+    async def streaming_response(
+        self,
+        messages: list[UniMessage],
+        config: UniConfig,
+    ) -> AsyncIterator[UniEvent]:
+        """
+        Generate content in streaming mode (stateless).
+
+        This method should use transform_uni_config_to_model_config and
+        transform_uni_message_to_model_input to prepare the request, then
+        transform_model_output_to_uni_event to convert each chunk.
+
+        Args:
+            messages: List of universal message dictionaries containing conversation history
+            config: Universal configuration dict
+
+        Yields:
+            Universal events from the streaming response
+        """
+        pass
+
+    async def streaming_response_stateful(
+        self,
+        message: UniMessage,
+        config: UniConfig,
+    ) -> AsyncIterator[UniEvent]:
+        """
+        Generate content in streaming mode (stateful).
+
+        This method should use transform_uni_config_to_model_config,
+        transform_uni_message_to_model_input, transform_model_output_to_uni_event,
+        and transform_uni_event_to_uni_message to manage the conversation flow.
+
+        Args:
+            message: Latest universal message dictionary to add to conversation
+            config: Universal configuration dict
+
+        Yields:
+            Universal events from the streaming response
+        """
+        # Add user message to history
+        self._history.append(message)
+
+        # Collect all events for history
+        events = []
+        async for event in self.streaming_response(messages=self._history, config=config):
+            events.append(event)
+            yield event
+
+        # Convert events to message and add to history
+        if events:
+            assistant_message = self.concat_uni_events_to_uni_message(events)
+            self._history.append(assistant_message)
+
+        # Save history to file if trace_id is specified
+        if config.get("trace_id"):
+            from .tracer import Tracer
+
+            tracer = Tracer()
+            tracer.save_history(self._history, config["trace_id"], config)
+
+    def clear_history(self) -> None:
+        """Clear the message history."""
+        self._history.clear()
+
+    def get_history(self) -> list[UniMessage]:
+        """Get the current message history."""
+        return self._history.copy()

agenthub/claude4_5/__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 Claude4_5Client
+
+
+__all__ = ["Claude4_5Client"]

agenthub/claude4_5/client.py

@@ -0,0 +1,315 @@
+# 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
+import os
+from typing import Any, AsyncIterator
+
+from anthropic import AsyncAnthropic
+from anthropic.types import MessageParam, MessageStreamEvent
+
+from ..base_client import LLMClient
+from ..types import (
+    FinishReason,
+    PartialContentItem,
+    PartialUniEvent,
+    ThinkingLevel,
+    ToolChoice,
+    UniConfig,
+    UniEvent,
+    UniMessage,
+    UsageMetadata,
+)
+
+
+class Claude4_5Client(LLMClient):
+    """Claude 4.5-specific LLM client implementation."""
+
+    def __init__(self, model: str, api_key: str | None = None):
+        """Initialize Claude 4.5 client with model and API key."""
+        self._model = model
+        api_key = api_key or os.getenv("ANTHROPIC_API_KEY")
+        self._client = AsyncAnthropic(api_key=api_key)
+        self._history: list[UniMessage] = []
+
+    def _convert_thinking_level_to_budget(self, thinking_level: ThinkingLevel) -> dict:
+        """Convert ThinkingLevel enum to Claude's budget_tokens."""
+
+        mapping = {
+            ThinkingLevel.NONE: {"type": "disabled"},
+            ThinkingLevel.LOW: {"type": "enabled", "budget_tokens": 1024},
+            ThinkingLevel.MEDIUM: {"type": "enabled", "budget_tokens": 4096},
+            ThinkingLevel.HIGH: {"type": "enabled", "budget_tokens": 16384},
+        }
+        return mapping.get(thinking_level)
+
+    def _convert_tool_choice(self, tool_choice: ToolChoice) -> dict[str, Any]:
+        """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.")
+
+            return {"type": "any", "name": tool_choice[0]}
+        elif tool_choice == "none":
+            return {"type": "none"}
+        elif tool_choice == "auto":
+            return {"type": "auto"}
+        elif tool_choice == "required":
+            return {"type": "any"}
+
+    def transform_uni_config_to_model_config(self, config: UniConfig) -> dict[str, Any]:
+        """
+        Transform universal configuration to Claude-specific configuration.
+
+        Args:
+            config: Universal configuration dict
+
+        Returns:
+            Claude configuration dictionary
+        """
+        claude_config = {"model": self._model}
+
+        # Add max_tokens (required for Claude)
+        if config.get("max_tokens") is not None:
+            claude_config["max_tokens"] = config["max_tokens"]
+        else:
+            claude_config["max_tokens"] = 32768  # Claude requires max_tokens to be specified
+
+        # Add temperature
+        if config.get("temperature") is not None:
+            claude_config["temperature"] = config["temperature"]
+
+        # Add system prompt
+        if config.get("system_prompt") is not None:
+            claude_config["system"] = config["system_prompt"]
+
+        # Convert thinking configuration
+        # NOTE: Claude always provides thinking summary
+        if config.get("thinking_level") is not None:
+            claude_config["temperature"] = 1.0  # `temperature` may only be set to 1 when thinking is enabled
+            claude_config["thinking"] = self._convert_thinking_level_to_budget(config["thinking_level"])
+
+        # Convert tools to Claude's tool schema
+        if config.get("tools") is not None:
+            claude_tools = []
+            for tool in config["tools"]:
+                claude_tool = {}
+                for key, value in tool.items():
+                    claude_tool[key.replace("parameters", "input_schema")] = value
+
+                claude_tools.append(claude_tool)
+
+            claude_config["tools"] = claude_tools
+
+        # Convert tool_choice
+        if config.get("tool_choice") is not None:
+            claude_config["tool_choice"] = self._convert_tool_choice(config["tool_choice"])
+
+        return claude_config
+
+    def transform_uni_message_to_model_input(self, messages: list[UniMessage]) -> list[MessageParam]:
+        """
+        Transform universal message format to Claude's MessageParam format.
+
+        Args:
+            messages: List of universal message dictionaries
+
+        Returns:
+            List of Claude MessageParam objects
+        """
+        claude_messages: list[MessageParam] = []
+
+        for msg in messages:
+            content_blocks = []
+            for item in msg["content_items"]:
+                if item["type"] == "text":
+                    content_blocks.append({"type": "text", "text": item["text"]})
+                elif item["type"] == "image_url":
+                    # TODO: support base64 encoded images
+                    content_blocks.append({"type": "image", "source": {"type": "url", "url": item["image_url"]}})
+                elif item["type"] == "thinking":
+                    content_blocks.append(
+                        {"type": "thinking", "thinking": item["thinking"], "signature": item["signature"]}
+                    )
+                elif item["type"] == "tool_call":
+                    content_blocks.append(
+                        {
+                            "type": "tool_use",
+                            "id": item["tool_call_id"],
+                            "name": item["name"],
+                            "input": item["argument"],
+                        }
+                    )
+                elif item["type"] == "tool_result":
+                    if "tool_call_id" not in item:
+                        raise ValueError("tool_call_id is required for tool result.")
+
+                    content_blocks.append(
+                        {"type": "tool_result", "content": item["result"], "tool_use_id": item["tool_call_id"]}
+                    )
+                else:
+                    raise ValueError(f"Unknown item: {item}")
+
+            claude_messages.append({"role": msg["role"], "content": content_blocks})
+
+        return claude_messages
+
+    def transform_model_output_to_uni_event(self, model_output: MessageStreamEvent) -> PartialUniEvent:
+        """
+        Transform Claude model output to universal event format.
+
+        NOTE: Claude always has only one content item per event.
+
+        Args:
+            model_output: Claude streaming event
+
+        Returns:
+            Universal event dictionary
+        """
+        event_type = None
+        content_items: list[PartialContentItem] = []
+        usage_metadata: UsageMetadata | None = None
+        finish_reason: FinishReason | None = None
+
+        claude_event_type = model_output.type
+        if claude_event_type == "content_block_start":
+            event_type = "start"
+            block = model_output.content_block
+            if block.type == "tool_use":
+                content_items.append(
+                    {"type": "partial_tool_call", "name": block.name, "argument": "", "tool_call_id": block.id}
+                )
+
+        elif claude_event_type == "content_block_delta":
+            event_type = "delta"
+            delta = model_output.delta
+            if delta.type == "thinking_delta":
+                content_items.append({"type": "thinking", "thinking": delta.thinking})
+            elif delta.type == "text_delta":
+                content_items.append({"type": "text", "text": delta.text})
+            elif delta.type == "input_json_delta":
+                content_items.append({"type": "partial_tool_call", "argument": delta.partial_json})
+            elif delta.type == "signature_delta":
+                content_items.append({"type": "thinking", "thinking": "", "signature": delta.signature})
+
+        elif claude_event_type == "content_block_stop":
+            event_type = "stop"
+
+        elif claude_event_type == "message_start":
+            event_type = "start"
+            message = model_output.message
+            if getattr(message, "usage", None):
+                usage_metadata = {
+                    "prompt_tokens": message.usage.input_tokens,
+                    "thoughts_tokens": None,
+                    "response_tokens": None,
+                }
+
+        elif claude_event_type == "message_delta":
+            event_type = "stop"
+            delta = model_output.delta
+            if getattr(delta, "stop_reason", None):
+                stop_reason_mapping = {
+                    "end_turn": "stop",
+                    "max_tokens": "length",
+                    "stop_sequence": "stop",
+                    "tool_use": "stop",
+                }
+                finish_reason = stop_reason_mapping.get(delta.stop_reason, "unknown")
+
+            if getattr(model_output, "usage", None):
+                usage_metadata = {
+                    "prompt_tokens": None,
+                    "thoughts_tokens": None,
+                    "response_tokens": model_output.usage.output_tokens,
+                }
+
+        elif claude_event_type == "message_stop":
+            event_type = "stop"
+
+        elif claude_event_type in ["text", "thinking", "signature", "input_json"]:
+            event_type = "unused"
+
+        else:
+            raise ValueError(f"Unknown output: {model_output}")
+
+        return {
+            "role": "assistant",
+            "event": event_type,
+            "content_items": content_items,
+            "usage_metadata": usage_metadata,
+            "finish_reason": finish_reason,
+        }
+
+    async def streaming_response(
+        self,
+        messages: list[UniMessage],
+        config: UniConfig,
+    ) -> AsyncIterator[UniEvent]:
+        """Stream generate using Claude SDK with unified conversion methods."""
+        # Use unified config conversion
+        claude_config = self.transform_uni_config_to_model_config(config)
+
+        # Use unified message conversion
+        claude_messages = self.transform_uni_message_to_model_input(messages)
+
+        # Stream generate
+        partial_tool_call = {}
+        partial_usage = {}
+        async with self._client.messages.stream(**claude_config, messages=claude_messages) as stream:
+            async for event in stream:
+                event = self.transform_model_output_to_uni_event(event)
+                if event["event"] == "start":
+                    if event["content_items"] and event["content_items"][0]["type"] == "partial_tool_call":
+                        partial_tool_call["name"] = event["content_items"][0]["name"]
+                        partial_tool_call["argument"] = ""
+                        partial_tool_call["tool_call_id"] = event["content_items"][0]["tool_call_id"]
+
+                    if event["usage_metadata"] is not None:
+                        partial_usage["prompt_tokens"] = event["usage_metadata"]["prompt_tokens"]
+
+                elif event["event"] == "delta":
+                    if event["content_items"][0]["type"] == "partial_tool_call":
+                        partial_tool_call["argument"] += event["content_items"][0]["argument"]
+                    else:
+                        event.pop("event")
+                        yield event
+
+                elif event["event"] == "stop":
+                    if "name" in partial_tool_call and "argument" in partial_tool_call:
+                        yield {
+                            "role": "assistant",
+                            "content_items": [
+                                {
+                                    "type": "tool_call",
+                                    "name": partial_tool_call["name"],
+                                    "argument": json.loads(partial_tool_call["argument"]),
+                                    "tool_call_id": partial_tool_call["tool_call_id"],
+                                }
+                            ],
+                        }
+                        partial_tool_call = {}
+
+                    if "prompt_tokens" in partial_usage and event["usage_metadata"] is not None:
+                        yield {
+                            "role": "assistant",
+                            "content_items": [],
+                            "usage_metadata": {
+                                "prompt_tokens": partial_usage["prompt_tokens"],
+                                "thoughts_tokens": None,
+                                "response_tokens": event["usage_metadata"]["response_tokens"],
+                            },
+                            "finish_reason": event["finish_reason"],
+                        }
+                        partial_usage = {}

agenthub/gemini3/__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 Gemini3Client
+
+
+__all__ = ["Gemini3Client"]