Lars/mindnet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 21 Wiki Activity
0d1a98279e
mindnet/docs/developer_guide.md
Lars 0d1a98279e
All checks were successful
Deploy mindnet to llm-node / deploy (push) Successful in 3s
Details
docs/developer_guide.md aktualisiert
2025-12-08 17:33:46 +01:00

8.5 KiB
Raw Blame History

Mindnet v2.2 – Developer Guide

Datei: docs/mindnet_developer_guide_v2.2.md Stand: 2025-12-08 Status: FINAL (Inkl. RAG & AI-Teaching Paradigm) 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.

1. Projektstruktur (Aktualisiert)

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     # RAG-Chat (WP05)
│   │   ├── feedback.py # Feedback (WP04c)
│   │   └── ...
│   ├── services/       # Interne & Externe Dienste
│   │   ├── llm_service.py      # Ollama Client (WP05)
│   │   ├── 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 (WP05)
│   └── retriever.yaml  # Scoring-Regeln
├── 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 <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

# 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.

# 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 (WP05)
MINDNET_LLM_MODEL="phi3:mini"
MINDNET_OLLAMA_URL="http://127.0.0.1:11434"
MINDNET_PROMPTS_PATH="./config/prompts.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
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 Edge-Logik (app.core.derive_edges)

Hier wird entschieden, welche Kanten entstehen.

  • Rule-ID: Vergib zwingend eine eindeutige rule_id (z.B. custom:my_rule), damit die Herkunft für die Explanation nachvollziehbar bleibt.

3.3 Der Retriever & Chat (app.core.retriever / app.routers.chat)

Hier passiert das Scoring und die Generation.

  • Hybrid Search: Der Chat-Endpoint erzwingt mode="hybrid".
  • Context Enrichment: In _build_enriched_context (chat.py) werden Metadaten (Typ, Score) in den Prompt injiziert. Achte darauf, dass neue Typen hier ggf. berücksichtigt werden, falls sie spezielle Behandlung brauchen (aktuell generisch gelöst).

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. Chat / RAG Test (WP05)
# Prüft die gesamte Kette: Suche -> Kontext -> LLM -> Antwort
python tests/test_chat_wp05.py

# 3. 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 und Kontext. Wenn du dem System ein neues Konzept (z.B. "Risiko" oder "Strategie") beibringen willst, musst du an drei Stellen eingreifen. Dies ist der Core-Workflow für Erweiterungen.

Das Dreieck der Bedeutung

  1. Daten-Ebene (types.yaml): Definiert die Existenz und Wichtigkeit.
  2. Code-Ebene (chat.py): Macht den Typ für das LLM sichtbar (Labeling).
  3. Kognitive Ebene (prompts.yaml): Erklärt dem LLM, wie es den Typ interpretieren soll.

Workflow: Einen neuen Typ implementieren (Bsp: risk)

Schritt 1: Physik definieren (config/types.yaml) Definiere, wie der Typ importiert und gesucht wird.

risk:
  chunk_profile: short       # Risiken sind oft kurze Statements
  retriever_weight: 0.90     # Sehr wichtig, fast so hoch wie Decisions
  edge_defaults: ["blocks"]  # Ein Risiko blockiert oft das verlinkte Projekt

Ergebnis: Notizen werden importiert und landen bei Suchen weit oben.

Schritt 2: Labeling prüfen (app/routers/chat.py) Der Router (Funktion _build_enriched_context) liest das Feld type automatisch aus und injiziert es als TYP: [RISK] in den Prompt.

  • Prüfung: Keine Code-Änderung nötig, da der Router generisch programmiert ist.
  • Ausnahme: Wenn du spezielle Logik brauchst (z.B. "Risiken immer rot markieren"), müsstest du hier den Code anpassen.

Schritt 3: Verstehen lehren (config/prompts.yaml) Das LLM sieht nun [RISK]. Aber was soll es damit tun? Das definierst du hier. Ergänze den system_prompt oder das rag_template:

system_prompt: |
  ...
  REGELN FÜR TYPEN:
  - [DECISION]: Begründung für Handlungen.
  - [RISK]: Warnung! Wenn ein [RISK] im Kontext ist, weise den User darauf hin, bevor du eine Lösung empfiehlst.

Ergebnis: Das System entwickelt ein "Risikobewusstsein".

Fazit

Nur wenn alle drei Ebenen synchron sind, entsteht intelligente Persönlichkeit.

  • Ohne Schritt 1 findet das System die Notiz nicht.
  • Ohne Schritt 2 sieht das LLM nur Text, keinen Typ.
  • Ohne Schritt 3 ignoriert das LLM den Typ, weil es ihn nicht versteht.

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):

journalctl -u mindnet-dev -f