Dokumentation WP19
This commit is contained in:
1 parent
eccdf43cd3
commit
efd9c74cd3
8 files changed
+267
-58
No files matched your search
@@ -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.
|
||||
Reference in new issue
Block a user