docs und vault
Deploy mindnet to llm-node / deploy (push) Successful in 4s

This commit is contained in:
Lars committed 2025-12-18 11:22:03 +01:00
1 parent d53912a8f1
commit 77a6db7e92
25 files changed
+1741 -490

No files matched your search

+89
View File
@@ -0,0 +1,89 @@
---
doc_type: reference
audience: author
status: active
context: "Zentrales Wörterbuch für Kanten-Bezeichner (Edges). Referenz für Autoren zur Wahl des richtigen Verbindungstyps."
---
# Edge Vocabulary & Semantik
**Standort:** `01_User_Manual/01_edge_vocabulary.md`
**Zweck:** Damit Mindnet "verstehen" kann, was eine Verbindung bedeutet (z.B. für "Warum"-Fragen), nutzen wir konsistente Begriffe.
**Die Goldene Regel:**
Nutze bevorzugt den **System-Typ** (linke Spalte). Wenn dieser sprachlich nicht passt, nutze einen der **erlaubten Aliasse** (und bleibe dabei konsistent).
---
## 1. Kausalität & Logik ("Warum?")
*Verbindungen, die Gründe, Ursachen oder Herleitungen beschreiben.*
| System-Typ (Canonical) | Erlaubte Aliasse (User) | Wann nutzen? |
| :--- | :--- | :--- |
| **`caused_by`** | `ausgelöst_durch`, `wegen`, `ursache_ist` | Wenn A der direkte Auslöser für B ist. (Technisch/Faktisch) |
| **`derived_from`** | `abgeleitet_von`, `quelle`, `inspiriert_durch` | Wenn eine Idee/Prinzip aus einer Quelle stammt (z.B. Buch, Zitat). |
| **`based_on`** | `basiert_auf`, `fundament`, `grundlage` | Wenn B nicht existieren könnte ohne das fundamentale Konzept A (z.B. Werte). |
| **`solves`** | `löst`, `beantwortet`, `fix_für` | Wenn A eine Lösung für das Problem B ist. |
## 2. Struktur & Hierarchie ("Wo gehört es hin?")
*Verbindungen, die Ordnung schaffen.*
| System-Typ (Canonical) | Erlaubte Aliasse (User) | Wann nutzen? |
| :--- | :--- | :--- |
| **`part_of`** | `teil_von`, `gehört_zu`, `cluster` | Harte Hierarchie. Projekt A ist Teil von Programm B. |
| **`belongs_to`** | *(System-Intern)* | Automatisch generiert (Chunk -> Note). Nicht manuell nutzen. |
## 3. Abhängigkeit & Einfluss ("Was brauche ich?")
*Verbindungen, die Blockaden oder Voraussetzungen definieren.*
| System-Typ (Canonical) | Erlaubte Aliasse (User) | Wann nutzen? |
| :--- | :--- | :--- |
| **`depends_on`** | `hängt_ab_von`, `braucht`, `requires`, `enforced_by` | Harte Abhängigkeit. Ohne A kann B nicht starten/existieren. |
| **`blocks`** | `blockiert`, `verhindert`, `risiko_für` | Wenn A ein aktives Hindernis für B ist. |
| **`uses`** | `nutzt`, `verwendet`, `tool` | Wenn A ein Werkzeug/Methode B einsetzt (z.B. Projekt nutzt Python). |
| **`guides`** | `steuert`, `leitet`, `orientierung` | (Alias für `depends_on` oder `related_to`) Weiche Abhängigkeit, z.B. Prinzipien steuern Verhalten. |
## 4. Zeit & Prozess ("Was kommt dann?")
*Verbindungen für Abläufe zwischen verschiedenen Notizen.*
| System-Typ (Canonical) | Erlaubte Aliasse (User) | Wann nutzen? |
| :--- | :--- | :--- |
| **`next`** | `danach`, `folgt`, `nachfolger`, `followed_by` | Manuell: Wenn Notiz A logisch vor Notiz B kommt (Prozesskette: A -> B). |
| **`prev`** | `davor`, `vorgänger`, `preceded_by` | Manuell: Der vorherige Prozessschritt (B -> A). |
## 5. Assoziation ("Was ist ähnlich?")
*Lose Verbindungen für Entdeckungen.*
| System-Typ (Canonical) | Erlaubte Aliasse (User) | Wann nutzen? |
| :--- | :--- | :--- |
| **`related_to`** | `siehe_auch`, `kontext`, `thematisch` | Wenn zwei Dinge etwas miteinander zu tun haben, ohne strikte Logik. |
| **`similar_to`** | `ähnlich_wie`, `vergleichbar` | Wenn A und B fast das Gleiche sind (z.B. Synonyme, Alternativen). |
| **`references`** | *(Kein Alias)* | Standard für "erwähnt einfach nur". (Niedrigste Prio). |
---
## Best Practices für Autoren
### A. Der "Callout"-Standard (Footer)
Sammle Verbindungen, die für die **ganze Notiz** gelten, am Ende der Datei in einem Bereich `## Kontext & Verbindungen`.
```markdown
## Kontext & Verbindungen
> [!edge] derived_from
> [[Buch der Weisen]]
> [!edge] part_of
> [[Leitbild – Identity Core]]
```
### B. Der "Inline"-Standard (Präzision)
Nutze Inline-Kanten nur, wenn du im Fließtext eine **spezifische Aussage** triffst, die im Graph sichtbar sein soll.
* *Schlecht:* "Das [[rel:related_to Projekt]] ist wichtig." (Wenig Aussagekraft)
* *Gut:* "Dieser Fehler wird [[rel:caused_by Systemabsturz]] verursacht." (Starke Kausalität)
### C. Konsistenz-Check
Bevor du ein neues Wort (z.B. `ermöglicht`) nutzt:
1. Prüfe diese Liste: Passt `solves` oder `depends_on`?
2. Falls nein: Schreibe `ermöglicht` in die Spalte "Erlaubte Aliasse" oben und ordne es einem System-Typ zu.
+26 -1
View File
@@ -45,6 +45,8 @@ Eine Übersicht der implementierten Features zum schnellen Auffinden von Funktio
| **WP-11** | Backend Intelligence | `nomic-embed-text` (768d) und Matrix-Logik für Kanten-Typisierung. |
| **WP-15** | Smart Edge Allocation | LLM-Filter für Kanten in Chunks + Traffic Control (Semaphore) + Strict Chunking. |
| **WP-19** | Graph Visualisierung | **Frontend Modularisierung:** Umbau auf `ui_*.py`.<br>**Graph Engines:** Parallelbetrieb von Cytoscape (COSE) und Agraph.<br>**Tools:** "Single Source of Truth" Editor, Persistenz via URL. |
| **WP-20** | Cloud Hybrid Mode | Nutzung von Public LLM für schnellere Verarbeitung und bestimmte Aufgaben |
| **WP-21** | Semantic Graph Routing & Canonical Edges | Transformation des Graphen von statischen Verbindungen zu dynamischen, kontextsensitiven Pfaden. Das System soll verstehen, *welche* Art von Verbindung für die aktuelle Frage relevant ist ("Warum?" vs. "Was kommt danach?"). |
---
@@ -102,6 +104,25 @@ Diese Features stehen als nächstes an oder befinden sich in der Umsetzung.
**Ziel:** "Turbo-Modus" für Massen-Imports.
* **Konzept:** Switch in `.env`, um statt Ollama (Lokal) auf Google Gemini (Cloud) umzuschalten.
### WP-21 – Semantic Graph Routing & Canonical Edges
**Status:** 🟡 Geplant
**Ziel:** Transformation des Graphen von statischen Verbindungen zu dynamischen, kontextsensitiven Pfaden. Das System soll verstehen, *welche* Art von Verbindung für die aktuelle Frage relevant ist ("Warum?" vs. "Was kommt danach?").
**Problem:**
1. **Statische Gewichte:** Aktuell ist `caused_by` immer gleich wichtig (z.B. 1.2), egal ob der User nach Ursachen oder Definitionen fragt.
2. **Vokabular-Zwang:** Der Nutzer muss exakte System-Begriffe (`caused_by`) verwenden. Natürliche Synonyme (`führt_zu`, `ausgelöst_durch`) werden als unbekannte Kanten ignoriert oder nicht speziell gewichtet.
**Lösungsansätze & Kern-Features:**
1. **Canonical Edge Mapping (Middleware):**
* Einführung einer Mapping-Schicht (z.B. in `edges.yaml`).
* *Funktion:* Normalisiert User-Vokabular (`leads_to`, `triggers`, `starts`) automatisch auf System-Typen (`caused_by`).
* *Benefit:* Maximale Schreibfreiheit für den Nutzer bei gleichzeitiger System-Konsistenz.
2. **Dynamic Intent Boosting (Query-Time):**
* Erweiterung der `Decision Engine`.
* *Funktion:* Der Router erkennt den Intent der Frage (z.B. `EXPLANATION` für "Warum-Fragen") und injiziert temporäre `edge_weights` in den Retriever.
* *Beispiel:* Bei "Warum ist das passiert?" wird `caused_by` von 1.2 auf 2.5 geboostet, während `related_to` auf 0.1 sinkt.
3. **Graph Reasoning:**
* Der Retriever priorisiert Pfade, die dem semantischen Muster der Frage entsprechen, nicht nur dem Text-Match.
---
## 4. Abhängigkeiten & Release-Plan
@@ -113,4 +134,8 @@ graph TD
WP15(Smart Edges) --> WP16(Auto-Discovery)
WP15 --> WP14(Refactoring)
WP03(Import) --> WP18(Health Check)
WP03/WP04 --> WP13(MCP)
WP03/WP04 --> WP13(MCP)
graph TD
WP06(Decision Engine) --> WP21(Semantic Routing)
WP03(Import Pipeline) --> WP21
WP15(Smart Edges) --> WP21
+55 -1
View File
@@ -199,4 +199,58 @@ Wir starten **WP-18: Graph Health & Maintenance**.
- Keine Datenlöschung ohne Log-Eintrag.
Bitte bestätige und skizziere die Logik für den Transactional Hash Update.
```
```
## WP-21: Semantic Graph Routing
**Status:** 🟡 Geplant
**Fokus:** Graph-Logik, Retrieval-Präzision, User-Experience.
```text
Du bist der Lead Architect für "Mindnet" (v2.7.0).
Wir starten **WP-21: Semantic Graph Routing**.
**Status Quo:**
- Edge-Gewichte sind statisch in `retriever.yaml` definiert.
- User müssen exakte Edge-Typen (`caused_by`) nutzen; Synonyme werden nicht erkannt.
- Der `HybridRouter` (WP-06) erkennt Intents, nutzt diese aber nur für Note-Typen (`inject_types`), nicht für Kanten.
**Dein Auftrag (WP-21):**
Implementiere eine semantische Steuerung für den Graphen, die (A) Schreibfreiheit erlaubt und (B) die Suche kontextabhängig macht.
**Technische Anforderungen:**
1. **Canonical Edge Mapping (Ingestion-Layer):**
- Erstelle eine neue Config `config/edge_mappings.yaml` (oder erweitere `types.yaml`).
- Definiere Mappings: `User-Synonym` -> `System-Canonical` (z.B. `["führt_zu", "resultat"]` -> `caused_by`).
- Erweitere `import_markdown.py` / `Chunker`: Mappe beim Einlesen alle Inline/Callout-Kanten auf den Canonical-Typ, *bevor* sie in Qdrant gespeichert werden. (Speichere das Original ggf. als Metadatum).
2. **Dynamic Boosting (Retrieval-Layer):**
- Erweitere die `DecisionEngine` (`app/services/decision_engine.py` und YAML).
- Füge `boost_edges` zu den Strategien hinzu (z.B. `strategy: EXPLANATION` -> `boost: {caused_by: 2.0}`).
- Passe den `Retriever` an, um diese dynamischen Gewichte im Query-Moment mit den statischen Config-Werten zu verrechnen (Multiplikator).
**Zielbild:**
- User schreibt: `[[rel:wegen Systemfehler]]`.
- System speichert: `caused_by` -> `Systemfehler`.
- User fragt: "Warum Absturz?".
- System erkennt "Warum" -> Boostet `caused_by` -> Findet die Notiz präzise.
**Regeln:**
- Abwärtskompatibilität wahren (alte Kanten müssen weiter funktionieren).
- Performance: Das Mapping muss O(1) sein (Hashmap Lookup), kein LLM-Call pro Kante!
Bitte bestätige die Übernahme, erstelle die `edge_mappings.yaml` Struktur und skizziere die Anpassung im `Retriever`.
---
### Warum diese Lösungsansätze?
1. **Warum Mapping beim Import (Ingestion) und nicht bei der Suche?**
* **Performance:** Es ist viel effizienter, die Daten *einmal* beim Schreiben zu säubern ("Canonical Form"), als bei *jeder* Suche tausende Synonyme abzufragen.
* **Konsistenz:** Der Graph in Qdrant bleibt sauber. `caused_by` ist immer `caused_by`, egal ob der User `wegen`, `durch` oder `ursache` geschrieben hat.
2. **Warum Boosting über die Decision Engine?**
* Wir haben den `HybridRouter` (aus WP-06) schon. Er "versteht" bereits, was der User will (`DECISION` vs `EMPATHY`).
* Es ist der logisch perfekte Ort, um zu sagen: "Wenn der User im Analyse-Modus ist, sind Fakten-Kanten wichtiger als Gefühls-Kanten."
Damit hast du das perfekte Paket für den nächsten Entwicklungsschritt geschnürt!