Text_Agent/HANDOFF.md

# HANDOFF.md — Aktueller Projektstand

**Letzte Aktualisierung:** 2026-05-12  
**Session:** Vollständige llama.cpp-Pipeline + Writer-Umbenennung

---

## Aktueller Stand: Dual-Backend-System (Ollama + llama.cpp)

Alle P1–P3-Features implementiert. Zusätzlich vollständige llama.cpp-Pipeline für Reasoning-Modelle (Qwopus/Qwen3), die Ollama-Timeout-Probleme bei Thinking-Modellen umgeht.

Naming-Convention: `ollama-<agent>.ts` (Ollama-Backend) / `llama-<agent>.ts` (llama.cpp-Backend, ★ BEVORZUGT).

---

## Zuletzt erledigt (2026-05-12)

### Vollständige llama.cpp-Pipeline implementiert
- **`llama-claim-extractor.ts`** — Pi-Tool: `extract_claims_llama`
- **`llama-verifier.ts`** — Pi-Tool: `verify_claim_llama` ★ BEVORZUGT
- **`llama-verify-article.ts`** — Pi-Tool: `verify_article_llama`
- **`llama-writer.ts`** — Pi-Tool: `write_article_llama` ★ BEVORZUGT
- Alle llama.cpp-Agenten: Schema im System-Prompt, `/no_think`-Prefix, `reasoning_content`-Fallback, Retry 3×/15s

### Umbenennungen
- `writer.ts` → `ollama-writer.ts`
- `verify-article.ts` → `ollama-verify-article.ts`

### Deployment
- Alle Symlinks in `~/.pi/agent/extensions/fact-checker/` aktualisiert
- `package.json`: 9 Extensions (4 Ollama + 4 llama.cpp + logic-editor)
- AGENTS.md, README.md, HANDOFF.md, TODO.md, WORKLOG.md aktualisiert
- Git: 47 Dateien committed (Branch: master)

---

## Zuletzt erledigt (2026-04-17)

### Standard-Modell für Claim-Extraktion auf `qwen3.5:9b` gesetzt
- **ollama-claim-extractor.ts** — `DEFAULT_MODEL` von `qwen3.5:27b` auf `qwen3.5:9b` geändert
- **Präzision:** 8/9 Claims vs. 9/9 (27B) — minimaler Verlust
- **Geschwindigkeit:** 2× schneller (96 s vs. 205 s bei Apollo-11-Text)
- **VRAM:** 6.6 GB statt 17 GB — vollständig in VRAM, kein CPU-Offloading
- **Kommentar** in Header aktualisiert: Empfehlung qwen3.5:9b (6.6 GB, 1 GPU, fast gleiche Präzision wie 27B, 2× schneller)
- **TypeBox-Parameter:** Beschreibung ergänzt "Empfohlene Alternative: qwen3.5:27b für maximale Präzision"

---

## Zuletzt erledigt (P3-Session — 2026-04-16)

### `lib/cache.ts` — neu (globaler Perplexity-Claim-Cache)
- SHA256 des normalisierten Claim-Texts als Cache-Key
- Ablageort: `~/.pi/agent/cache/perplexity/<sha256>.json`, TTL 7 Tage
- `getCached<T>(claimText)` / `setCached<T>(claimText, data)` — fehlertolerant
- `pruneCache()` — abgelaufene Einträge löschen
- `cacheStats()` — {total, expired, sizeBytes}
- Integriert in `verify-article.ts`: prüft globalen Cache **vor** Job-Cache und Perplexity-Aufruf
- `--no-cache` CLI-Flag in `verify-article.ts` um Cache zu umgehen

### `tests/corpus/` — 10 Testfälle
Themen: Inflation DE, EZB-Zins, Mondlandung, Bevölkerung DE, Erneuerbare Energien,
Bitcoin ATH, COVID-Impfstoff, Bundeshaushalt, Klimaabkommen, Weltbevölkerung.
- **Fehler-Fälle** (erwartetes `contradicted`): 001, 002, 004, 005, 006, 008
- **Negativtests** (nur korrekte Fakten, kein False-Positive erwartet): 003, 007, 009, 010

### `tests/run_corpus.sh` — Test-Runner
- Führt alle 10 Fälle durch `verify-article --json`, vergleicht mit `expected.json`
- Berechnet Precision + Recall für `contradicted`-Urteile, TP/FP/FN/TN
- Selektiver Aufruf: `bash tests/run_corpus.sh case_001 case_002`
- Reports in `tests/results/<timestamp>/`, Summary als `summary.txt`

---

## Früher erledigt (P1/P2-Sessions)

### `lib/jobs.ts`
Persistente Job-Verzeichnisse `~/.pi/agent/jobs/<datum>_<slug>/` — Resume-Logik für abgebrochene Pipelines.

### `lib/logger.ts`
File-Logger `~/.pi/agent/logs/`, `--verbose`-Flag in allen CLI-Tools.

### Chunking + Retry (`ollama-claim-extractor.ts`)
Texte >4000 Zeichen → Chunks ≤3000 (Absatzgrenzen), 3 Retries à 15s bei `fetch failed`.

---

## Bekannte Einschränkungen

