Text_Agent/BEDIENUNGSANLEITUNG.md

# Bedienungsanleitung — Pi Text-Agent

Fact-Checking, Artikelschreiben und Argumentationsanalyse — lokal und kostengünstig.

---

## Was kann das System?

| Aufgabe | Pi-Tool (★ bevorzugt) | Kosten |
|---------|----------------------|--------|
| Behauptungen aus einem Text extrahieren | `extract_claims_llama` ★ | kostenlos (lokal) |
| Einzelne Behauptung auf Wahrheit prüfen | `verify_claim_llama` ★ | ~$0.005–0.015 (Perplexity) |
| Ganzen Artikel automatisch fact-checken | `verify_article_llama` ★ | ~$0.05–0.15 pro Artikel |
| Fact-gechecken Artikel schreiben | `write_article_llama` ★ | kostenlos (lokal) |
| Text auf Fehlschlüsse analysieren | `analyze_logic_llama` ★ | kostenlos (lokal) |
| Im Web recherchieren | `research_web` | ~$0.001–0.005 |

★ = llama.cpp-Backend (bevorzugt). Ollama-Varianten (ohne `_llama`) sind ebenfalls verfügbar.

---

## Voraussetzungen

```bash
# llama.cpp-Server läuft? (★ bevorzugtes Backend)
curl -s http://localhost:8000/v1/models | python3 -m json.tool

# Ollama läuft? (für Fallback + research_web)
curl -s http://localhost:11434/api/tags | python3 -m json.tool | grep name

# API-Keys gesetzt?
echo $PERPLEXITY_API_KEY    # muss gesetzt sein für Fact-Checking
echo $OPENROUTER_API_KEY    # optional, nur für --cloud (Ollama-Writer)

# llama.cpp-Server starten (falls nicht aktiv):
llama-server --model Qwopus3.6-35B-A3B-v1-Q4_K_M.gguf \
             --host 0.0.0.0 --port 8000 -c 32768

# Ollama-Modelle verfügbar?
ollama list | grep -E "qwen3.5:27b|deepseek-r1:32b"
```

---

## Verwendung in Pi

Einfach Pi öffnen und in natürlicher Sprache beschreiben was du willst. Pi ruft die richtigen Tools automatisch auf.

### Typische Pi-Eingaben

```
Prüfe diesen Artikel auf Fakten: [Text einfügen]

Extrahiere alle Behauptungen aus diesem Text und zeige mir nur die prüfbaren: [Text]

Verifiziere diese Behauptung: "Die EZB hat den Leitzins im Juni 2024 auf 4,25% gesenkt."

Schreibe einen Blog-Artikel auf Basis dieses verifizierten Reports: [Report einfügen]

Analysiere diesen Text auf logische Fehlschlüsse: [Text]

Recherchiere: Wie hoch ist der aktuelle Wohnungsbestand in Deutschland?
```

### Hinweise für Pi-Nutzung

- Pi verarbeitet Claims **nacheinander** — nicht erschrecken wenn es etwas dauert
- Fortschritt wird in Pi direkt angezeigt
- Lange Texte werden automatisch in Abschnitte aufgeteilt (kein manuelles Kürzen nötig)
- Bei `verify_article_llama`: Pi zeigt nach der Verifikation welche Claims bestätigt/widerlegt wurden

---

## Verwendung via CLI

### 1. Behauptungen extrahieren

```bash
cd ~/Pi_Agent_Projekts/text_agent

# ★ llama.cpp-Version (empfohlen)
npx tsx agenten/llama-claim-extractor.ts "Die Erde hat 8 Milliarden Einwohner. \
  Die Inflationsrate lag 2024 bei 3,2 Prozent."

# Aus Datei
npx tsx agenten/llama-claim-extractor.ts --file ~/Dokumente/artikel.txt

# Nur prüfbare Claims
npx tsx agenten/llama-claim-extractor.ts --only-checkable "$(cat artikel.txt)"

# JSON-Ausgabe (für Weiterverarbeitung)
npx tsx agenten/llama-claim-extractor.ts --json "$(cat artikel.txt)" > claims.json

# Mit Übersetzung (englischer Text → deutsche Claim-Anzeige)
npx tsx agenten/llama-claim-extractor.ts --translate-to de --file english_article.txt

# Ollama-Fallback (falls llama.cpp nicht verfügbar)
npx tsx agenten/ollama-claim-extractor.ts --verbose "$(cat ~/Dokumente/langer-essay.txt)"
```

