erster Aufschlag WP22

This commit is contained in:
Lars committed 2025-12-18 11:50:52 +01:00
1 parent 77a6db7e92
commit e2ee5df815
7 files changed
+313 -106

No files matched your search

-89
View File
@@ -1,89 +0,0 @@
---
doc_type: reference
audience: author
status: active
context: "Zentrales Wörterbuch für Kanten-Bezeichner (Edges). Referenz für Autoren zur Wahl des richtigen Verbindungstyps."
---
# Edge Vocabulary & Semantik
**Standort:** `01_User_Manual/01_edge_vocabulary.md`
**Zweck:** Damit Mindnet "verstehen" kann, was eine Verbindung bedeutet (z.B. für "Warum"-Fragen), nutzen wir konsistente Begriffe.
**Die Goldene Regel:**
Nutze bevorzugt den **System-Typ** (linke Spalte). Wenn dieser sprachlich nicht passt, nutze einen der **erlaubten Aliasse** (und bleibe dabei konsistent).
---
## 1. Kausalität & Logik ("Warum?")
*Verbindungen, die Gründe, Ursachen oder Herleitungen beschreiben.*
| System-Typ (Canonical) | Erlaubte Aliasse (User) | Wann nutzen? |
| :--- | :--- | :--- |
| **`caused_by`** | `ausgelöst_durch`, `wegen`, `ursache_ist` | Wenn A der direkte Auslöser für B ist. (Technisch/Faktisch) |
| **`derived_from`** | `abgeleitet_von`, `quelle`, `inspiriert_durch` | Wenn eine Idee/Prinzip aus einer Quelle stammt (z.B. Buch, Zitat). |
| **`based_on`** | `basiert_auf`, `fundament`, `grundlage` | Wenn B nicht existieren könnte ohne das fundamentale Konzept A (z.B. Werte). |
| **`solves`** | `löst`, `beantwortet`, `fix_für` | Wenn A eine Lösung für das Problem B ist. |
## 2. Struktur & Hierarchie ("Wo gehört es hin?")
*Verbindungen, die Ordnung schaffen.*
| System-Typ (Canonical) | Erlaubte Aliasse (User) | Wann nutzen? |
| :--- | :--- | :--- |
| **`part_of`** | `teil_von`, `gehört_zu`, `cluster` | Harte Hierarchie. Projekt A ist Teil von Programm B. |
| **`belongs_to`** | *(System-Intern)* | Automatisch generiert (Chunk -> Note). Nicht manuell nutzen. |
## 3. Abhängigkeit & Einfluss ("Was brauche ich?")
*Verbindungen, die Blockaden oder Voraussetzungen definieren.*
| System-Typ (Canonical) | Erlaubte Aliasse (User) | Wann nutzen? |
| :--- | :--- | :--- |
| **`depends_on`** | `hängt_ab_von`, `braucht`, `requires`, `enforced_by` | Harte Abhängigkeit. Ohne A kann B nicht starten/existieren. |
| **`blocks`** | `blockiert`, `verhindert`, `risiko_für` | Wenn A ein aktives Hindernis für B ist. |
| **`uses`** | `nutzt`, `verwendet`, `tool` | Wenn A ein Werkzeug/Methode B einsetzt (z.B. Projekt nutzt Python). |
| **`guides`** | `steuert`, `leitet`, `orientierung` | (Alias für `depends_on` oder `related_to`) Weiche Abhängigkeit, z.B. Prinzipien steuern Verhalten. |
## 4. Zeit & Prozess ("Was kommt dann?")
*Verbindungen für Abläufe zwischen verschiedenen Notizen.*
| System-Typ (Canonical) | Erlaubte Aliasse (User) | Wann nutzen? |
| :--- | :--- | :--- |
| **`next`** | `danach`, `folgt`, `nachfolger`, `followed_by` | Manuell: Wenn Notiz A logisch vor Notiz B kommt (Prozesskette: A -> B). |
| **`prev`** | `davor`, `vorgänger`, `preceded_by` | Manuell: Der vorherige Prozessschritt (B -> A). |
## 5. Assoziation ("Was ist ähnlich?")
*Lose Verbindungen für Entdeckungen.*
| System-Typ (Canonical) | Erlaubte Aliasse (User) | Wann nutzen? |
| :--- | :--- | :--- |
| **`related_to`** | `siehe_auch`, `kontext`, `thematisch` | Wenn zwei Dinge etwas miteinander zu tun haben, ohne strikte Logik. |
| **`similar_to`** | `ähnlich_wie`, `vergleichbar` | Wenn A und B fast das Gleiche sind (z.B. Synonyme, Alternativen). |
| **`references`** | *(Kein Alias)* | Standard für "erwähnt einfach nur". (Niedrigste Prio). |
---
## Best Practices für Autoren
### A. Der "Callout"-Standard (Footer)
Sammle Verbindungen, die für die **ganze Notiz** gelten, am Ende der Datei in einem Bereich `## Kontext & Verbindungen`.
```markdown
## Kontext & Verbindungen
> [!edge] derived_from
> [[Buch der Weisen]]
> [!edge] part_of
> [[Leitbild – Identity Core]]
```
### B. Der "Inline"-Standard (Präzision)
Nutze Inline-Kanten nur, wenn du im Fließtext eine **spezifische Aussage** triffst, die im Graph sichtbar sein soll.
* *Schlecht:* "Das [[rel:related_to Projekt]] ist wichtig." (Wenig Aussagekraft)
* *Gut:* "Dieser Fehler wird [[rel:caused_by Systemabsturz]] verursacht." (Starke Kausalität)
### C. Konsistenz-Check
Bevor du ein neues Wort (z.B. `ermöglicht`) nutzt:
1. Prüfe diese Liste: Passt `solves` oder `depends_on`?
2. Falls nein: Schreibe `ermöglicht` in die Spalte "Erlaubte Aliasse" oben und ordne es einem System-Typ zu.
+18 -1
View File
@@ -47,7 +47,7 @@ Eine Übersicht der implementierten Features zum schnellen Auffinden von Funktio
| **WP-19** | Graph Visualisierung | **Frontend Modularisierung:** Umbau auf `ui_*.py`.<br>**Graph Engines:** Parallelbetrieb von Cytoscape (COSE) und Agraph.<br>**Tools:** "Single Source of Truth" Editor, Persistenz via URL. |
| **WP-20** | Cloud Hybrid Mode | Nutzung von Public LLM für schnellere Verarbeitung und bestimmte Aufgaben |
| **WP-21** | Semantic Graph Routing & Canonical Edges | Transformation des Graphen von statischen Verbindungen zu dynamischen, kontextsensitiven Pfaden. Das System soll verstehen, *welche* Art von Verbindung für die aktuelle Frage relevant ist ("Warum?" vs. "Was kommt danach?"). |
| **WP-22** | Content Lifecycle & Meta-Configuration | Professionalisierung der Datenhaltung durch Einführung eines Lebenszyklus (Status) und "Docs-as-Code" Konfiguration. |
---
## 3. Offene Workpackages (Planung)
@@ -123,6 +123,23 @@ Diese Features stehen als nächstes an oder befinden sich in der Umsetzung.
3. **Graph Reasoning:**
* Der Retriever priorisiert Pfade, die dem semantischen Muster der Frage entsprechen, nicht nur dem Text-Match.
### WP-22 – Content Lifecycle & Meta-Configuration
**Status:** 🟡 Geplant
**Ziel:** Professionalisierung der Datenhaltung durch Einführung eines Lebenszyklus (Status) und "Docs-as-Code" Konfiguration.
**Problem:**
1. **Müll im Index:** Unfertige Ideen (`draft`) oder System-Dateien (`templates`) verschmutzen die Suchergebnisse.
2. **Redundanz:** Kanten-Typen müssen in Python-Code und Obsidian-Skripten doppelt gepflegt werden.
**Lösungsansätze:**
1. **Status-Logik (Frontmatter):**
* `status: system` / `template` → **Hard Skip** im Importer (Kein Index).
* `status: draft` vs. `stable` → **Scoring Modifier** im Retriever (Stabiles Wissen wird bevorzugt).
2. **Single Source of Truth (SSOT):**
* Die Datei `01_edge_vocabulary.md` wird zur führenden Konfiguration.
* Eine neue `Registry`-Klasse liest diese Markdown-Datei beim Start und validiert Kanten dagegen.
3. **Self-Learning Loop:**
* Unbekannte Kanten-Typen (vom User neu erfunden) werden nicht verworfen, sondern in ein `unknown_edges.jsonl` Log geschrieben, um das Vokabular organisch zu erweitern.
---
## 4. Abhängigkeiten & Release-Plan
+63 -1
View File
@@ -253,4 +253,66 @@ Bitte bestätige die Übernahme, erstelle die `edge_mappings.yaml` Struktur und
* Wir haben den `HybridRouter` (aus WP-06) schon. Er "versteht" bereits, was der User will (`DECISION` vs `EMPATHY`).
* Es ist der logisch perfekte Ort, um zu sagen: "Wenn der User im Analyse-Modus ist, sind Fakten-Kanten wichtiger als Gefühls-Kanten."
Damit hast du das perfekte Paket für den nächsten Entwicklungsschritt geschnürt!
Damit hast du das perfekte Paket für den nächsten Entwicklungsschritt geschnürt!
## WP-22: Content Lifecycle & Meta-Config
**Status:** 🚀 Startklar
**Fokus:** Ingestion-Filter, Scoring-Logik, Registry-Architektur.
```text
Du bist der Lead Architect für "Mindnet" (v2.7).
Wir starten ein umfassendes Architektur-Paket: **WP-22: Graph Intelligence & Lifecycle**.
**Kontext:**
Wir professionalisieren die Datenhaltung ("Docs as Code") und machen die Suche kontextsensitiv.
Wir haben eine Markdown-Datei (`01_edge_vocabulary.md`), die als Single-Source-of-Truth für Kanten-Typen dient.
**Dein Auftrag:**
Implementiere (A) den Content-Lifecycle, (B) die Edge-Registry und (C) das Semantic Routing.
---
### Teil A: Content Lifecycle (Ingestion Logic)
Steuerung über Frontmatter `status`:
1. **System-Dateien (No-Index):**
* Wenn `status` in `['system', 'template']`: **Hard Skip**. Datei wird nicht vektorisiert.
2. **Wissens-Status (Scoring):**
* Wenn `status` in `['draft', 'active', 'stable']`: Status wird im Payload gespeichert.
* **ToDo:** Erweitere `scoring.py`, damit `stable` Notizen einen Bonus erhalten (`x 1.2`), `drafts` einen Malus (`x 0.5`).
---
### Teil B: Central Edge Registry & Validation
1. **Registry Klasse:**
* Erstelle `EdgeRegistry` (Singleton).
* Liest beim Start `01_User_Manual/01_edge_vocabulary.md` (Regex parsing der Tabelle).
* Stellt `canonical_types` und `aliases` bereit.
2. **Rückwärtslogik (Learning):**
* Prüfe beim Import jede Kante gegen die Registry.
* Unbekannte Typen werden **nicht** verworfen, sondern in `data/logs/unknown_edges.jsonl` geloggt (für späteres Review).
---
### Teil C: Semantic Graph Routing (Dynamic Boosting)
**Ziel:** Die Bedeutung einer Kante soll sich je nach Frage-Typ ändern ("Warum" vs. "Wie").
**Architektur-Vorgabe (WICHTIG):**
Die Gewichtung findet **Pre-Retrieval** (im Scoring-Algorithmus) statt, **nicht** im LLM-Prompt.
1. **Decision Engine (`decision_engine.yaml`):**
* Füge `boost_edges` zu Strategien hinzu.
* *Beispiel:* `EXPLANATION` (Warum-Fragen) -> Boost `caused_by: 2.5`, `derived_from: 2.0`.
* *Beispiel:* `ACTION` (Wie-Fragen) -> Boost `next: 3.0`, `depends_on: 2.0`.
2. **Scoring-Logik (`scoring.py`):**
* Der `Retriever` erhält vom Router die `boost_edges` Map.
* Berechne Score: `BaseScore * (1 + ConfigWeight + DynamicBoost)`.
---
**Deine Aufgaben:**
1. Zeige die `EdgeRegistry` Klasse (Parsing Logik).
2. Zeige die Integration in `ingestion.py` (Status-Filter & Edge-Validierung).
3. Zeige die Erweiterung in `scoring.py` (Status-Gewicht & Dynamic Edge Boosting).
Bitte bestätige die Übernahme dieses Architektur-Pakets.