mindnet/docs/developer_guide.md

Mindnet v2.2 – Developer Guide

Datei: docs/mindnet_developer_guide_v2.2.md Stand: 2025-12-07 Status: FINAL (Konsolidiert WP02–WP04a) Quellen: mindnet_technical_architecture.md, Handbuch.md, docs_mindnet_retriever.md, mindnet_v2_implementation_playbook.md.

Zielgruppe: Entwickler:innen. Zweck: Anleitung zum Aufsetzen der Entwicklungsumgebung, Verständnis der Modulstruktur und Durchführung von Tests.

---

1. Projektstruktur

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 & Graph-Expansion (WP04 Logik)
│   │   ├── qdrant.py           # DB-Verbindung
│   │   └── ...
│   ├── models/         # Pydantic DTOs (Request/Response)
│   ├── routers/        # FastAPI Endpoints
│   ├── services/       # Externe Dienste (LLM, Embeddings)
│   └── main.py         # Entrypoint der API
├── config/             # YAML-Konfigurationen (Single Source of Truth)
│   ├── types.yaml      # Import-Regeln
│   └── retriever.yaml  # Scoring-Regeln
├── scripts/            # CLI-Tools (Import, Diagnose, Reset)
├── tests/              # Pytest Suite
└── vault/              # Dein lokaler Markdown-Content (Git-ignored)

---

2. Lokales Setup (Development)

2.1 Voraussetzungen

• Python: 3.10 oder höher.
• Docker: Für Qdrant.
• 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

# 2. Virtual Environment erstellen
python3 -m venv .venv
source .venv/bin/activate

# 3. Abhängigkeiten installieren
pip install -r requirements.txt

2.3 Konfiguration (Environment)

Erstelle eine .env Datei im Root-Verzeichnis oder exportiere die Variablen.

# Qdrant Verbindung
QDRANT_URL="http://localhost:6333"
QDRANT_API_KEY="" # Leer lassen für lokal

# Mindnet Settings
COLLECTION_PREFIX="mindnet_dev"
MINDNET_TYPES_FILE="./config/types.yaml"
MINDNET_RETRIEVER_CONFIG="./config/retriever.yaml"

# Hash-Strategie (für Importer-Debugging)
MINDNET_HASH_COMPARE="Body" 
MINDNET_HASH_SOURCE="parsed"

2.4 Dienste starten

Starten von Qdrant via Docker: docker run -d --name mindnet_qdrant_dev -p 6333:6333 -p 6334:6334 qdrant/qdrant

---

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) basierend auf Dateipfaden/Titeln.
• Debugging: Wenn du am Importer arbeitest, nutze --dry-run oder scripts/payload_dryrun.py, um DB-Schreibvorgänge zu vermeiden.

3.2 Edge-Logik (app.core.derive_edges)

Hier wird entschieden, welche Kanten entstehen.

• Erweiterung: Wenn du neue Edge-Regeln (z.B. Regex-Parser) hinzufügst, tue dies hier.
• Rule-ID: Vergib zwingend eine eindeutige rule_id (z.B. custom:my_rule), damit die Herkunft nachvollziehbar bleibt.

3.3 Der Retriever (app.core.retriever)

Hier passiert das Scoring und die Graph-Expansion.

• Gewichtung: Hardcodiere niemals Gewichte (0.5 etc.) im Code. Nutze app.core.config.get_retriever_config(), um retriever.yaml zu lesen.
• Graph-Adapter: Nutze graph_adapter.expand(), um Nachbarn zu laden. Vermeide direkte Qdrant-Point-Queries im Retriever-Code, um die Abstraktion zu wahren.

---

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, ob import_markdown valide JSON-Objekte erzeugt, ohne in die DB zu schreiben. Essentiell bei Schema-Änderungen. python3 -m scripts.payload_dryrun --vault ./mindnet_v2_test_vault

• Edge Checks: Prüft Graph-Invarianten (z.B. next muss reziprok zu prev sein). python3 -m scripts.edges_full_check

4.3 Smoke Tests (E2E)

Prüfen das laufende System (API) gegen eine echte (lokale) Qdrant-Instanz. # 1. API im Hintergrund starten uvicorn app.main:app --port 8000 &

# 2. Smoke Test feuern
python scripts/test_retriever_smoke.py --query "Test" --mode hybrid --top-k 5

---

5. Guidelines für Erweiterungen

5.1 Neuen Note-Typ hinzufügen

• Nicht im Code! Bearbeite config/types.yaml.
• Definiere chunk_profile und retriever_weight.
• Führe einen Re-Import durch, damit die Änderungen wirksam werden.

5.2 Schema-Änderungen

Wenn du Felder in mindnet_notes oder mindnet_chunks hinzufügst:

1. Passe app/core/note_payload.py bzw. chunk_payload.py an.
2. Aktualisiere tests/assert_payload_schema.py.
3. Führe scripts/reset_qdrant.py (Wipe) aus, um die Indizes neu anzulegen.

5.3 Neue API-Endpunkte

• Erstelle einen neuen Router in app/routers/.
• Nutze Pydantic Models aus app/models/dto.py für Request/Response.
• Registriere den Router in app/main.py.

---

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

Warum wird mein File nicht importiert? python3 -m scripts.diagnose_changed --vault ./vault --all