This commit is contained in:
parent
c454fc40bb
commit
ec759dd1dc
76
docs/05_Development/05_AI_dev_prompt_templates.md
Normal file
76
docs/05_Development/05_AI_dev_prompt_templates.md
Normal file
|
|
@ -0,0 +1,76 @@
|
|||
# SYSTEM-ANWEISUNG: SICHERS MARKDOWN-RENDERING
|
||||
|
||||
Du agierst als technischer Dokumentations-Assistent. Deine Aufgabe ist das Erstellen von Markdown-Dateien (`.md`), die oft selbst Code-Blöcke (Python, JSON, YAML, Bash) enthalten.
|
||||
|
||||
**DAS PROBLEM:**
|
||||
Wenn du eine Markdown-Datei generierst, die Code-Blöcke (```) enthält, und diese Ausgabe selbst in einen Code-Block packst, interpretiert das Chat-Interface das erste innere ` ``` ` oft fälschlicherweise als das Ende der Ausgabe. Das "zerreißt" die Datei und macht das Kopieren unmöglich.
|
||||
|
||||
**DIE REGEL (STRIKT BEFOLGEN):**
|
||||
Um eine ununterbrochene Darstellung zu garantieren, musst du zwingend eine der folgenden Kapselungs-Methoden anwenden:
|
||||
|
||||
### Methode A: Die 4-Backtick-Methode (Bevorzugt)
|
||||
Umschließe den **gesamten** Datei-Inhalt mit **4 Backticks** statt 3.
|
||||
Dies erlaubt dir, innerhalb der Datei normale 3 Backticks zu verwenden.
|
||||
|
||||
Beispiel für deinen Output:
|
||||
````markdown
|
||||
---
|
||||
title: Beispiel
|
||||
---
|
||||
Hier ist Python Code:
|
||||
```python
|
||||
print("Hello")
|
||||
### Methode B: Die 4-Space-Einrückung (Alternative)
|
||||
Wenn du außen 3 Backticks verwendest, darfst du im Inneren **KEINE** Backticks verwenden.
|
||||
Stattdessen müssen alle inneren Code-Beispiele mit **4 Leerzeichen (Spaces)** eingerückt werden.
|
||||
|
||||
Beispiel für deinen Output:
|
||||
```markdown
|
||||
Hier ist Python Code:
|
||||
|
||||
print("Hello")
|
||||
```
|
||||
|
||||
**ZUSAMMENFASSUNG:**
|
||||
Generiere niemals verschachtelte 3-Backtick-Blöcke innerhalb von 3-Backtick-Blöcken. Nutze immer **4 Backticks** für den äußersten Container.
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
Du agierst als **Technical Documentation Lead**.
|
||||
|
||||
**Kontext:**
|
||||
Wir haben soeben das Workpackage (WP) abgeschlossen. Der Code ist implementiert, getestet und die Änderungen sind im Chat-Verlauf dokumentiert.
|
||||
Jetzt müssen wir die Systemdokumentation (Mindnet v2.6 Modular Docs) aktualisieren, um den neuen Stand widerzuspiegeln.
|
||||
|
||||
**Deine Aufgabe - Phase 1: Identifikation**
|
||||
Analysiere die durchgeführten Änderungen dieses Workpackages.
|
||||
Nutze die beiliegende `00_documentation_map.md`, um zu identifizieren, welche Dokumentations-Module von diesen Änderungen betroffen sind.
|
||||
|
||||
**Beachte die Mapping-Logik:**
|
||||
* Haben wir neue Features/Konzepte eingeführt? -> `00_glossary.md`, `02_Concepts/*`
|
||||
* Haben wir die Datenbank/Payloads geändert? -> `03_tech_data_model.md`
|
||||
* Hat sich der Import/Algorithmus geändert? -> `03_tech_ingestion_pipeline.md`, `03_tech_retrieval_scoring.md`
|
||||
* Muss der Admin etwas Neues konfigurieren? -> `03_tech_configuration.md`, `04_admin_operations.md`
|
||||
* Ändert sich etwas für den Nutzer/Autor? -> `01_User_Manual/*`
|
||||
|
||||
**Output für Phase 1:**
|
||||
Erstelle eine **Liste der betroffenen Dateien** mit einer kurzen Begründung pro Datei (z.B. "Muss neuen Parameter X aufnehmen").
|
||||
Fordere mich dann explizit auf, dir diese spezifischen Dateien hochzuladen.
|
||||
|
||||
---
|
||||
|
||||
**Deine Aufgabe - Phase 2: Sequenzielle Bearbeitung (Warte auf Dateien)**
|
||||
Sobald ich die Dateien hochgeladen habe, aktualisieren wir sie **Schritt für Schritt**.
|
||||
1. Nimm dir **eine** Datei aus der Liste vor.
|
||||
2. Schreibe den kompletten, aktualisierten Inhalt dieser Datei als Markdown-Codeblock.
|
||||
* *Wichtig:* Halte dich strikt an den bestehenden Stil (Frontmatter, JSON-Beispiele, Warnhinweise).
|
||||
* *Wichtig:* Füge Änderungen nahtlos ein, lösche nichts Relevantes.
|
||||
3. **Warte** nach der Ausgabe der Datei auf mein "OK" oder "Weiter", bevor du die nächste Datei bearbeitest.
|
||||
|
||||
**Sonderaufgabe Roadmap:**
|
||||
Aktualisiere am Ende immer die `06_active_roadmap.md`:
|
||||
* Setze den Status des aktuellen WPs auf "Fertig/Live".
|
||||
* Verschiebe Details in die Historie-Tabelle (falls relevant).
|
||||
|
||||
**Bist du bereit für die Analyse? (Ich habe Map und Roadmap hochgeladen).**
|
||||
|
|
@ -4,7 +4,7 @@ audience: developer
|
|||
scope: workflow, testing, architecture, modules
|
||||
status: active
|
||||
version: 2.6
|
||||
context: "Umfassender Guide für Entwickler: Architektur, Modul-Interna, Setup, Git-Workflow und Erweiterungs-Anleitungen."
|
||||
context: "Umfassender Guide für Entwickler: Architektur, Modul-Interna (Deep Dive), Setup, Git-Workflow und Erweiterungs-Anleitungen."
|
||||
---
|
||||
|
||||
# Mindnet Developer Guide & Workflow
|
||||
|
|
@ -23,85 +23,135 @@ Mindnet läuft in einer verteilten Umgebung (Post-WP15 Setup).
|
|||
* **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". Speichert den Code und verwaltet Versionen.
|
||||
* **Gitea:** Der "Safe" (Raspberry Pi). Speichert den Code und verwaltet Versionen.
|
||||
|
||||
---
|
||||
|
||||
## 2. Projektstruktur & Core-Module
|
||||
|
||||
Der Code ist modular in `app` (Logik), `scripts` (CLI) und `config` (Steuerung) getrennt.
|
||||
## 2. Projektstruktur & Referenz
|
||||
|
||||
### 2.1 Verzeichnisbaum
|
||||
|
||||
```text
|
||||
mindnet/
|
||||
├── app/
|
||||
│ ├── core/ # Kernlogik
|
||||
│ │ ├── ingestion.py # Async Ingestion Service mit Change Detection
|
||||
│ │ ├── chunker.py # Smart Chunker Orchestrator
|
||||
│ │ ├── derive_edges.py # Edge-Erzeugung (WP03 Logik)
|
||||
│ │ ├── retriever.py # Scoring & Hybrid Search
|
||||
│ │ └── qdrant.py # DB-Verbindung
|
||||
│ ├── core/ # Ingestion, Chunker, Qdrant Wrapper
|
||||
│ ├── routers/ # FastAPI Endpoints
|
||||
│ │ ├── query.py # Suche
|
||||
│ │ ├── chat.py # Hybrid Router v5 & Interview Logic
|
||||
│ │ └── feedback.py # Feedback (WP04c)
|
||||
│ ├── services/ # Interne & Externe Dienste
|
||||
│ │ ├── llm_service.py # Ollama Client mit Traffic Control
|
||||
│ │ ├── semantic_analyzer.py# LLM-Filter für Edges (WP15)
|
||||
│ │ ├── embeddings_client.py# Async Embeddings (HTTPX)
|
||||
│ │ └── discovery.py # Intelligence Logic (WP11)
|
||||
│ ├── 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)
|
||||
│ ├── services/ # Ollama Client, Traffic Control
|
||||
│ ├── 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/ # Dein lokaler Markdown-Content
|
||||
└── vault/ # Lokaler Test-Content
|
||||
```
|
||||
|
||||
### 2.2 Modul-Details (Wie es funktioniert)
|
||||
### 2.2 Vollständige Datei-Referenz (Auto-Scan)
|
||||
|
||||
**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.
|
||||
Eine Übersicht aller Skripte und Module im System.
|
||||
|
||||
**Der Importer (`scripts.import_markdown`)**
|
||||
* Das komplexeste Modul.
|
||||
* Nutzt `app.core.chunker` und `app.services.semantic_analyzer` (Smart Edges).
|
||||
* **Idempotenz:** Nutzt deterministische UUIDv5 IDs. Kann beliebig oft laufen.
|
||||
* **Robustheit:** Implementiert Change Detection (Hash) und Retry-Logik.
|
||||
|
||||
**Der Hybrid Router (`app.routers.chat`)**
|
||||
* Hier liegt die Logik für Intent Detection (WP06).
|
||||
* **Question Detection:** Prüft auf `?` und W-Wörter.
|
||||
* **Priority:** Ruft `llm_service` mit `priority="realtime"` auf (umgeht Import-Warteschlange).
|
||||
|
||||
**Der Retriever (`app.core.retriever`)**
|
||||
* Implementiert die Scoring-Formel (`Semantik + Graph + Typ`).
|
||||
* **Hybrid Search:** Lädt dynamisch den Subgraphen (`graph_adapter.expand`).
|
||||
|
||||
**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.
|
||||
| Datei/Pfad | Typ | Beschreibung |
|
||||
| :--- | :--- | :--- |
|
||||
| **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. |
|
||||
| **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. |
|
||||
|
||||
---
|
||||
|
||||
## 3. Lokales Setup (Development)
|
||||
## 3. Core-Module im Detail (Architektur)
|
||||
|
||||
Hier wird erklärt, *wie* die wichtigsten Komponenten unter der Haube arbeiten.
|
||||
|
||||
### 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).
|
||||
|
||||
---
|
||||
|
||||
## 4. Lokales Setup (Development)
|
||||
|
||||
**Voraussetzungen:** Python 3.10+, Docker, Ollama.
|
||||
|
||||
**Installation:**
|
||||
|
||||
```bash
|
||||
# 1. Repo & Venv
|
||||
git clone <repo> mindnet
|
||||
|
|
@ -109,7 +159,7 @@ cd mindnet
|
|||
python3 -m venv .venv
|
||||
source .venv/bin/activate
|
||||
|
||||
# 2. Dependencies (inkl. st-cytoscape)
|
||||
# 2. Dependencies
|
||||
pip install -r requirements.txt
|
||||
|
||||
# 3. Ollama (Nomic ist Pflicht!)
|
||||
|
|
@ -117,8 +167,7 @@ ollama pull phi3:mini
|
|||
ollama pull nomic-embed-text
|
||||
```
|
||||
|
||||
**Konfiguration (.env):**
|
||||
|
||||
**Konfiguration (`.env`):**
|
||||
```ini
|
||||
QDRANT_URL="http://localhost:6333"
|
||||
COLLECTION_PREFIX="mindnet_dev"
|
||||
|
|
@ -130,63 +179,68 @@ MINDNET_LLM_TIMEOUT=300.0
|
|||
|
||||
---
|
||||
|
||||
## 4. Der Entwicklungs-Zyklus
|
||||
## 5. Der Entwicklungs-Zyklus (Workflow)
|
||||
|
||||
### Phase 1: Windows (Code)
|
||||
1. **Basis holen:** `git checkout main && git pull`.
|
||||
2. **Branch:** `git checkout -b feature/mein-feature`.
|
||||
3. **Code & Push:** `git push origin feature/mein-feature`.
|
||||
1. **Basis aktualisieren:** `git checkout main && git pull`.
|
||||
2. **Branch erstellen:** `git checkout -b feature/mein-feature`.
|
||||
3. **Coden & Committen.**
|
||||
4. **Push:** `git push origin feature/mein-feature`.
|
||||
|
||||
### Phase 2: Beelink (Test)
|
||||
1. **SSH:** `ssh user@beelink`.
|
||||
### Phase 2: Beelink (Test / Dev)
|
||||
Hier prüfst du, ob dein Code auf Linux läuft.
|
||||
1. **Einloggen:** `ssh user@beelink`.
|
||||
2. **Ordner:** `cd ~/mindnet_dev`.
|
||||
3. **Checkout:** `git fetch && git checkout feature/mein-feature && git pull`.
|
||||
3. **Code holen:** `git fetch && git checkout feature/mein-feature && git pull`.
|
||||
4. **Dependencies:** `pip install -r requirements.txt`.
|
||||
5. **Restart:** `sudo systemctl restart mindnet-dev`.
|
||||
6. **Validierung (Smoke Tests):**
|
||||
* **Last-Test:** Starte `python3 -m scripts.import_markdown ...` und chatte gleichzeitig im UI (Port 8502).
|
||||
* **Last-Test:** Starte `python3 -m scripts.import_markdown ...` im Terminal und chatte gleichzeitig im UI (Port 8502).
|
||||
* **API Check:** `curl -X POST "http://localhost:8002/ingest/analyze" ...`
|
||||
|
||||
### Phase 3: Release & Deploy
|
||||
### Phase 3: Release & Deployment (Prod)
|
||||
Wenn alles getestet ist:
|
||||
1. **Gitea:** Pull Request erstellen und mergen.
|
||||
2. **Beelink (Prod):**
|
||||
2. **Deploy auf Prod (Beelink):**
|
||||
```bash
|
||||
cd ~/mindnet
|
||||
git pull origin main
|
||||
|
||||
# Sicherstellen, dass Prod-Dependencies aktuell sind
|
||||
source .venv/bin/activate
|
||||
pip install -r requirements.txt
|
||||
ollama pull nomic-embed-text # Falls neue Modelle nötig sind
|
||||
|
||||
# Restart
|
||||
sudo systemctl restart mindnet-prod
|
||||
sudo systemctl restart mindnet-ui-prod
|
||||
```
|
||||
3. **Cleanup:** Branch löschen.
|
||||
3. **Cleanup:** Branch löschen (lokal und remote).
|
||||
|
||||
---
|
||||
|
||||
## 5. Erweiterungs-Guide: "Teach-the-AI"
|
||||
## 6. Erweiterungs-Guide: "Teach-the-AI"
|
||||
|
||||
Mindnet lernt durch Konfiguration, nicht durch Training.
|
||||
Mindnet lernt nicht durch Training (Fine-Tuning), sondern durch **Konfiguration** und **Vernetzung**.
|
||||
|
||||
### Workflow A: Neuen Typ implementieren (z. B. `type: risk`)
|
||||
1. **Physik (`types.yaml`):**
|
||||
1. **Physik (`config/types.yaml`):**
|
||||
```yaml
|
||||
risk:
|
||||
retriever_weight: 0.90
|
||||
edge_defaults: ["blocks"]
|
||||
retriever_weight: 0.90 # Sehr wichtig
|
||||
edge_defaults: ["blocks"] # Automatische Kante
|
||||
detection_keywords: ["gefahr", "risiko"]
|
||||
```
|
||||
2. **Strategie (`decision_engine.yaml`):**
|
||||
2. **Strategie (`config/decision_engine.yaml`):**
|
||||
```yaml
|
||||
DECISION:
|
||||
inject_types: ["value", "risk"] # Füge 'risk' hinzu
|
||||
```
|
||||
3. **Visualisierung (`ui_config.py`):**
|
||||
Füge dem `GRAPH_COLORS` Dictionary einen Eintrag hinzu:
|
||||
```python
|
||||
"risk": "#ff6b6b"
|
||||
inject_types: ["value", "risk"] # <--- "risk" hinzufügen
|
||||
```
|
||||
*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 (`types.yaml`):**
|
||||
1. **Schema (`config/types.yaml`):**
|
||||
```yaml
|
||||
project:
|
||||
schema:
|
||||
|
|
@ -194,21 +248,19 @@ Wenn Mindnet neue Fragen stellen soll (z.B. "Budget" bei Projekten):
|
|||
- "Ziel"
|
||||
- "Budget (Neu)"
|
||||
```
|
||||
2. **Kein Code nötig:** Der `One-Shot Extractor` liest dies dynamisch.
|
||||
2. **Kein Code nötig:** Der `One-Shot Extractor` (Prompt Template) liest diese Liste dynamisch.
|
||||
|
||||
---
|
||||
|
||||
## 6. Tests & Debugging
|
||||
|
||||
**Unit Tests:**
|
||||
## 7. Tests & Debugging
|
||||
|
||||
**Unit Tests (Pytest):**
|
||||
```bash
|
||||
pytest tests/test_retriever_basic.py
|
||||
pytest tests/test_chunking.py
|
||||
```
|
||||
|
||||
**Pipeline Tests:**
|
||||
|
||||
**Pipeline Tests (Integration):**
|
||||
```bash
|
||||
# JSON-Schema prüfen
|
||||
python3 -m scripts.payload_dryrun --vault ./test_vault
|
||||
|
|
@ -218,7 +270,6 @@ 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?"
|
||||
|
|
@ -229,27 +280,25 @@ python tests/test_feedback_smoke.py --url http://localhost:8002/query
|
|||
|
||||
---
|
||||
|
||||
## 7. Troubleshooting & One-Liners
|
||||
## 8. Troubleshooting & One-Liners
|
||||
|
||||
**DB komplett zurücksetzen (Vorsicht!):**
|
||||
|
||||
```bash
|
||||
# --yes überspringt die Bestätigung
|
||||
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: Backend braucht für Smart Edges länger als 60s.
|
||||
* Lösung: `MINDNET_API_TIMEOUT=300.0` in `.env` setzen.
|
||||
**"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.
|
||||
Loading…
Reference in New Issue
Block a user