Joachim M. Vis commited on
Commit
fadc0bc
·
verified ·
1 Parent(s): dd6b4e3

Upload 15 files

Browse files
Files changed (3) hide show
  1. docs/enhanced_web_search.md +299 -0
  2. docs/examples.md +62 -0
  3. docs/index.md +2 -0
docs/enhanced_web_search.md ADDED
@@ -0,0 +1,299 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ # Enhanced Web Search
2
+
3
+ The Enhanced Web Search system provides a comprehensive three-tier approach to web search, intelligently routing queries to the most appropriate search tools based on query type and available resources. This system is designed to handle a wide range of search needs, from simple factual queries to complex reasoning questions.
4
+
5
+ ## Overview
6
+
7
+ The Enhanced Web Search system consists of three specialized search tools:
8
+
9
+ 1. **BrowserSearchTool** - For direct browser-based searches of any website
10
+ 2. **LibrarySearchTool** - For searches using imported libraries like arXiv and DuckDuckGo
11
+ 3. **ApiSearchTool** - For searches using API services like Perplexity and Serper
12
+
13
+ These tools work together in a fallback chain, ensuring that if one tool fails or is unavailable, the system can fall back to another tool. This approach provides robust search capabilities that can adapt to different environments and query types.
14
+
15
+ ## Three-Tier Search Approach
16
+
17
+ ### 1. BrowserSearchTool
18
+
19
+ The BrowserSearchTool enables direct browser-based searches of any website using the browser_action capability.
20
+
21
+ **Purpose:**
22
+ - Directly interact with websites through a browser interface
23
+ - Access content that may be difficult to retrieve through APIs or libraries
24
+ - Provide visual context for search results
25
+
26
+ **Advantages:**
27
+ - Can access any website, including those without APIs
28
+ - Provides visual context and can interact with dynamic content
29
+ - Works with a wide range of websites without requiring API keys
30
+
31
+ **Use Cases:**
32
+ - Searching websites that don't have public APIs
33
+ - Accessing content behind login screens (with proper credentials)
34
+ - Interacting with dynamic web content
35
+ - Visual verification of search results
36
+
37
+ **Example:**
38
+
39
+ ```python
40
+ from tools.web_tools import create_browser_search
41
+
42
+ # Create the browser search tool
43
+ browser_tool = create_browser_search()
44
+
45
+ # Search Wikipedia
46
+ results = browser_tool.search("quantum computing", source="wikipedia")
47
+
48
+ # The results include instructions for using browser_action
49
+ print(results[0]["instructions"])
50
+ ```
51
+
52
+ ### 2. LibrarySearchTool
53
+
54
+ The LibrarySearchTool leverages imported Python libraries (DuckDuckGo and arXiv) for search operations, intelligently routing queries to the appropriate library based on query type.
55
+
56
+ **Purpose:**
57
+ - Use established Python libraries for search operations
58
+ - Provide specialized academic search capabilities
59
+ - Offer general web search without requiring API keys
60
+
61
+ **Advantages:**
62
+ - No API keys required
63
+ - Specialized academic search through arXiv
64
+ - General web search through DuckDuckGo
65
+ - Works offline with locally installed libraries
66
+
67
+ **Use Cases:**
68
+ - Academic research and paper searches
69
+ - General web searches when API keys aren't available
70
+ - Environments with limited internet access but installed libraries
71
+
72
+ **Example:**
73
+
74
+ ```python
75
+ from tools.web_tools import create_library_search
76
+
77
+ # Create the library search tool
78
+ library_tool = create_library_search()
79
+
80
+ # For academic queries, it automatically uses arXiv
81
+ academic_results = library_tool.search("recent papers on quantum computing")
82
+
83
+ # For general queries, it automatically uses DuckDuckGo
84
+ general_results = library_tool.search("weather in New York")
85
+ ```
86
+
87
+ ### 3. ApiSearchTool
88
+
89
+ The ApiSearchTool uses external API services (Perplexity and Serper) for search operations, intelligently selecting between them based on the query type.
90
+
91
+ **Purpose:**
92
+ - Leverage powerful commercial search APIs
93
+ - Provide high-quality results for complex queries
94
+ - Offer fast and reliable search capabilities
95
+
96
+ **Advantages:**
97
+ - High-quality results for complex queries through Perplexity
98
+ - Fast and reliable search through Serper's Google search API
99
+ - Structured and consistent results
100
+
101
+ **Use Cases:**
102
+ - Complex, reasoning-based queries that benefit from Perplexity's capabilities
103
+ - Factual and simple queries that can be handled by Serper
104
+ - Production environments with API access
105
+
106
+ **Example:**
107
+
108
+ ```python
109
+ from tools.web_tools import create_api_search
110
+
111
+ # Create the API search tool
112
+ api_tool = create_api_search()
113
+
114
+ # For complex queries, it automatically uses Perplexity
115
+ complex_results = api_tool.search("Explain quantum computing in detail and its potential impact on cryptography")
116
+
117
+ # For simple queries, it automatically uses Serper
118
+ simple_results = api_tool.search("weather in New York")
119
+ ```
120
+
121
+ ## Fallback Chain
122
+
123
+ The three search tools work together in a fallback chain, ensuring robust search capabilities even when some tools are unavailable or fail. The EnhancedWebSearchTool manages this fallback chain.
124
+
125
+ **Fallback Process:**
126
+
127
+ 1. First, try the most appropriate tool based on the query type
128
+ 2. If that tool fails or is unavailable, try the next most appropriate tool
129
+ 3. Continue until a successful result is found or all tools have been tried
130
+
131
+ **Example:**
132
+
133
+ ```python
134
+ from tools.web_tools import create_enhanced_web_search
135
+
136
+ # Create the enhanced web search tool
137
+ enhanced_tool = create_enhanced_web_search()
138
+
139
+ # Search for information
140
+ # This will automatically select the most appropriate tool
141
+ # and fall back to others if needed
142
+ results = enhanced_tool.search("Who nominated the only Featured Article on English Wikipedia about a dinosaur that was promoted in November 2016?")
143
+ ```
144
+
145
+ ## Query Type Detection
146
+
147
+ Each tool includes specialized methods to detect specific types of queries:
148
+
149
+ - **BrowserSearchTool**: Detects website-specific queries (e.g., "wikipedia article about...")
150
+ - **LibrarySearchTool**: Detects academic queries for arXiv vs. general queries for DuckDuckGo
151
+ - **ApiSearchTool**: Detects complex queries for Perplexity vs. simple queries for Serper
152
+
153
+ These detection methods ensure that queries are routed to the most appropriate search tool.
154
+
155
+ ## Implementation Details
156
+
157
+ ### BrowserSearchTool
158
+
159
+ The BrowserSearchTool provides search templates for common websites:
160
+
161
+ ```python
162
+ self.search_templates = {
163
+ "wikipedia": "https://en.wikipedia.org/wiki/Special:Search?search={query}",
164
+ "arxiv": "https://arxiv.org/search/?query={query}&searchtype=all",
165
+ "google": "https://www.google.com/search?q={query}",
166
+ "youtube": "https://www.youtube.com/results?search_query={query}",
167
+ # Additional templates...
168
+ }
169
+ ```
170
+
171
+ It can detect the most appropriate source based on the query content and provides specific instructions for using browser_action with each source.
172
+
173
+ ### LibrarySearchTool
174
+
175
+ The LibrarySearchTool includes methods to detect academic queries:
176
+
177
+ ```python
178
+ def _is_academic_query(self, query: str) -> bool:
179
+ # Check for academic keywords, fields, and citation patterns
180
+ # ...
181
+ return has_academic_keyword or has_academic_field or has_citation_pattern
182
+ ```
183
+
184
+ It uses the DuckDuckGo library for general queries and the arXiv library for academic queries, formatting the results consistently.
185
+
186
+ ### ApiSearchTool
187
+
188
+ The ApiSearchTool includes methods to detect complex queries:
189
+
190
+ ```python
191
+ def _is_complex_query(self, query: str) -> bool:
192
+ # Check for question words, complex indicators, and query length
193
+ # ...
194
+ return has_question_word or has_complex_indicator or is_long_query
195
+ ```
196
+
197
+ It uses the Perplexity API for complex queries and the Serper API for simple queries, formatting the results consistently.
198
+
199
+ ## Configuration
200
+
201
+ Each tool can be configured through environment variables and configuration files:
202
+
203
+ ### ApiSearchTool
204
+
205
+ - **PERPLEXITY_API_KEY**: API key for Perplexity
206
+ - **SERPER_API_KEY**: API key for Serper
207
+
208
+ ### LibrarySearchTool
209
+
210
+ - No API keys required, but the DuckDuckGo and arXiv libraries must be installed
211
+
212
+ ### BrowserSearchTool
213
+
214
+ - No API keys required, but browser_action capability must be available
215
+
216
+ ## Usage
217
+
218
+ ### Basic Usage
219
+
220
+ ```python
221
+ from tools.web_tools import create_enhanced_web_search
222
+
223
+ # Create the enhanced web search tool
224
+ enhanced_tool = create_enhanced_web_search()
225
+
226
+ # Search for information
227
+ results = enhanced_tool.search("Who nominated the only Featured Article on English Wikipedia about a dinosaur that was promoted in November 2016?")
228
+
229
+ # Process the results
230
+ for result in results:
231
+ print(f"Title: {result.get('title')}")
232
+ print(f"Snippet: {result.get('snippet')}")
233
+ print(f"Source: {result.get('source')}")
234
+ print(f"Relevance: {result.get('relevance_score')}")
235
+ print("---")
236
+ ```
237
+
238
+ ### Using with the Tool Registry
239
+
240
+ ```python
241
+ from agent.tool_registry import create_default_registry, unified_search
242
+
243
+ # Create the registry
244
+ registry = create_default_registry()
245
+
246
+ # Search using unified_search
247
+ results = unified_search(registry, "How many studio albums were published by Mercedes Sosa between 2000 and 2009?")
248
+
249
+ # Process the results
250
+ for result in results["results"]:
251
+ print(f"Title: {result.get('title')}")
252
+ print(f"Snippet: {result.get('snippet')}")
253
+ print(f"Source: {result.get('source')}")
254
+ print(f"Relevance: {result.get('relevance_score')}")
255
+ print("---")
256
+ ```
257
+
258
+ ## Testing
259
+
260
+ You can test the Enhanced Web Search system using the provided test scripts:
261
+
262
+ ```bash
263
+ # Run all tests
264
+ python tests/run_gaia_web_search_tests.py
265
+
266
+ # Run only direct tests (without registry)
267
+ python tests/run_gaia_web_search_tests.py --direct-only
268
+
269
+ # Run only registry tests
270
+ python tests/run_gaia_web_search_tests.py --registry-only
271
+
272
+ # Enable verbose logging
273
+ python tests/run_gaia_web_search_tests.py --verbose
274
+ ```
275
+
276
+ ## Examples
277
+
278
+ See the following example scripts for complete examples of how to use the Enhanced Web Search system:
279
+
280
+ - `examples/enhanced_web_search_example.py` - Example of using the EnhancedWebSearchTool
281
+ - `examples/multi_search_example.py` - Example of using multiple search tools together
282
+
283
+ ## Requirements
284
+
285
+ - Perplexity API key (set as `PERPLEXITY_API_KEY` environment variable) for ApiSearchTool
286
+ - Serper API key (set as `SERPER_API_KEY` environment variable) for ApiSearchTool
287
+ - DuckDuckGo and arXiv libraries installed for LibrarySearchTool
288
+ - Browser_action capability for BrowserSearchTool
289
+
290
+ ## Conclusion
291
+
292
+ The Enhanced Web Search system provides a robust, flexible approach to web search through its three-tier architecture. By intelligently routing queries to the most appropriate search tools and implementing a fallback chain, it ensures reliable search capabilities across a wide range of environments and query types.
293
+
294
+ This system significantly improves search performance by leveraging the strengths of each search approach:
295
+ - Direct browser-based searches for website-specific content
296
+ - Library-based searches for academic and general queries without API keys
297
+ - API-based searches for high-quality results on complex queries
298
+
299
+ Together, these tools provide a comprehensive solution for web search needs in various contexts and environments.
docs/examples.md CHANGED
@@ -175,6 +175,68 @@ custom_config = {
175
  result = run_benchmark(SAMPLE_QUESTIONS, agent_config=custom_config)
176
  ```
177
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
178
  ## Command-Line Usage
179
 
180
  You can also run the agent from the command line using the provided scripts:
 
175
  result = run_benchmark(SAMPLE_QUESTIONS, agent_config=custom_config)
176
  ```
177
 
178
+ ## Enhanced Web Search Examples
179
+
180
+ The GAIA agent includes enhanced web search tools specifically designed to handle certain GAIA assessment questions. The following examples demonstrate how to use these tools directly.
181
+
182
+ ### Running the Enhanced Web Search Example
183
+
184
+ ```bash
185
+ # Run all enhanced web search examples
186
+ python examples/enhanced_web_search_example.py
187
+
188
+ # Run only the Wikipedia example
189
+ python examples/enhanced_web_search_example.py --wikipedia
190
+
191
+ # Run only the DuckDuckGo example
192
+ python examples/enhanced_web_search_example.py --duckduckgo
193
+
194
+ # Run only the Universe Today example
195
+ python examples/enhanced_web_search_example.py --universe-today
196
+
197
+ # Run only the Malko Competition example
198
+ python examples/enhanced_web_search_example.py --malko
199
+ ```
200
+
201
+ ### Using the Enhanced Web Search Tools in Your Code
202
+
203
+ ```python
204
+ from tools.web_tools import WikipediaSearchTool, DuckDuckGoSearchTool, SerperSearchTool, WebContentExtractor
205
+
206
+ # Example 1: Using the WikipediaSearchTool to find information about featured articles
207
+ wiki_tool = WikipediaSearchTool()
208
+ results = wiki_tool.search("Who nominated the only Featured Article on English Wikipedia about a dinosaur that was promoted in November 2016?")
209
+ for result in results:
210
+ print(f"Title: {result.get('title', '')}")
211
+ print(f"Snippet: {result.get('snippet', '')}")
212
+ print()
213
+
214
+ # Example 2: Using the DuckDuckGoSearchTool to find information about music albums
215
+ ddg_tool = DuckDuckGoSearchTool()
216
+ results = ddg_tool.search("How many studio albums were published by Mercedes Sosa between 2000 and 2009 (included)?")
217
+ for result in results:
218
+ print(f"Title: {result.get('title', '')}")
219
+ print(f"Snippet: {result.get('snippet', '')}")
220
+ print()
221
+
222
+ # Example 3: Using the WebContentExtractor to extract specific information from web pages
223
+ extractor = WebContentExtractor()
224
+ content = extractor.extract_content("https://universetoday.com/example-article")
225
+ extracted_info = content.get("extracted_info", {})
226
+ if "nasa_award_numbers" in extracted_info:
227
+ print(f"NASA Award Numbers: {extracted_info['nasa_award_numbers']}")
228
+
229
+ # Example 4: Using the SerperSearchTool to find information about competitions
230
+ serper_tool = SerperSearchTool()
231
+ results = serper_tool.search("Who won the Malko Competition for Young Conductors in 2021?")
232
+ for result in results:
233
+ print(f"Title: {result.get('title', '')}")
234
+ print(f"Snippet: {result.get('snippet', '')}")
235
+ print()
236
+ ```
237
+
238
+ For more detailed information on the enhanced web search tools, see [Enhanced Web Search](enhanced_web_search.md).
239
+
240
  ## Command-Line Usage
241
 
242
  You can also run the agent from the command line using the provided scripts:
docs/index.md CHANGED
@@ -20,6 +20,7 @@ Welcome to the GAIA Agent documentation. This comprehensive guide provides detai
20
  - [Serper Integration](serper_integration.md): Guide for using the Serper API for Google search
21
  - [DuckDuckGo Integration](duckduckgo_integration.md): Guide for using DuckDuckGo search
22
  - [Multi-Search Integration](multi_search_integration.md): Guide for using multiple search providers
 
23
  - [Perplexity Integration](perplexity_integration.md): Guide for using Perplexity AI
24
 
25
  ### Memory Integrations
@@ -43,6 +44,7 @@ Welcome to the GAIA Agent documentation. This comprehensive guide provides detai
43
 
44
  ## Recent Updates
45
 
 
46
  - **April 30, 2025**: Added troubleshooting guide and langchain_openai integration documentation
47
  - **April 25, 2025**: Updated model configurations to use GPT-4o
48
  - **April 20, 2025**: Added multi-search integration documentation
 
20
  - [Serper Integration](serper_integration.md): Guide for using the Serper API for Google search
21
  - [DuckDuckGo Integration](duckduckgo_integration.md): Guide for using DuckDuckGo search
22
  - [Multi-Search Integration](multi_search_integration.md): Guide for using multiple search providers
23
+ - [Enhanced Web Search](enhanced_web_search.md): Guide for the enhanced web search tools for GAIA assessment
24
  - [Perplexity Integration](perplexity_integration.md): Guide for using Perplexity AI
25
 
26
  ### Memory Integrations
 
44
 
45
  ## Recent Updates
46
 
47
+ - **May 1, 2025**: Added enhanced web search tools for GAIA assessment questions
48
  - **April 30, 2025**: Added troubleshooting guide and langchain_openai integration documentation
49
  - **April 25, 2025**: Updated model configurations to use GPT-4o
50
  - **April 20, 2025**: Added multi-search integration documentation