README.md

# RAG Ingestion Tools

Lokale Python-Tools zum Importieren von Dokumenten in pgvector-Datenbanken.
Drei eigenständige Tools für unterschiedliche Zieldatenbanken und Anwendungsfälle.

---

## Übersicht

| Tool | Zieldatenbank | Verbindung | Besonderheit |
|---|---|---|---|
| `ingest.py` | Hetzner (anythingllm) | SSH-Tunnel | OCR + KI-Normalisierung |
| `ingest_anythingllm.py` | Hetzner (anythingllm) | SSH-Tunnel | Einfach, nur MD/TXT/PDF |
| `ingest_job_matching.py` | NAS 192.168.178.128 | Direkt (Port 5433) | Job-Matching-Datenbank |

---

## Tool 1: `ingest.py` — Vollpipeline mit OCR + KI-Normalisierung

Das Haupt-Tool der neuen Generation. Verarbeitet beliebige Dokumente (inkl. Scans
und Bilder) und normalisiert sie via Claude KI in die einheitliche Template-Struktur.

**Abhängigkeiten:** `extractor.py`, `normalizer.py` (müssen im gleichen Verzeichnis liegen)

### Unterstützte Formate

`.md` `.txt` `.pdf` `.docx` `.png` `.jpg` `.jpeg` `.tif` `.tiff` `.bmp` `.webp`

### Voraussetzungen

```bash
# Tesseract (OCR, einmalig)
brew install tesseract tesseract-lang

# Python-Pakete
pip install -r requirements.txt

# .env konfigurieren
cp .env.example .env
# ANTHROPIC_API_KEY eintragen
```

### Verwendung

```bash
# Einzelne Datei (mit KI-Normalisierung)
python ingest.py file ~/Downloads/fremdes_cv.pdf

# Erst testen ohne DB-Speicherung
python ingest.py file ~/Desktop/scan.png --dry-run

# Ohne KI-Normalisierung (z.B. eigene fertige Templates)
python ingest.py file ~/templates/ausgefuellt/mein_cv.md --no-normalize

# Ganzes Verzeichnis
python ingest.py dir ~/Dokumente/bewerbungsunterlagen/ --force

# Ordner live beobachten (neue Dateien automatisch verarbeiten)
python ingest.py watch ~/Desktop/scan-eingang/

# DB-Inhalt anzeigen
python ingest.py list

# Dokument löschen
python ingest.py delete "fremdes_cv.pdf"
```

### Flags

| Flag | Beschreibung |
|---|---|
| `--force` | Bestehende Chunks überschreiben |
| `--no-normalize` | KI-Normalisierung überspringen |
| `--dry-run` | Nur extrahieren + normalisieren, nicht speichern |
| `--quality-min 0.5` | Mindest-Qualitäts-Score (0.0–1.0) |

### KI-Normalisierung

Erkennt den Dokumenttyp automatisch und transformiert den Inhalt in die passende
Template-Struktur aus `templates/`. Nutzt die ausgefüllten Beispiele aus
`templates/ausgefuellt/` als Few-Shot-Referenz.

- Typ-Erkennung: Claude Haiku (günstig + schnell)
- Transformation: Claude Sonnet
- Fehlende Felder werden mit `[FEHLT]` markiert, nicht halluziniert

---

## Tool 2: `ingest_anythingllm.py` — Einfaches Ingestion-Script

Schlankes Tool ohne OCR und ohne KI-Normalisierung. Direkte Übernahme von
MD/TXT/PDF-Dateien in die anythingllm-Datenbank auf dem Hetzner-Server.

Geeignet für: eigene, bereits fertig strukturierte Dokumente.

### Unterstützte Formate

`.md` `.txt` `.pdf`

### Voraussetzungen

```bash
pip install openai psycopg2-binary pgvector sshtunnel python-dotenv pypdf tiktoken sentence-transformers
cp .env.example .env
# OPENAI_API_KEY eintragen (wird nur für Client-Init benötigt, Embeddings laufen lokal)
```

### Verwendung

```bash
# Einzelne Datei
python ingest_anythingllm.py file ~/Dokumente/Lebenslauf.md

# Mit --force (bestehende Chunks überschreiben)
python ingest_anythingllm.py file ~/Dokumente/Lebenslauf.md --force

# Ganzes Verzeichnis
python ingest_anythingllm.py dir ~/Dokumente/bewerbung/

# DB-Inhalt anzeigen
python ingest_anythingllm.py list
```

---

## Tool 3: `ingest_job_matching.py` — Job-Matching-Datenbank (NAS)

Importiert Dokumente direkt in die `job_matching`-Datenbank auf dem lokalen NAS
(192.168.178.128, Port 5433). Kein SSH-Tunnel erforderlich.

### Voraussetzungen

```bash
pip install -r requirements.txt
cp .env.job_matching .env.job_matching.local
# Werte in .env.job_matching.local anpassen
```

### Verwendung

```bash
python ingest_job_matching.py file ~/Dokumente/stellenanzeige.pdf
python ingest_job_matching.py dir ~/Dokumente/stellen/
python ingest_job_matching.py list
```

---

## Gemeinsame Infrastruktur

### Embedding-Modell

Alle Tools verwenden `intfloat/multilingual-e5-small` (384 Dimensionen) lokal.
Wird beim ersten Aufruf automatisch heruntergeladen (~120 MB).

### Templates

```
templates/
├── *_TEMPLATE.md          Ziel-Strukturvorlagen (leer)
└── ausgefuellt/           Ausgefüllte Referenzbeispiele (für KI-Few-Shot)
```

### Umgebungsvariablen

| Datei | Verwendet von |
|---|---|
| `.env` | `ingest.py`, `ingest_anythingllm.py` |
| `.env.job_matching` | `ingest_job_matching.py` |

---

## Setup (komplett, einmalig)

```bash
cd ~/Projekte/rag-ingestion
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt
brew install tesseract tesseract-lang   # nur für ingest.py (OCR)
cp .env.example .env
nano .env                               # API-Keys + DB-Zugangsdaten eintragen
```