diff --git a/docs/mindnet_technical_architecture.md b/docs/mindnet_technical_architecture.md index 69a7a4f..9842ab0 100644 --- a/docs/mindnet_technical_architecture.md +++ b/docs/mindnet_technical_architecture.md @@ -1,8 +1,8 @@ # Mindnet v2.2 – Technische Architektur **Datei:** `docs/mindnet_technical_architecture_v2.2.md` -**Stand:** 2025-12-07 -**Status:** **FINAL** (Integrierter Stand WP01–WP04a) -**Quellen:** `mindnet_technical_architecture.md`, `chunking_strategy.md`, `Handbuch.md`, `wp04_retriever_scoring.md`, `Überarbeitungshinweise_WP03.md`, `Überarbeitungshinweise_WP04.md`. +**Stand:** 2025-12-08 +**Status:** **FINAL** (Integrierter Stand WP01–WP04c) +**Quellen:** `mindnet_technical_architecture.md`, `chunking_strategy.md`, `Handbuch.md`, `wp04_retriever_scoring.md`. > **Ziel dieses Dokuments:** > Vollständige, konsolidierte Beschreibung der aktuellen technischen Architektur von **Mindnet v2.2**. Es definiert die Datenstrukturen in Qdrant, die Verarbeitungspipelines (Importer, Chunker, Edges) und die Retrieval-Logik. Es bildet den **aktuellen Implementierungsstand** ab. @@ -15,8 +15,10 @@ Mindnet ist ein **persönliches Wissensnetz**. Technisch bedeutet das: 1. **Source:** Markdown-Notizen in einem Vault (Obsidian-kompatibel). 2. **Pipeline:** Ein Python-Importer transformiert diese in **Notes**, **Chunks** und **Edges**. -3. **Storage:** Speicherung in **Qdrant** (Vektor-Datenbank) in drei getrennten Collections. -4. **Service:** Eine FastAPI-Anwendung stellt Endpunkte für **Semantische** und **Hybride Suche** bereit. +3. **Storage:** + * **Qdrant:** Vektor-Datenbank für Graph und Semantik (Collections: notes, chunks, edges). + * **Local Files (JSONL):** Append-Only Logs für Feedback und Search-History (Data Flywheel). +4. **Service:** Eine FastAPI-Anwendung stellt Endpunkte für **Semantische** und **Hybride Suche** sowie **Feedback** bereit. Das System arbeitet **deterministisch** (stabile IDs) und ist **konfigurationsgetrieben** (`types.yaml`, `retriever.yaml`). @@ -34,12 +36,21 @@ Die Codebasis ist modular aufgebaut. │ │ ├── chunker.py # Text-Zerlegung (Profiling) │ │ ├── edges.py # Edge-Datenstrukturen │ │ ├── derive_edges.py # Logik der Kantenableitung (WP03) - │ │ └── retriever.py # Scoring & Graph-Expansion (WP04) - │ ├── models/ # Pydantic DTOs (QueryRequest, etc.) - │ └── routers/ # API Routen + │ │ ├── graph_adapter.py # Subgraph & Reverse-Lookup (WP04b) + │ │ └── retriever.py # Scoring, Expansion & Explanation (WP04a/b) + │ ├── models/ # Pydantic DTOs (QueryHit, Explanation, FeedbackRequest) + │ ├── routers/ + │ │ ├── query.py # Such-Endpunkt + │ │ ├── feedback.py # Feedback-Endpunkt (WP04c) + │ │ └── ... + │ ├── services/ + │ │ ├── feedback_service.py # Logging-Logik (WP04c) + │ │ └── embeddings_client.py ├── config/ │ ├── types.yaml # Typ-Definitionen (Import-Zeit) │ └── retriever.yaml # Scoring-Gewichte (Laufzeit) + ├── data/ + │ └── logs/ # Lokale JSONL-Logs (WP04c) ├── scripts/ │ ├── import_markdown.py # Haupt-Importer CLI │ ├── payload_dryrun.py # Diagnose: JSON-Generierung ohne DB @@ -69,8 +80,6 @@ Repräsentiert die Metadaten einer Datei. | `updated` | Integer | Zeitstempel (z.B. YYYYMMDD...). | File Stats | | `fulltext` | Text | Gesamter Inhalt (für Export/Rekonstruktion). | Body | - - ### 2.2 Chunks Collection (`_chunks`) Die atomaren Sucheinheiten. * **Zweck:** Vektorsuche (Embeddings), Granulares Ergebnis. @@ -88,8 +97,6 @@ Die atomaren Sucheinheiten. | `neighbors_prev` | List[Str] | ID des Vorgänger-Chunks. | | `neighbors_next` | List[Str] | ID des Nachfolger-Chunks. | - - ### 2.3 Edges Collection (`_edges`) Gerichtete Kanten. Massiv erweitert in WP03 für Provenienz-Tracking. * **Zweck:** Graph-Traversal, Kontext-Anreicherung. @@ -106,8 +113,6 @@ Gerichtete Kanten. Massiv erweitert in WP03 für Provenienz-Tracking. | `rule_id` | Keyword | Herkunftsregel. | `explicit:wikilink`, `inline:rel` | | `confidence` | Float | Vertrauenswürdigkeit (0.0-1.0). | 1.0, 0.95, 0.7 | - - --- ## 3. Konfiguration @@ -185,12 +190,44 @@ $$ * $B_{cent}$: Centrality-Bonus (im lokalen Subgraphen). * **Gewichte ($W$):** Stammen aus `retriever.yaml`. -### 5.3 Graph-Expansion -Der Hybrid-Modus lädt dynamisch die Nachbarschaft der Top-K Vektor-Treffer ("Seeds") über `graph_adapter.expand`. Dies baut einen temporären `NetworkX`-Graphen im Speicher, auf dem Boni berechnet werden. +### 5.3 Explanation Layer (WP04b) +Der Retriever kann Ergebnisse erklären (`explain=True`). +* **Logik:** + * Berechnung des `ScoreBreakdown` (Anteile von Semantik, Graph, Typ). + * Analyse des lokalen Subgraphen mittels `graph_adapter.py`. + * **Incoming Edges (Authority):** Wer zeigt auf diesen Treffer? (z.B. "Referenziert von...") + * **Outgoing Edges (Hub):** Worauf zeigt dieser Treffer? (z.B. "Verweist auf...") +* **Output:** `QueryHit` enthält ein `explanation` Objekt mit menschenlesbaren `reasons` und `related_edges`. + +### 5.4 Graph-Expansion +Der Hybrid-Modus lädt dynamisch die Nachbarschaft der Top-K Vektor-Treffer ("Seeds") über `graph_adapter.expand`. Dies baut einen temporären `NetworkX`-artigen Graphen im Speicher (Klasse `Subgraph`), auf dem Boni berechnet werden. --- -## 6. Indizes & Performance +## 6. Feedback & Logging Architektur (WP04c) + +Mindnet implementiert ein "Data Flywheel" zur späteren Optimierung (Self-Tuning). + +### 6.1 Komponenten +* **Feedback Service (`app/services/feedback_service.py`):** Kapselt die Schreibzugriffe. +* **Storage:** Lokales Dateisystem (`data/logs/`), Format JSONL (Line-delimited JSON). + +### 6.2 Log-Dateien +1. **`search_history.jsonl`**: + * Speichert jede Anfrage an `/query`. + * Enthält: `query_id`, `query_text`, `timestamp`, `hits` (inkl. `score_breakdown` Snapshots). + * Zweck: Trainingsdaten ("Was hat das System gesehen?"). +2. **`feedback.jsonl`**: + * Speichert User-Reaktionen an `/feedback`. + * Enthält: `query_id`, `node_id`, `score` (1-5), `comment`. + * Zweck: Labels ("War es gut?"). + +### 6.3 Traceability +Die `query_id` (UUIDv4) wird im `/query` Response generiert und muss vom Client beim `/feedback` Aufruf mitgesendet werden. Dies ermöglicht den Join zwischen Snapshot und Bewertung. + +--- + +## 7. Indizes & Performance Damit Qdrant performant bleibt, sind Payload-Indizes essenziell. @@ -203,7 +240,7 @@ Validierung erfolgt über `tests/ensure_indexes_and_show.py`. --- -## 7. Offene Punkte / Known Limitations +## 8. Offene Punkte / Known Limitations 1. **Multi-Target Inline-Relations:** * `rel: similar_to [[A]] [[B]]` wird aktuell parser-seitig nicht unterstützt.