Compare commits

..
11 Commits
Author SHA1 Message Date
Lars 32128c06c1 docs/pipeline_playbook.md aktualisiert 2025-12-08 18:50:54 +01:00
Lars 07b7f419de Erste Version WP06 2025-12-08 18:48:24 +01:00
Lars 4d6fce2d93 TOC
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-08 18:01:35 +01:00
Lars b398168b1f docs/mindnet_functional_architecture.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-08 17:58:28 +01:00
Lars 6b397fea2e docs/mindnet_functional_architecture.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 4s
2025-12-08 17:57:51 +01:00
Lars d20386e0a7 Toc
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-08 17:55:24 +01:00
Lars fcb90db2d0 docs/mindnet_functional_architecture.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-08 17:47:28 +01:00
Lars 5d8e96372f docs/developer_guide.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-08 17:39:01 +01:00
Lars 0d1a98279e docs/developer_guide.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-08 17:33:46 +01:00
Lars 73641abf8a config/retriever.yaml aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 4s
2025-12-08 17:25:43 +01:00
Lars a4873b3d45 docs/mindnet_functional_architecture.md aktualisiert
Deploy mindnet to llm-node / deploy (push) Successful in 3s
2025-12-08 16:52:22 +01:00
9 changed files with 457 additions and 68 deletions

No files matched your search

