# 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