harden code and add messenger services and ne README.md and SYSTEM.,d

2026-02-15 14:36:04 +01:00
parent 993531b268
commit 5b100039e0
8 changed files with 865 additions and 215 deletions
--- a/SYSTEM.md
+++ b/SYSTEM.md
@@ -0,0 +1,334 @@
+# mitho AI Agent
+Enterprise Hybrid RAG System (Symfony + NDJSON + FAISS)
+
+---
+
+## Überblick
+
+Der **mitho AI Agent** ist ein deterministisches, governance-stabiles Enterprise-RAG-System auf Symfony-Basis.
+
+Es kombiniert:
+
+- Versionierte Dokumente
+- Streaming-NDJSON-Index
+- Deterministischen Full-Vector-Rebuild
+- Keyword- + Vektor-Hybrid-Retrieval
+- Rollen- und Governance-Modell
+- Lock- und Guardrail-Mechanismen
+- Produktionsfähige Adminoberfläche
+
+> „Wir nutzen KI nicht, um kreativ zu raten, sondern um verlässlich auf Basis Ihres Wissens zu antworten.“
+
+---
+
+# Architektur (Enterprise-Version)
+
+## 1. Kernprinzipien
+
+- Dokumente sind immutable Primärquellen
+- index.ndjson ist Single Source of Truth
+- FAISS wird IMMER vollständig aus index.ndjson neu gebaut
+- Keine partiellen Vektor-Updates
+- Strukturänderungen erzwingen Global Reindex
+- Atomare Switch-Strategie (.tmp + rename)
+- >200k Chunks skalierbar
+- Kein Full-JSON-RAM-Load
+
+---
+
+# Wissensarchitektur
+
+```
+var/knowledge/
+ ├── uploads/
+ ├── chunks/
+ ├── index.ndjson
+ ├── index_meta.json
+ ├── vector.index
+ └── vector_meta.json
+```
+
+---
+
+# Indexstruktur
+
+## index.ndjson
+
+- Streamingfähig
+- Eine Zeile = ein Chunk
+- JSON pro Zeile
+- Enthält:
+    - chunk_id
+    - document_id
+    - version
+    - text
+    - meta
+
+NDJSON ersetzt das frühere index.json (kein Array mehr).
+
+---
+
+# Index Meta
+
+`index_meta.json` enthält:
+
+- index_version
+- embedding_model
+- embedding_dimension
+- chunk_size
+- overlap
+- scoring_version
+- index_format
+
+Wird verwaltet durch:
+
+- `IndexMetaManager`
+- `IndexConfiguration`
+
+---
+
+# Ingest-Architektur
+
+## Zentrale Klassen
+
+| Klasse | Aufgabe |
+|--------|----------|
+| `DocumentService` | Dokumentverwaltung |
+| `DocumentVersionRepository` | Versionierung |
+| `KnowledgeIngestService` | Chunk-Erstellung |
+| `ChunkManager` | NDJSON Append + Compaction |
+| `SimpleChunker` | deterministische Text-Splittung |
+| `TextNormalizer` | Normalisierung |
+| `StopWords` | Stopword-Filter |
+| `IngestFlow` | Ablaufsteuerung |
+| `IngestOrchestrator` | Gesamtkoordination |
+| `IngestJobService` | Job-Verwaltung |
+| `LockService` | Reindex-Lock-Mechanismus |
+| `IndexMetaManager` | Index-Metadaten |
+| `IndexStructureChangedException` | Guardrail bei Strukturdrift |
+
+---
+
+# Ingest-Typen
+
+## 1. Lokaler Ingest
+
+- Neue Dokumentversion
+- Alte Chunks der document_id werden kompakt entfernt
+- Neue Chunks werden appended
+- Danach vollständiger FAISS-Rebuild
+- index_version bleibt gleich
+
+## 2. Global Reindex
+
+- Alle aktiven Dokumente neu ingestieren
+- index.ndjson komplett neu schreiben
+- FAISS komplett neu bauen
+- index_version++
+
+---
+
+# Vektor-Architektur
+
+## vector_ingest.py
+
+Buildet FAISS vollständig aus index.ndjson.
+
+Eigenschaften:
+
+- Streaming NDJSON read
+- normalize_embeddings=True
+- IndexFlatIP (Inner Product)
+- Batch-Size 64
+- Modell konfigurierbar
+
+Aufruf:
+
+```bash
+python vector_ingest.py --index path/to/index.ndjson --out path/to/vector.index
+```
+
+Keine inkrementellen Updates. Immer Full-Rebuild.
+
+---
+
+## vector_search.py
+
+- Nimmt Query + Limit
+- Lädt vector.index
+- Lädt vector_meta.json
+- Gibt JSON mit chunk_id + score zurück
+
+Aufruf:
+
+```bash
+python vector_search.py "query" 5
+```
+
+Rückgabe:
+
+```json
+[
+  { "chunk_id": "...", "score": 0.83 }
+]
+```
+
+---
+
+# Hybrid Retrieval
+
+## Komponenten
+
+| Klasse | Aufgabe |
+|--------|----------|
+| `NdjsonHybridRetriever` | Score-Fusion |
+| `NdjsonKeywordSearch` | Keyword-Scoring |
+| `NdjsonChunkLookup` | Chunk-Resolving |
+| `VectorSearchClient` | Python-Bridge |
+| `CachedRetriever` | Cache Layer |
+
+---
+
+## Retrieval Flow
+
+1. Prompt
+2. Keyword-Ranking
+3. FAISS Top-K
+4. Score-Fusion
+5. Final Chunk-Auswahl
+6. Kontextaufbau
+7. LLM-Antwort
+
+Keyword bleibt führend.
+Vektor ergänzt semantisch.
+
+---
+
+# Dokument-Extraktion
+
+Unterstützt via:
+
+- `DocumentExtractorInterface`
+- `ExtractorResolver`
+- `PdfExtractor`
+- `DocumentLoader`
+
+PDFs werden robust extrahiert und normalisiert.
+
+---
+
+# Adminbereich (Symfony)
+
+Controller:
+
+- `DashboardController`
+- `DocumentController`
+- `IngestJobController`
+- `SecurityController`
+
+Entities:
+
+- `Document`
+- `DocumentVersion`
+- `IngestJob`
+- `User`
+
+Repositories:
+
+- `DocumentVersionRepository`
+- `UserRepository`
+
+Rollenmodell:
+
+- Super Admin
+- Knowledge Admin
+- Redaktion
+- Frontend User
+
+---
+
+# Guardrails & Sicherheit
+
+- Lock bei Reindex
+- Strukturdrift-Erkennung
+- Keine Live-Änderung von Ingest-Profilen
+- Deterministische Rebuilds
+- Atomare Datei-Switches
+- NDJSON niemals vollständig im RAM
+
+---
+
+# LLM-Integration
+
+- Ollama oder kompatibler Endpoint
+- Streaming via SSE
+- Historienverwaltung
+- Prompt-Versionierung
+- Kontextkontrolle
+
+---
+
+# Performance-Merkmale
+
+- Streaming NDJSON
+- Kein JSON-Array-Load
+- Deterministischer FAISS-Rebuild
+- Cache-Layer
+- >200k Chunks skalierbar
+
+---
+
+# Mindestanforderungen
+
+Backend:
+- PHP 8.2+
+- Symfony 7.x
+
+Python:
+- Python 3.9+
+- faiss
+- sentence-transformers
+
+Optional:
+- Ollama
+
+---
+
+# Produktstatus
+
+Enterprise-ready:
+
+- Governance-stabil
+- Drift-sicher
+- Deterministisch reproduzierbar
+- Skalierbar
+- Adminfähig
+- Rollenbasiert
+
+---
+
+# Positionierung
+
+Dieses System ist keine generische KI.
+
+Es ist:
+
+- kontrolliert
+- versioniert
+- reproduzierbar
+- auditierbar
+- enterprise-tauglich
+
+---
+
+# Fazit
+
+Der mitho AI Agent ist ein kontrolliertes Enterprise-RAG-System mit:
+
+- NDJSON-Streaming-Index
+- deterministischem Vector-Rebuild
+- Hybrid-Retrieval
+- Guardrail-Mechanismen
+- Symfony-Admin-Governance
+
+Er ist gebaut für produktiven, langfristigen Unternehmenseinsatz.