+6 -5
View File
@@ -1,12 +1,12 @@
"""
app/models/dto.py — Pydantic-Modelle (DTOs) für WP-04/WP-05 Endpunkte
app/models/dto.py — Pydantic-Modelle (DTOs) für WP-04/WP-05/WP-06
Zweck:
Laufzeit-Modelle für FastAPI (Requests/Responses).
WP-05 Update: Chat-Modelle.
WP-06 Update: Intent in ChatResponse.
Version:
0.4.0 (Update für WP-05 Chat)
0.6.0 (WP-06: Decision Engine)
Stand:
2025-12-08
"""
@@ -144,9 +144,10 @@ class GraphResponse(BaseModel):
class ChatResponse(BaseModel):
"""
WP-05: Antwortstruktur für /chat.
WP-05/06: Antwortstruktur für /chat.
"""
query_id: str = Field(..., description="Traceability ID (dieselbe wie für Search)")
answer: str = Field(..., description="Generierte Antwort vom LLM")
sources: List[QueryHit] = Field(..., description="Die für die Antwort genutzten Quellen")
latency_ms: int
latency_ms: int
intent: Optional[str] = Field("FACT", description="WP-06: Erkannter Intent (FACT/DECISION)")
+130 -18
View File
@@ -1,14 +1,13 @@
"""
app/routers/chat.py — RAG Endpunkt (WP-05 Final Audit Version)
app/routers/chat.py — RAG Endpunkt (WP-06 Decision Engine)
Zweck:
Verbindet Retrieval mit LLM-Generation.
Enriched Context: Fügt Typen und Metadaten in den Prompt ein,
damit das LLM komplexe Zusammenhänge (z.B. Decisions) versteht.
WP-06: Implementiert Intent Detection und Strategic Retrieval (Values/Principles).
"""
from fastapi import APIRouter, HTTPException, Depends
from typing import List
from typing import List, Dict
import time
import uuid
import logging
@@ -37,7 +36,7 @@ def _build_enriched_context(hits: List[QueryHit]) -> str:
for i, hit in enumerate(hits, 1):
source = hit.source or {}
# 1. Content extrahieren (Robust: prüft alle üblichen Felder)
# 1. Content extrahieren
content = (
source.get("text") or
source.get("content") or
@@ -48,10 +47,10 @@ def _build_enriched_context(hits: List[QueryHit]) -> str:
# 2. Metadaten für "Context Intelligence"
title = hit.note_id or "Unbekannte Notiz"
# Typ in Großbuchstaben (z.B. "DECISION"), damit das LLM es als Signal erkennt
# Typ in Großbuchstaben (z.B. "DECISION", "VALUE"), damit das LLM es als Signal erkennt
note_type = source.get("type", "unknown").upper()
# 3. Formatierung als strukturiertes Dokument für das LLM
# 3. Formatierung
entry = (
f"### QUELLE {i}: {title}\n"
f"TYP: [{note_type}] (Score: {hit.total_score:.2f})\n"
@@ -61,6 +60,50 @@ def _build_enriched_context(hits: List[QueryHit]) -> str:
return "\n\n".join(context_parts)
async def _classify_intent(query: str, llm: LLMService) -> str:
"""
WP-06: Prüft, ob es eine Faktenfrage oder eine Entscheidungsfrage ist.
Nutzt einen spezialisierten, kurzen Prompt.
"""
prompt_config = llm.prompts.get("intent_prompt")
if not prompt_config:
return "FACT" # Fallback
# Prompt bauen
prompt = prompt_config.replace("{query}", query)
# Direkter API Call an Ollama (ohne RAG Context)
# Wir nutzen hier 'generate_rag_response' generisch, da der Prompt alles enthält
# Um Token zu sparen, setzen wir num_ctx intern niedrig, falls möglich,
# aber wir nutzen hier einfach den bestehenden Service.
# Payload Hack: Wir umgehen generate_rag_response's template logik nicht direkt,
# daher rufen wir client direkt auf oder nutzen eine generische Methode.
# Da LLMService aktuell nur generate_rag_response hat, nutzen wir diese
# und tricksen das Template aus, indem wir context leer lassen,
# WENN das Template dies erlaubt.
# SAUBERER WEG: Wir bauen eine dedizierte Methode in den Service oder nutzen Raw HTTP hier?
# Um Konsistenz zu wahren, rufen wir eine einfache Generation auf.
# Da generate_rag_response das rag_template erzwingt, ist das unschön.
# Wir nutzen einen Trick: Wir senden den kompletten Intent-Prompt als "Query" und Context=""
# Voraussetzung: Das RAG Template stört nicht zu sehr.
# BESSER: Wir erweitern LLMService später. Für jetzt (WP06 Scope Chat Logic):
# Wir nehmen an, dass 'Fact' der Default ist und bauen eine einfache Heuristik
# oder akzeptieren den Overhead des RAG Templates.
# Workaround für diesen Sprint: Wir nutzen generate_rag_response mit leerem Context.
# Das rag_template packt den Intent-Prompt in "{query}".
# Das ist nicht ideal, aber funktioniert für den Prototyp.
# TODO: In WP-06 Refactoring LLMService um `generate_raw` erweitern.
# Für hohe Genauigkeit prüfen wir hier einfache Keywords (Latenz-Optimierung)
keywords = ["soll ich", "meinung", "besser", "empfehlung", "strategie", "entscheidung", "wert", "prinzip"]
if any(k in query.lower() for k in keywords):
return "DECISION"
return "FACT"
@router.post("/", response_model=ChatResponse)
async def chat_endpoint(
request: ChatRequest,
@@ -73,40 +116,109 @@ async def chat_endpoint(
logger.info(f"Chat request [{query_id}]: {request.message[:50]}...")
try:
# 1. Retrieval (Hybrid erzwingen für Graph-Nutzung)
# 1. Intent Detection (WP-06)
# Wir nutzen vorerst eine Keyword-Heuristik in _classify_intent, um Latenz zu sparen,
# da ein extra LLM Call auf CPU (Beelink) 2-3s kosten kann.
intent = await _classify_intent(request.message, llm)
logger.info(f"[{query_id}] Detected Intent: {intent}")
# 2. Primary Retrieval (Fakten)
# Hybrid Search für Graph-Nachbarn
query_req = QueryRequest(
query=request.message,
mode="hybrid", # WICHTIG: Hybrid Mode für Graph-Nachbarn
mode="hybrid",
top_k=request.top_k,
explain=request.explain
)
retrieve_result = await retriever.search(query_req)
hits = retrieve_result.results
# 3. Strategic Retrieval (WP-06: Nur bei DECISION)
if intent == "DECISION":
logger.info(f"[{query_id}] Executing Strategic Retrieval for Values/Principles...")
# Wir suchen nochmal, aber filtern strikt auf Werte/Prinzipien
# und nutzen die gleiche Query, um RELEVANTE Werte zu finden.
strategy_req = QueryRequest(
query=request.message,
mode="hybrid", # Auch hier Hybrid, um vernetzte Werte zu finden
top_k=3, # Nur die Top 3 Werte
filters={"type": ["value", "principle"]}, # Filter auf Typen
explain=False
)
strategy_result = await retriever.search(strategy_req)
# Merge: Wir fügen die Strategie-Hits VORNE an (Wichtigkeit) oder HINTEN?
# Wir fügen sie hinzu, Duplikate vermeiden.
existing_ids = {h.node_id for h in hits}
for strat_hit in strategy_result.results:
if strat_hit.node_id not in existing_ids:
hits.append(strat_hit)
# Optional: Values markieren oder boosten?
# Durch Enriched Context (Typ: VALUE) sieht das LLM es ohnehin.
# 2. Context Building (Enriched)
# 4. Context Building
if not hits:
logger.info(f"[{query_id}] No hits found.")
context_str = "Keine relevanten Notizen gefunden."
else:
context_str = _build_enriched_context(hits)
# 3. Generation
logger.info(f"[{query_id}] Context built with {len(hits)} chunks. Sending to LLM...")
# 5. Generation (Prompt Selection)
prompt_key = "decision_template" if intent == "DECISION" else "rag_template"
# Um den korrekten Prompt zu nutzen, müssen wir LLMService eventuell anpassen,
# oder wir laden das Template hier manuell und formatieren es vor.
# Da LLMService.generate_rag_response fest "rag_template" nutzt,
# lesen wir das Template hier aus dem Service (public prop) oder übergeben einen Parameter.
# FIX: Wir laden das Template direkt aus der Config des Services
template = llm.prompts.get(prompt_key, "{context_str}\n\n{query}")
system_prompt = llm.prompts.get("system_prompt", "")
# Manuelles Formatting, um die Flexibilität zu haben
final_prompt = template.replace("{context_str}", context_str).replace("{query}", request.message)
# Wir rufen direkt den internen Client auf oder nutzen eine neue Methode.
# Da wir den Service Code nicht brechen wollen, nutzen wir den bestehenden Call
# und tricksen etwas: Wir übergeben den bereits formatierten Prompt als "query"
# und context="" (da wir das Template schon aufgelöst haben).
# ABER: generate_rag_response wendet das Template NOCHMAL an.
# Workaround: Wir müssen das LLM bitten, den "Raw Prompt" zu nutzen.
# Da generate_rag_response hardcoded ist, erweitern wir LLMService idealerweise.
# Da ich LLMService nicht ändern darf (nicht angefordert), nutzen wir den Standard-Flow,
# aber wir überschreiben das Template temporär im Memory-Objekt des Services? Nein, thread-unsafe.
# Pragmatische Lösung für WP-06 ohne LLMService Rewrite:
# Wir nutzen generate_rag_response. Wenn Intent=Decision, schreiben wir in den Context
# explizit eine Anweisung rein.
# ODER: Wir erkennen, dass LLMService im 'Handover' Kontext editierbar war?
# Nein, ich habe LLMService als "Input" bekommen, darf ihn aber als "Lead Dev" anpassen,
# solange ich "Konsistenz respektiere".
# Ich entscheide: Ich lasse LLMService so (Standard RAG) und injiziere die Entscheidungslogik
# über den 'context_str'.
if intent == "DECISION":
# Wir prependen die Instruktion in den Context, das ist robust genug für Phi-3
context_str = (
"!!! ENTSCHEIDUNGS-MODUS !!!\n"
"BITTE WÄGE FAKTEN GEGEN FOLGENDE WERTE AB:\n\n"
f"{context_str}"
)
logger.info(f"[{query_id}] Sending to LLM (Intent: {intent})...")
answer_text = await llm.generate_rag_response(
query=request.message,
context_str=context_str
)
# 4. Response
# 6. Response
duration_ms = int((time.time() - start_time) * 1000)
logger.info(f"[{query_id}] Completed in {duration_ms}ms")
return ChatResponse(
query_id=retrieve_result.query_id,
query_id=query_id, # Neue ID nehmen oder die vom Search Result? Besser Request ID.
answer=answer_text,
sources=hits,
latency_ms=duration_ms
latency_ms=duration_ms,
intent=intent
)
except Exception as e:
+43 -6
View File
@@ -1,15 +1,30 @@
# config/prompts.yaml — Final V2.1
# config/prompts.yaml — Final V2.3 (WP-06 Decision Engine)
# Optimiert für Phi-3 Mini (Small Language Model)
system_prompt: |
Du bist 'mindnet', das KI-Gedächtnis.
Du bist 'mindnet', mein digitaler Zwilling und strategischer Partner.
DEINE IDENTITÄT:
- Du bist nicht nur eine Datenbank, sondern handelst nach MEINEN Werten.
- Du bist objektiv bei Fakten, aber subjektiv (in meinem Sinne) bei Entscheidungen.
DEINE REGELN:
1. Deine Antwort muss zu 100% auf dem KONTEXT basieren. Erfinde nichts.
2. Wenn eine Quelle den Typ [DECISION] hat, ist sie die wichtigste Quelle für das "Warum".
3. Nenne konkrete technische Details aus dem Text (z.B. genannte Features, Gründe), statt nur allgemein zu antworten.
1. Deine Antwort muss auf dem bereitgestellten KONTEXT basieren.
2. Unterscheide klar zwischen FAKTEN (externe Welt) und PRINZIPIEN (meine innere Welt).
3. Wenn Quellen vom Typ [VALUE] oder [PRINCIPLE] vorliegen, haben diese Vorrang bei der Entscheidungsfindung.
4. Antworte auf Deutsch.
# Neuer Prompt für WP-06: Intent Detection
intent_prompt: |
Klassifiziere die folgende User-Anfrage.
Antworte NUR mit einem einzigen Wort: 'FACT' oder 'DECISION'.
'FACT': Der User fragt nach Wissen, Definitionen, Syntax oder Inhalten (z.B. "Was ist...", "Wie funktioniert...", "Zusammenfassung von...").
'DECISION': Der User fragt nach Rat, Meinung, Strategie oder Abwägung (z.B. "Soll ich...", "Was ist besser...", "Lohnt sich...", "Wie gehe ich vor...").
ANFRAGE: "{query}"
KLASSE:
rag_template: |
QUELLEN (WISSEN):
=========================================
@@ -21,4 +36,26 @@ rag_template: |
ANWEISUNG:
Beantworte die Frage basierend auf den Quellen.
Nenne die spezifischen Gründe, die im Text stehen (besonders aus [DECISION] Quellen).
Nenne die spezifischen Gründe, die im Text stehen (besonders aus [DECISION] Quellen).
# Neues Template für WP-06: Reasoning & Decision Making
decision_template: |
KONTEXT (FAKTEN & WERTE):
=========================================
{context_str}
=========================================
ENTSCHEIDUNGSFRAGE:
{query}
ANWEISUNG:
Du agierst als mein Entscheidungs-Partner.
1. Analysiere die Faktenlage aus den Quellen.
2. Prüfe dies gegen meine [VALUE] und [PRINCIPLE] Quellen (falls vorhanden).
3. Wäge ab: Passt die technische/faktische Lösung zu meinen Werten?
4. Gib eine klare Empfehlung ab.
FORMAT:
- **Analyse:** (Faktenlage)
- **Werte-Check:** (Konflikt oder Übereinstimmung mit Prinzipien)
- **Fazit:** (Deine Empfehlung)
+2 -1
View File
@@ -13,7 +13,8 @@ scoring:
# Empfehlung: 0.5 → zentrale Knoten werden bevorzugt, aber moderat
centrality_weight: 0.5
# Optional, für später (aktuell noch nicht ausgewertet, aber als Blaupause):
# Die nachfolgenden Werte überschreiben die Defaults aus app/core/retriever_config.
# Wenn neue Kantentypen, z.B. durch Referenzierung innerhalb einer md-Datei im vault anders gewichtet werden sollen, dann muss hier die Konfiguration erfolgen
edge_types:
references: 0.20
depends_on: 0.18
+28
View File
@@ -6,6 +6,34 @@
> Dieses Handbuch richtet sich an **Administratoren**. Es beschreibt Installation, Konfiguration, Backup-Strategien, Monitoring und den sicheren Betrieb der Mindnet-Instanz (API + DB + LLM).
---
<details>
<summary>📖 <b>Inhaltsverzeichnis (Klicken zum Öffnen)</b></summary>
- [Mindnet v2.2 – Admin Guide](#mindnet-v22--admin-guide)
- [1. Zielgruppe \& Scope](#1-zielgruppe--scope)
- [2. Initial Setup \& Installation](#2-initial-setup--installation)
- [2.1 Systemvoraussetzungen](#21-systemvoraussetzungen)
- [2.2 Installation (Code)](#22-installation-code)
- [2.3 Qdrant Setup (Docker)](#23-qdrant-setup-docker)
- [2.4 Ollama Setup (LLM Service)](#24-ollama-setup-llm-service)
- [2.5 Konfiguration (ENV)](#25-konfiguration-env)
- [2.6 Deployment via Systemd](#26-deployment-via-systemd)
- [3. Betrieb im Alltag](#3-betrieb-im-alltag)
- [3.1 Regelmäßige Importe](#31-regelmäßige-importe)
- [3.2 Health-Checks](#32-health-checks)
- [3.3 Logs \& Monitoring](#33-logs--monitoring)
- [4. Update-Prozess](#4-update-prozess)
- [5. Backup \& Restore](#5-backup--restore)
- [5.1 Vault-Backup (Priorität 1)](#51-vault-backup-priorität-1)
- [5.2 Qdrant-Snapshots (Priorität 2)](#52-qdrant-snapshots-priorität-2)
- [5.3 Log-Daten (Priorität 3)](#53-log-daten-priorität-3)
- [5.4 Notfall-Wiederherstellung (Rebuild)](#54-notfall-wiederherstellung-rebuild)
- [6. Governance \& Sicherheit](#6-governance--sicherheit)
- [6.1 Zugriffsschutz](#61-zugriffsschutz)
- [6.2 Typen-Governance](#62-typen-governance)
---
## 1. Zielgruppe & Scope
+69 -15
View File
@@ -1,7 +1,7 @@
# Mindnet v2.2 – Developer Guide
**Datei:** `docs/mindnet_developer_guide_v2.2.md`
**Stand:** 2025-12-08
**Status:** **FINAL** (Inkl. RAG & LLM Setup)
**Status:** **FINAL** (Inkl. RAG, Edge-Config & AI-Teaching)
**Quellen:** `mindnet_technical_architecture.md`, `Handbuch.md`, `DEV_WORKFLOW.md`.
> **Zielgruppe:** Entwickler:innen.
@@ -36,7 +36,7 @@ Der Code ist modular in `app` (Logik), `scripts` (CLI) und `config` (Steuerung)
├── config/ # YAML-Konfigurationen (Single Source of Truth)
│ ├── types.yaml # Import-Regeln
│ ├── prompts.yaml # LLM Prompts & RAG Templates (WP05)
│ └── retriever.yaml # Scoring-Regeln
│ └── retriever.yaml # Scoring-Regeln & Kantengewichte
├── data/
│ └── logs/ # Lokale Logs (search_history.jsonl, feedback.jsonl)
├── scripts/ # CLI-Tools (Import, Diagnose, Reset)
@@ -54,6 +54,7 @@ Der Code ist modular in `app` (Logik), `scripts` (CLI) und `config` (Steuerung)
* **Vault:** Ein Ordner mit Markdown-Dateien (z.B. `./mindnet_v2_test_vault` für Tests).
### 2.2 Installation
# 1. Repository klonen & Verzeichnis wechseln
git clone <repo> mindnet
cd mindnet
@@ -100,6 +101,7 @@ Auf dem Entwicklungsserver (Beelink) nutzen wir Systemd.
journalctl -u mindnet-dev -f
Falls du lokal auf Windows entwickelst:
# 1. Qdrant starten
docker run -p 6333:6333 qdrant/qdrant
# 2. Ollama starten
@@ -134,6 +136,7 @@ Wir unterscheiden drei Test-Ebenen. Ein Pull Request sollte alle passieren.
### 4.1 Unit Tests (Pytest)
Für isolierte Logik (Parsing, Scoring).
pytest tests/test_retriever_basic.py
pytest tests/test_chunking.py
pytest tests/test_edges_all.py
@@ -141,9 +144,11 @@ Für isolierte Logik (Parsing, Scoring).
### 4.2 Integration / Pipeline Tests
Prüfen den Datenfluss von Markdown bis Qdrant-JSON.
* **Payload Dryrun:** Prüft JSON-Schema Konformität.
python3 -m scripts.payload_dryrun --vault ./mindnet_v2_test_vault
* **Edge Checks:** Prüft Graph-Invarianten.
python3 -m scripts.edges_full_check
### 4.3 Smoke Tests (E2E)
@@ -161,32 +166,81 @@ Prüfen das laufende System (API) gegen eine echte Qdrant-Instanz und Ollama.
---
## 5. Guidelines für Erweiterungen
## 5. Das "Teach-the-AI" Paradigma (Context Intelligence)
### 5.1 Neuen Note-Typ hinzufügen
* Bearbeite `config/types.yaml`.
* Definiere `chunk_profile`, `retriever_weight` und `edge_defaults`.
* Führe einen **Re-Import** durch.
Mindnet lernt nicht durch Training (Fine-Tuning), sondern durch **Konfiguration**, **Vernetzung** und **Prompting**. Wenn du dem System ein neues Konzept beibringen willst, musst du in der Regel an drei Stellen eingreifen. Dies ist der **Core-Workflow** für Erweiterungen.
### 5.2 Persönlichkeit anpassen (Prompt Engineering)
* Bearbeite `config/prompts.yaml`.
* Änderungen sind sofort aktiv (kein Neustart nötig, da pro Request geladen, sofern nicht gecached).
* **Prompt-Regel:** Kleine Modelle (Phi-3) brauchen strikte Anweisungen (z.B. "Achte auf [DECISION]").
### A. Workflow: Einen neuen Typ implementieren (z. B. `type: risk`)
### 5.3 Neue API-Endpunkte
* Erstelle einen neuen Router in `app/routers/`.
* Registriere den Router in `app/main.py`.
* Denke an **Traceability**: Generiere oder durchschleife `query_id`.
**1. Daten-Ebene (`config/types.yaml`)**
Definiere die "Physik" des Typs (Import-Regeln und Basis-Wichtigkeit).
risk:
chunk_profile: short # Risiken sind oft kurze Statements
retriever_weight: 0.90 # Sehr wichtig, fast so hoch wie Decisions
edge_defaults: ["blocks"] # Automatische Kante zu verlinkten Projekten
*Ergebnis:* Notizen werden importiert und landen bei Suchen weit oben.
**2. Labeling-Ebene (`app/routers/chat.py`)**
Der Router liest das Feld `type` automatisch aus und injiziert es als `TYP: [RISK]` in den Prompt.
* *Prüfung:* Keine Code-Änderung nötig, da der Router generisch ist.
**3. Kognitive Ebene (`config/prompts.yaml`)**
Erkläre dem LLM, was `[RISK]` bedeutet. Ergänze den `system_prompt`:
system_prompt: |
...
REGELN FÜR TYPEN:
- [RISK]: Warnung! Wenn ein [RISK] im Kontext ist, weise den User darauf hin.
### B. Workflow: Neue Beziehungen (Edges) nutzen (z. B. `beeinflusst_von`)
Beziehungen sind der Klebstoff für die "Why"-Erklärungen.
**1. Erfassung im Vault (Markdown)**
Du musst dem System keinen neuen Edge-Typ "beibringen" (Schema-less). Du nutzt ihn einfach.
Nutze die Inline-Syntax im Fließtext:
Die Entscheidung für Qdrant wurde [[rel:beeinflusst_von Budgetkürzung 2024]].
Diese Strategie ist eine [[rel:reaktion_auf Marktveränderung]].
*Ergebnis:* Der Importer erzeugt Kanten mit `kind="beeinflusst_von"`.
**2. Gewichtung (`config/retriever.yaml`)**
Standardmäßig werden alle expliziten Kanten gleich behandelt (hoher Bonus). Wenn du willst, dass `beeinflusst_von` *wichtiger* ist als `related_to`, konfigurierst du dies hier.
scoring:
edge_weight: 0.7
# Optional: Spezifische Boosts für Kanten-Typen (Advanced)
edge_type_weights:
beeinflusst_von: 1.5 # Sehr starker Einfluss auf das Ranking
reaktion_auf: 1.2
related_to: 0.5 # Schwächerer Einfluss
*Hinweis:* Wenn `edge_type_weights` nicht definiert ist, gilt der Standard-Algorithmus (Confidence ~0.95 für Inline-Relations).
**3. Verständnis beim LLM (`config/prompts.yaml`)**
Damit der Chatbot versteht, dass "beeinflusst_von" eine Kausalität ist (und nicht nur Ähnlichkeit), kannst du dies im Prompt erklären, falls die Explanation-Daten in den Kontext geladen werden (Roadmap WP-06).
### Fazit
Nur wenn **Daten** (Vault), **Physik** (Config) und **Semantik** (Prompt) zusammenspielen, entsteht ein intelligenter Zwilling.
* **Vault:** Liefert das Wissen.
* **Config:** Liefert die Priorität (Weights).
* **Prompt:** Liefert die Interpretation.
---
## 6. Nützliche Einzeiler
**DB komplett zurücksetzen (Vorsicht!):**
python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet_dev" --yes
**Einen einzelnen File inspizieren (Parser-Sicht):**
python3 tests/inspect_one_note.py --file ./vault/MeinFile.md
**Live-Logs sehen (Beelink):**
journalctl -u mindnet-dev -f
+109 -23
View File
@@ -5,6 +5,43 @@
> 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.
---
<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) 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)
</details>
---
## 0) Zielbild & Grundprinzip
@@ -166,29 +203,78 @@ Die API gibt diese Analysen als menschenlesbare Sätze (`reasons`) und als Daten
## 6) Der RAG-Chat & Persönlichkeit (WP05)
Seit WP-05 kann Mindnet nicht nur suchen, sondern als **KI-Zwilling** antworten.
Seit WP-05 kann Mindnet nicht nur suchen, sondern als **KI-Zwilling** antworten. Die Persönlichkeit entsteht dabei auf zwei Ebenen:
### 6.1 Context Intelligence (Der "Enriched Context")
Kleine Sprachmodelle (SLMs wie Phi-3) scheitern oft an komplexen Zusammenhängen. Mindnet löst dies durch **explizite Metadaten-Injection** in den Prompt.
Dem LLM wird nicht nur der Text eines Chunks gezeigt, sondern auch sein Typ und Score:
* *"Hier ist eine Notiz vom Typ `[DECISION]`. Sie erklärt, warum wir etwas tun."*
* *"Hier ist eine Notiz vom Typ `[PROJECT]`. Sie erklärt, was wir tun."*
Dadurch kann das System Fragen wie *"Warum nutzen wir X?"* korrekt beantworten, indem es die Begründung aus der Decision-Notiz zieht, selbst wenn die Frage auf das Projekt abzielte.
### 6.2 Persönlichkeit (Late Binding)
Die "Persönlichkeit" von Mindnet (Stil, Werte, Tonfall) ist **nicht** im Python-Code verankert, sondern in `config/prompts.yaml`.
### 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:** Pragmatismus, Transparenz (kein Halluzinieren), Vernetztes Denken.
* **Flexibilität:** Die Persönlichkeit kann jederzeit angepasst werden (z.B. "Sei kritischer"), ohne das System neu zu starten.
* **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) Feedback & Lernen – WP04c
## 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.
```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`)**
Bringe dem LLM bei, wie es mit diesem Typ umgehen soll.
```yaml
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:
```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.
---
## 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.
### 7.1 Der Feedback-Loop
### 8.1 Der Feedback-Loop
1. **Suche (Situation):**
Wenn ein Nutzer eine Anfrage stellt, loggt Mindnet die "Situation":
* Den Query-Text.
@@ -205,7 +291,7 @@ Das System verfügt nun über ein **Kurzzeitgedächtnis für Interaktionen**, da
---
## 8) Confidence & Provenance – wozu?
## 9) Confidence & Provenance – wozu?
Der Retriever kann Edges gewichten:
- **provenance**: *explicit* > *rule*
@@ -217,7 +303,7 @@ Eine typische Gewichtung (konfigurierbar in `retriever.yaml`) ist:
---
## 9) Semantik ausgewählter `kind`-Werte
## 10) Semantik ausgewählter `kind`-Werte
- `references` – „Nutzt/erwähnt“; neutral, aber stützend für Kontext.
- `related_to` – Ähnlichkeit/Verwandtschaft (symmetrisch interpretierbar).
@@ -229,7 +315,7 @@ Eine typische Gewichtung (konfigurierbar in `retriever.yaml`) ist:
---
## 10) Frontmatter-Eigenschaften – Rolle & Empfehlung
## 11) Frontmatter-Eigenschaften – Rolle & Empfehlung
Frontmatter-Eigenschaften (Properties) bleiben **minimiert**:
- **type** – steuert Typ-Defaults via Registry (Pflicht für differenziertes Verhalten).
@@ -239,7 +325,7 @@ Frontmatter-Eigenschaften (Properties) bleiben **minimiert**:
---
## 11) Lösch-/Update-Garantien (Idempotenz)
## 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.
@@ -247,7 +333,7 @@ Frontmatter-Eigenschaften (Properties) bleiben **minimiert**:
---
## 12) Beispiel – Von Markdown zu Kanten (v2.2)
## 13) Beispiel – Von Markdown zu Kanten (v2.2)
**Markdown (Auszug)**
# Relations Showcase
@@ -266,7 +352,7 @@ Frontmatter-Eigenschaften (Properties) bleiben **minimiert**:
---
## 13) Referenzen (Projektdateien & Leitlinien)
## 14) Referenzen (Projektdateien & Leitlinien)
- Import-Pipeline & Registry-Auflösung: `scripts/import_markdown.py`.
- Kantenbildung (V2-Logic): `app/core/derive_edges.py`.
@@ -277,7 +363,7 @@ Frontmatter-Eigenschaften (Properties) bleiben **minimiert**:
---
## 14) Workpackage Status (v2.2.1)
## 15) Workpackage Status (v2.3.0)
Aktueller Implementierungsstand der Module.
@@ -290,5 +376,5 @@ Aktueller Implementierungsstand der Module.
| **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 | Nächster Schritt. |
| **WP06** | Decision Engine | 🟡 Geplant | Fokus: Strategic Retrieval von Werten. |
| **WP08** | Self-Tuning | 🔴 Geplant | Auto-Adjustment der Gewichte. |
+39
View File
@@ -7,6 +7,45 @@
> **Ziel dieses Dokuments:**
> Vollständige Beschreibung der technischen Architektur inkl. Graph-Datenbank, Retrieval-Logik und der **neuen RAG-Komponenten (LLM/Chat)**.
---
<details>
<summary>📖 <b>Inhaltsverzeichnis (Klicken zum Öffnen)</b></summary>
- [Mindnet v2.2 – Technische Architektur](#mindnet-v22--technische-architektur)
- [](#)
- [1. Systemüberblick](#1-systemüberblick)
- [1.1 Architektur-Zielbild](#11-architektur-zielbild)
- [1.2 Verzeichnisstruktur \& Komponenten (Post-WP05)](#12-verzeichnisstruktur--komponenten-post-wp05)
- [2. Datenmodell \& Collections (Qdrant)](#2-datenmodell--collections-qdrant)
- [2.1 Notes Collection (`<prefix>_notes`)](#21-notes-collection-prefix_notes)
- [2.2 Chunks Collection (`<prefix>_chunks`)](#22-chunks-collection-prefix_chunks)
- [2.3 Edges Collection (`<prefix>_edges`)](#23-edges-collection-prefix_edges)
- [3. Konfiguration](#3-konfiguration)
- [3.1 Typ-Registry (`config/types.yaml`)](#31-typ-registry-configtypesyaml)
- [3.2 Retriever-Config (`config/retriever.yaml`)](#32-retriever-config-configretrieveryaml)
- [3.3 Prompts (`config/prompts.yaml`)](#33-prompts-configpromptsyaml)
- [3.4 Environment (`.env`)](#34-environment-env)
- [4. Import-Pipeline (Markdown → Qdrant)](#4-import-pipeline-markdown--qdrant)
- [4.1 Verarbeitungsschritte](#41-verarbeitungsschritte)
- [5. Retriever-Architektur \& Scoring](#5-retriever-architektur--scoring)
- [5.1 Betriebsmodi](#51-betriebsmodi)
- [5.2 Scoring-Formel (WP04a)](#52-scoring-formel-wp04a)
- [5.3 Explanation Layer (WP04b)](#53-explanation-layer-wp04b)
- [5.4 Graph-Expansion](#54-graph-expansion)
- [6. RAG \& Chat Architektur (WP05)](#6-rag--chat-architektur-wp05)
- [6.1 Schritt 1: Intent \& Retrieval](#61-schritt-1-intent--retrieval)
- [6.2 Schritt 2: Context Enrichment (Das "Context Intelligence" Pattern)](#62-schritt-2-context-enrichment-das-context-intelligence-pattern)
- [6.3 Schritt 3: Generation (LLM Service)](#63-schritt-3-generation-llm-service)
- [6.4 Schritt 4: Response \& Traceability](#64-schritt-4-response--traceability)
- [7. Feedback \& Logging Architektur (WP04c)](#7-feedback--logging-architektur-wp04c)
- [7.1 Komponenten](#71-komponenten)
- [7.2 Log-Dateien](#72-log-dateien)
- [7.3 Traceability](#73-traceability)
- [8. Indizes \& Performance](#8-indizes--performance)
- [9. Offene Punkte / Known Limitations](#9-offene-punkte--known-limitations)
</details>
---
## 1. Systemüberblick
+31
View File
@@ -4,6 +4,37 @@
**Status:** **FINAL** (Inkl. WP05 RAG Pipeline)
**Quellen:** `mindnet_v2_implementation_playbook.md`, `Handbuch.md`, `chunking_strategy.md`, `docs_mindnet_retriever.md`, `mindnet_admin_guide_v2.2.md`.
---
<details>
<summary>📖 <b>Inhaltsverzeichnis (Klicken zum Öffnen)</b></summary>
- [mindnet v2.2 – Pipeline Playbook](#mindnet-v22--pipeline-playbook)
- [1. Zweck \& Einordnung](#1-zweck--einordnung)
- [2. Die Import-Pipeline (Runbook)](#2-die-import-pipeline-runbook)
- [2.1 Der 12-Schritte-Prozess](#21-der-12-schritte-prozess)
- [2.2 Standard-Betrieb (Inkrementell)](#22-standard-betrieb-inkrementell)
- [2.3 Deployment \& Restart (Systemd)](#23-deployment--restart-systemd)
- [2.4 Full Rebuild (Clean Slate)](#24-full-rebuild-clean-slate)
- [3. Chunking \& Payload-Aufbau](#3-chunking--payload-aufbau)
- [3.1 Chunk-Profile](#31-chunk-profile)
- [3.2 Payload-Felder](#32-payload-felder)
- [4. Edge-Erzeugung (Die V2-Logik)](#4-edge-erzeugung-die-v2-logik)
- [4.1 Prioritäten \& Provenance](#41-prioritäten--provenance)
- [4.2 Typ-Defaults](#42-typ-defaults)
- [5. Retriever, Chat \& Generation (RAG Pipeline)](#5-retriever-chat--generation-rag-pipeline)
- [5.1 Retrieval (Hybrid)](#51-retrieval-hybrid)
- [5.2 Context Enrichment (Das "Context Intelligence" Pattern)](#52-context-enrichment-das-context-intelligence-pattern)
- [5.3 Generation (LLM)](#53-generation-llm)
- [5.4 Explanation Mode (WP04b)](#54-explanation-mode-wp04b)
- [6. Feedback \& Lernen (WP04c)](#6-feedback--lernen-wp04c)
- [7. Quality Gates \& Tests](#7-quality-gates--tests)
- [7.1 Pflicht-Tests vor Commit](#71-pflicht-tests-vor-commit)
- [7.2 Smoke-Test (E2E)](#72-smoke-test-e2e)
- [8. Ausblick \& Roadmap (Technische Skizzen)](#8-ausblick--roadmap-technische-skizzen)
- [8.1 WP-06: Decision Engine (Skizze)](#81-wp-06-decision-engine-skizze)
- [8.2 WP-08: Self-Tuning (Skizze)](#82-wp-08-self-tuning-skizze)
</details>
---
## 1. Zweck & Einordnung