# RAG Ingestion Tools

Lokale Python-Tools zum Importieren von Dokumenten in pgvector-Vektordatenbanken.
Drei eigenständige Scripts für unterschiedliche Zielplattformen und Anwendungsfälle,
plus zwei gemeinsame Module für Extraktion und KI-Normalisierung.

---

## Übersicht & Zielplattformen

| Tool | Wofür? | Zielplattform | Verbindung | .env-Datei |
|---|---|---|---|---|
| `ingest_V2.py` | Fremde Dokumente, Scans, Bilder — mit automatischer Strukturierung | Hetzner · anythingllm DB | SSH-Tunnel | `.env.ingest` |
| `ingest_anythingllm.py` | Eigene, bereits strukturierte Dokumente (Templates) | Hetzner · anythingllm DB | SSH-Tunnel | `.env.ingest` |
| `ingest_job_matching.py` | Stellenanzeigen & Profil-Dokumente für Job-Matching | NAS · job_matching DB | Direkt (Port 5433) | `.env.job_matching` |

**Wann welches Tool?**

- Du hast ein **fremdes CV, einen Scan oder ein Bild** → `ingest_V2.py` (OCR + KI-Normalisierung)
- Du hast ein **eigenes, fertiges Markdown-Dokument** (z.B. ausgefülltes Template) → `ingest_anythingllm.py`
- Du willst **Stellenanzeigen oder Profil-Dokumente** für Job-Matching einpflegen → `ingest_job_matching.py`

---

## Dateistruktur

```
rag-ingestion/
├── ingest_V2.py             Vollpipeline v2: OCR + KI-Normalisierung (→ Hetzner)
├── ingest_anythingllm.py    Einfaches Script v1: nur MD/TXT/PDF (→ Hetzner)
├── ingest_job_matching.py   Job-Matching Script: direkt auf NAS (→ NAS Port 5433)
│
├── extractor.py             Modul: Text-Extraktion + OCR (wird von ingest_V2 genutzt)
├── normalizer.py            Modul: KI-Normalisierung via Claude (wird von ingest_V2 genutzt)
│
├── architektur/
│   └── ocr_rag_pipeline.svg Architektur-Diagramm der ingest_V2 Pipeline
│
├── templates/
│   ├── *_TEMPLATE.md        Ziel-Strukturvorlagen (leer)
│   └── ausgefuellt/         Ausgefüllte Referenzbeispiele (Few-Shot für KI, nicht in Git)
│
├── .env.ingest              Secrets für ingest_V2.py + ingest_anythingllm.py (nicht in Git)
├── .env.job_matching        Secrets für ingest_job_matching.py (nicht in Git)
└── .env.example             Vorlage für .env.ingest
```

---

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

**Verwendungszweck:** Verarbeitung beliebiger Fremddokumente — gescannte PDFs, Bilder,
DOCX-Dateien, fremde CVs — die zunächst per OCR extrahiert und dann via Claude KI
automatisch in die einheitliche Template-Struktur transformiert werden.

**Zielplattform:** pgvector-Datenbank (`anythingllm`) auf Hetzner-Server via SSH-Tunnel.

**Benötigt:** `extractor.py` und `normalizer.py` im gleichen Verzeichnis.

### Architektur

![OCR → RAG Ingestion Pipeline](architektur/ocr_rag_pipeline.svg)

### Unterstützte Formate

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

### Voraussetzungen

```bash
# System-Tools (einmalig)
brew install tesseract tesseract-lang poppler

# Python-Pakete
pip install -r requirements.txt

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

### Verwendung

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

# Dry-Run: erst testen, nichts in DB schreiben
python ingest_V2.py file ~/Desktop/scan.png --dry-run

# Dry-Run + normalisiertes Markdown automatisch speichern (<dateiname>_normalized.md)
python ingest_V2.py file ~/Downloads/cv.pdf --dry-run

# Dry-Run + normalisiertes Markdown in bestimmte Datei speichern
python ingest_V2.py file ~/Downloads/cv.pdf --dry-run --output ~/Desktop/cv_normalisiert.md

# Ohne KI-Normalisierung (für bereits strukturierte Dokumente)
python ingest_V2.py file ~/templates/ausgefuellt/mein_cv.md --no-normalize

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

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

### Datenbank verwalten

```bash
# Alle importierten Dokumente anzeigen
# Zeigt: Titel, Dokumenttyp, Qualitäts-Score, Format, Anzahl Chunks, Datum
python ingest_V2.py list

