MtoRagSystem/SYSTEM.md

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:

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:

python vector_search.py "query" 5

Rückgabe:

[
  { "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.