Dokumentation WP11

This commit is contained in:
Lars committed 2025-12-11 16:58:23 +01:00
1 parent 00aecf692d
commit 5bf91d51da
14 files changed
+319 -208

No files matched your search

+17 -16
View File
@@ -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.
+19 -16
View File
@@ -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.
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.
+49 -47
View File
@@ -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.
* **Qdrant:** Auf `127.0.0.1` beschränken.
+17 -7
View File
@@ -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.** |
| **WP10a**| Draft Editor | 🟢 Live | **Interaktives UI für WP07 Drafts.** |
| **WP11** | Backend Intelligence | 🟢 Live | **Async Core, Nomic, Matrix.** |
@@ -0,0 +1,27 @@
# Architecture Snapshot v2.2.1
**Stand:** Nach Abschluss von WP-04c
**Kontext:** Wichtig für WP-05 Entwicklung.
## 1. Neue Komponenten (Seit v2.2.0)
### A. Feedback Service (`app/services/feedback_service.py`)
- **Zweck:** Logging von Trainingsdaten für späteres Self-Tuning (WP-08).
- **Storage:** Lokale JSONL-Dateien in `data/logs/` (Append-Only).
- `search_history.jsonl`: Query + Snapshot der Ergebnisse (Scores).
- `feedback.jsonl`: User-Rating zu spezifischer `node_id`.
### B. Explanation Layer (`app/core/retriever.py`)
- **Logik:** Der Retriever berechnet nicht nur Scores, sondern generiert `Explanation`-Objekte.
- **Graph:** `Subgraph` (in `graph_adapter.py`) führt jetzt auch `reverse_adj` (Incoming Edges), um zu erklären, warum ein Knoten wichtig ist ("Referenziert von...").
### C. DTOs (`app/models/dto.py`)
Das Datenmodell wurde massiv erweitert. Wichtige Klassen für WP-05:
- `QueryResponse`: Enthält jetzt `query_id` (UUID).
- `QueryHit`: Enthält optional `explanation` (Typ `Explanation`).
- `FeedbackRequest`: Für den Feedback-Loop.
## 2. Implikationen für WP-05 (Chat)
1. **Logging:** Auch der neue `/chat` Endpoint sollte idealerweise die `query_id` loggen oder nutzen, um Konsistenz zu wahren.
2. **DTO-Nutzung:** Der Chat-Service wird intern den Retriever aufrufen. Er muss mit den `QueryHit`-Objekten arbeiten, um den Kontext für das LLM zu bauen.
3. **Config:** Die Persönlichkeit wird in `config/prompts.yaml` definiert (Late Binding), nicht im Python-Code hardcodiert.
+307
View File
@@ -0,0 +1,307 @@
# mindnet v2 — Dokumentationsreview (vollständig & konsolidiert)
Dieses Dokument fasst alle notwendigen Anpassungen der mindnet-v2 Dokumentation zusammen.
Der Fokus liegt ausschließlich auf Aspekten, die durch die aktuellen Arbeiten verändert wurden:
- neue Edge-Mechanik
- neuer Importer
- neues Verhalten von note_payload & chunk_payload
- Default-Typregeln aus `types.yaml`
- Inline- und Callout-Relations
- WP04a – Einführung der Retriever-Schicht
- neue Diagnose- und Testskripte
Es handelt sich um eine strukturelle Analyse.
Nichts davon überschreibt bestehende Inhalte — es markiert nur, **was angepasst werden muss**.
---
# 1) knowledge_design.md
## Erforderliche Anpassungen
### 1.1 Neue Edge-Arten dokumentieren
Es müssen vier neue Kategorien beschrieben werden:
1. **Inline-Edges**
Beispiel:
`[ [rel:depends_on Embeddings 101] ]`
(Leerzeichen hier zur Demonstration; im echten Dokument ohne Leerzeichen)
2. **Callout-Edges**
> [!edge] related_to: [[Vector DB Basics]] [[Embeddings 101]]
3. **Typbasierte Default-Kanten**
Aus `types.yaml` → `edge_defaults`
4. **Strukturkanten**
- belongs_to
- next
- prev
### 1.2 Neue Edge-Felder ergänzen
Jeder Edge enthält jetzt:
- `rule_id`
- `confidence`
- `scope = "chunk"`
- deterministischer `edge_id`
Diese Felder müssen vollständig erklärt werden.
### 1.3 Chunk-basierte Kanten
Neu: **Alle Kanten entstehen ausschließlich zwischen Chunks**, nie zwischen Notes.
Notes dienen nur noch als Metadatencontainer.
---
# 2) TYPE_REGISTRY_MANUAL.md
## Erforderliche Anpassungen
### 2.1 Typauflösung dokumentieren
Die Regeln sind jetzt:
- Typ aus Frontmatter → höchste Priorität
- Falls nicht gesetzt: Typ aus Dateipfad ableiten
- Falls unbekannt: Fallback auf `types.default`
- Typ definiert:
- retriever_weight
- chunk_profile
- edge_defaults
Diese müssen klar dokumentiert werden.
### 2.2 Neue Fallback-Regeln
Wenn Werte fehlen, werden sie ersetzt durch:
types.default.retriever_weight
types.default.chunk_profile
types.default.edge_defaults
### 2.3 Beispiele aktualisieren
Alle Beispiele müssen auf die neue Inline-Syntax angepasst werden.
---
# 3) wp04_retriever_scoring.md
## Erforderliche Anpassungen
### 3.1 Neue Scoring-Formel
total_score =
semantic_weight * semantic_score
+ edge_weight * edge_bonus
+ centrality_weight * centrality_bonus
+ type_weight * retriever_weight
### 3.2 Bedeutung von `confidence`
confidence wirkt multiplikativ bei edge_bonus.
Inline > Callout > Default (Standardwerte im Code hinterlegt).
### 3.3 Pfadbegründungen
Der Retriever gibt optional `paths[]` zurück:
paths: [
{
"via": "depends_on",
"confidence": 0.7,
"hops": ["Note A", "Chunk A#01", "Note B"]
}
]
Diese Funktion müssen dokumentiert werden.
---
# 4) mindnet_v2_implementation_playbook.md
## Erforderliche Anpassungen
### 4.1 Neuer Import-Prozess vollständig dokumentieren
Der Importer läuft jetzt so:
1. Markdown lesen
2. Frontmatter extrahieren
3. Typauflösung via `types.yaml`
4. Note-Payload generieren
5. Chunking anwenden
6. Inline-Kanten finden
7. Callout-Kanten finden
8. Default-Edges erzeugen
9. Strukturkanten erzeugen
10. Chunks in Qdrant upserten
11. Edges upserten
12. Diagnose laufen lassen:
python3 -m scripts.payload_dryrun
python3 -m scripts.edges_full_check
### 4.2 Erweiterte Testpipeline
Neu zu dokumentieren:
tests.test_edges_all
scripts.edges_full_check
scripts.payload_dryrun
Diese Testschritte sind jetzt Standardanforderung nach jeder Änderung.
---
# 5) mindnet_technical_architecture.md
## Erforderliche Anpassungen
### 5.1 Aktualisiertes Schema für Qdrant Collections
#### Notes:
note_id
title
type
fulltext
retriever_weight
chunk_profile
edge_defaults
tags
updated
#### Chunks:
chunk_id
note_id
text
window
ord
retriever_weight
chunk_profile
neighbors_prev
neighbors_next
#### Edges:
edge_id
source_id
target_id
kind
scope = "chunk"
rule_id
confidence
### 5.2 Dokumentation der Edge-Pipeline
Neu beschreiben:
- Inline-Parser
- Callout-Parser
- Default-Edge-Resolver
- Strukturkanten
- Normalisierung für Qdrant
- deterministische ID-Bildung
---
# 6) mindnet_functional_architecture.md
## Erforderliche Anpassungen
### 6.1 Inline-Relations – einzig gültige Syntax
Nur diese Syntax erzeugt Kanten:
[[rel:depends_on Embeddings 101]]
Nicht unterstützt:
rel:depends_on [[Embeddings 101]]
Dies muss klar dokumentiert werden.
### 6.2 Prioritäten der Kantenerzeugung
Gültige Reihenfolge:
1. Inline
2. Callout
3. Typdefaults
4. Strukturkanten
### 6.3 Relaunch der Chunk-zentrierten Funktionslogik
Alle Beispiele müssen angepasst werden.
---
# 7) chunking_strategy.md
## Erforderliche Änderungen
### 7.1 Neues Verhalten der Chunks
- `ord` ist jetzt Sortierkriterium
- `window` wird über chunk_config erzeugt
- Chunkprofile kommen ausschließlich aus `types.yaml`
### 7.2 Best Practices erneuern
Empfehlung:
- keine manuelle Chunkprofile mehr im Frontmatter setzen
---
# 8) docs_mindnet_retriever.md
## Erforderliche Änderungen
### 8.1 Neue Ausgabeparameter dokumentieren
Retriever liefert jetzt:
semantic_score
edge_bonus
centrality_bonus
type_score
total_score
paths[]
### 8.2 Graph-Expansion
Dokumentieren:
- Seed-Auswahl
- Depth-Limit
- Edge-Filterung
- Wirkung von `confidence` auf edge_bonus
---
# 9) Handbuch.md
## Erforderliche Änderungen
### 9.1 Neuer Import-Workflow
Erläuterung der Parser:
- Inline-Parser
- Callout-Parser
- Default-Kanten
- Struktur-Kanten
### 9.2 Best Practices
Ergänzen:
- Typenpflege erfolgt nur in `types.yaml`
- Tests immer nach Änderungen ausführen
---
# Gesamtübersicht der notwendigen Anpassungen
| Dokument | Anpassungsbedarf |
|---------|------------------|
| knowledge_design.md | neue Edge-Arten, Felder, Chunk-Edges |
| TYPE_REGISTRY_MANUAL.md | Typauflösung, neue Felder, neue Fallbacks |
| wp04_retriever_scoring.md | neue Score-Formel, Pfade, confidence |
| implementation_playbook.md | neuer Importprozess, Tests |
| technical_architecture.md | aktualisierte Schemas |
| functional_architecture.md | Syntax + Prioritäten |
| chunking_strategy.md | ord, window, neue Profile |
| docs_mindnet_retriever.md | neue API-Parameter |
| Handbuch.md | Parser + Best Practices |
---
# Empfehlung zur Umsetzung
1. Dieses Review-Dokument als Master-Referenz verwenden.
2. Jedes Dokument strikt nur an den beschriebenen Stellen anpassen.
3. Überprüfen, ob Wann/Wo Typen, Kanten und Parser erklärt werden.
4. Nach jeder Anpassung Testlauf:
python3 -m scripts.payload_dryrun
python3 -m scripts.edges_full_check
5. Danach Playbook + Programmplan updaten.
+322
View File
@@ -0,0 +1,322 @@
# mindnet – Änderungs- und Ergänzungsleitfaden für bestehende Dokumentation
# (Stand: Tag Wp04a-Retriever_final)
Dieser Leitfaden listet **alle notwendigen Änderungen und Ergänzungen** für die
bestehenden Dokumente auf. Er umfasst ausschließlich Inhalte, die durch die
tatsächliche Implementierung von WP-04a (Retriever, Hybrid Scoring, Graph-Integration,
retriever.yaml, Explainability-Vorbereitung, Centrality, Edge-Bonus, Query-API)
betroffen sind.
Er dient dazu, dass ein anderer Chat alle Dokumente vollständig und korrekt
überarbeiten kann, ohne Interpretationsspielraum oder fehlende Informationen.
============================================================
# 1. Änderungen für: knowledge_design.md
============================================================
## 1.1 Ergänzen: Rolle von retriever_weight pro Note-Type
Die Implementierung nutzt `retriever_weight`, das im Importer aus `types.yaml`
pro Note-Type übernommen und auf *Chunk-Ebene* vererbt wird.
**Ergänzen:**
- Erklärung, dass `retriever_weight` ein konzeptionelles Typ-Attribut ist,
das im hybriden Scoring als Multiplikator wirkt.
- Klarstellung, dass `retriever_weight` *nicht* durch Markdown-Frontmatter
überschrieben werden muss.
- Dokumentation, dass Qdrant-Payload dieses Feld für Notes und Chunks enthält.
## 1.2 Ergänzen: Edge-Typen, die im Retriever genutzt werden
Der Retriever unterstützt aktuell:
- `references`
- `related_to`
- `depends_on`
- `similar_to`
- `belongs_to`
- sowie generierte Strukturkanten `next` / `prev`.
**Ergänzen:**
- Welche Edges für den Graph-Bonus ausgewertet werden.
- Wie `confidence` aus mindnet_edges genutzt wird.
## 1.3 Ergänzen: Definition des lokalen Subgraphen
Die reale Retrieval-Logik nutzt:
- Seed-Notes (aus semantisch Top-K)
- Expansionstiefe `depth`
- Edge-Typ-Filter
- Bonusberechnung pro Knoten
Dies ist im ursprünglichen Dokument nicht beschrieben und muss hinzugefügt werden.
============================================================
# 2. Änderungen für: chunking_strategy.md
============================================================
## 2.1 Ergänzen: Chunk-Payload-Felder, die der Retriever nutzt
Die aktuelle Strategy beschreibt Chunks korrekt, es fehlt jedoch:
**Ergänzen:**
- `retriever_weight` (vererbt vom Note-Type)
- `chunk_profile` (aktuell ungenutzt im Retriever, aber Teil der Payload)
- Hinweise, dass der Retriever nur aus *Chunks* semantische Seeds bildet,
das Ranking aber auf *Notes* aggregiert wird.
## 2.2 Ergänzen: Section/Window-Felder und ihre Relevanz
Die Felder existieren im Qdrant, werden aber im retriever.yaml nicht verändert.
**Hinweis ergänzen:**
- Der Retriever nutzt aktuell `text` und `window`; kein Einfluss der Abschnittslogik.
============================================================
# 3. Änderungen für: TYPE_REGISTRY_MANUAL.md
============================================================
Dieses Dokument muss **aktualisiert** werden, da WP-04a folgende Mechanismen nutzt:
## 3.1 Ergänzen: Bedeutung von retriever_weight
- Definition als quantitatives Typ-Merkmal.
- Erklärung, dass es in Qdrant gespeichert wird.
- Erklärung des Einflusses auf Semantikscore:
- Formel:
final_semantic = semantic_score * retriever_weight
- Hinweis, dass in future WP-08 das Gewicht durch Feedback lernbar wird.
## 3.2 Ergänzen: Neue Edge-Typen und ihre Standard-Konfiguration
- `similar_to`
- `belongs_to`
- Strukturkanten `next` / `prev`
Diese sind im Importer bereits aktiv, aber nicht ausreichend dokumentiert.
## 3.3 Ergänzen: Edge-Konfidenzen
Die automatische Edge-Ableitung generiert `confidence`.
Retriever nutzt diesen Wert linear im Edge-Bonus.
**Dokumentation muss ergänzt werden.**
============================================================
# 4. Änderungen für: docs_mindnet_retriever.md
============================================================
Dieses Dokument ist am stärksten betroffen und muss auf den Stand der tatsächlichen
Implementierung aktualisiert werden.
## 4.1 Aktualisieren: Gesamtscoring-Formel
Bisher: Semantik + einfache Typgewichtung.
Neu implementiert:
total_score =
semantic_weight * semantic_score
+ edge_weight * edge_bonus
+ centrality_weight * centrality_bonus
Diese Formel muss vollständig dokumentiert werden.
## 4.2 Aktualisieren: Einführung retriever.yaml
Dokumentation benötigt:
- Speicherort: `app/config/retriever.yaml`
- Default-Werte
- Abschnittsweise Beschreibung:
- semantic_weight
- edge_weight
- centrality_weight
- Hinweis: Änderungen wirken ohne Codeänderung.
## 4.3 Ergänzen: Beschreibung Graph-Expansion
Der Retriever nutzt:
- Expand-depth (default 1)
- Edge-Typ-Filter
- Aggregation pro Node
- Bonus-Skalierung
Diese Logik ist neu und muss detailliert erklärt werden.
## 4.4 Ergänzen: Beschreibung centrality_bonus
Aktuell:
- proportionale Verteilung anhand Knotendichte
- Normalisierung über lokales Subgraph-Maß
Dokumentation muss Minimum enthalten:
- wie centrality gewichtet wird
- welche Grenze existieren
## 4.5 Ergänzen: Explainability-Schnittstelle (WP-04b Vorbereitung)
Die Implementierung erzeugt intern:
- edge_bonus pro Node
- centrality_bonus pro Node
- Liste der Edges, die beteiligt waren
Diese Werte sind abrufbar und müssen dokumentiert werden.
## 4.6 Ergänzen: Fehlertoleranzen & Timeout (Health Check)
Der Retriever kann:
- Fallback auf Vektor-Suche (pure semantic)
- Fallback bei fehlendem expand
Diese Sicherheitsmechanismen müssen dokumentiert werden.
============================================================
# 5. Änderungen für: mindnet_technical_architecture.md
============================================================
## 5.1 Ergänzen: Komponentenübersicht Retrieval-Layer
Eine neue Abbildung oder Abschnitt muss hinzu:
- QueryRequest-Parsing
- Embedding-Lookup oder Vector-Passthrough
- Semantic Seed Search (Qdrant)
- Graph-Expansion (mindnet_edges)
- Node-/Note-Aggregation
- Score-Combination
- Response-Ausgabe via FastAPI
## 5.2 Ergänzen: Datenstruktur mindnet_edges
Vor WP-04 nicht vollständig dokumentiert.
Benötigt:
- Felder:
- edge_id
- kind
- source_id
- target_id
- confidence
- rule_id
- Wie Edges im Retriever ausgewertet werden.
## 5.3 Ergänzen: retriever.yaml als Konfigurationsquelle
Architekturdiagramm muss updated werden:
- Retriever nutzt YAML
- Keine Hardcodierung im Python
## 5.4 Ergänzen: Health Check Script
Technischer Abschnitt muss dokumentieren:
- health_check_mindnet.py
- Semantik:
- semantic query
- hybrid query
- Fehlercodes
============================================================
# 6. Änderungen für: mindnet_functional_architecture.md
============================================================
## 6.1 Ergänzen: Funktionale Rolle des Retrievers
Retriever ist jetzt:
- Teil des Functional Layers
- Grundlage für Agenten / Decision Engine
- Hauptquelle für Begründungen
## 6.2 Ergänzen: Einbindung des Explainability-Layers
Funktional gehört dies zwischen:
- Retriever
- Antwortgenerierung (LLM)
Der Explainability-Layer formuliert Gründe:
- Welche Edges?
- Welche Scores?
- Warum diese Note?
## 6.3 Ergänzen: Self-Tuning als neuen Funktionsblock (WP-08)
Muss aufgenommen werden:
- Logging von Feedback
- Bewertung
- Tuning der retriever.yaml
- Human-in-the-loop Freigabe
============================================================
# 7. Änderungen für: wp04_retriever_scoring.md
============================================================
Dieses Dokument ist **direkt WP-04** und muss am stärksten überarbeitet werden.
## 7.1 Aktualisieren: Finale Scoring-Formel
Die Formel muss exakt so dokumentiert werden, wie inzwischen implementiert.
## 7.2 Ergänzen: Bonusberechnung
Die bisherige Planung wurde implementiert, aber der Text muss aktualisiert werden:
- Bonusberechnung je Edge
- confidence-Einfluss
- Node-Aggregation
- Note-Aggregation
## 7.3 Ergänzen: Centrality
Dokument ist zu ergänzen um:
- Definition
- Berechnung
- Normalisierung
- Gewichtung über retriever.yaml
## 7.4 Ergänzen: Teststrategie
Die finale Testbasis muss dokumentiert werden:
- Unit-Tests
- Hybrid-Tests
- API-Tests
- Smoke-Test
- Diagnose-Skripte
## 7.5 Ergänzen: Einschränkungen & Offene Punkte
Hinweis für WP-04b:
- Explainability fehlt noch
- Edge-Type Weights noch nicht implementiert
- Self-Tuning in WP-08
============================================================
# 8. Änderungen für: mindnet_v2_implementation_playbook.md
============================================================
## 8.1 Ergänzen: Arbeitsablauf mit Retriever
Einrichtung, Nutzung und Test sollte ergänzt werden:
- Starten von FastAPI
- Testen des Retrievers via health_check
- Import-Workflow (neue Vaults → Qdrant → Retriever)
## 8.2 Ergänzen: Konfigurationsverwaltung
Einbindung in Gitea-Workflows:
- retriever.yaml versionieren
- Tags/Branches für Funktionsstände setzen
## 8.3 Ergänzen: Self-Tuning-Prozess (nur Rahmen)
Der Playbook-Abschnitt soll die späteren Mechanismen vorbeschreiben.
============================================================
# 9. Änderungen für: Handbuch.md
============================================================
## 9.1 Ergänzen: Einfache Erklärung des Retrievers
Das Handbuch benötigt eine verständliche, nicht-technische Beschreibung:
- Was macht der Retriever?
- Warum kommt ein Ergebnis zustande?
- Welche Rolle spielen Edges?
- Wie kann der Nutzer die Gewichtung beeinflussen (YAML)?
## 9.2 Ergänzen: Troubleshooting
Aufnehmen:
- „Ergebnisse wirken unpassend“ → Prüfe retriever.yaml
- „Edge-Bonus fehlt“ → Prüfe mindnet_edges
- health_check-Skript nutzen
## 9.3 Ergänzen: API-Nutzung für Endanwender
Einfacher Abschnitt:
- Wie man `/query` testet
- Beispiele für semantic & hybrid queries
+26 -34
View File
@@ -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://<IP>: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.
+30 -10
View File
@@ -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):**
+42 -15
View File
@@ -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).
---
<details>
@@ -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.** |
| **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.** |
+43 -28
View File
@@ -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 (`<prefix>_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) |
+35 -15
View File
@@ -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.** |
| **WP10a**| Draft Editor | 🟢 Live | **Interaktives UI für WP07 Drafts.** |
| **WP11** | Backend Intelligence | 🟢 Live | **Async Ingestion, Nomic Embeddings, Matrix Logic.** |
+16 -4
View File
@@ -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.
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.