Programmmanagement/Überarbeitungshinweise_WP04.md hinzugefügt

Programmmanagement/Überarbeitungshinweise_WP04.md

@@ -0,0 +1,322 @@
+# mindnet – Änderungs- und Ergänzungsleitfaden für bestehende Dokumentation
+# (Stand: Tag Wp04a-Retriever_final)
+
+Dieser Leitfaden listet **alle notwendigen Änderungen und Ergänzungen** für die
+bestehenden Dokumente auf. Er umfasst ausschließlich Inhalte, die durch die
+tatsächliche Implementierung von WP-04a (Retriever, Hybrid Scoring, Graph-Integration,
+retriever.yaml, Explainability-Vorbereitung, Centrality, Edge-Bonus, Query-API)
+betroffen sind.
+
+Er dient dazu, dass ein anderer Chat alle Dokumente vollständig und korrekt
+überarbeiten kann, ohne Interpretationsspielraum oder fehlende Informationen.
+
+
+============================================================
+# 1. Änderungen für: knowledge_design.md
+============================================================
+
+## 1.1 Ergänzen: Rolle von retriever_weight pro Note-Type
+Die Implementierung nutzt `retriever_weight`, das im Importer aus `types.yaml`
+pro Note-Type übernommen und auf *Chunk-Ebene* vererbt wird.
+
+**Ergänzen:**
+- Erklärung, dass `retriever_weight` ein konzeptionelles Typ-Attribut ist,
+  das im hybriden Scoring als Multiplikator wirkt.
+- Klarstellung, dass `retriever_weight` *nicht* durch Markdown-Frontmatter
+  überschrieben werden muss.
+- Dokumentation, dass Qdrant-Payload dieses Feld für Notes und Chunks enthält.
+
+## 1.2 Ergänzen: Edge-Typen, die im Retriever genutzt werden
+Der Retriever unterstützt aktuell:
+- `references`
+- `related_to`
+- `depends_on`
+- `similar_to`
+- `belongs_to`
+- sowie generierte Strukturkanten `next` / `prev`.
+
+**Ergänzen:**
+- Welche Edges für den Graph-Bonus ausgewertet werden.
+- Wie `confidence` aus mindnet_edges genutzt wird.
+
+## 1.3 Ergänzen: Definition des lokalen Subgraphen
+Die reale Retrieval-Logik nutzt:
+- Seed-Notes (aus semantisch Top-K)
+- Expansionstiefe `depth`
+- Edge-Typ-Filter
+- Bonusberechnung pro Knoten
+
+Dies ist im ursprünglichen Dokument nicht beschrieben und muss hinzugefügt werden.
+
+============================================================
+# 2. Änderungen für: chunking_strategy.md
+============================================================
+
+## 2.1 Ergänzen: Chunk-Payload-Felder, die der Retriever nutzt
+Die aktuelle Strategy beschreibt Chunks korrekt, es fehlt jedoch:
+
+**Ergänzen:**
+- `retriever_weight` (vererbt vom Note-Type)
+- `chunk_profile` (aktuell ungenutzt im Retriever, aber Teil der Payload)
+- Hinweise, dass der Retriever nur aus *Chunks* semantische Seeds bildet,
+  das Ranking aber auf *Notes* aggregiert wird.
+
+## 2.2 Ergänzen: Section/Window-Felder und ihre Relevanz
+Die Felder existieren im Qdrant, werden aber im retriever.yaml nicht verändert.
+
+**Hinweis ergänzen:**
+- Der Retriever nutzt aktuell `text` und `window`; kein Einfluss der Abschnittslogik.
+
+
+============================================================
+# 3. Änderungen für: TYPE_REGISTRY_MANUAL.md
+============================================================
+
+Dieses Dokument muss **aktualisiert** werden, da WP-04a folgende Mechanismen nutzt:
+
+## 3.1 Ergänzen: Bedeutung von retriever_weight
+- Definition als quantitatives Typ-Merkmal.
+- Erklärung, dass es in Qdrant gespeichert wird.
+- Erklärung des Einflusses auf Semantikscore:
+    - Formel:  
+      
+          final_semantic = semantic_score * retriever_weight
+
+- Hinweis, dass in future WP-08 das Gewicht durch Feedback lernbar wird.
+
+## 3.2 Ergänzen: Neue Edge-Typen und ihre Standard-Konfiguration
+- `similar_to`
+- `belongs_to`
+- Strukturkanten `next` / `prev`
+
+Diese sind im Importer bereits aktiv, aber nicht ausreichend dokumentiert.
+
+## 3.3 Ergänzen: Edge-Konfidenzen
+Die automatische Edge-Ableitung generiert `confidence`.  
+Retriever nutzt diesen Wert linear im Edge-Bonus.
+
+**Dokumentation muss ergänzt werden.**
+
+
+============================================================
+# 4. Änderungen für: docs_mindnet_retriever.md
+============================================================
+
+Dieses Dokument ist am stärksten betroffen und muss auf den Stand der tatsächlichen
+Implementierung aktualisiert werden.
+
+## 4.1 Aktualisieren: Gesamtscoring-Formel
+Bisher: Semantik + einfache Typgewichtung.
+
+Neu implementiert:
+
+    total_score =
+        semantic_weight     * semantic_score
+      + edge_weight         * edge_bonus
+      + centrality_weight   * centrality_bonus
+
+Diese Formel muss vollständig dokumentiert werden.
+
+## 4.2 Aktualisieren: Einführung retriever.yaml
+Dokumentation benötigt:
+
+- Speicherort: `app/config/retriever.yaml`
+- Default-Werte
+- Abschnittsweise Beschreibung:
+    - semantic_weight
+    - edge_weight
+    - centrality_weight
+- Hinweis: Änderungen wirken ohne Codeänderung.
+
+## 4.3 Ergänzen: Beschreibung Graph-Expansion
+Der Retriever nutzt:
+
+- Expand-depth (default 1)
+- Edge-Typ-Filter
+- Aggregation pro Node
+- Bonus-Skalierung
+
+Diese Logik ist neu und muss detailliert erklärt werden.
+
+## 4.4 Ergänzen: Beschreibung centrality_bonus
+Aktuell:
+- proportionale Verteilung anhand Knotendichte
+- Normalisierung über lokales Subgraph-Maß
+
+Dokumentation muss Minimum enthalten:
+- wie centrality gewichtet wird
+- welche Grenze existieren
+
+## 4.5 Ergänzen: Explainability-Schnittstelle (WP-04b Vorbereitung)
+Die Implementierung erzeugt intern:
+- edge_bonus pro Node
+- centrality_bonus pro Node
+- Liste der Edges, die beteiligt waren
+
+Diese Werte sind abrufbar und müssen dokumentiert werden.
+
+## 4.6 Ergänzen: Fehlertoleranzen & Timeout (Health Check)
+Der Retriever kann:
+- Fallback auf Vektor-Suche (pure semantic)
+- Fallback bei fehlendem expand
+
+Diese Sicherheitsmechanismen müssen dokumentiert werden.
+
+
+============================================================
+# 5. Änderungen für: mindnet_technical_architecture.md
+============================================================
+
+## 5.1 Ergänzen: Komponentenübersicht Retrieval-Layer
+Eine neue Abbildung oder Abschnitt muss hinzu:
+
+- QueryRequest-Parsing
+- Embedding-Lookup oder Vector-Passthrough
+- Semantic Seed Search (Qdrant)
+- Graph-Expansion (mindnet_edges)
+- Node-/Note-Aggregation
+- Score-Combination
+- Response-Ausgabe via FastAPI
+
+## 5.2 Ergänzen: Datenstruktur mindnet_edges
+Vor WP-04 nicht vollständig dokumentiert.
+
+Benötigt:
+
+- Felder:
+    - edge_id
+    - kind
+    - source_id
+    - target_id
+    - confidence
+    - rule_id
+- Wie Edges im Retriever ausgewertet werden.
+
+## 5.3 Ergänzen: retriever.yaml als Konfigurationsquelle
+Architekturdiagramm muss updated werden:
+- Retriever nutzt YAML  
+- Keine Hardcodierung im Python
+
+## 5.4 Ergänzen: Health Check Script
+Technischer Abschnitt muss dokumentieren:
+
+- health_check_mindnet.py
+- Semantik:
+    - semantic query
+    - hybrid query
+- Fehlercodes
+
+
+============================================================
+# 6. Änderungen für: mindnet_functional_architecture.md
+============================================================
+
+## 6.1 Ergänzen: Funktionale Rolle des Retrievers
+Retriever ist jetzt:
+
+- Teil des Functional Layers
+- Grundlage für Agenten / Decision Engine
+- Hauptquelle für Begründungen
+
+## 6.2 Ergänzen: Einbindung des Explainability-Layers
+Funktional gehört dies zwischen:
+- Retriever  
+- Antwortgenerierung (LLM)  
+
+Der Explainability-Layer formuliert Gründe:
+- Welche Edges?
+- Welche Scores?
+- Warum diese Note?
+
+## 6.3 Ergänzen: Self-Tuning als neuen Funktionsblock (WP-08)
+Muss aufgenommen werden:
+
+- Logging von Feedback
+- Bewertung
+- Tuning der retriever.yaml
+- Human-in-the-loop Freigabe
+
+
+============================================================
+# 7. Änderungen für: wp04_retriever_scoring.md
+============================================================
+
+Dieses Dokument ist **direkt WP-04** und muss am stärksten überarbeitet werden.
+
+## 7.1 Aktualisieren: Finale Scoring-Formel
+Die Formel muss exakt so dokumentiert werden, wie inzwischen implementiert.
+
+## 7.2 Ergänzen: Bonusberechnung
+Die bisherige Planung wurde implementiert, aber der Text muss aktualisiert werden:
+
+- Bonusberechnung je Edge
+- confidence-Einfluss
+- Node-Aggregation
+- Note-Aggregation
+
+## 7.3 Ergänzen: Centrality
+Dokument ist zu ergänzen um:
+
+- Definition
+- Berechnung
+- Normalisierung
+- Gewichtung über retriever.yaml
+
+## 7.4 Ergänzen: Teststrategie
+Die finale Testbasis muss dokumentiert werden:
+
+- Unit-Tests
+- Hybrid-Tests
+- API-Tests
+- Smoke-Test
+- Diagnose-Skripte
+
+## 7.5 Ergänzen: Einschränkungen & Offene Punkte
+Hinweis für WP-04b:
+- Explainability fehlt noch
+- Edge-Type Weights noch nicht implementiert
+- Self-Tuning in WP-08
+
+
+============================================================
+# 8. Änderungen für: mindnet_v2_implementation_playbook.md
+============================================================
+
+## 8.1 Ergänzen: Arbeitsablauf mit Retriever
+Einrichtung, Nutzung und Test sollte ergänzt werden:
+
+- Starten von FastAPI
+- Testen des Retrievers via health_check
+- Import-Workflow (neue Vaults → Qdrant → Retriever)
+
+## 8.2 Ergänzen: Konfigurationsverwaltung
+Einbindung in Gitea-Workflows:
+- retriever.yaml versionieren
+- Tags/Branches für Funktionsstände setzen
+
+## 8.3 Ergänzen: Self-Tuning-Prozess (nur Rahmen)
+Der Playbook-Abschnitt soll die späteren Mechanismen vorbeschreiben.
+
+
+============================================================
+# 9. Änderungen für: Handbuch.md
+============================================================
+
+## 9.1 Ergänzen: Einfache Erklärung des Retrievers
+Das Handbuch benötigt eine verständliche, nicht-technische Beschreibung:
+
+- Was macht der Retriever?
+- Warum kommt ein Ergebnis zustande?
+- Welche Rolle spielen Edges?
+- Wie kann der Nutzer die Gewichtung beeinflussen (YAML)?
+
+## 9.2 Ergänzen: Troubleshooting
+Aufnehmen:
+- „Ergebnisse wirken unpassend“ → Prüfe retriever.yaml
+- „Edge-Bonus fehlt“ → Prüfe mindnet_edges
+- health_check-Skript nutzen
+
+## 9.3 Ergänzen: API-Nutzung für Endanwender
+Einfacher Abschnitt:
+- Wie man `/query` testet
+- Beispiele für semantic & hybrid queries