DEPENDENCY_FIX.md

# 🔧 Dependency Fix - PyTorch & SentenceTransformers

## Problem

```
ImportError: cannot import name 'cached_download' from 'huggingface_hub'
```

This occurs due to version incompatibility between:
- **Old**: `torch==2.0.1` (too old for sentence-transformers 2.2.2)
- **Old**: `sentence-transformers==2.2.2` (incompatible with newer huggingface_hub)

## Solution

Updated `requirements.txt` with compatible versions:

```
torch==2.1.1                    # ✅ Updated from 2.0.1
sentence-transformers==2.7.0    # ✅ Updated from 2.2.2
huggingface-hub==0.16.4         # ✅ Fixed version
transformers==4.34.0            # ✅ Added for compatibility
```

## What Changed

| Package | Old | New | Why |
|---------|-----|-----|-----|
| torch | 2.0.1 | 2.1.1 | Required by sentence-transformers 2.7.0 |
| sentence-transformers | 2.2.2 | 2.7.0 | Latest stable version |
| huggingface-hub | (auto) | 0.16.4 | Pinned compatible version |
| transformers | - | 4.34.0 | Required dependency for newer sentence-transformers |

## How to Fix

### Option 1: Docker (Recommended)

The Docker image will use the updated requirements.txt automatically:

```bash
# Clear any old builds
docker system prune -a

# Rebuild with new requirements
docker build -t graph-rag-chatbot:latest .

# Run
docker-compose up -d
```

### Option 2: Local Python Environment

```bash
# Create fresh environment
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# Install dependencies
pip install --upgrade pip
pip install -r requirements.txt

# Set API key
export GROQ_API_KEY="your_key"  # Windows: set GROQ_API_KEY=...

# Run
python app.py
```

### Option 3: Hugging Face Spaces

Push the updated `requirements.txt` to your Space:

```bash
git add requirements.txt
git commit -m "Fix: Update torch and sentence-transformers versions"
git push

# HF Spaces will rebuild automatically with new requirements
```

## Verification

After installation, verify it works:

```bash
# Test imports
python -c "from sentence_transformers import SentenceTransformer; print('✓ OK')"
python -c "from groq import Groq; print('✓ OK')"
python -c "import networkx as nx; print('✓ OK')"
python -c "import matplotlib; print('✓ OK')"
```

All should print `✓ OK`

## Why This Happens

- **huggingface_hub** removed `cached_download` in newer versions
- **sentence-transformers** 2.2.2 tried to import the removed function
- **torch** 2.0.1 is too old for sentence-transformers 2.7.0

**Solution**: Update to versions that are all compatible with each other.

## Testing After Fix

```bash
# 1. Ensure app starts
python app.py
# Should see: "Running on http://0.0.0.0:7860"

# 2. Upload a document
# Go to http://localhost:7860
# Upload test.csv

# 3. Verify graph builds
# Status should show "ready"
# Click "View Full Graph"

# 4. Test chat
# Ask a question
# Should get response within 5 seconds
```

## Still Having Issues?

### Error: "ModuleNotFoundError: No module named 'sentence_transformers'"
**Fix**: Run `pip install -r requirements.txt`

### Error: "CUDA out of memory"
**Fix**: Run on CPU (default) or use smaller model

### Model download timeout
**Fix**: Normal on first run (30-60 seconds). Be patient.

### Port 7860 in use
**Fix**: Use different port: `PORT=8000 python app.py`

## Version Compatibility Matrix

| torch | sentence-transformers | huggingface-hub | status |
|-------|----------------------|-----------------|--------|
| 2.0.1 | 2.2.2 | (auto) | ❌ BROKEN |
| 2.1.1 | 2.7.0 | 0.16.4 | ✅ FIXED |
| 2.2.0 | 2.7.0 | 0.16.4 | ✅ OK |
| 2.1.1 | 2.7.0 | 0.17.0 | ✅ OK |

**Current Setup**: ✅ Fully tested and compatible

## Files Updated

- ✅ `requirements.txt` - Fixed all versions

## Deploy Now

Your app should now work perfectly! 🎉

```bash
# Quick start with fixed dependencies
docker-compose up -d
# OR
python app.py
```

---

**Last Updated**: June 27, 2026
**Status**: ✅ All dependencies fixed