crossword-app/backend-py/README-local-setup.md

# Local Development Setup

## Quick Start

```bash
# 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:
```bash
# 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:
```bash
# 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

```bash
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:
```bash
# 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

```bash
# 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.