Compare commits
8
Commits
V2.2.1
..
e39b685b1e
| Author | SHA1 | Date | |
|---|---|---|---|
|
|
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
-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)
|
||||||
@@ -0,0 +1,65 @@
|
|||||||
|
import requests
|
||||||
|
import json
|
||||||
|
import sys
|
||||||
|
import time
|
||||||
|
|
||||||
|
# Konfiguration
|
||||||
|
BASE_URL = "http://localhost:8002"
|
||||||
|
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