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.
276 lines
7.4 KiB
Markdown
276 lines
7.4 KiB
Markdown
# Note-Scope Extraktions-Zonen (v4.5.8)
|
|
|
|
**Version:** v4.5.8
|
|
**Status:** Aktiv
|
|
**Aktualisiert:** WP-24c Phase 3 Agentic Edge Validation
|
|
|
|
## Ü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 Phase 3 Validierung (WP-24c v4.5.8)
|
|
|
|
Note-Scope Links können **zwei verschiedene Provenance** haben:
|
|
|
|
### Explizite Note-Scope Links (Keine Validierung)
|
|
|
|
Links in `## Smart Edges` Zonen werden als `explicit:note_zone` markiert und **direkt übernommen** (keine Phase 3 Validierung):
|
|
|
|
```markdown
|
|
## Smart Edges
|
|
|
|
[[rel:depends_on|System-Architektur]]
|
|
[[rel:part_of|Gesamt-System]]
|
|
```
|
|
|
|
**Vorteil:** Sofortige Übernahme, höchste Priorität, keine Validierungs-Kosten.
|
|
|
|
### Validierte Note-Scope Links (Phase 3 Validierung)
|
|
|
|
Links in `### Unzugeordnete Kanten` erhalten `candidate:` Präfix und werden in **Phase 3** validiert:
|
|
|
|
```markdown
|
|
### Unzugeordnete Kanten
|
|
|
|
related_to:Mögliche Verbindung
|
|
depends_on:Unsicherer Link
|
|
```
|
|
|
|
**Validierungsprozess:**
|
|
1. Links erhalten `candidate:` Präfix
|
|
2. **Phase 3 Validierung:** LLM prüft semantisch gegen Note-Summary oder Note-Text (Note-Scope Kontext-Optimierung)
|
|
3. **Erfolg (VERIFIED):** `candidate:` Präfix wird entfernt, Kante wird persistiert
|
|
4. **Ablehnung (REJECTED):** Kante wird **nicht** in die Datenbank geschrieben
|
|
|
|
**Wichtig:**
|
|
- Links in `### Unzugeordnete Kanten` werden als `candidate:` markiert und durchlaufen Phase 3
|
|
- Links in `## Smart Edges` werden als `explicit:note_zone` markiert und **nicht** validiert (direkt übernommen)
|
|
- **Note-Scope Kontext-Optimierung:** Bei Note-Scope Kanten nutzt Phase 3 `note_summary` (Top 5 Chunks) oder `note_text` (aggregierter Gesamttext) für bessere Validierungs-Genauigkeit
|
|
|
|
## 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: Das hängt von der Zone ab:
|
|
- **`## Smart Edges`:** Nein, werden direkt übernommen (explizite Links, keine Validierung)
|
|
- **`### Unzugeordnete Kanten`:** Ja, durchlaufen Phase 3 Validierung (candidate: Präfix)
|
|
|
|
**Q: Was ist der Unterschied zwischen Note-Scope in Smart Edges vs. Unzugeordnete Kanten?**
|
|
A:
|
|
- **Smart Edges:** Explizite Links, sofortige Übernahme, höchste Priorität
|
|
- **Unzugeordnete Kanten:** Validierte Links, Phase 3 Prüfung, candidate: Präfix
|
|
|
|
**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)
|