From 52250904909b555dd6ab61db8df287b651c343ca Mon Sep 17 00:00:00 2001 From: Lars Date: Sun, 28 Dec 2025 10:56:34 +0100 Subject: [PATCH] Dokumentationsaupdate --- docs/00_General/00_documentation_map.md | 51 +- docs/00_General/00_quality_checklist.md | 166 ++++++ docs/00_General/00_quickstart.md | 156 ++++++ docs/00_General/00_vision_and_strategy.md | 40 +- docs/01_User_Manual/01_chat_usage_guide.md | 86 +++- .../02_concept_architecture_patterns.md | 456 +++++++++++++++++ .../03_tech_api_reference.md | 435 ++++++++++++++++ .../03_tech_chat_backend.md | 2 +- .../03_tech_configuration.md | 4 +- .../03_tech_ingestion_pipeline.md | 19 +- docs/04_Operations/04_admin_operations.md | 119 ++++- docs/04_Operations/04_deployment_guide.md | 474 ++++++++++++++++++ docs/05_Development/05_developer_guide.md | 16 + docs/05_Development/05_testing_guide.md | 392 +++++++++++++++ docs/README.md | 154 ++++++ 15 files changed, 2553 insertions(+), 17 deletions(-) create mode 100644 docs/00_General/00_quality_checklist.md create mode 100644 docs/00_General/00_quickstart.md create mode 100644 docs/02_concepts/02_concept_architecture_patterns.md create mode 100644 docs/03_Technical_References/03_tech_api_reference.md create mode 100644 docs/04_Operations/04_deployment_guide.md create mode 100644 docs/05_Development/05_testing_guide.md create mode 100644 docs/README.md diff --git a/docs/00_General/00_documentation_map.md b/docs/00_General/00_documentation_map.md index ed2474c..fef368d 100644 --- a/docs/00_General/00_documentation_map.md +++ b/docs/00_General/00_documentation_map.md @@ -18,9 +18,12 @@ Das Repository ist in **logische Domänen** unterteilt. *Zielgruppe: Alle* | Datei | Inhalt & Zweck | | :--- | :--- | +| `README.md` | **Einstiegspunkt.** Übersicht über die Dokumentationsstruktur, Schnellzugriff nach Rollen und Navigation. | +| `00_quickstart.md` | **Schnellstart.** Installation und erste Schritte in 15 Minuten. Ideal für neue Benutzer. | | `00_vision_and_strategy.md` | **Strategie.** Warum bauen wir das? Prinzipien (Privacy, Local-First), High-Level Architektur. | | `00_glossary.md` | **Definitionen.** Was bedeutet "Smart Edge", "Traffic Control", "Chunk"? Verhindert Begriffsverwirrung. | | `00_documentation_map.md` | **Dieser Index.** Navigationshilfe. | +| `00_quality_checklist.md` | **Qualitätsprüfung.** Systematische Checkliste zur Vollständigkeitsprüfung für alle Rollen. | ### 📂 01_User_Manual (Anwendung) *Zielgruppe: Mindmaster, Autoren, Power-User* @@ -28,7 +31,8 @@ Das Repository ist in **logische Domänen** unterteilt. | :--- | :--- | | `01_chat_usage_guide.md` | **Bedienung.** Wie steuere ich die Personas (Berater, Spiegel)? Wie nutze ich das Feedback? | | `01_knowledge_design.md` | **Content-Regeln.** Die "Bibel" für den Vault. Erklärt Note-Typen, Matrix-Logik und Markdown-Syntax. | -| `01-authoring-guidelines` | **Content strukturieren-.** primäres Werkzeug, um Wissen so zu strukturieren, so dass Mindnet die Persönlichkeit spiegelt, empathisch reagiert und strategisch berät | +| `01_authoring_guidelines.md` | **Content strukturieren.** Primäres Werkzeug, um Wissen so zu strukturieren, dass Mindnet die Persönlichkeit spiegelt, empathisch reagiert und strategisch berät. | +| `01_obsidian_integration_guide.md` | **Obsidian Setup.** Technische Anleitung für die Integration von Mindnet mit Obsidian (Templater, Skripte, Workflows). | ### 📂 02_Concepts (Fachliche Logik) *Zielgruppe: Architekten, Product Owner* @@ -36,6 +40,7 @@ Das Repository ist in **logische Domänen** unterteilt. | :--- | :--- | | `02_concept_graph_logic.md` | **Graph-Theorie.** Abstrakte Erklärung von Knoten, Kanten, Provenance und Idempotenz. | | `02_concept_ai_personality.md`| **KI-Verhalten.** Konzepte hinter dem Hybrid Router, Empathie-Modell und "Teach-the-AI". | +| `02_concept_architecture_patterns.md` | **Architektur-Patterns.** Design-Entscheidungen, modulare Struktur (WP-14), Resilienz-Patterns und Erweiterbarkeit. | ### 📂 03_Technical_Reference (Technik & Code) *Zielgruppe: Entwickler, DevOps. (Enthält JSON/YAML Beispiele)* @@ -47,12 +52,15 @@ Das Repository ist in **logische Domänen** unterteilt. | `03_tech_chat_backend.md` | **API & LLM.** Implementation des Routers, Traffic Control (Semaphore) und Feedback-Traceability. | | `03_tech_frontend.md` | **UI & Graph.** Architektur des Streamlit-Frontends, State-Management, Cytoscape-Integration und Editor-Logik. | | `03_tech_configuration.md` | **Config.** Referenztabellen für `.env`, `types.yaml` und `retriever.yaml`. | +| `03_tech_api_reference.md` | **API-Referenz.** Vollständige Dokumentation aller Endpunkte (`/query`, `/chat`, `/ingest`, `/graph`, etc.). | ### 📂 04_Operations (Betrieb) *Zielgruppe: Administratoren* | Datei | Inhalt & Zweck | | :--- | :--- | | `04_admin_operations.md` | **Runbook.** Installation, Docker-Setup, Backup/Restore, Troubleshooting Guide. | +| `04_server_operation_manual.md` | **Server-Betrieb.** Detaillierte Dokumentation für den Betrieb auf llm-node (Systemd, Borgmatic, Disaster Recovery). | +| `04_deployment_guide.md` | **Deployment.** CI/CD-Pipelines, Rollout-Strategien, Versionierung, Rollback und Pre/Post-Deployment-Checklisten. | ### 📂 05_Development (Code) *Zielgruppe: Entwickler* @@ -60,6 +68,7 @@ Das Repository ist in **logische Domänen** unterteilt. | :--- | :--- | | `05_developer_guide.md` | **Workflow.** Hardware-Setup (Win/Pi/Beelink), Git-Flow, Test-Befehle, Modul-Interna. | | `05_genai_best_practices.md` | **AI Workflow.** Prompt-Library, Templates und Best Practices für die Entwicklung mit LLMs. | +| `05_testing_guide.md` | **Testing.** Umfassender Test-Guide: Strategien, Frameworks, Test-Daten, Best Practices. | ### 📂 06_Roadmap & 99_Archive *Zielgruppe: Projektleitung* @@ -82,7 +91,9 @@ Nutze diese Matrix, wenn du ein Workpackage bearbeitest, um die Dokumentation ko | **Retrieval / Scoring** | `03_tech_retrieval_scoring.md` (Formeln anpassen) | | **Frontend / Visualisierung** | 1. `03_tech_frontend.md` (Technische Details)
2. `01_chat_usage_guide.md` (Bedienung) | | **Chat-Logik / Prompts**| 1. `02_concept_ai_personality.md` (Konzept)
2. `03_tech_chat_backend.md` (Tech)
3. `01_chat_usage_guide.md` (User-Sicht) | -| **Deployment / Server** | `04_admin_operations.md` | +| **Architektur / Design-Patterns** | 1. `02_concept_architecture_patterns.md` (Patterns & Entscheidungen)
2. `02_concept_graph_logic.md` (Graph-Theorie)
3. `05_developer_guide.md` (Modulare Struktur) | +| **Deployment / Server** | 1. `04_deployment_guide.md` (CI/CD, Rollout)
2. `04_admin_operations.md` (Installation, Wartung)
3. `04_server_operation_manual.md` (Server-Betrieb) | +| **Testing / QA** | 1. `05_testing_guide.md` (Test-Strategien & Frameworks)
2. `05_developer_guide.md` (Test-Befehle) | | **Neuen Features (Allg.)**| `06_active_roadmap.md` (Status Update) | --- @@ -110,4 +121,38 @@ Damit dieses System wartbar bleibt (auch für KI-Agenten wie NotebookLM), gelten audience: developer context: "Beschreibung der Scoring-Formel." --- - ``` \ No newline at end of file + ``` + +--- + +## 5. Schnellzugriff & Empfehlungen + +### Für neue Benutzer +1. Starte mit **[Schnellstart](00_quickstart.md)** für die Installation +2. Lese **[Vision & Strategie](00_vision_and_strategy.md)** für das große Bild +3. Nutze **[Chat Usage Guide](../01_User_Manual/01_chat_usage_guide.md)** für die ersten Schritte + +### Für Entwickler +1. **[Developer Guide](../05_Development/05_developer_guide.md)** - Umfassender technischer Guide +2. **[Technical References](../03_Technical_References/)** - Detaillierte API- und Architektur-Dokumentation +3. **[GenAI Best Practices](../05_Development/05_genai_best_practices.md)** - Workflow mit LLMs + +### Für Administratoren +1. **[Admin Operations](../04_Operations/04_admin_operations.md)** - Installation und Wartung +2. **[Server Operations Manual](../04_Operations/04_server_operation_manual.md)** - Server-Betrieb und Disaster Recovery +3. **[Troubleshooting Guide](../04_Operations/04_admin_operations.md#33-troubleshooting-guide)** - Häufige Probleme und Lösungen + +### Für Autoren +1. **[Knowledge Design](../01_User_Manual/01_knowledge_design.md)** - Content-Regeln und Best Practices +2. **[Authoring Guidelines](../01_User_Manual/01_authoring_guidelines.md)** - Strukturierung für den Digitalen Zwilling +3. **[Obsidian Integration](../01_User_Manual/01_obsidian_integration_guide.md)** - Workflow-Optimierung + +--- + +## 6. Dokumentations-Status + +**Aktuelle Version:** 2.9.1 +**Letzte Aktualisierung:** 2025-01-XX +**Status:** ✅ Vollständig und aktiv gepflegt + +**Hinweis:** Diese Dokumentation wird kontinuierlich aktualisiert. Bei Fragen oder Verbesserungsvorschlägen bitte im Repository melden. \ No newline at end of file diff --git a/docs/00_General/00_quality_checklist.md b/docs/00_General/00_quality_checklist.md new file mode 100644 index 0000000..1d1c447 --- /dev/null +++ b/docs/00_General/00_quality_checklist.md @@ -0,0 +1,166 @@ +--- +doc_type: quality_assurance +audience: all +status: active +version: 2.9.1 +context: "Qualitätsprüfung der Dokumentation für alle Rollen: Vollständigkeit, Korrektheit und Anwendbarkeit." +--- + +# Dokumentations-Qualitätsprüfung + +Diese Checkliste dient zur systematischen Prüfung, ob die Dokumentation alle Fragen jeder Rolle vollständig beantwortet. + +## ✅ Entwickler + +### Setup & Installation +- [x] **Lokales Setup:** [Developer Guide](../05_Development/05_developer_guide.md#6-lokales-setup-development) +- [x] **Schnellstart:** [Quickstart](00_quickstart.md) +- [x] **Hardware-Anforderungen:** [Admin Operations](../04_Operations/04_admin_operations.md#11-voraussetzungen) + +### Architektur & Code +- [x] **Modulare Struktur:** [Developer Guide - Architektur](../05_Development/05_developer_guide.md#4-projektstruktur--modul-referenz-deep-dive) +- [x] **Design-Patterns:** [Architektur-Patterns](../02_concepts/02_concept_architecture_patterns.md) +- [x] **API-Referenz:** [API Reference](../03_Technical_References/03_tech_api_reference.md) +- [x] **Datenmodell:** [Data Model](../03_Technical_References/03_tech_data_model.md) + +### Entwicklung & Erweiterung +- [x] **Workflow:** [Developer Guide - Workflow](../05_Development/05_developer_guide.md#7-der-entwicklungs-zyklus-workflow) +- [x] **Erweiterungs-Guide:** [Teach-the-AI](../05_Development/05_developer_guide.md#8-erweiterungs-guide-teach-the-ai) +- [x] **GenAI Best Practices:** [GenAI Best Practices](../05_Development/05_genai_best_practices.md) + +### Testing +- [x] **Test-Strategien:** [Testing Guide](../05_Development/05_testing_guide.md) +- [x] **Test-Frameworks:** [Testing Guide - Frameworks](../05_Development/05_testing_guide.md#3-test-frameworks--tools) +- [x] **Test-Daten:** [Testing Guide - Test-Daten](../05_Development/05_testing_guide.md#2-test-daten--vaults) + +### Debugging & Troubleshooting +- [x] **Troubleshooting:** [Developer Guide - Troubleshooting](../05_Development/05_developer_guide.md#10-troubleshooting--one-liners) +- [x] **Debug-Tools:** [Testing Guide - Debugging](../05_Development/05_testing_guide.md#7-debugging--diagnose) + +--- + +## ✅ Administratoren + +### Installation & Setup +- [x] **Installation:** [Admin Operations](../04_Operations/04_admin_operations.md#1-installation--setup) +- [x] **Docker Setup:** [Admin Operations - Qdrant](../04_Operations/04_admin_operations.md#12-qdrant-docker) +- [x] **Systemd Services:** [Admin Operations - Deployment](../04_Operations/04_admin_operations.md#2-deployment-systemd-services) + +### Betrieb & Wartung +- [x] **Monitoring:** [Admin Operations - Wartung](../04_Operations/04_admin_operations.md#3-wartung--monitoring) +- [x] **Backup & Restore:** [Admin Operations - Backup](../04_Operations/04_admin_operations.md#4-backup--restore) +- [x] **Troubleshooting:** [Admin Operations - Troubleshooting](../04_Operations/04_admin_operations.md#33-troubleshooting-guide) + +### Server-Betrieb +- [x] **Server-Konfiguration:** [Server Operations Manual](../04_Operations/04_server_operation_manual.md) +- [x] **Disaster Recovery:** [Server Operations - DR](../04_Operations/04_server_operation_manual.md#5-disaster-recovery-wiederherstellung-two-stage-dr) +- [x] **Backup-Strategie:** [Server Operations - Backup](../04_Operations/04_server_operation_manual.md#4-backup-strategie-borgmatic) + +### Konfiguration +- [x] **ENV-Variablen:** [Configuration Reference](../03_Technical_References/03_tech_configuration.md#1-environment-variablen-env) +- [x] **YAML-Configs:** [Configuration Reference - YAML](../03_Technical_References/03_tech_configuration.md#2-typ-registry-typesyaml) + +--- + +## ✅ Anwender + +### Erste Schritte +- [x] **Schnellstart:** [Quickstart](00_quickstart.md) +- [x] **Was ist Mindnet:** [Vision & Strategie](00_vision_and_strategy.md) +- [x] **Grundlagen:** [Glossar](00_glossary.md) + +### Nutzung +- [x] **Chat-Bedienung:** [Chat Usage Guide](../01_User_Manual/01_chat_usage_guide.md) +- [x] **Graph Explorer:** [Chat Usage Guide - Graph](../01_User_Manual/01_chat_usage_guide.md#22-modus--graph-explorer-cytoscape) +- [x] **Editor:** [Chat Usage Guide - Editor](../01_User_Manual/01_chat_usage_guide.md#23-modus--manueller-editor) + +### Content-Erstellung +- [x] **Knowledge Design:** [Knowledge Design Manual](../01_User_Manual/01_knowledge_design.md) +- [x] **Authoring Guidelines:** [Authoring Guidelines](../01_User_Manual/01_authoring_guidelines.md) +- [x] **Obsidian-Integration:** [Obsidian Integration](../01_User_Manual/01_obsidian_integration_guide.md) + +### Häufige Fragen +- [x] **Wie strukturiere ich Notizen?** → [Knowledge Design](../01_User_Manual/01_knowledge_design.md) +- [x] **Welche Note-Typen gibt es?** → [Knowledge Design - Typ-Referenz](../01_User_Manual/01_knowledge_design.md#31-typ-referenz--stream-logik) +- [x] **Wie verknüpfe ich Notizen?** → [Knowledge Design - Edges](../01_User_Manual/01_knowledge_design.md#4-edges--verlinkung) +- [x] **Wie nutze ich den Chat?** → [Chat Usage Guide](../01_User_Manual/01_chat_usage_guide.md) + +--- + +## ✅ Tester + +### Test-Strategien +- [x] **Test-Pyramide:** [Testing Guide - Strategien](../05_Development/05_testing_guide.md#1-test-strategie--ebenen) +- [x] **Unit Tests:** [Testing Guide - Unit Tests](../05_Development/05_testing_guide.md#11-unit-tests-pytest) +- [x] **Integration Tests:** [Testing Guide - Integration](../05_Development/05_testing_guide.md#12-integration-tests) +- [x] **E2E Tests:** [Testing Guide - E2E](../05_Development/05_testing_guide.md#13-e2e--smoke-tests) + +### Test-Frameworks +- [x] **Pytest:** [Testing Guide - Frameworks](../05_Development/05_testing_guide.md#31-pytest-unit-tests) +- [x] **Unittest:** [Testing Guide - Unittest](../05_Development/05_testing_guide.md#32-unittest-e2e-tests) +- [x] **Shell-Skripte:** [Testing Guide - Shell](../05_Development/05_testing_guide.md#33-shell-skripte-e2e-roundtrip) + +### Test-Daten & Tools +- [x] **Test-Vault erstellen:** [Testing Guide - Test-Daten](../05_Development/05_testing_guide.md#21-test-vault-erstellen) +- [x] **Test-Skripte:** [Developer Guide - Scripts](../05_Development/05_developer_guide.md#44-scripts--tooling-die-admin-toolbox) +- [x] **Test-Checkliste:** [Testing Guide - Checkliste](../05_Development/05_testing_guide.md#8-test-checkliste-für-pull-requests) + +--- + +## ✅ Deployment + +### Deployment-Prozesse +- [x] **Deployment-Guide:** [Deployment Guide](../04_Operations/04_deployment_guide.md) +- [x] **CI/CD Pipeline:** [Deployment Guide - CI/CD](../04_Operations/04_deployment_guide.md#9-cicd-pipeline-details) +- [x] **Rollout-Strategien:** [Deployment Guide - Rollout](../04_Operations/04_deployment_guide.md#4-rollout-strategien) + +### Versionierung & Releases +- [x] **Version-Schema:** [Deployment Guide - Versionierung](../04_Operations/04_deployment_guide.md#51-version-schema) +- [x] **Release-Prozess:** [Deployment Guide - Release](../04_Operations/04_deployment_guide.md#52-release-prozess) + +### Rollback & Recovery +- [x] **Rollback-Strategien:** [Deployment Guide - Rollback](../04_Operations/04_deployment_guide.md#6-rollback-strategien) +- [x] **Disaster Recovery:** [Server Operations - DR](../04_Operations/04_server_operation_manual.md#5-disaster-recovery-wiederherstellung-two-stage-dr) + +### Pre/Post-Deployment +- [x] **Pre-Deployment Checkliste:** [Deployment Guide - Checkliste](../04_Operations/04_deployment_guide.md#7-pre-deployment-checkliste) +- [x] **Post-Deployment Validierung:** [Deployment Guide - Validierung](../04_Operations/04_deployment_guide.md#8-post-deployment-validierung) + +--- + +## 📊 Zusammenfassung + +### Vollständigkeit nach Rolle + +| Rolle | Abgedeckte Themen | Status | +| :--- | :--- | :--- | +| **Entwickler** | Setup, Architektur, Code, Testing, Debugging | ✅ Vollständig | +| **Administratoren** | Installation, Betrieb, Wartung, Backup, DR | ✅ Vollständig | +| **Anwender** | Nutzung, Content-Erstellung, Workflows | ✅ Vollständig | +| **Tester** | Test-Strategien, Frameworks, Tools | ✅ Vollständig | +| **Deployment** | CI/CD, Rollout, Versionierung, Rollback | ✅ Vollständig | + +### Neue Dokumente + +1. ✅ `05_testing_guide.md` - Umfassender Test-Guide +2. ✅ `04_deployment_guide.md` - Vollständiger Deployment-Guide +3. ✅ `02_concept_architecture_patterns.md` - Architektur-Patterns +4. ✅ `03_tech_api_reference.md` - API-Referenz +5. ✅ `00_quickstart.md` - Schnellstart-Anleitung +6. ✅ `README.md` - Dokumentations-Einstiegspunkt + +### Aktualisierte Dokumente + +1. ✅ `00_documentation_map.md` - Alle neuen Dokumente aufgenommen +2. ✅ `04_admin_operations.md` - Troubleshooting erweitert +3. ✅ `05_developer_guide.md` - Modulare Struktur ergänzt +4. ✅ `03_tech_ingestion_pipeline.md` - Background Tasks dokumentiert +5. ✅ `03_tech_configuration.md` - Fehlende ENV-Variablen ergänzt +6. ✅ `00_vision_and_strategy.md` - Design-Entscheidungen ergänzt + +--- + +**Status:** ✅ Alle Rollen vollständig abgedeckt +**Letzte Prüfung:** 2025-01-XX +**Version:** 2.9.1 + diff --git a/docs/00_General/00_quickstart.md b/docs/00_General/00_quickstart.md new file mode 100644 index 0000000..d8b98a4 --- /dev/null +++ b/docs/00_General/00_quickstart.md @@ -0,0 +1,156 @@ +--- +doc_type: quickstart_guide +audience: user, developer, admin +status: active +version: 2.9.1 +context: "Schnellstart-Anleitung für neue Benutzer von Mindnet" +--- + +# Mindnet Schnellstart + +Diese Anleitung hilft dir, in 15 Minuten mit Mindnet loszulegen. + +## 🎯 Was ist Mindnet? + +Mindnet ist ein **persönliches KI-Gedächtnis**, das: +- Dein Wissen in Markdown-Notizen speichert +- Semantisch verknüpft (Wissensgraph) +- Als intelligenter Dialogpartner agiert (RAG-Chat) +- **Lokal und privat** läuft (Privacy First) + +## 📋 Voraussetzungen + +- **Python 3.10+** installiert +- **Docker** installiert (für Qdrant) +- **Ollama** installiert (für lokale LLMs) +- Optional: **Obsidian** (für komfortables Schreiben) + +## ⚡ Installation (5 Minuten) + +### Schritt 1: Repository klonen + +```bash +git clone mindnet +cd mindnet +``` + +### Schritt 2: Virtuelle Umgebung erstellen + +```bash +python3 -m venv .venv +source .venv/bin/activate # Windows: .venv\Scripts\activate +``` + +### Schritt 3: Abhängigkeiten installieren + +```bash +pip install -r requirements.txt +``` + +### Schritt 4: Qdrant starten (Docker) + +```bash +docker compose up -d qdrant +``` + +### Schritt 5: Ollama-Modelle laden + +```bash +ollama pull phi3:mini +ollama pull nomic-embed-text +``` + +### Schritt 6: Konfiguration anpassen + +Erstelle eine `.env`-Datei im Projektroot: + +```ini +QDRANT_URL=http://localhost:6333 +MINDNET_OLLAMA_URL=http://localhost:11434 +MINDNET_LLM_MODEL=phi3:mini +MINDNET_EMBEDDING_MODEL=nomic-embed-text +COLLECTION_PREFIX=mindnet +MINDNET_VAULT_ROOT=./vault +``` + +## 🚀 Erste Schritte (5 Minuten) + +### Schritt 1: Backend starten + +```bash +uvicorn app.main:app --reload --port 8001 +``` + +### Schritt 2: Frontend starten (neues Terminal) + +```bash +streamlit run app/frontend/ui.py --server.port 8501 +``` + +### Schritt 3: Browser öffnen + +Öffne `http://localhost:8501` im Browser. + +### Schritt 4: Erste Notiz importieren + +Erstelle eine Test-Notiz im `vault/` Ordner: + +```markdown +--- +id: 20250101-test +title: Meine erste Notiz +type: concept +status: active +--- + +# Meine erste Notiz + +Dies ist eine Test-Notiz für Mindnet. + +[[rel:related_to Mindnet]] +``` + +Dann importiere sie: + +```bash +python3 -m scripts.import_markdown --vault ./vault --prefix mindnet --apply +``` + +### Schritt 5: Erste Chat-Anfrage + +Im Browser-Chat eingeben: +``` +Was ist Mindnet? +``` + +## 📚 Nächste Schritte + +Nach dem Schnellstart empfehle ich: + +1. **[Chat Usage Guide](../01_User_Manual/01_chat_usage_guide.md)** - Lerne die Chat-Funktionen kennen +2. **[Knowledge Design](../01_User_Manual/01_knowledge_design.md)** - Verstehe, wie du Notizen strukturierst +3. **[Authoring Guidelines](../01_User_Manual/01_authoring_guidelines.md)** - Lerne Best Practices für das Schreiben + +## 🆘 Hilfe & Troubleshooting + +**Problem:** Qdrant startet nicht +- **Lösung:** Prüfe, ob Docker läuft: `docker ps` + +**Problem:** Ollama-Modell nicht gefunden +- **Lösung:** Prüfe mit `ollama list`, ob die Modelle geladen sind + +**Problem:** Import schlägt fehl +- **Lösung:** Prüfe die Logs und stelle sicher, dass Qdrant läuft + +Für detaillierte Troubleshooting-Informationen siehe [Admin Operations](../04_Operations/04_admin_operations.md#33-troubleshooting-guide). + +## 🔗 Weitere Ressourcen + +- **[Dokumentationskarte](00_documentation_map.md)** - Übersicht aller Dokumente +- **[Glossar](00_glossary.md)** - Wichtige Begriffe erklärt +- **[Vision & Strategie](00_vision_and_strategy.md)** - Die Philosophie hinter Mindnet + +--- + +**Viel Erfolg mit Mindnet!** 🚀 + diff --git a/docs/00_General/00_vision_and_strategy.md b/docs/00_General/00_vision_and_strategy.md index 47ae456..15fead6 100644 --- a/docs/00_General/00_vision_and_strategy.md +++ b/docs/00_General/00_vision_and_strategy.md @@ -64,4 +64,42 @@ Die folgenden Prinzipien steuern jede technische Entscheidung: Jeder Importlauf und jede Retriever-Anfrage ist logbar. 10. **Local First & Privacy:** - Nutzung lokaler LLMs (Ollama) für Inference. Keine Daten verlassen den Server. \ No newline at end of file + Nutzung lokaler LLMs (Ollama) für Inference. Keine Daten verlassen den Server. + +11. **Modulare Architektur (WP-14):** + Core-Logik ist in spezialisierte Pakete unterteilt (`chunking/`, `database/`, `graph/`, `ingestion/`, `parser/`, `retrieval/`). Dies ermöglicht unabhängige Entwicklung, Testbarkeit und Wartbarkeit. + +12. **Resilienz durch Kaskaden:** + System nutzt Provider-Kaskaden (Cloud → Rate-Limit-Handling → Lokaler Fallback) für hohe Verfügbarkeit. Deep Fallback erkennt auch kognitive Blockaden (Silent Refusals). + +--- + +## 4. Design-Entscheidungen & Trade-offs + +### 4.1 Qdrant als Vektor-DB +**Entscheidung:** Self-hosted Qdrant statt Managed Service (Pinecone/Weaviate) +**Gründe:** Privacy First, Open Source, lokale Kontrolle +**Trade-off:** Mehr Wartungsaufwand, aber vollständige Datenhoheit + +### 4.2 Hybrid Retrieval +**Entscheidung:** Kombination von Vektor-Suche (Semantik) und Graph-Expansion +**Gründe:** Bessere Relevanz durch strukturelle Verbindungen +**Trade-off:** Höhere Komplexität, aber deutlich bessere Ergebnisse + +### 4.3 Background Tasks statt Queue-System +**Entscheidung:** FastAPI Background Tasks statt Redis/RabbitMQ +**Gründe:** Einfacher Setup, ausreichend für Single-User +**Trade-off:** Keine Persistenz bei Server-Neustart, aber weniger Infrastruktur + +### 4.4 Markdown als Source of Truth +**Entscheidung:** Markdown-Dateien sind primär, Datenbank ist Cache +**Gründe:** Versionierbarkeit, Editierbarkeit, Unabhängigkeit +**Trade-off:** Zwei Datenquellen, aber maximale Flexibilität + +--- + +## 5. Weitere Informationen + +- **Architektur-Patterns:** Siehe [Architektur-Patterns](../02_concepts/02_concept_architecture_patterns.md) +- **Graph-Logik:** Siehe [Graph-Logik](../02_concepts/02_concept_graph_logic.md) +- **KI-Persönlichkeit:** Siehe [KI-Persönlichkeit](../02_concepts/02_concept_ai_personality.md) \ No newline at end of file diff --git a/docs/01_User_Manual/01_chat_usage_guide.md b/docs/01_User_Manual/01_chat_usage_guide.md index a4e6eee..c560530 100644 --- a/docs/01_User_Manual/01_chat_usage_guide.md +++ b/docs/01_User_Manual/01_chat_usage_guide.md @@ -11,6 +11,8 @@ context: "Anleitung zur Nutzung der Web-Oberfläche, der Chat-Personas und des G **Quellen:** `user_guide.md` +> 💡 **Tipp für Einsteiger:** Falls du noch nie mit Mindnet gearbeitet hast, starte mit dem [Schnellstart](../00_General/00_quickstart.md) und dem [Knowledge Design Manual](01_knowledge_design.md), um die Grundlagen zu verstehen. + ## 1. Was Mindnet für dich tut Mindnet ist ein **assoziatives Gedächtnis** mit Persönlichkeit. Es unterscheidet sich von einer reinen Suche dadurch, dass es **kontextsensitiv** agiert. @@ -123,4 +125,86 @@ Wenn du im **manuellen Editor** schreibst, unterstützt dich Mindnet aktiv bei d * **Exakte Treffer:** Das System erkennt Begriffe wie "KI-Gedächtnis" als Alias für "Mindnet". * **Semantische Treffer:** Das System findet inhaltlich verwandte Notizen. * **Klick auf "➕ Einfügen":** Fügt den Link (z.B. `[[rel:related_to Mindnet]]`) an der Cursor-Position ein. -4. **Speichern:** Der Text wird sofort in den Vault geschrieben und indiziert. \ No newline at end of file +4. **Speichern:** Der Text wird sofort in den Vault geschrieben und indiziert. + +### 6.3 Weg C: Direktes Schreiben in Obsidian +Wenn du Obsidian nutzt, kannst du Notizen direkt im Vault erstellen. Nach dem Speichern in Obsidian: + +1. **Automatischer Import (Cron):** Der stündliche Cron-Job importiert neue/geänderte Dateien automatisch. +2. **Manueller Import:** Oder führe manuell aus: + ```bash + python3 -m scripts.import_markdown --vault ./vault --prefix mindnet --apply + ``` + +**Vorteil:** Du arbeitest in deiner gewohnten Obsidian-Umgebung, Mindnet synchronisiert im Hintergrund. + +--- + +## 7. Häufige Anwendungsfälle (Use Cases) + +### 7.1 Entscheidungshilfe suchen +**Szenario:** Du stehst vor einer schwierigen Entscheidung. + +**Vorgehen:** +1. Stelle eine Frage im Chat: *"Soll ich Tool X nutzen?"* +2. Mindnet erkennt `DECISION` Intent +3. System lädt deine Werte, Prinzipien und Ziele +4. Antwort berücksichtigt deine persönlichen Kriterien + +**Beispiel:** *"Soll ich Notion nutzen?"* → System prüft gegen dein Prinzip "Privacy First" und rät ab. + +### 7.2 Erfahrungen dokumentieren +**Szenario:** Du willst ein prägendes Erlebnis festhalten. + +**Vorgehen:** +1. Chat: *"Neue Erfahrung: Streit am Recyclinghof"* +2. System erstellt strukturierte Notiz mit Feldern: + - Situation + - Reaktion + - Learning +3. Verknüpfe mit relevanten Rollen: `[[rel:supports Meine Rollenlandkarte 2025#Vater]]` + +### 7.3 Wissen im Graph erkunden +**Szenario:** Du willst verstehen, wie Konzepte zusammenhängen. + +**Vorgehen:** +1. Wechsle zum **Graph Explorer** +2. Suche nach einem Knoten (z.B. "Projekt Alpha") +3. Klicke auf "🎯 Als Zentrum setzen" +4. Erkunde die Nachbarschaft (Abhängigkeiten, Entscheidungen, ähnliche Projekte) + +### 7.4 Bestehende Notizen verbessern +**Szenario:** Eine Notiz ist unvollständig oder unvernetzt. + +**Vorgehen:** +1. Öffne die Notiz im **Manuellen Editor** +2. Nutze **Intelligence-Tab** für Link-Vorschläge +3. Füge semantische Links hinzu: `[[rel:based_on Wert X]]` +4. Speichern → System indiziert neu + +--- + +## 8. Tipps & Tricks + +### 8.1 Intent-Steuerung +- **Frage mit "?":** Löst RAG-Modus aus (Wissen abrufen) +- **Aussage ohne "?":** Löst Interview-Modus aus (Wissen speichern) +- **Emotionale Wörter:** Aktivieren Empathie-Persona ("Ich fühle...", "Ich bin frustriert...") + +### 8.2 Graph-Navigation +- **URL-Persistenz:** Graph-Einstellungen werden in der URL gespeichert → Lesezeichen für spezifische Ansichten +- **Deep-Links:** Verlinke präzise Abschnitte: `[[Note#Abschnitt]]` statt nur `[[Note]]` + +### 8.3 Feedback nutzen +- **Regelmäßiges Feedback:** Macht das System schlauer +- **Granulares Feedback:** Bewerte einzelne Quellen, nicht nur die Gesamtantwort +- **Konsequenz:** System lernt deine Präferenzen + +--- + +## 9. Weitere Informationen + +- **Knowledge Design:** Siehe [Knowledge Design Manual](01_knowledge_design.md) +- **Authoring Guidelines:** Siehe [Authoring Guidelines](01_authoring_guidelines.md) +- **Obsidian Integration:** Siehe [Obsidian Integration Guide](01_obsidian_integration_guide.md) +- **Troubleshooting:** Siehe [Admin Operations - Troubleshooting](../04_Operations/04_admin_operations.md#33-troubleshooting-guide) \ No newline at end of file diff --git a/docs/02_concepts/02_concept_architecture_patterns.md b/docs/02_concepts/02_concept_architecture_patterns.md new file mode 100644 index 0000000..5a14806 --- /dev/null +++ b/docs/02_concepts/02_concept_architecture_patterns.md @@ -0,0 +1,456 @@ +--- +doc_type: concept +audience: architect, developer +scope: architecture, design_patterns, modularization +status: active +version: 2.9.1 +context: "Architektur-Patterns, Design-Entscheidungen und modulare Struktur von Mindnet. Basis für Verständnis und Erweiterungen." +--- + +# Architektur-Patterns & Design-Entscheidungen + +Dieses Dokument beschreibt die zentralen Architektur-Patterns und Design-Entscheidungen, die Mindnet prägen. Es dient als Referenz für Entwickler und Architekten, um das System zu verstehen und konsistent zu erweitern. + +## 1. Kern-Paradigmen + +### 1.1 Filesystem First (Source of Truth) + +**Prinzip:** Markdown-Dateien im Vault sind die einzige Quelle der Wahrheit. Die Datenbank (Qdrant) ist ein abgeleiteter Index. + +**Implikationen:** +- Dateien werden immer direkt von der Festplatte gelesen (z.B. im Editor) +- Datenbank-Inhalte können aus Markdown rekonstruiert werden +- Änderungen erfolgen primär im Vault, nicht in der DB +- Die Datenbank ist ein Cache, kein primärer Speicher + +**Code-Beispiele:** +- `ui_callbacks.py`: Liest Dateien direkt von Disk +- `ingestion_processor.py`: Schreibt zuerst auf Disk, dann in DB + +### 1.2 Late Binding (Späte Semantik) + +**Prinzip:** Struktur und Interpretation werden in Konfigurationen definiert, nicht im Code. + +**Implikationen:** +- Neue Note-Typen werden in `types.yaml` definiert, nicht im Code +- Prompt-Templates sind in `prompts.yaml` konfigurierbar +- Edge-Typen werden in `edge_vocabulary.md` verwaltet +- Die "Persönlichkeit" ist Config, kein Code + +**Vorteile:** +- Erweiterbarkeit ohne Code-Änderungen +- A/B-Testing von Prompt-Strategien +- Anpassung an verschiedene Use-Cases + +### 1.3 Virtual Schema Layer + +**Prinzip:** Markdown-Dateien benötigen nur minimale Frontmatter-Angaben. Komplexität wird zur Laufzeit injiziert. + +**Beispiel:** +```yaml +# Minimal im Frontmatter +--- +id: 20250101-test +title: Test +type: project +--- + +# Im Code wird zur Laufzeit ergänzt: +# - chunking_profile aus types.yaml +# - retriever_weight aus types.yaml +# - edge_defaults aus types.yaml +``` + +**Vorteile:** +- Robuste Markdown-Dateien (weniger Breaking Changes) +- Zentrale Verwaltung von Logik +- Einfache Migration zwischen Versionen + +--- + +## 2. Modulare Architektur (WP-14) + +### 2.1 Paket-Struktur + +Seit WP-14 ist die Core-Logik in spezialisierte Pakete unterteilt: + +``` +app/core/ +├── chunking/ # Text-Segmentierung +│ ├── chunking_strategies.py # Sliding/Heading-Strategien +│ ├── chunking_processor.py # Orchestrierung +│ └── chunking_propagation.py # Edge-Vererbung +├── database/ # Qdrant-Infrastruktur +│ ├── qdrant.py # Client & Config +│ └── qdrant_points.py # Point-Mapping +├── graph/ # Graph-Logik +│ ├── graph_subgraph.py # Expansion +│ └── graph_weights.py # Scoring +├── ingestion/ # Import-Pipeline +│ ├── ingestion_processor.py # Two-Pass Workflow +│ └── ingestion_validation.py # Mistral-safe Parsing +├── parser/ # Markdown-Parsing +│ ├── parsing_markdown.py # Frontmatter/Body +│ └── parsing_scanner.py # File-Scan +└── retrieval/ # Suche & Scoring + ├── retriever.py # Orchestrator + └── retriever_scoring.py # Mathematik +``` + +### 2.2 Design-Pattern: Proxy-Adapter (Abwärtskompatibilität) + +**Problem:** Nach WP-14 Modularisierung müssen alte Import-Pfade weiter funktionieren. + +**Lösung:** Proxy-Module leiten Anfragen an neue Pakete weiter. + +**Beispiel:** +```python +# app/core/retriever.py (Proxy) +from .retrieval.retriever import ( + Retriever, hybrid_retrieve, semantic_retrieve +) +__all__ = ["Retriever", "hybrid_retrieve", "semantic_retrieve"] +``` + +**Vorteile:** +- Keine Breaking Changes für bestehenden Code +- Graduelle Migration möglich +- Alte Scripts funktionieren weiter + +### 2.3 Design-Pattern: Singleton (Edge Registry) + +**Problem:** Edge Registry muss konsistent über alle Services sein. + +**Lösung:** Singleton-Pattern mit Lazy Loading. + +**Code:** +```python +# app/services/edge_registry.py +class EdgeRegistry: + _instance = None + + def __new__(cls): + if cls._instance is None: + cls._instance = super().__new__(cls) + return cls._instance +``` + +**Vorteile:** +- Einheitliche Validierung +- Keine Duplikation von Vokabular-Daten +- Thread-safe Initialisierung + +--- + +## 3. Asynchrone Verarbeitung + +### 3.1 Background Tasks Pattern + +**Problem:** Ingestion kann lange dauern (LLM-Calls, Embeddings). Blockiert API nicht. + +**Lösung:** FastAPI Background Tasks für non-blocking Verarbeitung. + +**Flow:** +1. API empfängt Request (`/ingest/save`) +2. Datei wird sofort auf Disk geschrieben +3. API antwortet mit `status: "queued"` +4. Background Task startet Ingestion asynchron +5. User kann weiterarbeiten + +**Code:** +```python +@router.post("/save") +async def save_note(req: SaveRequest, background_tasks: BackgroundTasks): + # Sofortige Persistenz + write_to_disk(req.markdown_content) + + # Async Processing + background_tasks.add_task(run_ingestion_task, ...) + + return SaveResponse(status="queued", ...) +``` + +**Vorteile:** +- Keine Timeouts bei großen Dateien +- Bessere User Experience +- System bleibt responsiv + +### 3.2 Traffic Control (Semaphore Pattern) + +**Problem:** Parallele LLM-Calls können System überlasten. + +**Lösung:** Semaphore begrenzt parallele Hintergrund-Tasks. + +**Code:** +```python +# app/services/llm_service.py +background_semaphore = asyncio.Semaphore( + settings.BACKGROUND_LIMIT # Default: 2 +) + +async def generate(...): + if priority == "background": + async with background_semaphore: + return await _call_llm(...) + else: # realtime + return await _call_llm(...) # Keine Limitierung +``` + +**Vorteile:** +- Schutz vor API-Quoten-Überschreitung +- Stabiler Betrieb bei hoher Last +- Priorisierung von Echtzeit-Anfragen + +--- + +## 4. Resilienz-Patterns + +### 4.1 Provider-Kaskade (Fallback-Kette) + +**Problem:** Cloud-Provider können ausfallen oder Quoten überschreiten. + +**Lösung:** Dreistufige Kaskade mit intelligentem Fallback. + +**Stufen:** +1. **Cloud (OpenRouter/Gemini):** Schnell, aber abhängig von Provider +2. **Rate-Limit-Handling:** Automatische Retries bei HTTP 429 +3. **Lokaler Fallback (Ollama):** Langsam, aber immer verfügbar + +**Code:** +```python +# app/services/llm_service.py +async def generate(...): + try: + return await _call_cloud(...) + except RateLimitError: + await asyncio.sleep(LLM_RATE_LIMIT_WAIT) + return await _call_cloud(...) # Retry + except Exception: + return await _call_ollama(...) # Fallback +``` + +**Vorteile:** +- Hohe Verfügbarkeit +- Kostenoptimierung (Cloud für Speed, Lokal für Fallback) +- Resilienz gegen Provider-Ausfälle + +### 4.2 Deep Fallback (Kognitiver Fallback) + +**Problem:** Cloud liefert technisch erfolgreiche, aber inhaltlich leere Antworten (Silent Refusal). + +**Lösung:** Validierung der Antwort-Qualität, nicht nur HTTP-Status. + +**Code:** +```python +response = await _call_cloud(...) +if is_valid_json(response): + return response +else: + # Deep Fallback: Cloud hat blockiert, lokaler Fallback + return await _call_ollama(...) +``` + +**Vorteile:** +- Erkennung von Policy-Violations +- Datenintegrität trotz Cloud-Filter +- Lokale Souveränität + +--- + +## 5. Datenfluss-Patterns + +### 5.1 Two-Pass Workflow (WP-15b) + +**Problem:** Smart Edge Validation benötigt globalen Kontext (alle Notizen). + +**Lösung:** Zwei-Phasen-Import mit Pre-Scan. + +**Pass 1: Pre-Scan** +- Schnelles Scannen aller Dateien +- Aufbau von `LocalBatchCache` (IDs, Titel, Summaries) +- Keine LLM-Calls + +**Pass 2: Semantic Processing** +- Nur für geänderte Dateien +- Binäre Validierung gegen Cache +- Effiziente Nutzung von LLM-Quoten + +**Vorteile:** +- Reduktion von LLM-Calls (nur Validierung, keine Extraktion) +- Konsistente Validierung (globaler Kontext) +- Schnellerer Import + +### 5.2 Idempotenz-Pattern + +**Prinzip:** Mehrfache Imports derselben Datei führen zum gleichen Ergebnis. + +**Mechanismen:** +- **Deterministische IDs:** UUIDv5 basierend auf Datei-Inhalt +- **Hash-basierte Change Detection:** Multi-Hash für `body` und `full` +- **Deduplizierung:** Kanten werden anhand Identität erkannt + +**Code:** +```python +# Deterministische ID +note_id = uuid.uuid5(NAMESPACE_URL, f"{file_path}#{content_hash}") + +# Change Detection +if current_hash == stored_hash: + skip_processing() # Idempotent +``` + +**Vorteile:** +- Sicherheit bei Re-Imports +- Keine Duplikate +- Konsistente Datenbank + +--- + +## 6. Frontend-Patterns + +### 6.1 Active Inspector Pattern + +**Problem:** Graph-Re-Renders bei Knoten-Selektion führen zu Flackern. + +**Lösung:** CSS-Klassen statt State-Änderungen für Selektion. + +**Code:** +```python +# ui_graph_cytoscape.py +stylesheet = [ + { + "selector": ".inspected", + "style": {"border-width": 6, "border-color": "#FFC300"} + } +] +# Selektion ändert nur CSS-Klasse, nicht React-Key +``` + +**Vorteile:** +- Stabiles UI (kein Re-Render) +- Bessere Performance +- Smooth User Experience + +### 6.2 Resurrection Pattern + +**Problem:** Streamlit vergisst Eingaben bei Re-Runs. + +**Lösung:** Aggressive Synchronisation in `session_state`. + +**Code:** +```python +# ui_editor.py +if widget_key not in st.session_state: + st.session_state[widget_key] = restore_from_data_key() +``` + +**Vorteile:** +- Texteingaben überleben Tab-Wechsel +- Keine Datenverluste +- Bessere UX + +--- + +## 7. Erweiterbarkeit: "Teach-the-AI" Paradigma + +Mindnet lernt durch **Konfiguration**, nicht durch Training. + +### 7.1 Drei-Ebenen-Erweiterung + +**1. Daten-Ebene (`types.yaml`):** +```yaml +risk: + retriever_weight: 0.90 + edge_defaults: ["blocks"] +``` + +**2. Strategie-Ebene (`decision_engine.yaml`):** +```yaml +DECISION: + inject_types: ["value", "risk"] +``` + +**3. Kognitive Ebene (`prompts.yaml`):** +```yaml +risk_definition: + ollama: "Ein Risiko ist eine potenzielle Gefahr..." +``` + +**Vorteile:** +- Keine Code-Änderungen nötig +- Schnelle Iteration +- A/B-Testing möglich + +--- + +## 8. Design-Entscheidungen & Trade-offs + +### 8.1 Qdrant als Vektor-DB + +**Entscheidung:** Qdrant statt Pinecone/Weaviate + +**Gründe:** +- Self-hosted (Privacy First) +- Open Source +- Gute Performance bei lokaler Installation + +**Trade-off:** Mehr Wartungsaufwand als Managed Service + +### 8.2 Hybrid Retrieval (Semantik + Graph) + +**Entscheidung:** Kombination von Vektor-Suche und Graph-Expansion + +**Gründe:** +- Semantik findet ähnliche Inhalte +- Graph findet strukturelle Verbindungen +- Kombination liefert bessere Relevanz + +**Trade-off:** Höhere Komplexität, mehr Berechnungsaufwand + +### 8.3 Background Tasks statt Queue-System + +**Entscheidung:** FastAPI Background Tasks statt Redis/RabbitMQ + +**Gründe:** +- Einfacher Setup (keine zusätzliche Infrastruktur) +- Ausreichend für Single-User-Szenario +- Weniger Moving Parts + +**Trade-off:** Keine Persistenz bei Server-Neustart (Tasks gehen verloren) + +--- + +## 9. Konsistenz-Garantien + +### 9.1 Deterministische IDs + +**Prinzip:** UUIDv5 basierend auf Datei-Inhalt + +**Vorteile:** +- Reproduzierbare IDs +- Keine Duplikate bei Re-Import +- Graph ist aus Markdown rekonstruierbar + +### 9.2 Provenance-Hierarchie + +**Prinzip:** Kanten haben Qualitätsstufen (explicit > smart > rule) + +**Vorteile:** +- Menschliche Intention hat Vorrang +- System-Heuristiken können überschrieben werden +- Transparente Gewichtung + +--- + +## 10. Weitere Informationen + +- **Vision & Strategie:** Siehe [Vision & Strategie](../00_General/00_vision_and_strategy.md) +- **Graph-Logik:** Siehe [Graph-Logik](02_concept_graph_logic.md) +- **KI-Persönlichkeit:** Siehe [KI-Persönlichkeit](02_concept_ai_personality.md) +- **Developer Guide:** Siehe [Developer Guide](../05_Development/05_developer_guide.md) + +--- + +**Letzte Aktualisierung:** 2025-01-XX +**Version:** 2.9.1 + diff --git a/docs/03_Technical_References/03_tech_api_reference.md b/docs/03_Technical_References/03_tech_api_reference.md new file mode 100644 index 0000000..198f542 --- /dev/null +++ b/docs/03_Technical_References/03_tech_api_reference.md @@ -0,0 +1,435 @@ +--- +doc_type: technical_reference +audience: developer, integrator +scope: api, endpoints, integration +status: active +version: 2.9.1 +context: "Vollständige API-Referenz für alle Mindnet-Endpunkte. Basis für Integration und Entwicklung." +--- + +# API Reference + +Diese Dokumentation beschreibt alle verfügbaren API-Endpunkte von Mindnet. Die API basiert auf FastAPI und nutzt automatische OpenAPI-Dokumentation (verfügbar unter `/docs`). + +## Basis-URL + +``` +http://localhost:8001 # Production +http://localhost:8002 # Development +``` + +## Health Check + +### `GET /healthz` + +Prüft den Status der API und der Verbindung zu Qdrant. + +**Response:** +```json +{ + "status": "ok", + "qdrant": "http://localhost:6333", + "prefix": "mindnet" +} +``` + +--- + +## Query Endpoints + +### `POST /query` + +Führt eine hybride oder semantische Suche im Wissensgraph durch. + +**Request Body:** +```json +{ + "query": "Was ist Mindnet?", + "mode": "hybrid", // "hybrid" oder "semantic" + "top_k": 10, + "expand_depth": 1, + "explain": true +} +``` + +**Response:** +```json +{ + "query_id": "uuid-v4", + "hits": [ + { + "chunk_id": "uuid", + "note_id": "uuid", + "text": "Auszug...", + "score": 0.85, + "explanation": { + "reasons": [...] + } + } + ], + "stats": { + "total_hits": 10, + "query_time_ms": 45 + } +} +``` + +**Hinweis:** Das Feedback-Logging erfolgt asynchron im Hintergrund (Background Tasks). + +--- + +## Chat Endpoints + +### `POST /chat/` + +Hauptendpunkt für RAG-Chat und Interview-Modus. Unterstützt Streaming. + +**Request Body:** +```json +{ + "message": "Was ist Mindnet?", + "history": [], // Optional: Chat-Verlauf + "stream": true // Optional: SSE-Streaming +} +``` + +**Response (Non-Streaming):** +```json +{ + "intent": "FACT", + "response": "Mindnet ist ein persönliches KI-Gedächtnis...", + "sources": [...], + "query_id": "uuid" +} +``` + +**Response (Streaming):** +Server-Sent Events (SSE) mit Chunks der Antwort. + +**Intent-Typen:** +- `FACT`: Wissensabfrage +- `DECISION`: Entscheidungsfrage +- `EMPATHY`: Emotionale Anfrage +- `INTERVIEW`: Wissen erfassen + +--- + +## Graph Endpoints + +### `GET /graph/{note_id}` + +Lädt den Subgraphen um eine Note herum. + +**Query Parameters:** +- `depth` (int, default: 1): Tiefe der Graph-Expansion +- `edge_types` (List[str], optional): Filter für Kanten-Typen + +**Response:** +```json +{ + "center_note_id": "uuid", + "nodes": [ + { + "id": "uuid", + "type": "project", + "title": "Projekt Alpha", + "tags": ["ki"], + "in_degree": 5, + "out_degree": 3 + } + ], + "edges": [ + { + "id": "uuid->uuid:depends_on", + "kind": "depends_on", + "source": "uuid", + "target": "uuid", + "weight": 1.4, + "direction": "out" + } + ], + "stats": { + "node_count": 10, + "edge_count": 15 + } +} +``` + +--- + +## Ingest Endpoints + +### `POST /ingest/analyze` + +Analysiert einen Text-Draft und liefert Link-Vorschläge (Intelligence-Feature). + +**Request Body:** +```json +{ + "text": "Markdown-Text...", + "type": "concept" // Optional: Notiz-Typ +} +``` + +**Response:** +```json +{ + "suggestions": [ + { + "text": "Mindnet", + "type": "exact_match", + "note_id": "uuid", + "confidence": 0.95 + }, + { + "text": "KI-Gedächtnis", + "type": "semantic", + "note_id": "uuid", + "confidence": 0.82 + } + ] +} +``` + +### `POST /ingest/save` + +Speichert eine Notiz und startet die Ingestion im Hintergrund (WP-14: Background Tasks). + +**Request Body:** +```json +{ + "markdown_content": "---\nid: ...\n---\n# Titel\n...", + "filename": "meine-notiz.md", // Optional + "folder": "00_Inbox" // Optional, default: "00_Inbox" +} +``` + +**Response:** +```json +{ + "status": "queued", + "file_path": "00_Inbox/meine-notiz.md", + "note_id": "pending", + "message": "Speicherung & Hybrid-KI-Analyse (WP-20) im Hintergrund gestartet.", + "stats": { + "chunks": -1, // -1 = Async Processing + "edges": -1 + } +} +``` + +**Wichtig:** +- Die Datei wird sofort auf der Festplatte gespeichert +- Die Ingestion (Chunking, Embedding, Smart Edges) läuft asynchron im Hintergrund +- Dies verhindert Timeouts bei großen Dateien oder langsamen LLM-Calls + +--- + +## Feedback Endpoints + +### `POST /feedback` + +Nimmt explizites User-Feedback entgegen (WP-04c). + +**Request Body:** +```json +{ + "query_id": "uuid", + "rating": 5, // 1-5 Sterne + "feedback_type": "global", // "global" oder "granular" + "chunk_id": "uuid" // Optional für granular feedback +} +``` + +**Response:** +```json +{ + "status": "recorded", + "query_id": "uuid" +} +``` + +--- + +## Tools Endpoints + +### `GET /tools/ollama` + +Liefert JSON-Schemas für die Integration als Tools in externe Agenten (Ollama, OpenAI, etc.). + +**Response:** +```json +{ + "tools": [ + { + "type": "function", + "function": { + "name": "mindnet_query", + "description": "Hybrid-Retrieval über mindnet (Semantik + Edges).", + "parameters": { + "type": "object", + "properties": { + "query": { + "type": "string", + "description": "Freitext-Query" + }, + "top_k": { + "type": "integer", + "default": 10, + "minimum": 1, + "maximum": 50 + } + } + } + } + }, + { + "type": "function", + "function": { + "name": "mindnet_subgraph", + "description": "Gibt die Nachbarschaft (Edges) einer Note/Seed-ID zurück.", + "parameters": { + "type": "object", + "properties": { + "note_id": { + "type": "string" + }, + "depth": { + "type": "integer", + "default": 1, + "minimum": 0, + "maximum": 3 + } + }, + "required": ["note_id"] + } + } + } + ] +} +``` + +**Verwendung:** Diese Schemas können direkt in Ollama-Function-Calling oder OpenAI-Tools integriert werden. + +--- + +## Admin Endpoints + +### `GET /admin/stats` + +Liefert Statistiken über die Qdrant-Collections und die aktuelle Konfiguration. + +**Response:** +```json +{ + "collections": { + "notes": { + "name": "mindnet_notes", + "count": 150 + }, + "chunks": { + "name": "mindnet_chunks", + "count": 1250 + }, + "edges": { + "name": "mindnet_edges", + "count": 3200 + } + }, + "config": { + "qdrant": "http://localhost:6333", + "prefix": "mindnet", + "vector_size": 768, + "distance": "Cosine", + "retriever": { + "w_sem": 0.70, + "w_edge": 0.25, + "w_cent": 0.05, + "top_k": 10, + "expand_depth": 1 + } + } +} +``` + +**Hinweis:** Dieser Endpunkt ist optional und kann deaktiviert sein, wenn der `admin`-Router nicht geladen wird. + +--- + +## Fehlerbehandlung + +Alle Endpunkte verwenden standardisierte HTTP-Status-Codes: + +- `200 OK`: Erfolgreiche Anfrage +- `201 Created`: Ressource erfolgreich erstellt +- `400 Bad Request`: Ungültige Anfrage (z.B. fehlende Parameter) +- `500 Internal Server Error`: Server-Fehler + +**Fehler-Response-Format:** +```json +{ + "detail": "Fehlerbeschreibung" +} +``` + +--- + +## Rate Limiting & Timeouts + +- **Chat-Endpunkte:** Keine Retries (max_retries=0) für schnelle Fallback-Kaskade +- **Ingest-Endpunkte:** Background Tasks verhindern Timeouts +- **Query-Endpunkte:** Standard-Timeout konfigurierbar via `MINDNET_API_TIMEOUT` + +--- + +## OpenAPI Dokumentation + +Die vollständige interaktive API-Dokumentation ist verfügbar unter: +- Swagger UI: `http://localhost:8001/docs` +- ReDoc: `http://localhost:8001/redoc` +- OpenAPI JSON: `http://localhost:8001/openapi.json` + +--- + +## Integration Beispiele + +### Python (requests) + +```python +import requests + +# Query +response = requests.post( + "http://localhost:8001/query", + json={"query": "Was ist Mindnet?", "top_k": 5} +) +print(response.json()) + +# Chat +response = requests.post( + "http://localhost:8001/chat/", + json={"message": "Erkläre mir Mindnet"} +) +print(response.json()) +``` + +### cURL + +```bash +# Health Check +curl http://localhost:8001/healthz + +# Query +curl -X POST http://localhost:8001/query \ + -H "Content-Type: application/json" \ + -d '{"query": "Was ist Mindnet?", "top_k": 5}' +``` + +--- + +## Weitere Informationen + +- **Chat-Backend Details:** Siehe [Chat Backend Dokumentation](03_tech_chat_backend.md) +- **Ingestion-Pipeline:** Siehe [Ingestion Pipeline](03_tech_ingestion_pipeline.md) +- **Retrieval & Scoring:** Siehe [Retrieval & Scoring](03_tech_retrieval_scoring.md) + diff --git a/docs/03_Technical_References/03_tech_chat_backend.md b/docs/03_Technical_References/03_tech_chat_backend.md index 9752929..bb20742 100644 --- a/docs/03_Technical_References/03_tech_chat_backend.md +++ b/docs/03_Technical_References/03_tech_chat_backend.md @@ -3,7 +3,7 @@ doc_type: technical_reference audience: developer, architect scope: backend, chat, llm_service, traffic_control, resilience status: active -version: 2.8.1 +version: 2.9.1 context: "Technische Implementierung des FastAPI-Routers, des hybriden LLMService (v3.3.6) und der WP-20 Resilienz-Logik." --- diff --git a/docs/03_Technical_References/03_tech_configuration.md b/docs/03_Technical_References/03_tech_configuration.md index 77d4576..8553f00 100644 --- a/docs/03_Technical_References/03_tech_configuration.md +++ b/docs/03_Technical_References/03_tech_configuration.md @@ -20,13 +20,15 @@ Diese Variablen steuern die Infrastruktur, Pfade und globale Timeouts. Seit der | `QDRANT_URL` | `http://localhost:6333` | URL zur Vektor-DB API. | | `QDRANT_API_KEY` | *(leer)* | Optionaler Key für Absicherung. | | `COLLECTION_PREFIX` | `mindnet` | Namensraum für Collections (erzeugt `{prefix}_notes` etc). | +| `MINDNET_PREFIX` | *(leer)* | **Alternative zu COLLECTION_PREFIX.** Falls gesetzt, wird dieser Wert verwendet. | | `VECTOR_DIM` | `768` | **Muss 768 sein** (für Nomic Embeddings). | +| `MINDNET_DISTANCE` | `Cosine` | Metrik für Vektor-Ähnlichkeit (`Cosine`, `Euclidean`, `Dot`). | | `MINDNET_VECTOR_NAME` | `default` | **Neu (WP-14):** Basis-Vektorname für Named Vectors Support. | | `NOTES_VECTOR_NAME` | *(leer)* | **Neu (WP-14):** Spezifischer Vektorname für die Notes-Collection (Override). | | `CHUNKS_VECTOR_NAME` | *(leer)* | **Neu (WP-14):** Spezifischer Vektorname für die Chunks-Collection (Override). | | `EDGES_VECTOR_NAME` | *(leer)* | **Neu (WP-14):** Spezifischer Vektorname für die Edges-Collection (Override). | | `MINDNET_VOCAB_PATH` | *(Pfad)* | **Neu (WP-22):** Absoluter Pfad zur `01_edge_vocabulary.md`. Definiert den Ort des Dictionarys. | -| `MINDNET_VAULT_ROOT` | `./vault` | Basis-Pfad für Datei-Operationen. | +| `MINDNET_VAULT_ROOT` | `./vault_master` | **Achtung:** Standard ist `./vault_master`, nicht `./vault`! Basis-Pfad für Datei-Operationen. | | `MINDNET_TYPES_FILE` | `config/types.yaml` | Pfad zur Typ-Registry. | | `MINDNET_RETRIEVER_CONFIG`| `config/retriever.yaml`| Pfad zur Scoring-Konfiguration. | | `MINDNET_DECISION_CONFIG` | `config/decision_engine.yaml` | Pfad zur Router & Intent Config. | diff --git a/docs/03_Technical_References/03_tech_ingestion_pipeline.md b/docs/03_Technical_References/03_tech_ingestion_pipeline.md index 146baa3..ce199dd 100644 --- a/docs/03_Technical_References/03_tech_ingestion_pipeline.md +++ b/docs/03_Technical_References/03_tech_ingestion_pipeline.md @@ -66,7 +66,24 @@ Der Prozess ist **asynchron**, **idempotent** und wird nun in zwei logische Durc ## 2. Betrieb & CLI Befehle -### 2.1 Standard-Betrieb (Inkrementell) +### 2.1 API-Endpunkt: `/ingest/save` (Background Tasks) + +Seit WP-14 nutzt der `/ingest/save` Endpunkt **Background Tasks** für non-blocking Ingestion: + +**Workflow:** +1. **Request:** Frontend sendet Markdown an `/ingest/save` +2. **Sofortige Antwort:** API antwortet mit `status: "queued"` und `note_id: "pending"` +3. **Datei-Persistenz:** Markdown wird sofort auf Festplatte geschrieben +4. **Background Task:** Ingestion läuft asynchron im Hintergrund + - Chunking + - Embedding-Generierung + - Smart Edge Allocation (WP-15) + - Hybrid-Cloud-Analyse (WP-20) +5. **Vorteil:** Keine Timeouts bei großen Dateien oder langsamen LLM-Calls + +**Hinweis:** Die tatsächliche `note_id` steht erst nach dem Parsing fest. Das Frontend sollte den `file_path` für Tracking nutzen. + +### 2.2 CLI-Betrieb (Inkrementell) Erkennt Änderungen via Multi-Hash. ```bash diff --git a/docs/04_Operations/04_admin_operations.md b/docs/04_Operations/04_admin_operations.md index 962b786..3797ebc 100644 --- a/docs/04_Operations/04_admin_operations.md +++ b/docs/04_Operations/04_admin_operations.md @@ -131,30 +131,131 @@ Administratoren sollten regelmäßig das Log für unbekannte Kanten-Typen prüfe ### 3.3 Troubleshooting Guide +Dieser Abschnitt hilft bei häufigen Problemen und deren Lösung. + +#### Allgemeine Diagnose-Schritte + +Bevor du spezifische Fehler behebst, führe diese Checks durch: + +1. **Service-Status prüfen:** + ```bash + systemctl status mindnet-prod + systemctl status mindnet-ui-prod + docker ps | grep qdrant + ``` + +2. **Logs analysieren:** + ```bash + journalctl -u mindnet-prod -n 50 --no-pager + journalctl -u mindnet-ui-prod -n 50 --no-pager + docker logs qdrant --tail 50 + ``` + +3. **API-Verfügbarkeit testen:** + ```bash + curl http://localhost:8001/health + curl http://localhost:8001/query -X POST -H "Content-Type: application/json" -d '{"query": "test", "top_k": 1}' + ``` + +#### Häufige Fehler & Lösungen + **Fehler: "Registry Initialization Failure" (Neu in v2.7)** * **Symptom:** API startet, aber Kanten werden nicht gewichtet oder Fehlermeldung im Log. -* **Lösung:** Prüfen Sie `MINDNET_VOCAB_PATH` in der `.env`. Der Pfad muss absolut sein und auf eine existierende Markdown-Tabelle zeigen. +* **Diagnose:** Prüfe die Logs auf `EdgeRegistry`-Fehler. +* **Lösung:** + 1. Prüfe `MINDNET_VOCAB_PATH` in der `.env`. Der Pfad muss absolut sein. + 2. Stelle sicher, dass die Datei `01_edge_vocabulary.md` existiert und eine gültige Markdown-Tabelle enthält. + 3. Prüfe Dateiberechtigungen: `ls -l $MINDNET_VOCAB_PATH` **Fehler: "ModuleNotFoundError: No module named 'st_cytoscape'"** -* Ursache: Alte Dependencies oder falsches Paket installiert. -* Lösung: Environment aktualisieren. +* **Ursache:** Alte Dependencies oder falsches Paket installiert. +* **Lösung:** Environment aktualisieren. ```bash source .venv/bin/activate pip uninstall streamlit-cytoscapejs pip install st-cytoscape + pip install -r requirements.txt # Vollständige Synchronisation ``` **Fehler: "Vector dimension error: expected 768, got 384"** -* Ursache: Alte DB (v2.2), neues Modell (v2.4). -* Lösung: **Full Reset** (siehe Kap. 4.2). +* **Ursache:** Alte DB (v2.2), neues Modell (v2.4) oder falsches Embedding-Modell. +* **Diagnose:** Prüfe die Collection-Konfiguration in Qdrant. +* **Lösung:** **Full Reset** (siehe Kap. 4.2) oder Collection neu erstellen: + ```bash + python3 -m scripts.reset_qdrant --mode wipe --prefix mindnet --yes + python3 -m scripts.import_markdown --vault ./vault --prefix mindnet --apply --force + ``` **Fehler: Import sehr langsam** -* Ursache: Smart Edges sind aktiv und analysieren jeden Chunk. -* Lösung: `MINDNET_LLM_BACKGROUND_LIMIT` prüfen oder Feature in `types.yaml` deaktivieren. +* **Ursache:** Smart Edges sind aktiv und analysieren jeden Chunk mit LLM-Calls. +* **Diagnose:** Prüfe `MINDNET_LLM_BACKGROUND_LIMIT` und LLM-Provider-Status. +* **Lösung:** + 1. Erhöhe `MINDNET_LLM_BACKGROUND_LIMIT` in `.env` (Standard: 2) + 2. Oder deaktiviere Smart Edges temporär in `types.yaml` für bestimmte Typen + 3. Prüfe, ob Ollama/Cloud-Provider erreichbar ist **Fehler: UI "Read timed out"** -* Ursache: Backend braucht für Smart Edges länger als 60s. -* Lösung: `MINDNET_API_TIMEOUT=300.0` in `.env` setzen (oder im Systemd Service). +* **Ursache:** Backend braucht für Smart Edges länger als das Timeout-Limit. +* **Diagnose:** Prüfe Backend-Logs auf langsame LLM-Calls. +* **Lösung:** + 1. Erhöhe `MINDNET_API_TIMEOUT=300.0` in `.env` (oder im Systemd Service) + 2. Prüfe `MINDNET_LLM_TIMEOUT` für einzelne LLM-Requests + 3. Erwäge, Smart Edges für große Imports zu deaktivieren + +**Fehler: "Qdrant connection refused"** +* **Ursache:** Qdrant-Container läuft nicht oder falsche URL. +* **Lösung:** + ```bash + docker ps | grep qdrant # Prüfe Container-Status + docker start qdrant # Starte Container falls gestoppt + docker logs qdrant # Prüfe Container-Logs + # Prüfe QDRANT_URL in .env + ``` + +**Fehler: "Ollama model not found"** +* **Ursache:** Modell nicht geladen oder falscher Modellname. +* **Lösung:** + ```bash + ollama list # Zeige geladene Modelle + ollama pull phi3:mini # Lade fehlendes Modell + ollama pull nomic-embed-text + # Prüfe MINDNET_LLM_MODEL und MINDNET_EMBEDDING_MODEL in .env + ``` + +**Fehler: "Too many open files" (Qdrant)** +* **Ursache:** System-Limit für offene Dateien zu niedrig (besonders bei vielen Collections). +* **Lösung:** Erhöhe `ulimits` im Docker-Compose (siehe Kap. 1.2) oder systemweit: + ```bash + # Temporär + ulimit -n 65535 + # Permanently: /etc/security/limits.conf + ``` + +**Fehler: "Unknown edge type" in Logs** +* **Ursache:** Neue Kanten-Typen im Vault, die nicht in `edge_vocabulary.md` definiert sind. +* **Diagnose:** Prüfe `data/logs/unknown_edges.jsonl`. +* **Lösung:** + 1. Füge fehlende Typen als Aliase in `01_edge_vocabulary.md` hinzu + 2. Oder verwende kanonische Typen aus der Registry + +#### Performance-Optimierung + +**Problem: Langsame Chat-Antworten** +* Prüfe LLM-Provider (Cloud vs. lokal) +* Reduziere `top_k` in Query-Requests +* Prüfe Qdrant-Performance (Anzahl Collections, Index-Größe) + +**Problem: Hoher Speicherverbrauch** +* Reduziere `MINDNET_LLM_BACKGROUND_LIMIT` +* Prüfe Qdrant-Speicherverbrauch: `docker stats qdrant` +* Erwäge, alte Collections zu archivieren + +#### Weitere Hilfe + +Für detaillierte Informationen zu: +- **Server-Betrieb:** Siehe [Server Operations Manual](04_server_operation_manual.md) +- **Entwicklung:** Siehe [Developer Guide](../05_Development/05_developer_guide.md#10-troubleshooting--one-liners) +- **Konfiguration:** Siehe [Configuration Reference](../03_Technical_References/03_tech_configuration.md) --- diff --git a/docs/04_Operations/04_deployment_guide.md b/docs/04_Operations/04_deployment_guide.md new file mode 100644 index 0000000..db95ca6 --- /dev/null +++ b/docs/04_Operations/04_deployment_guide.md @@ -0,0 +1,474 @@ +--- +doc_type: operations_manual +audience: devops, deployment_engineer +scope: deployment, ci_cd, rollout, versioning +status: active +version: 2.9.1 +context: "Vollständiger Deployment-Guide für Mindnet: CI/CD, Rollout-Strategien, Versionierung und Rollback." +--- + +# Deployment Guide + +Dieses Dokument beschreibt die Deployment-Prozesse, CI/CD-Pipelines und Rollout-Strategien für Mindnet. + +## 1. Deployment-Architektur + +Mindnet läuft in einer **Multi-Environment-Architektur**: + +| Environment | Ports | Zweck | User | +| :--- | :--- | :--- | :--- | +| **Production** | 8001 (API), 8501 (UI) | Live-System | `llmadmin` | +| **Development** | 8002 (API), 8502 (UI) | Test & Entwicklung | `llmadmin` | + +**Wichtig:** Beide Environments teilen sich die gleiche Qdrant-Instanz, nutzen aber unterschiedliche Collection-Prefixes. + +--- + +## 2. Deployment-Methoden + +### 2.1 Automatisches Deployment (CI/CD) + +**Tool:** Gitea Actions (`.gitea/workflows/deploy.yml`) + +**Trigger:** Push auf `main` Branch + +**Prozess:** +1. **Checkout:** Code wird ausgecheckt +2. **Stop API:** Graceful Stop des API-Services +3. **Deploy:** Rsync der whitelisted Verzeichnisse +4. **Dependencies:** Python venv & requirements aktualisieren +5. **Restart:** API-Service neu starten + +**Deployierte Verzeichnisse:** +- `app/` - Backend-Code +- `scripts/` - Admin-Tools +- `config/` - Konfigurationsdateien +- `tests/` - Test-Suite +- `requirements.txt` - Dependencies + +**Ausgeschlossen:** +- `.env*` - Umgebungsvariablen (bleiben auf Server) +- `.venv` - Virtuelle Umgebung (wird neu erstellt) +- `vault/` - Content (bleibt auf Server) + +### 2.2 Manuelles Deployment + +**Für:** Hotfixes, manuelle Rollouts, Debugging + +**Prozess:** +```bash +# 1. Auf Server einloggen +ssh llmadmin@llm-node + +# 2. In Produktions-Verzeichnis wechseln +cd ~/mindnet + +# 3. Code aktualisieren +git fetch origin +git checkout main +git pull origin main + +# 4. Dependencies aktualisieren +source .venv/bin/activate +pip install -r requirements.txt + +# 5. Services neu starten +sudo systemctl restart mindnet-prod +sudo systemctl restart mindnet-ui-prod + +# 6. Status prüfen +sudo systemctl status mindnet-prod +sudo systemctl status mindnet-ui-prod +``` + +--- + +## 3. Systemd Services + +### 3.1 Backend Service (API) + +**Datei:** `/etc/systemd/system/mindnet-prod.service` + +```ini +[Unit] +Description=Mindnet API Prod (8001) +After=network.target + +[Service] +User=llmadmin +Group=llmadmin +WorkingDirectory=/home/llmadmin/mindnet +ExecStart=/home/llmadmin/mindnet/.venv/bin/uvicorn app.main:app --host 0.0.0.0 --port 8001 --env-file .env +Restart=always +RestartSec=5 +Environment="MINDNET_VOCAB_PATH=/home/llmadmin/mindnet/vault/_system/dictionary/edge_vocabulary.md" + +[Install] +WantedBy=multi-user.target +``` + +**Wichtig:** +- `--env-file .env` lädt Umgebungsvariablen +- `MINDNET_VOCAB_PATH` muss absolut sein (für Edge Registry) + +### 3.2 Frontend Service (UI) + +**Datei:** `/etc/systemd/system/mindnet-ui-prod.service` + +```ini +[Unit] +Description=Mindnet UI Prod (8501) +After=mindnet-prod.service + +[Service] +User=llmadmin +Group=llmadmin +WorkingDirectory=/home/llmadmin/mindnet +Environment="MINDNET_API_URL=http://localhost:8001" +Environment="MINDNET_API_TIMEOUT=300" +Environment="STREAMLIT_SERVER_PORT=8501" +Environment="STREAMLIT_SERVER_ADDRESS=0.0.0.0" +Environment="STREAMLIT_SERVER_HEADLESS=true" +ExecStart=/home/llmadmin/mindnet/.venv/bin/streamlit run app/frontend/ui.py +Restart=always +RestartSec=5 + +[Install] +WantedBy=multi-user.target +``` + +### 3.3 Service-Management + +**Befehle:** +```bash +# Status prüfen +sudo systemctl status mindnet-prod +sudo systemctl status mindnet-ui-prod + +# Starten +sudo systemctl start mindnet-prod +sudo systemctl start mindnet-ui-prod + +# Stoppen +sudo systemctl stop mindnet-prod +sudo systemctl stop mindnet-ui-prod + +# Neustart +sudo systemctl restart mindnet-prod +sudo systemctl restart mindnet-ui-prod + +# Logs anzeigen +sudo journalctl -u mindnet-prod -f +sudo journalctl -u mindnet-ui-prod -f +``` + +--- + +## 4. Rollout-Strategien + +### 4.1 Blue-Green Deployment (Empfohlen) + +**Konzept:** Zwei identische Environments, Switch zwischen ihnen. + +**Aktuell:** Prod/Dev als Blue-Green Setup + +**Vorgehen:** +1. Deploy auf Dev (Port 8002/8502) +2. Tests auf Dev durchführen +3. Wenn erfolgreich: Deploy auf Prod (Port 8001/8501) +4. Switch erfolgt durch Service-Restart + +**Vorteile:** +- Schneller Rollback (alte Version läuft noch) +- Keine Downtime +- Test vor Produktion + +### 4.2 Canary Deployment (Zukünftig) + +**Konzept:** Schrittweise Rollout an einen Teil der Nutzer. + +**Umsetzung:** +- Load Balancer mit Traffic-Splitting +- Monitoring der Fehlerrate +- Automatischer Rollback bei Fehlern + +**Status:** Noch nicht implementiert (Single-User-Szenario) + +--- + +## 5. Versionierung & Releases + +### 5.1 Version-Schema + +**Format:** `v2.9.1` + +- **Major (2):** Breaking Changes +- **Minor (9):** Neue Features, Backward Compatible +- **Patch (1):** Bugfixes, kleine Verbesserungen + +### 5.2 Release-Prozess + +**1. Feature-Entwicklung:** +```bash +git checkout -b feature/neue-funktion +# ... Entwicklung ... +git push origin feature/neue-funktion +``` + +**2. Testing:** +- Unit Tests +- Integration Tests +- Smoke Tests auf Dev + +**3. Merge:** +```bash +# Pull Request in Gitea +# Review & Merge nach main +``` + +**4. Deployment:** +- Automatisch via CI/CD (bei Push auf main) +- Oder manuell (siehe 2.2) + +**5. Tagging (Optional):** +```bash +git tag -a v2.9.2 -m "Release v2.9.2: Neue Funktion X" +git push origin v2.9.2 +``` + +--- + +## 6. Rollback-Strategien + +### 6.1 Code-Rollback + +**Methode 1: Git Revert** +```bash +cd ~/mindnet +git log --oneline -10 # Finde letzten guten Commit +git checkout +sudo systemctl restart mindnet-prod +``` + +**Methode 2: Git Reset (Vorsicht!)** +```bash +cd ~/mindnet +git reset --hard +sudo systemctl restart mindnet-prod +``` + +### 6.2 Datenbank-Rollback + +**Problem:** Code-Rollback hilft nicht bei Schema-Änderungen. + +**Lösung:** +- **Qdrant-Snapshots:** Regelmäßige Backups (siehe [Server Operations Manual](04_server_operation_manual.md)) +- **Collection-Versionierung:** Separate Collections pro Version (nicht empfohlen) + +**Vorgehen bei Schema-Änderung:** +1. Snapshot vor Deployment erstellen +2. Deployment durchführen +3. Bei Problemen: Snapshot wiederherstellen + +--- + +## 7. Pre-Deployment Checkliste + +Vor jedem Deployment sollten folgende Punkte geprüft werden: + +- [ ] **Code-Qualität:** + - [ ] Unit Tests bestehen + - [ ] Integration Tests bestehen + - [ ] Linting bestanden + +- [ ] **Dependencies:** + - [ ] `requirements.txt` aktualisiert + - [ ] Neue Dependencies dokumentiert + - [ ] Breaking Changes in Dependencies geprüft + +- [ ] **Konfiguration:** + - [ ] `.env` Variablen dokumentiert (falls neu) + - [ ] Config-Dateien (`types.yaml`, etc.) kompatibel + - [ ] Edge Registry Pfad korrekt + +- [ ] **Datenbank:** + - [ ] Schema-Änderungen dokumentiert + - [ ] Migration-Skripte vorhanden (falls nötig) + - [ ] Backup erstellt + +- [ ] **Dokumentation:** + - [ ] Changelog aktualisiert + - [ ] Dokumentation synchronisiert + - [ ] Breaking Changes dokumentiert + +--- + +## 8. Post-Deployment Validierung + +Nach jedem Deployment sollten folgende Checks durchgeführt werden: + +### 8.1 Service-Status + +```bash +# Services laufen +sudo systemctl status mindnet-prod +sudo systemctl status mindnet-ui-prod + +# Health Check +curl http://localhost:8001/healthz +``` + +### 8.2 Funktionalität + +```bash +# API-Test +curl -X POST http://localhost:8001/query \ + -H "Content-Type: application/json" \ + -d '{"query": "test", "top_k": 1}' + +# UI-Test (Manuell) +# Öffne http://localhost:8501 im Browser +``` + +### 8.3 Logs prüfen + +```bash +# Fehler in Logs +sudo journalctl -u mindnet-prod --since "5 minutes ago" | grep -i error + +# Warnings +sudo journalctl -u mindnet-prod --since "5 minutes ago" | grep -i warning +``` + +--- + +## 9. CI/CD Pipeline Details + +### 9.1 Gitea Actions Workflow + +**Datei:** `.gitea/workflows/deploy.yml` + +**Trigger:** +- Push auf `main` Branch +- Concurrency: Nur ein Deployment gleichzeitig + +**Schritte:** +1. **Checkout:** Code aus Repository +2. **Stop API:** Graceful Stop (continue-on-error) +3. **Deploy:** Rsync der Verzeichnisse +4. **Python Setup:** Venv & Requirements +5. **Start API:** Service neu starten + +**Wichtig:** +- `.env` wird **nicht** deployed (bleibt auf Server) +- Vault wird **nicht** deployed (bleibt auf Server) + +### 9.2 Deployment-Verzeichnisse + +**Whitelist:** +``` +app scripts schemas docker tests config requirements.txt README.md +``` + +**Excluded:** +- `.git/` +- `.env*` +- `.venv/` +- `vault/` +- `hf_cache/` + +--- + +## 10. Monitoring & Alerting + +### 10.1 Health Checks + +**API Health Endpoint:** +```bash +curl http://localhost:8001/healthz +``` + +**Response:** +```json +{ + "status": "ok", + "qdrant": "http://localhost:6333", + "prefix": "mindnet" +} +``` + +**Monitoring-Script:** +```bash +python3 -m scripts.health_check_mindnet --url http://localhost:8001 --strict +``` + +### 10.2 Log-Monitoring + +**Systemd Journal:** +```bash +# Live-Logs +sudo journalctl -u mindnet-prod -f + +# Letzte 100 Zeilen +sudo journalctl -u mindnet-prod -n 100 + +# Seit gestern +sudo journalctl -u mindnet-prod --since "yesterday" +``` + +### 10.3 Metriken (Zukünftig) + +**Geplante Metriken:** +- Request-Rate +- Response-Zeiten +- Fehler-Rate +- LLM-Call-Dauer +- Qdrant-Performance + +**Tools:** Prometheus + Grafana (noch nicht implementiert) + +--- + +## 11. Disaster Recovery + +Siehe [Server Operations Manual](04_server_operation_manual.md#5-disaster-recovery-wiederherstellung-two-stage-dr) für detaillierte Disaster-Recovery-Prozeduren. + +**Kurzfassung:** +1. **Stage 1:** Basis-Image Restore (Bare Metal) +2. **Stage 2:** Daten-Update via Borgmatic +3. **Dienste:** Gitea, Qdrant, Ollama spezifisch wiederherstellen + +--- + +## 12. Best Practices + +### 12.1 Deployment-Zeiten + +- **Produktion:** Während Wartungsfenstern (nachts, Wochenenden) +- **Development:** Jederzeit (ist Test-Umgebung) + +### 12.2 Kommunikation + +- **Breaking Changes:** Vorher ankündigen +- **Downtime:** Bei größeren Deployments kommunizieren +- **Rollback-Plan:** Immer bereit haben + +### 12.3 Testing + +- **Immer zuerst auf Dev testen** +- **Smoke Tests nach Deployment** +- **Monitoring für erste Stunden nach Deployment** + +--- + +## 13. Weitere Informationen + +- **Admin Operations:** Siehe [Admin Operations Guide](04_admin_operations.md) +- **Server Operations:** Siehe [Server Operations Manual](04_server_operation_manual.md) +- **Troubleshooting:** Siehe [Admin Operations - Troubleshooting](04_admin_operations.md#33-troubleshooting-guide) + +--- + +**Letzte Aktualisierung:** 2025-01-XX +**Version:** 2.9.1 + diff --git a/docs/05_Development/05_developer_guide.md b/docs/05_Development/05_developer_guide.md index 831f285..427d163 100644 --- a/docs/05_Development/05_developer_guide.md +++ b/docs/05_Development/05_developer_guide.md @@ -216,6 +216,22 @@ Das Frontend ist eine Streamlit-App, die sich wie eine Single-Page-Application ( Das Backend ist das Herzstück. Es stellt die Logik via REST-API bereit. +**Wichtig:** Seit WP-14 ist die Core-Logik in spezialisierte Pakete unterteilt: + +#### Core-Pakete (Modularisierung WP-14) + +| Paket | Zweck | Wichtige Module | +| :--- | :--- | :--- | +| **`app/core/chunking/`** | Text-Segmentierung | `chunking_strategies.py` (Sliding/Heading), `chunking_processor.py` (Orchestrierung) | +| **`app/core/database/`** | Qdrant-Infrastruktur | `qdrant.py` (Client), `qdrant_points.py` (Point-Mapping) | +| **`app/core/graph/`** | Graph-Logik | `graph_subgraph.py` (Expansion), `graph_weights.py` (Scoring) | +| **`app/core/ingestion/`** | Import-Pipeline | `ingestion_processor.py` (Two-Pass), `ingestion_validation.py` (Mistral-safe Parsing) | +| **`app/core/parser/`** | Markdown-Parsing | `parsing_markdown.py` (Frontmatter/Body), `parsing_scanner.py` (File-Scan) | +| **`app/core/retrieval/`** | Suche & Scoring | `retriever.py` (Orchestrator), `retriever_scoring.py` (Mathematik) | +| **`app/core/registry.py`** | SSOT & Utilities | Text-Bereinigung, Circular-Import-Fix | + +**Legacy-Bridges:** Die alten Dateien (`app/core/retriever.py`, `app/core/qdrant.py`) existieren noch als Proxy-Adapter für Abwärtskompatibilität, delegieren aber an die neuen Pakete. + | Layer | Datei | Status | Verantwortung | | :--- | :--- | :--- | :--- | | **Entry** | `app/main.py` | 🟢 **Core** | **Entrypoint.** Initialisiert FastAPI, CORS, und bindet alle Router ein. | diff --git a/docs/05_Development/05_testing_guide.md b/docs/05_Development/05_testing_guide.md new file mode 100644 index 0000000..3310877 --- /dev/null +++ b/docs/05_Development/05_testing_guide.md @@ -0,0 +1,392 @@ +--- +doc_type: developer_guide +audience: developer, tester +scope: testing, quality_assurance, test_strategies +status: active +version: 2.9.1 +context: "Umfassender Test-Guide für Mindnet: Test-Strategien, Test-Frameworks, Test-Daten und Best Practices." +--- + +# Testing Guide + +Dieses Dokument beschreibt die Test-Strategien, Test-Frameworks und Best Practices für die Qualitätssicherung von Mindnet. + +## 1. Test-Strategie & Ebenen + +Mindnet nutzt eine **dreistufige Test-Pyramide**: + +``` + /\ + /E2E\ ← Wenige, langsame, teure Tests + /------\ + /Integration\ ← Mittlere Anzahl, mittlere Geschwindigkeit + /------------\ + / Unit Tests \ ← Viele, schnelle, isolierte Tests + /----------------\ +``` + +### 1.1 Unit Tests (Pytest) + +**Zweck:** Isolierte Logik-Tests ohne externe Abhängigkeiten. + +**Framework:** `pytest` + +**Beispiele:** +- `tests/test_retriever_basic.py` - Scoring-Logik +- `tests/test_chunking.py` - Chunking-Strategien +- `tests/test_edges_all.py` - Edge-Logik +- `tests/test_type_registry.py` - Registry-Funktionen + +**Ausführung:** +```bash +# Einzelner Test +pytest tests/test_retriever_basic.py -v + +# Alle Unit Tests +pytest tests/ -k "test_" --ignore=tests/test_*_smoke.py + +# Mit Coverage +pytest tests/ --cov=app --cov-report=html +``` + +**Best Practices:** +- Tests sollten isoliert sein (keine Abhängigkeiten zu Qdrant/Ollama) +- Mock externe Services (LLM, Qdrant) +- Schnelle Ausführung (< 1 Sekunde pro Test) + +### 1.2 Integration Tests + +**Zweck:** Prüfen den Datenfluss von Markdown bis Qdrant. + +**Tools:** +- `scripts/payload_dryrun.py` - JSON-Schema-Konformität +- `scripts/edges_full_check.py` - Graph-Integrität +- `scripts/make_test_vault.py` - Test-Daten-Generierung + +**Ausführung:** +```bash +# Payload-Validierung +python3 -m scripts.payload_dryrun --vault ./test_vault --with-edges + +# Graph-Integrität +python3 -m scripts.edges_full_check + +# Test-Vault erstellen +python3 -m scripts.make_test_vault --out ./test_vault --force +``` + +**Was wird geprüft:** +- Frontmatter-Parsing +- Chunk-Generierung +- Edge-Erstellung +- Payload-Schema-Konformität +- Graph-Invarianten (keine Dangling Edges) + +### 1.3 E2E / Smoke Tests + +**Zweck:** Prüfen das laufende System gegen echte Infrastruktur (Qdrant, Ollama). + +**Framework:** Python `unittest` + Shell-Skripte + +**Beispiele:** +- `tests/test_wp06_decision.py` - Decision Engine +- `tests/test_feedback_smoke.py` - Feedback-Loop +- `tests/test_dialog_full_flow.py` - Vollständiger Dialog-Flow +- `tests/run_e2e_roundtrip.sh` - Kompletter Roundtrip (Import → Export) + +**Ausführung:** +```bash +# Decision Engine Test +python tests/test_wp06_decision.py -p 8002 -e DECISION -q "Soll ich X tun?" + +# Feedback Test +python tests/test_feedback_smoke.py --url http://localhost:8002/query + +# E2E Roundtrip +./tests/run_e2e_roundtrip.sh --vault ./test_vault --prefix mindnet_test +``` + +**Voraussetzungen:** +- Qdrant läuft auf `localhost:6333` +- Ollama läuft auf `localhost:11434` +- API läuft auf Port 8002 (Dev) + +--- + +## 2. Test-Daten & Vaults + +### 2.1 Test-Vault erstellen + +**Tool:** `scripts/make_test_vault.py` + +**Zweck:** Erstellt einen minimalen, nachvollziehbaren Test-Vault. + +**Inhalt:** +- Verschiedene Note-Typen (`concept`, `experience`, `project`) +- Verschiedene Edge-Szenarien (explicit, implicit, missing links) +- Externe Links für Edge-Tests + +**Verwendung:** +```bash +# Standard +python3 -m scripts.make_test_vault --out ./test_vault + +# Mit fehlenden Links (für Link-Auflösungs-Tests) +python3 -m scripts.make_test_vault --out ./test_vault --with-missing + +# Überschreiben bestehenden Vault +python3 -m scripts.make_test_vault --out ./test_vault --force +``` + +### 2.2 Test-Collection Prefix + +**Wichtig:** Nutze separate Prefixes für Tests, um Produktionsdaten nicht zu beeinflussen. + +```bash +export COLLECTION_PREFIX="mindnet_test" +python3 -m scripts.import_markdown --vault ./test_vault --prefix mindnet_test --apply +``` + +--- + +## 3. Test-Frameworks & Tools + +### 3.1 Pytest (Unit Tests) + +**Installation:** +```bash +pip install pytest pytest-asyncio pytest-cov +``` + +**Konfiguration:** `pytest.ini` oder `pyproject.toml` + +**Async Tests:** +```python +import pytest + +@pytest.mark.asyncio +async def test_async_function(): + result = await async_function() + assert result == expected +``` + +### 3.2 Unittest (E2E Tests) + +**Framework:** Python `unittest` + +**Beispiel:** +```python +import unittest +from app.routers.ingest import save_note, SaveRequest + +class TestIngest(unittest.IsolatedAsyncioTestCase): + async def test_save_note(self): + req = SaveRequest(markdown_content="...", filename="test.md") + response = await save_note(req) + self.assertEqual(response.status, "queued") +``` + +### 3.3 Shell-Skripte (E2E Roundtrip) + +**Tool:** `tests/run_e2e_roundtrip.sh` + +**Zweck:** Vollständiger Test-Zyklus (Import → Export → Vergleich) + +**Schritte:** +1. Qdrant truncate +2. Import (Create-Fall) +3. Import (Idempotenz-Test) +4. Hash-Reporter +5. Export +6. Vergleich Vault vs. Export +7. Sync-Deletes Test + +--- + +## 4. Test-Szenarien + +### 4.1 Chunking-Tests + +**Was wird getestet:** +- Sliding Window Strategie +- Heading-basierte Strategie +- Edge-Vererbung +- Chunk-Größen-Limits + +**Tests:** +- `tests/test_smart_chunking_integration.py` +- `scripts/preview_chunks.py` (Manuelle Inspektion) + +### 4.2 Retrieval-Tests + +**Was wird getestet:** +- Semantic Search +- Hybrid Search (Semantik + Graph) +- Scoring-Formel +- Explanation Layer + +**Tests:** +- `tests/test_retriever_basic.py` +- `tests/test_retriever_edges.py` +- `tests/test_retriever_weight.py` +- `tests/test_explanation_smoke.py` + +### 4.3 Edge-Tests + +**Was wird getestet:** +- Edge-Erstellung (explicit, smart, rule) +- Edge-Validierung (Registry) +- Edge-Vererbung +- Unresolved References + +**Tests:** +- `tests/test_edges_all.py` +- `tests/test_edges_smoke.py` +- `tests/test_edges_defaults_smoke.py` +- `scripts/edges_full_check.py` + +### 4.4 Chat & Intent-Tests + +**Was wird getestet:** +- Intent-Erkennung (FACT, DECISION, EMPATHY, INTERVIEW) +- Decision Engine +- Interview-Modus +- Feedback-Loop + +**Tests:** +- `tests/test_wp06_decision.py` +- `tests/test_interview_intent.py` +- `tests/test_chat_wp05.py` +- `tests/test_feedback_smoke.py` + +### 4.5 Ingestion-Tests + +**Was wird getestet:** +- Two-Pass Workflow +- Change Detection (Hash-basiert) +- Background Tasks +- Smart Edge Allocation + +**Tests:** +- `tests/test_dialog_full_flow.py` +- `tests/test_WP22_intelligence.py` +- `scripts/import_markdown.py` (mit `--dry-run`) + +--- + +## 5. Continuous Integration + +### 5.1 Pre-Commit Checks + +**Empfohlene Checks:** +```bash +# Linting +flake8 app/ scripts/ + +# Type Checking (optional) +mypy app/ + +# Unit Tests +pytest tests/ -k "test_" --ignore=tests/test_*_smoke.py +``` + +### 5.2 CI/CD Pipeline + +**Gitea Actions:** `.gitea/workflows/` + +**Typische Pipeline:** +1. Checkout +2. Python Setup +3. Dependencies installieren +4. Unit Tests +5. Integration Tests (optional) +6. Deployment (bei main branch) + +--- + +## 6. Test-Best Practices + +### 6.1 Isolation + +- **Unit Tests:** Keine externen Abhängigkeiten (Mock alles) +- **Integration Tests:** Echte Qdrant, aber isolierte Collections +- **E2E Tests:** Separate Test-Umgebung (Port 8002) + +### 6.2 Test-Daten + +- Nutze `make_test_vault.py` für konsistente Test-Daten +- Separate Collection-Prefixes für Tests +- Cleanup nach Tests (oder isolierte Collections) + +### 6.3 Performance + +- Unit Tests sollten < 1 Sekunde dauern +- Integration Tests können länger dauern (10-30 Sekunden) +- E2E Tests sind langsam (1-5 Minuten) + +### 6.4 Wartbarkeit + +- Klare Test-Namen (`test__`) +- Dokumentation in Test-Docstrings +- Keine Hardcoded-Pfade (nutze `os.path`) + +--- + +## 7. Debugging & Diagnose + +### 7.1 Test-Debugging + +**Pytest Debug-Modus:** +```bash +pytest tests/test_retriever_basic.py -v --pdb +``` + +**Einzelnen Test inspizieren:** +```bash +python3 -m scripts.payload_dryrun --vault ./test_vault --note-id "test-note" +``` + +### 7.2 Qdrant-State prüfen + +```bash +# Collection-Status +python3 -m scripts.debug_qdrant_state --prefix mindnet_test + +# Payload-Indexe prüfen +python3 -m scripts.diag_payload_indexes --prefix mindnet_test +``` + +### 7.3 Chunk-Inspektion + +```bash +# Chunks für eine Note anzeigen +python3 -m scripts.dump_note_chunks --note-id "test-note" --prefix mindnet_test + +# Chunk-Text-Verifikation +python3 -m scripts.verify_chunk_texts --prefix mindnet_test +``` + +--- + +## 8. Test-Checkliste für Pull Requests + +Vor jedem PR sollten folgende Tests durchlaufen: + +- [ ] Unit Tests: `pytest tests/ -k "test_" --ignore=tests/test_*_smoke.py` +- [ ] Payload-Validierung: `python3 -m scripts.payload_dryrun --vault ./test_vault` +- [ ] Graph-Integrität: `python3 -m scripts.edges_full_check` +- [ ] Smoke Test (wenn API läuft): `python tests/test_wp06_decision.py -p 8002` + +--- + +## 9. Weitere Informationen + +- **Developer Guide:** Siehe [Developer Guide](05_developer_guide.md) +- **Scripts-Übersicht:** Siehe [Developer Guide - Scripts](05_developer_guide.md#44-scripts--tooling-die-admin-toolbox) +- **Troubleshooting:** Siehe [Admin Operations - Troubleshooting](../04_Operations/04_admin_operations.md#33-troubleshooting-guide) + +--- + +**Letzte Aktualisierung:** 2025-01-XX +**Version:** 2.9.1 + diff --git a/docs/README.md b/docs/README.md new file mode 100644 index 0000000..b9d04f4 --- /dev/null +++ b/docs/README.md @@ -0,0 +1,154 @@ +--- +doc_type: documentation_index +audience: all +status: active +version: 2.9.1 +context: "Zentraler Einstiegspunkt für die Mindnet-Dokumentation" +--- + +# Mindnet Dokumentation + +Willkommen in der Dokumentation von Mindnet v2.9.1! Diese Dokumentation hilft dir dabei, das System zu verstehen, zu nutzen und weiterzuentwickeln. + +## 🚀 Schnellstart + +**Neu hier?** Beginne mit diesen Dokumenten: + +1. **[Vision & Strategie](00_General/00_vision_and_strategy.md)** - Verstehe die Ziele und Prinzipien von Mindnet +2. **[Glossar](00_General/00_glossary.md)** - Lerne die wichtigsten Begriffe kennen +3. **[Dokumentationskarte](00_General/00_documentation_map.md)** - Finde schnell die richtige Dokumentation + +**Je nach Rolle:** + +- **👤 Benutzer/Autor:** Starte mit [Chat Usage Guide](01_User_Manual/01_chat_usage_guide.md) und [Knowledge Design](01_User_Manual/01_knowledge_design.md) +- **👨‍💻 Entwickler:** Beginne mit [Developer Guide](05_Development/05_developer_guide.md) +- **🔧 Administrator:** Siehe [Admin Operations](04_Operations/04_admin_operations.md) + +## 📚 Dokumentationsstruktur + +Die Dokumentation ist in logische Bereiche unterteilt: + +### 00_General (Grundlagen) +Grundlegende Informationen für alle Zielgruppen: +- Vision & Strategie +- Glossar +- Dokumentationskarte (Navigation) + +### 01_User_Manual (Anwendung) +Anleitungen für Endbenutzer und Autoren: +- Chat-Bedienung +- Knowledge Design (Content-Regeln) +- Authoring Guidelines +- Obsidian-Integration + +### 02_Concepts (Fachliche Logik) +Konzeptionelle Erklärungen für Architekten: +- Graph-Logik +- KI-Persönlichkeit & Router + +### 03_Technical_Reference (Technik & Code) +Detaillierte technische Referenzen für Entwickler: +- Datenmodell +- Ingestion-Pipeline +- Retrieval & Scoring +- Chat-Backend +- Frontend-Architektur +- Konfiguration + +### 04_Operations (Betrieb) +Betriebsanleitungen für Administratoren: +- Admin Operations (Installation, Backup, Troubleshooting) +- Server Operations Manual (Systemd, Disaster Recovery) + +### 05_Development (Entwicklung) +Entwickler-Ressourcen: +- Developer Guide (Workflow, Architektur, Module) +- GenAI Best Practices (Prompt-Library) + +### 06_Roadmap (Planung) +Projektplanung und Roadmap: +- Active Roadmap (aktuelle Workpackages) +- Handover Prompts (Übergabe-Prompts für neue Entwickler) + +### 99_Archive (Archiv) +Historische Dokumentation: +- Legacy Workpackages (abgeschlossene WPs) + +## 🔍 Navigation nach Rolle + +### 👨‍💻 Entwickler +| Frage | Dokument | +|-------|----------| +| Wie richte ich meine Entwicklungsumgebung ein? | [Developer Guide](05_Development/05_developer_guide.md#6-lokales-setup-development) | +| Wie ist die Architektur aufgebaut? | [Architektur-Patterns](02_concepts/02_concept_architecture_patterns.md) | +| Wie erweitere ich das System? | [Developer Guide - Teach-the-AI](05_Development/05_developer_guide.md#8-erweiterungs-guide-teach-the-ai) | +| Wie teste ich meine Änderungen? | [Testing Guide](05_Development/05_testing_guide.md) | +| Welche API-Endpunkte gibt es? | [API Reference](03_Technical_References/03_tech_api_reference.md) | + +### 🔧 Administratoren +| Frage | Dokument | +|-------|----------| +| Wie installiere ich Mindnet? | [Admin Operations](04_Operations/04_admin_operations.md#1-installation--setup) | +| Wie konfiguriere ich die Services? | [Admin Operations - Deployment](04_Operations/04_admin_operations.md#2-deployment-systemd-services) | +| Wie führe ich Backups durch? | [Admin Operations - Backup](04_Operations/04_admin_operations.md#4-backup--restore) | +| Was tun bei Problemen? | [Admin Operations - Troubleshooting](04_Operations/04_admin_operations.md#33-troubleshooting-guide) | +| Wie betreibe ich den Server? | [Server Operations Manual](04_Operations/04_server_operation_manual.md) | + +### 👤 Anwender +| Frage | Dokument | +|-------|----------| +| Wie starte ich mit Mindnet? | [Schnellstart](00_General/00_quickstart.md) | +| Wie nutze ich den Chat? | [Chat Usage Guide](01_User_Manual/01_chat_usage_guide.md) | +| Wie strukturiere ich meine Notizen? | [Knowledge Design](01_User_Manual/01_knowledge_design.md) | +| Wie schreibe ich für den Digitalen Zwilling? | [Authoring Guidelines](01_User_Manual/01_authoring_guidelines.md) | +| Wie integriere ich Obsidian? | [Obsidian Integration](01_User_Manual/01_obsidian_integration_guide.md) | + +### 🧪 Tester +| Frage | Dokument | +|-------|----------| +| Welche Test-Strategien gibt es? | [Testing Guide - Strategien](05_Development/05_testing_guide.md#1-test-strategie--ebenen) | +| Wie führe ich Tests aus? | [Testing Guide - Frameworks](05_Development/05_testing_guide.md#3-test-frameworks--tools) | +| Wie erstelle ich Test-Daten? | [Testing Guide - Test-Daten](05_Development/05_testing_guide.md#2-test-daten--vaults) | +| Was ist die Test-Checkliste? | [Testing Guide - Checkliste](05_Development/05_testing_guide.md#8-test-checkliste-für-pull-requests) | + +### 🚀 Deployment +| Frage | Dokument | +|-------|----------| +| Wie deploye ich automatisch? | [Deployment Guide - CI/CD](04_Operations/04_deployment_guide.md#9-cicd-pipeline-details) | +| Welche Rollout-Strategien gibt es? | [Deployment Guide - Rollout](04_Operations/04_deployment_guide.md#4-rollout-strategien) | +| Wie führe ich einen Rollback durch? | [Deployment Guide - Rollback](04_Operations/04_deployment_guide.md#6-rollback-strategien) | +| Was muss vor dem Deployment geprüft werden? | [Deployment Guide - Checkliste](04_Operations/04_deployment_guide.md#7-pre-deployment-checkliste) | + +## 📖 Dokumentationsprinzipien + +Diese Dokumentation folgt klaren Prinzipien: + +1. **Single Source of Truth:** Informationen werden nicht dupliziert, sondern referenziert +2. **Konkrete Beispiele:** Technische Dokumente enthalten immer Code-Snippets +3. **Human Readable:** Benutzerhandbücher enthalten Narrative und Szenarien +4. **KI-Optimiert:** Jede Datei hat YAML-Frontmatter für bessere RAG-Integration + +## 🔄 Dokumentation aktualisieren + +Wenn du an einem Feature arbeitest, nutze die [Maintenance Matrix](00_General/00_documentation_map.md#3-maintenance-guide-welche-datei-muss-ich-ändern) in der Dokumentationskarte, um zu sehen, welche Dateien aktualisiert werden müssen. + +## ✅ Qualitätsprüfung + +Die Dokumentation wurde systematisch für alle Rollen geprüft: +- **Entwickler:** Setup, Architektur, Code, Testing, Debugging ✅ +- **Administratoren:** Installation, Betrieb, Wartung, Backup, DR ✅ +- **Anwender:** Nutzung, Content-Erstellung, Workflows ✅ +- **Tester:** Test-Strategien, Frameworks, Tools ✅ +- **Deployment:** CI/CD, Rollout, Versionierung, Rollback ✅ + +Siehe [Qualitäts-Checkliste](00_General/00_quality_checklist.md) für Details. + +## 💡 Feedback + +Falls du Verbesserungsvorschläge für die Dokumentation hast oder Fehler findest, melde diese bitte im Repository. + +--- + +**Letzte Aktualisierung:** 2025-01-XX +**Version:** 2.9.1 +