DEPLOYMENT.md

Deployment Guide for Hugging Face Spaces

This guide will help you deploy NyayaSpashti to Hugging Face Spaces.

Prerequisites

1. A Hugging Face account (sign up here)
2. Google Gemini API key (get one here)
3. Pre-built indexes (the storage/ folder with Chroma and BM25 indexes)

Step-by-Step Deployment

1. Prepare Your Repository

Make sure your project has:

• ✅ app.py in the root directory
• ✅ requirements.txt with all dependencies
• ✅ README.md (this will be displayed on your Space)
• ✅ rag/ folder with all RAG modules
• ✅ data/pdfs/ folder with your PDF files (optional, if you want to rebuild indexes)
• ✅ storage/ folder with pre-built indexes (recommended)

2. Create a New Space

1. Go to Hugging Face Spaces
2. Click "Create new Space"
3. Fill in the details:
   • Space name: nyaya-spashti (or your preferred name)
   • SDK: Select "Streamlit"
   • Visibility: Choose Public or Private
4. Click "Create Space"

3. Upload Your Files

You can upload files in two ways:

Option A: Using Git (Recommended)

1. Clone your Space repository:

   git clone https://huggingface.co/spaces/YOUR_USERNAME/nyaya-spashti
   cd nyaya-spashti
   

2. Copy all your project files:

   # Copy all files from your local project
   cp -r /path/to/NyayaSpashti/* .
   

3. Commit and push:

   git add .
   git commit -m "Initial deployment"
   git push
   

Option B: Using Web Interface

1. Go to your Space page
2. Click "Files and versions" tab
3. Click "Add file" → "Upload files"
4. Upload all necessary files and folders

4. Set Up Secrets (API Keys)

1. Go to your Space settings (click the gear icon)
2. Navigate to "Variables and secrets" tab
3. Click "New secret"
4. Add the following secrets:
   • Name: GOOGLE_API_KEY
   • Value: Your Google Gemini API key
   • (Optional) Name: GEMINI_MODEL_NAME
   • (Optional) Value: gemini-2.5-flash-lite (or your preferred model)

5. Verify Deployment

1. Go to your Space page
2. The app should automatically build and deploy
3. Wait for the build to complete (check the "Logs" tab if there are issues)
4. Once deployed, test the application

Important Notes

Storage Considerations

• Pre-built indexes: Upload your storage/ folder with pre-built Chroma and BM25 indexes
• File size limits: Hugging Face Spaces has file size limits. If your indexes are too large:
  • Consider using Git LFS for large files
  • Or rebuild indexes on first run (slower but works)

Environment Variables

The app automatically reads environment variables set in HF Spaces secrets:

• GOOGLE_API_KEY - Required
• GEMINI_MODEL_NAME - Optional (defaults to gemini-2.5-flash-lite)

Paths

The app uses relative paths that work in HF Spaces:

• data/pdfs/ - PDF files directory
• storage/ - Index storage directory

Building Indexes on HF Spaces

If you need to rebuild indexes on HF Spaces:

1. Make sure data/pdfs/ folder contains all PDF files
2. The app will automatically load existing indexes if available
3. Note: Building indexes on HF Spaces may take time and consume resources

Troubleshooting

Build Fails

• Check the "Logs" tab for error messages
• Verify all dependencies are in requirements.txt
• Ensure app.py is in the root directory

API Key Issues

• Verify the secret is named exactly GOOGLE_API_KEY
• Check that the API key is valid and has proper permissions
• Ensure the secret is set in Space settings, not in code

Index Loading Errors

• Verify storage/ folder is uploaded correctly
• Check that Chroma and BM25 indexes exist
• If indexes are missing, you may need to rebuild them

Memory Issues

• HF Spaces have memory limits
• If you encounter OOM errors, consider:
  • Using smaller batch sizes
  • Optimizing model loading
  • Using a Space with more resources (upgrade if needed)

Updating Your Space

To update your deployed Space:

1. Make changes to your local files
2. Commit and push to your Space repository:

   git add .
   git commit -m "Update description"
   git push
   

3. HF Spaces will automatically rebuild and redeploy

Support

For issues or questions:

• Check HF Spaces documentation
• Review the app logs in the "Logs" tab
• Check GitHub issues (if applicable)