README.md

metadata

title: GAIA Lite
emoji: 🤖
colorFrom: green
colorTo: blue
sdk: gradio
sdk_version: 5.25.2
app_file: app.py
pinned: false
hf_oauth: true
hf_oauth_expiration_minutes: 480

🤖 GAIA Lite

🌟 Introduction

GAIA Lite is a small tool-calling agent for learning LangGraph and for the GAIA / Hugging Face Agents Course homework. It keeps a short tool list, a bounded think–act loop, regex answer extraction, and a cached evaluation runner.

🚀 Key Features

• 🔍 Multi-Modal Search: Web search, Wikipedia, and arXiv paper search
• 💻 Code Execution: Support for Python, Bash, SQL, C, and Java
• 🖼️ Image Processing: Analysis, transformation, OCR, and generation
• 📄 Document Processing: PDF, CSV, Excel, and text file analysis
• 📁 File Upload Support: Handle multiple file types with drag-and-drop
• 🧮 Mathematical Operations: Complete set of mathematical tools
• 💬 Conversational Interface: Natural chat-based interaction
• 📊 Evaluation System: Automated benchmark testing and submission

🏗️ Project Structure

gaia-lite/
├── app.py                    # Gradio Q&A chatbot
├── evaluation_app.py         # GAIA eval + cached submit
├── agent.py                  # Tools + LangGraph loop
├── extract_answer.py         # Parse/normalize FINAL ANSWER
├── files_util.py             # Attachment download + prompt paths
├── code_interpreter.py       # Python (and other) code execution
├── image_processing.py       # Optional image helpers (not wired)
├── system_prompt.txt         # Agent instructions
├── answers_cache.json        # Local eval cache (gitignored)
├── requirements.txt
└── README.md

🛠️ Tools (kept small on purpose)

The agent binds six tools. Extra math/image-generation helpers were removed from the loop so the model spends less time picking the wrong tool.

• web_search — Tavily, up to 3 hits
• wiki_search — Wikipedia, up to 2 pages
• execute_python — calculation, pandas, dates, CSV/Excel via code
• download_file_from_url — save a remote file locally
• read_file — preview text, CSV, Excel, PDF
• extract_text_from_image — Tesseract OCR

Vector-store retrieval is off by default. Pass build_graph(use_retriever=True) only if you explicitly want similar-question context.

🎯 How to Use

Q&A Chatbot Interface (app.py)

1. Start the Chatbot:

   python app.py
   

2. Access the Interface:

   • Open http://localhost:7860 in your browser
   • Upload files (images, documents, CSV, etc.) if needed
   • Ask questions in natural language
   • Get comprehensive answers with tool usage

3. Supported Interactions:

   • Text Questions: "What is the capital of France?"
   • Math Problems: "Calculate the square root of 144"
   • Code Requests: "Write a Python function to sort a list"
   • Image Analysis: Upload an image and ask "What do you see?"
   • Data Analysis: Upload a CSV and ask "What are the trends?"
   • Web Search: "What are the latest AI developments?"

Evaluation Runner (evaluation_app.py)

1. Run the Evaluation:

   python evaluation_app.py
   

2. Benchmark Testing:

   • Log in with your Hugging Face account
   • Click "Run Evaluation & Submit All Answers"
   • Monitor progress as the agent processes GAIA benchmark questions
   • View results and scores automatically

🔧 Technical Architecture

LangGraph State Machine

START → maybe_example → assistant ⇄ tools
                          ↑           ↓
                          └───────────┘

1. maybe_example: no-op unless use_retriever=True
2. assistant: Groq Qwen with tools; after 8 tool rounds or a repeated identical call, it is forced to emit FINAL ANSWER
3. tools: ToolNode runs the selected Python functions
4. extract_final_answer: regex parse + light normalization before scoring submit

Evaluation writes answers_cache.json, skips successful tasks on rerun, and submits from cache in a separate button. Attachments use GET /files/{task_id}, with an optional Hugging Face GAIA dataset fallback.

Vector Database Integration

• Supabase Vector Store: Stores GAIA benchmark Q&A pairs
• Semantic Search: Finds similar questions for context
• HuggingFace Embeddings: sentence-transformers/all-mpnet-base-v2

Multi-Modal File Support

• Images: JPG, PNG, GIF, BMP, WebP
• Documents: PDF, DOC, DOCX, TXT, MD
• Data: CSV, Excel, JSON
• Code: Python, Bash, SQL, C, Java

⚙️ Installation & Setup

Hugging Face Space secrets (most common crash)

If logs say GROQ_API_KEY is missing, open the Space → Settings → Variables and secrets and add at least:

• GROQ_API_KEY — from https://console.groq.com/keys
• TAVILY_API_KEY — for web search

Then Restart the Space. Do not put keys in public git.

Local setup

git clone https://github.com/fisherman611/gaia-agent.git gaia-lite
cd gaia-lite
pip install -r requirements.txt

Create a .env file with your API keys:

SUPABASE_URL=your_supabase_url
SUPABASE_SERVICE_ROLE_KEY=your_supabase_key
GROQ_API_KEY=your_groq_api_key
TAVILY_API_KEY=your_tavily_api_key
HUGGINGFACEHUB_API_TOKEN=your_hf_token
LANGSMITH_API_KEY=your_langsmith_key

LANGSMITH_TRACING=true
LANGSMITH_PROJECT=gaia-lite
LANGSMITH_ENDPOINT=https://api.smith.langchain.com

4. Database Setup (Supabase)

Execute this SQL in your Supabase database:

-- Enable pgvector extension
CREATE EXTENSION IF NOT EXISTS vector;

-- Create match function for documents2 table
CREATE OR REPLACE FUNCTION public.match_documents_2(
  query_embedding vector(768)
)
RETURNS TABLE(
  id         bigint,
  content    text,
  metadata   jsonb,
  embedding  vector(768),
  similarity double precision
)
LANGUAGE sql STABLE
AS $$
  SELECT
    id,
    content,
    metadata,
    embedding,
    1 - (embedding <=> query_embedding) AS similarity
  FROM public.documents2
  ORDER BY embedding <=> query_embedding
  LIMIT 10;
$$;

-- Grant permissions
GRANT EXECUTE ON FUNCTION public.match_documents_2(vector) TO anon, authenticated;

🚀 Running the Application

Chatbot Interface

python app.py

Access at: http://localhost:7860

Evaluation Runner

python evaluation_app.py

Access at: http://localhost:7860

Live Demo

Upstream template Space: fisherman611/gaia-agent

🔗 Resources

• GAIA Benchmark
• Hugging Face Agents Course
• LangGraph Documentation
• Supabase Vector Store

🤝 Contributing

Contributions are welcome! Areas for improvement:

• New Tools: Add specialized tools for specific domains
• UI Enhancements: Improve the chatbot interface
• Performance: Optimize response times and accuracy
• Documentation: Expand examples and use cases

📄 License

This project is licensed under the MIT License.