local-deep-research 0.5.2__py3-none-any.whl → 0.5.4__py3-none-any.whl

local_deep_research/error_handling/report_generator.py

@@ -0,0 +1,403 @@
+"""
+ErrorReportGenerator - Create user-friendly error reports
+"""
+
+from typing import Dict, Any, Optional
+from loguru import logger
+
+from .error_reporter import ErrorReporter
+
+
+class ErrorReportGenerator:
+    """
+    Generates comprehensive, user-friendly error reports
+    """
+
+    def __init__(self, llm=None):
+        """
+        Initialize error report generator
+
+        Args:
+            llm: Optional LLM instance (unused, kept for compatibility)
+        """
+        self.error_reporter = ErrorReporter()
+
+    def generate_error_report(
+        self,
+        error_message: str,
+        query: str,
+        partial_results: Optional[Dict[str, Any]] = None,
+        search_iterations: int = 0,
+        research_id: Optional[int] = None,
+    ) -> str:
+        """
+        Generate a comprehensive error report
+
+        Args:
+            error_message: The error that occurred
+            query: The research query
+            partial_results: Any partial results that were collected
+            search_iterations: Number of search iterations completed
+            research_id: Research ID for reference
+
+        Returns:
+            str: Formatted error report in Markdown
+        """
+        try:
+            # Analyze the error
+            context = {
+                "query": query,
+                "search_iterations": search_iterations,
+                "research_id": research_id,
+                "partial_results": partial_results,
+            }
+
+            if partial_results:
+                context.update(partial_results)
+
+            error_analysis = self.error_reporter.analyze_error(
+                error_message, context
+            )
+
+            # Build the simplified report
+            report_parts = []
+
+            # Header with user-friendly error message and logs reference
+            user_friendly_message = self._make_error_user_friendly(
+                error_message
+            )
+            category_title = error_analysis.get("title", "Error")
+
+            report_parts.append("# ⚠️ Research Failed")
+            report_parts.append(f"\n**Error Type:** {category_title}")
+            report_parts.append(f"\n**What happened:** {user_friendly_message}")
+            report_parts.append(
+                '\n*For detailed error information, scroll down to the research logs and select "Errors" from the filter.*'
+            )
+
+            # Support links - moved up for better visibility
+            report_parts.append("\n## 💬 Get Help")
+            report_parts.append("We're here to help you get this working:")
+            report_parts.append(
+                "- 📖 **Documentation & guides:** [Wiki](https://github.com/LearningCircuit/local-deep-research/wiki)"
+            )
+            report_parts.append(
+                "- 💬 **Chat with the community:** [Discord #help-and-support](https://discord.gg/ttcqQeFcJ3)"
+            )
+            report_parts.append(
+                "- 🐛 **Report bugs or get help:** [GitHub Issues](https://github.com/LearningCircuit/local-deep-research/issues) *(don't hesitate to ask if you're stuck!)*"
+            )
+            report_parts.append(
+                "- 💭 **Join discussions:** [Reddit r/LocalDeepResearch](https://www.reddit.com/r/LocalDeepResearch/) *(checked less frequently)*"
+            )
+
+            # Show partial results if available (in expandable section)
+            if error_analysis.get("has_partial_results"):
+                partial_content = self._format_partial_results(partial_results)
+                if partial_content:
+                    report_parts.append(
+                        f"\n<details>\n<summary>📊 Partial Results Available</summary>\n\n{partial_content}\n</details>"
+                    )
+
+            return "\n".join(report_parts)
+
+        except Exception as e:
+            # Fallback: always return something, even if error report generation fails
+            logger.exception(f"Failed to generate error report: {e}")
+            return f"""# ⚠️ Research Failed
+
+**What happened:** {error_message}
+
+## 💬 Get Help
+We're here to help you get this working:
+- 📖 **Documentation & guides:** [Wiki](https://github.com/LearningCircuit/local-deep-research/wiki)
+- 💬 **Chat with the community:** [Discord #help-and-support](https://discord.gg/ttcqQeFcJ3)
+- 🐛 **Report bugs or get help:** [GitHub Issues](https://github.com/LearningCircuit/local-deep-research/issues) *(don't hesitate to ask if you're stuck!)*
+
+*Note: Error report generation failed - showing basic error information.*"""
+
+    def _format_partial_results(
+        self, partial_results: Optional[Dict[str, Any]]
+    ) -> str:
+        """
+        Format partial results for display
+
+        Args:
+            partial_results: Partial results data
+
+        Returns:
+            str: Formatted partial results
+        """
+        if not partial_results:
+            return ""
+
+        formatted_parts = []
+
+        # Current knowledge summary
+        if "current_knowledge" in partial_results:
+            knowledge = partial_results["current_knowledge"]
+            if knowledge and len(knowledge.strip()) > 50:
+                formatted_parts.append("### Research Summary\n")
+                formatted_parts.append(
+                    knowledge[:1000] + "..."
+                    if len(knowledge) > 1000
+                    else knowledge
+                )
+                formatted_parts.append("")
+
+        # Search results
+        if "search_results" in partial_results:
+            results = partial_results["search_results"]
+            if results:
+                formatted_parts.append("### Search Results Found\n")
+                for i, result in enumerate(results[:5], 1):  # Show top 5
+                    title = result.get("title", "Untitled")
+                    url = result.get("url", "")
+                    formatted_parts.append(f"{i}. **{title}**")
+                    if url:
+                        formatted_parts.append(f"   - URL: {url}")
+                formatted_parts.append("")
+
+        # Findings
+        if "findings" in partial_results:
+            findings = partial_results["findings"]
+            if findings:
+                formatted_parts.append("### Research Findings\n")
+                for i, finding in enumerate(findings[:3], 1):  # Show top 3
+                    content = finding.get("content", "")
+                    if content and not content.startswith("Error:"):
+                        phase = finding.get("phase", f"Finding {i}")
+                        formatted_parts.append(f"**{phase}:**")
+                        formatted_parts.append(
+                            content[:500] + "..."
+                            if len(content) > 500
+                            else content
+                        )
+                        formatted_parts.append("")
+
+        if formatted_parts:
+            formatted_parts.append(
+                "*Note: The above results were successfully collected before the error occurred.*"
+            )
+
+        return "\n".join(formatted_parts) if formatted_parts else ""
+
+    def _get_technical_context(
+        self,
+        error_analysis: Dict[str, Any],
+        partial_results: Optional[Dict[str, Any]],
+    ) -> str:
+        """
+        Get additional technical context for the error
+
+        Args:
+            error_analysis: Error analysis results
+            partial_results: Partial results if available
+
+        Returns:
+            str: Technical context information
+        """
+        context_parts = []
+
+        # Add timing information if available
+        if partial_results:
+            if "start_time" in partial_results:
+                context_parts.append(
+                    f"- **Start Time:** {partial_results['start_time']}"
+                )
+
+            if "last_activity" in partial_results:
+                context_parts.append(
+                    f"- **Last Activity:** {partial_results['last_activity']}"
+                )
+
+            # Add model information
+            if "model_config" in partial_results:
+                config = partial_results["model_config"]
+                context_parts.append(
+                    f"- **Model:** {config.get('model_name', 'Unknown')}"
+                )
+                context_parts.append(
+                    f"- **Provider:** {config.get('provider', 'Unknown')}"
+                )
+
+            # Add search information
+            if "search_config" in partial_results:
+                search_config = partial_results["search_config"]
+                context_parts.append(
+                    f"- **Search Engine:** {search_config.get('engine', 'Unknown')}"
+                )
+                context_parts.append(
+                    f"- **Max Results:** {search_config.get('max_results', 'Unknown')}"
+                )
+
+            # Add any error codes or HTTP status
+            if "status_code" in partial_results:
+                context_parts.append(
+                    f"- **Status Code:** {partial_results['status_code']}"
+                )
+
+            if "error_code" in partial_results:
+                context_parts.append(
+                    f"- **Error Code:** {partial_results['error_code']}"
+                )
+
+        # Add error-specific context based on category
+        category = error_analysis.get("category")
+        if category:
+            if "connection" in category.value.lower():
+                context_parts.append(
+                    "- **Network Error:** Connection-related issue detected"
+                )
+                context_parts.append(
+                    "- **Retry Recommended:** Check service status and try again"
+                )
+            elif "model" in category.value.lower():
+                context_parts.append(
+                    "- **Model Error:** Issue with AI model or configuration"
+                )
+                context_parts.append(
+                    "- **Check:** Model service availability and parameters"
+                )
+
+        return "\n".join(context_parts) if context_parts else ""
+
+    def generate_quick_error_summary(
+        self, error_message: str
+    ) -> Dict[str, str]:
+        """
+        Generate a quick error summary for API responses
+
+        Args:
+            error_message: The error message
+
+        Returns:
+            dict: Quick error summary
+        """
+        error_analysis = self.error_reporter.analyze_error(error_message)
+
+        return {
+            "title": error_analysis["title"],
+            "category": error_analysis["category"].value,
+            "severity": error_analysis["severity"],
+            "recoverable": error_analysis["recoverable"],
+        }
+
+    def _make_error_user_friendly(self, error_message: str) -> str:
+        """
+        Replace cryptic technical error messages with user-friendly versions
+
+        Args:
+            error_message: The original technical error message
+
+        Returns:
+            str: User-friendly error message, or original if no replacement found
+        """
+        # Dictionary of technical errors to user-friendly messages
+        error_replacements = {
+            "max_workers must be greater than 0": (
+                "The LLM failed to generate search questions. This usually means the LLM service isn't responding properly.\n\n"
+                "**Try this:**\n"
+                "- Check if your LLM service (Ollama/LM Studio) is running\n"
+                "- Restart the LLM service\n"
+                "- Try a different model"
+            ),
+            "POST predict.*EOF": (
+                "Lost connection to Ollama. This usually means Ollama stopped responding or there's a network issue.\n\n"
+                "**Try this:**\n"
+                "- Restart Ollama: `ollama serve`\n"
+                "- Check if Ollama is still running: `ps aux | grep ollama`\n"
+                "- Try a different port if 11434 is in use"
+            ),
+            "HTTP error 404.*research results": (
+                "The research completed but the results can't be displayed. The files were likely generated successfully.\n\n"
+                "**Try this:**\n"
+                "- Check the `research_outputs` folder for your report\n"
+                "- Ensure the folder has proper read/write permissions\n"
+                "- Restart the LDR web interface"
+            ),
+            "Connection refused|\\[Errno 111\\]": (
+                "Cannot connect to the LLM service. The service might not be running or is using a different address.\n\n"
+                "**Try this:**\n"
+                "- Start your LLM service (Ollama: `ollama serve`, LM Studio: launch the app)\n"
+                "- **Docker on Mac/Windows:** Change URL from `http://localhost:1234` to `http://host.docker.internal:1234`\n"
+                "- **Docker on Linux:** Use your host IP instead of localhost (find with `hostname -I`)\n"
+                "- Check the service URL in settings matches where your LLM is running\n"
+                "- Verify the port number is correct (Ollama: 11434, LM Studio: 1234)"
+            ),
+            "The search is longer than 256 characters": (
+                "Your search query is too long for GitHub's API (max 256 characters).\n\n"
+                "**Try this:**\n"
+                "- Shorten your research query\n"
+                "- Use a different search engine (DuckDuckGo, Searx, etc.)\n"
+                "- Break your research into smaller, focused queries"
+            ),
+            "No module named.*local_deep_research": (
+                "Installation issue detected. The package isn't properly installed.\n\n"
+                "**Try this:**\n"
+                "- Reinstall: `pip install -e .` from the project directory\n"
+                "- Check you're using the right Python environment\n"
+                "- For Docker users: rebuild the container"
+            ),
+            "Failed to create search engine|could not be found": (
+                "Search engine configuration problem.\n\n"
+                "**Try this:**\n"
+                "- Use the default search engine (auto)\n"
+                "- Check search engine settings in Advanced Options\n"
+                "- Ensure required API keys are set for external search engines"
+            ),
+            "TypeError.*Context.*Size|'<' not supported between": (
+                "Model configuration issue. The context size setting might not be compatible with your model.\n\n"
+                "**Try this:**\n"
+                "- Check your model's maximum context size\n"
+                "- Leave context size settings at default\n"
+                "- Try a different model"
+            ),
+            "Model.*not found in Ollama": (
+                "The specified model isn't available in Ollama.\n\n"
+                "**Try this:**\n"
+                "- Check available models: `ollama list`\n"
+                "- Pull the model: `ollama pull <model-name>`\n"
+                "- Use the exact model name shown in `ollama list` (e.g., 'gemma2:9b' not 'gemma:latest')"
+            ),
+            "No auth credentials found|401.*API key": (
+                "API key is missing or incorrectly configured.\n\n"
+                "**Try this:**\n"
+                "- Set API key in the web UI settings (not in .env files)\n"
+                "- Go to Settings → Advanced → enter your API key\n"
+                "- For custom endpoints, ensure the key format matches what your provider expects"
+            ),
+            "Attempt to write readonly database": (
+                "Permission issue with the database file.\n\n"
+                "**Try this:**\n"
+                "- On Windows: Run as Administrator\n"
+                "- On Linux/Mac: Check folder permissions\n"
+                "- Delete and recreate the database file if corrupted"
+            ),
+            "Invalid value.*SearXNG|database.*locked": (
+                "SearXNG configuration or rate limiting issue.\n\n"
+                "**Try this:**\n"
+                "- Keep 'Search snippets only' enabled (don't turn it off)\n"
+                "- Restart SearXNG: `docker restart searxng`\n"
+                "- If rate limited, wait a few minutes or use a VPN"
+            ),
+            "host.*localhost.*Docker|127\\.0\\.0\\.1.*Docker|localhost.*1234.*Docker|LM.*Studio.*Docker.*Mac": (
+                "Docker networking issue - can't connect to services on host.\n\n"
+                "**Try this:**\n"
+                "- **On Mac/Windows Docker:** Replace 'localhost' or '127.0.0.1' with 'host.docker.internal'\n"
+                "- **On Linux Docker:** Use your host's actual IP address (find with `hostname -I`)\n"
+                "- **Example:** Change `http://localhost:1234` to `http://host.docker.internal:1234`\n"
+                "- Ensure the service port isn't blocked by firewall\n"
+                "- Alternative: Use host networking mode (see wiki for setup)"
+            ),
+        }
+
+        # Check each pattern and replace if found
+        for pattern, replacement in error_replacements.items():
+            import re
+
+            if re.search(pattern, error_message, re.IGNORECASE):
+                return f"{replacement}\n\nTechnical error: {error_message}"
+
+        # If no specific replacement found, return original message
+        return error_message

