new readme and phase A markdown

2026-02-26 18:51:08 +01:00
parent 8a97bd41e6
commit 948849dd6d
3 changed files with 557 additions and 181 deletions
--- a/README.md
+++ b/README.md
@@ -1,8 +1,9 @@
 # RAG-System – Technische Projektdokumentation
-**Version:** 1.0  
+**Version:** 1.3  
 **Stand:** Februar 2026  
 **Autor:** mitho  
-**Status:** Verbindliche Referenzarchitektur (System Freeze)
+**Status:** Verbindliche Referenzarchitektur (System Freeze – Phase A abgeschlossen)  
+**Validiert gegen:** aktuelle rag.zip (vollständig geprüft)

 ---

@@ -11,163 +12,237 @@
 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:
+Kernmerkmale:

- Versionierte Dokumentverwaltung
+- Versionierte Dokumentverwaltung (immutable Primärquellen)
 - Deterministisches Chunking
 - NDJSON als Single Source of Truth
- Vollständigen FAISS-Rebuild
- Hybrid Retrieval (Keyword + Vector + Tag)
- Job-basierte Orchestrierung
+- Vollständiger FAISS-Rebuild aus NDJSON
+- Rein vektorbasiertes Retrieval (Chunks + optional Tags)
+- Job-basierte Orchestrierung (async)
 - Rollen- und Guardrail-Architektur
 - SSE-Streaming

+Wichtig (validiert im Code):  
+Es existiert **kein Keyword-Retrieval** mehr. Retrieval erfolgt ausschließlich über den Vector-Service (Chunks) mit optionalem Tag-Routing.
+
 ---

 # 2. Architekturüberblick

 ## 2.1 Systemebenen

-### 1. Admin-Ebene (Symfony Backend)
+### 1) Admin-Ebene (Symfony Backend)
+
+Verantwortlich für:
+
 - Dokumentverwaltung
 - Versionierung
+- Aktivierung von DocumentVersion
 - Tag-Management
- Job-Steuerung
+- Ingest-Jobs
+- Tag-Rebuild-Jobs
 - System-Prompt-Verwaltung
- KI-Endpoint-Konfiguration
+- KI-Modell-/Generierungs-Konfiguration
+- Security/Login

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

-### 3. Vector-Ebene (Python)
+### 2) Wissensebene (Index & Artefakte)
+
+Speicherpfad: `var/knowledge/`
+
+Artefakte:
+
+- `index.ndjson` (Single Source of Truth)
+- `index_meta.json` (Index-Struktur/Governance)
+- `index_runtime.json` (Runtime-Stats)
+- `tags.ndjson`
+- `vector.index`
+- `vector.index.meta.json`
+- `vector_tags.index`
+- `vector_tags.index.meta.json`
+
+Chunks sind vollständig ableitbar aus DocumentVersion.
+
+---
+
+### 3) Vector-Ebene (Python, FAISS)
+
+- Persistenter Vector-Service (FastAPI)
 - Embedding-Modell (lokal)
 - FAISS-Index (Chunks)
 - FAISS-Index (Tags)
- Persistenter Vector-Service
- CLI-Fallback
+- CLI-Fallback-Skripte
+- Control-Script für Install / Start / Stop / Reload / Status

-### 4. Agent-Ebene
- Retrieval-Fusion
+FAISS wird ausschließlich aus `index.ndjson` erzeugt.
+
+---
+
+### 4) Agent-Ebene
+
+- Retrieval über `NdjsonHybridRetriever`
+- Query-Cleaning nur für Retrieval
+- Optionales Tag-Routing
 - PromptBuilder
 - SSE-Streaming
- Chat-History-Verarbeitung
+- History-Verarbeitung

 ---

 # 3. Dokumentenarchitektur

-## 3.1 Primärquellen
+## 3.1 Primärquellen-Prinzip

 - Dokumente sind immutable.
 - Jede Änderung erzeugt eine neue DocumentVersion.
