# RAG_SYSTEM_OVERVIEW.md

# RetrieX – Systemüberblick

> Hinweis: Die Datei heißt weiterhin `RAG_SYSTEM_OVERVIEW.md`, das System selbst wird fachlich jedoch als **RetrieX** bezeichnet.

## Grundidee

RetrieX ist ein dokumentenbasiertes Assistenzsystem mit **Retrieval-Augmented Generation**.

Das bedeutet:

- Antworten sollen nicht frei erfunden werden
- Wissen stammt primär aus den aktivierten Dokumenten im System
- die KI formuliert auf Basis von abgerufenem Kontext
- bei Produktanfragen können zusätzlich Live-Shopdaten einbezogen werden

RetrieX ist damit **kein frei antwortender Chatbot**, sondern ein kontrolliertes System aus:

- versionierten Wissensdokumenten
- deterministischem Ingest
- hybridem Retrieval
- optionaler Commerce-Erweiterung
- LLM-basierter Formulierung der Antwort

---

# Die Hauptbausteine des Systems

## 1. Dokumente als Wissensbasis

Die Wissensbasis besteht aus hochgeladenen Dokumenten, zum Beispiel:

- PDF
- DOCX
- Markdown
- TXT

Diese Dokumente werden nicht direkt „gelesen“, sondern in einen verarbeitbaren Wissensindex überführt.

Wichtige Eigenschaften:

- Dokumente sind versioniert
- pro Dokument gibt es fachlich genau eine aktive Version
- nur aktive Inhalte fließen in den Wissensindex ein
- Chunks sind abgeleitete Artefakte, keine manuell gepflegte Primärquelle

Die eigentliche Wissensquelle sind also die **aktiven Dokumentversionen**, nicht frei bearbeitete Textfragmente.

---

## 2. Ingest und Indexierung

Sobald eine Dokumentversion ingestiert oder aktiviert wird, läuft ein technischer Verarbeitungsprozess.

Dabei passiert im Kern:

1. Dokumentinhalt wird extrahiert
2. Inhalt wird in Chunks zerlegt
3. Chunk-Datensätze werden in `index.ndjson` geschrieben
4. der Vektorindex wird vollständig neu aufgebaut
5. Laufzeit-Metadaten werden aktualisiert

Der Ingest ist bewusst **deterministisch** aufgebaut.  
Das heißt: derselbe Datenstand soll immer wieder denselben Indexzustand erzeugen.

---

## 3. Retrieval zur Laufzeit

Wenn ein Nutzer eine Anfrage stellt, durchsucht RetrieX nicht „das ganze Dokument direkt“, sondern den vorbereiteten Wissensbestand.

Das Retrieval ist im aktuellen Stand **hybrid und routingfähig**:

- Vektor-Retrieval über FAISS
- zusätzliches Tag-Routing zur Vorselektion möglicher Dokumente
- Score-basierte Auswahl relevanter Chunks
- Sonderroute für Katalog-/Listenanfragen
- optionale Ergänzung durch Live-Shopdaten bei Commerce-Intent

Das System liefert also nicht einfach „irgendwelche Treffer“, sondern baut einen gezielten Kontextblock für das Modell.

---

## 4. Antwortgenerierung

Aus den ermittelten Informationen wird ein finaler Prompt aufgebaut.

Dieser Prompt kann aus mehreren Blöcken bestehen:

- aktiver System-Prompt
- Gesprächskontext des Nutzers
- Live-Shop-Ergebnisse
- abgerufene Wissens-Chunks
- optional extrahierter Inhalt einer URL aus der Nutzeranfrage
- aktuelle Nutzerfrage

Erst danach erzeugt das Sprachmodell die eigentliche Antwort.

Die KI ist damit die **Formulierungsinstanz**, nicht die eigentliche Wissensquelle.

---

# Architektur in vier Ebenen

## 1. Primärquellen

Primärquellen sind die fachlichen Eingaben des Systems:

- Dokumente
- Dokumentversionen
- aktive System-Prompts
- Modellkonfiguration
- optional externe Shopdaten

