# 🚀 Deployment Guide for Hugging Face Spaces

## Quick Deploy to Hugging Face Spaces

### Option 1: Direct Upload
1. **Create a new Space** on [Hugging Face Spaces](https://huggingface.co/spaces)
2. **Choose "Gradio" as the SDK**
3. **Upload these files** from the `deep_research` folder:
   - `app.py`
   - `deep_research.py`
   - `requirements.txt`
   - `README.md`
   - `metadata.json`
   - All the agent files (`*_agent.py`, `research_manager.py`)

### Option 2: Git Repository
1. **Create a new repository** or fork this one
2. **Copy the `deep_research` folder contents** to the root of your repository
3. **Create a new Space** and connect it to your repository

## Environment Configuration

In your Hugging Face Space settings, add these secrets:

### Required
- `OPENAI_API_KEY`: Your OpenAI API key

### Optional (for email functionality)
- `SENDGRID_API_KEY`: Your SendGrid API key
- `SENDGRID_FROM_EMAIL`: Your verified sender email

## Files Structure for Deployment

```
your-space/
├── app.py                 # Main entry point for HF Spaces
├── deep_research.py       # Core application logic
├── requirements.txt       # Python dependencies
├── README.md             # Space documentation
├── metadata.json         # HF Spaces configuration
├── research_manager.py   # Research orchestration
├── clarifier_agent.py    # Clarification agent
├── planner_agent.py      # Planning agent
├── search_agent.py       # Search agent
├── writer_agent.py       # Writing agent
├── evaluator_agent.py    # Quality evaluation agent
├── email_agent.py        # Email delivery agent
├── .gitignore           # Git ignore rules
└── env_example.txt      # Environment variables template
```

## Testing Your Deployment

1. **Local Testing**: Run `python app.py` to test locally
2. **Check Dependencies**: Ensure all imports work correctly
3. **Environment Variables**: Test with your actual API keys
4. **Gradio Interface**: Verify the UI loads and functions work

## Common Issues & Solutions

### Import Errors
- Make sure all agent files are in the same directory
- Verify `openai-agents` package is installed correctly

### API Key Issues
- Check that environment variables are set correctly in HF Spaces
- Ensure OpenAI API key has sufficient credits

### Email Functionality
- Email features are optional and will be disabled if SendGrid isn't configured
- Verify your SendGrid sender email is verified

## Performance Tips

- The app uses OpenAI's Agents framework which can take 1-2 minutes for complex research
- Consider upgrading to a paid HF Spaces plan for better performance
- Monitor usage to avoid API rate limits

## Support

If you encounter issues:
1. Check the Space logs in Hugging Face
2. Verify all environment variables are set
3. Test locally first to isolate the issue
4. Check OpenAI API status and quotas