docs/developer_guide.md aktualisiert

docs/developer_guide.md

@@ -1,7 +1,7 @@
 # Mindnet v2.2 – Developer Guide
 **Datei:** `docs/mindnet_developer_guide_v2.2.md`
 **Stand:** 2025-12-08
-**Status:** **FINAL** (Inkl. RAG & AI-Teaching Paradigm)
+**Status:** **FINAL** (Inkl. RAG, Edge-Config & AI-Teaching)
 **Quellen:** `mindnet_technical_architecture.md`, `Handbuch.md`, `DEV_WORKFLOW.md`.
 
 > **Zielgruppe:** Entwickler:innen.
@@ -36,7 +36,7 @@ Der Code ist modular in `app` (Logik), `scripts` (CLI) und `config` (Steuerung)
     ├── config/             # YAML-Konfigurationen (Single Source of Truth)
     │   ├── types.yaml      # Import-Regeln
     │   ├── prompts.yaml    # LLM Prompts & RAG Templates (WP05)
-    │   └── retriever.yaml  # Scoring-Regeln
+    │   └── retriever.yaml  # Scoring-Regeln & Kantengewichte
     ├── data/
     │   └── logs/           # Lokale Logs (search_history.jsonl, feedback.jsonl)
     ├── scripts/            # CLI-Tools (Import, Diagnose, Reset)
@@ -168,47 +168,66 @@ Prüfen das laufende System (API) gegen eine echte Qdrant-Instanz und Ollama.
 
 ## 5. Das "Teach-the-AI" Paradigma (Context Intelligence)
 
-Mindnet lernt nicht durch Training (Fine-Tuning), sondern durch **Konfiguration** und **Kontext**. Wenn du dem System ein neues Konzept (z.B. "Risiko" oder "Strategie") beibringen willst, musst du an drei Stellen eingreifen. Dies ist der **Core-Workflow** für Erweiterungen.
+Mindnet lernt nicht durch Training (Fine-Tuning), sondern durch **Konfiguration**, **Vernetzung** und **Prompting**. Wenn du dem System ein neues Konzept beibringen willst, musst du in der Regel an drei Stellen eingreifen. Dies ist der **Core-Workflow** für Erweiterungen.
 
-### Das Dreieck der Bedeutung
-1.  **Daten-Ebene (`types.yaml`):** Definiert die Existenz und Wichtigkeit.
-2.  **Code-Ebene (`chat.py`):** Macht den Typ für das LLM sichtbar (Labeling).
-3.  **Kognitive Ebene (`prompts.yaml`):** Erklärt dem LLM, wie es den Typ interpretieren soll.
+### A. Workflow: Einen neuen Typ implementieren (z. B. `type: risk`)
 
-### Workflow: Einen neuen Typ implementieren (Bsp: `risk`)
-
-**Schritt 1: Physik definieren (`config/types.yaml`)**
-Definiere, wie der Typ importiert und gesucht wird.
+**1. Daten-Ebene (`config/types.yaml`)**
+Definiere die "Physik" des Typs (Import-Regeln und Basis-Wichtigkeit).
 
     risk:
       chunk_profile: short       # Risiken sind oft kurze Statements
       retriever_weight: 0.90     # Sehr wichtig, fast so hoch wie Decisions
-      edge_defaults: ["blocks"]  # Ein Risiko blockiert oft das verlinkte Projekt
+      edge_defaults: ["blocks"]  # Automatische Kante zu verlinkten Projekten
 
 *Ergebnis:* Notizen werden importiert und landen bei Suchen weit oben.
 
