docs/deployment/deployment.md

# GAIA Agent Deployment Guide

This document provides instructions for deploying the GAIA agent in various environments, from local development to production settings.

## Prerequisites

Before deploying the GAIA agent, ensure you have:

1. Python 3.8 or higher installed
2. All required dependencies installed
3. API keys for any external services (OpenAI, Serper, Supabase, etc.)
4. Sufficient resources for your expected workload

## Local Deployment

### Installation

1. Clone the repository:
   ```bash
   git clone https://github.com/yourusername/gaia-agent.git
   cd gaia-agent
   ```

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. Create a `.env` file with your configuration:
   ```
   OPENAI_API_KEY=your-openai-api-key
   SERPER_API_KEY=your-serper-api-key
   SUPABASE_URL=https://your-project-url.supabase.co
   SUPABASE_KEY=your-supabase-api-key
   ```

5. Run the application:
   ```bash
   python app.py
   ```

### Testing

Before deploying to production, run the test suite to ensure everything is working correctly:

```bash
# Run all tests
python -m unittest discover tests

# Run benchmark tests
python -m tests.benchmark --output benchmark_results.json
```

## Deployment Options

### Hugging Face Spaces

The GAIA agent is designed to be easily deployed to Hugging Face Spaces:

1. Create a new Space on Hugging Face:
   - Go to https://huggingface.co/spaces
   - Click "Create new Space"
   - Select "Gradio" as the SDK
   - Choose a name for your Space

2. Configure your Space:
   - Add your API keys as secrets in the Space settings
   - Set the Python version to 3.8 or higher

3. Push your code to the Space:
   ```bash
   git remote add space https://huggingface.co/spaces/yourusername/your-space-name
   git push space main
   ```

4. Your agent will be automatically deployed and available at `https://huggingface.co/spaces/yourusername/your-space-name`

### Docker Deployment

For containerized deployment, you can use Docker:

1. Create a Dockerfile:
   ```dockerfile
   FROM python:3.9-slim

   WORKDIR /app

   COPY requirements.txt .
   RUN pip install --no-cache-dir -r requirements.txt

   COPY . .

   CMD ["python", "app.py"]
   ```

2. Build the Docker image:
   ```bash
   docker build -t gaia-agent .
   ```

3. Run the container:
   ```bash
   docker run -p 7860:7860 --env-file .env gaia-agent
   ```

### Cloud Deployment

#### AWS Elastic Beanstalk

1. Install the EB CLI:
   ```bash
   pip install awsebcli
   ```

2. Initialize your EB application:
   ```bash
   eb init -p python-3.8 gaia-agent
   ```

3. Create an environment:
   ```bash
   eb create gaia-agent-env
   ```

4. Configure environment variables:
   ```bash
   eb setenv OPENAI_API_KEY=your-openai-api-key SERPER_API_KEY=your-serper-api-key
   ```

5. Deploy your application:
   ```bash
   eb deploy
   ```

#### Google Cloud Run

1. Build and push your Docker image to Google Container Registry:
   ```bash
   gcloud builds submit --tag gcr.io/your-project-id/gaia-agent
   ```

2. Deploy to Cloud Run:
   ```bash
   gcloud run deploy gaia-agent \
     --image gcr.io/your-project-id/gaia-agent \
     --platform managed \
     --set-env-vars OPENAI_API_KEY=your-openai-api-key,SERPER_API_KEY=your-serper-api-key
   ```

## Scaling Considerations

### Memory Usage

The GAIA agent can be memory-intensive, especially when processing complex questions or using large language models. Consider the following:

- Monitor memory usage during benchmark testing
- Adjust `max_tokens` and other model parameters to control memory usage
- Consider using a memory cache for frequently asked questions

### API Rate Limits

Be aware of rate limits for external APIs:

- OpenAI has rate limits based on your subscription tier
- Serper and other search APIs typically have daily or monthly quotas
- Implement retry logic with exponential backoff for rate limit errors

### Cost Management

Using external APIs can incur costs:

- Monitor your API usage and costs
- Consider caching results to reduce API calls
- Use smaller or less expensive models for simpler tasks

## Production Best Practices

### Logging

Implement comprehensive logging:

```python
import logging

logging.basicConfig(
    level=logging.INFO,
    format='%(asctime)s - %(name)s - %(levelname)s - %(message)s',
    filename='gaia_agent.log'
)
```

### Monitoring

Set up monitoring for:

- API response times
- Error rates
- Memory and CPU usage
- Cost metrics

### Security

Protect sensitive information:

- Never hardcode API keys in your code
- Use environment variables or a secure secrets manager
- Implement proper authentication for your API endpoints
- Validate and sanitize all user inputs

### Backup and Recovery

Implement backup and recovery procedures:

- Regularly backup your Supabase database
- Create snapshots of your deployment environment
- Document recovery procedures

## Continuous Integration/Continuous Deployment (CI/CD)

Set up CI/CD pipelines to automate testing and deployment:

### GitHub Actions Example

Create a `.github/workflows/main.yml` file:

```yaml
name: CI/CD Pipeline

on:
  push:
    branches: [ main ]
  pull_request:
    branches: [ main ]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Set up Python
      uses: actions/setup-python@v2
      with:
        python-version: '3.9'
    - name: Install dependencies
      run: |
        python -m pip install --upgrade pip
        pip install -r requirements.txt
    - name: Run tests
      run: |
        python -m unittest discover tests

  deploy:
    needs: test
    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
    runs-on: ubuntu-latest
    steps:
    - uses: actions/checkout@v2
    - name: Deploy to Hugging Face Spaces
      uses: huggingface/huggingface-spaces-deploy-action@main
      with:
        space_id: ${{ secrets.SPACE_ID }}
        token: ${{ secrets.HF_TOKEN }}
```

## Troubleshooting

### Common Issues

1. **API Key Errors**:
   - Ensure all API keys are correctly set in your environment variables
   - Check for typos or trailing spaces in your API keys

2. **Memory Issues**:
   - Reduce the `max_tokens` parameter in your model configuration
   - Implement memory cleanup after processing each question

3. **Timeout Errors**:
   - Increase the timeout values in your configuration
   - Optimize your agent's workflow to reduce processing time

4. **Rate Limit Errors**:
   - Implement retry logic with exponential backoff
   - Consider upgrading your API subscription tier

### Getting Help

If you encounter issues not covered in this guide:

1. Check the project's GitHub issues for similar problems
2. Consult the documentation for the specific components (LangChain, LangGraph, etc.)
3. Reach out to the community for assistance

## Next Steps

For usage examples, see [Usage Examples](../usage/examples.md).

For configuration options, see [Configuration Guide](../development/configuration.md).