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](#prerequisites)
2. [Environment Configuration](#environment-configuration)
3. [Local Deployment](#local-deployment)
4. [Hugging Face Spaces Deployment](#hugging-face-spaces-deployment)
5. [Custom Server Deployment](#custom-server-deployment)
6. [API-Only Deployment](#api-only-deployment)
7. [Monitoring and Maintenance](#monitoring-and-maintenance)
8. [Troubleshooting](#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:

```bash
# 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:

```bash
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**
   ```bash
   git clone https://github.com/your-org/gaia.git
   cd gaia
   ```

2. **Create a virtual environment**
   ```bash
   python -m venv venv
   source venv/bin/activate  # On Windows: venv\Scripts\activate
   ```

3. **Install dependencies**
   ```bash
   pip install -r requirements.txt
   ```

4. **Set up environment variables**
   ```bash
   cp .env.example .env
   # Edit .env with your API keys and configuration
   ```

5. **Run the development server**
   ```bash
   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**
   ```bash
   docker build -t gaia-agent .
   ```

2. **Run the container**
   ```bash
   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**
   ```bash
   pip install huggingface_hub
   huggingface-cli login
   ```

3. **Deploy to Hugging Face Spaces**
   ```bash
   python src/gaia/deployment/deploy_to_huggingface.py
   ```

   Alternatively, use the deployment script with direct token:
   ```bash
   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:

```yaml
---
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**
   ```bash
   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**
   ```bash
   sudo systemctl start gaia
   sudo systemctl enable gaia
   ```

### Windows Deployment (with waitress)

1. **Install waitress**
   ```bash
   pip install waitress
   ```

2. **Create a startup script**
   ```python
   # serve.py
   from waitress import serve
   import app
   serve(app.app, host='0.0.0.0', port=8000, threads=4)
   ```

3. **Run the server**
   ```bash
   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**
   ```bash
   pip install fastapi uvicorn
   ```

2. **Create an API server file**
   ```python
   # 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**
   ```bash
   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**
   ```python
   # 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**
   ```python
   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:

```python
@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](https://github.com/your-org/gaia/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.