hud-python 0.4.19__py3-none-any.whl → 0.4.21__py3-none-any.whl

hud/shared/exceptions.py

@@ -1,36 +1,179 @@
+"""HUD SDK Exception System.
+
+This module provides intelligent exception handling with automatic error
+classification and helpful hints for users.
+
+Key Features:
+- Auto-converts generic exceptions to specific HUD exceptions
+- Attaches contextual hints based on error type
+- Clean chaining syntax: raise HudException() from e
+
+Example:
+    try:
+        client.call_tool("missing")
+    except Exception as e:
+        raise HudException() from e  # Becomes HudToolNotFoundError with hints
+"""
+
 from __future__ import annotations
 
+import asyncio
+import json
 import logging
-from typing import TYPE_CHECKING, Any
+from typing import TYPE_CHECKING, Any, ClassVar, TypeVar
 
 if TYPE_CHECKING:
     from typing import Self
 
     import httpx
 
+from hud.shared.hints import (
+    CLIENT_NOT_INITIALIZED,
+    ENV_VAR_MISSING,
+    HUD_API_KEY_MISSING,
+    INVALID_CONFIG,
+    MCP_SERVER_ERROR,
+    RATE_LIMIT_HIT,
+    TOOL_NOT_FOUND,
+    Hint,
+)
+
+T = TypeVar("T", bound="HudException")
+
 logger = logging.getLogger(__name__)
 
 
 class HudException(Exception):
     """Base exception class for all HUD SDK errors.
 
-    This is the parent class for all exceptions raised by the HUD SDK.
-    Consumers should be able to catch this exception to handle any HUD-related error.
+    Usage:
+        raise HudException() from e  # Auto-converts to appropriate subclass
+        raise HudException("Custom message") from e  # With custom message
     """
 
-    def __init__(self, message: str, response_json: dict[str, Any] | None = None) -> None:
-        super().__init__(message)
-        self.message = message
+    def __new__(cls, message: str = "", *args: Any, **kwargs: Any) -> Any:
+        """Auto-convert generic exceptions to specific HUD exceptions when chained."""
+        import sys
+
+        # Only intercept for base HudException, not subclasses
+        if cls is not HudException:
+            return super().__new__(cls)
+
+        # Check if we're in a 'raise...from' context
+        exc_type, exc_value, _ = sys.exc_info()
+        if exc_type and exc_value:
+            # If it's already a HudException, return it as-is
+            if isinstance(exc_value, HudException):
+                return exc_value
+            # Otherwise analyze if it's a regular Exception
+            elif isinstance(exc_value, Exception):
+                # Try to convert to a specific HudException
+                result = cls._analyze_exception(exc_value, message or str(exc_value))
+                # If we couldn't categorize it (still base HudException),
+                # just re-raise the original exception
+                if type(result) is HudException:
+                    # Re-raise the original exception unchanged
+                    raise exc_value from None
+                return result
+
+        # Normal creation
+        return super().__new__(cls)
+
+    # Subclasses can override this class attribute
+    default_hints: ClassVar[list[Hint]] = []
+
+    def __init__(
+        self,
+        message: str = "",
+        response_json: dict[str, Any] | None = None,
+        *,
+        hints: list[Hint] | None = None,
+    ) -> None:
+        # If we already have args set (from _analyze_exception), don't override them
+        if not self.args:
+            # Pass the message to the base Exception class
+            super().__init__(message)
+        self.message = message or (self.args[0] if self.args else "")
         self.response_json = response_json
+        # If hints not provided, use defaults defined by subclass
+        self.hints: list[Hint] = hints if hints is not None else list(self.default_hints)
 
     def __str__(self) -> str:
-        parts = [self.message]
+        # Get the message from the exception
+        # First check if we have args (standard Exception message storage)
+        msg = str(self.args[0]) if self.args and self.args[0] else ""
+
+        # Add response JSON if available
         if self.response_json:
-            parts.append(f"Response: {self.response_json}")
-        return " | ".join(parts)
+            if msg:
+                return f"{msg} | Response: {self.response_json}"
+            else:
+                return f"Response: {self.response_json}"
 
+        return msg
 
