Lars/mindnet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 21 Wiki Activity
V2.6.0
mindnet/docs/pipeline_playbook.md
Lars 302e2a3d24 Doku Update
2025-12-13 06:37:24 +01:00

14 KiB
Raw Permalink Blame History

mindnet v2.4 – Pipeline Playbook

Datei: docs/mindnet_pipeline_playbook_v2.6.md Stand: 2025-12-12 Status: FINAL (Inkl. Smart Edges & Traffic Control) Quellen: mindnet_v2_implementation_playbook.md, Handbuch.md, chunking_strategy.md, docs_mindnet_retriever.md, mindnet_admin_guide_v2.4.md.

📖 Inhaltsverzeichnis (Klicken zum Öffnen)
---

1. Zweck & Einordnung

Dieses Playbook ist das zentrale operative Handbuch für die mindnet-Pipeline. Es beschreibt, wie Daten vom Markdown-Vault in den Wissensgraphen (Qdrant) gelangen, wie der Retriever betrieben wird und wie die RAG-Generierung (inkl. Decision Engine & Interviewer) funktioniert.

Zielgruppe: Dev/Ops, Tech-Leads. Scope:

  • Ist-Stand (WP01–WP15): Async Import, Smart Chunking, Edge-Erzeugung, Hybrider Retriever, RAG-Chat (Hybrid Router), Feedback Loop, Frontend, Draft Editor, Active Intelligence.
  • Roadmap (Ausblick): Technische Skizze für Self-Tuning (WP08).

2. Die Import-Pipeline (Runbook)

Der Import ist der kritischste Prozess ("Data Ingestion"). Er muss deterministisch und idempotent sein. Wir nutzen scripts/import_markdown.py als zentralen Entrypoint.

2.1 Der 13-Schritte-Prozess (Async + Smart)

Seit v2.6 läuft der Import vollständig asynchron, nutzt intelligente Kantenvalidierung (Smart Edges) und drosselt sich selbst ("Traffic Control").

  1. Markdown lesen: Rekursives Scannen des Vaults.
  2. Frontmatter extrahieren: Validierung von Pflichtfeldern (id, type, title).
  3. Typauflösung: Bestimmung des type via types.yaml (Prio: Frontmatter > Pfad > Default).
  4. Note-Payload generieren: Erstellen des JSON-Objekts für mindnet_notes.
  5. Chunking anwenden: Zerlegung des Textes basierend auf dem chunk_profile des Typs (z.B. sliding_smart_edges).
  6. Smart Edge Allocation (Neu in WP15):
    • Wenn in types.yaml aktiviert (enable_smart_edge_allocation):
    • Der SemanticAnalyzer sendet jeden Chunk an das LLM.
    • Resilienz & Traffic Control:
      • Priority: Der Request nutzt priority="background".
      • Semaphore: Eine globale Semaphore (Limit: 2, konfigurierbar) verhindert System-Überlastung.
      • Retry & Backoff: Bei Fehlern (Timeouts) wird bis zu 5-mal mit exponentieller Wartezeit wiederholt.
      • JSON Repair: Der Analyzer erkennt fehlerhaftes JSON (z.B. Dict statt Liste) und repariert es automatisch.
      • Safety Fallback: Schlagen alle Versuche fehl, werden die Kanten allen Chunks zugewiesen, um Datenverlust zu vermeiden.
    • Ergebnis: Das LLM filtert irrelevante Links aus dem Chunk ("Broadcasting" verhindern).
  7. Inline-Kanten finden: Parsing von [[rel:...]] im Fließtext.
  8. Callout-Kanten finden: Parsing von > [!edge] Blöcken.
  9. Default-Edges erzeugen: Anwendung der edge_defaults aus der Typ-Registry.
  10. Strukturkanten erzeugen: belongs_to, next, prev (Sequenz).
  11. Embedding & Upsert (Async):
    • Generierung der Vektoren via nomic-embed-text (768 Dim).
  12. Strict Mode: Der Prozess bricht sofort ab, wenn ein Embedding leer ist oder die Dimension 0 hat.
  13. Diagnose: Automatischer Check der Integrität nach dem Lauf.

2.2 Standard-Betrieb (Inkrementell)

Für regelmäßige Updates (z.B. Cronjob). Erkennt Änderungen via Hash.

export QDRANT_URL="http://localhost:6333"
export COLLECTION_PREFIX="mindnet"

