MtoRagSystem/RAG_SYSTEM_OVERVIEW.md

# RAG_SYSTEM_OVERVIEW.md

# RetrieX v1.6.0 – 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. Version 1.6.0 beschreibt den aktuellen Stand aus RAG-Kern, Commerce-Erweiterung, Chat-/Admin-Trennung, Rollenmodell und Governance-Guardrails.

Das bedeutet:

- Antworten sollen nicht frei erfunden werden.
- Wissen stammt primär aus aktivierten Dokumentversionen.
- Die KI formuliert auf Basis von abgerufenem Kontext.
- Bei Produktanfragen können Live-Shopdaten einbezogen werden.
- Chat- und Adminzugang sind rollenbasiert getrennt.
- Konfigurierbare Fachlogik liegt überwiegend in YAML statt im PHP-Core.

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

- versionierten Wissensdokumenten
- deterministischem Ingest
- hybridem Retrieval
- optionaler Commerce-Erweiterung
- LLM-basierter Antwortformulierung
- SSE-basierter Browserausgabe
- rollenbasierter Betriebs- und Administrationslogik

---

# Die Hauptbausteine des Systems

## 1. Dokumente als Wissensbasis

Die Wissensbasis besteht aus hochgeladenen Dokumenten, aktuell verifiziert für:

- PDF
- TXT
- Markdown

Diese Dokumente werden nicht direkt zur Laufzeit vollständig 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. Runtime-Metadaten werden aktualisiert.
6. Der Status der Version wird auf `INDEXED` gesetzt.

Der Ingest ist bewusst deterministisch aufgebaut. Derselbe Datenstand soll 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:

- Query Cleaning
- Query Enrichment
- Intent-Erkennung
- Tag-Routing zur Kandidatendokument-Vorselektion
- FAISS-Vektor-Retrieval
- optionale gescopte Suche auf Kandidatendokumente
- Score- und RRF-basierte Fusion
- Sonderroute für Katalog-/Listenanfragen
- Präzisionsrouten für exakte Tabellen-/Grenzwert-/Indikatorfragen
- 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

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

---

## 5. Chat, Admin und Betrieb

Version 1.6.0 trennt den öffentlichen Chat-Einstieg architektonisch vom Adminbereich:

- Chat: `/`, `/chat`, `/chat/login`, `/chat/logout`
- Chat-APIs: `/ask-jobs`, `/ask-sse`, `/ask-sse/{jobId}`, `/history`, `/chat-messages/frontend`
- Admin: `/admin...`

Beide Bereiche nutzen denselben User-Provider, aber getrennte Firewalls und Rollenregeln. Dadurch kann ein Benutzer z. B. nur Chatrechte, nur Adminbasisrechte oder erweiterte Adminrechte besitzen.

---

# Architektur in fünf Ebenen

## 1. Primärquellen

Primärquellen sind die fachlichen Eingaben des Systems:

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

Diese Ebene bestimmt, welches Wissen und welche Regeln 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
- Client-ID-Auflösung
- Gesprächskontext
- URL-Auswertung
- Retrieval
- Intent-Erkennung
- Shop-Suche
- Query-Reparatur
- Prompt-Aufbau
- Streaming der Modellantwort
- Historienpersistenz

Zentrale Laufzeitklasse ist `AgentRunner`.

---

## 4. Ausgabe- und UI-Ebene

Die Antwort wird per Server-Sent Events gestreamt.

Die UI kann anzeigen:

- laufende Statusphasen
- Datenbasis und Confidence-Hinweise
- RAG-/Shop-Quellen
- Shopkarten
- gesendete Shopquery oder Einzelqueries
- Follow-up-Actions wie Preis anzeigen, nur Zubehör anzeigen oder technische Details anzeigen

Seit den neueren v1.6.0-Patches sind Follow-up-Actions kontextsensitiver und vermeiden Selbstloops, wenn dieselbe Shopquery bereits ausgeführt wurde.

---

## 5. Betriebs- und Governance-Ebene

Diese Ebene umfasst:

- Chat-/Admin-Firewalls
- Rollenmatrix
- Admin-Userverwaltung
- Aktiv-/Inaktiv-Loginprüfung
- Access-Denied-Handler
- 403/404/500-Fehlerseiten
- Konfigurationsvalidierung
- Source-Audit
- Core-Pattern-Audit
- Regressionstests

Damit wird RetrieX nicht nur fachlich, sondern auch organisatorisch betreibbar.

---

# 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
- 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 Strukturparameter ändern, darf lokaler Ingest nicht einfach weiterlaufen.