Diese Ebene bestimmt, **welches Wissen und welche Regeln** überhaupt verwendet werden dürfen.

---

## 2. Index- und Retrieval-Ebene

Diese Ebene erzeugt und verwaltet den Suchraum:

- `index.ndjson` als Chunk-Quelle
- `index_meta.json` als Struktur- und Governance-Metadaten
- `index_runtime.json` als Laufzeitstatus
- `vector.index` als FAISS-Index
- `tags.ndjson` und `vector_tags.index` für Tag-Routing

Diese Ebene ist für Suche, Relevanz und Reproduzierbarkeit zuständig.

---

## 3. Orchestrierungsebene

Diese Ebene verbindet alle Teile des Systems:

- Anfrageannahme
- URL-Auswertung
- Retrieval
- Intent-Erkennung
- Shop-Suche
- Prompt-Aufbau
- Streaming der Modellantwort
- Historienpersistenz

Zentrale Klasse für die Laufzeit ist hier insbesondere der `AgentRunner`.

---

## 4. Ausgabe- und UI-Ebene

Die Antwort wird per **Server-Sent Events (SSE)** gestreamt.

Dadurch erhält das Frontend die Ausgabe schrittweise, statt auf eine vollständige Blockantwort zu warten.

Der aktuelle Projektstand setzt für Browser-Streaming bevorzugt auf SSE.

---

# Wissensspeicher und Indexdateien

## index.ndjson

`index.ndjson` ist die zentrale Chunk-Datei des Systems.

Eigenschaften:

- NDJSON statt großes JSON-Array
- streamingfähig
- append-/rewrite-fähig
- geeignet für größere Bestände
- dient als operative Grundlage für den Vector-Rebuild

Jede Zeile repräsentiert einen Chunk-Datensatz.

---

## index_meta.json

`index_meta.json` beschreibt den strukturellen Zustand des Index.

Beispielhafte Inhalte:

- `index_version`
- `embedding_model`
- `embedding_dimension`
- `chunk_size`
- `chunk_overlap`
- `scoring_version`
- `index_format`
- `vector_backend`

Diese Datei ist wichtig für Guardrails.  
Wenn sich die Strukturparameter ändern, darf lokaler Ingest nicht einfach weiterlaufen.

---

## index_runtime.json

`index_runtime.json` enthält laufzeitbezogene Informationen zum aktuellen Indexzustand, zum Beispiel aktualisierte Chunk-Zählungen.

Diese Datei dient nicht als Primärquelle, sondern als technische Betriebsmetadatei.

---

## vector.index

`vector.index` ist der FAISS-Vektorindex des Systems.

Er wird nicht manuell gepflegt, sondern aus `index.ndjson` neu erzeugt.

---

## tags.ndjson und vector_tags.index

Neben dem Hauptindex existiert eine Tag-Ebene:

- `tags.ndjson`
- `vector_tags.index`

Diese wird für Tag-Routing bzw. thematische Vorselektion verwendet.

Sie ist eine ergänzende Routing-Schicht, kein Ersatz für das Hauptretrieval.

---

# Dokument-Lifecycle

## 1. Dokument anlegen

Ein Dokument wird als fachliche Einheit gespeichert.

## 2. Versionen verwalten

Dokumente besitzen Versionen.  
Diese Versionen sind der eigentliche inhaltliche Träger.

## 3. Aktivierung

Wird eine Version aktiviert, wird nicht einfach nur „ein Text ausgetauscht“, sondern ein definierter Prozess ausgelöst.

## 4. IngestJob

Die Aktivierung führt in die Ingest-Orchestrierung.

## 5. Chunk-Erzeugung

Aus der aktiven Version werden Chunk-Records erzeugt.

## 6. NDJSON-Update

Bestehende Chunks des betroffenen Dokuments werden entfernt und durch neue ersetzt.

## 7. Vollständiger Vector-Rebuild

Anschließend wird der gesamte FAISS-Index aus dem aktuellen NDJSON-Bestand neu gebaut.

---

# Ingest-Logik im aktuellen Stand

Der Ingest ist in mehrere spezialisierte Services getrennt.

