WP19 #10
|
|
@ -44,6 +44,7 @@ Das Repository ist in **logische Domänen** unterteilt.
|
|||
| `03_tech_ingestion_pipeline.md`| **Import.** Ablauflogik (13 Schritte), Chunker-Profile, Smart Edge Allocation. |
|
||||
| `03_tech_retrieval_scoring.md` | **Suche.** Die mathematischen Formeln für Scoring, Hybrid Search und Explanation Layer. |
|
||||
| `03_tech_chat_backend.md` | **API & LLM.** Implementation des Routers, Traffic Control (Semaphore) und Feedback-Traceability. |
|
||||
| `03_tech_frontend.md` | **UI & Graph.** Architektur des Streamlit-Frontends, State-Management, Cytoscape-Integration und Editor-Logik. |
|
||||
| `03_tech_configuration.md` | **Config.** Referenztabellen für `.env`, `types.yaml` und `retriever.yaml`. |
|
||||
|
||||
### 📂 04_Operations (Betrieb)
|
||||
|
|
@ -77,6 +78,7 @@ Nutze diese Matrix, wenn du ein Workpackage bearbeitest, um die Dokumentation ko
|
|||
| **Importer / Parsing** | `03_tech_ingestion_pipeline.md` |
|
||||
| **Datenbank-Schema** | `03_tech_data_model.md` (Payloads anpassen) |
|
||||
| **Retrieval / Scoring** | `03_tech_retrieval_scoring.md` (Formeln anpassen) |
|
||||
| **Frontend / Visualisierung** | 1. `03_tech_frontend.md` (Technische Details)<br>2. `01_chat_usage_guide.md` (Bedienung) |
|
||||
| **Chat-Logik / Prompts**| 1. `02_concept_ai_personality.md` (Konzept)<br>2. `03_tech_chat_backend.md` (Tech)<br>3. `01_chat_usage_guide.md` (User-Sicht) |
|
||||
| **Deployment / Server** | `04_admin_operations.md` |
|
||||
| **Neuen Features (Allg.)**| `06_active_roadmap.md` (Status Update) |
|
||||
|
|
|
|||
|
|
@ -1,13 +1,13 @@
|
|||
---
|
||||
doc_type: user_manual
|
||||
audience: user, mindmaster
|
||||
scope: chat, ui, feedback
|
||||
scope: chat, ui, feedback, graph
|
||||
status: active
|
||||
version: 2.6
|
||||
context: "Anleitung zur Nutzung der Web-Oberfläche, der Chat-Personas und des Feedbacks."
|
||||
context: "Anleitung zur Nutzung der Web-Oberfläche, der Chat-Personas und des Graph Explorers."
|
||||
---
|
||||
|
||||
# Chat Usage Guide
|
||||
# Chat & Graph Usage Guide
|
||||
|
||||
**Quellen:** `user_guide.md`
|
||||
|
||||
|
|
@ -36,10 +36,25 @@ Seit Version 2.3.1 bedienst du Mindnet über eine grafische Oberfläche im Brows
|
|||
* **Grüner Punkt:** Hohe Relevanz (Score > 0.8).
|
||||
* **Klick darauf:** Zeigt den Textauszug und die **Begründung** (Explanation Layer).
|
||||
|
||||
### 2.2 Die Sidebar
|
||||
* **Modus-Wahl:** Umschalten zwischen "💬 Chat" und "📝 Manueller Editor".
|
||||
* *Feature:* Der Editor nutzt ein "Resurrection Pattern" – deine Eingaben bleiben erhalten, auch wenn du den Tab wechselst.
|
||||
* **Settings:** Hier kannst du `Top-K` (Anzahl der Quellen) und `Explanation Layer` steuern.
|
||||
### 2.2 Modus: 🕸️ Graph Explorer (Cytoscape)
|
||||
*Neu in v2.6*: Eine interaktive Karte deines Wissens.
|
||||
|
||||
**Die Farb-Logik:**
|
||||
* 🔴 **Roter Rahmen:** Das aktuelle **Zentrum** (Ego). Alle geladenen Knoten sind Nachbarn dieses Knotens.
|
||||
* 🟡 **Gelber Rahmen:** Der **inspizierte** Knoten. Dessen Details siehst du im "Data Inspector" und in der Action-Bar.
|
||||
|
||||
**Bedienung:**
|
||||
1. **Klick auf einen Knoten:** Wählt ihn aus (Gelb). Der Graph bleibt stabil, aber die Info-Leiste oben aktualisiert sich.
|
||||
2. **Button "🎯 Als Zentrum setzen":** Lädt den Graphen neu und macht den ausgewählten Knoten zum roten Zentrum.
|
||||
3. **Button "📝 Bearbeiten":** Springt mit dem Inhalt dieses Knotens direkt in den Editor.
|
||||
|
||||
**Layout & Persistenz:**
|
||||
Du kannst in der linken Spalte die Physik (Abstoßung, Kantenlänge) einstellen. Diese Einstellungen werden in der **URL gespeichert**. Du kannst den Link als Lesezeichen speichern, um genau diese Ansicht wiederzufinden.
|
||||
|
||||
### 2.3 Modus: 📝 Manueller Editor
|
||||
Ein Editor mit **"File System First"** Garantie.
|
||||
* Wenn du eine Datei bearbeitest, liest Mindnet sie direkt von der Festplatte.
|
||||
* **Resurrection:** Wenn du zwischendurch in den Graph wechselst und zurückkommst, ist dein getippter Text noch da.
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
160
docs/03_Technical_References/03_tech_frontend.md
Normal file
160
docs/03_Technical_References/03_tech_frontend.md
Normal file
|
|
@ -0,0 +1,160 @@
|
|||
---
|
||||
doc_type: technical_reference
|
||||
audience: developer, frontend_architect
|
||||
scope: architecture, graph_viz, state_management
|
||||
status: active
|
||||
version: 2.6
|
||||
context: "Technische Dokumentation des modularen Streamlit-Frontends, der Graph-Engines und des Editors."
|
||||
---
|
||||
|
||||
# Technical Reference: Frontend & Visualization
|
||||
|
||||
**Kontext:** Mindnet nutzt Streamlit nicht nur als einfaches UI, sondern als komplexe Applikation mit eigenem State-Management, Routing und Persistenz.
|
||||
|
||||
---
|
||||
|
||||
## 1. Architektur & Modularisierung (WP19)
|
||||
|
||||
Seit Version 2.6 ist das Frontend (`app/frontend/`) kein Monolith mehr, sondern in funktionale Module unterteilt.
|
||||
|
||||
### 1.1 Dateistruktur & Aufgaben
|
||||
|
||||
| Modul | Funktion |
|
||||
| :--- | :--- |
|
||||
| `ui.py` | **Router.** Der Entrypoint. Initialisiert Session-State und entscheidet anhand der Sidebar-Auswahl, welche View gerendert wird. |
|
||||
| `ui_config.py` | **Konstanten.** Zentraler Ort für Farben (`GRAPH_COLORS`), API-Endpunkte und Timeouts. |
|
||||
| `ui_api.py` | **Backend-Bridge.** Kapselt alle `requests`-Aufrufe an die FastAPI. |
|
||||
| `ui_callbacks.py` | **State Transitions.** Logik für View-Wechsel (z.B. Sprung vom Graph in den Editor). |
|
||||
| `ui_utils.py` | **Helper.** Markdown-Parsing (`parse_markdown_draft`) und String-Normalisierung. |
|
||||
| `ui_graph_service.py`| **Data Logic.** Holt Daten aus Qdrant und bereitet Nodes/Edges auf (unabhängig von der Vis-Library). |
|
||||
| `ui_graph_cytoscape.py`| **View: Graph.** Implementierung mit `st-cytoscape` (COSE Layout). |
|
||||
| `ui_editor.py` | **View: Editor.** Logik für Drafts und manuelles Editieren. |
|
||||
|
||||
### 1.2 Konfiguration (`ui_config.py`)
|
||||
|
||||
Zentrale Steuerung der visuellen Semantik.
|
||||
|
||||
# Mapping von Node-Typen zu Farben (Hex)
|
||||
GRAPH_COLORS = {
|
||||
"project": "#ff9f43", # Orange
|
||||
"decision": "#5f27cd", # Lila
|
||||
"experience": "#feca57", # Gelb (Empathie)
|
||||
"concept": "#54a0ff", # Blau
|
||||
"risk": "#ff6b6b" # Rot
|
||||
}
|
||||
|
||||
---
|
||||
|
||||
## 2. Graph Visualisierung
|
||||
|
||||
Mindnet nutzt primär **Cytoscape** für Stabilität bei großen Graphen.
|
||||
|
||||
### 2.1 Engine: Cytoscape (`st-cytoscape`)
|
||||
* **Algorithmus:** `COSE` (Compound Spring Embedder).
|
||||
* **Vorteil:** Verhindert Überlappungen aktiv (`nodeRepulsion`).
|
||||
|
||||
### 2.2 Architektur-Pattern: "Active Inspector, Passive Graph"
|
||||
Ein häufiges Problem bei Streamlit-Graphen ist das "Flackern" (Re-Render) bei Klicks. Wir lösen das durch Entkopplung:
|
||||
|
||||
1. **Stable Key:** Der React-Key der Komponente hängt *nicht* von der Selektion ab, sondern nur vom Zentrum (`center_id`) und Layout-Settings.
|
||||
2. **CSS-Selektion:** Wir nutzen **nicht** den nativen `:selected` State (buggy bei Single-Select), sondern injizieren eine CSS-Klasse `.inspected`.
|
||||
|
||||
**Stylesheet Implementierung (`ui_graph_cytoscape.py`):**
|
||||
|
||||
stylesheet = [
|
||||
{
|
||||
"selector": "node",
|
||||
"style": { "background-color": "data(bg_color)" }
|
||||
},
|
||||
# Wir steuern das Highlight manuell über eine Klasse
|
||||
{
|
||||
"selector": ".inspected",
|
||||
"style": {
|
||||
"border-width": 6,
|
||||
"border-color": "#FFC300", # Gelb/Gold
|
||||
"z-index": 999
|
||||
}
|
||||
},
|
||||
# Native Selektion wird unterdrückt/unsichtbar gemacht
|
||||
{
|
||||
"selector": "node:selected",
|
||||
"style": { "overlay-opacity": 0, "border-width": 0 }
|
||||
}
|
||||
]
|
||||
|
||||
---
|
||||
|
||||
## 3. Editor & Single Source of Truth
|
||||
|
||||
Ein kritisches Design-Pattern ist der Umgang mit Datenkonsistenz beim Editieren ("File System First").
|
||||
|
||||
### 3.1 Das Problem
|
||||
Qdrant speichert Metadaten und Chunks, aber das Feld `fulltext` im Payload kann veraltet sein oder Formatierungen verlieren.
|
||||
|
||||
### 3.2 Die Lösung (Logic Flow)
|
||||
Der `switch_to_editor_callback` in `ui_callbacks.py` implementiert folgende Kaskade:
|
||||
|
||||
def switch_to_editor_callback(note_payload):
|
||||
# 1. Pfad aus Qdrant Payload lesen
|
||||
origin_fname = note_payload.get('path')
|
||||
|
||||
content = ""
|
||||
# 2. Versuch: Hard Read von der Festplatte (Source of Truth)
|
||||
if origin_fname and os.path.exists(origin_fname):
|
||||
with open(origin_fname, "r", encoding="utf-8") as f:
|
||||
content = f.read()
|
||||
else:
|
||||
# 3. Fallback: Rekonstruktion aus der DB ("Stitching")
|
||||
# Nur Notfall, falls Docker-Volume fehlt
|
||||
content = note_payload.get('fulltext', '')
|
||||
|
||||
# State setzen (Transport via Message-Bus)
|
||||
st.session_state.messages.append({
|
||||
"role": "assistant",
|
||||
"intent": "INTERVIEW",
|
||||
"content": content,
|
||||
"origin_filename": origin_fname
|
||||
})
|
||||
st.session_state["sidebar_mode_selection"] = "📝 Manueller Editor"
|
||||
|
||||
Dies garantiert, dass der Editor immer den **echten, aktuellen Stand** der Markdown-Datei anzeigt.
|
||||
|
||||
---
|
||||
|
||||
## 4. State Management Patterns
|
||||
|
||||
### 4.1 URL Persistenz (Deep Linking)
|
||||
Layout-Einstellungen werden in der URL gespeichert, damit sie einen Page-Refresh (F5) überleben.
|
||||
|
||||
# ui_graph_cytoscape.py
|
||||
def update_url_params():
|
||||
st.query_params["depth"] = st.session_state.cy_depth
|
||||
st.query_params["rep"] = st.session_state.cy_node_repulsion
|
||||
|
||||
# Init
|
||||
if "cy_depth" not in st.session_state:
|
||||
st.session_state.cy_depth = int(st.query_params.get("depth", 2))
|
||||
|
||||
### 4.2 Resurrection Pattern
|
||||
Verhindert Datenverlust, wenn der Nutzer während des Tippens den Tab wechselt. Der Editor-Inhalt wird bei jedem Keystroke (`on_change`) in `st.session_state` gespiegelt und beim Neuladen der Komponente von dort wiederhergestellt.
|
||||
|
||||
### 4.3 Healing Parser (`ui_utils.py`)
|
||||
Das LLM liefert oft invalides YAML oder Markdown. Der Parser (`parse_markdown_draft`):
|
||||
* Repariert fehlende Frontmatter-Trenner (`---`).
|
||||
* Extrahiert JSON/YAML aus Code-Blöcken.
|
||||
* Normalisiert Tags (entfernt `#`).
|
||||
|
||||
---
|
||||
|
||||
## 5. Constraints & Security (Known Limitations)
|
||||
|
||||
### 5.1 File System Security
|
||||
Der Editor ("File System First") vertraut dem Pfad im Qdrant-Feld `path`.
|
||||
* **Risiko:** Path Traversal (z.B. `../../etc/passwd`).
|
||||
* **Mitigation:** Aktuell findet keine strikte Prüfung statt, ob der Pfad innerhalb des `./vault` Ordners liegt. Das System setzt voraus, dass die Vektor-Datenbank eine **Trusted Source** ist und nur vom internen Importer befüllt wird.
|
||||
* **ToDo:** Bei Öffnung der API für Dritte muss hier eine `Path.resolve().is_relative_to(VAULT_ROOT)` Prüfung implementiert werden.
|
||||
|
||||
### 5.2 Browser Performance
|
||||
Die Graph-Visualisierung (`st-cytoscape`) rendert Client-seitig im Browser.
|
||||
* **Limit:** Ab ca. **500 Knoten/Kanten** kann das Rendering träge werden.
|
||||
* **Design-Entscheidung:** Das UI ist auf **Ego-Graphen** (Nachbarn eines Knotens) und gefilterte Ansichten ausgelegt, nicht auf die Darstellung des gesamten Knowledge-Graphs ("Whole Brain Visualization").
|
||||
|
|
@ -85,6 +85,7 @@ Environment="STREAMLIT_SERVER_PORT=8501"
|
|||
Environment="STREAMLIT_SERVER_ADDRESS=0.0.0.0"
|
||||
Environment="STREAMLIT_SERVER_HEADLESS=true"
|
||||
|
||||
# WICHTIG: Pfad zur neuen Router-Datei (ui.py)
|
||||
ExecStart=/home/llmadmin/mindnet/.venv/bin/streamlit run app/frontend/ui.py
|
||||
Restart=always
|
||||
RestartSec=5
|
||||
|
|
@ -107,21 +108,28 @@ Führt den Sync stündlich durch. Nutzt `--purge-before-upsert` für Sauberkeit.
|
|||
|
||||
### 3.2 Troubleshooting Guide
|
||||
|
||||
**Fehler: "ModuleNotFoundError: No module named 'st_cytoscape'"**
|
||||
* Ursache: Alte Dependencies oder falsches Paket installiert.
|
||||
* Lösung: Environment aktualisieren.
|
||||
```bash
|
||||
source .venv/bin/activate
|
||||
pip uninstall streamlit-cytoscapejs
|
||||
pip install st-cytoscape
|
||||
# Oder sicherheitshalber:
|
||||
pip install -r requirements.txt
|
||||
```
|
||||
|
||||
**Fehler: "Vector dimension error: expected 768, got 384"**
|
||||
* Ursache: Alte DB (v2.2), neues Modell (v2.4).
|
||||
* Lösung: **Full Reset** (siehe Kap. 4.2).
|
||||
|
||||
**Fehler: "500 Internal Server Error" (Ollama)**
|
||||
* Ursache: Timeout bei Cold-Start des Modells.
|
||||
* Lösung: `MINDNET_LLM_TIMEOUT=300.0` in `.env` setzen.
|
||||
|
||||
**Fehler: Import sehr langsam**
|
||||
* Ursache: Smart Edges sind aktiv und analysieren jeden Chunk.
|
||||
* Lösung: `MINDNET_LLM_BACKGROUND_LIMIT` prüfen oder Feature in `types.yaml` deaktivieren.
|
||||
|
||||
**Fehler: UI "Read timed out"**
|
||||
* Ursache: Backend braucht für Smart Edges länger als 60s.
|
||||
* Lösung: `MINDNET_API_TIMEOUT=300.0` setzen.
|
||||
* Lösung: `MINDNET_API_TIMEOUT=300.0` in `.env` setzen (oder im Systemd Service).
|
||||
|
||||
---
|
||||
|
||||
|
|
|
|||
|
|
@ -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.
|
||||
|
|
@ -8,20 +8,20 @@ context: "Aktuelle Planung für kommende Features (ab WP16), Release-Strategie u
|
|||
|
||||
# Mindnet Active Roadmap
|
||||
|
||||
**Aktueller Stand:** v2.6.0 (Post-WP15)
|
||||
**Fokus:** Usability, Memory & Visualisierung.
|
||||
**Aktueller Stand:** v2.6.0 (Post-WP19)
|
||||
**Fokus:** Visualisierung, Exploration & Deep Search.
|
||||
|
||||
## 1. Programmstatus
|
||||
|
||||
Wir haben Phase D (Interaktion) weitgehend abgeschlossen. Das System ist stabil, verfügt über Traffic Control und Smart Edges. Der Fokus verschiebt sich nun auf **Phase E (Maintenance & Scaling)** sowie die Vertiefung der KI-Fähigkeiten.
|
||||
Wir haben mit der Implementierung des Graph Explorers (WP19) einen Meilenstein in **Phase E (Maintenance & Scaling)** erreicht. Die Architektur ist nun modular. Der nächste Schritt (WP19a) vertieft die Analyse-Fähigkeiten.
|
||||
|
||||
| Phase | Fokus | Status |
|
||||
| :--- | :--- | :--- |
|
||||
| **Phase A** | Fundament & Import | ✅ Fertig |
|
||||
| **Phase B** | Semantik & Graph | ✅ Fertig |
|
||||
| **Phase C** | Persönlichkeit | ✅ Fertig |
|
||||
| **Phase D** | Interaktion & Tools | 🟡 Abschlussphase |
|
||||
| **Phase E** | Maintenance & Visualisierung | 🚀 Start |
|
||||
| **Phase D** | Interaktion & Tools | ✅ Fertig |
|
||||
| **Phase E** | Maintenance & Visualisierung | 🚀 Aktiv |
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -44,6 +44,7 @@ Eine Übersicht der implementierten Features zum schnellen Auffinden von Funktio
|
|||
| **WP-10a**| Draft Editor | GUI-Komponente zum Bearbeiten und Speichern generierter Notizen. |
|
||||
| **WP-11** | Backend Intelligence | `nomic-embed-text` (768d) und Matrix-Logik für Kanten-Typisierung. |
|
||||
| **WP-15** | Smart Edge Allocation | LLM-Filter für Kanten in Chunks + Traffic Control (Semaphore). |
|
||||
| **WP-19** | Graph Visualisierung | **Frontend Modularisierung:** Umbau auf `ui_*.py`.<br>**Graph Engines:** Parallelbetrieb von Cytoscape (COSE) und Agraph.<br>**Tools:** "Single Source of Truth" Editor, Persistenz via URL. |
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -51,19 +52,24 @@ Eine Übersicht der implementierten Features zum schnellen Auffinden von Funktio
|
|||
|
||||
Diese Features stehen als nächstes an.
|
||||
|
||||
### WP-19a – Graph Intelligence & Discovery (Sprint-Fokus)
|
||||
**Status:** 🚀 Startklar
|
||||
**Ziel:** Vom "Anschauen" zum "Verstehen". Deep-Dive Werkzeuge für den Graphen.
|
||||
* **Discovery Screen:** Neuer Tab für semantische Suche ("Finde Notizen über Vaterschaft") und Wildcard-Filter.
|
||||
* **Filter-Logik:** "Zeige nur Wege, die zu `type:decision` führen".
|
||||
* **Chunk Inspection:** Umschaltbare Granularität (Notiz vs. Chunk) zur Validierung des Smart Chunkers.
|
||||
|
||||
### WP-16 – Auto-Discovery & Enrichment
|
||||
**Status:** 🟡 Geplant
|
||||
**Ziel:** Automatisches Erkennen von fehlenden Kanten in "dummem" Text *vor* der Speicherung.
|
||||
* **Problem:** Nutzer vergessen Wikilinks.
|
||||
* **Lösung:** Ein "Enricher" scannt Text vor dem Import, findet Keywords (z.B. "Mindnet") und schlägt Links vor (`[[Mindnet]]`).
|
||||
* **Abgrenzung:** Anders als *Active Intelligence* (WP11, UI-basiert) läuft dies im Backend (Importer).
|
||||
|
||||
### WP-17 – Conversational Memory (Gedächtnis)
|
||||
**Status:** 🟡 Geplant
|
||||
**Ziel:** Echte Dialoge statt Request-Response.
|
||||
* **Tech:** Erweiterung des `ChatRequest` DTO um `history`.
|
||||
* **Logik:** Token-Management (Context Window Balancing zwischen RAG-Doks und Chat-Verlauf).
|
||||
* **Nutzen:** Rückfragen ("Was meinst du damit?") werden möglich.
|
||||
|
||||
### WP-18 – Graph Health & Maintenance
|
||||
**Status:** 🟡 Geplant (Prio 2)
|
||||
|
|
@ -71,17 +77,10 @@ Diese Features stehen als nächstes an.
|
|||
* **Feature:** Cronjob `check_graph_integrity.py`.
|
||||
* **Funktion:** Findet "Dangling Edges" (Links auf gelöschte Notizen) und repariert/löscht sie.
|
||||
|
||||
### WP-19 – Graph Visualisierung & Explorer
|
||||
**Status:** 🟡 Geplant (Prio 1)
|
||||
**Ziel:** Vertrauen durch Transparenz.
|
||||
* **UI:** Neuer Tab "🕸️ Graph" in Streamlit.
|
||||
* **Tech:** `streamlit-agraph` oder `pyvis`.
|
||||
* **Nutzen:** Visuelle Kontrolle der *Smart Edge Allocation* ("Hat das LLM die Kante wirklich hierhin gesetzt?").
|
||||
|
||||
### WP-20 – Cloud Hybrid Mode (Optional)
|
||||
**Status:** ⚪ Optional
|
||||
**Ziel:** "Turbo-Modus" für Massen-Imports.
|
||||
* **Konzept:** Switch in `.env`, um statt Ollama (Lokal) auf Google Gemini (Cloud) umzuschalten, wenn Datenschutz-unkritische Daten verarbeitet werden.
|
||||
* **Konzept:** Switch in `.env`, um statt Ollama (Lokal) auf Google Gemini (Cloud) umzuschalten.
|
||||
|
||||
---
|
||||
|
||||
|
|
@ -89,20 +88,7 @@ Diese Features stehen als nächstes an.
|
|||
|
||||
```mermaid
|
||||
graph TD
|
||||
WP15(Smart Edges) --> WP19(Visualisierung)
|
||||
WP15 --> WP16(Auto-Discovery)
|
||||
WP10(Chat UI) --> WP17(Memory)
|
||||
WP19(Graph Viz) --> WP19a(Discovery)
|
||||
WP19a --> WP17(Memory)
|
||||
WP15(Smart Edges) --> WP16(Auto-Discovery)
|
||||
WP03(Import) --> WP18(Health Check)
|
||||
```
|
||||
|
||||
**Nächstes Release (v2.7):**
|
||||
* Ziel: Visualisierung (WP19) + Conversational Memory (WP17).
|
||||
* ETA: Q1 2026.
|
||||
|
||||
---
|
||||
|
||||
## 5. Governance
|
||||
|
||||
* **Versionierung:** Semantic Versioning via Gitea Tags.
|
||||
* **Feature-Branches:** Jedes WP erhält einen Branch `feature/wpXX-name`.
|
||||
* **Sync First:** Bevor ein neuer Branch erstellt wird, muss `main` gepullt werden.
|
||||
|
|
@ -2,12 +2,12 @@
|
|||
doc_type: archive
|
||||
audience: historian, architect
|
||||
status: archived
|
||||
context: "Archivierte Details zu abgeschlossenen Workpackages (WP01-WP15). Referenz für historische Design-Entscheidungen."
|
||||
context: "Archivierte Details zu abgeschlossenen Workpackages (WP01-WP19). Referenz für historische Design-Entscheidungen."
|
||||
---
|
||||
|
||||
# Legacy Workpackages (Archiv)
|
||||
|
||||
**Quellen:** `Programmplan_V2.2.md`
|
||||
**Quellen:** `Programmplan_V2.2.md`, `Active Roadmap`
|
||||
|
||||
**Status:** Abgeschlossen / Implementiert.
|
||||
Dieses Dokument dient als Referenz für die Entstehungsgeschichte von Mindnet v2.6.
|
||||
|
|
@ -80,3 +80,15 @@ Dieses Dokument dient als Referenz für die Entstehungsgeschichte von Mindnet v2
|
|||
* **Problem:** "Broadcasting". Ein Chunk erbte alle Links der Note, auch irrelevante. Das verwässerte die Suchergebnisse.
|
||||
* **Lösung:** LLM prüft jeden Chunk auf Link-Relevanz.
|
||||
* **Tech:** Einführung von **Traffic Control** (Semaphore), um Import und Chat zu parallelisieren, ohne die Hardware zu überlasten.
|
||||
|
||||
---
|
||||
|
||||
## Phase E: Visualisierung & Maintenance (WP19)
|
||||
|
||||
### WP-19 – Graph Visualisierung & Modularisierung
|
||||
* **Ziel:** Transparenz über die Datenstruktur schaffen und technische Schulden (Monolith) abbauen.
|
||||
* **Ergebnis:**
|
||||
* **Modularisierung:** Aufsplittung der `ui.py` in Router, Services und Views (`ui_*.py`).
|
||||
* **Graph Explorer:** Einführung von `st-cytoscape` für stabile, nicht-überlappende Layouts (COSE) als Ergänzung zur Legacy-Engine (Agraph).
|
||||
* **Single Source of Truth:** Der Editor lädt Inhalte nun direkt vom Dateisystem statt aus (potenziell veralteten) Vektor-Payloads.
|
||||
* **UX:** Einführung von URL-Persistenz für Layout-Settings und CSS-basiertes Highlighting zur Vermeidung von Re-Renders.
|
||||
|
|
@ -31,3 +31,7 @@ pytest>=8.4.2
|
|||
|
||||
# --- Frontend (WP-10) ---
|
||||
streamlit>=1.39.0
|
||||
|
||||
# Visualization (Parallelbetrieb)
|
||||
streamlit-agraph>=0.0.45
|
||||
st-cytoscape>=1.0.0
|
||||
Loading…
Reference in New Issue
Block a user