# 🚀 FinVoice Hugging Face Deployment Guide

This folder contains the deployment-ready version of FinVoice for Hugging Face Spaces.

## 📁 Deployment Structure

```
deploy/
├── app.py                 # Main Gradio interface (unified)
├── fastapi1_multilingual.py  # Multilingual voice service
├── fastapi2_finance.py       # Finance RAG service
├── requirements.txt          # Python dependencies
├── config.yaml              # HF Spaces configuration
├── start_services.py        # Service startup script
├── .env.template            # Environment variables template
├── README.md               # This file
└── DEPLOYMENT_README.md    # Deployment instructions
```

## 🔧 Pre-Deployment Setup

### 1. API Keys Required
Create a `.env` file from `.env.template` and add:
- `GEMINI_API_KEY`: Google Gemini API key
- `GROQ_API_KEY`: Groq API key
- `HF_TOKEN`: Hugging Face token (for model access)

### 2. Model Access
Ensure your HF token has access to:
- `ai4bharat/indicconformer_hi`
- `ai4bharat/indictrans2-en-indic-1B`
- `ai4bharat/indictrans2-indic-en-1B`

## 🌐 Hugging Face Spaces Deployment

### Method 1: Direct Upload
1. Create a new Hugging Face Space
2. Choose "Gradio" as the SDK
3. Upload all files from this `deploy/` folder
4. Add your API keys in the Space settings (Secrets)

### Method 2: Git Repository
1. Initialize git in this deploy folder:
   ```bash
   git init
   git add .
   git commit -m "Initial deployment"
   ```
2. Add your HF Space as remote:
   ```bash
   git remote add origin https://huggingface.co/spaces/YOUR_USERNAME/finvoice
   git push -u origin main
   ```

## 🔑 Environment Variables in HF Spaces

Add these as "Repository secrets" in your Space settings:
- `GEMINI_API_KEY`
- `GROQ_API_KEY`
- `HF_TOKEN`
- `OPENAI_API_KEY` (optional)
- `ALPHA_VANTAGE_API_KEY` (optional)

## 🏗️ Architecture

The deployment uses a **unified architecture**:
- **Gradio Frontend**: Single interface with tabs for all features
- **Background Services**: FastAPI services run as background threads
- **Automatic Startup**: Services auto-start when the Space loads

## 🔄 Updating Code

To update the deployment with changes from your main code:

1. **Copy updated files**:
   ```bash
   # From your main project directory
   copy fastapi2\fastapi1_multilingual.py deploy\
   copy fastapi2\fastapi2_finance.py deploy\
   ```

2. **Update requirements if needed**:
   - Check if new dependencies were added
   - Update `requirements.txt`

3. **Push changes** (if using git method):
   ```bash
   git add .
   git commit -m "Update with latest changes"
   git push
   ```

## 🧪 Local Testing

Test the deployment locally before pushing:

```bash
cd deploy
pip install -r requirements.txt
python app.py
```

The interface will be available at `http://localhost:7860`

## 📊 Features Included

✅ **Voice Processing**: 11+ Indian languages  
✅ **Text Queries**: Multilingual financial Q&A  
✅ **Portfolio Optimization**: Modern Portfolio Theory  
✅ **RAG System**: Financial document retrieval  
✅ **Real-time Data**: Market data integration  
✅ **Risk Analysis**: Comprehensive risk metrics  

## 🔍 Troubleshooting

### Common Issues:
1. **Model Loading Errors**: Ensure HF_TOKEN has model access
2. **API Errors**: Verify all API keys are set correctly
3. **Memory Issues**: Some models require higher RAM (upgrade Space tier)
4. **Timeout Issues**: Increase `startup_duration_timeout` in config.yaml

### Debug Mode:
Set `show_error=True` in `app.py` for detailed error messages.

## 📞 Support

For deployment issues:
1. Check the Space logs for error messages
2. Verify all environment variables are set
3. Ensure model access permissions
4. Test API endpoints individually

---

**Ready to deploy? 🚀**  
Upload this entire folder to your Hugging Face Space and watch FinVoice come to life!