Text_Agent/README.md

# Pi Text-Agent

Lokales Multi-Agenten-System für Fact-Checking, Artikelschreiben und Argumentationsanalyse.
Läuft als Pi-Extension-Paket und als CLI. Zwei lokale KI-Backends: Ollama und llama.cpp (★ bevorzugt für Reasoning-Modelle), Webrecherche via Perplexity.

---

## Was es kann

```
Artikel-Text
    │
    ├─► extract_claims_llama ★  → Welche Behauptungen stecken im Text?
    │
    ├─► verify_article_llama ★  → Welche Behauptungen sind wahr / falsch?
    │       └─► verify_claim_llama ★  → Einzelne Behauptung prüfen
    │
    ├─► write_article_llama ★   → Neuen Artikel nur aus verifizierten Fakten schreiben
    │
    └─► analyze_logic_llama ★   → Welche logischen Fehlschlüsse enthält der Text?

Suchanfrage
    └─► research_web            → Webrecherche via Perplexity

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

---

## Voraussetzungen

- **llama.cpp-Server** mit `Qwopus3.6-35B-A3B-v1-Q4_K_M.gguf` auf Port 8000 (★ bevorzugtes Backend)
- **Ollama** mit `qwen3.5:27b` und `deepseek-r1:32b` (Fallback-Backend + Logik-Analyse)
- **Perplexity API Key** (`PERPLEXITY_API_KEY`) — für Webrecherche und Fact-Checking
- **Pi Coding Agent** — für den Extension-Modus
- **Node.js** ≥ 20 (empfohlen: v22 via nvm)
- Optional: **OpenRouter API Key** (`OPENROUTER_API_KEY`) — für Cloud-Modelle

```bash
# llama.cpp-Server starten (GPU 2, Port 8000)
llama-server --model Qwopus3.6-35B-A3B-v1-Q4_K_M.gguf --host 0.0.0.0 --port 8000 -c 32768

# Ollama-Modelle laden (für ollama-logic-editor + Fallback)
ollama pull qwen3.5:27b
ollama pull deepseek-r1:32b
```

---

## Schnellstart

```bash
cd ~/Pi_Agent_Projekts/text_agent

# ★ llama.cpp-Pipeline (empfohlen)
npx tsx agenten/llama-claim-extractor.ts "Die Inflationsrate betrug 2024 in Deutschland 3,2%."
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

# Fehlschlüsse analysieren (★ llama.cpp)
npx tsx agenten/llama-logic-editor.ts --only-fallacies "$(cat essay.txt)"
```

---

## Agenten

| Agent | Pi-Tool | Modell | Kosten |
|-------|---------|--------|--------|
| `llama-claim-extractor.ts` ★ | `extract_claims_llama` | Qwopus3.6-35B (llama.cpp) | kostenlos |
| `llama-verifier.ts` ★ | `verify_claim_llama` | Perplexity + Qwopus3.6 | ~$0.005–0.015/Claim |
| `llama-verify-article.ts` ★ | `verify_article_llama` | Perplexity + Qwopus3.6 | ~$0.05–0.15/Artikel |
| `llama-writer.ts` ★ | `write_article_llama` | Qwopus3.6 (llama.cpp) | kostenlos |
| `ollama-claim-extractor.ts` | `extract_claims` | qwen3.5:27b (Ollama) | kostenlos |
| `ollama-verifier.ts` | `verify_claim` | Perplexity + qwen3.5:27b | ~$0.005–0.015/Claim |
| `ollama-verify-article.ts` | `verify_article` | Perplexity + qwen3.5:27b | ~$0.05–0.15/Artikel |
| `ollama-writer.ts` | `write_article` | qwen3.5:27b (Ollama) | kostenlos |
| `llama-logic-editor.ts` ★ | `analyze_logic_llama` | Qwopus3.6 (llama.cpp) | kostenlos |
| `ollama-logic-editor.ts` | `analyze_logic` | deepseek-r1:32b (Ollama) | kostenlos |
| `research-web.ts` | `research_web` | Perplexity | ~$0.001–0.005 |

★ = llama.cpp-Backend, bevorzugt (kein Ollama-Timeout bei Reasoning-Modellen)

---

## Job-Speicher

`llama-verify-article.ts --job-id <slug>` sichert jeden Schritt in `~/.pi/agent/jobs/`:

```
~/.pi/agent/jobs/2026-04-16_mein-artikel/
├── input.txt         ← Originaltext
├── claims.json       ← Extrahierte Behauptungen
├── perplexity/
│   ├── c001.json     ← Perplexity-Ergebnis pro Claim (gecacht!)
│   └── c002.json
├── report.json       ← Verifikationsbericht
├── article.md        ← Fertiggestellter Artikel
└── meta.json         ← Status, Timestamps, Kosten
```

Bei Unterbrechung: denselben Befehl nochmals aufrufen. Bereits abgeschlossene Schritte — inklusive bereits bezahlter Perplexity-Anfragen — werden übersprungen.

---

## Verzeichnisstruktur

```
text_agent/
├── agenten/           ← Agenten (Pi-Extension + CLI)
├── lib/
│   ├── perplexity.ts  ← Perplexity-API-Wrapper
│   ├── router.ts      ← Model-Router (lokal/cloud)
│   ├── logger.ts      ← File-Logger (~/.pi/agent/logs/)
│   ├── jobs.ts        ← Job-Speicher (~/.pi/agent/jobs/)
│   └── cache.ts       ← SHA256-Claim-Cache (~/.pi/agent/cache/perplexity/)
├── schemas/           ← JSON-Schema-Definitionen
├── tests/
│   ├── corpus/        ← 10 Testfälle (input.txt, expected.json, notes.md)
│   └── run_corpus.sh  ← Precision/Recall-Test-Runner
├── types/             ← TypeScript-Typ-Stubs
└── docs/
    └── ARCHITECTURE.md
