Compare commits
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
fbaa07ba88 | ||
|
|
d0ecc5316f | ||
|
|
9ee39277ae | ||
|
|
9d3fd21c88 | ||
|
|
d7217672a3 | ||
|
|
e39b685b1e | ||
|
|
5b9399361d | ||
|
|
7631b93900 | ||
|
|
f98eb8fc16 | ||
|
|
ab60106fb9 | ||
|
|
caab41a760 | ||
|
|
78d8ab11ed | ||
|
|
d49da1b5fe |
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.
|
||||||
@@ -1,68 +1,68 @@
|
|||||||
# mindnet v2.2 — Programmplan
|
# mindnet v2.2 — Programmplan
|
||||||
**Version:** 2.2
|
**Version:** 2.2.1 (Post-WP04 Update)
|
||||||
**Stand:** 2025-12-06
|
**Stand:** 2025-12-07
|
||||||
**Status:** Aktiv (Fortschreibung von v2.1)
|
**Status:** Aktiv
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 1. Programmauftrag
|
## 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,
|
- Wissen, Erfahrungen, Werte und Entscheidungen speichert,
|
||||||
- diese Informationen semantisch verknüpft und rekonstruierbar macht,
|
- diese Informationen semantisch verknüpft und rekonstruierbar macht,
|
||||||
- einen KI-Zwilling aufbaut, der ähnlich argumentiert, entscheidet und reflektiert wie du,
|
- einen KI-Zwilling aufbaut, der ähnlich argumentiert, entscheidet und reflektiert wie du,
|
||||||
- über mehrere Kanäle gefüttert wird:
|
- über mehrere Kanäle gefüttert wird:
|
||||||
- Obsidian-Markdown (primäre Quelle),
|
- Obsidian-Markdown (primäre Quelle),
|
||||||
- Chat-basierter Agent (mindnet-Assistent),
|
- Chat-basierter Agent (mindnet-Assistent),
|
||||||
- später: Interview-Assistent (strukturierte Dialogerfassung),
|
- später: Interview-Assistent (strukturierte Dialogerfassung),
|
||||||
- automatisch neue Zusammenhänge erkennt und vernetzt (Edges, Typen, Hinweise),
|
- automatisch neue Zusammenhänge erkennt und vernetzt (Edges, Typen, Hinweise),
|
||||||
- sich durch Rückmeldungen (Feedback) selbst verbessert (Self-Tuning).
|
- 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,
|
- dich versteht,
|
||||||
- deine Denkweise reflektiert,
|
- deine Denkweise reflektiert,
|
||||||
- deine Werte kennt und verwendet,
|
- deine Werte kennt und verwendet,
|
||||||
- Entscheidungen begründen kann („Warum?“),
|
- Entscheidungen begründen kann („Warum?“),
|
||||||
- Erinnerungen einordnet,
|
- Erinnerungen einordnet,
|
||||||
- und für deine Nachkommen als dialogfähiger Gesprächspartner zur Verfügung steht.
|
- 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:
|
mindnet ist **kein statisches Wissensarchiv**, sondern ein **lebendes, lernendes Gedächtnismodell** mit Fokus auf:
|
||||||
|
|
||||||
- persönliche Perspektive,
|
- persönliche Perspektive,
|
||||||
- erklärbare Begründungspfade,
|
- erklärbare Begründungspfade,
|
||||||
- kontinuierliche Erweiterbarkeit,
|
- kontinuierliche Erweiterbarkeit,
|
||||||
- robuste technische Basis (lokal, nachvollziehbar, versioniert).
|
- robuste technische Basis (lokal, nachvollziehbar, versioniert).
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 2. Vision
|
## 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:
|
Kernprinzipien der Vision:
|
||||||
|
|
||||||
- **Erklärbarkeit:**
|
- **Erklärbarkeit:**
|
||||||
Jede Antwort muss über Edges, Scores, Werte-Bezüge und Herkunftsnotizen begründbar sein.
|
Jede Antwort muss über Edges, Scores, Werte-Bezüge und Herkunftsnotizen begründbar sein.
|
||||||
|
|
||||||
- **Wachstum:**
|
- **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.
|
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):**
|
- **Flexibilität (Late Binding):**
|
||||||
Semantik wird überwiegend in Konfiguration (z. B. `types.yaml`, Policies, Knowledge-Design) festgelegt, nicht in jeder einzelnen Markdown-Datei.
|
Semantik wird überwiegend in Konfiguration (z. B. `types.yaml`, Policies, Knowledge-Design) festgelegt, nicht in jeder einzelnen Markdown-Datei.
|
||||||
|
|
||||||
- **Autonomie & Self-Healing:**
|
- **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.
|
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:**
|
- **Lernen & Self-Tuning:**
|
||||||
Feedback zu Antworten (gut/schlecht, relevant/nicht relevant) fließt in Score-Gewichte, Policies und ggf. Edge-Struktur ein.
|
Feedback zu Antworten (gut/schlecht, relevant/nicht relevant) fließt in Score-Gewichte, Policies und ggf. Edge-Struktur ein.
|
||||||
|
|
||||||
- **Persönlichkeit:**
|
- **Persönlichkeit:**
|
||||||
Entscheidungen werden wert- und erfahrungsbasiert begründet; mittelfristig entsteht ein Persönlichkeitsmodell, das den KI-Zwilling trägt.
|
Entscheidungen werden wert- und erfahrungsbasiert begründet; mittelfristig entsteht ein Persönlichkeitsmodell, das den KI-Zwilling trägt.
|
||||||
|
|
||||||
- **Incremental Growth:**
|
- **Incremental Growth:**
|
||||||
Das System muss mit wenigen, heterogenen Notizen starten und sich fortlaufend verdichten können – ohne Retro-Massenmigrationen im Vault.
|
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)
|
### 3.1 Kurzfristig (nächste Monate)
|
||||||
|
|
||||||
- Automatische Sammlung von Wissen aus Markdown-Vault und ersten Chat-Dialogen.
|
- Automatische Sammlung von Wissen aus Markdown-Vault und ersten Chat-Dialogen.
|
||||||
- Aufbau eines stabilen Graph-Speichers in Qdrant (`*_notes`, `*_chunks`, `*_edges`).
|
- Aufbau eines stabilen Graph-Speichers in Qdrant (`*_notes`, `*_chunks`, `*_edges`).
|
||||||
- Semantischer und graphbasierter Retriever (WP-04a abgeschlossen, WP-04b/04c in Vorbereitung).
|
- 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:
|
- Automatisierte Erkennung von Beziehungen:
|
||||||
- Wikilinks, Inline-Relationen, Callout-Edges, Typ-Defaults.
|
- Wikilinks, Inline-Relationen, Callout-Edges, Typ-Defaults.
|
||||||
- Schrittweises Lernen über Feedback (Score-Tuning, noch „manuell“ konfiguriert). :contentReference[oaicite:8]{index=8}
|
- Schrittweises Lernen über Feedback (Score-Tuning, noch „manuell“ konfiguriert).
|
||||||
- „Mitwachsendes“ Schema ohne Obsidian-Umstrukturierungen:
|
- „Mitwachsendes“ Schema ohne Obsidian-Umstrukturierungen:
|
||||||
- Neues Wissen kann sofort erfasst werden,
|
- 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:
|
- Technische Basis für die späteren Agenten und den KI-Zwilling:
|
||||||
- lokaler FastAPI-Dienst,
|
- lokaler FastAPI-Dienst,
|
||||||
- Qdrant als Graph-Backend,
|
- Qdrant als Graph-Backend,
|
||||||
- konfigurierbarer Retriever (`retriever.yaml`).
|
- konfigurierbarer Retriever (`retriever.yaml`).
|
||||||
|
|
||||||
### 3.2 Mittelfristig
|
### 3.2 Mittelfristig
|
||||||
|
|
||||||
- Persönlichkeitsprofil wird stabil erkannt und für Antworten genutzt (Typen, Werte-Notizen, Entscheidungsnotizen).
|
- Persönlichkeitsprofil wird stabil erkannt und für Antworten genutzt (Typen, Werte-Notizen, Entscheidungsnotizen).
|
||||||
- Why-Layer: KI-Assistenz für Entscheidungen mit nachvollziehbarer Argumentation.
|
- **RAG-Chat:** KI antwortet in natürlicher Sprache auf Basis von Wissen und Persönlichkeit (WP-05).
|
||||||
- Interview-Assistent erstellt neue Notes automatisch (strukturierte Dialoge → Markdown).
|
- Why-Layer: KI-Assistenz für Entscheidungen mit nachvollziehbarer Argumentation.
|
||||||
- mindnet erzeugt Vorschläge für neue Notes & Edges und bietet einen „Vernetzungs-Assistenten“ für manuell angelegte Notizen.
|
- Interview-Assistent erstellt neue Notes automatisch (strukturierte Dialoge → Markdown).
|
||||||
- Agenten können über MCP-Tools (`mindnet_query`, `mindnet_subgraph`, `mindnet_store_note`, `mindnet_explain`) auf mindnet zugreifen.
|
- 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
|
### 3.3 Langfristig
|
||||||
|
|
||||||
- KI-Zwilling, der deinen Stil, deine Werte und deine typische Denkweise repräsentiert.
|
- 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).
|
- Weitgehend autonomes Self-Tuning der Wissensstruktur (auf Basis gespeicherter Feedback-Daten & Policies).
|
||||||
- Lebenslanges Gedächtnis, das
|
- Lebenslanges Gedächtnis, das
|
||||||
- konsistent bleibt,
|
- konsistent bleibt,
|
||||||
- wächst,
|
- wächst,
|
||||||
- sich weiterentwickelt,
|
- sich weiterentwickelt,
|
||||||
- und deine Geschichte für deine Nachkommen erzählbar und erlebbar macht.
|
- und deine Geschichte für deine Nachkommen erzählbar und erlebbar macht.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 4. Architekturprinzipien
|
## 4. Architekturprinzipien
|
||||||
|
|
||||||
Die folgenden Prinzipien steuern alle Workpackages und Entscheidungen:
|
Die folgenden Prinzipien steuern alle Workpackages und Entscheidungen:
|
||||||
|
|
||||||
1. **Late Binding (späte Semantik)**
|
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.
|
- 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.
|
- Erlaubt spätere Anpassungen ohne manuelle Massenänderungen.
|
||||||
|
|
||||||
2. **Virtual Schema Layer**
|
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`).
|
- 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).
|
- Markdown-Dateien benötigen nur minimale, robuste Angaben (Titel, Typ, optionale Properties).
|
||||||
|
|
||||||
3. **Self-Healing Graph**
|
3. **Self-Healing Graph**
|
||||||
- Der Graph wird regelmäßig analysiert (Edges, Centrality, fehlende Links).
|
- Der Graph wird regelmäßig analysiert (Edges, Centrality, fehlende Links).
|
||||||
- Automatisierte Jobs ergänzen fehlende Kanten (ähnliche Inhalte, typisierte Standardbeziehungen, Backlinks).
|
- Automatisierte Jobs ergänzen fehlende Kanten (ähnliche Inhalte, typisierte Standardbeziehungen, Backlinks).
|
||||||
|
|
||||||
4. **Deterministische IDs**
|
4. **Deterministische IDs**
|
||||||
- Notes, Chunks und Edges erhalten stabile IDs (z. B. UUIDv5, deterministische `note_id`/`chunk_id`/`edge_id`).
|
- 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).
|
- Der Graph ist jederzeit wiederaufbaubar (Import-Pipeline idempotent).
|
||||||
|
|
||||||
5. **Full Explainability**
|
5. **Full Explainability**
|
||||||
- Jeder Score, jede Beziehung, jeder Vorschlag muss über:
|
- Jeder Score, jede Beziehung, jeder Vorschlag muss über:
|
||||||
- Edges,
|
- Edges,
|
||||||
- Scoring-Komponenten (Semantik, Typ, Edge-Bonus, Centrality),
|
- 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**
|
6. **Persistence First**
|
||||||
- Obsidian bleibt die primäre Quelle der Wahrheit.
|
- 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).
|
- mindnet ergänzt, schlägt Änderungen vor, schreibt aber nur kontrolliert (z. B. über Rewriter oder Vernetzungs-Assistent mit Freigabe).
|
||||||
|
|
||||||
7. **Minimalinvasives Schreiben**
|
7. **Minimalinvasives Schreiben**
|
||||||
- Automatische Veränderungen an Markdown-Dateien erfolgen ausschließlich nach expliziter Zustimmung.
|
- Automatische Veränderungen an Markdown-Dateien erfolgen ausschließlich nach expliziter Zustimmung.
|
||||||
- Rewriter und Vernetzungs-Assistent arbeiten grundsätzlich im Vorschlagsmodus.
|
- Rewriter und Vernetzungs-Assistent arbeiten grundsätzlich im Vorschlagsmodus.
|
||||||
|
|
||||||
8. **Incremental Growth & Early Value**
|
8. **Incremental Growth & Early Value**
|
||||||
- Das System muss bereits mit wenigen Notizen und einem kleinen Vault sinnvolle Antworten liefern (Retrieval-MVP).
|
- 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.
|
- 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.
|
- Feedback-Mechanismen werden früh eingeführt, auch wenn sie anfangs noch nicht vollautomatisch ausgewertet werden.
|
||||||
|
|
||||||
9. **Observability & Testbarkeit**
|
9. **Observability & Testbarkeit**
|
||||||
- Jeder Importlauf, jede Retriever-Anfrage und jede Policy-Änderung soll prüfbar sein (Logs, Traces, Tests, Reports).
|
- 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 B – Semantik, Graph & Lernen
|
||||||
Phase C – Persönlichkeitsmodell & KI-Zwilling
|
Phase C – Persönlichkeitsmodell & KI-Zwilling
|
||||||
Phase D – Agenten, MCP & Interaktion
|
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
|
### Legende Aufwand / Komplexität
|
||||||
|
|
||||||
- Aufwand: Niedrig / Mittel / Hoch
|
- Aufwand: Niedrig / Mittel / Hoch
|
||||||
- Komplexität: 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)
|
### WP-01 – Wissensdesign (abgeschlossen)
|
||||||
|
|
||||||
**Phase:** A
|
**Phase:** A
|
||||||
**Status:** 🟢 abgeschlossen
|
**Status:** 🟢 abgeschlossen
|
||||||
|
|
||||||
**Ziel:**
|
**Ziel:**
|
||||||
Grundlegendes Schema für mindnet festlegen (`knowledge_design.md`), inkl.:
|
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.).
|
**Erreichte Ergebnisse:**
|
||||||
- Standard-Properties (Titel, Typ, Tags, Status, Zeitstempel, Referenzen, Policies).
|
- `knowledge_design.md` und `types.yaml` definieren die Zielarchitektur.
|
||||||
- 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.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### WP-02 – Chunking & Hash-Strategie (abgeschlossen)
|
### WP-02 – Chunking & Hash-Strategie (abgeschlossen)
|
||||||
|
|
||||||
**Phase:** A
|
**Phase:** A
|
||||||
**Status:** 🟢 abgeschlossen
|
**Status:** 🟢 abgeschlossen
|
||||||
|
|
||||||
**Ziel:**
|
**Ziel:**
|
||||||
Festlegen und implementieren einer robusten Chunking-Strategie und einer Hash-Logik zur Änderungserkennung.
|
Festlegen und implementieren einer robusten Chunking-Strategie und einer Hash-Logik zur Änderungserkennung.
|
||||||
|
|
||||||
**Umfang (fachlich & technisch):**
|
**Erreichte Ergebnisse:**
|
||||||
|
- Implementierte Chunker-Logik mit Overlap.
|
||||||
- Text in semantisch sinnvolle Chunks teilen (Heading-/Block-aware).
|
- Stabile Hash-Strategie zur sicheren Änderungserkennung.
|
||||||
- Parallelhaltung von:
|
|
||||||
- `text` (Chunk-Kern ohne Overlap),
|
|
||||||
- `window` (Chunk-Fenster mit Overlap für Embeddings).
|
|
||||||
- Hash-Modi zur Änderungserkennung (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 Änderungserkennung ohne Mass-Diffs bei Konfigurationswechsel.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### WP-03 – Import-Pipeline & Edge-System v2 (abgeschlossen)
|
### WP-03 – Import-Pipeline & Edge-System v2 (abgeschlossen)
|
||||||
|
|
||||||
**Phase:** A/B
|
**Phase:** A/B
|
||||||
**Status:** 🟢 abgeschlossen
|
**Status:** 🟢 abgeschlossen
|
||||||
|
|
||||||
**Ziel:**
|
**Ziel:**
|
||||||
Durchgängige Import-Pipeline von Markdown → Notes/Chunks/Edges in Qdrant mit deterministischen IDs, typbasierten Defaults und erklärbarem Edge-Modell.
|
Durchgängige Import-Pipeline von Markdown → Notes/Chunks/Edges in Qdrant mit deterministischen IDs.
|
||||||
|
|
||||||
**Umfang:**
|
**Erreichte Ergebnisse:**
|
||||||
|
- Vollständige E2E-Import-Pipeline.
|
||||||
- Parser (robust gegenüber Zeichensatzfehlern, Frontmatter/Body-Erkennung, Sonderfälle wie Silverbullet-Dateien).
|
- Vollständiges Edge-Modell (Strukturkanten, Wikilinks, Inline-Relationen).
|
||||||
- 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).
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### WP-04a – Retriever & Graph-Scoring (abgeschlossen)
|
### WP-04a – Retriever & Graph-Scoring (abgeschlossen)
|
||||||
|
|
||||||
**Phase:** B
|
**Phase:** B
|
||||||
**Status:** 🟢 abgeschlossen
|
**Status:** 🟢 abgeschlossen
|
||||||
|
|
||||||
**Ziel:**
|
**Ziel:**
|
||||||
Aufbau eines hybriden Retrievers, der Semantik (Embeddings), Typwissen (`retriever_weight`) und Graph-Informationen (Edges, Centrality) zu einem erklärbaren Score kombiniert.
|
Aufbau eines hybriden Retrievers, der Semantik, Typwissen und Graph-Informationen kombiniert.
|
||||||
|
|
||||||
**Umfang:**
|
**Erreichte Ergebnisse:**
|
||||||
|
- Hybrides Scoring-Modell (Semantic + Edge + Centrality).
|
||||||
- Retriever-Modul (`app/core/retriever.py`):
|
- Konfiguration über `retriever.yaml`.
|
||||||
- Vektorsuche über `*_chunks`,
|
- `/query` Endpoint aktiv.
|
||||||
- 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).
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### WP-04b – Explanation Layer (geplant)
|
### WP-04b – Explanation Layer ("Why-Layer") (abgeschlossen)
|
||||||
|
|
||||||
**Phase:** B
|
**Phase:** B
|
||||||
**Status:** 🟡 geplant
|
**Status:** 🟢 abgeschlossen (Neu)
|
||||||
|
|
||||||
**Ziel:**
|
**Ziel:**
|
||||||
Treffererklärungen liefern, die für dich (Mindmaster) und spätere Nutzer verständlich sind (Why-Layer).
|
Treffererklärungen liefern, die verständlich machen, warum ein Ergebnis gewählt wurde.
|
||||||
|
|
||||||
**Umfang:**
|
**Erreichte Ergebnisse:**
|
||||||
|
- **DTO-Erweiterung:** `QueryHit` enthält `explanation`, `breakdown` und `reason`.
|
||||||
- Erklärungsschicht über dem Retriever:
|
- **Logic:** Graph-Adapter unterstützt `incoming_edges` (Reverse Lookup) für Authority-Erklärungen.
|
||||||
- Aufschlüsselung des Scores pro Treffer,
|
- **Output:** `/query` Endpoint liefert auf Wunsch (`explain: true`) menschenlesbare Begründungen ("Verweist auf...").
|
||||||
- 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.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### WP-04c – Feedback Logging & Bewertungsdaten (geplant)
|
### WP-04c – Feedback Logging & Bewertungsdaten (abgeschlossen)
|
||||||
|
|
||||||
**Phase:** B
|
**Phase:** B
|
||||||
**Status:** 🟡 geplant
|
**Status:** 🟢 abgeschlossen (Neu)
|
||||||
|
|
||||||
**Ziel:**
|
**Ziel:**
|
||||||
Grundlage für Self-Tuning schaffen, indem Queries, Antworten und Bewertungen systematisch protokolliert werden.
|
Grundlage für Self-Tuning schaffen durch systematisches Logging.
|
||||||
|
|
||||||
**Umfang:**
|
**Erreichte Ergebnisse:**
|
||||||
|
- **Data Flywheel:** Logging von Queries und User-Feedback in lokalen JSONL-Dateien.
|
||||||
- Logging von:
|
- **Search Log:** Speichert Query + Score-Snapshot in `data/logs/search_history.jsonl`.
|
||||||
- Query-Texten,
|
- **Feedback Log:** Speichert User-Ratings in `data/logs/feedback.jsonl`.
|
||||||
- verwendeten Policies/Config-Versionen,
|
- **Traceability:** Durchgängige `query_id` von Request bis Feedback.
|
||||||
- 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.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### WP-05 – Persönlichkeitsmodell (geplant)
|
### WP-05 – Persönlichkeitsmodell & RAG-Chat (Startbereit)
|
||||||
|
|
||||||
**Phase:** C
|
**Phase:** C
|
||||||
**Status:** 🟡 geplant
|
**Status:** 🟡 geplant (Nächster Schritt)
|
||||||
|
|
||||||
**Ziel:**
|
**Ziel:**
|
||||||
Aufbau eines expliziten Persönlichkeitsmodells, das Werte, Prinzipien, prägende Erfahrungen und wiederkehrende Entscheidungsstrategien abbildet.
|
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:
|
**Aufwand / Komplexität:**
|
||||||
- `value`, `principle`, `life_event`, `milestone`, `decision`.
|
- Aufwand: Mittel
|
||||||
- Aufbau eines Modells, das:
|
- Komplexität: Mittel
|
||||||
- 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).
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### WP-06 – Decision Engine (geplant)
|
### WP-06 – Decision Engine (geplant)
|
||||||
|
|
||||||
**Phase:** C
|
**Phase:** C
|
||||||
**Status:** 🟡 geplant
|
**Status:** 🟡 geplant
|
||||||
|
|
||||||
**Ziel:**
|
**Ziel:**
|
||||||
Entscheidungsunterstützung auf Basis von Wissen, Persönlichkeit und Zielen – inklusive nachvollziehbarer Begründung.
|
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).
|
**Aufwand / Komplexität:**
|
||||||
- Integration von:
|
- Aufwand: Mittel
|
||||||
- fachlichem Wissen,
|
- Komplexität: Hoch
|
||||||
- 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.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### WP-07 – Interview-Assistent (geplant)
|
### WP-07 – Interview-Assistent (geplant)
|
||||||
|
|
||||||
**Phase:** C
|
**Phase:** C
|
||||||
**Status:** 🟡 geplant
|
**Status:** 🟡 geplant
|
||||||
|
|
||||||
**Ziel:**
|
**Ziel:**
|
||||||
Dialogbasierter Erfassungs-Assistent, der strukturierte Interviews führt und daraus konsistente Markdown-Notizen generiert.
|
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).
|
**Aufwand / Komplexität:**
|
||||||
- Konvertierung von Dialogtranskripten in typisierte Notes (inkl. Typ, Tags, erste Edges).
|
- Aufwand: Niedrig/Mittel
|
||||||
- Integration mit Vault-Struktur (Ablagepfade, Namenskonventionen).
|
- Komplexität: Mittel
|
||||||
|
|
||||||
**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.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### WP-08 – Self-Tuning v1/v2 (geplant)
|
### WP-08 – Self-Tuning v1/v2 (geplant)
|
||||||
|
|
||||||
**Phase:** B/C
|
**Phase:** B/C
|
||||||
**Status:** 🟡 geplant
|
**Status:** 🟡 geplant
|
||||||
|
|
||||||
**Ziel:**
|
**Ziel:**
|
||||||
Aufbau eines Self-Tuning-Mechanismus, der auf Basis von Feedback-Daten Vorschläge für Retriever- und Policy-Anpassungen macht.
|
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).
|
**Aufwand / Komplexität:**
|
||||||
- Regel-basierte Anpassungs-Vorschläge:
|
- Aufwand: Hoch
|
||||||
- Gewichte in `retriever.yaml`,
|
- Komplexität: Hoch
|
||||||
- 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.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### WP-09 – Vault-Onboarding & Migration (geplant)
|
### WP-09 – Vault-Onboarding & Migration (geplant)
|
||||||
|
|
||||||
**Phase:** B
|
**Phase:** B
|
||||||
**Status:** 🟡 geplant
|
**Status:** 🟡 geplant
|
||||||
|
|
||||||
**Ziel:**
|
**Ziel:**
|
||||||
Sicherstellen, dass bestehende und neue Obsidian-Vaults schrittweise in mindnet integriert werden können – ohne Massenumbau.
|
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:
|
**Aufwand / Komplexität:**
|
||||||
- Analyse des Vault-Status (Typen, Edges, Lücken),
|
- Aufwand: Mittel
|
||||||
- Empfehlungen für minimale Anpassungen (z. B. Typ-Setzung, Basis-Tags),
|
- Komplexität: Niedrig/Mittel
|
||||||
- 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).
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### WP-10 – Chat-Interface & Writeback (geplant)
|
### WP-10 – Chat-Interface & Writeback (geplant)
|
||||||
|
|
||||||
**Phase:** D
|
**Phase:** D
|
||||||
**Status:** 🟡 geplant
|
**Status:** 🟡 geplant
|
||||||
|
|
||||||
**Ziel:**
|
**Ziel:**
|
||||||
Chat-basierter mindnet-Agent, der sowohl Fragen beantwortet als auch neue Notizen erzeugen/aktualisieren kann (Writeback Richtung Vault).
|
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).
|
**Aufwand / Komplexität:**
|
||||||
- Anbindung an:
|
- Aufwand: Hoch
|
||||||
- `/query` (Retriever),
|
- Komplexität: Hoch
|
||||||
- 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.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### WP-11 – Knowledge-Builder & Vernetzungs-Assistent (geplant)
|
### WP-11 – Knowledge-Builder & Vernetzungs-Assistent (geplant)
|
||||||
|
|
||||||
**Phase:** D
|
**Phase:** D
|
||||||
**Status:** 🟡 geplant
|
**Status:** 🟡 geplant
|
||||||
|
|
||||||
**Ziel:**
|
**Ziel:**
|
||||||
Assistent, der manuell erstellte oder importierte Notizen analysiert und Vorschläge für Typen, Edges und Einordnung macht.
|
Assistent, der manuell erstellte oder importierte Notizen analysiert und Vorschläge für Typen, Edges und Einordnung macht.
|
||||||
|
|
||||||
**Umfang:**
|
**Aufwand / Komplexität:**
|
||||||
|
- Aufwand: Hoch
|
||||||
- Analyse neuer/aktualisierter Notes:
|
- Komplexität: Hoch
|
||||||
- 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.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### WP-12 – Knowledge Rewriter (Soft Mode, geplant)
|
### WP-12 – Knowledge Rewriter (Soft Mode, geplant)
|
||||||
|
|
||||||
**Phase:** C/D
|
**Phase:** C/D
|
||||||
**Status:** 🟡 geplant
|
**Status:** 🟡 geplant
|
||||||
|
|
||||||
**Ziel:**
|
**Ziel:**
|
||||||
Optionaler Assistent, der vorhandene Notes „aufräumt“, zusammenfasst oder reorganisiert – ausschließlich mit expliziter Freigabe. :contentReference[oaicite:31]{index=31}
|
Optionaler Assistent, der vorhandene Notes „aufräumt“, zusammenfasst oder reorganisiert – ausschließlich mit expliziter Freigabe.
|
||||||
|
|
||||||
**Einschränkungen:**
|
**Aufwand / Komplexität:**
|
||||||
|
- Aufwand: Niedrig/Mittel
|
||||||
- Änderungen an Markdown-Dateien nur nach Freigabe.
|
- Komplexität: Mittel
|
||||||
- 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.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### WP-13 – MCP-Integration & Agenten-Layer (geplant)
|
### WP-13 – MCP-Integration & Agenten-Layer (geplant)
|
||||||
|
|
||||||
**Phase:** D
|
**Phase:** D
|
||||||
**Status:** 🟡 geplant
|
**Status:** 🟡 geplant
|
||||||
|
|
||||||
**Ziel:**
|
**Ziel:**
|
||||||
mindnet als MCP-Server bereitstellen, damit Agenten/LLMs standardisierte Tools nutzen können (z. B. in deiner n8n- und LLM-Umgebung).
|
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:
|
**Aufwand / Komplexität:**
|
||||||
- `mindnet_query`,
|
- Aufwand: Mittel
|
||||||
- `mindnet_subgraph`,
|
- Komplexität: Mittel
|
||||||
- `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.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### WP-14 – Review / Refactoring / Dokumentation (geplant)
|
### WP-14 – Review / Refactoring / Dokumentation (geplant)
|
||||||
|
|
||||||
**Phase:** E
|
**Phase:** E
|
||||||
**Status:** 🟡 geplant
|
**Status:** 🟡 geplant
|
||||||
|
|
||||||
**Ziel:**
|
**Ziel:**
|
||||||
Aufräumen, dokumentieren, stabilisieren – insbesondere für Onboarding Dritter und Langfrist-Betrieb.
|
Aufräumen, dokumentieren, stabilisieren – insbesondere für Onboarding Dritter und Langfrist-Betrieb.
|
||||||
|
|
||||||
**Deliverables (Beispiele):**
|
**Aufwand / Komplexität:**
|
||||||
|
- Aufwand: Mittel
|
||||||
- konsolidierte technische Architektur (`mindnet_technical_architecture.md`),
|
- Komplexität: Niedrig/Mittel
|
||||||
- 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.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -690,13 +442,11 @@ Aufräumen, dokumentieren, stabilisieren – insbesondere für Onboarding Dritte
|
|||||||
WP03 → WP09
|
WP03 → WP09
|
||||||
WP01/WP03 → WP10 → WP11 → WP12
|
WP01/WP03 → WP10 → WP11 → WP12
|
||||||
WP03/WP04 → WP13
|
WP03/WP04 → WP13
|
||||||
Alles → WP14
|
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.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 8. Laufzeit- & Komplexitätsindikatoren (unverändert, ergänzt)
|
## 8. Laufzeit- & Komplexitätsindikatoren (aktualisiert)
|
||||||
|
|
||||||
| WP | Aufwand | Komplexität |
|
| 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 |
|
| WP11 | Hoch | Hoch |
|
||||||
| WP12 | Niedrig/Mittel | Mittel |
|
| WP12 | Niedrig/Mittel | Mittel |
|
||||||
| WP13 | Mittel | Mittel |
|
| WP13 | Mittel | Mittel |
|
||||||
| WP14 | Mittel | Niedrig/Mittel | :contentReference[oaicite:35]{index=35}
|
| WP14 | Mittel | Niedrig/Mittel |
|
||||||
|
|
||||||
Für WP01–WP04a gilt: Aufwand/Komplexität wie in v2.1; Status jetzt explizit „abgeschlossen“ mit beschriebenem Funktionsumfang.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
@@ -725,8 +473,8 @@ Für WP01–WP04a gilt: Aufwand/Komplexität wie in v2.1; Status jetzt explizit
|
|||||||
| WP02 | 🟢 |
|
| WP02 | 🟢 |
|
||||||
| WP03 | 🟢 |
|
| WP03 | 🟢 |
|
||||||
| WP04a | 🟢 |
|
| WP04a | 🟢 |
|
||||||
| WP04b | 🟡 |
|
| WP04b | 🟢 |
|
||||||
| WP04c | 🟡 |
|
| WP04c | 🟢 |
|
||||||
| WP05 | 🟡 |
|
| WP05 | 🟡 |
|
||||||
| WP06 | 🟡 |
|
| WP06 | 🟡 |
|
||||||
| WP07 | 🟡 |
|
| WP07 | 🟡 |
|
||||||
@@ -736,37 +484,30 @@ Für WP01–WP04a gilt: Aufwand/Komplexität wie in v2.1; Status jetzt explizit
|
|||||||
| WP11 | 🟡 |
|
| WP11 | 🟡 |
|
||||||
| WP12 | 🟡 |
|
| WP12 | 🟡 |
|
||||||
| WP13 | 🟡 |
|
| WP13 | 🟡 |
|
||||||
| WP14 | 🟡 | :contentReference[oaicite:36]{index=36}
|
| WP14 | 🟡 |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 10. Governance & Versionierung
|
## 10. Governance & Versionierung
|
||||||
|
|
||||||
- Versionierung über Gitea (Branches, Tags, Releases).
|
- Versionierung über Gitea (Branches, Tags, Releases).
|
||||||
- Jede wesentliche Änderung an Architektur/Schema:
|
- Feature-Branch Workflow mit "Sync First" Strategie.
|
||||||
- eigener Commit,
|
- Jede wesentliche Änderung an Architektur/Schema erhält einen eigenen 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).
|
||||||
- Jedes Workpackage erhält ein eigenes Chat-Fenster mit dediziertem Prompt (WP-Hand-Over).
|
- Programmleitung verantwortet Konsistenz und Priorisierung.
|
||||||
- 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.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 11. Executive Summary (unverändert, präzisiert)
|
## 11. Executive Summary
|
||||||
|
|
||||||
mindnet v2.2 ist so aufgesetzt, dass:
|
mindnet v2.2 ist so aufgesetzt, dass:
|
||||||
|
|
||||||
- du **schrittweise** Wissen erfassen kannst (Obsidian + Chat + später Interview-Assistent),
|
- du **schrittweise** Wissen erfassen kannst (Obsidian + Chat + später Interview-Assistent),
|
||||||
- die Struktur **mitwächst**, ohne Retro-Massenarbeit im Vault,
|
- die Struktur **mitwächst**, ohne Retro-Massenarbeit im Vault,
|
||||||
- ein **hybrider Retriever** qualitativ hochwertige, erklärbare Antworten liefert,
|
- ein **hybrider Retriever** qualitativ hochwertige, erklärbare Antworten liefert,
|
||||||
- ein **Self-Healing- und Self-Tuning-Mechanismus** vorbereitet ist, der auf Feedback aufsetzt,
|
- ein **Self-Healing- und Self-Tuning-Mechanismus** vorbereitet ist (durch WP-04c Feedback-Daten),
|
||||||
- ein **Persönlichkeitsmodell** und eine **Decision Engine** entstehen,
|
- ein **Persönlichkeitsmodell** und eine **Decision Engine** entstehen,
|
||||||
- langfristig ein **KI-Zwilling** aufgebaut wird, der deine Werte, Erfahrungen und Denkweise spiegelt,
|
- 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.
|
- 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.
|
|
||||||
|
|
||||||
|
Dieser Programmplan bildet die konsolidierte Grundlage (v2.2.1) für alle weiteren Arbeiten.
|
||||||
+9
-9
@@ -1,43 +1,43 @@
|
|||||||
"""
|
"""
|
||||||
app/main.py — mindnet API bootstrap (WP-04 Hooks)
|
app/main.py — mindnet API bootstrap
|
||||||
Version: 0.4.2 • Stand: 2025-10-07
|
|
||||||
"""
|
"""
|
||||||
|
|
||||||
from __future__ import annotations
|
from __future__ import annotations
|
||||||
from fastapi import FastAPI
|
from fastapi import FastAPI
|
||||||
from .config import get_settings
|
from .config import get_settings
|
||||||
from .routers.embed_router import router as embed_router
|
from .routers.embed_router import router as embed_router
|
||||||
from .routers.qdrant_router import router as qdrant_router
|
from .routers.qdrant_router import router as qdrant_router
|
||||||
|
|
||||||
# WP-04 Router:
|
|
||||||
from .routers.query import router as query_router
|
from .routers.query import router as query_router
|
||||||
from .routers.graph import router as graph_router
|
from .routers.graph import router as graph_router
|
||||||
from .routers.tools import router as tools_router
|
from .routers.tools import router as tools_router
|
||||||
# Optional:
|
# NEU: Feedback Router
|
||||||
|
from .routers.feedback import router as feedback_router
|
||||||
|
|
||||||
try:
|
try:
|
||||||
from .routers.admin import router as admin_router
|
from .routers.admin import router as admin_router
|
||||||
except Exception:
|
except Exception:
|
||||||
admin_router = None
|
admin_router = None
|
||||||
|
|
||||||
def create_app() -> FastAPI:
|
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()
|
s = get_settings()
|
||||||
|
|
||||||
@app.get("/healthz")
|
@app.get("/healthz")
|
||||||
def healthz():
|
def healthz():
|
||||||
return {"status": "ok", "qdrant": s.QDRANT_URL, "prefix": s.COLLECTION_PREFIX}
|
return {"status": "ok", "qdrant": s.QDRANT_URL, "prefix": s.COLLECTION_PREFIX}
|
||||||
|
|
||||||
# Bestehende Router (unverändert)
|
|
||||||
app.include_router(embed_router)
|
app.include_router(embed_router)
|
||||||
app.include_router(qdrant_router)
|
app.include_router(qdrant_router)
|
||||||
|
|
||||||
# WP-04 Endpunkte
|
|
||||||
app.include_router(query_router, prefix="/query", tags=["query"])
|
app.include_router(query_router, prefix="/query", tags=["query"])
|
||||||
app.include_router(graph_router, prefix="/graph", tags=["graph"])
|
app.include_router(graph_router, prefix="/graph", tags=["graph"])
|
||||||
app.include_router(tools_router, prefix="/tools", tags=["tools"])
|
app.include_router(tools_router, prefix="/tools", tags=["tools"])
|
||||||
|
# NEU:
|
||||||
|
app.include_router(feedback_router, prefix="/feedback", tags=["feedback"])
|
||||||
|
|
||||||
if admin_router:
|
if admin_router:
|
||||||
app.include_router(admin_router, prefix="/admin", tags=["admin"])
|
app.include_router(admin_router, prefix="/admin", tags=["admin"])
|
||||||
|
|
||||||
return app
|
return app
|
||||||
|
|
||||||
app = create_app()
|
app = create_app()
|
||||||
+32
-30
@@ -4,28 +4,26 @@ app/models/dto.py — Pydantic-Modelle (DTOs) für WP-04 Endpunkte
|
|||||||
Zweck:
|
Zweck:
|
||||||
Laufzeit-Modelle für FastAPI (Requests/Responses), getrennt von JSON-Schemas.
|
Laufzeit-Modelle für FastAPI (Requests/Responses), getrennt von JSON-Schemas.
|
||||||
Deckt die Graph-/Retriever-Endpunkte ab.
|
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:
|
Kompatibilität:
|
||||||
Python 3.12+, Pydantic 2.x, FastAPI 0.110+
|
Python 3.12+, Pydantic 2.x, FastAPI 0.110+
|
||||||
Version:
|
Version:
|
||||||
0.2.0 (Update für WP-04b Explanation Layer)
|
0.3.0 (Update für WP-04c Feedback)
|
||||||
Stand:
|
Stand:
|
||||||
2025-12-07
|
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 __future__ import annotations
|
||||||
from pydantic import BaseModel, Field
|
from pydantic import BaseModel, Field
|
||||||
from typing import List, Literal, Optional, Dict, Any
|
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"]
|
EdgeKind = Literal["references", "references_at", "backlink", "next", "prev", "belongs_to", "depends_on", "related_to", "similar_to"]
|
||||||
|
|
||||||
|
|
||||||
|
# --- Basis-DTOs ---
|
||||||
|
|
||||||
class NodeDTO(BaseModel):
|
class NodeDTO(BaseModel):
|
||||||
"""Darstellung eines Knotens (Note oder Chunk) im API-Graph."""
|
"""Darstellung eines Knotens (Note oder Chunk) im API-Graph."""
|
||||||
id: str
|
id: str
|
||||||
@@ -51,12 +49,14 @@ class EdgeDTO(BaseModel):
|
|||||||
direction: Literal["out", "in", "undirected"] = "out"
|
direction: Literal["out", "in", "undirected"] = "out"
|
||||||
|
|
||||||
|
|
||||||
|
# --- Request Models ---
|
||||||
|
|
||||||
class QueryRequest(BaseModel):
|
class QueryRequest(BaseModel):
|
||||||
"""
|
"""
|
||||||
Request für /query:
|
Request für /query:
|
||||||
- mode: 'semantic' | 'edge' | 'hybrid'
|
- mode: 'semantic' | 'edge' | 'hybrid'
|
||||||
- query: (optional) Freitext; Embedding wird später angebunden
|
- query: (optional) Freitext
|
||||||
- query_vector: (optional) direkter Vektor (384d) für Quick-Tests ohne Embedding
|
- query_vector: (optional) direkter Vektor
|
||||||
- explain: (optional) Fordert detaillierte Erklärungen an (WP-04b)
|
- explain: (optional) Fordert detaillierte Erklärungen an (WP-04b)
|
||||||
"""
|
"""
|
||||||
mode: Literal["semantic", "edge", "hybrid"] = "hybrid"
|
mode: Literal["semantic", "edge", "hybrid"] = "hybrid"
|
||||||
@@ -65,24 +65,29 @@ class QueryRequest(BaseModel):
|
|||||||
top_k: int = 10
|
top_k: int = 10
|
||||||
expand: Dict = {"depth": 1, "edge_types": ["references", "belongs_to", "prev", "next", "depends_on", "related_to"]}
|
expand: Dict = {"depth": 1, "edge_types": ["references", "belongs_to", "prev", "next", "depends_on", "related_to"]}
|
||||||
filters: Optional[Dict] = None
|
filters: Optional[Dict] = None
|
||||||
# Flags zur Steuerung der Rückgabe
|
|
||||||
ret: Dict = {"with_paths": True, "with_notes": True, "with_chunks": True}
|
ret: Dict = {"with_paths": True, "with_notes": True, "with_chunks": True}
|
||||||
# WP-04b: Soll eine Erklärung generiert werden?
|
|
||||||
explain: bool = False
|
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 ---
|
# --- WP-04b Explanation Models ---
|
||||||
|
|
||||||
class ScoreBreakdown(BaseModel):
|
class ScoreBreakdown(BaseModel):
|
||||||
"""
|
"""Aufschlüsselung der Score-Komponenten."""
|
||||||
Aufschlüsselung der Score-Komponenten.
|
|
||||||
Zeigt die gewichteten Beiträge zum Total Score.
|
|
||||||
"""
|
|
||||||
semantic_contribution: float = Field(..., description="W_sem * semantic_score * weight")
|
semantic_contribution: float = Field(..., description="W_sem * semantic_score * weight")
|
||||||
edge_contribution: float = Field(..., description="W_edge * edge_bonus")
|
edge_contribution: float = Field(..., description="W_edge * edge_bonus")
|
||||||
centrality_contribution: float = Field(..., description="W_cent * centrality_bonus")
|
centrality_contribution: float = Field(..., description="W_cent * centrality_bonus")
|
||||||
|
|
||||||
# Rohwerte für Transparenz
|
# Rohwerte
|
||||||
raw_semantic: float
|
raw_semantic: float
|
||||||
raw_edge_bonus: float
|
raw_edge_bonus: float
|
||||||
raw_centrality: float
|
raw_centrality: float
|
||||||
@@ -90,10 +95,7 @@ class ScoreBreakdown(BaseModel):
|
|||||||
|
|
||||||
|
|
||||||
class Reason(BaseModel):
|
class Reason(BaseModel):
|
||||||
"""
|
"""Ein semantischer Grund für das Ranking."""
|
||||||
Ein semantischer Grund für das Ranking.
|
|
||||||
z.B. 'Verlinkt von Projekt X', 'Hohe Textähnlichkeit'.
|
|
||||||
"""
|
|
||||||
kind: Literal["semantic", "edge", "type", "centrality"]
|
kind: Literal["semantic", "edge", "type", "centrality"]
|
||||||
message: str
|
message: str
|
||||||
score_impact: Optional[float] = None
|
score_impact: Optional[float] = None
|
||||||
@@ -101,24 +103,20 @@ class Reason(BaseModel):
|
|||||||
|
|
||||||
|
|
||||||
class Explanation(BaseModel):
|
class Explanation(BaseModel):
|
||||||
"""
|
"""Container für alle Erklärungsdaten eines Treffers."""
|
||||||
Container für alle Erklärungsdaten eines Treffers.
|
|
||||||
"""
|
|
||||||
breakdown: ScoreBreakdown
|
breakdown: ScoreBreakdown
|
||||||
reasons: List[Reason]
|
reasons: List[Reason]
|
||||||
# Optional: Pfade im Graphen, die zu diesem Treffer geführt haben
|
|
||||||
related_edges: Optional[List[EdgeDTO]] = None
|
related_edges: Optional[List[EdgeDTO]] = None
|
||||||
|
|
||||||
|
|
||||||
# --- End Explanation Models ---
|
# --- Response Models ---
|
||||||
|
|
||||||
|
|
||||||
class QueryHit(BaseModel):
|
class QueryHit(BaseModel):
|
||||||
"""Einzelnes Trefferobjekt für /query."""
|
"""Einzelnes Trefferobjekt für /query."""
|
||||||
node_id: str
|
node_id: str
|
||||||
note_id: Optional[str]
|
note_id: Optional[str]
|
||||||
|
|
||||||
# Flache Scores (Kompatibilität WP-04a)
|
# Flache Scores
|
||||||
semantic_score: float
|
semantic_score: float
|
||||||
edge_bonus: float
|
edge_bonus: float
|
||||||
centrality_bonus: float
|
centrality_bonus: float
|
||||||
@@ -127,19 +125,23 @@ class QueryHit(BaseModel):
|
|||||||
paths: Optional[List[List[Dict]]] = None
|
paths: Optional[List[List[Dict]]] = None
|
||||||
source: Optional[Dict] = None
|
source: Optional[Dict] = None
|
||||||
|
|
||||||
# WP-04b: Erklärungsobjekt (nur gefüllt, wenn explain=True)
|
# WP-04b: Erklärungsobjekt
|
||||||
explanation: Optional[Explanation] = None
|
explanation: Optional[Explanation] = None
|
||||||
|
|
||||||
|
|
||||||
class QueryResponse(BaseModel):
|
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]
|
results: List[QueryHit]
|
||||||
used_mode: str
|
used_mode: str
|
||||||
latency_ms: int
|
latency_ms: int
|
||||||
|
|
||||||
|
|
||||||
class GraphResponse(BaseModel):
|
class GraphResponse(BaseModel):
|
||||||
"""Antwortstruktur für /graph/{note_id} (Nachbarschaft)."""
|
"""Antwortstruktur für /graph/{note_id}."""
|
||||||
center_note_id: str
|
center_note_id: str
|
||||||
nodes: List[NodeDTO]
|
nodes: List[NodeDTO]
|
||||||
edges: List[EdgeDTO]
|
edges: List[EdgeDTO]
|
||||||
|
|||||||
@@ -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
@@ -15,24 +15,31 @@ Bezug:
|
|||||||
Nutzung:
|
Nutzung:
|
||||||
app.include_router(query.router, prefix="/query", tags=["query"])
|
app.include_router(query.router, prefix="/query", tags=["query"])
|
||||||
Änderungsverlauf:
|
Änderungsverlauf:
|
||||||
|
0.2.0 (2025-12-07) - Update für WP04c Feedback
|
||||||
0.1.0 (2025-10-07) – Erstanlage.
|
0.1.0 (2025-10-07) – Erstanlage.
|
||||||
"""
|
"""
|
||||||
|
|
||||||
from __future__ import annotations
|
from __future__ import annotations
|
||||||
from fastapi import APIRouter, HTTPException
|
from fastapi import APIRouter, HTTPException, BackgroundTasks
|
||||||
from app.models.dto import QueryRequest, QueryResponse
|
from app.models.dto import QueryRequest, QueryResponse
|
||||||
from app.core.retriever import hybrid_retrieve, semantic_retrieve
|
from app.core.retriever import hybrid_retrieve, semantic_retrieve
|
||||||
|
# NEU:
|
||||||
|
from app.services.feedback_service import log_search
|
||||||
|
|
||||||
router = APIRouter()
|
router = APIRouter()
|
||||||
|
|
||||||
@router.post("", response_model=QueryResponse)
|
@router.post("", response_model=QueryResponse)
|
||||||
def post_query(req: QueryRequest) -> QueryResponse:
|
def post_query(req: QueryRequest, background_tasks: BackgroundTasks) -> QueryResponse:
|
||||||
try:
|
try:
|
||||||
if req.mode == "semantic":
|
if req.mode == "semantic":
|
||||||
return semantic_retrieve(req)
|
res = semantic_retrieve(req)
|
||||||
# default: hybrid
|
else:
|
||||||
return hybrid_retrieve(req)
|
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:
|
except ValueError as e:
|
||||||
raise HTTPException(status_code=400, detail=str(e))
|
raise HTTPException(status_code=400, detail=str(e))
|
||||||
except Exception as 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}")
|
||||||
@@ -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
@@ -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
@@ -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. |
|
||||||
+62
-45
@@ -1,6 +1,6 @@
|
|||||||
# Mindnet v2.2 – Entwickler-Workflow
|
# Mindnet v2.2 – Entwickler-Workflow
|
||||||
**Datei:** `DEV_WORKFLOW.md`
|
**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).
|
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.
|
Hier erstellst du die neue Funktion in einer sicheren Umgebung.
|
||||||
|
|
||||||
1. **Sicherstellen, dass Git bereit ist:**
|
1. **Basis aktualisieren (WICHTIG!):**
|
||||||
* Öffne VS Code.
|
Bevor du startest, muss dein lokales `main` auf dem Stand des Servers sein.
|
||||||
* Unten links in der blauen Leiste sollte der aktuelle Branch stehen (z.B. `main`).
|
* 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):**
|
2. **Branch erstellen:**
|
||||||
* Klicke unten links auf den Branch-Namen (z.B. `main`).
|
* Klicke wieder unten links auf `main`.
|
||||||
* Wähle im Menü oben `+ Create new branch...`.
|
* Wähle `+ Create new branch...`.
|
||||||
* Gib den Namen ein: `feature/was-ich-tue` (z.B. `feature/wp04b-explanation`).
|
* Gib den Namen ein: `feature/was-ich-tue` (z.B. `feature/wp04b-explanation`).
|
||||||
* Drücke **Enter**.
|
* Drücke **Enter**.
|
||||||
|
|
||||||
3. **Sicherheits-Check:**
|
3. **Sicherheits-Check:**
|
||||||
* Schau unten links: Steht dort jetzt `feature/wp04b-explanation`?
|
* Steht unten links jetzt dein Feature-Branch? **Nur dann darfst du Code ändern!**
|
||||||
* **Nur wenn dort dein Feature-Branch steht, darfst du Code ändern!** Alles, was du jetzt speicherst, landet in diesem Branch.
|
|
||||||
|
|
||||||
4. **Coden:**
|
4. **Coden:**
|
||||||
* Nimm deine Änderungen vor.
|
* Nimm deine Änderungen vor.
|
||||||
|
|
||||||
5. **Sichern & Hochladen:**
|
5. **Sichern & Hochladen:**
|
||||||
* Klicke links auf das **Source Control** Icon (Gabel-Symbol).
|
* **Source Control** Icon (Gabel-Symbol) -> Nachricht eingeben -> **Commit**.
|
||||||
* Gib eine Nachricht ein: "feat: Add explanation layer logic".
|
* **Publish Branch** (oder "Sync Changes"), um den Branch zum Raspberry Pi (Gitea) zu senden.
|
||||||
* Klicke auf **Commit**.
|
|
||||||
* Klicke auf **Publish Branch** (oder "Sync Changes"), um den Branch zum Raspberry Pi (Gitea) zu senden.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
### Phase 2: Testen (Beelink / `mindnet_dev`)
|
### 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:**
|
1. **Einloggen:**
|
||||||
`ssh user@<BEELINK-IP>`
|
`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:**
|
3. **Code holen:**
|
||||||
```bash
|
```bash
|
||||||
git fetch
|
git fetch
|
||||||
|
# Tipp: 'git branch -r' zeigt alle verfügbaren Branches an
|
||||||
git checkout feature/wp04b-explanation
|
git checkout feature/wp04b-explanation
|
||||||
git pull
|
git pull
|
||||||
```
|
```
|
||||||
|
|
||||||
4. **Umgebung aktivieren (Venv):**
|
4. **Umgebung vorbereiten:**
|
||||||
Damit Python die installierten Bibliotheken findet, musst du das Virtual Environment aktivieren:
|
|
||||||
```bash
|
```bash
|
||||||
source .venv/bin/activate
|
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:**
|
5. **Test-Server neustarten (WICHTIG):**
|
||||||
*(Nur nötig, wenn du neue Libraries in `requirements.txt` eingetragen hast)*
|
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
|
```bash
|
||||||
pip install -r requirements.txt
|
uvicorn app.main:app --host 0.0.0.0 --port 8002 --env-file .env
|
||||||
```
|
```
|
||||||
|
|
||||||
6. **Test-Server starten:**
|
6. **Validieren:**
|
||||||
**WICHTIG:** Nutze Port **8002** und das Dev-Prefix!
|
Führe deine Tests in einem **zweiten Terminal** aus:
|
||||||
Stelle sicher, dass in `~/mindnet_dev/.env` steht: `COLLECTION_PREFIX="mindnet_dev"`.
|
|
||||||
|
|
||||||
```bash
|
```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)
|
### 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:
|
Wenn der Test auf Port 8002 erfolgreich war:
|
||||||
|
|
||||||
1. Öffne Gitea im Browser.
|
1. Öffne Gitea im Browser.
|
||||||
2. Du solltest einen Hinweis sehen "feature/... had recent pushes".
|
2. Erstelle einen **Pull Request** (Dein Branch -> `main`).
|
||||||
3. Erstelle einen **Pull Request** (Dein Branch -> `main`).
|
3. **Merge** den Pull Request.
|
||||||
4. **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
|
## 3. Cheat Sheet: Die wichtigsten Befehle
|
||||||
|
|
||||||
| Wo? | Befehl | Was tut es? |
|
| Wo? | Befehl | Was tut es? |
|
||||||
| :--- | :--- | :--- |
|
| :--- | :--- | :--- |
|
||||||
| **VS Code** | `Klick auf Branch-Namen` | Branch erstellen oder wechseln. |
|
| **VS Code** | `Sync (auf main)` | **WICHTIG:** Holt neuesten Code vom Server. |
|
||||||
| **VS Code** | `Sync Changes` | Lädt Code zu Gitea hoch. |
|
| **VS Code** | `Klick auf Branch` | Branch erstellen oder wechseln. |
|
||||||
| **Beelink** | `cd ~/mindnet_dev` | Gehe in den Test-Ordner. |
|
|
||||||
| **Beelink** | `source .venv/bin/activate` | **Aktiviert Python-Umgebung.** |
|
| **Beelink** | `source .venv/bin/activate` | **Aktiviert Python-Umgebung.** |
|
||||||
| **Beelink** | `git fetch` | "Gibt es neue Branches auf Gitea?" |
|
| **Beelink** | `git fetch` | Aktualisiert Remote-Branches. |
|
||||||
| **Beelink** | `git checkout <name>` | Wechsle auf einen anderen Branch. |
|
| **Beelink** | `git checkout <name>` | Wechsle Branch. |
|
||||||
| **Beelink** | `git pull` | Hol den neuesten Stand des aktuellen Branches. |
|
| **Beelink** | `git pull` | Aktualisiere aktuellen Branch. |
|
||||||
| **Beelink** | `uvicorn ... --port 8002` | Startet Test-Server (Dev). |
|
| **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`.
|
**"Hilfe, in meinem neuen Branch fehlen Dateien!"**
|
||||||
2. **Niemals** beide Umgebungen auf denselben `COLLECTION_PREFIX` zeigen lassen.
|
Das passiert, wenn du beim Erstellen nicht aktuell warst.
|
||||||
* Prod `.env`: `COLLECTION_PREFIX="mindnet"`
|
* **Lösung:**
|
||||||
* Dev `.env`: `COLLECTION_PREFIX="mindnet_dev"`
|
```bash
|
||||||
3. **Port-Disziplin:**
|
# In VS Code Terminal:
|
||||||
* **PROD:** Port 8001
|
git checkout feature/mein-kaputter-branch
|
||||||
* **DEV:** Port 8002
|
git merge main
|
||||||
|
# (Das holt die fehlenden Dateien aus main nach)
|
||||||
@@ -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`.
|
||||||
@@ -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.
|
||||||
|
|||||||
@@ -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()
|
||||||
Reference in new issue
Block a user