Update graph_db_adapter.py, graph_derive_edges.py, graph_subgraph.py, graph_utils.py, ingestion_processor.py, and retriever.py to version 4.1.0: Introduce Scope-Awareness and Section-Filtering features, enhancing edge retrieval and processing. Implement Note-Scope Zones extraction from Markdown, improve edge ID generation with target_section, and prioritize Note-Scope Links during de-duplication. Update documentation for clarity and consistency across modules.
This commit is contained in:
1 parent
be2bed9927
commit
39fd15b565
14 files changed
+1004
-37
No files matched your search
@@ -0,0 +1,253 @@
|
||||
# LLM-Validierung von Links in Notizen
|
||||
|
||||
**Version:** v4.1.0
|
||||
**Status:** Aktiv
|
||||
|
||||
## Übersicht
|
||||
|
||||
Das Mindnet-System unterstützt zwei Arten von Links:
|
||||
|
||||
1. **Explizite Links** - Werden direkt übernommen (keine Validierung)
|
||||
2. **Global Pool Links** - Werden vom LLM validiert (wenn aktiviert)
|
||||
|
||||
## Explizite Links (keine Validierung)
|
||||
|
||||
Diese Links werden **sofort** in den Graph übernommen, ohne LLM-Validierung:
|
||||
|
||||
### 1. Typed Relations
|
||||
```markdown
|
||||
[[rel:mastered_by|Klaus]]
|
||||
[[rel:depends_on|Projekt Alpha]]
|
||||
```
|
||||
|
||||
### 2. Standard Wikilinks
|
||||
```markdown
|
||||
[[Klaus]]
|
||||
[[Projekt Alpha]]
|
||||
```
|
||||
|
||||
### 3. Callouts
|
||||
```markdown
|
||||
> [!edge] mastered_by:Klaus
|
||||
> [!edge] depends_on:Projekt Alpha
|
||||
```
|
||||
|
||||
**Hinweis:** Explizite Links haben immer Vorrang und werden nicht validiert.
|
||||
|
||||
## Global Pool Links (mit LLM-Validierung)
|
||||
|
||||
Links, die vom LLM validiert werden sollen, müssen in einer speziellen Sektion am Ende der Notiz definiert werden.
|
||||
|
||||
### Format
|
||||
|
||||
Erstellen Sie eine Sektion mit einem der folgenden Titel:
|
||||
- `### Unzugeordnete Kanten`
|
||||
- `### Edge Pool`
|
||||
- `### Candidates`
|
||||
|
||||
In dieser Sektion listen Sie Links im Format `kind:target` auf:
|
||||
|
||||
```markdown
|
||||
---
|
||||
type: concept
|
||||
title: Meine Notiz
|
||||
---
|
||||
|
||||
# Inhalt der Notiz
|
||||
|
||||
Hier ist der normale Inhalt...
|
||||
|
||||
### Unzugeordnete Kanten
|
||||
|
||||
related_to:Klaus
|
||||
mastered_by:Projekt Alpha
|
||||
depends_on:Andere Notiz
|
||||
```
|
||||
|
||||
### Beispiel
|
||||
|
||||
```markdown
|
||||
---
|
||||
type: decision
|
||||
title: Entscheidung über Technologie-Stack
|
||||
---
|
||||
|
||||
# Entscheidung über Technologie-Stack
|
||||
|
||||
Wir haben uns für React entschieden, weil...
|
||||
|
||||
## Begründung
|
||||
|
||||
React bietet bessere Performance...
|
||||
|
||||
### Unzugeordnete Kanten
|
||||
|
||||
related_to:React-Dokumentation
|
||||
depends_on:Performance-Analyse
|
||||
uses:TypeScript
|
||||
```
|
||||
|
||||
### Validierung
|
||||
|
||||
**Wichtig:** Global Pool Links werden nur validiert, wenn:
|
||||
|
||||
1. Die Chunk-Konfiguration `enable_smart_edge_allocation: true` enthält
|
||||
2. Dies wird normalerweise in `config/types.yaml` pro Note-Typ konfiguriert
|
||||
|
||||
**Beispiel-Konfiguration in `types.yaml`:**
|
||||
|
||||
```yaml
|
||||
types:
|
||||
decision:
|
||||
chunking_profile: sliding_smart_edges
|
||||
chunking:
|
||||
sliding_smart_edges:
|
||||
enable_smart_edge_allocation: true # ← Aktiviert LLM-Validierung
|
||||
```
|
||||
|
||||
### Validierungsprozess
|
||||
|
||||
1. **Extraktion:** Links aus der "Unzugeordnete Kanten" Sektion werden extrahiert
|
||||
2. **Provenance:** Erhalten `provenance: "global_pool"`
|
||||
3. **Validierung:** Für jeden Link wird geprüft:
|
||||
- Ist der Link semantisch relevant für den Chunk-Kontext?
|
||||
- Passt die Relation (`kind`) zum Ziel?
|
||||
4. **Ergebnis:**
|
||||
- ✅ **YES** → Link wird in den Graph übernommen
|
||||
- ❌ **NO** → Link wird verworfen
|
||||
|
||||
### Validierungs-Prompt
|
||||
|
||||
Das System verwendet den Prompt `edge_validation` aus `config/prompts.yaml`:
|
||||
|
||||
```
|
||||
Verify relation '{edge_kind}' for graph integrity.
|
||||
Chunk: "{chunk_text}"
|
||||
Target: "{target_title}" ({target_summary})
|
||||
Respond ONLY with 'YES' or 'NO'.
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### ✅ Empfohlen
|
||||
|
||||
1. **Explizite Links für sichere Verbindungen:**
|
||||
```markdown
|
||||
Diese Entscheidung [[rel:depends_on|Performance-Analyse]] wurde getroffen.
|
||||
```
|
||||
|
||||
2. **Global Pool für unsichere/explorative Links:**
|
||||
```markdown
|
||||
### Unzugeordnete Kanten
|
||||
related_to:Mögliche Verbindung
|
||||
```
|
||||
|
||||
3. **Kombination beider Ansätze:**
|
||||
```markdown
|
||||
# Hauptinhalt
|
||||
|
||||
Explizite Verbindung: [[rel:depends_on|Sichere Notiz]]
|
||||
|
||||
## Weitere Überlegungen
|
||||
|
||||
### Unzugeordnete Kanten
|
||||
related_to:Unsichere Verbindung
|
||||
explored_in:Experimentelle Notiz
|
||||
```
|
||||
|
||||
### ❌ Vermeiden
|
||||
|
||||
1. **Nicht zu viele Global Pool Links:**
|
||||
- Jeder Link erfordert einen LLM-Aufruf
|
||||
- Kann die Ingestion verlangsamen
|
||||
|
||||
2. **Nicht für offensichtliche Links:**
|
||||
- Nutzen Sie explizite Links für klare Verbindungen
|
||||
- Global Pool ist für explorative/unsichere Links gedacht
|
||||
|
||||
## Aktivierung der Validierung
|
||||
|
||||
### Schritt 1: Chunk-Profile konfigurieren
|
||||
|
||||
In `config/types.yaml`:
|
||||
|
||||
```yaml
|
||||
types:
|
||||
your_type:
|
||||
chunking_profile: sliding_smart_edges
|
||||
chunking:
|
||||
sliding_smart_edges:
|
||||
enable_smart_edge_allocation: true
|
||||
```
|
||||
|
||||
### Schritt 2: Notiz erstellen
|
||||
|
||||
```markdown
|
||||
---
|
||||
type: your_type
|
||||
title: Meine Notiz
|
||||
---
|
||||
|
||||
# Inhalt
|
||||
|
||||
### Unzugeordnete Kanten
|
||||
|
||||
related_to:Ziel-Notiz
|
||||
```
|
||||
|
||||
### Schritt 3: Import ausführen
|
||||
|
||||
```bash
|
||||
python3 -m scripts.import_markdown --vault ./vault --apply
|
||||
```
|
||||
|
||||
## Logging & Debugging
|
||||
|
||||
Während der Ingestion sehen Sie im Log:
|
||||
|
||||
```
|
||||
⚖️ [VALIDATING] Relation 'related_to' -> 'Ziel-Notiz' (Profile: ingest_validator)...
|
||||
✅ [VALIDATED] Relation to 'Ziel-Notiz' confirmed.
|
||||
```
|
||||
|
||||
oder
|
||||
|
||||
```
|
||||
🚫 [REJECTED] Relation to 'Ziel-Notiz' irrelevant for this chunk.
|
||||
```
|
||||
|
||||
## Technische Details
|
||||
|
||||
### Provenance-System
|
||||
|
||||
- `explicit`: Explizite Links (keine Validierung)
|
||||
- `global_pool`: Global Pool Links (mit Validierung)
|
||||
- `semantic_ai`: KI-generierte Links
|
||||
- `rule`: Regel-basierte Links (z.B. aus types.yaml)
|
||||
|
||||
### Code-Referenzen
|
||||
|
||||
- **Extraktion:** `app/core/chunking/chunking_processor.py` (Zeile 66-81)
|
||||
- **Validierung:** `app/core/ingestion/ingestion_validation.py`
|
||||
- **Integration:** `app/core/ingestion/ingestion_processor.py` (Zeile 237-239)
|
||||
|
||||
## FAQ
|
||||
|
||||
**Q: Werden explizite Links auch validiert?**
|
||||
A: Nein, explizite Links werden direkt übernommen.
|
||||
|
||||
**Q: Kann ich die Validierung für bestimmte Links überspringen?**
|
||||
A: Ja, nutzen Sie explizite Links (`[[rel:kind|target]]` oder `> [!edge]`).
|
||||
|
||||
**Q: Was passiert, wenn das LLM nicht verfügbar ist?**
|
||||
A: Bei transienten Fehlern (Netzwerk) werden Links erlaubt. Bei permanenten Fehlern werden sie verworfen.
|
||||
|
||||
**Q: Kann ich mehrere Links in einer Zeile angeben?**
|
||||
A: Nein, jeder Link muss in einer eigenen Zeile stehen: `kind:target`.
|
||||
|
||||
## Zusammenfassung
|
||||
|
||||
- ✅ **Explizite Links:** `[[rel:kind|target]]` oder `> [!edge]` → Keine Validierung
|
||||
- ✅ **Global Pool Links:** Sektion `### Unzugeordnete Kanten` → Mit LLM-Validierung
|
||||
- ✅ **Aktivierung:** `enable_smart_edge_allocation: true` in Chunk-Config
|
||||
- ✅ **Format:** `kind:target` (eine pro Zeile)
|
||||
Reference in new issue
Block a user