docs/mindnet_technical_architecture.md aktualisiert

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
+**Stand:** 2025-12-08
-**Status:** **FINAL** (Integrierter Stand WP01–WP04a)
+**Status:** **FINAL** (Integrierter Stand WP01–WP04c)
-**Quellen:** `mindnet_technical_architecture.md`, `chunking_strategy.md`, `Handbuch.md`, `wp04_retriever_scoring.md`, `Überarbeitungshinweise_WP03.md`, `Überarbeitungshinweise_WP04.md`.
+**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.
+3.  **Storage:**
-4.  **Service:** Eine FastAPI-Anwendung stellt Endpunkte für **Semantische** und **Hybride Suche** bereit.
+    * **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)
+    │   │   ├── graph_adapter.py    # Subgraph & Reverse-Lookup (WP04b)
-    │   ├── models/                 # Pydantic DTOs (QueryRequest, etc.)
+    │   │   └── retriever.py        # Scoring, Expansion & Explanation (WP04a/b)
-    │   └── routers/                # API Routen
+    │   ├── 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 (`<prefix>_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 (`<prefix>_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
+### 5.3 Explanation Layer (WP04b)
-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.
+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.