diff --git a/docs/00_General/00_documentation_map.md b/docs/00_General/00_documentation_map.md index 3957f31..1a443b9 100644 --- a/docs/00_General/00_documentation_map.md +++ b/docs/00_General/00_documentation_map.md @@ -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)
2. `01_chat_usage_guide.md` (Bedienung) | | **Chat-Logik / Prompts**| 1. `02_concept_ai_personality.md` (Konzept)
2. `03_tech_chat_backend.md` (Tech)
3. `01_chat_usage_guide.md` (User-Sicht) | | **Deployment / Server** | `04_admin_operations.md` | | **Neuen Features (Allg.)**| `06_active_roadmap.md` (Status Update) | diff --git a/docs/01_User_Manual/01_chat_usage_guide.md b/docs/01_User_Manual/01_chat_usage_guide.md index e618c31..a4e6eee 100644 --- a/docs/01_User_Manual/01_chat_usage_guide.md +++ b/docs/01_User_Manual/01_chat_usage_guide.md @@ -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. --- diff --git a/docs/03_Technical_References/03_tech_frontend.md b/docs/03_Technical_References/03_tech_frontend.md new file mode 100644 index 0000000..9af4009 --- /dev/null +++ b/docs/03_Technical_References/03_tech_frontend.md @@ -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"). \ No newline at end of file diff --git a/docs/04_Operations/04_admin_operations.md b/docs/04_Operations/04_admin_operations.md index 438203f..0efd209 100644 --- a/docs/04_Operations/04_admin_operations.md +++ b/docs/04_Operations/04_admin_operations.md @@ -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). --- diff --git a/docs/05_Development/05_developer_guide.md b/docs/05_Development/05_developer_guide.md index 56216f1..05bb6e1 100644 --- a/docs/05_Development/05_developer_guide.md +++ b/docs/05_Development/05_developer_guide.md @@ -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 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`. \ No newline at end of file +* Ursache: Backend braucht für Smart Edges länger als 60s. +* Lösung: `MINDNET_API_TIMEOUT=300.0` in `.env` setzen. \ No newline at end of file diff --git a/docs/06_Roadmap/06_active_roadmap.md b/docs/06_Roadmap/06_active_roadmap.md index 7fdf107..fa9c220 100644 --- a/docs/06_Roadmap/06_active_roadmap.md +++ b/docs/06_Roadmap/06_active_roadmap.md @@ -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`.
**Graph Engines:** Parallelbetrieb von Cytoscape (COSE) und Agraph.
**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) - 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. \ No newline at end of file + WP19(Graph Viz) --> WP19a(Discovery) + WP19a --> WP17(Memory) + WP15(Smart Edges) --> WP16(Auto-Discovery) + WP03(Import) --> WP18(Health Check) \ No newline at end of file diff --git a/docs/99_Archive/99_legacy_workpackages.md b/docs/99_Archive/99_legacy_workpackages.md index 86efb9f..7eed15f 100644 --- a/docs/99_Archive/99_legacy_workpackages.md +++ b/docs/99_Archive/99_legacy_workpackages.md @@ -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. @@ -79,4 +79,16 @@ Dieses Dokument dient als Referenz für die Entstehungsgeschichte von Mindnet v2 ### WP-15 – Smart Edge Allocation (Meilenstein) * **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. \ No newline at end of file +* **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. \ No newline at end of file diff --git a/requirements.txt b/requirements.txt index 1828b3d..0027259 100644 --- a/requirements.txt +++ b/requirements.txt @@ -30,4 +30,8 @@ tqdm>=4.67.1 pytest>=8.4.2 # --- Frontend (WP-10) --- -streamlit>=1.39.0 \ No newline at end of file +streamlit>=1.39.0 + +# Visualization (Parallelbetrieb) +streamlit-agraph>=0.0.45 +st-cytoscape>=1.0.0 \ No newline at end of file