hud-python 0.4.45__py3-none-any.whl → 0.5.1__py3-none-any.whl

hud/environment/integrations/__init__.py

@@ -0,0 +1,45 @@
+"""Provider integrations - format conversion and framework tools."""
+
+from hud.environment.integrations.adk import ADKMixin
+from hud.environment.integrations.anthropic import AnthropicMixin
+from hud.environment.integrations.gemini import GeminiMixin
+from hud.environment.integrations.langchain import LangChainMixin
+from hud.environment.integrations.llamaindex import LlamaIndexMixin
+from hud.environment.integrations.openai import OpenAIMixin
+
+__all__ = ["IntegrationsMixin"]
+
+
+class IntegrationsMixin(
+    OpenAIMixin,
+    AnthropicMixin,
+    GeminiMixin,
+    LangChainMixin,
+    LlamaIndexMixin,
+    ADKMixin,
+):
+    """Combined integration mixin for all providers.
+
+    OpenAI:
+        as_openai_chat_tools() - Chat Completions format
+        as_openai_responses_tools() - Responses API format
+        as_openai_agent_tools() - Agents SDK (requires openai-agents)
+
+    Anthropic/Claude:
+        as_claude_tools() - Claude API format
+        as_claude_programmatic_tools() - Programmatic tool use
+        as_anthropic_runner() - Tool runner (requires anthropic)
+
+    Google/Gemini:
+        as_gemini_tools() - Gemini format
+        as_gemini_tool_config() - Tool config
+
+    Google ADK:
+        as_adk_tools() - ADK FunctionTool objects (requires google-adk)
+
+    LangChain:
+        as_langchain_tools() - StructuredTools (requires langchain-core)
+
+    LlamaIndex:
+        as_llamaindex_tools() - FunctionTools (requires llama-index-core)
+    """

hud/environment/integrations/adk.py

