mindnet/docs/03_Technical_References/PROD_PYTHON_CACHE_FIX.md

# Fix: Python-Modul-Cache-Problem in Prod

**Datum**: 2026-01-12  
**Version**: v4.5.10  
**Status**: 🔴 Kritisch

## Problem

Code in `app/models/dto.py` ist korrekt (enthält `explicit:callout`), aber Prod verwendet trotzdem eine alte Version.

**Symptom**:
```
ERROR: 1 validation error for EdgeDTO
provenance
  Input should be 'explicit', 'rule', 'smart' or 'structure' 
  [type=literal_error, input_value='explicit:callout', input_type=str]
```

## Ursache

**Python-Modul-Cache**: Python speichert kompilierte `.pyc` Dateien in `__pycache__` Verzeichnissen. Wenn der Code aktualisiert wird, aber der Service nicht neu gestartet wird, lädt Python die alte gecachte Version.

## Sofortmaßnahmen

### Schritt 1: Python-Cache leeren

```bash
# In Prod-System
cd ~/mindnet

# Finde und lösche alle __pycache__ Verzeichnisse
find . -type d -name __pycache__ -exec rm -r {} + 2>/dev/null || true

# Finde und lösche alle .pyc Dateien
find . -name "*.pyc" -delete

# Speziell für dto.py
rm -rf app/models/__pycache__
rm -rf app/__pycache__
rm -rf __pycache__
```

### Schritt 2: Verifikation des Codes

```bash
# Prüfe, ob der Code korrekt ist
grep -A 10 "provenance.*Literal" app/models/dto.py | grep "explicit:callout"
```

**Erwartete Ausgabe**: Sollte `explicit:callout` enthalten

### Schritt 3: Service neu starten

**Option A: FastAPI/uvicorn direkt**:
```bash
# Service stoppen (Ctrl+C oder kill)
# Dann neu starten
source .venv/bin/activate
uvicorn app.main:app --host 0.0.0.0 --port 8001 --reload
```

**Option B: Systemd-Service**:
```bash
sudo systemctl restart mindnet-prod
# oder
sudo systemctl restart mindnet
```

**Option C: Docker-Container**:
```bash
docker-compose restart mindnet
# oder
docker restart mindnet-container
```

### Schritt 4: Verifikation zur Laufzeit

**Test-Script ausführen** (wenn verfügbar):
```bash
python3 scripts/verify_dto_import.py
```

**Erwartete Ausgabe**:
```
✅ EdgeDTO unterstützt 'explicit:callout'
✅ 'explicit:callout' ist in der Literal-Liste enthalten
✅ EdgeDTO mit 'explicit:callout' erfolgreich erstellt!
```

**Oder manuell testen**:
```python
python3 -c "
from app.models.dto import EdgeDTO
test = EdgeDTO(
    id='test', kind='test', source='test', target='test',
    weight=1.0, provenance='explicit:callout'
)
print('✅ EdgeDTO mit explicit:callout funktioniert!')
"
```

## Code-Fix (Fallback-Mechanismus)

Ein Fallback-Mechanismus wurde in `retriever.py` implementiert:
- Wenn `EdgeDTO` mit `explicit:callout` fehlschlägt, wird automatisch `explicit` als Fallback verwendet
- Dies verhindert, dass der gesamte Retrieval-Prozess fehlschlägt
- **WICHTIG**: Dies ist nur eine temporäre Lösung - der Cache muss trotzdem geleert werden!

## Verifikation nach Fix

1. **Test-Query ausführen**:
   ```bash
   curl -X POST http://localhost:8001/api/chat \
     -H "Content-Type: application/json" \
     -d '{"message": "Was für einen Status hat das Projekt mindnet?"}'
   ```

2. **Log prüfen**:
   - ✅ Keine `validation error for EdgeDTO` mehr
   - ✅ Keine `⚠️ [EDGE-DTO] Provenance 'explicit:callout' nicht unterstützt` Warnungen
   - ✅ `✨ [SUCCESS] Stream 'facts_stream' lieferte X Treffer.`
   - ✅ Ergebnisse werden zurückgegeben

## Warum passiert das?

1. **Code wurde aktualisiert**, aber Service läuft noch mit alter Version im Speicher
2. **Python lädt Module nur einmal** - nach dem ersten Import wird die gecachte Version verwendet
3. **__pycache__ Verzeichnisse** enthalten kompilierte Bytecode-Versionen der alten Dateien

## Prävention

- **Immer Service neu starten** nach Code-Änderungen
- **Cache regelmäßig leeren** bei Deployment
- **Verwende `--reload` Flag** bei uvicorn für automatisches Neuladen (nur für Dev!)