README_HF_SPACES.md

Hugging Face Spaces Deployment

This document explains the changes made to support Hugging Face Spaces deployment.

Changes Made

1. Root-level Entry Point (app.py)

• Created a root-level app.py file that serves as the entry point for Hugging Face Spaces
• This file imports the FastAPI app from the ai_med_extract package
• Includes multiple fallback strategies for robust error handling
• Added comprehensive logging for debugging

2. Package Structure

• Added __init__.py at the root level to make it a proper Python package
• The main application code remains in services/ai-service/src/ai_med_extract/

3. Requirements File

• Created a root-level requirements.txt with all necessary dependencies
• This is used by Hugging Face Spaces for dependency installation

4. Environment Configuration

• Set FAST_MODE=true and PRELOAD_SMALL_MODELS=false for Hugging Face Spaces
• This ensures faster startup and reduced memory usage

5. Dockerfile Updates

• Updated the Dockerfile to use app:app instead of ai_med_extract.app:app
• Added cache clearing configuration in .huggingface.yaml

How It Works

1. Hugging Face Spaces looks for app.py at the root level
2. The app.py file adds the source directory to the Python path
3. It tries multiple import strategies:
   • Primary: Import from ai_med_extract.app
   • Fallback: Direct import from nested structure
   • Emergency: Create minimal FastAPI app
4. The app is initialized with minimal preloading for faster startup

Fallback Strategies

The app includes three levels of fallback:

1. Primary: Normal import from ai_med_extract.app
2. Fallback: Direct import from nested structure if package import fails
3. Emergency: Minimal FastAPI app if all imports fail

Testing

To test the import structure locally:

python -c "import app; print('App imported successfully:', app.app.title)"

Deployment

The app should now work correctly when deployed to Hugging Face Spaces. The key changes ensure that:

• The module structure is properly recognized
• Dependencies are correctly installed
• The app starts with minimal resource usage
• Multiple fallback strategies provide robust error handling
• Comprehensive logging helps with debugging

Troubleshooting

If you still encounter issues:

1. Check the logs - The app now includes comprehensive logging
2. Verify file structure - Ensure all files are in the correct locations
3. Clear cache - The .huggingface.yaml includes cache clearing
4. Check dependencies - Ensure all requirements are properly specified