Lars
b26d9fd10e
All checks were successful
Deploy mindnet to llm-node / deploy (push) Successful in 4s
255 lines
8.1 KiB
Markdown
255 lines
8.1 KiB
Markdown
---
|
|
doc_type: developer_guide
|
|
audience: developer
|
|
scope: workflow, testing, architecture, modules
|
|
status: active
|
|
version: 2.6
|
|
context: "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
|
|
|
|
```text
|
|
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:**
|
|
|
|
```bash
|
|
# 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):**
|
|
|
|
```ini
|
|
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):**
|
|
```bash
|
|
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`):**
|
|
```yaml
|
|
risk:
|
|
retriever_weight: 0.90
|
|
edge_defaults: ["blocks"]
|
|
detection_keywords: ["gefahr", "risiko"]
|
|
```
|
|
2. **Strategie (`decision_engine.yaml`):**
|
|
```yaml
|
|
DECISION:
|
|
inject_types: ["value", "risk"] # Füge 'risk' hinzu
|
|
```
|
|
3. **Visualisierung (`ui_config.py`):**
|
|
Füge dem `GRAPH_COLORS` Dictionary einen Eintrag hinzu:
|
|
```python
|
|
"risk": "#ff6b6b"
|
|
```
|
|
|
|
### Workflow B: Interview-Schema anpassen (WP07)
|
|
Wenn Mindnet neue Fragen stellen soll (z.B. "Budget" bei Projekten):
|
|
1. **Schema (`types.yaml`):**
|
|
```yaml
|
|
project:
|
|
schema:
|
|
- "Titel"
|
|
- "Ziel"
|
|
- "Budget (Neu)"
|
|
```
|
|
2. **Kein Code nötig:** Der `One-Shot Extractor` liest dies dynamisch.
|
|
|
|
---
|
|
|
|
## 6. Tests & Debugging
|
|
|
|
**Unit Tests:**
|
|
|
|
```bash
|
|
pytest tests/test_retriever_basic.py
|
|
pytest tests/test_chunking.py
|
|
```
|
|
|
|
**Pipeline Tests:**
|
|
|
|
```bash
|
|
# 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:**
|
|
|
|
```bash
|
|
# 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!):**
|
|
|
|
```bash
|
|
python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet_dev" --yes
|
|
```
|
|
|
|
**Einen einzelnen File inspizieren (Parser-Sicht):**
|
|
|
|
```bash
|
|
python3 tests/inspect_one_note.py --file ./vault/MeinFile.md
|
|
```
|
|
|
|
**Live-Logs sehen:**
|
|
|
|
```bash
|
|
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. |