simplified example in Common Error Scenarios for clarity

Author: tejas-dharani

python/docs/src/user-guide/core-user-guide/components/tools.ipynb

@@ -611,128 +611,56 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "import json\n",
-    "from typing import Any, Dict, Optional\n",
-    "\n",
-    "import requests\n",
+    "from typing import Optional\n",
     "from typing_extensions import Annotated\n",
     "\n",
-    "\n",
-    "async def robust_web_search(query: Annotated[str, \"Search query\"]) -> str:\n",
-    "    \"\"\"A robust web search tool that handles various error conditions.\"\"\"\n",
-    "\n",
+    "async def weather_forecast(city: Annotated[str, \"City name\"]) -> str:\n",
+    "    \"\"\"Get weather forecast for a city with error handling.\"\"\"\n",
+    "    \n",
     "    # Input validation\n",
-    "    if not query or not query.strip():\n",
-    "        raise ValueError(\"Search query cannot be empty\")\n",
-    "\n",
-    "    if len(query) > 500:\n",
-    "        raise ValueError(\"Search query is too long (max 500 characters)\")\n",
-    "\n",
-    "    try:\n",
-    "        # Simulate API call (replace with actual search API)\n",
-    "        # This is where you would make the actual HTTP request\n",
-    "\n",
-    "        # Simulate different types of failures\n",
-    "        if \"timeout\" in query.lower():\n",
-    "            raise requests.exceptions.Timeout(\"Search request timed out\")\n",
-    "\n",
-    "        if \"unauthorized\" in query.lower():\n",
-    "            raise requests.exceptions.HTTPError(\"401 Unauthorized: Invalid API key\")\n",
-    "\n",
-    "        if \"rate_limit\" in query.lower():\n",
-    "            raise requests.exceptions.HTTPError(\"429 Too Many Requests: Rate limit exceeded\")\n",
-    "\n",
-    "        # Simulate successful response\n",
-    "        return f\"Search results for '{query}': Found relevant information about the topic.\"\n",
-    "\n",
-    "    except requests.exceptions.Timeout as e:\n",
-    "        # Handle timeout specifically\n",
-    "        raise TimeoutError(f\"Search request for '{query}' timed out. Please try again.\") from e\n",
-    "\n",
-    "    except requests.exceptions.HTTPError as e:\n",
-    "        # Handle HTTP errors with specific messages\n",
-    "        if \"401\" in str(e):\n",
-    "            raise PermissionError(\"Search API authentication failed. Please check your API key.\") from e\n",
-    "        elif \"429\" in str(e):\n",
-    "            raise RuntimeError(\"Search API rate limit exceeded. Please wait before trying again.\") from e\n",
-    "        else:\n",
-    "            raise ConnectionError(f\"Search API error: {e}\") from e\n",
-    "\n",
-    "    except requests.exceptions.RequestException as e:\n",
-    "        # Handle other network-related errors\n",
-    "        raise ConnectionError(f\"Network error during search: {e}\") from e\n",
-    "\n",
-    "    except Exception as e:\n",
-    "        # Handle any other unexpected errors\n",
-    "        raise RuntimeError(f\"Unexpected error during search: {e}\") from e\n",
-    "\n",
-    "\n",
-    "async def file_processor(file_path: Annotated[str, \"Path to file to process\"]) -> str:\n",
-    "    \"\"\"A file processing tool with comprehensive error handling.\"\"\"\n",
-    "\n",
+    "    if not city or not city.strip():\n",
+    "        raise ValueError(\"City name cannot be empty\")\n",
+    "    \n",
     "    try:\n",