- Pro Dokument existiert genau eine aktive Version.
+- Genau eine Version pro Dokument ist aktiv.
+- Chunks sind abgeleitete Artefakte.
+- Keine manuelle Chunk-Manipulation.

-## 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
+## 3.2 Aktivierungsprozess (Async)
+
+1. Aktivierung einer DocumentVersion
+2. Erstellung eines IngestJob (Status: QUEUED)
+3. Async-Ausführung:
+
+bin/console mto:agent:ingest:run <jobId>
+
+4. IngestOrchestrator führt deterministisch aus:
+
+- Guardrail-Validierung
+- NDJSON Compaction by document_id
+- Chunking
+- Streaming Write
+- Vollständiger FAISS-Rebuild
+- Atomare Datei-Switches
+- Update von index_meta.json
+- Job-Status: COMPLETED / FAILED / ABORTED

 ---

 # 4. NDJSON-Architektur

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

- Streamingfähiges Format
- Kein JSON-Array
- Append-only mit Compaction
- Keine vollständige RAM-Verarbeitung
- Atomare Datei-Switches (.tmp → rename)
+Eigenschaften:
+
+- NDJSON (kein JSON-Array)
+- Streaming-fähig
+- Append + gezielte Compaction
+- Kein Full-RAM-Load
+- Atomare Dateioperationen
+
+FAISS wird immer vollständig aus index.ndjson neu gebaut.
+
+Es existiert keine zweite Wahrheitsquelle.
+
+---

 ## 4.2 index_meta.json

-Enthält:
+Struktur (validiert):

 - index_version
+- created_at
+- embedding_model
+- embedding_dimension
+- chunk_size
+- chunk_overlap
+- scoring_version
+- index_format (ndjson)
+- vector_backend (faiss)
+
+---
+
+## 4.3 Guardrail-Mechanismus
+
+Bei strukturellen Änderungen:
+
 - 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
+wird lokaler Ingest blockiert und ein Global Reindex erforderlich.

 ---

 # 5. Chunk-Management

-Verantwortlich: ChunkManager
+Verantwortlich: ChunkManager + Ingest-Services

 Eigenschaften:

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

 ---

 # 6. Vector-Architektur

-## 6.1 Betriebsmodi
+## 6.1 Persistenter Vector-Service (Standard)

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

-### B) CLI-Fallback
- Python-Skripte
- Wird genutzt, falls Service nicht verfügbar ist
+http://127.0.0.1:8090

-## 6.2 Rebuild-Strategie
+Endpoints:

- Immer vollständiger FAISS-Rebuild
- Kein inkrementelles Patchen
- Atomarer Index-Switch
- Deterministisch und drift-sicher
+- POST /search-chunks
+- POST /search-tags
+
+Control:
+
+bin/console mto:agent:vector:control --install
+bin/console mto:agent:vector:control --start
+bin/console mto:agent:vector:control --reload
+bin/console mto:agent:vector:control --status

 ---

-# 7. Hybrid Retrieval
+## 6.2 CLI-Fallback

-## 7.1 Retrieval-Komponenten
+Python-Skripte:

-1. Keyword-Retrieval (führend)
-2. FAISS-Chunk-Retrieval (ergänzend)
-3. Tag-Routing (Soft-Gate)
+- python/vector/vector_search.py
+- python/vector/vector_ingest.py
+- python/vector/vector_search_tags.py
+- python/vector/vector_ingest_tags.py

-## 7.2 Score-Fusion
+---

- Keyword hat Priorität
- Vector ergänzt semantische Nähe
- Tags dienen als Routing-Verstärker
+## 6.3 Rebuild-Strategie
+
+- Immer vollständiger FAISS-Rebuild
+- Kein inkrementelles Patchen
+- Atomarer Switch (.tmp → rename)
+- Deterministisch und reproduzierbar
+
+---
+
+# 7. Retrieval (Vector-only)
+
+Retrieval über `NdjsonHybridRetriever`.
+
+Ablauf:
+
+1) Query Cleaning (nur für Retrieval)
+2) Optional: Tag-Routing
+3) Chunk Vector Search
+4) NDJSON Chunk Lookup
+
+Keine Keyword-Suche im System vorhanden.

 ---

