MtoRagSystem/README.md

# RAG-System – Technische Projektdokumentation
**Version:** 1.0  
**Stand:** Februar 2026  
**Autor:** mitho  
**Status:** Verbindliche Referenzarchitektur (System Freeze)

---

# 1. Ziel des Systems

Das RAG-System dient der deterministischen, governance-stabilen Beantwortung von Nutzeranfragen auf Basis versionierter, kontrollierter Wissensquellen.

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

Das System kombiniert:

- Versionierte Dokumentverwaltung
- Deterministisches Chunking
- NDJSON als Single Source of Truth
- Vollständigen FAISS-Rebuild
- Hybrid Retrieval (Keyword + Vector + Tag)
- Job-basierte Orchestrierung
- Rollen- und Guardrail-Architektur
- SSE-Streaming

---

# 2. Architekturüberblick

## 2.1 Systemebenen

### 1. Admin-Ebene (Symfony Backend)
- Dokumentverwaltung
- Versionierung
- Tag-Management
- Job-Steuerung
- System-Prompt-Verwaltung
- KI-Endpoint-Konfiguration

### 2. Wissensebene
- Dokumente (immutable)
- DocumentVersion
- Chunks
- index.ndjson
- index_meta.json

### 3. Vector-Ebene (Python)
- Embedding-Modell (lokal)
- FAISS-Index (Chunks)
- FAISS-Index (Tags)
- Persistenter Vector-Service
- CLI-Fallback

### 4. Agent-Ebene
- Retrieval-Fusion
- PromptBuilder
- SSE-Streaming
- Chat-History-Verarbeitung

---

# 3. Dokumentenarchitektur

## 3.1 Primärquellen

- Dokumente sind immutable.
- Jede Änderung erzeugt eine neue DocumentVersion.
- Pro Dokument existiert genau eine aktive Version.

## 3.2 Aktivierungsprozess

1. Aktivierung einer Version
2. Erstellung eines IngestJob
3. Async-Start:
   ```
   bin/console mto:agent:ingest:run <jobId>
   ```
4. IngestOrchestrator:
    - Guardrail-Validierung
    - NDJSON Compaction by document_id
    - Chunking
    - Streaming Append
    - Vollständiger FAISS-Rebuild
    - index_meta.json Update
    - Status COMPLETED/FAILED

---

# 4. NDJSON-Architektur

## 4.1 index.ndjson (Single Source of Truth)

- Streamingfähiges Format
- Kein JSON-Array
- Append-only mit Compaction
- Keine vollständige RAM-Verarbeitung
- Atomare Datei-Switches (.tmp → rename)

## 4.2 index_meta.json

Enthält:

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

### Guardrail-Mechanismus

Bei strukturellen Änderungen (Embedding, Chunking, Scoring):
- Lokaler Ingest wird blockiert
- Global Reindex erforderlich

---

# 5. Chunk-Management

Verantwortlich: ChunkManager

Eigenschaften:

- Streaming-basiertes Schreiben
- Deterministische Reproduktion
- Hard Limit: 120.000 Chunks
- Warnlimit: 100.000 Chunks
- Kein vollständiger JSON-RAM-Load

---

# 6. Vector-Architektur

## 6.1 Betriebsmodi

### A) Persistenter Vector-Service (bevorzugt)
- Lädt Embedding-Modell einmal
- Lädt FAISS-Indizes in RAM
- REST-Endpunkte:
    - /search-chunks
    - /search-tags

### B) CLI-Fallback
- Python-Skripte
- Wird genutzt, falls Service nicht verfügbar ist

## 6.2 Rebuild-Strategie

- Immer vollständiger FAISS-Rebuild
- Kein inkrementelles Patchen
- Atomarer Index-Switch
- Deterministisch und drift-sicher

---

# 7. Hybrid Retrieval

## 7.1 Retrieval-Komponenten

1. Keyword-Retrieval (führend)
2. FAISS-Chunk-Retrieval (ergänzend)
3. Tag-Routing (Soft-Gate)

## 7.2 Score-Fusion

- Keyword hat Priorität
- Vector ergänzt semantische Nähe
- Tags dienen als Routing-Verstärker

---

# 8. Tag-System

## 8.1 Entities

- Tag
- DocumentTag
- TagRebuildJob

## 8.2 Trigger-Logik

Ein Rebuild wird ausgelöst bei:

- Tag-Erstellung
- Tag-Löschung
- Tag-Zuweisung
- Tag-Entfernung

## 8.3 Job-Mechanik

- Async-Start via:
  ```
  php bin/console mto:agent:tags:job:run <jobId>
  ```
- Logfile unter:
  ```
  var/log/tags/job_<uuid>.log
  ```

## 8.4 Stale-Protection

- QUEUED-Jobs älter als 5 Minuten → FAILED
- System kann nicht dauerhaft blockieren
- Coalescing (max. 1 aktiver Job)

## 8.5 Tag-Index

- tags.ndjson
- vector_tags.index
- Vollständiger Rebuild bei Änderung

---

# 9. Job-Architektur

Statusmodell:

- QUEUED
- RUNNING
- COMPLETED
- FAILED

Eigenschaften:

- Async exec
- LockService gegen Parallel-Ausführung
- Self-Healing gegen blockierte Jobs
- Logging pro Job

---

# 10. Governance & Guardrails

## 10.1 Rollen

- Super Admin
- Knowledge Admin
- Redaktion
- Frontend-User

## 10.2 Schutzmechanismen

- Dokumente immutable
- Keine manuelle Chunk-Manipulation
- Versionierte Ingest-Profile
- Versionierte System-Prompts
- Konfigurierbare KI-Endpunkte
- Logging & Audit-Fähigkeit

---

# 11. Agent-Architektur

- SSE-Streaming
- Historienverarbeitung korrekt implementiert
- Deterministischer PromptBuilder
- Retrieval-Kontext explizit eingebettet
- Kein Think-Mode-Leak

---

# 12. Skalierbarkeit

Zielgröße:

- >120.000 Chunks

Ermöglicht durch:

- NDJSON Streaming
- Kein Full-RAM-JSON
- Vollständiger FAISS-Rebuild
- Persistenter Vector-Service
- Atomare Switches
- Locking-Mechanismen

---

# 13. Stabilitätsstatus (Freeze-Zustand)

| Bereich | Status |
|----------|--------|
| Dokument-Ingest | Stabil |
| NDJSON-Architektur | Enterprise-Stabil |
| FAISS-Rebuild | Deterministisch |
| Tag-System | Stabil mit Stale-Recovery |
| Async-Jobs | Blockiersicher |
| Retrieval-Fusion | Funktional |
| SSE | Stabil |
| Governance | Aktiv |

---

# 14. System-Freeze-Definition

Dieses Dokument definiert den verbindlichen Referenzstand des Systems.

Ab diesem Punkt gilt:

- Keine strukturellen Änderungen ohne explizite Freigabe.
- Erweiterungen nur inkrementell.
- Keine Architektur-Rewrites.
- Determinismus und Reproduzierbarkeit sind oberstes Prinzip.

---

# 15. Zusammenfassung

Das System ist:

- deterministisch
- drift-sicher
- governance-konform
- skalierbar
- blockiersicher
- debugbar
- enterprise-ready

Es erfüllt die Anforderungen an ein kontrolliertes, reproduzierbares RAG-System mit klarer Trennung zwischen Wissensquelle, Index, Retrieval und Generierung.