## GuardrailValidator

Prüft, ob der aktuelle Indexzustand mit der erwarteten Struktur kompatibel ist.

Wenn nicht, wird lokaler Ingest blockiert.

---

## ChunkWriteService

Kapselt die Schreibvorgänge auf der Chunk-Ebene, insbesondere:

- Chunks zählen
- Chunks für ein Dokument entfernen
- neue Chunks anhängen
- gesamten NDJSON-Bestand neu schreiben

---

## VectorRebuildService

Verantwortet den vollständigen Rebuild des Vektorindex und die Aktualisierung der Runtime-Metadaten.

---

## IngestFlow

Der `IngestFlow` orchestriert den Gesamtprozess.

Für Dokument-Ingest bedeutet das insbesondere:

- Guardrail prüfen
- Status auf laufend setzen
- alte Dokument-Chunks entfernen
- neue Chunks streamingfähig anhängen
- Chunk-Limits überwachen
- Vector-Rebuild auslösen
- finalen Status setzen

---

# Guardrails und Reproduzierbarkeit

RetrieX schützt sich bewusst gegen strukturellen Drift.

Wenn sich zentrale Indexparameter ändern, etwa:

- Embedding-Modell
- Embedding-Dimension
- Chunk-Größe
- Chunk-Overlap
- Scoring-Version
- Indexformat

dann darf ein lokaler Ingest nicht stillschweigend in einen inkompatiblen Index hineinschreiben.

Stattdessen wird ein **Global Reindex** erforderlich.

Das verhindert inkonsistente Mischzustände.

---

# Global Reindex

Ein Global Reindex unterscheidet sich bewusst vom lokalen Dokument-Ingest.

Dabei passiert:

- alle aktiven Dokumente werden neu verarbeitet
- `index.ndjson` wird vollständig neu geschrieben
- der Vektorindex wird komplett neu gebaut
- die `index_version` wird erhöht

Der Global Reindex ist damit der kontrollierte Weg, strukturelle Änderungen sauber auf den gesamten Wissensbestand anzuwenden.

---

# Retrieval zur Anfragezeit

## Hybrid-Retrieval

Das aktuelle System verwendet kein rein lineares Suchmodell, sondern kombiniert mehrere Schritte:

- Query-Cleaning
- Query-Enrichment
- Intent-Erkennung
- Tag-Routing
- globale Vektorsuche
- optional gescopte Vektorsuche auf Kandidatendokumente
- Fusion und Auswahl relevanter Chunks

Das Ziel ist nicht einfach „mehr Treffer“, sondern **passendere, stabilere Kontexterzeugung**.

---

## Tag-Routing

Vor der eigentlichen Chunk-Auswahl kann das System thematisch passende Dokumente über Tags eingrenzen.

Das reduziert die Suchfläche und erhöht die Wahrscheinlichkeit, dass relevante Dokumente bevorzugt werden.

---

## Katalog-/Listenroute

Für bestimmte Anfragen erkennt das System, dass keine klassische Chunk-Antwort, sondern eher eine Listen- oder Katalogausgabe sinnvoll ist.

Dann kann statt normaler Chunk-Selektion ein Katalogblock erzeugt werden.

---

## Ergebnisbegrenzung

Die Zahl der zurückgegebenen Wissens-Chunks ist konfigurationsgetrieben.

Wichtige Steuergrößen sind:

- `retrievalMaxChunks`
- `retrievalVectorTopK`

Diese Werte stammen aus der aktiven Modell-/Generierungskonfiguration.

---

# Commerce-Erweiterung und Shop-Suche

Ein zentrales Merkmal des aktuellen Systemstands ist die **optionale Shopware-Store-API-Anbindung**.

Diese wird nicht immer verwendet, sondern nur dann, wenn die Anfrage nach Commerce-Logik aussieht.

## CommerceIntentLite

Die Anfrage wird heuristisch auf Commerce-Signale geprüft, zum Beispiel:

- Produktsuche
- Preisbezug
- Größen-/Farbhinweise
- SKU-ähnliche Nummern
- typische Produkt- oder Empfehlungsfragen

