Dokumentation WP11

This commit is contained in:
Lars committed 2025-12-11 16:58:23 +01:00
1 parent 00aecf692d
commit 5bf91d51da
14 files changed
+319 -208

No files matched your search

@@ -0,0 +1,27 @@
# Architecture Snapshot v2.2.1
**Stand:** Nach Abschluss von WP-04c
**Kontext:** Wichtig für WP-05 Entwicklung.
## 1. Neue Komponenten (Seit v2.2.0)
### A. Feedback Service (`app/services/feedback_service.py`)
- **Zweck:** Logging von Trainingsdaten für späteres Self-Tuning (WP-08).
- **Storage:** Lokale JSONL-Dateien in `data/logs/` (Append-Only).
- `search_history.jsonl`: Query + Snapshot der Ergebnisse (Scores).
- `feedback.jsonl`: User-Rating zu spezifischer `node_id`.
### B. Explanation Layer (`app/core/retriever.py`)
- **Logik:** Der Retriever berechnet nicht nur Scores, sondern generiert `Explanation`-Objekte.
- **Graph:** `Subgraph` (in `graph_adapter.py`) führt jetzt auch `reverse_adj` (Incoming Edges), um zu erklären, warum ein Knoten wichtig ist ("Referenziert von...").
### C. DTOs (`app/models/dto.py`)
Das Datenmodell wurde massiv erweitert. Wichtige Klassen für WP-05:
- `QueryResponse`: Enthält jetzt `query_id` (UUID).
- `QueryHit`: Enthält optional `explanation` (Typ `Explanation`).
- `FeedbackRequest`: Für den Feedback-Loop.
## 2. Implikationen für WP-05 (Chat)
1. **Logging:** Auch der neue `/chat` Endpoint sollte idealerweise die `query_id` loggen oder nutzen, um Konsistenz zu wahren.
2. **DTO-Nutzung:** Der Chat-Service wird intern den Retriever aufrufen. Er muss mit den `QueryHit`-Objekten arbeiten, um den Kontext für das LLM zu bauen.
3. **Config:** Die Persönlichkeit wird in `config/prompts.yaml` definiert (Late Binding), nicht im Python-Code hardcodiert.
+307
View File
@@ -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.
+322
View File
@@ -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