README.md

---
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

```text
.
├── 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
```shell
# 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:
```shell
python -m venv .venv
source .venv/bin/activate  # On Windows: venv\Scripts\activate
```

2. Install dependencies:
```shell
pip install -r requirements.txt
```

3. Set up environment variables:
```shell
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
```shell
# 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:
```shell
pre-commit install
```

## Configuration

Create a `.env` file with the following variables:
```python
# 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
```shell
python gagent/main.py
```

### Using Agents Programmatically

#### LangGraph Agent
```python
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
```python
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
```python
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
```shell
# 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:
```shell
git checkout -b feature/your-feature-name
```

2. Make your changes and run checks:
```shell
black .
ruff check .
mypy .
pytest
```

3. Commit your changes:
```shell
git add .
git commit -m "Description of your changes"
```

4. Push and create a PR:
```shell
git push origin feature/your-feature-name
```

## License

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