Local Development Setup
Quick Start
# Install all dependencies (same as production)
pip install -r requirements.txt
Python Version Support
- Recommended: Python 3.10-3.12
- Minimum: Python 3.10 (matches Docker)
Installation Troubleshooting
If you get PyTorch installation errors:
# Install PyTorch first with CPU support
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu
# Then install remaining dependencies
pip install -r requirements-local.txt --no-deps
pip install fastapi uvicorn[standard] python-dotenv python-multipart
For M1/M2 Macs:
# Use conda for better compatibility
conda install pytorch::pytorch torchvision torchaudio -c pytorch
pip install -r requirements-local.txt --no-deps
pip install sentence-transformers faiss-cpu transformers huggingface-hub
Running Locally
cd crossword-app/backend-py
python app.py
The server will start on http://localhost:7860
Features Available
Features Available:
- ✅ AI word generation via vector search
- ✅ 30K+ vocabulary from sentence-transformers
- ✅ Static word fallback
- ✅ All crossword features
- ✅ Same as production environment
Environment Variables
Create a .env file:
# Optional - defaults to sentence-transformers/all-mpnet-base-v2
EMBEDDING_MODEL=sentence-transformers/all-MiniLM-L6-v2
# Optional - similarity threshold for AI words
WORD_SIMILARITY_THRESHOLD=0.65
# Optional - logging level
LOG_LEVEL=INFO
Testing
# Test basic components
python test_local.py
# Test with pytest
pytest
Docker vs Local Development
Both use the same requirements.txt with modern, compatible versions that work across Python 3.9-3.12 and different platforms.