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