docs/deployment/DEPLOYMENT_GUIDE.md

GAIA Deployment Guide

This guide outlines the procedures for deploying the GAIA agent in various environments, including local development, testing, and production deployments.

Table of Contents

1. Prerequisites
2. Environment Configuration
3. Local Deployment
4. Hugging Face Spaces Deployment
5. Custom Server Deployment
6. API-Only Deployment
7. Monitoring and Maintenance
8. Troubleshooting

Prerequisites

Before deploying GAIA, ensure you have the following:

• Python 3.10+
• Git
• Required API keys for external services:
  • Supabase (for memory persistence)
  • Search providers (Serper, DuckDuckGo, etc.)
  • LLM providers (OpenAI, Anthropic, etc.)
• Virtual environment management tools

Environment Configuration

Environment Variables

GAIA uses environment variables for configuration. Create a .env file based on .env.example with the following sections:

# Core Configuration
GAIA_ENVIRONMENT=production  # or development or testing
GAIA_LOG_LEVEL=INFO  # DEBUG, INFO, WARNING, ERROR

# API Keys
OPENAI_API_KEY=your_openai_api_key
SERPER_API_KEY=your_serper_api_key
DUCKDUCKGO_API_KEY=your_duckduckgo_api_key
PERPLEXITY_API_KEY=your_perplexity_api_key

# Supabase Configuration
SUPABASE_URL=your_supabase_url
SUPABASE_KEY=your_supabase_key
SUPABASE_TABLE_PREFIX=gaia_

# Web Server Configuration
GAIA_HOST=0.0.0.0
GAIA_PORT=8000
GAIA_WORKERS=4  # Number of worker processes

# Memory Configuration
GAIA_MEMORY_PROVIDER=supabase  # or local
GAIA_MEMORY_TTL=86400  # Time to live in seconds (24 hours)

Validating Environment

Before deployment, validate your environment configuration:

python src/gaia/utils/validate_environment.py

This script checks that all required environment variables are set and that API credentials are valid.

Local Deployment

Development Environment

For local development and testing:

1. Clone the repository

   git clone https://github.com/your-org/gaia.git
   cd gaia
   

2. Create a virtual environment

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

3. Install dependencies

   pip install -r requirements.txt
   

4. Set up environment variables

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

5. Run the development server

   python app.py
   

The development server will be available at http://localhost:8000.

Running with Docker

For a containerized local deployment:

1. Build the Docker image

   docker build -t gaia-agent .
   

2. Run the container

   docker run -p 8000:8000 --env-file .env gaia-agent
   

Hugging Face Spaces Deployment

GAIA can be deployed to Hugging Face Spaces for easy access and sharing.

Deployment Steps

1. Prepare your repository

   • Ensure all tests pass: python src/gaia/tests/real_world/run_all_tests.py
   • Update the README.md with correct Hugging Face metadata

2. Set up Hugging Face CLI

   pip install huggingface_hub
   huggingface-cli login
   

3. Deploy to Hugging Face Spaces

   python src/gaia/deployment/deploy_to_huggingface.py
   

   Alternatively, use the deployment script with direct token:

   python src/gaia/deployment/deploy_with_token.py --token your_hf_token
   

4. Configure environment variables in Hugging Face

   • Go to your Space settings
   • Add all required environment variables from your .env file
   • For secure variables like API keys, use the "Secret" option

5. Verify deployment

   • Visit your Hugging Face Space URL
   • Run the validation script in the space
   • Test basic functionality

Hugging Face-Specific Configuration

The Hugging Face deployment uses additional configuration in the README.md file:

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

Custom Server Deployment

For deploying GAIA on your own server:

Gunicorn Deployment (Linux/macOS)

1. Install Gunicorn

   pip install gunicorn
   

