Lars/mindnet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 21 Wiki Activity
6b397fea2e
mindnet/docs/mindnet_functional_architecture.md
Lars 6b397fea2e
All checks were successful
Deploy mindnet to llm-node / deploy (push) Successful in 4s
Details
docs/mindnet_functional_architecture.md aktualisiert
2025-12-08 17:57:51 +01:00

18 KiB
Raw Blame History

Mindnet v2.2 – Fachliche Architektur

Datei: docs/mindnet_functional_architecture_v2.2.md Stand: 2025-12-08 Status: FINAL (Integrierter Stand WP01–WP05)

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 (Persönlichkeit). Die technische Umsetzung wird im technischen Dokument detailliert.

📖 Inhaltsverzeichnis (Klicken zum Öffnen) - [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) Der RAG-Chat \& Persönlichkeit (WP05)](#6-der-rag-chat--persönlichkeit-wp05) - [6.1 Stil \& Tonfall (System Prompt)](#61-stil--tonfall-system-prompt) - [6.2 Strategische Persönlichkeit (Ausblick WP06)](#62-strategische-persönlichkeit-ausblick-wp06) - [7) Erweiterbarkeit \& Teaching (Context Intelligence)](#7-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) - [8) Feedback \& Lernen – WP04c](#8-feedback--lernen--wp04c) - [8.1 Der Feedback-Loop](#81-der-feedback-loop) - [9) Confidence \& Provenance – wozu?](#9-confidence--provenance--wozu) - [10) Semantik ausgewählter `kind`-Werte](#10-semantik-ausgewählter-kind-werte) - [11) Frontmatter-Eigenschaften – Rolle \& Empfehlung](#11-frontmatter-eigenschaften--rolle--empfehlung) - [12) Lösch-/Update-Garantien (Idempotenz)](#12-lösch-update-garantien-idempotenz) - [13) Beispiel – Von Markdown zu Kanten (v2.2)](#13-beispiel--von-markdown-zu-kanten-v22) - [14) Referenzen (Projektdateien \& Leitlinien)](#14-referenzen-projektdateien--leitlinien) - [15) Workpackage Status (v2.3.0)](#15-workpackage-status-v230)
---

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) Der RAG-Chat & Persönlichkeit (WP05)

Seit WP-05 kann Mindnet nicht nur suchen, sondern als KI-Zwilling antworten. Die Persönlichkeit entsteht dabei auf zwei Ebenen:

6.1 Stil & Tonfall (System Prompt)

In config/prompts.yaml wird die Persona definiert.

  • System Prompt: Definiert die Rolle ("Ich bin dein digitales Gedächtnis...").
  • Werte im Prompt: Pragmatismus, Transparenz (kein Halluzinieren), Vernetztes Denken.
  • Context Intelligence: Dem LLM werden Metadaten (Typ, Score) injiziert, damit es komplexe Zusammenhänge erkennt (z.B. dass eine [DECISION] wichtiger ist als ein [CONCEPT]).

6.2 Strategische Persönlichkeit (Ausblick WP06)

Ein echter KI-Zwilling spiegelt nicht nur den Stil, sondern die Werte des Users wider.

  • Logik: Bei komplexen Fragen oder Entscheidungen ("Soll ich X tun?") lädt das System gezielt Notizen vom Typ [VALUE] und [PRINCIPLE] in den Kontext.
  • Effekt: Das System wägt die Fakten (aus der Suche) gegen die Werte (aus dem Profil) ab.

7) 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.

    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) Bringe dem LLM bei, wie es mit diesem Typ umgehen soll.

    system_prompt: |
  ...
  REGELN FÜR TYPEN:
  - [RISK]: Warnung! Wenn ein Chunk vom Typ 'risk' im Kontext ist, weise den User explizit darauf hin.

    Effekt: Der Chatbot ignoriert das Risiko nicht nur, sondern "versteht" die Warnfunktion.

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:

    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.

8) Feedback & Lernen – WP04c

Das System verfügt nun über ein Kurzzeitgedächtnis für Interaktionen, das die Basis für zukünftiges Lernen bildet.

8.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.

9) 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.

10) 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.

11) 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.

12) 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.

13) 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).

14) 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.
  • Logging Service: app/services/feedback_service.py.

15) Workpackage Status (v2.3.0)

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 🟡 Geplant Fokus: Strategic Retrieval von Werten.
WP08 Self-Tuning 🔴 Geplant Auto-Adjustment der Gewichte.