Compare commits

..
13 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
Lars e39b685b1e Merge pull request 'WP04c' (#2) from WP04c into main
Deploy mindnet to llm-node / deploy (push) Successful in 3s
Reviewed-on: #2
2025-12-08 07:07:12 +01:00
Lars 5b9399361d Programmmanagement/Programmplan_V2.2.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-08 06:59:40 +01:00
Lars 7631b93900 Programmmanagement/ARCHITECTURE_SNAPSHOT_v2.2.1.md hinzugefügt 2025-12-08 06:53:04 +01:00
Lars f98eb8fc16 neuer Test für Feedback (WP04c) 2025-12-07 19:32:30 +01:00
Lars ab60106fb9 Merge branch 'WP04c' of http://192.168.2.144:3000/Lars/mindnet into WP04c 2025-12-07 19:30:05 +01:00
Lars caab41a760 WP04c 2025-12-07 19:29:48 +01:00
Lars 78d8ab11ed docs/dev_workflow.md aktualisiert 2025-12-07 19:09:03 +01:00
Lars d49da1b5fe docs/dev_workflow.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-07 18:53:13 +01:00
13 changed files with 738 additions and 737 deletions

No files matched your search

@@ -0,0 +1,27 @@
# Architecture Snapshot v2.2.1
**Stand:** Nach Abschluss von WP-04c
**Kontext:** Wichtig für WP-05 Entwicklung.
## 1. Neue Komponenten (Seit v2.2.0)
### A. Feedback Service (`app/services/feedback_service.py`)
- **Zweck:** Logging von Trainingsdaten für späteres Self-Tuning (WP-08).
- **Storage:** Lokale JSONL-Dateien in `data/logs/` (Append-Only).
- `search_history.jsonl`: Query + Snapshot der Ergebnisse (Scores).
- `feedback.jsonl`: User-Rating zu spezifischer `node_id`.
### B. Explanation Layer (`app/core/retriever.py`)
- **Logik:** Der Retriever berechnet nicht nur Scores, sondern generiert `Explanation`-Objekte.
- **Graph:** `Subgraph` (in `graph_adapter.py`) führt jetzt auch `reverse_adj` (Incoming Edges), um zu erklären, warum ein Knoten wichtig ist ("Referenziert von...").
### C. DTOs (`app/models/dto.py`)
Das Datenmodell wurde massiv erweitert. Wichtige Klassen für WP-05:
- `QueryResponse`: Enthält jetzt `query_id` (UUID).
- `QueryHit`: Enthält optional `explanation` (Typ `Explanation`).
- `FeedbackRequest`: Für den Feedback-Loop.
## 2. Implikationen für WP-05 (Chat)
1. **Logging:** Auch der neue `/chat` Endpoint sollte idealerweise die `query_id` loggen oder nutzen, um Konsistenz zu wahren.
2. **DTO-Nutzung:** Der Chat-Service wird intern den Retriever aufrufen. Er muss mit den `QueryHit`-Objekten arbeiten, um den Kontext für das LLM zu bauen.
3. **Config:** Die Persönlichkeit wird in `config/prompts.yaml` definiert (Late Binding), nicht im Python-Code hardcodiert.
+247 -506
View File
@@ -1,68 +1,68 @@
# mindnet v2.2 — Programmplan
**Version:** 2.2
**Stand:** 2025-12-06
**Status:** Aktiv (Fortschreibung von v2.1)
# mindnet v2.2 — Programmplan
**Version:** 2.2.1 (Post-WP04 Update)
**Stand:** 2025-12-07
**Status:** Aktiv
---
## 1. Programmauftrag
mindnet v2.2 entwickelt ein persönliches, wachsendes KI-Gedächtnis, das:
mindnet v2.2 entwickelt ein persönliches, wachsendes KI-Gedächtnis, das:
- Wissen, Erfahrungen, Werte und Entscheidungen speichert,
- diese Informationen semantisch verknüpft und rekonstruierbar macht,
- einen KI-Zwilling aufbaut, der ähnlich argumentiert, entscheidet und reflektiert wie du,
- Wissen, Erfahrungen, Werte und Entscheidungen speichert,
- diese Informationen semantisch verknüpft und rekonstruierbar macht,
- einen KI-Zwilling aufbaut, der ähnlich argumentiert, entscheidet und reflektiert wie du,
- über mehrere Kanäle gefüttert wird:
- Obsidian-Markdown (primäre Quelle),
- Chat-basierter Agent (mindnet-Assistent),
- später: Interview-Assistent (strukturierte Dialogerfassung),
- automatisch neue Zusammenhänge erkennt und vernetzt (Edges, Typen, Hinweise),
- später: Interview-Assistent (strukturierte Dialogerfassung),
- automatisch neue Zusammenhänge erkennt und vernetzt (Edges, Typen, Hinweise),
- sich durch Rückmeldungen (Feedback) selbst verbessert (Self-Tuning).
Langfristig soll mindnet als **digitales Gegenüber** funktionieren, das:
Langfristig soll mindnet als **digitales Gegenüber** funktionieren, das:
- dich versteht,
- deine Denkweise reflektiert,
- deine Werte kennt und verwendet,
- Entscheidungen begründen kann („Warum?“),
- Erinnerungen einordnet,
- dich versteht,
- deine Denkweise reflektiert,
- deine Werte kennt und verwendet,
- Entscheidungen begründen kann („Warum?“),
- Erinnerungen einordnet,
- und für deine Nachkommen als dialogfähiger Gesprächspartner zur Verfügung steht.
mindnet ist **kein statisches Wissensarchiv**, sondern ein **lebendes, lernendes Gedächtnismodell** mit Fokus auf:
- persönliche Perspektive,
- erklärbare Begründungspfade,
- kontinuierliche Erweiterbarkeit,
- robuste technische Basis (lokal, nachvollziehbar, versioniert).
- persönliche Perspektive,
- erklärbare Begründungspfade,
- kontinuierliche Erweiterbarkeit,
- robuste technische Basis (lokal, nachvollziehbar, versioniert).
---
## 2. Vision
> „Ein persönliches semantisches Gedächtnis, das mit mir wächst, meine Persönlichkeit spiegelt und mir als intelligenter, erklärbarer, lernender Begleiter dient.“
> „Ein persönliches semantisches Gedächtnis, das mit mir wächst, meine Persönlichkeit spiegelt und mir als intelligenter, erklärbarer, lernender Begleiter dient.“
Kernprinzipien der Vision:
- **Erklärbarkeit:**
Jede Antwort muss über Edges, Scores, Werte-Bezüge und Herkunftsnotizen begründbar sein.
- **Erklärbarkeit:**
Jede Antwort muss über Edges, Scores, Werte-Bezüge und Herkunftsnotizen begründbar sein.
- **Wachstum:**
Das System arbeitet von Anfang an mit unvollständigen Daten, kann aber schrittweise dichter werden, ohne dass alte Notizen massenhaft manuell angepasst werden müssen.
- **Wachstum:**
Das System arbeitet von Anfang an mit unvollständigen Daten, kann aber schrittweise dichter werden, ohne dass alte Notizen massenhaft manuell angepasst werden müssen.
- **Flexibilität (Late Binding):**
Semantik wird überwiegend in Konfiguration (z. B. `types.yaml`, Policies, Knowledge-Design) festgelegt, nicht in jeder einzelnen Markdown-Datei.
- **Flexibilität (Late Binding):**
Semantik wird überwiegend in Konfiguration (z. B. `types.yaml`, Policies, Knowledge-Design) festgelegt, nicht in jeder einzelnen Markdown-Datei.
- **Autonomie & Self-Healing:**
mindnet schlägt fehlende Typen, Relationen und Edges vor (z. B. aus Inline-Relationen, Edge-Defaults, Ähnlichkeitsbeziehungen) und baut damit einen „self-healing graph“ auf.
- **Autonomie & Self-Healing:**
mindnet schlägt fehlende Typen, Relationen und Edges vor (z. B. aus Inline-Relationen, Edge-Defaults, Ähnlichkeitsbeziehungen) und baut damit einen „self-healing graph“ auf.
- **Lernen & Self-Tuning:**
Feedback zu Antworten (gut/schlecht, relevant/nicht relevant) fließt in Score-Gewichte, Policies und ggf. Edge-Struktur ein.
- **Lernen & Self-Tuning:**
Feedback zu Antworten (gut/schlecht, relevant/nicht relevant) fließt in Score-Gewichte, Policies und ggf. Edge-Struktur ein.
- **Persönlichkeit:**
Entscheidungen werden wert- und erfahrungsbasiert begründet; mittelfristig entsteht ein Persönlichkeitsmodell, das den KI-Zwilling trägt.
- **Persönlichkeit:**
Entscheidungen werden wert- und erfahrungsbasiert begründet; mittelfristig entsteht ein Persönlichkeitsmodell, das den KI-Zwilling trägt.
- **Incremental Growth:**
Das System muss mit wenigen, heterogenen Notizen starten und sich fortlaufend verdichten können – ohne Retro-Massenmigrationen im Vault.
- **Incremental Growth:**
Das System muss mit wenigen, heterogenen Notizen starten und sich fortlaufend verdichten können – ohne Retro-Massenmigrationen im Vault.
---
@@ -70,81 +70,84 @@ Kernprinzipien der Vision:
### 3.1 Kurzfristig (nächste Monate)
- Automatische Sammlung von Wissen aus Markdown-Vault und ersten Chat-Dialogen.
- Aufbau eines stabilen Graph-Speichers in Qdrant (`*_notes`, `*_chunks`, `*_edges`).
- Semantischer und graphbasierter Retriever (WP-04a abgeschlossen, WP-04b/04c in Vorbereitung).
- Automatische Sammlung von Wissen aus Markdown-Vault und ersten Chat-Dialogen.
- Aufbau eines stabilen Graph-Speichers in Qdrant (`*_notes`, `*_chunks`, `*_edges`).
- Semantischer und graphbasierter Retriever (WP-04a abgeschlossen).
- **Erklärbarkeit:** Why-Layer liefert Begründungen zu Treffern (WP-04b abgeschlossen).
- **Feedback-Loop:** Systematisches Logging von Suche und Bewertung (WP-04c abgeschlossen).
- Automatisierte Erkennung von Beziehungen:
- Wikilinks, Inline-Relationen, Callout-Edges, Typ-Defaults.
- Schrittweises Lernen über Feedback (Score-Tuning, noch „manuell“ konfiguriert). :contentReference[oaicite:8]{index=8}
- Wikilinks, Inline-Relationen, Callout-Edges, Typ-Defaults.
- Schrittweises Lernen über Feedback (Score-Tuning, noch „manuell“ konfiguriert).
- „Mitwachsendes“ Schema ohne Obsidian-Umstrukturierungen:
- Neues Wissen kann sofort erfasst werden,
- bestehende Notizen bleiben gültig (Virtual Schema Layer).
- bestehende Notizen bleiben gültig (Virtual Schema Layer).
- Technische Basis für die späteren Agenten und den KI-Zwilling:
- lokaler FastAPI-Dienst,
- Qdrant als Graph-Backend,
- konfigurierbarer Retriever (`retriever.yaml`).
- konfigurierbarer Retriever (`retriever.yaml`).
### 3.2 Mittelfristig
- Persönlichkeitsprofil wird stabil erkannt und für Antworten genutzt (Typen, Werte-Notizen, Entscheidungsnotizen).
- Why-Layer: KI-Assistenz für Entscheidungen mit nachvollziehbarer Argumentation.
- Interview-Assistent erstellt neue Notes automatisch (strukturierte Dialoge → Markdown).
- mindnet erzeugt Vorschläge für neue Notes & Edges und bietet einen „Vernetzungs-Assistenten“ für manuell angelegte Notizen.
- Agenten können über MCP-Tools (`mindnet_query`, `mindnet_subgraph`, `mindnet_store_note`, `mindnet_explain`) auf mindnet zugreifen.
- Persönlichkeitsprofil wird stabil erkannt und für Antworten genutzt (Typen, Werte-Notizen, Entscheidungsnotizen).
- **RAG-Chat:** KI antwortet in natürlicher Sprache auf Basis von Wissen und Persönlichkeit (WP-05).
- Why-Layer: KI-Assistenz für Entscheidungen mit nachvollziehbarer Argumentation.
- Interview-Assistent erstellt neue Notes automatisch (strukturierte Dialoge → Markdown).
- mindnet erzeugt Vorschläge für neue Notes & Edges und bietet einen „Vernetzungs-Assistenten“ für manuell angelegte Notizen.
- Agenten können über MCP-Tools (`mindnet_query`, `mindnet_subgraph`, `mindnet_store_note`, `mindnet_explain`) auf mindnet zugreifen.
### 3.3 Langfristig
- KI-Zwilling, der deinen Stil, deine Werte und deine typische Denkweise repräsentiert.
- Weitgehend autonomes Self-Tuning der Wissensstruktur (auf Basis gespeicherter Feedback-Daten & Policies).
- KI-Zwilling, der deinen Stil, deine Werte und deine typische Denkweise repräsentiert.
- Weitgehend autonomes Self-Tuning der Wissensstruktur (auf Basis gespeicherter Feedback-Daten & Policies).
- Lebenslanges Gedächtnis, das
- konsistent bleibt,
- wächst,
- sich weiterentwickelt,
- und deine Geschichte für deine Nachkommen erzählbar und erlebbar macht.
- konsistent bleibt,
- wächst,
- sich weiterentwickelt,
- und deine Geschichte für deine Nachkommen erzählbar und erlebbar macht.
---
## 4. Architekturprinzipien
Die folgenden Prinzipien steuern alle Workpackages und Entscheidungen:
Die folgenden Prinzipien steuern alle Workpackages und Entscheidungen:
1. **Late Binding (späte Semantik)**
- Struktur und Interpretation werden in Konfigurationen (z. B. `types.yaml`, Policies, `knowledge_design.md`) definiert, nicht direkt in den Vault-Dateien.
1. **Late Binding (späte Semantik)**
- Struktur und Interpretation werden in Konfigurationen (z. B. `types.yaml`, Policies, `knowledge_design.md`) definiert, nicht direkt in den Vault-Dateien.
- Erlaubt spätere Anpassungen ohne manuelle Massenänderungen.
2. **Virtual Schema Layer**
- Typen, Regeln, Policies, Edge-Defaults werden im Schema-Layer beschrieben (z. B. `knowledge_design.md`, `mindnet_functional_architecture.md`, `types.yaml`).
2. **Virtual Schema Layer**
- Typen, Regeln, Policies, Edge-Defaults werden im Schema-Layer beschrieben (z. B. `knowledge_design.md`, `mindnet_functional_architecture.md`, `types.yaml`).
- Markdown-Dateien benötigen nur minimale, robuste Angaben (Titel, Typ, optionale Properties).
3. **Self-Healing Graph**
- Der Graph wird regelmäßig analysiert (Edges, Centrality, fehlende Links).
- Automatisierte Jobs ergänzen fehlende Kanten (ähnliche Inhalte, typisierte Standardbeziehungen, Backlinks).
3. **Self-Healing Graph**
- Der Graph wird regelmäßig analysiert (Edges, Centrality, fehlende Links).
- Automatisierte Jobs ergänzen fehlende Kanten (ähnliche Inhalte, typisierte Standardbeziehungen, Backlinks).
4. **Deterministische IDs**
- Notes, Chunks und Edges erhalten stabile IDs (z. B. UUIDv5, deterministische `note_id`/`chunk_id`/`edge_id`).
- Der Graph ist jederzeit wiederaufbaubar (Import-Pipeline idempotent).
4. **Deterministische IDs**
- Notes, Chunks und Edges erhalten stabile IDs (z. B. UUIDv5, deterministische `note_id`/`chunk_id`/`edge_id`).
- Der Graph ist jederzeit wiederaufbaubar (Import-Pipeline idempotent).
5. **Full Explainability**
5. **Full Explainability**
- Jeder Score, jede Beziehung, jeder Vorschlag muss über:
- Edges,
- Scoring-Komponenten (Semantik, Typ, Edge-Bonus, Centrality),
- Provenienz (Notizen, Chunks, rule_id, confidence) nachvollziehbar sein.
- Provenienz (Notizen, Chunks, rule_id, confidence) nachvollziehbar sein.
6. **Persistence First**
- Obsidian bleibt die primäre Quelle der Wahrheit.
6. **Persistence First**
- Obsidian bleibt die primäre Quelle der Wahrheit.
- mindnet ergänzt, schlägt Änderungen vor, schreibt aber nur kontrolliert (z. B. über Rewriter oder Vernetzungs-Assistent mit Freigabe).
7. **Minimalinvasives Schreiben**
- Automatische Veränderungen an Markdown-Dateien erfolgen ausschließlich nach expliziter Zustimmung.
7. **Minimalinvasives Schreiben**
- Automatische Veränderungen an Markdown-Dateien erfolgen ausschließlich nach expliziter Zustimmung.
- Rewriter und Vernetzungs-Assistent arbeiten grundsätzlich im Vorschlagsmodus.
8. **Incremental Growth & Early Value**
- Das System muss bereits mit wenigen Notizen und einem kleinen Vault sinnvolle Antworten liefern (Retrieval-MVP).
- Spätere Erweiterungen (Typen, Policies, zusätzliche Edges) dürfen bestehende Notizen nicht „ungültig“ machen, sondern ergänzen sie.
8. **Incremental Growth & Early Value**
- Das System muss bereits mit wenigen Notizen und einem kleinen Vault sinnvolle Antworten liefern (Retrieval-MVP).
- Spätere Erweiterungen (Typen, Policies, zusätzliche Edges) dürfen bestehende Notizen nicht „ungültig“ machen, sondern ergänzen sie.
- Feedback-Mechanismen werden früh eingeführt, auch wenn sie anfangs noch nicht vollautomatisch ausgewertet werden.
9. **Observability & Testbarkeit**
- Jeder Importlauf, jede Retriever-Anfrage und jede Policy-Änderung soll prüfbar sein (Logs, Traces, Tests, Reports).
9. **Observability & Testbarkeit**
- Jeder Importlauf, jede Retriever-Anfrage und jede Policy-Änderung soll prüfbar sein (Logs, Traces, Tests, Reports).
---
@@ -154,9 +157,9 @@ Die folgenden Prinzipien steuern alle Workpackages und Entscheidungen:
Phase B – Semantik, Graph & Lernen
Phase C – Persönlichkeitsmodell & KI-Zwilling
Phase D – Agenten, MCP & Interaktion
Phase E – Review, Refactoring, Dokumentation
Phase E – Review, Refactoring, Dokumentation
Alle Workpackages sind einer Phase zugeordnet; einige Workpackages (z. B. WP-03, WP-04a) sind bereits abgeschlossen und bilden heute die Basis für alle weiteren Schritte.
Alle Workpackages sind einer Phase zugeordnet. WP-01 bis WP-04c sind bereits erfolgreich abgeschlossen.
---
@@ -164,521 +167,270 @@ Alle Workpackages sind einer Phase zugeordnet; einige Workpackages (z. B. WP-03,
### Legende Aufwand / Komplexität
- Aufwand: Niedrig / Mittel / Hoch
- Komplexität: Niedrig / Mittel / Hoch
- Aufwand: Niedrig / Mittel / Hoch
- Komplexität: Niedrig / Mittel / Hoch
Die Status-Ampel zeigt den aktuellen Stand gemäß Programmfortschritt. :contentReference[oaicite:18]{index=18}
Die Status-Ampel zeigt den aktuellen Stand gemäß Programmfortschritt.
---
### WP-01 – Wissensdesign (abgeschlossen)
**Phase:** A
**Status:** 🟢 abgeschlossen
**Phase:** A
**Status:** 🟢 abgeschlossen
**Ziel:**
Grundlegendes Schema für mindnet festlegen (`knowledge_design.md`), inkl.:
**Ziel:**
Grundlegendes Schema für mindnet festlegen (`knowledge_design.md`), inkl.:
- Note-Typen (z. B. `concept`, `experience`, `project`, `decision`, `value`).
- Standard-Properties und Grundstruktur von Edges.
- Abbildung zentraler Lebens-Bereiche.
- Note-Typen (z. B. `concept`, `experience`, `project`, `decision`, `value`, `principle`, `person`, `event`, etc.).
- Standard-Properties (Titel, Typ, Tags, Status, Zeitstempel, Referenzen, Policies).
- Grundstruktur von Edges (z. B. `belongs_to`, `references`, `depends_on`, `similar_to`, `related_to`, `influenced_by`).
- Abbildung zentraler Lebens-Bereiche, Rollen und Wissenskategorien.
**Aufwand / Komplexität:**
- Aufwand: Mittel
- Komplexität: Mittel
**Erreichte Ergebnisse / Funktionsumfang:**
- `knowledge_design.md` in Version 1.5 definiert:
- Zielarchitektur,
- Collections,
- Identitätsmodell,
- zentrale Typen und Edges. :contentReference[oaicite:20]{index=20}
- Das Dokument beschreibt klar:
- wie Wissen fachlich strukturiert wird,
- welche Typen und Relationen in mindnet „erwartet“ werden,
- wie spätere Erweiterungen (neue Typen, zusätzliche Edge-Arten) ohne Retro-Migration möglich sind.
**DoD:**
- Schema ist konsistent beschrieben.
- Grundtypen und Edge-Arten sind definiert und im Code konzeptionell verankert (z. B. via `types.yaml`).
- Das Dokument dient als Referenz für alle folgenden WPs.
**Erreichte Ergebnisse:**
- `knowledge_design.md` und `types.yaml` definieren die Zielarchitektur.
---
### WP-02 – Chunking & Hash-Strategie (abgeschlossen)
**Phase:** A
**Status:** 🟢 abgeschlossen
**Phase:** A
**Status:** 🟢 abgeschlossen
**Ziel:**
Festlegen und implementieren einer robusten Chunking-Strategie und einer Hash-Logik zur Änderungs­erkennung.
**Ziel:**
Festlegen und implementieren einer robusten Chunking-Strategie und einer Hash-Logik zur Änderungserkennung.
**Umfang (fachlich & technisch):**
- Text in semantisch sinnvolle Chunks teilen (Heading-/Block-aware).
- Parallelhaltung von:
- `text` (Chunk-Kern ohne Overlap),
- `window` (Chunk-Fenster mit Overlap für Embeddings).
- Hash-Modi zur Änderungs­erkennung (Body / Frontmatter / Full, canonical vs. none).
- Unterstützung eines „Baseline-Modus“ (mehrere Hash-Signaturen), um spätere Modus-Wechsel zu ermöglichen, ohne alle Notizen als „geändert“ zu sehen.
**Aufwand / Komplexität:**
- Aufwand: Mittel
- Komplexität: Mittel/Hoch
**Erreichte Ergebnisse / Funktionsumfang:**
- Implementierte Chunker-Logik mit Ziel-Längen, Overlap und Nachbarschaft (`neighbors_prev`, `neighbors_next`).
- Tests zur Überprüfung der Rekonstruktion von Notiz-Bodies aus Chunks (`verify_chunks_integrity.py`, `check_chunks_window_vs_text.py`).
- Hash-Konfiguration über ENV-Variablen + Option `--baseline-modes`.
- Roundtrip-Tests für Vault → Qdrant → Export-Vault (keine ungewollten Veränderungen an Inhalten).
**DoD:**
- Chunking stabil, deterministisch, überprüft.
- Hash-Strategie ermöglicht sichere Änderungs­erkennung ohne Mass-Diffs bei Konfigurationswechsel.
**Erreichte Ergebnisse:**
- Implementierte Chunker-Logik mit Overlap.
- Stabile Hash-Strategie zur sicheren Änderungserkennung.
---
### WP-03 – Import-Pipeline & Edge-System v2 (abgeschlossen)
**Phase:** A/B
**Status:** 🟢 abgeschlossen
**Phase:** A/B
**Status:** 🟢 abgeschlossen
**Ziel:**
Durchgängige Import-Pipeline von Markdown → Notes/Chunks/Edges in Qdrant mit deterministischen IDs, typbasierten Defaults und erklärbarem Edge-Modell.
**Ziel:**
Durchgängige Import-Pipeline von Markdown → Notes/Chunks/Edges in Qdrant mit deterministischen IDs.
**Umfang:**
- Parser (robust gegenüber Zeichensatzfehlern, Frontmatter/Body-Erkennung, Sonderfälle wie Silverbullet-Dateien).
- Bau von Note-Payloads (`note_payload`):
- Typ-Vererbung (`retriever_weight`, `chunk_profile`, `edge_defaults`).
- Bau von Chunk-Payloads (`chunk_payload`):
- `text`, `window`, Nachbarn, Typ-Information.
- Edge-System:
- Strukturkanten (`belongs_to`, `next`, `prev`),
- explizite Wikilinks (`[[Note]]` → `references`),
- Inline-Relationen (`[[rel:depends_on Note]]`),
- Callout-Edges (`> [!edge] related_to: [[Note]]`),
- typbasierte Standardkanten aus `types.yaml` (`edge_defaults`).
- Idempotente Upserts in Qdrant (Notes/Chunks/Edges).
**Aufwand / Komplexität:**
- Aufwand: Hoch
- Komplexität: Hoch
**Erreichte Ergebnisse / Funktionsumfang:**
- Vollständige E2E-Import-Pipeline incl. Tests (`run_e2e_roundtrip.sh`, `compare_vaults.py`, `validate_edges`, `edges_full_check`).
- deterministische ID-Vergabe für Notes/Chunks/Edges.
- vollständiges Edge-Modell gemäß Facharchitektur (`mindnet_functional_architecture.md`). :contentReference[oaicite:26]{index=26}
- Exporte zurück nach Markdown (Export-Pipeline) ermöglicht Roundtrip-Vergleich.
**DoD:**
- Importer generiert stabile Notes/Chunks/Edges für gesamten Vault.
- Edge-Invarianten (`belongs_to == #Chunks`, `next/prev` konsistent) erfüllt.
- Roundtrip: Exportierte Vault-Version stimmt inhaltlich mit originalem Vault überein (bis auf bewusst ausgeschlossene Dateien).
**Erreichte Ergebnisse:**
- Vollständige E2E-Import-Pipeline.
- Vollständiges Edge-Modell (Strukturkanten, Wikilinks, Inline-Relationen).
---
### WP-04a – Retriever & Graph-Scoring (abgeschlossen)
**Phase:** B
**Status:** 🟢 abgeschlossen
**Phase:** B
**Status:** 🟢 abgeschlossen
**Ziel:**
Aufbau eines hybriden Retrievers, der Semantik (Embeddings), Typwissen (`retriever_weight`) und Graph-Informationen (Edges, Centrality) zu einem erklärbaren Score kombiniert.
**Ziel:**
Aufbau eines hybriden Retrievers, der Semantik, Typwissen und Graph-Informationen kombiniert.
**Umfang:**
- Retriever-Modul (`app/core/retriever.py`):
- Vektorsuche über `*_chunks`,
- Zusammenführung von Chunk-Treffern mit Note-Metadaten,
- Aufbau eines Subgraphen (Nachbarn über Edges, Centrality-Berechnung).
- Scoring-Formel:
semantic_score
retriever_weight
edge_bonus
centrality_bonus
- Konfiguration über `config/retriever.yaml` (Gewichte, Parameter). :contentReference[oaicite:28]{index=28}
- FastAPI-Endpoint `/query` mit Rückgabe:
- Trefferliste,
- Teil-Scores,
- Begründung (inkl. Edge-Kontext).
**Aufwand / Komplexität:**
- Aufwand: Hoch
- Komplexität: Hoch
**Erreichte Ergebnisse / Funktionsumfang:**
- Hybrides Scoring-Modell mit konfigurierbaren Gewichten (`semantic_weight`, `edge_weight`, `centrality_weight`).
- Nutzung von `retriever_weight` aus `types.yaml` in Score-Berechnung.
- Graph-boni aus echten Edges (explizit, Inline, Typ-Defaults, Strukturkanten).
- Funktionsfähiger `/query`-Endpoint mit Testcases (inkl. Relations-Showcase-Vault).
- Basis für spätere Self-Tuning-Mechanismen (Logging von Scores, Konfiguration in `retriever.yaml`).
**DoD:**
- `/query` liefert nachvollziehbare Ergebnisse mit sichtbarem Einfluss von:
- Typprioritäten,
- Edge-Struktur,
- Centrality.
- Scoring ist rein konfigurierbar (Konfig-Change → Score-Veränderung ohne Code-Änderung).
**Erreichte Ergebnisse:**
- Hybrides Scoring-Modell (Semantic + Edge + Centrality).
- Konfiguration über `retriever.yaml`.
- `/query` Endpoint aktiv.
---
### WP-04b – Explanation Layer (geplant)
### WP-04b – Explanation Layer ("Why-Layer") (abgeschlossen)
**Phase:** B
**Status:** 🟡 geplant
**Phase:** B
**Status:** 🟢 abgeschlossen (Neu)
**Ziel:**
Treffererklärungen liefern, die für dich (Mindmaster) und spätere Nutzer verständlich sind (Why-Layer).
**Ziel:**
Treffererklärungen liefern, die verständlich machen, warum ein Ergebnis gewählt wurde.
**Umfang:**
- Erklärungsschicht über dem Retriever:
- Aufschlüsselung des Scores pro Treffer,
- Ketten von Edges (Pfade) als Begründungsgraph,
- Markierung relevanter Chunks / Notizen.
- Darstellung von:
- verwendeten Typen,
- Edges und deren `rule_id` / `confidence`,
- Centrality-Beiträgen.
**Aufwand / Komplexität:**
- Aufwand: Mittel
- Komplexität: Hoch
**DoD (Zielbild):**
- API-Endpoint (z. B. `/query/explain`), der eine strukturierte Erklärung in JSON liefert.
- Mindestens ein Beispiel, in dem Score-Änderung nachvollziehbar auf Policies/Edges zurückgeführt werden kann.
**Erreichte Ergebnisse:**
- **DTO-Erweiterung:** `QueryHit` enthält `explanation`, `breakdown` und `reason`.
- **Logic:** Graph-Adapter unterstützt `incoming_edges` (Reverse Lookup) für Authority-Erklärungen.
- **Output:** `/query` Endpoint liefert auf Wunsch (`explain: true`) menschenlesbare Begründungen ("Verweist auf...").
---
### WP-04c – Feedback Logging & Bewertungsdaten (geplant)
### WP-04c – Feedback Logging & Bewertungsdaten (abgeschlossen)
**Phase:** B
**Status:** 🟡 geplant
**Phase:** B
**Status:** 🟢 abgeschlossen (Neu)
**Ziel:**
Grundlage für Self-Tuning schaffen, indem Queries, Antworten und Bewertungen systematisch protokolliert werden.
**Ziel:**
Grundlage für Self-Tuning schaffen durch systematisches Logging.
**Umfang:**
- Logging von:
- Query-Texten,
- verwendeten Policies/Config-Versionen,
- Trefferlisten (Scores, Edges),
- Feedback (z. B. „hilfreich“, „irrelevant“, „falsch“).
- Persistente Speicherung (z. B. in einer separaten Sammlung oder Datei-basiert).
- Bereitstellung von Auswertungs-Skripten (Statistiken, Ranking-Qualität).
**Aufwand / Komplexität:**
- Aufwand: Mittel
- Komplexität: Mittel/Hoch
**DoD (Zielbild):**
- Vollständiger Feedback-Trail für ausgewählte Test-Sessions.
- Exportfähige Datenbasis zur späteren Optimierung der Retriever-Parameter.
**Erreichte Ergebnisse:**
- **Data Flywheel:** Logging von Queries und User-Feedback in lokalen JSONL-Dateien.
- **Search Log:** Speichert Query + Score-Snapshot in `data/logs/search_history.jsonl`.
- **Feedback Log:** Speichert User-Ratings in `data/logs/feedback.jsonl`.
- **Traceability:** Durchgängige `query_id` von Request bis Feedback.
---
### WP-05 – Persönlichkeitsmodell (geplant)
### WP-05 – Persönlichkeitsmodell & RAG-Chat (Startbereit)
**Phase:** C
**Status:** 🟡 geplant
**Phase:** C
**Status:** 🟡 geplant (Nächster Schritt)
**Ziel:**
Aufbau eines expliziten Persönlichkeitsmodells, das Werte, Prinzipien, prägende Erfahrungen und wiederkehrende Entscheidungsstrategien abbildet.
**Ziel:**
Aufbau eines RAG-Systems, das nicht nur sucht, sondern in natürlicher Sprache antwortet und dabei eine definierte Persönlichkeit (Werte, Prinzipien) einnimmt.
**Umfang:**
**Umfang:**
- **Config:** `config/prompts.yaml` für System-Prompts, Werte und RAG-Templates.
- **Service:** `llm_service.py` für Text-Generierung (Ollama-Anbindung).
- **Router:** `/chat` Endpoint (Kontext-Assembly -> Prompt -> LLM).
- **Persönlichkeit:** Definition von "Mindnet" als KI-Zwilling (Stil, Haltung).
- Identifikation und Typisierung relevanter Notes:
- `value`, `principle`, `life_event`, `milestone`, `decision`.
- Aufbau eines Modells, das:
- typische Begründungsmuster erkennt,
- Wertprioritäten identifiziert,
- langfristig in Scoring & Antwort-Formulierung einfließt.
**Aufwand / Komplexität:**
- Aufwand: Mittel
- Komplexität: Mittel
**DoD (Zielbild):**
- Dokumentiertes Persönlichkeitsmodell (z. B. YAML/Markdown), das konkrete Wert-/Prinzipien-Strukturen beschreibt.
- Basis-Integration in den Retriever (z. B. Wert-Bezüge in Explanation-Layer).
**Aufwand / Komplexität:**
- Aufwand: Mittel
- Komplexität: Mittel
---
### WP-06 – Decision Engine (geplant)
**Phase:** C
**Status:** 🟡 geplant
**Phase:** C
**Status:** 🟡 geplant
**Ziel:**
Entscheidungsunterstützung auf Basis von Wissen, Persönlichkeit und Zielen – inklusive nachvollziehbarer Begründung.
**Ziel:**
Entscheidungsunterstützung auf Basis von Wissen, Persönlichkeit und Zielen – inklusive nachvollziehbarer Begründung.
**Umfang:**
**Umfang:**
- Identifikation typischer Entscheidungssituationen.
- Integration von fachlichem Wissen, Erfahrungen und Persönlichkeitsmodell.
- Ableitung von Entscheidungs-Templates / Heuristiken.
- Identifikation typischer Entscheidungssituationen (z. B. beruflich, familiär, gesundheitlich).
- Integration von:
- fachlichem Wissen,
- Erfahrungen (Vergangenheitsentscheidungen),
- Persönlichkeitsmodell.
- Ableitung von Entscheidungs-Templates / Heuristiken.
**Aufwand / Komplexität:**
- Aufwand: Mittel
- Komplexität: Hoch
**DoD (Zielbild):**
- Prototypischer „Decision-Assistant“, der für definierte Szenarien begründete Empfehlungen gibt.
- Erklärungen referenzieren konkrete Notes/Edges.
**Aufwand / Komplexität:**
- Aufwand: Mittel
- Komplexität: Hoch
---
### WP-07 – Interview-Assistent (geplant)
**Phase:** C
**Status:** 🟡 geplant
**Phase:** C
**Status:** 🟡 geplant
**Ziel:**
Dialogbasierter Erfassungs-Assistent, der strukturierte Interviews führt und daraus konsistente Markdown-Notizen generiert.
**Ziel:**
Dialogbasierter Erfassungs-Assistent, der strukturierte Interviews führt und daraus konsistente Markdown-Notizen generiert.
**Umfang:**
**Umfang:**
- Design von Interview-Flows.
- Konvertierung von Dialogtranskripten in typisierte Notes.
- Design von Interview-Flows (z. B. für Lebensereignisse, Projekte, Werte-Workshops).
- Konvertierung von Dialogtranskripten in typisierte Notes (inkl. Typ, Tags, erste Edges).
- Integration mit Vault-Struktur (Ablagepfade, Namenskonventionen).
**Aufwand / Komplexität:**
- Aufwand: Niedrig/Mittel
- Komplexität: Mittel
**DoD (Zielbild):**
- Mindestens ein produktionsnaher Flow (z. B. „Erzähle mir von einem prägenden Ereignis“).
- Automatische Erzeugung von Markdown-Notizen, die vom Importer direkt verarbeitet werden können.
**Aufwand / Komplexität:**
- Aufwand: Niedrig/Mittel
- Komplexität: Mittel
---
### WP-08 – Self-Tuning v1/v2 (geplant)
**Phase:** B/C
**Status:** 🟡 geplant
**Phase:** B/C
**Status:** 🟡 geplant
**Ziel:**
Aufbau eines Self-Tuning-Mechanismus, der auf Basis von Feedback-Daten Vorschläge für Retriever- und Policy-Anpassungen macht.
**Ziel:**
Aufbau eines Self-Tuning-Mechanismus, der auf Basis von Feedback-Daten (WP-04c) Vorschläge für Retriever- und Policy-Anpassungen macht.
**Umfang:**
**Umfang:**
- Auswertung der JSONL-Feedback-Daten.
- Regel-basierte Anpassungs-Vorschläge für `retriever.yaml` und Typ-Prioritäten.
- Auswertung der Feedback-Daten (WP-04c).
- Regel-basierte Anpassungs-Vorschläge:
- Gewichte in `retriever.yaml`,
- Typ-Prioritäten,
- Edge-Provenance-Gewichte.
- Optionale halbautomatische Übernahme (Freigabe durch Mindmaster).
**Aufwand / Komplexität:**
- Aufwand: Hoch
- Komplexität: Hoch
**DoD (Zielbild):**
- Mindestens ein in der Praxis getesteter Tuning-Zyklus:
- Feedback sammeln,
- Vorschlag generieren,
- Anpassung vornehmen,
- Qualitätsgewinn nachweisen.
**Aufwand / Komplexität:**
- Aufwand: Hoch
- Komplexität: Hoch
---
### WP-09 – Vault-Onboarding & Migration (geplant)
**Phase:** B
**Status:** 🟡 geplant
**Phase:** B
**Status:** 🟡 geplant
**Ziel:**
Sicherstellen, dass bestehende und neue Obsidian-Vaults schrittweise in mindnet integriert werden können – ohne Massenumbau.
**Ziel:**
Sicherstellen, dass bestehende und neue Obsidian-Vaults schrittweise in mindnet integriert werden können – ohne Massenumbau.
**Umfang:**
**Umfang:**
- Tools zur Analyse des Vault-Status.
- Empfehlungen für minimale Anpassungen.
- Tools/Guides für:
- Analyse des Vault-Status (Typen, Edges, Lücken),
- Empfehlungen für minimale Anpassungen (z. B. Typ-Setzung, Basis-Tags),
- optional automatisierte Ergänzung von Properties (mit Freigabe).
- Unterstützung eines „wachsenden Systems“:
- erste Notizen liefern sofort Mehrwert im Retriever,
- später können Typen und Edges ergänzt werden, ohne alte Notizen zu brechen.
**Aufwand / Komplexität:**
- Aufwand: Mittel
- Komplexität: Niedrig/Mittel
**DoD (Zielbild):**
- Dokumentierter Onboarding-Prozess für Produkt-Vault.
- Mindestens ein erfolgreicher Durchlauf mit deinem realen Vault (Pilot).
**Aufwand / Komplexität:**
- Aufwand: Mittel
- Komplexität: Niedrig/Mittel
---
### WP-10 – Chat-Interface & Writeback (geplant)
**Phase:** D
**Status:** 🟡 geplant
**Phase:** D
**Status:** 🟡 geplant
**Ziel:**
Chat-basierter mindnet-Agent, der sowohl Fragen beantwortet als auch neue Notizen erzeugen/aktualisieren kann (Writeback Richtung Vault).
**Ziel:**
Chat-basierter mindnet-Agent, der sowohl Fragen beantwortet als auch neue Notizen erzeugen/aktualisieren kann (Writeback Richtung Vault).
**Umfang:**
**Umfang:**
- Chat-Frontend.
- Funktionen für Q&A sowie Vorschlag neuer Notes/Edges.
- Chat-Frontend (z. B. in deiner bestehenden LLM-Umgebung).
- Anbindung an:
- `/query` (Retriever),
- MCP-Tools (WP-13),
- Import-/Export-Routinen.
- Funktionen:
- Antworten aus mindnet-Wissen,
- Vorschlag neuer Notes/Edges,
- optionales Schreiben ins Vault (Markdown-Erzeugung, Rewriting nur mit Freigabe).
**Aufwand / Komplexität:**
- Aufwand: Hoch
- Komplexität: Hoch
**DoD (Zielbild):**
- Du kannst im Chat:
- Fragen an dein Wissensnetz stellen,
- neue Gedanken/Erinnerungen erfassen,
- Vorschläge für Ablage & Vernetzung als Markdown-Notizen erhalten.
**Aufwand / Komplexität:**
- Aufwand: Hoch
- Komplexität: Hoch
---
### WP-11 – Knowledge-Builder & Vernetzungs-Assistent (geplant)
**Phase:** D
**Status:** 🟡 geplant
**Phase:** D
**Status:** 🟡 geplant
**Ziel:**
Assistent, der manuell erstellte oder importierte Notizen analysiert und Vorschläge für Typen, Edges und Einordnung macht.
**Ziel:**
Assistent, der manuell erstellte oder importierte Notizen analysiert und Vorschläge für Typen, Edges und Einordnung macht.
**Umfang:**
- Analyse neuer/aktualisierter Notes:
- mögliche Typen,
- passende Tags,
- potenzielle Relationen zu bestehenden Notes.
- Vorschläge:
- Inline-Relationen,
- Wikilinks,
- Typ-Zuweisung.
- Optional: Generierung konkreter Patch-Vorschläge für Markdown-Dateien (Diff-basiert).
**Aufwand / Komplexität:**
- Aufwand: Hoch
- Komplexität: Hoch
**DoD (Zielbild):**
- Mindestens ein produktionsnaher Workflow, bei dem ein neuer Eintrag:
- erstellt wird,
- analysiert wird,
- Vernetzungs-Vorschläge liefert,
- und nach Freigabe in den Vault zurückgeschrieben wird.
**Aufwand / Komplexität:**
- Aufwand: Hoch
- Komplexität: Hoch
---
### WP-12 – Knowledge Rewriter (Soft Mode, geplant)
**Phase:** C/D
**Status:** 🟡 geplant
**Phase:** C/D
**Status:** 🟡 geplant
**Ziel:**
Optionaler Assistent, der vorhandene Notes „aufräumt“, zusammenfasst oder reorganisiert – ausschließlich mit expliziter Freigabe. :contentReference[oaicite:31]{index=31}
**Ziel:**
Optionaler Assistent, der vorhandene Notes „aufräumt“, zusammenfasst oder reorganisiert – ausschließlich mit expliziter Freigabe.
**Einschränkungen:**
- Änderungen an Markdown-Dateien nur nach Freigabe.
- Kein „silent overwrite“ existierender Inhalte.
**Aufwand / Komplexität:**
- Aufwand: Niedrig/Mittel
- Komplexität: Mittel
**DoD (Zielbild):**
- Rewriter generiert Vorschläge (neue Versionen) inklusive Diffs.
- Nach Freigabe werden Notes konsistent aktualisiert:
- IDs, Edges und Typen bleiben konsistent oder werden sauber mitaktualisiert.
**Aufwand / Komplexität:**
- Aufwand: Niedrig/Mittel
- Komplexität: Mittel
---
### WP-13 – MCP-Integration & Agenten-Layer (geplant)
**Phase:** D
**Status:** 🟡 geplant
**Phase:** D
**Status:** 🟡 geplant
**Ziel:**
mindnet als MCP-Server bereitstellen, damit Agenten/LLMs standardisierte Tools nutzen können (z. B. in deiner n8n- und LLM-Umgebung).
**Ziel:**
mindnet als MCP-Server bereitstellen, damit Agenten/LLMs standardisierte Tools nutzen können.
**Umfang:**
**Umfang:**
- MCP-Server mit Tools (`mindnet_query`, `mindnet_explain`, etc.).
- MCP-Server mit Tools wie:
- `mindnet_query`,
- `mindnet_subgraph`,
- `mindnet_store_note`,
- `mindnet_explain`.
- Sichere Konfiguration (lokal, authentifiziert, logging-fähig).
**Aufwand / Komplexität:**
- Aufwand: Mittel
- Komplexität: Mittel
**DoD (Zielbild):**
- Lokaler MCP-Server läuft und ist aus einem LLM-Client nutzbar.
- Tools liefern konsistente Ergebnisse (aligned mit FastAPI-Endpoints).
- Sicherheits- und Loggingkonzept dokumentiert.
**Aufwand / Komplexität:**
- Aufwand: Mittel
- Komplexität: Mittel
---
### WP-14 – Review / Refactoring / Dokumentation (geplant)
**Phase:** E
**Status:** 🟡 geplant
**Phase:** E
**Status:** 🟡 geplant
**Ziel:**
Aufräumen, dokumentieren, stabilisieren – insbesondere für Onboarding Dritter und Langfrist-Betrieb.
**Ziel:**
Aufräumen, dokumentieren, stabilisieren – insbesondere für Onboarding Dritter und Langfrist-Betrieb.
**Deliverables (Beispiele):**
- konsolidierte technische Architektur (`mindnet_technical_architecture.md`),
- fachliche Architektur (`mindnet_functional_architecture.md`),
- Identity-Modell (`identity_model.md`),
- API-Spezifikation (`api_spec.md`),
- MCP-Integration (`mcp_integration.md`),
- aktualisiertes Handbuch (`Handbuch.md`).
**Aufwand / Komplexität:**
- Aufwand: Mittel
- Komplexität: Niedrig/Mittel
**DoD (Zielbild):**
- Aktueller Stand ist sauber dokumentiert.
- Wichtige Designentscheidungen sind nachvollziehbar festgehalten.
- Onboarding einer dritten Person (z. B. Entwickler:in) ist mit Dokumentation möglich.
**Aufwand / Komplexität:**
- Aufwand: Mittel
- Komplexität: Niedrig/Mittel
---
@@ -690,13 +442,11 @@ Aufräumen, dokumentieren, stabilisieren – insbesondere für Onboarding Dritte
WP03 → WP09
WP01/WP03 → WP10 → WP11 → WP12
WP03/WP04 → WP13
Alles → WP14
Diese Struktur bleibt gegenüber v2.1 unverändert, ist aber jetzt explizit an den bereits implementierten Stand (WP-03, WP-04a) angepasst.
Alles → WP14
---
## 8. Laufzeit- & Komplexitätsindikatoren (unverändert, ergänzt)
## 8. Laufzeit- & Komplexitätsindikatoren (aktualisiert)
| WP | Aufwand | Komplexität |
|-------|----------------|------------------|
@@ -711,9 +461,7 @@ Diese Struktur bleibt gegenüber v2.1 unverändert, ist aber jetzt explizit an d
| WP11 | Hoch | Hoch |
| WP12 | Niedrig/Mittel | Mittel |
| WP13 | Mittel | Mittel |
| WP14 | Mittel | Niedrig/Mittel | :contentReference[oaicite:35]{index=35}
Für WP01–WP04a gilt: Aufwand/Komplexität wie in v2.1; Status jetzt explizit „abgeschlossen“ mit beschriebenem Funktionsumfang.
| WP14 | Mittel | Niedrig/Mittel |
---
@@ -725,8 +473,8 @@ Für WP01–WP04a gilt: Aufwand/Komplexität wie in v2.1; Status jetzt explizit
| WP02 | 🟢 |
| WP03 | 🟢 |
| WP04a | 🟢 |
| WP04b | 🟡 |
| WP04c | 🟡 |
| WP04b | 🟢 |
| WP04c | 🟢 |
| WP05 | 🟡 |
| WP06 | 🟡 |
| WP07 | 🟡 |
@@ -736,37 +484,30 @@ Für WP01–WP04a gilt: Aufwand/Komplexität wie in v2.1; Status jetzt explizit
| WP11 | 🟡 |
| WP12 | 🟡 |
| WP13 | 🟡 |
| WP14 | 🟡 | :contentReference[oaicite:36]{index=36}
| WP14 | 🟡 |
---
## 10. Governance & Versionierung
- Versionierung über Gitea (Branches, Tags, Releases).
- Jede wesentliche Änderung an Architektur/Schema:
- eigener Commit,
- kurze Doku (z. B. in `CHANGELOG.md` oder Projekt-Notiz).
- Jedes Workpackage erhält ein eigenes Chat-Fenster mit dediziertem Prompt (WP-Hand-Over).
- Programmleitung verantwortet:
- Konsistenz von Fach- und Technikdokumenten,
- Abhängigkeiten und Priorisierung,
- Freigabe von Meilensteinen,
- Sicherstellung, dass Änderungen mit dem langfristigen Ziel (KI-Zwilling) vereinbar sind.
- Versionierung über Gitea (Branches, Tags, Releases).
- Feature-Branch Workflow mit "Sync First" Strategie.
- Jede wesentliche Änderung an Architektur/Schema erhält einen eigenen Commit.
- Jedes Workpackage erhält ein eigenes Chat-Fenster mit dediziertem Prompt (WP-Hand-Over).
- Programmleitung verantwortet Konsistenz und Priorisierung.
---
## 11. Executive Summary (unverändert, präzisiert)
## 11. Executive Summary
mindnet v2.2 ist so aufgesetzt, dass:
- du **schrittweise** Wissen erfassen kannst (Obsidian + Chat + später Interview-Assistent),
- die Struktur **mitwächst**, ohne Retro-Massenarbeit im Vault,
- ein **hybrider Retriever** qualitativ hochwertige, erklärbare Antworten liefert,
- ein **Self-Healing- und Self-Tuning-Mechanismus** vorbereitet ist, der auf Feedback aufsetzt,
- ein **Persönlichkeitsmodell** und eine **Decision Engine** entstehen,
- langfristig ein **KI-Zwilling** aufgebaut wird, der deine Werte, Erfahrungen und Denkweise spiegelt,
- die technische Architektur (FastAPI, Qdrant, YAML-Policies, MCP-Integration) lokal, nachvollziehbar und erweiterbar bleibt.
Dieser Programmplan bildet die konsolidierte Grundlage (v2.2) für alle weiteren Arbeiten.
Er integriert die bisherigen Ergebnisse (WP-01 bis WP-04a) und die zusätzlichen Anforderungen aus der späteren Planung (Feedback-basiertes Tuning, wachsendes System, Chat-/Interview-Eingabe, Vault-Writeback) in ein einheitliches, versionierbares Dokument.
- du **schrittweise** Wissen erfassen kannst (Obsidian + Chat + später Interview-Assistent),
- die Struktur **mitwächst**, ohne Retro-Massenarbeit im Vault,
- ein **hybrider Retriever** qualitativ hochwertige, erklärbare Antworten liefert,
- ein **Self-Healing- und Self-Tuning-Mechanismus** vorbereitet ist (durch WP-04c Feedback-Daten),
- ein **Persönlichkeitsmodell** und eine **Decision Engine** entstehen,
- langfristig ein **KI-Zwilling** aufgebaut wird, der deine Werte, Erfahrungen und Denkweise spiegelt,
- die technische Architektur (FastAPI, Qdrant, YAML-Policies, MCP-Integration) lokal, nachvollziehbar und erweiterbar bleibt.
Dieser Programmplan bildet die konsolidierte Grundlage (v2.2.1) für alle weiteren Arbeiten.
+9 -9
View File
@@ -1,43 +1,43 @@
"""
app/main.py — mindnet API bootstrap (WP-04 Hooks)
Version: 0.4.2 • Stand: 2025-10-07
app/main.py — mindnet API bootstrap
"""
from __future__ import annotations
from fastapi import FastAPI
from .config import get_settings
from .routers.embed_router import router as embed_router
from .routers.qdrant_router import router as qdrant_router
# WP-04 Router:
from .routers.query import router as query_router
from .routers.graph import router as graph_router
from .routers.tools import router as tools_router
# Optional:
# NEU: Feedback Router
from .routers.feedback import router as feedback_router
try:
from .routers.admin import router as admin_router
except Exception:
admin_router = None
def create_app() -> FastAPI:
app = FastAPI(title="mindnet API", version="0.1.0")
app = FastAPI(title="mindnet API", version="0.4.3") # Version bump
s = get_settings()
@app.get("/healthz")
def healthz():
return {"status": "ok", "qdrant": s.QDRANT_URL, "prefix": s.COLLECTION_PREFIX}
# Bestehende Router (unverändert)
app.include_router(embed_router)
app.include_router(qdrant_router)
# WP-04 Endpunkte
app.include_router(query_router, prefix="/query", tags=["query"])
app.include_router(graph_router, prefix="/graph", tags=["graph"])
app.include_router(tools_router, prefix="/tools", tags=["tools"])
# NEU:
app.include_router(feedback_router, prefix="/feedback", tags=["feedback"])
if admin_router:
app.include_router(admin_router, prefix="/admin", tags=["admin"])
return app
app = create_app()
app = create_app()
+32 -30
View File
@@ -4,28 +4,26 @@ app/models/dto.py — Pydantic-Modelle (DTOs) für WP-04 Endpunkte
Zweck:
Laufzeit-Modelle für FastAPI (Requests/Responses), getrennt von JSON-Schemas.
Deckt die Graph-/Retriever-Endpunkte ab.
Enthält Erweiterungen für WP-04b (Explanation Layer).
Enthält Erweiterungen für WP-04b (Explanation Layer) und WP-04c (Feedback).
Kompatibilität:
Python 3.12+, Pydantic 2.x, FastAPI 0.110+
Version:
0.2.0 (Update für WP-04b Explanation Layer)
0.3.0 (Update für WP-04c Feedback)
Stand:
2025-12-07
Bezug:
- schemas/*.json (Speicherschema für Notes/Chunks/Edges)
- WP-04 API-Design (Query- und Graph-Endpunkte)
Nutzung:
from app.models.dto import QueryRequest, QueryResponse, GraphResponse
"""
from __future__ import annotations
from pydantic import BaseModel, Field
from typing import List, Literal, Optional, Dict, Any
import uuid
EdgeKind = Literal["references", "references_at", "backlink", "next", "prev", "belongs_to", "depends_on", "related_to", "similar_to"]
# --- Basis-DTOs ---
class NodeDTO(BaseModel):
"""Darstellung eines Knotens (Note oder Chunk) im API-Graph."""
id: str
@@ -51,12 +49,14 @@ class EdgeDTO(BaseModel):
direction: Literal["out", "in", "undirected"] = "out"
# --- Request Models ---
class QueryRequest(BaseModel):
"""
Request für /query:
- mode: 'semantic' | 'edge' | 'hybrid'
- query: (optional) Freitext; Embedding wird später angebunden
- query_vector: (optional) direkter Vektor (384d) für Quick-Tests ohne Embedding
- query: (optional) Freitext
- query_vector: (optional) direkter Vektor
- explain: (optional) Fordert detaillierte Erklärungen an (WP-04b)
"""
mode: Literal["semantic", "edge", "hybrid"] = "hybrid"
@@ -65,24 +65,29 @@ class QueryRequest(BaseModel):
top_k: int = 10
expand: Dict = {"depth": 1, "edge_types": ["references", "belongs_to", "prev", "next", "depends_on", "related_to"]}
filters: Optional[Dict] = None
# Flags zur Steuerung der Rückgabe
ret: Dict = {"with_paths": True, "with_notes": True, "with_chunks": True}
# WP-04b: Soll eine Erklärung generiert werden?
explain: bool = False
class FeedbackRequest(BaseModel):
"""
User-Feedback zu einem spezifischen Treffer (WP-04c).
"""
query_id: str = Field(..., description="ID der ursprünglichen Suche")
node_id: str = Field(..., description="ID des bewerteten Treffers")
score: int = Field(..., ge=0, le=1, description="1 (Positiv) oder 0 (Negativ/Irrelevant)")
comment: Optional[str] = None
# --- WP-04b Explanation Models ---
class ScoreBreakdown(BaseModel):
"""
Aufschlüsselung der Score-Komponenten.
Zeigt die gewichteten Beiträge zum Total Score.
"""
"""Aufschlüsselung der Score-Komponenten."""
semantic_contribution: float = Field(..., description="W_sem * semantic_score * weight")
edge_contribution: float = Field(..., description="W_edge * edge_bonus")
centrality_contribution: float = Field(..., description="W_cent * centrality_bonus")
# Rohwerte für Transparenz
# Rohwerte
raw_semantic: float
raw_edge_bonus: float
raw_centrality: float
@@ -90,10 +95,7 @@ class ScoreBreakdown(BaseModel):
class Reason(BaseModel):
"""
Ein semantischer Grund für das Ranking.
z.B. 'Verlinkt von Projekt X', 'Hohe Textähnlichkeit'.
"""
"""Ein semantischer Grund für das Ranking."""
kind: Literal["semantic", "edge", "type", "centrality"]
message: str
score_impact: Optional[float] = None
@@ -101,24 +103,20 @@ class Reason(BaseModel):
class Explanation(BaseModel):
"""
Container für alle Erklärungsdaten eines Treffers.
"""
"""Container für alle Erklärungsdaten eines Treffers."""
breakdown: ScoreBreakdown
reasons: List[Reason]
# Optional: Pfade im Graphen, die zu diesem Treffer geführt haben
related_edges: Optional[List[EdgeDTO]] = None
# --- End Explanation Models ---
# --- Response Models ---
class QueryHit(BaseModel):
"""Einzelnes Trefferobjekt für /query."""
node_id: str
note_id: Optional[str]
# Flache Scores (Kompatibilität WP-04a)
# Flache Scores
semantic_score: float
edge_bonus: float
centrality_bonus: float
@@ -127,19 +125,23 @@ class QueryHit(BaseModel):
paths: Optional[List[List[Dict]]] = None
source: Optional[Dict] = None
# WP-04b: Erklärungsobjekt (nur gefüllt, wenn explain=True)
# WP-04b: Erklärungsobjekt
explanation: Optional[Explanation] = None
class QueryResponse(BaseModel):
"""Antwortstruktur für /query (Liste von Treffern + Telemetrie)."""
"""
Antwortstruktur für /query (Liste von Treffern + Telemetrie).
Enthält query_id für Traceability (WP-04c).
"""
query_id: str = Field(default_factory=lambda: str(uuid.uuid4()))
results: List[QueryHit]
used_mode: str
latency_ms: int
class GraphResponse(BaseModel):
"""Antwortstruktur für /graph/{note_id} (Nachbarschaft)."""
"""Antwortstruktur für /graph/{note_id}."""
center_note_id: str
nodes: List[NodeDTO]
edges: List[EdgeDTO]
+20
View File
@@ -0,0 +1,20 @@
"""
app/routers/feedback.py
Endpunkt für User-Feedback (WP-04c).
"""
from fastapi import APIRouter, HTTPException
from app.models.dto import FeedbackRequest
from app.services.feedback_service import log_feedback
router = APIRouter()
@router.post("", status_code=201)
def post_feedback(fb: FeedbackRequest):
"""
Nimmt Feedback entgegen (z.B. Daumen hoch für einen Treffer).
"""
try:
log_feedback(fb)
return {"status": "recorded", "query_id": fb.query_id}
except Exception as e:
raise HTTPException(status_code=500, detail=str(e))
+14 -7
View File
@@ -15,24 +15,31 @@ Bezug:
Nutzung:
app.include_router(query.router, prefix="/query", tags=["query"])
Änderungsverlauf:
0.2.0 (2025-12-07) - Update für WP04c Feedback
0.1.0 (2025-10-07) – Erstanlage.
"""
from __future__ import annotations
from fastapi import APIRouter, HTTPException
from fastapi import APIRouter, HTTPException, BackgroundTasks
from app.models.dto import QueryRequest, QueryResponse
from app.core.retriever import hybrid_retrieve, semantic_retrieve
# NEU:
from app.services.feedback_service import log_search
router = APIRouter()
@router.post("", response_model=QueryResponse)
def post_query(req: QueryRequest) -> QueryResponse:
def post_query(req: QueryRequest, background_tasks: BackgroundTasks) -> QueryResponse:
try:
if req.mode == "semantic":
return semantic_retrieve(req)
# default: hybrid
return hybrid_retrieve(req)
res = semantic_retrieve(req)
else:
res = hybrid_retrieve(req)
# WP-04c: Logging im Hintergrund (bremst Antwort nicht)
background_tasks.add_task(log_search, req, res)
return res
except ValueError as e:
raise HTTPException(status_code=400, detail=str(e))
except Exception as e:
raise HTTPException(status_code=500, detail=f"query failed: {e}")
raise HTTPException(status_code=500, detail=f"query failed: {e}")
+80
View File
@@ -0,0 +1,80 @@
"""
app/services/feedback_service.py
Service zum Loggen von Suchanfragen und Feedback (WP-04c).
Speichert Daten als JSONL für späteres Self-Tuning (WP-08).
"""
import json
import os
import time
from pathlib import Path
from typing import Dict, Any, List
from app.models.dto import QueryRequest, QueryResponse, FeedbackRequest
# Pfad für Logs (lokal auf dem Beelink/PC)
LOG_DIR = Path("data/logs")
SEARCH_LOG_FILE = LOG_DIR / "search_history.jsonl"
FEEDBACK_LOG_FILE = LOG_DIR / "feedback.jsonl"
def _ensure_log_dir():
if not LOG_DIR.exists():
os.makedirs(LOG_DIR, exist_ok=True)
def log_search(req: QueryRequest, res: QueryResponse):
"""
Speichert den "Snapshot" der Suche.
WICHTIG: Wir speichern die Scores (Breakdown), damit wir später wissen,
warum das System so entschieden hat.
"""
_ensure_log_dir()
# Wir reduzieren die Datenmenge etwas (z.B. keine vollen Texte)
hits_summary = []
for hit in res.results:
# Falls Explanation an war, speichern wir den Breakdown, sonst die Scores
breakdown = None
if hit.explanation and hit.explanation.breakdown:
breakdown = hit.explanation.breakdown.model_dump()
hits_summary.append({
"node_id": hit.node_id,
"note_id": hit.note_id,
"total_score": hit.total_score,
"breakdown": breakdown, # Wichtig für Training!
"rank_semantic": hit.semantic_score,
"rank_edge": hit.edge_bonus
})
entry = {
"timestamp": time.time(),
"query_id": res.query_id,
"query_text": req.query,
"mode": req.mode,
"top_k": req.top_k,
"hits": hits_summary
}
try:
with open(SEARCH_LOG_FILE, "a", encoding="utf-8") as f:
f.write(json.dumps(entry, ensure_ascii=False) + "\n")
except Exception as e:
print(f"ERROR logging search: {e}")
def log_feedback(fb: FeedbackRequest):
"""
Speichert das User-Feedback.
"""
_ensure_log_dir()
entry = {
"timestamp": time.time(),
"query_id": fb.query_id,
"node_id": fb.node_id,
"score": fb.score,
"comment": fb.comment
}
try:
with open(FEEDBACK_LOG_FILE, "a", encoding="utf-8") as f:
f.write(json.dumps(entry, ensure_ascii=False) + "\n")
except Exception as e:
print(f"ERROR logging feedback: {e}")
+62 -82
View File
@@ -1,7 +1,7 @@
# Mindnet v2.2 – Admin Guide
**Datei:** `docs/mindnet_admin_guide_v2.2.md`
**Stand:** 2025-12-07
**Status:** **FINAL** (Konsolidiert WP02–WP04a)
**Stand:** 2025-12-08
**Status:** **FINAL** (Konsolidiert WP02–WP04c)
**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.
@@ -11,15 +11,13 @@
## 1. Zielgruppe & Scope
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:
* Die Verfügbarkeit der Dienste (Qdrant, API).
* Die Datensicherheit (Backups).
* Die Integrität des Imports (Sync zwischen Vault und DB).
* Die Governance (wer darf zugreifen).
Wir unterscheiden strikt zwischen:
* **Production (Port 8001):** Stabiler `main` Branch.
* **Development (Port 8002):** Experimentelle Feature-Branches.
---
## 2. Initial Setup
## 2. Initial Setup & Installation
### 2.1 Systemvoraussetzungen
* **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).
* Disk: SSD empfohlen für Qdrant-Performance.
### 2.2 Installation
### 2.2 Installation (Code)
# 1. Repository klonen
git clone <repo-url> /opt/mindnet
cd /opt/mindnet
git clone <repo-url> /home/llmadmin/mindnet
cd /home/llmadmin/mindnet
# 2. Umgebung einrichten
python3 -m venv .venv
@@ -40,7 +38,7 @@ Als Admin bist du verantwortlich für:
pip install -r requirements.txt
# 3. Verzeichnisse anlegen
mkdir -p logs qdrant_storage
mkdir -p logs qdrant_storage data/logs
### 2.3 Qdrant Setup (Docker)
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
# Mindnet Core Settings
COLLECTION_PREFIX="mindnet"
COLLECTION_PREFIX="mindnet" # "mindnet_dev" für Dev-Umgebung
MINDNET_TYPES_FILE="./config/types.yaml"
MINDNET_RETRIEVER_CONFIG="./config/retriever.yaml"
# Embedding Settings (Default: all-MiniLM-L6-v2)
VECTOR_DIM=384
# Import-Strategie (Performance vs. Gründlichkeit)
# Body: Nur Textänderungen triggern Update (Standard)
# Full: Auch Frontmatter-Änderungen (z.B. Tags) triggern Update
# Import-Strategie
MINDNET_HASH_COMPARE="Body"
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.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):**
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.
* `--sync-deletes`: Wichtig, um Notizen aus dem Index zu entfernen, die im Vault gelöscht wurden.
* `--purge-before-upsert`: Entfernt Fragmente gelöschter Textstellen.
* `--sync-deletes`: Entfernt Notizen aus dem Index, die im Vault gelöscht wurden.
### 3.2 Health-Checks
Prüfe regelmäßig, ob die API und der Retriever korrekt arbeiten.
**API Status Check:**
curl -f http://localhost:8000/health || echo "API Down"
**System Status:**
sudo systemctl status mindnet-prod
**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
python3 scripts/test_retriever_smoke.py --mode hybrid --url http://localhost:8001/query
### 3.3 Umgang mit Fehlern im Importer
Falls der Importer abbricht oder Dateien ignoriert:
### 3.3 Logs & Monitoring
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.
python3 -m scripts.diagnose_changed --vault ./vault --note-id "MeineProblemnote"
2. **Schema-Validierung:** Prüfe mit `scripts/payload_dryrun.py`, ob eine spezifische Datei das JSON-Schema verletzt.
3. **Erzwingen:** Nutze `touch <filename>` im Vault, um den Zeitstempel zu aktualisieren und Hash-Checks zu umgehen, oder nutze `--force` (Vorsicht: Performance).
* **Technische Fehler (Live):**
`journalctl -u mindnet-prod -f`
* **Fachliche Logs (Data Flywheel):**
`/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
Wenn neue Versionen der Mindnet-Software (z.B. Schema-Updates in WP05) ausgerollt werden:
Wenn neue Versionen ausgerollt werden (Deployment):
1. **Code aktualisieren:**
cd /home/llmadmin/mindnet
git pull origin main
2. **Dependencies prüfen:**
source .venv/bin/activate
pip install -r requirements.txt
3. **Schema-Migration:**
Mindnet nutzt oft "Rebuild" statt komplexer Migrationen, da der Vault die Source of Truth ist.
* Prüfe `CHANGELOG.md` auf "Breaking Changes".
* Bei Schema-Änderungen: Führe einen **Full Rebuild** durch (siehe 5.3).
3. **Dienst neustarten (Zwingend!):**
sudo systemctl restart mindnet-prod
4. **Schema-Migration (falls nötig):**
Bei Änderungen an `types.yaml` oder Index-Strukturen:
python3 -m scripts.import_markdown ... --apply
---
## 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)
Der Markdown-Vault ist die **Single Source of Truth**. Er muss klassisch gesichert werden.
* **Strategie:** Git-Repository, rsync auf NAS, oder Cloud-Sync.
* **Restore:** Einfach Dateien zurückkopieren und Import laufen lassen.
Der Markdown-Vault ist die **Single Source of Truth**. Er muss klassisch gesichert werden (Git/NAS).
### 5.2 Qdrant-Snapshots (Priorität 2)
Für schnelle Wiederherstellung des Suchindex ohne stundenlangen Re-Import (bei großen Vaults).
**Backup erstellen (Volume-Level):**
Für schnelle Wiederherstellung des Suchindex.
docker stop mindnet_qdrant
tar -czf qdrant_backup_$(date +%F).tar.gz ./qdrant_storage
docker start mindnet_qdrant
**Alternativ: API-Snapshot (Zero-Downtime):**
Siehe Qdrant Dokumentation (Snapshot API).
**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.3 Log-Daten (Priorität 3)
Sichere den Ordner `data/logs/`. Verlust dieser Daten bedeutet, dass das System vergisst, welche Antworten Nutzer hilfreich fanden.
### 5.4 Notfall-Wiederherstellung (Rebuild)
Wenn die Datenbank korrupt ist:
# 1. DB komplett leeren (Wipe)
python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet" --yes
# 2. Alles neu importieren
python3 -m scripts.import_markdown --vault /path/to/vault --prefix "mindnet" --apply
---
## 6. Monitoring & Logging
## 6. Governance & Sicherheit
### 6.1 Log-Quellen
* **Importer:** Schreibt nach STDOUT/STDERR. Sollte im Cronjob in eine Datei (z.B. `/var/log/mindnet_import.log`) umgeleitet werden.
* **API (Uvicorn):** Standard Access-Logs.
* **Qdrant:** Docker Logs (`docker logs mindnet_qdrant`).
### 6.1 Zugriffsschutz
Mindnet hat aktuell **keine integrierte Authentifizierung**.
* **API:** Muss hinter einem Reverse Proxy (Nginx, Traefik) mit Basic Auth laufen, wenn sie im Netzwerk freigegeben wird.
* **Qdrant:** Sollte via Firewall (ufw) auf `127.0.0.1` beschränkt sein.
### 6.2 Wichtige Metriken (Log-Parsing)
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
### 6.2 Typen-Governance
Änderungen an der `types.yaml` (z.B. neue Gewichte) wirken global.
* **Prozess:** Änderungen sollten getestet werden (Smoke-Test), bevor sie produktiv gehen.
* **Review:** Prüfe, ob neue Typen (`type: xyz`) auch Chunking-Profile haben, sonst fallen sie auf Defaults zurück.
* **Prozess:** Änderungen sollten getestet werden (Smoke-Test), bevor sie produktiv gehen.
+19 -23
View File
@@ -1,7 +1,7 @@
# Mindnet v2.2 – Appendices & Referenzen
**Datei:** `docs/mindnet_appendices_v2.2.md`
**Stand:** 2025-12-07
**Status:** **FINAL** (Konsolidiert aus WP01–WP04a)
**Stand:** 2025-12-08
**Status:** **FINAL**
**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.
@@ -10,7 +10,7 @@
## 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 |
| :--- | :--- | :--- | :--- | :--- |
@@ -28,7 +28,7 @@ Diese Tabelle zeigt die Standard-Konfiguration der `types.yaml` (Stand v2.2). Di
## 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 |
| :--- | :--- | :--- | :--- |
@@ -46,7 +46,7 @@ Referenz aller implementierten Kantenarten (`kind`). Die Spalte "Herkunft" zeigt
## 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`)
{
@@ -101,31 +101,27 @@ Diese Variablen steuern das Verhalten der Skripte und Container.
| `MINDNET_RETRIEVER_CONFIG`| `config/retriever.yaml`| Pfad zur Scoring-Konfiguration. |
| `MINDNET_HASH_COMPARE` | `Body` | Vergleichsmodus für Import (`Body`, `Frontmatter`, `Full`). |
| `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). |
---
## Anhang E: Glossar
Zentrale Begriffe des Mindnet-Systems.
* **Callout-Edge:** Eine Kante, die durch einen Obsidian-Callout Block (`> [!edge]`) definiert wird. Dient für Listen.
* **Chunking:** Prozess des Zerlegens einer Notiz in kleinere, semantische Einheiten (Chunks).
* **Confidence:** Ein Wert (0.0-1.0), der angibt, wie sicher eine Kante ist. Explizite User-Eingaben haben 1.0, Defaults ~0.7.
* **Idempotenz:** Eigenschaft des Importers, bei mehrfacher Ausführung das exakt gleiche Ergebnis zu liefern (keine Duplikate).
* **Inline-Edge:** Eine Kante, die im Fließtext mittels `[[rel:type Ziel]]` definiert wird. Semantisch sehr stark.
* **Provenance:** Die Herkunft einer Information (z.B. "explicit" vs "rule" vs "inference").
* **Retriever:** Die Komponente (FastAPI), die Suchanfragen beantwortet und Scores berechnet.
* **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.
* **Callout-Edge:** Kante via `> [!edge]`.
* **Chunking:** Zerlegung von Notizen in kleinere Einheiten.
* **Confidence:** Vertrauenswürdigkeit einer Kante (0.0-1.0).
* **Explanation Layer:** Komponente, die Scores und Graphen als Begründung liefert.
* **Feedback Loop:** Prozess des Loggens und Auswertens von User-Reaktionen.
* **Idempotenz:** Mehrfache Ausführung liefert gleiches Ergebnis.
* **Inline-Edge:** Kante via `[[rel:type Ziel]]`.
* **Retriever:** Suchmaschine (FastAPI).
* **Vault:** Ordner mit Markdown-Dateien.
---
## 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 |
| :--- | :--- | :--- | :--- |
@@ -133,8 +129,8 @@ Status der Module gemäß Programmplan.
| **WP02** | Chunking Strategy | 🟢 Live | Profilbasiertes Chunking aktiv. |
| **WP03** | Edge Logic / Import | 🟢 Live | Neue Importer-Pipeline mit Provenance. |
| **WP04a**| Retriever Scoring | 🟢 Live | Hybrider Score (Semantik + Graph). |
| **WP04b**| Explanation Layer | 🟡 In Arbeit | API liefert Pfade, UI fehlt noch. |
| **WP04c**| Feedback Loop | 🔴 Geplant | Logging von User-Feedback. |
| **WP05** | Virtual Schema | 🟡 Teilw. | `types.yaml` aktiv, ACL fehlt. |
| **WP04b**| Explanation Layer | 🟢 Live | API liefert Reasons & Breakdown. |
| **WP04c**| Feedback Loop | 🟢 Live | Logging (JSONL) & Traceability aktiv. |
| **WP05** | Persönlichkeit / Chat | 🟡 Geplant | Nächster Schritt (RAG). |
| **WP06** | Self-Healing | 🔴 Geplant | Auto-Fixing von Broken Links. |
| **WP08** | Self-Tuning | 🔴 Geplant | Auto-Adjustment der Gewichte. |
+62 -45
View File
@@ -1,6 +1,6 @@
# Mindnet v2.2 – Entwickler-Workflow
**Datei:** `DEV_WORKFLOW.md`
**Stand:** 2025-12-07
**Stand:** 2025-12-07 (Aktualisiert: Sync-First Strategie)
Dieses Handbuch beschreibt den Entwicklungszyklus zwischen **Windows PC** (IDE), **Raspberry Pi** (Gitea) und **Beelink** (Runtime/Server).
@@ -22,34 +22,33 @@ Dieses Handbuch beschreibt den Entwicklungszyklus zwischen **Windows PC** (IDE),
Hier erstellst du die neue Funktion in einer sicheren Umgebung.
1. **Sicherstellen, dass Git bereit ist:**
* Öffne VS Code.
* Unten links in der blauen Leiste sollte der aktuelle Branch stehen (z.B. `main`).
1. **Basis aktualisieren (WICHTIG!):**
Bevor du startest, muss dein lokales `main` auf dem Stand des Servers sein.
* Klicke unten links auf den aktuellen Branch und wähle **`main`**.
* Klicke links im Menü "Source Control" auf die **drei Punkte (...)** -> **Pull** (oder das Synchronisieren-Symbol).
* *Erst jetzt hast du alle Dateien!*
2. **Branch erstellen (WICHTIG):**
* Klicke unten links auf den Branch-Namen (z.B. `main`).
* Wähle im Menü oben `+ Create new branch...`.
2. **Branch erstellen:**
* Klicke wieder unten links auf `main`.
* Wähle `+ Create new branch...`.
* Gib den Namen ein: `feature/was-ich-tue` (z.B. `feature/wp04b-explanation`).
* Drücke **Enter**.
3. **Sicherheits-Check:**
* Schau unten links: Steht dort jetzt `feature/wp04b-explanation`?
* **Nur wenn dort dein Feature-Branch steht, darfst du Code ändern!** Alles, was du jetzt speicherst, landet in diesem Branch.
* Steht unten links jetzt dein Feature-Branch? **Nur dann darfst du Code ändern!**
4. **Coden:**
* Nimm deine Änderungen vor.
5. **Sichern & Hochladen:**
* Klicke links auf das **Source Control** Icon (Gabel-Symbol).
* Gib eine Nachricht ein: "feat: Add explanation layer logic".
* Klicke auf **Commit**.
* Klicke auf **Publish Branch** (oder "Sync Changes"), um den Branch zum Raspberry Pi (Gitea) zu senden.
* **Source Control** Icon (Gabel-Symbol) -> Nachricht eingeben -> **Commit**.
* **Publish Branch** (oder "Sync Changes"), um den Branch zum Raspberry Pi (Gitea) zu senden.
---
### Phase 2: Testen (Beelink / `mindnet_dev`)
Hier prüfst du, ob dein neuer Code auf dem echten Server läuft, ohne die Produktion zu stören.
Hier prüfst du, ob dein neuer Code auf dem echten Server läuft.
1. **Einloggen:**
`ssh user@<BEELINK-IP>`
@@ -60,34 +59,34 @@ Hier prüfst du, ob dein neuer Code auf dem echten Server läuft, ohne die Produ
3. **Code holen:**
```bash
git fetch
# Tipp: 'git branch -r' zeigt alle verfügbaren Branches an
git checkout feature/wp04b-explanation
git pull
```
4. **Umgebung aktivieren (Venv):**
Damit Python die installierten Bibliotheken findet, musst du das Virtual Environment aktivieren:
4. **Umgebung vorbereiten:**
```bash
source .venv/bin/activate
pip install -r requirements.txt # Nur nötig bei neuen Paketen
```
*(Dein Prompt sollte jetzt `(.venv) user@...` zeigen)*
5. **Abhängigkeiten prüfen:**
*(Nur nötig, wenn du neue Libraries in `requirements.txt` eingetragen hast)*
5. **Test-Server neustarten (WICHTIG):**
Falls noch ein alter Prozess läuft, musst du ihn beenden.
* Drücke `Strg + C` falls der Server noch im Vordergrund läuft.
* Oder nutze `pkill -f "uvicorn app.main:app"`.
Starten auf **Port 8002**:
```bash
pip install -r requirements.txt
uvicorn app.main:app --host 0.0.0.0 --port 8002 --env-file .env
```
6. **Test-Server starten:**
**WICHTIG:** Nutze Port **8002** und das Dev-Prefix!
Stelle sicher, dass in `~/mindnet_dev/.env` steht: `COLLECTION_PREFIX="mindnet_dev"`.
6. **Validieren:**
Führe deine Tests in einem **zweiten Terminal** aus:
```bash
uvicorn app.main:app --host 0.0.0.0 --port 8002
# Beispiel für Smoke-Test gegen Dev-Port
python3 tests/test_explanation_smoke.py --url http://localhost:8002/query
```
7. **Testen:**
Prüfe deine Änderung (z.B. Browser auf `http://<BEELINK-IP>:8002/docs` oder Smoke-Test Skript).
---
### Phase 3: Release (Gitea / Raspberry Pi)
@@ -95,9 +94,8 @@ Hier prüfst du, ob dein neuer Code auf dem echten Server läuft, ohne die Produ
Wenn der Test auf Port 8002 erfolgreich war:
1. Öffne Gitea im Browser.
2. Du solltest einen Hinweis sehen "feature/... had recent pushes".
3. Erstelle einen **Pull Request** (Dein Branch -> `main`).
4. **Merge** den Pull Request.
2. Erstelle einen **Pull Request** (Dein Branch -> `main`).
3. **Merge** den Pull Request.
---
@@ -117,27 +115,46 @@ Jetzt bringen wir die Änderung in das Live-System (Port 8001).
---
### Phase 5: Aufräumen (Optional aber empfohlen)
Damit das Chaos nicht wächst, löschen wir den fertigen Branch.
1. **Gitea:** Im Pull Request auf "Delete Branch" klicken.
2. **Beelink (Dev):**
```bash
cd ~/mindnet_dev
git checkout main
git pull
git branch -d feature/wp04b-explanation
```
3. **VS Code:**
* Auf `main` wechseln.
* Sync drücken (um Löschung vom Server zu erfahren).
* `F1` -> `Git: Delete Branch` -> Branch auswählen.
---
## 3. Cheat Sheet: Die wichtigsten Befehle
| Wo? | Befehl | Was tut es? |
| :--- | :--- | :--- |
| **VS Code** | `Klick auf Branch-Namen` | Branch erstellen oder wechseln. |
| **VS Code** | `Sync Changes` | Lädt Code zu Gitea hoch. |
| **Beelink** | `cd ~/mindnet_dev` | Gehe in den Test-Ordner. |
| **VS Code** | `Sync (auf main)` | **WICHTIG:** Holt neuesten Code vom Server. |
| **VS Code** | `Klick auf Branch` | Branch erstellen oder wechseln. |
| **Beelink** | `source .venv/bin/activate` | **Aktiviert Python-Umgebung.** |
| **Beelink** | `git fetch` | "Gibt es neue Branches auf Gitea?" |
| **Beelink** | `git checkout <name>` | Wechsle auf einen anderen Branch. |
| **Beelink** | `git pull` | Hol den neuesten Stand des aktuellen Branches. |
| **Beelink** | `git fetch` | Aktualisiert Remote-Branches. |
| **Beelink** | `git checkout <name>` | Wechsle Branch. |
| **Beelink** | `git pull` | Aktualisiere aktuellen Branch. |
| **Beelink** | `uvicorn ... --port 8002` | Startet Test-Server (Dev). |
---
## 4. Sicherheitsregeln
## 4. Troubleshooting
1. **Niemals** in `~/mindnet` (Prod-Ordner) experimentieren oder `git checkout` machen. Dieser Ordner bleibt immer auf `main`.
2. **Niemals** beide Umgebungen auf denselben `COLLECTION_PREFIX` zeigen lassen.
* Prod `.env`: `COLLECTION_PREFIX="mindnet"`
* Dev `.env`: `COLLECTION_PREFIX="mindnet_dev"`
3. **Port-Disziplin:**
* **PROD:** Port 8001
* **DEV:** Port 8002
**"Hilfe, in meinem neuen Branch fehlen Dateien!"**
Das passiert, wenn du beim Erstellen nicht aktuell warst.
* **Lösung:**
```bash
# In VS Code Terminal:
git checkout feature/mein-kaputter-branch
git merge main
# (Das holt die fehlenden Dateien aus main nach)
+46 -17
View File
@@ -1,9 +1,9 @@
# Mindnet v2.2 – Fachliche Architektur
**Datei:** `docs/mindnet_functional_architecture_v2.2.md`
**Stand:** 2025-12-07
**Status:** **FINAL** (Integrierter Stand WP01–WP04a)
**Stand:** 2025-12-08
**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)
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
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).
* **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.
### 5.2 Erklärbarkeit (Explainability)
Der Retriever liefert **Begründungspfade**. Er gibt nicht nur Text zurück, sondern:
* `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").
### 5.2 Erklärbarkeit (Explainability) – WP04b
Der Retriever ist keine Blackbox mehr. Er liefert auf Wunsch (`explain=True`) eine strukturierte Begründung (`Explanation`-Objekt).
**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:
- **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.
- `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**:
- **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).
- 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)**
# 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).
- **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`.
- Kantenbildung (V2-Logic): `app/core/derive_edges.py`.
- 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
**Datei:** `docs/mindnet_technical_architecture_v2.2.md`
**Stand:** 2025-12-07
**Status:** **FINAL** (Integrierter Stand WP01–WP04a)
**Quellen:** `mindnet_technical_architecture.md`, `chunking_strategy.md`, `Handbuch.md`, `wp04_retriever_scoring.md`, `Überarbeitungshinweise_WP03.md`, `Überarbeitungshinweise_WP04.md`.
**Stand:** 2025-12-08
**Status:** **FINAL** (Integrierter Stand WP01–WP04c)
**Quellen:** `mindnet_technical_architecture.md`, `chunking_strategy.md`, `Handbuch.md`, `wp04_retriever_scoring.md`.
> **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.
@@ -15,8 +15,10 @@
Mindnet ist ein **persönliches Wissensnetz**. Technisch bedeutet das:
1. **Source:** Markdown-Notizen in einem Vault (Obsidian-kompatibel).
2. **Pipeline:** Ein Python-Importer transformiert diese in **Notes**, **Chunks** und **Edges**.
3. **Storage:** Speicherung in **Qdrant** (Vektor-Datenbank) in drei getrennten Collections.
4. **Service:** Eine FastAPI-Anwendung stellt Endpunkte für **Semantische** und **Hybride Suche** bereit.
3. **Storage:**
* **Qdrant:** Vektor-Datenbank für Graph und Semantik (Collections: notes, chunks, edges).
* **Local Files (JSONL):** Append-Only Logs für Feedback und Search-History (Data Flywheel).
4. **Service:** Eine FastAPI-Anwendung stellt Endpunkte für **Semantische** und **Hybride Suche** sowie **Feedback** bereit.
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)
│ │ ├── edges.py # Edge-Datenstrukturen
│ │ ├── derive_edges.py # Logik der Kantenableitung (WP03)
│ │ └── retriever.py # Scoring & Graph-Expansion (WP04)
│ ├── models/ # Pydantic DTOs (QueryRequest, etc.)
│ └── routers/ # API Routen
│ │ ├── graph_adapter.py # Subgraph & Reverse-Lookup (WP04b)
│ │ └── retriever.py # Scoring, Expansion & Explanation (WP04a/b)
│ ├── 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/
│ ├── types.yaml # Typ-Definitionen (Import-Zeit)
│ └── retriever.yaml # Scoring-Gewichte (Laufzeit)
├── data/
│ └── logs/ # Lokale JSONL-Logs (WP04c)
├── scripts/
│ ├── import_markdown.py # Haupt-Importer CLI
│ ├── 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 |
| `fulltext` | Text | Gesamter Inhalt (für Export/Rekonstruktion). | Body |
### 2.2 Chunks Collection (`<prefix>_chunks`)
Die atomaren Sucheinheiten.
* **Zweck:** Vektorsuche (Embeddings), Granulares Ergebnis.
@@ -88,8 +97,6 @@ Die atomaren Sucheinheiten.
| `neighbors_prev` | List[Str] | ID des Vorgänger-Chunks. |
| `neighbors_next` | List[Str] | ID des Nachfolger-Chunks. |
### 2.3 Edges Collection (`<prefix>_edges`)
Gerichtete Kanten. Massiv erweitert in WP03 für Provenienz-Tracking.
* **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` |
| `confidence` | Float | Vertrauenswürdigkeit (0.0-1.0). | 1.0, 0.95, 0.7 |
---
## 3. Konfiguration
@@ -185,12 +190,44 @@ $$
* $B_{cent}$: Centrality-Bonus (im lokalen Subgraphen).
* **Gewichte ($W$):** Stammen aus `retriever.yaml`.
### 5.3 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`-Graphen im Speicher, auf dem Boni berechnet werden.
### 5.3 Explanation Layer (WP04b)
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.
@@ -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:**
* `rel: similar_to [[A]] [[B]]` wird aktuell parser-seitig nicht unterstützt.
+65
View File
@@ -0,0 +1,65 @@
import requests
import json
import sys
import time
# Konfiguration
BASE_URL = "http://localhost:8001"
QUERY_URL = f"{BASE_URL}/query"
FEEDBACK_URL = f"{BASE_URL}/feedback"
def run_test():
print(f"--- 1. Sende Suchanfrage an {QUERY_URL} ---")
query_payload = {
"query": "mindnet architecture",
"mode": "hybrid",
"top_k": 2,
"explain": True # Wir wollen auch Breakdown loggen
}
try:
r = requests.post(QUERY_URL, json=query_payload)
r.raise_for_status()
res_data = r.json()
except Exception as e:
print(f"ERROR bei Suche: {e}")
sys.exit(1)
query_id = res_data.get("query_id")
results = res_data.get("results", [])
if not query_id:
print("FAIL: Keine query_id in der Antwort erhalten!")
sys.exit(1)
if not results:
print("WARNUNG: Keine Treffer gefunden, Test kann Feedback nur simuliert senden.")
target_node_id = "fake-node-id"
else:
target_node_id = results[0].get("node_id")
print(f"SUCCESS: Suche OK. Erhaltene Query-ID: {query_id}")
print(f"Target Node für Feedback: {target_node_id}")
# Kurze Pause, damit Background-Task Zeit hat zu schreiben (nur für Log-Check relevant)
time.sleep(0.5)
print(f"\n--- 2. Sende Feedback an {FEEDBACK_URL} ---")
feedback_payload = {
"query_id": query_id,
"node_id": target_node_id,
"score": 1,
"comment": "Automatisierter Smoke-Test: Dieser Treffer war hilfreich."
}
try:
r_fb = requests.post(FEEDBACK_URL, json=feedback_payload)
r_fb.raise_for_status()
print(f"SUCCESS: Feedback gesendet. Status: {r_fb.status_code}")
print(f"Response: {r_fb.json()}")
except Exception as e:
print(f"ERROR bei Feedback: {e}")
sys.exit(1)
if __name__ == "__main__":
run_test()