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:

pip install huggingface_hub

Login to Hugging Face:

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:

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:

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:

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:

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:

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:

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

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

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

Or perform the complete deployment process in one command:

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:

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:

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
• Hugging Face CLI Reference