Das Ergebnis ist einer von drei Zuständen:

- `none`
- `product_search`
- `advisory_product_search`

---

## CommerceQueryParser

Wenn Commerce erkannt wird, wird die Nutzeranfrage deterministisch aufbereitet.

Dabei werden strukturierte Suchinformationen abgeleitet, etwa:

- Suchkern
- Preis
- Größe
- Farbe
- weitere Suchsignale

---

## ShopSearchService

Der `ShopSearchService` baut daraus eine Shopware-Store-API-Anfrage und mappt die Ergebnisse in ein internes, schlankes Produktformat.

Typische Produktinformationen sind dann:

- Name
- Produktnummer
- Hersteller
- Preis
- Verfügbarkeit
- URL
- Beschreibung
- Bild
- ausgewählte Zusatzinformationen

---

## Rolle der Shopdaten

Shopdaten werden im Prompt ausdrücklich als **authoritative for products** behandelt.

Das bedeutet:

- für reale Produktdaten sind Live-Shopdaten führend
- Wissens-Chunks bleiben unterstützend
- das System trennt damit Produktwahrheit und Dokumentwissen bewusst voneinander

---

## Balance zwischen Shop und Wissen

Wenn Commerce aktiv ist, wird die Zahl der Wissens-Chunks reduziert:

- bei `product_search` stärker
- bei `advisory_product_search` moderat

So soll verhindert werden, dass Shopdaten im finalen Prompt von allgemeinen Wissens-Chunks verdrängt werden.

---

# URL-Auswertung

Wenn die Nutzeranfrage eine URL enthält, kann RetrieX den Inhalt dieser URL zusätzlich extrahieren.

Dazu wird:

- die erste URL im Prompt erkannt
- der Inhalt geladen
- über Readability verarbeitet
- HTML entfernt
- Text normalisiert
- auf eine maximale Länge begrenzt

Der extrahierte Inhalt wird anschließend als zusätzlicher unterstützender Wissensblock in den Prompt aufgenommen.

Das ist hilfreich, wenn ein Nutzer auf eine konkrete externe Quelle verweist.

---

# Prompt-Aufbau

Der finale Prompt wird systematisch zusammengesetzt.

## 1. Systemblock

Der aktive System-Prompt wird aus der Datenbank geladen.

Er ist die führende Regel- und Verhaltensbasis des Modells.

---

## 2. Gesprächskontext

Frühere Nachrichten des Nutzers werden als autoritativer Konversationskontext eingebunden.

So bleibt der Dialog über mehrere Turns konsistent.

---

## 3. Live-Shop-Block

Wenn Shop-Ergebnisse vorliegen, werden diese als eigener Block eingebaut.

Sie sind für Produktfragen führend.

---

## 4. Retrieved Knowledge

Die ausgewählten Wissens-Chunks werden als unterstützender Wissensblock eingefügt.

---

## 5. URL-Content

Optional kommt zusätzlich extrahierter Webinhalt hinzu.

---

## 6. Nutzerfrage

Am Ende steht die aktuelle Benutzerfrage.

---

# Antwort-Streaming

Die Antwort wird nicht gesammelt und dann komplett ausgeliefert, sondern als Stream übertragen.

## AskSseController

Der `AskSseController` stellt den SSE-Endpunkt bereit.

Dabei werden:

- Buffer geleert
- Cookies weitergereicht
- SSE-Header gesetzt
- Daten als `data:`-Zeilen gesendet
- am Ende ein `done`-Event ausgeliefert

## Vorteil

Das Frontend kann Antworten live darstellen und laufend erweitern.

Das verbessert die Benutzererfahrung deutlich, besonders bei längeren Antworten.

---

# Conversation Context und Historie

RetrieX verwaltet Nutzerkontext über eine eigene Context-Schicht.

Dazu gehören insbesondere:

- Aufbau eines nutzerspezifischen Gesprächskontexts
- Einbindung früherer Turns in den Prompt
- Persistierung der finalen Antworthistorie

So kann das System nicht nur auf Einzelfragen, sondern auf fortlaufende Dialoge reagieren.

