COMPATIBILITY.md

Compatibility Notes

Critical Version Constraints

Python

• Python 3.9-3.11: HF Spaces typically supports these versions
• Avoid Python 3.12+ for maximum compatibility

PyTorch

• PyTorch 2.1.x: Latest stable with good HF ecosystem support
• CPU-only builds for ZeroGPU deployments

Transformers

• Transformers 4.35.x: Latest features with stability
• Ensures compatibility with latest HF models

Gradio

• Gradio 4.x: Current major version with mobile optimizations
• Required for mobile-responsive interface

HF Spaces Specific Considerations

ZeroGPU Environment

• Limited GPU memory: CPU-optimized versions are used
• All models run on CPU
• Use faiss-cpu instead of faiss-gpu

Storage Limits

• Limited persistent storage: Efficient caching is crucial
• Session data must be optimized for minimal storage usage
• Implement aggressive cleanup policies

Network Restrictions

• May have restrictions on external API calls
• All LLM calls must use Hugging Face Inference API
• Avoid external HTTP requests in production

Model Selection

For ZeroGPU

• Embedding model: sentence-transformers/all-MiniLM-L6-v2 (384d, fast)
• Primary LLM: Use HF Inference API endpoint calls
• Avoid local model loading for large models

Memory Optimization

• Limit concurrent requests
• Use streaming responses
• Implement response compression

Performance Considerations

Cache Strategy

• In-memory caching for active sessions
• Aggressive cache eviction (LRU)
• TTL-based expiration

Mobile Optimization

• Reduced max tokens for mobile (800 vs 2000)
• Shorter timeout (15s vs 30s)
• Lazy loading of UI components

Dependencies Compatibility Matrix

Package	Version Range	Notes
Python	3.9-3.11	HF Spaces supported versions
PyTorch	2.1.x	CPU version
Transformers	4.35.x	Latest stable
Gradio	4.x	Mobile support
FAISS	CPU-only	No GPU support
NumPy	1.24.x	Compatibility layer

Known Issues & Workarounds

Issue: FAISS GPU Not Available

Solution: Use faiss-cpu in requirements.txt

Issue: Model Loading Memory

Solution: Use HF Inference API instead of local loading

Issue: Session Storage Limits

Solution: Implement data compression and TTL-based cleanup

Issue: Concurrent Request Limits

Solution: Implement request queue with max_workers limit

Testing Recommendations

1. Test on ZeroGPU environment before production
2. Verify memory usage stays under 512MB
3. Test mobile responsiveness
4. Validate cache efficiency (target: >60% hit rate)