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

hud/cli/utils/version_check.py

@@ -0,0 +1,258 @@
+"""Version checking utilities for HUD CLI.
+
+This module handles checking for updates to the hud-python package
+and prompting users to upgrade when a new version is available.
+
+Features:
+- Checks PyPI for the latest version of hud-python
+- Caches results for 6 hours to avoid excessive API calls
+- Displays a friendly prompt when an update is available
+- Can be disabled with HUD_SKIP_VERSION_CHECK=1 environment variable
+
+The version check runs automatically at the start of most CLI commands,
+but is skipped for help and version commands to keep them fast.
+"""
+
+from __future__ import annotations
+
+import contextlib
+import json
+import logging
+import os
+import time
+from pathlib import Path
+from typing import NamedTuple
+
+import httpx
+from packaging import version
+
+from hud.utils.hud_console import HUDConsole
+
+# Logger for version checking
+logger = logging.getLogger(__name__)
+
+# Cache location for version check data
+CACHE_DIR = Path.home() / ".hud" / ".cache"
+VERSION_CACHE_FILE = CACHE_DIR / "version_check.json"
+
+# Cache duration in seconds (6 hours)
+CACHE_DURATION = 6 * 60 * 60
+
+# PyPI API URL for package info
+PYPI_URL = "https://pypi.org/pypi/hud-python/json"
+
+
+class VersionInfo(NamedTuple):
+    """Version information from PyPI."""
+
+    latest: str
+    current: str
+    is_outdated: bool
+    checked_at: float
+
+
+def _get_current_version() -> str:
+    """Get the currently installed version of hud-python."""
+    try:
+        from hud import __version__
+
+        return __version__
+    except ImportError:
+        return "unknown"
+
+
+def _fetch_latest_version() -> str | None:
+    """Fetch the latest version from PyPI.
+
+    Returns:
+        The latest version string, or None if the request fails.
+    """
+    try:
+        with httpx.Client(timeout=3.0) as client:
+            response = client.get(PYPI_URL)
+            if response.status_code == 200:
+                data = response.json()
+                return data["info"]["version"]
+    except Exception:  # noqa: S110
+        # Silently fail - we don't want to disrupt the user's workflow
+        # if PyPI is down or there's a network issue
+        pass
+    return None
+
+
+def _load_cache() -> VersionInfo | None:
+    """Load cached version information.
+
+    Returns:
+        Cached VersionInfo if valid, None otherwise.
+    """
+    if not VERSION_CACHE_FILE.exists():
+        return None
+
+    try:
+        with open(VERSION_CACHE_FILE) as f:
+            data = json.load(f)
+
+        # Check if cache is still valid
+        if time.time() - data["checked_at"] > CACHE_DURATION:
+            return None
+
+        return VersionInfo(
+            latest=data["latest"],
+            current=data["current"],
+            is_outdated=data["is_outdated"],
+            checked_at=data["checked_at"],
+        )
+    except Exception:
+        # If cache is corrupted, return None
+        return None
+
+
+def _save_cache(info: VersionInfo) -> None:
+    """Save version information to cache.
+
+    Args:
+        info: Version information to cache.
+    """
+    try:
+        # Create cache directory if it doesn't exist
+        CACHE_DIR.mkdir(parents=True, exist_ok=True)
+
+        with open(VERSION_CACHE_FILE, "w") as f:
+            json.dump(
+                {
+                    "latest": info.latest,
+                    "current": info.current,
+                    "is_outdated": info.is_outdated,
+                    "checked_at": info.checked_at,
+                },
+                f,
+            )
+    except Exception:  # noqa: S110
+        # Silently fail if we can't write cache
+        pass
+
+
+def _compare_versions(current: str, latest: str) -> bool:
+    """Compare versions to determine if an update is available.
+
+    Args:
+        current: Current version string
+        latest: Latest version string
+
+    Returns:
+        True if latest is newer than current, False otherwise.
+    """
+    if current == "unknown":
+        return False
+
+    try:
+        current_v = version.parse(current)
+        latest_v = version.parse(latest)
+        return latest_v > current_v
+    except Exception:
+        # If we can't parse versions, assume no update needed
+        return False
+
+
+def check_for_updates() -> VersionInfo | None:
+    """Check for updates to hud-python.
+
+    This function checks PyPI for the latest version and caches the result
+    for 6 hours to avoid excessive API calls.
+
+    Returns:
+        VersionInfo if check succeeds, None otherwise.
+    """
+    # Check if we're in CI/testing environment
+    if os.environ.get("CI") or os.environ.get("HUD_SKIP_VERSION_CHECK"):
+        return None
+
+    # Get current version first
+    current = _get_current_version()
+    if current == "unknown":
+        return None
+
+    # Try to load from cache
+    cached_info = _load_cache()
+
+    # If cache exists but current version has changed (user upgraded), invalidate cache
+    if cached_info and cached_info.current != current:
+        cached_info = None  # Force fresh check
+
+    if cached_info:
+        # Update the current version in the cached info to reflect reality
+        # but keep the cached latest version and timestamp
+        return VersionInfo(
+            latest=cached_info.latest,
+            current=current,  # Use actual current version, not cached
+            is_outdated=_compare_versions(current, cached_info.latest),
+            checked_at=cached_info.checked_at,
+        )
+
+    # Fetch latest version from PyPI
+    latest = _fetch_latest_version()
+    if not latest:
+        return None
+
+    # Compare versions
+    is_outdated = _compare_versions(current, latest)
+
+    # Create version info
+    info = VersionInfo(
+        latest=latest,
+        current=current,
+        is_outdated=is_outdated,
+        checked_at=time.time(),
+    )
+
+    # Save to cache
+    _save_cache(info)
+
+    return info
+
+
+def display_update_prompt(console: HUDConsole | None = None) -> None:
+    """Display update prompt if a new version is available.
+
+    This function checks for updates and displays a prompt to the user
+    if their version is outdated.
+
+    Args:
+        console: HUDConsole instance for output. If None, creates a new one.
+    """
+    if console is None:
+        console = HUDConsole(logger=logger)
+
+    try:
+        info = check_for_updates()
+        if info and info.is_outdated:
+            # Create update message
+            update_msg = (
+                f"🆕 A new version of hud-python is available: "
+                f"[bold cyan]{info.latest}[/bold cyan] "
+                f"(current: [dim]{info.current}[/dim])\n"
+                f"   Run: [bold yellow]uv tool upgrade hud-python[/bold yellow] to update"
+            )
+
+            # Display using console info
+            console.info(f"[yellow]{update_msg}[/yellow]")
+    except Exception:  # noqa: S110
+        # Never let version checking disrupt the user's workflow
+        pass
+
+
+def force_version_check() -> VersionInfo | None:
+    """Force a version check, bypassing the cache.
+
+    This is useful for explicit version checks or testing.
+
+    Returns:
+        VersionInfo if check succeeds, None otherwise.
+    """
+    # Clear the cache to force a fresh check
+    if VERSION_CACHE_FILE.exists():
+        with contextlib.suppress(Exception):
+            VERSION_CACHE_FILE.unlink()
+
+    return check_for_updates()

