add complete readme beta

README.md

@@ -1,3 +1,250 @@
-# MtoRagSystem
+# mitho AI Agent
+**Hybrid RAG System auf Symfony-Basis mit Vektor- & Keyword-Retrieval**
 
-KI-Rag System portiert von der mitho python rag Anwendung
+---
+
+## Ü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:
+
+```bash
+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.