local_deep_research/web/routes/history_routes.py

@@ -254,7 +254,7 @@ def get_research_details(research_id):
     )
 
 
-@history_bp.route("/report/<int:research_id>")
+@history_bp.route("/history/report/<int:research_id>")
 def get_report(research_id):
     conn = get_db_connection()
     conn.row_factory = lambda cursor, row: {

local_deep_research/web/services/research_service.py

@@ -17,6 +17,7 @@ from ...utilities.threading_utils import thread_context, thread_with_app_context
 from ..database.models import ResearchStrategy, ResearchHistory
 from ..models.database import calculate_duration
 from .socket_service import SocketIOService
+from ...error_handling.report_generator import ErrorReportGenerator
 
 # Output directory for research results
 _PROJECT_ROOT = Path(__file__).parents[4]
@@ -657,8 +658,40 @@ def run_research_process(
                 )
 
                 try:
-                    # Get the synthesized content from the LLM directly
-                    clean_markdown = raw_formatted_findings
+                    # Check if we have an error in the findings and use enhanced error handling
+                    if isinstance(
+                        raw_formatted_findings, str
+                    ) and raw_formatted_findings.startswith("Error:"):
+                        logger.info(
+                            "Generating enhanced error report using ErrorReportGenerator"
+                        )
+
+                        # Get LLM for error explanation if available
+                        try:
+                            llm = get_llm(research_id=research_id)
+                        except Exception:
+                            llm = None
+                            logger.warning(
+                                "Could not get LLM for error explanation"
+                            )
+
+                        # Generate comprehensive error report
+                        error_generator = ErrorReportGenerator(llm)
+                        clean_markdown = error_generator.generate_error_report(
+                            error_message=raw_formatted_findings,
+                            query=query,
+                            partial_results=results,
+                            search_iterations=results.get("iterations", 0),
+                            research_id=research_id,
+                        )
+
+                        logger.info(
+                            "Generated enhanced error report with %d characters",
+                            len(clean_markdown),
+                        )
+                    else:
+                        # Get the synthesized content from the LLM directly
+                        clean_markdown = raw_formatted_findings
 
                     # Extract all sources from findings to add them to the summary
                     all_links = []
@@ -878,10 +911,77 @@ def run_research_process(
                     "solution": "Check API configuration and credentials."
                 }
 
+            # Generate enhanced error report for failed research
+            enhanced_report_content = None
+            try:
+                # Get LLM for error explanation if available
+                try:
+                    llm = get_llm(research_id=research_id)
+                except Exception:
+                    llm = None
+                    logger.warning(
+                        "Could not get LLM for error explanation in failure handler"
+                    )
+
+                # Get partial results if they exist
+                partial_results = results if "results" in locals() else None
+                search_iterations = (
+                    results.get("iterations", 0) if partial_results else 0
+                )
+
+                # Generate comprehensive error report
+                error_generator = ErrorReportGenerator(llm)
+                enhanced_report_content = error_generator.generate_error_report(
+                    error_message=f"Research failed: {str(e)}",
+                    query=query,
+                    partial_results=partial_results,
+                    search_iterations=search_iterations,
+                    research_id=research_id,
+                )
+
+                logger.info(
+                    "Generated enhanced error report for failed research (length: %d)",
+                    len(enhanced_report_content),
+                )
+
+                # Save enhanced error report as the actual report file
+                try:
+                    reports_folder = OUTPUT_DIR
+                    report_filename = f"research_{research_id}_error_report.md"
+                    report_path = reports_folder / report_filename
+
+                    with open(report_path, "w", encoding="utf-8") as f:
+                        f.write(enhanced_report_content)
+
+                    logger.info(
+                        "Saved enhanced error report to: %s", report_path
+                    )
+
+                    # Store the report path so it can be retrieved later
+                    report_path_to_save = str(
+                        report_path.relative_to(reports_folder.parent)
+                    )
+
+                except Exception as report_error:
+                    logger.exception(
+                        "Failed to save enhanced error report: %s", report_error
+                    )
+                    report_path_to_save = None
+
+            except Exception as error_gen_error:
+                logger.exception(
+                    "Failed to generate enhanced error report: %s",
+                    error_gen_error,
+                )
+                enhanced_report_content = None
+                report_path_to_save = None
+
             # Update metadata with more context about the error
             metadata = {"phase": "error", "error": user_friendly_error}
             if error_context:
                 metadata.update(error_context)
+            if enhanced_report_content:
+                metadata["has_enhanced_report"] = True
 
             # If we still have an active research record, update its log
             if research_id in active_research:
@@ -934,6 +1034,10 @@ def run_research_process(
                 research.duration_seconds = duration_seconds
                 research.metadata = metadata
 
+                # Add error report path if available
+                if "report_path_to_save" in locals() and report_path_to_save:
+                    research.report_path = report_path_to_save
+
                 db_session.commit()
 
             try:

local_deep_research/web/static/css/styles.css

@@ -119,6 +119,18 @@ a:hover {
   color: var(--text-primary);
 }
 
+.sidebar-nav li a:focus {
+  outline: 2px solid var(--accent-primary);
+  outline-offset: -2px;
+  background-color: var(--bg-tertiary);
+  color: var(--text-primary);
+}
+
+.sidebar-nav li a:focus .nav-shortcut {
+  background-color: var(--accent-primary);
+  color: var(--text-primary);
+}
+
 .sidebar-nav li.active {
   color: var(--accent-primary);
   background-color: rgba(110, 79, 246, 0.1);
@@ -130,13 +142,53 @@ a:hover {
   color: inherit;
 }
 
+/* Navigation shortcuts */
+.nav-shortcut {
+  margin-left: auto;
+  background-color: var(--bg-tertiary);
+  color: var(--text-muted);
+  padding: 0.2rem 0.5rem;
+  border-radius: 4px;
+  font-size: 0.75rem;
+  font-weight: 600;
+  min-width: 1.5rem;
+  text-align: center;
+  transition: all 0.2s;
+}
+
+.sidebar-nav li:hover .nav-shortcut {
+  background-color: var(--accent-primary);
+  color: var(--text-primary);
+}
+
+.sidebar-nav li.active .nav-shortcut {
+  background-color: var(--accent-primary);
+  color: var(--text-primary);
+}
+
 .sidebar-footer {
   padding: 1rem 1.5rem;
   border-top: 1px solid var(--border-color);
   color: var(--text-muted);
   font-size: 0.875rem;
   display: flex;
-  justify-content: center;
+  flex-direction: column;
+  align-items: center;
+  gap: 0.5rem;
+}
+
+.nav-hint {
+  font-size: 0.75rem;
+  opacity: 0.7;
+  margin: 0;
+}
+
+.nav-hint kbd {
+  background-color: var(--bg-tertiary);
+  padding: 0.1rem 0.3rem;
+  border-radius: 3px;
+  font-size: 0.7rem;
+  border: 1px solid var(--border-color);
 }
 
 /* Main Content */
@@ -1046,6 +1098,11 @@ textarea:focus, input[type="text"]:focus {
     justify-content: center;
   }
 
+  /* Hide navigation shortcuts on small screens */
+  .nav-shortcut {
+    display: none;
+  }
+
   /* Active state fix for icon view */
   .sidebar-nav li.active {
     border-left-width: 3px;
@@ -1581,6 +1638,10 @@ textarea:focus, input[type="text"]:focus {
     border-radius: 8px;
     background-color: rgba(64, 191, 255, 0.05);
     border: 1px solid rgba(64, 191, 255, 0.1);
+    width: 100%;
+    text-align: left;
+    font-family: inherit;
+    font-size: inherit;
 }
 
 .advanced-options-toggle:hover {
@@ -1605,11 +1666,25 @@ textarea:focus, input[type="text"]:focus {
 .advanced-options-panel {
     background-color: rgba(42, 42, 58, 0.5);
     border-radius: 8px;
-    padding: 1.5rem;
+    padding: 0 1.5rem;
     margin-bottom: 1.5rem;
     border: 1px solid var(--border-color);
-    display: none;
     box-shadow: inset 0 2px 10px rgba(0, 0, 0, 0.1);
+    max-height: 0;
+    overflow: hidden;
+    opacity: 0;
+    visibility: hidden;
+    pointer-events: none;
+    transition: all 0.3s ease;
+}
+
+.advanced-options-toggle.open + .advanced-options-panel,
+.advanced-options-panel.expanded {
+    max-height: 1000px;
+    opacity: 1;
+    visibility: visible;
+    pointer-events: auto;
+    padding: 1.5rem;
 }
 
 .form-row {