@@ -0,0 +1,67 @@
+"""Google ADK integration."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from hud.environment.utils.tool_wrappers import create_async_tool_fn
+
+if TYPE_CHECKING:
+    import mcp.types as mcp_types
+
+__all__ = ["ADKMixin"]
+
+
+class ADKMixin:
+    """Mixin providing Google ADK (Agent Development Kit) integration.
+
+    Integration methods (requires google-adk):
+        as_adk_tools() - ADK FunctionTool objects
+
+    Requires: as_tools() -> list[mcp_types.Tool], call_tool(name, args)
+    """
+
+    def as_tools(self) -> list[mcp_types.Tool]:
+        raise NotImplementedError
+
+    async def call_tool(self, name: str, arguments: dict[str, Any]) -> Any:
+        raise NotImplementedError
+
+    def as_adk_tools(self) -> list[Any]:
+        """Convert to Google ADK FunctionTool objects.
+
+        Requires: pip install google-adk
+
+        Returns:
+            List of FunctionTool objects for Google ADK agents.
+
+        Example:
+            ```python
+            from google.adk.agents import Agent
+            from google.adk.runners import Runner
+
+            async with env:
+                agent = Agent(
+                    name="assistant",
+                    model="gemini-2.0-flash",
+                    instruction="You are a helpful assistant.",
+                    tools=env.as_adk_tools(),
+                )
+                runner = Runner(agent=agent)
+                result = await runner.run("Find information about Python")
+            ```
+        """
+        try:
+            from google.adk.tools.function_tool import FunctionTool
+        except ImportError as e:
+            raise ImportError(
+                "Google ADK not installed. Install with: pip install google-adk"
+            ) from e
+
+        tools = []
+        for t in self.as_tools():
+            # ADK only needs async function - it wraps it in FunctionTool
+            async_fn = create_async_tool_fn(self, t.name, t.description)
+            tool = FunctionTool(async_fn)
+            tools.append(tool)
+        return tools

hud/environment/integrations/anthropic.py

@@ -0,0 +1,196 @@
+"""Anthropic/Claude integrations - format conversion and tool runner."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    import mcp.types as mcp_types
+
+__all__ = ["AnthropicMixin"]
+
+
+class AnthropicMixin:
+    """Mixin providing Anthropic/Claude format conversion and tool runner.
+
+    Format methods (no deps):
+        as_claude_tools() - Claude API format
+        as_claude_programmatic_tools() - Programmatic tool use format
+
+    Integration methods (requires anthropic):
+        as_anthropic_runner() - Tool runner for executing tool_use blocks
+
+    Requires: as_tools() -> list[mcp_types.Tool], call_tool(name, args)
+    """
+
+    def as_tools(self) -> list[mcp_types.Tool]:
+        raise NotImplementedError
+
+    async def call_tool(self, name: str, arguments: dict[str, Any]) -> Any:
+        raise NotImplementedError
+
+    # =========================================================================
+    # Format Conversion (no external deps)
+    # =========================================================================
+
+    def as_claude_tools(self, *, cache_control: bool = False) -> list[dict[str, Any]]:
+        """Convert to Claude/Anthropic tool format.
+
+        Args:
+            cache_control: Add cache_control for prompt caching
+
+        Returns:
+            List of tool definitions for Claude API.
+
+        Example:
+            ```python
+            from anthropic import Anthropic
+
+            client = Anthropic()
+            async with env:
+                response = client.messages.create(
+                    model="claude-sonnet-4-20250514",
+                    max_tokens=1024,
+                    messages=[{"role": "user", "content": "Navigate to google.com"}],
+                    tools=env.as_claude_tools(),
+                )
+                # Execute tool calls
+                for block in response.content:
+                    if block.type == "tool_use":
+                        result = await env.call_tool(block)
+            ```
+        """
+        tools = []
+        for t in self.as_tools():
+            tool: dict[str, Any] = {
+                "name": t.name,
+                "description": t.description or "",
+                "input_schema": t.inputSchema or {"type": "object", "properties": {}},
+            }
+            if cache_control:
+                tool["cache_control"] = {"type": "ephemeral"}
+            tools.append(tool)
+        return tools
+
+    def as_claude_programmatic_tools(self, *, cache_control: bool = False) -> list[dict[str, Any]]:
+        """Convert to Claude programmatic tool use format.
+
+        Programmatic tool use allows Claude to execute tools via code execution.
+
+        Example:
+            ```python
+            from anthropic import Anthropic
+
+            client = Anthropic()
+            async with env:
+                response = client.messages.create(
+                    model="claude-sonnet-4-20250514",
+                    max_tokens=1024,
+                    messages=[{"role": "user", "content": "Analyze the data"}],
+                    tools=env.as_claude_programmatic_tools(),
+                    betas=["code-execution-2025-01-24"],
+                )
+            ```
+        """
+        tools = []
+        for t in self.as_tools():
+            tool: dict[str, Any] = {
+                "name": t.name,
+                "description": t.description or "",
+                "input_schema": t.inputSchema or {"type": "object", "properties": {}},
+                "allowed_callers": ["code_execution_20250825"],
+            }
+            if cache_control:
+                tool["cache_control"] = {"type": "ephemeral"}
+            tools.append(tool)
+        return tools
+
+    # =========================================================================
+    # Tool Runner Integration (requires anthropic)
+    # =========================================================================
+
+    def as_anthropic_runner(self) -> EnvToolRunner:
+        """Create an Anthropic tool runner for this environment.
+
+        Requires: pip install anthropic
+
+        Returns:
+            EnvToolRunner that can process tool_use blocks from Claude.
+
+        Example:
+            ```python
+            from anthropic import Anthropic
+
+            client = Anthropic()
+            async with env:
+                runner = env.as_anthropic_runner()
+
+                response = client.messages.create(
+                    model="claude-sonnet-4-20250514",
+                    max_tokens=1024,
+                    messages=[{"role": "user", "content": "Navigate to google.com"}],
+                    tools=env.as_claude_tools(),
+                )
+
+                # Execute all tool_use blocks
+                results = []
+                for block in response.content:
+                    if block.type == "tool_use":
+                        result = await runner.run(block)
+                        results.append(result)
+            ```
+        """
+        return EnvToolRunner(self)
+
+
+class EnvToolRunner:
+    """Tool runner that executes tools against an Environment."""
+
+    def __init__(self, env: AnthropicMixin) -> None:
+        self.env = env
+        self._tool_names: set[str] | None = None
+
+    @property
+    def tool_names(self) -> set[str]:
+        """Get available tool names."""
+        if self._tool_names is None:
+            self._tool_names = {t.name for t in self.env.as_tools()}
+        return self._tool_names
+
+    async def run(self, tool_use_block: Any) -> Any:
+        """Execute a tool_use block from Claude.
+
+        Args:
+            tool_use_block: A ToolUseBlock from Claude's response.
+
+        Returns:
+            Tool result dict (or BetaToolResultBlockParam if anthropic installed).
+        """
+        name = tool_use_block.name
+        tool_use_id = tool_use_block.id
+        arguments = tool_use_block.input or {}
+
+        try:
+            result = await self.env.call_tool(name, **arguments)
+            content = result if isinstance(result, str) else json.dumps(result) if result else ""
+            result_dict: dict[str, Any] = {
+                "type": "tool_result",
+                "tool_use_id": tool_use_id,
+                "content": content,
+            }
+        except Exception as e:
+            result_dict = {
+                "type": "tool_result",
+                "tool_use_id": tool_use_id,
+                "content": f"Error: {e}",
+                "is_error": True,
+            }
+
+        # Return typed object if anthropic is available
+        try:
+            from anthropic.types.beta import BetaToolResultBlockParam
+
+            return BetaToolResultBlockParam(**result_dict)
+        except ImportError:
+            return result_dict

