import byzerllm


@byzerllm.prompt()
def _web_research() -> str:
    """
    # Web Research Guide: Iterative Multi-Round Search Methodology

    ## Overview

    When you need to gather information from the internet, use the `web_search` and `web_crawl` tools in an **iterative multi-round workflow**. This approach requires you to search multiple times, explore various URLs, and continuously refine your understanding until you have gathered sufficient, high-quality information.

    ## CRITICAL: Iterative Search Strategy

    **DO NOT stop after a single search.** Web research is an iterative process that typically requires 3-10 rounds of searching and crawling:

    1. **Round 1: Initial Broad Search**
       - Start with a general search query
       - Review initial results and identify knowledge gaps
       - Crawl 1-2 most promising URLs

    2. **Rounds 2-5: Targeted Deep Dives**
       - Refine search queries based on what you learned
       - Try different keyword combinations and phrasings
       - Explore official documentation, GitHub repos, and Stack Overflow
       - Crawl additional URLs to fill knowledge gaps

    3. **Rounds 6-10: Verification and Edge Cases**
       - Search for alternative solutions or approaches
       - Look for known issues, caveats, or limitations
       - Cross-validate information across multiple sources
       - Ensure you have complete understanding before concluding

    **Stop Criteria - Only conclude research when:**
    - You have found authoritative, consistent information from 2+ sources
    - You understand the solution well enough to implement it confidently
    - You have verified there are no major caveats or known issues
    - Your knowledge gaps have been addressed

    ## Multi-Stage Web Research Workflow

    Each round follows this pattern:

    1. **Stage 1: Discovery with web_search**
       - Search the web to find relevant URLs, titles, and descriptions
       - Review results to identify the most promising sources
       - web_search returns metadata (URLs, titles, snippets) but NOT full page content
       - Use varied search queries (synonyms, different phrasings, specific error messages)

    2. **Stage 2: Extraction with web_crawl**
       - Use web_crawl on specific URLs identified in Stage 1
       - Extract complete page content in markdown format
       - Get full documentation, code examples, and detailed information
       - Read multiple pages, not just one

    3. **Stage 3: Evaluate and Iterate**
       - Assess whether the information is sufficient and reliable
       - Identify remaining questions or uncertainties
       - Plan next search query if needed
       - Repeat until satisfied

    ## When to Use Web Research

    | Scenario | Priority |
    |----------|----------|
    | Coding problems persisting after multiple attempts | High |
    | Unfamiliar technologies, libraries, or frameworks | High |
    | Verifying current best practices or API changes | Medium |
    | Looking for implementation examples | Medium |
    | Researching solutions to specific technical problems | High |
    | Validating assumptions about external dependencies | Medium |

    ## Content Verification Strategy

    **Internet content requires careful validation through multiple sources:**

    ### 1. Source Authority Assessment

    | Source Type | Reliability | Notes |
    |-------------|-------------|-------|
    | Official documentation | Highest | Always prefer as primary source |
    | Well-maintained GitHub repos | High | Check recent commits and activity |
    | Stack Overflow (high-voted) | High | Verify answers are recent |
    | Technical blogs from experts | Medium-High | Cross-reference with docs |
    | Reddit/Hacker News discussions | Medium | Good for opinions, verify facts |
    | Unverified forums | Low | Always cross-validate |
    | Outdated tutorials | Low | Check publication dates |

    ### 2. Cross-Validation Approaches (REQUIRED)

    - **Always compare information across 2+ sources**
    - Check official repositories and changelogs
    - Verify against local codebase patterns
    - Test recommendations in isolated environments
    - Search for conflicting opinions or known issues

    ### 3. Quality Checklist

    Before using information from web research, verify:

    - [ ] Information comes from an authoritative source
    - [ ] Publication date is recent enough to be relevant
    - [ ] Cross-validated with at least one other source
    - [ ] No known contradictions or deprecation notices
    - [ ] Compatible with the project's current tech stack and versions

    ## Example Research Sessions

    ### Example 1: Learning a New Library

    ```
    Round 1: web_search("how to use library X for task Y")
             → web_crawl(official_docs_url)
             → Learned basics, but unclear on error handling

    Round 2: web_search("library X error handling best practices")
             → web_crawl(github_issues_url)
             → Found common pitfalls

    Round 3: web_search("library X vs alternatives for task Y")
             → web_crawl(comparison_article_url)
             → Confirmed X is the right choice

    Round 4: web_search("library X version compatibility issues")
             → web_crawl(changelog_url)
             → Verified version requirements

    → NOW ready to implement with confidence
    ```

    ### Example 2: Debugging an Error

    ```
    Round 1: web_search("error message: <exact error text>")
             → web_crawl(stackoverflow_url)
             → Found potential fix, but context differs

    Round 2: web_search("error message + specific library version")
             → web_crawl(github_issue_url)
             → Found root cause explanation

    Round 3: web_search("library X migration guide v2 to v3")
             → web_crawl(official_migration_guide)
             → Found the correct fix for current version

    → Applied fix with confidence
    ```

    ### Example 3: Evaluating Approaches

    ```
    Round 1: web_search("best approach for real-time data processing Python")
             → web_crawl(comparison_article)
             → Identified 3 candidate approaches

    Round 2: web_search("approach A vs approach B performance benchmarks")
             → web_crawl(benchmark_page)
             → Approach B has better performance characteristics

    Round 3: web_search("approach B Python production deployment tips")
             → web_crawl(engineering_blog)
             → Found production best practices

    Round 4: web_search("approach B known limitations and issues 2024")
             → web_crawl(discussion_thread)
             → No critical issues for our use case

    → Selected approach B with documented rationale
    ```

    ## Advanced Tips

    ### Search Query Formulation

    | Strategy | Example |
    |----------|---------|
    | Exact error messages | `"TypeError: cannot unpack non-sequence NoneType"` |
    | Library + version | `fastapi 0.100 websocket middleware` |
    | Comparison queries | `celery vs dramatiq vs huey 2024` |
    | Official docs targeting | `site:docs.python.org asyncio gather` |
    | Recent results | `Next.js server components 2024` |

    ### When to Use web_crawl vs web_search

    | Tool | Use For |
    |------|---------|
    | `web_search` | Discovering URLs, getting overviews, finding relevant pages |
    | `web_crawl` | Reading full page content, extracting code examples, getting documentation details |

    **Typical pattern:** web_search first to find URLs, then web_crawl on the most relevant ones.

    ## Guidelines

    1. **Never stop at one search** - Always do at least 2-3 rounds for any non-trivial query
    2. **Vary your search terms** - Use synonyms, rephrase, try different angles
    3. **Prioritize official sources** - Documentation > Blogs > Forums
    4. **Cross-validate everything** - At least 2 sources for critical information
    5. **Check dates** - Ensure information is current and applicable
    6. **Read multiple pages** - Don't rely on a single URL for your understanding
    7. **Document your findings** - Summarize what you learned before implementing
    """
