Joachim M. Vis commited on
Commit
479e45b
Β·
verified Β·
1 Parent(s): 1c31893

Update README.md

Browse files
Files changed (1) hide show
  1. README.md +216 -203
README.md CHANGED
@@ -1,204 +1,217 @@
1
- # GAIA Agent - Grounded AI Assistant
2
-
3
- ![GAIA Agent Logo](https://huggingface.co/datasets/huggingface-course/documentation-images/resolve/main/en/chapter9/gaia-agent.png)
4
-
5
- GAIA (Grounded AI Assistant) is a robust, LangGraph-based agent designed to provide accurate, well-reasoned responses by leveraging real-time web data and structured reasoning. This implementation offers a streamlined, production-ready version optimized for deployment on Hugging Face Spaces.
6
-
7
- ## Core Capabilities
8
-
9
- GAIA Agent delivers high-quality answers through:
10
-
11
- - **Web-Grounded Responses**: Retrieves current information from multiple search engines
12
- - **Structured Reasoning Process**: Follows a systematic workflow for analysis, planning, and answer formulation
13
- - **Adaptable Tool Usage**: Dynamically selects and executes appropriate tools based on question requirements
14
- - **Robust Error Handling**: Includes multiple fallback mechanisms to ensure reliability
15
-
16
- ## Key Features
17
-
18
- - **LangGraph Workflow Integration**: Manages the agent's reasoning process with a clear state-based approach
19
- - **Multiple Search Backends**: Supports both DuckDuckGo and Serper API for web searches
20
- - **Content Extraction**: Can analyze and extract relevant information from web pages
21
- - **Memory Management**: Efficiently caches responses and manages conversation context
22
- - **Special Case Detection**: Includes handling for edge cases like reversed text questions
23
- - **Graceful Degradation**: Continues functioning even with limited API access or resources
24
-
25
- ## Setup & Installation
26
-
27
- ### Environment Requirements
28
-
29
- The GAIA Agent requires the following environment variables:
30
-
31
- ```
32
- OPENAI_API_KEY=your_openai_key_here
33
- SERPER_API_KEY=your_serper_key_here # Optional, falls back to DuckDuckGo
34
- SUPABASE_URL=your_supabase_url # Optional, for enhanced memory
35
- SUPABASE_KEY=your_supabase_key # Optional, for enhanced memory
36
- ```
37
-
38
- ### Installation Steps
39
-
40
- 1. Clone this repository
41
- 2. Install dependencies:
42
- ```bash
43
- pip install -r requirements.txt
44
- ```
45
- 3. Set up environment variables (create a `.env` file or set them in your environment)
46
- 4. Run the application:
47
- ```bash
48
- python app.py
49
- ```
50
-
51
- ### Dependencies
52
-
53
- The GAIA Agent requires the following key packages:
54
-
55
- - `langchain` and `langgraph`: Core agent architecture components
56
- - `langchain-openai`: Integration with OpenAI models
57
- - `duckduckgo-search`: Web search capability
58
- - `requests` and `beautifulsoup4`: Web content extraction
59
- - `gradio`: User interface components
60
-
61
- ## Usage Instructions
62
-
63
- ### Basic Usage
64
-
65
- 1. Start the application with `python app.py`
66
- 2. Open the displayed URL in your browser
67
- 3. Type your question in the input box and click "Submit"
68
- 4. The agent will analyze your question, gather information, and provide a response
69
-
70
- ### API Usage
71
-
72
- You can also use the agent programmatically by importing the `GAIAAgent` class:
73
-
74
- ```python
75
- from agent import GAIAAgent
76
-
77
- # Initialize the agent
78
- agent = GAIAAgent()
79
-
80
- # Process a question and get a simple string response
81
- response = agent.process_question("What is the capital of France?")
82
- print(response)
83
-
84
- # Or get a detailed response with metadata
85
- result = agent.query("What is the capital of France?")
86
- print(result["answer"])
87
- print(result["tools_used"])
88
- ```
89
-
90
- ### Testing the Agent
91
-
92
- Run the test suite to verify the agent's functionality:
93
-
94
- ```bash
95
- # Run all tests
96
- python test_agent.py run
97
-
98
- # Run specific test categories
99
- python test_agent.py web # Test web search functionality
100
- python test_agent.py special # Test special case handling
101
- python test_agent.py memory # Test memory functionality
102
- ```
103
-
104
- ## Architecture & Design
105
-
106
- The GAIA Agent follows a structured workflow implemented with LangGraph:
107
-
108
- 1. **Question Analysis**: Examines the question to determine its type, complexity, and required tools
109
- 2. **Plan Creation**: Generates a step-by-step plan for answering the question
110
- 3. **Tool Execution**: Runs necessary tools (web search, content extraction) according to the plan
111
- 4. **Answer Formulation**: Synthesizes information into a comprehensive, accurate response
112
-
113
- ### Component Architecture
114
-
115
- ```
116
- GAIAAgent
117
- β”œβ”€β”€ LangGraph Workflow
118
- β”‚ β”œβ”€β”€ analyze_question()
119
- β”‚ β”œβ”€β”€ create_plan()
120
- β”‚ β”œβ”€β”€ execute_tool()
121
- β”‚ └── formulate_answer()
122
- β”‚
123
- β”œβ”€β”€ Tool Components
124
- β”‚ β”œβ”€β”€ WebSearchTool
125
- β”‚ β”‚ β”œβ”€β”€ DuckDuckGo search
126
- β”‚ β”‚ └── Serper API fallback
127
- β”‚ └── ContentExtractor
128
- β”‚
129
- └── SimpleMemory
130
- β”œβ”€β”€ Conversation history
131
- └── Result caching
132
- ```
133
-
134
- ### File Structure
135
-
136
- - `agent.py`: Core implementation of the GAIA Agent using LangGraph
137
- - `app.py`: Gradio-based user interface for interacting with the agent
138
- - `test_agent.py`: Comprehensive test suite for validating functionality
139
- - `requirements.txt`: Required dependencies
140
- - `run_test.py` and `run_test.sh`: Convenience scripts for testing
141
-
142
- ## API Requirements
143
-
144
- For full functionality, GAIA requires:
145
-
146
- - **OpenAI API**: Powers the large language model capabilities (required)
147
- - **Serper API**: Alternative web search backend (optional, falls back to DuckDuckGo)
148
- - **Supabase**: Enhanced memory capabilities (optional)
149
-
150
- ## Limitations & Known Issues
151
-
152
- - **Rate Limiting**: Web search tools may be subject to rate limiting when used extensively
153
- - **Content Extraction**: May struggle with some complex or JavaScript-heavy websites
154
- - **Answer Quality**: Responses depend on the quality of available search results
155
- - **Context Length**: Limited by the underlying LLM's context window size
156
- - **Computation Time**: Complex questions requiring multiple searches may take longer to answer
157
-
158
- ## Troubleshooting
159
-
160
- ### Common Issues
161
-
162
- 1. **Missing API Keys**
163
- - Error: "Error: GAIA Agent is not initialized"
164
- - Solution: Ensure the required environment variables are set, especially `OPENAI_API_KEY`
165
-
166
- 2. **Search Limitations**
167
- - Error: "Error searching with DuckDuckGo"
168
- - Solution: Retry with a different search query or try enabling the Serper API
169
-
170
- 3. **Model Errors**
171
- - Error: "Error during question analysis" or "Error formulating answer"
172
- - Solution: Check your OpenAI API key and quota, or try a less complex question
173
-
174
- 4. **Web Content Issues**
175
- - Error: "Error extracting content"
176
- - Solution: The target website may be blocking scraping; try a different source
177
-
178
- ### Debug Mode
179
-
180
- For enhanced debugging, modify the logging level in `agent.py`:
181
-
182
- ```python
183
- logging.basicConfig(
184
- level=logging.DEBUG, # Change from INFO to DEBUG
185
- format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
186
- )
187
- ```
188
-
189
- ## Extending GAIA
190
-
191
- You can extend GAIA's capabilities by:
192
-
193
- 1. **Adding New Tools**: Implement new tools in the `execute_tool` function in `agent.py`
194
- 2. **Customizing Prompts**: Modify the prompt templates in `analyze_question`, `create_plan`, and `formulate_answer`
195
- 3. **Enhancing Memory**: Extend the `SimpleMemory` class with additional storage options
196
- 4. **Optimizing Search**: Implement additional search backends or content extraction methods
197
-
198
- ## License & Attribution
199
-
200
- GAIA Agent is developed as part of the Hugging Face Agents course and is intended for educational and demonstration purposes.
201
-
202
- ---
203
-
 
 
 
 
 
 
 
 
 
 
 
 
 
204
  *For more information, questions, or issues, please visit the repository on Hugging Face Spaces or submit an issue on GitHub.*
 
1
+ ---
2
+ title: GAIA Agent
3
+ emoji: πŸ€–
4
+ colorFrom: blue
5
+ colorTo: green
6
+ sdk: gradio
7
+ sdk_version: 3.44.4
8
+ app_file: app.py
9
+ pinned: false
10
+ hf_oauth: true
11
+ hf_oauth_expiration_minutes: 480
12
+ ---
13
+
14
+ # GAIA Agent - Grounded AI Assistant
15
+
16
+ ![GAIA Agent Logo](https://huggingface.co/datasets/huggingface-course/documentation-images/resolve/main/en/chapter9/gaia-agent.png)
17
+
18
+ GAIA (Grounded AI Assistant) is a robust, LangGraph-based agent designed to provide accurate, well-reasoned responses by leveraging real-time web data and structured reasoning. This implementation offers a streamlined, production-ready version optimized for deployment on Hugging Face Spaces.
19
+
20
+ ## Core Capabilities
21
+
22
+ GAIA Agent delivers high-quality answers through:
23
+
24
+ - **Web-Grounded Responses**: Retrieves current information from multiple search engines
25
+ - **Structured Reasoning Process**: Follows a systematic workflow for analysis, planning, and answer formulation
26
+ - **Adaptable Tool Usage**: Dynamically selects and executes appropriate tools based on question requirements
27
+ - **Robust Error Handling**: Includes multiple fallback mechanisms to ensure reliability
28
+
29
+ ## Key Features
30
+
31
+ - **LangGraph Workflow Integration**: Manages the agent's reasoning process with a clear state-based approach
32
+ - **Multiple Search Backends**: Supports both DuckDuckGo and Serper API for web searches
33
+ - **Content Extraction**: Can analyze and extract relevant information from web pages
34
+ - **Memory Management**: Efficiently caches responses and manages conversation context
35
+ - **Special Case Detection**: Includes handling for edge cases like reversed text questions
36
+ - **Graceful Degradation**: Continues functioning even with limited API access or resources
37
+
38
+ ## Setup & Installation
39
+
40
+ ### Environment Requirements
41
+
42
+ The GAIA Agent requires the following environment variables:
43
+
44
+ ```
45
+ OPENAI_API_KEY=your_openai_key_here
46
+ SERPER_API_KEY=your_serper_key_here # Optional, falls back to DuckDuckGo
47
+ SUPABASE_URL=your_supabase_url # Optional, for enhanced memory
48
+ SUPABASE_KEY=your_supabase_key # Optional, for enhanced memory
49
+ ```
50
+
51
+ ### Installation Steps
52
+
53
+ 1. Clone this repository
54
+ 2. Install dependencies:
55
+ ```bash
56
+ pip install -r requirements.txt
57
+ ```
58
+ 3. Set up environment variables (create a `.env` file or set them in your environment)
59
+ 4. Run the application:
60
+ ```bash
61
+ python app.py
62
+ ```
63
+
64
+ ### Dependencies
65
+
66
+ The GAIA Agent requires the following key packages:
67
+
68
+ - `langchain` and `langgraph`: Core agent architecture components
69
+ - `langchain-openai`: Integration with OpenAI models
70
+ - `duckduckgo-search`: Web search capability
71
+ - `requests` and `beautifulsoup4`: Web content extraction
72
+ - `gradio`: User interface components
73
+
74
+ ## Usage Instructions
75
+
76
+ ### Basic Usage
77
+
78
+ 1. Start the application with `python app.py`
79
+ 2. Open the displayed URL in your browser
80
+ 3. Type your question in the input box and click "Submit"
81
+ 4. The agent will analyze your question, gather information, and provide a response
82
+
83
+ ### API Usage
84
+
85
+ You can also use the agent programmatically by importing the `GAIAAgent` class:
86
+
87
+ ```python
88
+ from agent import GAIAAgent
89
+
90
+ # Initialize the agent
91
+ agent = GAIAAgent()
92
+
93
+ # Process a question and get a simple string response
94
+ response = agent.process_question("What is the capital of France?")
95
+ print(response)
96
+
97
+ # Or get a detailed response with metadata
98
+ result = agent.query("What is the capital of France?")
99
+ print(result["answer"])
100
+ print(result["tools_used"])
101
+ ```
102
+
103
+ ### Testing the Agent
104
+
105
+ Run the test suite to verify the agent's functionality:
106
+
107
+ ```bash
108
+ # Run all tests
109
+ python test_agent.py run
110
+
111
+ # Run specific test categories
112
+ python test_agent.py web # Test web search functionality
113
+ python test_agent.py special # Test special case handling
114
+ python test_agent.py memory # Test memory functionality
115
+ ```
116
+
117
+ ## Architecture & Design
118
+
119
+ The GAIA Agent follows a structured workflow implemented with LangGraph:
120
+
121
+ 1. **Question Analysis**: Examines the question to determine its type, complexity, and required tools
122
+ 2. **Plan Creation**: Generates a step-by-step plan for answering the question
123
+ 3. **Tool Execution**: Runs necessary tools (web search, content extraction) according to the plan
124
+ 4. **Answer Formulation**: Synthesizes information into a comprehensive, accurate response
125
+
126
+ ### Component Architecture
127
+
128
+ ```
129
+ GAIAAgent
130
+ β”œβ”€β”€ LangGraph Workflow
131
+ β”‚ β”œβ”€β”€ analyze_question()
132
+ β”‚ β”œβ”€β”€ create_plan()
133
+ β”‚ β”œβ”€β”€ execute_tool()
134
+ β”‚ └── formulate_answer()
135
+ β”‚
136
+ β”œβ”€β”€ Tool Components
137
+ β”‚ β”œβ”€β”€ WebSearchTool
138
+ β”‚ β”‚ β”œβ”€β”€ DuckDuckGo search
139
+ β”‚ β”‚ └── Serper API fallback
140
+ β”‚ └── ContentExtractor
141
+ β”‚
142
+ └── SimpleMemory
143
+ β”œβ”€β”€ Conversation history
144
+ └── Result caching
145
+ ```
146
+
147
+ ### File Structure
148
+
149
+ - `agent.py`: Core implementation of the GAIA Agent using LangGraph
150
+ - `app.py`: Gradio-based user interface for interacting with the agent
151
+ - `test_agent.py`: Comprehensive test suite for validating functionality
152
+ - `requirements.txt`: Required dependencies
153
+ - `run_test.py` and `run_test.sh`: Convenience scripts for testing
154
+
155
+ ## API Requirements
156
+
157
+ For full functionality, GAIA requires:
158
+
159
+ - **OpenAI API**: Powers the large language model capabilities (required)
160
+ - **Serper API**: Alternative web search backend (optional, falls back to DuckDuckGo)
161
+ - **Supabase**: Enhanced memory capabilities (optional)
162
+
163
+ ## Limitations & Known Issues
164
+
165
+ - **Rate Limiting**: Web search tools may be subject to rate limiting when used extensively
166
+ - **Content Extraction**: May struggle with some complex or JavaScript-heavy websites
167
+ - **Answer Quality**: Responses depend on the quality of available search results
168
+ - **Context Length**: Limited by the underlying LLM's context window size
169
+ - **Computation Time**: Complex questions requiring multiple searches may take longer to answer
170
+
171
+ ## Troubleshooting
172
+
173
+ ### Common Issues
174
+
175
+ 1. **Missing API Keys**
176
+ - Error: "Error: GAIA Agent is not initialized"
177
+ - Solution: Ensure the required environment variables are set, especially `OPENAI_API_KEY`
178
+
179
+ 2. **Search Limitations**
180
+ - Error: "Error searching with DuckDuckGo"
181
+ - Solution: Retry with a different search query or try enabling the Serper API
182
+
183
+ 3. **Model Errors**
184
+ - Error: "Error during question analysis" or "Error formulating answer"
185
+ - Solution: Check your OpenAI API key and quota, or try a less complex question
186
+
187
+ 4. **Web Content Issues**
188
+ - Error: "Error extracting content"
189
+ - Solution: The target website may be blocking scraping; try a different source
190
+
191
+ ### Debug Mode
192
+
193
+ For enhanced debugging, modify the logging level in `agent.py`:
194
+
195
+ ```python
196
+ logging.basicConfig(
197
+ level=logging.DEBUG, # Change from INFO to DEBUG
198
+ format='%(asctime)s - %(name)s - %(levelname)s - %(message)s'
199
+ )
200
+ ```
201
+
202
+ ## Extending GAIA
203
+
204
+ You can extend GAIA's capabilities by:
205
+
206
+ 1. **Adding New Tools**: Implement new tools in the `execute_tool` function in `agent.py`
207
+ 2. **Customizing Prompts**: Modify the prompt templates in `analyze_question`, `create_plan`, and `formulate_answer`
208
+ 3. **Enhancing Memory**: Extend the `SimpleMemory` class with additional storage options
209
+ 4. **Optimizing Search**: Implement additional search backends or content extraction methods
210
+
211
+ ## License & Attribution
212
+
213
+ GAIA Agent is developed as part of the Hugging Face Agents course and is intended for educational and demonstration purposes.
214
+
215
+ ---
216
+
217
  *For more information, questions, or issues, please visit the repository on Hugging Face Spaces or submit an issue on GitHub.*