docs/deployment/HUGGING_FACE_DEPLOYMENT.md

# Hugging Face Deployment Guide for GAIA Agent

This guide provides detailed instructions for deploying the GAIA agent to Hugging Face Spaces. It covers cleaning the existing space, preparing the deployment package, uploading to Hugging Face, and verifying the deployment.

## Prerequisites

Before you begin, make sure you have the following:

1. A Hugging Face account
2. The Hugging Face CLI installed and configured
3. Access to the GAIA project repository
4. Python 3.8+ installed

## Installation of Required Tools

Install the Hugging Face CLI tool:

```bash
pip install huggingface_hub
```

Login to Hugging Face:

```bash
huggingface-cli login
```

## Deployment Process

### Step 1: Prepare the Deployment Package

The `prepare_hf_deployment.py` script helps you create a clean deployment package with only the necessary files. You can run it with different options depending on your needs.

#### List Files That Would Be Included

To see which files would be included in the deployment package without actually creating it:

```bash
python src/gaia/scripts/prepare_hf_deployment.py --list-only
```

#### Create a Deployment Package

To create a deployment package (ZIP file) with all essential files:

```bash
python src/gaia/scripts/prepare_hf_deployment.py --create-package
```

By default, this will create a package in a `deployment` directory. You can customize the output directory and package name:

```bash
python src/gaia/scripts/prepare_hf_deployment.py --create-package --output-dir custom_dir --package-name custom_package.zip
```

### Step 2: Clean the Existing Hugging Face Space

Before uploading new files, you can clean the existing space to remove old files:

```bash
python src/gaia/scripts/prepare_hf_deployment.py --clean-remote
```

This will prompt for confirmation before deleting files. Use the `--force` flag to skip confirmation:

```bash
python src/gaia/scripts/prepare_hf_deployment.py --clean-remote --force
```

### Step 3: Upload to Hugging Face

To upload the prepared package to Hugging Face:

```bash
python src/gaia/scripts/prepare_hf_deployment.py --upload
```

You need to create a package first. You can combine the steps:

```bash
python src/gaia/scripts/prepare_hf_deployment.py --create-package --upload
```

Or perform the complete deployment process in one command:

```bash
python src/gaia/scripts/prepare_hf_deployment.py --create-package --clean-remote --upload
```

### Step 4: Verify the Deployment

After uploading, verify that the deployment was successful:

1. Visit your Hugging Face Space at `https://huggingface.co/spaces/JoachimVC/Final_Assignment_GAIAAgent`
2. Check that the app loads correctly and all essential functionality works
3. Test the main features to ensure they're working as expected

## Customizing File Selection

The script uses default inclusion and exclusion patterns, but you can customize them.

### Using Custom Pattern Files

Create a file with patterns of files to include:

```
# include_patterns.txt
src/gaia/agent/**/*.py
src/gaia/config/**/*.py
src/gaia/tools/**/*.py
```

Create a file with patterns of files to exclude:

```
# exclude_patterns.txt
**/__pycache__/**
**/*.log
```

Then use these files with the script:

```bash
python src/gaia/scripts/prepare_hf_deployment.py --create-package --include-file include_patterns.txt --exclude-file exclude_patterns.txt
```

## Deployment to a Different Space

By default, the script deploys to the `JoachimVC/Final_Assignment_GAIAAgent` space. To deploy to a different space:

```bash
python src/gaia/scripts/prepare_hf_deployment.py --create-package --upload --space-id your-username/your-space-name
```

## Troubleshooting

### Authorization Issues

If you encounter authorization issues:

1. Ensure you're logged in with `huggingface-cli login`
2. Verify you have write access to the Space
3. Check your token hasn't expired (re-login if necessary)

### File Size Limitations

If your deployment package is too large:

1. Review the included files with `--list-only`
2. Add more exclusion patterns for large files
3. Consider splitting the deployment into multiple steps

### API Errors

If you encounter API errors:

1. Check your internet connection
2. Verify the Hugging Face API is operational
3. Retry the operation after a few minutes

## Best Practices

1. **Version your deployments**: Add version tags or timestamps to your packages
2. **Test locally first**: Ensure your app works locally before deploying
3. **Keep secrets out**: Never include API keys or sensitive information in the deployment
4. **Use the .huggingnorefile**: This helps exclude unnecessary files
5. **Regular cleanup**: Periodically clean old files from your Space

## Additional Resources

- [Hugging Face Spaces Documentation](https://huggingface.co/docs/hub/spaces)
- [Hugging Face CLI Reference](https://huggingface.co/docs/huggingface_hub/guides/cli)