hud/cli/{rl → utils}/viewer.py

@@ -1,4 +1,4 @@
-"""Inline JSON preview with expandable view for RL flow.
+"""Inline JSON preview with expandable view.
 
 Uses minimal terminal interaction for inline display.
 """
@@ -46,7 +46,7 @@ def _truncate_value(value: Any, max_len: int = 60) -> str:
         if len(value) > max_len:
             return value[:max_len] + "…"
         return value
-    elif isinstance(value, (dict, list)):
+    elif isinstance(value, dict | list):
         s = json.dumps(value, separators=(",", ":"))
         if len(s) > max_len:
             return s[:max_len] + "…"

hud/clients/README.md

@@ -7,8 +7,8 @@ This directory contains the MCP client implementations for HUD SDK. The architec
 ```
 hud/clients/
 ├── base.py          # Protocol definition and base class
-├── mcp_use.py       # MCP-use based implementation (legacy)
-├── fastmcp.py       # FastMCP based implementation (modern)
+├── mcp_use.py       # MCP-use based implementation (default)
+├── fastmcp.py       # FastMCP based implementation (alternative)
 └── __init__.py      # Exports and default client
 ```
 
@@ -30,15 +30,15 @@ class AgentMCPClient(Protocol):
 
 ## Available Implementations
 
-### 1. MCPUseHUDClient
+### 1. MCPUseHUDClient (Default)
 - Based on the `mcp_use` library
 - Supports multiple concurrent server connections
 - Battle-tested and stable
 - Good for complex multi-server setups
 
-### 2. FastMCPHUDClient (Default)
+### 2. FastMCPHUDClient
 - Based on the `fastmcp` library
-- Modern, clean API with better error handling
+- Alternative implementation with different transport handling
 - Supports various transports (HTTP, WebSocket, stdio, in-memory)
 - Better type safety and structured data support
 
@@ -47,7 +47,7 @@ class AgentMCPClient(Protocol):
 ### Basic Usage
 
 ```python
-from hud.clients import MCPUseHUDClient, FastMCPHUDClient
+from hud.clients import MCPClient, FastMCPHUDClient
 
 # Configuration works for both clients
 mcp_config = {
@@ -57,10 +57,10 @@ mcp_config = {
     }
 }
 
-# Option 1: MCP-use client
-client = MCPUseHUDClient(mcp_config)
+# Default client (MCPUseHUDClient)
+client = MCPClient(mcp_config)
 
-# Option 2: FastMCP client
+# Alternative: FastMCP client
 client = FastMCPHUDClient(mcp_config)
 
 # Both use the same API
@@ -73,13 +73,14 @@ async with client:
 
 ```python
 from hud.agents import ClaudeAgent
+from hud.clients import MCPClient
 
 # Either client works with agents
-client = FastMCPHUDClient(mcp_config)
+client = MCPClient(mcp_config)
 
 agent = ClaudeAgent(
     mcp_client=client,
-    model="claude-3-7-sonnet-20250219"
+    model="claude-sonnet-4-5"
 )
 
 # Agent works identically with either client

hud/clients/__init__.py

@@ -3,15 +3,16 @@
 from __future__ import annotations
 
 from .base import AgentMCPClient, BaseHUDClient
+from .environment import EnvironmentClient
 from .fastmcp import FastMCPHUDClient
-from .mcp_use import MCPUseHUDClient
 
-# Default to MCP-use for new features
-MCPClient = MCPUseHUDClient
+# Default to FastMCP client (no optional dependencies)
+MCPClient = FastMCPHUDClient
 
 __all__ = [
     "AgentMCPClient",
     "BaseHUDClient",
+    "EnvironmentClient",
     "FastMCPHUDClient",
     "MCPClient",
 ]

hud/clients/base.py

@@ -12,7 +12,6 @@ from mcp.types import Implementation
 from hud.shared.exceptions import HudAuthenticationError, HudException
 from hud.types import MCPToolCall, MCPToolResult
 from hud.utils.hud_console import HUDConsole
-from hud.utils.mcp import setup_hud_telemetry
 from hud.version import __version__ as hud_version
 
 if TYPE_CHECKING:
@@ -86,7 +85,6 @@ class BaseHUDClient(AgentMCPClient):
         mcp_config: dict[str, dict[str, Any]] | None = None,
         verbose: bool = False,
         strict_validation: bool = False,
-        auto_trace: bool = True,
     ) -> None:
         """
         Initialize base client.
