doku
This commit is contained in:
1 parent
0d71f41a13
commit
2cd3605017
8 files changed
+334
-263
No files matched your search
@@ -3,13 +3,13 @@ doc_type: concept
|
||||
audience: architect, product_owner
|
||||
scope: graph, logic, provenance
|
||||
status: active
|
||||
version: 2.6
|
||||
context: "Fachliche Beschreibung des Wissensgraphen: Knoten, Kanten, Provenance und Matrix-Logik."
|
||||
version: 2.7.0
|
||||
context: "Fachliche Beschreibung des Wissensgraphen: Knoten, Kanten, Provenance, Matrix-Logik und WP-22 Scoring-Prinzipien."
|
||||
---
|
||||
|
||||
# Konzept: Die Graph-Logik
|
||||
|
||||
**Quellen:** `mindnet_functional_architecture.md`, `chunking_strategy.md`
|
||||
**Quellen:** `mindnet_functional_architecture.md`, `chunking_strategy.md`, `01_edge_vocabulary.md`, `retriever_scoring.py`, `03_tech_retrieval_scoring.md`
|
||||
|
||||
Mindnet ist keine reine Dokumentablage, sondern ein **semantischer Graph**. Dieses Dokument beschreibt, wie aus statischen Textdateien ein vernetztes Wissensobjekt wird.
|
||||
|
||||
@@ -19,7 +19,7 @@ Der Graph besteht aus zwei Ebenen von Knoten.
|
||||
|
||||
### 1.1 Die Note (Das Fachobjekt)
|
||||
Eine Note repräsentiert ein atomares Konzept (z.B. "Projekt Alpha").
|
||||
* **Eigenschaften:** Titel, Typ, Tags, Erstellungsdatum.
|
||||
* **Eigenschaften:** Titel, Typ, Tags, Erstellungsdatum sowie der **Status** (Lifecycle).
|
||||
* **Rolle:** Sie ist der Container für Metadaten und steuert via `type`, wie der Inhalt verarbeitet wird (siehe `types.yaml`).
|
||||
* **Identität:** Definiert durch eine deterministische UUIDv5.
|
||||
|
||||
@@ -29,71 +29,97 @@ Da LLMs (Large Language Models) nicht unendlich viel Text auf einmal lesen könn
|
||||
* **Rolle:** Dies sind die eigentlichen Treffer bei einer Suche.
|
||||
* **Hierarchie:** Jeder Chunk gehört streng zu einer Note (`belongs_to`).
|
||||
|
||||
### 1.3 Content Lifecycle & Status (WP-22)
|
||||
Seit v2.7 beeinflusst der `status` einer Note direkt deren Gewichtung im Retrieval (Lifecycle Scoring).
|
||||
* **Stable:** Notizen mit `status: stable` erhalten einen positiven Modifier (Standard: 1.0), da sie geprüftes Wissen repräsentieren.
|
||||
* **Draft:** Notizen mit `status: draft` werden durch einen Malus (Standard: 0.5 - 0.8) herabgestuft, um "Rauschen" durch unfertige Gedanken zu reduzieren.
|
||||
* **System/Template:** Diese Status-Typen führen zu einem vollständigen Ausschluss aus dem Index.
|
||||
|
||||
---
|
||||
|
||||
## 2. Die Kanten (Edges)
|
||||
|
||||
Kanten machen aus isolierten Informationen Wissen. Mindnet nutzt gerichtete Kanten mit semantischer Bedeutung.
|
||||
Kanten machen aus isolierten Informationen Wissen. Mindnet nutzt gerichtete Kanten mit semantischer Bedeutung, die durch die **Edge Registry** validiert werden.
|
||||
|
||||
### 2.1 Semantische Typen
|
||||
### 2.1 Kanonische Typen & Aliase
|
||||
Um eine konsistente mathematische Gewichtung zu garantieren, werden alle Kanten auf **kanonische Typen** normalisiert.
|
||||
|
||||
| Kanten-Typ | Frage, die er beantwortet | Beispiel |
|
||||
| Kanonischer Typ | Aliase (Beispiele) | Bedeutung |
|
||||
| :--- | :--- | :--- |
|
||||
| `references` | Worüber wird gesprochen? | Text erwähnt "Python". |
|
||||
| `depends_on` | Was ist Voraussetzung? | Projekt braucht "Budget". |
|
||||
| `caused_by` | Warum ist das passiert? | Bug durch "Commit X". |
|
||||
| `blocks` | Was steht im Weg? | Risiko blockiert "Release". |
|
||||
| `based_on` | Worauf fußt das? | Erfahrung basiert auf "Wert Y". |
|
||||
| `derived_from` | Woher kommt das? | Prinzip stammt aus "Buch Z". |
|
||||
| `related_to` | Was ist ähnlich? | "Hund" ist verwandt mit "Wolf". |
|
||||
| `solves` | Was ist die Lösung? | "Qdrant" löst "Vektorsuche". |
|
||||
| `caused_by` | `ausgelöst_durch`, `wegen` | Kausalität: A löst B aus. |
|
||||
| `derived_from` | `abgeleitet_von`, `quelle` | Herkunft: A stammt von B. |
|
||||
| `based_on` | `basiert_auf`, `fundament` | Fundament: B baut auf A auf. |
|
||||
| `solves` | `löst`, `fix_für` | Lösung: A ist Lösung für Problem B. |
|
||||
| `part_of` | `teil_von`, `cluster` | Hierarchie: Kind -> Eltern. |
|
||||
| `depends_on` | `braucht`, `requires` | Abhängigkeit: A braucht B. |
|
||||
| `blocks` | `blockiert`, `risiko_für` | Blocker: A verhindert B. |
|
||||
| `related_to` | `siehe_auch`, `kontext` | Lose Assoziation. |
|
||||
|
||||
|
||||
|
||||
### 2.2 Provenance (Herkunft & Vertrauen)
|
||||
|
||||
Nicht alle Kanten sind gleich viel wert. Mindnet unterscheidet in v2.6 drei Qualitätsstufen (**Provenance**), um Konflikte aufzulösen.
|
||||
Nicht alle Kanten sind gleich viel wert. Mindnet unterscheidet drei Qualitätsstufen (**Provenance**), um bei der Berechnung des Edge-Bonus Prioritäten zu setzen.
|
||||
|
||||
**1. Explicit (Der Mensch hat es gesagt)**
|
||||
* *Quelle:* Inline-Links (`[[rel:...]]`) oder Wikilinks im Text.
|
||||
* *Vertrauen:* **Hoch (1.0)**.
|
||||
* *Bedeutung:* Dies ist hartes Faktenwissen. "Ich habe diesen Link bewusst gesetzt."
|
||||
* *Bedeutung:* Hartes Faktenwissen. Die explizite menschliche Intention wird im Scoring am stärksten gewichtet.
|
||||
|
||||
**2. Smart (Die KI hat es bestätigt)**
|
||||
* *Quelle:* Smart Edge Allocation (WP15).
|
||||
* *Vertrauen:* **Mittel (0.9)**.
|
||||
* *Bedeutung:* Ein LLM hat geprüft, ob der Link im Kontext dieses Textabschnitts wirklich relevant ist. Dies filtert "Rauschen" heraus (z.B. Links im Footer, die nichts mit dem Absatz zu tun haben).
|
||||
* *Bedeutung:* Ein LLM hat die Relevanz des Links im Kontext geprüft. Dies filtert irrelevante Links (z.B. aus Navigationsleisten) heraus.
|
||||
|
||||
**3. Rule (Die Regel hat es vermutet)**
|
||||
* *Quelle:* `types.yaml` Defaults.
|
||||
* *Quelle:* `types.yaml` Defaults oder Matrix-Logik.
|
||||
* *Vertrauen:* **Niedrig (0.7)**.
|
||||
* *Bedeutung:* Eine Heuristik. "Weil es ein Projekt ist, nehmen wir an, dass es von allen erwähnten Technologien abhängt."
|
||||
* *Bedeutung:* Systemseitige Heuristik. Diese Verbindungen dienen der Entdeckung neuer Pfade, haben aber weniger Gewicht als explizite Links.
|
||||
|
||||
---
|
||||
|
||||
## 3. Matrix-Logik (Kontext-Sensitivität)
|
||||
|
||||
Mit WP11 wurde eine Intelligenz eingeführt, die Kanten-Typen nicht nur anhand des Quell-Typs, sondern auch anhand des Ziel-Typs bestimmt ("Matrix").
|
||||
Die Matrix-Logik bestimmt Kanten-Typen dynamisch anhand der Quell- und Ziel-Typen der verknüpften Notizen.
|
||||
|
||||
**Logik-Beispiele:**
|
||||
|
||||
* **Quelle `experience` → Ziel `value`**
|
||||
* *Standard:* `references`
|
||||
* *Matrix:* `based_on` (Erfahrungen basieren auf Werten).
|
||||
|
||||
* **Quelle `principle` → Ziel `source` (Buch)**
|
||||
* *Standard:* `references`
|
||||
* *Matrix:* `derived_from` (Prinzipien stammen aus Quellen).
|
||||
|
||||
* **Quelle `project` → Ziel `tool`**
|
||||
* *Standard:* `references`
|
||||
* *Matrix:* `uses` (Projekte nutzen Tools).
|
||||
|
||||
*Nutzen:* Dies erlaubt im Chat präzise Fragen wie: *"Auf welchen Werten basiert diese Entscheidung?"* (Suche nach eingehenden `based_on` Kanten).
|
||||
* **Quelle `experience` → Ziel `value`**: Wird zu `based_on` (Erfahrungen fußen auf Werten).
|
||||
* **Quelle `principle` → Ziel `source`**: Wird zu `derived_from` (Prinzipien stammen aus Quellen).
|
||||
|
||||
---
|
||||
|
||||
## 4. Idempotenz & Konsistenz
|
||||
## 4. Semantisch bezogene Booster & Scoring-Logik
|
||||
|
||||
Das Scoring in Mindnet v2.7 folgt einer hybriden Logik, bei der semantische Ähnlichkeit durch kontextuelle Faktoren modifiziert wird.
|
||||
|
||||
### 4.1 Semantische Modifikatoren (Type & Status)
|
||||
Bevor der Graph-Bonus berechnet wird, durchläuft die semantische Ähnlichkeit (Cosine Similarity) zwei Filter:
|
||||
1. **Type-Weight ($W_{type}$):** Bestimmt die "Wichtigkeit" einer Notizklasse. Ein Wert von 1.0 (z. B. für `decision`) lässt die volle semantische Stärke durch. Ein Wert von 0.4 (z. B. für `glossary`) dämpft den Treffer massiv ab, es sei denn, die Frage passt exakt auf den Text.
|
||||
2. **Status-Modifier:** Agiert als Qualitätsfilter. `draft` markierte Inhalte werden herabgestuft, damit `stable` Inhalte bei gleicher semantischer Passung immer oben stehen.
|
||||
|
||||
### 4.2 Graph-Boosting (Additive Boni)
|
||||
Der Graph-Bonus wird auf den modifizierten semantischen Score addiert. Dies ermöglicht es Inhalten, im Ranking nach oben zu steigen, wenn sie stark mit anderen relevanten Treffern vernetzt sind.
|
||||
|
||||
| Parameter-Gruppe | Wertebereich | Logik |
|
||||
| :--- | :--- | :--- |
|
||||
| **Notiz-Gewichte** | 0.1 - 1.0 | Multiplikativ. Dient als Relevanz-Filter für Informationstypen. |
|
||||
| **Kanten-Boosts** | 0.1 - 3.0+ | Additiv. Hebt vernetztes Wissen über isolierte Texttreffer. |
|
||||
| **Status-Malus** | 0.5 - 0.9 | Multiplikativ. Bestraft unfertiges Wissen (Drafts). |
|
||||
|
||||
---
|
||||
|
||||
## 5. Dynamic Intent Boosting (WP-22)
|
||||
|
||||
In v2.7 ist die Graph-Gewichtung nicht mehr statisch, sondern hängt vom **Intent** der Nutzerfrage ab (Query-Time Boosting).
|
||||
|
||||
Der Intent-Router injiziert spezifische Multiplikatoren für kanonische Typen:
|
||||
* **Intent `EMPATHY`**: Boostet `based_on` (Fokus auf Werte).
|
||||
* **Intent `WHY`**: Boostet `caused_by` (Fokus auf Ursachenforschung).
|
||||
|
||||
---
|
||||
|
||||
## 6. Idempotenz & Konsistenz
|
||||
|
||||
Das System garantiert fachliche Konsistenz auch bei mehrfachen Importen.
|
||||
* **Stabile IDs:** Importiert man dieselbe Datei zweimal, ändern sich die IDs der Knoten nicht.
|
||||
* **Keine Duplikate:** Kanten werden dedupliziert. Die "stärkere" Quelle (Explicit > Smart > Rule) gewinnt.
|
||||
* **Lösch-Garantie:** Wenn eine Notiz gelöscht wird, verschwinden auch alle ihre Chunks und ausgehenden Kanten (via `--sync-deletes`).
|
||||
* **Stabile IDs:** Deterministische IDs verhindern Duplikate bei Re-Imports.
|
||||
* **Deduplizierung:** Kanten werden anhand ihrer Identität erkannt. Die "stärkere" Provenance gewinnt.
|
||||
Reference in new issue
Block a user