---

## `index_runtime.json`

`index_runtime.json` enthält laufzeitbezogene Informationen zum aktuellen Indexzustand, z. B. Chunk-Zählungen und Rebuild-Zeitpunkte.

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`
- `vector_tags.index.meta.json`

Diese Ebene unterstützt Tag-Routing und Kandidatendokument-Vorselektion.

---

# Dokument-Lifecycle

## 1. Dokument anlegen

Ein Dokument wird als fachliches Objekt im Adminbereich gepflegt.

## 2. Versionen verwalten

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

## 3. Aktivierung

Wird eine Version aktiviert, wird ein definierter Prozess ausgelöst. Die aktive Version bestimmt den Wissensstand des Dokuments.

## 4. IngestJob

Ingest-Jobs führen den Verarbeitungsprozess nachvollziehbar aus.

## 5. Chunk-Erzeugung

Aus der aktiven Version werden Chunk-Records erzeugt.

## 6. NDJSON-Update

Der Chunk-Bestand wird dokumentbezogen aktualisiert.

## 7. Vollständiger Vector-Rebuild

Nach relevanten Ingest-Schritten wird der FAISS-Index vollständig neu aufgebaut.

---

# Ingest-Logik

## `GuardrailValidator`

Prüft, ob der bestehende Index strukturell zur aktiven Konfiguration passt.

## `ChunkWriteService`

Kapselt Schreiboperationen auf `index.ndjson`.

## `VectorRebuildService`

Baut den Vektorindex neu und aktualisiert Runtime-Metadaten.

## `IngestFlow`

Orchestriert Einzel-Ingest, Global Reindex und Lösch-/Reset-Flows.

---

# Guardrails und Reproduzierbarkeit

RetrieX schützt sich gegen strukturellen Drift.

Lokaler Ingest darf nicht weiterlaufen, wenn sich z. B. diese Strukturparameter geändert haben:

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

Dann ist ein Global Reindex erforderlich.

---

# Global Reindex

Der Global Reindex baut den operativen Wissensbestand aus den aktiven Dokumentversionen neu auf.

Ziel:

- konsistenter Chunk-Bestand
- konsistenter Vektorindex
- aktualisierte Runtime-Metadaten
- reproduzierbarer Systemzustand

In v1.6.0 ist der Global-Reindex-Zugriff serverseitig und im Admin-UI auf `ROLE_SUPER_ADMIN` eingeschränkt.

---

# Retrieval zur Anfragezeit

## Hybrid-Retrieval

Der aktive Retriever kombiniert mehrere Signale:

- bereinigte Nutzerfrage
- Query-Enrichment-Regeln
- Intent-Routing
- Vektortreffer
- Tag-Routing
- gescopte Suche
- RRF-/Score-Fusion
- dokumentbezogene Begrenzung

## Tag-Routing

Tags können Kandidatendokumente vorselektieren. Dadurch kann die spätere Vektorsuche fokussierter laufen.

## Katalog-/Listenroute

Katalog- oder Listenfragen können direkt in einen Katalogblock führen, statt nur einzelne Textchunks zu liefern.

## Ergebnisbegrenzung

Parameter aus `retrieval.yaml`, `model.yaml` und `prompt.yaml` begrenzen Kandidaten, Chunks und Promptbudget.

---

# Commerce-Erweiterung und Shop-Suche

## `CommerceIntentLite`

Erkennt, ob eine Anfrage Commerce-Relevanz hat.

Mögliche Zustände:

- keine Commerce-Suche
- Produktsuche
- beratende Produktsuche

## `CommerceQueryParser`

Bereinigt und normalisiert Shopqueries:

- bekannte Marken behalten
- Bedienphrasen entfernen
- Tippfehler korrigieren
- Token kanonisieren
- Kontext-/Preservation-Tokens erhalten
- Preis-/Farb-/Größenmuster erkennen

## `ShopSearchService`

Führt die Shopware-Suche aus und kann Repair-Queries nachschieben, wenn primäre Treffer fehlen oder zu ungenau sind.

## Rolle der Shopdaten

Shopdaten sind für Produktinformationen autoritativ, insbesondere für:

- Produktname
- Artikelnummer
- Preis
- Verfügbarkeit
- Hersteller
- Shop-URL
- Shop-Beschreibung und Custom Fields

## Balance zwischen Shop und Wissen

Shopdaten ersetzen nicht automatisch fachliche Eignungsbelege. Bei technischen Eignungsfragen müssen RAG-Kontext, Shopdaten und Prompt-Guardrails zusammenpassen.

---

# v1.6.0 Commerce- und Follow-up-Guards

Version 1.6.0 enthält mehrere Präzisionsmechanismen:

- Direkte Produktnamen werden in Shopqueries erhalten.
- Noise-Tokens wie reine Bedien-, Relations- oder Denkmarker werden entfernt.
- Tippfehler wie `schwinnbad` können zu `schwimmbad` korrigiert und erhalten werden.
- Modellkürzel wie `LAB CL` bleiben erhalten, wenn sie im konfigurierten Kontext auftreten.
- generische Geräteanfragen können auf exakte fachliche Produktanker aufgelöst werden, z. B. bei SiO2/Silikat.
- Produktlisten-Follow-ups werden in einzelne Produktqueries aufgeteilt.
- Produktanker-Kanonisierung ist YAML-gestützt statt im PHP-Core hartcodiert.
- Exakte Zubehörcodes werden als exakte Codes behandelt.
- Preis-Folgeaktionen verwenden sichtbare Produktidentitäten mit Produktnummern.
- Schwache referenzielle Shopqueries können auf History-Modellanker zurückfallen.

---

# URL-Auswertung

`UrlAnalyzer` extrahiert Inhalt aus der ersten URL in einer Nutzerfrage.

Der Inhalt wird als unterstützende Quelle in den Prompt aufgenommen, nicht als Primärindex gespeichert.

---

# Prompt-Aufbau

Der final zusammengesetzte Prompt kann enthalten:

## 1. Systemblock

Aktiver System-Prompt.

## 2. Gesprächskontext

Historie des Nutzers, regulär oder explizit als Full-Context.

## 3. Live-Shop-Block

Shopware-Produkte mit Produktnummer, Preis, Verfügbarkeit, Hersteller, URL und weiteren Feldern.

## 4. Retrieved Knowledge

RAG-Chunks aus `index.ndjson`.

## 5. URL-Content

Optional extrahierter Inhalt einer URL.

## 6. Nutzerfrage

Aktuelle Frage.

---

# Antwort-Streaming

## `AskSseController`

Der Controller stellt zwei Streaming-Wege bereit:

- Job-basierter Flow: `POST /ask-jobs` plus `GET /ask-sse/{jobId}`
- direkter Flow: `POST /ask-sse`

Der Job-basierte Flow unterstützt Statusabfrage, Event-IDs, Replay/Tailing und Stale-Erkennung.

## Vorteil

Der Browser erhält schrittweise Ausgabe und kann Statusinformationen, Shopkarten und Folgeaktionen während bzw. nach der Antwort anzeigen.

---

# Conversation Context und Historie

`ContextService` speichert abgeschlossene Turns pro Client-ID.

Aktuelle Standardwerte:

- regulär: 25 Zeilen
- Full-Context: 500 Zeilen

Full-Context ist nicht mehr implizit der Browserstandard, sondern muss ausdrücklich angefordert werden.

---

# Security und Rollenmodell

## Firewalls

`config/packages/security.yaml` definiert getrennte Firewalls:

- `admin` für `^/admin`
- `chat` für Chat-, Ask-, SSE-, History- und Frontend-Message-Routen
- `main` für sonstige öffentliche/statische Ressourcen

## Rollenmatrix

| Bereich | Effektive Rolle |
| --- | --- |
| Chat, Ask/SSE, History, Frontend-Messages | `ROLE_CHAT_USER` |
| Admin-Dashboard, Guides, Jobs | `ROLE_ADMIN_AREA` |
| Dokumente, Versionen, Tags, Dokument-Ingest | `ROLE_EDITOR` |
| Modell-/Retrieval-Konfiguration, Ingest-Profile ansehen | `ROLE_KNOWLEDGE_ADMIN` |
| Userverwaltung, Logs, System Prompt/Agent, Global Reindex, Reset/Delete | `ROLE_SUPER_ADMIN` |

`ROLE_USER` alleine reicht für keinen Bereich.

---

# Admin-Bereich

Admins können je nach Rolle steuern:

- Dokumente und Versionen
- Tags und Tag-Zuweisungen
- Ingest-Jobs
- Global Reindex
- Modell-/Retrieval-Konfiguration
- Ingest-Profile
- System Prompt
- System Agent
- Logs
- Benutzerverwaltung

Die Admin-Navigation blendet Aktionen passend zur Rolle aus. Serverzugriffe sind zusätzlich über `access_control` und Controller-Checks geschützt.

---

# Userverwaltung

Die Userverwaltung in v1.6.0 umfasst:

- Liste, Anlage und Bearbeitung von Benutzern
- Rollenzuweisung
- Passwortsetzen
- Aktiv-/Inaktiv-Schaltung
- Self-Protection
- Schutz des letzten aktiven Super-Admins
- Loginblock für deaktivierte Benutzer
- Session-Abmeldung für nachträglich deaktivierte Benutzer

---

# Fehlerseiten und Access Denied

RetrieX rendert konsistente Fehlerseiten für:

- 403
- 404
- 500
- generische Fehler

Der Access-Denied-Handler unterscheidet Chat- und Adminbereich und zeigt die benötigte Rolle sowie sinnvolle Rücksprung- und Logout-Optionen.

---

# Modell- und Antwortsteuerung

Die Antwortqualität wird gesteuert durch:

- aktiven System-Prompt
- `prompt.yaml`
- `model.yaml`
- `retrieval.yaml`
- `language.yaml`
- `vocabulary.yaml`
- `commerce.yaml`
- `search_repair.yaml`
- `agent.yaml`
- `genre.yaml`
- `chat-messages.yaml`

Viele fachliche Listen liegen bewusst in YAML und nicht hartcodiert im PHP-Core.

---

# Was Admins fachlich steuern

Admins und Knowledge-Admins steuern je nach Rolle:

- welche Dokumentversion aktiv ist
- wann ingestiert oder reindiziert wird
- welche System-Prompts aktiv sind
- welche Modellkonfiguration genutzt wird
- welche Ingest-Profile sichtbar bzw. aktiv sind
- welche Benutzer Zugriff auf Chat oder Admin haben

---

# Was die Antwortqualität tatsächlich beeinflusst

## 1. Dokumentqualität

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

## 2. Aktivierungslogik

Nur aktive Versionen zählen.

## 3. Chunking

Chunkgröße und Overlap beeinflussen, wie viel Kontext pro Treffer verfügbar ist.

## 4. Retrieval-Konfiguration

Schwellenwerte, Routing, Tag-Suche, Query-Enrichment und Ergebnisbegrenzung bestimmen den Kontext.

## 5. System-Prompt und Prompt-Regeln

Diese Regeln bestimmen, wie das Modell mit Wissen, Shopdaten, Unsicherheit und Quellen umgeht.

## 6. Commerce-Daten

Shopware-Daten beeinflussen Produkt-, Preis-, Verfügbarkeits- und Linkantworten.

## 7. Rollen und UI-Flows

Rollen, Loginstatus und Access-Denied-Verhalten bestimmen, welche Nutzer welche Funktionen erreichen.

---

# Grundprinzipien des Systems

- Keine freie Wissensbehauptung ohne Datenbasis.
- Aktive Dokumentversionen sind fachliche Primärquelle.
- Shopdaten sind autoritativ für Produkt-/Preis-/Verfügbarkeitsdaten.
- Technische Eignung darf nicht aus Shopdaten allein überinterpretiert werden.
- YAML ist Source of Truth für konfigurierbare Fachlogik.
- PHP-Core soll Orchestrierung leisten, nicht Domainlisten verstecken.
- Rollen müssen UI-seitig und serverseitig konsistent sein.
- Regressionstests schützen bekannte stabile Flows.

---

# Was RetrieX ausdrücklich nicht ist

RetrieX ist nicht:

- ein frei improvisierender Chatbot
- ein Ersatz für Datenpflege
- ein Ersatz für validierte technische Beratung in Grenzfällen
- ein manuell gepflegter Chunk-Editor
- ein Shop-Scraper
- ein unkontrollierter Prompt-Wrapper um ein LLM

---

# Kurz zusammengefasst

1. Dokumente und Versionen definieren den Wissensstand.
2. Ingest erzeugt Chunks und FAISS-Indizes.
3. Retrieval sucht gezielt Kontext.
4. Commerce kann Shopware-Daten ergänzen.
5. PromptBuilder setzt Systemregeln, Kontext, Shopdaten und Frage zusammen.
6. Das LLM formuliert die Antwort.
7. SSE streamt die Antwort ins Frontend.
8. Rollen und Adminlogik steuern Zugriff und Betrieb.
9. YAML- und Audit-Guardrails schützen die Wartbarkeit.

---

# Merksatz

RetrieX v1.6.0 ist kein Chatbot mit Dokumentanhang, sondern eine kontrollierte Antwortinfrastruktur aus Wissen, Suche, Shopdaten, Rollenmodell und Governance.