Lars/mindnet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 21 Wiki Activity
62aa24a4bc
mindnet/docs/pipeline_playbook.md
Lars f2de556c16 dokumentation
2025-12-10 18:55:38 +01:00

11 KiB
Raw Blame History

mindnet v2.4 – Pipeline Playbook

Datei: docs/mindnet_pipeline_playbook_v2.4.md Stand: 2025-12-10 Status: FINAL (Inkl. WP07 Interview & WP10a Editor) 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–WP10a): Import, Chunking, Edge-Erzeugung, Hybrider Retriever, RAG-Chat (Hybrid Router), Feedback Loop, Frontend, Draft Editor.
  • 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 12-Schritte-Prozess

Gemäß WP03-Spezifikation läuft der Import intern wie folgt ab:

  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.
  6. Inline-Kanten finden: Parsing von [[rel:...]] im Fließtext.
  7. Callout-Kanten finden: Parsing von > [!edge] Blöcken.
  8. Default-Edges erzeugen: Anwendung der edge_defaults aus der Typ-Registry.
  9. Strukturkanten erzeugen: belongs_to (Chunk->Note), next/prev (Sequenz).
  10. Chunks upserten: Schreiben in Qdrant (mindnet_chunks).
  11. Edges upserten: Schreiben in Qdrant (mindnet_edges).
  12. 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. neue Chunk-Größen) oder Embedding-Modellen.

# 1. Qdrant Collections löschen und neu anlegen (Wipe inkl. Schema)
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

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

  • short: Max 128 Tokens (z.B. für Logs, Chats).
  • medium: Max 256 Tokens (z.B. für Konzepte).
  • long: Max 512 Tokens (z.B. für Essays, Projekte).
  • by_heading: Trennt strikt an Überschriften.

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.2 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 Default (via types.yaml) edge_defaults:... ~0.70
5 Struktur (automatisch) structure:... 1.00

4.2 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:

  1. Fast Path: Prüfung auf trigger_keywords aus decision_engine.yaml.
  2. Slow Path: Falls kein Keyword matched und llm_fallback_enabled=true, klassifiziert das LLM den Intent.
    • FACT: Wissen abfragen.
    • DECISION: Rat suchen.
    • EMPATHY: Trost suchen.
    • INTERVIEW: Wissen eingeben (Neu in WP07).
  3. Result: Auswahl der Strategie und der inject_types oder schemas.

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)

  • Engine: Ollama (lokal).
  • Modell: phi3:mini (Standard).
  • Prompting: Template wird basierend auf Intent gewählt (decision_template, interview_template etc.).
  • One-Shot (WP07): Im Interview-Modus generiert das LLM direkt einen Markdown-Block ohne Rückfragen.

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

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

# Interview Test (WP07)
python tests/test_wp06_decision.py -p 8002 -e INTERVIEW -q "Neues Projekt starten"

# 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.4.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.