hud/environment/integrations/gemini.py

@@ -0,0 +1,92 @@
+"""Google/Gemini integrations - format conversion."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    import mcp.types as mcp_types
+
+__all__ = ["GeminiMixin"]
+
+
+class GeminiMixin:
+    """Mixin providing Google/Gemini format conversion.
+
+    Format methods (no deps):
+        as_gemini_tools() - Gemini tool format
+        as_gemini_tool_config() - Tool execution config
+
+    Requires: as_tools() -> list[mcp_types.Tool]
+    """
+
+    def as_tools(self) -> list[mcp_types.Tool]:
+        raise NotImplementedError
+
+    def as_gemini_tools(self) -> list[dict[str, Any]]:
+        """Convert to Gemini/Google AI tool format.
+
+        Returns:
+            List with function_declarations for Gemini API.
+
+        Example:
+            ```python
+            import google.generativeai as genai
+
+            model = genai.GenerativeModel("gemini-1.5-pro")
+            async with env:
+                response = model.generate_content(
+                    "Navigate to google.com",
+                    tools=env.as_gemini_tools(),
+                )
+                # Execute tool calls
+                for part in response.candidates[0].content.parts:
+                    if fn := part.function_call:
+                        result = await env.call_tool(part)
+            ```
+        """
+        return [
+            {
+                "function_declarations": [
+                    {
+                        "name": t.name,
+                        "description": t.description or "",
+                        "parameters": t.inputSchema or {"type": "object", "properties": {}},
+                    }
+                    for t in self.as_tools()
+                ]
+            }
+        ]
+
+    def as_gemini_tool_config(
+        self,
+        mode: str = "AUTO",
+        allowed_tools: list[str] | None = None,
+    ) -> dict[str, Any]:
+        """Get Gemini tool_config for controlling tool execution.
+
+        Args:
+            mode: "AUTO", "ANY", or "NONE"
+            allowed_tools: If mode is "ANY", list of allowed tool names
+
+        Returns:
+            Tool config dict for Gemini API.
+
+        Example:
+            ```python
+            import google.generativeai as genai
+
+            model = genai.GenerativeModel("gemini-1.5-pro")
+            async with env:
+                # Force specific tool usage
+                response = model.generate_content(
+                    "Search for cats",
+                    tools=env.as_gemini_tools(),
+                    tool_config=env.as_gemini_tool_config(mode="ANY", allowed_tools=["search"]),
+                )
+            ```
+        """
+        config: dict[str, Any] = {"function_calling_config": {"mode": mode}}
+        if mode == "ANY" and allowed_tools:
+            config["function_calling_config"]["allowed_function_names"] = allowed_tools
+        return config

hud/environment/integrations/langchain.py

@@ -0,0 +1,82 @@
+"""LangChain integration."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from hud.environment.utils.schema import schema_to_pydantic
+from hud.environment.utils.tool_wrappers import create_tool_fns
+
+if TYPE_CHECKING:
+    import mcp.types as mcp_types
+
+__all__ = ["LangChainMixin"]
+
+
+class LangChainMixin:
+    """Mixin providing LangChain integration.
+
+    Integration methods (requires langchain-core):
+        as_langchain_tools() - LangChain StructuredTool objects
+
+    Requires: as_tools() -> list[mcp_types.Tool], call_tool(name, args)
+    """
+
+    def as_tools(self) -> list[mcp_types.Tool]:
+        raise NotImplementedError
+
+    async def call_tool(self, name: str, arguments: dict[str, Any]) -> Any:
+        raise NotImplementedError
+
+    def as_langchain_tools(self) -> list[Any]:
+        """Convert to LangChain StructuredTool objects.
+
+        Requires: pip install langchain-core
+
+        Returns:
+            List of StructuredTool objects for LangChain agents.
+
+        Example:
+            ```python
+            from langchain_openai import ChatOpenAI
+            from langchain.agents import create_tool_calling_agent, AgentExecutor
+            from langchain_core.prompts import ChatPromptTemplate
+
+            llm = ChatOpenAI(model="gpt-4o")
+            async with env:
+                tools = env.as_langchain_tools()
+
+                prompt = ChatPromptTemplate.from_messages(
+                    [
+                        ("system", "You are a helpful assistant."),
+                        ("human", "{input}"),
+                        ("placeholder", "{agent_scratchpad}"),
+                    ]
+                )
+
+                agent = create_tool_calling_agent(llm, tools, prompt)
+                executor = AgentExecutor(agent=agent, tools=tools)
+                result = await executor.ainvoke({"input": "Navigate to google.com"})
+            ```
+        """
+        try:
+            from langchain_core.tools import StructuredTool
+        except ImportError as e:
+            raise ImportError(
+                "LangChain not installed. Install with: pip install langchain-core"
+            ) from e
+
+        tools = []
+        for t in self.as_tools():
+            schema = t.inputSchema or {"type": "object", "properties": {}}
+            sync_fn, async_fn = create_tool_fns(self, t)
+
+            tool = StructuredTool(
+                name=t.name,
+                description=t.description or "",
+                func=sync_fn,
+                coroutine=async_fn,
+                args_schema=schema_to_pydantic(t.name, schema),
+            )
+            tools.append(tool)
+        return tools

