DEPLOYMENT_GUIDE.md

# Deployment Guide - Hugging Face Spaces

This guide walks you through deploying the UI Regression Testing System to Hugging Face Spaces.

## Prerequisites

- Hugging Face account (https://huggingface.co)
- GitHub account (for repository)
- Git installed locally

## Step 1: Create a GitHub Repository

1. Go to https://github.com/new
2. Create a new repository named `ui-regression-testing`
3. Clone it locally:
   ```bash
   git clone https://github.com/YOUR_USERNAME/ui-regression-testing.git
   cd ui-regression-testing
   ```

## Step 2: Prepare Your Files

Copy all project files to your repository:

```
ui-regression-testing/
├── app.py                          # Main Gradio app
├── requirements.txt                # Python dependencies
├── README.md                       # Documentation
├── .gitignore                      # Git ignore file
├── state_schema.py                 # Workflow state
├── report_generator.py             # Report generation
├── screenshot_annotator.py         # Screenshot annotation
├── image_comparison_enhanced.py    # Image comparison
├── workflow.py                     # LangGraph workflow
├── agents/
│   ├── __init__.py
│   ├── agent_0_super_agent.py
│   ├── agent_1_design_inspector.py
│   ├── agent_2_website_inspector.py
│   └── agent_3_difference_analyzer.py
└── utils/
    ├── __init__.py
    ├── figma_client.py
    └── website_capturer.py
```

## Step 3: Create .gitignore

Create a `.gitignore` file:

```
# Python
__pycache__/
*.py[cod]
*$py.class
*.so
.Python
env/
venv/
ENV/

# IDE
.vscode/
.idea/
*.swp
*.swo

# Environment
.env
.env.local

# Data
data/
reports/
*.png
*.jpg

# OS
.DS_Store
Thumbs.db
```

## Step 4: Update requirements.txt

Ensure your `requirements.txt` includes:

```
# Core Dependencies
python-dotenv>=1.0.0
requests>=2.31.0

# LangGraph & LangChain
langgraph>=0.0.50
langchain>=0.1.0
langchain-core>=0.1.0

# Web Automation
playwright>=1.40.0

# Data Processing
numpy>=1.24.3
pandas>=2.1.3
pillow>=11.0.0

# Async Support
aiohttp>=3.9.1

# Utilities
python-dateutil>=2.8.2
scipy>=1.11.0

# Gradio
gradio>=4.0.0

# Hugging Face
huggingface-hub>=0.19.0
transformers>=4.30.0
torch>=2.0.0

# Image processing
opencv-python>=4.8.0
scikit-image>=0.21.0
```

## Step 5: Push to GitHub

```bash
git add .
git commit -m "Initial commit: UI Regression Testing System"
git push origin main
```

## Step 6: Create HF Space

1. Go to https://huggingface.co/spaces
2. Click "Create new Space"
3. Fill in:
   - **Space name**: `ui-regression-testing`
   - **License**: `mit`
   - **Space SDK**: `Docker` (for better control)
   - **Space storage**: `Small` (minimum)
   - **Visibility**: `Public` (or `Private`)
4. Click "Create Space"

## Step 7: Configure Space

### Option A: Using Docker (Recommended)

1. In your Space settings, select "Docker" as SDK
2. Create a `Dockerfile` in your repository:

```dockerfile
FROM python:3.11-slim

WORKDIR /app

# Install system dependencies
RUN apt-get update && apt-get install -y \
    wget \
    gnupg \
    libglib2.0-0 \
    libsm6 \
    libxext6 \
    libxrender-dev \
    && rm -rf /var/lib/apt/lists/*

# Install Playwright browsers
RUN pip install --no-cache-dir playwright && \
    playwright install

# Copy requirements and install Python dependencies
COPY requirements.txt .
RUN pip install --no-cache-dir -r requirements.txt

# Copy application files
COPY . .

# Expose port
EXPOSE 7860

# Run the app
CMD ["python", "app.py"]
```

### Option B: Using Gradio SDK (Simpler)

1. In your Space settings, select "Gradio" as SDK
2. The space will automatically use `app.py` as entry point

## Step 8: Connect GitHub Repository

1. In Space settings, go to "Repository"
2. Connect your GitHub repository
3. Enable "Persistent Storage" (optional, for saving results)

## Step 9: Configure Environment Variables

In your Space settings, add these secrets:

```
FIGMA_ACCESS_TOKEN=your_token_here
HUGGINGFACE_TOKEN=your_token_here
```

Note: Users will provide these through the UI, so these are optional defaults.

## Step 10: Deploy

1. Push your code to GitHub
2. The Space will automatically rebuild
3. Monitor the build logs in the Space settings
4. Once deployed, your Space will be live at:
   ```
   https://huggingface.co/spaces/YOUR_USERNAME/ui-regression-testing
   ```

## Step 11: Test Your Deployment

1. Open your Space URL
2. Fill in test credentials
3. Click "Start Regression Test"
4. Verify all features work correctly

## Monitoring & Maintenance

### View Logs
- Go to Space settings → "Logs"
- Check for errors or warnings

### Update Code
- Push changes to GitHub
- Space will automatically rebuild

### Monitor Performance
- Track execution time
- Monitor memory usage
- Check error rates

## Troubleshooting

### Build Fails
- Check Docker build logs
- Verify all dependencies in requirements.txt
- Ensure Python version compatibility

### App Crashes
- Check Space logs
- Verify all imports are correct
- Test locally before deploying

### Slow Performance
- Optimize image processing
- Cache results
- Consider upgrading Space resources

### Memory Issues
- Reduce image resolution
- Implement garbage collection
- Use persistent storage

## Optimization Tips

### 1. Reduce Image Size
```python
# In image_comparison_enhanced.py
img = img.resize((img.width // 2, img.height // 2))
```

### 2. Cache Results
```python
from functools import lru_cache

@lru_cache(maxsize=10)
def expensive_operation(key):
    # Your code here
    pass
```

### 3. Use Persistent Storage
```python
import os
storage_dir = "/data"  # HF Spaces persistent storage
os.makedirs(storage_dir, exist_ok=True)
```

## Advanced Configuration

### Custom Domain
1. Go to Space settings → "Custom Domain"
2. Add your domain (requires DNS configuration)

### Webhooks
1. Set up GitHub webhooks for automatic deploys
2. Configure in repository settings

### Secrets Management
1. Use HF Spaces secrets for sensitive data
2. Never commit credentials to GitHub

## Performance Benchmarks

Expected performance on HF Spaces:

| Task | Time |
|------|------|
| Figma capture | 5-10s |
| Website capture | 10-15s |
| Difference analysis | 5-10s |
| Report generation | 2-5s |
| **Total** | **30-50s** |

## Scaling Considerations

For higher traffic:

1. **Upgrade Space**: Use larger instance
2. **Add Caching**: Cache comparison results
3. **Optimize Images**: Reduce resolution
4. **Async Processing**: Use background jobs
5. **Load Balancing**: Use multiple instances

## Support & Resources

- [HF Spaces Documentation](https://huggingface.co/docs/hub/spaces)
- [Gradio Documentation](https://www.gradio.app/)
- [Docker Documentation](https://docs.docker.com/)
- [GitHub Actions](https://github.com/features/actions)

## Next Steps

1. Deploy to HF Spaces
2. Share with team
3. Gather feedback
4. Iterate and improve
5. Monitor performance
6. Scale as needed

---

**Happy deploying! 🚀**