# mitho AI Agent
**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:

```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.