Documentation

tools/wikipedia.py

@@ -10,11 +10,15 @@ import config
 API_URL = "https://en.wikipedia.org/w/api.php"
 
 def strip_html(text: str) -> str:
-    """Removes HTML tags from a string using regex."""
+    """Removes HTML tags from a string using regex to provide clean text to the LLM."""
     return re.sub(r'<[^>]*>', '', text)
 
 def _make_request(params: Dict[str, Any]) -> Dict[str, Any]:
-    """Synchronous helper to make the API request using urllib."""
+    """
+    Synchronous helper to make the API request using urllib.
+    urllib is used instead of httpx to avoid TLS/HTTP fingerprinting 
+    that triggers 403 Forbidden responses from Wikipedia.
+    """
     query_string = urllib.parse.urlencode(params)
     url = f"{API_URL}?{query_string}"
     
@@ -27,6 +31,10 @@ def _make_request(params: Dict[str, Any]) -> Dict[str, Any]:
         return json.loads(response.read().decode('utf-8'))
 
 async def _search(title: str, limit: int = 5, fallback: bool = False) -> str:
+    """
+    Searches Wikipedia for a title.
+    fallback=True: Used when a direct page request fails, providing 'Article not found' header.
+    """
     params = {
         "action": "query",
         "list": "search",
@@ -34,6 +42,7 @@ async def _search(title: str, limit: int = 5, fallback: bool = False) -> str:
         "format": "json",
         "srlimit": limit
     }
+    # Run synchronous urllib call in a thread to avoid blocking the event loop
     data = await asyncio.to_thread(_make_request, params)
     
     search_results = data.get("query", {}).get("search", [])
@@ -49,11 +58,16 @@ async def _search(title: str, limit: int = 5, fallback: bool = False) -> str:
     for i, res in enumerate(search_results, 1):
         title_res = res.get("title")
         snippet = strip_html(res.get("snippet", ""))
+        # Brackets around title help the AI identify the exact string for subsequent calls
         lines.append(f"{i}. [{title_res}] - Snippet: {snippet}")
     
     return "\n".join(lines)
 
 async def _fetch_content(title: str, section_index: int) -> Optional[str]:
+    """
+    Retrieves raw Wikitext for a specific section.
+    section_index=0 returns the lead section.
+    """
     params = {
         "action": "query",
         "prop": "revisions",
@@ -82,6 +96,9 @@ async def _fetch_content(title: str, section_index: int) -> Optional[str]:
     return revisions[0].get("*")
 
 async def _fetch_toc(title: str) -> Optional[str]:
+    """
+    Retrieves the Table of Contents data and formats it hierarchically.
+    """
     params = {
         "action": "parse",
         "page": title,
@@ -111,6 +128,10 @@ async def _fetch_toc(title: str) -> Optional[str]:
     return "\n".join(lines)
 
 async def handle(args: Dict[str, Any]) -> Dict[str, Any]:
+    """
+    Main handler for the browse_wikipedia tool.
+    Supports modes: summary, toc, section, and search.
+    """
     title = args.get("title")
     if not title:
         raise ToolError("Missing required parameter: 'title'")
@@ -122,6 +143,7 @@ async def handle(args: Dict[str, Any]) -> Dict[str, Any]:
     if mode == "search":
         result = await _search(title, search_limit, fallback=False)
     elif mode == "summary":
+        # Lead section + ToC is the default 'summary' to guide the AI's next steps
         content = await _fetch_content(title, 0)
         if content is None:
             result = await _search(title, search_limit, fallback=True)