Lars
d7d7411fa0
All checks were successful
Deploy mindnet to llm-node / deploy (push) Successful in 4s
308 lines
7.1 KiB
Markdown
308 lines
7.1 KiB
Markdown
# 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.
|
||
|