@@ -99,11 +97,11 @@ class BaseHUDClient(AgentMCPClient):
         self.verbose = verbose
         self._mcp_config = mcp_config
         self._strict_validation = strict_validation
-        self._auto_trace = auto_trace
-        self._auto_trace_cm: Any | None = None  # Store auto-created trace context manager
 
         self._initialized = False
         self._telemetry_data = {}  # Initialize telemetry data
+        self._cached_resources: list[types.Resource] = []  # Cache for resources
+        self._cached_prompts: list[types.Prompt] = []  # Cache for prompts
 
         if self.verbose:
             self._setup_verbose_logging()
@@ -126,8 +124,6 @@ class BaseHUDClient(AgentMCPClient):
                 "Either pass it to the constructor or call initialize with a configuration"
             )
 
-        self._auto_trace_cm = setup_hud_telemetry(self._mcp_config, auto_trace=self._auto_trace)
-
         hud_console.debug("Initializing MCP client...")
 
         try:
@@ -135,18 +131,18 @@ class BaseHUDClient(AgentMCPClient):
             for server_config in self._mcp_config.values():
                 url = server_config.get("url", "")
                 headers = server_config.get("headers", {})
-                if "mcp.hud.so" in url and len(headers.get("Authorization", "")) < 10:
+                if "mcp.hud.ai" in url and len(headers.get("Authorization", "")) < 10:
                     raise HudAuthenticationError(
                         f'Sending authorization "{headers.get("Authorization", "")}", which may'
                         " be incomplete. Ensure HUD_API_KEY environment variable is set or send it"
-                        " as a header. You can get an API key at https://hud.so"
+                        " as a header. You can get an API key at https://hud.ai"
                     )
             # Subclasses implement connection
             await self._connect(self._mcp_config)
         except HudException:
             raise
         except Exception as e:
