docs/mindnet_functional_architecture.md aktualisiert

docs/mindnet_functional_architecture.md

@@ -1,9 +1,9 @@
 # Mindnet v2.2 – Fachliche Architektur
 **Datei:** `docs/mindnet_functional_architecture_v2.2.md`
-**Stand:** 2025-12-07
+**Stand:** 2025-12-08
-**Status:** **FINAL** (Integrierter Stand WP01–WP04a)
+**Status:** **FINAL** (Integrierter Stand WP01–WP04c)
 
-> Dieses Dokument beschreibt **was** Mindnet fachlich tut und **warum** – mit Fokus auf die Erzeugung und Nutzung von **Edges** (Kanten) zwischen Notizen/Chunks sowie die Logik des Retrievers. Die technische Umsetzung (Module, Flags, Schemas) wird im technischen Dokument detailliert.
+> Dieses Dokument beschreibt **was** Mindnet fachlich tut und **warum** – mit Fokus auf die Erzeugung und Nutzung von **Edges** (Kanten) zwischen Notizen/Chunks sowie die Logik des Retrievers und der Feedback-Mechanismen. Die technische Umsetzung wird im technischen Dokument detailliert.
 
 ---
 
@@ -134,7 +134,7 @@ Der Importer lädt die Registry aus `MINDNET_TYPES_FILE` oder nutzt Fallbacks. *
 
 ## 5) Der Retriever (Funktionaler Layer)
 
-Der Retriever ist in v2.2 der zentrale Zugangspunkt zum Wissen. Er realisiert die **Hybride Suche**.
+Der Retriever ist in v2.2 der zentrale Zugangspunkt. Er realisiert die **Hybride Suche**.
 
 ### 5.1 Scoring-Modell
 Die Relevanz eines Treffers ergibt sich nicht mehr nur aus Textähnlichkeit, sondern aus einer gewichteten Formel:
@@ -147,17 +147,45 @@ Die Relevanz eines Treffers ergibt sich nicht mehr nur aus Textähnlichkeit, son
 
 * **semantic_score:** Vektorähnlichkeit (Qdrant).
 * **retriever_weight:** Wichtigkeit des Typs (z.B. Projekte > Quellen).
-* **edge_bonus:** Belohnung für Chunks, die im Kontext der Anfrage stark vernetzt sind (unter Berücksichtigung der *confidence*).
+* **edge_bonus:** Belohnung für Chunks, die im Kontext der Anfrage stark vernetzt sind (Summe der Confidence eingehender relevanter Kanten).
 * **centrality_bonus:** Belohnung für Knoten, die zentrale Hubs im lokalen Graphen darstellen.
 
-### 5.2 Erklärbarkeit (Explainability)
+### 5.2 Erklärbarkeit (Explainability) – WP04b
-Der Retriever liefert **Begründungspfade**. Er gibt nicht nur Text zurück, sondern:
+Der Retriever ist keine Blackbox mehr. Er liefert auf Wunsch (`explain=True`) eine strukturierte Begründung (`Explanation`-Objekt).
-* `score_breakdown`: Warum ist dieser Chunk oben? (War es der Text oder der Graph?)
+
-* `paths`: Über welche Kanten wurde dieser Chunk gefunden? (z.B. "Gefunden via `depends_on` von deiner aktuellen Projekt-Notiz").
+**Die "Warum"-Logik:**
+1.  **Semantik:** Prüfung der Cosine-Similarity ("Sehr hohe textuelle Übereinstimmung").
+2.  **Typ:** Prüfung des `retriever_weight` ("Bevorzugt, da Entscheidung").
+3.  **Graph (Kontext):**
+    * **Hub (Outgoing):** Worauf verweist dieser Treffer? ("Verweist auf Qdrant").
+    * **Authority (Incoming):** Wer verweist auf diesen Treffer? ("Wird referenziert von Projekt Alpha").
+    
+Die API gibt diese Analysen als menschenlesbare Sätze (`reasons`) und als Datenstruktur (`score_breakdown`) zurück.
 
 ---
 
