From 5d8e96372f6b3127dd3fc1d8d6fe58af2fd28b6b Mon Sep 17 00:00:00 2001 From: Lars Date: Mon, 8 Dec 2025 17:39:01 +0100 Subject: [PATCH] docs/developer_guide.md aktualisiert --- docs/developer_guide.md | 71 ++++++++++++++++++++++++++--------------- 1 file changed, 45 insertions(+), 26 deletions(-) diff --git a/docs/developer_guide.md b/docs/developer_guide.md index b8aec41..7006039 100644 --- a/docs/developer_guide.md +++ b/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. ---