# Import starten (Apply = Schreiben, Purge = Sauberer Upsert)
# Nutzt das Venv der Produktionsumgebung
/home/llmadmin/mindnet/.venv/bin/python3 -m scripts.import_markdown \
    --vault ./vault \
    --prefix "$COLLECTION_PREFIX" \
    --apply \
    --purge-before-upsert \
    --sync-deletes
  • --apply: Ohne dieses Flag läuft ein Dry-Run (nur Simulation).
  • --purge-before-upsert: Löscht vor dem Schreiben einer Note ihre alten Chunks/Edges. Essentiell, um "Geister-Chunks" zu vermeiden, wenn Text gekürzt wurde.
  • --sync-deletes: Entfernt Notizen aus Qdrant, die im Vault gelöscht wurden.

2.3 Deployment & Restart (Systemd)

Nach einem Import oder Code-Update müssen die API-Prozesse neu gestartet werden.

# Neustart des Produktions-Services (API + UI)
sudo systemctl restart mindnet-prod
sudo systemctl restart mindnet-ui-prod

# Prüfung
sudo systemctl status mindnet-prod

2.4 Full Rebuild (Clean Slate)

Notwendig bei Änderungen an types.yaml (z.B. Smart Edges an/aus) oder beim Wechsel des Embedding-Modells.

WICHTIG: Vorher das Modell pullen, sonst schlägt der Import fehl!

# 0. Modell sicherstellen (WICHTIG für v2.4+)
ollama pull nomic-embed-text

# 1. Qdrant Collections löschen und neu anlegen (Wipe inkl. Schema 768d)
python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet" --yes

# 2. Vollständiger Import aller Dateien
python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force

3. Chunking & Payload-Aufbau

Das Chunking ist profilbasiert und typgesteuert.

3.1 Chunk-Profile

In types.yaml definiert. Standard-Profile (in chunk_config.py implementiert):

  • sliding_short: Max 128 Tokens (z.B. für Logs, Chats).
  • sliding_standard: Max 512 Tokens (Standard für Massendaten).
  • sliding_smart_edges: Sliding Window, optimiert für LLM-Analyse (Fließtext).
  • structured_smart_edges: Trennt strikt an Überschriften (für strukturierte Daten).

3.2 Payload-Felder

Jeder Chunk erhält zwei Text-Felder:

  • text: Der reine Inhalt des Chunks (ohne Overlap). Wird dem Nutzer angezeigt.
  • window: Der Inhalt plus Overlap zu Vorgänger/Nachfolger. Wird für das Embedding genutzt (besserer Kontext).

4. Edge-Erzeugung (Die V2-Logik)

In v2.6 entstehen Kanten nach strenger Priorität.

4.1 Prioritäten & Provenance

Der Importer setzt provenance, rule_id und confidence automatisch:

Priorität Quelle Syntax (Bsp.) Rule ID Confidence
1 Inline [[rel:depends_on X]] inline:rel ~0.95
2 Callout > [!edge] related_to: [[X]] callout:edge ~0.90
3 Wikilink [[X]] explicit:wikilink 1.00
4 Smart (via LLM Filter) smart:llm_filter 0.90
5 Default (via types.yaml) edge_defaults:... ~0.70
6 Struktur (automatisch) structure:... 1.00

4.2 Smart Edge Allocation (WP15)

Dieser Mechanismus löst das Problem, dass Chunks sonst alle Links der Note erben.

  • Prozess: Der SemanticAnalyzer prüft jeden Chunk: "Ist Link X im Kontext von Chunk Y relevant?"
  • Ergebnis: Kanten werden präzise an den Chunk gebunden, nicht global an die Note.
  • Steuerung: Das Feature wird in types.yaml per Typ aktiviert (enable_smart_edge_allocation: true).

4.3 Typ-Defaults

Wenn in types.yaml für einen Typ edge_defaults definiert sind, werden diese additiv zu expliziten Links erzeugt.

  • Beispiel: Note Typ project verlinkt [[Tool A]].
  • Ergebnis: Kante references (explizit) UND Kante depends_on (Default).

5. Retriever, Chat & Generation (RAG Pipeline)

Der Datenfluss endet nicht beim Finden. Er geht weiter bis zur Antwort.

5.1 Retrieval (Hybrid)

Der /chat Endpunkt nutzt Hybrid Retrieval (Semantic + Graph), um auch logisch verbundene, aber textlich unterschiedliche Notizen zu finden (z.B. Decisions zu einem Projekt).

5.2 Intent Router (WP06/07)