# Ausgabe-Beispiel:
#   Titel                                         Typ             Score    Fmt  Chunks  Datum
#   ──────────────────────────────────────────────────────────────────────────────────────────
#   Arbeitszeugnis Sopra Financial Technology...  arbeitszeugnis    95%   .pdf       3  2026-04-28

# Einzelnes Dokument löschen (alle Chunks)
# Hinweis: Titel = exakter Dateiname wie beim Import
python ingest_V2.py delete "Arbeitszeugnis Sopra Financial Technology GmbH.pdf"
```

### Flags

| Flag | Beschreibung |
|---|---|
| `--force` | Bestehende Chunks überschreiben |
| `--no-normalize` | KI-Normalisierung überspringen |
| `--dry-run` | Nur extrahieren + normalisieren, nicht in DB speichern |
| `--output <pfad>` | Normalisiertes Markdown als Datei speichern (nur mit `--dry-run`) |
| `--quality-min 0.5` | Mindest-Qualitäts-Score (0.0–1.0, Standard: 0.0) |

### KI-Normalisierung (`normalizer.py`)

- **Typ-Erkennung:** Claude Haiku (günstig + schnell)
- **Transformation:** Claude Sonnet
- **Fehlende Felder** werden mit `[FEHLT]` markiert, nie halluziniert
- **Qualitäts-Score:** 0.0–1.0 (Anteil befüllter Pflichtfelder)

Erkannte Typen: `arbeitszeugnis`, `cv`, `lebenslauf`, `anschreiben`,
`projektbeschreibung`, `karriereziele`, `technologie`, `zertifikate`,
`referenzen`, `elevatorpitch`, `rahmenbedingungen`, `zielstellen`

### OCR-Pipeline (`extractor.py`)

1. `pypdf` versucht Text zu extrahieren
2. Weniger als 150 Zeichen → OCR-Fallback via Tesseract (300 DPI)
3. Bilder (PNG, JPG etc.) → direkt OCR

---

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

**Verwendungszweck:** Schnelles Einpflegen von eigenen, bereits fertig strukturierten
Dokumenten — z.B. ausgefüllte Templates, eigene Markdown-Dateien oder einfache PDFs
die keiner OCR oder KI-Normalisierung bedürfen.

**Zielplattform:** pgvector-Datenbank (`anythingllm`) auf Hetzner-Server via SSH-Tunnel.
Gleiche Zieldatenbank wie `ingest_V2.py` — unterschiedlicher Verarbeitungsweg.

### Unterstützte Formate

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

### Verwendung

```bash
python ingest_anythingllm.py file ~/Dokumente/Lebenslauf.md
python ingest_anythingllm.py file ~/Dokumente/Lebenslauf.md --force
python ingest_anythingllm.py dir ~/Dokumente/bewerbung/
python ingest_anythingllm.py list
```

---

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

**Verwendungszweck:** Einpflegen von Stellenanzeigen und Profil-Dokumenten in die
dedizierte Job-Matching-Datenbank. Diese Datenbank wird von einem separaten
Job-Matching-Workflow genutzt um Stellenanzeigen mit dem eigenen Profil abzugleichen.

**Zielplattform:** pgvector-Datenbank (`job_matching`) direkt auf dem lokalen NAS
(192.168.178.128, Port 5433) — kein SSH-Tunnel erforderlich, nur im lokalen Netzwerk erreichbar.

Embeddings via OpenAI `text-embedding-3-small` (1536 Dimensionen, kostenpflichtig).

### 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
python ingest_job_matching.py clear "stellenanzeige.pdf"
```

---

## Gemeinsame Infrastruktur

### Embedding-Modelle

| Tool | Modell | Dimensionen | Kosten |
|---|---|---|---|
| `ingest_V2.py` | multilingual-e5-small (lokal) | 384 | kostenlos |
| `ingest_anythingllm.py` | multilingual-e5-small (lokal) | 384 | kostenlos |
| `ingest_job_matching.py` | OpenAI text-embedding-3-small | 1536 | kostenpflichtig |

### Umgebungsvariablen

| Datei | Verwendet von | Inhalt |
|---|---|---|
| `.env.ingest` | `ingest_V2.py`, `ingest_anythingllm.py` | ANTHROPIC_API_KEY, SSH, DB |
| `.env.job_matching` | `ingest_job_matching.py` | OPENAI_API_KEY, NAS-DB |

---

## 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 poppler   # nur für ingest_V2.py
cp .env.example .env.ingest
nano .env.ingest   # ANTHROPIC_API_KEY + SSH + DB-Zugangsdaten eintragen
```