From 413c76d710d6d8f68af47097bfe05e4e2deef0fa Mon Sep 17 00:00:00 2001 From: team 1 Date: Mon, 16 Feb 2026 09:38:40 +0100 Subject: [PATCH] add new md files --- README.md | 596 +++++++++++++++----------------------- SYSTEM.md | 334 --------------------- TECHNICAL_ARCHITECTURE.md | 368 +++++++++++++++++++++++ 3 files changed, 608 insertions(+), 690 deletions(-) delete mode 100644 SYSTEM.md create mode 100644 TECHNICAL_ARCHITECTURE.md diff --git a/README.md b/README.md index 0008ca3..fafb4c9 100644 --- a/README.md +++ b/README.md @@ -1,430 +1,314 @@ -# mitho AI Agent – Developer Deep Dive - +# mitho AI Agent – Developer README Enterprise Hybrid RAG System (Symfony + NDJSON + FAISS) ---- - -# 1. System Overview - -This system implements a deterministic, governance-stable Retrieval Augmented Generation (RAG) architecture based on: - -- Symfony (PHP backend) -- NDJSON-based knowledge index -- Full FAISS vector rebuild strategy -- Hybrid retrieval (keyword + vector) -- Deterministic ingest pipeline -- Strict versioning & guardrails -- Lock-based reindex protection - -No incremental vector mutation is allowed. -FAISS is always rebuilt from `index.ndjson`. +Stand: Februar 2026 +Status: Produktiv stabil – Job-basierte Ingest-Architektur vollständig integriert --- -# 2. High-Level Architecture +# 1. Systemüberblick -User Query -→ Hybrid Retrieval -→ Context Assembly -→ Prompt Builder -→ LLM -→ Streaming Response (SSE) +Dieses System implementiert eine deterministische, governance-stabile +Hybrid-RAG-Architektur mit: -Knowledge Flow: -Document → Version → Extract → Chunk → NDJSON → FAISS → Retrieval +- Symfony (PHP Backend) +- NDJSON als Single Source of Truth +- FAISS als Vektorindex (immer Full Rebuild) +- 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. --- -# 3. Directory Structure (Knowledge Layer) +# 2. Architekturprinzipien -``` -var/knowledge/ - ├── uploads/ - ├── chunks/ - ├── index.ndjson - ├── index_meta.json - ├── vector.index - └── vector_meta.json -``` +Determinismus: +- Gleiche Dokumente + gleiche Konfiguration → identisches index.ndjson +- Gleiches index.ndjson → identisches FAISS +- Gleiche Query → identisches Retrieval-Ergebnis + +Governance: +- Eine aktive Version pro Dokument +- Keine impliziten Index-Änderungen +- Strukturänderungen erzwingen Global Reindex +- Keine Selbstmodifikation durch KI + +Skalierbarkeit: +- NDJSON (streamingfähig) +- Keine RAM-basierte JSON-Arrays +- Zielgröße > 200k Chunks --- -# 4. NDJSON Index +# 3. Wissensspeicher -## 4.1 index.ndjson +## 3.1 index.ndjson -- Single Source of Truth -- One JSON object per line -- Streaming-readable -- No JSON array wrapper -- Scales beyond 200k chunks +Single Source of Truth. -Each line contains: +- 1 JSON-Objekt pro Zeile +- Streaming-Append +- Deterministische Compaction by document_id + +Beispielstruktur: -```json { - "chunk_id": "uuid", - "document_id": "uuid", - "version": 3, - "text": "...", - "meta": { ... } +"chunk_id": "uuid", +"document_id": "uuid", +"document_version_id": "uuid", +"text": "...", +"meta": {...} } -``` -NDJSON enables: -- Append-based writes -- Compaction per document -- Memory-safe streaming -- Deterministic rebuilds +Keine JSON-Array-Datei. +Keine Mutation einzelner Chunks. +Nur Append + deterministische Entfernung per document_id. --- -# 5. Index Metadata +## 3.2 index_meta.json -## index_meta.json - -Managed by: - -- IndexMetaManager -- IndexConfiguration - -Contains: +Enthält Strukturparameter: - index_version - embedding_model - embedding_dimension - chunk_size -- overlap +- chunk_overlap - scoring_version - index_format +- vector_backend -If configuration changes → Global Reindex required. - -Guarded by: -`IndexStructureChangedException` +Wenn einer dieser Werte sich ändert: +→ Global Reindex zwingend erforderlich. --- -# 6. Ingest Pipeline +## 3.3 FAISS -## 6.1 Core Services +Dateien: -| Service | Responsibility | -|----------|----------------| -| DocumentService | Document lifecycle | -| DocumentVersionRepository | Version persistence | -| KnowledgeIngestService | Chunk generation | -| SimpleChunker | Deterministic splitting | -| TextNormalizer | Text cleanup | -| StopWords | Keyword filtering | -| ChunkManager | NDJSON append + compaction | -| ChunkWriter | Chunk persistence | -| IngestFlow | Step orchestration | -| IngestOrchestrator | Full ingest coordination | -| IngestJobService | Job tracking | -| LockService | Concurrency guard | +- vector.index +- vector_meta.json (Chunk-ID Mapping) + +FAISS wird IMMER vollständig aus index.ndjson gebaut. +Keine Partial Updates. --- -## 6.2 Local Ingest +# 4. Dokument- & Versionsmodell -Used when: -- A single document version changes +Document +→ enthält mehrere DocumentVersion +→ genau eine Version ist aktiv -Process: +Regel: +Es darf immer nur eine aktive Version pro Dokument existieren. -1. Extract document -2. Normalize text -3. Chunk deterministically -4. Remove previous chunks of document_id -5. Append new chunks to index.ndjson -6. Rebuild FAISS completely - -index_version does NOT change. +Beim Aktivieren einer Version: +- Alle anderen Versionen werden inaktiv +- IngestStatus → PENDING +- Re-Ingest via Job --- -## 6.3 Global Reindex +# 5. Ingest-Architektur (vollständig Job-basiert) -Used when: -- Embedding model changes -- Chunk size changes -- Overlap changes -- Scoring logic changes -- index_format changes +Ingest läuft NIEMALS synchron im HTTP-Request. -Process: +Jede Mutation am Index läuft über: -1. Re-extract all active document versions -2. Recreate full index.ndjson -3. Rebuild FAISS +IngestJob → CLI Runner → IngestOrchestrator → IngestFlow + +--- + +## 5.1 Job-Typen + +DOCUMENT_VERSION_ACTIVATE +- Wird genutzt für: + - Version aktivieren + - Neue Datei hochladen (Auto-Ingest) + +DOCUMENT +- Manuelles Ingest einer Version + +GLOBAL_REINDEX +- Strukturänderungen + +--- + +## 5.2 Job-Status + +- QUEUED +- RUNNING +- COMPLETED +- FAILED +- ABORTED + +Jobs werden über CLI ausgeführt: + +php bin/console mto:agent:ingest:run + +Start erfolgt asynchron per exec() aus dem Controller. + +--- + +# 6. Admin-Flows (aktueller Stand) + +## 6.1 Neue Datei hochladen (NEU: Auto-Ingest) + +Beim Upload: + +1. Datei speichern +2. Document + Version 1 erzeugen +3. Version 1 aktiv setzen +4. IngestJob vom Typ DOCUMENT_VERSION_ACTIVATE anlegen +5. Job asynchron starten +6. Redirect auf Job-Detailseite + +Ergebnis: +Neue Dokumente werden automatisch indexiert. + +--- + +## 6.2 Version aktivieren + +1. DB-Status anpassen +2. IngestStatus → PENDING +3. DOCUMENT_VERSION_ACTIVATE Job erzeugen +4. Async Runner starten +5. Redirect zur Job-Seite + +--- + +## 6.3 Manuelles Ingest + +1. DOCUMENT Job erzeugen +2. Async Runner starten +3. Redirect zur Job-Seite + +--- + +## 6.4 Reset + +Reset löscht: + +- index.ndjson +- vector.index +- vector_meta.json +- Upload-Verzeichnis +- Tabellen: + - document + - document_version + - ingest_job + +Nur möglich, wenn exec() aktiv ist. + +--- + +# 7. Ingest-Flow Details + +Local Ingest (ein Dokument): + +1. Extract +2. Normalize +3. Chunk deterministisch +4. Entferne alte Chunks per document_id +5. Append neue Chunks +6. Full FAISS Rebuild + +Global Reindex: + +1. Alle aktiven Versionen neu verarbeiten +2. Komplettes index.ndjson neu schreiben +3. FAISS neu bauen 4. index_version++ --- -# 7. Vector Architecture - -## 7.1 vector_ingest.py - -Responsibilities: - -- Stream-read index.ndjson -- Extract text + chunk_id -- Build embeddings -- Normalize embeddings -- Build FAISS IndexFlatIP -- Write vector.index -- Write vector.meta.json - -Execution: - -```bash -python vector_ingest.py --index path/to/index.ndjson --out path/to/vector.index -``` - -Characteristics: - -- No partial updates -- No incremental mutation -- Always full rebuild -- Batch size = 64 -- normalize_embeddings=True - ---- - -## 7.2 vector_search.py - -Responsibilities: - -- Load vector.index -- Load vector_meta.json -- Encode query -- Search top-K -- Return JSON - -Execution: - -```bash -python vector_search.py "query" 5 -``` - -Output: - -```json -[ - { "chunk_id": "...", "score": 0.82 } -] -``` - ---- - -## 7.3 VectorSearchClient (PHP) - -- Executes Python search script -- Parses JSON response -- Returns structured results -- Handles timeout + error states - ---- - # 8. Hybrid Retrieval -## 8.1 Components +Ablauf: -| Class | Role | -|--------|------| -| NdjsonHybridRetriever | Orchestrator | -| NdjsonKeywordSearch | Keyword scoring | -| NdjsonChunkLookup | Chunk resolution | -| VectorSearchClient | Vector bridge | -| CachedRetriever | Cache layer | +User Query +→ Keyword Retrieval +→ FAISS Vector Retrieval +→ Score Fusion +→ NDJSON Chunk Lookup +→ Context Builder +→ LLM +→ SSE Streaming + +Keyword ist Primärsignal. +Vector ergänzt Semantik. --- -## 8.2 Retrieval Flow +# 9. Locking & Concurrency -1. Extract terms (StopWords + normalization) -2. Keyword scoring -3. Vector search -4. Score fusion -5. Limit to N chunks -6. Resolve chunk text -7. Build LLM context +LockService verhindert: -Keyword score remains primary signal. -Vector score augments semantic similarity. +- parallelen Ingest +- gleichzeitige Reindex-Vorgänge +- NDJSON-Korruption + +Keine gleichzeitigen Mutationen erlaubt. --- -# 9. Document Extraction +# 10. CLI Commands -Supported via: +mto:agent:ingest:run +mto:agent:vector:ingest +mto:agent:vector:search -- DocumentExtractorInterface -- ExtractorResolver -- PdfExtractor -- DocumentLoader - -Extraction must return clean UTF-8 text. -Chunking must remain deterministic. - ---- - -# 10. Admin Layer (Symfony) - -## Controllers - -- DashboardController -- DocumentController -- IngestJobController -- SecurityController - -## Entities - -- Document -- DocumentVersion -- IngestJob -- User - -## Repositories - -- DocumentVersionRepository -- UserRepository - ---- - -# 11. Concurrency & Locks - -LockService ensures: - -- No parallel reindex -- No parallel ingest conflict -- Controlled mutation of index.ndjson - -File-based or service-based locking. - ---- - -# 12. Determinism Rules - -The system guarantees: - -- Same documents + same config = identical index.ndjson -- Same index.ndjson = identical FAISS -- Same query + same index = identical results - -No randomness. -No adaptive mutation. -No auto-learning. - ---- - -# 13. LLM Integration - -- Context strictly limited to retrieved chunks -- PromptBuilder constructs deterministic system prompt -- ContextService manages history -- SSE streaming enabled -- Model endpoint configurable - -LLM never has direct access to full knowledge base. -Only retrieved chunks are injected. - ---- - -# 14. Scalability - -Designed for: - -- >200k chunks -- Streaming NDJSON reads -- Full FAISS rebuild -- Cache layer for retrieval -- Controlled memory usage - -No full-array JSON loads. - ---- - -# 15. Failure Modes - -Handled via: - -- Missing vector index detection -- Structure drift detection -- Lock collision detection -- Embedding dependency checks -- Python execution errors -- Empty chunk fallback - ---- - -# 16. Non-Goals - -This system intentionally does NOT include: - -- Online learning -- Embedding mutation -- Incremental FAISS update -- Auto chunk merging -- Self-modifying prompts - -All structural changes require explicit reindex. - ---- - -# 17. Design Philosophy - -This is a governance-first RAG architecture: - -- Deterministic -- Reproducible -- Drift-safe -- Audit-friendly -- Version-controlled - -It prioritizes correctness and control over dynamic mutation. - ---- - -# 18. Development Guidelines - -When extending the system: - -- Never mutate FAISS directly -- Never edit index.ndjson manually -- Always preserve determinism -- Increment index_version only via Global Reindex -- Guard all structural changes -- Maintain streaming compatibility - ---- - -# 19. CLI Commands (Symfony) - -Example: - -```bash -php bin/console mto:agent:vector:ingest -``` - -Custom commands follow namespace: - -``` +Alle Commands unter: mto:agent:* -``` --- -# 20. Summary +# 11. Failure Modes -This system is a deterministic, enterprise-grade hybrid RAG engine with: +- Vector index fehlt → vector ingest ausführen +- index_meta mismatch → Global Reindex +- exec deaktiviert → Async-Start schlägt fehl +- Lock aktiv → Parallel-Ingest blockiert -- NDJSON-based streaming index -- Full FAISS rebuild strategy -- Structured ingest pipeline -- Hybrid retrieval -- Admin governance layer -- Strict guardrails +--- -It is designed for controlled enterprise deployment, not experimental AI workflows. +# 12. Non-Goals + +- Kein Online-Learning +- Keine inkrementellen FAISS Updates +- Keine selbstverändernden Prompts +- Kein Auto-Merging von Chunks + +Strukturänderungen → explizit + reindex. + +--- + +# 13. Zusammenfassung + +Dieses System ist: + +- deterministisch +- reproduzierbar +- drift-sicher +- governance-stabil +- enterprise-ready +- job-basiert +- versionssicher + +Wichtige Neuerung: +Neue Dokumente lösen jetzt automatisch einen IngestJob aus +(exakt derselbe Mechanismus wie bei Version-Aktivierung). + +Kein HTTP-Ingest mehr. +Keine Inline-Rebuilds. +Alles läuft über das Job-System. diff --git a/SYSTEM.md b/SYSTEM.md deleted file mode 100644 index 60a1050..0000000 --- a/SYSTEM.md +++ /dev/null @@ -1,334 +0,0 @@ -# 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. diff --git a/TECHNICAL_ARCHITECTURE.md b/TECHNICAL_ARCHITECTURE.md new file mode 100644 index 0000000..c93e7e4 --- /dev/null +++ b/TECHNICAL_ARCHITECTURE.md @@ -0,0 +1,368 @@ +# TECHNICAL_ARCHITECTURE.md +mitho AI Agent – Enterprise Hybrid RAG System +Stand: Februar 2026 + +--- + +# 1. Zielsetzung + +Diese Dokumentation beschreibt die vollständige technische Architektur des +mitho AI Agent RAG-Systems. + +Ziele: + +- Deterministisches Retrieval +- Governance-stabile Index-Struktur +- Versionierte Wissensbasis +- Reproduzierbare Builds +- Keine inkrementellen Vektor-Mutationen +- Job-basierte, asynchrone Ingest-Architektur +- Skalierbarkeit >200k Chunks + +--- + +# 2. Architektur-Übersicht + +Systemebenen: + +1. Admin Layer (Symfony) +2. Ingest Layer +3. Storage Layer (NDJSON) +4. Vector Layer (FAISS) +5. Retrieval Layer (Hybrid) +6. Application Layer (LLM + SSE) + +--- + +# 3. Core Architekturprinzipien + +## 3.1 Determinismus + +Gleiche Eingabe + gleiche Konfiguration → identisches Ergebnis. + +- index.ndjson ist deterministisch +- FAISS wird vollständig neu gebaut +- Retrieval ist stabil reproduzierbar +- Keine impliziten Indexveränderungen + +## 3.2 Governance + +- Genau eine aktive Version pro Dokument +- Keine Inline-Rebuilds im HTTP-Request +- Strukturänderungen erzwingen Global Reindex +- Locking verhindert Parallel-Ingest + +## 3.3 Skalierbarkeit + +- NDJSON statt JSON-Array +- Streaming-Append +- Streaming-Compaction +- Kein RAM-Full-Load + +--- + +# 4. Domain Model + +## 4.1 Document + +Primäre Wissenseinheit. + +Eigenschaften: +- id (UUID) +- title +- createdAt +- createdBy +- archived (bool) +- currentVersion (ManyToOne → DocumentVersion) + +## 4.2 DocumentVersion + +Immutable Inhaltsversion. + +Eigenschaften: +- id (UUID) +- document (ManyToOne) +- versionNumber +- filePath +- checksum +- active (bool) +- ingestStatus (PENDING, RUNNING, INDEXED, FAILED) + +Regel: +Nur eine Version pro Dokument darf active = true sein. + +--- + +# 5. Ingest Architektur + +## 5.1 Grundsatz + +Kein Ingest läuft synchron im HTTP-Request. + +Jede Indexänderung läuft über: + +IngestJob → CLI Runner → IngestOrchestrator → IngestFlow + +--- + +## 5.2 IngestJob + +Entity mit: + +- id +- type +- status +- documentId +- documentVersionId +- startedAt +- finishedAt +- errorMessage + +Job-Typen: + +DOCUMENT_VERSION_ACTIVATE +DOCUMENT +GLOBAL_REINDEX + +Status: + +QUEUED +RUNNING +COMPLETED +FAILED +ABORTED + +--- + +## 5.3 Job-Execution + +Start: + +php bin/console mto:agent:ingest:run + +Execution-Flow: + +1. LockService.acquire() +2. Job → RUNNING +3. IngestFlow ausführen +4. Job → COMPLETED / FAILED +5. LockService.release() + +--- + +# 6. IngestFlow Details + +## 6.1 Local Ingest (Version aktivieren oder neue Datei) + +Ablauf: + +1. Extract (PDF/Text) +2. Normalize +3. Chunk deterministisch +4. Streaming Compaction: + - Entferne alle Chunks mit document_id +5. Append neue Chunks +6. Full FAISS Rebuild + +Wichtig: +Es werden immer alle alten Chunks des Dokuments entfernt. + +--- + +## 6.2 Global Reindex + +Wird ausgelöst bei: + +- embedding_model Änderung +- embedding_dimension Änderung +- chunk_size Änderung +- scoring_version Änderung +- index_format Änderung + +Ablauf: + +1. Alle aktiven Versionen extrahieren +2. Komplettes index.ndjson neu schreiben +3. FAISS neu bauen +4. index_version++ + +--- + +# 7. Storage Layer + +## 7.1 index.ndjson + +Single Source of Truth. + +Eigenschaften: + +- 1 JSON-Objekt pro Zeile +- Streaming-lesbar +- Append-only +- Compaction by document_id + +Beispiel: + +{ +"chunk_id": "...", +"document_id": "...", +"document_version_id": "...", +"text": "...", +"meta": {...} +} + +--- + +## 7.2 index_meta.json + +Enthält: + +- index_version +- embedding_model +- embedding_dimension +- chunk_size +- chunk_overlap +- scoring_version +- index_format +- vector_backend + +Bei strukturellem Mismatch: +→ Global Reindex zwingend. + +--- + +# 8. Vector Layer (FAISS) + +## 8.1 Build + +vector_ingest.py: + +- stream index.ndjson +- Embeddings berechnen +- FAISS IndexFlatIP bauen +- vector.index schreiben +- vector_meta.json schreiben + +Immer vollständiger Rebuild. +Keine Partial Updates. + +## 8.2 Search + +vector_search.py: + +Input: +- Query +- Top-K + +Output: +- chunk_id +- score + +--- + +# 9. Hybrid Retrieval + +Ablauf: + +1. Keyword Retrieval (NDJSON Keyword Search) +2. Vector Retrieval (FAISS) +3. Score Fusion +4. Chunk Lookup +5. Context Builder +6. Prompt Builder +7. LLM + +Keyword bleibt Primärsignal. +Vector ergänzt semantische Nähe. + +--- + +# 10. Locking + +LockService schützt: + +- NDJSON Mutationen +- FAISS Rebuild +- Global Reindex +- Aktivierungs-Parallelität + +Keine zwei Ingest-Jobs gleichzeitig erlaubt. + +--- + +# 11. Admin Flows + +## 11.1 Neue Datei hochladen + +1. Document + Version 1 erstellen +2. Version aktiv +3. DOCUMENT_VERSION_ACTIVATE Job anlegen +4. Async Runner starten +5. Redirect auf Job-Seite + +## 11.2 Version aktivieren + +1. DB-Status ändern +2. IngestStatus → PENDING +3. DOCUMENT_VERSION_ACTIVATE Job anlegen +4. Async Runner starten + +## 11.3 Manuelles Ingest + +1. DOCUMENT Job anlegen +2. Async Runner starten + +--- + +# 12. Error Handling + +Typische Fehler: + +- exec deaktiviert → Async Start nicht möglich +- Lock aktiv → paralleler Ingest blockiert +- index_meta mismatch → Reindex erforderlich +- Vector-Dateien fehlen → Rebuild ausführen + +--- + +# 13. Security & Stability + +- Keine User-Uploads direkt ins Retrieval +- Kein Self-Learning +- Kein unkontrollierter Index-Mutate +- Strict Separation: + - Admin Layer + - Ingest Layer + - Retrieval Layer + - LLM Layer + +--- + +# 14. System Guarantees + +Dieses System garantiert: + +- Reproduzierbarkeit +- Drift-Freiheit +- Auditierbarkeit +- Versionierte Wissensbasis +- Deterministische Retrieval-Ergebnisse +- Enterprise-taugliche Skalierbarkeit + +--- + +# 15. Zusammenfassung + +Das mitho AI Agent System ist eine: + +- deterministische Hybrid-RAG Engine +- NDJSON-basierte Wissensplattform +- Full-Rebuild-FAISS Architektur +- Job-basierte Ingest-Pipeline +- Versionierte, governance-stabile Wissensstruktur + +Keine Inline-Rebuilds. +Keine inkrementellen Vektor-Updates. +Keine impliziten Strukturänderungen. + +Alles läuft kontrolliert über das Job-System.