From beb87a8c43e5397e882da74c2dd228456bfbd278 Mon Sep 17 00:00:00 2001 From: Lars Date: Tue, 30 Dec 2025 12:16:58 +0100 Subject: [PATCH] Update documentation to version 2.9.1, introducing support for section-based links and multigraph functionality. Enhance glossary, user manual, and technical references to reflect new deep-linking capabilities and edge structure adjustments. Ensure proper migration instructions for users transitioning to the new version. --- docs/00_General/00_glossary.md | 9 ++-- docs/01_User_Manual/01_knowledge_design.md | 14 ++++- docs/02_concepts/02_concept_graph_logic.md | 28 ++++++++-- .../03_tech_api_reference.md | 5 +- .../03_tech_data_model.md | 16 ++++-- .../03_tech_frontend.md | 2 +- .../03_tech_ingestion_pipeline.md | 52 ++++++++++++++----- docs/04_Operations/04_admin_operations.md | 9 +++- 8 files changed, 109 insertions(+), 26 deletions(-) diff --git a/docs/00_General/00_glossary.md b/docs/00_General/00_glossary.md index e14ead9..3ff270b 100644 --- a/docs/00_General/00_glossary.md +++ b/docs/00_General/00_glossary.md @@ -2,7 +2,7 @@ doc_type: glossary audience: all status: active -version: 2.8.1 +version: 2.9.1 context: "Zentrales Glossar für Mindnet v2.8. Enthält Definitionen zu Hybrid-Cloud Resilienz, WP-14 Modularisierung, WP-15b Two-Pass Ingestion und Mistral-safe Parsing." --- @@ -14,7 +14,7 @@ context: "Zentrales Glossar für Mindnet v2.8. Enthält Definitionen zu Hybrid-C * **Note:** Repräsentiert eine Markdown-Datei. Die fachliche Haupteinheit. Verfügt über einen **Status** (stable, draft, system), der das Scoring beeinflusst. * **Chunk:** Ein Textabschnitt einer Note. Die technische Sucheinheit (Vektor). -* **Edge:** Eine gerichtete Verbindung zwischen zwei Knoten. Wird in WP-22 durch die Registry validiert. +* **Edge:** Eine gerichtete Verbindung zwischen zwei Knoten. Wird in WP-22 durch die Registry validiert. Seit v2.9.1 unterstützt Edges **Section-basierte Links** (`target_section`), sodass mehrere Kanten zwischen denselben Knoten existieren können, wenn sie auf verschiedene Abschnitte zeigen. * **Vault:** Der lokale Ordner mit den Markdown-Dateien (Source of Truth). * **Frontmatter:** Der YAML-Header am Anfang einer Notiz (enthält `id`, `type`, `title`, `status`). @@ -47,4 +47,7 @@ context: "Zentrales Glossar für Mindnet v2.8. Enthält Definitionen zu Hybrid-C * **Two-Pass Workflow (WP-15b):** Optimiertes Ingestion-Verfahren: * **Pass 1 (Pre-Scan):** Schnelles Scannen aller Dateien zur Befüllung des LocalBatchCache. * **Pass 2 (Semantic Processing):** Tiefenverarbeitung (Chunking, Embedding, Validierung) nur für geänderte Dateien. -* **Circular Import Registry (WP-14):** Entkopplung von Kern-Logik (wie Textbereinigung) in eine neutrale `registry.py`, um Abhängigkeitsschleifen zwischen Diensten und Ingestion-Utilities zu verhindern. \ No newline at end of file +* **Circular Import Registry (WP-14):** Entkopplung von Kern-Logik (wie Textbereinigung) in eine neutrale `registry.py`, um Abhängigkeitsschleifen zwischen Diensten und Ingestion-Utilities zu verhindern. +* **Deep-Link / Section-basierter Link:** Ein Link wie `[[Note#Section]]`, der auf einen spezifischen Abschnitt innerhalb einer Note verweist. Seit v2.9.1 wird dieser in `target_id="Note"` und `target_section="Section"` aufgeteilt, um "Phantom-Knoten" zu vermeiden und Multigraph-Support zu ermöglichen. +* **Atomic Section Logic (v3.9.9):** Chunking-Verfahren, das Sektions-Überschriften und deren Inhalte atomar in Chunks hält (Pack-and-Carry-Over). Verhindert, dass Überschriften über Chunk-Grenzen hinweg getrennt werden. +* **Registry-First Profiling (v2.13.12):** Hierarchische Auflösung des Chunking-Profils: Frontmatter > types.yaml Typ-Config > Global Defaults. Stellt sicher, dass Note-Typen automatisch das korrekte Profil erhalten. \ No newline at end of file diff --git a/docs/01_User_Manual/01_knowledge_design.md b/docs/01_User_Manual/01_knowledge_design.md index ed2f3b3..885664e 100644 --- a/docs/01_User_Manual/01_knowledge_design.md +++ b/docs/01_User_Manual/01_knowledge_design.md @@ -3,7 +3,7 @@ doc_type: user_manual audience: user, author scope: vault, markdown, schema status: active -version: 2.8.0 +version: 2.9.1 context: "Regelwerk für das Erstellen von Notizen im Vault. Die 'Source of Truth' für Autoren." --- @@ -208,6 +208,12 @@ Dies ist die **mächtigste** Methode. Du sagst dem System explizit, **wie** Ding > "Daher [[rel:depends_on Qdrant]]." > "Dieses Konzept ist [[rel:similar_to Pinecone]]." +**Deep-Links zu Abschnitten (v2.9.1):** +Du kannst auch auf spezifische Abschnitte innerhalb einer Note verlinken: +> "Siehe [[rel:based_on Mein Leitbild#P3 – Disziplin]]." + +Das System trennt automatisch den Note-Namen (`Mein Leitbild`) vom Abschnitts-Namen (`P3 – Disziplin`), sodass mehrere Links zur gleichen Note möglich sind, wenn sie auf verschiedene Abschnitte zeigen. + **Gültige Relationen:** * `depends_on`: Hängt ab von / Benötigt. * `blocks`: Blockiert oder gefährdet (z.B. Risiko -> Projekt). @@ -226,6 +232,12 @@ Für Zusammenfassungen am Ende einer Notiz, oder eines Absatzes: > [[AI Agents]] ``` +**Multi-Line Support (v2.9.1):** +Callout-Blocks mit mehreren Zeilen werden korrekt verarbeitet. Das System erkennt automatisch, wenn mehrere Links im gleichen Callout-Block stehen, und erstellt für jeden Link eine separate Kante (auch bei Deep-Links zu verschiedenen Sections). + +**Format-agnostische De-Duplizierung:** +Wenn Kanten bereits via `[!edge]` Callout vorhanden sind, werden sie nicht mehrfach injiziert. Das System erkennt vorhandene Kanten unabhängig vom Format (Inline, Callout, Wikilink). + ### 4.3 Implizite Bidirektionalität (Edger-Logik) [NEU] [PRÜFEN!] In Mindnet musst du Kanten **nicht** manuell in beide Richtungen pflegen. Der **Edger** übernimmt die Paarbildung automatisch im Hintergrund. diff --git a/docs/02_concepts/02_concept_graph_logic.md b/docs/02_concepts/02_concept_graph_logic.md index 6c08e4c..b7f89a7 100644 --- a/docs/02_concepts/02_concept_graph_logic.md +++ b/docs/02_concepts/02_concept_graph_logic.md @@ -3,7 +3,7 @@ doc_type: concept audience: architect, product_owner scope: graph, logic, provenance status: active -version: 2.7.0 +version: 2.9.1 context: "Fachliche Beschreibung des Wissensgraphen: Knoten, Kanten, Provenance, Matrix-Logik und WP-22 Scoring-Prinzipien." --- @@ -118,8 +118,30 @@ Der Intent-Router injiziert spezifische Multiplikatoren für kanonische Typen: --- -## 6. Idempotenz & Konsistenz +## 6. Section-basierte Links & Multigraph-Support + +Seit v2.9.1 unterstützt Mindnet **Deep-Links** zu spezifischen Abschnitten innerhalb einer Note. + +### 6.1 Link-Parsing +Links wie `[[Note#Section]]` werden in zwei Komponenten aufgeteilt: +* **`target_id`:** Enthält nur den Note-Namen (z.B. "Mein Leitbild") +* **`target_section`:** Enthält den Abschnitts-Namen (z.B. "P3 – Disziplin") + +**Vorteil:** Verhindert "Phantom-Knoten", die durch das Einbeziehen des Anchors in die `target_id` entstanden wären. + +### 6.2 Multigraph-Support +Die Edge-ID enthält nun einen `variant`-Parameter (die Section), sodass mehrere Kanten zwischen denselben Knoten existieren können, wenn sie auf verschiedene Sections zeigen: +* `[[Note#Section1]]` → Edge-ID: `src->tgt:kind@Section1` +* `[[Note#Section2]]` → Edge-ID: `src->tgt:kind@Section2` + +### 6.3 Semantische Deduplizierung +Die Deduplizierung basiert auf dem `src->tgt:kind@sec` Key, um sicherzustellen, dass identische Links (gleiche Quelle, Ziel, Typ und Section) nicht mehrfach erstellt werden. + +--- + +## 7. Idempotenz & Konsistenz Das System garantiert fachliche Konsistenz auch bei mehrfachen Importen. * **Stabile IDs:** Deterministische IDs verhindern Duplikate bei Re-Imports. -* **Deduplizierung:** Kanten werden anhand ihrer Identität erkannt. Die "stärkere" Provenance gewinnt. \ No newline at end of file +* **Deduplizierung:** Kanten werden anhand ihrer Identität (inkl. Section) erkannt. Die "stärkere" Provenance gewinnt. +* **Format-agnostische Erkennung:** Kanten werden unabhängig vom Format (Inline, Callout, Wikilink) erkannt, um Dopplungen zu vermeiden. \ No newline at end of file diff --git a/docs/03_Technical_References/03_tech_api_reference.md b/docs/03_Technical_References/03_tech_api_reference.md index 198f542..6e1d856 100644 --- a/docs/03_Technical_References/03_tech_api_reference.md +++ b/docs/03_Technical_References/03_tech_api_reference.md @@ -144,8 +144,11 @@ Lädt den Subgraphen um eine Note herum. "kind": "depends_on", "source": "uuid", "target": "uuid", + "target_section": "P3 – Disziplin", // Optional: Abschnitts-Name bei Deep-Links "weight": 1.4, - "direction": "out" + "direction": "out", + "provenance": "explicit", + "confidence": 1.0 } ], "stats": { diff --git a/docs/03_Technical_References/03_tech_data_model.md b/docs/03_Technical_References/03_tech_data_model.md index 6492522..320705a 100644 --- a/docs/03_Technical_References/03_tech_data_model.md +++ b/docs/03_Technical_References/03_tech_data_model.md @@ -3,7 +3,7 @@ doc_type: technical_reference audience: developer, architect scope: database, qdrant, schema status: active -version: 2.8.0 +version: 2.9.1 context: "Exakte Definition der Datenmodelle (Payloads) in Qdrant und Index-Anforderungen. Berücksichtigt WP-14 Modularisierung und WP-15b Multi-Hashes." --- @@ -96,15 +96,19 @@ Es müssen Payload-Indizes für folgende Felder existieren: ## 4. Edge Payload (`mindnet_edges`) -Gerichtete Kanten zwischen Knoten. Stark erweitert in v2.6 für Provenienz-Tracking. +Gerichtete Kanten zwischen Knoten. Stark erweitert in v2.6 für Provenienz-Tracking. Seit v2.9.1 unterstützt das System **Section-basierte Links** (`[[Note#Section]]`), die in `target_id` und `target_section` aufgeteilt werden. **JSON-Schema:** ```json { - "edge_id": "string (keyword)", // Deterministischer Hash aus (src, dst, kind) + "edge_id": "string (keyword)", // Deterministischer Hash aus (src, dst, kind, variant) + // variant = target_section (erlaubt Multigraph für Sections) "source_id": "string (keyword)", // Chunk-ID (Start) "target_id": "string (keyword)", // Chunk-ID oder Note-Titel (bei Unresolved) + // WICHTIG: Enthält NUR den Note-Namen, KEINE Section-Info + "target_section": "string (keyword)", // Optional: Abschnitts-Name (z.B. "P3 – Disziplin") + // Wird aus [[Note#Section]] extrahiert "kind": "string (keyword)", // Beziehungsart (z.B. 'depends_on') "scope": "string (keyword)", // Immer 'chunk' (Legacy-Support: 'note') "note_id": "string (keyword)", // Owner Note ID (Ursprung der Kante) @@ -116,10 +120,16 @@ Gerichtete Kanten zwischen Knoten. Stark erweitert in v2.6 für Provenienz-Track } ``` +**Section-Support:** +* Links wie `[[Note#Section]]` werden in `target_id="Note"` und `target_section="Section"` aufgeteilt. +* Die Edge-ID enthält die Section als `variant`, sodass mehrere Kanten zwischen denselben Knoten existieren können, wenn sie auf verschiedene Sections zeigen. +* Semantische Deduplizierung basiert auf `src->tgt:kind@sec` Key, um "Phantom-Knoten" zu vermeiden. + **Erforderliche Indizes:** Es müssen Payload-Indizes für folgende Felder existieren: * `source_id` * `target_id` +* `target_section` (neu: Keyword-Index für Section-basierte Filterung) * `kind` * `scope` * `note_id` diff --git a/docs/03_Technical_References/03_tech_frontend.md b/docs/03_Technical_References/03_tech_frontend.md index 5d61203..0ea3c64 100644 --- a/docs/03_Technical_References/03_tech_frontend.md +++ b/docs/03_Technical_References/03_tech_frontend.md @@ -3,7 +3,7 @@ doc_type: technical_reference audience: developer, frontend_architect scope: architecture, graph_viz, state_management status: active -version: 2.7.0 +version: 2.9.1 context: "Technische Dokumentation des modularen Streamlit-Frontends, der Graph-Engines und des Editors." --- diff --git a/docs/03_Technical_References/03_tech_ingestion_pipeline.md b/docs/03_Technical_References/03_tech_ingestion_pipeline.md index ce199dd..4d29518 100644 --- a/docs/03_Technical_References/03_tech_ingestion_pipeline.md +++ b/docs/03_Technical_References/03_tech_ingestion_pipeline.md @@ -3,7 +3,7 @@ doc_type: technical_reference audience: developer, devops scope: backend, ingestion, smart_edges, edge_registry, modularization status: active -version: 2.9.0 +version: 2.13.12 context: "Detaillierte technische Beschreibung der Import-Pipeline, Two-Pass-Workflow (WP-15b) und modularer Datenbank-Architektur (WP-14). Integriert Mistral-safe Parsing und Deep Fallback." --- @@ -31,9 +31,10 @@ Der Prozess ist **asynchron**, **idempotent** und wird nun in zwei logische Durc 4. **Edge Registry Initialisierung (WP-22):** * Laden der Singleton-Instanz der `EdgeRegistry`. * Validierung der Vokabular-Datei unter `MINDNET_VOCAB_PATH`. -5. **Config Resolution (WP-14):** +5. **Config Resolution (WP-14 / v2.13.12):** * Bestimmung von `chunking_profile` und `retriever_weight` via zentraler `TypeRegistry`. * **Priorität:** 1. Frontmatter (Override) -> 2. `types.yaml` (Type) -> 3. Global Default. + * **Registry-First Profiling:** Automatische Anwendung der korrekten Profile basierend auf dem Note-Typ (z.B. `value` nutzt automatisch `structured_smart_edges_strict`). 6. **LocalBatchCache & Summary Generation (WP-15b):** * Erstellung von Kurz-Zusammenfassungen für jede Note. * Speicherung im `batch_cache` als Referenzrahmen für die spätere Kantenvalidierung. @@ -126,19 +127,44 @@ Das Chunking ist profilbasiert und bezieht seine Konfiguration dynamisch aus der | `sliding_smart_edges`| `sliding_window` | Max: 600, Target: 400 | Fließtexte (Projekte). | | `structured_smart_edges` | `by_heading` | `strict: false` | Strukturierte Texte. | -### 3.2 Die `by_heading` Logik (v2.9 Hybrid) +### 3.2 Die `by_heading` Logik (v3.9.9 Atomic Section Logic) -Die Strategie `by_heading` zerlegt Texte anhand ihrer Struktur (Überschriften). Sie unterstützt ein "Safety Net" gegen zu große Chunks. +Die Strategie `by_heading` implementiert seit v3.9.9 das **"Pack-and-Carry-Over"** Verfahren (Regel 1-3), um Sektions-Überschriften und deren Inhalte atomar in Chunks zu halten. -* **Split Level:** Definiert die Tiefe (z.B. `2` = H1 & H2 triggern Split). -* **Modus "Strict" (`strict_heading_split: true`):** - * Jede Überschrift (`<= split_level`) erzwingt einen neuen Chunk. - * *Merge-Check:* Wenn der vorherige Chunk leer war (nur Überschriften), wird gemergt. - * *Safety Net:* Wird ein Abschnitt zu lang (> `max` Token), wird auch ohne Überschrift getrennt. -* **Modus "Soft" (`strict_heading_split: false`):** - * **Hierarchie-Check:** Überschriften *oberhalb* des Split-Levels erzwingen **immer** einen Split. - * **Füll-Logik:** Überschriften *auf* dem Split-Level lösen nur dann einen neuen Chunk aus, wenn der aktuelle Chunk die `target`-Größe erreicht hat. - * *Safety Net:* Auch hier greift das `max` Token Limit. +**Kernprinzipien:** +* **Atomic Section Logic:** Überschriften und deren Inhalte werden als atomare Einheiten behandelt und nicht über Chunk-Grenzen hinweg getrennt. +* **H1-Context Preservation:** Der Dokumenttitel (H1) wird zuverlässig als Breadcrumb in das Embedding-Fenster (`window`) aller Chunks injiziert. +* **Signature Alignment:** Parameter-Synchronisierung zwischen Orchestrator und Strategien (`context_prefix` statt `doc_title`). + +**Split Level:** Definiert die Tiefe (z.B. `2` = H1 & H2 triggern Split). + +**Modus "Strict" (`strict_heading_split: true`):** +* Jede Überschrift (`<= split_level`) erzwingt einen neuen Chunk. +* *Merge-Check:* Wenn der vorherige Chunk leer war (nur Überschriften), wird gemergt. +* *Safety Net:* Wird ein Abschnitt zu lang (> `max` Token), wird auch ohne Überschrift getrennt. + +**Modus "Soft" (`strict_heading_split: false`):** +* **Hierarchie-Check:** Überschriften *oberhalb* des Split-Levels erzwingen **immer** einen Split. +* **Füll-Logik:** Überschriften *auf* dem Split-Level lösen nur dann einen neuen Chunk aus, wenn der aktuelle Chunk die `target`-Größe erreicht hat. +* **Pack-and-Carry-Over:** Wenn ein Abschnitt zu groß ist, wird er intelligent zerlegt, wobei der Rest (mit Überschrift) zurück in die Queue gelegt wird. +* *Safety Net:* Auch hier greift das `max` Token Limit. + +### 3.3 Registry-First Profiling (v2.13.12) + +Seit v2.13.12 nutzt der `IngestionService` die korrekte Hierarchie zur Ermittlung des Chunking-Profils: + +**Priorität:** +1. **Frontmatter** (Override) - Explizite `chunking_profile` Angabe +2. **`types.yaml` Typ-Config** - Profil basierend auf `type` +3. **Global Defaults** - Fallback auf `sliding_standard` + +**Wichtig:** Ein Hard-Fallback auf `sliding_standard` erfolgt nur noch, wenn keine Konfiguration existiert. Dies stellt sicher, dass Note-Typen wie `value` automatisch das korrekte Profil (z.B. `structured_smart_edges_strict`) erhalten. + +### 3.4 Deterministic Hashing (v2.13.12) + +Der `full`-Hash inkludiert nun alle strategischen Parameter (z.B. `split_level`, `strict_heading_split`), sodass Konfigurationsänderungen im Frontmatter zwingend einen Re-Import auslösen. + +**Impact:** Änderungen an Chunking-Parametern werden zuverlässig erkannt, auch wenn der Text unverändert bleibt. --- diff --git a/docs/04_Operations/04_admin_operations.md b/docs/04_Operations/04_admin_operations.md index 3797ebc..96f7b1b 100644 --- a/docs/04_Operations/04_admin_operations.md +++ b/docs/04_Operations/04_admin_operations.md @@ -279,4 +279,11 @@ python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet" --yes # 2. Neu importieren (Force Hash recalculation) python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force -``` \ No newline at end of file +``` + +**Wichtig (v2.9.1 Migration):** +Nach dem Update auf v2.9.1 (Section-basierte Links, Multigraph-Support) ist ein vollständiger Re-Import erforderlich, um "Phantom-Knoten" zu beheben und die neue Edge-Struktur zu konsolidieren: +```bash +python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force +``` +Dies stellt sicher, dass alle bestehenden Links korrekt in `target_id` und `target_section` aufgeteilt werden. \ No newline at end of file