diff --git a/docs/developer_guide.md b/docs/developer_guide.md new file mode 100644 index 0000000..83bc2a0 --- /dev/null +++ b/docs/developer_guide.md @@ -0,0 +1,155 @@ +# 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 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 \ No newline at end of file