Lars
742792770c
Introduce a new method for persisting rejected edges for audit purposes, enhancing traceability and validation logic. Update the decision engine to utilize a generic fallback template for improved error handling during LLM validation. Revise documentation across multiple files to reflect the new versioning, context, and features related to Phase 3 validation, including automatic mirror edges and note-scope zones. This update ensures better graph integrity and validation accuracy in the ingestion process.
282 lines
13 KiB
Markdown
282 lines
13 KiB
Markdown
---
|
||
doc_type: concept
|
||
audience: architect, product_owner
|
||
scope: graph, logic, provenance, agentic_validation, note_scope
|
||
status: active
|
||
version: 4.5.8
|
||
context: "Fachliche Beschreibung des Wissensgraphen: Knoten, Kanten, Provenance, Matrix-Logik, WP-15c Multigraph-Support, WP-22 Scoring-Prinzipien, WP-24c Phase 3 Agentic Edge Validation und automatische Spiegelkanten."
|
||
---
|
||
|
||
# Konzept: Die Graph-Logik
|
||
|
||
**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.
|
||
|
||
## 1. Die Knoten (Nodes)
|
||
|
||
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 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.
|
||
|
||
### 1.2 Der Chunk (Das Suchobjekt)
|
||
Da LLMs (Large Language Models) nicht unendlich viel Text auf einmal lesen können, werden Notes in kleinere Segmente (**Chunks**) zerlegt.
|
||
* **Eigenschaften:** Vektor (Embedding 768d), Textfenster, Link zum Vorgänger/Nachfolger.
|
||
* **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, die durch die **Edge Registry** validiert werden.
|
||
|
||
### 2.1 Kanonische Typen & Aliase
|
||
Um eine konsistente mathematische Gewichtung zu garantieren, werden alle Kanten auf **kanonische Typen** normalisiert.
|
||
|
||
| Kanonischer Typ | Aliase (Beispiele) | Bedeutung |
|
||
| :--- | :--- | :--- |
|
||
| `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 mehrere 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:* 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 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 oder Matrix-Logik.
|
||
* *Vertrauen:* **Niedrig (0.7)**.
|
||
* *Bedeutung:* Systemseitige Heuristik. Diese Verbindungen dienen der Entdeckung neuer Pfade, haben aber weniger Gewicht als explizite Links.
|
||
|
||
**4. Structure (System-interne Verkettung)**
|
||
* *Quelle:* Automatische Struktur-Kanten (`belongs_to`, `next`, `prev`).
|
||
* *Vertrauen:* **Hoch (1.0)**.
|
||
* *Bedeutung:* Diese Kanten werden ausschließlich durch interne Prozesse erzeugt und sind durch die **Provenance Firewall** geschützt. Sie können weder durch Nutzer noch durch KI manipuliert werden.
|
||
|
||
### 2.3 Provenance Firewall (WP-15c)
|
||
|
||
Die **Edge Registry** (v0.8.0) implementiert eine strikte Trennung zwischen System-Kanten und Inhalts-Kanten:
|
||
|
||
* **Geschützte System-Kanten:** `next`, `prev`, `belongs_to` dürfen nur mit `provenance="structure"` gesetzt werden.
|
||
* **Blockierung:** Alle anderen Provenienzen (`explicit`, `semantic_ai`, `inherited`, `global_pool`, `rule`) werden bei System-Kanten blockiert und auf `related_to` zurückgesetzt.
|
||
* **Zweck:** Sichert die Graph-Integrität und verhindert Manipulationen an der internen Struktur.
|
||
|
||
---
|
||
|
||
## 3. Matrix-Logik (Kontext-Sensitivität)
|
||
|
||
Die Matrix-Logik bestimmt Kanten-Typen dynamisch anhand der Quell- und Ziel-Typen der verknüpften Notizen.
|
||
|
||
**Logik-Beispiele:**
|
||
* **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. 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. Section-basierte Links & Multigraph-Support
|
||
|
||
Seit v2.9.1 unterstützt Mindnet **Deep-Links** zu spezifischen Abschnitten innerhalb einer Note.
|
||
|
||
### 6.1 Link-Parsing & Self-Links (WP-15c)
|
||
|
||
Die Logik erkennt nun präzise **Obsidian-Anker** (`[[Note#Section]]`) und **Self-Links** (`[[#Section]]`):
|
||
|
||
* **Obsidian-Anker:** `[[Note#Section]]` wird in `target_id="Note"` und `target_section="Section"` aufgeteilt.
|
||
* **Self-Links:** `[[#Section]]` wird zu `target_id="current_note_id"` und `target_section="Section"` aufgelöst.
|
||
* **`target_id`:** Enthält nur den Note-Namen (z.B. "Mein Leitbild")
|
||
* **`target_section`:** Enthält den Abschnitts-Namen (z.B. "P3 – Disziplin")
|
||
|
||
**Vorteil:** Verhindert "Phantom-Knoten", die durch das Einbeziehen des Anchors in die `target_id` entstanden wären. Ermöglicht präzise Verlinkung innerhalb derselben Note.
|
||
|
||
### 6.2 Multigraph-Support
|
||
Die Edge-ID enthält nun einen `variant`-Parameter (die Section), sodass mehrere Kanten zwischen denselben Knoten existieren können, wenn sie auf verschiedene Sections zeigen:
|
||
* `[[Note#Section1]]` → Edge-ID: `src->tgt:kind@Section1`
|
||
* `[[Note#Section2]]` → Edge-ID: `src->tgt:kind@Section2`
|
||
|
||
### 6.3 Semantische Deduplizierung
|
||
Die Deduplizierung basiert auf dem `src->tgt:kind@sec` Key, um sicherzustellen, dass identische Links (gleiche Quelle, Ziel, Typ und Section) nicht mehrfach erstellt werden.
|
||
|
||
---
|
||
|
||
## 7. Automatische Spiegelkanten (Invers-Logik) - WP-24c v4.5.8
|
||
|
||
Das System erzeugt automatisch **Spiegelkanten** (Invers-Kanten) für explizite Verbindungen, um die Auffindbarkeit von Informationen zu verdoppeln.
|
||
|
||
### 7.1 Funktionsweise
|
||
|
||
**Beispiel:**
|
||
- **Explizite Kante:** Note A `depends_on: Note B`
|
||
- **Automatische Spiegelkante:** Note B `enforced_by: Note A`
|
||
|
||
**Vorteil:** Beide Richtungen sind durchsuchbar. Wenn du nach "Note B" suchst, findest du auch alle Notizen, die von "Note B" abhängen (via `enforced_by`).
|
||
|
||
### 7.2 Invers-Mapping
|
||
|
||
Die Edge Registry definiert für jeden Kanten-Typ das symmetrische Gegenstück:
|
||
- `depends_on` ↔ `enforced_by`
|
||
- `derived_from` ↔ `resulted_in`
|
||
- `impacts` ↔ `impacted_by`
|
||
- `blocks` ↔ `blocked_by`
|
||
- `next` ↔ `prev`
|
||
- `related_to` ↔ `related_to` (symmetrisch)
|
||
|
||
### 7.3 Priorität & Schutz
|
||
|
||
* **Explizite Kanten haben Vorrang:** Wenn du bereits beide Richtungen explizit gesetzt hast, wird keine automatische Spiegelkante erzeugt (keine Duplikate)
|
||
* **Höhere Wirksamkeit expliziter Kanten:** Explizit gesetzte Kanten haben höhere Confidence-Werte (`confidence: 1.0`) als automatisch generierte Spiegelkanten (`confidence: 0.9 * original`)
|
||
* **Provenance Firewall:** System-Kanten (`belongs_to`, `next`, `prev`) können nicht manuell überschrieben werden
|
||
|
||
### 7.4 Phase 2 Symmetrie-Injektion
|
||
|
||
Spiegelkanten werden am Ende des gesamten Imports (Phase 2) in einem Batch-Prozess injiziert:
|
||
- **Authority-Check:** Nur wenn keine explizite Kante existiert, wird die Spiegelkante erzeugt
|
||
- **ID-Konsistenz:** Verwendet exakt dieselbe ID-Generierung wie Phase 1 (inkl. `target_section`)
|
||
- **Logging:** `🔄 [SYMMETRY]` zeigt die erzeugten Spiegelkanten
|
||
|
||
---
|
||
|
||
## 8. Phase 3 Agentic Edge Validation - WP-24c v4.5.8
|
||
|
||
Das System implementiert ein finales Validierungs-Gate für alle Kanten mit `candidate:` Präfix, um "Geister-Verknüpfungen" zu verhindern und die Graph-Qualität zu sichern.
|
||
|
||
### 8.1 Trigger-Kriterium
|
||
|
||
Kanten erhalten `candidate:` Präfix, wenn sie:
|
||
- In `### Unzugeordnete Kanten` Sektionen stehen
|
||
- Von der Smart Edge Allocation als Kandidaten vorgeschlagen wurden
|
||
- Explizit als `candidate:` markiert wurden
|
||
|
||
### 8.2 Validierungsprozess
|
||
|
||
1. **Kontext-Optimierung:**
|
||
- **Note-Scope (`scope: note`):** LLM nutzt `note_summary` (Top 5 Chunks) oder `note_text` (aggregierter Gesamttext)
|
||
- **Chunk-Scope (`scope: chunk`):** LLM nutzt spezifischen Chunk-Text, falls verfügbar, sonst Note-Text
|
||
|
||
2. **LLM-Validierung:**
|
||
- Nutzt `ingest_validator` Profil (Temperature 0.0 für Determinismus)
|
||
- Prüft semantisch: "Passt diese Verbindung zum Kontext?"
|
||
- Binäre Entscheidung: YES (VERIFIED) oder NO (REJECTED)
|
||
|
||
3. **Ergebnis:**
|
||
- **VERIFIED:** `candidate:` Präfix wird entfernt, Kante wird persistiert
|
||
- **REJECTED:** Kante wird **nicht** in die Datenbank geschrieben (verhindert persistente "Geister-Verknüpfungen")
|
||
|
||
### 8.3 Fehlertoleranz
|
||
|
||
Das System unterscheidet zwischen:
|
||
- **Transienten Fehlern (Netzwerk, Timeout):** Kante wird erlaubt (Integrität vor Präzision)
|
||
- **Permanenten Fehlern (Config, Validation):** Kante wird abgelehnt (Graph-Qualität schützen)
|
||
|
||
### 8.4 Provenance nach Validierung
|
||
|
||
- **Vor Validierung:** `provenance: "candidate:global_pool"` oder `rule_id: "candidate:..."`
|
||
- **Nach VERIFIED:** `provenance: "global_pool"` oder `rule_id: "explicit"` (Präfix entfernt)
|
||
- **Nach REJECTED:** Kante existiert nicht im Graph (wird nicht persistiert)
|
||
|
||
---
|
||
|
||
## 9. Note-Scope vs. Chunk-Scope - WP-24c v4.2.0
|
||
|
||
Das System unterscheidet zwischen **Note-Scope** (globale Verbindungen) und **Chunk-Scope** (lokale Referenzen).
|
||
|
||
### 9.1 Chunk-Scope (Standard)
|
||
|
||
- **Quelle:** `source_id = chunk_id` (z.B. `note-id#c00`)
|
||
- **Kontext:** Spezifischer Textabschnitt (Chunk)
|
||
- **Verwendung:** Lokale Referenzen innerhalb eines Abschnitts
|
||
- **Phase 3 Validierung:** Nutzt spezifischen Chunk-Text
|
||
|
||
**Beispiel:**
|
||
```markdown
|
||
In diesem Abschnitt nutzen wir [[rel:uses|Technologie X]].
|
||
```
|
||
|
||
### 9.2 Note-Scope
|
||
|
||
- **Quelle:** `source_id = note_id` (nicht `chunk_id`)
|
||
- **Kontext:** Gesamte Note (Note-Summary oder Note-Text)
|
||
- **Verwendung:** Globale Verbindungen, die für die ganze Note gelten
|
||
- **Phase 3 Validierung:** Nutzt `note_summary` (Top 5 Chunks) oder `note_text` (aggregierter Gesamttext)
|
||
|
||
**Beispiel:**
|
||
```markdown
|
||
## Smart Edges
|
||
|
||
[[rel:depends_on|Projekt-Übersicht]]
|
||
[[rel:part_of|Größeres System]]
|
||
```
|
||
|
||
### 9.3 Priorität
|
||
|
||
Bei Duplikaten (gleiche Kante in Chunk-Scope und Note-Scope):
|
||
1. **Note-Scope Links** haben **höchste Priorität**
|
||
2. Dann Confidence-Wert
|
||
3. Dann Provenance-Priority
|
||
|
||
---
|
||
|
||
## 10. Idempotenz & Konsistenz
|
||
|
||
Das System garantiert fachliche Konsistenz auch bei mehrfachen Importen.
|
||
* **Stabile IDs:** Deterministische IDs verhindern Duplikate bei Re-Imports.
|
||
* **Deduplizierung:** Kanten werden anhand ihrer Identität (inkl. Section) erkannt. Die "stärkere" Provenance gewinnt.
|
||
* **Format-agnostische Erkennung:** Kanten werden unabhängig vom Format (Inline, Callout, Wikilink) erkannt, um Dopplungen zu vermeiden.
|
||
* **Phase 3 Validierung:** Verhindert persistente "Geister-Verknüpfungen" durch Ablehnung irrelevanter Kanten. |