@@ -179,115 +254,123 @@ Eigenschaften:
 - DocumentTag
 - TagRebuildJob

-## 8.2 Trigger-Logik
+## 8.2 Trigger

-Ein Rebuild wird ausgelöst bei:
+Rebuild bei:

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

-## 8.3 Job-Mechanik
+## 8.3 Async-Ausführung

- Async-Start via:
-  ```
-  php bin/console mto:agent:tags:job:run <jobId>
-  ```
- Logfile unter:
-  ```
-  var/log/tags/job_<uuid>.log
-  ```
+php bin/console mto:agent:tags:job:run <jobId>
+
+Log:
+
+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)
+- QUEUED > 300 Sekunden → FAILED
+- Maximal 1 aktiver Job
+- Lockfile: var/knowledge/locks/tag_rebuild.lock

 ## 8.5 Tag-Index

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

 ---

 # 9. Job-Architektur

-Statusmodell:
+Status:

 - QUEUED
 - RUNNING
 - COMPLETED
 - FAILED
+- ABORTED (Ingest)

 Eigenschaften:

 - Async exec
- LockService gegen Parallel-Ausführung
- Self-Healing gegen blockierte Jobs
+- Locking gegen Parallel-Ausführung
 - Logging pro Job
+- Recovery bei stale Jobs

 ---

-# 10. Governance & Guardrails
+# 10. Vector Health

-## 10.1 Rollen
+Health-Check:
+
+bin/console mto:agent:vector:health
+
+Prüft:
+
+- NDJSON Chunk Count
+- FAISS Index Count
+- Meta-Konsistenz
+
+---
+
+# 11. Governance & Guardrails
+
+Rollen:

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

-## 10.2 Schutzmechanismen
+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
+- Immutable Dokumente
+- Versionierung statt Ersetzen
+- Keine Chunk-Editierung
+- Guardrail gegen Strukturdrift
+- Atomare Dateioperationen
+- Locking & Job-Orchestrierung
+- Logging & Audit

 ---

 # 12. Skalierbarkeit

-Zielgröße:
+Ausgelegt für:

- >120.000 Chunks
+≥ 120.000 Chunks

 Ermöglicht durch:

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

+Ab >300k Chunks sollte Sharding evaluiert werden.
+
 ---

-# 13. Stabilitätsstatus (Freeze-Zustand)
+# 13. Stabilitätsstatus

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

@@ -295,15 +378,19 @@ Ermöglicht durch:

 # 14. System-Freeze-Definition

-Dieses Dokument definiert den verbindlichen Referenzstand des Systems.
+Dieses Dokument definiert den verbindlichen Referenzstand.

-Ab diesem Punkt gilt:
+Ab jetzt gilt:

 - Keine strukturellen Änderungen ohne explizite Freigabe.
- Erweiterungen nur inkrementell.
- Keine Architektur-Rewrites.
+- Keine inkrementellen Vector-Patches.
+- Keine zweite Wahrheitsquelle neben index.ndjson.
+- Erweiterungen nur additiv.
+- Kein Architektur-Rewrite.
 - Determinismus und Reproduzierbarkeit sind oberstes Prinzip.

+Phase A ist abgeschlossen.
+
 ---

 # 15. Zusammenfassung
@@ -315,7 +402,14 @@ Das System ist:
 - governance-konform
 - skalierbar
 - blockiersicher
- debugbar
+- auditierbar
+- reproduzierbar
 - enterprise-ready

-Es erfüllt die Anforderungen an ein kontrolliertes, reproduzierbares RAG-System mit klarer Trennung zwischen Wissensquelle, Index, Retrieval und Generierung.
+Retrieval ist vollständig vektorbasiert (Chunks + optional Tags).
+
+Architekturfluss:
+
+Primärquelle → NDJSON → FAISS → Vector Retrieval → Prompt → Generierung
+
+Das System befindet sich im stabilen Freeze-Zustand.