mindnet/docs/03_Technical_References/KONFIGURATION_EDGE_ZONEN.md

Konfiguration von Edge-Zonen Headern (v4.2.0)

Version: v4.2.0
Status: Aktiv

Übersicht

Das Mindnet-System unterstützt zwei Arten von speziellen Markdown-Sektionen für Kanten:

1. LLM-Validierung Zonen - Links, die vom LLM validiert werden
2. Note-Scope Zonen - Links, die der gesamten Note zugeordnet werden

Die Header-Namen für beide Zonen-Typen sind über Umgebungsvariablen konfigurierbar.

Konfiguration via .env

LLM-Validierung Header

Umgebungsvariablen:

• MINDNET_LLM_VALIDATION_HEADERS - Komma-separierte Liste von Header-Namen
• MINDNET_LLM_VALIDATION_HEADER_LEVEL - Header-Ebene (1-6, Default: 3 für ###)

Format: Komma-separierte Liste von Header-Namen

Default:

MINDNET_LLM_VALIDATION_HEADERS=Unzugeordnete Kanten,Edge Pool,Candidates
MINDNET_LLM_VALIDATION_HEADER_LEVEL=3

Beispiel:

MINDNET_LLM_VALIDATION_HEADERS=Unzugeordnete Kanten,Edge Pool,Candidates,Zu prüfende Links
MINDNET_LLM_VALIDATION_HEADER_LEVEL=3

Verwendung in Markdown:

### Unzugeordnete Kanten

related_to:Ziel-Notiz
depends_on:Andere Notiz

Wichtig: Diese Bereiche werden nicht als Chunks angelegt, sondern nur die Kanten extrahiert.

Note-Scope Zone Header

Umgebungsvariablen:

• MINDNET_NOTE_SCOPE_ZONE_HEADERS - Komma-separierte Liste von Header-Namen
• MINDNET_NOTE_SCOPE_HEADER_LEVEL - Header-Ebene (1-6, Default: 2 für ##)

Format: Komma-separierte Liste von Header-Namen

Default:

MINDNET_NOTE_SCOPE_ZONE_HEADERS=Smart Edges,Relationen,Global Links,Note-Level Relations,Globale Verbindungen
MINDNET_NOTE_SCOPE_HEADER_LEVEL=2

Beispiel:

MINDNET_NOTE_SCOPE_ZONE_HEADERS=Smart Edges,Relationen,Globale Verbindungen,Note-Level Links
MINDNET_NOTE_SCOPE_HEADER_LEVEL=2

Verwendung in Markdown:

## Smart Edges

[[rel:depends_on|Globale Notiz]]
[[rel:part_of|System-Übersicht]]

Wichtig: Diese Bereiche werden nicht als Chunks angelegt, sondern nur die Kanten extrahiert.

Konfiguration in prod.env

Fügen Sie die folgenden Zeilen zu Ihrer .env oder config/prod.env hinzu:

# --- WP-24c v4.2.0: Konfigurierbare Markdown-Header für Edge-Zonen ---
# Komma-separierte Liste von Headern für LLM-Validierung
MINDNET_LLM_VALIDATION_HEADERS=Unzugeordnete Kanten,Edge Pool,Candidates

# Header-Ebene für LLM-Validierung (1-6, Default: 3 für ###)
MINDNET_LLM_VALIDATION_HEADER_LEVEL=3

# Komma-separierte Liste von Headern für Note-Scope Zonen
MINDNET_NOTE_SCOPE_ZONE_HEADERS=Smart Edges,Relationen,Global Links,Note-Level Relations,Globale Verbindungen

# Header-Ebene für Note-Scope Zonen (1-6, Default: 2 für ##)
MINDNET_NOTE_SCOPE_HEADER_LEVEL=2

Wichtig: Beide Zonen-Typen werden nicht als Chunks angelegt. Nur die Kanten werden extrahiert, der Text selbst wird vom Chunking ausgeschlossen.

Unterschiede

LLM-Validierung Zonen

• Header-Ebene: Konfigurierbar via MINDNET_LLM_VALIDATION_HEADER_LEVEL (Default: 3 = ###)
• Zweck: Links werden vom LLM validiert
• Provenance: global_pool
• Scope: chunk (wird Chunks zugeordnet)
• Aktivierung: Nur wenn enable_smart_edge_allocation: true
• Chunking: ❌ Diese Bereiche werden NICHT als Chunks angelegt - nur Kanten werden extrahiert

Beispiel:

### Unzugeordnete Kanten

related_to:Mögliche Verbindung
depends_on:Unsichere Notiz

Note-Scope Zonen

• Header-Ebene: Konfigurierbar via MINDNET_NOTE_SCOPE_HEADER_LEVEL (Default: 2 = ##)
• Zweck: Links werden der gesamten Note zugeordnet
• Provenance: explicit:note_zone
• Scope: note (Note-weite Verbindung)
• Aktivierung: Immer aktiv
• Chunking: ❌ Diese Bereiche werden NICHT als Chunks angelegt - nur Kanten werden extrahiert

Beispiel:

## Smart Edges

[[rel:depends_on|Globale Notiz]]
[[rel:part_of|System-Übersicht]]

Best Practices

✅ Empfohlen

1. Konsistente Header-Namen:

   • Nutzen Sie aussagekräftige Namen
   • Dokumentieren Sie die verwendeten Header in Ihrem Team

2. Minimale Konfiguration:

   • Nutzen Sie die Defaults, wenn möglich
   • Nur bei Bedarf anpassen

3. Dokumentation:

   • Dokumentieren Sie benutzerdefinierte Header in Ihrer Projekt-Dokumentation

❌ Vermeiden

1. Zu viele Header:

   • Zu viele Optionen können verwirrend sein
   • Beschränken Sie sich auf 3-5 Header pro Typ

2. Ähnliche Namen:

   • Vermeiden Sie Header, die sich zu ähnlich sind
   • Klare Unterscheidung zwischen LLM-Validierung und Note-Scope

Technische Details

Code-Referenzen

• LLM-Validierung: app/core/chunking/chunking_processor.py (Zeile 66-72)
• Note-Scope Zonen: app/core/graph/graph_derive_edges.py → get_note_scope_zone_headers()

Fallback-Verhalten

• Wenn die Umgebungsvariable nicht gesetzt ist, werden die Defaults verwendet
• Wenn die Variable leer ist, werden ebenfalls die Defaults verwendet
• Header-Namen werden case-insensitive verglichen

Regex-Escape

• Header-Namen werden automatisch für Regex escaped
• Sonderzeichen in Header-Namen sind sicher

Beispiel-Konfiguration

# Eigene Header-Namen für LLM-Validierung (H3)
MINDNET_LLM_VALIDATION_HEADERS=Zu prüfende Links,Kandidaten,Edge Pool
MINDNET_LLM_VALIDATION_HEADER_LEVEL=3

# Eigene Header-Namen für Note-Scope Zonen (H2)
MINDNET_NOTE_SCOPE_ZONE_HEADERS=Globale Relationen,Note-Verbindungen,Smart Links
MINDNET_NOTE_SCOPE_HEADER_LEVEL=2

Alternative: Beide auf H2 setzen:

MINDNET_LLM_VALIDATION_HEADER_LEVEL=2
MINDNET_NOTE_SCOPE_HEADER_LEVEL=2

Verwendung:

---
type: decision
title: Meine Notiz
---

# Inhalt

## Globale Relationen

[[rel:depends_on|System-Architektur]]

### Zu prüfende Links

related_to:Mögliche Verbindung

FAQ

Q: Kann ich beide Zonen-Typen in einer Notiz verwenden?
A: Ja, beide können gleichzeitig verwendet werden.

Q: Was passiert, wenn ein Header in beiden Listen steht?
A: Die Note-Scope Zone hat Vorrang (wird als Note-Scope behandelt).

Q: Können Header-Namen Leerzeichen enthalten?
A: Ja, Leerzeichen werden beibehalten.

Q: Werden Header-Namen case-sensitive verglichen?
A: Nein, der Vergleich ist case-insensitive.

Q: Kann ich Header-Namen mit Sonderzeichen verwenden?
A: Ja, Sonderzeichen werden automatisch für Regex escaped.

Zusammenfassung

• ✅ LLM-Validierung:
  • MINDNET_LLM_VALIDATION_HEADERS (Header-Namen, komma-separiert)
  • MINDNET_LLM_VALIDATION_HEADER_LEVEL (Header-Ebene 1-6, Default: 3)
  • ❌ Nicht als Chunks angelegt - nur Kanten werden extrahiert
• ✅ Note-Scope Zonen:
  • MINDNET_NOTE_SCOPE_ZONE_HEADERS (Header-Namen, komma-separiert)
  • MINDNET_NOTE_SCOPE_HEADER_LEVEL (Header-Ebene 1-6, Default: 2)
  • ❌ Nicht als Chunks angelegt - nur Kanten werden extrahiert
• ✅ Format: Komma-separierte Liste für Header-Namen
• ✅ Fallback: Defaults werden verwendet, falls nicht konfiguriert
• ✅ Case-insensitive: Header-Namen werden case-insensitive verglichen