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:
Lars committed 2026-01-10 19:55:51 +01:00
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)
+240
View File
@@ -0,0 +1,240 @@
# Note-Scope Extraktions-Zonen (v4.2.0)
**Version:** v4.2.0
**Status:** Aktiv
## Übersicht
Das Mindnet-System unterstützt nun **Note-Scope Extraktions-Zonen**, die es ermöglichen, Links zu definieren, die der gesamten Note zugeordnet werden (nicht nur einem spezifischen Chunk).
### Unterschied: Chunk-Scope vs. Note-Scope
- **Chunk-Scope Links** (`scope: "chunk"`):
- Werden aus dem Text-Inhalt extrahiert
- Sind lokalem Kontext zugeordnet
- `source_id` = `chunk_id`
- **Note-Scope Links** (`scope: "note"`):
- Werden aus speziellen Markdown-Sektionen extrahiert
- Sind der gesamten Note zugeordnet
- `source_id` = `note_id`
- Haben höchste Priorität bei Duplikaten
## Verwendung
### Format
Erstellen Sie eine Sektion mit einem der folgenden Header:
- `## Smart Edges`
- `## Relationen`
- `## Global Links`
- `## Note-Level Relations`
- `## Globale Verbindungen`
**Wichtig:** Die Header müssen exakt (case-insensitive) übereinstimmen.
### Beispiel
```markdown
---
type: decision
title: Technologie-Entscheidung
---
# Entscheidung über Technologie-Stack
Wir haben uns für React entschieden...
## Begründung
React bietet bessere Performance...
## Smart Edges
[[rel:depends_on|Performance-Analyse]]
[[rel:uses|TypeScript]]
[[React-Dokumentation]]
## Weitere Überlegungen
Hier ist weiterer Inhalt...
```
### Unterstützte Link-Formate
In Note-Scope Zonen werden folgende Formate unterstützt:
1. **Typed Relations:**
```markdown
## Smart Edges
[[rel:depends_on|Ziel-Notiz]]
[[rel:uses|Andere Notiz]]
```
2. **Standard Wikilinks:**
```markdown
## Smart Edges
[[Ziel-Notiz]]
[[Andere Notiz]]
```
(Werden als `related_to` interpretiert)
3. **Callouts:**
```markdown
## Smart Edges
> [!edge] depends_on:[[Ziel-Notiz]]
> [!edge] uses:[[Andere Notiz]]
```
## Technische Details
### ID-Generierung
Note-Scope Links verwenden die **exakt gleiche ID-Generierung** wie Symmetrie-Kanten in Phase 2:
```python
_mk_edge_id(kind, note_id, target_id, "note", target_section=sec)
```
Dies stellt sicher, dass:
- ✅ Authority-Check in Phase 2 korrekt funktioniert
- ✅ Keine Duplikate entstehen
- ✅ Symmetrie-Schutz greift
### Provenance
Note-Scope Links erhalten:
- `provenance: "explicit:note_zone"`
- `confidence: 1.0` (höchste Priorität)
- `scope: "note"`
- `source_id: note_id` (nicht `chunk_id`)
### Priorisierung
Bei Duplikaten (gleiche ID):
1. **Note-Scope Links** haben **höchste Priorität**
2. Dann Confidence-Wert
3. Dann Provenance-Priority
**Beispiel:**
- Chunk-Link: `related_to:Note-A` (aus Text)
- Note-Scope Link: `related_to:Note-A` (aus Zone)
- **Ergebnis:** Note-Scope Link wird beibehalten
## Best Practices
### ✅ Empfohlen
1. **Note-Scope für globale Verbindungen:**
```markdown
## Smart Edges
[[rel:depends_on|Projekt-Übersicht]]
[[rel:part_of|Größeres System]]
```
2. **Chunk-Scope für lokale Referenzen:**
```markdown
In diesem Abschnitt verweisen wir auf [[rel:uses|Spezifische Technologie]].
```
3. **Kombination:**
```markdown
# Hauptinhalt
Lokale Referenz: [[rel:uses|Lokale Notiz]]
## Smart Edges
Globale Verbindung: [[rel:depends_on|Globale Notiz]]
```
### ❌ Vermeiden
1. **Nicht für lokale Kontext-Links:**
- Nutzen Sie Chunk-Scope Links für lokale Referenzen
- Note-Scope ist für Note-weite Verbindungen gedacht
2. **Nicht zu viele Note-Scope Links:**
- Beschränken Sie sich auf wirklich Note-weite Verbindungen
- Zu viele Note-Scope Links können die Graph-Struktur verwässern
## Integration mit LLM-Validierung
Note-Scope Links können auch **LLM-validiert** werden, wenn sie in der Sektion `### Unzugeordnete Kanten` stehen:
```markdown
### Unzugeordnete Kanten
related_to:Mögliche Verbindung
```
**Wichtig:** Links in `### Unzugeordnete Kanten` werden als `global_pool` markiert und validiert. Links in `## Smart Edges` werden als `explicit:note_zone` markiert und **nicht** validiert (direkt übernommen).
## Beispiel: Vollständige Notiz
```markdown
---
type: decision
title: Architektur-Entscheidung
---
# Architektur-Entscheidung
Wir haben uns für Microservices entschieden...
## Begründung
### Performance
Microservices bieten bessere Skalierbarkeit. Siehe auch [[rel:uses|Kubernetes]] für Orchestrierung.
### Sicherheit
Wir nutzen [[rel:enforced_by|OAuth2]] für Authentifizierung.
## Smart Edges
[[rel:depends_on|System-Architektur]]
[[rel:part_of|Gesamt-System]]
[[rel:uses|Cloud-Infrastruktur]]
## Weitere Details
Hier ist weiterer Inhalt...
```
**Ergebnis:**
- `uses:Kubernetes` → Chunk-Scope (aus Text)
- `enforced_by:OAuth2` → Chunk-Scope (aus Text)
- `depends_on:System-Architektur` → Note-Scope (aus Zone)
- `part_of:Gesamt-System` → Note-Scope (aus Zone)
- `uses:Cloud-Infrastruktur` → Note-Scope (aus Zone)
## Code-Referenzen
- **Extraktion:** `app/core/graph/graph_derive_edges.py` → `extract_note_scope_zones()`
- **Integration:** `app/core/graph/graph_derive_edges.py` → `build_edges_for_note()`
- **Header-Liste:** `NOTE_SCOPE_ZONE_HEADERS` in `graph_derive_edges.py`
## FAQ
**Q: Können Note-Scope Links auch Section-Links sein?**
A: Ja, `[[rel:kind|Target#Section]]` wird unterstützt. `target_section` fließt in die ID ein.
**Q: Was passiert, wenn ein Link sowohl in Chunk als auch in Note-Scope Zone steht?**
A: Der Note-Scope Link hat Vorrang und wird beibehalten.
**Q: Werden Note-Scope Links validiert?**
A: Nein, sie werden direkt übernommen (wie explizite Links). Für Validierung nutzen Sie `### Unzugeordnete Kanten`.
**Q: Kann ich eigene Header-Namen verwenden?**
A: Aktuell nur die vordefinierten Header. Erweiterung möglich durch Anpassung von `NOTE_SCOPE_ZONE_HEADERS`.
## Zusammenfassung
- ✅ **Note-Scope Zonen:** `## Smart Edges` oder ähnliche Header
- ✅ **Format:** `[[rel:kind|target]]` oder `[[target]]`
- ✅ **Scope:** `scope: "note"`, `source_id: note_id`
- ✅ **Priorität:** Höchste Priorität bei Duplikaten
- ✅ **ID-Konsistenz:** Exakt wie Symmetrie-Kanten (Phase 2)
@@ -0,0 +1,131 @@
# Audit: Retriever & Scoring (Gold-Standard v4.1.0)
**Datum:** 2026-01-10
**Version:** v4.1.0
**Status:** Audit abgeschlossen, Optimierungen implementiert
## Kontext
Das Ingestion-System wurde auf den Gold-Standard v4.1.0 aktualisiert. Die Kanten-Identität ist nun deterministisch und hochpräzise mit strikter Trennung zwischen:
- **Chunk-Scope-Edges:** Präzise Links aus Textabsätzen (Source = `chunk_id`), oft mit `target_section`
- **Note-Scope-Edges:** Strukturelle Links und Symmetrien (Source = `note_id`)
- **Multigraph-Support:** Identische Note-Verbindungen bleiben als separate Points erhalten, wenn sie auf unterschiedliche Sektionen zeigen oder aus unterschiedlichen Chunks stammen
## Prüffragen & Ergebnisse
### 1. Scope-Awareness ❌ **KRITISCH**
**Frage:** Sucht der Retriever bei einer Note-Anfrage sowohl nach Abgangskanten der `note_id` als auch nach Abgangskanten aller zugehörigen `chunk_ids`?
**Aktueller Status:**
- ❌ **NEIN**: Der Retriever sucht nur nach Edges, die von `note_id` ausgehen
- Die Graph-Expansion in `graph_db_adapter.py` filtert nur nach `source_id`, `target_id` und `note_id`
- Chunk-Level Edges (`scope="chunk"`) werden nicht explizit berücksichtigt
- **Risiko:** Datenverlust bei präzisen Chunk-Links
**Empfehlung:**
- Erweitere `fetch_edges_from_qdrant` um explizite Suche nach `chunk_id`-Edges
- Bei Note-Anfragen: Lade alle Chunks der Note und suche nach deren Edges
- Aggregiere Chunk-Edges in Note-Level Scoring
### 2. Section-Filtering ❌ **FEHLT**
**Frage:** Kann der Retriever bei einem Sektions-Link (`[[Note#Sektion]]`) die Ergebnismenge in Qdrant gezielt auf Chunks filtern, die das entsprechende `section`-Attribut im Payload tragen?
**Aktueller Status:**
- ❌ **NEIN**: Es gibt keine Filterung nach `target_section`
- `target_section` wird zwar im Edge-Payload gespeichert, aber nicht für Filterung verwendet
- **Risiko:** Unpräzise Ergebnisse bei Section-Links
**Empfehlung:**
- Erweitere `QueryRequest` um optionales `target_section` Feld
- Implementiere Filterung in `_semantic_hits` und `fetch_edges_from_qdrant`
- Nutze `target_section` für präzise Chunk-Filterung
### 3. Scoring-Aggregation ⚠️ **TEILWEISE**
**Frage:** Wie geht das Scoring damit um, wenn ein Ziel von mehreren Chunks derselben Note referenziert wird? Wird die Relevanz (In-Degree) auf Chunk-Ebene korrekt akkumuliert?
**Aktueller Status:**
- ⚠️ **TEILWEISE**: Super-Edge-Aggregation existiert (WP-15c), aber:
- Aggregiert nur nach Ziel-Note (`target_id`), nicht nach Chunk-Level
- Mehrere Chunks derselben Note, die auf dasselbe Ziel zeigen, werden nicht korrekt akkumuliert
- Die "Beweislast" (In-Degree) wird nicht auf Chunk-Ebene berechnet
- **Risiko:** Unterbewertung von Zielen, die von mehreren Chunks referenziert werden
**Empfehlung:**
- Erweitere Super-Edge-Aggregation um Chunk-Level Tracking
- Berechne In-Degree sowohl auf Note- als auch auf Chunk-Ebene
- Nutze Chunk-Level In-Degree als zusätzlichen Boost-Faktor
### 4. Authority-Priorisierung ⚠️ **TEILWEISE**
**Frage:** Nutzt das Scoring das Feld `provenance_priority` oder `confidence`, um manuelle "Explicit"-Kanten gegenüber "Virtual"-Symmetrien bei der Sortierung zu bevorzugen?
**Aktueller Status:**
- ⚠️ **TEILWEISE**:
- Provenance-Weighting existiert (Zeile 344-345 in `retriever.py`)
- Nutzt aber nicht `confidence` oder `provenance_priority` aus dem Payload
- Hardcoded Gewichtung: `explicit=1.0`, `smart=0.9`, `rule=0.7`
- `virtual` Flag wird nicht berücksichtigt
- **Risiko:** Virtual-Symmetrien werden nicht korrekt de-priorisiert
**Empfehlung:**
- Nutze `confidence` aus dem Edge-Payload
- Berücksichtige `virtual` Flag für explizite De-Priorisierung
- Integriere `PROVENANCE_PRIORITY` aus `graph_utils.py` statt Hardcoding
### 5. RAG-Kontext ❌ **FEHLT**
**Frage:** Wird beim Retrieval einer Kante der `source_id` (Chunk) direkt mitgeliefert, damit das LLM den exakten Herkunfts-Kontext der Verbindung erhält?
**Aktueller Status:**
- ❌ **NEIN**: `source_id` (Chunk-ID) wird nicht explizit im `QueryHit` mitgeliefert
- Edge-Payload enthält `source_id`, aber es wird nicht in den RAG-Kontext übernommen
- **Risiko:** LLM erhält keinen Kontext über die Herkunft der Verbindung
**Empfehlung:**
- Erweitere `QueryHit` um `source_chunk_id` Feld
- Bei Chunk-Scope Edges: Lade den Quell-Chunk-Text für RAG-Kontext
- Integriere Chunk-Kontext in Explanation Layer
## Implementierte Optimierungen
Siehe: `app/core/retrieval/retriever.py` (v0.8.0) und `app/core/graph/graph_db_adapter.py` (v1.2.0)
### Änderungen
1. **Scope-Aware Edge Retrieval**
- `fetch_edges_from_qdrant` sucht nun explizit nach `chunk_id`-Edges
- Bei Note-Anfragen werden alle zugehörigen Chunks geladen
2. **Section-Filtering**
- `QueryRequest` unterstützt optionales `target_section` Feld
- Filterung in `_semantic_hits` und Edge-Retrieval implementiert
3. **Chunk-Level Aggregation**
- Super-Edge-Aggregation erweitert um Chunk-Level Tracking
- In-Degree wird sowohl auf Note- als auch Chunk-Ebene berechnet
4. **Authority-Priorisierung**
- Nutzung von `confidence` und `PROVENANCE_PRIORITY`
- `virtual` Flag wird für De-Priorisierung berücksichtigt
5. **RAG-Kontext**
- `QueryHit` erweitert um `source_chunk_id`
- Chunk-Kontext wird in Explanation Layer integriert
## Validierung
- ✅ Scope-Awareness: Note- und Chunk-Edges werden korrekt geladen
- ✅ Section-Filtering: Präzise Filterung nach `target_section` funktioniert
- ✅ Scoring-Aggregation: Chunk-Level In-Degree wird korrekt akkumuliert
- ✅ Authority-Priorisierung: Explicit-Kanten werden bevorzugt
- ✅ RAG-Kontext: `source_chunk_id` wird mitgeliefert
## Nächste Schritte
1. Performance-Tests mit großen Vaults
2. Integration in Decision Engine
3. Dokumentation der neuen Features