Lars
0f351252b2
All checks were successful
Deploy mindnet to llm-node / deploy (push) Successful in 3s
323 lines
9.7 KiB
Markdown
323 lines
9.7 KiB
Markdown
# 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
|