Compare commits

...
9 Commits
Author SHA1 Message Date
Lars 4d6fce2d93 TOC
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-08 18:01:35 +01:00
Lars b398168b1f docs/mindnet_functional_architecture.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-08 17:58:28 +01:00
Lars 6b397fea2e docs/mindnet_functional_architecture.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 4s
2025-12-08 17:57:51 +01:00
Lars d20386e0a7 Toc
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-08 17:55:24 +01:00
Lars fcb90db2d0 docs/mindnet_functional_architecture.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-08 17:47:28 +01:00
Lars 5d8e96372f docs/developer_guide.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-08 17:39:01 +01:00
Lars 0d1a98279e docs/developer_guide.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-08 17:33:46 +01:00
Lars 73641abf8a config/retriever.yaml aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 4s
2025-12-08 17:25:43 +01:00
Lars a4873b3d45 docs/mindnet_functional_architecture.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-08 16:52:22 +01:00
6 changed files with 278 additions and 39 deletions

No files matched your search

+2 -1
View File
@@ -13,7 +13,8 @@ scoring:
# Empfehlung: 0.5 → zentrale Knoten werden bevorzugt, aber moderat # Empfehlung: 0.5 → zentrale Knoten werden bevorzugt, aber moderat
centrality_weight: 0.5 centrality_weight: 0.5
# Optional, für später (aktuell noch nicht ausgewertet, aber als Blaupause): # Die nachfolgenden Werte überschreiben die Defaults aus app/core/retriever_config.
# Wenn neue Kantentypen, z.B. durch Referenzierung innerhalb einer md-Datei im vault anders gewichtet werden sollen, dann muss hier die Konfiguration erfolgen
edge_types: edge_types:
references: 0.20 references: 0.20
depends_on: 0.18 depends_on: 0.18
+28
View File
@@ -6,6 +6,34 @@
> 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 + DB + LLM).
---
<details>
<summary>📖 <b>Inhaltsverzeichnis (Klicken zum Öffnen)</b></summary>
- [Mindnet v2.2 – Admin Guide](#mindnet-v22--admin-guide)
- [1. Zielgruppe \& Scope](#1-zielgruppe--scope)
- [2. Initial Setup \& Installation](#2-initial-setup--installation)
- [2.1 Systemvoraussetzungen](#21-systemvoraussetzungen)
- [2.2 Installation (Code)](#22-installation-code)
- [2.3 Qdrant Setup (Docker)](#23-qdrant-setup-docker)
- [2.4 Ollama Setup (LLM Service)](#24-ollama-setup-llm-service)
- [2.5 Konfiguration (ENV)](#25-konfiguration-env)
- [2.6 Deployment via Systemd](#26-deployment-via-systemd)
- [3. Betrieb im Alltag](#3-betrieb-im-alltag)
- [3.1 Regelmäßige Importe](#31-regelmäßige-importe)
- [3.2 Health-Checks](#32-health-checks)
- [3.3 Logs \& Monitoring](#33-logs--monitoring)
- [4. Update-Prozess](#4-update-prozess)
- [5. Backup \& Restore](#5-backup--restore)
- [5.1 Vault-Backup (Priorität 1)](#51-vault-backup-priorität-1)
- [5.2 Qdrant-Snapshots (Priorität 2)](#52-qdrant-snapshots-priorität-2)
- [5.3 Log-Daten (Priorität 3)](#53-log-daten-priorität-3)
- [5.4 Notfall-Wiederherstellung (Rebuild)](#54-notfall-wiederherstellung-rebuild)
- [6. Governance \& Sicherheit](#6-governance--sicherheit)
- [6.1 Zugriffsschutz](#61-zugriffsschutz)
- [6.2 Typen-Governance](#62-typen-governance)
--- ---
## 1. Zielgruppe & Scope ## 1. Zielgruppe & Scope
+69 -15
View File
@@ -1,7 +1,7 @@
# Mindnet v2.2 – Developer Guide # Mindnet v2.2 – Developer Guide
**Datei:** `docs/mindnet_developer_guide_v2.2.md` **Datei:** `docs/mindnet_developer_guide_v2.2.md`
**Stand:** 2025-12-08 **Stand:** 2025-12-08
**Status:** **FINAL** (Inkl. RAG & LLM Setup) **Status:** **FINAL** (Inkl. RAG, Edge-Config & AI-Teaching)
**Quellen:** `mindnet_technical_architecture.md`, `Handbuch.md`, `DEV_WORKFLOW.md`. **Quellen:** `mindnet_technical_architecture.md`, `Handbuch.md`, `DEV_WORKFLOW.md`.
> **Zielgruppe:** Entwickler:innen. > **Zielgruppe:** Entwickler:innen.
@@ -36,7 +36,7 @@ Der Code ist modular in `app` (Logik), `scripts` (CLI) und `config` (Steuerung)
├── config/ # YAML-Konfigurationen (Single Source of Truth) ├── config/ # YAML-Konfigurationen (Single Source of Truth)
│ ├── types.yaml # Import-Regeln │ ├── types.yaml # Import-Regeln
│ ├── prompts.yaml # LLM Prompts & RAG Templates (WP05) │ ├── prompts.yaml # LLM Prompts & RAG Templates (WP05)
│ └── retriever.yaml # Scoring-Regeln │ └── retriever.yaml # Scoring-Regeln & Kantengewichte
├── data/ ├── data/
│ └── logs/ # Lokale Logs (search_history.jsonl, feedback.jsonl) │ └── logs/ # Lokale Logs (search_history.jsonl, feedback.jsonl)
├── scripts/ # CLI-Tools (Import, Diagnose, Reset) ├── scripts/ # CLI-Tools (Import, Diagnose, Reset)
@@ -54,6 +54,7 @@ Der Code ist modular in `app` (Logik), `scripts` (CLI) und `config` (Steuerung)
* **Vault:** Ein Ordner mit Markdown-Dateien (z.B. `./mindnet_v2_test_vault` für Tests). * **Vault:** Ein Ordner mit Markdown-Dateien (z.B. `./mindnet_v2_test_vault` für Tests).
### 2.2 Installation ### 2.2 Installation
# 1. Repository klonen & Verzeichnis wechseln # 1. Repository klonen & Verzeichnis wechseln
git clone <repo> mindnet git clone <repo> mindnet
cd mindnet cd mindnet
@@ -100,6 +101,7 @@ Auf dem Entwicklungsserver (Beelink) nutzen wir Systemd.
journalctl -u mindnet-dev -f journalctl -u mindnet-dev -f
Falls du lokal auf Windows entwickelst: Falls du lokal auf Windows entwickelst:
# 1. Qdrant starten # 1. Qdrant starten
docker run -p 6333:6333 qdrant/qdrant docker run -p 6333:6333 qdrant/qdrant
# 2. Ollama starten # 2. Ollama starten
@@ -134,6 +136,7 @@ Wir unterscheiden drei Test-Ebenen. Ein Pull Request sollte alle passieren.
### 4.1 Unit Tests (Pytest) ### 4.1 Unit Tests (Pytest)
Für isolierte Logik (Parsing, Scoring). Für isolierte Logik (Parsing, Scoring).
pytest tests/test_retriever_basic.py pytest tests/test_retriever_basic.py
pytest tests/test_chunking.py pytest tests/test_chunking.py
pytest tests/test_edges_all.py pytest tests/test_edges_all.py
@@ -141,9 +144,11 @@ Für isolierte Logik (Parsing, Scoring).
### 4.2 Integration / Pipeline Tests ### 4.2 Integration / Pipeline Tests
Prüfen den Datenfluss von Markdown bis Qdrant-JSON. Prüfen den Datenfluss von Markdown bis Qdrant-JSON.
* **Payload Dryrun:** Prüft JSON-Schema Konformität. * **Payload Dryrun:** Prüft JSON-Schema Konformität.
python3 -m scripts.payload_dryrun --vault ./mindnet_v2_test_vault python3 -m scripts.payload_dryrun --vault ./mindnet_v2_test_vault
* **Edge Checks:** Prüft Graph-Invarianten. * **Edge Checks:** Prüft Graph-Invarianten.
python3 -m scripts.edges_full_check python3 -m scripts.edges_full_check
### 4.3 Smoke Tests (E2E) ### 4.3 Smoke Tests (E2E)
@@ -161,32 +166,81 @@ Prüfen das laufende System (API) gegen eine echte Qdrant-Instanz und Ollama.
--- ---
## 5. Guidelines für Erweiterungen ## 5. Das "Teach-the-AI" Paradigma (Context Intelligence)
### 5.1 Neuen Note-Typ hinzufügen Mindnet lernt nicht durch Training (Fine-Tuning), sondern durch **Konfiguration**, **Vernetzung** und **Prompting**. Wenn du dem System ein neues Konzept beibringen willst, musst du in der Regel an drei Stellen eingreifen. Dies ist der **Core-Workflow** für Erweiterungen.
* Bearbeite `config/types.yaml`.
* Definiere `chunk_profile`, `retriever_weight` und `edge_defaults`.
* Führe einen **Re-Import** durch.
### 5.2 Persönlichkeit anpassen (Prompt Engineering) ### A. Workflow: Einen neuen Typ implementieren (z. B. `type: risk`)
* Bearbeite `config/prompts.yaml`.
* Änderungen sind sofort aktiv (kein Neustart nötig, da pro Request geladen, sofern nicht gecached).
* **Prompt-Regel:** Kleine Modelle (Phi-3) brauchen strikte Anweisungen (z.B. "Achte auf [DECISION]").
### 5.3 Neue API-Endpunkte **1. Daten-Ebene (`config/types.yaml`)**
* Erstelle einen neuen Router in `app/routers/`. Definiere die "Physik" des Typs (Import-Regeln und Basis-Wichtigkeit).
* Registriere den Router in `app/main.py`.
* Denke an **Traceability**: Generiere oder durchschleife `query_id`. risk:
chunk_profile: short # Risiken sind oft kurze Statements
retriever_weight: 0.90 # Sehr wichtig, fast so hoch wie Decisions
edge_defaults: ["blocks"] # Automatische Kante zu verlinkten Projekten
*Ergebnis:* Notizen werden importiert und landen bei Suchen weit oben.
**2. Labeling-Ebene (`app/routers/chat.py`)**
Der Router liest das Feld `type` automatisch aus und injiziert es als `TYP: [RISK]` in den Prompt.
* *Prüfung:* Keine Code-Änderung nötig, da der Router generisch ist.
**3. Kognitive Ebene (`config/prompts.yaml`)**
Erkläre dem LLM, was `[RISK]` bedeutet. Ergänze den `system_prompt`:
system_prompt: |
...
REGELN FÜR TYPEN:
- [RISK]: Warnung! Wenn ein [RISK] im Kontext ist, weise den User darauf hin.
### B. Workflow: Neue Beziehungen (Edges) nutzen (z. B. `beeinflusst_von`)
Beziehungen sind der Klebstoff für die "Why"-Erklärungen.
**1. Erfassung im Vault (Markdown)**
Du musst dem System keinen neuen Edge-Typ "beibringen" (Schema-less). Du nutzt ihn einfach.
Nutze die Inline-Syntax im Fließtext:
Die Entscheidung für Qdrant wurde [[rel:beeinflusst_von Budgetkürzung 2024]].
Diese Strategie ist eine [[rel:reaktion_auf Marktveränderung]].
*Ergebnis:* Der Importer erzeugt Kanten mit `kind="beeinflusst_von"`.
**2. Gewichtung (`config/retriever.yaml`)**
Standardmäßig werden alle expliziten Kanten gleich behandelt (hoher Bonus). Wenn du willst, dass `beeinflusst_von` *wichtiger* ist als `related_to`, konfigurierst du dies hier.
scoring:
edge_weight: 0.7
# Optional: Spezifische Boosts für Kanten-Typen (Advanced)
edge_type_weights:
beeinflusst_von: 1.5 # Sehr starker Einfluss auf das Ranking
reaktion_auf: 1.2
related_to: 0.5 # Schwächerer Einfluss
*Hinweis:* Wenn `edge_type_weights` nicht definiert ist, gilt der Standard-Algorithmus (Confidence ~0.95 für Inline-Relations).
**3. Verständnis beim LLM (`config/prompts.yaml`)**
Damit der Chatbot versteht, dass "beeinflusst_von" eine Kausalität ist (und nicht nur Ähnlichkeit), kannst du dies im Prompt erklären, falls die Explanation-Daten in den Kontext geladen werden (Roadmap WP-06).
### Fazit
Nur wenn **Daten** (Vault), **Physik** (Config) und **Semantik** (Prompt) zusammenspielen, entsteht ein intelligenter Zwilling.
* **Vault:** Liefert das Wissen.
* **Config:** Liefert die Priorität (Weights).
* **Prompt:** Liefert die Interpretation.
--- ---
## 6. Nützliche Einzeiler ## 6. Nützliche Einzeiler
**DB komplett zurücksetzen (Vorsicht!):** **DB komplett zurücksetzen (Vorsicht!):**
python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet_dev" --yes python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet_dev" --yes
**Einen einzelnen File inspizieren (Parser-Sicht):** **Einen einzelnen File inspizieren (Parser-Sicht):**
python3 tests/inspect_one_note.py --file ./vault/MeinFile.md python3 tests/inspect_one_note.py --file ./vault/MeinFile.md
**Live-Logs sehen (Beelink):** **Live-Logs sehen (Beelink):**
journalctl -u mindnet-dev -f journalctl -u mindnet-dev -f
+109 -23
View File
@@ -5,6 +5,43 @@
> 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** (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 neuen **RAG-Chat** (Persönlichkeit). Die technische Umsetzung wird im technischen Dokument detailliert.
---
<details>
<summary>📖 <b>Inhaltsverzeichnis (Klicken zum Öffnen)</b></summary>
- [Mindnet v2.2 – Fachliche Architektur](#mindnet-v22--fachliche-architektur)
- [0) Zielbild \& Grundprinzip](#0-zielbild--grundprinzip)
- [1) Notizen \& Chunks (fachliche Perspektive)](#1-notizen--chunks-fachliche-perspektive)
- [1.1 Notiz (Note)](#11-notiz-note)
- [1.2 Chunk](#12-chunk)
- [2) Edges – fachliche Typen \& Bedeutung](#2-edges--fachliche-typen--bedeutung)
- [2.1 Struktur-Kanten (Das Skelett)](#21-struktur-kanten-das-skelett)
- [2.2 Inhalts-Kanten (explizit)](#22-inhalts-kanten-explizit)
- [2.3 Typ-basierte Default-Kanten (Regelbasiert)](#23-typ-basierte-default-kanten-regelbasiert)
- [3) Edge-Payload – Felder \& Semantik](#3-edge-payload--felder--semantik)
- [4) Typ-Registry (`config/types.yaml`)](#4-typ-registry-configtypesyaml)
- [4.1 Zweck](#41-zweck)
- [4.2 Beispiel (auslieferungsnah)](#42-beispiel-auslieferungsnah)
- [5) Der Retriever (Funktionaler Layer)](#5-der-retriever-funktionaler-layer)
- [5.1 Scoring-Modell](#51-scoring-modell)
- [5.2 Erklärbarkeit (Explainability) – WP04b](#52-erklärbarkeit-explainability--wp04b)
- [6) Der RAG-Chat \& Persönlichkeit (WP05)](#6-der-rag-chat--persönlichkeit-wp05)
- [6.1 Stil \& Tonfall (System Prompt)](#61-stil--tonfall-system-prompt)
- [6.2 Strategische Persönlichkeit (Ausblick WP06)](#62-strategische-persönlichkeit-ausblick-wp06)
- [7) Erweiterbarkeit \& Teaching (Context Intelligence)](#7-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)
- [8) Feedback \& Lernen – WP04c](#8-feedback--lernen--wp04c)
- [8.1 Der Feedback-Loop](#81-der-feedback-loop)
- [9) Confidence \& Provenance – wozu?](#9-confidence--provenance--wozu)
- [10) Semantik ausgewählter `kind`-Werte](#10-semantik-ausgewählter-kind-werte)
- [11) Frontmatter-Eigenschaften – Rolle \& Empfehlung](#11-frontmatter-eigenschaften--rolle--empfehlung)
- [12) Lösch-/Update-Garantien (Idempotenz)](#12-lösch-update-garantien-idempotenz)
- [13) Beispiel – Von Markdown zu Kanten (v2.2)](#13-beispiel--von-markdown-zu-kanten-v22)
- [14) Referenzen (Projektdateien \& Leitlinien)](#14-referenzen-projektdateien--leitlinien)
- [15) Workpackage Status (v2.3.0)](#15-workpackage-status-v230)
</details>
--- ---
## 0) Zielbild & Grundprinzip ## 0) Zielbild & Grundprinzip
@@ -166,29 +203,78 @@ Die API gibt diese Analysen als menschenlesbare Sätze (`reasons`) und als Daten
## 6) Der RAG-Chat & Persönlichkeit (WP05) ## 6) Der RAG-Chat & Persönlichkeit (WP05)
Seit WP-05 kann Mindnet nicht nur suchen, sondern als **KI-Zwilling** antworten. Seit WP-05 kann Mindnet nicht nur suchen, sondern als **KI-Zwilling** antworten. Die Persönlichkeit entsteht dabei auf zwei Ebenen:
### 6.1 Context Intelligence (Der "Enriched Context") ### 6.1 Stil & Tonfall (System Prompt)
Kleine Sprachmodelle (SLMs wie Phi-3) scheitern oft an komplexen Zusammenhängen. Mindnet löst dies durch **explizite Metadaten-Injection** in den Prompt. In `config/prompts.yaml` wird die Persona definiert.
Dem LLM wird nicht nur der Text eines Chunks gezeigt, sondern auch sein Typ und Score:
* *"Hier ist eine Notiz vom Typ `[DECISION]`. Sie erklärt, warum wir etwas tun."*
* *"Hier ist eine Notiz vom Typ `[PROJECT]`. Sie erklärt, was wir tun."*
Dadurch kann das System Fragen wie *"Warum nutzen wir X?"* korrekt beantworten, indem es die Begründung aus der Decision-Notiz zieht, selbst wenn die Frage auf das Projekt abzielte.
### 6.2 Persönlichkeit (Late Binding)
Die "Persönlichkeit" von Mindnet (Stil, Werte, Tonfall) ist **nicht** im Python-Code verankert, sondern in `config/prompts.yaml`.
* **System Prompt:** Definiert die Rolle ("Ich bin dein digitales Gedächtnis..."). * **System Prompt:** Definiert die Rolle ("Ich bin dein digitales Gedächtnis...").
* **Werte:** Pragmatismus, Transparenz (kein Halluzinieren), Vernetztes Denken. * **Werte im Prompt:** Pragmatismus, Transparenz (kein Halluzinieren), Vernetztes Denken.
* **Flexibilität:** Die Persönlichkeit kann jederzeit angepasst werden (z.B. "Sei kritischer"), ohne das System neu zu starten. * **Context Intelligence:** Dem LLM werden Metadaten (Typ, Score) injiziert, damit es komplexe Zusammenhänge erkennt (z.B. dass eine `[DECISION]` wichtiger ist als ein `[CONCEPT]`).
### 6.2 Strategische Persönlichkeit (Ausblick WP06)
Ein echter KI-Zwilling spiegelt nicht nur den Stil, sondern die **Werte** des Users wider.
* **Logik:** Bei komplexen Fragen oder Entscheidungen ("Soll ich X tun?") lädt das System gezielt Notizen vom Typ `[VALUE]` und `[PRINCIPLE]` in den Kontext.
* **Effekt:** Das System wägt die Fakten (aus der Suche) gegen die Werte (aus dem Profil) ab.
--- ---
## 7) Feedback & Lernen – WP04c ## 7) Erweiterbarkeit & Teaching (Context Intelligence)
Mindnet lernt nicht durch klassisches Training (Fine-Tuning), sondern durch **Konfiguration**, **Vernetzung** und **Prompting**. Dies ist das **"Teach-the-AI" Paradigma**: Wenn du dem System ein neues Konzept beibringen willst, musst du an drei Stellen eingreifen.
### A. Workflow: Einen neuen Typ implementieren (z. B. `type: risk`)
1. **Physik definieren (`config/types.yaml`)**
Steuere, wie schwer der Inhalt wiegt und wie er vernetzt wird.
```yaml
risk:
chunk_profile: short # Risiken sind prägnant
retriever_weight: 0.90 # Hohe Priorität im Ranking
edge_defaults: ["blocks"] # Automatische Kante zu verlinkten Projekten
```
*Effekt:* Der Retriever spült diese Notizen bei relevanten Anfragen nach oben.
2. **Semantik erklären (`config/prompts.yaml`)**
Bringe dem LLM bei, wie es mit diesem Typ umgehen soll.
```yaml
system_prompt: |
...
REGELN FÜR TYPEN:
- [RISK]: Warnung! Wenn ein Chunk vom Typ 'risk' im Kontext ist, weise den User explizit darauf hin.
```
*Effekt:* Der Chatbot ignoriert das Risiko nicht nur, sondern "versteht" die Warnfunktion.
### B. Workflow: Neue Beziehungen nutzen (z. B. `beeinflusst_von`)
Beziehungen sind der Klebstoff für logische Schlussfolgerungen.
1. **Erfassung im Vault (Markdown)**
Nutze die Inline-Syntax. Du musst nichts vorab definieren.
> "Die Entscheidung für Qdrant wurde [[rel:beeinflusst_von Budgetkürzung 2024]]."
2. **Gewichtung justieren (`config/retriever.yaml`)**
Standardmäßig sind alle Kanten gleich `1.0`. Wenn Kausalität wichtiger ist als Ähnlichkeit, definiere dies hier:
```yaml
retriever:
edge_weights:
beeinflusst_von: 1.5 # Starker Boost: Zieht Ursachen in den Kontext
related_to: 0.5 # Schwacher Boost: Nur "nice to know"
```
*Effekt:* Bei der Frage nach "Qdrant" landet die "Budgetkürzung" (Ursache) im Kontext, weil die Kante stark ist.
3. **Interpretation (Prompting)**
Das LLM erkennt im RAG-Kontext: `Qdrant --[beeinflusst_von]--> Budgetkürzung`.
Es kann daraus den Satz formulieren: *"Die Wahl fiel vermutlich aufgrund der Budgetkürzung auf Qdrant."*
**Fazit:** Nur wenn **Daten** (Vault), **Physik** (Config) und **Semantik** (Prompt) zusammenspielen, entsteht ein intelligenter Zwilling.
---
## 8) Feedback & Lernen – WP04c
Das System verfügt nun über ein **Kurzzeitgedächtnis für Interaktionen**, das die Basis für zukünftiges Lernen bildet. Das System verfügt nun über ein **Kurzzeitgedächtnis für Interaktionen**, das die Basis für zukünftiges Lernen bildet.
### 7.1 Der Feedback-Loop ### 8.1 Der Feedback-Loop
1. **Suche (Situation):** 1. **Suche (Situation):**
Wenn ein Nutzer eine Anfrage stellt, loggt Mindnet die "Situation": Wenn ein Nutzer eine Anfrage stellt, loggt Mindnet die "Situation":
* Den Query-Text. * Den Query-Text.
@@ -205,7 +291,7 @@ Das System verfügt nun über ein **Kurzzeitgedächtnis für Interaktionen**, da
--- ---
## 8) Confidence & Provenance – wozu? ## 9) Confidence & Provenance – wozu?
Der Retriever kann Edges gewichten: Der Retriever kann Edges gewichten:
- **provenance**: *explicit* > *rule* - **provenance**: *explicit* > *rule*
@@ -217,7 +303,7 @@ Eine typische Gewichtung (konfigurierbar in `retriever.yaml`) ist:
--- ---
## 9) Semantik ausgewählter `kind`-Werte ## 10) Semantik ausgewählter `kind`-Werte
- `references` – „Nutzt/erwähnt“; neutral, aber stützend für Kontext. - `references` – „Nutzt/erwähnt“; neutral, aber stützend für Kontext.
- `related_to` – Ähnlichkeit/Verwandtschaft (symmetrisch interpretierbar). - `related_to` – Ähnlichkeit/Verwandtschaft (symmetrisch interpretierbar).
@@ -229,7 +315,7 @@ Eine typische Gewichtung (konfigurierbar in `retriever.yaml`) ist:
--- ---
## 10) Frontmatter-Eigenschaften – Rolle & Empfehlung ## 11) Frontmatter-Eigenschaften – Rolle & Empfehlung
Frontmatter-Eigenschaften (Properties) bleiben **minimiert**: Frontmatter-Eigenschaften (Properties) bleiben **minimiert**:
- **type** – steuert Typ-Defaults via Registry (Pflicht für differenziertes Verhalten). - **type** – steuert Typ-Defaults via Registry (Pflicht für differenziertes Verhalten).
@@ -239,7 +325,7 @@ Frontmatter-Eigenschaften (Properties) bleiben **minimiert**:
--- ---
## 11) Lösch-/Update-Garantien (Idempotenz) ## 12) Lösch-/Update-Garantien (Idempotenz)
- Jede Note hat einen stabilen **note_id** (Frontmatter/Hash). - Jede Note hat einen stabilen **note_id** (Frontmatter/Hash).
- Vor einem Upsert können *alte Chunks/Edges einer Note* gefiltert gelöscht werden (`note_id`-Filter) – das hält Collections sauber bei Re-Imports. - Vor einem Upsert können *alte Chunks/Edges einer Note* gefiltert gelöscht werden (`note_id`-Filter) – das hält Collections sauber bei Re-Imports.
@@ -247,7 +333,7 @@ Frontmatter-Eigenschaften (Properties) bleiben **minimiert**:
--- ---
## 12) Beispiel – Von Markdown zu Kanten (v2.2) ## 13) Beispiel – Von Markdown zu Kanten (v2.2)
**Markdown (Auszug)** **Markdown (Auszug)**
# Relations Showcase # Relations Showcase
@@ -266,7 +352,7 @@ Frontmatter-Eigenschaften (Properties) bleiben **minimiert**:
--- ---
## 13) Referenzen (Projektdateien & Leitlinien) ## 14) Referenzen (Projektdateien & Leitlinien)
- Import-Pipeline & Registry-Auflösung: `scripts/import_markdown.py`. - Import-Pipeline & Registry-Auflösung: `scripts/import_markdown.py`.
- Kantenbildung (V2-Logic): `app/core/derive_edges.py`. - Kantenbildung (V2-Logic): `app/core/derive_edges.py`.
@@ -277,7 +363,7 @@ Frontmatter-Eigenschaften (Properties) bleiben **minimiert**:
--- ---
## 14) Workpackage Status (v2.2.1) ## 15) Workpackage Status (v2.3.0)
Aktueller Implementierungsstand der Module. Aktueller Implementierungsstand der Module.
@@ -290,5 +376,5 @@ Aktueller Implementierungsstand der Module.
| **WP04b**| Explanation Layer | 🟢 Live | API liefert Reasons & Breakdown. | | **WP04b**| Explanation Layer | 🟢 Live | API liefert Reasons & Breakdown. |
| **WP04c**| Feedback Loop | 🟢 Live | Logging (JSONL) & Traceability aktiv. | | **WP04c**| Feedback Loop | 🟢 Live | Logging (JSONL) & Traceability aktiv. |
| **WP05** | Persönlichkeit / Chat | 🟢 Live | RAG-Integration mit Context Enrichment. | | **WP05** | Persönlichkeit / Chat | 🟢 Live | RAG-Integration mit Context Enrichment. |
| **WP06** | Decision Engine | 🟡 Geplant | Nächster Schritt. | | **WP06** | Decision Engine | 🟡 Geplant | Fokus: Strategic Retrieval von Werten. |
| **WP08** | Self-Tuning | 🔴 Geplant | Auto-Adjustment der Gewichte. | | **WP08** | Self-Tuning | 🔴 Geplant | Auto-Adjustment der Gewichte. |
+39
View File
@@ -7,6 +7,45 @@
> **Ziel dieses Dokuments:** > **Ziel dieses Dokuments:**
> Vollständige Beschreibung der technischen Architektur inkl. Graph-Datenbank, Retrieval-Logik und der **neuen RAG-Komponenten (LLM/Chat)**. > Vollständige Beschreibung der technischen Architektur inkl. Graph-Datenbank, Retrieval-Logik und der **neuen RAG-Komponenten (LLM/Chat)**.
---
<details>
<summary>📖 <b>Inhaltsverzeichnis (Klicken zum Öffnen)</b></summary>
- [Mindnet v2.2 – Technische Architektur](#mindnet-v22--technische-architektur)
- [](#)
- [1. Systemüberblick](#1-systemüberblick)
- [1.1 Architektur-Zielbild](#11-architektur-zielbild)
- [1.2 Verzeichnisstruktur \& Komponenten (Post-WP05)](#12-verzeichnisstruktur--komponenten-post-wp05)
- [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)
- [2.3 Edges Collection (`<prefix>_edges`)](#23-edges-collection-prefix_edges)
- [3. Konfiguration](#3-konfiguration)
- [3.1 Typ-Registry (`config/types.yaml`)](#31-typ-registry-configtypesyaml)
- [3.2 Retriever-Config (`config/retriever.yaml`)](#32-retriever-config-configretrieveryaml)
- [3.3 Prompts (`config/prompts.yaml`)](#33-prompts-configpromptsyaml)
- [3.4 Environment (`.env`)](#34-environment-env)
- [4. Import-Pipeline (Markdown → Qdrant)](#4-import-pipeline-markdown--qdrant)
- [4.1 Verarbeitungsschritte](#41-verarbeitungsschritte)
- [5. Retriever-Architektur \& Scoring](#5-retriever-architektur--scoring)
- [5.1 Betriebsmodi](#51-betriebsmodi)
- [5.2 Scoring-Formel (WP04a)](#52-scoring-formel-wp04a)
- [5.3 Explanation Layer (WP04b)](#53-explanation-layer-wp04b)
- [5.4 Graph-Expansion](#54-graph-expansion)
- [6. RAG \& Chat Architektur (WP05)](#6-rag--chat-architektur-wp05)
- [6.1 Schritt 1: Intent \& Retrieval](#61-schritt-1-intent--retrieval)
- [6.2 Schritt 2: Context Enrichment (Das "Context Intelligence" Pattern)](#62-schritt-2-context-enrichment-das-context-intelligence-pattern)
- [6.3 Schritt 3: Generation (LLM Service)](#63-schritt-3-generation-llm-service)
- [6.4 Schritt 4: Response \& Traceability](#64-schritt-4-response--traceability)
- [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)
</details>
--- ---
## 1. Systemüberblick ## 1. Systemüberblick
+31
View File
@@ -4,6 +4,37 @@
**Status:** **FINAL** (Inkl. WP05 RAG Pipeline) **Status:** **FINAL** (Inkl. WP05 RAG Pipeline)
**Quellen:** `mindnet_v2_implementation_playbook.md`, `Handbuch.md`, `chunking_strategy.md`, `docs_mindnet_retriever.md`, `mindnet_admin_guide_v2.2.md`. **Quellen:** `mindnet_v2_implementation_playbook.md`, `Handbuch.md`, `chunking_strategy.md`, `docs_mindnet_retriever.md`, `mindnet_admin_guide_v2.2.md`.
---
<details>
<summary>📖 <b>Inhaltsverzeichnis (Klicken zum Öffnen)</b></summary>
- [mindnet v2.2 – Pipeline Playbook](#mindnet-v22--pipeline-playbook)
- [1. Zweck \& Einordnung](#1-zweck--einordnung)
- [2. Die Import-Pipeline (Runbook)](#2-die-import-pipeline-runbook)
- [2.1 Der 12-Schritte-Prozess](#21-der-12-schritte-prozess)
- [2.2 Standard-Betrieb (Inkrementell)](#22-standard-betrieb-inkrementell)
- [2.3 Deployment \& Restart (Systemd)](#23-deployment--restart-systemd)
- [2.4 Full Rebuild (Clean Slate)](#24-full-rebuild-clean-slate)
- [3. Chunking \& Payload-Aufbau](#3-chunking--payload-aufbau)
- [3.1 Chunk-Profile](#31-chunk-profile)
- [3.2 Payload-Felder](#32-payload-felder)
- [4. Edge-Erzeugung (Die V2-Logik)](#4-edge-erzeugung-die-v2-logik)
- [4.1 Prioritäten \& Provenance](#41-prioritäten--provenance)
- [4.2 Typ-Defaults](#42-typ-defaults)
- [5. Retriever, Chat \& Generation (RAG Pipeline)](#5-retriever-chat--generation-rag-pipeline)
- [5.1 Retrieval (Hybrid)](#51-retrieval-hybrid)
- [5.2 Context Enrichment (Das "Context Intelligence" Pattern)](#52-context-enrichment-das-context-intelligence-pattern)
- [5.3 Generation (LLM)](#53-generation-llm)
- [5.4 Explanation Mode (WP04b)](#54-explanation-mode-wp04b)
- [6. Feedback \& Lernen (WP04c)](#6-feedback--lernen-wp04c)
- [7. Quality Gates \& Tests](#7-quality-gates--tests)
- [7.1 Pflicht-Tests vor Commit](#71-pflicht-tests-vor-commit)
- [7.2 Smoke-Test (E2E)](#72-smoke-test-e2e)
- [8. Ausblick \& Roadmap (Technische Skizzen)](#8-ausblick--roadmap-technische-skizzen)
- [8.1 WP-06: Decision Engine (Skizze)](#81-wp-06-decision-engine-skizze)
- [8.2 WP-08: Self-Tuning (Skizze)](#82-wp-08-self-tuning-skizze)
--- ---
## 1. Zweck & Einordnung ## 1. Zweck & Einordnung