This commit is contained in:
1 parent
d53912a8f1
commit
77a6db7e92
25 files changed
+1741
-490
No files matched your search
@@ -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.
|
||||
@@ -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
|
||||
@@ -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!
|
||||
Reference in new issue
Block a user