docs/deployment/local.md

# Local Deployment Guide for GAIA

This guide provides detailed instructions for deploying and running the GAIA agent on a local machine for development, testing, or personal use.

## Prerequisites

Before deploying GAIA locally, ensure you have the following:

1. **Python Environment**:
   - Python 3.9 or higher installed
   - pip (Python package manager)
   - (Optional) virtualenv or conda for environment isolation

2. **API Keys**:
   - OpenAI API key for language models
   - Additional API keys based on your configuration (Serper, Perplexity, etc.)

3. **System Requirements**:
   - At least 4GB of RAM
   - At least 2GB of free disk space
   - Internet connection for API calls

## Installation

### Step 1: Clone the Repository

```bash
# Clone the GAIA repository
git clone https://github.com/your-organization/gaia.git
cd gaia
```

### Step 2: Set Up Python Environment

```bash
# Option 1: Create a virtual environment with venv
python -m venv venv

# Activate the virtual environment
# On Windows
venv\Scripts\activate
# On macOS/Linux
source venv/bin/activate

# Option 2: Create a conda environment
conda create -n gaia python=3.9
conda activate gaia
```

### Step 3: Install Dependencies

```bash
# Install required packages
pip install -r requirements.txt

# For development, install development dependencies as well
pip install -r requirements-dev.txt
```

### Step 4: Configure Environment Variables

Create a `.env` file in the root directory of the project:

```bash
# Create .env file from template
cp .env.example .env
```

Edit the `.env` file with your API keys and configuration:

```
# API Keys
OPENAI_API_KEY=your-openai-api-key
SERPER_API_KEY=your-serper-api-key
PERPLEXITY_API_KEY=your-perplexity-api-key

# Optional: Supabase configuration for memory
SUPABASE_URL=your-supabase-url
SUPABASE_KEY=your-supabase-key

# Agent Configuration
MODEL_NAME=gpt-4o
VERBOSE=true

# UI Configuration
DEMO_MODE=true
SIMPLE_UI=false
```

## Basic Deployment

### Running the Web Interface

The simplest way to deploy GAIA locally is to run the web interface:

```bash
# Start the web interface
python app.py
```

This will start a Gradio web server that you can access at `http://localhost:7860` in your browser.

### Running in Demo Mode

For quick testing without setting up authentication:

```bash
# Enable demo mode
export DEMO_MODE=true  # On Windows: set DEMO_MODE=true
python app.py
```

### Running with a Simplified UI

For a more streamlined interface:

```bash
# Enable simplified UI
export SIMPLE_UI=true  # On Windows: set SIMPLE_UI=true
python app.py
```

## Command-Line Usage

GAIA can also be used directly from the command line:

```bash
# Run a single query
python -m src.gaia.cli "What is quantum computing?"

# Run in interactive mode
python -m src.gaia.cli --interactive

# Run with specific configuration
python -m src.gaia.cli --model "gpt-3.5-turbo" --verbose "What is climate change?"
```

## Advanced Configuration

### Custom Configuration File

For more advanced configuration, create a custom configuration file:

```bash
# Create a config.json file
cat > config.json << EOF
{
  "api": {
    "openai": {
      "api_key": "your-openai-key"
    },
    "serper": {
      "api_key": "your-serper-key"
    }
  },
  "models": {
    "default": "gpt-4o",
    "fallback": "gpt-3.5-turbo"
  },
  "tools": {
    "web_search": {
      "enabled": true,
      "default_provider": "serper"
    },
    "academic_search": {
      "enabled": true
    }
  },
  "memory": {
    "supabase": {
      "enabled": false
    }
  }
}
EOF

# Run with custom configuration
python app.py --config config.json
```

### Enabling Memory with Supabase

To use Supabase for persistent memory:

