# Mindnet v2.2 – Developer Guide **Datei:** `docs/mindnet_developer_guide_v2.2.md` **Stand:** 2025-12-09 **Status:** **FINAL** (Inkl. RAG, Decision Engine & AI-Teaching) **Quellen:** `mindnet_technical_architecture.md`, `Handbuch.md`, `DEV_WORKFLOW.md`. > **Zielgruppe:** Entwickler:innen. > **Zweck:** Anleitung zum Aufsetzen der Entwicklungsumgebung, Verständnis der Modulstruktur und Durchführung von Tests. --- - [Mindnet v2.2 – Developer Guide](#mindnet-v22--developer-guide) - [1. Projektstruktur (Post-WP06)](#1-projektstruktur-post-wp06) - [2. Lokales Setup (Development)](#2-lokales-setup-development) - [2.1 Voraussetzungen](#21-voraussetzungen) - [2.2 Installation](#22-installation) - [2.3 Konfiguration (Environment)](#23-konfiguration-environment) - [2.4 Dienste starten (Systemd bevorzugt)](#24-dienste-starten-systemd-bevorzugt) - [3. Core-Module \& Entwicklung](#3-core-module--entwicklung) - [3.1 Der Importer (`scripts.import_markdown`)](#31-der-importer-scriptsimport_markdown) - [3.2 Der Hybrid Router (`app.routers.chat`)](#32-der-hybrid-router-approuterschat) - [3.3 Der Retriever (`app.core.retriever`)](#33-der-retriever-appcoreretriever) - [4. Tests \& Debugging](#4-tests--debugging) - [4.1 Unit Tests (Pytest)](#41-unit-tests-pytest) - [4.2 Integration / Pipeline Tests](#42-integration--pipeline-tests) - [4.3 Smoke Tests (E2E)](#43-smoke-tests-e2e) - [5. Das "Teach-the-AI" Paradigma (Context Intelligence)](#5-das-teach-the-ai-paradigma-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 (Edges) nutzen (z. B. `beeinflusst_von`)](#b-workflow-neue-beziehungen-edges-nutzen-z-b-beeinflusst_von) - [Fazit](#fazit) - [6. Nützliche Einzeiler](#6-nützliche-einzeiler) --- ## 1. Projektstruktur (Post-WP06) Der Code ist modular in `app` (Logik), `scripts` (CLI) und `config` (Steuerung) getrennt. mindnet/ ├── app/ │ ├── core/ # Kernlogik │ │ ├── chunker.py # Text-Zerlegung │ │ ├── derive_edges.py # Edge-Erzeugung (WP03 Logik) │ │ ├── retriever.py # Scoring & Hybrid Search │ │ ├── qdrant.py # DB-Verbindung │ │ └── ... │ ├── models/ # Pydantic DTOs │ │ └── dto.py # Zentrale DTO-Definition │ ├── routers/ # FastAPI Endpoints │ │ ├── query.py # Suche │ │ ├── chat.py # Hybrid Router & Decision Engine (WP06) │ │ ├── feedback.py # Feedback (WP04c) │ │ └── ... │ ├── services/ # Interne & Externe Dienste │ │ ├── llm_service.py # Ollama Client (Mit Timeout & Raw-Mode) │ │ ├── feedback_service.py # Logging (JSONL Writer) │ │ └── embeddings_client.py │ └── main.py # Entrypoint der API ├── config/ # YAML-Konfigurationen (Single Source of Truth) │ ├── types.yaml # Import-Regeln │ ├── prompts.yaml # LLM Prompts & RAG Templates (WP06) │ ├── decision_engine.yaml # Router-Strategien (WP06) │ └── retriever.yaml # Scoring-Regeln & Kantengewichte ├── data/ │ └── logs/ # Lokale Logs (search_history.jsonl, feedback.jsonl) ├── scripts/ # CLI-Tools (Import, Diagnose, Reset) ├── tests/ # Pytest Suite & Smoke Scripts └── vault/ # Dein lokaler Markdown-Content (Git-ignored) --- ## 2. Lokales Setup (Development) ### 2.1 Voraussetzungen * **Python:** 3.10 oder höher. * **Docker:** Für Qdrant. * **Ollama:** Für lokale LLM-Inference (erforderlich für `/chat`). * **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 mindnet cd mindnet # 2. Virtual Environment erstellen python3 -m venv .venv source .venv/bin/activate # 3. Abhängigkeiten installieren pip install -r requirements.txt # 4. Ollama Setup (Modell laden) # Wir nutzen Phi-3 Mini für schnelle CPU-Inference ollama pull phi3:mini ### 2.3 Konfiguration (Environment) Erstelle eine `.env` Datei im Root-Verzeichnis. Die Timeout-Settings sind kritisch für CPU-Inference. # Qdrant Verbindung QDRANT_URL="http://localhost:6333" QDRANT_API_KEY="" # Leer lassen für lokal # Mindnet Core Settings COLLECTION_PREFIX="mindnet_dev" MINDNET_TYPES_FILE="./config/types.yaml" MINDNET_RETRIEVER_CONFIG="./config/retriever.yaml" # LLM / RAG Settings (WP06) MINDNET_LLM_MODEL="phi3:mini" MINDNET_OLLAMA_URL="http://127.0.0.1:11434" MINDNET_LLM_TIMEOUT=300.0 MINDNET_PROMPTS_PATH="./config/prompts.yaml" MINDNET_DECISION_CONFIG="./config/decision_engine.yaml" # Import-Strategie MINDNET_HASH_COMPARE="Body" MINDNET_HASH_SOURCE="parsed" ### 2.4 Dienste starten (Systemd bevorzugt) Auf dem Entwicklungsserver (Beelink) nutzen wir Systemd. # Starten / Neustarten sudo systemctl restart mindnet-dev # Logs prüfen (Wichtig für LLM Debugging) journalctl -u mindnet-dev -f Falls du lokal auf Windows entwickelst: # 1. Qdrant starten docker run -p 6333:6333 qdrant/qdrant # 2. Ollama starten ollama serve # 3. API starten uvicorn app.main:app --host 0.0.0.0 --port 8002 --env-file .env --reload --- ## 3. Core-Module & Entwicklung ### 3.1 Der Importer (`scripts.import_markdown`) Dies ist das komplexeste Modul. * **Einstieg:** `scripts/import_markdown.py` -> `main()`. * **Idempotenz:** Der Importer muss mehrfach laufen können, ohne Duplikate zu erzeugen. Wir nutzen deterministische IDs (UUIDv5). * **Debugging:** Nutze `--dry-run` oder `scripts/payload_dryrun.py`. ### 3.2 Der Hybrid Router (`app.routers.chat`) Hier liegt die Logik für Intent Detection (WP06). * **Logic:** `_classify_intent` prüft zuerst Keywords (Fast Path) und fällt auf `llm_service.generate_raw_response` zurück (Slow Path), wenn konfiguriert. * **Config:** Gesteuert durch `decision_engine.yaml`. * **Erweiterung:** Um neue Intents hinzuzufügen, editiere nur die YAML, nicht den Python-Code (Late Binding). ### 3.3 Der Retriever (`app.core.retriever`) Hier passiert das Scoring. * **Hybrid Search:** Der Chat-Endpoint erzwingt `mode="hybrid"`. * **Strategic Retrieval:** In `chat.py` wird der Retriever *zweimal* aufgerufen, wenn ein Intent (z.B. `DECISION`) eine Injection (`value`) erfordert. --- ## 4. Tests & Debugging 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 ### 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) Prüfen das laufende System (API) gegen eine echte Qdrant-Instanz und Ollama. # 1. Retriever Test (Hybrid + Explanation) python scripts/test_retriever_smoke.py --query "Test" --mode hybrid --top-k 5 --explain # 2. Decision Engine Test (WP06) # Prüft Intent, Retrieval und Reasoning (mit Timeout-Handling) python tests/test_wp06_decision.py -p 8002 -e DECISION -q "Soll ich X tun?" # 3. Empathy Test (WP06) # Prüft LLM-Router Fallback python tests/test_wp06_decision.py -p 8002 -e EMPATHY -q "Alles ist grau" # 4. Feedback Test (WP04c) python tests/test_feedback_smoke.py --url http://localhost:8002/query --- ## 5. Das "Teach-the-AI" Paradigma (Context Intelligence) 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. ### A. Workflow: Einen neuen Typ implementieren (z. B. `type: risk`) **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 **2. Strategie-Ebene (`config/decision_engine.yaml`)** Damit dieser Typ aktiv geladen wird, musst du ihn einer Strategie zuordnen. DECISION: inject_types: ["value", "principle", "goal", "risk"] # <--- "risk" hinzugefügt *Ergebnis:* Wenn der Intent `DECISION` erkannt wird, sucht das System nun auch aktiv nach Risiken. **3. Kognitive Ebene (`config/prompts.yaml`)** Erkläre dem LLM im Template, was es damit tun soll. decision_template: | ... - Prüfe auf [RISK]: Wenn vorhanden, warne mich davor! ### 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]]. **2. Gewichtung (`config/retriever.yaml`)** Standardmäßig werden alle expliziten Kanten gleich behandelt. Wenn Kausalität wichtiger ist als Ähnlichkeit, konfiguriere dies hier. scoring: edge_type_weights: beeinflusst_von: 1.5 # Sehr starker Einfluss auf das Ranking ### Fazit * **Vault:** Liefert das Wissen. * **Config:** Liefert die Strategie (Router & 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) - inkl. LLM Thoughts:** journalctl -u mindnet-dev -f