neue Dokumentationstruktur - (QS geprüft)
Deploy mindnet to llm-node / deploy (push) Successful in 4s
Deploy mindnet to llm-node / deploy (push) Successful in 4s
This commit is contained in:
1 parent
0bb5f57cc6
commit
620858a575
39 files changed
+1840
No files matched your search
@@ -0,0 +1,292 @@
|
||||
# mindnet v2.4 – Knowledge Design Manual
|
||||
**Datei:** `docs/mindnet_knowledge_design_manual_v2.6.md`
|
||||
**Stand:** 2025-12-12
|
||||
**Status:** **FINAL** (Integrierter Stand WP01–WP15)
|
||||
**Quellen:** `knowledge_design.md`, `TYPE_REGISTRY_MANUAL.md`, `chunking_strategy.md`, `mindnet_functional_architecture.md`.
|
||||
|
||||
---
|
||||
|
||||
## ⚡ Die 5 Goldenen Regeln (TL;DR)
|
||||
|
||||
Damit Mindnet als dein Digitaler Zwilling funktioniert, beachte beim Schreiben diese Grundsätze:
|
||||
|
||||
1. **Atomare Gedanken:** Eine Notiz = Ein Thema. Wenn du über zwei Projekte schreibst, mach zwei Notizen draus.
|
||||
2. **Explizite Typen:** Setze immer den `type` im Frontmatter. Mindnet behandelt eine `decision` ("Wir machen X") völlig anders als ein `concept` ("Was ist X").
|
||||
3. **Semantische Links:** Schreibe nicht nur `[[Link]]`, sondern `[[rel:depends_on Link]]`. Sag dem System *wie* Dinge zusammenhängen.
|
||||
4. **Werte & Ziele definieren:** Damit die **Decision Engine** dich beraten kann, musst du deine Kriterien (`type: value`, `type: goal`) explizit als Notizen anlegen.
|
||||
5. **Emotionales Bridging:** Damit die **Empathie** funktioniert, nutze in Erfahrungsberichten (`type: experience`) emotionale Schlüsselwörter ("Krise", "Freude", "Angst"), damit der Vektor-Retriever sie bei Gefühls-Anfragen findet.
|
||||
|
||||
---
|
||||
|
||||
## 1. Zweck & Scope
|
||||
|
||||
Dieses Handbuch ist die **primäre Arbeitsanweisung** für dich als Mindmaster (Owner) und alle Autoren, die Inhalte im mindnet-Vault erstellen.
|
||||
|
||||
### 1.1 Zielsetzung
|
||||
Mindnet ist mehr als eine Dokumentablage. Es ist ein vernetztes System, das deine Persönlichkeit, Entscheidungen und Erfahrungen abbildet.
|
||||
Seit Version 2.6 verfügt Mindnet über:
|
||||
* **Hybrid Router:** Das System erkennt, ob du Fakten, Entscheidungen oder Empathie brauchst.
|
||||
* **Smart Edge Allocation:** Das System prüft deine Links intelligent und bindet sie nur an die Textabschnitte (Chunks), wo sie wirklich relevant sind.
|
||||
* **Web UI (WP10):** Du kannst direkt sehen, welche Quellen genutzt wurden.
|
||||
* **Active Intelligence (WP11):** Das System hilft dir beim Schreiben und Vernetzen (Link-Vorschläge).
|
||||
|
||||
### 1.2 Der Vault als „Source of Truth“
|
||||
Die Markdown-Dateien in deinem Vault sind die **einzige Quelle der Wahrheit**.
|
||||
* Mindnet importiert diesen Zustand deterministisch in die Datenbank (Qdrant).
|
||||
* Änderungen an IDs, Typen oder Inhalten müssen **immer** im Markdown erfolgen, niemals direkt in der Datenbank.
|
||||
* Was nicht im Markdown steht (z. B. implizites Wissen im Kopf), existiert für das System nicht.
|
||||
|
||||
---
|
||||
|
||||
## 2. Note-Struktur & Frontmatter
|
||||
|
||||
Jede Notiz benötigt einen YAML-Header (Frontmatter) am Dateianfang. Dieser Block macht die Notiz maschinenlesbar.
|
||||
|
||||
### 2.1 Pflichtfelder
|
||||
Jede Datei muss mindestens folgende Felder enthalten, um korrekt verarbeitet zu werden:
|
||||
|
||||
---
|
||||
id: 20251110-projekt-alpha-8a9b2c # Eindeutige Kennung (YYYYMMDD-slug)
|
||||
title: Projekt Alpha # Sprechender Titel (wird in Suchergebnissen angezeigt)
|
||||
type: project # Steuert Verarbeitung & Vernetzung (siehe Kap. 3)
|
||||
status: active # active, archived oder 'draft' (für generierte Notes)
|
||||
created: 2025-11-10 # Erstellungsdatum (ISO 8601 oder YYYY-MM-DD)
|
||||
updated: 2025-12-07 # Letzte Änderung
|
||||
tags: [ki, entwicklung] # Taxonomie für Filterung
|
||||
---
|
||||
|
||||
### 2.2 Optionale Felder
|
||||
Diese Felder sind technisch nicht zwingend, aber für bestimmte Typen sinnvoll:
|
||||
|
||||
lang: de # Sprache (Default: de)
|
||||
aliases: [Alpha Projekt, Project A] # Synonyme (WICHTIG für Exact Match in Intelligence)
|
||||
visibility: internal # internal (default), public, private
|
||||
|
||||
> **Hinweis:** Felder wie `retriever_weight` oder `chunk_profile` sollten **nicht** mehr manuell im Frontmatter gesetzt werden. Diese werden zentral über den `type` gesteuert (siehe Kap. 3), um die Wartbarkeit zu sichern.
|
||||
|
||||
### 2.3 Empfehlungen für IDs und Pfade
|
||||
|
||||
**Die ID (Identifikator):**
|
||||
* Muss global eindeutig und **stabil** sein.
|
||||
* Darf sich nicht ändern, wenn die Datei umbenannt oder verschoben wird.
|
||||
* **Empfehlung:** `YYYYMMDD-slug` (z. B. `20231027-vektor-db`). Dies garantiert Eindeutigkeit und Chronologie.
|
||||
|
||||
**Dateinamen & Pfade:**
|
||||
* Pfade dienen der menschlichen Ordnung (Ordnerstruktur), sind für Mindnet aber sekundär.
|
||||
* Dateinamen sollten dem Titel entsprechen (`Projekt Alpha.md`) oder dem Slug (`projekt-alpha.md`).
|
||||
* Sonderzeichen vermeiden (außer Bindestrich und Unterstrich).
|
||||
|
||||
---
|
||||
|
||||
## 3. Note-Typen & Typ-Registry
|
||||
|
||||
Der `type` ist der wichtigste Hebel im Knowledge Design. Er steuert nicht nur das Gewicht bei der Suche, sondern seit WP-06 auch, **wann** eine Notiz aktiv in den Chat geholt wird ("Strategic Retrieval") und seit WP-15, **ob Smart Edges aktiviert sind**.
|
||||
|
||||
### 3.1 Übersicht der Kern-Typen
|
||||
|
||||
Mindnet unterscheidet verschiedene Wissensarten. Wähle den Typ, der die **Rolle** der Notiz am besten beschreibt:
|
||||
|
||||
| Typ | Beschreibung & Einsatzzweck | Rolle im Chat (Intent) | Interview Schema (WP07) | Matrix-Logik (WP11) |
|
||||
| :--- | :--- | :--- | :--- | :--- |
|
||||
| **`concept`** | Fachbegriffe, Theorien. Zeitloses Wissen. | **FACT** | Titel, Definition, Tags | Ziel für `uses` |
|
||||
| **`project`** | Ein Vorhaben mit Ziel, Dauer und Aufgaben. | **FACT / DECISION** | Ziel, Status, Stakeholder | Quelle für `uses`, `depends_on` |
|
||||
| **`experience`** | Persönliche Erfahrung, Lektion oder Erkenntnis. | **EMPATHY** | Situation, Erkenntnis, Emotionen | Quelle für `based_on`, `derived_from` |
|
||||
| **`decision`** | Eine bewusst getroffene Entscheidung (ADR). | **DECISION** | Kontext, Entscheidung, Alternativen | Quelle für `depends_on`, `caused_by` |
|
||||
| **`value`** | Ein persönlicher Wert oder ein Prinzip. | **DECISION** | Definition, Anti-Beispiel | Ziel für `based_on` |
|
||||
| **`principle`** | Handlungsleitlinie. | **DECISION** | Regel, Ausnahme | Quelle für `derived_from` |
|
||||
| **`goal`** | Ein strategisches Ziel (kurz- oder langfristig). | **DECISION** | Zeitrahmen, KPIs, Werte | Ziel für `related_to` |
|
||||
| **`risk`** | Ein identifiziertes Risiko oder eine Gefahr. | **DECISION** | Auswirkung, Wahrscheinlichkeit | Quelle für `blocks` |
|
||||
| **`belief`** | Glaubenssatz / Überzeugung. | **EMPATHY** | Ursprung, Mantra | - |
|
||||
| **`person`** | Eine reale Person (Netzwerk, Autor). | **FACT** | Rolle, Kontext | - |
|
||||
| **`journal`** | Zeitbezogener Log-Eintrag, Daily Note. | **FACT** | Datum, Tags | - |
|
||||
| **`source`** | Externe Quelle (Buch, PDF, Artikel). | **FACT** | Autor, URL | - |
|
||||
|
||||
### 3.2 Zusammenspiel mit `types.yaml`
|
||||
|
||||
Der `type` steuert im Hintergrund drei technische Mechanismen:
|
||||
|
||||
1. **`retriever_weight` (Wichtigkeit):**
|
||||
* Ein `concept` (0.6) wiegt weniger als ein `project` (0.97) oder eine `decision` (1.0).
|
||||
2. **`chunk_profile` (Textzerlegung):**
|
||||
* `journal` (short): Wird fein zerlegt.
|
||||
* `experience` (sliding_smart_edges): Wird intelligent analysiert.
|
||||
3. **`enable_smart_edge_allocation` (WP15):**
|
||||
* Wenn `true`: Das System analysiert jeden Abschnitt mit KI, um zu prüfen, ob verlinkte Themen dort wirklich relevant sind. Das erhöht die Präzision massiv.
|
||||
|
||||
---
|
||||
|
||||
## 4. Edges & Referenzen in Notes
|
||||
|
||||
Um aus isolierten Dateien ein **Netzwerk** zu machen, nutzen wir Verlinkungen. In Version 2.2 sind diese Verlinkungen die Basis für den **Hybrid Retriever** (Suche über Nachbarn).
|
||||
|
||||
### 4.1 Wikilinks (Die Basis-Referenz)
|
||||
Der klassische Obsidian-Link.
|
||||
|
||||
Wir nutzen [[Qdrant]] als Vektordatenbank.
|
||||
|
||||
* **Bedeutung:** "Diese Notiz erwähnt Qdrant."
|
||||
* **Edge-Typ:** `references`
|
||||
|
||||
### 4.2 Inline-Relationen (Semantische Verknüpfung)
|
||||
Dies ist die **mächtigste** Methode. Du sagst dem System explizit, **wie** Dinge zusammenhängen.
|
||||
|
||||
Daher [[rel:depends_on Qdrant]].
|
||||
Dieses Konzept ist [[rel:similar_to Pinecone]].
|
||||
|
||||
* **Syntax:** `[[rel:RELATION ZIEL]]`.
|
||||
* **Gültige Relationen:**
|
||||
* `depends_on`: Hängt ab von / Benötigt. (Trigger für hohe Graph-Relevanz).
|
||||
* `similar_to`: Ähnelt / Ist vergleichbar mit.
|
||||
* `related_to`: Hat zu tun mit (allgemein).
|
||||
* `caused_by`: Wurde verursacht durch (Kausalität).
|
||||
* `solves`: Löst (Problem).
|
||||
* **`blocks`:** Blockiert oder gefährdet (z.B. Risiko -> Projekt).
|
||||
* **`derived_from`:** Stammt ab von (z.B. Prinzip -> Buch, Erfahrung -> Wert).
|
||||
* **`based_on`:** Basiert auf (Fundament).
|
||||
* **`uses`:** Nutzt (Werkzeug/Konzept).
|
||||
|
||||
### 4.3 Callout-Edges (Kuratierte Listen)
|
||||
Für Zusammenfassungen oder "Siehe auch"-Blöcke am Ende einer Notiz.
|
||||
|
||||
> [!edge] related_to: [[Vector Embeddings]] [[AI Agents]]
|
||||
|
||||
* **Funktion:** Erzeugt `related_to`-Kanten zu allen genannten Zielen in dieser Zeile.
|
||||
|
||||
---
|
||||
|
||||
## 5. Schreiben für den KI-Zwilling (New in v2.3/2.4)
|
||||
|
||||
Damit der **RAG-Chat (WP05/06)** nicht nur dumm Fakten wiedergibt, sondern dich berät, musst du "Futter" für die Decision Engine und das Empathie-Modul liefern.
|
||||
|
||||
### 5.1 Futter für die Decision Engine (`DECISION`)
|
||||
Das System soll abwägen: "Passt Tool X zu mir?". Dazu muss es wissen, was "Du" bist.
|
||||
|
||||
**Best Practice: Werte definieren**
|
||||
Erstelle Notizen mit `type: value`.
|
||||
|
||||
---
|
||||
type: value
|
||||
title: Prinzip: Datensparsamkeit
|
||||
---
|
||||
# Prinzip: Datensparsamkeit
|
||||
Wir speichern nur das Minimum an Daten. Cloud-Uploads persönlicher Daten sind verboten, es sei denn, sie sind E2E-verschlüsselt.
|
||||
|
||||
**Best Practice: Ziele definieren**
|
||||
Erstelle Notizen mit `type: goal`.
|
||||
|
||||
---
|
||||
type: goal
|
||||
title: Ziel: Unabhängigkeit 2026
|
||||
---
|
||||
# Ziel: Unabhängigkeit 2026
|
||||
Bis Ende 2026 wollen wir alle SaaS-Abos durch Self-Hosted Lösungen ersetzt haben.
|
||||
|
||||
*Effekt:* Wenn du fragst "Soll ich Notion nutzen?", lädt die Engine diese beiden Notizen und antwortet: *"Nein, Notion ist SaaS und nicht E2E-verschlüsselt. Das verletzt dein Prinzip der Datensparsamkeit und dein Ziel der Unabhängigkeit."*
|
||||
|
||||
### 5.2 Futter für den Empathie-Modus (`EMPATHY`)
|
||||
Das System soll dich verstehen, wenn du sagst: "Alles ist grau." Dazu braucht es deine Resonanzerfahrungen.
|
||||
|
||||
**Best Practice: Erfahrungen & Bridging**
|
||||
Erstelle Notizen mit `type: experience`. Nutze im Text **emotionale Brückenwörter**, damit der Retriever auch bei abstrakten Gefühlen ("grau") einen Treffer landet.
|
||||
|
||||
---
|
||||
type: experience
|
||||
title: Erfahrung: Der Durchbruch nach der Krise
|
||||
tags: [krise, hoffnung, grau, angst]
|
||||
---
|
||||
# Erfahrung: Der Durchbruch nach der Krise
|
||||
Es gibt Projektphasen, da wirkt alles **sinnlos** und **grau**.
|
||||
Ich habe gelernt: Das ist oft das Zeichen kurz vor dem Durchbruch.
|
||||
Mein Mantra in solchen Zeiten: "Einfach weitermachen, der Nebel lichtet sich."
|
||||
|
||||
*Effekt:* Wenn du im Chat jammerst ("Alles ist sinnlos"), findet das System diese Notiz und spiegelt dir deine eigene Erfahrung zurück.
|
||||
|
||||
### 5.3 Schreiben für den Chat (UI Optimization)
|
||||
Da deine Notizen im Web-Interface (WP10) angezeigt werden:
|
||||
* **Kurze Absätze:** Das LLM liest besser, und der Mensch scannt schneller.
|
||||
* **Klare Headings:** Nutze H1/H2, um dem Chunker logische Trennlinien zu geben.
|
||||
|
||||
### 5.4 Der Interview-Modus (Auto-Drafting)
|
||||
Seit v2.4 (WP07) kann Mindnet Notizen für dich entwerfen.
|
||||
|
||||
* **Wie:** Schreibe im Chat einfach: *"Ich möchte ein neues Projekt 'Alpha' anlegen, Ziel ist die Markteroberung."*
|
||||
* **Was passiert:** Mindnet erkennt den Wunsch (`INTERVIEW`), wählt das Schema für `project` und generiert **sofort** einen Markdown-Entwurf.
|
||||
* **Ergebnis:** Du erhältst einen Code-Block mit `status: draft`. Diesen kannst du im Draft-Editor (UI) direkt bearbeiten und herunterladen.
|
||||
* **Drafts:** Enthalten oft Platzhalter `[TODO]`. Das ist Absicht. Ergänze sie im Editor.
|
||||
|
||||
### 5.5 Futter für das Risikomanagement (`DECISION`)
|
||||
Damit Mindnet dich vor Fehlern warnen kann, musst du Risiken explizit machen.
|
||||
|
||||
**Best Practice: Risiken definieren**
|
||||
Erstelle Notizen mit `type: risk`. Nutze `blocks` oder `related_to`, um sie mit Projekten zu verknüpfen.
|
||||
|
||||
---
|
||||
type: risk
|
||||
title: Risiko: Vendor Lock-in bei Cloud-DBs
|
||||
tags: [architektur, kosten, abhängigkeit]
|
||||
---
|
||||
# Risiko: Vendor Lock-in bei Cloud-DBs
|
||||
Die Nutzung proprietärer Cloud-Datenbanken führt langfristig zu hohen Migrationskosten.
|
||||
Dies [[rel:blocks Ziel Unabhängigkeit 2026]].
|
||||
|
||||
*Effekt:* Wenn du fragst "Soll ich AWS DynamoDB nutzen?", erkennt die Decision Engine den Konflikt mit deinem Ziel "Unabhängigkeit" durch die Kante `blocks` und den hohen `retriever_weight` des Risikos.
|
||||
|
||||
---
|
||||
|
||||
## 6. Best Practices & Beispiele (Klassik)
|
||||
|
||||
### 6.1 Beispiel: Projekt-Notiz
|
||||
Projekte profitieren von `depends_on`, um Abhängigkeiten zu klären.
|
||||
|
||||
---
|
||||
id: 20251115-proj-mindnet
|
||||
title: Mindnet Implementierung
|
||||
type: project
|
||||
status: active
|
||||
---
|
||||
|
||||
# Mindnet Implementierung
|
||||
|
||||
Wir bauen ein persönliches Wissensnetz.
|
||||
|
||||
## Tech Stack
|
||||
Wir nutzen [[rel:depends_on Qdrant]] für die Vektorsuche und [[rel:depends_on FastAPI]] für das Backend.
|
||||
|
||||
## Architektur
|
||||
Das Konzept basiert auf [[RAG Architecture]]. (Automatisch 'depends_on' durch Typ-Default).
|
||||
|
||||
### 6.2 Beispiel: Entscheidung (Decision Record)
|
||||
Entscheidungen sind hoch gewichtet (`retriever_weight: 1.0`).
|
||||
|
||||
---
|
||||
id: 20251120-adr-vektordb
|
||||
title: ADR: Wahl von Qdrant
|
||||
type: decision
|
||||
status: final
|
||||
tags: [architektur, db]
|
||||
---
|
||||
|
||||
# Entscheidung: Qdrant
|
||||
|
||||
Wir haben uns für Qdrant entschieden.
|
||||
|
||||
## Alternativen
|
||||
Wir haben auch [[rel:similar_to Pinecone]] und [[rel:similar_to Weaviate]] betrachtet.
|
||||
|
||||
## Begründung
|
||||
Qdrant erlaubt lokalen Betrieb und [[rel:solves Payload Filtering Requirements]].
|
||||
|
||||
---
|
||||
|
||||
## 7. Langfristige Stabilität & Virtual Schema Layer
|
||||
|
||||
Mindnet ist auf Langlebigkeit ausgelegt.
|
||||
|
||||
### 7.1 Das "Virtual Schema" Prinzip
|
||||
Wir vermeiden es, Logik in den Markdown-Dateien hart zu kodieren.
|
||||
* Statt in jeder Notiz zu schreiben `chunk_size: 500`, schreiben wir nur `type: essay`.
|
||||
* Wie groß ein Chunk für ein Essay ist, definieren wir in der Konfiguration (`types.yaml`).
|
||||
|
||||
### 7.2 Was bedeutet das für dich?
|
||||
* Du kannst dich auf den Inhalt konzentrieren.
|
||||
* Wenn wir in Zukunft basierend auf Feedback lernen, dass "Projekte" noch wichtiger sind, ändern wir **eine Zeile** in der Konfiguration, und das gesamte System passt sich beim nächsten Import an.
|
||||
@@ -0,0 +1,105 @@
|
||||
# Mindnet v2.4 – Overview & Einstieg
|
||||
**Datei:** `docs/mindnet_overview_v2.6.md`
|
||||
**Stand:** 2025-12-12
|
||||
**Status:** **FINAL** (Inkl. Smart Edges, Traffic Control & Healing UI)
|
||||
**Version:** 2.6.0
|
||||
|
||||
---
|
||||
|
||||
## 1. Einführung: Was ist Mindnet?
|
||||
|
||||
**Mindnet** ist ein persönliches, lokales KI-Gedächtnis. Es ist der Versuch, einen **Digitalen Zwilling** deines Wissens und deiner Persönlichkeit zu erschaffen.
|
||||
|
||||
Anders als herkömmliche Notiz-Apps (wie Obsidian oder Evernote), die Texte nur passiv speichern, ist Mindnet ein **aktives System**:
|
||||
* Es **versteht** Zusammenhänge über einen Wissensgraphen.
|
||||
* Es **begründet** Antworten ("Warum ist das so?").
|
||||
* Es **unterstützt** beim Schreiben: Es schlägt automatisch Verbindungen zu bestehendem Wissen vor ("Active Intelligence").
|
||||
* Es **antwortet** situativ angepasst: Mal als Strategieberater, mal als empathischer Spiegel, und neu: **als Interviewer, der hilft, Wissen zu erfassen.**
|
||||
|
||||
### Die Vision
|
||||
> „Ein System, das nicht nur speichert, was ich weiß, sondern auch wie ich denke, fühle und arbeite.“
|
||||
|
||||
---
|
||||
|
||||
## 2. Die drei Ebenen des Systems
|
||||
|
||||
Mindnet arbeitet auf drei Schichten, die aufeinander aufbauen:
|
||||
|
||||
### Ebene 1: Content (Das Gedächtnis)
|
||||
* **Quelle:** Dein lokaler Obsidian-Vault (Markdown).
|
||||
* **Funktion:** Speicherung von Fakten, Projekten und Logs.
|
||||
* **Technik:** Async Import-Pipeline, Smart Chunking (LLM-gestützte Kantenzuweisung), Vektor-Datenbank (Qdrant).
|
||||
* **Status:** 🟢 Live (WP01–WP03, WP11, WP15).
|
||||
|
||||
### Ebene 2: Semantik (Das Verstehen)
|
||||
* **Funktion:** Verknüpfung von isolierten Notizen zu einem Netzwerk.
|
||||
* **Logik:** "Projekt A *hängt ab von* Entscheidung B".
|
||||
* **Technik:** Hybrider Retriever (Graph + Nomic Embeddings), Explanation Engine.
|
||||
* **Status:** 🟢 Live (WP04, WP11, WP15).
|
||||
|
||||
### Ebene 3: Identität & Interaktion (Die Persönlichkeit)
|
||||
* **Funktion:** Interaktion, Bewertung und Co-Creation.
|
||||
* **Logik:**
|
||||
* "Ich empfehle Lösung X, weil sie unserem Wert 'Datensparsamkeit' entspricht."
|
||||
* "Ich sehe, du willst ein Projekt starten. Lass uns die Eckdaten erfassen."
|
||||
* **Technik:**
|
||||
* **Hybrid Router v5:** Erkennt Absichten (Frage vs. Befehl) und unterscheidet Objekte (`types.yaml`) von Handlungen (`decision_engine.yaml`).
|
||||
* **Traffic Control:** Priorisiert Chat-Anfragen ("Realtime") vor Hintergrund-Jobs ("Background").
|
||||
* **One-Shot Extraction:** Generiert Entwürfe für neue Notizen.
|
||||
* **Active Intelligence:** Schlägt Links während des Schreibens vor.
|
||||
* **Status:** 🟢 Live (WP05–WP07, WP10, WP15).
|
||||
|
||||
---
|
||||
|
||||
## 3. End-to-End Architektur
|
||||
|
||||
Der Datenfluss in Mindnet ist zyklisch ("Data Flywheel"):
|
||||
|
||||
1. **Input:** Du schreibst Notizen in Obsidian **ODER** lässt sie von Mindnet im Chat entwerfen.
|
||||
2. **Intelligence (Live):** Während du schreibst, analysiert Mindnet den Text und schlägt Verknüpfungen vor (Sliding Window Analyse).
|
||||
3. **Ingest:** Ein asynchrones Python-Skript importiert und zerlegt die Daten.
|
||||
* **Neu (Smart Edges):** Ein LLM analysiert jeden Textabschnitt und entscheidet, welche Kanten relevant sind.
|
||||
4. **Intent Recognition:** Der Router analysiert deine Eingabe: Ist es eine Frage (RAG) oder ein Befehl (Interview)?
|
||||
5. **Retrieval / Action:**
|
||||
* Bei Fragen: Das System sucht Inhalte passend zum Intent.
|
||||
* Bei Interviews: Das System wählt das passende Schema (z.B. Projekt-Vorlage).
|
||||
6. **Generation:** Ein lokales LLM (Ollama) formuliert die Antwort oder den Markdown-Draft.
|
||||
7. **Feedback:** Du bewertest die Antwort. Das System lernt (langfristig) daraus.
|
||||
|
||||
**Tech-Stack:**
|
||||
* **Backend:** Python 3.10+, FastAPI (Async).
|
||||
* **Datenbank:** Qdrant (Vektor & Graph, 768 Dim).
|
||||
* **KI:** Ollama (Phi-3 Mini für Chat, Nomic für Embeddings) – 100% lokal.
|
||||
* **Traffic Control:** Semaphore-Logik zur Lastverteilung zwischen Chat und Import.
|
||||
* **Frontend:** Streamlit Web-UI (v2.5) mit Healing Parser.
|
||||
|
||||
---
|
||||
|
||||
## 4. Dokumentations-Wegweiser
|
||||
|
||||
Wo findest du was?
|
||||
|
||||
| Wenn du... | ...lies dieses Dokument |
|
||||
| :--- | :--- |
|
||||
| **...wissen willst, wie man Notizen schreibt.** | `mindnet_knowledge_design_manual_v2.6.md` |
|
||||
| **...das System installieren oder betreiben musst.** | `mindnet_admin_guide_v2.6.md` |
|
||||
| **...am Python-Code entwickeln willst.** | `mindnet_developer_guide_v2.6.md` |
|
||||
| **...die Pipeline (Import -> RAG) verstehen willst.** | `mindnet_pipeline_playbook_v2.6.md` |
|
||||
| **...die genaue JSON-Struktur oder APIs suchst.** | `mindnet_technical_architecture_v2.6.md` |
|
||||
| **...verstehen willst, was fachlich passiert.** | `mindnet_functional_architecture_v2.6.md` |
|
||||
| **...den aktuellen Projektstatus suchst.** | `mindnet_appendices_v2.6.md` |
|
||||
|
||||
---
|
||||
|
||||
## 5. Rollen im System
|
||||
|
||||
* **Mindmaster (User/Owner):** Du. Du erstellst Inhalte, stellst Fragen und gibst Feedback. Du definierst die Werte (`type: value`).
|
||||
* **Mindnet (Der Agent):** Der digitale Zwilling. Er agiert als pragmatischer, transparenter Assistent und Analyst.
|
||||
* **Administrator:** Verantwortlich für Docker-Container, Backups und LLM-Ressourcen.
|
||||
|
||||
---
|
||||
|
||||
## 6. Aktueller Fokus
|
||||
|
||||
Wir haben die **Smart Edge Allocation (WP15)** und die **System-Stabilisierung (Traffic Control)** erfolgreich abgeschlossen.
|
||||
Das System kann nun aktiv helfen, Wissen zu strukturieren, ohne dabei unter Last zusammenzubrechen. Der Fokus verschiebt sich nun in Richtung **Conversational Memory (WP17)** und **MCP Integration (WP13)**.
|
||||
@@ -0,0 +1,238 @@
|
||||
# Mindnet v2.4 – Admin Guide
|
||||
**Datei:** `docs/mindnet_admin_guide_v2.6.md`
|
||||
**Stand:** 2025-12-12
|
||||
**Status:** **FINAL** (Inkl. Traffic Control & Smart Edge Config)
|
||||
**Quellen:** `Handbuch.md`, `mindnet_developer_guide_v2.6.md`.
|
||||
|
||||
> Dieses Handbuch richtet sich an **Administratoren**. Es beschreibt Installation, Konfiguration, Backup-Strategien, Monitoring und den sicheren Betrieb der Mindnet-Instanz (API + UI + DB).
|
||||
|
||||
---
|
||||
|
||||
## 1. Zielgruppe & Scope
|
||||
|
||||
Mindnet ist als **Multi-Service-Architektur** konzipiert, die lokal oder auf einem privaten Server läuft.
|
||||
Wir unterscheiden strikt zwischen:
|
||||
* **Production:** Backend (8001) + Frontend (8501). Stabiler `main` Branch.
|
||||
* **Development:** Backend (8002) + Frontend (8502). Experimentelle Feature-Branches.
|
||||
|
||||
---
|
||||
|
||||
## 2. Initial Setup & Installation
|
||||
|
||||
### 2.1 Systemvoraussetzungen
|
||||
* **OS:** Linux (Ubuntu 22.04+ empfohlen) oder macOS.
|
||||
* **Runtime:** Python 3.10+, Docker (für Qdrant), Ollama (für LLM).
|
||||
* **Hardware:**
|
||||
* CPU: 4+ Cores empfohlen (für Async Import & Inference).
|
||||
* RAM: Min. 8GB empfohlen (4GB System + 4GB für Phi-3/Qdrant).
|
||||
* Disk: SSD empfohlen für Qdrant-Performance.
|
||||
|
||||
### 2.2 Installation (Code)
|
||||
|
||||
# 1. Repository klonen
|
||||
git clone <repo-url> /home/llmadmin/mindnet
|
||||
cd /home/llmadmin/mindnet
|
||||
|
||||
# 2. Umgebung einrichten
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
|
||||
# 3. Dependencies installieren (inkl. Streamlit, HTTPX)
|
||||
pip install -r requirements.txt
|
||||
|
||||
# 4. Verzeichnisse anlegen
|
||||
mkdir -p logs qdrant_storage data/logs vault
|
||||
|
||||
### 2.3 Qdrant Setup (Docker)
|
||||
Wir nutzen Qdrant als Vektor-Datenbank. Persistenz ist wichtig.
|
||||
|
||||
docker run -d \
|
||||
--name mindnet_qdrant \
|
||||
--restart always \
|
||||
-p 6333:6333 \
|
||||
-v $(pwd)/qdrant_storage:/qdrant/storage \
|
||||
qdrant/qdrant
|
||||
|
||||
### 2.4 Ollama Setup (LLM & Embeddings)
|
||||
Mindnet benötigt einen lokalen LLM-Server für Chat UND Embeddings.
|
||||
**WICHTIG (Update v2.4):** Es muss zwingend `nomic-embed-text` installiert sein, sonst startet der Import nicht.
|
||||
|
||||
# 1. Installieren (Linux Script)
|
||||
curl -fsSL https://ollama.com/install.sh | sh
|
||||
|
||||
# 2. Modelle laden
|
||||
ollama pull phi3:mini # Für Chat/Reasoning
|
||||
ollama pull nomic-embed-text # Für Vektoren (768 Dim)
|
||||
|
||||
# 3. Testen
|
||||
curl http://localhost:11434/api/generate -d '{"model": "phi3:mini", "prompt":"Hi"}'
|
||||
|
||||
### 2.5 Konfiguration (ENV)
|
||||
Erstelle eine `.env` Datei im Root-Verzeichnis. Achte besonders auf `VECTOR_DIM` und das neue `MINDNET_LLM_BACKGROUND_LIMIT`.
|
||||
|
||||
# Server Config
|
||||
UVICORN_HOST=0.0.0.0
|
||||
|
||||
# Qdrant Verbindung
|
||||
QDRANT_URL="http://localhost:6333"
|
||||
|
||||
# Mindnet Core Settings
|
||||
COLLECTION_PREFIX="mindnet"
|
||||
MINDNET_TYPES_FILE="./config/types.yaml"
|
||||
MINDNET_VAULT_ROOT="./vault"
|
||||
|
||||
# WICHTIG: Dimension auf 768 setzen (für Nomic)
|
||||
VECTOR_DIM=768
|
||||
|
||||
# AI Modelle (Ollama)
|
||||
MINDNET_OLLAMA_URL="http://127.0.0.1:11434"
|
||||
MINDNET_LLM_MODEL="phi3:mini"
|
||||
MINDNET_EMBEDDING_MODEL="nomic-embed-text"
|
||||
|
||||
# Timeouts (Erhöht für Async/Nomic/Smart Edges)
|
||||
MINDNET_LLM_TIMEOUT=300.0
|
||||
MINDNET_API_TIMEOUT=300.0 # Wichtig: Frontend muss warten können
|
||||
|
||||
# Traffic Control (Neu in v2.6)
|
||||
# Begrenzt parallele LLM-Calls im Import, um Chat stabil zu halten.
|
||||
MINDNET_LLM_BACKGROUND_LIMIT=2
|
||||
|
||||
# Configs
|
||||
MINDNET_PROMPTS_PATH="./config/prompts.yaml"
|
||||
MINDNET_DECISION_CONFIG="./config/decision_engine.yaml"
|
||||
|
||||
### 2.6 Deployment via Systemd (Backend & Frontend)
|
||||
|
||||
Mindnet benötigt zwei Services pro Umgebung: API (Uvicorn) und UI (Streamlit).
|
||||
|
||||
**Production Backend (`/etc/systemd/system/mindnet-prod.service`):**
|
||||
|
||||
[Unit]
|
||||
Description=Mindnet API Prod (8001)
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
User=llmadmin
|
||||
Group=llmadmin
|
||||
WorkingDirectory=/home/llmadmin/mindnet
|
||||
# Async Server Start
|
||||
ExecStart=/home/llmadmin/mindnet/.venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8001 --env-file .env
|
||||
Restart=always
|
||||
RestartSec=5
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
|
||||
**Production Frontend (`/etc/systemd/system/mindnet-ui-prod.service`):**
|
||||
|
||||
[Unit]
|
||||
Description=Mindnet UI Prod (8501)
|
||||
After=mindnet-prod.service
|
||||
|
||||
[Service]
|
||||
User=llmadmin
|
||||
Group=llmadmin
|
||||
WorkingDirectory=/home/llmadmin/mindnet
|
||||
|
||||
# Environment Variables
|
||||
Environment="MINDNET_API_URL=http://localhost:8001"
|
||||
Environment="MINDNET_API_TIMEOUT=300"
|
||||
Environment="STREAMLIT_SERVER_PORT=8501"
|
||||
Environment="STREAMLIT_SERVER_ADDRESS=0.0.0.0"
|
||||
Environment="STREAMLIT_SERVER_HEADLESS=true"
|
||||
|
||||
ExecStart=/home/llmadmin/mindnet/.venv/bin/streamlit run app/frontend/ui.py
|
||||
Restart=always
|
||||
RestartSec=5
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
|
||||
**Firewall (UFW):**
|
||||
Öffne die Ports für den Zugriff:
|
||||
|
||||
sudo ufw allow 8501/tcp # Prod UI
|
||||
sudo ufw allow 8502/tcp # Dev UI (falls gewünscht)
|
||||
|
||||
---
|
||||
|
||||
## 3. Betrieb im Alltag
|
||||
|
||||
### 3.1 Regelmäßige Importe
|
||||
Der Vault-Zustand sollte regelmäßig (z.B. stündlich per Cronjob) nach Qdrant synchronisiert werden. Das Skript nutzt nun **AsyncIO**, **Smart Edges** und **Traffic Control**.
|
||||
|
||||
**Cronjob-Beispiel (stündlich):**
|
||||
|
||||
0 * * * * cd /home/llmadmin/mindnet && .venv/bin/python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --purge-before-upsert --sync-deletes >> ./logs/import.log 2>&1
|
||||
|
||||
**Hinweis zu Smart Edges:**
|
||||
Der Import dauert nun länger (ca. 2-3 Min pro Datei), da das LLM intensiv genutzt wird. Dank `MINDNET_LLM_BACKGROUND_LIMIT=2` bleibt der Server dabei aber für den Chat responsive.
|
||||
|
||||
### 3.2 Health-Checks
|
||||
Prüfe regelmäßig, ob alle Komponenten laufen.
|
||||
|
||||
sudo systemctl status mindnet-prod
|
||||
sudo systemctl status mindnet-ui-prod
|
||||
sudo systemctl status ollama
|
||||
|
||||
### 3.3 Logs & Monitoring
|
||||
* **Backend Fehler:** `journalctl -u mindnet-prod -f`
|
||||
* **Frontend Fehler:** `journalctl -u mindnet-ui-prod -f`
|
||||
* **LLM Fehler:** `journalctl -u ollama -f`
|
||||
* **Fachliche Logs:** `data/logs/search_history.jsonl`
|
||||
|
||||
---
|
||||
|
||||
## 4. Troubleshooting (Update v2.6)
|
||||
|
||||
### "Vector dimension error: expected dim: 768, got 384"
|
||||
* **Ursache:** Du versuchst, in eine alte Qdrant-Collection (mit 384 Dim aus v2.2) neue Embeddings (mit 768 Dim von Nomic) zu schreiben.
|
||||
* **Lösung:** Full Reset erforderlich.
|
||||
1. `python -m scripts.reset_qdrant --mode wipe --prefix mindnet --yes` (Löscht DB).
|
||||
2. `python -m scripts.import_markdown ...` (Baut neu auf).
|
||||
|
||||
### "500 Internal Server Error" beim Speichern/Chatten
|
||||
* **Ursache:** Oft Timeout bei Ollama, wenn `nomic-embed-text` noch nicht im RAM geladen ist ("Cold Start") oder der Import die GPU blockiert.
|
||||
* **Lösung:**
|
||||
1. `MINDNET_LLM_TIMEOUT` in `.env` auf `300.0` setzen.
|
||||
2. `MINDNET_LLM_BACKGROUND_LIMIT` auf `1` reduzieren (falls Hardware schwach).
|
||||
|
||||
### Import ist sehr langsam
|
||||
* **Ursache:** Smart Edges sind aktiv (`types.yaml`) und analysieren jeden Chunk.
|
||||
* **Lösung:**
|
||||
* Akzeptieren (für bessere Qualität).
|
||||
* Oder für Massen-Initial-Import in `types.yaml` temporär `enable_smart_edge_allocation: false` setzen.
|
||||
|
||||
---
|
||||
|
||||
## 5. Backup & Restore
|
||||
|
||||
Datensicherheit ruht auf drei Säulen: Vault (Source), Qdrant (Index), JSONL-Logs (Lern-Daten).
|
||||
|
||||
### 5.1 Vault-Backup (Priorität 1)
|
||||
Der Markdown-Vault ist die **Single Source of Truth**.
|
||||
|
||||
### 5.2 Qdrant-Snapshots (Priorität 2)
|
||||
Für schnelle Wiederherstellung des Suchindex.
|
||||
|
||||
docker stop mindnet_qdrant
|
||||
tar -czf qdrant_backup_$(date +%F).tar.gz ./qdrant_storage
|
||||
docker start mindnet_qdrant
|
||||
|
||||
### 5.3 Notfall-Wiederherstellung (Rebuild)
|
||||
Wenn die Datenbank korrupt ist oder Modelle gewechselt werden:
|
||||
|
||||
# 1. DB komplett leeren (Wipe)
|
||||
python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet" --yes
|
||||
# 2. Alles neu importieren (Force re-calculates Hashes)
|
||||
python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force
|
||||
|
||||
---
|
||||
|
||||
## 6. Governance & Sicherheit
|
||||
|
||||
### 6.1 Zugriffsschutz
|
||||
Mindnet hat aktuell **keine integrierte Authentifizierung**.
|
||||
* **Frontend:** Streamlit auf Port 8501 ist offen. Nutze Nginx Basic Auth oder VPN.
|
||||
* **API:** Sollte nicht direkt im öffentlichen Netz stehen.
|
||||
* **Qdrant:** Auf `127.0.0.1` beschränken.
|
||||
@@ -0,0 +1,174 @@
|
||||
# Mindnet v2.4 – Appendices & Referenzen
|
||||
**Datei:** `docs/mindnet_appendices_v2.6.md`
|
||||
**Stand:** 2025-12-12
|
||||
**Status:** **FINAL** (Integrierter Stand WP01–WP15)
|
||||
**Quellen:** `TYPE_REGISTRY_MANUAL.md`, `chunking_strategy.md`, `mindnet_technical_architecture.md`, `Handbuch.md`.
|
||||
|
||||
> Dieses Dokument bündelt Tabellen, Schemata und technische Referenzen, die in den Prozess-Dokumenten (Playbook, Guides) den Lesefluss stören würden.
|
||||
|
||||
---
|
||||
|
||||
## Anhang A: Typ-Registry Referenz (Default-Werte)
|
||||
|
||||
Diese Tabelle zeigt die Standard-Konfiguration der `types.yaml` (Stand v2.6 / Config v1.6).
|
||||
|
||||
| Typ (`type`) | Chunk Profile | Retriever Weight | Smart Edges? | Beschreibung |
|
||||
| :--- | :--- | :--- | :--- | :--- |
|
||||
| **concept** | `sliding_smart_edges` | 0.60 | **Ja** | Abstrakte Begriffe, Theorien. |
|
||||
| **project** | `sliding_smart_edges` | 0.97 | **Ja** | Aktive Vorhaben. Hohe Priorität. |
|
||||
| **decision** | `structured_smart_edges` | 1.00 | **Ja** | Entscheidungen (ADRs). Höchste Prio. |
|
||||
| **experience** | `sliding_smart_edges` | 0.90 | **Ja** | Persönliche Learnings. Intensiv analysiert. |
|
||||
| **journal** | `sliding_standard` | 0.80 | Nein | Zeitgebundene Logs. Performance-optimiert. |
|
||||
| **person** | `sliding_standard` | 0.50 | Nein | Personen-Profile. |
|
||||
| **source** | `sliding_standard` | 0.50 | Nein | Externe Quellen (Bücher, PDFs). |
|
||||
| **event** | `sliding_standard` | 0.60 | Nein | Meetings, Konferenzen. |
|
||||
| **value** | `structured_smart_edges` | 1.00 | **Ja** | Persönliche Werte/Prinzipien. |
|
||||
| **principle** | `structured_smart_edges` | 1.00 | **Ja** | Handlungsleitlinien. |
|
||||
| **profile** | `structured_smart_edges` | 0.80 | **Ja** | Eigene Identitäts-Beschreibungen. |
|
||||
| **goal** | `sliding_standard` | 0.95 | Nein | Strategische Ziele. |
|
||||
| **belief** | `sliding_short` | 0.90 | Nein | Glaubenssätze. |
|
||||
| **risk** | `sliding_short` | 0.90 | Nein | Risiken & Gefahren. |
|
||||
| **task** | `sliding_short` | 0.70 | Nein | Aufgaben. |
|
||||
| **glossary** | `sliding_short` | 0.50 | Nein | Begriffsdefinitionen. |
|
||||
| **default** | `sliding_standard` | 1.00 | Nein | Fallback, wenn Typ unbekannt. |
|
||||
|
||||
---
|
||||
|
||||
## Anhang B: Edge-Typen & Semantik
|
||||
|
||||
Referenz aller implementierten Kantenarten (`kind`).
|
||||
|
||||
| Kind | Herkunft (Primär) | Symmetrisch? | Bedeutung & Nutzung |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `references` | Wikilink `[[...]]` | Nein | Standard-Verweis. "Erwähnt X". |
|
||||
| `belongs_to` | Struktur (Auto) | Nein | Verknüpft Chunk mit seiner Note. |
|
||||
| `next` / `prev` | Struktur (Auto) | Ja (Logisch) | Definiert Lesereihenfolge der Chunks. |
|
||||
| `depends_on` | Inline / Default | Nein | Harte Abhängigkeit. "Braucht X um zu funktionieren". |
|
||||
| `related_to` | Callout / Default | Ja (Oft) | Thematische Nähe. "Siehe auch X". |
|
||||
| `similar_to` | Inline | Ja | Inhaltliche Ähnlichkeit. "Ist wie X". |
|
||||
| `caused_by` | Inline | Nein | Kausalität. "X ist der Grund für Y". |
|
||||
| `solves` | Inline | Nein | Lösung. "Tool X löst Problem Y". |
|
||||
| `blocks` | Inline | Nein | **NEU:** Blockade. "Risiko X blockiert Projekt Y". |
|
||||
| `derived_from` | Matrix / Default | Nein | Herkunft. "Erkenntnis stammt aus Prinzip X". |
|
||||
| `based_on` | Matrix | Nein | Fundament. "Erfahrung basiert auf Wert Y". |
|
||||
| `uses` | Matrix | Nein | Nutzung. "Projekt nutzt Konzept Z". |
|
||||
|
||||
---
|
||||
|
||||
## Anhang C: Datenmodelle (JSON Payloads)
|
||||
|
||||
Diese sind die Felder, die effektiv in Qdrant gespeichert werden.
|
||||
|
||||
### C.1 Note Payload (`mindnet_notes`)
|
||||
|
||||
{
|
||||
"note_id": "string (keyword)", // UUIDv5 oder Slug
|
||||
"title": "string (text)", // Titel aus Frontmatter
|
||||
"type": "string (keyword)", // Typ (z.B. 'project')
|
||||
"retriever_weight": "float", // Numerische Wichtigkeit (0.0-1.0)
|
||||
"chunk_profile": "string", // Genutztes Profil (z.B. 'sliding_smart_edges')
|
||||
"edge_defaults": ["string"], // Liste der aktiven Default-Kanten
|
||||
"tags": ["string"], // Liste von Tags
|
||||
"created": "string (iso-date)", // Erstellungsdatum
|
||||
"updated": "integer", // Timestamp
|
||||
"fulltext": "string (no-index)" // Gesamter Text (für Recovery)
|
||||
}
|
||||
|
||||
### C.2 Chunk Payload (`mindnet_chunks`)
|
||||
|
||||
{
|
||||
"chunk_id": "string (keyword)", // Format: {note_id}#c{index}
|
||||
"note_id": "string (keyword)", // FK zur Note
|
||||
"type": "string (keyword)", // Typ-Kopie aus Note
|
||||
"text": "string (text)", // Reintext für Anzeige (ohne Overlap)
|
||||
"window": "string (text)", // Text + Overlap (für Embedding)
|
||||
"ord": "integer", // Laufende Nummer (1..N)
|
||||
"retriever_weight": "float", // Kopie aus Note (für Query-Speed)
|
||||
"chunk_profile": "string", // Vererbt von Note
|
||||
"neighbors_prev": ["string"], // ID des Vorgängers
|
||||
"neighbors_next": ["string"] // ID des Nachfolgers
|
||||
}
|
||||
|
||||
### C.3 Edge Payload (`mindnet_edges`)
|
||||
|
||||
{
|
||||
"edge_id": "string (keyword)", // Deterministischer Hash
|
||||
"source_id": "string (keyword)", // Chunk-ID (Start)
|
||||
"target_id": "string (keyword)", // Chunk-ID oder Note-Titel (Ziel)
|
||||
"kind": "string (keyword)", // z.B. 'depends_on'
|
||||
"scope": "string (keyword)", // Immer 'chunk'
|
||||
"rule_id": "string (keyword)", // Traceability: 'inline:rel', 'explicit:wikilink'
|
||||
"confidence": "float", // 0.0 - 1.0
|
||||
"note_id": "string (keyword)", // Owner Note ID
|
||||
"provenance": "keyword" // 'explicit', 'rule', 'smart' (NEU)
|
||||
}
|
||||
|
||||
---
|
||||
|
||||
## Anhang D: Environment Variablen
|
||||
|
||||
Diese Variablen steuern das Verhalten der Skripte und Container.
|
||||
|
||||
| Variable | Default | Beschreibung |
|
||||
| :--- | :--- | :--- |
|
||||
| `QDRANT_URL` | `http://localhost:6333` | URL zur Vektor-DB. |
|
||||
| `QDRANT_API_KEY` | *(leer)* | API-Key für Absicherung (optional). |
|
||||
| `COLLECTION_PREFIX` | `mindnet` | Namensraum für Collections (`{prefix}_notes` etc). |
|
||||
| `VECTOR_DIM` | `768` | **NEU:** Dimension für Embeddings (für Nomic). |
|
||||
| `MINDNET_TYPES_FILE` | `config/types.yaml` | Pfad zur Typ-Registry. |
|
||||
| `MINDNET_RETRIEVER_CONFIG`| `config/retriever.yaml`| Pfad zur Scoring-Konfiguration. |
|
||||
| `MINDNET_PROMPTS_PATH` | `config/prompts.yaml` | Pfad zu LLM-Prompts (Neu in v2.2). |
|
||||
| `MINDNET_DECISION_CONFIG` | `config/decision_engine.yaml` | Router & Interview Config (Neu in v2.3). |
|
||||
| `MINDNET_LLM_MODEL` | `phi3:mini` | Name des Chat-Modells. |
|
||||
| `MINDNET_EMBEDDING_MODEL` | `nomic-embed-text` | **NEU:** Name des Vektor-Modells. |
|
||||
| `MINDNET_OLLAMA_URL` | `http://127.0.0.1:11434`| URL zum LLM-Server (Neu in v2.2). |
|
||||
| `MINDNET_LLM_TIMEOUT` | `300.0` | Timeout für Ollama (Erhöht für CPU-Inference). |
|
||||
| `MINDNET_API_TIMEOUT` | `300.0` | **NEU:** Frontend Timeout (Erhöht für Smart Edges). |
|
||||
| `MINDNET_LLM_BACKGROUND_LIMIT`| `2` | **NEU:** Max. parallele Import-Tasks (Traffic Control). |
|
||||
| `MINDNET_VAULT_ROOT` | `./vault` | **NEU:** Pfad für Write-Back Operationen. |
|
||||
| `MINDNET_HASH_COMPARE` | `Body` | Vergleichsmodus für Import (`Body`, `Frontmatter`, `Full`). |
|
||||
| `MINDNET_HASH_SOURCE` | `parsed` | Quelle für Hash (`parsed`, `raw`, `file`). |
|
||||
|
||||
---
|
||||
|
||||
## Anhang E: Glossar
|
||||
|
||||
* **Active Intelligence:** Feature, das während des Schreibens Links vorschlägt.
|
||||
* **Async Ingestion:** Non-blocking Import-Prozess zur Vermeidung von Timeouts.
|
||||
* **Decision Engine:** Komponente, die den Intent prüft und Strategien wählt (WP06).
|
||||
* **Draft Editor:** Web-Komponente zur Bearbeitung generierter Notizen (WP10a).
|
||||
* **Explanation Layer:** Komponente, die Scores und Graphen als Begründung liefert.
|
||||
* **Healing Parser:** UI-Funktion, die defektes YAML von LLMs repariert (v2.5).
|
||||
* **Hybrid Router:** Kombination aus Keyword-Matching und LLM-Klassifizierung für Intents.
|
||||
* **Matrix Logic:** Regelwerk, das Kanten-Typen basierend auf Quell- und Ziel-Typ bestimmt.
|
||||
* **Nomic:** Das neue, hochpräzise Embedding-Modell (768 Dim).
|
||||
* **One-Shot Extractor:** LLM-Strategie zur sofortigen Generierung von Drafts ohne Rückfragen (WP07).
|
||||
* **RAG (Retrieval Augmented Generation):** Kombination aus Suche und Text-Generierung.
|
||||
* **Resurrection Pattern:** UI-Technik, um Eingaben bei Tab-Wechseln zu erhalten.
|
||||
* **Smart Edge Allocation:** LLM-basierte Prüfung, ob ein Link zu einem Chunk passt (WP15).
|
||||
* **Traffic Control:** Priorisierung von Chat-Anfragen ("Realtime") vor Import-Last ("Background") im LLM-Service (v2.6).
|
||||
|
||||
---
|
||||
|
||||
## Anhang F: Workpackage Status (v2.6.0)
|
||||
|
||||
Aktueller Implementierungsstand der Module.
|
||||
|
||||
| WP | Titel | Status | Anmerkung |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **WP01** | Knowledge Design | 🟢 Live | Typen, Frontmatter definiert. |
|
||||
| **WP02** | Chunking Strategy | 🟢 Live | Profilbasiertes Chunking aktiv. |
|
||||
| **WP03** | Edge Logic / Import | 🟢 Live | Neue Importer-Pipeline mit Provenance. |
|
||||
| **WP04a**| Retriever Scoring | 🟢 Live | Hybrider Score (Semantik + Graph). |
|
||||
| **WP04b**| Explanation Layer | 🟢 Live | API liefert Reasons & Breakdown. |
|
||||
| **WP04c**| Feedback Loop | 🟢 Live | Logging (JSONL) & Traceability aktiv. |
|
||||
| **WP05** | Persönlichkeit / Chat | 🟢 Live | RAG-Integration mit Context Enrichment. |
|
||||
| **WP06** | Decision Engine | 🟢 Live | Hybrid Router v5, Strategic Retrieval. |
|
||||
| **WP07** | Interview Assistent | 🟢 Live | **One-Shot Extractor & Schemas aktiv.** |
|
||||
| **WP08** | Self-Tuning | 🔴 Geplant | Auto-Adjustment der Gewichte. |
|
||||
| **WP10** | Chat Interface | 🟢 Live | Web-Interface (Streamlit). |
|
||||
| **WP10a**| Draft Editor | 🟢 Live | **Interaktives UI & Healing Parser.** |
|
||||
| **WP11** | Backend Intelligence | 🟢 Live | **Async Ingestion, Nomic, Matrix.** |
|
||||
| **WP15** | Smart Edge Allocation | 🟢 Live | **LLM-Filter & Traffic Control.** |
|
||||
| **WP16** | Auto-Discovery | 🟡 Geplant | UX & Retrieval Tuning. |
|
||||
| **WP17** | Conversational Memory | 🟡 Geplant | Dialog-Gedächtnis. |
|
||||
@@ -0,0 +1,220 @@
|
||||
# Mindnet v2.4 – Entwickler-Workflow
|
||||
**Datei:** `docs/DEV_WORKFLOW.md`
|
||||
**Stand:** 2025-12-12 (Aktualisiert: v2.6 mit Traffic Control)
|
||||
|
||||
Dieses Handbuch beschreibt den Entwicklungszyklus zwischen **Windows PC** (IDE), **Raspberry Pi** (Gitea) und **Beelink** (Runtime/Server).
|
||||
|
||||
---
|
||||
|
||||
## 1. Die Architektur
|
||||
|
||||
* **Windows 11 (VS Code):** Hier schreibst du Code. **Nie** direkt auf `main` arbeiten!
|
||||
* **Raspberry Pi (Gitea):** Der Tresor. Speichert den Code und verwaltet Versionen.
|
||||
* **Beelink (Runtime):** Hier läuft die Software. Wir nutzen **Systemd-Services**:
|
||||
* **PROD:**
|
||||
* API: `mindnet-prod` (Port 8001). Ordner: `~/mindnet`.
|
||||
* UI: `mindnet-ui-prod` (Port 8501).
|
||||
* **DEV:**
|
||||
* API: `mindnet-dev` (Port 8002). Ordner: `~/mindnet_dev`.
|
||||
* UI: `mindnet-ui-dev` (Port 8502).
|
||||
|
||||
---
|
||||
|
||||
## 2. Der Zyklus: Von der Idee zum Release
|
||||
|
||||
### Phase 1: Entwicklung (Windows / VS Code)
|
||||
|
||||
Hier erstellst du die neue Funktion in einer sicheren Umgebung.
|
||||
|
||||
1. **Basis aktualisieren (WICHTIG!):**
|
||||
Bevor du startest, muss dein lokales `main` auf dem Stand des Servers sein.
|
||||
* Klicke unten links auf den aktuellen Branch und wähle **`main`**.
|
||||
* Klicke links im Menü "Source Control" auf die **drei Punkte (...)** -> **Pull** (oder das Synchronisieren-Symbol).
|
||||
* *Erst jetzt hast du alle Dateien!*
|
||||
|
||||
2. **Branch erstellen:**
|
||||
* Klicke wieder unten links auf `main`.
|
||||
* Wähle `+ Create new branch...`.
|
||||
* Gib den Namen ein: `feature/was-ich-tue` (z.B. `feature/wp15-traffic-control`).
|
||||
* Drücke **Enter**.
|
||||
|
||||
3. **Sicherheits-Check:**
|
||||
* Steht unten links jetzt dein Feature-Branch? **Nur dann darfst du Code ändern!**
|
||||
|
||||
4. **Coden:**
|
||||
* Nimm deine Änderungen vor (z.B. neue Schemas in `types.yaml` oder Async-Logik in `ingestion.py`).
|
||||
|
||||
5. **Sichern & Hochladen:**
|
||||
* **Source Control** Icon (Gabel-Symbol) -> Nachricht eingeben -> **Commit**.
|
||||
* **Publish Branch** (oder "Sync Changes"), um den Branch zum Raspberry Pi (Gitea) zu senden.
|
||||
|
||||
---
|
||||
|
||||
### Phase 2: Testen (Beelink / `mindnet_dev`)
|
||||
|
||||
Hier prüfst du, ob dein neuer Code auf dem echten Server läuft.
|
||||
|
||||
1. **Einloggen:**
|
||||
`ssh user@<BEELINK-IP>`
|
||||
|
||||
2. **In die Werkstatt gehen:**
|
||||
`cd /home/llmadmin/mindnet_dev`
|
||||
|
||||
3. **Code holen:**
|
||||
```bash
|
||||
git fetch
|
||||
# Tipp: 'git branch -r' zeigt alle verfügbaren Branches an
|
||||
git checkout feature/wp15-traffic-control
|
||||
git pull
|
||||
```
|
||||
|
||||
4. **Umgebung vorbereiten (WICHTIG für v2.6):**
|
||||
Prüfe deine `.env` Datei. Sie benötigt jetzt Einträge für die Traffic Control.
|
||||
```bash
|
||||
nano .env
|
||||
```
|
||||
**Ergänze/Prüfe:**
|
||||
```ini
|
||||
# Traffic Control (Neu in v2.6)
|
||||
MINDNET_LLM_BACKGROUND_LIMIT=2 # Max. parallele Import-Tasks
|
||||
MINDNET_API_TIMEOUT=300.0 # Frontend wartet länger
|
||||
MINDNET_EMBEDDING_MODEL="nomic-embed-text"
|
||||
```
|
||||
|
||||
**Dependencies aktualisieren:**
|
||||
```bash
|
||||
source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
ollama pull nomic-embed-text
|
||||
```
|
||||
|
||||
5. **Test-Server aktualisieren (WICHTIG):**
|
||||
Der Code ist da, aber die Prozesse im RAM sind noch alt. Wir müssen die Services neustarten.
|
||||
|
||||
**Option A: Standard (Als Service laufen lassen)**
|
||||
Ideal, wenn du nur testen willst, ob es läuft.
|
||||
```bash
|
||||
# 1. API neustarten (Backend)
|
||||
sudo systemctl restart mindnet-dev
|
||||
# 2. UI neustarten (Frontend)
|
||||
sudo systemctl restart mindnet-ui-dev
|
||||
|
||||
# Logs prüfen (um Fehler zu sehen):
|
||||
journalctl -u mindnet-dev -f
|
||||
```
|
||||
|
||||
**Option B: Manuell Debuggen (Direct Output)**
|
||||
Ideal, wenn du Print-Ausgaben direkt sehen willst oder der Service dauernd crasht.
|
||||
```bash
|
||||
# 1. Services stoppen (wichtig, sonst sind Ports 8002/8502 belegt!)
|
||||
sudo systemctl stop mindnet-dev
|
||||
sudo systemctl stop mindnet-ui-dev
|
||||
|
||||
# 2. Manuell starten (z.B. API)
|
||||
uvicorn app.main:app --host 0.0.0.0 --port 8002 --env-file .env
|
||||
```
|
||||
|
||||
6. **Validieren (Smoke Tests v2.6):**
|
||||
|
||||
* **Test A: Last-Test (Traffic Control):**
|
||||
1. Starte einen Import im Terminal: `python3 -m scripts.import_markdown ...`
|
||||
2. Öffne **gleichzeitig** `http://<IP>:8502` im Browser.
|
||||
3. Stelle eine Chat-Frage ("Was ist Mindnet?").
|
||||
4. **Erwartung:** Der Chat antwortet sofort (Realtime Lane), während der Import im Hintergrund weiterläuft (Background Lane).
|
||||
|
||||
* **Test B: API Check**
|
||||
```bash
|
||||
curl -X POST "http://localhost:8002/ingest/analyze" -d '{"text": "mindnet", "type": "journal"}'
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Release (Gitea / Raspberry Pi)
|
||||
|
||||
Wenn der Test auf Port 8002 / 8502 erfolgreich war:
|
||||
|
||||
1. Öffne Gitea im Browser.
|
||||
2. Erstelle einen **Pull Request** (Dein Branch -> `main`).
|
||||
3. **Merge** den Pull Request.
|
||||
|
||||
---
|
||||
|
||||
### Phase 4: Deployment (Beelink / `mindnet`)
|
||||
|
||||
Jetzt bringen wir die Änderung in das Live-System (Port 8001 / 8501).
|
||||
|
||||
1. **Deploy-Agent (Automatisch):**
|
||||
Wenn dein `deploy.yml` aktiv ist, passiert das jetzt von selbst!
|
||||
|
||||
2. **Manuell (Falls nötig):**
|
||||
```bash
|
||||
cd /home/llmadmin/mindnet
|
||||
git pull origin main
|
||||
|
||||
# Dependencies updaten & Modelle checken
|
||||
source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
ollama pull nomic-embed-text
|
||||
|
||||
# .env prüfen (Traffic Control)
|
||||
# Ggf. MINDNET_LLM_BACKGROUND_LIMIT=2 hinzufügen
|
||||
|
||||
# Falls sich die Vektor-Dimension geändert hat (v2.4 Upgrade):
|
||||
# python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet" --yes
|
||||
# python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force
|
||||
|
||||
# Produktions-Services neustarten
|
||||
sudo systemctl restart mindnet-prod
|
||||
sudo systemctl restart mindnet-ui-prod
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 5: Aufräumen (Optional aber empfohlen)
|
||||
|
||||
Damit das Chaos nicht wächst, löschen wir den fertigen Branch.
|
||||
|
||||
1. **Gitea:** Im Pull Request auf "Delete Branch" klicken.
|
||||
2. **Beelink (Dev):**
|
||||
```bash
|
||||
cd ~/mindnet_dev
|
||||
git checkout main
|
||||
git pull
|
||||
git branch -d feature/wp15-traffic-control
|
||||
```
|
||||
3. **VS Code:**
|
||||
* Auf `main` wechseln.
|
||||
* Sync drücken.
|
||||
* `F1` -> `Git: Delete Branch` -> Branch auswählen.
|
||||
|
||||
---
|
||||
|
||||
## 3. Cheat Sheet: Die wichtigsten Befehle
|
||||
|
||||
| Wo? | Befehl | Was tut es? |
|
||||
| :--- | :--- | :--- |
|
||||
| **Beelink** | `sudo systemctl restart mindnet-dev` | **Neustart Dev-Backend (Port 8002).** |
|
||||
| **Beelink** | `sudo systemctl restart mindnet-ui-dev` | **Neustart Dev-Frontend (Port 8002).** |
|
||||
| **Beelink** | `journalctl -u mindnet-dev -f` | **Live-Logs Backend.** |
|
||||
| **Beelink** | `python debug_analysis.py` | **Prüft Aliases & Scores.** |
|
||||
| **Beelink** | `python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet_dev" --yes` | **Löscht & Repariert DB.** |
|
||||
| **Beelink** | `python3 -m scripts.import_markdown --vault ./vault_master --prefix "mindnet_dev" --apply --force` | **Löscht & Repariert DB.** |
|
||||
| **Beelink** | `source .venv/bin/activate` | **Aktivieren des virtual environments** |
|
||||
|
||||
---
|
||||
|
||||
## 4. Troubleshooting
|
||||
|
||||
**"Read timed out" im Frontend**
|
||||
* **Ursache:** Backend braucht für Smart Edges länger als 60s.
|
||||
* **Lösung:** `MINDNET_API_TIMEOUT=300.0` in `.env` setzen und Services neustarten.
|
||||
|
||||
**Import ist extrem langsam**
|
||||
* **Ursache:** Smart Edges analysieren jeden Chunk mit LLM.
|
||||
* **Lösung:**
|
||||
* Akzeptieren (Qualität vor Speed).
|
||||
* Oder temporär in `config/types.yaml`: `enable_smart_edge_allocation: false`.
|
||||
|
||||
**"UnicodeDecodeError in .env"**
|
||||
* **Ursache:** Umlaute oder Sonderzeichen in der `.env` Datei.
|
||||
* **Lösung:** `.env` bereinigen (nur ASCII nutzen) und sicherstellen, dass sie UTF-8 ohne BOM ist.
|
||||
@@ -0,0 +1,310 @@
|
||||
# Mindnet v2.4 – Developer Guide
|
||||
**Datei:** `docs/mindnet_developer_guide_v2.6.md`
|
||||
**Stand:** 2025-12-12
|
||||
**Status:** **FINAL** (Inkl. Async Core, Nomic, Traffic Control & Frontend State)
|
||||
**Quellen:** `mindnet_technical_architecture.md`, `Handbuch.md`, `DEV_WORKFLOW.md`.
|
||||
|
||||
> **Zielgruppe:** Entwickler:innen.
|
||||
> **Zweck:** Anleitung zum Aufsetzen der Entwicklungsumgebung, Verständnis der Modulstruktur und Durchführung von Tests.
|
||||
|
||||
---
|
||||
- [Mindnet v2.4 – Developer Guide](#mindnet-v24--developer-guide)
|
||||
- [1. Projektstruktur (Post-WP15)](#1-projektstruktur-post-wp15)
|
||||
- [2. Lokales Setup (Development)](#2-lokales-setup-development)
|
||||
- [2.1 Voraussetzungen](#21-voraussetzungen)
|
||||
- [2.2 Installation](#22-installation)
|
||||
- [2.3 Konfiguration (Environment)](#23-konfiguration-environment)
|
||||
- [2.4 Dienste starten (API \& UI)](#24-dienste-starten-api--ui)
|
||||
- [3. Core-Module \& Entwicklung](#3-core-module--entwicklung)
|
||||
- [3.1 Der Importer (`scripts.import_markdown`)](#31-der-importer-scriptsimport_markdown)
|
||||
- [3.2 Der Hybrid Router (`app.routers.chat`)](#32-der-hybrid-router-approuterschat)
|
||||
- [3.3 Der Retriever (`app.core.retriever`)](#33-der-retriever-appcoreretriever)
|
||||
- [3.4 Das Frontend (`app.frontend.ui`)](#34-das-frontend-appfrontendui)
|
||||
- [3.5 Embedding Service (`app.services.embeddings_client`)](#35-embedding-service-appservicesembeddings_client)
|
||||
- [3.6 Traffic Control (`app.services.llm_service`)](#36-traffic-control-appservicesllm_service)
|
||||
- [4. Tests \& Debugging](#4-tests--debugging)
|
||||
- [4.1 Unit Tests (Pytest)](#41-unit-tests-pytest)
|
||||
- [4.2 Integration / Pipeline Tests](#42-integration--pipeline-tests)
|
||||
- [4.3 Smoke Tests (E2E)](#43-smoke-tests-e2e)
|
||||
- [5. Das "Teach-the-AI" Paradigma (Context Intelligence)](#5-das-teach-the-ai-paradigma-context-intelligence)
|
||||
- [A. Workflow: Einen neuen Typ implementieren (z. B. `type: risk`)](#a-workflow-einen-neuen-typ-implementieren-z-b-type-risk)
|
||||
- [B. Workflow: Neue Beziehungen (Edges) nutzen (z. B. `beeinflusst_von`)](#b-workflow-neue-beziehungen-edges-nutzen-z-b-beeinflusst_von)
|
||||
- [C. Workflow: Interview-Schema anpassen (WP07)](#c-workflow-interview-schema-anpassen-wp07)
|
||||
- [Fazit](#fazit)
|
||||
- [6. Nützliche Einzeiler](#6-nützliche-einzeiler)
|
||||
|
||||
---
|
||||
|
||||
## 1. Projektstruktur (Post-WP15)
|
||||
|
||||
Der Code ist modular in `app` (Logik), `scripts` (CLI) und `config` (Steuerung) getrennt.
|
||||
|
||||
mindnet/
|
||||
├── app/
|
||||
│ ├── core/ # Kernlogik
|
||||
│ │ ├── ingestion.py # NEU: Async Ingestion Service mit Change Detection
|
||||
│ │ ├── chunker.py # Smart Chunker Orchestrator
|
||||
│ │ ├── derive_edges.py # Edge-Erzeugung (WP03 Logik)
|
||||
│ │ ├── retriever.py # Scoring & Hybrid Search
|
||||
│ │ ├── qdrant.py # DB-Verbindung
|
||||
│ │ └── ...
|
||||
│ ├── models/ # Pydantic DTOs
|
||||
│ │ └── dto.py # Zentrale DTO-Definition
|
||||
│ ├── routers/ # FastAPI Endpoints
|
||||
│ │ ├── query.py # Suche
|
||||
│ │ ├── ingest.py # NEU: Save/Analyze (WP11)
|
||||
│ │ ├── chat.py # Hybrid Router v5 & Interview Logic
|
||||
│ │ ├── feedback.py # Feedback (WP04c)
|
||||
│ │ └── ...
|
||||
│ ├── services/ # Interne & Externe Dienste
|
||||
│ │ ├── llm_service.py # Ollama Client mit Traffic Control
|
||||
│ │ ├── semantic_analyzer.py# NEU: LLM-Filter für Edges (WP15)
|
||||
│ │ ├── embeddings_client.py# Async Embeddings (HTTPX)
|
||||
│ │ ├── feedback_service.py # Logging (JSONL Writer)
|
||||
│ │ └── discovery.py # NEU: Intelligence Logic (WP11)
|
||||
│ ├── frontend/ # NEU (WP10)
|
||||
│ │ └── ui.py # Streamlit Application inkl. Healing Parser
|
||||
│ └── main.py # Entrypoint der API
|
||||
├── config/ # YAML-Konfigurationen (Single Source of Truth)
|
||||
│ ├── types.yaml # Import-Regeln & Smart-Edge Config
|
||||
│ ├── prompts.yaml # LLM Prompts & Interview Templates
|
||||
│ ├── decision_engine.yaml # Router-Strategien (Actions only)
|
||||
│ └── retriever.yaml # Scoring-Regeln & Kantengewichte
|
||||
├── data/
|
||||
│ └── logs/ # Lokale Logs (search_history.jsonl, feedback.jsonl)
|
||||
├── scripts/ # CLI-Tools (Import, Diagnose, Reset)
|
||||
├── tests/ # Pytest Suite & Smoke Scripts
|
||||
└── vault/ # Dein lokaler Markdown-Content (Git-ignored)
|
||||
|
||||
---
|
||||
|
||||
## 2. Lokales Setup (Development)
|
||||
|
||||
### 2.1 Voraussetzungen
|
||||
* **Python:** 3.10 oder höher.
|
||||
* **Docker:** Für Qdrant.
|
||||
* **Ollama:** Für lokale LLM-Inference (erforderlich für `/chat` und Embeddings).
|
||||
* **Vault:** Ein Ordner mit Markdown-Dateien (z.B. `./mindnet_v2_test_vault` für Tests).
|
||||
|
||||
### 2.2 Installation
|
||||
|
||||
# 1. Repository klonen & Verzeichnis wechseln
|
||||
git clone <repo> mindnet
|
||||
cd mindnet
|
||||
|
||||
# 2. Virtual Environment erstellen
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
|
||||
# 3. Abhängigkeiten installieren (inkl. Streamlit)
|
||||
pip install -r requirements.txt
|
||||
|
||||
# 4. Ollama Setup (Modelle laden)
|
||||
# Chat-Modell (Phi-3)
|
||||
ollama pull phi3:mini
|
||||
# Embedding-Modell (Nomic) - PFLICHT für v2.4!
|
||||
ollama pull nomic-embed-text
|
||||
|
||||
### 2.3 Konfiguration (Environment)
|
||||
Erstelle eine `.env` Datei im Root-Verzeichnis.
|
||||
|
||||
# Qdrant Verbindung
|
||||
QDRANT_URL="http://localhost:6333"
|
||||
QDRANT_API_KEY="" # Leer lassen für lokal
|
||||
|
||||
# Mindnet Core Settings
|
||||
COLLECTION_PREFIX="mindnet_dev"
|
||||
VECTOR_DIM=768 # NEU: 768 für Nomic (vorher 384)
|
||||
MINDNET_TYPES_FILE="./config/types.yaml"
|
||||
MINDNET_RETRIEVER_CONFIG="./config/retriever.yaml"
|
||||
MINDNET_VAULT_ROOT="./vault"
|
||||
|
||||
# LLM / RAG Settings (WP06/07)
|
||||
MINDNET_LLM_MODEL="phi3:mini"
|
||||
MINDNET_EMBEDDING_MODEL="nomic-embed-text" # NEU
|
||||
MINDNET_OLLAMA_URL="http://127.0.0.1:11434"
|
||||
MINDNET_LLM_TIMEOUT=300.0 # Timeout für CPU-Inference Cold-Starts
|
||||
MINDNET_DECISION_CONFIG="./config/decision_engine.yaml"
|
||||
MINDNET_LLM_BACKGROUND_LIMIT=2 # NEU: Limit für parallele Import-Tasks
|
||||
|
||||
# Frontend Settings (WP10)
|
||||
MINDNET_API_URL="http://localhost:8002"
|
||||
MINDNET_API_TIMEOUT=300.0 # Erhöht wegen Smart Edge Berechnung
|
||||
|
||||
# Import-Strategie
|
||||
MINDNET_HASH_COMPARE="Body"
|
||||
MINDNET_HASH_SOURCE="parsed"
|
||||
|
||||
### 2.4 Dienste starten (API & UI)
|
||||
|
||||
Wir entwickeln mit zwei Services. Du kannst sie manuell in zwei Terminals starten oder die Systemd-Services nutzen (siehe `admin_guide.md`).
|
||||
|
||||
**Terminal A: Backend (API)**
|
||||
|
||||
# Startet auf Port 8002 (Dev Standard)
|
||||
uvicorn app.main:app --host 0.0.0.0 --port 8002 --env-file .env --reload
|
||||
|
||||
**Terminal B: Frontend (UI)**
|
||||
|
||||
# Startet auf Port 8502 (Dev Standard)
|
||||
# --server.port 8502 verhindert Konflikte mit Prod (8501)
|
||||
streamlit run app/frontend/ui.py --server.port 8502
|
||||
|
||||
---
|
||||
|
||||
## 3. Core-Module & Entwicklung
|
||||
|
||||
### 3.1 Der Importer (`scripts.import_markdown`)
|
||||
Dies ist das komplexeste Modul.
|
||||
* **Einstieg:** `scripts/import_markdown.py` -> `main_async()`.
|
||||
* **Smart Edges:** Nutzt `app.core.chunker` und `app.services.semantic_analyzer` zur Kanten-Filterung.
|
||||
* **Idempotenz:** Der Importer muss mehrfach laufen können, ohne Duplikate zu erzeugen. Wir nutzen deterministische IDs (UUIDv5).
|
||||
* **Robustheit:** In `ingestion.py` sind Mechanismen wie Change Detection und Robust File I/O (fsync) implementiert.
|
||||
|
||||
### 3.2 Der Hybrid Router (`app.routers.chat`)
|
||||
Hier liegt die Logik für Intent Detection (WP06) und Interview-Modus (WP07).
|
||||
* **Question Detection:** Prüft zuerst, ob der Input eine Frage ist. Falls ja -> RAG.
|
||||
* **Keyword Match:** Prüft Keywords in `decision_engine.yaml` und `types.yaml`.
|
||||
* **Priority:** Ruft `llm_service` mit `priority="realtime"` auf.
|
||||
|
||||
### 3.3 Der Retriever (`app.core.retriever`)
|
||||
Hier passiert das Scoring.
|
||||
* **Hybrid Search:** Der Chat-Endpoint erzwingt `mode="hybrid"`.
|
||||
* **Strategic Retrieval:** In `chat.py` wird der Retriever *zweimal* aufgerufen, wenn ein Intent (z.B. `DECISION`) eine Injection (`value`) erfordert.
|
||||
|
||||
### 3.4 Das Frontend (`app.frontend.ui`)
|
||||
Eine Streamlit-App (WP10).
|
||||
* **Resurrection Pattern:** Das UI nutzt ein spezielles State-Management, um Eingaben bei Tab-Wechseln (Chat <-> Editor) zu erhalten. Widgets synchronisieren sich mit `st.session_state`.
|
||||
* **Healing Parser:** Die Funktion `parse_markdown_draft` repariert defekte YAML-Frontmatter (fehlendes `---`) automatisch.
|
||||
* **Logik:** Ruft `/chat`, `/feedback` und `/ingest/analyze` Endpoints der API auf.
|
||||
|
||||
### 3.5 Embedding Service (`app.services.embeddings_client`)
|
||||
**Neu in v2.4:**
|
||||
* Nutzt `httpx.AsyncClient` für non-blocking Calls an Ollama (Primary Mode).
|
||||
* Besitzt einen **Fallback** auf `requests` (Synchron), falls Legacy-Skripte ihn nutzen.
|
||||
* Unterstützt dediziertes Embedding-Modell (`nomic-embed-text`) getrennt vom Chat-Modell.
|
||||
|
||||
### 3.6 Traffic Control (`app.services.llm_service`)
|
||||
**Neu in v2.6 (Version 2.8.0):**
|
||||
* Stellt sicher, dass Batch-Prozesse (Import) den Live-Chat nicht ausbremsen.
|
||||
* **Methode:** `generate_raw_response(..., priority="background")` aktiviert eine Semaphore.
|
||||
* **Limit:** Konfigurierbar über `MINDNET_LLM_BACKGROUND_LIMIT` (Default: 2) in der `.env`.
|
||||
|
||||
---
|
||||
|
||||
## 4. Tests & Debugging
|
||||
|
||||
Wir unterscheiden drei Test-Ebenen. Ein Pull Request sollte alle passieren.
|
||||
|
||||
### 4.1 Unit Tests (Pytest)
|
||||
Für isolierte Logik (Parsing, Scoring).
|
||||
|
||||
pytest tests/test_retriever_basic.py
|
||||
pytest tests/test_chunking.py
|
||||
pytest tests/test_edges_all.py
|
||||
|
||||
### 4.2 Integration / Pipeline Tests
|
||||
Prüfen den Datenfluss von Markdown bis Qdrant-JSON.
|
||||
* **Payload Dryrun:** Prüft JSON-Schema Konformität.
|
||||
|
||||
python3 -m scripts.payload_dryrun --vault ./mindnet_v2_test_vault
|
||||
|
||||
* **Edge Checks:** Prüft Graph-Invarianten.
|
||||
|
||||
python3 -m scripts.edges_full_check
|
||||
|
||||
### 4.3 Smoke Tests (E2E)
|
||||
Prüfen das laufende System gegen eine echte Qdrant-Instanz und Ollama.
|
||||
|
||||
# 1. API Test (Decision Engine)
|
||||
python tests/test_wp06_decision.py -p 8002 -e DECISION -q "Soll ich X tun?"
|
||||
|
||||
# 2. UI Test (Manuell)
|
||||
# Öffne http://localhost:8502
|
||||
# Stelle eine Frage und prüfe Intent-Badge und Quellen-Anzeige.
|
||||
|
||||
# 3. Feedback Test
|
||||
python tests/test_feedback_smoke.py --url http://localhost:8002/query
|
||||
|
||||
# 4. Intelligence Test (WP11)
|
||||
python debug_analysis.py
|
||||
|
||||
---
|
||||
|
||||
## 5. Das "Teach-the-AI" Paradigma (Context Intelligence)
|
||||
|
||||
Mindnet lernt nicht durch Training (Fine-Tuning), sondern durch **Konfiguration**, **Vernetzung** und **Prompting**. Dies ist der **Core-Workflow** für Erweiterungen.
|
||||
|
||||
### A. Workflow: Einen neuen Typ implementieren (z. B. `type: risk`)
|
||||
|
||||
**1. Daten-Ebene (`config/types.yaml`)**
|
||||
Definiere die "Physik" des Typs (Import-Regeln und Basis-Wichtigkeit).
|
||||
|
||||
risk:
|
||||
chunk_profile: sliding_short # Risiken sind oft kurze Statements
|
||||
retriever_weight: 0.90 # Sehr wichtig
|
||||
edge_defaults: ["blocks"] # Automatische Kante zu verlinkten Projekten
|
||||
detection_keywords: ["gefahr", "risiko"]
|
||||
|
||||
**2. Strategie-Ebene (`config/decision_engine.yaml`)**
|
||||
Damit dieser Typ aktiv geladen wird, musst du ihn einer Strategie zuordnen.
|
||||
|
||||
DECISION:
|
||||
inject_types: ["value", "principle", "goal", "risk"] # <--- "risk" hinzugefügt
|
||||
|
||||
*Ergebnis:* Wenn der Intent `DECISION` erkannt wird, sucht das System nun auch aktiv nach Risiken.
|
||||
|
||||
**3. Kognitive Ebene (`config/prompts.yaml`)**
|
||||
Erkläre dem LLM im Template, was es damit tun soll.
|
||||
|
||||
### 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)**
|
||||
Nutze die Inline-Syntax im Fließtext:
|
||||
> "Die Entscheidung für Qdrant wurde [[rel:beeinflusst_von Budgetkürzung 2024]]."
|
||||
|
||||
**2. Gewichtung (`config/retriever.yaml`)**
|
||||
Konfiguriere `edge_weights`, wenn Kausalität wichtiger ist als Ähnlichkeit.
|
||||
|
||||
### C. Workflow: Interview-Schema anpassen (WP07)
|
||||
|
||||
Wenn Mindnet neue Fragen stellen soll:
|
||||
|
||||
**1. Schema erweitern (`config/types.yaml`)**
|
||||
Füge das Feld in die Liste ein (Neu: Schemas liegen jetzt hier).
|
||||
|
||||
project:
|
||||
schema:
|
||||
- "Titel"
|
||||
- "Ziel"
|
||||
- "Budget (Neu)"
|
||||
|
||||
**2. Keine Code-Änderung nötig**
|
||||
Der `One-Shot Extractor` (Prompt Template) liest diese Liste dynamisch.
|
||||
|
||||
### Fazit
|
||||
* **Vault:** Liefert das Wissen.
|
||||
* **Config:** Liefert die Strategie (Router & Weights).
|
||||
* **Prompt:** Liefert die Interpretation.
|
||||
|
||||
---
|
||||
|
||||
## 6. Nützliche Einzeiler
|
||||
|
||||
**DB komplett zurücksetzen (Vorsicht!):**
|
||||
|
||||
# --yes überspringt die Bestätigung
|
||||
python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet_dev" --yes
|
||||
|
||||
**Einen einzelnen File inspizieren (Parser-Sicht):**
|
||||
|
||||
python3 tests/inspect_one_note.py --file ./vault/MeinFile.md
|
||||
|
||||
**Live-Logs sehen (Systemd):**
|
||||
|
||||
# Backend
|
||||
journalctl -u mindnet-dev -f
|
||||
# Frontend
|
||||
journalctl -u mindnet-ui-dev -f
|
||||
@@ -0,0 +1,494 @@
|
||||
# Mindnet v2.4 – Fachliche Architektur
|
||||
**Datei:** `docs/mindnet_functional_architecture_v2.6.md`
|
||||
**Stand:** 2025-12-12
|
||||
**Status:** **FINAL** (Integrierter Stand WP01–WP15: Smart Edges & Traffic Control)
|
||||
|
||||
> Dieses Dokument beschreibt **was** Mindnet fachlich tut und **warum** – mit Fokus auf die Erzeugung und Nutzung von **Smart Edges** (Kanten), die Logik des Retrievers und den **RAG-Chat** (Decision Engine, Interview-Modus & Persönlichkeit).
|
||||
|
||||
---
|
||||
<details>
|
||||
<summary>📖 <b>Inhaltsverzeichnis (Klicken zum Öffnen)</b></summary>
|
||||
|
||||
- [Mindnet v2.4 – Fachliche Architektur](#mindnet-v24--fachliche-architektur)
|
||||
- [](#)
|
||||
- [0) Zielbild \& Grundprinzip](#0-zielbild--grundprinzip)
|
||||
- [1) Notizen \& Chunks (fachliche Perspektive)](#1-notizen--chunks-fachliche-perspektive)
|
||||
- [1.1 Notiz (Note)](#11-notiz-note)
|
||||
- [1.2 Chunk](#12-chunk)
|
||||
- [2) Edges – fachliche Typen \& Bedeutung](#2-edges--fachliche-typen--bedeutung)
|
||||
- [2.1 Struktur-Kanten (Das Skelett)](#21-struktur-kanten-das-skelett)
|
||||
- [2.2 Inhalts-Kanten (explizit)](#22-inhalts-kanten-explizit)
|
||||
- [2.3 Typ-basierte Default-Kanten (Regelbasiert)](#23-typ-basierte-default-kanten-regelbasiert)
|
||||
- [2.4 Smart Edge Allocation (LLM-gefiltert) – Neu in v2.6](#24-smart-edge-allocation-llm-gefiltert--neu-in-v26)
|
||||
- [2.5 Matrix-Logik (Kontextsensitive Kanten)](#25-matrix-logik-kontextsensitive-kanten)
|
||||
- [3) Edge-Payload – Felder \& Semantik](#3-edge-payload--felder--semantik)
|
||||
- [4) Typ-Registry (`config/types.yaml`)](#4-typ-registry-configtypesyaml)
|
||||
- [4.1 Zweck](#41-zweck)
|
||||
- [4.2 Beispiel (auslieferungsnah)](#42-beispiel-auslieferungsnah)
|
||||
- [5) Der Retriever (Funktionaler Layer)](#5-der-retriever-funktionaler-layer)
|
||||
- [5.1 Scoring-Modell](#51-scoring-modell)
|
||||
- [5.2 Erklärbarkeit (Explainability) – WP04b](#52-erklärbarkeit-explainability--wp04b)
|
||||
- [5.3 Graph-Expansion](#53-graph-expansion)
|
||||
- [6) Context Intelligence \& Intent Router (WP06–WP15)](#6-context-intelligence--intent-router-wp06wp15)
|
||||
- [6.1 Das Problem: Statische vs. Dynamische Antworten](#61-das-problem-statische-vs-dynamische-antworten)
|
||||
- [6.2 Der Hybrid Router v5 (Action vs. Question)](#62-der-hybrid-router-v5-action-vs-question)
|
||||
- [6.3 Traffic Control (Realtime vs. Background)](#63-traffic-control-realtime-vs-background)
|
||||
- [6.4 Strategic Retrieval (Injektion von Werten)](#64-strategic-retrieval-injektion-von-werten)
|
||||
- [6.5 Reasoning (Das Gewissen)](#65-reasoning-das-gewissen)
|
||||
- [6.6 Der Interview-Modus (One-Shot Extraction)](#66-der-interview-modus-one-shot-extraction)
|
||||
- [6.7 Active Intelligence (Link Suggestions)](#67-active-intelligence-link-suggestions)
|
||||
- [7) Future Concepts: The Empathic Digital Twin (Ausblick)](#7-future-concepts-the-empathic-digital-twin-ausblick)
|
||||
- [7.1 Antizipation durch Erfahrung](#71-antizipation-durch-erfahrung)
|
||||
- [7.2 Empathie \& "Ich"-Modus](#72-empathie--ich-modus)
|
||||
- [7.3 Glaubenssätze \& Rituale](#73-glaubenssätze--rituale)
|
||||
- [8) Erweiterbarkeit \& Teaching (Context Intelligence)](#8-erweiterbarkeit--teaching-context-intelligence)
|
||||
- [A. Workflow: Einen neuen Typ implementieren (z. B. `type: risk`)](#a-workflow-einen-neuen-typ-implementieren-z-b-type-risk)
|
||||
- [B. Workflow: Neue Beziehungen nutzen (z. B. `beeinflusst_von`)](#b-workflow-neue-beziehungen-nutzen-z-b-beeinflusst_von)
|
||||
- [9) Feedback \& Lernen – WP04c/WP10](#9-feedback--lernen--wp04cwp10)
|
||||
- [9.1 Der Feedback-Loop](#91-der-feedback-loop)
|
||||
- [10) Confidence \& Provenance – wozu?](#10-confidence--provenance--wozu)
|
||||
- [11) Semantik ausgewählter `kind`-Werte](#11-semantik-ausgewählter-kind-werte)
|
||||
- [12) Frontmatter-Eigenschaften – Rolle \& Empfehlung](#12-frontmatter-eigenschaften--rolle--empfehlung)
|
||||
- [13) Lösch-/Update-Garantien (Idempotenz)](#13-lösch-update-garantien-idempotenz)
|
||||
- [14) Beispiel – Von Markdown zu Kanten](#14-beispiel--von-markdown-zu-kanten)
|
||||
- [15) Referenzen (Projektdateien \& Leitlinien)](#15-referenzen-projektdateien--leitlinien)
|
||||
- [16) Workpackage Status (v2.6.0)](#16-workpackage-status-v260)
|
||||
|
||||
</details>
|
||||
---
|
||||
|
||||
## 0) Zielbild & Grundprinzip
|
||||
|
||||
Mindnet wandelt Obsidian-Markdown-Notizen in einen **dynamischen Graphen aus Punkten und Kanten** um.
|
||||
Die drei zentralen Artefakt-Sammlungen lauten:
|
||||
|
||||
- `mindnet_notes` – genau **eine** Note pro Markdown-Datei (Metadaten & Hashes)
|
||||
- `mindnet_chunks` – semantische Teilstücke einer Note (Fenster/„Chunks“)
|
||||
- `mindnet_edges` – gerichtete Beziehungen zwischen Knoten (Chunks/Notes)
|
||||
|
||||
Die Import-Pipeline (seit v2.6 mit **Traffic Control** und **Smart Edges**) erzeugt diese Artefakte **deterministisch** und **idempotent** (erneute Läufe überschreiben konsistent statt zu duplizieren). Die Import-Schritte sind: *parse → chunk → embed → smart-edge-allocation → upsert*.
|
||||
|
||||
---
|
||||
|
||||
## 1) Notizen & Chunks (fachliche Perspektive)
|
||||
|
||||
### 1.1 Notiz (Note)
|
||||
- Repräsentiert eine fachliche Einheit (z. B. *„Vector DB Basics“*, *„KI-Projekt“*).
|
||||
- Trägt Eigenschaften (Titel, Typ, Zeitstempel, optionale Policies).
|
||||
- **Typ** (*type*) steuert u. a. Chunk-Profil und Default-Relationen (siehe §4).
|
||||
- **retriever_weight** und **chunk_profile** werden systematisch an Note **und** Chunks gespiegelt, damit der Retriever beides nutzen kann.
|
||||
|
||||
### 1.2 Chunk
|
||||
- Ausschnitt/Textfenster aus der Note, als eigenständiger Such-Anker.
|
||||
- Jeder Chunk gehört **genau einer** Note.
|
||||
- Chunks bilden eine Sequenz (1…N) – das ermöglicht *next/prev*.
|
||||
- **Update v2.4:** Chunks werden jetzt durch das Modell `nomic-embed-text` in **768-dimensionale Vektoren** umgewandelt. Dies erlaubt eine deutlich höhere semantische Auflösung als frühere Modelle (384 Dim).
|
||||
- **Update v2.6 (Smart Chunking):** Ein Chunk ist nicht mehr nur ein dummer Textblock, der alle Links der Mutter-Notiz erbt. Durch die **Smart Edge Allocation (WP15)** "weiß" jeder Chunk genau, welche Kanten inhaltlich zu ihm gehören (siehe 2.4).
|
||||
|
||||
> **Wichtig:** Chunking-Profile (short/medium/long/sliding_smart_edges) kommen aus `types.yaml` (per Note-Typ), können aber lokal überschrieben werden. Die effektiven Werte werden bei der Payload-Erzeugung bestimmt.
|
||||
|
||||
---
|
||||
|
||||
## 2) Edges – fachliche Typen & Bedeutung
|
||||
|
||||
Edges kodieren Beziehungen. Sie sind **gerichtet** und werden in `mindnet_edges` gespeichert. Die Erzeugung folgt einer strengen Priorität: **Inline > Callout > Defaults > Struktur**.
|
||||
|
||||
### 2.1 Struktur-Kanten (Das Skelett)
|
||||
- **belongs_to**: *Chunk → Note* (Zuordnung)
|
||||
- **next / prev**: Kettenbeziehungen zwischen aufeinanderfolgenden Chunks derselben Note.
|
||||
→ ermöglichen „lineares Weiterlesen“ oder Kontextpfade in Antworten.
|
||||
Diese Kanten entstehen immer, unabhängig von Inhalten.
|
||||
|
||||
### 2.2 Inhalts-Kanten (explizit)
|
||||
Hier unterscheidet v2.6 präzise zwischen verschiedenen Quellen der Evidenz:
|
||||
|
||||
1. **Explizite Inline-Relationen (Höchste Priorität):**
|
||||
Im Fließtext notierte, semantisch qualifizierte Relationen.
|
||||
* Syntax: `[[rel:depends_on Embeddings 101]]`
|
||||
* Fachliche Aussage: "Hängt ab von", "Ähnlich zu".
|
||||
* *rule_id*: `inline:rel`
|
||||
* *confidence*: ~0.95
|
||||
|
||||
2. **Callout-Edges (Kuratierte Listen):**
|
||||
Redaktionell gepflegte Listen am Ende einer Notiz (z.B. "Siehe auch").
|
||||
* Syntax: `> [!edge] related_to: [[Vector DB Basics]]`
|
||||
* *rule_id*: `callout:edge`
|
||||
* *confidence*: ~0.90
|
||||
|
||||
3. **Wikilinks (Standard-Referenzen):**
|
||||
Der klassische Obsidian-Link.
|
||||
* Syntax: `[[Vector DB Basics]]`
|
||||
* Typ: `references`
|
||||
* *rule_id*: `explicit:wikilink`
|
||||
* *confidence*: 1.0
|
||||
|
||||
> Alle expliziten Quellen (Wikilink, Inline-Rel, Callout) sind **Primärbelege**.
|
||||
|
||||
### 2.3 Typ-basierte Default-Kanten (Regelbasiert)
|
||||
Jede Note hat einen *Typ* (z. B. `concept`, `project`, `profile`). In `config/types.yaml` definieren wir pro Typ **edge_defaults**, z. B.:
|
||||
|
||||
- `concept`: `["references","related_to"]`
|
||||
- `project`: `["references","depends_on"]`
|
||||
|
||||
Regel: **Für jede gefundene explizite Referenz** (s. o.) werden **zusätzliche** Edges nach diesen Defaults erzeugt.
|
||||
Beispiel: Ein *project* mit `edge_defaults=["depends_on"]` erzeugt zu *jedem* explizit referenzierten Ziel **zusätzlich** eine `depends_on`-Kante.
|
||||
Diese Kanten tragen *provenance=rule* und eine **rule_id** der Form `edge_defaults:{note_type}:{relation}` sowie eine geringere Confidence (~0.7).
|
||||
|
||||
### 2.4 Smart Edge Allocation (LLM-gefiltert) – Neu in v2.6
|
||||
Mit **WP15** wurde ein intelligenter Filter eingeführt, um das Problem des "Broadcasting" zu lösen. Früher erbte jeder Chunk einer Notiz *alle* Links der Notiz, was zu unpräzisem Retrieval führte.
|
||||
|
||||
**Der neue Prozess:**
|
||||
1. **Scan:** Das System sammelt alle expliziten Links der gesamten Notiz.
|
||||
2. **Chunking:** Der Text wird in Abschnitte zerlegt.
|
||||
3. **Analyse (LLM):** Ein lokales LLM (Semantic Analyzer) liest jeden Chunk einzeln.
|
||||
4. **Entscheidung:** Das LLM entscheidet für jeden Link aus Schritt 1: *"Ist dieser Link im Kontext dieses spezifischen Textabschnitts relevant?"*
|
||||
5. **Zuweisung:** Nur wenn das LLM zustimmt, wird die Kante am Chunk erstellt.
|
||||
|
||||
*Steuerung:* Dies ist pro Typ in der `types.yaml` konfigurierbar (`enable_smart_edge_allocation: true`).
|
||||
|
||||
### 2.5 Matrix-Logik (Kontextsensitive Kanten)
|
||||
Mit WP-11 wurde eine Intelligenz eingeführt, die Kanten-Typen nicht nur anhand des Quell-Typs, sondern auch anhand des Ziel-Typs bestimmt ("Matrix").
|
||||
|
||||
**Beispiel für `Source Type: experience`:**
|
||||
* Wenn Ziel ist `value` -> Kante: `based_on`
|
||||
* Wenn Ziel ist `principle` -> Kante: `derived_from`
|
||||
* Wenn Ziel ist `project` -> Kante: `related_to`
|
||||
|
||||
Dies ermöglicht im Graphen präzise Abfragen wie "Zeige alle Erfahrungen, die auf Wert X basieren" (via `based_on`), was mit generischen `related_to` Kanten nicht möglich wäre.
|
||||
|
||||
---
|
||||
|
||||
## 3) Edge-Payload – Felder & Semantik
|
||||
|
||||
Jede Kante hat mindestens:
|
||||
|
||||
- `kind` – Beziehungsart *(belongs_to, next, prev, references, related_to, depends_on, similar_to, based_on, uses, …)*
|
||||
- `scope` – `"chunk"` (Standard in v2.2)
|
||||
- `source_id`, `target_id` – Quell-/Ziel-Knoten (Chunk-IDs oder Note-Titel bei unresolved Targets)
|
||||
- `note_id` – **Owner-Note** (die Note, aus der die Kante stammt)
|
||||
|
||||
Erweiterte/abgeleitete Felder (WP03 Superset):
|
||||
|
||||
- `provenance` – `"explicit"` (Wikilink/Inline/Callout), `"rule"` (Typ-Defaults) oder neu `"smart"` (vom LLM validiert).
|
||||
- `rule_id` – maschinenlesbare Regelquelle (z.B. `inline:rel`, `edge_defaults:project:depends_on`)
|
||||
- `confidence` – 0.0–1.0; Heuristik zur Gewichtung im Scoring.
|
||||
|
||||
**Dedup-Schlüssel** (fachlich): Gleichlautende `(source_id, target_id, kind, scope, rule_id)` werden nicht mehrfach geschrieben.
|
||||
|
||||
---
|
||||
|
||||
## 4) Typ-Registry (`config/types.yaml`)
|
||||
|
||||
### 4.1 Zweck
|
||||
- Steuert **Chunking-Profile** (`short|medium|long`) **pro Typ**
|
||||
- Liefert **retriever_weight** (Note-/Chunk-Gewichtung im Ranking) **pro Typ**
|
||||
- Definiert **edge_defaults** je Typ (s. o.)
|
||||
- **Neu in v2.6:** Steuert `enable_smart_edge_allocation` (LLM-Filter) und `detection_keywords` für den Hybrid Router.
|
||||
|
||||
Der Importer lädt die Registry aus `MINDNET_TYPES_FILE` oder nutzt Fallbacks. **Frontmatter-Overrides** für Profile werden in v2.2 weitgehend ignoriert zugunsten einer zentralen Governance in der YAML-Datei.
|
||||
|
||||
### 4.2 Beispiel (auslieferungsnah)
|
||||
version: 2.6.0
|
||||
types:
|
||||
concept:
|
||||
chunk_profile: medium
|
||||
edge_defaults: ["references", "related_to"]
|
||||
retriever_weight: 0.60
|
||||
experience:
|
||||
chunk_profile: sliding_smart_edges
|
||||
enable_smart_edge_allocation: true # WP15: LLM prüft Kanten
|
||||
detection_keywords: ["passiert", "erlebt", "situation"] # WP06: Router-Trigger
|
||||
schema: # WP07: Interview-Struktur
|
||||
- "Situation (Was ist passiert?)"
|
||||
- "Meine Reaktion (Was habe ich getan?)"
|
||||
|
||||
**Auflösung im Importer**
|
||||
- `effective_chunk_profile(note_type, registry)` → `"short|medium|long"|None`
|
||||
- `effective_retriever_weight(note_type, registry)` → `float|None`
|
||||
- Ergebnis wird in `note_payload` **und** `chunk_payloads` gespiegelt.
|
||||
|
||||
---
|
||||
|
||||
## 5) Der Retriever (Funktionaler Layer)
|
||||
|
||||
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:
|
||||
|
||||
total_score =
|
||||
semantic_weight * semantic_score
|
||||
+ edge_weight * edge_bonus
|
||||
+ centrality_weight * centrality_bonus
|
||||
+ type_weight * retriever_weight
|
||||
|
||||
* **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 (Summe der Confidence eingehender relevanter Kanten).
|
||||
* **centrality_bonus:** Belohnung für Knoten, die zentrale Hubs im lokalen Graphen darstellen.
|
||||
|
||||
### 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.
|
||||
|
||||
### 5.3 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) Context Intelligence & Intent Router (WP06–WP15)
|
||||
|
||||
Seit WP06 agiert Mindnet nicht mehr statisch, sondern passt seine Suchstrategie dem **Intent** (der Absicht) des Nutzers an. Dies ist die Transformation vom reinen Wissens-Abrufer zum strategischen Partner.
|
||||
|
||||
### 6.1 Das Problem: Statische vs. Dynamische Antworten
|
||||
* **Früher (Pre-WP06):** Jede Frage ("Was ist X?" oder "Soll ich X?") wurde gleich behandelt -> Fakten-Retrieval.
|
||||
* **Heute (WP06):** Das System erkennt, *was* der User will (Rat, Fakten oder Datenerfassung) und wechselt den Modus.
|
||||
|
||||
### 6.2 Der Hybrid Router v5 (Action vs. Question)
|
||||
Der Router wurde in v2.6 (WP15) weiterentwickelt, um Fehlalarme zu vermeiden.
|
||||
|
||||
1. **Frage-Erkennung:**
|
||||
* Das System prüft zuerst: Enthält der Satz ein `?` oder typische W-Wörter (Wer, Wie, Was)?
|
||||
* Wenn **JA** -> Gehe in den **RAG Modus** (Intent `FACT` oder `DECISION`). Interviews werden hier blockiert.
|
||||
|
||||
2. **Befehls-Erkennung (Fast Path):**
|
||||
* Wenn **NEIN** (keine Frage), prüft das System auf Keywords in `types.yaml` ("Projekt", "Erfahrung").
|
||||
* Treffer -> **INTERVIEW Modus** (Erfassen). Das Schema wird aus `types.yaml` geladen.
|
||||
|
||||
3. **LLM Fallback (Slow Path):**
|
||||
* Wenn beides fehlschlägt, entscheidet das LLM über den Intent.
|
||||
|
||||
### 6.3 Traffic Control (Realtime vs. Background)
|
||||
Um den Live-Betrieb (Chat) nicht durch den ressourcenintensiven Smart-Import (LLM-Analyse) zu gefährden, implementiert v2.6 ein **Traffic Control System** im `LLMService`.
|
||||
|
||||
* **Realtime Lane (Chat):** Anfragen aus dem Chat erhalten `priority="realtime"`. Sie umgehen alle Warteschlangen und werden sofort bearbeitet.
|
||||
* **Background Lane (Import):** Anfragen zur Kantenanalyse erhalten `priority="background"`. Sie werden durch eine **Semaphore** gedrosselt (Standard: max 2 parallel), um die Hardware nicht zu überlasten.
|
||||
|
||||
### 6.4 Strategic Retrieval (Injektion von Werten)
|
||||
Im Modus `DECISION` führt das System eine **zweite Suchstufe** aus. Es sucht nicht nur nach semantisch passenden Texten zur Frage, sondern erzwingt das Laden von strategischen Notizen wie:
|
||||
* **Values (`type: value`):** Moralische Werte (z.B. "Privacy First").
|
||||
* **Principles (`type: principle`):** Handlungsanweisungen.
|
||||
* **Goals (`type: goal`):** Strategische Ziele.
|
||||
|
||||
### 6.5 Reasoning (Das Gewissen)
|
||||
Das LLM erhält im Prompt die explizite Anweisung: *"Wäge die Fakten (aus der Suche) gegen die injizierten Werte ab."*
|
||||
Dadurch entstehen Antworten, die nicht nur technisch korrekt sind, sondern subjektiv passend ("Tool X passt nicht zu deinem Ziel Z").
|
||||
|
||||
### 6.6 Der Interview-Modus (One-Shot Extraction)
|
||||
Wenn der User Wissen erfassen will ("Ich möchte ein neues Projekt anlegen"), wechselt Mindnet in den **Interview-Modus**.
|
||||
|
||||
* **Late Binding Schema:** Das System lädt ein konfiguriertes Schema für den Ziel-Typ (z.B. `project`: Pflichtfelder sind Titel, Ziel, Status).
|
||||
* **One-Shot Extraction:** Statt eines langen Dialogs extrahiert das LLM **sofort** alle verfügbaren Infos aus dem Prompt und generiert einen validen Markdown-Draft mit Frontmatter.
|
||||
* **Healing Parser (v2.5):** Falls das LLM die YAML-Syntax beschädigt (z.B. fehlendes Ende), repariert das Frontend den Entwurf automatisch.
|
||||
* **UI-Integration:** Das Frontend rendert statt einer Chat-Antwort einen **interaktiven Editor** (WP10), in dem der Entwurf finalisiert werden kann.
|
||||
|
||||
### 6.7 Active Intelligence (Link Suggestions)
|
||||
Im **Draft Editor** (Frontend) unterstützt das System den Autor aktiv.
|
||||
* **Analyse:** Ein "Sliding Window" scannt den Text im Hintergrund (auch lange Entwürfe).
|
||||
* **Erkennung:** Es findet Begriffe ("Mindnet") und semantische Konzepte ("Autofahrt in Italien").
|
||||
* **Matching:** Es prüft gegen den Index (Aliases und Vektoren).
|
||||
* **Vorschlag:** Es bietet fertige Markdown-Links an (z.B. `[[rel:related_to ...]]`), die per Klick eingefügt werden.
|
||||
* **Logik:** Dabei kommt die in 2.5 beschriebene **Matrix-Logik** zum Einsatz, um den korrekten Kanten-Typ vorzuschlagen.
|
||||
|
||||
---
|
||||
|
||||
## 7) Future Concepts: The Empathic Digital Twin (Ausblick)
|
||||
|
||||
Um Mindnet von einer Entscheidungsmaschine zu einem echten **Spiegel der Persönlichkeit** zu entwickeln, sind folgende Erweiterungen konzeptionell vorgesehen:
|
||||
|
||||
### 7.1 Antizipation durch Erfahrung
|
||||
* **Konzept:** Das System soll Konsequenzen vorhersagen ("Was passiert, wenn...?").
|
||||
* **Umsetzung:** Neben Werten werden vergangene Erfahrungen (`type: experience`) geladen.
|
||||
* **Logik:** *"In einer ähnlichen Situation (Projekt A) hat Entscheidung X zu Ergebnis Y geführt."*
|
||||
|
||||
### 7.2 Empathie & "Ich"-Modus
|
||||
* **Konzept:** Das System antwortet nicht wie ein Roboter, sondern im Tonfall und Stil des Nutzers.
|
||||
* **Umsetzung (Few-Shot Prompting):** Der System-Prompt wird dynamisch mit Beispielen gefüttert, wie der Nutzer typischerweise auf E-Mails oder Fragen antwortet.
|
||||
* **Datenbasis:** `type: profile` oder `type: manifesto` definieren das Selbstbild.
|
||||
|
||||
### 7.3 Glaubenssätze & Rituale
|
||||
* **Konzept:** Berücksichtigung weicher Faktoren und Gewohnheiten.
|
||||
* **Umsetzung:** Erweiterung der `decision_engine.yaml` um `inject_types: ["belief", "ritual"]`.
|
||||
* **Szenario:** Bei Terminplanungen werden Rituale ("Keine Meetings vor 10 Uhr") automatisch als harte Restriktion gegen Anfragen geprüft.
|
||||
|
||||
---
|
||||
|
||||
## 8) Erweiterbarkeit & Teaching (Context Intelligence)
|
||||
|
||||
Mindnet lernt nicht durch klassisches Training (Fine-Tuning), sondern durch **Konfiguration**, **Vernetzung** und **Prompting**. Dies ist das **"Teach-the-AI" Paradigma**: Wenn du dem System ein neues Konzept beibringen willst, musst du an drei Stellen eingreifen.
|
||||
|
||||
### A. Workflow: Einen neuen Typ implementieren (z. B. `type: risk`)
|
||||
|
||||
1. **Physik definieren (`config/types.yaml`)**
|
||||
Steuere, wie schwer der Inhalt wiegt und wie er vernetzt wird.
|
||||
```yaml
|
||||
risk:
|
||||
chunk_profile: short # Risiken sind oft kurze Statements
|
||||
retriever_weight: 0.90 # Hohe Priorität im Ranking
|
||||
edge_defaults: ["blocks"] # Automatische Kante zu verlinkten Projekten
|
||||
detection_keywords: ["gefahr", "risiko"] # Für den Hybrid Router
|
||||
```
|
||||
*Effekt:* Der Router erkennt das Wort "Risiko" und bietet ein Interview an. Der Retriever spült diese Notizen bei relevanten Anfragen nach oben.
|
||||
|
||||
2. **Semantik erklären (`config/prompts.yaml` / `decision_engine.yaml`)**
|
||||
Bringe dem LLM bei, wie es mit diesem Typ umgehen soll. Füge `risk` zur `DECISION`-Strategie hinzu (`inject_types`), damit es bei Entscheidungen geladen wird.
|
||||
|
||||
### B. Workflow: Neue Beziehungen nutzen (z. B. `beeinflusst_von`)
|
||||
|
||||
Beziehungen sind der Klebstoff für logische Schlussfolgerungen.
|
||||
|
||||
1. **Erfassung im Vault (Markdown)**
|
||||
Nutze die Inline-Syntax. Du musst nichts vorab definieren.
|
||||
> "Die Entscheidung für Qdrant wurde [[rel:beeinflusst_von Budgetkürzung 2024]]."
|
||||
|
||||
2. **Gewichtung justieren (`config/retriever.yaml`)**
|
||||
Standardmäßig sind alle Kanten gleich `1.0`. Wenn Kausalität wichtiger ist als Ähnlichkeit, definiere dies hier:
|
||||
```yaml
|
||||
retriever:
|
||||
edge_weights:
|
||||
beeinflusst_von: 1.5 # Starker Boost: Zieht Ursachen in den Kontext
|
||||
related_to: 0.5 # Schwacher Boost: Nur "nice to know"
|
||||
```
|
||||
*Effekt:* Bei der Frage nach "Qdrant" landet die "Budgetkürzung" (Ursache) im Kontext, weil die Kante stark ist.
|
||||
|
||||
3. **Interpretation (Prompting)**
|
||||
Das LLM erkennt im RAG-Kontext: `Qdrant --[beeinflusst_von]--> Budgetkürzung`.
|
||||
Es kann daraus den Satz formulieren: *"Die Wahl fiel vermutlich aufgrund der Budgetkürzung auf Qdrant."*
|
||||
|
||||
**Fazit:** Nur wenn **Daten** (Vault), **Physik** (Config) und **Semantik** (Prompt) zusammenspielen, entsteht ein intelligenter Zwilling.
|
||||
|
||||
---
|
||||
|
||||
## 9) Feedback & Lernen – WP04c/WP10
|
||||
|
||||
Das System verfügt nun über ein **Kurzzeitgedächtnis für Interaktionen**, das die Basis für zukünftiges Lernen bildet.
|
||||
|
||||
### 9.1 Der Feedback-Loop
|
||||
Die Interaktion erfolgt primär über das **Web-Interface (WP10)**.
|
||||
|
||||
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 bewertet die Antwort (**Sterne**) oder einzelne Quellen (**Faces**) im Frontend.
|
||||
Dieses Feedback wird unter Referenzierung der `query_id` in `feedback.jsonl` 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.
|
||||
|
||||
---
|
||||
|
||||
## 10) Confidence & Provenance – wozu?
|
||||
|
||||
Der Retriever kann Edges gewichten:
|
||||
- **provenance**: *explicit* > *smart* (Neu) > *rule*
|
||||
- **confidence**: numerische Feinsteuerung
|
||||
- **retriever_weight (Note/Chunk)**: skaliert die Relevanz des gesamten Knotens
|
||||
|
||||
Eine typische Gewichtung (konfigurierbar in `retriever.yaml`) ist:
|
||||
`explicit: 1.0`, `smart: 0.9`, `rule: 0.8`. Damit bevorzugt der Graph **kuratiertes Wissen** (explizit notierte Links) vor „erweiterten“ Default-Ableitungen.
|
||||
|
||||
---
|
||||
|
||||
## 11) Semantik ausgewählter `kind`-Werte
|
||||
|
||||
- `references` – „Nutzt/erwähnt“; neutral, aber stützend für Kontext.
|
||||
- `related_to` – Ähnlichkeit/Verwandtschaft (symmetrisch interpretierbar).
|
||||
- `similar_to` – noch engere Ähnlichkeit; oft aus Inline-Rel (bewusst gesetzt).
|
||||
- `depends_on` – fachliche Abhängigkeit (z. B. „Projekt X hängt von Y ab“).
|
||||
- **Neu in v2.4 (Matrix):**
|
||||
- `based_on` – Erfahrung basiert auf Wert.
|
||||
- `derived_from` – Erkenntnis stammt aus Prinzip.
|
||||
- `uses` – Projekt nutzt Konzept.
|
||||
- `belongs_to`, `next`, `prev` – Struktur.
|
||||
|
||||
> Symmetrische Relationen (z. B. `related_to`, `similar_to`) können **explizit** nur einseitig notiert sein, aber im Retriever beidseitig interpretiert werden.
|
||||
|
||||
---
|
||||
|
||||
## 12) Frontmatter-Eigenschaften – Rolle & Empfehlung
|
||||
|
||||
Frontmatter-Eigenschaften (Properties) bleiben **minimiert**:
|
||||
- **type** – steuert Typ-Defaults via Registry (Pflicht für differenziertes Verhalten).
|
||||
- **tags** – für klassische Filterung.
|
||||
- **retriever_weight / chunk_profile** – Sollten **nicht** manuell gesetzt werden (Best Practice: `types.yaml` nutzen).
|
||||
- **links** – Veraltet. Bitte Links primär über Text (Wikilink/Inline/Callout) pflegen.
|
||||
|
||||
---
|
||||
|
||||
## 13) 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.
|
||||
- Die Import-Skripte unterstützen Modi wie `--purge-before-upsert` und `--sync-deletes`, um den Graph sauber zu halten.
|
||||
|
||||
---
|
||||
|
||||
## 14) Beispiel – Von Markdown zu Kanten
|
||||
|
||||
**Markdown (Auszug)**
|
||||
# Relations Showcase
|
||||
…
|
||||
Wir nutzen [[rel:depends_on Qdrant Vektordatenbank]] für die Suche.
|
||||
…
|
||||
Siehe auch: [[Embeddings 101]]
|
||||
|
||||
> [!edge] related_to: [[Vector DB Basics]]
|
||||
|
||||
**Ergebnis (fachlich - Smart Edges)**
|
||||
Das LLM analysiert jeden Chunk.
|
||||
1. Chunk 1 ("Wir nutzen..."): Enthält `depends_on(Chunk→Qdrant)`. Das LLM bestätigt: Relevant. -> Kante wird erstellt.
|
||||
2. Chunk 2 ("Siehe auch..."): Enthält `references(Chunk→Embeddings)`. Das LLM bestätigt.
|
||||
3. **Wichtig:** Ein Chunk 3 ("Die Benutzeroberfläche ist blau..."), der keine Erwähnung von Qdrant hat, bekommt **keine** `depends_on` Kante zu Qdrant, auch wenn die Note global verlinkt ist. Das ist der Gewinn von WP15.
|
||||
|
||||
---
|
||||
|
||||
## 15) Referenzen (Projektdateien & Leitlinien)
|
||||
|
||||
- Import-Pipeline & Registry-Auflösung: `scripts/import_markdown.py`.
|
||||
- Kantenbildung (V2-Logic): `app/core/derive_edges.py`.
|
||||
- Smart Chunking & Traffic Control: `app/core/chunker.py` & `app/services/llm_service.py`.
|
||||
- Typ-Registry: `config/types.yaml` & `TYPE_REGISTRY_MANUAL.md`.
|
||||
- Retriever-Scoring & Explanation: `app/core/retriever.py`.
|
||||
- Persönlichkeit & Chat: `config/prompts.yaml` & `app/routers/chat.py`.
|
||||
- Decision Engine: `config/decision_engine.yaml`.
|
||||
- Logging Service: `app/services/feedback_service.py`.
|
||||
- Frontend UI: `app/frontend/ui.py`.
|
||||
- Intelligence Logic: `app/services/discovery.py`.
|
||||
|
||||
---
|
||||
|
||||
## 16) Workpackage Status (v2.6.0)
|
||||
|
||||
Aktueller Implementierungsstand der Module.
|
||||
|
||||
| WP | Titel | Status | Anmerkung |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **WP01** | Knowledge Design | 🟢 Live | Typen, Frontmatter definiert. |
|
||||
| **WP02** | Chunking Strategy | 🟢 Live | Profilbasiertes Chunking aktiv. |
|
||||
| **WP03** | Edge Logic / Import | 🟢 Live | Neue Importer-Pipeline mit Provenance. |
|
||||
| **WP04a**| Retriever Scoring | 🟢 Live | Hybrider Score (Semantik + Graph). |
|
||||
| **WP04b**| Explanation Layer | 🟢 Live | API liefert Reasons & Breakdown. |
|
||||
| **WP04c**| Feedback Loop | 🟢 Live | Logging (JSONL) & Traceability aktiv. |
|
||||
| **WP05** | Persönlichkeit / Chat | 🟢 Live | RAG-Integration mit Context Enrichment. |
|
||||
| **WP06** | Decision Engine | 🟢 Live | Hybrid Router, Strategic Retrieval. |
|
||||
| **WP07** | Interview Assistent | 🟢 Live | **One-Shot Extractor & Schemas aktiv.** |
|
||||
| **WP08** | Self-Tuning | 🔴 Geplant | Auto-Adjustment der Gewichte. |
|
||||
| **WP10** | Chat Interface | 🟢 Live | Web-Interface (Streamlit). |
|
||||
| **WP10a**| Draft Editor | 🟢 Live | **Interaktives UI & Healing Parser.** |
|
||||
| **WP11** | Backend Intelligence | 🟢 Live | **Async Ingestion, Nomic Embeddings, Matrix Logic.** |
|
||||
| **WP15** | Smart Edge Allocation | 🟢 Live | **LLM-Filter & Traffic Control aktiv.** |
|
||||
| **WP16** | Auto-Discovery | 🟡 Geplant | UX & Retrieval Tuning. |
|
||||
| **WP17** | Conversational Memory | 🟡 Geplant | Dialog-Gedächtnis. |
|
||||
@@ -0,0 +1,450 @@
|
||||
# Mindnet v2.6 – Technische Architektur
|
||||
**Datei:** `docs/mindnet_technical_architecture_v2.6.md`
|
||||
**Stand:** 2025-12-12
|
||||
**Status:** **FINAL** (Integrierter Stand WP01–WP15: Smart Edges & Traffic Control)
|
||||
**Quellen:** `Programmplan_V2.6.md`, `Handbuch.md`, `chunking_strategy.md`, `wp04_retriever_scoring.md`.
|
||||
|
||||
> **Ziel dieses Dokuments:**
|
||||
> Vollständige Beschreibung der technischen Architektur inkl. Graph-Datenbank, Retrieval-Logik, der **RAG-Komponenten (Decision Engine & Hybrid Router)**, des **Traffic Control Systems** und dem **Frontend (Streamlit)**.
|
||||
|
||||
---
|
||||
<details>
|
||||
<summary>📖 <b>Inhaltsverzeichnis (Klicken zum Öffnen)</b></summary>
|
||||
|
||||
- [Mindnet v2.6 – Technische Architektur](#mindnet-v26--technische-architektur)
|
||||
- [](#)
|
||||
- [1. Systemüberblick](#1-systemüberblick)
|
||||
- [1.1 Architektur-Zielbild](#11-architektur-zielbild)
|
||||
- [1.2 Verzeichnisstruktur \& Komponenten (Post-WP15)](#12-verzeichnisstruktur--komponenten-post-wp15)
|
||||
- [2. Datenmodell \& Collections (Qdrant)](#2-datenmodell--collections-qdrant)
|
||||
- [2.1 Notes Collection (`<prefix>_notes`)](#21-notes-collection-prefix_notes)
|
||||
- [2.2 Chunks Collection (`<prefix>_chunks`)](#22-chunks-collection-prefix_chunks)
|
||||
- [2.3 Edges Collection (`<prefix>_edges`)](#23-edges-collection-prefix_edges)
|
||||
- [3. Konfiguration](#3-konfiguration)
|
||||
- [3.1 Typ-Registry (`config/types.yaml`)](#31-typ-registry-configtypesyaml)
|
||||
- [3.2 Retriever-Config (`config/retriever.yaml`)](#32-retriever-config-configretrieveryaml)
|
||||
- [3.3 Decision Engine (`config/decision_engine.yaml`)](#33-decision-engine-configdecision_engineyaml)
|
||||
- [3.4 Prompts (`config/prompts.yaml`)](#34-prompts-configpromptsyaml)
|
||||
- [3.5 Environment (`.env`)](#35-environment-env)
|
||||
- [4. Import-Pipeline (Markdown → Qdrant)](#4-import-pipeline-markdown--qdrant)
|
||||
- [4.1 Verarbeitungsschritte (Async + Smart)](#41-verarbeitungsschritte-async--smart)
|
||||
- [5. Retriever-Architektur \& Scoring](#5-retriever-architektur--scoring)
|
||||
- [5.1 Betriebsmodi](#51-betriebsmodi)
|
||||
- [5.2 Scoring-Formel (WP04a)](#52-scoring-formel-wp04a)
|
||||
- [5.3 Explanation Layer (WP04b)](#53-explanation-layer-wp04b)
|
||||
- [5.4 Graph-Expansion](#54-graph-expansion)
|
||||
- [6. RAG \& Chat Architektur (WP06 Hybrid Router + WP07 Interview)](#6-rag--chat-architektur-wp06-hybrid-router--wp07-interview)
|
||||
- [6.1 Architektur-Pattern: Intent Router v5](#61-architektur-pattern-intent-router-v5)
|
||||
- [6.2 Traffic Control (Priorisierung)](#62-traffic-control-priorisierung)
|
||||
- [6.3 Schritt 1: Intent Detection (Question vs. Action)](#63-schritt-1-intent-detection-question-vs-action)
|
||||
- [6.4 Schritt 2: Strategy Resolution](#64-schritt-2-strategy-resolution)
|
||||
- [6.5 Schritt 3: Retrieval vs. Extraction](#65-schritt-3-retrieval-vs-extraction)
|
||||
- [6.6 Schritt 4: Generation \& Response](#66-schritt-4-generation--response)
|
||||
- [7. Frontend Architektur (WP10)](#7-frontend-architektur-wp10)
|
||||
- [7.1 Kommunikation](#71-kommunikation)
|
||||
- [7.2 Features \& UI-Logik](#72-features--ui-logik)
|
||||
- [7.3 Draft-Editor \& Healing Parser (Neu in WP10a/v2.5)](#73-draft-editor--healing-parser-neu-in-wp10av25)
|
||||
- [7.4 State Management (Resurrection Pattern)](#74-state-management-resurrection-pattern)
|
||||
- [7.5 Deployment Ports](#75-deployment-ports)
|
||||
- [8. Feedback \& Logging Architektur (WP04c)](#8-feedback--logging-architektur-wp04c)
|
||||
- [8.1 Komponenten](#81-komponenten)
|
||||
- [8.2 Log-Dateien](#82-log-dateien)
|
||||
- [8.3 Traceability](#83-traceability)
|
||||
- [9. Indizes \& Performance](#9-indizes--performance)
|
||||
- [10. Offene Punkte / Known Limitations](#10-offene-punkte--known-limitations)
|
||||
|
||||
|
||||
</details>
|
||||
---
|
||||
|
||||
## 1. Systemüberblick
|
||||
|
||||
### 1.1 Architektur-Zielbild
|
||||
Mindnet ist ein **lokales RAG-System (Retrieval Augmented Generation)** mit Web-Interface.
|
||||
1. **Source:** Markdown-Notizen in einem Vault (Obsidian-kompatibel).
|
||||
2. **Pipeline:** Ein Python-Importer transformiert diese in **Notes**, **Chunks** und **Edges**.
|
||||
* **Neu in v2.6:** Intelligente Kanten-Zuweisung durch lokale LLMs (**Smart Edge Allocation**).
|
||||
3. **Storage:**
|
||||
* **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. **Backend:** Eine FastAPI-Anwendung stellt Endpunkte für **Semantische** und **Hybride Suche** sowie **Feedback** bereit.
|
||||
* **Update v2.6:** Der Core arbeitet nun vollständig **asynchron (AsyncIO)** mit **Traffic Control** (Semaphore zur Lastverteilung).
|
||||
5. **Frontend:** Streamlit-App (`ui.py`) für Interaktion und Visualisierung inkl. **Draft Editor**, **Active Intelligence** und **Healing Parser**.
|
||||
6. **Inference:** Lokales LLM (Ollama: Phi-3 Mini) für RAG-Chat und Antwortgenerierung. Embedding via `nomic-embed-text`.
|
||||
|
||||
Das System arbeitet **deterministisch** (stabile IDs) und ist **konfigurationsgetrieben** (`types.yaml`, `retriever.yaml`, `decision_engine.yaml`, `prompts.yaml`).
|
||||
|
||||
### 1.2 Verzeichnisstruktur & Komponenten (Post-WP15)
|
||||
|
||||
/mindnet/
|
||||
├── app/
|
||||
│ ├── main.py # FastAPI Einstiegspunkt
|
||||
│ ├── core/
|
||||
│ │ ├── ingestion.py # NEU: Async Ingestion mit Change Detection
|
||||
│ │ ├── qdrant.py # Client-Factory & Connection
|
||||
│ │ ├── qdrant_points.py # Low-Level Point Operations (Upsert/Delete)
|
||||
│ │ ├── note_payload.py # Bau der Note-Objekte
|
||||
│ │ ├── chunk_payload.py # Bau der Chunk-Objekte
|
||||
│ │ ├── chunker.py # Smart Chunker Orchestrator (WP15)
|
||||
│ │ ├── edges.py # Edge-Datenstrukturen
|
||||
│ │ ├── derive_edges.py # Logik der Kantenableitung (WP03)
|
||||
│ │ ├── graph_adapter.py # Subgraph & Reverse-Lookup (WP04b)
|
||||
│ │ └── retriever.py # Scoring, Expansion & Explanation (WP04a/b)
|
||||
│ ├── models/ # Pydantic DTOs
|
||||
│ │ └── dto.py # Zentrale DTO-Definition
|
||||
│ ├── routers/
|
||||
│ │ ├── query.py # Such-Endpunkt
|
||||
│ │ ├── ingest.py # NEU: API für Save & Analyze (WP11)
|
||||
│ │ ├── chat.py # Hybrid Router v5 & Interview Logic (WP06/07)
|
||||
│ │ ├── feedback.py # Feedback-Endpunkt (WP04c)
|
||||
│ │ └── ...
|
||||
│ ├── services/
|
||||
│ │ ├── llm_service.py # Ollama Chat Client mit Traffic Control (v2.8.0)
|
||||
│ │ ├── semantic_analyzer.py# NEU: LLM-Filter für Edges (WP15)
|
||||
│ │ ├── embeddings_client.py# NEU: Async Embeddings (HTTPX)
|
||||
│ │ ├── feedback_service.py # Logging (JSONL Writer)
|
||||
│ │ └── discovery.py # NEU: Intelligence Logic (WP11)
|
||||
│ ├── frontend/ # NEU (WP10)
|
||||
│ │ └── ui.py # Streamlit Application inkl. Healing Parser
|
||||
│ └── main.py # Entrypoint der API
|
||||
├── config/ # YAML-Konfigurationen (Single Source of Truth)
|
||||
│ ├── types.yaml # Import-Regeln & Smart-Edge Config
|
||||
│ ├── prompts.yaml # LLM Prompts & Interview Templates (WP06/07)
|
||||
│ ├── decision_engine.yaml # Router-Strategien (Actions only)
|
||||
│ └── retriever.yaml # Scoring-Regeln & Kantengewichte
|
||||
├── data/
|
||||
│ └── logs/ # Lokale Logs (search_history.jsonl, feedback.jsonl)
|
||||
├── scripts/ # CLI-Tools (Import, Diagnose, Reset)
|
||||
│ ├── import_markdown.py # Haupt-Importer CLI (Async)
|
||||
│ ├── payload_dryrun.py # Diagnose: JSON-Generierung ohne DB
|
||||
│ └── edges_full_check.py # Diagnose: Graph-Integrität
|
||||
├── tests/ # Pytest Suite & Smoke Scripts
|
||||
└── vault/ # Dein lokaler Markdown-Content (Git-ignored)
|
||||
|
||||
---
|
||||
|
||||
## 2. Datenmodell & Collections (Qdrant)
|
||||
|
||||
Das Datenmodell verteilt sich auf drei Collections, definiert durch `COLLECTION_PREFIX` (Standard: `mindnet`).
|
||||
|
||||
### 2.1 Notes Collection (`<prefix>_notes`)
|
||||
Repräsentiert die Metadaten einer Datei.
|
||||
* **Zweck:** Filterung, Metadaten-Haltung, Vererbung von Eigenschaften an Chunks.
|
||||
* **Schema (Payload):**
|
||||
|
||||
| Feld | Datentyp | Beschreibung | Herkunft |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `note_id` | Keyword | Stabile ID (UUIDv5 oder Slug). | Frontmatter |
|
||||
| `title` | Text | Titel der Notiz. | Frontmatter |
|
||||
| `type` | Keyword | Logischer Typ (z.B. `concept`). | `types.yaml` Resolver |
|
||||
| `retriever_weight` | Float | Wichtigkeit im Retrieval. | `types.yaml` |
|
||||
| `chunk_profile` | Keyword | Genutztes Chunking-Profil. | `types.yaml` |
|
||||
| `edge_defaults` | List[Str] | Aktive Default-Relationen. | `types.yaml` |
|
||||
| `tags` | List[Kw] | Tags zur Filterung. | Frontmatter |
|
||||
| `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.
|
||||
* **Update v2.4:** Vektor-Dimension ist jetzt **768** (für `nomic-embed-text`).
|
||||
* **Schema (Payload):**
|
||||
|
||||
| Feld | Datentyp | Beschreibung |
|
||||
| :--- | :--- | :--- |
|
||||
| `chunk_id` | Keyword | Deterministisch: `{note_id}#c{index:02d}`. |
|
||||
| `note_id` | Keyword | Referenz zur Note. |
|
||||
| `type` | Keyword | **Kopie des Note-Typs** (Denormalisiert für Filter). |
|
||||
| `text` | Text | **Reiner Inhalt** (ohne Overlap). Anzeige-Text. |
|
||||
| `window` | Text | **Kontext-Fenster** (mit Overlap). Embedding-Basis. |
|
||||
| `ord` | Integer | Sortierreihenfolge (1..N). |
|
||||
| `retriever_weight` | Float | Vererbt von Note. |
|
||||
| `chunk_profile` | Keyword | Vererbt von Note. |
|
||||
| `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.
|
||||
* **Schema (Payload):**
|
||||
|
||||
| Feld | Datentyp | Beschreibung | Wertebereich (Bsp.) |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `edge_id` | Keyword | Hash aus (src, dst, kind). | |
|
||||
| `source_id` | Keyword | ID des Start-Chunks. | |
|
||||
| `target_id` | Keyword | ID des Ziel-Chunks (oder Note-Titel). | |
|
||||
| `note_id` | Keyword | Note, die diese Kante definiert. | |
|
||||
| `kind` | Keyword | Art der Beziehung. | `references`, `depends_on`, `next` |
|
||||
| `scope` | Keyword | Geltungsbereich. | Immer `"chunk"` (v2.2). |
|
||||
| `rule_id` | Keyword | Herkunftsregel. | `explicit:wikilink`, `inline:rel` |
|
||||
| `confidence` | Float | Vertrauenswürdigkeit (0.0-1.0). | 1.0, 0.95, 0.7 |
|
||||
| `provenance` | Keyword | Quelle der Kante (Neu in v2.6). | `explicit`, `rule`, `smart` |
|
||||
|
||||
---
|
||||
|
||||
## 3. Konfiguration
|
||||
|
||||
Die Logik ist ausgelagert in YAML-Dateien.
|
||||
|
||||
### 3.1 Typ-Registry (`config/types.yaml`)
|
||||
Steuert den Import-Prozess.
|
||||
* **Priorität:** Frontmatter > Pfad > Default.
|
||||
* **Neu in v2.6:**
|
||||
* `enable_smart_edge_allocation`: (Bool) Aktiviert den LLM-Filter für diesen Typ.
|
||||
* `detection_keywords`: (List) Keywords für den Hybrid Router ("Objekterkennung").
|
||||
* **Inhalt (Beispiel):**
|
||||
|
||||
types:
|
||||
concept:
|
||||
chunk_profile: sliding_standard
|
||||
edge_defaults: ["references", "related_to"]
|
||||
retriever_weight: 0.60
|
||||
experience:
|
||||
chunk_profile: sliding_smart_edges
|
||||
enable_smart_edge_allocation: true
|
||||
detection_keywords: ["erfahrung", "erlebt"]
|
||||
|
||||
### 3.2 Retriever-Config (`config/retriever.yaml`)
|
||||
Steuert das Scoring zur Laufzeit (WP04a).
|
||||
* **Inhalt (Beispiel):**
|
||||
|
||||
scoring:
|
||||
semantic_weight: 1.0
|
||||
edge_weight: 0.7
|
||||
centrality_weight: 0.5
|
||||
|
||||
### 3.3 Decision Engine (`config/decision_engine.yaml`)
|
||||
**Neu in WP06/07:** Steuert den Intent-Router.
|
||||
* Definiert Strategien (`DECISION`, `INTERVIEW`, etc.).
|
||||
* **Update v2.6:** Enthält nur noch **Handlungs-Keywords** (Verben wie "neu", "erstellen"). Objektnamen ("Projekt") werden nun über `types.yaml` aufgelöst.
|
||||
* Definiert LLM-Router-Settings (`llm_fallback_enabled`).
|
||||
|
||||
### 3.4 Prompts (`config/prompts.yaml`)
|
||||
Steuert die LLM-Persönlichkeit und Templates.
|
||||
* Enthält Templates für alle Strategien inkl. `interview_template` und neu `router_prompt`.
|
||||
|
||||
### 3.5 Environment (`.env`)
|
||||
Erweiterung für LLM-Steuerung und Embedding-Modell:
|
||||
|
||||
MINDNET_LLM_MODEL=phi3:mini
|
||||
MINDNET_EMBEDDING_MODEL=nomic-embed-text # NEU in v2.3.10
|
||||
MINDNET_OLLAMA_URL=http://127.0.0.1:11434
|
||||
MINDNET_LLM_TIMEOUT=300.0 # Neu: Erhöht für CPU-Inference Cold-Starts
|
||||
MINDNET_API_TIMEOUT=300.0 # Neu: Timeout für Frontend-API (Smart Edges brauchen Zeit)
|
||||
MINDNET_DECISION_CONFIG="config/decision_engine.yaml"
|
||||
MINDNET_VAULT_ROOT="./vault" # Neu: Pfad für Write-Back
|
||||
MINDNET_LLM_BACKGROUND_LIMIT=2 # Neu: Limit für parallele Hintergrund-Jobs (Traffic Control)
|
||||
|
||||
---
|
||||
|
||||
## 4. Import-Pipeline (Markdown → Qdrant)
|
||||
|
||||
Das Skript `scripts/import_markdown.py` orchestriert den Prozess.
|
||||
**Neu in v2.6:** Der Import nutzt `asyncio` und **Traffic Control**, um Ollama nicht zu überlasten.
|
||||
|
||||
### 4.1 Verarbeitungsschritte (Async + Smart)
|
||||
|
||||
1. **Discovery & Parsing:** Hash-Vergleich zur Erkennung von Änderungen.
|
||||
2. **Typauflösung:** Bestimmung des `type` via `types.yaml`.
|
||||
3. **Config Check:** Laden des `chunk_profile` und `enable_smart_edge_allocation`.
|
||||
4. **Chunking & Smart Edges (WP15):**
|
||||
* Zerlegung des Textes via `chunker.py`.
|
||||
* Wenn Smart Edges aktiv: Der `SemanticAnalyzer` sendet Chunks an das LLM.
|
||||
* **Traffic Control:** Der Request nutzt `priority="background"`. Die Semaphore (Limit: 2) drosselt die Parallelität.
|
||||
5. **Kantenableitung (Edge Derivation):**
|
||||
* `derive_edges.py` erzeugt Inline-, Callout- und Default-Edges.
|
||||
6. **Embedding (Async):**
|
||||
* Der `EmbeddingsClient` (`app/services/embeddings_client.py`) sendet Text-Chunks asynchron an Ollama.
|
||||
* Modell: `nomic-embed-text` (768d).
|
||||
7. **Upsert:**
|
||||
* Schreiben in Qdrant. Nutzung von `--purge-before-upsert`.
|
||||
* **Strict Mode:** Der Prozess bricht ab, wenn Embeddings leer sind oder Dimension `0` haben.
|
||||
|
||||
---
|
||||
|
||||
## 5. Retriever-Architektur & Scoring
|
||||
|
||||
Der Retriever (`app/core/retriever.py`) unterstützt zwei Modi. Für den Chat wird **zwingend** der Hybrid-Modus genutzt.
|
||||
|
||||
### 5.1 Betriebsmodi
|
||||
* **Semantic:** Reine Vektorsuche (768d).
|
||||
* **Hybrid:** Vektorsuche + Graph-Expansion (Tiefe N) + Re-Ranking.
|
||||
|
||||
### 5.2 Scoring-Formel (WP04a)
|
||||
Die Relevanzberechnung ist nun eine gewichtete Summe:
|
||||
|
||||
$$
|
||||
TotalScore = (W_{sem} \cdot S_{sem} \cdot \max(W_{type}, 0)) + (W_{edge} \cdot B_{edge}) + (W_{cent} \cdot B_{cent})
|
||||
$$
|
||||
|
||||
* **Komponenten:**
|
||||
* $S_{sem}$: Semantic Score (Cosine Similarity).
|
||||
* $W_{type}$: `retriever_weight` (aus Note/Chunk Payload).
|
||||
* $B_{edge}$: Edge-Bonus (Summe der Konfidenzen eingehender relevanter Kanten).
|
||||
* $B_{cent}$: Centrality-Bonus (im lokalen Subgraphen).
|
||||
* **Gewichte ($W$):** Stammen aus `retriever.yaml`.
|
||||
|
||||
### 5.3 Explanation Layer (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.
|
||||
|
||||
### 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. RAG & Chat Architektur (WP06 Hybrid Router + WP07 Interview)
|
||||
|
||||
Der Flow für eine Chat-Anfrage (`/chat`) wurde in WP06 auf eine **Configuration-Driven Architecture** umgestellt und in WP15 (v2.6) verfeinert.
|
||||
|
||||
### 6.1 Architektur-Pattern: Intent Router v5
|
||||
Die Behandlung einer Anfrage ist nicht mehr hartkodiert, sondern wird dynamisch zur Laufzeit entschieden.
|
||||
* **Input:** User Message.
|
||||
* **Config:** `decision_engine.yaml` (Strategien) + `types.yaml` (Objekte).
|
||||
* **Komponenten:**
|
||||
* **Traffic Control:** `LLMService` priorisiert Chat-Anfragen.
|
||||
* **Question Detection:** Unterscheidung Frage vs. Befehl.
|
||||
|
||||
### 6.2 Traffic Control (Priorisierung)
|
||||
Der `LLMService` implementiert zwei Spuren basierend auf `app/services/llm_service.py` (v2.8.0):
|
||||
* **Realtime (Chat):** `priority="realtime"`. Umgeht die Semaphore. Antwortet sofort.
|
||||
* **Background (Import/Analyse):** `priority="background"`. Wartet in der Semaphore (`asyncio.Semaphore`), die lazy mit `MINDNET_LLM_BACKGROUND_LIMIT` initialisiert wird.
|
||||
|
||||
### 6.3 Schritt 1: Intent Detection (Question vs. Action)
|
||||
Der Router ermittelt die Absicht (`Intent`) des Nutzers.
|
||||
1. **Frage-Check:** Wenn der Input ein `?` enthält oder mit W-Wörtern beginnt, wird der **RAG-Modus** erzwungen (oder LLM-Entscheidung). Interviews werden hier unterdrückt.
|
||||
2. **Keyword Scan (Fast Path):**
|
||||
* Prüfung auf `trigger_keywords` (Handlung) in `decision_engine.yaml`.
|
||||
* Prüfung auf `detection_keywords` (Objekt) in `types.yaml`.
|
||||
* Treffer -> **INTERVIEW Modus** (Erfassen).
|
||||
3. **LLM Fallback (Slow Path):**
|
||||
* Greift, wenn keine Keywords passen. Sendet Query an LLM Router.
|
||||
|
||||
### 6.4 Schritt 2: Strategy Resolution
|
||||
Basierend auf dem Intent lädt der Router die Parameter:
|
||||
* **Bei RAG (FACT/DECISION):** `inject_types` für Strategic Retrieval.
|
||||
* **Bei INTERVIEW (WP07):** `schemas` (Pflichtfelder) basierend auf der erkannten Ziel-Entität (`_detect_target_type`).
|
||||
|
||||
### 6.5 Schritt 3: Retrieval vs. Extraction
|
||||
Der Router verzweigt hier:
|
||||
|
||||
**A) RAG Modus (FACT, DECISION, EMPATHY):**
|
||||
1. **Primary Retrieval:** Hybride Suche nach der User-Query.
|
||||
2. **Strategic Retrieval (Conditional):** Wenn `inject_types` definiert sind, erfolgt eine zweite Suche, die explizit auf diese Typen filtert.
|
||||
3. **Merge:** Ergebnisse werden dedupliziert zusammengeführt.
|
||||
|
||||
**B) Interview Modus (INTERVIEW):**
|
||||
1. **Kein Retrieval:** Der Kontext ist der Chat-Verlauf (oder initial die Query).
|
||||
2. **Schema Injection:** Das Schema für den erkannten Typ (z.B. "Project") wird geladen.
|
||||
3. **Prompt Assembly:** Der `interview_template` Prompt wird mit der Schema-Definition ("Ziel", "Status") gefüllt.
|
||||
|
||||
### 6.6 Schritt 4: Generation & Response
|
||||
* **Templating:** Das LLM erhält den Prompt basierend auf dem gewählten Template.
|
||||
* **Execution:** Der `LLMService` führt den Call mit `priority="realtime"` aus.
|
||||
* **Response:** Rückgabe enthält Antworttext (im Interview-Modus: Markdown Codeblock), Quellenliste und den erkannten `intent`.
|
||||
|
||||
---
|
||||
|
||||
## 7. Frontend Architektur (WP10)
|
||||
|
||||
Das Frontend ist eine **Streamlit-Anwendung** (`app/frontend/ui.py`), die als separater Prozess läuft und via HTTP mit dem Backend kommuniziert.
|
||||
|
||||
### 7.1 Kommunikation
|
||||
* **Backend-URL:** Konfiguriert via `MINDNET_API_URL` (Default: `http://localhost:8002`).
|
||||
* **Endpoints:**
|
||||
* `/chat` (Interaktion)
|
||||
* `/feedback` (Bewertungen)
|
||||
* `/ingest/analyze` (Active Intelligence / Link-Vorschläge)
|
||||
* `/ingest/save` (Persistence / Speichern im Vault)
|
||||
* **Resilienz:** Das Frontend nutzt `MINDNET_API_TIMEOUT` (300s), um auf langsame Backend-Prozesse (Smart Edges) zu warten.
|
||||
|
||||
### 7.2 Features & UI-Logik
|
||||
* **State Management:** Session-State speichert Chat-Verlauf und `query_id`.
|
||||
* **Visualisierung:**
|
||||
* **Intent Badges:** Zeigt Router-Entscheidung (`DECISION`, `INTERVIEW`, etc.).
|
||||
* **Source Expanders:** Zeigt verwendete Chunks inkl. Score und "Why"-Explanation.
|
||||
* **Sidebar:** Zeigt Suchhistorie (Log-basiert) und Konfiguration.
|
||||
|
||||
### 7.3 Draft-Editor & Healing Parser (Neu in WP10a/v2.5)
|
||||
Wenn der Intent `INTERVIEW` ist, rendert die UI statt einer Textblase den **Draft-Editor**.
|
||||
|
||||
1. **Parsing:** Die Funktion `parse_markdown_draft` extrahiert den Codeblock aus der LLM-Antwort.
|
||||
* **Healing:** Erkennt und repariert defekte YAML-Frontmatter (z.B. fehlendes schließendes `---`), falls das LLM unter Last Fehler macht.
|
||||
2. **Sanitization (`normalize_meta_and_body`):**
|
||||
* Prüft den YAML-Frontmatter auf unerlaubte Felder (Halluzinationen des LLMs).
|
||||
* Verschiebt ungültige Felder (z.B. "Situation") in den Body der Notiz.
|
||||
3. **Editor Widget:** `st.text_area` erlaubt das Bearbeiten des Inhalts vor dem Speichern.
|
||||
4. **Save Action:** Speichert über `/ingest/save` atomar in Vault und DB. Erzeugt intelligente Dateinamen via `slugify`.
|
||||
|
||||
### 7.4 State Management (Resurrection Pattern)
|
||||
Um Datenverlust bei Tab-Wechseln (Chat <-> Editor) zu verhindern, nutzt `ui.py` ein Persistenz-Muster:
|
||||
* Daten liegen in `st.session_state[data_key]`.
|
||||
* Widgets liegen in `st.session_state[widget_key]`.
|
||||
* Callbacks (`on_change`) synchronisieren Widget -> Data.
|
||||
* Beim Neu-Rendern wird Widget-State aus Data-State wiederhergestellt.
|
||||
|
||||
### 7.5 Deployment Ports
|
||||
Zur sauberen Trennung von Prod und Dev laufen Frontend und Backend auf dedizierten Ports:
|
||||
|
||||
| Umgebung | Backend (FastAPI) | Frontend (Streamlit) |
|
||||
| :--- | :--- | :--- |
|
||||
| **Production** | 8001 | 8501 |
|
||||
| **Development** | 8002 | 8502 |
|
||||
|
||||
---
|
||||
|
||||
## 8. Feedback & Logging Architektur (WP04c)
|
||||
|
||||
Mindnet implementiert ein "Data Flywheel" zur späteren Optimierung (Self-Tuning).
|
||||
|
||||
### 8.1 Komponenten
|
||||
* **Feedback Service (`app/services/feedback_service.py`):** Kapselt die Schreibzugriffe.
|
||||
* **Storage:** Lokales Dateisystem (`data/logs/`), Format JSONL (Line-delimited JSON).
|
||||
|
||||
### 8.2 Log-Dateien
|
||||
1. **`search_history.jsonl`**:
|
||||
* Speichert jede Anfrage an `/query` und `/chat`.
|
||||
* 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`.
|
||||
* **Granularität:** Kann sich auf `generated_answer` (Global) oder eine spezifische `node_id` (Quelle) beziehen.
|
||||
* Zweck: Labels ("War es gut?").
|
||||
|
||||
### 8.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.
|
||||
|
||||
---
|
||||
|
||||
## 9. Indizes & Performance
|
||||
|
||||
Damit Qdrant performant bleibt, sind Payload-Indizes essenziell.
|
||||
|
||||
**Erforderliche Indizes:**
|
||||
* **Notes:** `note_id`, `type`, `tags`.
|
||||
* **Chunks:** `note_id`, `chunk_id`, `type`.
|
||||
* **Edges:** `source_id`, `target_id`, `kind`, `scope`, `note_id`.
|
||||
|
||||
Validierung erfolgt über `tests/ensure_indexes_and_show.py`.
|
||||
|
||||
---
|
||||
|
||||
## 10. Offene Punkte / Known Limitations
|
||||
|
||||
1. **Multi-Target Inline-Relations:**
|
||||
* `rel: similar_to [[A]] [[B]]` wird aktuell parser-seitig nicht unterstützt.
|
||||
* Workaround: Zwei separate Inline-Links `[[rel:similar_to A]] [[rel:similar_to B]]`.
|
||||
2. **Unresolved Targets:**
|
||||
* Kanten zu Notizen, die noch nicht existieren, werden mit `target_id="Titel"` angelegt.
|
||||
* Heilung durch `scripts/resolve_unresolved_references.py` möglich.
|
||||
3. **Hardware-Last bei Smart Import:**
|
||||
* Der "Smart Edge" Import ist rechenintensiv. Trotz Traffic Control kann die Antwortzeit im Chat leicht steigen, wenn die GPU am VRAM-Limit arbeitet.
|
||||
@@ -0,0 +1,291 @@
|
||||
# mindnet v2.4 – Pipeline Playbook
|
||||
**Datei:** `docs/mindnet_pipeline_playbook_v2.6.md`
|
||||
**Stand:** 2025-12-12
|
||||
**Status:** **FINAL** (Inkl. Smart Edges & Traffic Control)
|
||||
**Quellen:** `mindnet_v2_implementation_playbook.md`, `Handbuch.md`, `chunking_strategy.md`, `docs_mindnet_retriever.md`, `mindnet_admin_guide_v2.4.md`.
|
||||
|
||||
---
|
||||
<details>
|
||||
<summary>📖 <b>Inhaltsverzeichnis (Klicken zum Öffnen)</b></summary>
|
||||
|
||||
- [mindnet v2.4 – Pipeline Playbook](#mindnet-v24--pipeline-playbook)
|
||||
- [](#)
|
||||
- [1. Zweck \& Einordnung](#1-zweck--einordnung)
|
||||
- [2. Die Import-Pipeline (Runbook)](#2-die-import-pipeline-runbook)
|
||||
- [2.1 Der 13-Schritte-Prozess (Async + Smart)](#21-der-13-schritte-prozess-async--smart)
|
||||
- [2.2 Standard-Betrieb (Inkrementell)](#22-standard-betrieb-inkrementell)
|
||||
- [2.3 Deployment \& Restart (Systemd)](#23-deployment--restart-systemd)
|
||||
- [2.4 Full Rebuild (Clean Slate)](#24-full-rebuild-clean-slate)
|
||||
- [3. Chunking \& Payload-Aufbau](#3-chunking--payload-aufbau)
|
||||
- [3.1 Chunk-Profile](#31-chunk-profile)
|
||||
- [3.2 Payload-Felder](#32-payload-felder)
|
||||
- [4. Edge-Erzeugung (Die V2-Logik)](#4-edge-erzeugung-die-v2-logik)
|
||||
- [4.1 Prioritäten \& Provenance](#41-prioritäten--provenance)
|
||||
- [4.2 Smart Edge Allocation (WP15)](#42-smart-edge-allocation-wp15)
|
||||
- [4.3 Typ-Defaults](#43-typ-defaults)
|
||||
- [5. Retriever, Chat \& Generation (RAG Pipeline)](#5-retriever-chat--generation-rag-pipeline)
|
||||
- [5.1 Retrieval (Hybrid)](#51-retrieval-hybrid)
|
||||
- [5.2 Intent Router (WP06/07)](#52-intent-router-wp0607)
|
||||
- [5.3 Context Enrichment](#53-context-enrichment)
|
||||
- [5.4 Generation (LLM) mit Traffic Control](#54-generation-llm-mit-traffic-control)
|
||||
- [5.5 Active Intelligence Pipeline (Neu in v2.4)](#55-active-intelligence-pipeline-neu-in-v24)
|
||||
- [6. Feedback \& Lernen (WP04c)](#6-feedback--lernen-wp04c)
|
||||
- [7. Quality Gates \& Tests](#7-quality-gates--tests)
|
||||
- [7.1 Pflicht-Tests vor Commit](#71-pflicht-tests-vor-commit)
|
||||
- [7.2 Smoke-Test (E2E)](#72-smoke-test-e2e)
|
||||
- [8. Ausblick \& Roadmap (Technische Skizzen)](#8-ausblick--roadmap-technische-skizzen)
|
||||
- [8.1 WP-08: Self-Tuning (Skizze)](#81-wp-08-self-tuning-skizze)
|
||||
- [16. Workpackage Status (v2.6.0)](#16-workpackage-status-v260)
|
||||
|
||||
</details>
|
||||
---
|
||||
|
||||
## 1. Zweck & Einordnung
|
||||
|
||||
Dieses Playbook ist das zentrale operative Handbuch für die **mindnet-Pipeline**. Es beschreibt, wie Daten vom Markdown-Vault in den Wissensgraphen (Qdrant) gelangen, wie der Retriever betrieben wird und wie die **RAG-Generierung** (inkl. Decision Engine & Interviewer) funktioniert.
|
||||
|
||||
**Zielgruppe:** Dev/Ops, Tech-Leads.
|
||||
**Scope:**
|
||||
* **Ist-Stand (WP01–WP15):** Async Import, Smart Chunking, Edge-Erzeugung, Hybrider Retriever, RAG-Chat (Hybrid Router), Feedback Loop, Frontend, Draft Editor, Active Intelligence.
|
||||
* **Roadmap (Ausblick):** Technische Skizze für Self-Tuning (WP08).
|
||||
|
||||
---
|
||||
|
||||
## 2. Die Import-Pipeline (Runbook)
|
||||
|
||||
Der Import ist der kritischste Prozess ("Data Ingestion"). Er muss **deterministisch** und **idempotent** sein. Wir nutzen `scripts/import_markdown.py` als zentralen Entrypoint.
|
||||
|
||||
### 2.1 Der 13-Schritte-Prozess (Async + Smart)
|
||||
Seit v2.6 läuft der Import vollständig asynchron, nutzt intelligente Kantenvalidierung (Smart Edges) und drosselt sich selbst ("Traffic Control").
|
||||
|
||||
1. **Markdown lesen:** Rekursives Scannen des Vaults.
|
||||
2. **Frontmatter extrahieren:** Validierung von Pflichtfeldern (`id`, `type`, `title`).
|
||||
3. **Typauflösung:** Bestimmung des `type` via `types.yaml` (Prio: Frontmatter > Pfad > Default).
|
||||
4. **Note-Payload generieren:** Erstellen des JSON-Objekts für `mindnet_notes`.
|
||||
5. **Chunking anwenden:** Zerlegung des Textes basierend auf dem `chunk_profile` des Typs (z.B. `sliding_smart_edges`).
|
||||
6. **Smart Edge Allocation (Neu in WP15):**
|
||||
* Wenn in `types.yaml` aktiviert (`enable_smart_edge_allocation`):
|
||||
* Der `SemanticAnalyzer` sendet jeden Chunk an das LLM.
|
||||
* **Resilienz & Traffic Control:**
|
||||
* **Priority:** Der Request nutzt `priority="background"`.
|
||||
* **Semaphore:** Eine globale Semaphore (Limit: 2, konfigurierbar) verhindert System-Überlastung.
|
||||
* **Retry & Backoff:** Bei Fehlern (Timeouts) wird bis zu 5-mal mit exponentieller Wartezeit wiederholt.
|
||||
* **JSON Repair:** Der Analyzer erkennt fehlerhaftes JSON (z.B. Dict statt Liste) und repariert es automatisch.
|
||||
* **Safety Fallback:** Schlagen alle Versuche fehl, werden die Kanten *allen* Chunks zugewiesen, um Datenverlust zu vermeiden.
|
||||
* Ergebnis: Das LLM filtert irrelevante Links aus dem Chunk ("Broadcasting" verhindern).
|
||||
7. **Inline-Kanten finden:** Parsing von `[[rel:...]]` im Fließtext.
|
||||
8. **Callout-Kanten finden:** Parsing von `> [!edge]` Blöcken.
|
||||
9. **Default-Edges erzeugen:** Anwendung der `edge_defaults` aus der Typ-Registry.
|
||||
10. **Strukturkanten erzeugen:** `belongs_to`, `next`, `prev` (Sequenz).
|
||||
11. **Embedding & Upsert (Async):**
|
||||
* Generierung der Vektoren via `nomic-embed-text` (768 Dim).
|
||||
12. **Strict Mode:** Der Prozess bricht sofort ab, wenn ein Embedding leer ist oder die Dimension `0` hat.
|
||||
13. **Diagnose:** Automatischer Check der Integrität nach dem Lauf.
|
||||
|
||||
### 2.2 Standard-Betrieb (Inkrementell)
|
||||
Für regelmäßige Updates (z.B. Cronjob). Erkennt Änderungen via Hash.
|
||||
|
||||
export QDRANT_URL="http://localhost:6333"
|
||||
export COLLECTION_PREFIX="mindnet"
|
||||
|
||||
# Import starten (Apply = Schreiben, Purge = Sauberer Upsert)
|
||||
# Nutzt das Venv der Produktionsumgebung
|
||||
/home/llmadmin/mindnet/.venv/bin/python3 -m scripts.import_markdown \
|
||||
--vault ./vault \
|
||||
--prefix "$COLLECTION_PREFIX" \
|
||||
--apply \
|
||||
--purge-before-upsert \
|
||||
--sync-deletes
|
||||
|
||||
* `--apply`: Ohne dieses Flag läuft ein Dry-Run (nur Simulation).
|
||||
* `--purge-before-upsert`: Löscht vor dem Schreiben einer Note ihre alten Chunks/Edges. Essentiell, um "Geister-Chunks" zu vermeiden, wenn Text gekürzt wurde.
|
||||
* `--sync-deletes`: Entfernt Notizen aus Qdrant, die im Vault gelöscht wurden.
|
||||
|
||||
### 2.3 Deployment & Restart (Systemd)
|
||||
Nach einem Import oder Code-Update müssen die API-Prozesse neu gestartet werden.
|
||||
|
||||
# Neustart des Produktions-Services (API + UI)
|
||||
sudo systemctl restart mindnet-prod
|
||||
sudo systemctl restart mindnet-ui-prod
|
||||
|
||||
# Prüfung
|
||||
sudo systemctl status mindnet-prod
|
||||
|
||||
### 2.4 Full Rebuild (Clean Slate)
|
||||
Notwendig bei Änderungen an `types.yaml` (z.B. Smart Edges an/aus) oder beim Wechsel des Embedding-Modells.
|
||||
|
||||
**WICHTIG:** Vorher das Modell pullen, sonst schlägt der Import fehl!
|
||||
|
||||
# 0. Modell sicherstellen (WICHTIG für v2.4+)
|
||||
ollama pull nomic-embed-text
|
||||
|
||||
# 1. Qdrant Collections löschen und neu anlegen (Wipe inkl. Schema 768d)
|
||||
python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet" --yes
|
||||
|
||||
# 2. Vollständiger Import aller Dateien
|
||||
python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force
|
||||
|
||||
---
|
||||
|
||||
## 3. Chunking & Payload-Aufbau
|
||||
|
||||
Das Chunking ist profilbasiert und typgesteuert.
|
||||
|
||||
### 3.1 Chunk-Profile
|
||||
In `types.yaml` definiert. Standard-Profile (in `chunk_config.py` implementiert):
|
||||
* `sliding_short`: Max 128 Tokens (z.B. für Logs, Chats).
|
||||
* `sliding_standard`: Max 512 Tokens (Standard für Massendaten).
|
||||
* `sliding_smart_edges`: Sliding Window, optimiert für LLM-Analyse (Fließtext).
|
||||
* `structured_smart_edges`: Trennt strikt an Überschriften (für strukturierte Daten).
|
||||
|
||||
### 3.2 Payload-Felder
|
||||
Jeder Chunk erhält zwei Text-Felder:
|
||||
* `text`: Der reine Inhalt des Chunks (ohne Overlap). Wird dem Nutzer angezeigt.
|
||||
* `window`: Der Inhalt plus Overlap zu Vorgänger/Nachfolger. Wird für das Embedding genutzt (besserer Kontext).
|
||||
|
||||
---
|
||||
|
||||
## 4. Edge-Erzeugung (Die V2-Logik)
|
||||
|
||||
In v2.6 entstehen Kanten nach strenger Priorität.
|
||||
|
||||
### 4.1 Prioritäten & Provenance
|
||||
Der Importer setzt `provenance`, `rule_id` und `confidence` automatisch:
|
||||
|
||||
| Priorität | Quelle | Syntax (Bsp.) | Rule ID | Confidence |
|
||||
| :--- | :--- | :--- | :--- | :--- |
|
||||
| **1** | Inline | `[[rel:depends_on X]]` | `inline:rel` | ~0.95 |
|
||||
| **2** | Callout | `> [!edge] related_to: [[X]]` | `callout:edge` | ~0.90 |
|
||||
| **3** | Wikilink | `[[X]]` | `explicit:wikilink` | 1.00 |
|
||||
| **4** | Smart | *(via LLM Filter)* | `smart:llm_filter` | 0.90 |
|
||||
| **5** | Default | *(via types.yaml)* | `edge_defaults:...` | ~0.70 |
|
||||
| **6** | Struktur | *(automatisch)* | `structure:...` | 1.00 |
|
||||
|
||||
### 4.2 Smart Edge Allocation (WP15)
|
||||
Dieser Mechanismus löst das Problem, dass Chunks sonst alle Links der Note erben.
|
||||
* **Prozess:** Der `SemanticAnalyzer` prüft jeden Chunk: "Ist Link X im Kontext von Chunk Y relevant?"
|
||||
* **Ergebnis:** Kanten werden präzise an den Chunk gebunden, nicht global an die Note.
|
||||
* **Steuerung:** Das Feature wird in `types.yaml` per Typ aktiviert (`enable_smart_edge_allocation: true`).
|
||||
|
||||
### 4.3 Typ-Defaults
|
||||
Wenn in `types.yaml` für einen Typ `edge_defaults` definiert sind, werden diese **additiv** zu expliziten Links erzeugt.
|
||||
* *Beispiel:* Note Typ `project` verlinkt `[[Tool A]]`.
|
||||
* *Ergebnis:* Kante `references` (explizit) UND Kante `depends_on` (Default).
|
||||
|
||||
---
|
||||
|
||||
## 5. Retriever, Chat & Generation (RAG Pipeline)
|
||||
|
||||
Der Datenfluss endet nicht beim Finden. Er geht weiter bis zur Antwort.
|
||||
|
||||
### 5.1 Retrieval (Hybrid)
|
||||
Der `/chat` Endpunkt nutzt **Hybrid Retrieval** (Semantic + Graph), um auch logisch verbundene, aber textlich unterschiedliche Notizen zu finden (z.B. Decisions zu einem Projekt).
|
||||
|
||||
### 5.2 Intent Router (WP06/07)
|
||||
Der Request durchläuft den **Hybrid Router v5**:
|
||||
1. **Question Detection:** Ist es eine Frage (`?`, W-Wörter)? -> RAG Modus. Interviews werden hier blockiert.
|
||||
2. **Keyword Scan:** Enthält es Keywords aus `types.yaml` (Objekt, z.B. "Projekt") oder `decision_engine.yaml` (Action, z.B. "erstellen")? -> INTERVIEW Modus.
|
||||
3. **LLM Fallback:** Wenn unklar, entscheidet das LLM.
|
||||
|
||||
### 5.3 Context Enrichment
|
||||
Der Router (`chat.py`) reichert die gefundenen Chunks mit Metadaten an:
|
||||
* **Typ-Injection:** `[DECISION]`, `[PROJECT]`.
|
||||
* **Reasoning-Infos:** `(Score: 0.75)`.
|
||||
|
||||
### 5.4 Generation (LLM) mit Traffic Control
|
||||
* **Engine:** Ollama (lokal).
|
||||
* **Modell:** `phi3:mini` (Standard).
|
||||
* **Prompting:** Template wird basierend auf Intent gewählt (`decision_template`, `interview_template` etc.).
|
||||
* **Traffic Control:** Der `LLMService` unterscheidet:
|
||||
* **Chat-Requests** (`priority="realtime"`) -> Sofortige Ausführung.
|
||||
* **Import-Requests** (`priority="background"`) -> Gedrosselt durch Semaphore (Standard: 2).
|
||||
|
||||
### 5.5 Active Intelligence Pipeline (Neu in v2.4)
|
||||
Ein paralleler Datenfluss im Frontend ("Draft Editor") zur Unterstützung des Autors.
|
||||
1. **Trigger:** User klickt "Analyse starten" oder tippt.
|
||||
2. **Service:** `ingest/analyze` (Backend).
|
||||
3. **Discovery:**
|
||||
* **Sliding Window:** Zerlegt Text in Abschnitte.
|
||||
* **Embedding:** Vektorisiert Abschnitte via Nomic (Async).
|
||||
* **Exact Match:** Sucht nach Aliases ("KI-Gedächtnis").
|
||||
* **Matrix Logic:** Bestimmt Kanten-Typ (`experience` -> `based_on` -> `value`).
|
||||
4. **Feedback:** UI zeigt Vorschläge (`[[rel:...]]`) zum Einfügen an.
|
||||
|
||||
---
|
||||
|
||||
## 6. Feedback & Lernen (WP04c)
|
||||
|
||||
Das System schreibt kontinuierlich Logs ("Data Flywheel"):
|
||||
* `data/logs/search_history.jsonl`: Trainingsdaten (Query + Ergebnisse + Breakdown).
|
||||
* `data/logs/feedback.jsonl`: Labels (User-Rating zur `query_id`).
|
||||
|
||||
---
|
||||
|
||||
## 7. Quality Gates & Tests
|
||||
|
||||
Diese Tests garantieren die Stabilität der Pipeline.
|
||||
|
||||
### 7.1 Pflicht-Tests vor Commit
|
||||
|
||||
1. **Payload Dryrun (Schema-Check):**
|
||||
Simuliert Import, prüft JSON-Schema Konformität.
|
||||
|
||||
python3 -m scripts.payload_dryrun --vault ./test_vault
|
||||
|
||||
2. **Full Edge Check (Graph-Integrität):**
|
||||
Prüft Invarianten (z.B. `next` muss reziprok zu `prev` sein).
|
||||
|
||||
python3 -m scripts.edges_full_check
|
||||
|
||||
### 7.2 Smoke-Test (E2E)
|
||||
Prüft am laufenden System (Prod oder Dev), ob Semantik, Graph und Feedback funktionieren.
|
||||
|
||||
# Retriever Test
|
||||
python scripts/test_retriever_smoke.py --mode hybrid --top-k 5
|
||||
|
||||
# Intelligence Test (WP11)
|
||||
curl -X POST "http://localhost:8002/ingest/analyze" -d '{"text": "mindnet", "type": "journal"}'
|
||||
|
||||
# Decision Engine Test (WP06)
|
||||
python tests/test_wp06_decision.py -p 8002 -e EMPATHY -q "Alles ist grau"
|
||||
|
||||
# Feedback Test
|
||||
python tests/test_feedback_smoke.py --url http://localhost:8001/query
|
||||
|
||||
---
|
||||
|
||||
## 8. Ausblick & Roadmap (Technische Skizzen)
|
||||
|
||||
Wie entwickeln wir die Pipeline weiter?
|
||||
|
||||
### 8.1 WP-08: Self-Tuning (Skizze)
|
||||
**Ziel:** Die Gewichte in `retriever.yaml` basierend auf `feedback.jsonl` optimieren.
|
||||
**Ansatz:** Ein Offline-Learning-Skript `scripts/optimize_weights.py`.
|
||||
1. **Load:** Liest `search_history.jsonl` und joint mit `feedback.jsonl` via `query_id`.
|
||||
2. **Analyze:** Korrelation Scores vs. User-Rating.
|
||||
3. **Optimize:** Vorschlag neuer Gewichte für `retriever.yaml`.
|
||||
|
||||
---
|
||||
|
||||
## 16. Workpackage Status (v2.6.0)
|
||||
|
||||
Aktueller Implementierungsstand der Module.
|
||||
|
||||
| WP | Titel | Status | Anmerkung |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **WP01** | Knowledge Design | 🟢 Live | Typen, Frontmatter definiert. |
|
||||
| **WP02** | Chunking Strategy | 🟢 Live | Profilbasiertes Chunking aktiv. |
|
||||
| **WP03** | Edge Logic / Import | 🟢 Live | Neue Importer-Pipeline mit Provenance. |
|
||||
| **WP04a**| Retriever Scoring | 🟢 Live | Hybrider Score (Semantik + Graph). |
|
||||
| **WP04b**| Explanation Layer | 🟢 Live | API liefert Reasons & Breakdown. |
|
||||
| **WP04c**| Feedback Loop | 🟢 Live | Logging (JSONL) & Traceability aktiv. |
|
||||
| **WP05** | Persönlichkeit / Chat | 🟢 Live | RAG-Integration mit Context Enrichment. |
|
||||
| **WP06** | Decision Engine | 🟢 Live | Hybrid Router, Strategic Retrieval. |
|
||||
| **WP07** | Interview Assistent | 🟢 Live | **One-Shot Extractor & Schemas aktiv.** |
|
||||
| **WP08** | Self-Tuning | 🔴 Geplant | Auto-Adjustment der Gewichte. |
|
||||
| **WP10** | Chat Interface | 🟢 Live | Web-Interface (Streamlit). |
|
||||
| **WP10a**| Draft Editor | 🟢 Live | **Interaktives UI für WP07 Drafts.** |
|
||||
| **WP11** | Backend Intelligence | 🟢 Live | **Async Ingestion, Nomic Embeddings, Matrix Logic.** |
|
||||
| **WP15** | Smart Edge Allocation | 🟢 Live | **LLM-Filter & Traffic Control aktiv.** |
|
||||
| **WP16** | Auto-Discovery | 🟡 Geplant | UX & Retrieval Tuning. |
|
||||
| **WP17** | Conversational Memory | 🟡 Geplant | Dialog-Gedächtnis. |
|
||||
@@ -0,0 +1,139 @@
|
||||
# Mindnet v2.4 – User Guide
|
||||
**Datei:** `docs/mindnet_user_guide_v2.6.md`
|
||||
**Stand:** 2025-12-12
|
||||
**Status:** **FINAL** (Inkl. Smart Edges, Hybrid Router v5 & Healing UI)
|
||||
**Quellen:** `knowledge_design.md`, `wp04_retriever_scoring.md`, `Programmplan_V2.2.md`, `Handbuch.md`.
|
||||
|
||||
> **Willkommen bei Mindnet.**
|
||||
> Dies ist dein persönliches Wissensnetzwerk und dein Digitaler Zwilling. Es hilft dir beim Erinnern, beim Entscheiden, beim Reflektieren und beim **Erstellen von Inhalten**.
|
||||
|
||||
---
|
||||
|
||||
## 1. Was Mindnet für dich tut
|
||||
|
||||
Mindnet ist ein **assoziatives Gedächtnis** mit Persönlichkeit. Es unterscheidet sich von einer reinen Suche (wie Google) dadurch, dass es **kontextsensitiv** agiert.
|
||||
|
||||
### 1.1 Das Gedächtnis (Der Graph)
|
||||
Wenn du nach "Projekt Alpha" suchst, findet Mindnet nicht nur das Dokument. Es findet auch:
|
||||
* **Abhängigkeiten:** "Technologie X wird benötigt".
|
||||
* **Entscheidungen:** "Warum nutzen wir X?".
|
||||
* **Ähnliches:** "Projekt Beta war ähnlich".
|
||||
* **Neu in v2.6 (Smart Edges):** Mindnet zeigt dir präzise Verknüpfungen an, die für den spezifischen Textabschnitt relevant sind, statt pauschal alle Links der Notiz anzuzeigen.
|
||||
|
||||
### 1.2 Der Zwilling (Die Personas)
|
||||
Mindnet passt seinen Charakter dynamisch an deine Frage an:
|
||||
1. **Der Bibliothekar (FACT):** Liefert präzise Fakten und Definitionen.
|
||||
2. **Der Berater (DECISION):** Hilft dir beim Abwägen, basierend auf deinen Werten und Zielen.
|
||||
3. **Der Spiegel (EMPATHY):** Hört zu und antwortet basierend auf deinen Erfahrungen ("Ich"-Perspektive).
|
||||
4. **Der Analyst (INTERVIEW):** Hilft dir, neue Notizen zu entwerfen und strukturiert zu erfassen.
|
||||
|
||||
---
|
||||
|
||||
## 2. Die Oberfläche (Web UI)
|
||||
|
||||
Seit Version 2.3.1 bedienst du Mindnet über eine grafische Oberfläche im Browser.
|
||||
|
||||
### 2.1 Der Chat-Bereich
|
||||
* **Eingabe:** Unten findest du das Textfeld.
|
||||
* **Intent-Badge:** Über jeder Antwort zeigt ein kleines Label (z.B. **⚖️ Intent: DECISION**), in welchem Modus das System arbeitet und ob dies durch ein Schlüsselwort oder die KI erkannt wurde.
|
||||
* **Quellen-Karten:** Unter der Antwort findest du ausklappbare Karten ("Expanders").
|
||||
* **Grüner Punkt:** Hohe Relevanz (Score > 0.8).
|
||||
* **Gelber Punkt:** Mittlere Relevanz.
|
||||
* **Klick darauf:** Zeigt den Textauszug und die **Begründung** ("Warum wurde das gefunden?").
|
||||
|
||||
### 2.2 Die Sidebar (Einstellungen & Verlauf)
|
||||
* **Modus-Wahl:** Umschalten zwischen "💬 Chat" und "📝 Manueller Editor".
|
||||
* *Neu in v2.4:* Der manuelle Editor speichert deine Eingaben auch beim Wechseln der Tabs ("State Resurrection").
|
||||
* **Verlauf:** Die letzten Suchanfragen sind hier gelistet. Ein Klick führt die Suche erneut aus.
|
||||
* **Settings:**
|
||||
* **Top-K:** Wie viele Quellen sollen gelesen werden? (Standard: 5).
|
||||
* **Explanation Layer:** Schaltet die "Warum"-Erklärungen an/aus.
|
||||
|
||||
---
|
||||
|
||||
## 3. Den Chat steuern (Intents)
|
||||
|
||||
Du steuerst die Persönlichkeit von Mindnet durch deine Wortwahl. Das System nutzt einen **Hybrid Router v5**, der intelligent zwischen Frage und Befehl unterscheidet.
|
||||
|
||||
### 3.1 Frage-Modus (Wissen abrufen)
|
||||
Sobald du ein Fragezeichen `?` benutzt oder Wörter wie "Wer", "Wie", "Was", "Soll ich" verwendest, sucht Mindnet nach Antworten (**RAG**).
|
||||
|
||||
* **Entscheidung ("Soll ich?"):** Mindnet lädt deine **Werte** (`type: value`) und **Ziele** (`type: goal`) in den Kontext und prüft die Fakten dagegen.
|
||||
* *Beispiel:* "Soll ich Tool X nutzen?" -> "Nein, Tool X speichert Daten in den USA. Das verstößt gegen dein Prinzip 'Privacy First' und dein Ziel 'Digitale Autarkie'."
|
||||
* **Empathie ("Ich fühle..."):** Mindnet lädt deine **Erfahrungen** (`type: experience`) und **Glaubenssätze** (`type: belief`). Es antwortet verständnisvoll und zitiert deine eigenen Lektionen.
|
||||
* *Beispiel:* "Ich bin frustriert." -> "Das erinnert mich an Projekt Y, da ging es uns ähnlich..."
|
||||
|
||||
### 3.2 Befehls-Modus (Wissen erfassen / Interview)
|
||||
Wenn du keine Frage stellst, sondern eine Absicht äußerst, wechselt Mindnet in den **Interview-Modus**.
|
||||
|
||||
* **Auslöser:** "Neues Projekt", "Notiz erstellen", "Ich will etwas festhalten", "Neue Entscheidung dokumentieren".
|
||||
* **Was passiert:** Mindnet sucht nicht im Archiv, sondern öffnet den **Draft-Editor**.
|
||||
* **Beispiel:** "Neue Erfahrung: Streit am Recyclinghof." -> Das System erstellt sofort eine strukturierte Notiz mit den Feldern "Situation", "Reaktion" und "Learning".
|
||||
|
||||
---
|
||||
|
||||
## 4. Ergebnisse interpretieren (Explanation Layer)
|
||||
|
||||
Mindnet liefert nicht einfach nur Treffer. Es liefert eine **Begründung** (Explanation), warum es etwas gefunden hat.
|
||||
|
||||
### 4.1 Die Gründe ("Reasons")
|
||||
Öffne eine Quellen-Karte, um zu sehen:
|
||||
* *"Hohe textuelle Übereinstimmung."* (Semantik)
|
||||
* *"Bevorzugt aufgrund des Typs 'decision'."* (Wichtigkeit)
|
||||
* *"Verweist auf 'Projekt X' via 'depends_on'."* (Graph-Kontext)
|
||||
|
||||
---
|
||||
|
||||
## 5. Feedback & Lernen
|
||||
|
||||
Mindnet wird schlauer, wenn du es pflegst. Nutze die Feedback-Funktionen im Chat:
|
||||
|
||||
### 5.1 Globales Feedback (Antwort-Qualität)
|
||||
* **Wie:** Klicke auf die **Sterne (1-5)** unter der Antwort.
|
||||
* **Bedeutung:** Bewertet, wie gut die generierte Antwort war (Prompting, Tonfall).
|
||||
|
||||
### 5.2 Granulares Feedback (Quellen-Relevanz)
|
||||
* **Wie:** Klicke innerhalb einer Quellen-Karte auf die **Smileys (Faces)**.
|
||||
* **Bedeutung:**
|
||||
* 😞 (Sad): Diese Quelle ist irrelevant/falsch. (Senkt zukünftig das Gewicht).
|
||||
* 😐 (Neutral): Okay, aber nicht entscheidend.
|
||||
* 😀 (Grin): Das ist der perfekte Treffer! (Stärkt diesen Typ/Kante).
|
||||
|
||||
---
|
||||
|
||||
## 6. Neues Wissen beisteuern (Authoring)
|
||||
|
||||
Mindnet lebt von deinem Input. Du musst kein Techniker sein, um gutes Wissen zu designen. Siehe dazu das **Knowledge Design Manual** für Details.
|
||||
|
||||
### 6.1 Die Goldene Regel: "Verlinke semantisch"
|
||||
Statt einfach nur `[[Link]]` zu schreiben, versuche zu sagen, *wie* es zusammenhängt.
|
||||
* Hängt es davon ab? -> `[[rel:depends_on Ziel]]`
|
||||
* Ist es ähnlich? -> `[[rel:similar_to Ziel]]`
|
||||
|
||||
### 6.2 Typen nutzen (Wichtig!)
|
||||
Setze im Frontmatter deiner Notizen den richtigen Typ. Das ist der wichtigste Hebel für den Chat:
|
||||
* Willst du, dass Mindnet etwas als **Regel** nutzt? -> `type: principle`
|
||||
* Willst du, dass Mindnet dich an eine **Lektion** erinnert? -> `type: experience`
|
||||
|
||||
### 6.3 Der Interview-Assistent (Drafting)
|
||||
Mindnet kann dir helfen, Markdown-Notizen zu schreiben.
|
||||
|
||||
1. **Start:** Schreibe im Chat: *"Ich möchte ein neues Projekt 'Apollo' starten, Ziel ist die Mondlandung."*
|
||||
2. **Generierung:** Mindnet erkennt den Wunsch (`INTERVIEW`), analysiert den Satz und erstellt **sofort** einen Entwurf.
|
||||
3. **Editor:** Die UI wechselt von der Chat-Blase zu einem **Draft-Editor**.
|
||||
* Du siehst das generierte Frontmatter (`type: project`, `status: draft`).
|
||||
* **Healing UI (v2.5):** Falls das LLM Syntax-Fehler gemacht hat (z.B. fehlendes `---`), hat der Editor das bereits automatisch repariert.
|
||||
* Du siehst den Body-Text mit Platzhaltern (`[TODO]`), wo Infos fehlten (z.B. Stakeholder).
|
||||
4. **Finalisierung:** Ergänze die fehlenden Infos direkt im Editor und klicke auf **Download** oder **Kopieren**.
|
||||
5. **Speichern:** Klicke auf "💾 Speichern". Die Notiz landet sofort im Vault und im Index.
|
||||
|
||||
### 6.4 Der Intelligence-Workflow (Neu in v2.4)
|
||||
Wenn du Texte im **manuellen Editor** schreibst, unterstützt dich Mindnet aktiv bei der Vernetzung:
|
||||
|
||||
1. **Schreiben:** Tippe deinen Text im Tab **"✏️ Inhalt"**.
|
||||
2. **Analysieren:** Wechsle zum Tab **"🧠 Intelligence"** und klicke auf **"🔍 Analyse starten"**. Das System scannt deinen Text (Vektor-Suche & Exact Match).
|
||||
3. **Vorschläge nutzen:**
|
||||
* **Exakte Treffer:** Das System erkennt Begriffe wie "KI-Gedächtnis" automatisch als Alias für "Mindnet (System)".
|
||||
* **Semantische Treffer:** Das System findet inhaltlich verwandte Notizen.
|
||||
* **Klick auf "➕ Einfügen":** Fügt den Link (z.B. `[[rel:related_to Mindnet]]`) an der Cursor-Position oder am Ende ein.
|
||||
4. **Speichern:** Klicke auf "💾 Speichern & Indizieren". Der Text wird sofort in den Vault geschrieben und in Qdrant indiziert.
|
||||
Reference in new issue
Block a user