Implement WP-24c v4.2.0: Introduce configurable header names and levels for LLM validation and Note-Scope zones in the chunking system. Update chunking models, parser, and processor to support exclusion of edge zones during chunking. Enhance documentation and configuration files to reflect new environment variables for improved flexibility in Markdown processing.

This commit is contained in:
Lars committed 2026-01-10 21:46:51 +01:00
1 parent 39fd15b565
commit 003a270548
7 files changed
+401 -28

No files matched your search

@@ -50,6 +50,11 @@ Diese Variablen steuern die Infrastruktur, Pfade und globale Timeouts. Seit der
| `MINDNET_LL_BACKGROUND_LIMIT`| `2` | **Traffic Control:** Max. parallele Hintergrund-Tasks (Semaphore). |
| `MINDNET_CHANGE_DETECTION_MODE` | `full` | `full` (Text + Meta) oder `body` (nur Text). |
| `MINDNET_DEFAULT_RETRIEVER_WEIGHT` | `1.0` | **Neu (WP-22):** Systemweiter Standard für das Retriever-Gewicht einer Notiz. |
| `MINDNET_LLM_VALIDATION_HEADERS` | `Unzugeordnete Kanten,Edge Pool,Candidates` | **Neu (v4.2.0):** Komma-separierte Header-Namen für LLM-Validierung. |
| `MINDNET_LLM_VALIDATION_HEADER_LEVEL` | `3` | **Neu (v4.2.0):** Header-Ebene für LLM-Validierung (1-6, Default: 3 für ###). |
| `MINDNET_NOTE_SCOPE_ZONE_HEADERS` | `Smart Edges,Relationen,Global Links,Note-Level Relations,Globale Verbindungen` | **Neu (v4.2.0):** Komma-separierte Header-Namen für Note-Scope Zonen. |
| `MINDNET_NOTE_SCOPE_HEADER_LEVEL` | `2` | **Neu (v4.2.0):** Header-Ebene für Note-Scope Zonen (1-6, Default: 2 für ##). |
| `MINDNET_IGNORE_FOLDERS` | *(leer)* | **Neu (v4.1.0):** Komma-separierte Liste von Ordnernamen, die beim Import ignoriert werden. |
---
@@ -0,0 +1,242 @@
# 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:**
```env
MINDNET_LLM_VALIDATION_HEADERS=Unzugeordnete Kanten,Edge Pool,Candidates,Zu prüfende Links
MINDNET_LLM_VALIDATION_HEADER_LEVEL=3
```
**Verwendung in Markdown:**
```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:**
```env
MINDNET_NOTE_SCOPE_ZONE_HEADERS=Smart Edges,Relationen,Globale Verbindungen,Note-Level Links
MINDNET_NOTE_SCOPE_HEADER_LEVEL=2
```
**Verwendung in Markdown:**
```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:
```env
# --- 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:**
```markdown
### 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:**
```markdown
## 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
```env
# 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:
```env
MINDNET_LLM_VALIDATION_HEADER_LEVEL=2
MINDNET_NOTE_SCOPE_HEADER_LEVEL=2
```
**Verwendung:**
```markdown
---
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