Lars
013e8c6d0c
All checks were successful
Deploy mindnet to llm-node / deploy (push) Successful in 3s
155 lines
6.0 KiB
Markdown
155 lines
6.0 KiB
Markdown
# 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 |