# RAG-System – Technische Projektdokumentation

Version: 2.0  
Stand: Februar 2026  
Status: Code-validierte Referenzarchitektur

---

# 1. Ziel des Systems

Das System implementiert ein deterministisches Retrieval-Augmented-Generation (RAG) Framework auf Basis versionierter Dokumente.

Leitprinzip:

> „Wir nutzen KI nicht, um kreativ zu raten, sondern um verlässlich auf Basis Ihres Wissens zu antworten.“

Das System stellt sicher:

- Versionierte Dokumentverwaltung
- Deterministisches Chunking
- Streamingfähige NDJSON Source of Truth
- Vollständiger FAISS-Rebuild bei strukturellen Änderungen
- Persistenter Python Vector-Service
- Governance-stabile Ingest- und Reindex-Mechanik

---

# 2. Architekturüberblick

## 2.1 Hauptkomponenten

Symfony (PHP)
- Dokumentverwaltung
- Versionierung
- Ingest-Orchestrierung
- Job-System
- Admin-Oberfläche
- PromptBuilder
- VectorSearchClient

Python Layer
- Embedding-Modell (SentenceTransformers)
- FAISS Index
- Vector-Service (FastAPI + uvicorn)
- CLI-Fallback Scripts

Persistenz
- index.ndjson (Single Source of Truth)
- index_meta.json (Struktur-Metadaten)
- vector.index (FAISS)
- tags.ndjson (optional)
- vector_tags.index (optional)

---

# 3. Verzeichnisstruktur (verifiziert)

bin/
config/
migrations/
public/
python/
src/
templates/
var/

Python-Vektorlayer:

python/
vector_service.py
vector_control.py
vector_ingest.py
vector_search.py
vector_ingest_tags.py
vector_search_tags.py

---

# 4. Source of Truth Konzept

## 4.1 index.ndjson

Streamingfähiges NDJSON-Format:

- Eine JSON-Zeile pro Chunk
- Kein JSON-Array
- Append-fähig
- Speicheroptimiert für >200k Chunks

## 4.2 index_meta.json

Beinhaltet:

- index_version
- embedding_model
- embedding_dimension
- chunk_size
- overlap
- scoring_version
- index_format

Bei strukturellen Änderungen wird ein Global Reindex erzwungen.

---

# 5. Dokument-Lifecycle

Dokument
→ Version
→ Aktivierung
→ IngestJob (QUEUE)
→ Chunking
→ NDJSON Compaction by document_id
→ Full FAISS Rebuild
→ Status INDEXED

Wichtige Regel:

Es existiert immer nur eine aktive Version pro Dokument.

---

# 6. Ingest-System

## 6.1 Job-Typen

- DOCUMENT_UPLOAD
- DOCUMENT_VERSION_ACTIVATE
- GLOBAL_REINDEX

## 6.2 Aktivierung

Beim Aktivieren einer Version:

- DB-Status wird geändert
- IngestStatus → PENDING
- IngestJob wird erzeugt
- CLI-Execution via:

```
bin/console mto:agent:ingest:run <jobId>
```

LockService verhindert Parallel-Ingest.

---

# 7. Retrieval

## 7.1 Architektur

Hybrid im Sinne von:

- FAISS Vektor-Retrieval
- Optionales Tag-Routing (separater Tag-Index)

Kein klassisches Keyword-Retrieval mehr aktiv.

## 7.2 Ablauf

1. Anfrage
2. VectorSearchClient → Python Service
3. FAISS Similarity Search
4. Top-K Chunks
5. PromptBuilder
6. LLM Response

---

# 8. Python Vector Service

FastAPI Service mit uvicorn.

Steuerung über:

```
bin/console mto:agent:vector:control
```

Mögliche Aktionen:

- --install
- --start
- --stop
- --reload
- --status

Service lädt:

- Embedding-Modell einmalig
- FAISS Index einmalig
- Hält alles persistent im RAM

CLI-Fallback bleibt verfügbar.

---

# 9. Embedding

Verwendetes Modell ist konfigurierbar.

Embedding-Dimension wird aus Modell bestimmt und im index_meta.json gespeichert.

Bei Dimensionsänderung:

→ Guardrail blockiert lokalen Ingest  
→ Global Reindex erforderlich

---

# 10. Reindex-Strategie

## 10.1 Lokaler Re-Ingest

- Compaction nur für document_id
- Neue Chunks append
- Danach vollständiger FAISS-Rebuild

## 10.2 Global Reindex

- Alle aktiven Dokumente neu ingestieren
- index.ndjson komplett neu schreiben
- index_version++
- FAISS neu bauen

---

# 11. Rollenmodell

- SUPER_ADMIN
- KNOWLEDGE_ADMIN
- Wissensredaktion
- Frontend-User

Dokumente sind immutable.
Chunks sind niemals manuell editierbar.

---

# 12. Guardrails

Verhindert:

- Embedding-Modell-Drift
- Chunking-Parameter-Drift
- Index-Format-Drift
- Parallele Ingest-Jobs
- Live-Änderung aktiver Ingest-Profile

---

# 13. Wichtige Symfony Commands (validiert)

mto:agent:ingest:run
mto:agent:vector:control
mto:agent:vector:ingest
mto:agent:vector:search

Namespace ist durchgehend:

mto:agent:*

---

# 14. Systemgrenzen

Das System ist ausgelegt für:

- >200.000 Chunks
- Deterministische Reproduzierbarkeit
- Enterprise-Governance
- Drift-Sicherheit
- Skalierbare Erweiterung

---

# 15. Nicht Bestandteil

- Kein manuelles Chunk-Editing
- Kein Keyword-Retrieval
- Kein partieller FAISS-Rebuild
- Kein In-Place Index Update

Immer vollständiger Rebuild.

---

# 16. Zusammenfassung

Das System implementiert eine deterministische, governance-stabile RAG-Architektur mit:

- NDJSON als Streaming-Single-Source
- Vollständigem FAISS-Rebuild
- Persistenter Vector-Service-Schicht
- Versionierter Dokumentverwaltung
- Strikter Guardrail-Logik

Diese README entspricht vollständig dem aktuellen Code-Stand der rag.zip.