-class HudRequestError(Exception):
+    @classmethod
+    def _analyze_exception(cls, e: Exception, message: str = "") -> HudException:
+        """Convert generic exceptions to specific HUD exceptions based on content."""
+        error_msg = str(e).lower()
+        final_msg = message or str(e)
+
+        # Map error patterns to exception types
+        patterns = [
+            # (condition_func, exception_class)
+            (
+                lambda: "not initialized" in error_msg or "not connected" in error_msg,
+                HudClientError,
+            ),
+            (
+                lambda: "invalid json" in error_msg or "config" in error_msg or "json" in error_msg,
+                HudConfigError,
+            ),
+            (
+                lambda: "tool" in error_msg
+                and ("not found" in error_msg or "not exist" in error_msg),
+                HudToolNotFoundError,
+            ),
+            (
+                lambda: ("api key" in error_msg or "authorization" in error_msg)
+                and ("hud" in error_msg or "mcp.hud.so" in error_msg),
+                HudAuthenticationError,
+            ),
+            (
+                lambda: "rate limit" in error_msg or "too many request" in error_msg,
+                HudRateLimitError,
+            ),
+            (lambda: isinstance(e, (TimeoutError | asyncio.TimeoutError)), HudTimeoutError),
+            (lambda: isinstance(e, json.JSONDecodeError), HudConfigError),
+            (
+                lambda: "environment variable" in error_msg and "required" in error_msg,
+                HudEnvVarError,
+            ),
+            (lambda: "event loop" in error_msg and "closed" in error_msg, HudClientError),
+            (
+                lambda: type(e).__name__ == "McpError",  # Check by name to avoid import issues
+                HudMCPError,
+            ),
+        ]
+
+        # Find first matching pattern
+        for condition, exception_class in patterns:
+            if condition():
+                # Create instance directly using Exception.__new__ to bypass our custom __new__
+                instance = Exception.__new__(exception_class)
+                # Manually set args before calling __init__ to ensure proper Exception behavior
+                instance.args = (final_msg,)
+                instance.__init__(final_msg)
+                return instance
+
+        # No pattern matched - return base exception instance
+        instance = Exception.__new__(HudException)
+        instance.args = (final_msg,)
+        instance.__init__(final_msg)
+        return instance
+
+
+class HudRequestError(HudException):
     """Any request to the HUD API can raise this exception."""
 
     def __init__(
@@ -40,13 +183,24 @@ class HudRequestError(Exception):
         response_text: str | None = None,
         response_json: dict[str, Any] | None = None,
         response_headers: dict[str, str] | None = None,
+        *,
+        hints: list[Hint] | None = None,
     ) -> None:
-        self.message = message
         self.status_code = status_code
         self.response_text = response_text
-        self.response_json = response_json
         self.response_headers = response_headers
-        super().__init__(message)
+        # Compute default hints from status code if none provided
+        if hints is None and status_code in (401, 403, 429):
+            try:
+                from hud.shared.hints import HUD_API_KEY_MISSING, RATE_LIMIT_HIT  # type: ignore
+
+                if status_code in (401, 403):
+                    hints = [HUD_API_KEY_MISSING]
+                elif status_code == 429:
+                    hints = [RATE_LIMIT_HIT]
+            except Exception as import_error:
+                logger.debug("Failed to attach structured hints: %s", import_error)
+        super().__init__(message, response_json, hints=hints)
 
     def __str__(self) -> str:
         parts = [self.message]
@@ -110,13 +264,14 @@ class HudRequestError(Exception):
             response_text[:500],
             "..." if len(response_text) > 500 else "",
         )
