code header
This commit is contained in:
1 parent
ec759dd1dc
commit
83bb18b6a7
42 files changed
+469
-615
No files matched your search
@@ -9,145 +9,200 @@ context: "Umfassender Guide für Entwickler: Architektur, Modul-Interna (Deep Di
|
||||
|
||||
# Mindnet Developer Guide & Workflow
|
||||
|
||||
**Quellen:** `developer_guide.md`, `dev_workflow.md`
|
||||
**Quellen:** `developer_guide.md`, `dev_workflow.md`, `Architecture_Audit_v2.6`
|
||||
|
||||
Dieser Guide vereint das technische Verständnis der Module mit dem operativen Workflow zwischen Windows (Dev) und Linux (Runtime).
|
||||
Dieser Guide ist die zentrale technische Referenz für Mindnet v2.6. Er vereint das technische Verständnis der Module mit dem operativen Workflow zwischen Windows (Dev) und Linux (Runtime).
|
||||
|
||||
---
|
||||
|
||||
## 1. Die physische Architektur
|
||||
## 1. Einführung & Systemüberblick
|
||||
|
||||
### Was ist Mindnet?
|
||||
Mindnet ist ein **Hybrides Knowledge Management System**, das klassische Notizen (Markdown) mit KI-gestützter Analyse verbindet. Es kombiniert **RAG** (Retrieval Augmented Generation) mit einer **Graphen-Datenbank** (Qdrant), um Wissen nicht nur semantisch zu finden, sondern auch strukturell zu vernetzen.
|
||||
|
||||
### Kern-Philosophie
|
||||
1. **Filesystem First:** Die Wahrheit liegt immer auf der Festplatte (Markdown-Dateien). Die Datenbank ist ein abgeleiteter Index.
|
||||
2. **Hybrid Retrieval:** Relevanz entsteht aus Textähnlichkeit (Semantik) + Graphen-Verbindungen (Edges) + Wichtigkeit (Centrality).
|
||||
3. **Active Intelligence:** Das System wartet nicht nur auf Anfragen, sondern schlägt beim Schreiben proaktiv Verbindungen vor ("Matrix Logic").
|
||||
4. **Local Privacy:** Alle KI-Berechnungen (Ollama) laufen lokal. Keine Cloud-Abhängigkeit für Inference.
|
||||
|
||||
---
|
||||
|
||||
## 2. Architektur
|
||||
|
||||
### 2.1 High-Level Übersicht
|
||||
Das System folgt einer strikten Trennung zwischen Frontend (Streamlit) und Backend (FastAPI), wobei bestimmte Performance-Pfade (Graph-Visualisierung) optimiert wurden.
|
||||
|
||||
```mermaid
|
||||
graph TD
|
||||
User((User))
|
||||
|
||||
subgraph "Frontend Layer (Streamlit)"
|
||||
UI[ui.py Router]
|
||||
ViewChat[Chat View]
|
||||
ViewGraph[Graph View]
|
||||
ViewEditor[Editor View]
|
||||
Logic[Callbacks & State]
|
||||
end
|
||||
|
||||
subgraph "Backend Layer (FastAPI)"
|
||||
API[main.py]
|
||||
RouterChat[Chat / RAG]
|
||||
RouterIngest[Ingest / Write]
|
||||
CoreRet[Retriever Engine]
|
||||
CoreIngest[Ingestion Pipeline]
|
||||
end
|
||||
|
||||
subgraph "Infrastructure & Services"
|
||||
LLM[Ollama (Phi3/Nomic)]
|
||||
DB[(Qdrant Vector DB)]
|
||||
FS[File System (.md)]
|
||||
end
|
||||
|
||||
User <--> UI
|
||||
UI --> API : REST (Chat, Save, Feedback)
|
||||
UI -.-> DB : Direct Read (Graph Viz Performance)
|
||||
API --> LLM : Embeddings & Completion
|
||||
API --> DB : Read/Write
|
||||
API --> FS : Read/Write (Source of Truth)
|
||||
```
|
||||
|
||||
### 2.2 Datenfluss-Muster
|
||||
|
||||
1. **Ingestion (Write):**
|
||||
`Markdown` -> `Parser` -> `Chunker` -> `SemanticAnalyzer (LLM)` -> `Embedder` -> `Qdrant (Points)`
|
||||
2. **Retrieval (Read):**
|
||||
`Query` -> `Embedding` -> `Hybrid Search (Vector + Graph)` -> `Re-Ranking` -> `LLM Context`
|
||||
3. **Visualisierung (Graph):**
|
||||
`UI` -> `GraphService` -> `Qdrant (Edges Collection)` -> `Cytoscape`
|
||||
|
||||
---
|
||||
|
||||
## 3. 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!
|
||||
* **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`.
|
||||
* **Gitea:** Der "Safe" (Raspberry Pi). Speichert den Code und verwaltet Versionen.
|
||||
* **Windows 11 (VS Code):** Entwicklungsumgebung. **Nie** direkt auf `main` arbeiten!
|
||||
* **Beelink (Runtime):** Der Server hostet zwei Instanzen via Systemd:
|
||||
* **PROD:** API (Port 8001) + UI (Port 8501). Home: `~/mindnet`.
|
||||
* **DEV:** API (Port 8002) + UI (Port 8502). Home: `~/mindnet_dev`.
|
||||
* **Gitea (Raspberry Pi):** Versionskontrolle ("Safe"). Speichert den Code.
|
||||
|
||||
---
|
||||
|
||||
## 2. Projektstruktur & Referenz
|
||||
## 4. Projektstruktur & Modul-Referenz (Deep Dive)
|
||||
|
||||
### 2.1 Verzeichnisbaum
|
||||
Das System ist modular aufgebaut. Hier ist die detaillierte Analyse aller Komponenten.
|
||||
|
||||
### 4.1 Verzeichnisbaum
|
||||
|
||||
```text
|
||||
mindnet/
|
||||
├── app/
|
||||
│ ├── core/ # Ingestion, Chunker, Qdrant Wrapper
|
||||
│ ├── routers/ # FastAPI Endpoints
|
||||
│ ├── services/ # Ollama Client, Traffic Control
|
||||
│ ├── core/ # Business Logic & Algorithms
|
||||
│ ├── routers/ # API Interface (FastAPI)
|
||||
│ ├── services/ # External Integrations (LLM, DB)
|
||||
│ ├── models/ # Pydantic DTOs
|
||||
│ └── frontend/ # Streamlit UI Module
|
||||
├── config/ # YAML Configs (Single Source of Truth)
|
||||
├── scripts/ # CLI Tools (Import, Diagnose, Reset)
|
||||
├── tests/ # Pytest Suite & Smoke Scripts
|
||||
└── vault/ # Lokaler Test-Content
|
||||
│ └── frontend/ # UI Logic (Streamlit)
|
||||
├── config/ # Configuration Files (YAML)
|
||||
├── scripts/ # CLI Tools (Ops & Maintenance)
|
||||
└── vault/ # Local Content Storage
|
||||
```
|
||||
|
||||
### 2.2 Vollständige Datei-Referenz (Auto-Scan)
|
||||
### 4.2 Frontend Architecture (`app/frontend/`)
|
||||
|
||||
Eine Übersicht aller Skripte und Module im System.
|
||||
Das Frontend ist eine Streamlit-App, die sich wie eine Single-Page-Application (SPA) verhält.
|
||||
|
||||
| Datei/Pfad | Typ | Beschreibung |
|
||||
| Modul | Status | Verantwortung |
|
||||
| :--- | :--- | :--- |
|
||||
| **Backend Core** | | |
|
||||
| `app/main.py` | Skript | Bootstrap der FastAPI API. |
|
||||
| `app/config.py` | Config | Zentrale Konfiguration (Pydantic Settings). |
|
||||
| `app/core/ingestion.py` | Core Modul | Async Ingestion Service & Change Detection. |
|
||||
| `app/core/chunker.py` | Core Modul | Smart Chunker Orchestrator. |
|
||||
| `app/core/retriever.py` | Core Modul | Hybrider Such-Algorithmus (Semantik + Graph). |
|
||||
| `app/core/ranking.py` | Core Modul | Kombiniertes Scoring (WP-04). |
|
||||
| `app/core/graph_adapter.py` | Core Modul | Adjazenzaufbau & Subgraph-Expansion. |
|
||||
| `app/core/qdrant.py` | Core Modul | Qdrant Client Wrapper. |
|
||||
| `app/core/qdrant_points.py` | Core Modul | Robuste Point-Helper für Qdrant (Retry-Logik). |
|
||||
| `app/core/derive_edges.py` | Core Modul | Edge-Erzeugung aus Markdown. |
|
||||
| `app/core/edges.py` | Core Modul | Datenstrukturen für Kanten. |
|
||||
| `app/core/edges_writer.py` | Core Modul | Schreibt Kanten in die DB. |
|
||||
| `app/core/note_payload.py` | Core Modul | Builder für Note-Metadaten. |
|
||||
| `app/core/chunk_payload.py` | Core Modul | Builder für Chunk-Payloads. |
|
||||
| `app/core/type_registry.py` | Core Modul | Logik zum Laden der `types.yaml`. |
|
||||
| `app/core/schema_loader.py` | Core Modul | Lädt JSON-Schemas für Validierung. |
|
||||
| `app/core/env_vars.py` | Core Modul | Environment-Variablen Konstanten. |
|
||||
| **API Router** | | |
|
||||
| `app/routers/chat.py` | API Router | RAG Endpunkt & Hybrid Router. |
|
||||
| `app/routers/query.py` | API Router | Query-Endpunkte (WP-04). |
|
||||
| `app/routers/graph.py` | API Router | Graph-Endpunkte (WP-04). |
|
||||
| `app/routers/ingest.py` | API Router | Ingestion-Trigger & Analyse. |
|
||||
| `app/routers/feedback.py` | API Router | Feedback-Endpunkt. |
|
||||
| `app/routers/tools.py` | API Router | Tool-Definitionen für Ollama/n8n/MCP. |
|
||||
| `app/routers/admin.py` | API Router | Admin-/Monitoring-Endpunkte. |
|
||||
| **`ui.py`** | 🟢 Core | **Main Router.** Initialisiert Session-State und entscheidet anhand der Sidebar-Auswahl, welche View gerendert wird. |
|
||||
| **`ui_config.py`** | 🟢 Config | **Constants.** Zentraler Ort für Farben (`GRAPH_COLORS`), API-URLs und Timeouts. Änderungen am Look & Feel passieren hier. |
|
||||
| **`ui_chat.py`** | 🟢 View | **Chat UI.** Rendert Nachrichtenverlauf, Intent-Badges, Quellen-Expanders und Feedback-Buttons. |
|
||||
| **`ui_editor.py`** | 🟢 View | **Editor UI.** Markdown-Editor mit Live-Vorschau. Integriert "Intelligence" (KI-Link-Vorschläge). |
|
||||
| **`ui_graph_cytoscape.py`**| 🟢 View | **Modern Graph.** Interaktiver Graph basierend auf Cytoscape.js (COSE Layout). |
|
||||
| **`ui_graph.py`** | 🟡 Legacy | **Graph UI (Fallback).** Alte Implementierung mittels `streamlit-agraph`. |
|
||||
| **`ui_callbacks.py`** | 🟢 Logic | **State Controller.** Handhabt komplexe State-Übergänge (z.B. Graph -> Editor). |
|
||||
| **`ui_utils.py`** | 🟢 Logic | **Helper.** Enthält den **Healing Parser** (`parse_markdown_draft`), der defektes JSON/YAML von LLMs repariert. |
|
||||
| **`ui_api.py`** | 🟢 Data | **API Client.** Wrapper für Backend REST-Calls. |
|
||||
| **`ui_graph_service.py`** | 🟢 Data | **Performance Hack.** Greift direkt auf Qdrant zu (bypass API), um Graphen schnell zu laden. |
|
||||
|
||||
#### Frontend Design Patterns (Wichtig!)
|
||||
|
||||
1. **Active Inspector Pattern (`ui_graph_cytoscape.py`)**
|
||||
Um Re-Renders im Graphen zu vermeiden, nutzen wir CSS-Klassen. Wird ein Knoten angeklickt, ändert sich nur die CSS-Klasse (`.inspected`), aber die Physik-Simulation startet nicht neu. Das sorgt für ein stabiles UI-Gefühl.
|
||||
|
||||
2. **Resurrection Pattern (`ui_editor.py`)**
|
||||
Streamlit neigt dazu, Eingaben bei Re-Runs zu "vergessen". Der Editor synchronisiert seinen Inhalt aggressiv in den `session_state`.
|
||||
* Logik: `if widget_key not in session_state: restore_from_data_key()`.
|
||||
* Ergebnis: Texteingaben überleben Tab-Wechsel.
|
||||
|
||||
3. **Filesystem First (`ui_callbacks.py`)**
|
||||
Wenn man im Graphen auf "Bearbeiten" klickt:
|
||||
1. Versucht das System, die **echte Datei** von der Festplatte zu lesen.
|
||||
2. Nur wenn das fehlschlägt, wird der Text aus den Datenbank-Chunks rekonstruiert ("Stitching").
|
||||
Dies verhindert, dass veraltete Datenbank-Stände die echten Dateien überschreiben.
|
||||
|
||||
---
|
||||
|
||||
### 4.3 Backend Architecture (`app/`)
|
||||
|
||||
Das Backend stellt die Logik via REST-API bereit.
|
||||
|
||||
| Modul | Typ | Verantwortung |
|
||||
| :--- | :--- | :--- |
|
||||
| **Core Engine** | | |
|
||||
| `core/ingestion.py` | Engine | **Pipeline Controller.** Koordiniert den 13-Schritte-Import, Parsing, Hash-Check und DB-Upserts. |
|
||||
| `core/retriever.py` | Engine | **Search Engine.** Berechnet Hybrid-Score: `(Semantic * W) + (Edge Bonus * 0.25) + (Centrality * 0.05)`. |
|
||||
| `core/chunker.py` | Engine | **Segmentation.** Zerlegt Text intelligent. Orchestriert `SemanticAnalyzer` für Smart Edges. |
|
||||
| `core/derive_edges.py`| Engine | **Link Extractor.** Findet Wikilinks, Callouts und Typed Relations im Text. |
|
||||
| `core/qdrant_points.py`| Mapper | **Object Mapper.** Wandelt Payloads in Qdrant `PointStruct`s um. |
|
||||
| `core/graph_adapter.py` | Algo | **Graph Logic.** Baut In-Memory Graphen für Re-Ranking und Pfad-Analysen. |
|
||||
| **Router (API)** | | |
|
||||
| `routers/chat.py` | Router | **Hybrid Router.** Entscheidet: RAG-Antwort vs. Interview-Modus. |
|
||||
| `routers/ingest.py` | Router | **Write API.** Nimmt Markdown entgegen, steuert Ingestion und Discovery-Analyse. |
|
||||
| `routers/query.py` | Router | **Search API.** Klassischer Hybrid-Retriever Endpunkt. |
|
||||
| `routers/graph.py` | Router | **Viz API.** Liefert Knoten/Kanten für Frontend. |
|
||||
| **Services** | | |
|
||||
| `app/services/llm_service.py` | Service | LLM Client mit Traffic Control. |
|
||||
| `app/services/llm_ollama.py` | Service | Legacy: Ollama-Integration & Prompt-Bau. |
|
||||
| `app/services/embeddings_client.py` | Service | Async Text→Embedding Service. |
|
||||
| `app/services/semantic_analyzer.py` | Service | Smart Edge Validation & Filtering. |
|
||||
| `app/services/discovery.py` | Service | Backend Intelligence (Matrix-Logik). |
|
||||
| `app/services/feedback_service.py` | Service | Schreibt JSONL-Logs. |
|
||||
| **Frontend** | | |
|
||||
| `app/frontend/ui.py` | Frontend | Entrypoint (Streamlit). |
|
||||
| `app/frontend/ui_editor.py` | Frontend | Editor-View & Logic. |
|
||||
| `app/frontend/ui_chat.py` | Frontend | Chat-View. |
|
||||
| `app/frontend/ui_graph_cytoscape.py` | Frontend | Graph-Visualisierung (Modern). |
|
||||
| `app/frontend/ui_graph.py` | Frontend | Graph-Visualisierung (Legacy). |
|
||||
| `app/frontend/ui_graph_service.py` | Frontend | Datenaufbereitung für Graphen. |
|
||||
| `app/frontend/ui_callbacks.py` | Frontend | Event-Handler. |
|
||||
| `app/frontend/ui_api.py` | Frontend | Backend-Bridge. |
|
||||
| `app/frontend/ui_utils.py` | Frontend | Helper (Healing Parser). |
|
||||
| `app/frontend/ui_config.py` | Frontend | Konstanten (Farben, URLs). |
|
||||
| **CLI & Scripts** | | |
|
||||
| `scripts/import_markdown.py` | Skript | Haupt-Importer CLI. |
|
||||
| `scripts/reset_qdrant.py` | Skript | Löscht Collections (`--mode wipe`). |
|
||||
| `scripts/payload_dryrun.py` | Skript | Zeigt Payloads VOR dem Upsert. |
|
||||
| `scripts/edges_dryrun.py` | Skript | Erzeugt Edges ohne DB-Write. |
|
||||
| `scripts/edges_full_check.py` | Skript | Prüft Graph-Integrität. |
|
||||
| `scripts/resolve_unresolved_references.py`| Skript | Löst Wikilinks nachträglich auf. |
|
||||
| `scripts/audit_vault_vs_qdrant.py` | Skript | Konsistenz-Check File vs. DB. |
|
||||
| `scripts/audit_edges_vs_expectations.py`| Skript | Prüft Kanten gegen Erwartungswert. |
|
||||
| `scripts/setup_mindnet_collections.py` | Skript | Richtet Collections initial ein. |
|
||||
| `scripts/export_markdown.py` | Skript | Exportiert Qdrant zurück zu Markdown. |
|
||||
| `scripts/wp04_smoketest.py` | Skript | E2E-Schnelltest der WP-04 Endpunkte. |
|
||||
| `scripts/health_check_mindnet.py` | Skript | System Health Check. |
|
||||
| `scripts/report_hashes.py` | Skript | Übersicht bei Mehrfach-Hashes. |
|
||||
| `scripts/make_test_vault.py` | Skript | Erzeugt minimalen Test-Vault. |
|
||||
| `scripts/ollama_tool_runner.py` | Skript | Minimaler Tool-Caller für Ollama. |
|
||||
| `services/llm_service.py`| Service | **Traffic Control.** Async Client für Ollama. Nutzt **Semaphore**, um Hintergrund-Jobs (Import) zu drosseln. |
|
||||
| `services/discovery.py`| Service | **Intelligence.** "Matrix Logic" für Link-Vorschläge (WP-11). |
|
||||
| `services/semantic_analyzer.py`| Service | **Filter.** KI-Validierung von Kanten im Hintergrund. |
|
||||
| `services/feedback_service.py`| Service | **Logging.** Schreibt Interaktions-Logs (JSONL). |
|
||||
|
||||
---
|
||||
|
||||
## 3. Core-Module im Detail (Architektur)
|
||||
### 4.4 Scripts & Tooling (Die Admin-Toolbox)
|
||||
|
||||
Hier wird erklärt, *wie* die wichtigsten Komponenten unter der Haube arbeiten.
|
||||
Der Ordner `scripts/` enthält verifizierte Werkzeuge für den Betrieb.
|
||||
|
||||
### 3.1 Der Importer (`scripts.import_markdown`)
|
||||
Dies ist das komplexeste Modul.
|
||||
* **Orchestrierung:** Es ruft `app.core.chunker` für die Textzerlegung und `app.services.semantic_analyzer` für Smart Edges auf.
|
||||
* **Idempotenz:** Der Importer kann beliebig oft laufen. Er nutzt deterministische IDs (UUIDv5) und überschreibt vorhandene Einträge konsistent.
|
||||
* **Robustheit:** In `ingestion.py` sind Mechanismen wie Change Detection (Hash-Vergleich) und Robust File I/O implementiert.
|
||||
|
||||
### 3.2 Der Hybrid Router (`app.routers.chat`)
|
||||
Hier liegt die Logik für Intent Detection (WP06) und Interview-Modus (WP07).
|
||||
* **Question Detection:** Prüft zuerst regelbasiert, ob der Input eine Frage ist (`?`, W-Wörter). Falls ja -> RAG.
|
||||
* **Keyword Match:** Prüft Keywords aus `decision_engine.yaml` und `types.yaml`.
|
||||
* **Priority:** Ruft `llm_service` mit `priority="realtime"` auf, um die Import-Warteschlange zu umgehen.
|
||||
|
||||
### 3.3 Der Retriever (`app.core.retriever`)
|
||||
Hier passiert das Scoring (WP04a).
|
||||
* **Hybrid Search:** Der Chat-Endpoint erzwingt `mode="hybrid"`.
|
||||
* **Strategic Retrieval:** In `chat.py` wird der Retriever ggf. *zweimal* aufgerufen, wenn ein Intent (z.B. `DECISION`) eine Injection (`value`) erfordert.
|
||||
|
||||
### 3.4 Das Frontend (`app.frontend.ui`)
|
||||
Eine Streamlit-App (WP10/19).
|
||||
* **Resurrection Pattern:** Das UI nutzt ein spezielles State-Management (`st.session_state`), um Eingaben bei Tab-Wechseln (Chat <-> Editor) zu erhalten. Widgets synchronisieren sich via Callbacks.
|
||||
* **Healing Parser:** Die Funktion `parse_markdown_draft` repariert defekte YAML-Frontmatter (z.B. fehlendes `---`) vom LLM automatisch.
|
||||
|
||||
### 3.5 Traffic Control (`app.services.llm_service`)
|
||||
Neu in v2.6. Stellt sicher, dass Batch-Prozesse (Import) den Live-Chat nicht ausbremsen.
|
||||
* **Methode:** `generate_raw_response(..., priority="background")` aktiviert eine Semaphore.
|
||||
* **Limit:** Konfigurierbar über `MINDNET_LLM_BACKGROUND_LIMIT` (Default: 2).
|
||||
| Skript | Status | Zweck | Wichtiges Argument |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| **`import_markdown.py`** | 🟢 Prod | **Master-Sync.** Der zentrale Importer. | `--apply`, `--purge-before-upsert` |
|
||||
| **`reset_qdrant.py`** | ⚠️ Ops | **Wipe.** Löscht Collections für Rebuilds. | `--mode wipe`, `--yes` |
|
||||
| **`export_markdown.py`** | 🟢 Backup| **Backup.** Exportiert DB-Inhalt zurück zu MD. | -- |
|
||||
| **`health_check_mindnet.py`**| 🟢 Ops | **Monitoring.** Prüft ob API/DB laufen. | (Exit Code 0/1) |
|
||||
| **`payload_dryrun.py`** | 🟢 Test | **Audit.** Simuliert Import (Schema Check). | -- |
|
||||
| **`edges_full_check.py`** | 🟢 Test | **Integrity.** Prüft Graph-Logik. | -- |
|
||||
| **`resolve_unresolved.py`**| 🟡 Maint | **Repair.** Versucht, kaputte Links zu heilen. | -- |
|
||||
|
||||
---
|
||||
|
||||
## 4. Lokales Setup (Development)
|
||||
## 5. Maintenance & "Kill List"
|
||||
|
||||
Folgende Dateien wurden im Audit v2.6 als veraltet, redundant oder "Zombie-Code" identifiziert und sollten entfernt werden.
|
||||
|
||||
| Datei | Diagnose | Empfohlene Aktion |
|
||||
| :--- | :--- | :--- |
|
||||
| `app/embed_server.py` | **Zombie.** Alter Standalone-Server. | 🗑️ Löschen |
|
||||
| `app/embeddings.py` | **Zombie.** Veraltete lokale Lib. | 🗑️ Löschen |
|
||||
| `app/core/edges.py` | **Redundant.** Ersetzt durch `derive_edges.py`. | 🗑️ Löschen |
|
||||
| `app/core/ranking.py` | **Redundant.** Logik in `retriever.py` integriert. | 🗑️ Löschen |
|
||||
| `app/core/type_registry.py` | **Redundant.** Logik in `ingestion.py` integriert. | 🗑️ Löschen |
|
||||
| `app/core/env_vars.py` | **Veraltet.** Ersetzt durch `config.py`. | 🗑️ Löschen |
|
||||
| `app/routers/qdrant_router.py`| **Deprecated.** Keine Logik, nur CRUD. | 📂 Verschieben nach `scripts/archive/` |
|
||||
|
||||
---
|
||||
|
||||
## 6. Lokales Setup (Development)
|
||||
|
||||
**Voraussetzungen:** Python 3.10+, Docker, Ollama.
|
||||
|
||||
@@ -170,16 +225,18 @@ ollama pull nomic-embed-text
|
||||
**Konfiguration (`.env`):**
|
||||
```ini
|
||||
QDRANT_URL="http://localhost:6333"
|
||||
MINDNET_OLLAMA_URL="http://localhost:11434"
|
||||
MINDNET_LLM_MODEL="phi3:mini"
|
||||
MINDNET_EMBEDDING_MODEL="nomic-embed-text"
|
||||
COLLECTION_PREFIX="mindnet_dev"
|
||||
VECTOR_DIM=768
|
||||
MINDNET_LLM_BACKGROUND_LIMIT=2
|
||||
MINDNET_API_URL="http://localhost:8002"
|
||||
MINDNET_LLM_TIMEOUT=300.0
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 5. Der Entwicklungs-Zyklus (Workflow)
|
||||
## 7. Der Entwicklungs-Zyklus (Workflow)
|
||||
|
||||
### Phase 1: Windows (Code)
|
||||
1. **Basis aktualisieren:** `git checkout main && git pull`.
|
||||
@@ -219,7 +276,7 @@ Wenn alles getestet ist:
|
||||
|
||||
---
|
||||
|
||||
## 6. Erweiterungs-Guide: "Teach-the-AI"
|
||||
## 8. Erweiterungs-Guide: "Teach-the-AI"
|
||||
|
||||
Mindnet lernt nicht durch Training (Fine-Tuning), sondern durch **Konfiguration** und **Vernetzung**.
|
||||
|
||||
@@ -227,6 +284,7 @@ Mindnet lernt nicht durch Training (Fine-Tuning), sondern durch **Konfiguration*
|
||||
1. **Physik (`config/types.yaml`):**
|
||||
```yaml
|
||||
risk:
|
||||
chunk_profile: sliding_short
|
||||
retriever_weight: 0.90 # Sehr wichtig
|
||||
edge_defaults: ["blocks"] # Automatische Kante
|
||||
detection_keywords: ["gefahr", "risiko"]
|
||||
@@ -238,21 +296,20 @@ Mindnet lernt nicht durch Training (Fine-Tuning), sondern durch **Konfiguration*
|
||||
```
|
||||
*Ergebnis:* Wenn der Intent `DECISION` erkannt wird, sucht das System nun auch aktiv nach Risiken.
|
||||
|
||||
### Workflow B: Interview-Schema anpassen (WP07)
|
||||
Wenn Mindnet neue Fragen stellen soll (z.B. "Budget" bei Projekten):
|
||||
1. **Schema (`config/types.yaml`):**
|
||||
```yaml
|
||||
project:
|
||||
schema:
|
||||
- "Titel"
|
||||
- "Ziel"
|
||||
- "Budget (Neu)"
|
||||
```
|
||||
2. **Kein Code nötig:** Der `One-Shot Extractor` (Prompt Template) liest diese Liste dynamisch.
|
||||
### Workflow B: Graph-Farben ändern
|
||||
1. Öffne `app/frontend/ui_config.py`.
|
||||
2. Bearbeite das Dictionary `GRAPH_COLORS`.
|
||||
|
||||
```python
|
||||
GRAPH_COLORS = {
|
||||
"project": "#FF4B4B",
|
||||
"risk": "#8B0000" # Neu
|
||||
}
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 7. Tests & Debugging
|
||||
## 9. Tests & Debugging
|
||||
|
||||
**Unit Tests (Pytest):**
|
||||
```bash
|
||||
@@ -280,7 +337,7 @@ python tests/test_feedback_smoke.py --url http://localhost:8002/query
|
||||
|
||||
---
|
||||
|
||||
## 8. Troubleshooting & One-Liners
|
||||
## 10. Troubleshooting & One-Liners
|
||||
|
||||
**DB komplett zurücksetzen (Vorsicht!):**
|
||||
```bash
|
||||
@@ -300,5 +357,9 @@ journalctl -u mindnet-ui-dev -f
|
||||
```
|
||||
|
||||
**"UnicodeDecodeError in .env":**
|
||||
* Ursache: Umlaute oder Sonderzeichen in der `.env`.
|
||||
* Lösung: Datei bereinigen (nur ASCII) und sicherstellen, dass UTF-8 ohne BOM genutzt wird.
|
||||
* **Ursache:** Umlaute oder Sonderzeichen in der `.env`.
|
||||
* **Lösung:** Datei bereinigen (nur ASCII) und sicherstellen, dass UTF-8 ohne BOM genutzt wird.
|
||||
|
||||
**"Read timed out" im Frontend:**
|
||||
* **Ursache:** Smart Edges brauchen länger als 60s.
|
||||
* **Lösung:** `MINDNET_API_TIMEOUT=300.0` in `.env`.
|
||||
Reference in new issue
Block a user