Compare commits

...
5 Commits
Author SHA1 Message Date
Lars fbaa07ba88 docs/appendix.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-08 09:14:14 +01:00
Lars d0ecc5316f docs/mindnet_functional_architecture.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-08 09:11:24 +01:00
Lars 9ee39277ae docs/mindnet_technical_architecture.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-08 09:08:12 +01:00
Lars 9d3fd21c88 docs/admin_guide.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-08 09:07:34 +01:00
Lars d7217672a3 tests/test_feedback_smoke.py aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 4s
2025-12-08 07:10:44 +01:00
5 changed files with 182 additions and 140 deletions

No files matched your search

+61 -81
View File
@@ -1,7 +1,7 @@
# Mindnet v2.2 – Admin Guide # Mindnet v2.2 – Admin Guide
**Datei:** `docs/mindnet_admin_guide_v2.2.md` **Datei:** `docs/mindnet_admin_guide_v2.2.md`
**Stand:** 2025-12-07 **Stand:** 2025-12-08
**Status:** **FINAL** (Konsolidiert WP02–WP04a) **Status:** **FINAL** (Konsolidiert WP02–WP04c)
**Quellen:** `Handbuch.md`, `mindnet_v2_implementation_playbook.md`, `mindnet_technical_architecture.md`, `Programmplan_V2.2.md`. **Quellen:** `Handbuch.md`, `mindnet_v2_implementation_playbook.md`, `mindnet_technical_architecture.md`, `Programmplan_V2.2.md`.
> Dieses Handbuch richtet sich an **Administratoren**. Es beschreibt Installation, Konfiguration, Backup-Strategien, Monitoring und den sicheren Betrieb der Mindnet-Instanz. > Dieses Handbuch richtet sich an **Administratoren**. Es beschreibt Installation, Konfiguration, Backup-Strategien, Monitoring und den sicheren Betrieb der Mindnet-Instanz.
@@ -11,15 +11,13 @@
## 1. Zielgruppe & Scope ## 1. Zielgruppe & Scope
Mindnet ist als **Single-Node System** konzipiert, das lokal (z.B. Laptop) oder auf einem privaten Server (Homelab, Intranet) läuft. Mindnet ist als **Single-Node System** konzipiert, das lokal (z.B. Laptop) oder auf einem privaten Server (Homelab, Intranet) läuft.
Als Admin bist du verantwortlich für: Wir unterscheiden strikt zwischen:
* Die Verfügbarkeit der Dienste (Qdrant, API). * **Production (Port 8001):** Stabiler `main` Branch.
* Die Datensicherheit (Backups). * **Development (Port 8002):** Experimentelle Feature-Branches.
* Die Integrität des Imports (Sync zwischen Vault und DB).
* Die Governance (wer darf zugreifen).
--- ---
## 2. Initial Setup ## 2. Initial Setup & Installation
### 2.1 Systemvoraussetzungen ### 2.1 Systemvoraussetzungen
* **OS:** Linux (Ubuntu 22.04+ empfohlen) oder macOS. * **OS:** Linux (Ubuntu 22.04+ empfohlen) oder macOS.
@@ -29,10 +27,10 @@ Als Admin bist du verantwortlich für:
* RAM: Min. 4GB (abhängig von der Vault-Größe und Qdrant-Index). * RAM: Min. 4GB (abhängig von der Vault-Größe und Qdrant-Index).
* Disk: SSD empfohlen für Qdrant-Performance. * Disk: SSD empfohlen für Qdrant-Performance.
### 2.2 Installation ### 2.2 Installation (Code)
# 1. Repository klonen # 1. Repository klonen
git clone <repo-url> /opt/mindnet git clone <repo-url> /home/llmadmin/mindnet
cd /opt/mindnet cd /home/llmadmin/mindnet
# 2. Umgebung einrichten # 2. Umgebung einrichten
python3 -m venv .venv python3 -m venv .venv
@@ -40,7 +38,7 @@ Als Admin bist du verantwortlich für:
pip install -r requirements.txt pip install -r requirements.txt
# 3. Verzeichnisse anlegen # 3. Verzeichnisse anlegen
mkdir -p logs qdrant_storage mkdir -p logs qdrant_storage data/logs
### 2.3 Qdrant Setup (Docker) ### 2.3 Qdrant Setup (Docker)
Wir nutzen Qdrant als Vektor-Datenbank. Persistenz ist wichtig. Wir nutzen Qdrant als Vektor-Datenbank. Persistenz ist wichtig.
@@ -59,132 +57,114 @@ Erstelle eine `.env` Datei im Root-Verzeichnis. Diese Variablen steuern das Verh
QDRANT_API_KEY="" # Leer lassen für lokale Instanzen ohne Auth QDRANT_API_KEY="" # Leer lassen für lokale Instanzen ohne Auth
# Mindnet Core Settings # Mindnet Core Settings
COLLECTION_PREFIX="mindnet" COLLECTION_PREFIX="mindnet" # "mindnet_dev" für Dev-Umgebung
MINDNET_TYPES_FILE="./config/types.yaml" MINDNET_TYPES_FILE="./config/types.yaml"
MINDNET_RETRIEVER_CONFIG="./config/retriever.yaml" MINDNET_RETRIEVER_CONFIG="./config/retriever.yaml"
# Embedding Settings (Default: all-MiniLM-L6-v2) # Embedding Settings (Default: all-MiniLM-L6-v2)
VECTOR_DIM=384 VECTOR_DIM=384
# Import-Strategie (Performance vs. Gründlichkeit) # Import-Strategie
# Body: Nur Textänderungen triggern Update (Standard)
# Full: Auch Frontmatter-Änderungen (z.B. Tags) triggern Update
MINDNET_HASH_COMPARE="Body" MINDNET_HASH_COMPARE="Body"
MINDNET_HASH_SOURCE="parsed" MINDNET_HASH_SOURCE="parsed"
### 2.5 Deployment via Systemd (Standard ab v2.2.1)
Mindnet wird nicht mehr manuell gestartet, sondern als Systemdienst.
**Production Service (`/etc/systemd/system/mindnet-prod.service`):**
* Läuft auf Port 8001.
* Autostart (`enabled`).
* Restart Policy: `always` (heilt Abstürze automatisch).
**Development Service (`/etc/systemd/system/mindnet-dev.service`):**
* Läuft auf Port 8002.
* Getrennter Ordner (`~/mindnet_dev`).
--- ---
## 3. Betrieb im Alltag ## 3. Betrieb im Alltag
### 3.1 Regelmäßige Importe ### 3.1 Regelmäßige Importe
Der Vault-Zustand sollte regelmäßig (z.B. stündlich per Cronjob oder Trigger) nach Qdrant synchronisiert werden. Das Skript erkennt Änderungen automatisch. Der Vault-Zustand sollte regelmäßig (z.B. stündlich per Cronjob) nach Qdrant synchronisiert werden.
**Cronjob-Beispiel (stündlich):** **Cronjob-Beispiel (stündlich):**
0 * * * * cd /opt/mindnet && .venv/bin/python3 -m scripts.import_markdown --vault /path/to/vault --prefix "mindnet" --apply --purge-before-upsert --sync-deletes >> ./logs/import.log 2>&1 0 * * * * cd /home/llmadmin/mindnet && .venv/bin/python3 -m scripts.import_markdown --vault /path/to/vault --prefix "mindnet" --apply --purge-before-upsert --sync-deletes >> ./logs/import.log 2>&1
* `--purge-before-upsert`: Wichtig, um Fragmente gelöschter Textstellen zu entfernen. * `--purge-before-upsert`: Entfernt Fragmente gelöschter Textstellen.
* `--sync-deletes`: Wichtig, um Notizen aus dem Index zu entfernen, die im Vault gelöscht wurden. * `--sync-deletes`: Entfernt Notizen aus dem Index, die im Vault gelöscht wurden.
### 3.2 Health-Checks ### 3.2 Health-Checks
Prüfe regelmäßig, ob die API und der Retriever korrekt arbeiten. Prüfe regelmäßig, ob die API und der Retriever korrekt arbeiten.
**API Status Check:** **System Status:**
curl -f http://localhost:8000/health || echo "API Down" sudo systemctl status mindnet-prod
**Logischer Smoke-Test:** **Logischer Smoke-Test:**
Führt eine echte Hybrid-Suche durch und prüft, ob Scores berechnet werden. python3 scripts/test_retriever_smoke.py --mode hybrid --url http://localhost:8001/query
python3 scripts/test_retriever_smoke.py --mode hybrid
### 3.3 Umgang mit Fehlern im Importer ### 3.3 Logs & Monitoring
Falls der Importer abbricht oder Dateien ignoriert: Seit v2.2.1 werden technische Logs im Systemd Journal und fachliche Logs in JSONL-Dateien gespeichert.
1. **Diagnose:** Nutze `scripts/diagnose_changed.py`, um zu sehen, warum eine Datei als "unchanged" gilt. * **Technische Fehler (Live):**
python3 -m scripts.diagnose_changed --vault ./vault --note-id "MeineProblemnote" `journalctl -u mindnet-prod -f`
2. **Schema-Validierung:** Prüfe mit `scripts/payload_dryrun.py`, ob eine spezifische Datei das JSON-Schema verletzt. * **Fachliche Logs (Data Flywheel):**
3. **Erzwingen:** Nutze `touch <filename>` im Vault, um den Zeitstempel zu aktualisieren und Hash-Checks zu umgehen, oder nutze `--force` (Vorsicht: Performance). `/home/llmadmin/mindnet/data/logs/search_history.jsonl`
`/home/llmadmin/mindnet/data/logs/feedback.jsonl`
> **Hinweis:** Die JSONL-Logs wachsen endlos ("Append Only"). Richte bei Bedarf `logrotate` ein oder archiviere alte Logs. Lösche sie nicht, da sie die Basis für WP08 (Self-Tuning) sind.
--- ---
## 4. Update-Prozess ## 4. Update-Prozess
Wenn neue Versionen der Mindnet-Software (z.B. Schema-Updates in WP05) ausgerollt werden: Wenn neue Versionen ausgerollt werden (Deployment):
1. **Code aktualisieren:** 1. **Code aktualisieren:**
cd /home/llmadmin/mindnet
git pull origin main git pull origin main
2. **Dependencies prüfen:** 2. **Dependencies prüfen:**
source .venv/bin/activate
pip install -r requirements.txt pip install -r requirements.txt
3. **Schema-Migration:** 3. **Dienst neustarten (Zwingend!):**
Mindnet nutzt oft "Rebuild" statt komplexer Migrationen, da der Vault die Source of Truth ist. sudo systemctl restart mindnet-prod
* Prüfe `CHANGELOG.md` auf "Breaking Changes". 4. **Schema-Migration (falls nötig):**
* Bei Schema-Änderungen: Führe einen **Full Rebuild** durch (siehe 5.3). Bei Änderungen an `types.yaml` oder Index-Strukturen:
python3 -m scripts.import_markdown ... --apply
--- ---
## 5. Backup & Restore ## 5. Backup & Restore
Datensicherheit ruht auf zwei Säulen: Dem Vault (Original) und Qdrant (Index). Datensicherheit ruht auf drei Säulen: Vault (Source), Qdrant (Index), JSONL-Logs (Lern-Daten).
### 5.1 Vault-Backup (Priorität 1) ### 5.1 Vault-Backup (Priorität 1)
Der Markdown-Vault ist die **Single Source of Truth**. Er muss klassisch gesichert werden. Der Markdown-Vault ist die **Single Source of Truth**. Er muss klassisch gesichert werden (Git/NAS).
* **Strategie:** Git-Repository, rsync auf NAS, oder Cloud-Sync.
* **Restore:** Einfach Dateien zurückkopieren und Import laufen lassen.
### 5.2 Qdrant-Snapshots (Priorität 2) ### 5.2 Qdrant-Snapshots (Priorität 2)
Für schnelle Wiederherstellung des Suchindex ohne stundenlangen Re-Import (bei großen Vaults). Für schnelle Wiederherstellung des Suchindex.
**Backup erstellen (Volume-Level):**
docker stop mindnet_qdrant docker stop mindnet_qdrant
tar -czf qdrant_backup_$(date +%F).tar.gz ./qdrant_storage tar -czf qdrant_backup_$(date +%F).tar.gz ./qdrant_storage
docker start mindnet_qdrant docker start mindnet_qdrant
**Alternativ: API-Snapshot (Zero-Downtime):** ### 5.3 Log-Daten (Priorität 3)
Siehe Qdrant Dokumentation (Snapshot API). Sichere den Ordner `data/logs/`. Verlust dieser Daten bedeutet, dass das System vergisst, welche Antworten Nutzer hilfreich fanden.
**Restore:**
1. Container stoppen.
2. Inhalt von `qdrant_storage` löschen.
3. Backup entpacken.
4. Container starten.
### 5.3 Notfall-Wiederherstellung (Rebuild)
Wenn die Datenbank korrupt ist oder Indizes defekt sind, ist der sauberste Weg ein Rebuild:
### 5.4 Notfall-Wiederherstellung (Rebuild)
Wenn die Datenbank korrupt ist:
# 1. DB komplett leeren (Wipe) # 1. DB komplett leeren (Wipe)
python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet" --yes python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet" --yes
# 2. Alles neu importieren # 2. Alles neu importieren
python3 -m scripts.import_markdown --vault /path/to/vault --prefix "mindnet" --apply python3 -m scripts.import_markdown --vault /path/to/vault --prefix "mindnet" --apply
--- ---
## 6. Monitoring & Logging ## 6. Governance & Sicherheit
### 6.1 Log-Quellen ### 6.1 Zugriffsschutz
* **Importer:** Schreibt nach STDOUT/STDERR. Sollte im Cronjob in eine Datei (z.B. `/var/log/mindnet_import.log`) umgeleitet werden. Mindnet hat aktuell **keine integrierte Authentifizierung**.
* **API (Uvicorn):** Standard Access-Logs. * **API:** Muss hinter einem Reverse Proxy (Nginx, Traefik) mit Basic Auth laufen, wenn sie im Netzwerk freigegeben wird.
* **Qdrant:** Docker Logs (`docker logs mindnet_qdrant`). * **Qdrant:** Sollte via Firewall (ufw) auf `127.0.0.1` beschränkt sein.
### 6.2 Wichtige Metriken (Log-Parsing) ### 6.2 Typen-Governance
Achte in den Import-Logs auf folgende Muster:
* `edges_created`: Sollte bei neuen Inhalten > 0 sein.
* `chunks_created`: Sollte plausibel zur Anzahl neuer/geänderter Notizen sein.
* `unresolved_references`: Ein hoher Anstieg deutet auf tote Links oder Tippfehler im Vault hin.
* `ERROR` / `WARNING`: Parsing-Fehler (z.B. ungültiges YAML).
---
## 7. Governance & Sicherheit
### 7.1 Zugriffsschutz
Mindnet hat aktuell **keine integrierte Authentifizierung** (By Design für lokalen Betrieb).
* **API:** Muss hinter einem Reverse Proxy (Nginx, Traefik, Caddy) mit Basic Auth oder OAuth laufen, wenn sie im Netzwerk freigegeben wird.
* **Qdrant:** Sollte nicht öffentlich erreichbar sein (Firewall auf Port 6333, `127.0.0.1` Bindung).
### 7.2 Datenschutz & Sichtbarkeit
* **Interne Nutzung:** Standardmäßig sind alle Inhalte im Index "internal".
* **Trennung:** Wenn du öffentliche und private Daten hast, nutze unterschiedliche `COLLECTION_PREFIX` (z.B. `mindnet_public`, `mindnet_private`) und getrennte Import-Jobs/Vault-Ordner, oder warte auf die WP05-ACL-Implementierung (Filterung auf API-Ebene).
### 7.3 Typen-Governance
Änderungen an der `types.yaml` (z.B. neue Gewichte) wirken global. Änderungen an der `types.yaml` (z.B. neue Gewichte) wirken global.
* **Prozess:** Änderungen sollten getestet werden (Smoke-Test), bevor sie produktiv gehen. * **Prozess:** Änderungen sollten getestet werden (Smoke-Test), bevor sie produktiv gehen.
* **Review:** Prüfe, ob neue Typen (`type: xyz`) auch Chunking-Profile haben, sonst fallen sie auf Defaults zurück.
+19 -23
View File
@@ -1,7 +1,7 @@
# Mindnet v2.2 – Appendices & Referenzen # Mindnet v2.2 – Appendices & Referenzen
**Datei:** `docs/mindnet_appendices_v2.2.md` **Datei:** `docs/mindnet_appendices_v2.2.md`
**Stand:** 2025-12-07 **Stand:** 2025-12-08
**Status:** **FINAL** (Konsolidiert aus WP01–WP04a) **Status:** **FINAL**
**Quellen:** `TYPE_REGISTRY_MANUAL.md`, `chunking_strategy.md`, `mindnet_technical_architecture.md`, `Handbuch.md`. **Quellen:** `TYPE_REGISTRY_MANUAL.md`, `chunking_strategy.md`, `mindnet_technical_architecture.md`, `Handbuch.md`.
> Dieses Dokument bündelt Tabellen, Schemata und technische Referenzen, die in den Prozess-Dokumenten (Playbook, Guides) den Lesefluss stören würden. > Dieses Dokument bündelt Tabellen, Schemata und technische Referenzen, die in den Prozess-Dokumenten (Playbook, Guides) den Lesefluss stören würden.
@@ -10,7 +10,7 @@
## Anhang A: Typ-Registry Referenz (Default-Werte) ## Anhang A: Typ-Registry Referenz (Default-Werte)
Diese Tabelle zeigt die Standard-Konfiguration der `types.yaml` (Stand v2.2). Diese Werte werden beim Import angewendet, sofern im Frontmatter nichts anderes definiert ist. Diese Tabelle zeigt die Standard-Konfiguration der `types.yaml` (Stand v2.2).
| Typ (`type`) | Chunk Profile | Retriever Weight | Edge Defaults (Auto-Kanten) | Beschreibung | | Typ (`type`) | Chunk Profile | Retriever Weight | Edge Defaults (Auto-Kanten) | Beschreibung |
| :--- | :--- | :--- | :--- | :--- | | :--- | :--- | :--- | :--- | :--- |
@@ -28,7 +28,7 @@ Diese Tabelle zeigt die Standard-Konfiguration der `types.yaml` (Stand v2.2). Di
## Anhang B: Edge-Typen & Semantik ## Anhang B: Edge-Typen & Semantik
Referenz aller implementierten Kantenarten (`kind`). Die Spalte "Herkunft" zeigt, durch welchen Mechanismus diese Kante primär entsteht. Referenz aller implementierten Kantenarten (`kind`).
| Kind | Herkunft (Primär) | Symmetrisch? | Bedeutung & Nutzung | | Kind | Herkunft (Primär) | Symmetrisch? | Bedeutung & Nutzung |
| :--- | :--- | :--- | :--- | | :--- | :--- | :--- | :--- |
@@ -46,7 +46,7 @@ Referenz aller implementierten Kantenarten (`kind`). Die Spalte "Herkunft" zeigt
## Anhang C: Datenmodelle (JSON Payloads) ## Anhang C: Datenmodelle (JSON Payloads)
Dies sind die Felder, die effektiv in Qdrant gespeichert werden. Dient als Referenz für Entwickler und Debugging (`payload_dryrun`). Dies sind die Felder, die effektiv in Qdrant gespeichert werden.
### C.1 Note Payload (`mindnet_notes`) ### C.1 Note Payload (`mindnet_notes`)
{ {
@@ -101,31 +101,27 @@ Diese Variablen steuern das Verhalten der Skripte und Container.
| `MINDNET_RETRIEVER_CONFIG`| `config/retriever.yaml`| Pfad zur Scoring-Konfiguration. | | `MINDNET_RETRIEVER_CONFIG`| `config/retriever.yaml`| Pfad zur Scoring-Konfiguration. |
| `MINDNET_HASH_COMPARE` | `Body` | Vergleichsmodus für Import (`Body`, `Frontmatter`, `Full`). | | `MINDNET_HASH_COMPARE` | `Body` | Vergleichsmodus für Import (`Body`, `Frontmatter`, `Full`). |
| `MINDNET_HASH_SOURCE` | `parsed` | Quelle für Hash (`parsed`, `raw`, `file`). | | `MINDNET_HASH_SOURCE` | `parsed` | Quelle für Hash (`parsed`, `raw`, `file`). |
| `MINDNET_HASH_NORMALIZE` | `canonical` | Normalisierung vor Hash (`canonical`, `none`). |
| `VECTOR_DIM` | `384` | Dimension der Embeddings (Modellabhängig). | | `VECTOR_DIM` | `384` | Dimension der Embeddings (Modellabhängig). |
--- ---
## Anhang E: Glossar ## Anhang E: Glossar
Zentrale Begriffe des Mindnet-Systems. * **Callout-Edge:** Kante via `> [!edge]`.
* **Chunking:** Zerlegung von Notizen in kleinere Einheiten.
* **Callout-Edge:** Eine Kante, die durch einen Obsidian-Callout Block (`> [!edge]`) definiert wird. Dient für Listen. * **Confidence:** Vertrauenswürdigkeit einer Kante (0.0-1.0).
* **Chunking:** Prozess des Zerlegens einer Notiz in kleinere, semantische Einheiten (Chunks). * **Explanation Layer:** Komponente, die Scores und Graphen als Begründung liefert.
* **Confidence:** Ein Wert (0.0-1.0), der angibt, wie sicher eine Kante ist. Explizite User-Eingaben haben 1.0, Defaults ~0.7. * **Feedback Loop:** Prozess des Loggens und Auswertens von User-Reaktionen.
* **Idempotenz:** Eigenschaft des Importers, bei mehrfacher Ausführung das exakt gleiche Ergebnis zu liefern (keine Duplikate). * **Idempotenz:** Mehrfache Ausführung liefert gleiches Ergebnis.
* **Inline-Edge:** Eine Kante, die im Fließtext mittels `[[rel:type Ziel]]` definiert wird. Semantisch sehr stark. * **Inline-Edge:** Kante via `[[rel:type Ziel]]`.
* **Provenance:** Die Herkunft einer Information (z.B. "explicit" vs "rule" vs "inference"). * **Retriever:** Suchmaschine (FastAPI).
* **Retriever:** Die Komponente (FastAPI), die Suchanfragen beantwortet und Scores berechnet. * **Vault:** Ordner mit Markdown-Dateien.
* **Rule ID:** Ein String, der genau identifiziert, welche Code-Regel eine Kante erzeugt hat (z.B. `edge_defaults:project:depends_on`).
* **Vault:** Der lokale Ordner mit Markdown-Dateien. Die "Single Source of Truth".
* **Vector Search:** Suche basierend auf semantischer Ähnlichkeit (Embeddings) statt reiner Stichworte.
--- ---
## Anhang F: Workpackage Status (v2.2) ## Anhang F: Workpackage Status (v2.2.1)
Status der Module gemäß Programmplan. Aktueller Implementierungsstand der Module.
| WP | Titel | Status | Anmerkung | | WP | Titel | Status | Anmerkung |
| :--- | :--- | :--- | :--- | | :--- | :--- | :--- | :--- |
@@ -133,8 +129,8 @@ Status der Module gemäß Programmplan.
| **WP02** | Chunking Strategy | 🟢 Live | Profilbasiertes Chunking aktiv. | | **WP02** | Chunking Strategy | 🟢 Live | Profilbasiertes Chunking aktiv. |
| **WP03** | Edge Logic / Import | 🟢 Live | Neue Importer-Pipeline mit Provenance. | | **WP03** | Edge Logic / Import | 🟢 Live | Neue Importer-Pipeline mit Provenance. |
| **WP04a**| Retriever Scoring | 🟢 Live | Hybrider Score (Semantik + Graph). | | **WP04a**| Retriever Scoring | 🟢 Live | Hybrider Score (Semantik + Graph). |
| **WP04b**| Explanation Layer | 🟡 In Arbeit | API liefert Pfade, UI fehlt noch. | | **WP04b**| Explanation Layer | 🟢 Live | API liefert Reasons & Breakdown. |
| **WP04c**| Feedback Loop | 🔴 Geplant | Logging von User-Feedback. | | **WP04c**| Feedback Loop | 🟢 Live | Logging (JSONL) & Traceability aktiv. |
| **WP05** | Virtual Schema | 🟡 Teilw. | `types.yaml` aktiv, ACL fehlt. | | **WP05** | Persönlichkeit / Chat | 🟡 Geplant | Nächster Schritt (RAG). |
| **WP06** | Self-Healing | 🔴 Geplant | Auto-Fixing von Broken Links. | | **WP06** | Self-Healing | 🔴 Geplant | Auto-Fixing von Broken Links. |
| **WP08** | Self-Tuning | 🔴 Geplant | Auto-Adjustment der Gewichte. | | **WP08** | Self-Tuning | 🔴 Geplant | Auto-Adjustment der Gewichte. |
+46 -17
View File
@@ -1,9 +1,9 @@
# Mindnet v2.2 – Fachliche Architektur # Mindnet v2.2 – Fachliche Architektur
**Datei:** `docs/mindnet_functional_architecture_v2.2.md` **Datei:** `docs/mindnet_functional_architecture_v2.2.md`
**Stand:** 2025-12-07 **Stand:** 2025-12-08
**Status:** **FINAL** (Integrierter Stand WP01–WP04a) **Status:** **FINAL** (Integrierter Stand WP01–WP04c)
> Dieses Dokument beschreibt **was** Mindnet fachlich tut und **warum** – mit Fokus auf die Erzeugung und Nutzung von **Edges** (Kanten) zwischen Notizen/Chunks sowie die Logik des Retrievers. Die technische Umsetzung (Module, Flags, Schemas) wird im technischen Dokument detailliert. > Dieses Dokument beschreibt **was** Mindnet fachlich tut und **warum** – mit Fokus auf die Erzeugung und Nutzung von **Edges** (Kanten) zwischen Notizen/Chunks sowie die Logik des Retrievers und der Feedback-Mechanismen. Die technische Umsetzung wird im technischen Dokument detailliert.
--- ---
@@ -134,7 +134,7 @@ Der Importer lädt die Registry aus `MINDNET_TYPES_FILE` oder nutzt Fallbacks. *
## 5) Der Retriever (Funktionaler Layer) ## 5) Der Retriever (Funktionaler Layer)
Der Retriever ist in v2.2 der zentrale Zugangspunkt zum Wissen. Er realisiert die **Hybride Suche**. Der Retriever ist in v2.2 der zentrale Zugangspunkt. Er realisiert die **Hybride Suche**.
### 5.1 Scoring-Modell ### 5.1 Scoring-Modell
Die Relevanz eines Treffers ergibt sich nicht mehr nur aus Textähnlichkeit, sondern aus einer gewichteten Formel: Die Relevanz eines Treffers ergibt sich nicht mehr nur aus Textähnlichkeit, sondern aus einer gewichteten Formel:
@@ -147,17 +147,45 @@ Die Relevanz eines Treffers ergibt sich nicht mehr nur aus Textähnlichkeit, son
* **semantic_score:** Vektorähnlichkeit (Qdrant). * **semantic_score:** Vektorähnlichkeit (Qdrant).
* **retriever_weight:** Wichtigkeit des Typs (z.B. Projekte > Quellen). * **retriever_weight:** Wichtigkeit des Typs (z.B. Projekte > Quellen).
* **edge_bonus:** Belohnung für Chunks, die im Kontext der Anfrage stark vernetzt sind (unter Berücksichtigung der *confidence*). * **edge_bonus:** Belohnung für Chunks, die im Kontext der Anfrage stark vernetzt sind (Summe der Confidence eingehender relevanter Kanten).
* **centrality_bonus:** Belohnung für Knoten, die zentrale Hubs im lokalen Graphen darstellen. * **centrality_bonus:** Belohnung für Knoten, die zentrale Hubs im lokalen Graphen darstellen.
### 5.2 Erklärbarkeit (Explainability) ### 5.2 Erklärbarkeit (Explainability) – WP04b
Der Retriever liefert **Begründungspfade**. Er gibt nicht nur Text zurück, sondern: Der Retriever ist keine Blackbox mehr. Er liefert auf Wunsch (`explain=True`) eine strukturierte Begründung (`Explanation`-Objekt).
* `score_breakdown`: Warum ist dieser Chunk oben? (War es der Text oder der Graph?)
* `paths`: Über welche Kanten wurde dieser Chunk gefunden? (z.B. "Gefunden via `depends_on` von deiner aktuellen Projekt-Notiz"). **Die "Warum"-Logik:**
1. **Semantik:** Prüfung der Cosine-Similarity ("Sehr hohe textuelle Übereinstimmung").
2. **Typ:** Prüfung des `retriever_weight` ("Bevorzugt, da Entscheidung").
3. **Graph (Kontext):**
* **Hub (Outgoing):** Worauf verweist dieser Treffer? ("Verweist auf Qdrant").
* **Authority (Incoming):** Wer verweist auf diesen Treffer? ("Wird referenziert von Projekt Alpha").
Die API gibt diese Analysen als menschenlesbare Sätze (`reasons`) und als Datenstruktur (`score_breakdown`) zurück.
--- ---
## 6) Confidence & Provenance – wozu? ## 6) Feedback & Lernen – WP04c
Das System verfügt nun über ein **Kurzzeitgedächtnis für Interaktionen**, das die Basis für zukünftiges Lernen bildet.
### 6.1 Der Feedback-Loop
1. **Suche (Situation):**
Wenn ein Nutzer eine Anfrage stellt, loggt Mindnet die "Situation":
* Den Query-Text.
* Die Top-K Ergebnisse.
* Den exakten `score_breakdown` zu diesem Zeitpunkt.
* Eine eindeutige `query_id` wird generiert.
2. **Bewertung (Label):**
Der Nutzer (oder ein Agent) bewertet einen spezifischen Treffer (`node_id`) positiv oder negativ (Score 1-5).
Dieses Feedback wird unter Referenzierung der `query_id` gespeichert.
3. **Lernen (Perspektive WP08):**
Durch die Verknüpfung von Situation und Bewertung entstehen Trainingsdaten. Mindnet kann später analysieren: *"Nutzer bevorzugen Treffer mit hohem Edge-Bonus, auch wenn der Text weniger passt."* -> Konsequenz: `edge_weight` erhöhen.
---
## 7) Confidence & Provenance – wozu?
Der Retriever kann Edges gewichten: Der Retriever kann Edges gewichten:
- **provenance**: *explicit* > *rule* - **provenance**: *explicit* > *rule*
@@ -169,7 +197,7 @@ Eine typische Gewichtung (konfigurierbar in `retriever.yaml`) ist:
--- ---
## 7) Semantik ausgewählter `kind`-Werte ## 8) 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).
@@ -181,7 +209,7 @@ Eine typische Gewichtung (konfigurierbar in `retriever.yaml`) ist:
--- ---
## 8) Frontmatter-Eigenschaften – Rolle & Empfehlung ## 9) 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).
@@ -191,7 +219,7 @@ Frontmatter-Eigenschaften (Properties) bleiben **minimiert**:
--- ---
## 9) Lösch-/Update-Garantien (Idempotenz) ## 10) 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.
@@ -199,7 +227,7 @@ Frontmatter-Eigenschaften (Properties) bleiben **minimiert**:
--- ---
## 10) Beispiel – Von Markdown zu Kanten (v2.2) ## 11) Beispiel – Von Markdown zu Kanten (v2.2)
**Markdown (Auszug)** **Markdown (Auszug)**
# Relations Showcase # Relations Showcase
@@ -218,7 +246,7 @@ Frontmatter-Eigenschaften (Properties) bleiben **minimiert**:
--- ---
## 11) Qualitäts- und Testkriterien (fachlich) ## 12) Qualitäts- und Testkriterien (fachlich)
- **Keine Duplikate** gleicher `(src, relation, dst)` in der Collectionsicht (Dedup). - **Keine Duplikate** gleicher `(src, relation, dst)` in der Collectionsicht (Dedup).
- **Explizite Links** werden vollständig materialisiert (*explicit_total*). - **Explizite Links** werden vollständig materialisiert (*explicit_total*).
@@ -227,9 +255,10 @@ Frontmatter-Eigenschaften (Properties) bleiben **minimiert**:
--- ---
## 12) Referenzen (Projektdateien & Leitlinien) ## 13) 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`.
- Typ-Registry: `config/types.yaml` & `TYPE_REGISTRY_MANUAL.md`. - Typ-Registry: `config/types.yaml` & `TYPE_REGISTRY_MANUAL.md`.
- Retriever-Scoring: `app/core/retriever.py` & `wp04_retriever_scoring.md`. - Retriever-Scoring & Explanation: `app/core/retriever.py`.
- Logging Service: `app/services/feedback_service.py`.
+55 -18
View File
@@ -1,8 +1,8 @@
# Mindnet v2.2 – Technische Architektur # Mindnet v2.2 – Technische Architektur
**Datei:** `docs/mindnet_technical_architecture_v2.2.md` **Datei:** `docs/mindnet_technical_architecture_v2.2.md`
**Stand:** 2025-12-07 **Stand:** 2025-12-08
**Status:** **FINAL** (Integrierter Stand WP01–WP04a) **Status:** **FINAL** (Integrierter Stand WP01–WP04c)
**Quellen:** `mindnet_technical_architecture.md`, `chunking_strategy.md`, `Handbuch.md`, `wp04_retriever_scoring.md`, `Überarbeitungshinweise_WP03.md`, `Überarbeitungshinweise_WP04.md`. **Quellen:** `mindnet_technical_architecture.md`, `chunking_strategy.md`, `Handbuch.md`, `wp04_retriever_scoring.md`.
> **Ziel dieses Dokuments:** > **Ziel dieses Dokuments:**
> Vollständige, konsolidierte Beschreibung der aktuellen technischen Architektur von **Mindnet v2.2**. Es definiert die Datenstrukturen in Qdrant, die Verarbeitungspipelines (Importer, Chunker, Edges) und die Retrieval-Logik. Es bildet den **aktuellen Implementierungsstand** ab. > Vollständige, konsolidierte Beschreibung der aktuellen technischen Architektur von **Mindnet v2.2**. Es definiert die Datenstrukturen in Qdrant, die Verarbeitungspipelines (Importer, Chunker, Edges) und die Retrieval-Logik. Es bildet den **aktuellen Implementierungsstand** ab.
@@ -15,8 +15,10 @@
Mindnet ist ein **persönliches Wissensnetz**. Technisch bedeutet das: Mindnet ist ein **persönliches Wissensnetz**. Technisch bedeutet das:
1. **Source:** Markdown-Notizen in einem Vault (Obsidian-kompatibel). 1. **Source:** Markdown-Notizen in einem Vault (Obsidian-kompatibel).
2. **Pipeline:** Ein Python-Importer transformiert diese in **Notes**, **Chunks** und **Edges**. 2. **Pipeline:** Ein Python-Importer transformiert diese in **Notes**, **Chunks** und **Edges**.
3. **Storage:** Speicherung in **Qdrant** (Vektor-Datenbank) in drei getrennten Collections. 3. **Storage:**
4. **Service:** Eine FastAPI-Anwendung stellt Endpunkte für **Semantische** und **Hybride Suche** bereit. * **Qdrant:** Vektor-Datenbank für Graph und Semantik (Collections: notes, chunks, edges).
* **Local Files (JSONL):** Append-Only Logs für Feedback und Search-History (Data Flywheel).
4. **Service:** Eine FastAPI-Anwendung stellt Endpunkte für **Semantische** und **Hybride Suche** sowie **Feedback** bereit.
Das System arbeitet **deterministisch** (stabile IDs) und ist **konfigurationsgetrieben** (`types.yaml`, `retriever.yaml`). Das System arbeitet **deterministisch** (stabile IDs) und ist **konfigurationsgetrieben** (`types.yaml`, `retriever.yaml`).
@@ -34,12 +36,21 @@ Die Codebasis ist modular aufgebaut.
│ │ ├── chunker.py # Text-Zerlegung (Profiling) │ │ ├── chunker.py # Text-Zerlegung (Profiling)
│ │ ├── edges.py # Edge-Datenstrukturen │ │ ├── edges.py # Edge-Datenstrukturen
│ │ ├── derive_edges.py # Logik der Kantenableitung (WP03) │ │ ├── derive_edges.py # Logik der Kantenableitung (WP03)
│ │ └── retriever.py # Scoring & Graph-Expansion (WP04) │ │ ├── graph_adapter.py # Subgraph & Reverse-Lookup (WP04b)
│ ├── models/ # Pydantic DTOs (QueryRequest, etc.) │ │ └── retriever.py # Scoring, Expansion & Explanation (WP04a/b)
│ └── routers/ # API Routen │ ├── models/ # Pydantic DTOs (QueryHit, Explanation, FeedbackRequest)
│ ├── routers/
│ │ ├── query.py # Such-Endpunkt
│ │ ├── feedback.py # Feedback-Endpunkt (WP04c)
│ │ └── ...
│ ├── services/
│ │ ├── feedback_service.py # Logging-Logik (WP04c)
│ │ └── embeddings_client.py
├── config/ ├── config/
│ ├── types.yaml # Typ-Definitionen (Import-Zeit) │ ├── types.yaml # Typ-Definitionen (Import-Zeit)
│ └── retriever.yaml # Scoring-Gewichte (Laufzeit) │ └── retriever.yaml # Scoring-Gewichte (Laufzeit)
├── data/
│ └── logs/ # Lokale JSONL-Logs (WP04c)
├── scripts/ ├── scripts/
│ ├── import_markdown.py # Haupt-Importer CLI │ ├── import_markdown.py # Haupt-Importer CLI
│ ├── payload_dryrun.py # Diagnose: JSON-Generierung ohne DB │ ├── payload_dryrun.py # Diagnose: JSON-Generierung ohne DB
@@ -69,8 +80,6 @@ Repräsentiert die Metadaten einer Datei.
| `updated` | Integer | Zeitstempel (z.B. YYYYMMDD...). | File Stats | | `updated` | Integer | Zeitstempel (z.B. YYYYMMDD...). | File Stats |
| `fulltext` | Text | Gesamter Inhalt (für Export/Rekonstruktion). | Body | | `fulltext` | Text | Gesamter Inhalt (für Export/Rekonstruktion). | Body |
### 2.2 Chunks Collection (`<prefix>_chunks`) ### 2.2 Chunks Collection (`<prefix>_chunks`)
Die atomaren Sucheinheiten. Die atomaren Sucheinheiten.
* **Zweck:** Vektorsuche (Embeddings), Granulares Ergebnis. * **Zweck:** Vektorsuche (Embeddings), Granulares Ergebnis.
@@ -88,8 +97,6 @@ Die atomaren Sucheinheiten.
| `neighbors_prev` | List[Str] | ID des Vorgänger-Chunks. | | `neighbors_prev` | List[Str] | ID des Vorgänger-Chunks. |
| `neighbors_next` | List[Str] | ID des Nachfolger-Chunks. | | `neighbors_next` | List[Str] | ID des Nachfolger-Chunks. |
### 2.3 Edges Collection (`<prefix>_edges`) ### 2.3 Edges Collection (`<prefix>_edges`)
Gerichtete Kanten. Massiv erweitert in WP03 für Provenienz-Tracking. Gerichtete Kanten. Massiv erweitert in WP03 für Provenienz-Tracking.
* **Zweck:** Graph-Traversal, Kontext-Anreicherung. * **Zweck:** Graph-Traversal, Kontext-Anreicherung.
@@ -106,8 +113,6 @@ Gerichtete Kanten. Massiv erweitert in WP03 für Provenienz-Tracking.
| `rule_id` | Keyword | Herkunftsregel. | `explicit:wikilink`, `inline:rel` | | `rule_id` | Keyword | Herkunftsregel. | `explicit:wikilink`, `inline:rel` |
| `confidence` | Float | Vertrauenswürdigkeit (0.0-1.0). | 1.0, 0.95, 0.7 | | `confidence` | Float | Vertrauenswürdigkeit (0.0-1.0). | 1.0, 0.95, 0.7 |
--- ---
## 3. Konfiguration ## 3. Konfiguration
@@ -185,12 +190,44 @@ $$
* $B_{cent}$: Centrality-Bonus (im lokalen Subgraphen). * $B_{cent}$: Centrality-Bonus (im lokalen Subgraphen).
* **Gewichte ($W$):** Stammen aus `retriever.yaml`. * **Gewichte ($W$):** Stammen aus `retriever.yaml`.
### 5.3 Graph-Expansion ### 5.3 Explanation Layer (WP04b)
Der Hybrid-Modus lädt dynamisch die Nachbarschaft der Top-K Vektor-Treffer ("Seeds") über `graph_adapter.expand`. Dies baut einen temporären `NetworkX`-Graphen im Speicher, auf dem Boni berechnet werden. Der Retriever kann Ergebnisse erklären (`explain=True`).
* **Logik:**
* Berechnung des `ScoreBreakdown` (Anteile von Semantik, Graph, Typ).
* Analyse des lokalen Subgraphen mittels `graph_adapter.py`.
* **Incoming Edges (Authority):** Wer zeigt auf diesen Treffer? (z.B. "Referenziert von...")
* **Outgoing Edges (Hub):** Worauf zeigt dieser Treffer? (z.B. "Verweist auf...")
* **Output:** `QueryHit` enthält ein `explanation` Objekt mit menschenlesbaren `reasons` und `related_edges`.
### 5.4 Graph-Expansion
Der Hybrid-Modus lädt dynamisch die Nachbarschaft der Top-K Vektor-Treffer ("Seeds") über `graph_adapter.expand`. Dies baut einen temporären `NetworkX`-artigen Graphen im Speicher (Klasse `Subgraph`), auf dem Boni berechnet werden.
--- ---
## 6. Indizes & Performance ## 6. Feedback & Logging Architektur (WP04c)
Mindnet implementiert ein "Data Flywheel" zur späteren Optimierung (Self-Tuning).
### 6.1 Komponenten
* **Feedback Service (`app/services/feedback_service.py`):** Kapselt die Schreibzugriffe.
* **Storage:** Lokales Dateisystem (`data/logs/`), Format JSONL (Line-delimited JSON).
### 6.2 Log-Dateien
1. **`search_history.jsonl`**:
* Speichert jede Anfrage an `/query`.
* Enthält: `query_id`, `query_text`, `timestamp`, `hits` (inkl. `score_breakdown` Snapshots).
* Zweck: Trainingsdaten ("Was hat das System gesehen?").
2. **`feedback.jsonl`**:
* Speichert User-Reaktionen an `/feedback`.
* Enthält: `query_id`, `node_id`, `score` (1-5), `comment`.
* Zweck: Labels ("War es gut?").
### 6.3 Traceability
Die `query_id` (UUIDv4) wird im `/query` Response generiert und muss vom Client beim `/feedback` Aufruf mitgesendet werden. Dies ermöglicht den Join zwischen Snapshot und Bewertung.
---
## 7. Indizes & Performance
Damit Qdrant performant bleibt, sind Payload-Indizes essenziell. Damit Qdrant performant bleibt, sind Payload-Indizes essenziell.
@@ -203,7 +240,7 @@ Validierung erfolgt über `tests/ensure_indexes_and_show.py`.
--- ---
## 7. Offene Punkte / Known Limitations ## 8. Offene Punkte / Known Limitations
1. **Multi-Target Inline-Relations:** 1. **Multi-Target Inline-Relations:**
* `rel: similar_to [[A]] [[B]]` wird aktuell parser-seitig nicht unterstützt. * `rel: similar_to [[A]] [[B]]` wird aktuell parser-seitig nicht unterstützt.
+1 -1
View File
@@ -4,7 +4,7 @@ import sys
import time import time
# Konfiguration # Konfiguration
BASE_URL = "http://localhost:8002" BASE_URL = "http://localhost:8001"
QUERY_URL = f"{BASE_URL}/query" QUERY_URL = f"{BASE_URL}/query"
FEEDBACK_URL = f"{BASE_URL}/feedback" FEEDBACK_URL = f"{BASE_URL}/feedback"