---

# Modell- und Antwortsteuerung

Ein Teil des Systemverhaltens wird über Modellkonfigurationen gesteuert.

Dazu gehören fachlich und technisch insbesondere:

- welches Modell verwendet wird
- wie Retrieval parametriert ist
- wie viele Chunks eingebunden werden
- wie breit die Vektorsuche sucht
- wie stark die Antwort durch System-Prompt und Kontext geprägt wird

Diese Konfiguration ist bewusst nicht „wild überschreibbar“, sondern an die aktiven Systemobjekte gebunden.

---

# Was Admins fachlich steuern

Aus Admin-Sicht wird nicht nur „die KI“ gesteuert, sondern ein ganzes Wissens- und Antwortsystem.

Steuerbar sind unter anderem:

- welche Dokumente im System existieren
- welche Version aktiv ist
- welche Ingest-Profile gelten
- wann Reindexing ausgelöst wird
- welcher System-Prompt aktiv ist
- welche Modellkonfiguration aktiv ist
- ob und wie Commerce integriert ist

---

# Was die Antwortqualität tatsächlich beeinflusst

Die Qualität der Antworten hängt direkt von mehreren Ebenen ab:

## 1. Dokumentqualität

Schlecht strukturierte oder inhaltlich schwache Dokumente führen zu schwachen Antworten.

## 2. Aktivierungslogik

Nur aktive Versionen zählen.  
Falsche Aktivierung bedeutet falscher Wissensstand.

## 3. Chunking

Chunk-Größe und Overlap beeinflussen, wie gut relevante Informationen später gefunden werden.

## 4. Retrieval-Konfiguration

Top-K, Auswahlgrenzen und Routing beeinflussen, welche Informationen überhaupt im Prompt landen.

## 5. System-Prompt

Der System-Prompt bestimmt Stil, Regelverhalten und Prioritäten der Ausgabe.

## 6. Commerce-Daten

Bei Produktfragen entscheidet die Qualität der Live-Shopdaten über die Produktwahrheit der Antwort.

---

# Grundprinzipien des Systems

RetrieX folgt im aktuellen Stand diesen Grundprinzipien:

- dokumentenzentriert statt modellzentriert
- deterministisch statt zufällig orchestriert
- reproduzierbar statt implizit
- governance-fähig statt unkontrolliert
- hybrid im Retrieval
- erweiterbar durch Shopdaten
- streamingfähig in der Ausgabe

---

# Was RetrieX ausdrücklich nicht ist

RetrieX ist im aktuellen Design:

- kein rein freier LLM-Chat
- kein ausschließlich kreatives Generierungssystem
- kein manuell gepflegter Chunk-Editor
- kein Produktkatalog ohne Wissenslogik
- kein rein vektorbasierter Blackbox-Sucher

Es ist ein **kontrolliertes Antwortsystem**, das Wissen, Routing, Produktdaten und Modellformulierung zusammenführt.

---

# Kurz zusammengefasst

RetrieX arbeitet im Kern so:

1. Dokumente und Versionen definieren den Wissensstand
2. Ingest erzeugt daraus NDJSON-Chunks
3. daraus wird der FAISS-Index vollständig neu aufgebaut
4. bei einer Anfrage laufen Retrieval, Routing und optional Commerce-Suche
5. PromptBuilder kombiniert Systemregeln, Kontext, Wissenschunks, URL-Inhalte und Shopdaten
6. das Modell formuliert daraus die Antwort
7. die Ausgabe wird per SSE ins Frontend gestreamt

Kurzform:

**Dokumente → Ingest → NDJSON → Vector Index → Retrieval → Prompt-Aufbau → LLM-Antwort → SSE-Streaming**

---

# Merksatz

> Sie steuern in RetrieX nicht einfach nur ein Modell.  
> Sie steuern die zugelassene Wissensbasis, die Suchlogik, die Antwortregeln und – bei Produktfragen – die produktbezogene Live-Datenquelle.

Die KI formuliert.  
RetrieX bestimmt, worauf sie sich dabei stützen darf.