web_search.py

"""
Web Search Module
-----------------
Performs web search requests using the requests library.
Uses DuckDuckGo Instant Answer API (free, no API key required).
"""

import requests
from urllib.parse import quote


def search(query: str) -> dict:
    """
    Perform a web search for the given query.

    Uses DuckDuckGo Instant Answer API - a free API that returns
    structured information about search queries. No API key required.

    Args:
        query: The search query string (e.g., "John Smith Acme Corp")

    Returns:
        Dictionary containing search results:
        - abstract: Brief description/summary
        - abstract_url: URL for more info
        - related_topics: List of related search topics
        - success: Whether the request succeeded
    """
    if not query or not str(query).strip():
        return {
            "success": False,
            "error": "Empty search query",
            "abstract": None,
            "abstract_url": None,
            "related_topics": [],
        }

    base_url = "https://api.duckduckgo.com/"
    params = {
        "q": query,
        "format": "json",
        "no_html": 1,
    }

    try:
        response = requests.get(base_url, params=params, timeout=10)
        response.raise_for_status()
        data = response.json()

        # Extract relevant fields from DuckDuckGo response
        abstract = data.get("Abstract", "") or data.get("AbstractText", "")
        abstract_url = data.get("AbstractURL", "")
        related = data.get("RelatedTopics", [])

        # Get first few related topics (simplified for display)
        related_topics = []
        for topic in related[:5]:
            if isinstance(topic, dict) and "Text" in topic:
                related_topics.append(topic.get("Text", ""))
            elif isinstance(topic, str):
                related_topics.append(topic)

        return {
            "success": True,
            "query": query,
            "abstract": abstract or "(No summary available)",
            "abstract_url": abstract_url or None,
            "related_topics": related_topics,
        }

    except requests.RequestException as e:
        return {
            "success": False,
            "error": str(e),
            "query": query,
            "abstract": None,
            "abstract_url": None,
            "related_topics": [],
        }


def format_search_result(result: dict) -> str:
    """
    Format a search result for console display.

    Args:
        result: The result dictionary from search()

    Returns:
        Formatted string for printing
    """
    if not result.get("success"):
        return f"  [ERROR] {result.get('error', 'Unknown error')}"

    lines = [
        f"  Summary: {result.get('abstract', 'N/A')}",
        f"  URL: {result.get('abstract_url', 'N/A')}",
    ]

    related = result.get("related_topics", [])
    if related:
        lines.append("  Related topics:")
        for topic in related[:3]:
            if topic:
                lines.append(f"    - {topic}")

    return "\n".join(lines)