Der Request durchläuft den Hybrid Router v5:

  1. Question Detection: Ist es eine Frage (?, W-Wörter)? -> RAG Modus. Interviews werden hier blockiert.
  2. Keyword Scan: Enthält es Keywords aus types.yaml (Objekt, z.B. "Projekt") oder decision_engine.yaml (Action, z.B. "erstellen")? -> INTERVIEW Modus.
  3. LLM Fallback: Wenn unklar, entscheidet das LLM.

5.3 Context Enrichment

Der Router (chat.py) reichert die gefundenen Chunks mit Metadaten an:

  • Typ-Injection: [DECISION], [PROJECT].
  • Reasoning-Infos: (Score: 0.75).

5.4 Generation (LLM) mit Traffic Control

  • Engine: Ollama (lokal).
  • Modell: phi3:mini (Standard).
  • Prompting: Template wird basierend auf Intent gewählt (decision_template, interview_template etc.).
  • Traffic Control: Der LLMService unterscheidet:
    • Chat-Requests (priority="realtime") -> Sofortige Ausführung.
    • Import-Requests (priority="background") -> Gedrosselt durch Semaphore (Standard: 2).

5.5 Active Intelligence Pipeline (Neu in v2.4)

Ein paralleler Datenfluss im Frontend ("Draft Editor") zur Unterstützung des Autors.

  1. Trigger: User klickt "Analyse starten" oder tippt.
  2. Service: ingest/analyze (Backend).
  3. Discovery:
    • Sliding Window: Zerlegt Text in Abschnitte.
    • Embedding: Vektorisiert Abschnitte via Nomic (Async).
    • Exact Match: Sucht nach Aliases ("KI-Gedächtnis").
    • Matrix Logic: Bestimmt Kanten-Typ (experience -> based_on -> value).
  4. Feedback: UI zeigt Vorschläge ([[rel:...]]) zum Einfügen an.

6. Feedback & Lernen (WP04c)

Das System schreibt kontinuierlich Logs ("Data Flywheel"):

  • data/logs/search_history.jsonl: Trainingsdaten (Query + Ergebnisse + Breakdown).
  • data/logs/feedback.jsonl: Labels (User-Rating zur query_id).

7. Quality Gates & Tests

Diese Tests garantieren die Stabilität der Pipeline.

7.1 Pflicht-Tests vor Commit

  1. Payload Dryrun (Schema-Check): Simuliert Import, prüft JSON-Schema Konformität.

    python3 -m scripts.payload_dryrun --vault ./test_vault

  2. Full Edge Check (Graph-Integrität): Prüft Invarianten (z.B. next muss reziprok zu prev sein).

    python3 -m scripts.edges_full_check

7.2 Smoke-Test (E2E)

Prüft am laufenden System (Prod oder Dev), ob Semantik, Graph und Feedback funktionieren.

# Retriever Test
python scripts/test_retriever_smoke.py --mode hybrid --top-k 5

# Intelligence Test (WP11)
curl -X POST "http://localhost:8002/ingest/analyze" -d '{"text": "mindnet", "type": "journal"}'

# Decision Engine Test (WP06)
python tests/test_wp06_decision.py -p 8002 -e EMPATHY -q "Alles ist grau"

# Feedback Test
python tests/test_feedback_smoke.py --url http://localhost:8001/query

8. Ausblick & Roadmap (Technische Skizzen)

Wie entwickeln wir die Pipeline weiter?

8.1 WP-08: Self-Tuning (Skizze)

Ziel: Die Gewichte in retriever.yaml basierend auf feedback.jsonl optimieren. Ansatz: Ein Offline-Learning-Skript scripts/optimize_weights.py.

  1. Load: Liest search_history.jsonl und joint mit feedback.jsonl via query_id.
  2. Analyze: Korrelation Scores vs. User-Rating.
  3. Optimize: Vorschlag neuer Gewichte für retriever.yaml.

16. Workpackage Status (v2.6.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 🟢 Live Hybrid Router, Strategic Retrieval.
WP07 Interview Assistent 🟢 Live One-Shot Extractor & Schemas aktiv.
WP08 Self-Tuning 🔴 Geplant Auto-Adjustment der Gewichte.
WP10 Chat Interface 🟢 Live Web-Interface (Streamlit).
WP10a Draft Editor 🟢 Live Interaktives UI für WP07 Drafts.
WP11 Backend Intelligence 🟢 Live Async Ingestion, Nomic Embeddings, Matrix Logic.
WP15 Smart Edge Allocation 🟢 Live LLM-Filter & Traffic Control aktiv.
WP16 Auto-Discovery 🟡 Geplant UX & Retrieval Tuning.
WP17 Conversational Memory 🟡 Geplant Dialog-Gedächtnis.