hud/environment/integrations/llamaindex.py

@@ -0,0 +1,68 @@
+"""LlamaIndex integration."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from hud.environment.utils.tool_wrappers import create_tool_fns
+
+if TYPE_CHECKING:
+    import mcp.types as mcp_types
+
+__all__ = ["LlamaIndexMixin"]
+
+
+class LlamaIndexMixin:
+    """Mixin providing LlamaIndex integration.
+
+    Integration methods (requires llama-index-core):
+        as_llamaindex_tools() - LlamaIndex FunctionTool objects
+
+    Requires: as_tools() -> list[mcp_types.Tool], call_tool(name, args)
+    """
+
+    def as_tools(self) -> list[mcp_types.Tool]:
+        raise NotImplementedError
+
+    async def call_tool(self, name: str, arguments: dict[str, Any]) -> Any:
+        raise NotImplementedError
+
+    def as_llamaindex_tools(self) -> list[Any]:
+        """Convert to LlamaIndex FunctionTool objects.
+
+        Requires: pip install llama-index-core
+
+        Returns:
+            List of FunctionTool objects for LlamaIndex agents.
+
+        Example:
+            ```python
+            from llama_index.llms.openai import OpenAI
+            from llama_index.core.agent import ReActAgent
+
+            llm = OpenAI(model="gpt-4o")
+            async with env:
+                tools = env.as_llamaindex_tools()
+                agent = ReActAgent.from_tools(tools, llm=llm, verbose=True)
+                response = await agent.achat("Find information about Python")
+            ```
+        """
+        try:
+            from llama_index.core.tools import FunctionTool
+        except ImportError as e:
+            raise ImportError(
+                "LlamaIndex not installed. Install with: pip install llama-index-core"
+            ) from e
+
+        tools = []
+        for t in self.as_tools():
+            sync_fn, async_fn = create_tool_fns(self, t)
+
+            tool = FunctionTool.from_defaults(
+                fn=sync_fn,
+                async_fn=async_fn,
+                name=t.name,
+                description=t.description or "",
+            )
+            tools.append(tool)
+        return tools