hud-python 0.4.52__py3-none-any.whl → 0.4.53__py3-none-any.whl

hud/otel/tests/test_instrumentation.py

@@ -0,0 +1,207 @@
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+import pytest
+
+from hud.otel.instrumentation import (
+    _patch_get_error_type,
+    _patch_mcp_instrumentation,
+    install_mcp_instrumentation,
+)
+
+
+def test_install_mcp_instrumentation_success():
+    """Test successful installation of MCP instrumentation."""
+    mock_provider = MagicMock()
+
+    with (
+        patch("opentelemetry.instrumentation.mcp.instrumentation"),
+        patch(
+            "opentelemetry.instrumentation.mcp.instrumentation.McpInstrumentor"
+        ) as mock_instrumentor_class,
+        patch("hud.otel.instrumentation._patch_mcp_instrumentation"),
+    ):
+        mock_instrumentor = MagicMock()
+        mock_instrumentor_class.return_value = mock_instrumentor
+
+        install_mcp_instrumentation(mock_provider)
+
+        mock_instrumentor.instrument.assert_called_once_with(tracer_provider=mock_provider)
+
+
+def test_install_mcp_instrumentation_import_error():
+    """Test installation handles ImportError gracefully."""
+    mock_provider = MagicMock()
+
+    # Mock the import to raise ImportError
+    import sys
+
+    with patch.dict(sys.modules, {"opentelemetry.instrumentation.mcp.instrumentation": None}):
+        # Should not raise
+        install_mcp_instrumentation(mock_provider)
+
+
+def test_install_mcp_instrumentation_general_exception():
+    """Test installation handles general exceptions gracefully."""
+    mock_provider = MagicMock()
+
+    with (
+        patch("opentelemetry.instrumentation.mcp.instrumentation"),
+        patch(
+            "opentelemetry.instrumentation.mcp.instrumentation.McpInstrumentor"
+        ) as mock_instrumentor_class,
+    ):
+        mock_instrumentor_class.side_effect = Exception("Unexpected error")
+
+        # Should not raise
+        install_mcp_instrumentation(mock_provider)
+
+
+def test_patch_mcp_instrumentation_success():
+    """Test successful patching of MCP instrumentation."""
+    with (
+        patch("opentelemetry.instrumentation.mcp.instrumentation.McpInstrumentor") as mock_class,
+        patch("hud.otel.instrumentation._patch_get_error_type"),
+    ):
+        mock_class._transport_wrapper = None
+
+        _patch_mcp_instrumentation()
+
+        # Should have set the _transport_wrapper
+        assert mock_class._transport_wrapper is not None
+
+
+def test_patch_mcp_instrumentation_exception():
+    """Test patching handles exceptions gracefully."""
+    with patch(
+        "opentelemetry.instrumentation.mcp.instrumentation.McpInstrumentor",
+        side_effect=Exception("Error"),
+    ):
+        # Should not raise
+        _patch_mcp_instrumentation()
+
+
+def test_patch_get_error_type_success():
+    """Test successful patching of get_error_type."""
+    with patch("opentelemetry.instrumentation.mcp.instrumentation") as mock_mcp_inst:
+        mock_mcp_inst.get_error_type = None
+
+        _patch_get_error_type()
+
+        # Should have set get_error_type
+        assert mock_mcp_inst.get_error_type is not None
+
+
+def test_patch_get_error_type_exception():
+    """Test patching get_error_type handles exceptions."""
+    with patch(
+        "opentelemetry.instrumentation.mcp.instrumentation", side_effect=ImportError("Not found")
+    ):
+        # Should not raise
+        _patch_get_error_type()
+
+
+def test_patched_get_error_type_valid_4xx():
+    """Test patched get_error_type with valid 4xx status code."""
+    with patch("opentelemetry.instrumentation.mcp.instrumentation") as mock_mcp_inst:
+        _patch_get_error_type()
+
+        patched_func = mock_mcp_inst.get_error_type
+
+        # Test with a valid 4xx error
+        result = patched_func("Error 404 not found")
+        assert result == "NOT_FOUND"
+
+
+def test_patched_get_error_type_valid_5xx():
+    """Test patched get_error_type with valid 5xx status code."""
+    with patch("opentelemetry.instrumentation.mcp.instrumentation") as mock_mcp_inst:
+        _patch_get_error_type()
+
+        patched_func = mock_mcp_inst.get_error_type
+
+        # Test with a valid 5xx error
+        result = patched_func("Error 500 internal server error")
+        assert result == "INTERNAL_SERVER_ERROR"
+
+
+def test_patched_get_error_type_invalid_status():
+    """Test patched get_error_type with invalid status code."""
+    with patch("opentelemetry.instrumentation.mcp.instrumentation") as mock_mcp_inst:
+        _patch_get_error_type()
+
+        patched_func = mock_mcp_inst.get_error_type
+
+        # Test with an invalid HTTP status code (e.g., 499 doesn't exist in HTTPStatus)
+        result = patched_func("Error 499 custom error")
+        # Should return the name even if it's not a standard HTTPStatus
+        assert result is None or isinstance(result, str)
+
+
+def test_patched_get_error_type_no_status():
+    """Test patched get_error_type with no status code."""
+    with patch("opentelemetry.instrumentation.mcp.instrumentation") as mock_mcp_inst:
+        _patch_get_error_type()
+
+        patched_func = mock_mcp_inst.get_error_type
+
+        result = patched_func("Error message without status code")
+        assert result is None
+
+
+def test_patched_get_error_type_non_string():
+    """Test patched get_error_type with non-string input."""
+    with patch("opentelemetry.instrumentation.mcp.instrumentation") as mock_mcp_inst:
+        _patch_get_error_type()
+
+        patched_func = mock_mcp_inst.get_error_type
+
+        result = patched_func(None)
+        assert result is None
+
+        result = patched_func(123)
+        assert result is None
+
+
+def test_patched_get_error_type_3xx_ignored():
+    """Test patched get_error_type ignores 3xx codes."""
+    with patch("opentelemetry.instrumentation.mcp.instrumentation") as mock_mcp_inst:
+        _patch_get_error_type()
+
+        patched_func = mock_mcp_inst.get_error_type
+
+        result = patched_func("Error 301 moved")
+        assert result is None
+
+
+@pytest.mark.asyncio
+async def test_transport_wrapper_three_values():
+    """Test transport wrapper handles 3-value tuple."""
+    with (
+        patch("opentelemetry.instrumentation.mcp.instrumentation.McpInstrumentor") as mock_class,
+        patch("hud.otel.instrumentation._patch_get_error_type"),
+    ):
+        mock_class._transport_wrapper = None
+
+        _patch_mcp_instrumentation()
+
+        # Get the patched wrapper
+        wrapper_func = mock_class._transport_wrapper
+        assert wrapper_func is not None
+
+
+@pytest.mark.asyncio
+async def test_transport_wrapper_two_values():
+    """Test transport wrapper handles 2-value tuple."""
+    with (
+        patch("opentelemetry.instrumentation.mcp.instrumentation.McpInstrumentor") as mock_class,
+        patch("hud.otel.instrumentation._patch_get_error_type"),
+    ):
+        mock_class._transport_wrapper = None
+
+        _patch_mcp_instrumentation()
+
+        # Get the patched wrapper
+        wrapper_func = mock_class._transport_wrapper
+        assert wrapper_func is not None

