diff --git a/Programmmanagement/Programmplan_V2.2.md b/Programmmanagement/Programmplan_V2.2.md index 91ee315..9b09f5f 100644 --- a/Programmmanagement/Programmplan_V2.2.md +++ b/Programmmanagement/Programmplan_V2.2.md @@ -1,10 +1,10 @@ -# mindnet v2.2 — Programmplan -**Version:** 2.4.0 (Inkl. WP-07 Interview & WP-10a Draft Editor) -**Stand:** 2025-12-10 +# mindnet v2.4 — Programmplan +**Version:** 2.4.0 (Inkl. WP-11 Backend Intelligence) +**Stand:** 2025-12-11 **Status:** Aktiv --- -- [mindnet v2.2 — Programmplan](#mindnet-v22--programmplan) +- [mindnet v2.4 — Programmplan](#mindnet-v24--programmplan) - [1. Programmauftrag](#1-programmauftrag) - [2. Vision](#2-vision) - [3. Programmziele](#3-programmziele) @@ -29,7 +29,7 @@ - [WP-09 – Vault-Onboarding \& Migration (geplant)](#wp-09--vault-onboarding--migration-geplant) - [WP-10 – Chat-Interface \& Writeback (abgeschlossen)](#wp-10--chat-interface--writeback-abgeschlossen) - [WP-10a – GUI Evolution: Draft Editor (abgeschlossen)](#wp-10a--gui-evolution-draft-editor-abgeschlossen) - - [WP-11 – Knowledge-Builder \& Vernetzungs-Assistent (geplant)](#wp-11--knowledge-builder--vernetzungs-assistent-geplant) + - [WP-11 – Backend Intelligence \& Persistence (abgeschlossen)](#wp-11--backend-intelligence--persistence-abgeschlossen) - [WP-12 – Knowledge Rewriter (Soft Mode, geplant)](#wp-12--knowledge-rewriter-soft-mode-geplant) - [WP-13 – MCP-Integration \& Agenten-Layer (geplant)](#wp-13--mcp-integration--agenten-layer-geplant) - [WP-14 – Review / Refactoring / Dokumentation (geplant)](#wp-14--review--refactoring--dokumentation-geplant) @@ -51,7 +51,8 @@ mindnet v2.4 entwickelt ein persönliches, wachsendes KI-Gedächtnis, das: - über mehrere Kanäle gefüttert wird: - Obsidian-Markdown (primäre Quelle), - Chat-basierter Agent (Decision Engine & RAG-Chat aktiv), - - **Interview-Assistent (One-Shot Extraction aktiv)**, + - Interview-Assistent (One-Shot Extraction aktiv), + - **Draft Editor (Active Intelligence aktiv)**, - automatisch neue Zusammenhänge erkennt und vernetzt (Edges, Typen, Hinweise), - sich durch Rückmeldungen (Feedback) selbst verbessert (Self-Tuning). @@ -116,7 +117,8 @@ Kernprinzipien der Vision: - **Multi-Persona:** System wechselt den Tonfall (Empathisch vs. Analytisch) situativ (WP-06 abgeschlossen). - **Chat Interface:** Web-basiertes Frontend (Streamlit) für einfache Interaktion und Feedback-Gabe (WP-10 abgeschlossen). - **Interview-Assistent (WP-07):** One-Shot Extraction von Notizen ("Neues Projekt anlegen") ist live. -- Technische Basis: FastAPI, Qdrant, Ollama (Local LLM), Streamlit. +- **Active Intelligence (WP-11):** Automatische Link-Vorschläge (Matrix-Logik) während des Schreibens. +- Technische Basis: FastAPI (Async), Qdrant (768 Dim), Ollama (Phi-3/Nomic), Streamlit. - Automatisierte Erkennung von Beziehungen: - Wikilinks, Inline-Relationen, Callout-Edges, Typ-Defaults. - „Mitwachsendes“ Schema ohne Obsidian-Umstrukturierungen: @@ -126,8 +128,7 @@ Kernprinzipien der Vision: ### 3.2 Mittelfristig (Nächste Schritte) - **Self-Tuning (WP-08):** Optimierung der Gewichte in `retriever.yaml` basierend auf dem gesammelten Feedback. -- **Knowledge-Builder (WP-11):** Assistent zur Analyse und Vernetzung manuell erstellter Notizen. -- Agenten können über MCP-Tools (`mindnet_query`, `mindnet_chat`) auf mindnet zugreifen. +- Agenten können über MCP-Tools (`mindnet_query`, `mindnet_chat`) auf mindnet zugreifen (WP-13). ### 3.3 Langfristig @@ -180,7 +181,7 @@ Die folgenden Prinzipien steuern alle Workpackages und Entscheidungen: - Jeder Importlauf, jede Retriever-Anfrage und jede Policy-Änderung soll prüfbar sein. 10. **Local First & Privacy** - - Nutzung lokaler LLMs (Ollama/Phi-3) für Inference. Keine Daten verlassen den Server. + - Nutzung lokaler LLMs (Ollama) für Inference. Keine Daten verlassen den Server. --- @@ -192,7 +193,7 @@ Die folgenden Prinzipien steuern alle Workpackages und Entscheidungen: Phase D – Agenten, MCP & Interaktion (Aktiv) Phase E – Review, Refactoring, Dokumentation -Alle Workpackages sind einer Phase zugeordnet. WP-01 bis WP-07 und WP-10/10a sind erfolgreich abgeschlossen. +Alle Workpackages sind einer Phase zugeordnet. WP-01 bis WP-07 und WP-10/10a/11 sind erfolgreich abgeschlossen. --- @@ -447,13 +448,20 @@ Anpassung der GUI an komplexe Interaktionsmuster, die durch den Interview-Assist --- -### WP-11 – Knowledge-Builder & Vernetzungs-Assistent (geplant) +### WP-11 – Backend Intelligence & Persistence (abgeschlossen) **Phase:** D -**Status:** 🟡 geplant +**Status:** 🟢 abgeschlossen **Ziel:** -Assistent, der manuell erstellte oder importierte Notizen analysiert und Vorschläge für Typen, Edges und Einordnung macht. +Ermöglichung von "Active Intelligence" durch asynchrone Verarbeitung und semantische Analyse im Hintergrund. + +**Erreichte Ergebnisse:** +- **Async Core:** Umstellung der Pipeline auf `asyncio` und `httpx` (Vermeidung von Blockaden). +- **Nomic Embeddings:** Integration von `nomic-embed-text` (768 Dim) für State-of-the-Art Semantik. +- **Matrix Logic:** Regelwerk für kontextsensitive Kanten (`experience` + `value` -> `based_on`). +- **Sliding Window:** Analyse langer Texte für Link-Vorschläge. +- **Persistence API:** Neuer Endpunkt `/ingest/save` für atomares Speichern & Indizieren. **Aufwand / Komplexität:** - Aufwand: Hoch @@ -557,7 +565,7 @@ Aufräumen, dokumentieren, stabilisieren – insbesondere für Onboarding Dritte | WP09 | 🟡 | | WP10 | 🟢 | | WP10a | 🟢 | -| WP11 | 🟡 | +| WP11 | 🟢 | | WP12 | 🟡 | | WP13 | 🟡 | | WP14 | 🟡 | @@ -585,7 +593,8 @@ mindnet v2.4 ist so aufgesetzt, dass: - ein **Self-Healing- und Self-Tuning-Mechanismus** vorbereitet ist (durch WP-04c Feedback-Daten), - ein **Persönlichkeitsmodell** (Decision Engine, Empathie) existiert und den Tonfall situativ anpasst, - eine **grafische Oberfläche** (WP-10/10a) existiert, die komplexe Zusammenhänge visualisiert und Co-Creation ermöglicht, +- **Active Intelligence** (WP-11) dich beim Schreiben unterstützt, indem es automatisch Verknüpfungen vorschlägt, - langfristig ein **KI-Zwilling** aufgebaut wird, der deine Werte, Erfahrungen und Denkweise spiegelt, -- die technische Architektur (FastAPI, Qdrant, YAML-Policies, MCP-Integration) lokal, nachvollziehbar und erweiterbar bleibt. +- die technische Architektur (AsyncIO, Qdrant 768d, YAML-Policies) lokal, nachvollziehbar und performant bleibt. Dieser Programmplan bildet die konsolidierte Grundlage (v2.4.0) für alle weiteren Arbeiten. \ No newline at end of file diff --git a/docs/Knowledge_Design_Manual.md b/docs/Knowledge_Design_Manual.md index 95de77e..e5d2a44 100644 --- a/docs/Knowledge_Design_Manual.md +++ b/docs/Knowledge_Design_Manual.md @@ -1,7 +1,7 @@ # mindnet v2.4 – Knowledge Design Manual **Datei:** `docs/mindnet_knowledge_design_manual_v2.4.md` -**Stand:** 2025-12-10 -**Status:** **FINAL** (Integrierter Stand WP01–WP10a) +**Stand:** 2025-12-11 +**Status:** **FINAL** (Integrierter Stand WP01–WP11) **Quellen:** `knowledge_design.md`, `TYPE_REGISTRY_MANUAL.md`, `chunking_strategy.md`, `mindnet_functional_architecture.md`. --- @@ -24,11 +24,11 @@ Dieses Handbuch ist die **primäre Arbeitsanweisung** für dich als Mindmaster ( ### 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.3.1 verfügt Mindnet über: +Seit Version 2.4 verfügt Mindnet über: * **Hybrid Router:** Das System erkennt, ob du Fakten, Entscheidungen oder Empathie brauchst. * **Context Intelligence:** Das System lädt je nach Situation unterschiedliche Notiz-Typen (z.B. Werte bei Entscheidungen). * **Web UI (WP10):** Du kannst direkt sehen, welche Quellen genutzt wurden. -* **Interview Modus (WP07):** Du kannst Notizen direkt im Chat entwerfen lassen. +* **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**. @@ -59,7 +59,7 @@ Jede Datei muss mindestens folgende Felder enthalten, um korrekt verarbeitet zu Diese Felder sind technisch nicht zwingend, aber für bestimmte Typen sinnvoll: lang: de # Sprache (Default: de) - aliases: [Alpha Projekt, Project A] # Synonyme für die Suche + 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. @@ -86,17 +86,17 @@ Der `type` ist der wichtigste Hebel im Knowledge Design. Er steuert nicht nur da 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) | -| :--- | :--- | :--- | :--- | -| **`concept`** | Fachbegriffe, Theorien. Zeitloses Wissen. | **FACT** | Titel, Definition, Tags | -| **`project`** | Ein Vorhaben mit Ziel, Dauer und Aufgaben. | **FACT / DECISION** | Ziel, Status, Stakeholder, Steps | -| **`experience`** | Persönliche Erfahrung, Lektion oder Erkenntnis. | **EMPATHY** | Situation, Erkenntnis, Emotionen | -| **`decision`** | Eine bewusst getroffene Entscheidung (ADR). | **DECISION** | Kontext, Entscheidung, Alternativen | -| **`value`** | Ein persönlicher Wert oder ein Prinzip. | **DECISION** | Definition, Anti-Beispiel | -| **`goal`** | Ein strategisches Ziel (kurz- oder langfristig). | **DECISION** | Zeitrahmen, KPIs, Werte | -| **`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 | +| 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` | +| **`decision`** | Eine bewusst getroffene Entscheidung (ADR). | **DECISION** | Kontext, Entscheidung, Alternativen | Quelle für `depends_on` | +| **`value`** | Ein persönlicher Wert oder ein Prinzip. | **DECISION** | Definition, Anti-Beispiel | Ziel für `based_on` | +| **`goal`** | Ein strategisches Ziel (kurz- oder langfristig). | **DECISION** | Zeitrahmen, KPIs, Werte | Ziel für `related_to` | +| **`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` @@ -139,6 +139,7 @@ Dies ist die **mächtigste** Methode. Du sagst dem System explizit, **wie** Ding * `related_to`: Hat zu tun mit (allgemein). * `caused_by`: Wurde verursacht durch. * `solves`: Löst (Problem). + * **Neu (v2.4):** `based_on`, `uses`, `derived_from` (werden oft automatisch vorgeschlagen). ### 4.3 Callout-Edges (Kuratierte Listen) Für Zusammenfassungen oder "Siehe auch"-Blöcke am Ende einer Notiz. diff --git a/docs/Overview.md b/docs/Overview.md index d8aacdc..b7cc8f0 100644 --- a/docs/Overview.md +++ b/docs/Overview.md @@ -1,7 +1,7 @@ # Mindnet v2.4 – Overview & Einstieg **Datei:** `docs/mindnet_overview_v2.4.md` -**Stand:** 2025-12-10 -**Status:** **FINAL** (Inkl. Interview-Assistent & Web-Editor) +**Stand:** 2025-12-11 +**Status:** **FINAL** (Inkl. Async Intelligence & Editor) **Version:** 2.4.0 --- @@ -13,6 +13,7 @@ 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 @@ -27,14 +28,14 @@ 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:** Import-Pipeline, Chunking, Vektor-Datenbank (Qdrant). -* **Status:** 🟢 Live (WP01–WP03). +* **Technik:** Async Import-Pipeline, Chunking, Vektor-Datenbank (Qdrant). +* **Status:** 🟢 Live (WP01–WP03, WP11). ### 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 + Vektor), Explanation Engine. -* **Status:** 🟢 Live (WP04). +* **Technik:** Hybrider Retriever (Graph + Nomic Embeddings), Explanation Engine. +* **Status:** 🟢 Live (WP04, WP11). ### Ebene 3: Identität & Interaktion (Die Persönlichkeit) * **Funktion:** Interaktion, Bewertung und Co-Creation. @@ -45,6 +46,7 @@ Mindnet arbeitet auf drei Schichten, die aufeinander aufbauen: * **Intent Router:** Erkennt Absichten (Fakt vs. Gefühl vs. Entscheidung vs. Interview). * **Strategic Retrieval:** Lädt gezielt Werte oder Erfahrungen nach. * **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). --- @@ -54,18 +56,19 @@ Mindnet arbeitet auf drei Schichten, die aufeinander aufbauen: 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. **Ingest:** Ein Python-Skript importiert, zerlegt (Chunking) und vernetzt (Edges) die Daten in Qdrant. -3. **Intent Recognition:** Der Router analysiert deine Frage: Willst du Fakten, Code, Empathie oder etwas dokumentieren? -4. **Retrieval / Action:** +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, zerlegt (Chunking) und vernetzt (Edges) die Daten in Qdrant. +4. **Intent Recognition:** Der Router analysiert deine Frage: Willst du Fakten, Code, Empathie oder etwas dokumentieren? +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). -5. **Generation:** Ein lokales LLM (Ollama) formuliert die Antwort oder den Markdown-Draft. -6. **Feedback:** Du bewertest die Antwort. Das System lernt (langfristig) daraus. +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. -* **Datenbank:** Qdrant (Vektor & Graph). -* **KI:** Ollama (Phi-3 Mini) – 100% lokal. +* **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. * **Frontend:** Streamlit Web-UI (v2.4). --- @@ -96,5 +99,5 @@ Wo findest du was? ## 6. Aktueller Fokus -Wir haben den **Interview-Assistenten (WP07)** und den **Draft-Editor (WP10a)** erfolgreich integriert. -Das System kann nun aktiv helfen, Wissen zu strukturieren, anstatt es nur abzurufen. Der Fokus verschiebt sich nun in Richtung **Self-Tuning (WP08)**, um aus dem gesammelten Feedback automatisch zu lernen. \ No newline at end of file +Wir haben den **Interview-Assistenten (WP07)** und die **Backend Intelligence (WP11)** erfolgreich integriert. +Das System kann nun aktiv helfen, Wissen zu strukturieren und zu vernetzen. Der Fokus verschiebt sich nun in Richtung **Self-Tuning (WP08)**, um aus dem gesammelten Feedback automatisch zu lernen. \ No newline at end of file diff --git a/docs/admin_guide.md b/docs/admin_guide.md index c9bafe8..ef87828 100644 --- a/docs/admin_guide.md +++ b/docs/admin_guide.md @@ -1,7 +1,7 @@ # Mindnet v2.4 – Admin Guide **Datei:** `docs/mindnet_admin_guide_v2.4.md` -**Stand:** 2025-12-10 -**Status:** **FINAL** (Inkl. Frontend Deployment & Interview Config) +**Stand:** 2025-12-11 +**Status:** **FINAL** (Inkl. Async Architecture & Nomic Model) **Quellen:** `Handbuch.md`, `mindnet_developer_guide_v2.4.md`. > Dieses Handbuch richtet sich an **Administratoren**. Es beschreibt Installation, Konfiguration, Backup-Strategien, Monitoring und den sicheren Betrieb der Mindnet-Instanz (API + UI + DB). @@ -23,7 +23,7 @@ Wir unterscheiden strikt zwischen: * **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 Import & Inference). + * 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. @@ -37,11 +37,11 @@ Wir unterscheiden strikt zwischen: python3 -m venv .venv source .venv/bin/activate - # 3. Dependencies installieren (inkl. Streamlit) + # 3. Dependencies installieren (inkl. Streamlit, HTTPX) pip install -r requirements.txt # 4. Verzeichnisse anlegen - mkdir -p logs qdrant_storage data/logs + mkdir -p logs qdrant_storage data/logs vault ### 2.3 Qdrant Setup (Docker) Wir nutzen Qdrant als Vektor-Datenbank. Persistenz ist wichtig. @@ -53,36 +53,49 @@ Wir nutzen Qdrant als Vektor-Datenbank. Persistenz ist wichtig. -v $(pwd)/qdrant_storage:/qdrant/storage \ qdrant/qdrant -### 2.4 Ollama Setup (LLM Service) -Mindnet benötigt einen lokalen LLM-Server für den Chat. +### 2.4 Ollama Setup (LLM & Embeddings) +Mindnet benötigt einen lokalen LLM-Server für Chat UND Embeddings. +**WICHTIG (Update v2.3.10):** Es muss zwingend `nomic-embed-text` installiert sein, sonst startet der Import nicht. # 1. Installieren (Linux Script) - curl -fsSL [https://ollama.com/install.sh](https://ollama.com/install.sh) | sh + curl -fsSL https://ollama.com/install.sh | sh - # 2. Modell laden (Phi-3 Mini für CPU-Performance) - ollama pull phi3:mini + # 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. Die neuen Settings für WP-06/WP-07 (Timeout, Decision Config) sind essenziell für stabilen Betrieb auf CPUs. +Erstelle eine `.env` Datei im Root-Verzeichnis. Achte besonders auf `VECTOR_DIM` und `MINDNET_EMBEDDING_MODEL`. + # 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" - # LLM / RAG Settings - MINDNET_LLM_MODEL="phi3:mini" + # 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" # NEU - # Config & Timeouts + # Timeouts (Erhöht für Async/Nomic) + MINDNET_LLM_TIMEOUT=300.0 + MINDNET_API_TIMEOUT=60.0 + + # Configs MINDNET_PROMPTS_PATH="./config/prompts.yaml" MINDNET_DECISION_CONFIG="./config/decision_engine.yaml" - MINDNET_LLM_TIMEOUT=300.0 ### 2.6 Deployment via Systemd (Backend & Frontend) @@ -98,6 +111,7 @@ Mindnet benötigt zwei Services pro Umgebung: API (Uvicorn) und UI (Streamlit). 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 @@ -141,11 +155,11 @@ Mindnet benötigt zwei Services pro Umgebung: API (Uvicorn) und UI (Streamlit). ## 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. +Der Vault-Zustand sollte regelmäßig (z.B. stündlich per Cronjob) nach Qdrant synchronisiert werden. Das Skript nutzt nun **AsyncIO** und eine Semaphore, um Ollama nicht zu überlasten. **Cronjob-Beispiel (stündlich):** - 0 * * * * cd /home/llmadmin/mindnet && .venv/bin/python3 -m scripts.import_markdown --vault /path/to/vault --prefix "mindnet" --apply --purge-before-upsert --sync-deletes >> ./logs/import.log 2>&1 + 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 Health-Checks Prüfe regelmäßig, ob alle Komponenten laufen. @@ -157,34 +171,28 @@ Prüfe regelmäßig, ob alle Komponenten laufen. ### 3.3 Logs & Monitoring * **Backend Fehler:** `journalctl -u mindnet-prod -f` * **Frontend Fehler:** `journalctl -u mindnet-ui-prod -f` - * Achte auf "Timeout"-Meldungen im Frontend, wenn das Backend zu langsam antwortet. * **LLM Fehler:** `journalctl -u ollama -f` * **Fachliche Logs:** `data/logs/search_history.jsonl` --- -## 4. Update-Prozess +## 4. Troubleshooting (Update v2.4) -Wenn neue Versionen ausgerollt werden (Deployment): +### "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). -1. **Code aktualisieren:** - - cd /home/llmadmin/mindnet - git pull origin main +### "500 Internal Server Error" beim Speichern +* **Ursache:** Oft Timeout bei Ollama, wenn `nomic-embed-text` noch nicht im RAM geladen ist ("Cold Start"). +* **Lösung:** + 1. Sicherstellen, dass Modell existiert: `ollama list`. + 2. API neustarten (re-initialisiert Async Clients). -2. **Dependencies prüfen:** - - source .venv/bin/activate - pip install -r requirements.txt - -3. **Dienste neustarten (Zwingend!):** - - sudo systemctl restart mindnet-prod - sudo systemctl restart mindnet-ui-prod - -4. **Schema-Migration (falls nötig):** - - python3 -m scripts.import_markdown ... --apply +### "NameError: name 'os' is not defined" +* **Ursache:** Fehlender Import in Skripten nach Updates. +* **Lösung:** `git pull` (Fix wurde in v2.3.10 deployed). --- @@ -202,16 +210,13 @@ Für schnelle Wiederherstellung des Suchindex. tar -czf qdrant_backup_$(date +%F).tar.gz ./qdrant_storage docker start mindnet_qdrant -### 5.3 Log-Daten (Priorität 3) -Sichere den Ordner `data/logs/`. Verlust dieser Daten bedeutet Verlust des Trainingsmaterials für Self-Tuning. - -### 5.4 Notfall-Wiederherstellung (Rebuild) -Wenn die Datenbank korrupt ist: +### 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 - python3 -m scripts.import_markdown --vault /path/to/vault --prefix "mindnet" --apply + python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force --- @@ -221,7 +226,4 @@ Wenn die Datenbank korrupt ist: 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. - -### 6.2 Typen-Governance -Änderungen an der `types.yaml` (z.B. neue Gewichte) wirken global und erfordern Tests. \ No newline at end of file +* **Qdrant:** Auf `127.0.0.1` beschränken. \ No newline at end of file diff --git a/docs/appendix.md b/docs/appendix.md index d9fc8f4..2244d5d 100644 --- a/docs/appendix.md +++ b/docs/appendix.md @@ -1,7 +1,7 @@ # Mindnet v2.4 – Appendices & Referenzen **Datei:** `docs/mindnet_appendices_v2.4.md` -**Stand:** 2025-12-10 -**Status:** **FINAL** (Integrierter Stand WP01–WP10a) +**Stand:** 2025-12-11 +**Status:** **FINAL** (Integrierter Stand WP01–WP11) **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. @@ -43,7 +43,9 @@ Referenz aller implementierten Kantenarten (`kind`). | `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". | -| `derived_from` | Default (Exp) | Nein | Herkunft. "Erkenntnis stammt aus Quelle X". | +| `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". | --- @@ -104,28 +106,35 @@ Diese Variablen steuern das Verhalten der Skripte und Container. | `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 Ollama-Modells (Neu in v2.2). | +| `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` | Frontend Timeout (Streamlit). | +| `MINDNET_API_TIMEOUT` | `60.0` | **NEU:** Frontend Timeout (Streamlit). | +| `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`). | -| `VECTOR_DIM` | `384` | Dimension der Embeddings (Modellabhängig). | --- ## 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. * **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. --- @@ -146,4 +155,5 @@ Aktueller Implementierungsstand der Module. | **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.** | \ No newline at end of file +| **WP10a**| Draft Editor | 🟢 Live | **Interaktives UI für WP07 Drafts.** | +| **WP11** | Backend Intelligence | 🟢 Live | **Async Core, Nomic, Matrix.** | \ No newline at end of file diff --git a/Programmmanagement/ARCHITECTURE_SNAPSHOT_v2.2.1.md b/docs/archiv/ARCHITECTURE_SNAPSHOT_v2.2.1.md similarity index 100% rename from Programmmanagement/ARCHITECTURE_SNAPSHOT_v2.2.1.md rename to docs/archiv/ARCHITECTURE_SNAPSHOT_v2.2.1.md diff --git a/Programmmanagement/Überarbeitungshinweise_WP03.md b/docs/archiv/Überarbeitungshinweise_WP03.md similarity index 100% rename from Programmmanagement/Überarbeitungshinweise_WP03.md rename to docs/archiv/Überarbeitungshinweise_WP03.md diff --git a/Programmmanagement/Überarbeitungshinweise_WP04.md b/docs/archiv/Überarbeitungshinweise_WP04.md similarity index 100% rename from Programmmanagement/Überarbeitungshinweise_WP04.md rename to docs/archiv/Überarbeitungshinweise_WP04.md diff --git a/docs/dev_workflow.md b/docs/dev_workflow.md index 70537eb..806f19e 100644 --- a/docs/dev_workflow.md +++ b/docs/dev_workflow.md @@ -1,6 +1,6 @@ # Mindnet v2.4 – Entwickler-Workflow **Datei:** `docs/DEV_WORKFLOW.md` -**Stand:** 2025-12-10 (Aktualisiert: Inkl. Interview-Tests WP07) +**Stand:** 2025-12-11 (Aktualisiert: Inkl. Async Intelligence & Nomic) Dieses Handbuch beschreibt den Entwicklungszyklus zwischen **Windows PC** (IDE), **Raspberry Pi** (Gitea) und **Beelink** (Runtime/Server). @@ -35,14 +35,14 @@ Hier erstellst du die neue Funktion in einer sicheren Umgebung. 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/wp07-interview`). + * Gib den Namen ein: `feature/was-ich-tue` (z.B. `feature/wp11-async-fix`). * 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 `decision_engine.yaml`). + * Nimm deine Änderungen vor (z.B. neue Schemas in `decision_engine.yaml` oder Async-Logik in `ingestion.py`). 5. **Sichern & Hochladen:** * **Source Control** Icon (Gabel-Symbol) -> Nachricht eingeben -> **Commit**. @@ -64,14 +64,16 @@ Hier prüfst du, ob dein neuer Code auf dem echten Server läuft. ```bash git fetch # Tipp: 'git branch -r' zeigt alle verfügbaren Branches an - git checkout feature/wp07-interview + git checkout feature/wp11-async-fix git pull ``` -4. **Umgebung vorbereiten (bei Bedarf):** +4. **Umgebung vorbereiten (WICHTIG für v2.4):** ```bash source .venv/bin/activate - pip install -r requirements.txt # Nur nötig bei neuen Paketen + pip install -r requirements.txt # HTTPX usw. + # Sicherstellen, dass das neue Embedding-Modell da ist: + ollama pull nomic-embed-text ``` 5. **Test-Server aktualisieren (WICHTIG):** @@ -87,8 +89,6 @@ Hier prüfst du, ob dein neuer Code auf dem echten Server läuft. # Logs prüfen (um Fehler zu sehen): journalctl -u mindnet-dev -f - # Oder Frontend Logs: - journalctl -u mindnet-ui-dev -f ``` **Option B: Manuell Debuggen (Direct Output)** @@ -100,13 +100,6 @@ Hier prüfst du, ob dein neuer Code auf dem echten Server läuft. # 2. Manuell starten (z.B. API) uvicorn app.main:app --host 0.0.0.0 --port 8002 --env-file .env - - # ... Testen ... - - # 3. Wenn fertig: Services wieder anschalten (Optional) - # Strg+C drücken - sudo systemctl start mindnet-dev - sudo systemctl start mindnet-ui-dev ``` 6. **Validieren (Smoke Tests):** @@ -114,16 +107,15 @@ Hier prüfst du, ob dein neuer Code auf dem echten Server läuft. * **Browser:** Öffne `http://:8502` um die UI zu testen (Intent Badge prüfen!). * **CLI:** Führe Testskripte in einem **zweiten Terminal** aus: - **Test A: Decision Engine** + **Test A: Intelligence / Aliases (Neu in WP11)** ```bash - python tests/test_wp06_decision.py -p 8002 -q "Soll ich Qdrant nutzen?" - # Erwartung: Intent DECISION + python debug_analysis.py + # Erwartung: "✅ ALIAS GEFUNDEN" ``` - **Test B: Interview Modus (Neu!)** + **Test B: API Check** ```bash - python tests/test_wp06_decision.py -p 8002 -q "Ich will ein neues Projekt starten" - # Erwartung: Intent INTERVIEW, Output ist Markdown Codeblock + curl -X POST "http://localhost:8002/ingest/analyze" -d '{"text": "mindnet", "type": "journal"}' ``` --- @@ -150,16 +142,18 @@ Jetzt bringen wir die Änderung in das Live-System (Port 8001 / 8501). cd /home/llmadmin/mindnet git pull origin main - # Dependencies updaten + # Dependencies updaten & Modelle checken source .venv/bin/activate pip install -r requirements.txt + ollama pull nomic-embed-text + + # 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 - - # Kurz prüfen, ob er läuft - sudo systemctl status mindnet-prod ``` --- @@ -174,7 +168,7 @@ Damit das Chaos nicht wächst, löschen wir den fertigen Branch. cd ~/mindnet_dev git checkout main git pull - git branch -d feature/wp07-interview + git branch -d feature/wp11-async-fix ``` 3. **VS Code:** * Auf `main` wechseln. @@ -187,27 +181,25 @@ Damit das Chaos nicht wächst, löschen wir den fertigen Branch. | Wo? | Befehl | Was tut es? | | :--- | :--- | :--- | -| **VS Code** | `Sync (auf main)` | **WICHTIG:** Holt neuesten Code vom Server. | -| **Beelink** | `git fetch` | Aktualisiert Liste der Remote-Branches. | | **Beelink** | `sudo systemctl restart mindnet-dev` | **Neustart Dev-Backend (Port 8002).** | -| **Beelink** | `sudo systemctl restart mindnet-ui-dev` | **Neustart Dev-Frontend (Port 8502).** | | **Beelink** | `journalctl -u mindnet-dev -f` | **Live-Logs Backend.** | -| **Beelink** | `journalctl -u mindnet-ui-dev -f` | **Live-Logs Frontend.** | +| **Beelink** | `python debug_analysis.py` | **Prüft Aliases & Scores.** | +| **Beelink** | `python -m scripts.reset_qdrant ...` | **Löscht & Repariert DB.** | --- ## 4. Troubleshooting +**"Vector dimension error: expected 768, got 384"** +* **Ursache:** Du hast `nomic-embed-text` (768) aktiviert, aber die DB ist noch alt (384). +* **Lösung:** `scripts.reset_qdrant` ausführen und neu importieren. + **"Read timed out (300s)" / 500 Error beim Interview** * **Ursache:** Das LLM (Ollama) braucht für den One-Shot Draft länger als das Timeout erlaubt. * **Lösung:** 1. Erhöhe in `.env` den Wert: `MINDNET_LLM_TIMEOUT=300.0`. 2. Starte die Server neu. -**"Port 8002 / 8502 already in use"** -* **Ursache:** Du willst `uvicorn` oder `streamlit` manuell starten, aber der Service läuft noch. -* **Lösung:** `sudo systemctl stop mindnet-dev` bzw. `mindnet-ui-dev`. - **"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. \ No newline at end of file diff --git a/docs/developer_guide.md b/docs/developer_guide.md index e536dcd..ba6abf2 100644 --- a/docs/developer_guide.md +++ b/docs/developer_guide.md @@ -1,7 +1,7 @@ # Mindnet v2.4 – Developer Guide **Datei:** `docs/mindnet_developer_guide_v2.4.md` -**Stand:** 2025-12-10 -**Status:** **FINAL** (Inkl. RAG, Interview Mode & Frontend WP10) +**Stand:** 2025-12-11 +**Status:** **FINAL** (Inkl. Async Core, Nomic & Frontend State) **Quellen:** `mindnet_technical_architecture.md`, `Handbuch.md`, `DEV_WORKFLOW.md`. > **Zielgruppe:** Entwickler:innen. @@ -20,6 +20,7 @@ - [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) - [4. Tests \& Debugging](#4-tests--debugging) - [4.1 Unit Tests (Pytest)](#41-unit-tests-pytest) - [4.2 Integration / Pipeline Tests](#42-integration--pipeline-tests) @@ -40,6 +41,7 @@ Der Code ist modular in `app` (Logik), `scripts` (CLI) und `config` (Steuerung) mindnet/ ├── app/ │ ├── core/ # Kernlogik + │ │ ├── ingestion.py # NEU: Async Ingestion Service (WP11) │ │ ├── chunker.py # Text-Zerlegung │ │ ├── derive_edges.py # Edge-Erzeugung (WP03 Logik) │ │ ├── retriever.py # Scoring & Hybrid Search @@ -49,13 +51,15 @@ Der Code ist modular in `app` (Logik), `scripts` (CLI) und `config` (Steuerung) │ │ └── dto.py # Zentrale DTO-Definition │ ├── routers/ # FastAPI Endpoints │ │ ├── query.py # Suche + │ │ ├── ingest.py # NEU: Save/Analyze (WP11) │ │ ├── chat.py # Hybrid Router & Interview Logic (WP06/WP07) │ │ ├── feedback.py # Feedback (WP04c) │ │ └── ... │ ├── services/ # Interne & Externe Dienste │ │ ├── llm_service.py # Ollama Client (Mit Timeout & Raw-Mode) + │ │ ├── embeddings_client.py# NEU: Async Embeddings (HTTPX) │ │ ├── feedback_service.py # Logging (JSONL Writer) - │ │ └── embeddings_client.py + │ │ └── discovery.py # NEU: Intelligence Logic (WP11) │ ├── frontend/ # NEU (WP10) │ │ └── ui.py # Streamlit Application inkl. Draft-Editor │ └── main.py # Entrypoint der API @@ -77,7 +81,7 @@ Der Code ist modular in `app` (Logik), `scripts` (CLI) und `config` (Steuerung) ### 2.1 Voraussetzungen * **Python:** 3.10 oder höher. * **Docker:** Für Qdrant. -* **Ollama:** Für lokale LLM-Inference (erforderlich für `/chat`). +* **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 @@ -93,9 +97,11 @@ Der Code ist modular in `app` (Logik), `scripts` (CLI) und `config` (Steuerung) # 3. Abhängigkeiten installieren (inkl. Streamlit) pip install -r requirements.txt - # 4. Ollama Setup (Modell laden) - # Wir nutzen Phi-3 Mini für schnelle CPU-Inference + # 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. @@ -106,18 +112,21 @@ Erstelle eine `.env` Datei im Root-Verzeichnis. # 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 - MINDNET_PROMPTS_PATH="./config/prompts.yaml" MINDNET_DECISION_CONFIG="./config/decision_engine.yaml" # Frontend Settings (WP10) MINDNET_API_URL="http://localhost:8002" + MINDNET_API_TIMEOUT=60.0 # Import-Strategie MINDNET_HASH_COMPARE="Body" @@ -144,7 +153,8 @@ Wir entwickeln mit zwei Services. Du kannst sie manuell in zwei Terminals starte ### 3.1 Der Importer (`scripts.import_markdown`) Dies ist das komplexeste Modul. -* **Einstieg:** `scripts/import_markdown.py` -> `main()`. +* **Einstieg:** `scripts/import_markdown.py` -> `main_async()`. +* **Async & Semaphore:** Das Skript nutzt nun `asyncio` und eine Semaphore (Limit: 5), um parallele Embeddings zu erzeugen, ohne Ollama zu überlasten. * **Idempotenz:** Der Importer muss mehrfach laufen können, ohne Duplikate zu erzeugen. Wir nutzen deterministische IDs (UUIDv5). * **Debugging:** Nutze `--dry-run` oder `scripts/payload_dryrun.py`. @@ -161,9 +171,15 @@ Hier passiert das Scoring. ### 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`. * **Draft Editor:** Enthält einen YAML-Sanitizer (`normalize_meta_and_body`), der sicherstellt, dass LLM-Halluzinationen im Frontmatter nicht das File zerstören. -* **State:** Nutzt `st.session_state` für Chat-History und Drafts. -* **Logik:** Ruft `/chat` und `/feedback` Endpoints der API auf. +* **Logik:** Ruft `/chat` und `/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. +* Unterstützt dediziertes Embedding-Modell (`nomic-embed-text`) getrennt vom Chat-Modell. +* Enthält Legacy-Funktion `embed_text` für synchrone Skripte. --- @@ -201,6 +217,9 @@ Prüfen das laufende System gegen eine echte Qdrant-Instanz und Ollama. # 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) @@ -263,6 +282,7 @@ Der `One-Shot Extractor` (Prompt Template) liest diese Liste dynamisch und weist **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):** diff --git a/docs/mindnet_functional_architecture.md b/docs/mindnet_functional_architecture.md index 25dfff5..32b5dd2 100644 --- a/docs/mindnet_functional_architecture.md +++ b/docs/mindnet_functional_architecture.md @@ -1,9 +1,9 @@ # Mindnet v2.4 – Fachliche Architektur **Datei:** `docs/mindnet_functional_architecture_v2.4.md` -**Stand:** 2025-12-10 -**Status:** **FINAL** (Integrierter Stand WP01–WP10 + WP07) +**Stand:** 2025-12-11 +**Status:** **FINAL** (Integrierter Stand WP01–WP11: Async Intelligence) -> Dieses Dokument beschreibt **was** Mindnet fachlich tut und **warum** – mit Fokus auf die Erzeugung und Nutzung von **Edges** (Kanten), die Logik des Retrievers und den **RAG-Chat** (Decision Engine, Interview-Modus & Persönlichkeit). Die technische Umsetzung wird im technischen Dokument detailliert. +> Dieses Dokument beschreibt **was** Mindnet fachlich tut und **warum** – mit Fokus auf die Erzeugung und Nutzung von **Edges** (Kanten), die Logik des Retrievers und den **RAG-Chat** (Decision Engine, Interview-Modus & Persönlichkeit). ---
@@ -19,6 +19,7 @@ - [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 Matrix-Logik (Kontextsensitive Kanten) – Neu in v2.4](#24-matrix-logik-kontextsensitive-kanten--neu-in-v24) - [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) @@ -26,12 +27,13 @@ - [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) - - [6) Context Intelligence \& Intent Router (WP06/WP07)](#6-context-intelligence--intent-router-wp06wp07) + - [6) Context Intelligence \& Intent Router (WP06–WP11)](#6-context-intelligence--intent-router-wp06wp11) - [6.1 Das Problem: Statische vs. Dynamische Antworten](#61-das-problem-statische-vs-dynamische-antworten) - [6.2 Der Intent-Router (Keyword \& Semantik)](#62-der-intent-router-keyword--semantik) - [6.3 Strategic Retrieval (Injektion von Werten)](#63-strategic-retrieval-injektion-von-werten) - [6.4 Reasoning (Das Gewissen)](#64-reasoning-das-gewissen) - - [6.5 Der Interview-Modus (One-Shot Extraction) – Neu in v2.4](#65-der-interview-modus-one-shot-extraction--neu-in-v24) + - [6.5 Der Interview-Modus (One-Shot Extraction)](#65-der-interview-modus-one-shot-extraction) + - [6.6 Active Intelligence (Link Suggestions) – Neu in v2.4](#66-active-intelligence-link-suggestions--neu-in-v24) - [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) @@ -45,7 +47,7 @@ - [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 (v2.2)](#14-beispiel--von-markdown-zu-kanten-v22) + - [14) Beispiel – Von Markdown zu Kanten](#14-beispiel--von-markdown-zu-kanten) - [15) Referenzen (Projektdateien \& Leitlinien)](#15-referenzen-projektdateien--leitlinien) - [16) Workpackage Status (v2.4.0)](#16-workpackage-status-v240) @@ -61,7 +63,7 @@ Die drei zentralen Artefakt-Sammlungen lauten: - `mindnet_chunks` – semantische Teilstücke einer Note (Fenster/„Chunks“) - `mindnet_edges` – gerichtete Beziehungen zwischen Knoten (Chunks/Notes) -Die Import-Pipeline erzeugt diese Artefakte **deterministisch** und **idempotent** (erneute Läufe überschreiben konsistent statt zu duplizieren). Die Import-Schritte sind: *parse → chunk → edge → upsert*. +Die Import-Pipeline (seit v2.3.10 asynchron) erzeugt diese Artefakte **deterministisch** und **idempotent** (erneute Läufe überschreiben konsistent statt zu duplizieren). Die Import-Schritte sind: *parse → chunk → embed → edge → upsert*. --- @@ -77,6 +79,7 @@ Die Import-Pipeline erzeugt diese Artefakte **deterministisch** und **idempotent - 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). - **Neu in v2.2:** Alle Kanten entstehen ausschließlich zwischen Chunks (Scope="chunk"), nie zwischen Notes direkt. Notes dienen nur noch als Metadatencontainer. > **Wichtig:** Chunking-Profile (short/medium/long) kommen aus `types.yaml` (per Note-Typ), können aber lokal überschrieben werden. Die effektiven Werte werden bei der Payload-Erzeugung bestimmt. @@ -128,13 +131,23 @@ Regel: **Für jede gefundene explizite Referenz** (s. o.) werden **zusätzliche* 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 Matrix-Logik (Kontextsensitive Kanten) – Neu in v2.4 +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, …)* +- `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) @@ -209,9 +222,9 @@ Die API gibt diese Analysen als menschenlesbare Sätze (`reasons`) und als Daten --- -## 6) Context Intelligence & Intent Router (WP06/WP07) +## 6) Context Intelligence & Intent Router (WP06–WP11) -Seit WP06/WP07 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. +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. @@ -223,7 +236,7 @@ Der Router prüft vor jeder Antwort die Absicht über konfigurierbare Strategien 1. **FACT:** Reine Wissensfrage ("Was ist Qdrant?"). → Standard RAG. 2. **DECISION:** Frage nach Rat oder Strategie ("Soll ich Qdrant nutzen?"). → Aktiviert die Decision Engine. 3. **EMPATHY:** Emotionale Zustände ("Ich bin gestresst"). → Aktiviert den empathischen Modus. -4. **INTERVIEW (Neu in WP07):** Wunsch, Wissen zu erfassen ("Neues Projekt anlegen"). → Aktiviert den Draft-Generator. +4. **INTERVIEW (WP07):** Wunsch, Wissen zu erfassen ("Neues Projekt anlegen"). → Aktiviert den Draft-Generator. 5. **CODING:** Technische Anfragen. ### 6.3 Strategic Retrieval (Injektion von Werten) @@ -236,7 +249,7 @@ Im Modus `DECISION` führt das System eine **zweite Suchstufe** aus. Es sucht ni 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.5 Der Interview-Modus (One-Shot Extraction) – Neu in v2.4 +### 6.5 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). @@ -244,6 +257,14 @@ Wenn der User Wissen erfassen will ("Ich möchte ein neues Projekt anlegen"), we * **Draft-Status:** Fehlende Pflichtfelder werden mit `[TODO]` markiert. * **UI-Integration:** Das Frontend rendert statt einer Chat-Antwort einen **interaktiven Editor** (WP10), in dem der Entwurf finalisiert werden kann. +### 6.6 Active Intelligence (Link Suggestions) – Neu in v2.4 +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.4 beschriebene **Matrix-Logik** zum Einsatz, um den korrekten Kanten-Typ vorzuschlagen. + --- ## 7) Future Concepts: The Empathic Digital Twin (Ausblick) @@ -353,6 +374,10 @@ Eine typische Gewichtung (konfigurierbar in `retriever.yaml`) ist: - `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. @@ -377,7 +402,7 @@ Frontmatter-Eigenschaften (Properties) bleiben **minimiert**: --- -## 14) Beispiel – Von Markdown zu Kanten (v2.2) +## 14) Beispiel – Von Markdown zu Kanten **Markdown (Auszug)** # Relations Showcase @@ -406,6 +431,7 @@ Frontmatter-Eigenschaften (Properties) bleiben **minimiert**: - 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`. --- @@ -425,5 +451,6 @@ Aktueller Implementierungsstand der Module. | **WP06** | Decision Engine | 🟢 Live | Intent-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-UI mit Feedback & Intents. | -| **WP10a**| Draft Editor | 🟢 Live | **Interaktiver Editor für WP07 Drafts.** | \ No newline at end of file +| **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.** | \ No newline at end of file diff --git a/docs/mindnet_technical_architecture.md b/docs/mindnet_technical_architecture.md index 7636dd6..875bc98 100644 --- a/docs/mindnet_technical_architecture.md +++ b/docs/mindnet_technical_architecture.md @@ -1,7 +1,7 @@ # Mindnet v2.4 – Technische Architektur **Datei:** `docs/mindnet_technical_architecture_v2.4.md` -**Stand:** 2025-12-10 -**Status:** **FINAL** (Integrierter Stand WP01–WP10 + WP07) +**Stand:** 2025-12-11 +**Status:** **FINAL** (Integrierter Stand WP01–WP11: Async Intelligence) **Quellen:** `Programmplan_V2.2.md`, `Handbuch.md`, `chunking_strategy.md`, `wp04_retriever_scoring.md`. > **Ziel dieses Dokuments:** @@ -27,7 +27,7 @@ - [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](#41-verarbeitungsschritte) + - [4.1 Verarbeitungsschritte (Async)](#41-verarbeitungsschritte-async) - [5. Retriever-Architektur \& Scoring](#5-retriever-architektur--scoring) - [5.1 Betriebsmodi](#51-betriebsmodi) - [5.2 Scoring-Formel (WP04a)](#52-scoring-formel-wp04a) @@ -43,7 +43,8 @@ - [7.1 Kommunikation](#71-kommunikation) - [7.2 Features \& UI-Logik](#72-features--ui-logik) - [7.3 Draft-Editor \& Sanitizer (Neu in WP10a)](#73-draft-editor--sanitizer-neu-in-wp10a) - - [7.4 Deployment Ports](#74-deployment-ports) + - [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) @@ -65,8 +66,9 @@ Mindnet ist ein **lokales RAG-System (Retrieval Augmented Generation)** mit Web- * **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. -5. **Frontend:** Streamlit-App (`ui.py`) für Interaktion und Visualisierung inkl. **Draft Editor**. -6. **Inference:** Lokales LLM (Ollama: Phi-3 Mini) für RAG-Chat und Antwortgenerierung. + * **Update v2.3.10:** Der Core arbeitet nun vollständig **asynchron (AsyncIO)**, um Blockaden bei Embedding-Requests zu vermeiden. +5. **Frontend:** Streamlit-App (`ui.py`) für Interaktion und Visualisierung inkl. **Draft Editor** und **Intelligence-Features**. +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`). @@ -76,6 +78,7 @@ Das System arbeitet **deterministisch** (stabile IDs) und ist **konfigurationsge ├── app/ │ ├── main.py # FastAPI Einstiegspunkt │ ├── core/ + │ │ ├── ingestion.py # NEU: Async Ingestion Service (WP11) │ │ ├── qdrant.py # Client-Factory & Connection │ │ ├── qdrant_points.py # Low-Level Point Operations (Upsert/Delete) │ │ ├── note_payload.py # Bau der Note-Objekte @@ -88,13 +91,14 @@ Das System arbeitet **deterministisch** (stabile IDs) und ist **konfigurationsge │ ├── models/ # Pydantic DTOs │ ├── routers/ │ │ ├── query.py # Such-Endpunkt + │ │ ├── ingest.py # NEU: API für Save & Analyze (WP11) │ │ ├── chat.py # Hybrid Router & Interview Logic (WP06/07) │ │ ├── feedback.py # Feedback-Endpunkt (WP04c) │ │ └── ... │ ├── services/ - │ │ ├── llm_service.py # Ollama Client mit Timeout & Raw-Mode - │ │ ├── feedback_service.py # JSONL Logging (WP04c) - │ │ └── embeddings_client.py + │ │ ├── llm_service.py # Ollama Chat Client + │ │ ├── embeddings_client.py# NEU: Async Embedding Client (HTTPX) + │ │ └── feedback_service.py # JSONL Logging (WP04c) │ ├── frontend/ # NEU (WP10) │ └── ui.py # Streamlit Application inkl. Sanitizer ├── config/ @@ -105,7 +109,7 @@ Das System arbeitet **deterministisch** (stabile IDs) und ist **konfigurationsge ├── data/ │ └── logs/ # Lokale JSONL-Logs (WP04c) ├── scripts/ - │ ├── import_markdown.py # Haupt-Importer CLI + │ ├── 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 @@ -136,6 +140,7 @@ Repräsentiert die Metadaten einer Datei. ### 2.2 Chunks Collection (`_chunks`) Die atomaren Sucheinheiten. * **Zweck:** Vektorsuche (Embeddings), Granulares Ergebnis. +* **Update v2.3.10:** Vektor-Dimension ist jetzt **768** (für `nomic-embed-text`). * **Schema (Payload):** | Feld | Datentyp | Beschreibung | @@ -204,37 +209,40 @@ Steuert die LLM-Persönlichkeit und Templates. * Enthält Templates für alle Strategien inkl. `interview_template` mit One-Shot Logik. ### 3.5 Environment (`.env`) -Erweiterung für LLM-Steuerung: +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=60.0 # Neu: Timeout für Frontend-API Calls MINDNET_DECISION_CONFIG="config/decision_engine.yaml" + MINDNET_VAULT_ROOT="./vault" # Neu: Pfad für Write-Back --- ## 4. Import-Pipeline (Markdown → Qdrant) Das Skript `scripts/import_markdown.py` orchestriert den Prozess. +**Neu in v2.3.10:** Der Import nutzt `asyncio` und eine **Semaphore**, um Ollama nicht zu überlasten. -### 4.1 Verarbeitungsschritte +### 4.1 Verarbeitungsschritte (Async) 1. **Discovery & Parsing:** * Einlesen der `.md` Dateien. Hash-Vergleich (Body/Frontmatter) zur Erkennung von Änderungen. 2. **Typauflösung:** - * Laden der `types.yaml`. Bestimmen des effektiven Typs und der `edge_defaults`. + * Bestimmung des `type` via `types.yaml`. 3. **Chunking:** - * Zerlegung via `chunker.py` basierend auf `chunk_profile` (z.B. `by_heading`, `short`, `long`). - * Trennung von `text` (Kern) und `window` (Embedding-Kontext). -4. **Kantenableitung (Edge Derivation):** - Die `derive_edges.py` erzeugt Kanten in strikter Reihenfolge: - 1. **Inline-Edges:** `[[rel:depends_on X]]` → `kind=depends_on`, `rule_id=inline:rel`, `conf=0.95`. - 2. **Callout-Edges:** `> [!edge] related_to: [[X]]` → `kind=related_to`, `rule_id=callout:edge`, `conf=0.90`. - 3. **Explizite Referenzen:** `[[X]]` → `kind=references`, `rule_id=explicit:wikilink`, `conf=1.0`. - 4. **Typ-Defaults:** Für jede Referenz werden Zusatzkanten gemäß `edge_defaults` erzeugt (z.B. `project` -> `depends_on`). `rule_id=edge_defaults:...`, `conf=0.7`. - 5. **Struktur:** `belongs_to`, `next`, `prev` (automatisch). -5. **Upsert:** - * Schreiben in Qdrant. Nutzung von `--purge-before-upsert` für saubere Updates. + * Zerlegung via `chunker.py` basierend auf `chunk_profile`. +4. **Embedding (Async):** + * Der `EmbeddingsClient` (`app/services/embeddings_client.py`) sendet Text-Chunks asynchron an Ollama. + * Modell: `nomic-embed-text` (768d). + * Semaphore: Max. 5 gleichzeitige Files, um OOM (Out-of-Memory) zu verhindern. +5. **Kantenableitung (Edge Derivation):** + * `derive_edges.py` erzeugt Inline-, Callout- und Default-Edges. +6. **Upsert:** + * Schreiben in Qdrant. Nutzung von `--purge-before-upsert`. + * **Strict Mode:** Der Prozess bricht ab, wenn Embeddings leer sind oder Dimension `0` haben. --- @@ -243,7 +251,7 @@ Das Skript `scripts/import_markdown.py` orchestriert den Prozess. 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. Schnell. +* **Semantic:** Reine Vektorsuche (768d). * **Hybrid:** Vektorsuche + Graph-Expansion (Tiefe N) + Re-Ranking. ### 5.2 Scoring-Formel (WP04a) @@ -274,7 +282,7 @@ Der Hybrid-Modus lädt dynamisch die Nachbarschaft der Top-K Vektor-Treffer ("Se --- -## 6. RAG & Chat Architektur (WP06 Hybrid Router + WP07 Interview) +## 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. Der `ChatRouter` (`app/routers/chat.py`) fungiert als zentraler Dispatcher. @@ -329,7 +337,7 @@ Das Frontend ist eine **Streamlit-Anwendung** (`app/frontend/ui.py`), die als se ### 7.1 Kommunikation * **Backend-URL:** Konfiguriert via `MINDNET_API_URL` (Default: `http://localhost:8002`). -* **Endpoints:** Nutzt `/chat` für Interaktion und `/feedback` für Bewertungen. +* **Endpoints:** Nutzt `/chat` für Interaktion, `/feedback` für Bewertungen und `/ingest/analyze` für Intelligence. * **Resilienz:** Das Frontend implementiert eigene Timeouts (`MINDNET_API_TIMEOUT`, Default 300s). ### 7.2 Features & UI-Logik @@ -350,7 +358,14 @@ Wenn der Intent `INTERVIEW` ist, rendert die UI statt einer Textblase den **Draf 3. **Editor Widget:** `st.text_area` erlaubt das Bearbeiten des Inhalts vor dem Speichern. 4. **Action:** Buttons zum Download oder Kopieren des fertigen Markdowns. -### 7.4 Deployment Ports +### 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) | diff --git a/docs/pipeline_playbook.md b/docs/pipeline_playbook.md index 2834ee3..ac1170a 100644 --- a/docs/pipeline_playbook.md +++ b/docs/pipeline_playbook.md @@ -1,7 +1,7 @@ # mindnet v2.4 – Pipeline Playbook **Datei:** `docs/mindnet_pipeline_playbook_v2.4.md` -**Stand:** 2025-12-10 -**Status:** **FINAL** (Inkl. WP07 Interview & WP10a Editor) +**Stand:** 2025-12-11 +**Status:** **FINAL** (Inkl. Async Ingestion & Active Intelligence) **Quellen:** `mindnet_v2_implementation_playbook.md`, `Handbuch.md`, `chunking_strategy.md`, `docs_mindnet_retriever.md`, `mindnet_admin_guide_v2.4.md`. --- @@ -12,7 +12,7 @@ - [](#) - [1. Zweck \& Einordnung](#1-zweck--einordnung) - [2. Die Import-Pipeline (Runbook)](#2-die-import-pipeline-runbook) - - [2.1 Der 12-Schritte-Prozess](#21-der-12-schritte-prozess) + - [2.1 Der 12-Schritte-Prozess (Async)](#21-der-12-schritte-prozess-async) - [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) @@ -27,6 +27,7 @@ - [5.2 Intent Router (WP06/07)](#52-intent-router-wp0607) - [5.3 Context Enrichment](#53-context-enrichment) - [5.4 Generation (LLM)](#54-generation-llm) + - [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) @@ -44,7 +45,7 @@ Dieses Playbook ist das zentrale operative Handbuch für die **mindnet-Pipeline* **Zielgruppe:** Dev/Ops, Tech-Leads. **Scope:** -* **Ist-Stand (WP01–WP10a):** Import, Chunking, Edge-Erzeugung, Hybrider Retriever, RAG-Chat (Hybrid Router), Feedback Loop, Frontend, Draft Editor. +* **Ist-Stand (WP01–WP11):** Async Import, 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). --- @@ -53,8 +54,8 @@ Dieses Playbook ist das zentrale operative Handbuch für die **mindnet-Pipeline* 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 12-Schritte-Prozess -Gemäß WP03-Spezifikation läuft der Import intern wie folgt ab: +### 2.1 Der 12-Schritte-Prozess (Async) +Seit v2.3.10 läuft der Import **asynchron**, um Netzwerk-Blockaden bei der Embedding-Generierung zu vermeiden. 1. **Markdown lesen:** Rekursives Scannen des Vaults. 2. **Frontmatter extrahieren:** Validierung von Pflichtfeldern (`id`, `type`, `title`). @@ -65,8 +66,10 @@ Gemäß WP03-Spezifikation läuft der Import intern wie folgt ab: 7. **Callout-Kanten finden:** Parsing von `> [!edge]` Blöcken. 8. **Default-Edges erzeugen:** Anwendung der `edge_defaults` aus der Typ-Registry. 9. **Strukturkanten erzeugen:** `belongs_to` (Chunk->Note), `next`/`prev` (Sequenz). -10. **Chunks upserten:** Schreiben in Qdrant (`mindnet_chunks`). -11. **Edges upserten:** Schreiben in Qdrant (`mindnet_edges`). +10. **Embedding & Upsert (Async):** + * Das System nutzt eine **Semaphore** (Limit: 5 Files concurrent), um Ollama nicht zu überlasten. + * Generierung der Vektoren via `nomic-embed-text` (768 Dim). +11. **Strict Mode:** Der Prozess bricht sofort ab, wenn ein Embedding leer ist oder die Dimension `0` hat. 12. **Diagnose:** Automatischer Check der Integrität nach dem Lauf. ### 2.2 Standard-Betrieb (Inkrementell) @@ -99,13 +102,18 @@ Nach einem Import oder Code-Update müssen die API-Prozesse neu gestartet werden sudo systemctl status mindnet-prod ### 2.4 Full Rebuild (Clean Slate) -Notwendig bei Änderungen an `types.yaml` (z.B. neue Chunk-Größen) oder Embedding-Modellen. +Notwendig bei Änderungen an `types.yaml` (z.B. neue Chunk-Größen) oder beim Wechsel des Embedding-Modells (z.B. Update auf `nomic-embed-text`). - # 1. Qdrant Collections löschen und neu anlegen (Wipe inkl. Schema) +**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 + python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force --- @@ -177,6 +185,17 @@ Der Router (`chat.py`) reichert die gefundenen Chunks mit Metadaten an: * **Prompting:** Template wird basierend auf Intent gewählt (`decision_template`, `interview_template` etc.). * **One-Shot (WP07):** Im Interview-Modus generiert das LLM direkt einen Markdown-Block ohne Rückfragen. +### 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) @@ -209,12 +228,12 @@ Prüft am laufenden System (Prod oder Dev), ob Semantik, Graph und Feedback funk # 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" - # Interview Test (WP07) - python tests/test_wp06_decision.py -p 8002 -e INTERVIEW -q "Neues Projekt starten" - # Feedback Test python tests/test_feedback_smoke.py --url http://localhost:8001/query @@ -250,4 +269,5 @@ Aktueller Implementierungsstand der Module. | **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.** | \ No newline at end of file +| **WP10a**| Draft Editor | 🟢 Live | **Interaktives UI für WP07 Drafts.** | +| **WP11** | Backend Intelligence | 🟢 Live | **Async Ingestion, Nomic Embeddings, Matrix Logic.** | \ No newline at end of file diff --git a/docs/user_guide.md b/docs/user_guide.md index 09756d2..8f77940 100644 --- a/docs/user_guide.md +++ b/docs/user_guide.md @@ -1,7 +1,7 @@ # Mindnet v2.4 – User Guide **Datei:** `docs/mindnet_user_guide_v2.4.md` -**Stand:** 2025-12-10 -**Status:** **FINAL** (Inkl. RAG, Web-Interface & Interview-Assistent) +**Stand:** 2025-12-11 +**Status:** **FINAL** (Inkl. RAG, Web-Interface & Interview-Assistent & Intelligence) **Quellen:** `knowledge_design.md`, `wp04_retriever_scoring.md`, `Programmplan_V2.2.md`, `Handbuch.md`. > **Willkommen bei Mindnet.** @@ -42,6 +42,7 @@ Seit Version 2.3.1 bedienst du Mindnet über eine grafische Oberfläche im Brows ### 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). @@ -68,7 +69,7 @@ Wenn du frustriert bist oder reflektieren willst, wechselt Mindnet in den "Ich"- * **Auslöser (Keywords & Semantik):** "Ich fühle mich...", "Traurig", "Gestresst", "Alles ist sinnlos", "Ich bin überfordert". * **Was passiert:** Mindnet lädt deine **Erfahrungen** (`type: experience`) und **Glaubenssätze** (`type: belief`). Es antwortet verständnisvoll und zitiert deine eigenen Lektionen. -### 3.3 Modus: Interview ("Der Analyst") – Neu! +### 3.3 Modus: Interview ("Der Analyst") Wenn du Wissen festhalten willst, statt zu suchen. * **Auslöser:** "Neues Projekt", "Notiz erstellen", "Ich will etwas festhalten", "Neue Entscheidung dokumentieren". @@ -128,4 +129,15 @@ Mindnet kann dir helfen, Markdown-Notizen zu schreiben. * Du siehst das generierte Frontmatter (`type: project`, `status: draft`). * 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:** Speichere die Datei in deinen Obsidian Vault. Beim nächsten Import ist sie im System. \ No newline at end of file +5. **Speichern:** Speichere die Datei in deinen Obsidian Vault. Beim nächsten Import ist sie im System. + +### 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. \ No newline at end of file