From d7d7411fa061f1c406478d2215199c86dd990955 Mon Sep 17 00:00:00 2001 From: Lars Date: Sat, 6 Dec 2025 18:30:08 +0100 Subject: [PATCH] =?UTF-8?q?Programmmanagement/=C3=9Cberarbeitungshinweise?= =?UTF-8?q?=5FWP03.md=20hinzugef=C3=BCgt?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../Überarbeitungshinweise_WP03.md | 307 ++++++++++++++++++ 1 file changed, 307 insertions(+) create mode 100644 Programmmanagement/Überarbeitungshinweise_WP03.md diff --git a/Programmmanagement/Überarbeitungshinweise_WP03.md b/Programmmanagement/Überarbeitungshinweise_WP03.md new file mode 100644 index 0000000..3dbaae7 --- /dev/null +++ b/Programmmanagement/Überarbeitungshinweise_WP03.md @@ -0,0 +1,307 @@ +# mindnet v2 — Dokumentationsreview (vollständig & konsolidiert) + +Dieses Dokument fasst alle notwendigen Anpassungen der mindnet-v2 Dokumentation zusammen. +Der Fokus liegt ausschließlich auf Aspekten, die durch die aktuellen Arbeiten verändert wurden: + +- neue Edge-Mechanik +- neuer Importer +- neues Verhalten von note_payload & chunk_payload +- Default-Typregeln aus `types.yaml` +- Inline- und Callout-Relations +- WP04a – Einführung der Retriever-Schicht +- neue Diagnose- und Testskripte + +Es handelt sich um eine strukturelle Analyse. +Nichts davon überschreibt bestehende Inhalte — es markiert nur, **was angepasst werden muss**. + +--- + +# 1) knowledge_design.md +## Erforderliche Anpassungen + +### 1.1 Neue Edge-Arten dokumentieren +Es müssen vier neue Kategorien beschrieben werden: + +1. **Inline-Edges** + + Beispiel: + `[ [rel:depends_on Embeddings 101] ]` + (Leerzeichen hier zur Demonstration; im echten Dokument ohne Leerzeichen) + +2. **Callout-Edges** + + > [!edge] related_to: [[Vector DB Basics]] [[Embeddings 101]] + +3. **Typbasierte Default-Kanten** + Aus `types.yaml` → `edge_defaults` + +4. **Strukturkanten** + - belongs_to + - next + - prev + +### 1.2 Neue Edge-Felder ergänzen +Jeder Edge enthält jetzt: + +- `rule_id` +- `confidence` +- `scope = "chunk"` +- deterministischer `edge_id` + +Diese Felder müssen vollständig erklärt werden. + +### 1.3 Chunk-basierte Kanten +Neu: **Alle Kanten entstehen ausschließlich zwischen Chunks**, nie zwischen Notes. +Notes dienen nur noch als Metadatencontainer. + +--- + +# 2) TYPE_REGISTRY_MANUAL.md +## Erforderliche Anpassungen + +### 2.1 Typauflösung dokumentieren +Die Regeln sind jetzt: + +- Typ aus Frontmatter → höchste Priorität +- Falls nicht gesetzt: Typ aus Dateipfad ableiten +- Falls unbekannt: Fallback auf `types.default` +- Typ definiert: + - retriever_weight + - chunk_profile + - edge_defaults + +Diese müssen klar dokumentiert werden. + +### 2.2 Neue Fallback-Regeln +Wenn Werte fehlen, werden sie ersetzt durch: + + types.default.retriever_weight + types.default.chunk_profile + types.default.edge_defaults + +### 2.3 Beispiele aktualisieren +Alle Beispiele müssen auf die neue Inline-Syntax angepasst werden. + +--- + +# 3) wp04_retriever_scoring.md +## Erforderliche Anpassungen + +### 3.1 Neue Scoring-Formel + total_score = + semantic_weight * semantic_score + + edge_weight * edge_bonus + + centrality_weight * centrality_bonus + + type_weight * retriever_weight + +### 3.2 Bedeutung von `confidence` +confidence wirkt multiplikativ bei edge_bonus. +Inline > Callout > Default (Standardwerte im Code hinterlegt). + +### 3.3 Pfadbegründungen +Der Retriever gibt optional `paths[]` zurück: + + paths: [ + { + "via": "depends_on", + "confidence": 0.7, + "hops": ["Note A", "Chunk A#01", "Note B"] + } + ] + +Diese Funktion müssen dokumentiert werden. + +--- + +# 4) mindnet_v2_implementation_playbook.md +## Erforderliche Anpassungen + +### 4.1 Neuer Import-Prozess vollständig dokumentieren +Der Importer läuft jetzt so: + +1. Markdown lesen +2. Frontmatter extrahieren +3. Typauflösung via `types.yaml` +4. Note-Payload generieren +5. Chunking anwenden +6. Inline-Kanten finden +7. Callout-Kanten finden +8. Default-Edges erzeugen +9. Strukturkanten erzeugen +10. Chunks in Qdrant upserten +11. Edges upserten +12. Diagnose laufen lassen: + + python3 -m scripts.payload_dryrun + python3 -m scripts.edges_full_check + +### 4.2 Erweiterte Testpipeline +Neu zu dokumentieren: + + tests.test_edges_all + scripts.edges_full_check + scripts.payload_dryrun + +Diese Testschritte sind jetzt Standardanforderung nach jeder Änderung. + +--- + +# 5) mindnet_technical_architecture.md +## Erforderliche Anpassungen + +### 5.1 Aktualisiertes Schema für Qdrant Collections + +#### Notes: + note_id + title + type + fulltext + retriever_weight + chunk_profile + edge_defaults + tags + updated + +#### Chunks: + chunk_id + note_id + text + window + ord + retriever_weight + chunk_profile + neighbors_prev + neighbors_next + +#### Edges: + edge_id + source_id + target_id + kind + scope = "chunk" + rule_id + confidence + +### 5.2 Dokumentation der Edge-Pipeline +Neu beschreiben: + +- Inline-Parser +- Callout-Parser +- Default-Edge-Resolver +- Strukturkanten +- Normalisierung für Qdrant +- deterministische ID-Bildung + +--- + +# 6) mindnet_functional_architecture.md +## Erforderliche Anpassungen + +### 6.1 Inline-Relations – einzig gültige Syntax +Nur diese Syntax erzeugt Kanten: + + [[rel:depends_on Embeddings 101]] + +Nicht unterstützt: + + rel:depends_on [[Embeddings 101]] + +Dies muss klar dokumentiert werden. + +### 6.2 Prioritäten der Kantenerzeugung +Gültige Reihenfolge: + +1. Inline +2. Callout +3. Typdefaults +4. Strukturkanten + +### 6.3 Relaunch der Chunk-zentrierten Funktionslogik +Alle Beispiele müssen angepasst werden. + +--- + +# 7) chunking_strategy.md +## Erforderliche Änderungen + +### 7.1 Neues Verhalten der Chunks +- `ord` ist jetzt Sortierkriterium +- `window` wird über chunk_config erzeugt +- Chunkprofile kommen ausschließlich aus `types.yaml` + +### 7.2 Best Practices erneuern +Empfehlung: + +- keine manuelle Chunkprofile mehr im Frontmatter setzen + +--- + +# 8) docs_mindnet_retriever.md +## Erforderliche Änderungen + +### 8.1 Neue Ausgabeparameter dokumentieren +Retriever liefert jetzt: + + semantic_score + edge_bonus + centrality_bonus + type_score + total_score + paths[] + +### 8.2 Graph-Expansion +Dokumentieren: + +- Seed-Auswahl +- Depth-Limit +- Edge-Filterung +- Wirkung von `confidence` auf edge_bonus + +--- + +# 9) Handbuch.md +## Erforderliche Änderungen + +### 9.1 Neuer Import-Workflow +Erläuterung der Parser: + +- Inline-Parser +- Callout-Parser +- Default-Kanten +- Struktur-Kanten + +### 9.2 Best Practices +Ergänzen: + +- Typenpflege erfolgt nur in `types.yaml` +- Tests immer nach Änderungen ausführen + +--- + +# Gesamtübersicht der notwendigen Anpassungen + +| Dokument | Anpassungsbedarf | +|---------|------------------| +| knowledge_design.md | neue Edge-Arten, Felder, Chunk-Edges | +| TYPE_REGISTRY_MANUAL.md | Typauflösung, neue Felder, neue Fallbacks | +| wp04_retriever_scoring.md | neue Score-Formel, Pfade, confidence | +| implementation_playbook.md | neuer Importprozess, Tests | +| technical_architecture.md | aktualisierte Schemas | +| functional_architecture.md | Syntax + Prioritäten | +| chunking_strategy.md | ord, window, neue Profile | +| docs_mindnet_retriever.md | neue API-Parameter | +| Handbuch.md | Parser + Best Practices | + +--- + +# Empfehlung zur Umsetzung +1. Dieses Review-Dokument als Master-Referenz verwenden. +2. Jedes Dokument strikt nur an den beschriebenen Stellen anpassen. +3. Überprüfen, ob Wann/Wo Typen, Kanten und Parser erklärt werden. +4. Nach jeder Anpassung Testlauf: + + python3 -m scripts.payload_dryrun + python3 -m scripts.edges_full_check + +5. Danach Playbook + Programmplan updaten. +