-**Schritt 2: Labeling prüfen (`app/routers/chat.py`)**
-Der Router (Funktion `_build_enriched_context`) liest das Feld `type` automatisch aus und injiziert es als `TYP: [RISK]` in den Prompt.
-* *Prüfung:* Keine Code-Änderung nötig, da der Router generisch programmiert ist.
-* *Ausnahme:* Wenn du spezielle Logik brauchst (z.B. "Risiken immer rot markieren"), müsstest du hier den Code anpassen.
+**2. Labeling-Ebene (`app/routers/chat.py`)**
+Der Router liest das Feld `type` automatisch aus und injiziert es als `TYP: [RISK]` in den Prompt.
+* *Prüfung:* Keine Code-Änderung nötig, da der Router generisch ist.
 
-**Schritt 3: Verstehen lehren (`config/prompts.yaml`)**
-Das LLM sieht nun `[RISK]`. Aber was soll es damit tun? Das definierst du hier.
-Ergänze den `system_prompt` oder das `rag_template`:
+**3. Kognitive Ebene (`config/prompts.yaml`)**
+Erkläre dem LLM, was `[RISK]` bedeutet. Ergänze den `system_prompt`:
 
     system_prompt: |
       ...
       REGELN FÜR TYPEN:
-      - [DECISION]: Begründung für Handlungen.
-      - [RISK]: Warnung! Wenn ein [RISK] im Kontext ist, weise den User darauf hin, bevor du eine Lösung empfiehlst.
+      - [RISK]: Warnung! Wenn ein [RISK] im Kontext ist, weise den User darauf hin.
 
-*Ergebnis:* Das System entwickelt ein "Risikobewusstsein".
+### B. Workflow: Neue Beziehungen (Edges) nutzen (z. B. `beeinflusst_von`)
+
+Beziehungen sind der Klebstoff für die "Why"-Erklärungen.
+
+**1. Erfassung im Vault (Markdown)**
+Du musst dem System keinen neuen Edge-Typ "beibringen" (Schema-less). Du nutzt ihn einfach.
+Nutze die Inline-Syntax im Fließtext:
+
+    Die Entscheidung für Qdrant wurde [[rel:beeinflusst_von Budgetkürzung 2024]].
+    Diese Strategie ist eine [[rel:reaktion_auf Marktveränderung]].
+
+*Ergebnis:* Der Importer erzeugt Kanten mit `kind="beeinflusst_von"`.
+
+**2. Gewichtung (`config/retriever.yaml`)**
+Standardmäßig werden alle expliziten Kanten gleich behandelt (hoher Bonus). Wenn du willst, dass `beeinflusst_von` *wichtiger* ist als `related_to`, konfigurierst du dies hier.
+
+    scoring:
+      edge_weight: 0.7
+      # Optional: Spezifische Boosts für Kanten-Typen (Advanced)
+      edge_type_weights:
+        beeinflusst_von: 1.5  # Sehr starker Einfluss auf das Ranking
+        reaktion_auf: 1.2
+        related_to: 0.5       # Schwächerer Einfluss
+
+*Hinweis:* Wenn `edge_type_weights` nicht definiert ist, gilt der Standard-Algorithmus (Confidence ~0.95 für Inline-Relations).
+
+**3. Verständnis beim LLM (`config/prompts.yaml`)**
+Damit der Chatbot versteht, dass "beeinflusst_von" eine Kausalität ist (und nicht nur Ähnlichkeit), kannst du dies im Prompt erklären, falls die Explanation-Daten in den Kontext geladen werden (Roadmap WP-06).
 
 ### Fazit
-Nur wenn **alle drei Ebenen** synchron sind, entsteht intelligente Persönlichkeit.
-* Ohne Schritt 1 findet das System die Notiz nicht.
-* Ohne Schritt 2 sieht das LLM nur Text, keinen Typ.
-* Ohne Schritt 3 ignoriert das LLM den Typ, weil es ihn nicht versteht.
+Nur wenn **Daten** (Vault), **Physik** (Config) und **Semantik** (Prompt) zusammenspielen, entsteht ein intelligenter Zwilling.
+* **Vault:** Liefert das Wissen.
+* **Config:** Liefert die Priorität (Weights).
+* **Prompt:** Liefert die Interpretation.
 
 ---