-            # Auto-converts to appropriate HUD exception type with hints
+            hud_console.error(f"Failed to initialize MCP client: {e}")
             raise HudException from e
 
         # Common hud behavior - fetch telemetry
@@ -156,21 +152,12 @@ class BaseHUDClient(AgentMCPClient):
 
     async def shutdown(self) -> None:
         """Disconnect from the MCP server."""
-        # Clean up auto-created trace if any
-        if self._auto_trace_cm:
-            try:
-                self._auto_trace_cm.__exit__(None, None, None)
-                hud_console.info("Closed auto-created trace")
-            except Exception as e:
-                hud_console.warning(f"Failed to close auto-created trace: {e}")
-            finally:
-                self._auto_trace_cm = None
-
-        # Disconnect from server
         if self._initialized:
             await self._disconnect()
             self._initialized = False
-            hud_console.info("Shutdown completed")
+            self._cached_resources.clear()
+            self._cached_prompts.clear()
+            hud_console.info("Environment Shutdown completed")
         else:
             hud_console.debug("Client was not initialized, skipping disconnect")
 
@@ -211,11 +198,41 @@ class BaseHUDClient(AgentMCPClient):
         """List all available tools."""
         raise NotImplementedError
 
-    @abstractmethod
     async def list_resources(self) -> list[types.Resource]:
-        """List all available resources."""
+        """List all available resources.
+
+        Uses cached resources if available, otherwise fetches from the server.
+
+        Returns:
+            List of available resources.
+        """
+        # If cache is empty, populate it
+        if not self._cached_resources:
+            self._cached_resources = await self._list_resources_impl()
+        return self._cached_resources
+
+    @abstractmethod
+    async def _list_resources_impl(self) -> list[types.Resource]:
+        """Implementation-specific resource listing. Subclasses must implement this."""
         raise NotImplementedError
 
+    async def list_prompts(self) -> list[types.Prompt]:
+        """List all available prompts.
+
+        Uses cached prompts if available, otherwise fetches from the server.
+        Prompts are optional in MCP; default implementation returns an empty list.
+        """
+        if not self._cached_prompts:
+            self._cached_prompts = await self._list_prompts_impl()
+        return self._cached_prompts
+
+    async def _list_prompts_impl(self) -> list[types.Prompt]:
+        """Implementation-specific prompt listing (optional).
+
+        Subclasses can override to support prompt discovery.
+        """
+        return []
+
     @abstractmethod
     async def _call_tool(self, tool_call: MCPToolCall) -> MCPToolResult:
         """Execute a tool by name."""
@@ -270,6 +287,17 @@ class BaseHUDClient(AgentMCPClient):
     async def _fetch_telemetry(self) -> None:
         """Common telemetry fetching for all hud clients."""
         try:
+            # Get resources (will use cache if available, otherwise fetch)
+            resources = await self.list_resources()
+            telemetry_available = any(
+                str(resource.uri) == "telemetry://live" for resource in resources
+            )
+
+            if not telemetry_available:
+                if self.verbose:
+                    hud_console.debug("Telemetry resource not available from server")
+                return
+
             # Try to read telemetry resource directly
             result = await self.read_resource("telemetry://live")
             if result and result.contents:
@@ -321,6 +349,9 @@ class BaseHUDClient(AgentMCPClient):
             "hub_tools": {},
             "telemetry": self._telemetry_data,
             "resources": [],
