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,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)
|
||||
Reference in new issue
Block a user