DEPLOYMENT.md

🚀 Hugging Face Spaces Deployment Guide

This guide will help you deploy the Inclusive World Curriculum Assistant to Hugging Face Spaces using Gradio.

📋 Prerequisites

1. Hugging Face Account: Create an account at huggingface.co
2. Hugging Face Token: Get your access token from your profile settings
3. Curriculum PDFs: Prepare your curriculum PDF files

🎯 Step-by-Step Deployment

1. Create a New Space

1. Go to huggingface.co/spaces
2. Click "Create new Space"
3. Choose the following settings:
   • Owner: Your username
   • Space name: inclusive-world-curriculum-assistant (or your preferred name)
   • Space SDK: Gradio
   • Space hardware: CPU (or GPU if you have access)
   • License: Choose appropriate license
   • Visibility: Public or Private

2. Upload Files

Upload the following files to your Space:

Required Files:

• app.py - Main Gradio application
• config.py - Configuration settings
• utils.py - Utility functions
• requirements.txt - Python dependencies
• README.md - Documentation
• app_config.toml - Spaces configuration

Optional Files:

• Slides/ directory with your curriculum PDFs
• .gitignore - Git ignore rules

3. Configure Environment Variables

In your Space settings, add these environment variables:

HF_HUB_ENABLE_HF_TRANSFER=1
TRANSFORMERS_CACHE=/tmp/transformers_cache
HF_HOME=/tmp/hf_home

4. Set Up Curriculum Files

1. Create a Slides/ directory in your Space
2. Upload your curriculum PDF files to this directory
3. Ensure PDFs contain extractable text (not just images)

5. Deploy and Test

1. Automatic Deployment: Spaces will automatically build and deploy your app
2. Monitor Build: Check the build logs for any errors
3. Test the App: Visit your Space URL and test the functionality

🔧 Configuration Options

Model Selection

The app is configured to use microsoft/DialoGPT-medium for optimal performance on Spaces. You can change this in config.py:

MODEL_CONFIG = {
    "model_name": "microsoft/DialoGPT-medium",  # Change this
    # ... other settings
}

Gradio Interface Settings

Update app_config.toml for Gradio-specific settings:

[gradio]
title = "Inclusive World Curriculum Assistant"
description = "AI-powered assistant that answers questions about curriculum and shows relevant slide pages"
theme = "soft"
share = false

Hardware Requirements

Update app_config.toml based on your Space's hardware:

[hardware]
cpu = "2"        # Number of CPU cores
memory = "8GB"   # RAM requirement
disk = "10GB"    # Disk space

🐛 Troubleshooting

Common Issues

Build Fails

• Check that all required files are uploaded
• Verify requirements.txt has correct package versions
• Ensure Python version compatibility

Model Loading Issues

• Check if the model name is accessible
• Verify internet connectivity
• Try a smaller model if memory is limited

PDF Processing Errors

• Ensure PDFs are not corrupted
• Check that PDFs contain text (not just images)
• Verify file permissions

Page Matching Issues

• Ensure PDFs have proper page structure
• Check that text extraction is working correctly
• Verify metadata is being stored properly

Performance Issues

• Use CPU instead of GPU if available
• Reduce model size in config
• Optimize chunk sizes for vector database

Debug Steps

1. Check Build Logs: Look for error messages in the build process
2. Test Locally: Run the app locally first to identify issues
3. Simplify: Remove complex features temporarily to isolate problems
4. Monitor Resources: Check CPU and memory usage in Space settings

📊 Monitoring and Maintenance

Performance Monitoring

• Monitor response times for Q&A queries
• Check memory usage during model loading
• Track vector database performance
• Monitor page matching accuracy

Regular Maintenance

• Update dependencies periodically
• Monitor model performance and accuracy
• Backup curriculum documents
• Review and update configuration settings

🔒 Security Considerations

Access Control

• Use private Spaces for sensitive curriculum content
• Implement authentication if needed
• Monitor access logs

Data Privacy

• Ensure curriculum content doesn't contain sensitive information
• Use appropriate licensing for educational content
• Follow data protection regulations

📈 Scaling Considerations

For High Usage

• Consider using GPU Spaces for better performance
• Implement caching for frequently asked questions
• Use larger models for better response quality
• Optimize vector database settings

Cost Optimization

• Use CPU Spaces when possible
• Implement request rate limiting
• Monitor resource usage
• Choose appropriate model sizes

🎓 Educational Deployment Tips

For Educational Institutions

1. Content Management: Organize curriculum by weeks/topics
2. Access Control: Use private Spaces for institutional content
3. Customization: Adapt prompts for specific curriculum needs
4. Integration: Consider integrating with existing LMS systems

For Individual Instructors

1. Content Preparation: Ensure PDFs are well-structured with clear page content
2. Testing: Test with various question types
3. Documentation: Provide clear usage instructions for students
4. Feedback: Collect student feedback for improvements

📞 Support

For deployment issues:

1. Check the Hugging Face Spaces documentation
2. Review build logs for specific error messages
3. Test with minimal configuration first
4. Consider using the Hugging Face community forums

🆕 New Features in This Version

Page-Level Matching

• Shows exact slide pages that match your questions
• Provides content previews from specific pages
• Ranks pages by relevance to your query

Enhanced RAG Pipeline

• Page metadata tracking throughout the process
• Improved relevance scoring
• Better content organization

Gradio Interface

• Modern, responsive web interface
• Better user experience
• Optimized for educational use

---

Happy Deploying! 🚀