# 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