Improve error handling with better messages and logging

Enhanced error handling across multiple modules to provide more
user-friendly error messages and better debugging information:

- tools.py: Added context-aware error messages for timeouts, network
  issues, and permission errors. Includes exception type information
  in logs while keeping user messages clear and actionable.

- agent_creator.py: Replaced print statements with proper logging
  module usage. Added better error context and debugging information
  for JSON parsing failures.

- utils.py: Improved WebSocket error handling with specific checks
  for connection and timeout issues, providing more informative
  warning messages.

All changes maintain backward compatibility while significantly
improving the developer and user experience when errors occur.

Author: Bolajiadesina

gpt_researcher/actions/agent_creator.py

@@ -1,9 +1,12 @@
 import json
 import re
 import json_repair
+import logging
 from ..utils.llm import create_chat_completion
 from ..prompts import PromptFamily
 
+logger = logging.getLogger(__name__)
+
 async def choose_agent(
     query,
     cfg,
@@ -57,18 +60,27 @@ async def handle_json_error(response):
         if agent_dict.get("server") and agent_dict.get("agent_role_prompt"):
             return agent_dict["server"], agent_dict["agent_role_prompt"]
     except Exception as e:
-        print(f"⚠️ Error in reading JSON and failed to repair with json_repair: {e}")
-        print(f"⚠️ LLM Response: `{response}`")
+        error_type = type(e).__name__
+        error_msg = str(e)
+        logger.warning(
+            f"Failed to parse agent JSON with json_repair: {error_type}: {error_msg}",
+            exc_info=True
+        )
+        if response:
+            logger.debug(f"LLM response that failed to parse: {response[:500]}...")
 
     json_string = extract_json_with_regex(response)
     if json_string:
         try:
             json_data = json.loads(json_string)
             return json_data["server"], json_data["agent_role_prompt"]
         except json.JSONDecodeError as e:
-            print(f"Error decoding JSON: {e}")
+            logger.warning(
+                f"Failed to decode JSON from regex extraction: {str(e)}",
+                exc_info=True
+            )
 
-    print("No JSON found in the string. Falling back to Default Agent.")
+    logger.info("No valid JSON found in LLM response. Falling back to default agent.")
     return "Default Agent", (
         "You are an AI critical thinker research assistant. Your sole purpose is to write well written, "
         "critically acclaimed, objective and structured reports on given text."

gpt_researcher/actions/utils.py

@@ -46,7 +46,17 @@ async def safe_send_json(websocket: Any, data: Dict[str, Any]) -> None:
     try:
         await websocket.send_json(data)
     except Exception as e:
-        logger.error(f"Error sending JSON through WebSocket: {e}")
+        error_type = type(e).__name__
+        error_msg = str(e)
+        logger.error(
+            f"Error sending JSON through WebSocket: {error_type}: {error_msg}",
+            exc_info=True
+        )
+        # Check for common WebSocket errors and provide helpful context
+        if "closed" in error_msg.lower() or "connection" in error_msg.lower():
+            logger.warning("WebSocket connection appears to be closed. Client may have disconnected.")
+        elif "timeout" in error_msg.lower():
+            logger.warning("WebSocket send operation timed out. The client may be unresponsive.")
 
 
 def calculate_cost(

gpt_researcher/utils/tools.py

@@ -121,8 +121,21 @@ async def create_chat_completion_with_tools(
                                 tool_result = await tool(**tool_args) if asyncio.iscoroutinefunction(tool) else tool(**tool_args)
                             break
                         except Exception as e:
-                            logger.error(f"Error executing tool {tool_name}: {e}")
-                            tool_result = f"Tool error: {str(e)}"
+                            error_type = type(e).__name__
+                            error_msg = str(e)
+                            logger.error(
+                                f"Error executing tool '{tool_name}': {error_type}: {error_msg}",
+                                exc_info=True
+                            )
+                            # Provide user-friendly error message
+                            if "timeout" in error_msg.lower() or "timed out" in error_msg.lower():
+                                tool_result = f"Tool '{tool_name}' timed out. The operation took too long to complete. Please try again or check your network connection."
+                            elif "connection" in error_msg.lower() or "network" in error_msg.lower():
+                                tool_result = f"Tool '{tool_name}' failed due to a network issue. Please check your internet connection and try again."
+                            elif "permission" in error_msg.lower() or "access" in error_msg.lower():
+                                tool_result = f"Tool '{tool_name}' failed due to insufficient permissions. Please check your API keys or access credentials."
+                            else:
+                                tool_result = f"Tool '{tool_name}' encountered an error: {error_msg}. Please check the logs for more details."
 
                 # Add tool result to conversation
                 tool_message = ToolMessage(content=str(tool_result), tool_call_id=tool_id)
@@ -159,7 +172,12 @@ async def create_chat_completion_with_tools(
             return response.content, []
 
     except Exception as e:
-        logger.error(f"Error in tool-enabled chat completion: {str(e)}")
+        error_type = type(e).__name__
+        error_msg = str(e)
+        logger.error(
+            f"Error in tool-enabled chat completion: {error_type}: {error_msg}",
+            exc_info=True
+        )
         logger.info("Falling back to simple chat completion without tools")
 
         # Fallback to simple chat completion without tools
@@ -202,8 +220,21 @@ def search_tool(query: str) -> str:
             else:
                 return f"No search results found for: {query}"
         except Exception as e:
-            logger.error(f"Search tool error: {str(e)}")
-            return f"Search error: {str(e)}"
+            error_type = type(e).__name__
+            error_msg = str(e)
+            logger.error(
+                f"Search tool error: {error_type}: {error_msg}",
+                exc_info=True
+            )
+            # Provide context-aware error messages
+            if "api" in error_msg.lower() or "key" in error_msg.lower():
+                return f"Search failed: API key issue. Please verify your search API credentials are configured correctly."
+            elif "timeout" in error_msg.lower() or "timed out" in error_msg.lower():
+                return f"Search timed out. The search request took too long. Please try again with a different query."
+            elif "rate limit" in error_msg.lower() or "quota" in error_msg.lower():
+                return f"Search rate limit exceeded. Please wait a moment before trying again."
+            else:
+                return f"Search encountered an error: {error_msg}. Please check your search provider configuration."
 
     return search_tool
 
@@ -232,8 +263,19 @@ def custom_tool(*args, **kwargs) -> str:
             result = function(*args, **kwargs)
             return str(result) if result is not None else "Tool executed successfully"
         except Exception as e:
-            logger.error(f"Custom tool '{name}' error: {str(e)}")
-            return f"Tool error: {str(e)}"
+            error_type = type(e).__name__
+            error_msg = str(e)
+            logger.error(
+                f"Custom tool '{name}' error: {error_type}: {error_msg}",
+                exc_info=True
+            )
+            # Provide informative error message without exposing internal details
+            if "validation" in error_msg.lower() or "invalid" in error_msg.lower():
+                return f"Tool '{name}' received invalid input. Please check the parameters and try again."
+            elif "not found" in error_msg.lower() or "missing" in error_msg.lower():
+                return f"Tool '{name}' could not find required resources. Please verify the input data is correct."
+            else:
+                return f"Tool '{name}' encountered an error: {error_msg}. Please check the tool configuration."
 
     # Set tool metadata
     custom_tool.name = name