2025-12-14 20:47:49 +01:00

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

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

Phase 2: Beelink (Test)

SSH: ssh user@beelink.
Ordner: cd ~/mindnet_dev.
Checkout: git fetch && git checkout feature/mein-feature && git pull.
Dependencies: pip install -r requirements.txt.
Restart: sudo systemctl restart mindnet-dev.
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

Gitea: Pull Request erstellen und mergen.

Beelink (Prod):

cd ~/mindnet
git pull origin main
sudo systemctl restart mindnet-prod

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

Physik (types.yaml):

risk:
  retriever_weight: 0.90
  edge_defaults: ["blocks"]
  detection_keywords: ["gefahr", "risiko"]

Strategie (decision_engine.yaml):

DECISION:
  inject_types: ["value", "risk"] # Füge 'risk' hinzu

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

Schema (types.yaml):

project:
  schema:
    - "Titel"
    - "Ziel"
    - "Budget (Neu)"

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.

8.0 KiB Raw Blame History