Compare commits

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

No files matched your search

@@ -0,0 +1,27 @@
# Architecture Snapshot v2.2.1
**Stand:** Nach Abschluss von WP-04c
**Kontext:** Wichtig für WP-05 Entwicklung.
## 1. Neue Komponenten (Seit v2.2.0)
### A. Feedback Service (`app/services/feedback_service.py`)
- **Zweck:** Logging von Trainingsdaten für späteres Self-Tuning (WP-08).
- **Storage:** Lokale JSONL-Dateien in `data/logs/` (Append-Only).
- `search_history.jsonl`: Query + Snapshot der Ergebnisse (Scores).
- `feedback.jsonl`: User-Rating zu spezifischer `node_id`.
### B. Explanation Layer (`app/core/retriever.py`)
- **Logik:** Der Retriever berechnet nicht nur Scores, sondern generiert `Explanation`-Objekte.
- **Graph:** `Subgraph` (in `graph_adapter.py`) führt jetzt auch `reverse_adj` (Incoming Edges), um zu erklären, warum ein Knoten wichtig ist ("Referenziert von...").
### C. DTOs (`app/models/dto.py`)
Das Datenmodell wurde massiv erweitert. Wichtige Klassen für WP-05:
- `QueryResponse`: Enthält jetzt `query_id` (UUID).
- `QueryHit`: Enthält optional `explanation` (Typ `Explanation`).
- `FeedbackRequest`: Für den Feedback-Loop.
## 2. Implikationen für WP-05 (Chat)
1. **Logging:** Auch der neue `/chat` Endpoint sollte idealerweise die `query_id` loggen oder nutzen, um Konsistenz zu wahren.
2. **DTO-Nutzung:** Der Chat-Service wird intern den Retriever aufrufen. Er muss mit den `QueryHit`-Objekten arbeiten, um den Kontext für das LLM zu bauen.
3. **Config:** Die Persönlichkeit wird in `config/prompts.yaml` definiert (Late Binding), nicht im Python-Code hardcodiert.
+75 -334
View File
@@ -1,7 +1,7 @@
# 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
--- ---
@@ -72,10 +72,12 @@ Kernprinzipien der Vision:
- 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).
@@ -87,6 +89,7 @@ Kernprinzipien der Vision:
### 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).
- **RAG-Chat:** KI antwortet in natürlicher Sprache auf Basis von Wissen und Persönlichkeit (WP-05).
- Why-Layer: KI-Assistenz für Entscheidungen mit nachvollziehbarer Argumentation. - Why-Layer: KI-Assistenz für Entscheidungen mit nachvollziehbarer Argumentation.
- Interview-Assistent erstellt neue Notes automatisch (strukturierte Dialoge → Markdown). - Interview-Assistent erstellt neue Notes automatisch (strukturierte Dialoge → Markdown).
- mindnet erzeugt Vorschläge für neue Notes & Edges und bietet einen „Vernetzungs-Assistenten“ für manuell angelegte Notizen. - mindnet erzeugt Vorschläge für neue Notes & Edges und bietet einen „Vernetzungs-Assistenten“ für manuell angelegte Notizen.
@@ -156,7 +159,7 @@ Die folgenden Prinzipien steuern alle Workpackages und Entscheidungen:
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.
--- ---
@@ -167,7 +170,7 @@ Alle Workpackages sind einer Phase zugeordnet; einige Workpackages (z. B. WP-03,
- 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.
--- ---
@@ -178,33 +181,12 @@ Die Status-Ampel zeigt den aktuellen Stand gemäß Programmfortschritt. :content
**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.
--- ---
@@ -214,32 +196,11 @@ Grundlegendes Schema für mindnet festlegen (`knowledge_design.md`), inkl.:
**Status:** 🟢 abgeschlossen **Status:** 🟢 abgeschlossen
**Ziel:** **Ziel:**
Festlegen und implementieren einer robusten Chunking-Strategie und einer Hash-Logik zur Änderungs­erkennung. 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 Änderungs­erkennung (Body / Frontmatter / Full, canonical vs. none).
- Unterstützung eines „Baseline-Modus“ (mehrere Hash-Signaturen), um spätere Modus-Wechsel zu ermöglichen, ohne alle Notizen als „geändert“ zu sehen.
**Aufwand / Komplexität:**
- Aufwand: Mittel
- Komplexität: Mittel/Hoch
**Erreichte Ergebnisse / Funktionsumfang:**
- Implementierte Chunker-Logik mit Ziel-Längen, Overlap und Nachbarschaft (`neighbors_prev`, `neighbors_next`).
- Tests zur Überprüfung der Rekonstruktion von Notiz-Bodies aus Chunks (`verify_chunks_integrity.py`, `check_chunks_window_vs_text.py`).
- Hash-Konfiguration über ENV-Variablen + Option `--baseline-modes`.
- Roundtrip-Tests für Vault → Qdrant → Export-Vault (keine ungewollten Veränderungen an Inhalten).
**DoD:**
- Chunking stabil, deterministisch, überprüft.
- Hash-Strategie ermöglicht sichere Änderungs­erkennung ohne Mass-Diffs bei Konfigurationswechsel.
--- ---
@@ -249,39 +210,11 @@ Festlegen und implementieren einer robusten Chunking-Strategie und einer Hash-Lo
**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).
--- ---
@@ -291,132 +224,64 @@ Durchgängige Import-Pipeline von Markdown → Notes/Chunks/Edges in Qdrant mit
**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.
- Identifikation und Typisierung relevanter Notes: - **Service:** `llm_service.py` für Text-Generierung (Ollama-Anbindung).
- `value`, `principle`, `life_event`, `milestone`, `decision`. - **Router:** `/chat` Endpoint (Kontext-Assembly -> Prompt -> LLM).
- Aufbau eines Modells, das: - **Persönlichkeit:** Definition von "Mindnet" als KI-Zwilling (Stil, Haltung).
- typische Begründungsmuster erkennt,
- Wertprioritäten identifiziert,
- langfristig in Scoring & Antwort-Formulierung einfließt.
**Aufwand / Komplexität:** **Aufwand / Komplexität:**
- Aufwand: Mittel - Aufwand: Mittel
- Komplexität: 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)
@@ -428,23 +293,14 @@ Aufbau eines expliziten Persönlichkeitsmodells, das Werte, Prinzipien, prägend
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.
- Identifikation typischer Entscheidungssituationen (z. B. beruflich, familiär, gesundheitlich). - Integration von fachlichem Wissen, Erfahrungen und Persönlichkeitsmodell.
- Integration von:
- fachlichem Wissen,
- Erfahrungen (Vergangenheitsentscheidungen),
- Persönlichkeitsmodell.
- Ableitung von Entscheidungs-Templates / Heuristiken. - Ableitung von Entscheidungs-Templates / Heuristiken.
**Aufwand / Komplexität:** **Aufwand / Komplexität:**
- Aufwand: Mittel - Aufwand: Mittel
- Komplexität: Hoch - 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)
@@ -456,20 +312,13 @@ Entscheidungsunterstützung auf Basis von Wissen, Persönlichkeit und Zielen –
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.
- Design von Interview-Flows (z. B. für Lebensereignisse, Projekte, Werte-Workshops). - Konvertierung von Dialogtranskripten in typisierte Notes.
- Konvertierung von Dialogtranskripten in typisierte Notes (inkl. Typ, Tags, erste Edges).
- Integration mit Vault-Struktur (Ablagepfade, Namenskonventionen).
**Aufwand / Komplexität:** **Aufwand / Komplexität:**
- Aufwand: Niedrig/Mittel - Aufwand: Niedrig/Mittel
- Komplexität: 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)
@@ -478,29 +327,16 @@ Dialogbasierter Erfassungs-Assistent, der strukturierte Interviews führt und da
**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.
- Auswertung der Feedback-Daten (WP-04c). - Regel-basierte Anpassungs-Vorschläge für `retriever.yaml` und Typ-Prioritäten.
- Regel-basierte Anpassungs-Vorschläge:
- Gewichte in `retriever.yaml`,
- Typ-Prioritäten,
- Edge-Provenance-Gewichte.
- Optionale halbautomatische Übernahme (Freigabe durch Mindmaster).
**Aufwand / Komplexität:** **Aufwand / Komplexität:**
- Aufwand: Hoch - Aufwand: Hoch
- Komplexität: 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)
@@ -512,24 +348,13 @@ Aufbau eines Self-Tuning-Mechanismus, der auf Basis von Feedback-Daten Vorschlä
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.
- Tools/Guides für: - Empfehlungen für minimale Anpassungen.
- Analyse des Vault-Status (Typen, Edges, Lücken),
- Empfehlungen für minimale Anpassungen (z. B. Typ-Setzung, Basis-Tags),
- optional automatisierte Ergänzung von Properties (mit Freigabe).
- Unterstützung eines „wachsenden Systems“:
- erste Notizen liefern sofort Mehrwert im Retriever,
- später können Typen und Edges ergänzt werden, ohne alte Notizen zu brechen.
**Aufwand / Komplexität:** **Aufwand / Komplexität:**
- Aufwand: Mittel - Aufwand: Mittel
- Komplexität: Niedrig/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)
@@ -541,28 +366,13 @@ Sicherstellen, dass bestehende und neue Obsidian-Vaults schrittweise in mindnet
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.
- Chat-Frontend (z. B. in deiner bestehenden LLM-Umgebung). - Funktionen für Q&A sowie Vorschlag neuer Notes/Edges.
- Anbindung an:
- `/query` (Retriever),
- MCP-Tools (WP-13),
- Import-/Export-Routinen.
- Funktionen:
- Antworten aus mindnet-Wissen,
- Vorschlag neuer Notes/Edges,
- optionales Schreiben ins Vault (Markdown-Erzeugung, Rewriting nur mit Freigabe).
**Aufwand / Komplexität:** **Aufwand / Komplexität:**
- Aufwand: Hoch - Aufwand: Hoch
- Komplexität: 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)
@@ -573,30 +383,10 @@ Chat-basierter mindnet-Agent, der sowohl Fragen beantwortet als auch neue Notize
**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:**
- Analyse neuer/aktualisierter Notes:
- mögliche Typen,
- passende Tags,
- potenzielle Relationen zu bestehenden Notes.
- Vorschläge:
- Inline-Relationen,
- Wikilinks,
- Typ-Zuweisung.
- Optional: Generierung konkreter Patch-Vorschläge für Markdown-Dateien (Diff-basiert).
**Aufwand / Komplexität:** **Aufwand / Komplexität:**
- Aufwand: Hoch - Aufwand: Hoch
- Komplexität: 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)
@@ -605,23 +395,12 @@ Assistent, der manuell erstellte oder importierte Notizen analysiert und Vorschl
**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:**
- Änderungen an Markdown-Dateien nur nach Freigabe.
- Kein „silent overwrite“ existierender Inhalte.
**Aufwand / Komplexität:** **Aufwand / Komplexität:**
- Aufwand: Niedrig/Mittel - Aufwand: Niedrig/Mittel
- Komplexität: 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)
@@ -630,27 +409,15 @@ Optionaler Assistent, der vorhandene Notes „aufräumt“, zusammenfasst oder r
**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:
- `mindnet_query`,
- `mindnet_subgraph`,
- `mindnet_store_note`,
- `mindnet_explain`.
- Sichere Konfiguration (lokal, authentifiziert, logging-fähig).
**Aufwand / Komplexität:** **Aufwand / Komplexität:**
- Aufwand: Mittel - Aufwand: Mittel
- Komplexität: 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)
@@ -661,25 +428,10 @@ mindnet als MCP-Server bereitstellen, damit Agenten/LLMs standardisierte Tools n
**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):**
- konsolidierte technische Architektur (`mindnet_technical_architecture.md`),
- fachliche Architektur (`mindnet_functional_architecture.md`),
- Identity-Modell (`identity_model.md`),
- API-Spezifikation (`api_spec.md`),
- MCP-Integration (`mcp_integration.md`),
- aktualisiertes Handbuch (`Handbuch.md`).
**Aufwand / Komplexität:** **Aufwand / Komplexität:**
- Aufwand: Mittel - Aufwand: Mittel
- Komplexität: Niedrig/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.
--- ---
## 7. Abhängigkeiten (vereinfacht, aktualisiert) ## 7. Abhängigkeiten (vereinfacht, aktualisiert)
@@ -692,11 +444,9 @@ Aufräumen, dokumentieren, stabilisieren – insbesondere für Onboarding Dritte
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: - Programmleitung verantwortet Konsistenz und Priorisierung.
- 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. Dieser Programmplan bildet die konsolidierte Grundlage (v2.2.1) 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.
+8 -8
View File
@@ -1,40 +1,40 @@
""" """
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"])
+32 -30
View File
@@ -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]
+20
View File
@@ -0,0 +1,20 @@
"""
app/routers/feedback.py
Endpunkt für User-Feedback (WP-04c).
"""
from fastapi import APIRouter, HTTPException
from app.models.dto import FeedbackRequest
from app.services.feedback_service import log_feedback
router = APIRouter()
@router.post("", status_code=201)
def post_feedback(fb: FeedbackRequest):
"""
Nimmt Feedback entgegen (z.B. Daumen hoch für einen Treffer).
"""
try:
log_feedback(fb)
return {"status": "recorded", "query_id": fb.query_id}
except Exception as e:
raise HTTPException(status_code=500, detail=str(e))
+13 -6
View File
@@ -15,23 +15,30 @@ 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:
+80
View File
@@ -0,0 +1,80 @@
"""
app/services/feedback_service.py
Service zum Loggen von Suchanfragen und Feedback (WP-04c).
Speichert Daten als JSONL für späteres Self-Tuning (WP-08).
"""
import json
import os
import time
from pathlib import Path
from typing import Dict, Any, List
from app.models.dto import QueryRequest, QueryResponse, FeedbackRequest
# Pfad für Logs (lokal auf dem Beelink/PC)
LOG_DIR = Path("data/logs")
SEARCH_LOG_FILE = LOG_DIR / "search_history.jsonl"
FEEDBACK_LOG_FILE = LOG_DIR / "feedback.jsonl"
def _ensure_log_dir():
if not LOG_DIR.exists():
os.makedirs(LOG_DIR, exist_ok=True)
def log_search(req: QueryRequest, res: QueryResponse):
"""
Speichert den "Snapshot" der Suche.
WICHTIG: Wir speichern die Scores (Breakdown), damit wir später wissen,
warum das System so entschieden hat.
"""
_ensure_log_dir()
# Wir reduzieren die Datenmenge etwas (z.B. keine vollen Texte)
hits_summary = []
for hit in res.results:
# Falls Explanation an war, speichern wir den Breakdown, sonst die Scores
breakdown = None
if hit.explanation and hit.explanation.breakdown:
breakdown = hit.explanation.breakdown.model_dump()
hits_summary.append({
"node_id": hit.node_id,
"note_id": hit.note_id,
"total_score": hit.total_score,
"breakdown": breakdown, # Wichtig für Training!
"rank_semantic": hit.semantic_score,
"rank_edge": hit.edge_bonus
})
entry = {
"timestamp": time.time(),
"query_id": res.query_id,
"query_text": req.query,
"mode": req.mode,
"top_k": req.top_k,
"hits": hits_summary
}
try:
with open(SEARCH_LOG_FILE, "a", encoding="utf-8") as f:
f.write(json.dumps(entry, ensure_ascii=False) + "\n")
except Exception as e:
print(f"ERROR logging search: {e}")
def log_feedback(fb: FeedbackRequest):
"""
Speichert das User-Feedback.
"""
_ensure_log_dir()
entry = {
"timestamp": time.time(),
"query_id": fb.query_id,
"node_id": fb.node_id,
"score": fb.score,
"comment": fb.comment
}
try:
with open(FEEDBACK_LOG_FILE, "a", encoding="utf-8") as f:
f.write(json.dumps(entry, ensure_ascii=False) + "\n")
except Exception as e:
print(f"ERROR logging feedback: {e}")
+62 -45
View File
@@ -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)
+65
View File
@@ -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()