2. Create a systemd service file (for Linux)

   [Unit]
   Description=GAIA Agent
   After=network.target
   
   [Service]
   User=yourusername
   WorkingDirectory=/path/to/gaia
   Environment="PATH=/path/to/gaia/venv/bin"
   EnvironmentFile=/path/to/gaia/.env
   ExecStart=/path/to/gaia/venv/bin/gunicorn -w 4 -b 0.0.0.0:8000 app:app
   
   [Install]
   WantedBy=multi-user.target
   

3. Start the service

   sudo systemctl start gaia
   sudo systemctl enable gaia
   

Windows Deployment (with waitress)

1. Install waitress

   pip install waitress
   

2. Create a startup script

   # serve.py
   from waitress import serve
   import app
   serve(app.app, host='0.0.0.0', port=8000, threads=4)
   

3. Run the server

   python serve.py
   

4. Create a Windows service (optional)

   • Use NSSM (Non-Sucking Service Manager) to create a Windows service
   • Configure the service to run python serve.py in the correct directory

API-Only Deployment

For headless API-only deployments:

1. Install FastAPI and Uvicorn

   pip install fastapi uvicorn
   

2. Create an API server file

   # api.py
   from fastapi import FastAPI, HTTPException
   from src.gaia.agent import GAIAAgent
   
   app = FastAPI(title="GAIA API")
   agent = GAIAAgent()
   
   @app.post("/query")
   async def process_query(query: str):
       try:
           response = agent.process(query)
           return {"response": response}
       except Exception as e:
           raise HTTPException(status_code=500, detail=str(e))
   

3. Run the API server

   uvicorn api:app --host 0.0.0.0 --port 8000
   

Monitoring and Maintenance

Logging Configuration

Configure logging to monitor GAIA operation:

1. Set up log rotation

   # In your startup script
   import logging
   from logging.handlers import RotatingFileHandler
   
   handler = RotatingFileHandler(
       'logs/gaia.log', 
       maxBytes=10*1024*1024,  # 10MB
       backupCount=5
   )
   logging.getLogger('gaia').addHandler(handler)
   

2. Configure log levels based on environment

   if os.environ.get('GAIA_ENVIRONMENT') == 'production':
       logging.getLogger('gaia').setLevel(logging.WARNING)
   else:
       logging.getLogger('gaia').setLevel(logging.DEBUG)
   

Health Check Endpoint

Add a health check endpoint for monitoring:

@app.get("/health")
async def health_check():
    return {
        "status": "ok",
        "version": "2.0.0",
        "environment": os.environ.get('GAIA_ENVIRONMENT', 'unknown')
    }

Backup Procedures

For production deployments, implement regular backups:

1. Supabase data backup

   • Use the Supabase API to export data
   • Schedule regular backups using cron or similar tools

2. Configuration backup

   • Keep versioned backups of your environment files
   • Store sensitive credentials in a secure vault

Troubleshooting

Common Deployment Issues

1. Missing environment variables

   • Run python src/gaia/utils/validate_environment.py to check for missing variables
   • Check for typos in variable names

2. API key issues

   • Verify API keys by running python src/gaia/utils/validate_all_credentials.py
   • Check for rate limiting or access restrictions

3. Memory persistence problems

   • Verify Supabase connection with python src/gaia/tests/real_world/verify_supabase_data.py
   • Check Supabase table permissions and structure

4. Performance issues

   • Run python src/gaia/tests/real_world/performance/test_response_time.py to check performance
   • Consider increasing worker processes for high-load deployments

Getting Support

If you encounter issues not covered in this guide:

1. Check the GitHub issues for similar problems
2. Review the logs in results/logs/ for error messages
3. Run specific component tests to isolate the issue
4. Create a detailed issue report with environment information and steps to reproduce

Conclusion

This deployment guide covers the most common deployment scenarios for GAIA. By following these procedures, you can deploy GAIA in various environments while maintaining reliability and performance. Always validate your environment and run tests before deploying to production to ensure a smooth operation.