MtoRagSystem/README.md

mitho AI Agent (Alpha Version)

Hybrid RAG System auf Symfony-Basis mit Vektor- & Keyword-Retrieval

---

Überblick

Der mitho AI Agent ist ein produktionsreifes, Symfony-basiertes RAG-System (Retrieval Augmented Generation), das KI nicht frei „raten“ lässt, sondern Antworten strikt auf Basis eines kontrollierten Wissenspools erzeugt.

Leitsatz:
„Wir nutzen KI nicht, um kreativ zu raten, sondern um verlässlich auf Basis Ihres Wissens zu antworten.“

Das System kombiniert:

• Large Language Model (LLM, z. B. Qwen via Ollama)
• Keyword-basiertes Retrieval
• FAISS-Vektor-Suche
• Versionierte Wissensstruktur (Chunks + Index)
• Streaming-Ausgabe via Server-Sent Events (SSE)
• Persistente Chat-Historie pro Client

---

Architektur

1. Backend

Technologie

• PHP 8.2+
• Symfony 7.4
• Monolog Logging
• Symfony Cache
• Session Support

Zentrale Komponenten

Komponente	Aufgabe
AgentRunner	Orchestriert Prompt, Kontext & LLM
PromptBuilder	Baut System- & User-Prompt
ContextService	Historienverwaltung
ChunkKeywordRetriever	Keyword-Scoring
VectorSearchClient	Python-FAISS-Anbindung
KnowledgeIngestService	Dokument → Chunks
ChunkIndexWriter	index.json Verwaltung
CachedRetriever	Performance-Optimierung

---

2. Hybrid Retrieval (Produktionsarchitektur)

Das System nutzt eine hybride Sucharchitektur:

A) Keyword-Retrieval (führend)

• Stopword-Filter
• Lemma-Logik
• Score-Berechnung
• deterministische Gewichtung

B) Vektor-Retrieval (ergänzend)

• SentenceTransformer: all-MiniLM-L6-v2
• FAISS Index (Inner Product)
• Normalisierte Embeddings
• Top-K Suche

Retrieval-Flow

1. User Prompt
2. Keyword-Scoring
3. FAISS-Suche
4. Score-Fusion
5. Top-N Chunks
6. Kontextaufbau
7. LLM-Antwort

---

3. Wissensarchitektur

var/knowledge/
 ├── uploads/
 ├── chunks/
 ├── manifest.json
 └── index.json

Prinzipien

• Dokumente sind Primärquelle
• Chunks sind abgeleitete Artefakte
• index.json ist Single Source of Truth
• Re-Ingest ist deterministisch
• Keine manuelle Chunk-Manipulation

---

4. Vektor-Ingest

CLI Command:

php bin/console mto:agent:vector:ingest

Ablauf:

1. index.json lesen
2. Chunk-Texte laden
3. Embeddings erzeugen
4. FAISS Index erstellen
5. vector.index speichern
6. vector_meta.json schreiben

---

5. LLM-Anbindung

Standardmäßig via Ollama.

Konfiguration über ENV:

AI_LLM_API_URL=
AI_LLM_MODEL=
AI_LLM_TIMEOUT=
AI_DEBUG=
AI_LOG_PROMPT=
AI_LOG_CONTEXT=
AI_HISTORY_DIR=

Features:

• Streaming-fähig
• Konfigurierbarer Timeout
• Denkmodus unterdrückbar
• Historienintegration

---

6. Frontend

Technologie:

• Bootstrap
• Marked (Markdown)
• DOMPurify
• SSE Streaming

Features:

• Live-Streaming
• Markdown-Rendering
• Abbruch-Funktion
• Chat-Verlauf
• Client-ID per Cookie
• Verlaufslöschung

---

7. Logging & Debug

Log-Datei:

var/log/agent.log

Optional aktivierbar:

• Prompt Logging
• Kontext Logging
• Debug-Modus

---

Sicherheit & Governance

• Rollenmodell (Super Admin / Knowledge Admin / Redaktion)
• Versionierte Dokumente
• Versionierte Ingest-Profile
• Versionierte System-Prompts
• KI-Endpunkt abstrahiert
• Audit-Logs
• Lock-Mechanismen bei Reindex

---

Produktstatus

Das System ist:

• Produktionsreif
• Framework-neutral
• Kundenfähig
• Skalierbar
• Erweiterbar (Adminbereich geplant)

Nicht enthalten:

• Autonomes Fine-Tuning
• Live-Lernsystem
• Self-Modifying Knowledge

---

Unterschied zu generischen KI-Tools

Generische KI	mitho AI Agent
trainiert auf Internet	basiert auf Ihrem Wissen
keine Governance	volle Kontrolle
keine Versionierung	Dokument-Versionierung
nicht nachvollziehbar	transparente Wissensbasis
generisch	unternehmensspezifisch

---

Mindestanforderungen

• PHP 8.2+
• Python 3.9+
• faiss
• sentence-transformers
• Ollama (oder kompatibles LLM)

---

Vision

Dieses System bildet die Grundlage für:

• Agentic Commerce
• Interne Wissenssysteme
• Support-Automatisierung
• Vertriebsassistenz
• Technische Dokumentations-KI
• DSGVO-konforme Unternehmens-KI

---

Fazit

Der mitho AI Agent ist kein Spielzeug-Chatbot.

Er ist ein strukturiertes, kontrolliertes KI-System mit klarer Wissensbasis, deterministischem Retrieval und professioneller Architektur – gebaut für produktiven Unternehmenseinsatz.