Dokumentation WP19

This commit is contained in:
Lars committed 2025-12-14 20:47:49 +01:00
1 parent eccdf43cd3
commit efd9c74cd3
8 files changed
+267 -58

No files matched your search

+32 -10
View File
@@ -32,6 +32,7 @@ Mindnet läuft in einer verteilten Umgebung (Post-WP15 Setup).
Der Code ist modular in `app` (Logik), `scripts` (CLI) und `config` (Steuerung) getrennt.
### 2.1 Verzeichnisbaum
```text
mindnet/
├── app/
@@ -50,8 +51,15 @@ mindnet/
│ │ ├── semantic_analyzer.py# LLM-Filter für Edges (WP15)
│ │ ├── embeddings_client.py# Async Embeddings (HTTPX)
│ │ └── discovery.py # Intelligence Logic (WP11)
│ ├── frontend/
│ │ └── ui.py # Streamlit App inkl. Healing Parser
│ ├── 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)
@@ -61,6 +69,12 @@ mindnet/
### 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).
@@ -76,10 +90,6 @@ mindnet/
* Implementiert die Scoring-Formel (`Semantik + Graph + Typ`).
* **Hybrid Search:** Lädt dynamisch den Subgraphen (`graph_adapter.expand`).
**Das Frontend (`app.frontend.ui`)**
* **Resurrection Pattern:** Nutzt `st.session_state`, um Eingaben bei Tab-Wechseln zu erhalten.
* **Healing Parser:** Die Funktion `parse_markdown_draft` repariert defekte YAML-Frontmatter vom LLM automatisch.
**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.
@@ -91,6 +101,7 @@ mindnet/
**Voraussetzungen:** Python 3.10+, Docker, Ollama.
**Installation:**
```bash
# 1. Repo & Venv
git clone <repo> mindnet
@@ -98,7 +109,7 @@ cd mindnet
python3 -m venv .venv
source .venv/bin/activate
# 2. Dependencies
# 2. Dependencies (inkl. st-cytoscape)
pip install -r requirements.txt
# 3. Ollama (Nomic ist Pflicht!)
@@ -107,6 +118,7 @@ ollama pull nomic-embed-text
```
**Konfiguration (.env):**
```ini
QDRANT_URL="http://localhost:6333"
COLLECTION_PREFIX="mindnet_dev"
@@ -164,7 +176,11 @@ Mindnet lernt durch Konfiguration, nicht durch Training.
DECISION:
inject_types: ["value", "risk"] # Füge 'risk' hinzu
```
3. **Kognition (`prompts.yaml`):** (Optional) Passe den System-Prompt an, falls nötig.
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):
@@ -183,12 +199,14 @@ Wenn Mindnet neue Fragen stellen soll (z.B. "Budget" bei Projekten):
## 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
@@ -198,6 +216,7 @@ 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?"
@@ -211,21 +230,24 @@ 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: Smart Edges brauchen länger als 60s.
* Lösung: `MINDNET_API_TIMEOUT=300.0` in `.env`.
* Ursache: Backend braucht für Smart Edges länger als 60s.
* Lösung: `MINDNET_API_TIMEOUT=300.0` in `.env` setzen.