hud/server/tests/test_server_extra.py

@@ -2,6 +2,7 @@
 from __future__ import annotations
 
 import asyncio
+import sys
 from contextlib import asynccontextmanager, suppress
 
 import anyio
@@ -98,6 +99,7 @@ async def test_last_shutdown_handler_wins(patch_stdio):
     server_mod._sigterm_received = False  # type: ignore[attr-defined]
 
 
+@pytest.mark.skipif(sys.platform == "win32", reason="asyncio.add_signal_handler is Unix-only")
 def test__run_with_sigterm_registers_handlers_when_enabled(monkeypatch: pytest.MonkeyPatch):
     """
     Verify that _run_with_sigterm attempts to register SIGTERM/SIGINT handlers

hud/shared/exceptions.py

@@ -185,11 +185,42 @@ class HudRequestError(HudException):
         self.response_text = response_text
         self.response_headers = response_headers
         # Compute default hints from status code if none provided
-        if hints is None and status_code in (401, 403, 429):
+        if hints is None and status_code in (401, 402, 403, 429):
             try:
-                from hud.shared.hints import HUD_API_KEY_MISSING, RATE_LIMIT_HIT  # type: ignore
-
-                if status_code in (401, 403):
+                from hud.shared.hints import (  # type: ignore
+                    CREDITS_EXHAUSTED,
+                    HUD_API_KEY_MISSING,
+                    PRO_PLAN_REQUIRED,
+                    RATE_LIMIT_HIT,
+                )
+
+                if status_code == 402:
+                    hints = [CREDITS_EXHAUSTED]
+                elif status_code == 403:
+                    # Default 403 to auth unless the message clearly indicates Pro plan
+                    combined_text = (message or "").lower()
+                    try:
+                        if response_text:
+                            combined_text += "\n" + str(response_text).lower()
+                    except Exception:  # noqa: S110
+                        pass
+                    try:
+                        if response_json and isinstance(response_json, dict):
+                            detail = response_json.get("detail")
+                            if isinstance(detail, str):
+                                combined_text += "\n" + detail.lower()
+                    except Exception:  # noqa: S110
+                        pass
+
+                    mentions_pro = (
+                        "pro plan" in combined_text
+                        or "requires pro" in combined_text
+                        or "pro mode" in combined_text
+                        or combined_text.strip().startswith("pro ")
+                    )
+
+                    hints = [PRO_PLAN_REQUIRED] if mentions_pro else [HUD_API_KEY_MISSING]
+                elif status_code == 401:
                     hints = [HUD_API_KEY_MISSING]
                 elif status_code == 429:
                     hints = [RATE_LIMIT_HIT]

hud/shared/hints.py

@@ -61,6 +61,31 @@ RATE_LIMIT_HIT = Hint(
     context=["network"],
 )
 
+# Billing / plan upgrade
+PRO_PLAN_REQUIRED = Hint(
+    title="Pro plan required",
+    message="This feature requires Pro.",
+    tips=[
+        "Upgrade your plan to continue",
+    ],
+    docs_url="https://hud.so/project/billing",
+    command_examples=None,
+    code="PRO_PLAN_REQUIRED",
+    context=["billing", "plan"],
+)
+
+CREDITS_EXHAUSTED = Hint(
+    title="Credits exhausted",
+    message="Your credits are exhausted.",
+    tips=[
+        "Top up credits or upgrade your plan",
+    ],
+    docs_url="https://hud.so/project/billing",
+    command_examples=None,
+    code="CREDITS_EXHAUSTED",
+    context=["billing", "credits"],
+)
+
 TOOL_NOT_FOUND = Hint(
     title="Tool not found",
     message="Requested tool doesn't exist.",

hud/shared/requests.py

@@ -18,7 +18,11 @@ from hud.shared.exceptions import (
     HudRequestError,
     HudTimeoutError,
 )
-from hud.shared.hints import HUD_API_KEY_MISSING, RATE_LIMIT_HIT
+from hud.shared.hints import (
+    CREDITS_EXHAUSTED,
+    HUD_API_KEY_MISSING,
+    RATE_LIMIT_HIT,
+)
 
 # Set up logger
 logger = logging.getLogger("hud.http")
@@ -137,9 +141,13 @@ async def make_request(
                 raise HudTimeoutError(f"Request timed out: {e!s}") from None
             except httpx.HTTPStatusError as e:
                 err = HudRequestError.from_httpx_error(e)
-                if getattr(err, "status_code", None) == 429 and RATE_LIMIT_HIT not in err.hints:
+                code = getattr(err, "status_code", None)
+                if code == 429 and RATE_LIMIT_HIT not in err.hints:
                     logger.debug("Attaching RATE_LIMIT hint to 429 error")
                     err.hints.append(RATE_LIMIT_HIT)
+                elif code == 402 and CREDITS_EXHAUSTED not in err.hints:
+                    logger.debug("Attaching CREDITS_EXHAUSTED hint to 402 error")
+                    err.hints.append(CREDITS_EXHAUSTED)
                 raise err from None
             except httpx.RequestError as e:
                 if attempt <= max_retries:
@@ -234,9 +242,13 @@ def make_request_sync(
                 raise HudTimeoutError(f"Request timed out: {e!s}") from None
             except httpx.HTTPStatusError as e:
                 err = HudRequestError.from_httpx_error(e)
-                if getattr(err, "status_code", None) == 429 and RATE_LIMIT_HIT not in err.hints:
+                code = getattr(err, "status_code", None)
+                if code == 429 and RATE_LIMIT_HIT not in err.hints:
                     logger.debug("Attaching RATE_LIMIT hint to 429 error")
                     err.hints.append(RATE_LIMIT_HIT)
+                elif code == 402 and CREDITS_EXHAUSTED not in err.hints:
+                    logger.debug("Attaching CREDITS_EXHAUSTED hint to 402 error")
+                    err.hints.append(CREDITS_EXHAUSTED)
                 raise err from None
             except httpx.RequestError as e:
                 if attempt <= max_retries:

hud/shared/tests/test_exceptions.py

@@ -17,7 +17,6 @@ from hud.shared.exceptions import (
     HudClientError,
     HudConfigError,
     HudException,
-    HudMCPError,
     HudRateLimitError,
     HudRequestError,
     HudTimeoutError,
@@ -27,6 +26,7 @@ from hud.shared.hints import (
     CLIENT_NOT_INITIALIZED,
     HUD_API_KEY_MISSING,
     INVALID_CONFIG,
+    PRO_PLAN_REQUIRED,
     RATE_LIMIT_HIT,
     TOOL_NOT_FOUND,
 )
@@ -157,25 +157,23 @@ class TestHudExceptionAutoConversion:
             assert str(exc_info.value) == "Async operation timed out"
 
     def test_generic_error_remains_hudexception(self):
-        """Test that unmatched errors remain as base HudException."""
+        """Uncategorized errors become base HudException with original message."""
         try:
             raise ValueError("Some random error")
         except Exception as e:
             with pytest.raises(HudException) as exc_info:
                 raise HudException from e
-
-            # Should be base HudException, not a subclass
+            # Should be base HudException, not subclass
             assert type(exc_info.value) is HudException
-            assert exc_info.value.hints == []
+            assert str(exc_info.value) == "Some random error"
 
     def test_custom_message_override(self):
-        """Test that custom message overrides the original."""
+        """Custom message should be used for categorized errors."""
         try:
-            raise ValueError("Original error")
+            raise ValueError("Client not initialized - call initialize() first")
         except Exception as e:
-            with pytest.raises(HudException) as exc_info:
+            with pytest.raises(HudClientError) as exc_info:
                 raise HudException("Custom error message") from e
-
             assert str(exc_info.value) == "Custom error message"
 
     def test_already_hud_exception_passthrough(self):
@@ -205,6 +203,22 @@ class TestHudRequestError:
         error = HudRequestError("Forbidden", status_code=403)
         assert HUD_API_KEY_MISSING in error.hints
 
+    def test_403_pro_plan_message_sets_pro_hint(self):
+        """403 with Pro wording should map to PRO_PLAN_REQUIRED, not auth."""
+        error = HudRequestError("Feature requires Pro plan", status_code=403)
+        assert PRO_PLAN_REQUIRED in error.hints
+        assert HUD_API_KEY_MISSING not in error.hints
+
+    def test_403_pro_plan_detail_sets_pro_hint(self):
+        """403 with detail indicating Pro should map to PRO_PLAN_REQUIRED."""
+        error = HudRequestError(
+            "Forbidden",
+            status_code=403,
+            response_json={"detail": "Requires Pro plan"},
+        )
+        assert PRO_PLAN_REQUIRED in error.hints
+        assert HUD_API_KEY_MISSING not in error.hints
+
     def test_429_adds_rate_limit_hint(self):
         """Test that 429 status adds rate limit hint."""
         error = HudRequestError("Too Many Requests", status_code=429)
@@ -244,23 +258,19 @@ class TestMCPErrorHandling:
     @pytest.mark.asyncio
     async def test_mcp_error_handling(self):
         """Test that McpError is handled appropriately."""
-
-        # Create a mock McpError class
-        class McpError(Exception):
-            pass
-
-        # Create a mock MCP error
-        mcp_error = McpError("MCP protocol error: Unknown method")
+        # Create a dynamic class named "McpError" to trigger name-based detection
+        McpError = type("McpError", (Exception,), {})
 
         try:
-            raise mcp_error
+            raise McpError("MCP protocol error: Unknown method")
         except Exception as e:
             # This would typically be caught in the client code
             # and re-raised as HudException
-            with pytest.raises(HudMCPError) as exc_info:
+            with pytest.raises(HudException) as exc_info:
                 raise HudException from e
 
             assert "MCP protocol error" in str(exc_info.value)
+            assert "MCP protocol error" in str(exc_info.value)
 
     def test_mcp_tool_error_result(self):
         """Test handling of MCP tool execution errors (isError: true)."""
@@ -353,6 +363,7 @@ class TestExceptionRendering:
         assert len(error.hints) == 1
         assert error.hints[0] == HUD_API_KEY_MISSING
         assert error.hints[0].title == "HUD API key required"
+        # Hint copy evolved; keep the assertion robust to minor copy changes
         assert "Set HUD_API_KEY" in error.hints[0].tips[0]
 
     def test_exception_type_preservation(self):
@@ -397,16 +408,13 @@ class TestEdgeCases:
             assert type(error) is HudException
 
     def test_empty_error_message(self):
-        """Test handling of empty error messages."""
+        """Empty message still results in a HudException instance."""
         try:
             raise ValueError("")
         except Exception as e:
-            with pytest.raises(HudException) as exc_info:
+            with pytest.raises(HudException):
                 raise HudException from e
 
-            # Should still have some message
-            assert str(exc_info.value) != ""
-
     def test_circular_exception_chain(self):
         """Test that we don't create circular exception chains."""
         original = HudAuthenticationError("Original")

