Lars/mindnet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 21 Wiki Activity
dbefd30dce
mindnet/docs/05_Development/05_developer_guide.md
Lars b26d9fd10e
All checks were successful
Deploy mindnet to llm-node / deploy (push) Successful in 4s
Details
docs/05_Development/05_developer_guide.md aktualisiert
2025-12-14 21:02:30 +01:00

8.1 KiB
Raw Blame History

doc_type audience scope status version context
developer_guide developer workflow, testing, architecture, modules active 2.6 Umfassender Guide für Entwickler: Architektur, Modul-Interna, Setup, Git-Workflow und Erweiterungs-Anleitungen.

Mindnet Developer Guide & Workflow

Quellen: developer_guide.md, dev_workflow.md

Dieser Guide vereint das technische Verständnis der Module mit dem operativen Workflow zwischen Windows (Dev) und Linux (Runtime).

1. Die physische Architektur

Mindnet läuft in einer verteilten Umgebung (Post-WP15 Setup).

  • Windows 11 (VS Code): Hier schreibst du Code. Nie direkt auf main arbeiten!
  • Raspberry Pi (Gitea): Der "Safe". Speichert den Code und verwaltet Versionen.
  • Beelink (Runtime): Der Server. Hier läuft die Software. Wir nutzen Systemd-Services:
    • PROD: API (8001) + UI (8501). Ordner: ~/mindnet.
    • DEV: API (8002) + UI (8502). Ordner: ~/mindnet_dev.

2. Projektstruktur & Core-Module

Der Code ist modular in app (Logik), scripts (CLI) und config (Steuerung) getrennt.

2.1 Verzeichnisbaum

mindnet/
├── app/
│   ├── core/           # Kernlogik
│   │   ├── ingestion.py        # Async Ingestion Service mit Change Detection
│   │   ├── chunker.py          # Smart Chunker Orchestrator
│   │   ├── derive_edges.py     # Edge-Erzeugung (WP03 Logik)
│   │   ├── retriever.py        # Scoring & Hybrid Search
│   │   └── qdrant.py           # DB-Verbindung
│   ├── routers/        # FastAPI Endpoints
│   │   ├── query.py    # Suche
│   │   ├── chat.py     # Hybrid Router v5 & Interview Logic
│   │   └── feedback.py # Feedback (WP04c)
│   ├── services/       # Interne & Externe Dienste
│   │   ├── llm_service.py      # Ollama Client mit Traffic Control
│   │   ├── semantic_analyzer.py# LLM-Filter für Edges (WP15)
│   │   ├── embeddings_client.py# Async Embeddings (HTTPX)
│   │   └── discovery.py        # Intelligence Logic (WP11)
│   ├── frontend/       # UI Logic (WP19 Modularisierung)
│   │   ├── ui.py               # Main Entrypoint & Routing
│   │   ├── ui_config.py        # Styles & Constants
│   │   ├── ui_api.py           # Backend Connector
│   │   ├── ui_callbacks.py     # State Transitions
│   │   ├── ui_utils.py         # Helper & Parsing
│   │   ├── ui_graph_service.py # Graph Data Logic
│   │   ├── ui_graph_cytoscape.py # Modern Graph View (St-Cytoscape)
│   │   └── ui_editor.py        # Editor View
│   └── main.py         # Entrypoint der API
├── config/             # YAML-Konfigurationen (Single Source of Truth)
├── scripts/            # CLI-Tools (Import, Diagnose, Reset)
├── tests/              # Pytest Suite & Smoke Scripts
└── vault/              # Dein lokaler Markdown-Content

2.2 Modul-Details (Wie es funktioniert)

Das Frontend (app.frontend) - Neu in v2.6

  • Router (ui.py): Entscheidet, welche View geladen wird.
  • Service-Layer (ui_graph_service.py): Kapselt die Qdrant-Abfragen. Liefert rohe Nodes/Edges, die dann von den Views visualisiert werden.
  • Graph Engine: Wir nutzen st-cytoscape für das Layout. Die Logik zur Vermeidung von Re-Renders (Stable Keys, CSS-Selektion) ist essentiell.
  • Data Consistency: Der Editor (ui_editor.py) liest Dateien bevorzugt direkt vom Dateisystem ("File System First"), um Datenverlust durch veraltete DB-Einträge zu vermeiden.

Der Importer (scripts.import_markdown)

  • Das komplexeste Modul.
  • Nutzt app.core.chunker und app.services.semantic_analyzer (Smart Edges).
  • Idempotenz: Nutzt deterministische UUIDv5 IDs. Kann beliebig oft laufen.
  • Robustheit: Implementiert Change Detection (Hash) und Retry-Logik.

