Compare commits

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