Spaces:
Sleeping
Sleeping
|
Download README.md from jm-vis/Final_Assignment_GAIAAgent: direct link, hf CLI and curl.
- Browser
- Download file 7.46 kB
-
https://huggingface.co/spaces/jm-vis/Final_Assignment_GAIAAgent/resolve/main/README.md
- Command line
-
hf download hf://spaces/jm-vis/Final_Assignment_GAIAAgent/README.md
-
curl -L -o README.md https://huggingface.co/spaces/jm-vis/Final_Assignment_GAIAAgent/resolve/main/README.md
7.46 kB
| title: GAIA Agent | |
| emoji: π | |
| colorFrom: indigo | |
| colorTo: indigo | |
| sdk: gradio | |
| sdk_version: 3.44.4 | |
| app_file: app.py | |
| pinned: false | |
| hf_oauth: true | |
| hf_oauth_expiration_minutes: 480 | |
| # GAIA Agent - Grounded AI Assistant | |
|  | |
| 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. | |
| ## Core Capabilities | |
| GAIA Agent delivers high-quality answers through: | |
| - **Web-Grounded Responses**: Retrieves current information from multiple search engines | |
| - **Structured Reasoning Process**: Follows a systematic workflow for analysis, planning, and answer formulation | |
| - **Adaptable Tool Usage**: Dynamically selects and executes appropriate tools based on question requirements | |
| - **Robust Error Handling**: Includes multiple fallback mechanisms to ensure reliability | |
| ## Key Features | |
| - **LangGraph Workflow Integration**: Manages the agent's reasoning process with a clear state-based approach | |
| - **Multiple Search Backends**: Supports both DuckDuckGo and Serper API for web searches | |
| - **Content Extraction**: Can analyze and extract relevant information from web pages | |
| - **Memory Management**: Efficiently caches responses and manages conversation context | |
| - **Special Case Detection**: Includes handling for edge cases like reversed text questions | |
| - **Graceful Degradation**: Continues functioning even with limited API access or resources | |
| ## Setup & Installation | |
| ### Environment Requirements | |
| The GAIA Agent requires the following environment variables: | |
| ``` | |
| OPENAI_API_KEY=your_openai_key_here | |
| SERPER_API_KEY=your_serper_key_here # Optional, falls back to DuckDuckGo | |
| SUPABASE_URL=your_supabase_url # Optional, for enhanced memory | |
| SUPABASE_KEY=your_supabase_key # Optional, for enhanced memory | |
| ``` | |
| ### Installation Steps | |
| 1. Clone this repository | |
| 2. Install dependencies: | |
| ```bash | |
| pip install -r requirements.txt | |
| ``` | |
| 3. Set up environment variables (create a `.env` file or set them in your environment) | |
| 4. Run the application: | |
| ```bash | |
| python app.py | |
| ``` | |
| ### Dependencies | |
| The GAIA Agent requires the following key packages: | |
| - `langchain` and `langgraph`: Core agent architecture components | |
| - `langchain-openai`: Integration with OpenAI models | |
| - `duckduckgo-search`: Web search capability | |
| - `requests` and `beautifulsoup4`: Web content extraction | |
| - `gradio`: User interface components | |
| ## Usage Instructions | |
| ### Basic Usage | |
| 1. Start the application with `python app.py` | |
| 2. Open the displayed URL in your browser | |
| 3. Type your question in the input box and click "Submit" | |
| 4. The agent will analyze your question, gather information, and provide a response | |
| ### API Usage | |
| You can also use the agent programmatically by importing the `GAIAAgent` class: | |
| ```python | |
| from agent import GAIAAgent | |
| # Initialize the agent | |
| agent = GAIAAgent() | |
| # Process a question and get a simple string response | |
| response = agent.process_question("What is the capital of France?") | |
| print(response) | |
| # Or get a detailed response with metadata | |
| result = agent.query("What is the capital of France?") | |
| print(result["answer"]) | |
| print(result["tools_used"]) | |
| ``` | |
| ### Testing the Agent | |
| Run the test suite to verify the agent's functionality: | |
| ```bash | |
| # Run all tests | |
| python test_agent.py run | |
| # Run specific test categories | |
| python test_agent.py web # Test web search functionality | |
| python test_agent.py special # Test special case handling | |
| python test_agent.py memory # Test memory functionality | |
| ``` | |
| ## Architecture & Design | |
| The GAIA Agent follows a structured workflow implemented with LangGraph: | |
| 1. **Question Analysis**: Examines the question to determine its type, complexity, and required tools | |
| 2. **Plan Creation**: Generates a step-by-step plan for answering the question | |
| 3. **Tool Execution**: Runs necessary tools (web search, content extraction) according to the plan | |
| 4. **Answer Formulation**: Synthesizes information into a comprehensive, accurate response | |
| ### Component Architecture | |
| ``` | |
| GAIAAgent | |
| βββ LangGraph Workflow | |
| β βββ analyze_question() | |
| β βββ create_plan() | |
| β βββ execute_tool() | |
| β βββ formulate_answer() | |
| β | |
| βββ Tool Components | |
| β βββ WebSearchTool | |
| β β βββ DuckDuckGo search | |
| β β βββ Serper API fallback | |
| β βββ ContentExtractor | |
| β | |
| βββ SimpleMemory | |
| βββ Conversation history | |
| βββ Result caching | |
| ``` | |
| ### File Structure | |
| - `agent.py`: Core implementation of the GAIA Agent using LangGraph | |
| - `app.py`: Gradio-based user interface for interacting with the agent | |
| - `test_agent.py`: Comprehensive test suite for validating functionality | |
| - `requirements.txt`: Required dependencies | |
| - `run_test.py` and `run_test.sh`: Convenience scripts for testing | |
| ## API Requirements | |
| For full functionality, GAIA requires: | |
| - **OpenAI API**: Powers the large language model capabilities (required) | |
| - **Serper API**: Alternative web search backend (optional, falls back to DuckDuckGo) | |
| - **Supabase**: Enhanced memory capabilities (optional) | |
| ## Limitations & Known Issues | |
| - **Rate Limiting**: Web search tools may be subject to rate limiting when used extensively | |
| - **Content Extraction**: May struggle with some complex or JavaScript-heavy websites | |
| - **Answer Quality**: Responses depend on the quality of available search results | |
| - **Context Length**: Limited by the underlying LLM's context window size | |
| - **Computation Time**: Complex questions requiring multiple searches may take longer to answer | |
| ## Troubleshooting | |
| ### Common Issues | |
| 1. **Missing API Keys** | |
| - Error: "Error: GAIA Agent is not initialized" | |
| - Solution: Ensure the required environment variables are set, especially `OPENAI_API_KEY` | |
| 2. **Search Limitations** | |
| - Error: "Error searching with DuckDuckGo" | |
| - Solution: Retry with a different search query or try enabling the Serper API | |
| 3. **Model Errors** | |
| - Error: "Error during question analysis" or "Error formulating answer" | |
| - Solution: Check your OpenAI API key and quota, or try a less complex question | |
| 4. **Web Content Issues** | |
| - Error: "Error extracting content" | |
| - Solution: The target website may be blocking scraping; try a different source | |
| ### Debug Mode | |
| For enhanced debugging, modify the logging level in `agent.py`: | |
| ```python | |
| logging.basicConfig( | |
| level=logging.DEBUG, # Change from INFO to DEBUG | |
| format='%(asctime)s - %(name)s - %(levelname)s - %(message)s' | |
| ) | |
| ``` | |
| ## Extending GAIA | |
| You can extend GAIA's capabilities by: | |
| 1. **Adding New Tools**: Implement new tools in the `execute_tool` function in `agent.py` | |
| 2. **Customizing Prompts**: Modify the prompt templates in `analyze_question`, `create_plan`, and `formulate_answer` | |
| 3. **Enhancing Memory**: Extend the `SimpleMemory` class with additional storage options | |
| 4. **Optimizing Search**: Implement additional search backends or content extraction methods | |
| ## License & Attribution | |
| GAIA Agent is developed as part of the Hugging Face Agents course and is intended for educational and demonstration purposes. | |
| --- | |
| *For more information, questions, or issues, please visit the repository on Hugging Face Spaces or submit an issue on GitHub.* |