```

---

## Deployment als Pi-Extension

```bash
# Symlinks anlegen (einmalig)
mkdir -p ~/.pi/agent/extensions/fact-checker
ln -s ~/Pi_Agent_Projekts/text_agent/lib ~/.pi/agent/extensions/lib
for agent in ollama-claim-extractor llama-claim-extractor \
             ollama-verifier llama-verifier \
             ollama-verify-article llama-verify-article \
             ollama-logic-editor llama-logic-editor \
             ollama-writer llama-writer; do
  ln -s ~/Pi_Agent_Projekts/text_agent/agenten/${agent}.ts \
        ~/.pi/agent/extensions/fact-checker/${agent}.ts
done

# In Pi nach Änderungen
/reload
```

---

## Dokumentation

| Datei | Inhalt |
|-------|--------|
| `BEDIENUNGSANLEITUNG.md` | Ausführliche Nutzungsanleitung mit Beispielen |
| `docs/ARCHITECTURE.md` | Technische Architektur, Datenfluß, VRAM-Details |
| `AGENTS.md` | Arbeitsgrundlage für Pi Coding Agent |
| `HANDOFF.md` | Aktueller Projektstand für Entwickler-Übergaben |
| `TODO.md` | Offene Aufgaben nach Priorität |

---

## Roadmap

| Priorität | Feature | Beschreibung |
|-----------|---------|--------------|
| P1 | **Mehrsprachigkeit Ollama-Agenten** | `--lang`-Flag und mehrsprachige Prompts für alle `ollama-*`-Agenten (analog zu den llama.cpp-Varianten) |
| P1 | **Parallelisierung** | 3-Phasen-Pipeline: Claim-Extraktion sequenziell → Perplexity aller Fälle parallel → Batch-Synthese in einem llama.cpp-Aufruf; Ziel: ~75% kürzere Laufzeit |
| P2 | **Weggelassene Fakten erkennen** | Vergleich zwischen Originaltext und generiertem Artikel — Meldung wenn prüfbare Fakten im Artikel fehlen oder weggelassen wurden |
| P2 | **Fakten-Gewichtung** | Claims nach Relevanz und Belegbarkeit gewichten; wichtigere Fakten erhalten höheres Gewicht in Precision/Recall und im Artikel-Output |

---

## Technische Details

- **Sprache:** TypeScript (ESM), keine Build-Schritte — direkt via `npx tsx`
- **llama.cpp:** OpenAI-kompatibles API `/v1/chat/completions`, Schema als JSON-Literal im System-Prompt, `/no_think`-Prefix für Reasoning-Modelle
- **Ollama structured output:** `format: <JSON-Schema>`, `stream: false`, `num_ctx: 8192`
- **Chunking:** Texte > 4000 Zeichen werden automatisch in Abschnitte ≤ 3000 Zeichen aufgeteilt
- **Parallelität:** Max. 5 gleichzeitige Perplexity-Anfragen; llama.cpp und Ollama sequenziell
- **Retry:** 3 Versuche mit 15s Pause bei Verbindungsfehlern
- **Getestet auf:** Ubuntu, 2× RTX 3090 (24 GB), Node.js v22