diff --git a/docs/00_General/00_documentation_map.md b/docs/00_General/00_documentation_map.md new file mode 100644 index 0000000..3957f31 --- /dev/null +++ b/docs/00_General/00_documentation_map.md @@ -0,0 +1,109 @@ +# Mindnet v2.6 – Documentation Map & Governance +**Status:** Active +**Context:** Central Navigation & Maintenance Guide + +## 1. Zweck dieses Dokuments + +Diese Karte dient Entwicklern, dem Mindmaster und KI-Agenten als **zentraler Einstiegspunkt**. Sie beantwortet zwei Fragen: +1. **Navigation:** In welcher Datei finde ich Informationen zu Thema X? +2. **Wartung:** Ich arbeite an Feature Y – welche Dateien muss ich aktualisieren? + +--- + +## 2. Verzeichnisstruktur & Inhalte + +Das Repository ist in **logische Domänen** unterteilt. + +### 📂 00_General (Grundlagen) +*Zielgruppe: Alle* +| Datei | Inhalt & Zweck | +| :--- | :--- | +| `00_vision_and_strategy.md` | **Strategie.** Warum bauen wir das? Prinzipien (Privacy, Local-First), High-Level Architektur. | +| `00_glossary.md` | **Definitionen.** Was bedeutet "Smart Edge", "Traffic Control", "Chunk"? Verhindert Begriffsverwirrung. | +| `00_documentation_map.md` | **Dieser Index.** Navigationshilfe. | + +### 📂 01_User_Manual (Anwendung) +*Zielgruppe: Mindmaster, Autoren, Power-User* +| Datei | Inhalt & Zweck | +| :--- | :--- | +| `01_chat_usage_guide.md` | **Bedienung.** Wie steuere ich die Personas (Berater, Spiegel)? Wie nutze ich das Feedback? | +| `01_knowledge_design.md` | **Content-Regeln.** Die "Bibel" für den Vault. Erklärt Note-Typen, Matrix-Logik und Markdown-Syntax. | + +### 📂 02_Concepts (Fachliche Logik) +*Zielgruppe: Architekten, Product Owner* +| Datei | Inhalt & Zweck | +| :--- | :--- | +| `02_concept_graph_logic.md` | **Graph-Theorie.** Abstrakte Erklärung von Knoten, Kanten, Provenance und Idempotenz. | +| `02_concept_ai_personality.md`| **KI-Verhalten.** Konzepte hinter dem Hybrid Router, Empathie-Modell und "Teach-the-AI". | + +### 📂 03_Technical_Reference (Technik & Code) +*Zielgruppe: Entwickler, DevOps. (Enthält JSON/YAML Beispiele)* +| Datei | Inhalt & Zweck | +| :--- | :--- | +| `03_tech_data_model.md` | **Datenbank.** Exakte Qdrant-Schemas (Payloads) und Index-Anforderungen. | +| `03_tech_ingestion_pipeline.md`| **Import.** Ablauflogik (13 Schritte), Chunker-Profile, Smart Edge Allocation. | +| `03_tech_retrieval_scoring.md` | **Suche.** Die mathematischen Formeln für Scoring, Hybrid Search und Explanation Layer. | +| `03_tech_chat_backend.md` | **API & LLM.** Implementation des Routers, Traffic Control (Semaphore) und Feedback-Traceability. | +| `03_tech_configuration.md` | **Config.** Referenztabellen für `.env`, `types.yaml` und `retriever.yaml`. | + +### 📂 04_Operations (Betrieb) +*Zielgruppe: Administratoren* +| Datei | Inhalt & Zweck | +| :--- | :--- | +| `04_admin_operations.md` | **Runbook.** Installation, Docker-Setup, Backup/Restore, Troubleshooting Guide. | + +### 📂 05_Development (Code) +*Zielgruppe: Entwickler* +| Datei | Inhalt & Zweck | +| :--- | :--- | +| `05_developer_guide.md` | **Workflow.** Hardware-Setup (Win/Pi/Beelink), Git-Flow, Test-Befehle, Modul-Interna. | + +### 📂 06_Roadmap & 99_Archive +*Zielgruppe: Projektleitung* +| Datei | Inhalt & Zweck | +| :--- | :--- | +| `06_active_roadmap.md` | **Zukunft.** Aktive Workpackages (WP16+), Release-Planung und WP-Historie (Tabelle). | +| `99_legacy_workpackages.md` | **Vergangenheit.** Detaillierte Archivdaten zu abgeschlossenen WPs (WP01–WP15). | + +--- + +## 3. Maintenance Guide: "Welche Datei muss ich ändern?" + +Nutze diese Matrix, wenn du ein Workpackage bearbeitest, um die Dokumentation konsistent zu halten. + +| Wenn du arbeitest an... | ...aktualisiere diese Dateien: | +| :--- | :--- | +| **Neuen Note-Typen** | 1. `01_knowledge_design.md` (Für Autoren)
2. `03_tech_configuration.md` (Technische Referenz)
3. `05_developer_guide.md` (Erweiterungs-How-To) | +| **Importer / Parsing** | `03_tech_ingestion_pipeline.md` | +| **Datenbank-Schema** | `03_tech_data_model.md` (Payloads anpassen) | +| **Retrieval / Scoring** | `03_tech_retrieval_scoring.md` (Formeln anpassen) | +| **Chat-Logik / Prompts**| 1. `02_concept_ai_personality.md` (Konzept)
2. `03_tech_chat_backend.md` (Tech)
3. `01_chat_usage_guide.md` (User-Sicht) | +| **Deployment / Server** | `04_admin_operations.md` | +| **Neuen Features (Allg.)**| `06_active_roadmap.md` (Status Update) | + +--- + +## 4. Prinzipien für die Dokumentation (Governance) + +Damit dieses System wartbar bleibt (auch für KI-Agenten wie NotebookLM), gelten folgende Regeln: + +1. **Single Source of Truth:** + Kopiere keine Informationen. Referenziere sie. + * *Ausnahme:* Konkrete JSON-Beispiele in `03_Technical_Reference`. Diese müssen dort stehen, damit Entwickler nicht suchen müssen. + +2. **Konkrete Beispiele:** + Technische Dokumente (`03_*`) müssen **immer** Code-Snippets (JSON, YAML, Shell) enthalten. Abstrakte Beschreibungen reichen nicht für die Implementierung. + +3. **Human Readable:** + User Manuals (`01_*`) müssen Narrative und Szenarien enthalten ("Stell dir vor..."), keine technischen Auflistungen. + +4. **KI-Optimiert (Context Header):** + Jede Datei muss mit einem YAML-Frontmatter beginnen, der `context`, `audience` und `scope` definiert. Dies hilft RAG-Systemen, den Inhalt korrekt einzuordnen. + + ```yaml + --- + doc_type: technical_reference + audience: developer + context: "Beschreibung der Scoring-Formel." + --- + ``` \ No newline at end of file diff --git a/docs/00_General/00_glossary.md b/docs/00_General/00_glossary.md new file mode 100644 index 0000000..29dbb5d --- /dev/null +++ b/docs/00_General/00_glossary.md @@ -0,0 +1,42 @@ +--- +doc_type: glossary +audience: all +status: active +version: 2.6 +context: "Definitionen zentraler Begriffe und Entitäten im Mindnet-System." +--- + +# Mindnet Glossar + +**Quellen:** `appendix.md`, `Overview.md` + +## Kern-Entitäten + +* **Note:** Repräsentiert eine Markdown-Datei. Die fachliche Haupteinheit. +* **Chunk:** Ein Textabschnitt einer Note (meist 512 Tokens). Die technische Sucheinheit (Vektor). +* **Edge:** Eine gerichtete Verbindung zwischen zwei Knoten (Chunks oder Notes). +* **Vault:** Der lokale Ordner mit den Markdown-Dateien (Source of Truth). +* **Frontmatter:** Der YAML-Header am Anfang einer Notiz (enthält `id`, `type`, `title`). + +## Komponenten + +* **Importer:** Das Python-Skript (`ingestion.py`), das Markdown liest und in Qdrant schreibt. +* **Retriever:** Die Komponente, die sucht. Nutzt hybrides Scoring (Semantik + Graph). +* **Decision Engine:** Teil des Routers, der entscheidet, wie auf eine Anfrage reagiert wird (z.B. Strategie wählen). +* **Hybrid Router v5:** Die Logik, die erkennt, ob der User eine Frage stellt (`RAG`) oder einen Befehl gibt (`INTERVIEW`). +* **Draft Editor:** Die Web-UI-Komponente, in der generierte Notizen bearbeitet werden. +* **Traffic Control:** Ein Mechanismus im `LLMService`, der Chat-Anfragen priorisiert und Hintergrund-Jobs (wie Import) drosselt. + +## Konzepte & Features + +* **Active Intelligence:** Feature im Web-Editor, das während des Schreibens automatisch Links vorschlägt. +* **Smart Edge Allocation (WP15):** Ein KI-Verfahren, das prüft, ob ein Link in einer Notiz für einen spezifischen Textabschnitt relevant ist. +* **Healing Parser:** UI-Funktion, die fehlerhaften Output des LLMs (z.B. defektes YAML) automatisch repariert. +* **Explanation Layer:** Die Schicht, die dem Nutzer erklärt, *warum* ein Suchergebnis gefunden wurde (z.B. "Weil Projekt X davon abhängt"). +* **Provenance:** Die Herkunft einer Kante. + * `explicit`: Vom Mensch geschrieben. + * `smart`: Vom LLM validiert. + * `rule`: Durch Config-Regel erzeugt. +* **Matrix Logic:** Regelwerk, das den Typ einer Kante basierend auf Quell- und Ziel-Typ bestimmt (z.B. Erfahrung -> Wert = `based_on`). +* **Idempotenz:** Die Eigenschaft des Importers, bei mehrfacher Ausführung dasselbe Ergebnis zu liefern ohne Duplikate. +* **Resurrection Pattern:** UI-Technik, um User-Eingaben beim Tab-Wechsel zu erhalten. \ No newline at end of file diff --git a/docs/00_General/00_vision_and_strategy.md b/docs/00_General/00_vision_and_strategy.md new file mode 100644 index 0000000..47ae456 --- /dev/null +++ b/docs/00_General/00_vision_and_strategy.md @@ -0,0 +1,67 @@ +--- +doc_type: strategy +audience: all +status: active +version: 2.6 +context: "Vision, Mission und Architekturprinzipien von Mindnet." +--- + +# Mindnet Vision & Strategie + +**Quellen:** `Programmplan_V2.2.md` + +## 1. Programmauftrag + +Mindnet v2.6 entwickelt ein persönliches, wachsendes KI-Gedächtnis. Es ist ein **Digitaler Zwilling**, der: +- Wissen, Erfahrungen und Werte speichert. +- Semantisch verknüpft (Graphen-basiert). +- Als Dialogpartner agiert (RAG-Chat). +- **Lokal und privat** läuft (Privacy First). + +Es ist **kein statisches Archiv**, sondern ein lebendes System, das durch Interaktion (Feedback, Smart Edges) besser wird. + +## 2. Vision + +> „Ein persönliches semantisches Gedächtnis, das mit mir wächst, meine Persönlichkeit spiegelt und mir als intelligenter, erklärbarer, lernender Begleiter dient.“ + +**Kernprinzipien der Vision:** +* **Erklärbarkeit:** Jede Antwort muss begründbar sein ("Why-Layer"). +* **Wachstum:** Das System startet klein und verdichtet sich. +* **Autonomie:** Es schlägt fehlende Kanten selbstständig vor (Smart Edges). +* **Persönlichkeit:** Es entscheidet basierend auf *deinen* Werten. + +--- + +## 3. Architekturprinzipien + +Die folgenden Prinzipien steuern jede technische Entscheidung: + +1. **Late Binding (Späte Semantik):** + Struktur und Interpretation werden in Konfigurationen (`types.yaml`, `prompts.yaml`) definiert, nicht direkt in den Vault-Dateien. Die "Persönlichkeit" ist Config, kein Code. + +2. **Virtual Schema Layer:** + Markdown-Dateien benötigen nur minimale, robuste Angaben (Frontmatter). Komplexität (Chunk-Größe, Gewichte) wird zur Laufzeit injiziert. + +3. **Self-Healing Graph:** + Der Graph wird regelmäßig auf Konsistenz geprüft. "Dangling Edges" werden bereinigt, fehlende Links durch Smart Edges ergänzt. + +4. **Deterministische IDs:** + Notes und Chunks erhalten stabile IDs (UUIDv5). Der Graph ist jederzeit aus dem Markdown wiederaufbaubar. + +5. **Full Explainability:** + Keine Blackbox. Jede Antwort liefert Metadaten (`[DECISION]`, `[PROJECT]`) und Begründungen. + +6. **Persistence First:** + Obsidian (Markdown) bleibt die **einzige Quelle der Wahrheit**. Die Datenbank ist nur ein abgeleiteter Cache. + +7. **Minimalinvasives Schreiben:** + Mindnet schreibt nie ungefragt in deine Notizen. Änderungen erfolgen nur über den Draft Editor oder mit expliziter Zustimmung. + +8. **Incremental Growth:** + Das System muss bereits mit wenigen Notizen nützlich sein. + +9. **Observability:** + Jeder Importlauf und jede Retriever-Anfrage ist logbar. + +10. **Local First & Privacy:** + Nutzung lokaler LLMs (Ollama) für Inference. Keine Daten verlassen den Server. \ No newline at end of file diff --git a/docs/01_User_Manual/01_chat_usage_guide.md b/docs/01_User_Manual/01_chat_usage_guide.md new file mode 100644 index 0000000..e618c31 --- /dev/null +++ b/docs/01_User_Manual/01_chat_usage_guide.md @@ -0,0 +1,111 @@ +--- +doc_type: user_manual +audience: user, mindmaster +scope: chat, ui, feedback +status: active +version: 2.6 +context: "Anleitung zur Nutzung der Web-Oberfläche, der Chat-Personas und des Feedbacks." +--- + +# Chat Usage Guide + +**Quellen:** `user_guide.md` + +## 1. Was Mindnet für dich tut + +Mindnet ist ein **assoziatives Gedächtnis** mit Persönlichkeit. Es unterscheidet sich von einer reinen Suche dadurch, dass es **kontextsensitiv** agiert. + +**Das Gedächtnis (Der Graph):** +Wenn du nach "Projekt Alpha" suchst, findet Mindnet auch: +* **Abhängigkeiten:** "Technologie X wird benötigt". +* **Entscheidungen:** "Warum nutzen wir X?". +* **Ähnliches:** "Projekt Beta war ähnlich". + +**Der Zwilling (Die Personas):** +Mindnet passt seinen Charakter an: Mal ist es der neutrale Bibliothekar, mal der strategische Berater, mal der empathische Spiegel. + +--- + +## 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 +* **Intent-Badge:** Über jeder Antwort siehst du ein Label (z.B. **⚖️ Intent: DECISION**). +* **Quellen-Karten:** Unter der Antwort findest du ausklappbare Karten ("Expanders"). + * **Grüner Punkt:** Hohe Relevanz (Score > 0.8). + * **Klick darauf:** Zeigt den Textauszug und die **Begründung** (Explanation Layer). + +### 2.2 Die Sidebar +* **Modus-Wahl:** Umschalten zwischen "💬 Chat" und "📝 Manueller Editor". + * *Feature:* Der Editor nutzt ein "Resurrection Pattern" – deine Eingaben bleiben erhalten, auch wenn du den Tab wechselst. +* **Settings:** Hier kannst du `Top-K` (Anzahl der Quellen) und `Explanation Layer` steuern. + +--- + +## 3. Den Chat steuern (Intents) + +Du steuerst die Persönlichkeit von Mindnet durch deine Wortwahl. Der **Hybrid Router v5** unterscheidet intelligent: + +### 3.1 Frage-Modus (Wissen abrufen) +Ausgelöst durch `?` oder W-Wörter. + +* **Entscheidung ("Soll ich?"):** Der **Berater**. + * Mindnet lädt deine Werte (`type: value`) und Ziele (`type: goal`). + * *Beispiel:* "Soll ich Tool X nutzen?" -> "Nein, Tool X speichert Daten in den USA. Das verstößt gegen dein Prinzip 'Privacy First'." +* **Empathie ("Ich fühle..."):** Der **Spiegel**. + * Mindnet lädt deine Erfahrungen (`type: experience`). + * *Beispiel:* "Ich bin frustriert." -> "Das erinnert mich an Projekt Y, da ging es uns ähnlich..." +* **Fakten ("Was ist?"):** Der **Bibliothekar**. + * Liefert präzise Definitionen. + +### 3.2 Befehls-Modus (Interview) +Ausgelöst durch Aussagen wie "Neues Projekt", "Ich will festhalten". + +* **Was passiert:** Mindnet sucht nicht, 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 eine **Begründung** ("Reasons"), warum es etwas gefunden hat. +Ö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. + +* **Globales Feedback (Sterne):** Bewertet die generierte Antwort (Prompting, Tonfall). +* **Granulares Feedback (Smileys):** Bewertet die einzelne Quelle. + * 😞 (Sad): Irrelevant. (Senkt das Gewicht dieser Verbindung). + * 😀 (Grin): Perfekter Treffer! (Stärkt diesen Typ/Kante). + +--- + +## 6. Neues Wissen beisteuern (Authoring & Intelligence) + +Mindnet lebt von deinem Input. Du hast drei Wege, Wissen einzugeben: + +### 6.1 Weg A: Der Interview-Assistent (Auto-Drafting) +1. **Start:** Schreibe im Chat: *"Ich möchte ein neues Projekt 'Apollo' starten."* +2. **Generierung:** Mindnet erkennt `INTERVIEW`, wählt das Schema und erstellt einen Entwurf. +3. **Editor:** Die UI zeigt den Entwurf (`status: draft`). + * *Healing UI:* Falls das LLM Syntax-Fehler gemacht hat, hat der Editor sie bereits repariert. +4. **Speichern:** Klicke auf "💾 Speichern". + +### 6.2 Weg B: Der Intelligence-Workflow +Wenn du 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" als Alias für "Mindnet". + * **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 ein. +4. **Speichern:** Der Text wird sofort in den Vault geschrieben und indiziert. \ No newline at end of file diff --git a/docs/01_User_Manual/01_knowledge_design.md b/docs/01_User_Manual/01_knowledge_design.md new file mode 100644 index 0000000..c2cbcd7 --- /dev/null +++ b/docs/01_User_Manual/01_knowledge_design.md @@ -0,0 +1,192 @@ +--- +doc_type: user_manual +audience: user, author +scope: vault, markdown, schema +status: active +version: 2.6 +context: "Regelwerk für das Erstellen von Notizen im Vault. Die 'Source of Truth' für Autoren." +--- + +# Knowledge Design Manual + +**Quellen:** `knowledge_design.md`, `TYPE_REGISTRY_MANUAL.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"). + +--- + +## 1. Zweck & Scope + +Mindnet ist mehr als eine Dokumentablage. Es ist ein vernetztes System, das deine Persönlichkeit abbildet. Die Markdown-Dateien in deinem Vault sind die **einzige Quelle der Wahrheit** ("Source of Truth"). Was nicht im Markdown steht, existiert für das System nicht. + +--- + +## 2. Note-Struktur & Frontmatter + +Jede Notiz benötigt einen YAML-Header (Frontmatter). + +**Pflichtfelder:** + +```yaml +--- +id: 20251212-projekt-alpha # Eindeutige Kennung (YYYYMMDD-slug empfohlen) +title: Projekt Alpha # Sprechender Titel +type: project # Steuert Chunking & Wichtigkeit +status: active # active, archived, draft +created: 2025-12-12 # ISO 8601 +tags: [ki, entwicklung] # Taxonomie +--- +``` + +**Optionale Felder:** +* `aliases`: [Alpha Projekt] – Wichtig für "Active Intelligence" (Exact Match). +* `visibility`: internal (default) / public. + +> **Wichtig:** Felder wie `retriever_weight` oder `chunk_profile` werden zentral über `types.yaml` gesteuert und müssen nicht mehr manuell gesetzt werden (Virtual Schema Layer). + +--- + +## 3. Typ-Referenz & Verhalten + +Wähle den Typ, der die **Rolle** der Notiz am besten beschreibt. Der Typ steuert Chunking, Gewichtung und Kanten-Logik. + +| Typ | Beschreibung & Einsatzzweck | Rolle im Chat (Intent) | Matrix-Logik | +| :--- | :--- | :--- | :--- | +| **`concept`** | Fachbegriffe, Theorien. Zeitloses Wissen. | **FACT** | Ziel für `uses` | +| **`project`** | Ein Vorhaben mit Ziel, Dauer und Aufgaben. | **FACT / DECISION** | Quelle für `depends_on` | +| **`experience`** | Persönliche Erfahrung, Lektion oder Erkenntnis. | **EMPATHY** | Quelle für `based_on` | +| **`decision`** | Eine bewusst getroffene Entscheidung (ADR). | **DECISION** | Quelle für `caused_by` | +| **`value`** | Ein persönlicher Wert oder ein Prinzip. | **DECISION** | Ziel für `based_on` | +| **`principle`** | Handlungsleitlinie. | **DECISION** | Quelle für `derived_from` | +| **`goal`** | Ein strategisches Ziel. | **DECISION** | Ziel für `related_to` | +| **`risk`** | Ein identifiziertes Risiko. | **DECISION** | Quelle für `blocks` | +| **`journal`** | Zeitbezogener Log-Eintrag. | **FACT** | - | + +--- + +## 4. Edges & Verlinkung + +Mindnet versteht Zusammenhänge durch Kanten. + +### 4.1 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]]." + +**Gültige Relationen:** +* `depends_on`: Hängt ab von / Benötigt. +* `blocks`: Blockiert oder gefährdet (z.B. Risiko -> Projekt). +* `caused_by`: Wurde verursacht durch (Kausalität). +* `similar_to`: Ähnelt / Ist vergleichbar mit. +* `solves`: Löst (Problem). +* `based_on`: Basiert auf (Fundament). + +### 4.2 Callout-Edges +Für Zusammenfassungen am Ende einer Notiz: + +```markdown +> [!edge] related_to: [[Vector Embeddings]] [[AI Agents]] +``` + +--- + +## 5. Schreiben für den KI-Zwilling (Szenarien) + +Damit der **RAG-Chat** dich berät, musst du "Futter" für die Decision Engine liefern. + +### Szenario A: Decision Engine (`DECISION`) +* **Ziel:** Das System soll abwägen: "Passt Tool X zu mir?" +* **Vorgehen:** Erstelle Notizen mit `type: value` oder `type: goal`. + +**Beispiel Notiz:** +```yaml +--- +type: value +title: Prinzip: Datensparsamkeit +--- +Wir speichern nur das Minimum an Daten. Cloud-Uploads persönlicher Daten sind verboten, es sei denn, sie sind E2E-verschlüsselt. +``` + +* **Effekt:** Wenn du fragst "Soll ich Notion nutzen?", lädt die Engine diese Notiz und antwortet: *"Nein, Notion ist SaaS ohne E2E. Das verletzt dein Prinzip der Datensparsamkeit."* + +### Szenario B: Empathie (`EMPATHY`) +* **Ziel:** Das System soll dich verstehen. +* **Vorgehen:** Erstelle `type: experience` mit **emotionalen Brückenwörtern**. + +**Beispiel Notiz:** +```yaml +--- +type: experience +title: Erfahrung: Der Durchbruch nach der Krise +tags: [krise, hoffnung, grau, angst] +--- +Es gibt Projektphasen, da wirkt alles **sinnlos** und **grau**. +Ich habe gelernt: Das ist oft das Zeichen kurz vor dem Durchbruch. +``` +* **Effekt:** Bei "Alles ist grau" findet das System diese Notiz und spiegelt die Lektion zurück. + +--- + +## 6. Best Practices & Beispiele (Klassik) + +Hier sind vollständige Vorlagen für häufige Typen. + +### 6.1 Beispiel: Projekt-Notiz +Projekte profitieren von `depends_on`, um Abhängigkeiten zu klären. + +```markdown +--- +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, falls konfiguriert). +``` + +### 6.2 Beispiel: Entscheidung (Decision Record) +Entscheidungen sind hoch gewichtet (`retriever_weight: 1.0`). + +```markdown +--- +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 + +Wir nutzen das Prinzip des **Virtual Schema Layers**. Wir kodieren keine Logik (wie `chunk_size`) in die Notizen. Das wird zentral in der `types.yaml` verwaltet. Das bedeutet für dich: Du kannst dich rein auf den Inhalt konzentrieren. Wenn wir die Chunking-Strategie ändern, müssen wir nicht 1000 Markdown-Dateien anfassen. \ No newline at end of file diff --git a/docs/02_concepts/02_concept_ai_personality.md b/docs/02_concepts/02_concept_ai_personality.md new file mode 100644 index 0000000..4f2afe6 --- /dev/null +++ b/docs/02_concepts/02_concept_ai_personality.md @@ -0,0 +1,92 @@ +--- +doc_type: concept +audience: architect, product_owner +scope: ai, router, personas +status: active +version: 2.6 +context: "Fachkonzept der KI-Persönlichkeit, der Decision Engine und Erweiterungsstrategien." +--- + +# Konzept: KI-Persönlichkeit & Router + +**Quellen:** `mindnet_functional_architecture.md`, `Programmplan_V2.2.md` + +Mindnet soll nicht wie eine Suchmaschine wirken, sondern wie ein **Digitaler Zwilling**. Dazu muss das System erkennen, **was** der Nutzer will, und seine "Persönlichkeit" anpassen. + +## 1. Der Hybrid Router (Das Gehirn) + +Jede Eingabe durchläuft den **Hybrid Router**. Er entscheidet über die Strategie. + +### Modus A: RAG (Retrieval Augmented Generation) +* *Intent:* Der Nutzer hat eine Frage oder ein Problem (`FACT`, `DECISION`, `EMPATHY`). +* *Aktion:* Das System sucht im Gedächtnis und generiert eine Antwort. + +### Modus B: Interview (Knowledge Capture) +* *Intent:* Der Nutzer will Wissen speichern (`INTERVIEW`). +* *Aktion:* Das System sucht **nicht**, sondern fragt ab und erstellt einen Draft. + +--- + +## 2. Die Personas (Strategien) + +Mindnet wechselt den Hut, je nach Situation. + +### 2.1 Der Berater (Strategy: DECISION) +* **Auslöser:** Fragen wie "Soll ich...?", "Was ist besser?". +* **Strategic Retrieval:** Lädt aktiv Notizen der Typen `value` (Werte), `goal` (Ziele) und `risk` (Risiken), auch wenn sie im Text nicht direkt vorkommen. +* **Reasoning:** *"Wäge die Fakten gegen meine Werte ab. Sei strikt bei Risiken."* + +### 2.2 Der Spiegel (Strategy: EMPATHY) +* **Auslöser:** Emotionale Aussagen ("Ich bin frustriert"). +* **Strategic Retrieval:** Lädt `experience` (Erfahrungen) und `belief` (Glaubenssätze). +* **Reasoning:** *"Nutze meine eigenen Erfahrungen, um die Situation einzuordnen."* + +### 2.3 Der Bibliothekar (Strategy: FACT) +* **Auslöser:** Sachfragen ("Was ist Qdrant?"). +* **Behavior:** Präzise, neutral, kurz. + +--- + +## 3. Future Concepts: The Empathic Digital Twin + +Um Mindnet von einer Maschine zu einem echten Spiegel der Persönlichkeit zu entwickeln, sind folgende Konzepte in der Architektur angelegt: + +### 3.1 Antizipation durch Erfahrung +* **Konzept:** Das System soll Konsequenzen vorhersagen ("Was passiert, wenn...?"). +* **Logik:** *"In einer ähnlichen Situation (Projekt A) hat Entscheidung X zu Ergebnis Y geführt."* (Analogie-Schluss). + +### 3.2 Empathie & "Ich"-Modus +* **Konzept:** Das System antwortet im Tonfall des Nutzers. +* **Umsetzung:** Few-Shot Prompting mit eigenen E-Mails/Texten als Stilvorlage. + +### 3.3 Glaubenssätze & Rituale +* **Konzept:** Berücksichtigung weicher Faktoren. +* **Szenario:** Bei Terminplanungen werden Rituale ("Keine Meetings vor 10 Uhr") automatisch als harte Restriktion gegen Anfragen geprüft. + +--- + +## 4. Erweiterbarkeit: Das "Teach-the-AI" Paradigma + +Mindnet lernt nicht durch Training (Fine-Tuning), sondern durch **Konfiguration** und **Vernetzung**. Wenn du dem System ein neues Konzept beibringen willst, musst du an drei Stellen eingreifen. + +**Beispiel: Du willst den Typ `risk` einführen.** + +**1. Daten-Ebene (Physik)** +In `types.yaml`: Definiere Gewicht und Verhalten. +```yaml +risk: + retriever_weight: 0.90 # Hohe Priorität + edge_defaults: ["blocks"] # Automatische Kante zu Projekten +``` + +**2. Strategie-Ebene (Router)** +In `decision_engine.yaml`: Wann soll das geladen werden? +```yaml +DECISION: + inject_types: ["value", "risk"] # Füge 'risk' hinzu +``` + +**3. Kognitive Ebene (Verständnis)** +In `prompts.yaml`: Erkläre dem LLM, was ein Risiko ist. + +**Fazit:** Nur wenn **Daten** (Vault), **Physik** (Config) und **Semantik** (Prompt) zusammenspielen, entsteht ein intelligenter Zwilling. \ No newline at end of file diff --git a/docs/02_concepts/02_concept_graph_logic.md b/docs/02_concepts/02_concept_graph_logic.md new file mode 100644 index 0000000..161a8cf --- /dev/null +++ b/docs/02_concepts/02_concept_graph_logic.md @@ -0,0 +1,99 @@ +--- +doc_type: concept +audience: architect, product_owner +scope: graph, logic, provenance +status: active +version: 2.6 +context: "Fachliche Beschreibung des Wissensgraphen: Knoten, Kanten, Provenance und Matrix-Logik." +--- + +# Konzept: Die Graph-Logik + +**Quellen:** `mindnet_functional_architecture.md`, `chunking_strategy.md` + +Mindnet ist keine reine Dokumentablage, sondern ein **semantischer Graph**. Dieses Dokument beschreibt, wie aus statischen Textdateien ein vernetztes Wissensobjekt wird. + +## 1. Die Knoten (Nodes) + +Der Graph besteht aus zwei Ebenen von Knoten. + +### 1.1 Die Note (Das Fachobjekt) +Eine Note repräsentiert ein atomares Konzept (z.B. "Projekt Alpha"). +* **Eigenschaften:** Titel, Typ, Tags, Erstellungsdatum. +* **Rolle:** Sie ist der Container für Metadaten und steuert via `type`, wie der Inhalt verarbeitet wird (siehe `types.yaml`). +* **Identität:** Definiert durch eine deterministische UUIDv5. + +### 1.2 Der Chunk (Das Suchobjekt) +Da LLMs (Large Language Models) nicht unendlich viel Text auf einmal lesen können, werden Notes in kleinere Segmente (**Chunks**) zerlegt. +* **Eigenschaften:** Vektor (Embedding 768d), Textfenster, Link zum Vorgänger/Nachfolger. +* **Rolle:** Dies sind die eigentlichen Treffer bei einer Suche. +* **Hierarchie:** Jeder Chunk gehört streng zu einer Note (`belongs_to`). + +--- + +## 2. Die Kanten (Edges) + +Kanten machen aus isolierten Informationen Wissen. Mindnet nutzt gerichtete Kanten mit semantischer Bedeutung. + +### 2.1 Semantische Typen + +| Kanten-Typ | Frage, die er beantwortet | Beispiel | +| :--- | :--- | :--- | +| `references` | Worüber wird gesprochen? | Text erwähnt "Python". | +| `depends_on` | Was ist Voraussetzung? | Projekt braucht "Budget". | +| `caused_by` | Warum ist das passiert? | Bug durch "Commit X". | +| `blocks` | Was steht im Weg? | Risiko blockiert "Release". | +| `based_on` | Worauf fußt das? | Erfahrung basiert auf "Wert Y". | +| `derived_from` | Woher kommt das? | Prinzip stammt aus "Buch Z". | +| `related_to` | Was ist ähnlich? | "Hund" ist verwandt mit "Wolf". | +| `solves` | Was ist die Lösung? | "Qdrant" löst "Vektorsuche". | + +### 2.2 Provenance (Herkunft & Vertrauen) + +Nicht alle Kanten sind gleich viel wert. Mindnet unterscheidet in v2.6 drei Qualitätsstufen (**Provenance**), um Konflikte aufzulösen. + +**1. Explicit (Der Mensch hat es gesagt)** +* *Quelle:* Inline-Links (`[[rel:...]]`) oder Wikilinks im Text. +* *Vertrauen:* **Hoch (1.0)**. +* *Bedeutung:* Dies ist hartes Faktenwissen. "Ich habe diesen Link bewusst gesetzt." + +**2. Smart (Die KI hat es bestätigt)** +* *Quelle:* Smart Edge Allocation (WP15). +* *Vertrauen:* **Mittel (0.9)**. +* *Bedeutung:* Ein LLM hat geprüft, ob der Link im Kontext dieses Textabschnitts wirklich relevant ist. Dies filtert "Rauschen" heraus (z.B. Links im Footer, die nichts mit dem Absatz zu tun haben). + +**3. Rule (Die Regel hat es vermutet)** +* *Quelle:* `types.yaml` Defaults. +* *Vertrauen:* **Niedrig (0.7)**. +* *Bedeutung:* Eine Heuristik. "Weil es ein Projekt ist, nehmen wir an, dass es von allen erwähnten Technologien abhängt." + +--- + +## 3. Matrix-Logik (Kontext-Sensitivität) + +Mit WP11 wurde eine Intelligenz eingeführt, die Kanten-Typen nicht nur anhand des Quell-Typs, sondern auch anhand des Ziel-Typs bestimmt ("Matrix"). + +**Logik-Beispiele:** + +* **Quelle `experience` → Ziel `value`** + * *Standard:* `references` + * *Matrix:* `based_on` (Erfahrungen basieren auf Werten). + +* **Quelle `principle` → Ziel `source` (Buch)** + * *Standard:* `references` + * *Matrix:* `derived_from` (Prinzipien stammen aus Quellen). + +* **Quelle `project` → Ziel `tool`** + * *Standard:* `references` + * *Matrix:* `uses` (Projekte nutzen Tools). + +*Nutzen:* Dies erlaubt im Chat präzise Fragen wie: *"Auf welchen Werten basiert diese Entscheidung?"* (Suche nach eingehenden `based_on` Kanten). + +--- + +## 4. Idempotenz & Konsistenz + +Das System garantiert fachliche Konsistenz auch bei mehrfachen Importen. +* **Stabile IDs:** Importiert man dieselbe Datei zweimal, ändern sich die IDs der Knoten nicht. +* **Keine Duplikate:** Kanten werden dedupliziert. Die "stärkere" Quelle (Explicit > Smart > Rule) gewinnt. +* **Lösch-Garantie:** Wenn eine Notiz gelöscht wird, verschwinden auch alle ihre Chunks und ausgehenden Kanten (via `--sync-deletes`). \ No newline at end of file diff --git a/docs/03_Technical_References/03_tech_chat_backend.md b/docs/03_Technical_References/03_tech_chat_backend.md new file mode 100644 index 0000000..c32f2d1 --- /dev/null +++ b/docs/03_Technical_References/03_tech_chat_backend.md @@ -0,0 +1,78 @@ +--- +doc_type: technical_reference +audience: developer, architect +scope: backend, chat, ollama, traffic_control +status: active +version: 2.6 +context: "Technische Implementierung des FastAPI-Routers, der Decision Engine und des Traffic Control Systems." +--- + +# Chat Backend & Traffic Control + +## 1. Hybrid Router (Decision Engine) + +Der zentrale Einstiegspunkt für jede Chatanfrage ist der **Hybrid Router** (`app/routers/chat.py`). Er entscheidet dynamisch, welche Strategie gewählt wird, basierend auf dem User-Input. + +### 1.1 Intent-Erkennung (Logik) + +Der Router prüft den Input in drei Stufen (Wasserfall-Prinzip): + +1. **Question Detection (Regelbasiert):** + * Prüfung auf Vorhandensein von `?` oder W-Wörtern (Wer, Wie, Was, Soll ich). + * Wenn positiv: **RAG Modus** (Interview wird blockiert). +2. **Keyword Scan (Fast Path):** + * Lädt `types.yaml` (Objekte, z.B. "Projekt") und `decision_engine.yaml` (Handlungen, z.B. "neu"). + * Wenn Match (z.B. "Projekt" + "neu"): **INTERVIEW Modus**. +3. **LLM Fallback (Slow Path):** + * Wenn unklar: Anfrage an LLM zur Klassifizierung. + +### 1.2 RAG Flow (Technisch) + +Wenn der Intent `FACT` oder `DECISION` ist, wird folgender Flow ausgeführt: + +1. **Pre-Processing:** Query Rewriting (optional). +2. **Context Enrichment:** + * Abruf via `retriever.py` (Hybrid Search). + * Injection von Metadaten (`[TYPE]`, `[SCORE]`) in den Prompt. +3. **Prompt Construction:** Assembly aus System-Prompt (Persona) + Context + Query. +4. **Streaming:** LLM-Antwort wird via **SSE (Server-Sent Events)** an den Client gestreamt. +5. **Post-Processing:** Anhängen des `Explanation` Layers (JSON-Breakdown) an das Ende des Streams. + +--- + +## 2. Traffic Control (WP-15) + +Das Traffic Control System (`app/core/llm_service.py`) schützt das System vor Überlastung, wenn rechenintensive Hintergrundprozesse (Smart Edge Import) und Latenz-kritische Chat-Anfragen gleichzeitig laufen. + +### 2.1 Prioritäts-Semaphor + +Jeder LLM-Request muss ein `priority`-Flag setzen. + +**Prioritäten-Levels:** + +| Priority | Verwendung | Limitierung | +| :--- | :--- | :--- | +| **realtime** | Chat-Anfragen | Keine (Hardware-Limit) | +| **background** | Smart Edge Allocation, Drafts | `MINDNET_LLM_BACKGROUND_LIMIT` | + +**Funktionsweise:** +* Hintergrund-Tasks nutzen `asyncio.Semaphore`. +* Wenn das Limit (Default: 2) erreicht ist, warten weitere Import-Tasks. +* Chat-Tasks umgehen die Semaphore und werden sofort bearbeitet. + +### 2.2 Timeout-Konfiguration + +Deadlocks werden durch strikte Timeouts verhindert, die in der `.env` definiert sind. + +* **Chat:** `MINDNET_LLM_TIMEOUT` (Default: 300s). +* **Frontend:** `MINDNET_API_TIMEOUT` (Default: 300s). + +--- + +## 3. Feedback Traceability + +Unterstützt das geplante Self-Tuning (WP08). + +1. **Query ID:** Generiert bei jedem `/query` Call eine `UUIDv4`. +2. **Logging:** Speichert einen Snapshot in `data/logs/query_snapshot.jsonl` (Input + Retrieved Context). +3. **Feedback:** Der `/feedback` Endpoint verknüpft das User-Rating (1-5) mit der `query_id`. \ No newline at end of file diff --git a/docs/03_Technical_References/03_tech_configuration.md b/docs/03_Technical_References/03_tech_configuration.md new file mode 100644 index 0000000..70d90bb --- /dev/null +++ b/docs/03_Technical_References/03_tech_configuration.md @@ -0,0 +1,132 @@ +--- +doc_type: technical_reference +audience: developer, admin +scope: configuration, env +status: active +version: 2.6 +context: "Referenztabellen für Umgebungsvariablen und YAML-Konfigurationen." +--- + +# Konfigurations-Referenz + +Dieses Dokument beschreibt die Steuerungsdateien von Mindnet. + +## 1. Environment Variablen (`.env`) + +Diese Variablen steuern die Infrastruktur, Timeouts und Feature-Flags. + +| Variable | Default | Beschreibung | +| :--- | :--- | :--- | +| `QDRANT_URL` | `http://localhost:6333` | URL zur Vektor-DB API. | +| `QDRANT_API_KEY` | *(leer)* | Optionaler Key für Absicherung. | +| `COLLECTION_PREFIX` | `mindnet` | Namensraum für Collections (erzeugt `{prefix}_notes` etc). | +| `VECTOR_DIM` | `768` | **Muss 768 sein** (für Nomic Embeddings). | +| `MINDNET_TYPES_FILE` | `config/types.yaml` | Pfad zur Typ-Registry. | +| `MINDNET_RETRIEVER_CONFIG`| `config/retriever.yaml`| Pfad zur Scoring-Konfiguration. | +| `MINDNET_DECISION_CONFIG` | `config/decision_engine.yaml` | Pfad zur Router & Intent Config. | +| `MINDNET_PROMPTS_PATH` | `config/prompts.yaml` | Pfad zu LLM Prompts. | +| `MINDNET_LLM_MODEL` | `phi3:mini` | Name des Chat-Modells (Ollama). | +| `MINDNET_EMBEDDING_MODEL` | `nomic-embed-text` | Name des Embedding-Modells (Ollama). | +| `MINDNET_OLLAMA_URL` | `http://127.0.0.1:11434`| URL zum LLM-Server. | +| `MINDNET_LLM_TIMEOUT` | `300.0` | Timeout in Sekunden (Erhöht für CPU Cold-Starts). | +| `MINDNET_API_TIMEOUT` | `300.0` | Frontend Timeout (Erhöht für Smart Edge Wartezeiten). | +| `MINDNET_LLM_BACKGROUND_LIMIT`| `2` | **Traffic Control:** Max. parallele Import-Tasks. | +| `MINDNET_VAULT_ROOT` | `./vault` | Pfad für Write-Back Operationen (Drafts). | +| `MINDNET_HASH_COMPARE` | `Body` | Import-Strategie: `Body`, `Frontmatter` oder `Full`. | +| `MINDNET_HASH_SOURCE` | `parsed` | Hash-Quelle: `parsed`, `raw` oder `file`. | + +--- + +## 2. Typ-Registry (`types.yaml`) + +Steuert das Import-Verhalten, Chunking und die Kanten-Logik pro Typ. + +**Referenztabelle (Stand v2.6):** + +| Typ (`type`) | Chunk Profile | Retriever Weight | Smart Edges? | Beschreibung | +| :--- | :--- | :--- | :--- | :--- | +| **concept** | `sliding_smart_edges` | 0.60 | Ja | Abstrakte Begriffe. | +| **project** | `sliding_smart_edges` | 0.97 | Ja | Aktive Vorhaben. | +| **decision** | `structured_smart_edges` | 1.00 | Ja | Entscheidungen (ADRs). | +| **experience** | `sliding_smart_edges` | 0.90 | Ja | Persönliche Learnings. | +| **journal** | `sliding_standard` | 0.80 | Nein | Logs / Dailies. | +| **value** | `structured_smart_edges` | 1.00 | Ja | Werte/Prinzipien. | +| **risk** | `sliding_short` | 0.90 | Nein | Risiken. | +| **person** | `sliding_standard` | 0.50 | Nein | Profile. | +| **source** | `sliding_standard` | 0.50 | Nein | Externe Quellen. | +| **event** | `sliding_standard` | 0.60 | Nein | Meetings. | +| **goal** | `sliding_standard` | 0.95 | Nein | Strategische Ziele. | +| **belief** | `sliding_short` | 0.90 | Nein | Glaubenssätze. | +| **default** | `sliding_standard` | 1.00 | Nein | Fallback. | + +*Hinweis: `Smart Edges?` entspricht dem YAML-Key `enable_smart_edge_allocation: true`.* + +--- + +## 3. Retriever Config (`retriever.yaml`) + +Steuert die Gewichtung der Scoring-Formel (WP04a). + +**Beispielkonfiguration:** + +```yaml +scoring: + semantic_weight: 1.0 # Basis-Relevanz (Cosine Similarity) + edge_weight: 0.7 # Einfluss des Graphen (Bonus) + centrality_weight: 0.5 # Einfluss von Hubs + +edge_weights: + # Multiplikatoren für den Edge-Bonus + depends_on: 1.5 # Harte Abhängigkeiten stark gewichten + blocks: 1.5 # Risiken stark gewichten + caused_by: 1.2 # Kausalitäten stärken + related_to: 0.5 # Weiche Themen schwächer gewichten + references: 0.8 # Standard-Referenzen + based_on: 1.3 # Werte-Bezug +``` + +--- + +## 4. Edge Typen Referenz + +Definiert die Semantik der `kind`-Felder in der Edge-Collection. + +| Kind | Symmetrisch? | Herkunft (Primär) | Bedeutung | +| :--- | :--- | :--- | :--- | +| `references` | Nein | Wikilink | Standard-Verweis. "Erwähnt X". | +| `belongs_to` | Nein | Struktur | Chunk gehört zu Note. | +| `next` / `prev` | Ja | Struktur | Lesereihenfolge. | +| `depends_on` | Nein | Inline / Default | Harte Abhängigkeit. | +| `related_to` | Ja | Callout / Default | Thematische Nähe. | +| `similar_to` | Ja | Inline | Inhaltliche Ähnlichkeit. | +| `caused_by` | Nein | Inline | Kausalität. | +| `solves` | Nein | Inline | Lösung für ein Problem. | +| `blocks` | Nein | Inline | Blockade / Risiko. | +| `derived_from` | Nein | Matrix | Herkunft (z.B. Prinzip -> Buch). | +| `based_on` | Nein | Matrix | Fundament (z.B. Erfahrung -> Wert). | +| `uses` | Nein | Matrix | Nutzung (z.B. Projekt -> Tool). | + +--- + +## 5. Decision Engine (`decision_engine.yaml`) + +Steuert den Hybrid Router (WP06). Definiert, welche Keywords welche Strategie auslösen. + +**Beispielauszug:** + +```yaml +# Strategie-Definitionen +strategies: + DECISION: + description: "Hilfe bei Entscheidungen" + inject_types: ["value", "principle", "goal", "risk"] # Strategic Retrieval + llm_fallback_enabled: true + + INTERVIEW: + description: "Wissenserfassung" + trigger_keywords: ["erstellen", "neu", "anlegen", "festhalten"] + + EMPATHY: + description: "Emotionaler Support" + inject_types: ["experience", "belief"] +``` \ No newline at end of file diff --git a/docs/03_Technical_References/03_tech_data_model.md b/docs/03_Technical_References/03_tech_data_model.md new file mode 100644 index 0000000..961123c --- /dev/null +++ b/docs/03_Technical_References/03_tech_data_model.md @@ -0,0 +1,114 @@ +--- +doc_type: technical_reference +audience: developer, architect +scope: database, qdrant, schema +status: active +version: 2.6 +context: "Exakte Definition der Datenmodelle (Payloads) in Qdrant und Index-Anforderungen." +--- + +# Technisches Datenmodell (Qdrant Schema) + +## 1. Collections & Namenskonvention + +Mindnet speichert Daten in drei getrennten Qdrant-Collections. Der Prefix ist via ENV `COLLECTION_PREFIX` konfigurierbar (Default: `mindnet`). + +Das System nutzt folgende drei Collections: +* `{prefix}_notes`: Metadaten der Dateien. +* `{prefix}_chunks`: Vektorisierte Textsegmente. +* `{prefix}_edges`: Gerichtete Graph-Kanten. + +--- + +## 2. Note Payload (`mindnet_notes`) + +Repräsentiert die Metadaten einer Markdown-Datei (1:1 Beziehung). + +**JSON-Schema:** + +```json +{ + "note_id": "string (keyword)", // UUIDv5 (deterministisch) oder Slug + "title": "string (text)", // Titel aus Frontmatter + "type": "string (keyword)", // Logischer Typ (z.B. 'project', 'concept') + "retriever_weight": "float", // Numerische Wichtigkeit (0.0-1.0), aus types.yaml + "chunk_profile": "string", // Genutztes Profil (z.B. 'sliding_smart_edges') + "edge_defaults": ["string"], // Liste der aktiven Default-Kanten + "tags": ["string"], // Liste von Tags aus Frontmatter + "created": "string (iso-date)", // Erstellungsdatum + "updated": "integer", // Timestamp (File Modification Time) + "fulltext": "string (no-index)" // Gesamter Text (nur für Recovery/Export) +} +``` + +**Erforderliche Indizes:** +Es müssen Payload-Indizes für folgende Felder existieren: +* `note_id` +* `type` +* `tags` + +--- + +## 3. Chunk Payload (`mindnet_chunks`) + +Die atomare Sucheinheit. Enthält den Vektor. + +**Vektor-Konfiguration:** +* Modell: `nomic-embed-text` +* Dimension: **768** +* Metrik: Cosine Similarity + +**JSON-Schema:** + +```json +{ + "chunk_id": "string (keyword)", // Format: {note_id}#c{index} (z.B. 'abc-123#c01') + "note_id": "string (keyword)", // Foreign Key zur Note + "type": "string (keyword)", // Kopie aus Note (Denormalisiert für Filterung) + "text": "string (text)", // Reintext für Anzeige (ohne Overlap) + "window": "string (text)", // Text + Overlap (Basis für Embedding) + "ord": "integer", // Laufende Nummer (1..N) für Sortierung + "retriever_weight": "float", // Kopie aus Note (für Query-Speed) + "chunk_profile": "string", // Vererbt von Note + "neighbors_prev": ["string"], // ID des Vorgängers (Linked List) + "neighbors_next": ["string"] // ID des Nachfolgers +} +``` + +**Erforderliche Indizes:** +Es müssen Payload-Indizes für folgende Felder existieren: +* `note_id` +* `chunk_id` +* `type` + +--- + +## 4. Edge Payload (`mindnet_edges`) + +Gerichtete Kanten zwischen Knoten. Stark erweitert in v2.6 für Provenienz-Tracking. + +**JSON-Schema:** + +```json +{ + "edge_id": "string (keyword)", // Deterministischer Hash aus (src, dst, kind) + "source_id": "string (keyword)", // Chunk-ID (Start) + "target_id": "string (keyword)", // Chunk-ID oder Note-Titel (bei Unresolved) + "kind": "string (keyword)", // Beziehungsart (z.B. 'depends_on') + "scope": "string (keyword)", // Immer 'chunk' (Legacy-Support: 'note') + "note_id": "string (keyword)", // Owner Note ID (Ursprung der Kante) + + // Provenance & Quality (WP03/WP15) + "provenance": "keyword", // 'explicit', 'rule', 'smart' (NEU) + "rule_id": "string (keyword)", // Traceability: 'inline:rel', 'explicit:wikilink', 'smart:llm' + "confidence": "float" // Vertrauenswürdigkeit (0.0 - 1.0) +} +``` + +**Erforderliche Indizes:** +Es müssen Payload-Indizes für folgende Felder existieren: +* `source_id` +* `target_id` +* `kind` +* `scope` +* `note_id` \ No newline at end of file diff --git a/docs/03_Technical_References/03_tech_ingestion_pipeline.md b/docs/03_Technical_References/03_tech_ingestion_pipeline.md new file mode 100644 index 0000000..03e8fb2 --- /dev/null +++ b/docs/03_Technical_References/03_tech_ingestion_pipeline.md @@ -0,0 +1,122 @@ +--- +doc_type: technical_reference +audience: developer, devops +scope: backend, ingestion, smart_edges +status: active +version: 2.6 +context: "Detaillierte technische Beschreibung der Import-Pipeline, Quality Gates und CLI-Befehle." +--- + +# Ingestion Pipeline & Smart Processing + +**Quellen:** `pipeline_playbook.md`, `Handbuch.md` + +Die Ingestion transformiert Markdown in den Graphen. Entrypoint: `scripts/import_markdown.py`. + +## 1. Der Import-Prozess (13-Schritte-Workflow) + +Der Prozess ist **asynchron** und **idempotent**. + +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`. +4. **Note-Payload generieren:** Erstellen des JSON-Objekts für `mindnet_notes`. +5. **Chunking anwenden:** Zerlegung des Textes basierend auf dem `chunk_profile` (siehe unten). +6. **Smart Edge Allocation (WP15):** + * Wenn `enable_smart_edge_allocation: true`: Der `SemanticAnalyzer` sendet Chunks an das LLM. + * **Traffic Control:** Request nutzt `priority="background"`. Semaphore (Limit: 2) drosselt die Last. + * **Resilienz:** Bei Timeout (Ollama) greift ein Fallback (Broadcasting an alle Chunks). +7. **Inline-Kanten finden:** Parsing von `[[rel:...]]`. +8. **Callout-Kanten finden:** Parsing von `> [!edge]`. +9. **Default-Edges erzeugen:** Anwendung der `edge_defaults` aus Registry. +10. **Strukturkanten erzeugen:** `belongs_to`, `next`, `prev`. +11. **Embedding (Async):** Generierung via `nomic-embed-text` (768d). +12. **Strict Mode:** Abbruch bei leeren Embeddings oder Dimension 0. +13. **Diagnose:** Integritäts-Check nach dem Lauf. + +--- + +## 2. Betrieb & CLI Befehle + +### 2.1 Standard-Betrieb (Inkrementell) +Für regelmäßige Updates (Cronjob). Erkennt Änderungen via Hash. + +```bash +export QDRANT_URL="http://localhost:6333" +export COLLECTION_PREFIX="mindnet" + +# 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 +``` + +> **[!WARNING] Purge-Before-Upsert** +> Das Flag `--purge-before-upsert` ist kritisch. Es löscht vor dem Schreiben einer Note ihre alten Chunks/Edges. Ohne dieses Flag entstehen **"Geister-Chunks"** (alte Textabschnitte, die im Markdown gelöscht wurden, aber im Index verbleiben). + +### 2.2 Full Rebuild (Clean Slate) +Notwendig bei Änderungen an `types.yaml` oder Modell-Wechsel. + +```bash +# 0. Modell sicherstellen +ollama pull nomic-embed-text + +# 1. Qdrant Collections löschen (Wipe) +python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet" --yes + +# 2. Vollständiger Import (Force) +python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force +``` + +--- + +## 3. Chunking & Payload + +Das Chunking ist profilbasiert. + +| Profil | Max Token | Overlap | Einsatz | +| :--- | :--- | :--- | :--- | +| `sliding_short` | 128 | 20 | Logs, Chats. | +| `sliding_standard` | 512 | 50 | Massendaten. | +| `sliding_smart_edges`| 512 | 50 | Wichtige Inhalte (Experience, Project). | +| `structured_smart` | n/a | n/a | Trennt strikt an Headings (für ADRs). | + +**Payload-Felder:** +* `text`: Der reine Inhalt (Anzeige). +* `window`: Inhalt plus Overlap (für Embedding). + +--- + +## 4. Edge-Erzeugung & Prioritäten + +Kanten werden nach Vertrauenswürdigkeit (`provenance`) priorisiert. Die höhere Prio gewinnt. + +| Prio | Quelle | Rule ID | Confidence | +| :--- | :--- | :--- | :--- | +| **1** | Inline | `inline:rel` | 0.95 | +| **2** | Callout | `callout:edge` | 0.90 | +| **3** | Wikilink | `explicit:wikilink` | 1.00 | +| **4** | Smart Edge | `smart:llm_filter` | 0.90 | +| **5** | Type Default | `edge_defaults` | 0.70 | +| **6** | Struktur | `structure` | 1.00 | + +--- + +## 5. Quality Gates & Tests + +Diese Tests garantieren die Stabilität der Pipeline. + +**1. Payload Dryrun (Schema-Check):** +Simuliert Import, prüft JSON-Schema Konformität. +```bash +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). +```bash +python3 -m scripts.edges_full_check +``` \ No newline at end of file diff --git a/docs/03_Technical_References/03_tech_retrieval_scoring.md b/docs/03_Technical_References/03_tech_retrieval_scoring.md new file mode 100644 index 0000000..fee2eba --- /dev/null +++ b/docs/03_Technical_References/03_tech_retrieval_scoring.md @@ -0,0 +1,113 @@ +--- +doc_type: technical_reference +audience: developer, data_scientist +scope: backend, retrieval, scoring +status: active +version: 2.6 +context: "Formeln und Algorithmen des Hybrid Retrievers und Explanation Layer." +--- + +# Retrieval & Scoring Algorithmen + +Der Retriever (`app/core/retriever.py`) unterstützt **Semantic Search** und **Hybrid Search**. Seit v2.4 (WP04a) nutzt Mindnet ein gewichtetes Scoring-Modell, das Semantik, Graphentheorie und Metadaten kombiniert. + +## 1. Scoring Formel (WP04a) + +Der Gesamtscore eines Treffers berechnet sich als gewichtete Summe. Alle Gewichte ($W$) sind in `retriever.yaml` konfigurierbar. + +$$ +TotalScore = (W_{sem} \cdot S_{sem} \cdot \max(W_{type}, 0)) + (W_{edge} \cdot B_{edge}) + (W_{cent} \cdot B_{cent}) +$$ + +### Die Komponenten + +**1. Semantic Score ($S_{sem}$):** +* **Basis:** Cosine Similarity des Vektors. +* **Modell:** `nomic-embed-text` (768d). +* **Wertebereich:** 0.0 bis 1.0. + +**2. Type Weight ($W_{type}$):** +* **Herkunft:** Feld `retriever_weight` aus der Note/Chunk Payload. +* **Zweck:** Priorisierung bestimmter Dokumententypen unabhängig vom Inhalt. +* **Beispiel:** Eine `decision` (Gewicht 1.0) schlägt ein `concept` (Gewicht 0.6) bei gleicher textueller Ähnlichkeit. + +**3. Edge Bonus ($B_{edge}$):** +* **Kontext:** Berechnet im lokalen Subgraphen (Expansion Tiefe 1). +* **Logik:** Summe der `confidence` aller eingehenden Kanten, die von Knoten stammen, die *ebenfalls* im aktuellen Result-Set (oder dem übergebenen Kontext) enthalten sind. +* **Zweck:** Belohnt Chunks, die "im Thema" vernetzt sind. + +**4. Centrality Bonus ($B_{cent}$):** +* **Kontext:** Berechnet im lokalen Subgraphen. +* **Logik:** Eine vereinfachte PageRank-Metrik (Degree Centrality) im temporären Graphen. +* **Zweck:** Belohnt "Hubs", die viele Verbindungen zu anderen Treffern haben. + +--- + +## 2. Hybrid Retrieval Flow + +Der Hybrid-Modus ist der Standard für den Chat (`/chat`). Er läuft in drei Phasen ab: + +**Phase 1: Vector Search (Seed Generation)** +* Suche die Top-K (z.B. 20) Kandidaten via Embeddings in Qdrant. +* Dies sind die "Seeds" für den Graphen. + +**Phase 2: Graph Expansion** +* Nutze `graph_adapter.expand(seeds, depth=1)`. +* Lade alle direkten Nachbarn (Incoming & Outgoing) der Seeds aus der `_edges` Collection. +* Konstruiere einen temporären `NetworkX`-Graphen im Speicher (`Subgraph`). + +**Phase 3: Re-Ranking** +* Berechne für jeden Knoten im Subgraphen die Boni ($B_{edge}$, $B_{cent}$). +* Wende die Scoring-Formel an. +* Sortiere die Liste neu absteigend nach `TotalScore`. +* Schneide die Liste beim finalen Limit (z.B. 5) ab. + +--- + +## 3. Explanation Layer (WP04b) + +Wenn der Parameter `explain=True` an die API übergeben wird, generiert der Retriever ein `Explanation` Objekt für jeden Treffer. + +**JSON-Struktur der Erklärung:** + +```json +{ + "score_breakdown": { + "semantic": 0.85, + "type_boost": 1.0, + "edge_bonus": 0.4, + "centrality": 0.1 + }, + "reasons": [ + "Hohe textuelle Übereinstimmung (>0.85).", + "Bevorzugt, da Typ 'decision' (Gewicht 1.0).", + "Wird referenziert von 'Projekt Alpha' via 'depends_on'." + ] +} +``` + +**Logik der Text-Generierung:** +* **Semantik:** Wenn $S_{sem} > 0.8$: "Hohe Übereinstimmung". +* **Typ:** Wenn $W_{type} > 0.8$: "Bevorzugt, da Typ X". +* **Graph:** Listet bis zu 3 eingehende Kanten mit hoher Konfidenz auf ("Wird referenziert von..."). + +--- + +## 4. Konfiguration (`retriever.yaml`) + +Diese Datei steuert die Balance der Formel. + +```yaml +scoring: + semantic_weight: 1.0 # Basis-Relevanz (sollte immer ca. 1.0 sein) + edge_weight: 0.7 # Einfluss des Graphen (0.5 - 1.0 empfohlen) + centrality_weight: 0.5 # Einfluss der Zentralität (Hub-Bonus) + +# Kanten-spezifische Gewichtung für den Edge-Bonus +edge_weights: + depends_on: 1.5 # Harte Abhängigkeiten sehr stark gewichten + blocks: 1.5 # Risiken/Blocker stark gewichten + caused_by: 1.2 # Kausalitäten moderat stärken + related_to: 0.5 # Weiche Themen schwächer gewichten + references: 0.8 # Standard-Referenzen +``` \ No newline at end of file diff --git a/docs/04_Operations/04_admin_operations.md b/docs/04_Operations/04_admin_operations.md new file mode 100644 index 0000000..438203f --- /dev/null +++ b/docs/04_Operations/04_admin_operations.md @@ -0,0 +1,148 @@ +--- +doc_type: operations_manual +audience: admin, devops +scope: deployment, maintenance, backup +status: active +version: 2.6 +context: "Installationsanleitung, Systemd-Units und Wartungsprozesse." +--- + +# Admin Operations Guide + +## 1. Installation & Setup + +### 1.1 Voraussetzungen +* **OS:** Ubuntu 22.04+ (empfohlen). +* **Tools:** Python 3.10+, Docker, Ollama. +* **Hardware:** Min. 8GB RAM, 4 CPU Cores (für Async Import). + +### 1.2 Qdrant (Docker) +Startet die Vektor-DB mit persistentem Storage auf Port 6333. + +```bash +docker run -d \ + --name mindnet_qdrant \ + --restart always \ + -p 6333:6333 \ + -v $(pwd)/qdrant_storage:/qdrant/storage \ + qdrant/qdrant +``` + +### 1.3 Ollama (Modelle) +**Wichtig:** Seit v2.4 ist `nomic-embed-text` Pflicht für Embeddings. + +```bash +# Modelle laden +ollama pull phi3:mini +ollama pull nomic-embed-text + +# Testen +curl http://localhost:11434/api/generate -d '{"model": "phi3:mini", "prompt":"Hi"}' +``` + +--- + +## 2. Deployment (Systemd Services) + +Wir unterscheiden strikt zwischen **Prod** (Port 8001/8501) und **Dev** (Port 8002/8502). + +### 2.1 Backend Service (`/etc/systemd/system/mindnet-prod.service`) + +```ini +[Unit] +Description=Mindnet API Prod (8001) +After=network.target + +[Service] +User=llmadmin +Group=llmadmin +WorkingDirectory=/home/llmadmin/mindnet +# Startet Uvicorn (Async Server) +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 +``` + +### 2.2 UI Service (`/etc/systemd/system/mindnet-ui-prod.service`) + +```ini +[Unit] +Description=Mindnet UI Prod (8501) +After=mindnet-prod.service + +[Service] +User=llmadmin +Group=llmadmin +WorkingDirectory=/home/llmadmin/mindnet + +# Environment für Streamlit Port & API-Ziel +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 +``` + +--- + +## 3. Wartung & Cronjobs + +### 3.1 Regelmäßiger Import (Cron) +Führt den Sync stündlich durch. Nutzt `--purge-before-upsert` für Sauberkeit. + +```bash +# Crontab Eintrag (user: llmadmin) +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 +``` + +### 3.2 Troubleshooting Guide + +**Fehler: "Vector dimension error: expected 768, got 384"** +* Ursache: Alte DB (v2.2), neues Modell (v2.4). +* Lösung: **Full Reset** (siehe Kap. 4.2). + +**Fehler: "500 Internal Server Error" (Ollama)** +* Ursache: Timeout bei Cold-Start des Modells. +* Lösung: `MINDNET_LLM_TIMEOUT=300.0` in `.env` setzen. + +**Fehler: Import sehr langsam** +* Ursache: Smart Edges sind aktiv und analysieren jeden Chunk. +* Lösung: `MINDNET_LLM_BACKGROUND_LIMIT` prüfen oder Feature in `types.yaml` deaktivieren. + +**Fehler: UI "Read timed out"** +* Ursache: Backend braucht für Smart Edges länger als 60s. +* Lösung: `MINDNET_API_TIMEOUT=300.0` setzen. + +--- + +## 4. Backup & Restore + +### 4.1 Qdrant Snapshot +Sichert den Vektor-Index. + +```bash +docker stop mindnet_qdrant +tar -czf qdrant_backup_$(date +%F).tar.gz ./qdrant_storage +docker start mindnet_qdrant +``` + +### 4.2 Notfall-Rebuild (Clean Slate) +Wenn alles inkonsistent ist oder Dimensionen sich ändern: + +```bash +# 1. DB löschen +python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet" --yes + +# 2. Neu importieren (Force Hash recalculation) +python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force +``` \ No newline at end of file diff --git a/docs/05_Development/05_developer_guide.md b/docs/05_Development/05_developer_guide.md new file mode 100644 index 0000000..56216f1 --- /dev/null +++ b/docs/05_Development/05_developer_guide.md @@ -0,0 +1,231 @@ +--- +doc_type: developer_guide +audience: developer +scope: workflow, testing, architecture, modules +status: active +version: 2.6 +context: "Umfassender Guide für Entwickler: Architektur, Modul-Interna, Setup, Git-Workflow und Erweiterungs-Anleitungen." +--- + +# Mindnet Developer Guide & Workflow + +**Quellen:** `developer_guide.md`, `dev_workflow.md` + +Dieser Guide vereint das technische Verständnis der Module mit dem operativen Workflow zwischen Windows (Dev) und Linux (Runtime). + +--- + +## 1. Die physische Architektur + +Mindnet läuft in einer verteilten Umgebung (Post-WP15 Setup). + +* **Windows 11 (VS Code):** Hier schreibst du Code. **Nie** direkt auf `main` arbeiten! +* **Raspberry Pi (Gitea):** Der "Safe". Speichert den Code und verwaltet Versionen. +* **Beelink (Runtime):** Der Server. Hier läuft die Software. Wir nutzen **Systemd-Services**: + * **PROD:** API (8001) + UI (8501). Ordner: `~/mindnet`. + * **DEV:** API (8002) + UI (8502). Ordner: `~/mindnet_dev`. + +--- + +## 2. Projektstruktur & Core-Module + +Der Code ist modular in `app` (Logik), `scripts` (CLI) und `config` (Steuerung) getrennt. + +### 2.1 Verzeichnisbaum +```text +mindnet/ +├── app/ +│ ├── core/ # Kernlogik +│ │ ├── ingestion.py # 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 +│ ├── routers/ # FastAPI Endpoints +│ │ ├── query.py # Suche +│ │ ├── 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# LLM-Filter für Edges (WP15) +│ │ ├── embeddings_client.py# Async Embeddings (HTTPX) +│ │ └── discovery.py # Intelligence Logic (WP11) +│ ├── frontend/ +│ │ └── ui.py # Streamlit App inkl. Healing Parser +│ └── main.py # Entrypoint der API +├── config/ # YAML-Konfigurationen (Single Source of Truth) +├── scripts/ # CLI-Tools (Import, Diagnose, Reset) +├── tests/ # Pytest Suite & Smoke Scripts +└── vault/ # Dein lokaler Markdown-Content +``` + +### 2.2 Modul-Details (Wie es funktioniert) + +**Der Importer (`scripts.import_markdown`)** +* Das komplexeste Modul. +* Nutzt `app.core.chunker` und `app.services.semantic_analyzer` (Smart Edges). +* **Idempotenz:** Nutzt deterministische UUIDv5 IDs. Kann beliebig oft laufen. +* **Robustheit:** Implementiert Change Detection (Hash) und Retry-Logik. + +**Der Hybrid Router (`app.routers.chat`)** +* Hier liegt die Logik für Intent Detection (WP06). +* **Question Detection:** Prüft auf `?` und W-Wörter. +* **Priority:** Ruft `llm_service` mit `priority="realtime"` auf (umgeht Import-Warteschlange). + +**Der Retriever (`app.core.retriever`)** +* Implementiert die Scoring-Formel (`Semantik + Graph + Typ`). +* **Hybrid Search:** Lädt dynamisch den Subgraphen (`graph_adapter.expand`). + +**Das Frontend (`app.frontend.ui`)** +* **Resurrection Pattern:** Nutzt `st.session_state`, um Eingaben bei Tab-Wechseln zu erhalten. +* **Healing Parser:** Die Funktion `parse_markdown_draft` repariert defekte YAML-Frontmatter vom LLM automatisch. + +**Traffic Control (`app.services.llm_service`)** +* Stellt sicher, dass der Chat responsive bleibt, auch wenn ein Import läuft. +* Nutzt `asyncio.Semaphore` (`MINDNET_LLM_BACKGROUND_LIMIT`), um Hintergrund-Jobs zu drosseln. + +--- + +## 3. Lokales Setup (Development) + +**Voraussetzungen:** Python 3.10+, Docker, Ollama. + +**Installation:** +```bash +# 1. Repo & Venv +git clone mindnet +cd mindnet +python3 -m venv .venv +source .venv/bin/activate + +# 2. Dependencies +pip install -r requirements.txt + +# 3. Ollama (Nomic ist Pflicht!) +ollama pull phi3:mini +ollama pull nomic-embed-text +``` + +**Konfiguration (.env):** +```ini +QDRANT_URL="http://localhost:6333" +COLLECTION_PREFIX="mindnet_dev" +VECTOR_DIM=768 +MINDNET_LLM_BACKGROUND_LIMIT=2 +MINDNET_API_URL="http://localhost:8002" +MINDNET_LLM_TIMEOUT=300.0 +``` + +--- + +## 4. Der Entwicklungs-Zyklus + +### Phase 1: Windows (Code) +1. **Basis holen:** `git checkout main && git pull`. +2. **Branch:** `git checkout -b feature/mein-feature`. +3. **Code & Push:** `git push origin feature/mein-feature`. + +### Phase 2: Beelink (Test) +1. **SSH:** `ssh user@beelink`. +2. **Ordner:** `cd ~/mindnet_dev`. +3. **Checkout:** `git fetch && git checkout feature/mein-feature && git pull`. +4. **Dependencies:** `pip install -r requirements.txt`. +5. **Restart:** `sudo systemctl restart mindnet-dev`. +6. **Validierung (Smoke Tests):** + * **Last-Test:** Starte `python3 -m scripts.import_markdown ...` und chatte gleichzeitig im UI (Port 8502). + * **API Check:** `curl -X POST "http://localhost:8002/ingest/analyze" ...` + +### Phase 3: Release & Deploy +1. **Gitea:** Pull Request erstellen und mergen. +2. **Beelink (Prod):** + ```bash + cd ~/mindnet + git pull origin main + sudo systemctl restart mindnet-prod + ``` +3. **Cleanup:** Branch löschen. + +--- + +## 5. Erweiterungs-Guide: "Teach-the-AI" + +Mindnet lernt durch Konfiguration, nicht durch Training. + +### Workflow A: Neuen Typ implementieren (z. B. `type: risk`) +1. **Physik (`types.yaml`):** + ```yaml + risk: + retriever_weight: 0.90 + edge_defaults: ["blocks"] + detection_keywords: ["gefahr", "risiko"] + ``` +2. **Strategie (`decision_engine.yaml`):** + ```yaml + DECISION: + inject_types: ["value", "risk"] # Füge 'risk' hinzu + ``` +3. **Kognition (`prompts.yaml`):** (Optional) Passe den System-Prompt an, falls nötig. + +### Workflow B: Interview-Schema anpassen (WP07) +Wenn Mindnet neue Fragen stellen soll (z.B. "Budget" bei Projekten): +1. **Schema (`types.yaml`):** + ```yaml + project: + schema: + - "Titel" + - "Ziel" + - "Budget (Neu)" + ``` +2. **Kein Code nötig:** Der `One-Shot Extractor` liest dies dynamisch. + +--- + +## 6. Tests & Debugging + +**Unit Tests:** +```bash +pytest tests/test_retriever_basic.py +pytest tests/test_chunking.py +``` + +**Pipeline Tests:** +```bash +# JSON-Schema prüfen +python3 -m scripts.payload_dryrun --vault ./test_vault + +# Graph-Integrität prüfen +python3 -m scripts.edges_full_check +``` + +**E2E Smoke Tests:** +```bash +# Decision Engine +python tests/test_wp06_decision.py -p 8002 -e DECISION -q "Soll ich X tun?" + +# Feedback +python tests/test_feedback_smoke.py --url http://localhost:8002/query +``` + +--- + +## 7. Troubleshooting & One-Liners + +**DB komplett zurücksetzen (Vorsicht!):** +```bash +python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet_dev" --yes +``` + +**Einen einzelnen File inspizieren (Parser-Sicht):** +```bash +python3 tests/inspect_one_note.py --file ./vault/MeinFile.md +``` + +**Live-Logs sehen:** +```bash +journalctl -u mindnet-dev -f +journalctl -u mindnet-ui-dev -f +``` + +**"Read timed out" im Frontend:** +* Ursache: Smart Edges brauchen länger als 60s. +* Lösung: `MINDNET_API_TIMEOUT=300.0` in `.env`. \ No newline at end of file diff --git a/docs/06_Roadmap/06_active_roadmap.md b/docs/06_Roadmap/06_active_roadmap.md new file mode 100644 index 0000000..7fdf107 --- /dev/null +++ b/docs/06_Roadmap/06_active_roadmap.md @@ -0,0 +1,108 @@ +--- +doc_type: roadmap +audience: product_owner, developer +status: active +version: 2.6 +context: "Aktuelle Planung für kommende Features (ab WP16), Release-Strategie und Historie der abgeschlossenen WPs." +--- + +# Mindnet Active Roadmap + +**Aktueller Stand:** v2.6.0 (Post-WP15) +**Fokus:** Usability, Memory & Visualisierung. + +## 1. Programmstatus + +Wir haben Phase D (Interaktion) weitgehend abgeschlossen. Das System ist stabil, verfügt über Traffic Control und Smart Edges. Der Fokus verschiebt sich nun auf **Phase E (Maintenance & Scaling)** sowie die Vertiefung der KI-Fähigkeiten. + +| Phase | Fokus | Status | +| :--- | :--- | :--- | +| **Phase A** | Fundament & Import | ✅ Fertig | +| **Phase B** | Semantik & Graph | ✅ Fertig | +| **Phase C** | Persönlichkeit | ✅ Fertig | +| **Phase D** | Interaktion & Tools | 🟡 Abschlussphase | +| **Phase E** | Maintenance & Visualisierung | 🚀 Start | + +--- + +## 2. Historie: Abgeschlossene Workpackages + +Eine Übersicht der implementierten Features zum schnellen Auffinden von Funktionen. Details siehe `99_legacy_workpackages.md`. + +| WP | Titel | Ergebnis / Kern-Feature | +| :--- | :--- | :--- | +| **WP-01** | Knowledge Design | Definition von `types.yaml` und Note-Typen (Project, Concept, etc.). | +| **WP-02** | Chunking Strategy | Implementierung von Sliding-Window und Hash-basierter Änderungserkennung. | +| **WP-03** | Import-Pipeline | Asynchroner Importer, der Markdown in Qdrant (Notes/Edges) schreibt. | +| **WP-04a**| Retriever Scoring | Hybride Suche: `Score = Semantik + GraphBonus + TypGewicht`. | +| **WP-04b**| Explanation Layer | Transparenz: API liefert "Reasons" (Warum wurde das gefunden?). | +| **WP-04c**| Feedback Loop | Logging von User-Feedback (JSONL) als Basis für Learning. | +| **WP-05** | RAG-Chat | Integration von Ollama (`phi3`) und Context-Enrichment im Prompt. | +| **WP-06** | Decision Engine | Hybrid Router unterscheidet Frage (`RAG`) vs. Handlung (`Interview`). | +| **WP-07** | Interview-Assistent | One-Shot Extraction: Erzeugt Markdown-Drafts aus User-Input. | +| **WP-10** | Web UI | Streamlit-Frontend als Ersatz für das Terminal. | +| **WP-10a**| Draft Editor | GUI-Komponente zum Bearbeiten und Speichern generierter Notizen. | +| **WP-11** | Backend Intelligence | `nomic-embed-text` (768d) und Matrix-Logik für Kanten-Typisierung. | +| **WP-15** | Smart Edge Allocation | LLM-Filter für Kanten in Chunks + Traffic Control (Semaphore). | + +--- + +## 3. Offene Workpackages (Planung) + +Diese Features stehen als nächstes an. + +### WP-16 – Auto-Discovery & Enrichment +**Status:** 🟡 Geplant +**Ziel:** Automatisches Erkennen von fehlenden Kanten in "dummem" Text *vor* der Speicherung. +* **Problem:** Nutzer vergessen Wikilinks. +* **Lösung:** Ein "Enricher" scannt Text vor dem Import, findet Keywords (z.B. "Mindnet") und schlägt Links vor (`[[Mindnet]]`). +* **Abgrenzung:** Anders als *Active Intelligence* (WP11, UI-basiert) läuft dies im Backend (Importer). + +### WP-17 – Conversational Memory (Gedächtnis) +**Status:** 🟡 Geplant +**Ziel:** Echte Dialoge statt Request-Response. +* **Tech:** Erweiterung des `ChatRequest` DTO um `history`. +* **Logik:** Token-Management (Context Window Balancing zwischen RAG-Doks und Chat-Verlauf). +* **Nutzen:** Rückfragen ("Was meinst du damit?") werden möglich. + +### WP-18 – Graph Health & Maintenance +**Status:** 🟡 Geplant (Prio 2) +**Ziel:** Konsistenzprüfung ("Garbage Collection"). +* **Feature:** Cronjob `check_graph_integrity.py`. +* **Funktion:** Findet "Dangling Edges" (Links auf gelöschte Notizen) und repariert/löscht sie. + +### WP-19 – Graph Visualisierung & Explorer +**Status:** 🟡 Geplant (Prio 1) +**Ziel:** Vertrauen durch Transparenz. +* **UI:** Neuer Tab "🕸️ Graph" in Streamlit. +* **Tech:** `streamlit-agraph` oder `pyvis`. +* **Nutzen:** Visuelle Kontrolle der *Smart Edge Allocation* ("Hat das LLM die Kante wirklich hierhin gesetzt?"). + +### WP-20 – Cloud Hybrid Mode (Optional) +**Status:** ⚪ Optional +**Ziel:** "Turbo-Modus" für Massen-Imports. +* **Konzept:** Switch in `.env`, um statt Ollama (Lokal) auf Google Gemini (Cloud) umzuschalten, wenn Datenschutz-unkritische Daten verarbeitet werden. + +--- + +## 4. Abhängigkeiten & Release-Plan + +```mermaid +graph TD + WP15(Smart Edges) --> WP19(Visualisierung) + WP15 --> WP16(Auto-Discovery) + WP10(Chat UI) --> WP17(Memory) + WP03(Import) --> WP18(Health Check) +``` + +**Nächstes Release (v2.7):** +* Ziel: Visualisierung (WP19) + Conversational Memory (WP17). +* ETA: Q1 2026. + +--- + +## 5. Governance + +* **Versionierung:** Semantic Versioning via Gitea Tags. +* **Feature-Branches:** Jedes WP erhält einen Branch `feature/wpXX-name`. +* **Sync First:** Bevor ein neuer Branch erstellt wird, muss `main` gepullt werden. \ No newline at end of file diff --git a/docs/99_Archive/99_legacy_workpackages.md b/docs/99_Archive/99_legacy_workpackages.md new file mode 100644 index 0000000..86efb9f --- /dev/null +++ b/docs/99_Archive/99_legacy_workpackages.md @@ -0,0 +1,82 @@ +--- +doc_type: archive +audience: historian, architect +status: archived +context: "Archivierte Details zu abgeschlossenen Workpackages (WP01-WP15). Referenz für historische Design-Entscheidungen." +--- + +# Legacy Workpackages (Archiv) + +**Quellen:** `Programmplan_V2.2.md` + +**Status:** Abgeschlossen / Implementiert. +Dieses Dokument dient als Referenz für die Entstehungsgeschichte von Mindnet v2.6. + +## Phase A: Fundament (WP01-03) + +### WP-01 – Wissensdesign +* **Ziel:** Definition der Datenstruktur. +* **Ergebnis:** Entscheidung gegen komplexe Ontologien (RDF/OWL), für pragmatische Typen (`project`, `concept`). Definition der YAML-Frontmatter-Pflichtfelder. +* **Artefakt:** `01_knowledge_design.md`. + +### WP-02 – Chunking & Hash-Strategie +* **Ziel:** Texte suchbar machen und Änderungen erkennen. +* **Ergebnis:** Implementierung des `SlidingWindowChunker`. Einführung von UUIDv5 für deterministische IDs. +* **Learning:** Starre Chunking-Grenzen zerschneiden oft den Kontext. Daher Einführung von Overlap (50 Tokens). + +### WP-03 – Import-Pipeline & Edge-System +* **Ziel:** Markdown in Vektoren wandeln. +* **Ergebnis:** Der "Importer" (`import_markdown.py`). Entscheidung, Kanten (`_edges`) als eigene Collection zu führen statt als Payload in Chunks (für bessere Graphen-Algorithmen wie Centrality). + +--- + +## Phase B: Semantik (WP04) + +### WP-04a – Retriever & Graph-Scoring +* **Ziel:** Bessere Suchergebnisse als reines Vektor-Matching. +* **Ergebnis:** Die Formel `Score = Semantik + GraphBonus + TypGewicht`. +* **Learning:** Reine Vektorsuche reichte nicht, um den Kontext ("Warum ist das wichtig?") zu erfassen. Der "Graph Bonus" war der Durchbruch für assoziatives Finden. + +### WP-04b – Explanation Layer ("Why-Layer") +* **Ziel:** Transparenz. +* **Ergebnis:** `explain=True` Parameter. Die API liefert menschenlesbare Gründe ("Gefunden, weil Projekt Alpha davon abhängt"). + +### WP-04c – Feedback Logging +* **Ziel:** Datenbasis für zukünftiges Lernen schaffen. +* **Ergebnis:** Das "Data Flywheel". Jede Suche und Bewertung wird in JSONL-Dateien geloggt (`search_history.jsonl`, `feedback.jsonl`). + +--- + +## Phase C: Persönlichkeit (WP05-07) + +### WP-05 – RAG-Chat +* **Ziel:** Natürliche Sprache statt Suchergebnisse. +* **Ergebnis:** Integration von Ollama (`phi3`). +* **Tech:** Prompt-Engineering (`prompts.yaml`) statt Fine-Tuning, um flexibel zu bleiben. + +### WP-06 – Decision Engine +* **Ziel:** Strategische Beratung statt nur Fakten. +* **Ergebnis:** Der Hybrid Router. +* **Konzept:** Unterscheidung von *Fragen* (RAG) und *Handlungen* (Interview). Strategisches Laden von Werten (`type: value`), um Entscheidungen moralisch zu begründen. + +### WP-07 – Interview-Assistent +* **Ziel:** Bekämpfung des "Writer's Block". +* **Ergebnis:** One-Shot Extraction. Der Chatbot generiert aus einem losen Satz ("Neues Projekt Alpha") einen strukturierten Markdown-Draft. + +--- + +## Phase D: Interaktion (WP10-15) + +### WP-10/10a – Web UI & Draft Editor +* **Ziel:** Usability für Nicht-Techniker. +* **Ergebnis:** Streamlit App. Ablösung des Terminals. +* **Feature:** "Healing Parser", der defektes JSON vom LLM repariert. + +### WP-11 – Backend Intelligence +* **Ziel:** Automatisierung der Vernetzung. +* **Ergebnis:** AsyncIO Umstellung für Performance. Einführung von `nomic-embed-text` (768d) für präzise Semantik. Matrix-Logik für automatische Kanten-Typisierung. + +### WP-15 – Smart Edge Allocation (Meilenstein) +* **Problem:** "Broadcasting". Ein Chunk erbte alle Links der Note, auch irrelevante. Das verwässerte die Suchergebnisse. +* **Lösung:** LLM prüft jeden Chunk auf Link-Relevanz. +* **Tech:** Einführung von **Traffic Control** (Semaphore), um Import und Chat zu parallelisieren, ohne die Hardware zu überlasten. \ No newline at end of file diff --git a/Programmmanagement/Dokumentationsrahmenplan.md b/docs/99_Archive/alte_Versionen/Dokumentationsrahmenplan.md similarity index 100% rename from Programmmanagement/Dokumentationsrahmenplan.md rename to docs/99_Archive/alte_Versionen/Dokumentationsrahmenplan.md diff --git a/Programmmanagement/Programmplan_V2.2.md b/docs/99_Archive/alte_Versionen/Programmplan_V2.2.md similarity index 100% rename from Programmmanagement/Programmplan_V2.2.md rename to docs/99_Archive/alte_Versionen/Programmplan_V2.2.md diff --git a/docs/Knowledge_Design_Manual.md b/docs/99_Archive/alte_Versionen/V2.6.0/Knowledge_Design_Manual.md similarity index 100% rename from docs/Knowledge_Design_Manual.md rename to docs/99_Archive/alte_Versionen/V2.6.0/Knowledge_Design_Manual.md diff --git a/docs/Overview.md b/docs/99_Archive/alte_Versionen/V2.6.0/Overview.md similarity index 100% rename from docs/Overview.md rename to docs/99_Archive/alte_Versionen/V2.6.0/Overview.md diff --git a/docs/admin_guide.md b/docs/99_Archive/alte_Versionen/V2.6.0/admin_guide.md similarity index 100% rename from docs/admin_guide.md rename to docs/99_Archive/alte_Versionen/V2.6.0/admin_guide.md diff --git a/docs/appendix.md b/docs/99_Archive/alte_Versionen/V2.6.0/appendix.md similarity index 100% rename from docs/appendix.md rename to docs/99_Archive/alte_Versionen/V2.6.0/appendix.md diff --git a/docs/dev_workflow.md b/docs/99_Archive/alte_Versionen/V2.6.0/dev_workflow.md similarity index 100% rename from docs/dev_workflow.md rename to docs/99_Archive/alte_Versionen/V2.6.0/dev_workflow.md diff --git a/docs/developer_guide.md b/docs/99_Archive/alte_Versionen/V2.6.0/developer_guide.md similarity index 100% rename from docs/developer_guide.md rename to docs/99_Archive/alte_Versionen/V2.6.0/developer_guide.md diff --git a/docs/mindnet_functional_architecture.md b/docs/99_Archive/alte_Versionen/V2.6.0/mindnet_functional_architecture.md similarity index 100% rename from docs/mindnet_functional_architecture.md rename to docs/99_Archive/alte_Versionen/V2.6.0/mindnet_functional_architecture.md diff --git a/docs/mindnet_technical_architecture.md b/docs/99_Archive/alte_Versionen/V2.6.0/mindnet_technical_architecture.md similarity index 100% rename from docs/mindnet_technical_architecture.md rename to docs/99_Archive/alte_Versionen/V2.6.0/mindnet_technical_architecture.md diff --git a/docs/pipeline_playbook.md b/docs/99_Archive/alte_Versionen/V2.6.0/pipeline_playbook.md similarity index 100% rename from docs/pipeline_playbook.md rename to docs/99_Archive/alte_Versionen/V2.6.0/pipeline_playbook.md diff --git a/docs/user_guide.md b/docs/99_Archive/alte_Versionen/V2.6.0/user_guide.md similarity index 100% rename from docs/user_guide.md rename to docs/99_Archive/alte_Versionen/V2.6.0/user_guide.md diff --git a/docs/archiv/ARCHITECTURE_SNAPSHOT_v2.2.1.md b/docs/99_Archive/alte_Versionen/fragmente/ARCHITECTURE_SNAPSHOT_v2.2.1.md similarity index 100% rename from docs/archiv/ARCHITECTURE_SNAPSHOT_v2.2.1.md rename to docs/99_Archive/alte_Versionen/fragmente/ARCHITECTURE_SNAPSHOT_v2.2.1.md diff --git a/docs/archiv/CHANGELOG_TYPE_REGISTRY.md b/docs/99_Archive/alte_Versionen/fragmente/CHANGELOG_TYPE_REGISTRY.md similarity index 100% rename from docs/archiv/CHANGELOG_TYPE_REGISTRY.md rename to docs/99_Archive/alte_Versionen/fragmente/CHANGELOG_TYPE_REGISTRY.md diff --git a/docs/archiv/Handbuch.md b/docs/99_Archive/alte_Versionen/fragmente/Handbuch.md similarity index 100% rename from docs/archiv/Handbuch.md rename to docs/99_Archive/alte_Versionen/fragmente/Handbuch.md diff --git a/docs/archiv/TYPE_REGISTRY_MANUAL.md b/docs/99_Archive/alte_Versionen/fragmente/TYPE_REGISTRY_MANUAL.md similarity index 100% rename from docs/archiv/TYPE_REGISTRY_MANUAL.md rename to docs/99_Archive/alte_Versionen/fragmente/TYPE_REGISTRY_MANUAL.md diff --git a/docs/archiv/chunking_strategy.md b/docs/99_Archive/alte_Versionen/fragmente/chunking_strategy.md similarity index 100% rename from docs/archiv/chunking_strategy.md rename to docs/99_Archive/alte_Versionen/fragmente/chunking_strategy.md diff --git a/docs/archiv/docs_mindnet_retriever.md b/docs/99_Archive/alte_Versionen/fragmente/docs_mindnet_retriever.md similarity index 100% rename from docs/archiv/docs_mindnet_retriever.md rename to docs/99_Archive/alte_Versionen/fragmente/docs_mindnet_retriever.md diff --git a/docs/archiv/knowledge_design.md b/docs/99_Archive/alte_Versionen/fragmente/knowledge_design.md similarity index 100% rename from docs/archiv/knowledge_design.md rename to docs/99_Archive/alte_Versionen/fragmente/knowledge_design.md diff --git a/docs/archiv/mindnet_v2_implementation_playbook.md b/docs/99_Archive/alte_Versionen/fragmente/mindnet_v2_implementation_playbook.md similarity index 100% rename from docs/archiv/mindnet_v2_implementation_playbook.md rename to docs/99_Archive/alte_Versionen/fragmente/mindnet_v2_implementation_playbook.md diff --git a/docs/archiv/wp04_retriever_scoring.md b/docs/99_Archive/alte_Versionen/fragmente/wp04_retriever_scoring.md similarity index 100% rename from docs/archiv/wp04_retriever_scoring.md rename to docs/99_Archive/alte_Versionen/fragmente/wp04_retriever_scoring.md diff --git a/docs/archiv/Überarbeitungshinweise_WP03.md b/docs/99_Archive/alte_Versionen/fragmente/Überarbeitungshinweise_WP03.md similarity index 100% rename from docs/archiv/Überarbeitungshinweise_WP03.md rename to docs/99_Archive/alte_Versionen/fragmente/Überarbeitungshinweise_WP03.md diff --git a/docs/archiv/Überarbeitungshinweise_WP04.md b/docs/99_Archive/alte_Versionen/fragmente/Überarbeitungshinweise_WP04.md similarity index 100% rename from docs/archiv/Überarbeitungshinweise_WP04.md rename to docs/99_Archive/alte_Versionen/fragmente/Überarbeitungshinweise_WP04.md