419 lines
21 KiB
Markdown
419 lines
21 KiB
Markdown
# Mindnet v2.2 – Fachliche Architektur
|
||
**Datei:** `docs/mindnet_functional_architecture_v2.2.md`
|
||
**Stand:** 2025-12-09
|
||
**Status:** **FINAL** (Integrierter Stand WP01–WP06)
|
||
|
||
> Dieses Dokument beschreibt **was** Mindnet fachlich tut und **warum** – mit Fokus auf die Erzeugung und Nutzung von **Edges** (Kanten), die Logik des Retrievers und den neuen **RAG-Chat** (Decision Engine & Persönlichkeit). Die technische Umsetzung wird im technischen Dokument detailliert.
|
||
|
||
---
|
||
<details>
|
||
<summary>📖 <b>Inhaltsverzeichnis (Klicken zum Öffnen)</b></summary>
|
||
|
||
- [Mindnet v2.2 – Fachliche Architektur](#mindnet-v22--fachliche-architektur)
|
||
- [](#)
|
||
- [0) Zielbild \& Grundprinzip](#0-zielbild--grundprinzip)
|
||
- [1) Notizen \& Chunks (fachliche Perspektive)](#1-notizen--chunks-fachliche-perspektive)
|
||
- [1.1 Notiz (Note)](#11-notiz-note)
|
||
- [1.2 Chunk](#12-chunk)
|
||
- [2) Edges – fachliche Typen \& Bedeutung](#2-edges--fachliche-typen--bedeutung)
|
||
- [2.1 Struktur-Kanten (Das Skelett)](#21-struktur-kanten-das-skelett)
|
||
- [2.2 Inhalts-Kanten (explizit)](#22-inhalts-kanten-explizit)
|
||
- [2.3 Typ-basierte Default-Kanten (Regelbasiert)](#23-typ-basierte-default-kanten-regelbasiert)
|
||
- [3) Edge-Payload – Felder \& Semantik](#3-edge-payload--felder--semantik)
|
||
- [4) Typ-Registry (`config/types.yaml`)](#4-typ-registry-configtypesyaml)
|
||
- [4.1 Zweck](#41-zweck)
|
||
- [4.2 Beispiel (auslieferungsnah)](#42-beispiel-auslieferungsnah)
|
||
- [5) Der Retriever (Funktionaler Layer)](#5-der-retriever-funktionaler-layer)
|
||
- [5.1 Scoring-Modell](#51-scoring-modell)
|
||
- [5.2 Erklärbarkeit (Explainability) – WP04b](#52-erklärbarkeit-explainability--wp04b)
|
||
- [6) Context Intelligence \& Intent Router (WP06)](#6-context-intelligence--intent-router-wp06)
|
||
- [6.1 Das Problem: Statische vs. Dynamische Antworten](#61-das-problem-statische-vs-dynamische-antworten)
|
||
- [6.2 Der Intent-Router (Keyword \& Semantik)](#62-der-intent-router-keyword--semantik)
|
||
- [6.3 Strategic Retrieval (Injektion von Werten)](#63-strategic-retrieval-injektion-von-werten)
|
||
- [6.4 Reasoning (Das Gewissen)](#64-reasoning-das-gewissen)
|
||
- [7) Future Concepts: The Empathic Digital Twin (Ausblick)](#7-future-concepts-the-empathic-digital-twin-ausblick)
|
||
- [7.1 Antizipation durch Erfahrung](#71-antizipation-durch-erfahrung)
|
||
- [7.2 Empathie \& "Ich"-Modus](#72-empathie--ich-modus)
|
||
- [7.3 Glaubenssätze \& Rituale](#73-glaubenssätze--rituale)
|
||
- [8) Erweiterbarkeit \& Teaching (Context Intelligence)](#8-erweiterbarkeit--teaching-context-intelligence)
|
||
- [A. Workflow: Einen neuen Typ implementieren (z. B. `type: risk`)](#a-workflow-einen-neuen-typ-implementieren-z-b-type-risk)
|
||
- [B. Workflow: Neue Beziehungen nutzen (z. B. `beeinflusst_von`)](#b-workflow-neue-beziehungen-nutzen-z-b-beeinflusst_von)
|
||
- [9) Feedback \& Lernen – WP04c](#9-feedback--lernen--wp04c)
|
||
- [9.1 Der Feedback-Loop](#91-der-feedback-loop)
|
||
- [10) Confidence \& Provenance – wozu?](#10-confidence--provenance--wozu)
|
||
- [11) Semantik ausgewählter `kind`-Werte](#11-semantik-ausgewählter-kind-werte)
|
||
- [12) Frontmatter-Eigenschaften – Rolle \& Empfehlung](#12-frontmatter-eigenschaften--rolle--empfehlung)
|
||
- [13) Lösch-/Update-Garantien (Idempotenz)](#13-lösch-update-garantien-idempotenz)
|
||
- [14) Beispiel – Von Markdown zu Kanten (v2.2)](#14-beispiel--von-markdown-zu-kanten-v22)
|
||
- [15) Referenzen (Projektdateien \& Leitlinien)](#15-referenzen-projektdateien--leitlinien)
|
||
- [16) Workpackage Status (v2.3.1)](#16-workpackage-status-v231)
|
||
|
||
</details>
|
||
---
|
||
|
||
## 0) Zielbild & Grundprinzip
|
||
|
||
Mindnet wandelt Obsidian-Markdown-Notizen in einen **dynamischen Graphen aus Punkten und Kanten** um.
|
||
Die drei zentralen Artefakt-Sammlungen lauten:
|
||
|
||
- `mindnet_notes` – genau **eine** Note pro Markdown-Datei (Metadaten & Hashes)
|
||
- `mindnet_chunks` – semantische Teilstücke einer Note (Fenster/„Chunks“)
|
||
- `mindnet_edges` – gerichtete Beziehungen zwischen Knoten (Chunks/Notes)
|
||
|
||
Die Import-Pipeline erzeugt diese Artefakte **deterministisch** und **idempotent** (erneute Läufe überschreiben konsistent statt zu duplizieren). Die Import-Schritte sind: *parse → chunk → edge → upsert*.
|
||
|
||
---
|
||
|
||
## 1) Notizen & Chunks (fachliche Perspektive)
|
||
|
||
### 1.1 Notiz (Note)
|
||
- Repräsentiert eine fachliche Einheit (z. B. *„Vector DB Basics“*, *„KI-Projekt“*).
|
||
- Trägt Eigenschaften (Titel, Typ, Zeitstempel, optionale Policies).
|
||
- **Typ** (*type*) steuert u. a. Chunk-Profil und Default-Relationen (siehe §4).
|
||
- **retriever_weight** und **chunk_profile** werden systematisch an Note **und** Chunks gespiegelt, damit der Retriever beides nutzen kann.
|
||
|
||
### 1.2 Chunk
|
||
- Ausschnitt/Textfenster aus der Note, als eigenständiger Such-Anker.
|
||
- Jeder Chunk gehört **genau einer** Note.
|
||
- Chunks bilden eine Sequenz (1…N) – das ermöglicht *next/prev*.
|
||
- **Neu in v2.2:** Alle Kanten entstehen ausschließlich zwischen Chunks (Scope="chunk"), nie zwischen Notes direkt. Notes dienen nur noch als Metadatencontainer.
|
||
|
||
> **Wichtig:** Chunking-Profile (short/medium/long) kommen aus `types.yaml` (per Note-Typ), können aber lokal überschrieben werden. Die effektiven Werte werden bei der Payload-Erzeugung bestimmt.
|
||
|
||
---
|
||
|
||
## 2) Edges – fachliche Typen & Bedeutung
|
||
|
||
Edges kodieren Beziehungen. Sie sind **gerichtet** und werden in `mindnet_edges` gespeichert. Die Erzeugung folgt einer strengen Priorität: **Inline > Callout > Defaults > Struktur**.
|
||
|
||
### 2.1 Struktur-Kanten (Das Skelett)
|
||
- **belongs_to**: *Chunk → Note* (Zuordnung)
|
||
- **next / prev**: Kettenbeziehungen zwischen aufeinanderfolgenden Chunks derselben Note.
|
||
→ ermöglichen „lineares Weiterlesen“ oder Kontextpfade in Antworten.
|
||
Diese Kanten entstehen immer, unabhängig von Inhalten.
|
||
|
||
### 2.2 Inhalts-Kanten (explizit)
|
||
Hier unterscheidet v2.2 präzise zwischen verschiedenen Quellen der Evidenz:
|
||
|
||
1. **Explizite Inline-Relationen (Höchste Priorität):**
|
||
Im Fließtext notierte, semantisch qualifizierte Relationen.
|
||
* Syntax: `[[rel:depends_on Embeddings 101]]`
|
||
* Fachliche Aussage: "Hängt ab von", "Ähnlich zu".
|
||
* *rule_id*: `inline:rel`
|
||
* *confidence*: ~0.95
|
||
|
||
2. **Callout-Edges (Kuratierte Listen):**
|
||
Redaktionell gepflegte Listen am Ende einer Notiz (z.B. "Siehe auch").
|
||
* Syntax: `> [!edge] related_to: [[Vector DB Basics]]`
|
||
* *rule_id*: `callout:edge`
|
||
* *confidence*: ~0.90
|
||
|
||
3. **Wikilinks (Standard-Referenzen):**
|
||
Der klassische Obsidian-Link.
|
||
* Syntax: `[[Vector DB Basics]]`
|
||
* Typ: `references`
|
||
* *rule_id*: `explicit:wikilink`
|
||
* *confidence*: 1.0
|
||
|
||
> Alle expliziten Quellen (Wikilink, Inline-Rel, Callout) sind **Primärbelege**.
|
||
|
||
### 2.3 Typ-basierte Default-Kanten (Regelbasiert)
|
||
Jede Note hat einen *Typ* (z. B. `concept`, `project`, `profile`). In `config/types.yaml` definieren wir pro Typ **edge_defaults**, z. B.:
|
||
|
||
- `concept`: `["references","related_to"]`
|
||
- `project`: `["references","depends_on"]`
|
||
|
||
Regel: **Für jede gefundene explizite Referenz** (s. o.) werden **zusätzliche** Edges nach diesen Defaults erzeugt.
|
||
Beispiel: Ein *project* mit `edge_defaults=["depends_on"]` erzeugt zu *jedem* explizit referenzierten Ziel **zusätzlich** eine `depends_on`-Kante.
|
||
Diese Kanten tragen *provenance=rule* und eine **rule_id** der Form `edge_defaults:{note_type}:{relation}` sowie eine geringere Confidence (~0.7).
|
||
|
||
---
|
||
|
||
## 3) Edge-Payload – Felder & Semantik
|
||
|
||
Jede Kante hat mindestens:
|
||
|
||
- `kind` – Beziehungsart *(belongs_to, next, prev, references, related_to, depends_on, similar_to, …)*
|
||
- `scope` – `"chunk"` (Standard in v2.2)
|
||
- `source_id`, `target_id` – Quell-/Ziel-Knoten (Chunk-IDs oder Note-Titel bei unresolved Targets)
|
||
- `note_id` – **Owner-Note** (die Note, aus der die Kante stammt)
|
||
|
||
Erweiterte/abgeleitete Felder (WP03 Superset):
|
||
|
||
- `provenance` – `"explicit"` (Wikilink/Inline/Callout) oder `"rule"` (Typ-Defaults)
|
||
- `rule_id` – maschinenlesbare Regelquelle (z.B. `inline:rel`, `edge_defaults:project:depends_on`)
|
||
- `confidence` – 0.0–1.0; Heuristik zur Gewichtung im Scoring.
|
||
|
||
**Dedup-Schlüssel** (fachlich): Gleichlautende `(source_id, target_id, kind, scope, rule_id)` werden nicht mehrfach geschrieben.
|
||
|
||
---
|
||
|
||
## 4) Typ-Registry (`config/types.yaml`)
|
||
|
||
### 4.1 Zweck
|
||
- Steuert **Chunking-Profile** (`short|medium|long`) **pro Typ**
|
||
- Liefert **retriever_weight** (Note-/Chunk-Gewichtung im Ranking) **pro Typ**
|
||
- Definiert **edge_defaults** je Typ (s. o.)
|
||
|
||
Der Importer lädt die Registry aus `MINDNET_TYPES_FILE` oder nutzt Fallbacks. **Frontmatter-Overrides** für Profile werden in v2.2 weitgehend ignoriert zugunsten einer zentralen Governance in der YAML-Datei.
|
||
|
||
### 4.2 Beispiel (auslieferungsnah)
|
||
version: 1.0
|
||
types:
|
||
concept:
|
||
chunk_profile: medium
|
||
edge_defaults: ["references", "related_to"]
|
||
retriever_weight: 0.60
|
||
project:
|
||
chunk_profile: long
|
||
edge_defaults: ["references", "depends_on"]
|
||
retriever_weight: 0.97
|
||
|
||
**Auflösung im Importer**
|
||
- `effective_chunk_profile(note_type, registry)` → `"short|medium|long"|None`
|
||
- `effective_retriever_weight(note_type, registry)` → `float|None`
|
||
- Ergebnis wird in `note_payload` **und** `chunk_payloads` gespiegelt.
|
||
|
||
---
|
||
|
||
## 5) Der Retriever (Funktionaler Layer)
|
||
|
||
Der Retriever ist in v2.2 der zentrale Zugangspunkt. Er realisiert die **Hybride Suche**.
|
||
|
||
### 5.1 Scoring-Modell
|
||
Die Relevanz eines Treffers ergibt sich nicht mehr nur aus Textähnlichkeit, sondern aus einer gewichteten Formel:
|
||
|
||
total_score =
|
||
semantic_weight * semantic_score
|
||
+ edge_weight * edge_bonus
|
||
+ centrality_weight * centrality_bonus
|
||
+ type_weight * retriever_weight
|
||
|
||
* **semantic_score:** Vektorähnlichkeit (Qdrant).
|
||
* **retriever_weight:** Wichtigkeit des Typs (z.B. Projekte > Quellen).
|
||
* **edge_bonus:** Belohnung für Chunks, die im Kontext der Anfrage stark vernetzt sind (Summe der Confidence eingehender relevanter Kanten).
|
||
* **centrality_bonus:** Belohnung für Knoten, die zentrale Hubs im lokalen Graphen darstellen.
|
||
|
||
### 5.2 Erklärbarkeit (Explainability) – WP04b
|
||
Der Retriever ist keine Blackbox mehr. Er liefert auf Wunsch (`explain=True`) eine strukturierte Begründung (`Explanation`-Objekt).
|
||
|
||
**Die "Warum"-Logik:**
|
||
1. **Semantik:** Prüfung der Cosine-Similarity ("Sehr hohe textuelle Übereinstimmung").
|
||
2. **Typ:** Prüfung des `retriever_weight` ("Bevorzugt, da Entscheidung").
|
||
3. **Graph (Kontext):**
|
||
* **Hub (Outgoing):** Worauf verweist dieser Treffer? ("Verweist auf Qdrant").
|
||
* **Authority (Incoming):** Wer verweist auf diesen Treffer? ("Wird referenziert von Projekt Alpha").
|
||
|
||
Die API gibt diese Analysen als menschenlesbare Sätze (`reasons`) und als Datenstruktur (`score_breakdown`) zurück.
|
||
|
||
---
|
||
|
||
## 6) Context Intelligence & Intent Router (WP06)
|
||
|
||
Seit WP06 agiert Mindnet nicht mehr statisch, sondern passt seine Suchstrategie dem **Intent** (der Absicht) des Nutzers an. Dies ist die Transformation vom reinen Wissens-Abrufer zum strategischen Entscheidungspartner.
|
||
|
||
### 6.1 Das Problem: Statische vs. Dynamische Antworten
|
||
* **Früher (Pre-WP06):** Jede Frage ("Was ist X?" oder "Soll ich X?") wurde gleich behandelt -> Fakten-Retrieval.
|
||
* **Heute (WP06):** Das System erkennt, *was* der User will, und lädt unterschiedliche Wissensbausteine.
|
||
|
||
### 6.2 Der Intent-Router (Keyword & Semantik)
|
||
Der Router prüft vor jeder Antwort die Absicht über konfigurierbare Strategien (`config/decision_engine.yaml`):
|
||
|
||
1. **FACT:** Reine Wissensfrage ("Was ist Qdrant?"). → Standard RAG.
|
||
2. **DECISION:** Frage nach Rat oder Strategie ("Soll ich Qdrant nutzen?"). → Aktiviert die Decision Engine.
|
||
3. **EMPATHY:** Emotionale Zustände ("Ich bin gestresst"). → Aktiviert den empathischen Modus.
|
||
4. **CODING:** Technische Anfragen.
|
||
|
||
**Erkennung:**
|
||
* **Fast Path:** Prüfung auf Schlüsselwörter (z.B. "soll ich").
|
||
* **Slow Path (Smart Fallback):** Wenn kein Keyword passt, prüft ein LLM (Phi-3) die Semantik des Satzes.
|
||
|
||
### 6.3 Strategic Retrieval (Injektion von Werten)
|
||
Im Modus `DECISION` führt das System eine **zweite Suchstufe** aus. Es sucht nicht nur nach semantisch passenden Texten zur Frage, sondern erzwingt das Laden von strategischen Notizen wie:
|
||
* **Values (`type: value`):** Moralische Werte (z.B. "Privacy First").
|
||
* **Principles (`type: principle`):** Handlungsanweisungen.
|
||
* **Goals (`type: goal`):** Strategische Ziele.
|
||
|
||
Dies wird über **Late Binding** in `config/decision_engine.yaml` gesteuert. Neue Facetten der Persönlichkeit können dort konfiguriert werden, ohne den Code zu ändern.
|
||
|
||
### 6.4 Reasoning (Das Gewissen)
|
||
Das LLM erhält im Prompt die explizite Anweisung: *"Wäge die Fakten (aus der Suche) gegen die injizierten Werte ab."*
|
||
Dadurch entstehen Antworten, die nicht nur technisch korrekt sind, sondern subjektiv passend ("Tool X passt nicht zu deinem Ziel Z").
|
||
|
||
---
|
||
|
||
## 7) Future Concepts: The Empathic Digital Twin (Ausblick)
|
||
|
||
Um Mindnet von einer Entscheidungsmaschine zu einem echten **Spiegel der Persönlichkeit** zu entwickeln, sind folgende Erweiterungen konzeptionell vorgesehen:
|
||
|
||
### 7.1 Antizipation durch Erfahrung
|
||
* **Konzept:** Das System soll Konsequenzen vorhersagen ("Was passiert, wenn...?").
|
||
* **Umsetzung:** Neben Werten werden vergangene Erfahrungen (`type: experience`) geladen.
|
||
* **Logik:** *"In einer ähnlichen Situation (Projekt A) hat Entscheidung X zu Ergebnis Y geführt."*
|
||
|
||
### 7.2 Empathie & "Ich"-Modus
|
||
* **Konzept:** Das System antwortet nicht wie ein Roboter, sondern im Tonfall und Stil des Nutzers.
|
||
* **Umsetzung (Few-Shot Prompting):** Der System-Prompt wird dynamisch mit Beispielen gefüttert, wie der Nutzer typischerweise auf E-Mails oder Fragen antwortet.
|
||
* **Datenbasis:** `type: profile` oder `type: manifesto` definieren das Selbstbild.
|
||
|
||
### 7.3 Glaubenssätze & Rituale
|
||
* **Konzept:** Berücksichtigung weicher Faktoren und Gewohnheiten.
|
||
* **Umsetzung:** Erweiterung der `decision_engine.yaml` um `inject_types: ["belief", "ritual"]`.
|
||
* **Szenario:** Bei Terminplanungen werden Rituale ("Keine Meetings vor 10 Uhr") automatisch als harte Restriktion gegen Anfragen geprüft.
|
||
|
||
---
|
||
|
||
## 8) Erweiterbarkeit & Teaching (Context Intelligence)
|
||
|
||
Mindnet lernt nicht durch klassisches Training (Fine-Tuning), sondern durch **Konfiguration**, **Vernetzung** und **Prompting**. Dies ist das **"Teach-the-AI" Paradigma**: Wenn du dem System ein neues Konzept beibringen willst, musst du an drei Stellen eingreifen.
|
||
|
||
### A. Workflow: Einen neuen Typ implementieren (z. B. `type: risk`)
|
||
|
||
1. **Physik definieren (`config/types.yaml`)**
|
||
Steuere, wie schwer der Inhalt wiegt und wie er vernetzt wird.
|
||
```yaml
|
||
risk:
|
||
chunk_profile: short # Risiken sind prägnant
|
||
retriever_weight: 0.90 # Hohe Priorität im Ranking
|
||
edge_defaults: ["blocks"] # Automatische Kante zu verlinkten Projekten
|
||
```
|
||
*Effekt:* Der Retriever spült diese Notizen bei relevanten Anfragen nach oben.
|
||
|
||
2. **Semantik erklären (`config/prompts.yaml` / `decision_engine.yaml`)**
|
||
Bringe dem LLM bei, wie es mit diesem Typ umgehen soll. Füge `risk` zur `DECISION`-Strategie hinzu (`inject_types`), damit es bei Entscheidungen geladen wird.
|
||
|
||
### B. Workflow: Neue Beziehungen nutzen (z. B. `beeinflusst_von`)
|
||
|
||
Beziehungen sind der Klebstoff für logische Schlussfolgerungen.
|
||
|
||
1. **Erfassung im Vault (Markdown)**
|
||
Nutze die Inline-Syntax. Du musst nichts vorab definieren.
|
||
> "Die Entscheidung für Qdrant wurde [[rel:beeinflusst_von Budgetkürzung 2024]]."
|
||
|
||
2. **Gewichtung justieren (`config/retriever.yaml`)**
|
||
Standardmäßig sind alle Kanten gleich `1.0`. Wenn Kausalität wichtiger ist als Ähnlichkeit, definiere dies hier:
|
||
```yaml
|
||
retriever:
|
||
edge_weights:
|
||
beeinflusst_von: 1.5 # Starker Boost: Zieht Ursachen in den Kontext
|
||
related_to: 0.5 # Schwacher Boost: Nur "nice to know"
|
||
```
|
||
*Effekt:* Bei der Frage nach "Qdrant" landet die "Budgetkürzung" (Ursache) im Kontext, weil die Kante stark ist.
|
||
|
||
3. **Interpretation (Prompting)**
|
||
Das LLM erkennt im RAG-Kontext: `Qdrant --[beeinflusst_von]--> Budgetkürzung`.
|
||
Es kann daraus den Satz formulieren: *"Die Wahl fiel vermutlich aufgrund der Budgetkürzung auf Qdrant."*
|
||
|
||
**Fazit:** Nur wenn **Daten** (Vault), **Physik** (Config) und **Semantik** (Prompt) zusammenspielen, entsteht ein intelligenter Zwilling.
|
||
|
||
---
|
||
|
||
## 9) Feedback & Lernen – WP04c
|
||
|
||
Das System verfügt nun über ein **Kurzzeitgedächtnis für Interaktionen**, das die Basis für zukünftiges Lernen bildet.
|
||
|
||
### 9.1 Der Feedback-Loop
|
||
1. **Suche (Situation):**
|
||
Wenn ein Nutzer eine Anfrage stellt, loggt Mindnet die "Situation":
|
||
* Den Query-Text.
|
||
* Die Top-K Ergebnisse.
|
||
* Den exakten `score_breakdown` zu diesem Zeitpunkt.
|
||
* Eine eindeutige `query_id` wird generiert.
|
||
|
||
2. **Bewertung (Label):**
|
||
Der Nutzer (oder ein Agent) bewertet einen spezifischen Treffer (`node_id`) positiv oder negativ (Score 1-5).
|
||
Dieses Feedback wird unter Referenzierung der `query_id` gespeichert.
|
||
|
||
3. **Lernen (Perspektive WP08):**
|
||
Durch die Verknüpfung von Situation und Bewertung entstehen Trainingsdaten. Mindnet kann später analysieren: *"Nutzer bevorzugen Treffer mit hohem Edge-Bonus, auch wenn der Text weniger passt."* -> Konsequenz: `edge_weight` erhöhen.
|
||
|
||
---
|
||
|
||
## 10) Confidence & Provenance – wozu?
|
||
|
||
Der Retriever kann Edges gewichten:
|
||
- **provenance**: *explicit* > *rule*
|
||
- **confidence**: numerische Feinsteuerung
|
||
- **retriever_weight (Note/Chunk)**: skaliert die Relevanz des gesamten Knotens
|
||
|
||
Eine typische Gewichtung (konfigurierbar in `retriever.yaml`) ist:
|
||
`explicit: 1.0`, `rule: 0.8`. Damit bevorzugt der Graph **kuratiertes Wissen** (explizit notierte Links) vor „erweiterten“ Default-Ableitungen.
|
||
|
||
---
|
||
|
||
## 11) Semantik ausgewählter `kind`-Werte
|
||
|
||
- `references` – „Nutzt/erwähnt“; neutral, aber stützend für Kontext.
|
||
- `related_to` – Ähnlichkeit/Verwandtschaft (symmetrisch interpretierbar).
|
||
- `similar_to` – noch engere Ähnlichkeit; oft aus Inline-Rel (bewusst gesetzt).
|
||
- `depends_on` – fachliche Abhängigkeit (z. B. „Projekt X hängt von Y ab“).
|
||
- `belongs_to`, `next`, `prev` – Struktur.
|
||
|
||
> Symmetrische Relationen (z. B. `related_to`, `similar_to`) können **explizit** nur einseitig notiert sein, aber im Retriever beidseitig interpretiert werden.
|
||
|
||
---
|
||
|
||
## 12) Frontmatter-Eigenschaften – Rolle & Empfehlung
|
||
|
||
Frontmatter-Eigenschaften (Properties) bleiben **minimiert**:
|
||
- **type** – steuert Typ-Defaults via Registry (Pflicht für differenziertes Verhalten).
|
||
- **tags** – für klassische Filterung.
|
||
- **retriever_weight / chunk_profile** – Sollten **nicht** manuell gesetzt werden (Best Practice: `types.yaml` nutzen).
|
||
- **links** – Veraltet. Bitte Links primär über Text (Wikilink/Inline/Callout) pflegen.
|
||
|
||
---
|
||
|
||
## 13) Lösch-/Update-Garantien (Idempotenz)
|
||
|
||
- Jede Note hat einen stabilen **note_id** (Frontmatter/Hash).
|
||
- Vor einem Upsert können *alte Chunks/Edges einer Note* gefiltert gelöscht werden (`note_id`-Filter) – das hält Collections sauber bei Re-Imports.
|
||
- Die Import-Skripte unterstützen Modi wie `--purge-before-upsert` und `--sync-deletes`, um den Graph sauber zu halten.
|
||
|
||
---
|
||
|
||
## 14) Beispiel – Von Markdown zu Kanten (v2.2)
|
||
|
||
**Markdown (Auszug)**
|
||
# Relations Showcase
|
||
…
|
||
Wir nutzen [[rel:depends_on Qdrant Vektordatenbank]] für die Suche.
|
||
…
|
||
Siehe auch: [[Embeddings 101]]
|
||
|
||
> [!edge] related_to: [[Vector DB Basics]]
|
||
|
||
**Ergebnis (fachlich)**
|
||
1. `depends_on(Chunk→Qdrant)` mit `rule_id=inline:rel`, `confidence≈0.95`.
|
||
2. `references(Chunk→Embeddings 101)` mit `rule_id=explicit:wikilink`, `confidence=1.0`.
|
||
3. `related_to(Chunk→Vector DB Basics)` via Callout; `rule_id=callout:edge`, `confidence≈0.90`.
|
||
4. **Typ-Defaults:** Falls die Note vom Typ `project` ist, entstehen zusätzlich `depends_on`-Kanten zu den Zielen aus (2) und (3).
|
||
|
||
---
|
||
|
||
## 15) Referenzen (Projektdateien & Leitlinien)
|
||
|
||
- Import-Pipeline & Registry-Auflösung: `scripts/import_markdown.py`.
|
||
- Kantenbildung (V2-Logic): `app/core/derive_edges.py`.
|
||
- Typ-Registry: `config/types.yaml` & `TYPE_REGISTRY_MANUAL.md`.
|
||
- Retriever-Scoring & Explanation: `app/core/retriever.py`.
|
||
- Persönlichkeit & Chat: `config/prompts.yaml` & `app/routers/chat.py`.
|
||
- Decision Engine: `config/decision_engine.yaml`.
|
||
- Logging Service: `app/services/feedback_service.py`.
|
||
|
||
---
|
||
|
||
## 16) Workpackage Status (v2.3.1)
|
||
|
||
Aktueller Implementierungsstand der Module.
|
||
|
||
| WP | Titel | Status | Anmerkung |
|
||
| :--- | :--- | :--- | :--- |
|
||
| **WP01** | Knowledge Design | 🟢 Live | Typen, Frontmatter definiert. |
|
||
| **WP02** | Chunking Strategy | 🟢 Live | Profilbasiertes Chunking aktiv. |
|
||
| **WP03** | Edge Logic / Import | 🟢 Live | Neue Importer-Pipeline mit Provenance. |
|
||
| **WP04a**| Retriever Scoring | 🟢 Live | Hybrider Score (Semantik + Graph). |
|
||
| **WP04b**| Explanation Layer | 🟢 Live | API liefert Reasons & Breakdown. |
|
||
| **WP04c**| Feedback Loop | 🟢 Live | Logging (JSONL) & Traceability aktiv. |
|
||
| **WP05** | Persönlichkeit / Chat | 🟢 Live | RAG-Integration mit Context Enrichment. |
|
||
| **WP06** | Decision Engine | 🟢 Live | Intent-Router & Strategic Retrieval. |
|
||
| **WP08** | Self-Tuning | 🔴 Geplant | Auto-Adjustment der Gewichte. | |