+            "prompts": [],
+            "scenarios": [],
+            "verbose": self.verbose,
             "metadata": {
                 "servers": list(self._mcp_config.keys()),  # type: ignore
                 "initialized": self._initialized,
@@ -333,7 +364,7 @@ class BaseHUDClient(AgentMCPClient):
             tool_info = {
                 "name": tool.name,
                 "description": tool.description,
-                "input_schema": tool.inputSchema,
+                "inputSchema": tool.inputSchema,
             }
             analysis["tools"].append(tool_info)
 
@@ -352,16 +383,125 @@ class BaseHUDClient(AgentMCPClient):
         try:
             resources = await self.list_resources()
             for resource in resources:
-                resource_info = {
+                resource_info: dict[str, Any] = {
                     "uri": str(resource.uri),
                     "name": resource.name,
                     "description": resource.description,
                     "mime_type": getattr(resource, "mimeType", None),
                 }
+                # Include meta field if present (contains scenario source code)
+                meta = getattr(resource, "meta", None)
+                if meta:
+                    resource_info["meta"] = meta
                 analysis["resources"].append(resource_info)
         except Exception as e:
             if self.verbose:
-                hud_console.debug(f"Could not list resources: {e}")
+                hud_console.debug("Could not list resources: " + str(e))
+
+        # Get all prompts (optional)
+        try:
+            prompts = await self.list_prompts()
+            for prompt in prompts:
+                raw_args = getattr(prompt, "arguments", []) or []
+                args: list[dict[str, Any]] = [
+                    {
+                        "name": getattr(a, "name", None),
+                        "required": getattr(a, "required", None),
+                        "description": getattr(a, "description", None),
+                    }
+                    for a in raw_args
+                ]
+
+                prompt_info: dict[str, Any] = {
+                    "name": prompt.name,
+                    "description": prompt.description,
+                    "arguments": args,
+                }
+                # Include meta field if present
+                meta = getattr(prompt, "meta", None)
+                if meta:
+                    prompt_info["meta"] = meta
+                    # Merge type/default info from meta.arguments into the arguments array
+                    if isinstance(meta, dict) and "arguments" in meta:
+                        meta_args = {a["name"]: a for a in meta["arguments"] if "name" in a}
+                        for arg in args:
+                            arg_name = arg.get("name")
+                            if arg_name and arg_name in meta_args:
+                                meta_arg = meta_args[arg_name]
+                                if "default" in meta_arg:
+                                    arg["default"] = meta_arg["default"]
+                                if "type" in meta_arg:
+                                    arg["type"] = meta_arg["type"]
+                                if "inputSchema" in meta_arg:
+                                    arg["inputSchema"] = meta_arg["inputSchema"]
+                analysis["prompts"].append(prompt_info)
+        except Exception as e:
+            if self.verbose:
+                hud_console.debug("Could not list prompts: " + str(e))
+
+        # Derive "scenarios" from Environment.@scenario prompts/resources.
+        # A scenario is exposed as:
+        # - Prompt: name "{env}:{scenario}" with description prefix "[Setup]"
+        # - Resource: uri "{env}:{scenario}" with description prefix "[Evaluate]"
+        # Both prompt and resource contain meta.code with the scenario source code
+        scenarios_by_id: dict[str, dict[str, Any]] = {}
+
+        for p in analysis.get("prompts", []):
+            desc = (p.get("description") or "").strip()
+            if not desc.startswith("[Setup]"):
+                continue
+            scenario_id = p.get("name")
+            if not scenario_id:
+                continue
+            env_name, scenario_name = ([*scenario_id.split(":", 1), ""])[:2]
+            scenario_info: dict[str, Any] = {
+                "id": scenario_id,
+                "env": env_name,
+                "name": scenario_name or scenario_id,
+                "setup_description": desc,
+                "arguments": p.get("arguments") or [],
+                "has_setup_prompt": True,
+                "has_evaluate_resource": False,
+            }
+            # Extract code from meta field if present
+            meta = p.get("meta")
+            if meta and isinstance(meta, dict) and "code" in meta:
+                scenario_info["code"] = meta["code"]
+            scenarios_by_id[scenario_id] = scenario_info
+
+        for r in analysis.get("resources", []):
+            desc = (r.get("description") or "").strip()
+            if not desc.startswith("[Evaluate]"):
+                continue
+            scenario_id = r.get("uri")
+            if not scenario_id:
+                continue
+            env_name, scenario_name = ([*scenario_id.split(":", 1), ""])[:2]
+            if scenario_id not in scenarios_by_id:
+                scenarios_by_id[scenario_id] = {
+                    "id": scenario_id,
+                    "env": env_name,
+                    "name": scenario_name or scenario_id,
+                    "arguments": [],
+                    "has_setup_prompt": False,
+                    "has_evaluate_resource": True,
+                }
+            scenarios_by_id[scenario_id]["evaluate_description"] = desc
+            scenarios_by_id[scenario_id]["has_evaluate_resource"] = True
+            # Extract code from meta field if not already present (from prompt)
+            meta = r.get("meta")
+            if (
+                meta
+                and isinstance(meta, dict)
+                and "code" in meta
+                and "code" not in scenarios_by_id[scenario_id]
+            ):
+                scenarios_by_id[scenario_id]["code"] = meta["code"]
+
+        analysis["scenarios"] = sorted(
+            scenarios_by_id.values(),
+            key=lambda s: (str(s.get("env") or ""), str(s.get("name") or "")),
+        )
 
         return analysis