DEPLOYMENT.md

# 🚀 Deployment Guide for Agentic Browser

## Hugging Face Spaces Deployment

### Prerequisites
1. Hugging Face account
2. Git and Git LFS installed
3. The fixed codebase (this repository)

### Step-by-Step Deployment

#### 1. Create a New Space
1. Go to [Hugging Face Spaces](https://huggingface.co/spaces)
2. Click "Create new Space"
3. Fill in the details:
   - **Owner**: Your username/organization
   - **Space name**: `agentic-browser` (or your preferred name)
   - **License**: MIT
   - **SDK**: Streamlit
   - **Hardware**: CPU basic (free tier) or upgrade for better performance

#### 2. Clone Your Space Repository
```bash
git clone https://huggingface.co/spaces/YOUR_USERNAME/agentic-browser
cd agentic-browser
```

#### 3. Copy Files
Copy all files from this directory to your cloned space repository:
```bash
# Copy all files except .git directory
cp -r /path/to/this/directory/* /path/to/your/space/
cp -r /path/to/this/directory/.* /path/to/your/space/ 2>/dev/null || true
```

#### 4. Push to Hugging Face
```bash
git add .
git commit -m "Initial deployment of Agentic Browser"
git push origin main
```

### Files Structure
```
agentic-browser/
├── app.py                 # Main entry point for HF Spaces
├── requirements.txt       # Python dependencies
├── README.md             # Space description
├── packages.txt          # System packages
├── .env.example          # Environment variables example
├── src/
│   ├── streamlit_app.py  # Main Streamlit application
│   ├── models/
│   │   └── model_manager.py  # Model management
│   └── config/
│       └── model_config.py   # Model configurations
└── config/
    └── __init__.py
```

### Important Notes

#### Fixed Issues:
✅ **Module Import Errors**: Fixed all `ModuleNotFoundError` issues by:
- Proper path management in `app.py`
- Fallback imports in `model_manager.py`
- Robust error handling for missing dependencies

✅ **Dependencies**: Simplified `requirements.txt` for HF Spaces compatibility:
- Removed heavy dependencies (auto-gptq, bitsandbytes) that may not work in HF Spaces
- Kept essential ML libraries (torch, transformers, streamlit)
- Added fallback model configurations

✅ **Streamlit Compatibility**: Updated deprecated functions:
- Changed `st.experimental_rerun()` to `st.rerun()`
- Fixed session state handling

#### Model Configuration:
- **TinyLlama**: Lightweight model for quick responses
- **DialoGPT-small**: Alternative to larger models for HF Spaces compatibility
- Models are loaded on-demand to optimize memory usage

#### Performance Optimization:
- CPU-first approach for HF Spaces free tier
- Automatic fallback to CPU if CUDA is not available
- Graceful error handling for model loading failures

### Troubleshooting

#### Common Issues:

1. **Model Loading Errors**:
   - The app includes fallback configurations
   - Models will automatically use CPU if GPU is not available
   - Error messages are displayed in the UI

2. **Memory Issues**:
   - Use smaller models (TinyLlama recommended for free tier)
   - Consider upgrading to paid HF Spaces tier for larger models

3. **Import Errors**:
   - All import paths have been fixed with fallback mechanisms
   - Missing dependencies are handled gracefully

### Testing Locally

Before deploying, test locally:
```bash
cd agentic-browser
pip install -r requirements.txt
streamlit run app.py
```

### Monitoring

After deployment:
1. Check the Space logs for any runtime errors
2. Monitor memory usage in the HF Spaces dashboard
3. Test model loading functionality through the UI

### Upgrading

To upgrade your deployment:
1. Make changes to your local copy
2. Test locally
3. Push updates:
```bash
git add .
git commit -m "Update: description of changes"
git push origin main
```

The Space will automatically rebuild and redeploy with your changes.

## Alternative Deployment Options

### Local Development
```bash
pip install -r requirements.txt
streamlit run app.py
```

### Docker Deployment
```bash
docker build -t agentic-browser .
docker run -p 8501:8501 agentic-browser
```

### Cloud Platforms
- **Streamlit Cloud**: Upload to GitHub and connect
- **Railway**: Deploy directly from GitHub
- **Heroku**: Use the included Dockerfile
- **Google Cloud Run**: Container-based deployment