| Problem | Ursache | Status |
|---------|---------|--------|
| Chunking-Laufzeit ~4 min/Chunk | qwen3.5:27b auf 1 GPU | erwartet, kein Bug |
| Erste Ollama-Anfrage nach Inaktivität ~200s | Modell-Ladezeit | OLLAMA_KEEP_ALIVE noch nicht gesetzt |
| `fetch failed` Ollama + Thinking-Modell + format: | qwen3.5:27b verbraucht Kontext-Budget im Thinking-Modus | **GELÖST**: llama-writer.ts verwenden |
| `fetch failed` bei manuellem Ollama-Neustart | Verbindung unterbrochen | Retry-Logik fängt das ab (3×15s) |
| Nur 1 GPU genutzt (GPU 2 idle) | Ollama kennt nur GPU 1 | CUDA_VISIBLE_DEVICES noch nicht gesetzt |

---

## Offene Punkte

### Nutzer-Aktion erforderlich: OLLAMA_KEEP_ALIVE + Dual-GPU

```bash
sudo systemctl edit ollama
# Einfügen unter [Service]:
# Environment="OLLAMA_KEEP_ALIVE=-1"
# Environment="CUDA_VISIBLE_DEVICES=1,2"
# Environment="OLLAMA_NUM_PARALLEL=2"
sudo systemctl daemon-reload && sudo systemctl restart ollama
```
Effekt: Modell bleibt geladen (keine 200s Wartezeit), beide RTX 3090s genutzt (48 GB VRAM → größere Modelle möglich).

---

## Wichtige Pfade

| Was | Pfad |
|-----|------|
| Projekt | `~/Pi_Agent_Projekts/text_agent/` |
| Pi Extensions | `~/.pi/agent/extensions/fact-checker/` |
| Lib-Symlink | `~/.pi/agent/extensions/lib` → `~/Pi_Agent_Projekts/text_agent/lib` |
| Standalone research-web | `~/.pi/agent/extensions/research-web.ts` |
| Job-Verzeichnisse | `~/.pi/agent/jobs/<datum>_<slug>/` |
| Log-Dateien | `~/.pi/agent/logs/<timestamp>.log` |
| Perplexity-Cache | `~/.pi/agent/cache/perplexity/<sha256>.json` |
| Testkorpus | `~/Pi_Agent_Projekts/text_agent/tests/corpus/` |

---

## GPU-Setup

```
GPU 0  T600       4 GB  →  Display
GPU 1  RTX 3090  24 GB  →  Ollama (nur diese, CUDA_VISIBLE_DEVICES noch nicht gesetzt)
GPU 2  RTX 3090  24 GB  →  idle (ungenutzt!)
```

Modelle aktuell auf GPU 1:
- `qwen3.5:27b` — 22 GB, für Extraktion + Verifikation + Schreiben
- `deepseek-r1:32b` — 19 GB, für Argumentationsanalyse (logic-editor)

Mit `CUDA_VISIBLE_DEVICES=1,2` hätte Ollama 48 GB → könnte 70B-Modelle laden.

---

## Umgebungsvariablen

| Variable | Zweck | Status |
|----------|-------|--------|
| `PERPLEXITY_API_KEY` | Perplexity Sonar API | gesetzt ✓ |
| `OPENROUTER_API_KEY` | Cloud-Modelle via OpenRouter | gesetzt ✓ |
| `OLLAMA_KEEP_ALIVE` | Modell im Speicher halten | **nicht gesetzt** |
| `CUDA_VISIBLE_DEVICES` | Welche GPUs Ollama nutzt | **nicht gesetzt** (nur GPU 1) |
| `OLLAMA_NUM_PARALLEL` | Parallele Anfragen | **nicht gesetzt** |
| `ROUTER_FORCE_LOCAL=1` | Immer lokales Modell | optional |
| `ROUTER_FORCE_CLOUD=1` | Immer OpenRouter | optional |

---

## Getestete Workflows

```bash
# llama.cpp-Pipeline ★ BEVORZUGT (kein Ollama-Timeout bei Thinking-Modellen)
npx tsx agenten/llama-claim-extractor.ts "Textinhalt..."
npx tsx agenten/llama-verifier.ts "Die EZB hat den Leitzins im Juni 2024 gesenkt."
npx tsx agenten/llama-verify-article.ts --job-id mein-artikel "$(cat artikel.txt)"
npx tsx agenten/llama-writer.ts --from-job mein-artikel --style blog

# Ollama-Pipeline (Fallback oder explizit gewünscht)
npx tsx agenten/ollama-claim-extractor.ts --verbose "$(cat ~/Dokumente/Umerziehung.md)"
npx tsx agenten/ollama-verify-article.ts --job-id mein-artikel --verbose "$(cat artikel.txt)"
npx tsx agenten/ollama-writer.ts --from-job mein-artikel --style blog

# Argumentationsanalyse
npx tsx agenten/logic-editor.ts --only-fallacies "Argumentativer Text..."

# Testkorpus ausführen
bash tests/run_corpus.sh                      # alle 10 Fälle
bash tests/run_corpus.sh --mode deep          # mit sonar-pro
bash tests/run_corpus.sh case_001 case_002    # selektiv
```