README.md

metadata

title: GAgent
emoji: 🔥
colorFrom: green
colorTo: blue
sdk: gradio
sdk_version: 5.27.0
app_file: app.py
pinned: false
hf_oauth: true
hf_oauth_expiration_minutes: 480

Agentic AI

This project implements multiple agentic systems including:

1. LangGraph-based agents with various tools
2. Gemini-powered agents with multimedia analysis capabilities
3. GAIA agents built with smolagents for flexible deployment

Project Structure

.
├── gagent/           # Main package
│   ├── __init__.py     # Package initialization
│   ├── agents/         # Agent implementations
│   │   ├── base_agent.py      # Base agent implementation
│   │   ├── gemini_agent.py    # Gemini-based agent
│   │   ├── huggingface_agent.py # HuggingFace-based agent
│   │   ├── ollama_agent.py    # Ollama-based agent
│   │   ├── openai_agent.py    # OpenAI-based agent
│   │   ├── registry.py        # Agent registry
│   │   └── __init__.py        # Package initialization
│   ├── config/         # Configuration settings
│   │   ├── settings.py        # Application settings
│   │   └── __init__.py        # Package initialization
│   ├── rag/            # Retrieval Augmented Generation
│   │   ├── chroma_vector_store.py   # Chroma vectorstore implementation
│   │   ├── supabase_vector_store.py # Supabase vectorstore implementation
│   │   ├── vector_store.py          # Base vectorstore implementation
│   │   └── __init__.py              # Package initialization
│   ├── tools/          # Tool implementations
│   │   ├── code_interpreter.py  # Code execution tools
│   │   ├── data.py             # Data processing tools
│   │   ├── file.py             # File handling tools
│   │   ├── image.py            # Image processing tools
│   │   ├── math.py             # Mathematical tools
│   │   ├── media.py            # Media handling tools
│   │   ├── search.py           # Search tools
│   │   ├── utilities.py        # Utility tools
│   │   ├── wrappers.py         # Tool wrappers
│   │   └── __init__.py         # Package initialization
├── tests/              # Test files
│   ├── __init__.py
│   └── agents/         # Agent tests
│       ├── fixtures.py      # Test fixtures
│       ├── test_agents.py   # Agent tests
│       └── __init__.py      # Package initialization
├── exp/                # Experimental code and notebooks
├── app.py             # Gradio application
├── system_prompt.txt  # System prompt for the agent
├── pyproject.toml     # Project configuration
├── requirements.txt   # Dependencies
├── install.sh         # Installation script
├── env.example        # Example environment variables
├── .pre-commit-config.yaml # Pre-commit hooks configuration
└── README.md          # This file

Installation

Quick Start

# Clone the repository
git clone https://github.com/uoc/gagent.git
cd gagent

# Run the installation script
./install.sh

Manual Installation

1. Create and activate a virtual environment:

python -m venv .venv
source .venv/bin/activate  # On Windows: venv\Scripts\activate

2. Install dependencies:

pip install -r requirements.txt

3. Set up environment variables:

cp .env.example .env
# Edit .env with your API keys and configuration

Development Setup

Prerequisites

• Python 3.8 or higher
• Git
• Virtual environment (recommended)

Development Tools

The project uses several development tools:

• Ruff: For linting and code formatting
• Black: For code formatting
• MyPy: For type checking
• Pytest: For testing

Running Development Tools

# Format code
black .

# Lint code
ruff check .

# Type check
mypy .

# Run tests
pytest

Pre-commit Hooks

Pre-commit hooks are set up to run checks before each commit:

pre-commit install

Configuration

Create a .env file with the following variables:

# API Keys
OPENAI_API_KEY=your_openai_api_key
GOOGLE_API_KEY=your_google_api_key
HUGGINGFACE_API_KEY=your_huggingface_api_key

# Database Configuration
SUPABASE_URL=your_supabase_url
SUPABASE_KEY=your_supabase_key

# Other Configuration
PYTHONPATH=$(pwd)

Usage

Running the Application

python gagent/main.py

Using Agents Programmatically

LangGraph Agent

from main import process_question

# Process a question using Google's Gemini
result = process_question("Your question here", provider="google")

# Or use Groq
result = process_question("Your question here", provider="groq")

# Or use HuggingFace
result = process_question("Your question here", provider="huggingface")

Gemini Agent

from main import create_gemini_agent

# Create the agent
agent = create_gemini_agent(api_key="your_google_api_key")

# Run a query
response = agent.run("What are the main effects of climate change?")

GAIA Agent

from main import create_gaia_agent

# Create with HuggingFace models
agent = create_gaia_agent(
    model_type="HfApiModel",
    model_id="meta-llama/Llama-3-70B-Instruct",
    verbose=True
)

# Or create with OpenAI
agent = create_gaia_agent(
    model_type="OpenAIServerModel",
    model_id="gpt-4o",
    verbose=True
)

# Answer a question
response = agent.answer_question("What is the square root of 144?")

Testing

Running Tests

# Run all tests
pytest

# Run tests with coverage
pytest --cov=gagent

# Run specific test file
pytest tests/test_agents.py

Writing Tests

1. Create test files in the tests directory
2. Use fixtures from conftest.py
3. Follow pytest best practices

Available Agent Types

1. LangGraph Agent:

   • Graph-based approach for complex reasoning
   • Vectorstore-backed retrieval
   • Multiple LLM provider support

2. Gemini Agent:

   • Media analysis capabilities (images, videos, tables)
   • Multi-tool framework with web search and Wikipedia
   • Conversation memory

3. GAIA Agent:

   • Built with smolagents
   • Code execution capability
   • Multiple model backends
   • File handling and data analysis

Available Tools

1. Mathematical Operations:

   • Addition, Subtraction, Multiplication, Division, Modulus

2. Search Tools:

   • Wikipedia Search
   • Web Search (via Tavily or DuckDuckGo)
   • ArXiv Search

3. File & Media Tools:

   • Image analysis
   • Excel/CSV analysis
   • File download and processing

Contributing

1. Fork the repository
2. Create a feature branch
3. Set up development environment
4. Make your changes
5. Run tests and checks
6. Commit your changes
7. Push to the branch
8. Create a Pull Request

Development Workflow

1. Create a new branch:

git checkout -b feature/your-feature-name

2. Make your changes and run checks:

black .
ruff check .
mypy .
pytest

3. Commit your changes:

git add .
git commit -m "Description of your changes"

4. Push and create a PR:

git push origin feature/your-feature-name

License

This project is licensed under the MIT License - see the LICENSE file for details.