mindnet/Programmmanagement/Überarbeitungshinweise_WP04.md

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