-## 6) Confidence & Provenance – wozu?
+## 6) Feedback & Lernen – WP04c
+
+Das System verfügt nun über ein **Kurzzeitgedächtnis für Interaktionen**, das die Basis für zukünftiges Lernen bildet.
+
+### 6.1 Der Feedback-Loop
+1.  **Suche (Situation):**
+    Wenn ein Nutzer eine Anfrage stellt, loggt Mindnet die "Situation":
+    * Den Query-Text.
+    * Die Top-K Ergebnisse.
+    * Den exakten `score_breakdown` zu diesem Zeitpunkt.
+    * Eine eindeutige `query_id` wird generiert.
+
+2.  **Bewertung (Label):**
+    Der Nutzer (oder ein Agent) bewertet einen spezifischen Treffer (`node_id`) positiv oder negativ (Score 1-5).
+    Dieses Feedback wird unter Referenzierung der `query_id` gespeichert.
+
+3.  **Lernen (Perspektive WP08):**
+    Durch die Verknüpfung von Situation und Bewertung entstehen Trainingsdaten. Mindnet kann später analysieren: *"Nutzer bevorzugen Treffer mit hohem Edge-Bonus, auch wenn der Text weniger passt."* -> Konsequenz: `edge_weight` erhöhen.
+
+---
+
+## 7) Confidence & Provenance – wozu?
 
 Der Retriever kann Edges gewichten:
 - **provenance**: *explicit* > *rule*
@@ -169,7 +197,7 @@ Eine typische Gewichtung (konfigurierbar in `retriever.yaml`) ist:
 
 ---
 
-## 7) Semantik ausgewählter `kind`-Werte
+## 8) Semantik ausgewählter `kind`-Werte
 
 - `references` – „Nutzt/erwähnt“; neutral, aber stützend für Kontext.
 - `related_to` – Ähnlichkeit/Verwandtschaft (symmetrisch interpretierbar).
@@ -181,7 +209,7 @@ Eine typische Gewichtung (konfigurierbar in `retriever.yaml`) ist:
 
 ---
 
-## 8) Frontmatter-Eigenschaften – Rolle & Empfehlung
+## 9) Frontmatter-Eigenschaften – Rolle & Empfehlung
 
 Frontmatter-Eigenschaften (Properties) bleiben **minimiert**:
 - **type** – steuert Typ-Defaults via Registry (Pflicht für differenziertes Verhalten).
@@ -191,7 +219,7 @@ Frontmatter-Eigenschaften (Properties) bleiben **minimiert**:
 
 ---
 
-## 9) Lösch-/Update-Garantien (Idempotenz)
+## 10) Lösch-/Update-Garantien (Idempotenz)
 
 - Jede Note hat einen stabilen **note_id** (Frontmatter/Hash).
 - Vor einem Upsert können *alte Chunks/Edges einer Note* gefiltert gelöscht werden (`note_id`-Filter) – das hält Collections sauber bei Re-Imports.
@@ -199,7 +227,7 @@ Frontmatter-Eigenschaften (Properties) bleiben **minimiert**:
 
 ---
 
-## 10) Beispiel – Von Markdown zu Kanten (v2.2)
+## 11) Beispiel – Von Markdown zu Kanten (v2.2)
 
 **Markdown (Auszug)**
     # Relations Showcase
@@ -218,7 +246,7 @@ Frontmatter-Eigenschaften (Properties) bleiben **minimiert**:
 
 ---
 
-## 11) Qualitäts- und Testkriterien (fachlich)
+## 12) Qualitäts- und Testkriterien (fachlich)
 
 - **Keine Duplikate** gleicher `(src, relation, dst)` in der Collectionsicht (Dedup).
 - **Explizite Links** werden vollständig materialisiert (*explicit_total*).
@@ -227,9 +255,10 @@ Frontmatter-Eigenschaften (Properties) bleiben **minimiert**:
 
 ---
 
-## 12) Referenzen (Projektdateien & Leitlinien)
+## 13) Referenzen (Projektdateien & Leitlinien)
 
 - Import-Pipeline & Registry-Auflösung: `scripts/import_markdown.py`.
 - Kantenbildung (V2-Logic): `app/core/derive_edges.py`.
 - Typ-Registry: `config/types.yaml` & `TYPE_REGISTRY_MANUAL.md`.
-- Retriever-Scoring: `app/core/retriever.py` & `wp04_retriever_scoring.md`.
+- Retriever-Scoring & Explanation: `app/core/retriever.py`.
+- Logging Service: `app/services/feedback_service.py`.