**Beispielausgabe:**
```
## Claim-Extraktion: 4 Behauptungen gefunden

**✓ Prüfbar (2):**
`c001` ✓ [STATISTIK] Die Erde hat 8 Milliarden Einwohner.
       Entitäten: Erde | Zeit: 2024 | Zitat nötig: ja

`c002` ✓ [STATISTIK] Die Inflationsrate lag 2024 in Deutschland bei 3,2 Prozent.
       Entitäten: Deutschland | Zeit: 2024 | Zitat nötig: ja
```

---

### 2. Einzelne Behauptung prüfen

```bash
# ★ llama.cpp-Version (empfohlen)
npx tsx agenten/llama-verifier.ts "Die EZB hat den Leitzins im Juni 2024 gesenkt."

# Genauere Suche (sonar-pro)
npx tsx agenten/llama-verifier.ts --mode deep "Die Inflationsrate betrug 2024 in Deutschland 3,2%."

# Urteilstext auf Englisch
npx tsx agenten/llama-verifier.ts --user-language en "Claim in any language..."

# JSON-Ausgabe
npx tsx agenten/llama-verifier.ts --json "Behauptung..." > result.json

# Ollama-Fallback
npx tsx agenten/ollama-verifier.ts --verbose "Behauptung..."
```

**Beispielausgabe:**
```
## Verifikation
**Behauptung:** "Die Inflationsrate betrug 2024 in Deutschland 3,2%."

**✗ WIDERLEGT** (Konfidenz: hoch)

**Begründung:** Die Inflationsrate in Deutschland betrug 2024 durchschnittlich 2,2%,
nicht 3,2%. Destatis bestätigt diesen Wert.

**Gegenbelege:** Statistisches Bundesamt weist 2,2% für 2024 aus.

**Quellen:**
[1] ✓ [Destatis — Inflationsrate 2024](https://www.destatis.de/...)
```

---

### 3. Ganzen Artikel fact-checken

#### Mit Job-Speicher (empfohlen für lange Texte)

Der Job-Speicher sichert jeden Schritt. Bei Unterbrechung (Server-Neustart, Stromausfall)
einfach denselben Befehl nochmals aufrufen — bereits erledigte Schritte werden übersprungen,
und vor allem: bereits bezahlte Perplexity-Anfragen werden **nicht nochmals abgerechnet**.

```bash
# ★ llama.cpp-Version (empfohlen)
npx tsx agenten/llama-verify-article.ts --job-id mein-artikel "$(cat artikel.txt)"

# Bei Unterbrechung: identisch nochmals aufrufen
npx tsx agenten/llama-verify-article.ts --job-id mein-artikel "$(cat artikel.txt)"
# → Claims aus Cache geladen — Extraktion übersprungen.
# → 3/12 Perplexity-Ergebnisse aus Job-Cache geladen.
# → 9 neue Perplexity-Anfragen...

# Mit ausführlichem Log
npx tsx agenten/llama-verify-article.ts --job-id mein-artikel --verbose "$(cat artikel.txt)"

# Cache umgehen (erzwingt neue Perplexity-Anfragen)
npx tsx agenten/llama-verify-article.ts --no-cache --job-id test "$(cat artikel.txt)"

# Ollama-Fallback
npx tsx agenten/ollama-verify-article.ts --job-id mein-artikel "$(cat artikel.txt)"
```

**Jobs ansehen:**
```bash
ls ~/.pi/agent/jobs/
cat ~/.pi/agent/jobs/2026-05-12_mein-artikel/meta.json
```

**Beispielausgabe:**
```
Modus: fast | Max. Claims: 15 | Job: mein-artikel

  Claims extrahieren (llama.cpp)...
  8 Claims — 5 prüfbar, 3 nicht prüfbar.
  Recherche läuft (5 Claims, max. 5 parallel)...
  [1/5] c001 ✓ "Die Inflationsrate betrug 2024 in Deutschland..."
  [2/5] c002 ✓ "Die EZB hat den Leitzins im Juni 2024 gesenkt."
  ...
  Urteilssynthese (llama.cpp, 5 Claims)...

## Verifikationsbericht
8 Claims extrahiert, 5 recherchiert. 3 bestätigt. 1 widerlegt. 1 ohne Belege.

**✗ WIDERLEGT (1):**
`c001` "Die Inflationsrate betrug 2024 in Deutschland 3,2%."
  → Die tatsächliche Rate war 2,2% (Destatis). Abweichung: +1 Prozentpunkt.
  ✗ Gegenbeleg: Statistisches Bundesamt weist 2,2% für 2024 aus.
```

---

### 4. Artikel schreiben