hud/shared/tests/test_hints.py

@@ -0,0 +1,167 @@
+from __future__ import annotations
+
+from unittest.mock import MagicMock, patch
+
+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,
+    render_hints,
+)
+
+
+def test_hint_objects_basic():
+    assert HUD_API_KEY_MISSING.title and isinstance(HUD_API_KEY_MISSING.tips, list)
+    assert RATE_LIMIT_HIT.code == "RATE_LIMIT"
+    assert TOOL_NOT_FOUND.title.startswith("Tool")
+    assert CLIENT_NOT_INITIALIZED.message
+    assert ENV_VAR_MISSING.command_examples is not None
+
+
+def test_all_hint_constants():
+    """Test that all predefined hint constants have required fields."""
+    hints = [
+        HUD_API_KEY_MISSING,
+        RATE_LIMIT_HIT,
+        TOOL_NOT_FOUND,
+        CLIENT_NOT_INITIALIZED,
+        INVALID_CONFIG,
+        ENV_VAR_MISSING,
+        MCP_SERVER_ERROR,
+    ]
+
+    for hint in hints:
+        assert hint.title
+        assert hint.message
+        assert hint.code
+
+
+def test_hint_creation():
+    """Test creating a custom Hint."""
+    hint = Hint(
+        title="Test Hint",
+        message="This is a test",
+        tips=["Tip 1", "Tip 2"],
+        docs_url="https://example.com",
+        command_examples=["command 1"],
+        code="TEST_CODE",
+        context=["test", "custom"],
+    )
+
+    assert hint.title == "Test Hint"
+    assert hint.message == "This is a test"
+    assert hint.tips and len(hint.tips) == 2
+    assert hint.docs_url == "https://example.com"
+    assert hint.command_examples and len(hint.command_examples) == 1
+    assert hint.code == "TEST_CODE"
+    assert hint.context and "test" in hint.context
+
+
+def test_hint_minimal():
+    """Test creating a minimal Hint with only required fields."""
+    hint = Hint(title="Minimal", message="Just basics")
+
+    assert hint.title == "Minimal"
+    assert hint.message == "Just basics"
+    assert hint.tips is None
+    assert hint.docs_url is None
+    assert hint.command_examples is None
+    assert hint.code is None
+    assert hint.context is None
+
+
+def test_render_hints_none():
+    """Test that render_hints handles None gracefully."""
+    # Should not raise
+    render_hints(None)
+
+
+def test_render_hints_empty_list():
+    """Test that render_hints handles empty list gracefully."""
+    # Should not raise
+    render_hints([])
+
+
+@patch("hud.utils.hud_console.hud_console")
+def test_render_hints_with_tips(mock_console):
+    """Test rendering hints with tips."""
+    render_hints([HUD_API_KEY_MISSING])
+
+    # Should call warning for title/message
+    mock_console.warning.assert_called()
+    # Should call info for tips
+    assert mock_console.info.call_count >= 1
+
+
+@patch("hud.utils.hud_console.hud_console")
+def test_render_hints_with_command_examples(mock_console):
+    """Test rendering hints with command examples."""
+    render_hints([ENV_VAR_MISSING])
+
+    # Should call command_example
+    mock_console.command_example.assert_called()
+
+
+@patch("hud.utils.hud_console.hud_console")
+def test_render_hints_with_docs_url(mock_console):
+    """Test rendering hints with documentation URL."""
+    hint = Hint(
+        title="Test",
+        message="Test message",
+        docs_url="https://docs.example.com",
+    )
+
+    render_hints([hint])
+
+    # Should call link for docs URL
+    mock_console.link.assert_called_with("https://docs.example.com")
+
+
+@patch("hud.utils.hud_console.hud_console")
+def test_render_hints_same_title_and_message(mock_console):
+    """Test rendering hints when title equals message."""
+    hint = Hint(title="Same", message="Same")
+
+    render_hints([hint])
+
+    # Should only call warning once with just the message
+    mock_console.warning.assert_called_once_with("Same")
+
+
+@patch("hud.utils.hud_console.hud_console")
+def test_render_hints_different_title_and_message(mock_console):
+    """Test rendering hints when title differs from message."""
+    hint = Hint(title="Title", message="Different message")
+
+    render_hints([hint])
+
+    # Should call warning with both title and message
+    mock_console.warning.assert_called_once()
+    call_args = mock_console.warning.call_args[0][0]
+    assert "Title" in call_args
+    assert "Different message" in call_args
+
+
+def test_render_hints_with_custom_design():
+    """Test rendering hints with custom design object."""
+    custom_design = MagicMock()
+
+    hint = Hint(title="Test", message="Message")
+    # Should not raise when custom design is provided
+    render_hints([hint], design=custom_design)
+
+
+@patch("hud.utils.hud_console.hud_console")
+def test_render_hints_handles_exception(mock_console):
+    """Test that render_hints handles exceptions gracefully."""
+    mock_console.warning.side_effect = Exception("Test error")
+
+    hint = Hint(title="Test", message="Message")
+
+    # Should not raise, just log warning
+    render_hints([hint])