docs/DEPENDENCIES.md

# Dependency Management Guide

> **Note**: As of V3.0, VoiceForge uses [Poetry](https://python-poetry.org/) for dependency management. Legacy `requirements.txt` is maintained for compatibility but Poetry is recommended.

## 📦 Critical Constraints

### Numpy & PyTorch Lock
**Status**: ⚠️ **Strictly Pinned**
- **Numpy**: `1.26.4` (Last stable 1.x version)
- **Torch**: `2.3.1` (Compatible with Numpy 1.x)
- **Reason**: `pyannote.audio==3.1.1` requires `numpy<2.0.0`. Upgrading to Numpy 2.0+ will break speaker diarization until `pyannote` is updated.

### Audio Libraries
- **Pyannote Audio**: `3.1.1` (Strict pin)
- **Transformers**: `4.42.4` (Pinned for stable MarianMT translation)
- **MeloTTS**: `0.1.2` (Requires C++ build tools only if installing from source)

---

## 🛠️ Managing Dependencies with Poetry

### 1. Installation
```bash
pip install poetry
```

### 2. Adding a Package
```bash
# Add a production dependency
poetry add package_name

# Add a development dependency
poetry add --group dev package_name
```

### 3. Updating Dependencies
```bash
# Update all packages (respecting constraints)
poetry update

# Update a specific package
poetry update package_name
```

### 4. Running the App
```bash
poetry run uvicorn app.main:app --reload
```

---

## 🐳 Docker Note
The `Dockerfile` uses Poetry to install dependencies.
- It generates a clean environment based on `poetry.lock`.
- This ensures that the Docker build matches your local environment exactly (if you use Poetry locally).

## ⚠️ Troubleshooting

### "Failed to build melotts"
- **Cause**: Missing C++ Build Tools (common on Windows).
- **Solution**: 
  - **Option A (Easy)**: Ignore it. VoiceForge automatically falls back to EdgeTTS if MeloTTS is missing.
  - **Option B (Fix)**: Install "Desktop development with C++" workload via Visual Studio Installer.
  - **Option C (Docker)**: Use Docker, which runs Linux and handles the build automatically.

### "SolverProblemError"
- **Cause**: Conflicting version constraints.
- **Solution**: Check `pyproject.toml` for incompatible pins. Ensure you aren't trying to force `numpy>=2.0` while `pyannote.audio` is installed.