```bash
# ★ llama.cpp-Version (empfohlen)
npx tsx agenten/llama-writer.ts --from-job mein-artikel --style blog

# Aus Pipe (kein Job-Speicher)
npx tsx agenten/llama-verify-article.ts --json "$(cat artikel.txt)" \
  | npx tsx agenten/llama-writer.ts --from-report --style journalistic

# Stile: journalistic | blog | academic | editorial | explanatory
# Länge anpassen
npx tsx agenten/llama-writer.ts --from-job mein-artikel --style blog --words 800

# Ollama-Version mit Cloud-Modell (besserer Stil, kostenpflichtig)
npx tsx agenten/ollama-writer.ts --from-job mein-artikel --style academic --cloud
```

**Beispielausgabe:**
```markdown
# Inflation in Deutschland: Was die Zahlen wirklich sagen

_Die Diskussion um die Inflationsrate hat in den letzten Monaten an Schärfe gewonnen.
Doch was sagen die offiziellen Daten tatsächlich?_

Laut Statistischem Bundesamt lag die Inflationsrate in Deutschland 2024 bei 2,2 Prozent [1].
Die EZB reagierte im Juni 2024 mit einer Zinssenkung auf 4,25 Prozent [2]...

**Quellen:**
[1] [Destatis — Inflationsrate 2024](https://...)
[2] [EZB — Zinsentscheid Juni 2024](https://...)

_[llama.cpp: Qwopus3.6-35B-A3B-v1-Q4_K_M.gguf · 412 Wörter · kostenlos (lokal) · 22.4s]_
```

---

### 5. Fehlschlüsse analysieren

```bash
# ★ llama.cpp-Version (empfohlen)
npx tsx agenten/llama-logic-editor.ts "$(cat essay.txt)"

# Nur Fehlschlüsse (schneller, kompakter)
npx tsx agenten/llama-logic-editor.ts --only-fallacies "$(cat essay.txt)"

# JSON für Weiterverarbeitung
npx tsx agenten/llama-logic-editor.ts --json "$(cat essay.txt)" > analysis.json

# Ollama-Version mit Cloud-Modell (deepseek-r1 via OpenRouter)
npx tsx agenten/ollama-logic-editor.ts --cloud "$(cat komplexer-text.txt)"
```

**Beispielausgabe:**
```
⚠ Ad Hominem (kritisch)
  Der Autor greift die Person an statt das Argument zu widerlegen.
  _"Wer so denkt, hat offensichtlich keine Ahnung von Wirtschaft."_

⚠ Falsche Dichotomie (kritisch)
  Es werden nur zwei Optionen präsentiert, obwohl weitere existieren.
  _"Entweder wir sparen jetzt, oder wir gehen bankrott."_

~ Autoritätsargument (moderat)
  Berufung auf Autorität ohne Prüfung der Aussage.
  _"Experten sind sich einig, dass..."_
```

---

### 6. Vollständiger Workflow — von Artikel zu Artikel

```bash
# Schritt 1: Artikel fact-checken (★ llama.cpp, mit Job-Speicher)
npx tsx agenten/llama-verify-article.ts \
  --job-id klimaartikel \
  --mode deep \
  --verbose \
  "$(cat ~/Dokumente/klimaartikel.txt)"

# Schritt 2: Verifikationsbericht ansehen
cat ~/.pi/agent/jobs/2026-05-12_klimaartikel/report.json | python3 -m json.tool

# Schritt 3: Neuen Artikel schreiben (nur aus verifizierten Fakten)
npx tsx agenten/llama-writer.ts \
  --from-job klimaartikel \
  --style journalistic \
  --words 600

# Schritt 4: Argumente des Original-Artikels analysieren
npx tsx agenten/llama-logic-editor.ts --only-fallacies "$(cat ~/Dokumente/klimaartikel.txt)"
```

---

## Optionen im Überblick

### Gemeinsame Flags (alle CLI-Tools)

| Flag | Beschreibung |
|------|-------------|
| `--json` | Ausgabe als JSON (maschinenlesbar, stdout) |
| `--verbose`, `-v` | Ausführliche Ausgabe + Log-Datei in `~/.pi/agent/logs/` |
| `--model <name>` | Modell überschreiben |

### `llama-claim-extractor.ts` / `ollama-claim-extractor.ts`

| Flag | Beschreibung |
|------|-------------|
| `--only-checkable` | Nur empirisch prüfbare Claims anzeigen |
| `--max-claims <n>` | Max. Anzahl Claims (Standard: 40) |
| `--file <path>` | Textdatei statt Argument (nur llama-Version) |
| `--translate-to <lang>` | Übersetzung der Claims (nur llama-Version) |