1. Create a Supabase project at [https://supabase.com](https://supabase.com)
2. Create the required tables using the provided SQL script:

```bash
# Copy the SQL script
cp docs/deployment/schema/supabase_tables.sql ./supabase_setup.sql

# Manually execute this in your Supabase SQL editor
# or use the Supabase CLI
```

3. Update your `.env` file with Supabase credentials:

```
SUPABASE_URL=your-supabase-url
SUPABASE_KEY=your-supabase-key
SUPABASE_MEMORY_ENABLED=true
```

## Running as a Service

### Using Systemd (Linux)

To run GAIA as a background service on Linux using systemd:

1. Create a systemd service file:

```bash
sudo nano /etc/systemd/system/gaia.service
```

2. Add the following content:

```
[Unit]
Description=GAIA Assessment Agent
After=network.target

[Service]
User=your-username
WorkingDirectory=/path/to/gaia
Environment="PATH=/path/to/gaia/venv/bin"
ExecStart=/path/to/gaia/venv/bin/python app.py
Restart=on-failure
RestartSec=5
StandardOutput=journal
StandardError=journal

[Install]
WantedBy=multi-user.target
```

3. Enable and start the service:

```bash
sudo systemctl enable gaia
sudo systemctl start gaia
```

4. Check service status:

```bash
sudo systemctl status gaia
```

### Using PM2 (Cross-platform)

For a more flexible service manager that works across platforms:

1. Install PM2:

```bash
npm install -g pm2
```

2. Create an ecosystem file:

```bash
cat > ecosystem.config.js << EOF
module.exports = {
  apps: [{
    name: "gaia",
    script: "app.py",
    interpreter: "./venv/bin/python",
    env: {
      OPENAI_API_KEY: "your-openai-key",
      SERPER_API_KEY: "your-serper-key",
      MODEL_NAME: "gpt-4o",
      VERBOSE: "true"
    }
  }]
}
EOF
```

3. Start with PM2:

```bash
pm2 start ecosystem.config.js
```

4. Monitor and manage:

```bash
pm2 status
pm2 logs gaia
pm2 restart gaia
```

## Docker Deployment

GAIA can also be deployed using Docker for better isolation and portability:

### Step 1: Create a Dockerfile

```bash
cat > Dockerfile << EOF
FROM python:3.9-slim

WORKDIR /app

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

COPY . .

EXPOSE 7860

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

### Step 2: Create a Docker Compose File

```bash
cat > docker-compose.yml << EOF
version: '3'

services:
  gaia:
    build: .
    ports:
      - "7860:7860"
    environment:
      - OPENAI_API_KEY=your-openai-key
      - SERPER_API_KEY=your-serper-key
      - PERPLEXITY_API_KEY=your-perplexity-key
      - MODEL_NAME=gpt-4o
      - VERBOSE=true
      - DEMO_MODE=true
    volumes:
      - ./logs:/app/logs
EOF
```

### Step 3: Build and Run with Docker Compose

```bash
# Build the Docker image
docker-compose build

# Run the container
docker-compose up -d

# Check logs
docker-compose logs -f
```

## Performance Optimization

### Memory Usage

To optimize memory usage:

```bash
# Limit result cache size
export MEMORY_RESULT_CACHE_SIZE=100

# Set a shorter TTL for cached results (in seconds)
export MEMORY_TTL=1800  # 30 minutes
```

### CPU Usage

For lower CPU usage:

```bash
# Disable verbose logging
export VERBOSE=false

# Use a lighter model
export MODEL_NAME=gpt-3.5-turbo

# Limit the number of tools enabled
export WEB_SEARCH_ENABLED=true
export ACADEMIC_SEARCH_ENABLED=false
```

## Troubleshooting

### Common Issues

1. **API Key Issues**:
   ```
   Error: Authentication error with OpenAI API
   ```
   Solution: Check that your API key is correct and has sufficient credits.

2. **Port Conflicts**:
   ```
   Error: Address already in use
   ```
   Solution: Change the port using an environment variable:
   ```bash
   export PORT=7861
   python app.py
   ```

3. **Missing Dependencies**:
   ```
   ImportError: No module named 'some_package'
   ```
   Solution: Ensure all dependencies are installed:
   ```bash
   pip install -r requirements.txt
   ```

4. **Memory Issues**:
   ```
   MemoryError or Process killed
   ```
   Solution: Limit memory usage as described in the Performance Optimization section.

### Logging

Enable detailed logging for troubleshooting:

```bash
# Enable debug logging
export LOG_LEVEL=DEBUG
python app.py
```

Log files are stored in the `logs/` directory by default.

### Diagnostic Commands

Use these commands to diagnose issues:

```bash
# Check environment variables
python -c "import os; print(os.environ.get('OPENAI_API_KEY', 'Not set'))"

# Test API connections
python -m src.gaia.utils.cli.verify_connections

# Test memory connections
python -m src.gaia.utils.cli.verify_memory
```

## Security Considerations

When deploying GAIA locally, consider these security practices:

1. **API Key Management**:
   - Store API keys in environment variables or a secure `.env` file
   - Never commit API keys to version control
   - Consider using a secret management solution for production

2. **Network Security**:
   - By default, the web interface only listens on localhost
   - To expose to other machines, use `--host 0.0.0.0` with caution
   - Consider using a reverse proxy with authentication for wider access

3. **Data Privacy**:
   - Be aware of what data is being sent to external APIs
   - Consider privacy implications when using memory features
   - Regularly clear cached data for sensitive applications

## Upgrading

To upgrade your GAIA installation:

```bash
# Pull the latest changes
git pull

# Update dependencies
pip install -r requirements.txt

# Run migration scripts if available
python -m src.gaia.utils.cli.run_migrations

# Restart the service
# If using systemd:
sudo systemctl restart gaia
# If using PM2:
pm2 restart gaia
```

## Conclusion

You now have GAIA running locally on your machine. For more advanced deployment options, check out the [Hugging Face Deployment Guide](huggingface.md) or explore the [API documentation](../api/agent.md) to integrate GAIA into your own applications.

For any issues or questions, please refer to the [troubleshooting section](#troubleshooting) or create an issue on the project's GitHub repository.