Der Hybrid Router (app.routers.chat)

  • Hier liegt die Logik für Intent Detection (WP06).
  • Question Detection: Prüft auf ? und W-Wörter.
  • Priority: Ruft llm_service mit priority="realtime" auf (umgeht Import-Warteschlange).

Der Retriever (app.core.retriever)

  • Implementiert die Scoring-Formel (Semantik + Graph + Typ).
  • Hybrid Search: Lädt dynamisch den Subgraphen (graph_adapter.expand).

Traffic Control (app.services.llm_service)

  • Stellt sicher, dass der Chat responsive bleibt, auch wenn ein Import läuft.
  • Nutzt asyncio.Semaphore (MINDNET_LLM_BACKGROUND_LIMIT), um Hintergrund-Jobs zu drosseln.

3. Lokales Setup (Development)

Voraussetzungen: Python 3.10+, Docker, Ollama.

Installation:

# 1. Repo & Venv
git clone <repo> mindnet
cd mindnet
python3 -m venv .venv
source .venv/bin/activate

# 2. Dependencies (inkl. st-cytoscape)
pip install -r requirements.txt

# 3. Ollama (Nomic ist Pflicht!)
ollama pull phi3:mini
ollama pull nomic-embed-text

Konfiguration (.env):

QDRANT_URL="http://localhost:6333"
COLLECTION_PREFIX="mindnet_dev"
VECTOR_DIM=768
MINDNET_LLM_BACKGROUND_LIMIT=2
MINDNET_API_URL="http://localhost:8002"
MINDNET_LLM_TIMEOUT=300.0

4. Der Entwicklungs-Zyklus

Phase 1: Windows (Code)

  1. Basis holen: git checkout main && git pull.
  2. Branch: git checkout -b feature/mein-feature.
  3. Code & Push: git push origin feature/mein-feature.

Phase 2: Beelink (Test)

  1. SSH: ssh user@beelink.
  2. Ordner: cd ~/mindnet_dev.
  3. Checkout: git fetch && git checkout feature/mein-feature && git pull.
  4. Dependencies: pip install -r requirements.txt.
  5. Restart: sudo systemctl restart mindnet-dev.
  6. Validierung (Smoke Tests):
    • Last-Test: Starte python3 -m scripts.import_markdown ... und chatte gleichzeitig im UI (Port 8502).
    • API Check: curl -X POST "http://localhost:8002/ingest/analyze" ...

Phase 3: Release & Deploy

  1. Gitea: Pull Request erstellen und mergen.
  2. Beelink (Prod): 
    cd ~/mindnet
git pull origin main
pip install -r requirements.txt
sudo systemctl restart mindnet-prod
sudo systemctl restart mindnet-ui-prod
  3. Cleanup: Branch löschen.

5. Erweiterungs-Guide: "Teach-the-AI"

Mindnet lernt durch Konfiguration, nicht durch Training.

Workflow A: Neuen Typ implementieren (z. B. type: risk)

  1. Physik (types.yaml): 
    risk:
  retriever_weight: 0.90
  edge_defaults: ["blocks"]
  detection_keywords: ["gefahr", "risiko"]
  2. Strategie (decision_engine.yaml): 
    DECISION:
  inject_types: ["value", "risk"] # Füge 'risk' hinzu
  3. Visualisierung (ui_config.py): Füge dem GRAPH_COLORS Dictionary einen Eintrag hinzu: 
    "risk": "#ff6b6b"

Workflow B: Interview-Schema anpassen (WP07)

Wenn Mindnet neue Fragen stellen soll (z.B. "Budget" bei Projekten):

  1. Schema (types.yaml): 
    project:
  schema:
    - "Titel"
    - "Ziel"
    - "Budget (Neu)"
  2. Kein Code nötig: Der One-Shot Extractor liest dies dynamisch.

6. Tests & Debugging

Unit Tests:

pytest tests/test_retriever_basic.py
pytest tests/test_chunking.py

Pipeline Tests:

# JSON-Schema prüfen
python3 -m scripts.payload_dryrun --vault ./test_vault

# Graph-Integrität prüfen
python3 -m scripts.edges_full_check

E2E Smoke Tests:

# Decision Engine
python tests/test_wp06_decision.py -p 8002 -e DECISION -q "Soll ich X tun?"

# Feedback
python tests/test_feedback_smoke.py --url http://localhost:8002/query

7. Troubleshooting & One-Liners

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:

journalctl -u mindnet-dev -f
journalctl -u mindnet-ui-dev -f

"Read timed out" im Frontend:

  • Ursache: Backend braucht für Smart Edges länger als 60s.
  • Lösung: MINDNET_API_TIMEOUT=300.0 in .env setzen.