diff --git a/docs/mindnet_functional_architecture.md b/docs/mindnet_functional_architecture.md index 20252ae..9c43074 100644 --- a/docs/mindnet_functional_architecture.md +++ b/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 -**Status:** **FINAL** (Integrierter Stand WP01–WP04a) +**Stand:** 2025-12-08 +**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) -Der Retriever liefert **Begründungspfade**. Er gibt nicht nur Text zurück, sondern: -* `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"). +### 5.2 Erklärbarkeit (Explainability) – WP04b +Der Retriever ist keine Blackbox mehr. Er liefert auf Wunsch (`explain=True`) eine strukturierte Begründung (`Explanation`-Objekt). + +**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`. \ No newline at end of file +- Retriever-Scoring & Explanation: `app/core/retriever.py`. +- Logging Service: `app/services/feedback_service.py`. \ No newline at end of file