### `llama-verifier.ts` / `ollama-verifier.ts`

| Flag | Beschreibung |
|------|-------------|
| `--mode fast\|deep` | Perplexity-Modell: `sonar` (Standard) oder `sonar-pro` |
| `--user-language <lang>` | Sprache des Urteilstexts, z.B. `de`, `en` (nur llama-Version) |

### `llama-verify-article.ts` / `ollama-verify-article.ts`

| Flag | Beschreibung |
|------|-------------|
| `--job-id <slug>` | Job-Speicher aktivieren (Resume bei Unterbrechung) |
| `--mode fast\|deep` | Perplexity-Modus |
| `--max-claims <n>` | Max. zu prüfende Claims (Standard: 15, Max: 20) |
| `--no-cache` | Globalen Claim-Cache deaktivieren (erzwingt neue Perplexity-Anfragen) |

### `llama-writer.ts` / `ollama-writer.ts`

| Flag | Beschreibung |
|------|-------------|
| `--from-report` | Report von stdin lesen (Pipe-Modus) |
| `--from-job <slug>` | Report aus Job-Speicher laden |
| `--style <s>` | `journalistic` \| `blog` \| `academic` \| `editorial` \| `explanatory` |
| `--words <n>` | Ziel-Wortanzahl (Standard: 400) |
| `--cloud` | OpenRouter statt lokalem Backend (nur ollama-writer, besserer Stil) |

### `llama-logic-editor.ts` / `ollama-logic-editor.ts`

| Flag | Beschreibung |
|------|-------------|
| `--only-fallacies` | Nur Fehlschlüsse ausgeben (ohne vollständige ArgumentMap) |
| `--cloud` | OpenRouter (nur ollama-logic-editor — deepseek-r1 via Cloud) |

---

## Kosten-Übersicht

| Schritt | Backend | Kosten | Anmerkung |
|---------|---------|--------|-----------|
| Claim-Extraktion | llama.cpp (Qwopus3.6) | $0.00 | auch bei Chunking |
| Perplexity `fast` | sonar | ~$0.005/Claim | Standard |
| Perplexity `deep` | sonar-pro | ~$0.015/Claim | für heikle Themen |
| Verdict-Synthese | llama.cpp (Qwopus3.6) | $0.00 | Batch für alle Claims |
| Artikel schreiben | llama.cpp (Qwopus3.6) | $0.00 | Standard ★ |
| Artikel schreiben | OpenRouter (`--cloud`) | ~$0.01–0.05 | besserer Stil |
| Argumentationsanalyse | llama.cpp (Qwopus3.6) | $0.00 | ★ |

**Typische Gesamtkosten pro Artikel:** $0.03–0.15 (nur Perplexity)

---

## Troubleshooting

### „fetch failed" (llama.cpp)
```bash
# llama.cpp-Server läuft?
curl -s http://localhost:8000/v1/models
# Falls nicht: Server neu starten
llama-server --model Qwopus3.6-35B-A3B-v1-Q4_K_M.gguf --host 0.0.0.0 --port 8000 -c 32768
# Retry-Logik wartet automatisch 15s und versucht 3×
```

### „fetch failed" (Ollama)
```bash
# Ollama läuft?
systemctl status ollama
curl -s http://localhost:11434/api/tags | head -1
# Ollama neu starten
sudo systemctl restart ollama
# Dann denselben Befehl nochmals aufrufen — Retry-Logik wartet automatisch 15s
```

### „0 Claims extrahiert"
Sollte mit der aktuellen Chunking-Implementierung nicht mehr auftreten.
Falls doch: Text kürzer als 500 Zeichen? Dann gibt es möglicherweise schlicht keine prüfbaren Behauptungen.

### Erste Ollama-Anfrage dauert 200+ Sekunden
Das Modell wird geladen. Folgeaufrufe sind schnell. Dauerhaft lösen:
```bash
sudo systemctl edit ollama
# Environment="OLLAMA_KEEP_ALIVE=-1"
sudo systemctl daemon-reload && sudo systemctl restart ollama
```

### GPU wird nicht genutzt
```bash
nvidia-smi   # GPU-Auslastung prüfen
# GPU 2 (zweite RTX 3090) ist aktuell idle — für parallele Nutzung:
sudo systemctl edit ollama
# Environment="CUDA_VISIBLE_DEVICES=1,2"
```

### Log-Dateien lesen
```bash
ls -lt ~/.pi/agent/logs/           # Neueste Logs zuerst
cat ~/.pi/agent/logs/2026-05-12_*.log | tail -50
```