README_HF_SPACES.md

Hugging Face Spaces Deployment

This guide explains how to deploy the Knowledge Graph Extraction app to Hugging Face Spaces using the provided Dockerfile.

Deployment Steps

1. Create a New Space

1. Go to Hugging Face Spaces
2. Click "Create new Space"
3. Choose a name for your space
4. Select "Docker" as the SDK
5. Choose "Public" or "Private" visibility

2. Upload Files

Upload all the project files to your space, including:

• Dockerfile
• app_streamlit.py
• requirements.txt
• src/ directory with all modules
• config/ directory
• .env.example (optional)

3. Environment Variables

In your Hugging Face Space settings, add the following environment variable:

• OPENROUTER_API_KEY: Your OpenRouter API key (optional, users can also input it in the app)

4. Docker Configuration

The Dockerfile is already optimized for HF Spaces with:

• Port 7860 (HF Spaces standard)
• Proper system dependencies for PDF processing
• Streamlit configured for headless deployment
• Health checks enabled

5. App Features

Once deployed, users can:

• Upload PDF, TXT, DOCX, or JSON documents
• Enter their OpenRouter API key in the sidebar
• Extract knowledge graphs using LLM processing
• Visualize graphs with various layout options
• Filter entities by type and importance
• Export graphs in JSON, GraphML, or GEXF formats

Technical Details

Dependencies

The Dockerfile installs:

• System packages: poppler-utils, libpoppler-cpp-dev for PDF processing
• Python packages: All from requirements.txt

File Limits

• Default Streamlit file upload limit: 200MB
• Recommended per-file limit in config: 10MB

Models Used

• Primary: qwen/qwen3-32b (free model via OpenRouter)
• The app uses cost-effective models to minimize API costs

Usage Notes

• Users need their own OpenRouter API key
• Processing time depends on document size and complexity
• The app supports batch processing of multiple documents
• Temporary files are automatically cleaned up after processing

Troubleshooting

If deployment fails:

1. Check that all files are uploaded correctly
2. Verify the Dockerfile syntax
3. Check HF Spaces logs for specific error messages
4. Ensure requirements.txt contains all necessary dependencies