mitho AI Agent – Developer README

Enterprise Hybrid RAG System (Symfony + NDJSON + FAISS + Persistent Vector Service)

Stand: Februar 2026
Status: Produktiv stabil – Job-basierte Ingest-Architektur + Persistenter Vector-Service integriert

---

1. Systemüberblick

Dieses System implementiert eine deterministische, governance-stabile
Hybrid-RAG-Architektur mit:

• Symfony (PHP Backend)
• NDJSON als Single Source of Truth
• FAISS als Vektorindex (immer Full Rebuild)
• Persistenter Python Vector-Service (FastAPI + Uvicorn)
• Hybrid Retrieval (Keyword + Vektor)
• Versioniertes Dokumentmodell
• Job-basierte Ingest-Pipeline
• Lock-geschützte Reindex-Operationen
• SSE-Streaming im Frontend

Grundprinzip:

• Keine inkrementellen Vektor-Updates
• FAISS wird immer vollständig aus index.ndjson neu gebaut
• Retrieval läuft über einen persistenten Service (kein Python-Spawn pro Anfrage)

---

2. Architekturprinzipien

2.1 Determinismus

• Gleiche Dokumente + gleiche Konfiguration → identisches index.ndjson
• Gleiches index.ndjson → identisches FAISS
• Gleiche Query → identisches Retrieval-Ergebnis

2.2 Governance

• Eine aktive Version pro Dokument
• Keine impliziten Index-Änderungen
• Strukturänderungen erzwingen Global Reindex
• Keine Selbstmodifikation durch KI

2.3 Skalierbarkeit

• NDJSON (streamingfähig)
• Kein RAM-basiertes JSON-Array
• Zielgröße > 200k Chunks
• FAISS Full Rebuild ist deterministisch

---

3. Wissensspeicher

3.1 index.ndjson

Single Source of Truth.

• 1 JSON-Objekt pro Zeile
• Streaming-Append
• Deterministische Compaction by document_id

Beispielstruktur:

{
  "chunk_id": "uuid",
  "document_id": "uuid",
  "document_version_id": "uuid",
  "text": "...",
  "meta": { ... }
}

Regeln:

• Keine JSON-Array-Datei
• Keine Mutation einzelner Chunks
• Nur Append + deterministische Entfernung per document_id

---

3.2 index_meta.json

Strukturparameter:

• index_version
• embedding_model
• embedding_dimension
• chunk_size
• chunk_overlap
• scoring_version
• index_format
• vector_backend

Wenn einer dieser Werte sich ändert:

→ Global Reindex zwingend erforderlich

---

3.3 FAISS

Dateien:

• vector.index
• vector.index.meta.json
• vector_tags.index
• vector_tags.index.meta.json

FAISS wird IMMER vollständig aus index.ndjson gebaut.

Keine Partial Updates.
Kein inkrementelles Vector-Append.

---

4. Persistenter Vector-Service

Retrieval läuft nicht mehr über:

• Symfony Process
• exec()
• python vector_search.py pro Anfrage

Sondern über:

FastAPI + Uvicorn (persistent im RAM)

4.1 Eigenschaften

Beim Start lädt der Service:

• Embedding-Modell
• Chunk-Index
• Tag-Index
• ID-Mappings

Diese bleiben dauerhaft im RAM.

Kein Modell-Reload pro Anfrage.
Kein Disk-Reload pro Anfrage.
Kein Python-Spawn pro Anfrage.

4.2 Endpoints

• GET /health
• POST /search-chunks
• POST /search-tags
• POST /reload

4.3 Reload-Mechanismus

Nach Global Reindex:

curl -X POST http://127.0.0.1:8090/reload

Lädt:

• Chunk-Index neu
• Tag-Index neu
• Modell nur wenn embedding_model geändert wurde

Kein Neustart nötig.
Keine Downtime.

---

5. Score-Gates (Routing-Sicherheit)

5.1 Tag-Gate

Tags steuern Routing.