-        return cls(
+        inst = cls(
             message=message,
             status_code=status_code,
             response_text=response_text,
             response_json=response_json,
             response_headers=response_headers,
         )
+        return inst
 
 
 class HudResponseError(HudException):
@@ -148,35 +303,53 @@ class HudResponseError(HudException):
 
 
 class HudAuthenticationError(HudException):
-    """Raised when authentication with the HUD API fails.
+    """Missing or invalid HUD API key."""
 
-    This exception is raised when an API key is missing, invalid, or
-    has insufficient permissions for the requested operation.
-    """
+    default_hints: ClassVar[list[Hint]] = [HUD_API_KEY_MISSING]
 
 
 class HudRateLimitError(HudException):
-    """Raised when the rate limit for the HUD API is exceeded.
+    """Too many requests to the API."""
 
-    This exception is raised when too many requests are made in a
-    short period of time.
-    """
+    default_hints: ClassVar[list[Hint]] = [RATE_LIMIT_HIT]
 
 
 class HudTimeoutError(HudException):
-    """Raised when a request to the HUD API times out.
-
-    This exception is raised when a request takes longer than the
-    configured timeout period.
-    """
+    """Request timed out."""
 
 
 class HudNetworkError(HudException):
-    """Raised when there is a network-related error.
+    """Network connection issue."""
 
-    This exception is raised when there are issues with the network
-    connection, DNS resolution, or other network-related problems.
-    """
+
+class HudClientError(HudException):
+    """MCP client not initialized."""
+
+    default_hints: ClassVar[list[Hint]] = [CLIENT_NOT_INITIALIZED]
+
+
+class HudConfigError(HudException):
+    """Invalid or missing configuration."""
+
+    default_hints: ClassVar[list[Hint]] = [INVALID_CONFIG]
+
+
+class HudEnvVarError(HudException):
+    """Missing required environment variables."""
+
+    default_hints: ClassVar[list[Hint]] = [ENV_VAR_MISSING]
+
+
+class HudToolNotFoundError(HudException):
+    """Requested tool not found."""
+
+    default_hints: ClassVar[list[Hint]] = [TOOL_NOT_FOUND]
+
+
+class HudMCPError(HudException):
+    """MCP protocol or server error."""
+
+    default_hints: ClassVar[list[Hint]] = [MCP_SERVER_ERROR]
 
 
 class GymMakeException(HudException):

hud/shared/hints.py

@@ -0,0 +1,177 @@
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from typing import TYPE_CHECKING, Any
+
+if TYPE_CHECKING:
+    from collections.abc import Iterable
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class Hint:
+    """Structured hint for user guidance.
+
+    Attributes:
+        title: Short title describing the hint.
+        message: Main explanatory message.
+        tips: Optional list of short actionable tips.
+        docs_url: Optional URL for documentation.
+        command_examples: Optional list of command examples to show.
+        code: Optional machine-readable code (e.g., "AUTH_API_KEY_MISSING").
+        context: Optional context tags (e.g., ["auth", "docker", "mcp"]).
+    """
+
+    title: str
+    message: str
+    tips: list[str] | None = None
+    docs_url: str | None = None
+    command_examples: list[str] | None = None
+    code: str | None = None
+    context: list[str] | None = None
+
+
+# Common, reusable hints
+HUD_API_KEY_MISSING = Hint(
+    title="HUD API key required",
+    message="Missing or invalid HUD_API_KEY.",
+    tips=[
+        "Set HUD_API_KEY environment variable",
+        "Get a key at https://app.hud.so",
+        "Check for whitespace or truncation",
+    ],
+    docs_url=None,
+    command_examples=None,
+    code="HUD_AUTH_MISSING",
+    context=["auth", "hud"],
+)
+
+RATE_LIMIT_HIT = Hint(
+    title="Rate limit reached",
+    message="Too many requests.",
+    tips=[
+        "Lower --max-concurrent",
+        "Add retry delay",
+        "Check API quotas",
+    ],
+    docs_url=None,
+    command_examples=None,
+    code="RATE_LIMIT",
+    context=["network"],
+)
+
+TOOL_NOT_FOUND = Hint(
+    title="Tool not found",
+    message="Requested tool doesn't exist.",
+    tips=[
+        "Check tool name spelling",
+        "Run: hud analyze --live <image>",
+        "Verify server implements tool",
+    ],
+    docs_url=None,
+    command_examples=None,
+    code="TOOL_NOT_FOUND",
+    context=["mcp", "tools"],
+)
+
+CLIENT_NOT_INITIALIZED = Hint(
+    title="Client not initialized",
+    message="MCP client must be initialized before use.",
+    tips=[
+        "Call client.initialize() first",
+        "Or use async with client:",
+        "Check connection succeeded",
+    ],
+    docs_url=None,
+    command_examples=None,
+    code="CLIENT_NOT_INIT",
+    context=["mcp", "client"],
+)
+
+INVALID_CONFIG = Hint(
+    title="Invalid configuration",
+    message="Configuration is missing or malformed.",
+    tips=[
+        "Check JSON syntax",
+        "Verify required fields",
+        "See examples in docs",
+    ],
+    docs_url=None,
+    command_examples=None,
+    code="INVALID_CONFIG",
+    context=["config"],
+)
+
+ENV_VAR_MISSING = Hint(
+    title="Environment variable required",
+    message="Required environment variables are missing.",
+    tips=[
+        "Set required environment variables",
+        "Use -e flag: hud build . -e VAR_NAME=value",
+        "Check Dockerfile for ENV requirements",
+        "Run hud debug . --build for detailed logs",
+    ],
+    docs_url=None,
+    command_examples=["hud build . -e BROWSER_PROVIDER=anchorbrowser"],
+    code="ENV_VAR_MISSING",
+    context=["env", "config"],
+)
+
+MCP_SERVER_ERROR = Hint(
+    title="MCP server error",
+    message="The MCP server encountered an error.",
+    tips=[
+        "Check server logs for details",
+        "Verify server configuration",
+        "Ensure all dependencies are installed",
+        "Run hud debug to see detailed output",
+    ],
+    docs_url=None,
+    command_examples=["hud debug", "hud dev --verbose"],
+    code="MCP_SERVER_ERROR",
+    context=["mcp", "server"],
+)
+
+
+def render_hints(hints: Iterable[Hint] | None, *, design: Any | None = None) -> None:
+    """Render a collection of hints using the HUD design system if available.
+
+    If design is not provided, this is a no-op to keep library use headless.
+    """
+    if not hints:
+        return
+
+    try:
+        if design is None:
+            from hud.utils.design import design as default_design  # lazy import
+
+            design = default_design
+    except Exception:
+        # If design is unavailable (non-CLI contexts), silently skip rendering
+        return
+
+    for hint in hints:
+        try:
+            # Compact rendering - skip title if same as message
+            if hint.title and hint.title != hint.message:
+                design.warning(f"{hint.title}: {hint.message}")
+            else:
+                design.warning(hint.message)
+
+            # Tips as bullet points
+            if hint.tips:
+                for tip in hint.tips:
+                    design.info(f"  • {tip}")
+
+            # Only show command examples if provided
+            if hint.command_examples:
+                for cmd in hint.command_examples:
+                    design.command_example(cmd)
+
+            # Only show docs URL if provided
+            if hint.docs_url:
+                design.link(hint.docs_url)
+        except Exception:
+            logger.warning("Failed to render hint: %s", hint)
+            continue

hud/shared/requests.py

@@ -18,6 +18,7 @@ from hud.shared.exceptions import (
     HudRequestError,
     HudTimeoutError,
 )
+from hud.shared.hints import HUD_API_KEY_MISSING, RATE_LIMIT_HIT
 
 # Set up logger
 logger = logging.getLogger("hud.http")
@@ -97,7 +98,10 @@ async def make_request(
         HudTimeoutError: If the request times out.
     """
     if not api_key:
-        raise HudAuthenticationError("API key is required but not provided")
+        raise HudAuthenticationError(
+            "API key is required but not provided",
+            hints=[HUD_API_KEY_MISSING],
+        )
 
     headers = {"Authorization": f"Bearer {api_key}"}
     retry_status_codes = [502, 503, 504]
@@ -132,7 +136,11 @@ async def make_request(
             except httpx.TimeoutException as e:
                 raise HudTimeoutError(f"Request timed out: {e!s}") from None
             except httpx.HTTPStatusError as e:
-                raise HudRequestError.from_httpx_error(e) from None
+                err = HudRequestError.from_httpx_error(e)
+                if getattr(err, "status_code", None) == 429 and RATE_LIMIT_HIT not in err.hints:
+                    logger.debug("Attaching RATE_LIMIT hint to 429 error")
+                    err.hints.append(RATE_LIMIT_HIT)
+                raise err from None
             except httpx.RequestError as e:
                 if attempt <= max_retries:
                     await _handle_retry(
@@ -225,7 +233,11 @@ def make_request_sync(
             except httpx.TimeoutException as e:
                 raise HudTimeoutError(f"Request timed out: {e!s}") from None
             except httpx.HTTPStatusError as e:
-                raise HudRequestError.from_httpx_error(e) from None
+                err = HudRequestError.from_httpx_error(e)
+                if getattr(err, "status_code", None) == 429 and RATE_LIMIT_HIT not in err.hints:
+                    logger.debug("Attaching RATE_LIMIT hint to 429 error")
+                    err.hints.append(RATE_LIMIT_HIT)
+                raise err from None
             except httpx.RequestError as e:
                 if attempt <= max_retries:
                     retry_time = retry_delay * (2 ** (attempt - 1))