-    "        # Simulate file operations\n",
-    "        if not file_path:\n",
-    "            raise ValueError(\"File path cannot be empty\")\n",
-    "\n",
-    "        if file_path == \"nonexistent.txt\":\n",
-    "            raise FileNotFoundError(f\"File not found: {file_path}\")\n",
-    "\n",
-    "        if file_path == \"permission_denied.txt\":\n",
-    "            raise PermissionError(f\"Permission denied accessing file: {file_path}\")\n",
-    "\n",
-    "        if file_path == \"corrupted.txt\":\n",
-    "            raise ValueError(f\"File appears to be corrupted: {file_path}\")\n",
-    "\n",
-    "        # Simulate successful processing\n",
-    "        return f\"Successfully processed file: {file_path}\"\n",
-    "\n",
-    "    except FileNotFoundError as e:\n",
-    "        # Re-raise with more context\n",
-    "        raise FileNotFoundError(f\"The file '{file_path}' does not exist. Please check the path and try again.\") from e\n",
-    "\n",
-    "    except PermissionError as e:\n",
-    "        # Re-raise with helpful message\n",
-    "        raise PermissionError(f\"Access denied to file '{file_path}'. Please check file permissions.\") from e\n",
-    "\n",
+    "        # Simulate API behavior for demonstration\n",
+    "        if city.lower() == \"error\":\n",
+    "            raise ConnectionError(\"Failed to connect to weather service\")\n",
+    "            \n",
+    "        if city.lower() == \"unknown\":\n",
+    "            raise ValueError(f\"City not found: {city}\")\n",
+    "            \n",
+    "        # Successful case\n",
+    "        return f\"The weather in {city} is sunny with a high of 75°F\"\n",
+    "        \n",
+    "    except ConnectionError as e:\n",
+    "        # Network-related errors\n",
+    "        raise ConnectionError(f\"Network error: {e}. Please try again later.\")\n",
+    "        \n",
     "    except ValueError as e:\n",
-    "        # Handle validation errors\n",
-    "        raise ValueError(f\"Invalid file or content: {e}\") from e\n",
-    "\n",
+    "        # Data-related errors\n",
+    "        raise ValueError(f\"Invalid city: {e}\")\n",
+    "        \n",
     "    except Exception as e:\n",
-    "        # Catch-all for unexpected errors\n",
-    "        raise RuntimeError(f\"Unexpected error processing file '{file_path}': {e}\") from e\n",
-    "\n",
-    "\n",
-    "# Create tools\n",
-    "search_tool = FunctionTool(robust_web_search, description=\"Search the web for information\")\n",
-    "file_tool = FunctionTool(file_processor, description=\"Process files\")\n",
-    "\n",
-    "# Test different error scenarios\n",
-    "test_cases = [\n",
-    "    (search_tool, {\"query\": \"python programming\"}),  # Success\n",
-    "    (search_tool, {\"query\": \"\"}),  # Empty query error\n",
-    "    (search_tool, {\"query\": \"timeout example\"}),  # Timeout error\n",
-    "    (file_tool, {\"file_path\": \"document.txt\"}),  # Success\n",
-    "    (file_tool, {\"file_path\": \"nonexistent.txt\"}),  # File not found\n",
-    "    (file_tool, {\"file_path\": \"permission_denied.txt\"}),  # Permission error\n",
-    "]\n",
+    "        # Unexpected errors\n",
+    "        raise RuntimeError(f\"Unexpected error getting weather: {e}\")\n",
     "\n",
     "\n",
-    "async def test_error_handling() -> None:\n",
-    "    \"\"\"Test various error scenarios.\"\"\"\n",
-    "    cancellation_token = CancellationToken()\n",
+    "# Create the tool\n",
+    "weather_tool = FunctionTool(weather_forecast, description=\"Get weather forecast for a city\")\n",
     "\n",
-    "    for tool, args in test_cases:\n",
+    "# Test different scenarios\n",
+    "async def test_weather_tool() -> None:\n",
+    "    cancellation_token = CancellationToken()\n",
+    "    \n",
+    "    for city in [\"New York\", \"\", \"error\", \"unknown\"]:\n",
     "        try:\n",
-    "            result = await tool.run_json(args, cancellation_token)\n",
-    "            print(f\"✅ {tool.name}: {tool.return_value_as_string(result)}\")\n",
+    "            result = await weather_tool.run_json({\"city\": city}, cancellation_token)\n",
+    "            print(f\"✅ Weather for {city}: {weather_tool.return_value_as_string(result)}\")\n",
     "        except Exception as e:\n",
-    "            print(f\"❌ {tool.name}: {type(e).__name__}: {e}\")\n",
-    "\n",
+    "            print(f\"❌ Error for {city}: {type(e).__name__}: {e}\")\n",
     "\n",
     "# Run the tests\n",
-    "await test_error_handling()"
+    "await test_weather_tool()"
    ]
   },
   {