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

hud/environment/utils/tool_wrappers.py

@@ -0,0 +1,113 @@
+"""Shared tool wrapper utilities for agent framework integrations."""
+
+from __future__ import annotations
+
+import json
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Callable
+
+    import mcp.types as mcp_types
+
+__all__ = [
+    "create_async_tool_fn",
+    "create_sync_tool_fn",
+    "create_tool_fns",
+    "stringify_result",
+]
+
+
+def stringify_result(result: Any) -> str:
+    """Convert a tool result to string format.
+
+    Args:
+        result: The tool result (str, dict, or other).
+
+    Returns:
+        String representation of the result.
+    """
+    if isinstance(result, str):
+        return result
+    return json.dumps(result) if result else ""
+
+
+def create_async_tool_fn(
+    env: Any,
+    tool_name: str,
+    description: str | None = None,
+) -> Callable[..., Any]:
+    """Create an async function that calls a tool on the environment.
+
+    Args:
+        env: Environment with call_tool method.
+        tool_name: Name of the tool to call.
+        description: Optional description for the function docstring.
+
+    Returns:
+        Async function that calls the tool and returns string result.
+    """
+
+    async def async_fn(**kwargs: Any) -> str:
+        result = await env.call_tool(tool_name, **kwargs)
+        return stringify_result(result)
+
+    async_fn.__name__ = tool_name
+    async_fn.__doc__ = description or f"Tool: {tool_name}"
+    return async_fn
+
+
+def create_sync_tool_fn(
+    env: Any,
+    tool_name: str,
+    description: str | None = None,
+) -> Callable[..., Any]:
+    """Create a sync function that calls a tool on the environment.
+
+    This handles the complexity of running async code from sync context,
+    including when already in an async event loop.
+
+    Args:
+        env: Environment with call_tool method.
+        tool_name: Name of the tool to call.
+        description: Optional description for the function docstring.
+
+    Returns:
+        Sync function that calls the tool and returns string result.
+    """
+    import asyncio
+
+    def sync_fn(**kwargs: Any) -> str:
+        loop = asyncio.get_event_loop()
+        if loop.is_running():
+            import concurrent.futures
+
+            with concurrent.futures.ThreadPoolExecutor() as executor:
+                future = executor.submit(asyncio.run, env.call_tool(tool_name, **kwargs))
+                result = future.result()
+        else:
+            result = loop.run_until_complete(env.call_tool(tool_name, **kwargs))
+
+        return stringify_result(result)
+
+    sync_fn.__name__ = tool_name
+    sync_fn.__doc__ = description or f"Tool: {tool_name}"
+    return sync_fn
+
+
+def create_tool_fns(
+    env: Any,
+    tool: mcp_types.Tool,
+) -> tuple[Callable[..., str], Callable[..., Any]]:
+    """Create both sync and async functions for a tool.
+
+    Args:
+        env: Environment with call_tool method.
+        tool: MCP tool definition.
+
+    Returns:
+        Tuple of (sync_fn, async_fn).
+    """
+    sync_fn = create_sync_tool_fn(env, tool.name, tool.description)
+    async_fn = create_async_tool_fn(env, tool.name, tool.description)
+    return sync_fn, async_fn

hud/eval/__init__.py

@@ -0,0 +1,67 @@
+"""HUD Eval - Evaluation context and management.
+
+This module provides:
+- Task: A runnable evaluation unit (from env())
+- EvalContext: Environment with evaluation tracking (trace_id, reward, etc.)
+- eval(): Standalone context manager for task-based evaluation
+
+Usage:
+    # Using env() to create Task
+    env = Environment("my-env").connect_hub("browser")
+
+    async with env() as ctx:
+        await ctx.call_tool("navigate", url="...")
+
+    async with env("checkout", user_id="alice") as ctx:
+        await agent.run(ctx.prompt)
+
+    # Standalone with task slugs
+    async with hud.eval("my-org/task:1") as ctx:
+        await agent.run(ctx)
+
+    # Orchestrated with Task objects
+    tasks = [env("checkout", user_id="alice"), env("checkout", user_id="bob")]
+    async with hud.eval(tasks, variants={"model": ["gpt-4o"]}, group=4) as ctx:
+        await agent.run(ctx.prompt)
+
+    # Blank eval for manual reward
+    async with hud.eval() as ctx:
+        ctx.reward = compute_reward()
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+# Auto-instrument httpx on import
+import hud.eval.instrument  # noqa: F401
+
+# run_eval is safe to import (uses lazy imports internally)
+from hud.eval.manager import run_eval
+
+# Task is safe to import
+from hud.eval.task import Task
+
+# Utils for v4 format handling
+from hud.eval.utils import build_env_from_v4, is_v4_format, validate_v4_task
+
+if TYPE_CHECKING:
+    from hud.eval.context import EvalContext
+
+__all__ = [
+    "EvalContext",
+    "Task",
+    "build_env_from_v4",
+    "is_v4_format",
+    "run_eval",
+    "validate_v4_task",
+]
+
+
+def __getattr__(name: str) -> object:
+    """Lazy import EvalContext to avoid circular imports."""
+    if name == "EvalContext":
+        from hud.eval.context import EvalContext
+
+        return EvalContext
+    raise AttributeError(f"module 'hud.eval' has no attribute {name!r}")