Empfohlener Mindestscore:

MIN_SCORE ≈ 0.70

Schützt vor:

• zufälligen semantischen Treffern
• falschem Dokumentrouting

5.2 Chunk-Gate

Chunks sind Kontext.

Weicher Gate:

MIN_SCORE ≈ 0.50

Optional: relativer Score zum besten Treffer.

---

6. Dokument- & Versionsmodell

Document
→ enthält mehrere DocumentVersion
→ genau eine Version ist aktiv

Regel:

Es darf immer nur eine aktive Version pro Dokument existieren.

Beim Aktivieren einer Version:

• Alle anderen Versionen werden inaktiv
• IngestStatus → PENDING
• Re-Ingest via Job

---

7. Ingest-Architektur (vollständig Job-basiert)

Ingest läuft NIEMALS synchron im HTTP-Request.

Jede Mutation am Index läuft über:

IngestJob → CLI Runner → IngestOrchestrator → IngestFlow

7.1 Job-Typen

• DOCUMENT_VERSION_ACTIVATE
• DOCUMENT
• GLOBAL_REINDEX

7.2 Job-Status

• QUEUED
• RUNNING
• COMPLETED
• FAILED
• ABORTED

CLI-Ausführung:

php bin/console mto:agent:ingest:run <jobId>

---

8. Hybrid Retrieval

Flow:

User Query
→ Keyword Retrieval
→ Tag Vector Search
→ Dokumentfilter
→ Chunk Vector Retrieval
→ Score Fusion
→ NDJSON Lookup
→ Context Builder
→ LLM
→ SSE Streaming

Keyword bleibt Primärsignal.
Vector ergänzt Semantik.

---

9. Locking & Concurrency

LockService verhindert:

• parallelen Ingest
• gleichzeitige Reindex-Vorgänge
• NDJSON-Korruption

Keine gleichzeitigen Mutationen erlaubt.

---

10. Vector Control (Production Safe)

Ein zentrales Kommando steuert:

• Dependency-Check
• Auto-Install (opt-in)
• Service Start
• Service Stop
• Reload
• Status
• Health-Check
• PID-Management

Command

mto:agent:vector:control

Beispiele

Status:

bin/console mto:agent:vector:control

Install + Start:

bin/console mto:agent:vector:control --install --start

Stop:

bin/console mto:agent:vector:control --stop

Reload:

bin/console mto:agent:vector:control --reload

Production-Safety

• PID-File unter var/run/vector_service.pid
• SIGTERM Stop mit Timeout
• Optional SIGKILL (--force)
• Health-Check mit Retry-Mechanismus
• Kein automatisches Install ohne Flag

---

11. CLI Commands

• mto:agent:ingest:run <jobId>
• mto:agent:vector:control
• mto:agent:test
• mto:agent:chat

Alle Commands unter:

mto:agent:*

---

12. Failure Modes

Vector Service nicht erreichbar
→ vector:control --start

Reload Endpoint fehlt
→ falsche Service-Version

index_meta mismatch
→ Global Reindex

Lock aktiv
→ Parallel-Ingest blockiert

---

13. Non-Goals

• Kein Online-Learning
• Keine inkrementellen FAISS Updates
• Keine selbstverändernden Prompts
• Kein Auto-Merging von Chunks
• Kein Vector-Append im Runtime

Strukturänderungen → explizit + Reindex.

---

14. Zusammenfassung

Dieses System ist:

• deterministisch
• reproduzierbar
• drift-sicher
• governance-stabil
• enterprise-ready
• job-basiert
• versionssicher
• persistent im Retrieval
• ohne Spawn-Overhead
• reload-fähig ohne Downtime

Wichtige Neuerungen:

• Persistenter Vector-Service ersetzt CLI-Spawn
• Score-Gates verhindern falsches Routing
• Reload-Endpoint vermeidet Neustarts
• Production-Safe Control Command integriert
• Vollständige Trennung von Ingest und Runtime