Dokumentation WP10
This commit is contained in:
parent
38abde8516
commit
be406d230f
|
|
@ -1,6 +1,6 @@
|
|||
# mindnet v2.2 — Programmplan
|
||||
**Version:** 2.3.1 (Post-WP06 Decision Engine)
|
||||
**Stand:** 2025-12-09
|
||||
**Version:** 2.3.2 (Inkl. WP-10a GUI Evolution)
|
||||
**Stand:** 2025-12-10
|
||||
**Status:** Aktiv
|
||||
|
||||
---
|
||||
|
|
@ -27,7 +27,8 @@
|
|||
- [WP-07 – Interview-Assistent (geplant)](#wp-07--interview-assistent-geplant)
|
||||
- [WP-08 – Self-Tuning v1/v2 (geplant)](#wp-08--self-tuning-v1v2-geplant)
|
||||
- [WP-09 – Vault-Onboarding \& Migration (geplant)](#wp-09--vault-onboarding--migration-geplant)
|
||||
- [WP-10 – Chat-Interface \& Writeback (geplant)](#wp-10--chat-interface--writeback-geplant)
|
||||
- [WP-10 – Chat-Interface \& Writeback (abgeschlossen)](#wp-10--chat-interface--writeback-abgeschlossen)
|
||||
- [WP-10a – GUI Evolution: Interaktion \& Tools (geplant)](#wp-10a--gui-evolution-interaktion--tools-geplant)
|
||||
- [WP-11 – Knowledge-Builder \& Vernetzungs-Assistent (geplant)](#wp-11--knowledge-builder--vernetzungs-assistent-geplant)
|
||||
- [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)
|
||||
|
|
@ -115,7 +116,8 @@ Kernprinzipien der Vision:
|
|||
- **RAG-Chat:** KI antwortet in natürlicher Sprache auf Basis von Wissen und Persönlichkeit (WP-05 abgeschlossen).
|
||||
- **Decision Engine:** System erkennt Intent (Fakt vs. Entscheidung) und wägt Werte ab (WP-06 abgeschlossen).
|
||||
- **Multi-Persona:** System wechselt den Tonfall (Empathisch vs. Analytisch) situativ (WP-06 abgeschlossen).
|
||||
- Technische Basis: FastAPI, Qdrant, Ollama (Local LLM).
|
||||
- **Chat Interface:** Web-basiertes Frontend (Streamlit) für einfache Interaktion und Feedback-Gabe (WP-10 abgeschlossen).
|
||||
- Technische Basis: FastAPI, Qdrant, Ollama (Local LLM), Streamlit.
|
||||
- Automatisierte Erkennung von Beziehungen:
|
||||
- Wikilinks, Inline-Relationen, Callout-Edges, Typ-Defaults.
|
||||
- „Mitwachsendes“ Schema ohne Obsidian-Umstrukturierungen:
|
||||
|
|
@ -124,10 +126,10 @@ Kernprinzipien der Vision:
|
|||
|
||||
### 3.2 Mittelfristig (Nächste Schritte)
|
||||
|
||||
- **Chat Interface (WP-10):** Ablösung der Terminal-Interaktion durch ein Web-Frontend (Streamlit/React) für bessere UX und einfacheres Feedback-Geben.
|
||||
- Interview-Assistent erstellt neue Notes automatisch (strukturierte Dialoge → Markdown).
|
||||
- **Interview-Assistent (WP-07):** Geführte Dialoge zur Erfassung neuer Notizen (Startbereit).
|
||||
- mindnet erzeugt Vorschläge für neue Notes & Edges und bietet einen „Vernetzungs-Assistenten“ für manuell angelegte Notizen.
|
||||
- Agenten können über MCP-Tools (`mindnet_query`, `mindnet_chat`) auf mindnet zugreifen.
|
||||
- Self-Tuning optimiert die Gewichte in `retriever.yaml` basierend auf dem gesammelten Feedback (WP-08).
|
||||
|
||||
### 3.3 Langfristig
|
||||
|
||||
|
|
@ -189,10 +191,10 @@ Die folgenden Prinzipien steuern alle Workpackages und Entscheidungen:
|
|||
Phase A – Fundament & Import (Fertig)
|
||||
Phase B – Semantik, Graph & Lernen (Fertig)
|
||||
Phase C – Persönlichkeitsmodell & KI-Zwilling (Fertig)
|
||||
Phase D – Agenten, MCP & Interaktion (Startend)
|
||||
Phase D – Agenten, MCP & Interaktion (Laufend)
|
||||
Phase E – Review, Refactoring, Dokumentation
|
||||
|
||||
Alle Workpackages sind einer Phase zugeordnet. WP-01 bis WP-06 sind bereits erfolgreich abgeschlossen.
|
||||
Alle Workpackages sind einer Phase zugeordnet. WP-01 bis WP-06 und WP-10 sind bereits erfolgreich abgeschlossen.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -354,15 +356,15 @@ Transformation vom reinen Wissens-Abrufer zum strategischen Entscheidungspartner
|
|||
|
||||
### WP-07 – Interview-Assistent (geplant)
|
||||
|
||||
**Phase:** C
|
||||
**Status:** 🟡 geplant
|
||||
**Phase:** C/D
|
||||
**Status:** 🟡 geplant (Nächster Fokus)
|
||||
|
||||
**Ziel:**
|
||||
Dialogbasierter Erfassungs-Assistent, der strukturierte Interviews führt und daraus konsistente Markdown-Notizen generiert.
|
||||
|
||||
**Umfang:**
|
||||
- Design von Interview-Flows.
|
||||
- Konvertierung von Dialogtranskripten in typisierte Notes.
|
||||
- Design von Interview-Flows (via Router-Strategie `INTERVIEW`).
|
||||
- Konvertierung von Dialogtranskripten in typisierte Notes (Draft-Erstellung).
|
||||
|
||||
**Aufwand / Komplexität:**
|
||||
- Aufwand: Niedrig/Mittel
|
||||
|
|
@ -406,25 +408,46 @@ Sicherstellen, dass bestehende und neue Obsidian-Vaults schrittweise in mindnet
|
|||
|
||||
---
|
||||
|
||||
### WP-10 – Chat-Interface & Writeback (geplant)
|
||||
### WP-10 – Chat-Interface & Writeback (abgeschlossen)
|
||||
|
||||
**Phase:** D
|
||||
**Status:** 🟡 geplant (Priorität B - "Quick Win")
|
||||
**Status:** 🟢 abgeschlossen
|
||||
|
||||
**Ziel:**
|
||||
Ablösung der Terminal-Interaktion durch ein grafisches Interface.
|
||||
|
||||
**Umfang:**
|
||||
- Technologie: Streamlit oder einfaches HTML/JS Frontend.
|
||||
- Funktionen: Chat-Verlauf, Anzeige der Quellen (mit Scores), Daumen-hoch/runter für WP-04c Feedback.
|
||||
- Funktionen für Q&A sowie Vorschlag neuer Notes/Edges.
|
||||
**Erreichte Ergebnisse:**
|
||||
- **Tech-Stack:** Streamlit Frontend (`app/frontend/ui.py`).
|
||||
- **Funktionen:** Chat-Verlauf, Visualisierung von Intents und Quellen (Expander).
|
||||
- **Feedback:** Globales Rating (Sterne) und granulare Quellen-Bewertung (Faces).
|
||||
- **Writeback:** Mockup-Interface für neue Einträge (Vorbereitung WP-07).
|
||||
- **Deployment:** Systemd-Services für Prod (8501) und Dev (8502).
|
||||
|
||||
**Aufwand / Komplexität:**
|
||||
- Aufwand: Hoch (durch Writeback) / Mittel (für reines Frontend)
|
||||
- Aufwand: Hoch
|
||||
- Komplexität: Hoch
|
||||
|
||||
---
|
||||
|
||||
### WP-10a – GUI Evolution: Interaktion & Tools (geplant)
|
||||
|
||||
**Phase:** D
|
||||
**Status:** 🟡 geplant (nach WP07/11)
|
||||
|
||||
**Ziel:**
|
||||
Anpassung der GUI an komplexe Interaktionsmuster, die durch den Interview-Assistenten und Knowledge-Builder entstehen.
|
||||
|
||||
**Umfang:**
|
||||
- **Draft-Editor:** Interaktive Bearbeitung und Bestätigung der Markdown-Entwürfe aus WP-07.
|
||||
- **Suggestion-UI:** Checkboxen/Toggles für Kanten-Vorschläge aus WP-11 (Human-in-the-Loop).
|
||||
- **Writeback:** Physisches Speichern der bestätigten Inhalte im Vault.
|
||||
|
||||
**Aufwand / Komplexität:**
|
||||
- Aufwand: Mittel
|
||||
- Komplexität: Mittel
|
||||
|
||||
---
|
||||
|
||||
### WP-11 – Knowledge-Builder & Vernetzungs-Assistent (geplant)
|
||||
|
||||
**Phase:** D
|
||||
|
|
@ -489,6 +512,7 @@ Aufräumen, dokumentieren, stabilisieren – insbesondere für Onboarding Dritte
|
|||
WP01 → WP02 → WP03 → WP04a
|
||||
WP04a → WP04b → WP04c → WP08
|
||||
WP03 → WP05 → WP06 → WP07
|
||||
WP07/WP11 → WP10a
|
||||
WP03 → WP09
|
||||
WP01/WP03 → WP10 → WP11 → WP12
|
||||
WP03/WP04 → WP13
|
||||
|
|
@ -508,6 +532,7 @@ Aufräumen, dokumentieren, stabilisieren – insbesondere für Onboarding Dritte
|
|||
| WP08 | Hoch | Hoch |
|
||||
| WP09 | Mittel | Niedrig/Mittel |
|
||||
| WP10 | Hoch | Hoch |
|
||||
| WP10a | Mittel | Mittel |
|
||||
| WP11 | Hoch | Hoch |
|
||||
| WP12 | Niedrig/Mittel | Mittel |
|
||||
| WP13 | Mittel | Mittel |
|
||||
|
|
@ -531,7 +556,8 @@ Aufräumen, dokumentieren, stabilisieren – insbesondere für Onboarding Dritte
|
|||
| WP07 | 🟡 |
|
||||
| WP08 | 🟡 |
|
||||
| WP09 | 🟡 |
|
||||
| WP10 | 🟡 |
|
||||
| WP10 | 🟢 |
|
||||
| WP10a | 🟡 |
|
||||
| WP11 | 🟡 |
|
||||
| WP12 | 🟡 |
|
||||
| WP13 | 🟡 |
|
||||
|
|
@ -559,6 +585,7 @@ mindnet v2.2 ist so aufgesetzt, dass:
|
|||
- ein **hybrider Retriever** qualitativ hochwertige, erklärbare Antworten liefert,
|
||||
- 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) existiert, die komplexe Zusammenhänge (Intents, Quellen) visualisiert,
|
||||
- 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.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
# mindnet v2.2 – Knowledge Design Manual
|
||||
**Datei:** `docs/mindnet_knowledge_design_manual_v2.2.md`
|
||||
**Stand:** 2025-12-09
|
||||
**Status:** **FINAL** (Integrierter Stand WP01–WP06)
|
||||
**Stand:** 2025-12-10
|
||||
**Status:** **FINAL** (Integrierter Stand WP01–WP10)
|
||||
**Quellen:** `knowledge_design.md`, `TYPE_REGISTRY_MANUAL.md`, `chunking_strategy.md`, `mindnet_functional_architecture.md`.
|
||||
|
||||
---
|
||||
|
|
@ -27,6 +27,7 @@ Mindnet ist mehr als eine Dokumentablage. Es ist ein vernetztes System, das dein
|
|||
Seit Version 2.3.1 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.
|
||||
|
||||
### 1.2 Der Vault als „Source of Truth“
|
||||
Die Markdown-Dateien in deinem Vault sind die **einzige Quelle der Wahrheit**.
|
||||
|
|
@ -194,6 +195,11 @@ Erstelle Notizen mit `type: experience`. Nutze im Text **emotionale Brückenwör
|
|||
|
||||
*Effekt:* Wenn du im Chat jammerst ("Alles ist sinnlos"), findet das System diese Notiz und spiegelt dir deine eigene Erfahrung zurück.
|
||||
|
||||
### 5.3 Schreiben für den Chat (UI Optimization)
|
||||
Da deine Notizen im Web-Interface (WP10) angezeigt werden:
|
||||
* **Kurze Absätze:** Das LLM liest besser, und der Mensch scannt schneller.
|
||||
* **Klare Headings:** Nutze H1/H2, um dem Chunker logische Trennlinien zu geben.
|
||||
|
||||
---
|
||||
|
||||
## 6. Best Practices & Beispiele (Klassik)
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
# Mindnet v2.2 – Overview & Einstieg
|
||||
**Datei:** `docs/mindnet_overview_v2.2.md`
|
||||
**Stand:** 2025-12-09
|
||||
**Status:** **FINAL** (Post-WP06 Release)
|
||||
**Stand:** 2025-12-10
|
||||
**Status:** **FINAL** (Post-WP10 Release)
|
||||
**Version:** 2.3.1
|
||||
|
||||
---
|
||||
|
|
@ -39,7 +39,8 @@ Mindnet arbeitet auf drei Schichten, die aufeinander aufbauen:
|
|||
### Ebene 3: Identität (Die Persönlichkeit)
|
||||
* **Funktion:** Interaktion und Bewertung. Das System nimmt eine Haltung ein.
|
||||
* **Logik:** "Ich empfehle Lösung X, weil sie unserem Wert 'Datensparsamkeit' entspricht."
|
||||
* **Technik:** * **Intent Router:** Erkennt Absichten (Fakt vs. Gefühl vs. Entscheidung).
|
||||
* **Technik:**
|
||||
* **Intent Router:** Erkennt Absichten (Fakt vs. Gefühl vs. Entscheidung).
|
||||
* **Strategic Retrieval:** Lädt gezielt Werte oder Erfahrungen nach.
|
||||
* **Multi-Persona:** Passt den Tonfall an.
|
||||
* **Status:** 🟢 Live (WP05–WP06).
|
||||
|
|
@ -61,7 +62,7 @@ Der Datenfluss in Mindnet ist zyklisch ("Data Flywheel"):
|
|||
* **Backend:** Python 3.12, FastAPI.
|
||||
* **Datenbank:** Qdrant (Vektor & Graph).
|
||||
* **KI:** Ollama (Phi-3 Mini / Mistral) – 100% lokal.
|
||||
* **Frontend:** Terminal (aktuell) / Web-UI (geplant WP10).
|
||||
* **Frontend:** Streamlit Web-UI (v2.3.1).
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -91,5 +92,5 @@ Wo findest du was?
|
|||
|
||||
## 6. Aktueller Fokus
|
||||
|
||||
Wir haben **Phase C (Persönlichkeit)** mit WP06 (Decision Engine) abgeschlossen.
|
||||
Das System kann nun strategisch denken und fühlen. Als Nächstes folgt **Phase D (Interaktion)** mit dem **Chat Interface (WP10)** für bessere Usability.
|
||||
Wir haben **Phase D (Interaktion)** mit WP10 (Chat Interface) begonnen und die UI erfolgreich deployed.
|
||||
Das System ist nun für Endnutzer bedienbar. Als Nächstes folgt der **Interview-Assistent (WP07)**, um Wissen dialogisch zu erfassen.
|
||||
|
|
@ -1,19 +1,19 @@
|
|||
# Mindnet v2.2 – Admin Guide
|
||||
**Datei:** `docs/mindnet_admin_guide_v2.2.md`
|
||||
**Stand:** 2025-12-09
|
||||
**Status:** **FINAL** (Inkl. RAG, Decision Engine & LLM Ops)
|
||||
**Stand:** 2025-12-10
|
||||
**Status:** **FINAL** (Inkl. Frontend Deployment)
|
||||
**Quellen:** `Handbuch.md`, `mindnet_developer_guide_v2.2.md`.
|
||||
|
||||
> Dieses Handbuch richtet sich an **Administratoren**. Es beschreibt Installation, Konfiguration, Backup-Strategien, Monitoring und den sicheren Betrieb der Mindnet-Instanz (API + DB + LLM).
|
||||
> Dieses Handbuch richtet sich an **Administratoren**. Es beschreibt Installation, Konfiguration, Backup-Strategien, Monitoring und den sicheren Betrieb der Mindnet-Instanz (API + UI + DB).
|
||||
|
||||
---
|
||||
|
||||
## 1. Zielgruppe & Scope
|
||||
|
||||
Mindnet ist als **Single-Node System** konzipiert, das lokal (z.B. Laptop) oder auf einem privaten Server (Homelab, Intranet) läuft.
|
||||
Mindnet ist als **Multi-Service-Architektur** konzipiert, die lokal oder auf einem privaten Server läuft.
|
||||
Wir unterscheiden strikt zwischen:
|
||||
* **Production (Port 8001):** Stabiler `main` Branch.
|
||||
* **Development (Port 8002):** Experimentelle Feature-Branches.
|
||||
* **Production:** Backend (8001) + Frontend (8501). Stabiler `main` Branch.
|
||||
* **Development:** Backend (8002) + Frontend (8502). Experimentelle Feature-Branches.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -36,9 +36,11 @@ Wir unterscheiden strikt zwischen:
|
|||
# 2. Umgebung einrichten
|
||||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
|
||||
# 3. Dependencies installieren (inkl. Streamlit)
|
||||
pip install -r requirements.txt
|
||||
|
||||
# 3. Verzeichnisse anlegen
|
||||
# 4. Verzeichnisse anlegen
|
||||
mkdir -p logs qdrant_storage data/logs
|
||||
|
||||
### 2.3 Qdrant Setup (Docker)
|
||||
|
|
@ -55,7 +57,7 @@ Wir nutzen Qdrant als Vektor-Datenbank. Persistenz ist wichtig.
|
|||
Mindnet benötigt einen lokalen LLM-Server für den Chat.
|
||||
|
||||
# 1. Installieren (Linux Script)
|
||||
curl -fsSL https://ollama.com/install.sh | sh
|
||||
curl -fsSL [https://ollama.com/install.sh](https://ollama.com/install.sh) | sh
|
||||
|
||||
# 2. Modell laden (Phi-3 Mini für CPU-Performance)
|
||||
ollama pull phi3:mini
|
||||
|
|
@ -75,24 +77,64 @@ Erstelle eine `.env` Datei im Root-Verzeichnis. Die neuen Settings für WP-06 (T
|
|||
|
||||
# LLM / RAG Settings
|
||||
MINDNET_LLM_MODEL="phi3:mini"
|
||||
MINDNET_OLLAMA_URL="http://127.0.0.1:11434"
|
||||
MINDNET_OLLAMA_URL="[http://127.0.0.1:11434](http://127.0.0.1:11434)"
|
||||
|
||||
# NEU in v2.3: Config & Timeouts
|
||||
# Pfad zu Prompts
|
||||
# Config & Timeouts
|
||||
MINDNET_PROMPTS_PATH="./config/prompts.yaml"
|
||||
# Pfad zur Decision Engine Config
|
||||
MINDNET_DECISION_CONFIG="./config/decision_engine.yaml"
|
||||
# Timeout in Sekunden (300s = 5min fuer Cold Starts)
|
||||
MINDNET_LLM_TIMEOUT=300.0
|
||||
|
||||
### 2.6 Deployment via Systemd
|
||||
Mindnet wird als Systemdienst gestartet. Ollama läuft meist als eigener Dienst (`ollama.service`).
|
||||
### 2.6 Deployment via Systemd (Backend & Frontend)
|
||||
|
||||
**Production Service (`/etc/systemd/system/mindnet-prod.service`):**
|
||||
* Läuft auf Port 8001.
|
||||
* Autostart (`enabled`).
|
||||
* Restart Policy: `always`.
|
||||
* Abhängigkeit: Sollte nach `docker` und `ollama` starten.
|
||||
Mindnet benötigt zwei Services pro Umgebung: API (Uvicorn) und UI (Streamlit).
|
||||
|
||||
**Production Backend (`/etc/systemd/system/mindnet-prod.service`):**
|
||||
|
||||
[Unit]
|
||||
Description=Mindnet API Prod (8001)
|
||||
After=network.target
|
||||
|
||||
[Service]
|
||||
User=llmadmin
|
||||
Group=llmadmin
|
||||
WorkingDirectory=/home/llmadmin/mindnet
|
||||
ExecStart=/home/llmadmin/mindnet/.venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8001 --env-file .env
|
||||
Restart=always
|
||||
RestartSec=5
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
|
||||
**Production Frontend (`/etc/systemd/system/mindnet-ui-prod.service`):**
|
||||
|
||||
[Unit]
|
||||
Description=Mindnet UI Prod (8501)
|
||||
After=mindnet-prod.service
|
||||
|
||||
[Service]
|
||||
User=llmadmin
|
||||
Group=llmadmin
|
||||
WorkingDirectory=/home/llmadmin/mindnet
|
||||
|
||||
# Environment Variables
|
||||
Environment="MINDNET_API_URL=http://localhost:8001"
|
||||
Environment="MINDNET_API_TIMEOUT=300"
|
||||
Environment="STREAMLIT_SERVER_PORT=8501"
|
||||
Environment="STREAMLIT_SERVER_ADDRESS=0.0.0.0"
|
||||
Environment="STREAMLIT_SERVER_HEADLESS=true"
|
||||
|
||||
ExecStart=/home/llmadmin/mindnet/.venv/bin/streamlit run app/frontend/ui.py
|
||||
Restart=always
|
||||
RestartSec=5
|
||||
|
||||
[Install]
|
||||
WantedBy=multi-user.target
|
||||
|
||||
**Firewall (UFW):**
|
||||
Öffne die Ports für den Zugriff:
|
||||
|
||||
sudo ufw allow 8501/tcp # Prod UI
|
||||
sudo ufw allow 8502/tcp # Dev UI (falls gewünscht)
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -106,27 +148,19 @@ Der Vault-Zustand sollte regelmäßig (z.B. stündlich per Cronjob) nach Qdrant
|
|||
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
|
||||
|
||||
### 3.2 Health-Checks
|
||||
Prüfe regelmäßig, ob alle drei Komponenten (API, DB, LLM) laufen.
|
||||
|
||||
**Status prüfen:**
|
||||
Prüfe regelmäßig, ob alle Komponenten laufen.
|
||||
|
||||
sudo systemctl status mindnet-prod
|
||||
sudo systemctl status mindnet-ui-prod
|
||||
sudo systemctl status ollama
|
||||
|
||||
**Logischer Smoke-Test:**
|
||||
|
||||
python3 scripts/test_retriever_smoke.py --mode hybrid --url http://localhost:8001/query
|
||||
|
||||
### 3.3 Logs & Monitoring
|
||||
* **Technische Fehler (API):** `journalctl -u mindnet-prod -f`
|
||||
* Achte auf: `LLM Router Raw Output`. Hier siehst du, wie die Decision Engine entscheidet.
|
||||
* **LLM Fehler (Ollama):** `journalctl -u ollama -f`
|
||||
* **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`
|
||||
|
||||
**Troubleshooting Chat:**
|
||||
* Wenn `/chat` in den Timeout läuft (>300s): Prüfe `MINDNET_LLM_TIMEOUT` in `.env` und ob das Modell im RAM liegt.
|
||||
* Wenn `/chat` halluziniert: Prüfe `config/prompts.yaml` und ob der Import aktuell ist.
|
||||
|
||||
---
|
||||
|
||||
## 4. Update-Prozess
|
||||
|
|
@ -143,9 +177,10 @@ Wenn neue Versionen ausgerollt werden (Deployment):
|
|||
source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
|
||||
3. **Dienst neustarten (Zwingend!):**
|
||||
3. **Dienste neustarten (Zwingend!):**
|
||||
|
||||
sudo systemctl restart mindnet-prod
|
||||
sudo systemctl restart mindnet-ui-prod
|
||||
|
||||
4. **Schema-Migration (falls nötig):**
|
||||
|
||||
|
|
@ -158,7 +193,7 @@ Wenn neue Versionen ausgerollt werden (Deployment):
|
|||
Datensicherheit ruht auf drei Säulen: Vault (Source), Qdrant (Index), JSONL-Logs (Lern-Daten).
|
||||
|
||||
### 5.1 Vault-Backup (Priorität 1)
|
||||
Der Markdown-Vault ist die **Single Source of Truth**. Er muss klassisch gesichert werden (Git/NAS).
|
||||
Der Markdown-Vault ist die **Single Source of Truth**.
|
||||
|
||||
### 5.2 Qdrant-Snapshots (Priorität 2)
|
||||
Für schnelle Wiederherstellung des Suchindex.
|
||||
|
|
@ -168,7 +203,7 @@ Für schnelle Wiederherstellung des Suchindex.
|
|||
docker start mindnet_qdrant
|
||||
|
||||
### 5.3 Log-Daten (Priorität 3)
|
||||
Sichere den Ordner `data/logs/`. Verlust dieser Daten bedeutet, dass das System vergisst, welche Antworten Nutzer hilfreich fanden.
|
||||
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:
|
||||
|
|
@ -184,10 +219,9 @@ Wenn die Datenbank korrupt ist:
|
|||
|
||||
### 6.1 Zugriffsschutz
|
||||
Mindnet hat aktuell **keine integrierte Authentifizierung**.
|
||||
* **API:** Muss hinter einem Reverse Proxy (Nginx) mit Basic Auth laufen.
|
||||
* **Qdrant:** Sollte via Firewall (ufw) auf `127.0.0.1` beschränkt sein.
|
||||
* **Ollama:** Standardmäßig hört Ollama nur auf `localhost`. Das ist sicher.
|
||||
* **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.
|
||||
* **Prozess:** Änderungen sollten getestet werden (Smoke-Test), bevor sie produktiv gehen.
|
||||
Änderungen an der `types.yaml` (z.B. neue Gewichte) wirken global und erfordern Tests.
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
# Mindnet v2.2 – Appendices & Referenzen
|
||||
**Datei:** `docs/mindnet_appendices_v2.2.md`
|
||||
**Stand:** 2025-12-09
|
||||
**Status:** **FINAL** (Integrierter Stand WP01–WP06)
|
||||
**Stand:** 2025-12-10
|
||||
**Status:** **FINAL** (Integrierter Stand WP01–WP10)
|
||||
**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.
|
||||
|
|
@ -128,7 +128,7 @@ Diese Variablen steuern das Verhalten der Skripte und Container.
|
|||
|
||||
---
|
||||
|
||||
## Anhang F: Workpackage Status (v2.3.1)
|
||||
## Anhang F: Workpackage Status (v2.3.2)
|
||||
|
||||
Aktueller Implementierungsstand der Module.
|
||||
|
||||
|
|
@ -142,5 +142,7 @@ Aktueller Implementierungsstand der Module.
|
|||
| **WP04c**| Feedback Loop | 🟢 Live | Logging (JSONL) & Traceability aktiv. |
|
||||
| **WP05** | Persönlichkeit / Chat | 🟢 Live | RAG-Chat mit Context Enrichment. |
|
||||
| **WP06** | Decision Engine | 🟢 Live | Hybrid Router, Strategic Retrieval, Multi-Persona. |
|
||||
| **WP07** | Interview Assistent | 🟡 Geplant | Dialog-Modus (Nächster Schritt). |
|
||||
| **WP08** | Self-Tuning | 🔴 Geplant | Auto-Adjustment der Gewichte. |
|
||||
| **WP10** | Chat Interface | 🟡 Geplant | Nächster Schritt (Frontend). |
|
||||
| **WP10** | Chat Interface | 🟢 Live | Web-Interface (Streamlit). |
|
||||
| **WP10a**| GUI Evolution | 🔴 Geplant | Interaktive Tools & Editor. |
|
||||
|
|
@ -1,6 +1,6 @@
|
|||
# Mindnet v2.2 – Entwickler-Workflow
|
||||
**Datei:** `DEV_WORKFLOW.md`
|
||||
**Stand:** 2025-12-09 (Aktualisiert: LLM Timeouts & Systemd)
|
||||
**Stand:** 2025-12-10 (Aktualisiert: Inkl. Frontend WP10)
|
||||
|
||||
Dieses Handbuch beschreibt den Entwicklungszyklus zwischen **Windows PC** (IDE), **Raspberry Pi** (Gitea) und **Beelink** (Runtime/Server).
|
||||
|
||||
|
|
@ -11,8 +11,12 @@ Dieses Handbuch beschreibt den Entwicklungszyklus zwischen **Windows PC** (IDE),
|
|||
* **Windows 11 (VS Code):** Hier schreibst du Code. **Nie** direkt auf `main` arbeiten!
|
||||
* **Raspberry Pi (Gitea):** Der Tresor. Speichert den Code und verwaltet Versionen.
|
||||
* **Beelink (Runtime):** Hier läuft die Software. Wir nutzen **Systemd-Services**:
|
||||
* **PROD (`mindnet-prod`):** Läuft stabil auf `main`. Ordner: `~/mindnet`. **Port 8001**.
|
||||
* **DEV (`mindnet-dev`):** Deine Spielwiese. Ordner: `~/mindnet_dev`. **Port 8002**.
|
||||
* **PROD:**
|
||||
* API: `mindnet-prod` (Port 8001). Ordner: `~/mindnet`.
|
||||
* UI: `mindnet-ui-prod` (Port 8501).
|
||||
* **DEV:**
|
||||
* API: `mindnet-dev` (Port 8002). Ordner: `~/mindnet_dev`.
|
||||
* UI: `mindnet-ui-dev` (Port 8502).
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -71,45 +75,53 @@ Hier prüfst du, ob dein neuer Code auf dem echten Server läuft.
|
|||
```
|
||||
|
||||
5. **Test-Server aktualisieren (WICHTIG):**
|
||||
Der Code ist da, aber der Prozess im RAM ist noch alt. Wir müssen den Service neustarten.
|
||||
Der Code ist da, aber die Prozesse im RAM sind noch alt. Wir müssen die Services neustarten.
|
||||
|
||||
**Option A: Standard (Als Service laufen lassen)**
|
||||
Ideal, wenn du nur testen willst, ob es läuft.
|
||||
```bash
|
||||
# 1. API neustarten
|
||||
sudo systemctl restart mindnet-dev
|
||||
# 2. UI neustarten (falls Frontend-Änderungen)
|
||||
sudo systemctl restart mindnet-ui-dev
|
||||
|
||||
# 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)**
|
||||
Ideal, wenn du Print-Ausgaben direkt sehen willst oder der Service dauernd crasht.
|
||||
```bash
|
||||
# 1. Service stoppen (wichtig, sonst ist Port 8002 belegt!)
|
||||
# 1. Services stoppen (wichtig, sonst sind Ports 8002/8502 belegt!)
|
||||
sudo systemctl stop mindnet-dev
|
||||
sudo systemctl stop mindnet-ui-dev
|
||||
|
||||
# 2. Manuell starten
|
||||
# 2. Manuell starten (z.B. API)
|
||||
uvicorn app.main:app --host 0.0.0.0 --port 8002 --env-file .env
|
||||
|
||||
# ... Testen ...
|
||||
|
||||
# 3. Wenn fertig: Service wieder anschalten (Optional)
|
||||
# 3. Wenn fertig: Services wieder anschalten (Optional)
|
||||
# Strg+C drücken
|
||||
sudo systemctl start mindnet-dev
|
||||
sudo systemctl start mindnet-ui-dev
|
||||
```
|
||||
|
||||
6. **Validieren:**
|
||||
Führe deine Tests in einem **zweiten Terminal** aus:
|
||||
```bash
|
||||
# Beispiel für Decision Engine Test
|
||||
python tests/test_wp06_decision.py -p 8002 -q "Soll ich...?"
|
||||
```
|
||||
* **Browser:** Öffne `http://<IP>:8502` um die UI zu testen.
|
||||
* **CLI:** Führe Testskripte in einem **zweiten Terminal** aus:
|
||||
```bash
|
||||
# Beispiel für Decision Engine Test
|
||||
python tests/test_wp06_decision.py -p 8002 -q "Soll ich...?"
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
### Phase 3: Release (Gitea / Raspberry Pi)
|
||||
|
||||
Wenn der Test auf Port 8002 erfolgreich war:
|
||||
Wenn der Test auf Port 8002 / 8502 erfolgreich war:
|
||||
|
||||
1. Öffne Gitea im Browser.
|
||||
2. Erstelle einen **Pull Request** (Dein Branch -> `main`).
|
||||
|
|
@ -119,7 +131,7 @@ Wenn der Test auf Port 8002 erfolgreich war:
|
|||
|
||||
### Phase 4: Deployment (Beelink / `mindnet`)
|
||||
|
||||
Jetzt bringen wir die Änderung in das Live-System (Port 8001).
|
||||
Jetzt bringen wir die Änderung in das Live-System (Port 8001 / 8501).
|
||||
|
||||
1. **Deploy-Agent (Automatisch):**
|
||||
Wenn dein `deploy.yml` aktiv ist, passiert das jetzt von selbst!
|
||||
|
|
@ -129,8 +141,13 @@ Jetzt bringen wir die Änderung in das Live-System (Port 8001).
|
|||
cd /home/llmadmin/mindnet
|
||||
git pull origin main
|
||||
|
||||
# Produktions-Service neustarten
|
||||
# Dependencies updaten
|
||||
source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
|
||||
# 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
|
||||
|
|
@ -163,8 +180,10 @@ Damit das Chaos nicht wächst, löschen wir den fertigen Branch.
|
|||
| :--- | :--- | :--- |
|
||||
| **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-Server (Port 8002).** |
|
||||
| **Beelink** | `journalctl -u mindnet-dev -f` | **Live-Logs vom Dev-Server sehen.** |
|
||||
| **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.** |
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -173,13 +192,13 @@ Damit das Chaos nicht wächst, löschen wir den fertigen Branch.
|
|||
**"Read timed out (120s)" / 500 Error beim Chat**
|
||||
* **Ursache:** Das LLM (Ollama) braucht zu lange zum Laden ("Cold Start").
|
||||
* **Lösung:**
|
||||
1. Erhöhe in `.env` den Wert: `MINDNET_LLM_TIMEOUT=300.0`.
|
||||
2. Starte den Server neu (`sudo systemctl restart mindnet-dev`).
|
||||
1. Erhöhe in `.env` den Wert: `MINDNET_LLM_TIMEOUT=300.0` (Backend) oder `MINDNET_API_TIMEOUT` (Frontend).
|
||||
2. Starte die Server neu.
|
||||
3. Stelle sicher, dass dein Test-Skript (Client) auch ein hohes Timeout hat.
|
||||
|
||||
**"Port 8002 already in use"**
|
||||
* **Ursache:** Du willst `uvicorn` manuell starten, aber der Service läuft noch.
|
||||
* **Lösung:** `sudo systemctl stop mindnet-dev`.
|
||||
**"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.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
# Mindnet v2.2 – Developer Guide
|
||||
**Datei:** `docs/mindnet_developer_guide_v2.2.md`
|
||||
**Stand:** 2025-12-09
|
||||
**Status:** **FINAL** (Inkl. RAG, Decision Engine & AI-Teaching)
|
||||
**Stand:** 2025-12-10
|
||||
**Status:** **FINAL** (Inkl. RAG, Decision Engine & Frontend WP10)
|
||||
**Quellen:** `mindnet_technical_architecture.md`, `Handbuch.md`, `DEV_WORKFLOW.md`.
|
||||
|
||||
> **Zielgruppe:** Entwickler:innen.
|
||||
|
|
@ -9,16 +9,17 @@
|
|||
|
||||
---
|
||||
- [Mindnet v2.2 – Developer Guide](#mindnet-v22--developer-guide)
|
||||
- [1. Projektstruktur (Post-WP06)](#1-projektstruktur-post-wp06)
|
||||
- [1. Projektstruktur (Post-WP10)](#1-projektstruktur-post-wp10)
|
||||
- [2. Lokales Setup (Development)](#2-lokales-setup-development)
|
||||
- [2.1 Voraussetzungen](#21-voraussetzungen)
|
||||
- [2.2 Installation](#22-installation)
|
||||
- [2.3 Konfiguration (Environment)](#23-konfiguration-environment)
|
||||
- [2.4 Dienste starten (Systemd bevorzugt)](#24-dienste-starten-systemd-bevorzugt)
|
||||
- [2.4 Dienste starten (API \& UI)](#24-dienste-starten-api--ui)
|
||||
- [3. Core-Module \& Entwicklung](#3-core-module--entwicklung)
|
||||
- [3.1 Der Importer (`scripts.import_markdown`)](#31-der-importer-scriptsimport_markdown)
|
||||
- [3.2 Der Hybrid Router (`app.routers.chat`)](#32-der-hybrid-router-approuterschat)
|
||||
- [3.3 Der Retriever (`app.core.retriever`)](#33-der-retriever-appcoreretriever)
|
||||
- [3.4 Das Frontend (`app.frontend.ui`)](#34-das-frontend-appfrontendui)
|
||||
- [4. Tests \& Debugging](#4-tests--debugging)
|
||||
- [4.1 Unit Tests (Pytest)](#41-unit-tests-pytest)
|
||||
- [4.2 Integration / Pipeline Tests](#42-integration--pipeline-tests)
|
||||
|
|
@ -31,7 +32,7 @@
|
|||
|
||||
---
|
||||
|
||||
## 1. Projektstruktur (Post-WP06)
|
||||
## 1. Projektstruktur (Post-WP10)
|
||||
|
||||
Der Code ist modular in `app` (Logik), `scripts` (CLI) und `config` (Steuerung) getrennt.
|
||||
|
||||
|
|
@ -54,6 +55,8 @@ Der Code ist modular in `app` (Logik), `scripts` (CLI) und `config` (Steuerung)
|
|||
│ │ ├── llm_service.py # Ollama Client (Mit Timeout & Raw-Mode)
|
||||
│ │ ├── feedback_service.py # Logging (JSONL Writer)
|
||||
│ │ └── embeddings_client.py
|
||||
│ ├── frontend/ # NEU (WP10)
|
||||
│ │ └── ui.py # Streamlit Application
|
||||
│ └── main.py # Entrypoint der API
|
||||
├── config/ # YAML-Konfigurationen (Single Source of Truth)
|
||||
│ ├── types.yaml # Import-Regeln
|
||||
|
|
@ -86,7 +89,7 @@ Der Code ist modular in `app` (Logik), `scripts` (CLI) und `config` (Steuerung)
|
|||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
|
||||
# 3. Abhängigkeiten installieren
|
||||
# 3. Abhängigkeiten installieren (inkl. Streamlit)
|
||||
pip install -r requirements.txt
|
||||
|
||||
# 4. Ollama Setup (Modell laden)
|
||||
|
|
@ -94,7 +97,7 @@ Der Code ist modular in `app` (Logik), `scripts` (CLI) und `config` (Steuerung)
|
|||
ollama pull phi3:mini
|
||||
|
||||
### 2.3 Konfiguration (Environment)
|
||||
Erstelle eine `.env` Datei im Root-Verzeichnis. Die Timeout-Settings sind kritisch für CPU-Inference.
|
||||
Erstelle eine `.env` Datei im Root-Verzeichnis.
|
||||
|
||||
# Qdrant Verbindung
|
||||
QDRANT_URL="http://localhost:6333"
|
||||
|
|
@ -112,28 +115,28 @@ Erstelle eine `.env` Datei im Root-Verzeichnis. Die Timeout-Settings sind kritis
|
|||
MINDNET_PROMPTS_PATH="./config/prompts.yaml"
|
||||
MINDNET_DECISION_CONFIG="./config/decision_engine.yaml"
|
||||
|
||||
# Frontend Settings (WP10)
|
||||
MINDNET_API_URL="http://localhost:8002"
|
||||
|
||||
# Import-Strategie
|
||||
MINDNET_HASH_COMPARE="Body"
|
||||
MINDNET_HASH_SOURCE="parsed"
|
||||
|
||||
### 2.4 Dienste starten (Systemd bevorzugt)
|
||||
Auf dem Entwicklungsserver (Beelink) nutzen wir Systemd.
|
||||
### 2.4 Dienste starten (API & UI)
|
||||
|
||||
# Starten / Neustarten
|
||||
sudo systemctl restart mindnet-dev
|
||||
|
||||
# Logs prüfen (Wichtig für LLM Debugging)
|
||||
journalctl -u mindnet-dev -f
|
||||
Wir entwickeln mit zwei Services. Du kannst sie manuell in zwei Terminals starten oder die Systemd-Services nutzen (siehe `admin_guide.md`).
|
||||
|
||||
Falls du lokal auf Windows entwickelst:
|
||||
**Terminal A: Backend (API)**
|
||||
|
||||
# 1. Qdrant starten
|
||||
docker run -p 6333:6333 qdrant/qdrant
|
||||
# 2. Ollama starten
|
||||
ollama serve
|
||||
# 3. API starten
|
||||
# Startet auf Port 8002 (Dev Standard)
|
||||
uvicorn app.main:app --host 0.0.0.0 --port 8002 --env-file .env --reload
|
||||
|
||||
**Terminal B: Frontend (UI)**
|
||||
|
||||
# Startet auf Port 8502 (Dev Standard)
|
||||
# --server.port 8502 verhindert Konflikte mit Prod (8501)
|
||||
streamlit run app/frontend/ui.py --server.port 8502
|
||||
|
||||
---
|
||||
|
||||
## 3. Core-Module & Entwicklung
|
||||
|
|
@ -155,6 +158,12 @@ Hier passiert das Scoring.
|
|||
* **Hybrid Search:** Der Chat-Endpoint erzwingt `mode="hybrid"`.
|
||||
* **Strategic Retrieval:** In `chat.py` wird der Retriever *zweimal* aufgerufen, wenn ein Intent (z.B. `DECISION`) eine Injection (`value`) erfordert.
|
||||
|
||||
### 3.4 Das Frontend (`app.frontend.ui`)
|
||||
Eine Streamlit-App (WP10).
|
||||
* **State:** Nutzt `st.session_state` für Chat-History und Drafts.
|
||||
* **Logik:** Ruft `/chat` und `/feedback` Endpoints der API auf.
|
||||
* **Anpassung:** CSS Styles sind direkt in `ui.py` eingebettet.
|
||||
|
||||
---
|
||||
|
||||
## 4. Tests & Debugging
|
||||
|
|
@ -179,20 +188,16 @@ Prüfen den Datenfluss von Markdown bis Qdrant-JSON.
|
|||
python3 -m scripts.edges_full_check
|
||||
|
||||
### 4.3 Smoke Tests (E2E)
|
||||
Prüfen das laufende System (API) gegen eine echte Qdrant-Instanz und Ollama.
|
||||
Prüfen das laufende System gegen eine echte Qdrant-Instanz und Ollama.
|
||||
|
||||
# 1. Retriever Test (Hybrid + Explanation)
|
||||
python scripts/test_retriever_smoke.py --query "Test" --mode hybrid --top-k 5 --explain
|
||||
|
||||
# 2. Decision Engine Test (WP06)
|
||||
# Prüft Intent, Retrieval und Reasoning (mit Timeout-Handling)
|
||||
# 1. API Test (Decision Engine)
|
||||
python tests/test_wp06_decision.py -p 8002 -e DECISION -q "Soll ich X tun?"
|
||||
|
||||
# 3. Empathy Test (WP06)
|
||||
# Prüft LLM-Router Fallback
|
||||
python tests/test_wp06_decision.py -p 8002 -e EMPATHY -q "Alles ist grau"
|
||||
# 2. UI Test (Manuell)
|
||||
# Öffne http://localhost:8502
|
||||
# Stelle eine Frage und prüfe Intent-Badge und Quellen-Anzeige.
|
||||
|
||||
# 4. Feedback Test (WP04c)
|
||||
# 3. Feedback Test
|
||||
python tests/test_feedback_smoke.py --url http://localhost:8002/query
|
||||
|
||||
---
|
||||
|
|
@ -260,6 +265,9 @@ Standardmäßig werden alle expliziten Kanten gleich behandelt. Wenn Kausalität
|
|||
|
||||
python3 tests/inspect_one_note.py --file ./vault/MeinFile.md
|
||||
|
||||
**Live-Logs sehen (Beelink) - inkl. LLM Thoughts:**
|
||||
**Live-Logs sehen (Systemd):**
|
||||
|
||||
journalctl -u mindnet-dev -f
|
||||
# Backend
|
||||
journalctl -u mindnet-dev -f
|
||||
# Frontend
|
||||
journalctl -u mindnet-ui-dev -f
|
||||
|
|
@ -1,9 +1,9 @@
|
|||
# Mindnet v2.2 – Fachliche Architektur
|
||||
**Datei:** `docs/mindnet_functional_architecture_v2.2.md`
|
||||
**Stand:** 2025-12-09
|
||||
**Status:** **FINAL** (Integrierter Stand WP01–WP06)
|
||||
**Stand:** 2025-12-10
|
||||
**Status:** **FINAL** (Integrierter Stand WP01–WP10)
|
||||
|
||||
> 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 neuen **RAG-Chat** (Decision Engine & 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 & Persönlichkeit). Die technische Umsetzung wird im technischen Dokument detailliert.
|
||||
|
||||
---
|
||||
<details>
|
||||
|
|
@ -38,7 +38,7 @@
|
|||
- [8) Erweiterbarkeit \& Teaching (Context Intelligence)](#8-erweiterbarkeit--teaching-context-intelligence)
|
||||
- [A. Workflow: Einen neuen Typ implementieren (z. B. `type: risk`)](#a-workflow-einen-neuen-typ-implementieren-z-b-type-risk)
|
||||
- [B. Workflow: Neue Beziehungen nutzen (z. B. `beeinflusst_von`)](#b-workflow-neue-beziehungen-nutzen-z-b-beeinflusst_von)
|
||||
- [9) Feedback \& Lernen – WP04c](#9-feedback--lernen--wp04c)
|
||||
- [9) Feedback \& Lernen – WP04c/WP10](#9-feedback--lernen--wp04cwp10)
|
||||
- [9.1 Der Feedback-Loop](#91-der-feedback-loop)
|
||||
- [10) Confidence \& Provenance – wozu?](#10-confidence--provenance--wozu)
|
||||
- [11) Semantik ausgewählter `kind`-Werte](#11-semantik-ausgewählter-kind-werte)
|
||||
|
|
@ -46,7 +46,7 @@
|
|||
- [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)
|
||||
- [15) Referenzen (Projektdateien \& Leitlinien)](#15-referenzen-projektdateien--leitlinien)
|
||||
- [16) Workpackage Status (v2.3.1)](#16-workpackage-status-v231)
|
||||
- [16) Workpackage Status (v2.3.2)](#16-workpackage-status-v232)
|
||||
|
||||
</details>
|
||||
---
|
||||
|
|
@ -273,7 +273,7 @@ Mindnet lernt nicht durch klassisches Training (Fine-Tuning), sondern durch **Ko
|
|||
Steuere, wie schwer der Inhalt wiegt und wie er vernetzt wird.
|
||||
```yaml
|
||||
risk:
|
||||
chunk_profile: short # Risiken sind prägnant
|
||||
chunk_profile: short # Risiken sind oft kurze Statements
|
||||
retriever_weight: 0.90 # Hohe Priorität im Ranking
|
||||
edge_defaults: ["blocks"] # Automatische Kante zu verlinkten Projekten
|
||||
```
|
||||
|
|
@ -308,11 +308,13 @@ Beziehungen sind der Klebstoff für logische Schlussfolgerungen.
|
|||
|
||||
---
|
||||
|
||||
## 9) Feedback & Lernen – WP04c
|
||||
## 9) Feedback & Lernen – WP04c/WP10
|
||||
|
||||
Das System verfügt nun über ein **Kurzzeitgedächtnis für Interaktionen**, das die Basis für zukünftiges Lernen bildet.
|
||||
|
||||
### 9.1 Der Feedback-Loop
|
||||
Die Interaktion erfolgt primär über das **Web-Interface (WP10)**.
|
||||
|
||||
1. **Suche (Situation):**
|
||||
Wenn ein Nutzer eine Anfrage stellt, loggt Mindnet die "Situation":
|
||||
* Den Query-Text.
|
||||
|
|
@ -321,8 +323,8 @@ Das System verfügt nun über ein **Kurzzeitgedächtnis für Interaktionen**, da
|
|||
* Eine eindeutige `query_id` wird generiert.
|
||||
|
||||
2. **Bewertung (Label):**
|
||||
Der Nutzer (oder ein Agent) bewertet einen spezifischen Treffer (`node_id`) positiv oder negativ (Score 1-5).
|
||||
Dieses Feedback wird unter Referenzierung der `query_id` gespeichert.
|
||||
Der Nutzer bewertet die Antwort (**Sterne**) oder einzelne Quellen (**Faces**) im Frontend.
|
||||
Dieses Feedback wird unter Referenzierung der `query_id` in `feedback.jsonl` gespeichert.
|
||||
|
||||
3. **Lernen (Perspektive WP08):**
|
||||
Durch die Verknüpfung von Situation und Bewertung entstehen Trainingsdaten. Mindnet kann später analysieren: *"Nutzer bevorzugen Treffer mit hohem Edge-Bonus, auch wenn der Text weniger passt."* -> Konsequenz: `edge_weight` erhöhen.
|
||||
|
|
@ -402,7 +404,7 @@ Frontmatter-Eigenschaften (Properties) bleiben **minimiert**:
|
|||
|
||||
---
|
||||
|
||||
## 16) Workpackage Status (v2.3.1)
|
||||
## 16) Workpackage Status (v2.3.2)
|
||||
|
||||
Aktueller Implementierungsstand der Module.
|
||||
|
||||
|
|
@ -416,4 +418,7 @@ Aktueller Implementierungsstand der Module.
|
|||
| **WP04c**| Feedback Loop | 🟢 Live | Logging (JSONL) & Traceability aktiv. |
|
||||
| **WP05** | Persönlichkeit / Chat | 🟢 Live | RAG-Integration mit Context Enrichment. |
|
||||
| **WP06** | Decision Engine | 🟢 Live | Intent-Router & Strategic Retrieval. |
|
||||
| **WP08** | Self-Tuning | 🔴 Geplant | Auto-Adjustment der Gewichte. |
|
||||
| **WP07** | Interview Assistent | 🟡 Geplant | Dialog-Modus (Nächster Schritt). |
|
||||
| **WP08** | Self-Tuning | 🔴 Geplant | Auto-Adjustment der Gewichte. |
|
||||
| **WP10** | Chat Interface | 🟢 Live | Web-UI mit Feedback & Intents. |
|
||||
| **WP10a**| GUI Evolution | 🔴 Geplant | Erweiterte Interaktion. |
|
||||
|
|
@ -1,11 +1,11 @@
|
|||
# Mindnet v2.2 – Technische Architektur
|
||||
**Datei:** `docs/mindnet_technical_architecture_v2.2.md`
|
||||
**Stand:** 2025-12-09
|
||||
**Status:** **FINAL** (Integrierter Stand WP01–WP06)
|
||||
**Stand:** 2025-12-10
|
||||
**Status:** **FINAL** (Integrierter Stand WP01–WP10)
|
||||
**Quellen:** `Programmplan_V2.2.md`, `Handbuch.md`, `chunking_strategy.md`, `wp04_retriever_scoring.md`.
|
||||
|
||||
> **Ziel dieses Dokuments:**
|
||||
> Vollständige Beschreibung der technischen Architektur inkl. Graph-Datenbank, Retrieval-Logik und der **neuen RAG-Komponenten (Decision Engine & Hybrid Router)**.
|
||||
> Vollständige Beschreibung der technischen Architektur inkl. Graph-Datenbank, Retrieval-Logik, der **neuen RAG-Komponenten (Decision Engine & Hybrid Router)** und dem **Frontend (Streamlit)**.
|
||||
|
||||
---
|
||||
<details>
|
||||
|
|
@ -15,7 +15,7 @@
|
|||
- [](#)
|
||||
- [1. Systemüberblick](#1-systemüberblick)
|
||||
- [1.1 Architektur-Zielbild](#11-architektur-zielbild)
|
||||
- [1.2 Verzeichnisstruktur \& Komponenten (Post-WP06)](#12-verzeichnisstruktur--komponenten-post-wp06)
|
||||
- [1.2 Verzeichnisstruktur \& Komponenten (Post-WP10)](#12-verzeichnisstruktur--komponenten-post-wp10)
|
||||
- [2. Datenmodell \& Collections (Qdrant)](#2-datenmodell--collections-qdrant)
|
||||
- [2.1 Notes Collection (`<prefix>_notes`)](#21-notes-collection-prefix_notes)
|
||||
- [2.2 Chunks Collection (`<prefix>_chunks`)](#22-chunks-collection-prefix_chunks)
|
||||
|
|
@ -39,12 +39,16 @@
|
|||
- [6.3 Schritt 2: Strategy Resolution (Late Binding)](#63-schritt-2-strategy-resolution-late-binding)
|
||||
- [6.4 Schritt 3: Multi-Stage Retrieval](#64-schritt-3-multi-stage-retrieval)
|
||||
- [6.5 Schritt 4: Generation \& Response](#65-schritt-4-generation--response)
|
||||
- [7. Feedback \& Logging Architektur (WP04c)](#7-feedback--logging-architektur-wp04c)
|
||||
- [7.1 Komponenten](#71-komponenten)
|
||||
- [7.2 Log-Dateien](#72-log-dateien)
|
||||
- [7.3 Traceability](#73-traceability)
|
||||
- [8. Indizes \& Performance](#8-indizes--performance)
|
||||
- [9. Offene Punkte / Known Limitations](#9-offene-punkte--known-limitations)
|
||||
- [7. Frontend Architektur (WP10)](#7-frontend-architektur-wp10)
|
||||
- [7.1 Kommunikation](#71-kommunikation)
|
||||
- [7.2 Features \& UI-Logik](#72-features--ui-logik)
|
||||
- [7.3 Deployment Ports](#73-deployment-ports)
|
||||
- [8. Feedback \& Logging Architektur (WP04c)](#8-feedback--logging-architektur-wp04c)
|
||||
- [8.1 Komponenten](#81-komponenten)
|
||||
- [8.2 Log-Dateien](#82-log-dateien)
|
||||
- [8.3 Traceability](#83-traceability)
|
||||
- [9. Indizes \& Performance](#9-indizes--performance)
|
||||
- [10. Offene Punkte / Known Limitations](#10-offene-punkte--known-limitations)
|
||||
|
||||
|
||||
</details>
|
||||
|
|
@ -53,18 +57,19 @@
|
|||
## 1. Systemüberblick
|
||||
|
||||
### 1.1 Architektur-Zielbild
|
||||
Mindnet ist ein **lokales RAG-System (Retrieval Augmented Generation)**.
|
||||
Mindnet ist ein **lokales RAG-System (Retrieval Augmented Generation)** mit Web-Interface.
|
||||
1. **Source:** Markdown-Notizen in einem Vault (Obsidian-kompatibel).
|
||||
2. **Pipeline:** Ein Python-Importer transformiert diese in **Notes**, **Chunks** und **Edges**.
|
||||
3. **Storage:**
|
||||
* **Qdrant:** Vektor-Datenbank für Graph und Semantik (Collections: notes, chunks, edges).
|
||||
* **Local Files (JSONL):** Append-Only Logs für Feedback und Search-History (Data Flywheel).
|
||||
4. **Service:** Eine FastAPI-Anwendung stellt Endpunkte für **Semantische** und **Hybride Suche** sowie **Feedback** bereit.
|
||||
5. **Inference:** Lokales LLM (Ollama: Phi-3 Mini) für RAG-Chat und Antwortgenerierung.
|
||||
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.
|
||||
6. **Inference:** Lokales LLM (Ollama: Phi-3 Mini) für RAG-Chat und Antwortgenerierung.
|
||||
|
||||
Das System arbeitet **deterministisch** (stabile IDs) und ist **konfigurationsgetrieben** (`types.yaml`, `retriever.yaml`, `decision_engine.yaml`, `prompts.yaml`).
|
||||
|
||||
### 1.2 Verzeichnisstruktur & Komponenten (Post-WP06)
|
||||
### 1.2 Verzeichnisstruktur & Komponenten (Post-WP10)
|
||||
|
||||
/mindnet/
|
||||
├── app/
|
||||
|
|
@ -89,6 +94,8 @@ Das System arbeitet **deterministisch** (stabile IDs) und ist **konfigurationsge
|
|||
│ │ ├── llm_service.py # Ollama Client mit Timeout & Raw-Mode
|
||||
│ │ ├── feedback_service.py # JSONL Logging (WP04c)
|
||||
│ │ └── embeddings_client.py
|
||||
│ ├── frontend/ # NEU (WP10)
|
||||
│ └── ui.py # Streamlit Application
|
||||
├── config/
|
||||
│ ├── types.yaml # Typ-Definitionen (Import-Zeit)
|
||||
│ ├── retriever.yaml # Scoring-Gewichte (Laufzeit)
|
||||
|
|
@ -308,15 +315,44 @@ Basierend auf dem Intent lädt der Router die Parameter:
|
|||
|
||||
---
|
||||
|
||||
## 7. Feedback & Logging Architektur (WP04c)
|
||||
## 7. Frontend Architektur (WP10)
|
||||
|
||||
Das Frontend ist eine **Streamlit-Anwendung**, die als separater Prozess läuft und via HTTP mit dem Backend kommuniziert.
|
||||
|
||||
### 7.1 Kommunikation
|
||||
* **Backend-URL:** Konfiguriert via `MINDNET_API_URL` (Default: `http://localhost:8002`).
|
||||
* **Endpoints:** Nutzt `/chat` für Interaktion und `/feedback` für Bewertungen.
|
||||
* **Resilienz:** Das Frontend implementiert eigene Timeouts (`MINDNET_API_TIMEOUT`, Default 300s), um lange Wartezeiten lokaler LLMs abzufangen.
|
||||
|
||||
### 7.2 Features & UI-Logik
|
||||
* **State Management:** Session-State speichert Chat-Verlauf und `query_id` für Feedback.
|
||||
* **Visualisierung:**
|
||||
* **Intent Badges:** Zeigt Router-Entscheidung (`DECISION`, `FACT`, etc.) und Quelle (`Keyword` vs. `LLM`).
|
||||
* **Source Expanders:** Zeigt verwendete Chunks inkl. Score und "Why"-Explanation.
|
||||
* **Sidebar:** Zeigt Suchhistorie (Log-basiert) und Konfiguration.
|
||||
* **Feedback:**
|
||||
* Global (Antwort): 1-5 Sterne Rating.
|
||||
* Granular (Quellen): Faces-Rating (Mapped auf 1-5 Score).
|
||||
|
||||
### 7.3 Deployment Ports
|
||||
Zur sauberen Trennung von Prod und Dev laufen Frontend und Backend auf dedizierten Ports:
|
||||
|
||||
| Umgebung | Backend (FastAPI) | Frontend (Streamlit) |
|
||||
| :--- | :--- | :--- |
|
||||
| **Production** | 8001 | 8501 |
|
||||
| **Development** | 8002 | 8502 |
|
||||
|
||||
---
|
||||
|
||||
## 8. Feedback & Logging Architektur (WP04c)
|
||||
|
||||
Mindnet implementiert ein "Data Flywheel" zur späteren Optimierung (Self-Tuning).
|
||||
|
||||
### 7.1 Komponenten
|
||||
### 8.1 Komponenten
|
||||
* **Feedback Service (`app/services/feedback_service.py`):** Kapselt die Schreibzugriffe.
|
||||
* **Storage:** Lokales Dateisystem (`data/logs/`), Format JSONL (Line-delimited JSON).
|
||||
|
||||
### 7.2 Log-Dateien
|
||||
### 8.2 Log-Dateien
|
||||
1. **`search_history.jsonl`**:
|
||||
* Speichert jede Anfrage an `/query` und `/chat`.
|
||||
* Enthält: `query_id`, `query_text`, `timestamp`, `hits` (inkl. `score_breakdown` Snapshots).
|
||||
|
|
@ -324,14 +360,15 @@ Mindnet implementiert ein "Data Flywheel" zur späteren Optimierung (Self-Tuning
|
|||
2. **`feedback.jsonl`**:
|
||||
* Speichert User-Reaktionen an `/feedback`.
|
||||
* Enthält: `query_id`, `node_id`, `score` (1-5), `comment`.
|
||||
* **Granularität:** Kann sich auf `generated_answer` (Global) oder eine spezifische `node_id` (Quelle) beziehen.
|
||||
* Zweck: Labels ("War es gut?").
|
||||
|
||||
### 7.3 Traceability
|
||||
### 8.3 Traceability
|
||||
Die `query_id` (UUIDv4) wird im `/query` Response generiert und muss vom Client beim `/feedback` Aufruf mitgesendet werden. Dies ermöglicht den Join zwischen Snapshot und Bewertung.
|
||||
|
||||
---
|
||||
|
||||
## 8. Indizes & Performance
|
||||
## 9. Indizes & Performance
|
||||
|
||||
Damit Qdrant performant bleibt, sind Payload-Indizes essenziell.
|
||||
|
||||
|
|
@ -344,7 +381,7 @@ Validierung erfolgt über `tests/ensure_indexes_and_show.py`.
|
|||
|
||||
---
|
||||
|
||||
## 9. Offene Punkte / Known Limitations
|
||||
## 10. Offene Punkte / Known Limitations
|
||||
|
||||
1. **Multi-Target Inline-Relations:**
|
||||
* `rel: similar_to [[A]] [[B]]` wird aktuell parser-seitig nicht unterstützt.
|
||||
|
|
|
|||
|
|
@ -1,7 +1,7 @@
|
|||
# mindnet v2.2 – Pipeline Playbook
|
||||
**Datei:** `docs/mindnet_pipeline_playbook_v2.2.md`
|
||||
**Stand:** 2025-12-09
|
||||
**Status:** **FINAL** (Inkl. WP06 Decision Engine)
|
||||
**Stand:** 2025-12-10
|
||||
**Status:** **FINAL** (Inkl. WP10 Frontend)
|
||||
**Quellen:** `mindnet_v2_implementation_playbook.md`, `Handbuch.md`, `chunking_strategy.md`, `docs_mindnet_retriever.md`, `mindnet_admin_guide_v2.2.md`.
|
||||
|
||||
---
|
||||
|
|
@ -33,6 +33,7 @@
|
|||
- [7.2 Smoke-Test (E2E)](#72-smoke-test-e2e)
|
||||
- [8. Ausblick \& Roadmap (Technische Skizzen)](#8-ausblick--roadmap-technische-skizzen)
|
||||
- [8.1 WP-08: Self-Tuning (Skizze)](#81-wp-08-self-tuning-skizze)
|
||||
- [16. Workpackage Status (v2.3.2)](#16-workpackage-status-v232)
|
||||
|
||||
</details>
|
||||
---
|
||||
|
|
@ -43,7 +44,7 @@ Dieses Playbook ist das zentrale operative Handbuch für die **mindnet-Pipeline*
|
|||
|
||||
**Zielgruppe:** Dev/Ops, Tech-Leads.
|
||||
**Scope:**
|
||||
* **Ist-Stand (WP01–WP06):** Import, Chunking, Edge-Erzeugung, Hybrider Retriever, RAG-Chat (Hybrid Router), Feedback Loop.
|
||||
* **Ist-Stand (WP01–WP10):** Import, Chunking, Edge-Erzeugung, Hybrider Retriever, RAG-Chat (Hybrid Router), Feedback Loop, Frontend.
|
||||
* **Roadmap (Ausblick):** Technische Skizze für Self-Tuning (WP08).
|
||||
|
||||
---
|
||||
|
|
@ -88,10 +89,11 @@ Für regelmäßige Updates (z.B. Cronjob). Erkennt Änderungen via Hash.
|
|||
* `--sync-deletes`: Entfernt Notizen aus Qdrant, die im Vault gelöscht wurden.
|
||||
|
||||
### 2.3 Deployment & Restart (Systemd)
|
||||
Nach einem Import oder Code-Update muss der API-Prozess neu gestartet werden.
|
||||
Nach einem Import oder Code-Update müssen die API-Prozesse neu gestartet werden.
|
||||
|
||||
# Neustart des Produktions-Services
|
||||
# Neustart des Produktions-Services (API + UI)
|
||||
sudo systemctl restart mindnet-prod
|
||||
sudo systemctl restart mindnet-ui-prod
|
||||
|
||||
# Prüfung
|
||||
sudo systemctl status mindnet-prod
|
||||
|
|
@ -203,7 +205,7 @@ 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
|
||||
|
||||
# Chat / Decision Engine Test (Neu WP06)
|
||||
# Decision Engine Test (WP06)
|
||||
python tests/test_wp06_decision.py -p 8002 -e EMPATHY -q "Alles ist grau"
|
||||
|
||||
# Feedback Test
|
||||
|
|
@ -220,4 +222,25 @@ Wie entwickeln wir die Pipeline weiter?
|
|||
**Ansatz:** Ein Offline-Learning-Skript `scripts/optimize_weights.py`.
|
||||
1. **Load:** Liest `search_history.jsonl` und joint mit `feedback.jsonl` via `query_id`.
|
||||
2. **Analyze:** Korrelation Scores vs. User-Rating.
|
||||
3. **Optimize:** Vorschlag neuer Gewichte für `retriever.yaml`.
|
||||
3. **Optimize:** Vorschlag neuer Gewichte für `retriever.yaml`.
|
||||
|
||||
---
|
||||
|
||||
## 16. Workpackage Status (v2.3.2)
|
||||
|
||||
Aktueller Implementierungsstand der Module.
|
||||
|
||||
| WP | Titel | Status | Anmerkung |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **WP01** | Knowledge Design | 🟢 Live | Typen, Frontmatter definiert. |
|
||||
| **WP02** | Chunking Strategy | 🟢 Live | Profilbasiertes Chunking aktiv. |
|
||||
| **WP03** | Edge Logic / Import | 🟢 Live | Neue Importer-Pipeline mit Provenance. |
|
||||
| **WP04a**| Retriever Scoring | 🟢 Live | Hybrider Score (Semantik + Graph). |
|
||||
| **WP04b**| Explanation Layer | 🟢 Live | API liefert Reasons & Breakdown. |
|
||||
| **WP04c**| Feedback Loop | 🟢 Live | Logging (JSONL) & Traceability aktiv. |
|
||||
| **WP05** | Persönlichkeit / Chat | 🟢 Live | RAG-Integration mit Context Enrichment. |
|
||||
| **WP06** | Decision Engine | 🟢 Live | Hybrid Router, Strategic Retrieval. |
|
||||
| **WP07** | Interview Assistent | 🟡 Geplant | Nächster Schritt (Dialog-Modus). |
|
||||
| **WP08** | Self-Tuning | 🔴 Geplant | Auto-Adjustment der Gewichte. |
|
||||
| **WP10** | Chat Interface | 🟢 Live | Streamlit Web-UI mit Feedback & Intents. |
|
||||
| **WP10a**| GUI Evolution | 🔴 Geplant | Draft-Editor & Interaktionstools. |
|
||||
|
|
@ -1,7 +1,7 @@
|
|||
# Mindnet v2.2 – User Guide
|
||||
**Datei:** `docs/mindnet_user_guide_v2.2.md`
|
||||
**Stand:** 2025-12-09
|
||||
**Status:** **FINAL** (Inkl. RAG & Multi-Personality Chat)
|
||||
**Stand:** 2025-12-10
|
||||
**Status:** **FINAL** (Inkl. RAG & Web-Interface)
|
||||
**Quellen:** `knowledge_design.md`, `wp04_retriever_scoring.md`, `Programmplan_V2.2.md`, `Handbuch.md`.
|
||||
|
||||
> **Willkommen bei Mindnet.**
|
||||
|
|
@ -20,7 +20,7 @@ Wenn du nach "Projekt Alpha" suchst, findet Mindnet nicht nur das Dokument. Es f
|
|||
* **Ähnliches:** "Projekt Beta war ähnlich".
|
||||
|
||||
### 1.2 Der Zwilling (Die Personas)
|
||||
Seit Version 2.3.1 passt Mindnet seinen Charakter dynamisch an deine Frage an:
|
||||
Mindnet passt seinen Charakter dynamisch an deine Frage an:
|
||||
1. **Der Bibliothekar (FACT):** Liefert präzise Fakten und Definitionen.
|
||||
2. **Der Berater (DECISION):** Hilft dir beim Abwägen, basierend auf deinen Werten und Zielen.
|
||||
3. **Der Spiegel (EMPATHY):** Hört zu und antwortet basierend auf deinen Erfahrungen ("Ich"-Perspektive).
|
||||
|
|
@ -28,11 +28,32 @@ Seit Version 2.3.1 passt Mindnet seinen Charakter dynamisch an deine Frage an:
|
|||
|
||||
---
|
||||
|
||||
## 2. Den Chat steuern (Intents)
|
||||
## 2. Die Oberfläche (Web UI)
|
||||
|
||||
Seit Version 2.3.1 bedienst du Mindnet über eine grafische Oberfläche im Browser.
|
||||
|
||||
### 2.1 Der Chat-Bereich
|
||||
* **Eingabe:** Unten findest du das Textfeld.
|
||||
* **Intent-Badge:** Über jeder Antwort zeigt ein kleines Label (z.B. **⚖️ Intent: DECISION**), in welchem Modus das System arbeitet und ob dies durch ein Schlüsselwort oder die KI erkannt wurde.
|
||||
* **Quellen-Karten:** Unter der Antwort findest du ausklappbare Karten ("Expanders").
|
||||
* **Grüner Punkt:** Hohe Relevanz (Score > 0.8).
|
||||
* **Gelber Punkt:** Mittlere Relevanz.
|
||||
* **Klick darauf:** Zeigt den Textauszug und die **Begründung** ("Warum wurde das gefunden?").
|
||||
|
||||
### 2.2 Die Sidebar (Einstellungen & Verlauf)
|
||||
* **Modus-Wahl:** Umschalten zwischen "💬 Chat" und "📝 Neuer Eintrag" (Vorbereitung für WP07).
|
||||
* **Verlauf:** Die letzten Suchanfragen sind hier gelistet. Ein Klick führt die Suche erneut aus.
|
||||
* **Settings:**
|
||||
* **Top-K:** Wie viele Quellen sollen gelesen werden? (Standard: 5).
|
||||
* **Explanation Layer:** Schaltet die "Warum"-Erklärungen an/aus.
|
||||
|
||||
---
|
||||
|
||||
## 3. Den Chat steuern (Intents)
|
||||
|
||||
Du steuerst die Persönlichkeit von Mindnet durch deine Wortwahl. Das System nutzt einen **Hybrid Router**, der sowohl auf Schlüsselwörter als auch auf die Bedeutung achtet.
|
||||
|
||||
### 2.1 Modus: Entscheidung ("Der Berater")
|
||||
### 3.1 Modus: Entscheidung ("Der Berater")
|
||||
Wenn du vor einer Wahl stehst, hilft Mindnet dir, konform zu deinen Prinzipien zu bleiben.
|
||||
|
||||
* **Auslöser (Keywords):** "Soll ich...", "Was ist deine Meinung?", "Strategie für...", "Vor- und Nachteile".
|
||||
|
|
@ -41,68 +62,57 @@ Wenn du vor einer Wahl stehst, hilft Mindnet dir, konform zu deinen Prinzipien z
|
|||
* *Du:* "Soll ich Tool X nutzen?"
|
||||
* *Mindnet:* "Nein. Tool X speichert Daten in den USA. Das verstößt gegen dein Prinzip 'Privacy First' und dein Ziel 'Digitale Autarkie'."
|
||||
|
||||
### 2.2 Modus: Empathie ("Der Spiegel")
|
||||
### 3.2 Modus: Empathie ("Der Spiegel")
|
||||
Wenn du frustriert bist oder reflektieren willst, wechselt Mindnet in den "Ich"-Modus.
|
||||
|
||||
* **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.
|
||||
* **Beispiel-Dialog:**
|
||||
* *Du:* "Ich bin total überfordert, nichts funktioniert."
|
||||
* *Mindnet:* "Das Gefühl kenne ich. Erinnere dich an die Situation im Projekt X ('Der Durchbruch nach der Krise'). Damals hat uns das Mantra 'Einfach weitermachen, der Nebel lichtet sich' geholfen."
|
||||
|
||||
### 2.3 Modus: Coding ("Der Techniker")
|
||||
* **Auslöser:** "Code", "Python", "Funktion", "Syntax".
|
||||
* **Was passiert:** Mindnet antwortet kurz, prägnant und liefert Code-Blöcke. Smalltalk wird reduziert.
|
||||
|
||||
### 2.4 Modus: Fakten (Standard)
|
||||
### 3.3 Modus: Fakten (Standard)
|
||||
* **Auslöser:** Alles andere. "Was ist Qdrant?", "Zusammenfassung von X".
|
||||
* **Was passiert:** Standard-Suche nach Wissen ohne spezielle Filter.
|
||||
|
||||
---
|
||||
|
||||
## 3. Ergebnisse interpretieren (Explanation Layer)
|
||||
## 4. Ergebnisse interpretieren (Explanation Layer)
|
||||
|
||||
Mindnet liefert nicht einfach nur Treffer. Es liefert eine **Begründung** (Explanation), warum es etwas gefunden hat.
|
||||
|
||||
### 3.1 Die Gründe ("Reasons")
|
||||
Das System sagt dir in natürlicher Sprache, warum ein Treffer relevant ist:
|
||||
### 4.1 Die Gründe ("Reasons")
|
||||
Öffne eine Quellen-Karte, um zu sehen:
|
||||
* *"Hohe textuelle Übereinstimmung."* (Semantik)
|
||||
* *"Bevorzugt aufgrund des Typs 'decision'."* (Wichtigkeit)
|
||||
* *"Verweist auf 'Projekt X' via 'depends_on'."* (Graph-Kontext)
|
||||
|
||||
### 3.2 Der Score Breakdown
|
||||
Wenn du es genau wissen willst, schau auf die Aufschlüsselung:
|
||||
|
||||
Score = (Text) + (Typ-Bonus) + (Vernetzungs-Bonus)
|
||||
|
||||
---
|
||||
|
||||
## 4. Neues Wissen beisteuern (Authoring)
|
||||
|
||||
Mindnet lebt von deinem Input. Du musst kein Techniker sein, um gutes Wissen zu designen. Siehe dazu das **Knowledge Design Manual** für Details.
|
||||
|
||||
### 4.1 Die Goldene Regel: "Verlinke semantisch"
|
||||
Statt einfach nur `[[Link]]` zu schreiben, versuche zu sagen, *wie* es zusammenhängt.
|
||||
* Hängt es davon ab? -> `[[rel:depends_on Ziel]]`
|
||||
* Ist es ähnlich? -> `[[rel:similar_to Ziel]]`
|
||||
|
||||
### 4.2 Typen nutzen (Wichtig!)
|
||||
Setze im Frontmatter deiner Notizen den richtigen Typ. Das ist der wichtigste Hebel für den Chat:
|
||||
* Willst du, dass Mindnet etwas als **Regel** nutzt? -> `type: principle`
|
||||
* Willst du, dass Mindnet dich an eine **Lektion** erinnert? -> `type: experience`
|
||||
|
||||
---
|
||||
|
||||
## 5. Feedback & Lernen
|
||||
|
||||
Mindnet wird schlauer, wenn du es pflegst.
|
||||
Mindnet wird schlauer, wenn du es pflegst. Nutze die Feedback-Funktionen im Chat:
|
||||
|
||||
### 5.1 Feedback geben (Data Flywheel)
|
||||
Das System zeichnet auf, welche Ergebnisse es liefert. Du kannst Treffer bewerten (geplant für WP-10 UI).
|
||||
In Zukunft analysiert das System diese Daten, um seine Gewichte selbstständig anzupassen (Self-Tuning).
|
||||
### 5.1 Globales Feedback (Antwort-Qualität)
|
||||
* **Wie:** Klicke auf die **Sterne (1-5)** unter der Antwort.
|
||||
* **Bedeutung:** Bewertet, wie gut die generierte Antwort war (Prompting, Tonfall).
|
||||
|
||||
### 5.2 Ergebnis fehlt? Troubleshooting
|
||||
Wenn Mindnet etwas nicht findet:
|
||||
1. **Existiert** die Notiz im Vault? (Dateiname korrekt?)
|
||||
2. **Typ korrekt?** (Eine Erfahrung als `concept` getaggt wird im Empathie-Modus vielleicht übersehen).
|
||||
3. **Keywords?** (Wenn du "grau" sagst, aber in der Notiz nur "schlecht" steht, füge das Wort "grau" zur Notiz hinzu).
|
||||
### 5.2 Granulares Feedback (Quellen-Relevanz)
|
||||
* **Wie:** Klicke innerhalb einer Quellen-Karte auf die **Smileys (Faces)**.
|
||||
* **Bedeutung:**
|
||||
* 😞 (Sad): Diese Quelle ist irrelevant/falsch. (Senkt zukünftig das Gewicht).
|
||||
* 😐 (Neutral): Okay, aber nicht entscheidend.
|
||||
* 😀 (Grin): Das ist der perfekte Treffer! (Stärkt diesen Typ/Kante).
|
||||
|
||||
---
|
||||
|
||||
## 6. Neues Wissen beisteuern (Authoring)
|
||||
|
||||
Mindnet lebt von deinem Input. Du musst kein Techniker sein, um gutes Wissen zu designen. Siehe dazu das **Knowledge Design Manual** für Details.
|
||||
|
||||
### 6.1 Die Goldene Regel: "Verlinke semantisch"
|
||||
Statt einfach nur `[[Link]]` zu schreiben, versuche zu sagen, *wie* es zusammenhängt.
|
||||
* Hängt es davon ab? -> `[[rel:depends_on Ziel]]`
|
||||
* Ist es ähnlich? -> `[[rel:similar_to Ziel]]`
|
||||
|
||||
### 6.2 Typen nutzen (Wichtig!)
|
||||
Setze im Frontmatter deiner Notizen den richtigen Typ. Das ist der wichtigste Hebel für den Chat:
|
||||
* Willst du, dass Mindnet etwas als **Regel** nutzt? -> `type: principle`
|
||||
* Willst du, dass Mindnet dich an eine **Lektion** erinnert? -> `type: experience`
|
||||
Loading…
Reference in New Issue
Block a user