diff --git a/docs/05_Development/05_AI_dev_prompt_templates.md b/docs/05_Development/05_AI_dev_prompt_templates.md deleted file mode 100644 index 452e9c2..0000000 --- a/docs/05_Development/05_AI_dev_prompt_templates.md +++ /dev/null @@ -1,76 +0,0 @@ -# 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).** \ No newline at end of file diff --git a/docs/05_Development/05_developer_guide.md b/docs/05_Development/05_developer_guide.md index 1bdcc87..17ed425 100644 --- a/docs/05_Development/05_developer_guide.md +++ b/docs/05_Development/05_developer_guide.md @@ -3,7 +3,7 @@ doc_type: developer_guide audience: developer scope: workflow, testing, architecture, modules status: active -version: 2.6 +version: 2.6.1 context: "Umfassender Guide für Entwickler: Architektur, Modul-Interna (Deep Dive), Setup, Git-Workflow und Erweiterungs-Anleitungen." --- @@ -14,6 +14,7 @@ context: "Umfassender Guide für Entwickler: Architektur, Modul-Interna (Deep Di 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). --- + # Inhaltsverzeichnis - [Mindnet Developer Guide \& Workflow](#mindnet-developer-guide--workflow) - [Inhaltsverzeichnis](#inhaltsverzeichnis) @@ -35,9 +36,6 @@ Dieser Guide ist die zentrale technische Referenz für Mindnet v2.6. Er vereint - [4.4 Scripts \& Tooling (Die Admin-Toolbox)](#44-scripts--tooling-die-admin-toolbox) - [1. Script-Übersicht](#1-script-übersicht) - [2. Einsatzszenarien \& Bewertung](#2-einsatzszenarien--bewertung) - - [🟢 Essentiell für den Betrieb (Must-Have)](#-essentiell-für-den-betrieb-must-have) - - [🟡 Hilfreich für Entwicklung \& Debugging (Should-Have)](#-hilfreich-für-entwicklung--debugging-should-have) - - [🔵 Wartung \& Spezialfälle (Nice-to-Have)](#-wartung--spezialfälle-nice-to-have) - [5. Maintenance \& "Kill List"](#5-maintenance--kill-list) - [6. Lokales Setup (Development)](#6-lokales-setup-development) - [7. Der Entwicklungs-Zyklus (Workflow)](#7-der-entwicklungs-zyklus-workflow) @@ -51,6 +49,7 @@ Dieser Guide ist die zentrale technische Referenz für Mindnet v2.6. Er vereint - [10. Troubleshooting \& One-Liners](#10-troubleshooting--one-liners) --- + ## 1. Einführung & Systemüberblick ### Was ist Mindnet? @@ -123,29 +122,30 @@ graph LR Die hybride Suche für Chat & RAG. ```mermaid graph LR - Query([Query]) --> Embed(Embedding) - Embed --> Hybrid{Hybrid Search} + Query(["Query"]) --> Embed("Embedding") + Embed --> Hybrid{"Hybrid Search"} subgraph Search Components - Vec[Vector Score] - Graph[Graph/Edge Bonus] + Vec["Vector Score"] + Graph["Graph/Edge Bonus"] end Vec --> Hybrid Graph --> Hybrid - Hybrid --> Rank(Re-Ranking) - Rank --> Ctx[LLM Context] + Hybrid --> Rank("Re-Ranking") + Rank --> Ctx["LLM Context"] ``` #### C. Visualisierung (Graph) Der optimierte Pfad für das Frontend. ```mermaid graph LR - UI[Frontend UI] --> Service(GraphService) - Service -- "Direct Read" --> DB[(Qdrant
Edges Collection)] - DB --> Cyto[Cytoscape
Rendering] + UI["Frontend UI"] --> Service("GraphService") + Service -- "Direct Read" --> DB[("Qdrant
Edges Collection")] + DB --> Cyto["Cytoscape
Rendering"] ``` + --- ## 3. Physische Architektur @@ -185,16 +185,16 @@ Das Frontend ist eine Streamlit-App, die sich wie eine Single-Page-Application ( | Modul | Status | Verantwortung | | :--- | :--- | :--- | -| **`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. | +| **`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!) @@ -212,37 +212,35 @@ Das Frontend ist eine Streamlit-App, die sich wie eine Single-Page-Application ( 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. +Das Backend ist das Herzstück. Es 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** | | | -| `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). | - ---- +| Layer | Datei | Status | Verantwortung | +| :--- | :--- | :--- | :--- | +| **Entry** | `app/main.py` | 🟢 **Core** | **Entrypoint.** Initialisiert FastAPI, CORS, und bindet alle Router ein. | +| **Config** | `app/config.py` | 🟢 **Core** | **Settings.** Zentrale Konfiguration (Pydantic). Lädt Env-Vars für Qdrant, LLM und Pfade. | +| **Router** | `app/routers/chat.py` | 🟢 **API** | **Conversation API.** Haupt-Endpunkt für Chat. Entscheidet zwischen Interview- und RAG-Modus. | +| | `app/routers/ingest.py` | 🟢 **API** | **Write API.** Nimmt Markdown entgegen, steuert Ingestion und Discovery-Analyse. | +| | `app/routers/query.py` | 🟢 **API** | **Search API.** Klassischer Hybrid-Retriever Endpunkt. | +| | `app/routers/graph.py` | 🟢 **API** | **Viz API.** Liefert Knoten/Kanten für Frontend-Graphen (Cytoscape). | +| | `app/routers/tools.py` | 🟢 **API** | **Agent Specs.** Liefert JSON-Schemas für die Integration in externe Agenten (Ollama/MCP). | +| **Engine** | `app/core/ingestion.py` | ⚙️ **Core** | **Pipeline Controller.** Koordiniert Parsing, Hashing (Change-Detection) und DB-Upserts. | +| | `app/core/retriever.py` | ⚙️ **Core** | **Search Engine.** Berechnet Scores (Vektor + Graph + Centrality) und baut Erklärungen. | +| | `app/core/chunker.py` | ⚙️ **Core** | **Segmentation.** Zerlegt Text intelligent. Orchestriert `SemanticAnalyzer` für Smart Edges. | +| | `app/core/parser.py` | ⚙️ **Core** | **I/O.** Liest Markdown robust (Encoding-Fallback), trennt Frontmatter/Body. | +| | `app/core/derive_edges.py`| ⚙️ **Core** | **Link Extractor.** Findet Wikilinks, Callouts und Typed Relations im Text. | +| | `app/core/note_payload.py`| ⚙️ **Core** | **Builder.** Erzeugt JSON für `mindnet_notes`. Vererbt Configs (Frontmatter > Type > Default). | +| | `app/core/qdrant_points.py`| ⚙️ **Core** | **Object Mapper.** Wandelt Payloads in Qdrant `PointStruct`s um. Handhabt UUIDs. | +| **Services** | `app/services/llm_service.py`| 🧠 **AI** | **AI Client.** Async Client für Ollama. Verwaltet Concurrency (Semaphore). | +| | `app/services/embeddings_client.py`| 🧠 **AI** | **Vector Client.** Unified Client für Embeddings (Ollama/Nomic). Ersetzt lokale Modelle. | +| | `app/services/discovery.py`| 🧠 **AI** | **Intelligence.** "Matrix Logic" für Link-Vorschläge (WP-11). | +| | `app/services/semantic_analyzer.py`| 🧠 **AI** | **Filter.** KI-Validierung von Kanten im Hintergrund (Background Priority). | ### 4.4 Scripts & Tooling (Die Admin-Toolbox) Der Ordner `scripts/` enthält verifizierte Werkzeuge für den Betrieb. + #### 1. Script-Übersicht | Skript | Status | Zweck | Argumente & Parameter | Beispielaufruf | @@ -255,22 +253,21 @@ Der Ordner `scripts/` enthält verifizierte Werkzeuge für den Betrieb. | **`resolve_unresolved_references.py`** | 🔵 **Maint** | **Link-Healer.** Repariert "tote" Links in der DB nachträglich und erzeugt Backlinks. | `--prefix TEXT`
`--limit INT`
`--apply` (Schreibt Änderungen) | `python3 -m scripts.resolve_unresolved_references --apply` | | **`export_markdown.py`** | ⚪ **Utility** | **Reverse ETL.** Exportiert den Datenbank-Inhalt zurück in Markdown-Dateien (Backup/Recovery). | `--out PATH` (Ziel)
`--note-id ID`
`--include-edges {yaml,footer}`
`--flatten-paths` | `python3 -m scripts.export_markdown --out ./backup` | ---- - #### 2. Einsatzszenarien & Bewertung -### 🟢 Essentiell für den Betrieb (Must-Have) -* **`import_markdown.py`**: Das Arbeitspferd. Ohne dieses Skript kommen keine Daten ins System (außer man nutzt die API einzeln). Es ist für Cronjobs optimiert. -* **`reset_qdrant.py`**: Zwingend notwendig für CI/CD-Pipelines oder saubere Neustarts bei Schema-Änderungen. -* **`health_check_mindnet.py`**: Ideal für Docker-Healthchecks oder Monitoring-Tools (Nagios, Uptime Kuma), da es keine Python-Abhängigkeiten zur App hat. +* **🟢 Essentiell für den Betrieb (Must-Have):** + * **`import_markdown.py`**: Das Arbeitspferd. Ohne dieses Skript kommen keine Daten ins System. + * **`reset_qdrant.py`**: Zwingend notwendig für CI/CD-Pipelines. + * **`health_check_mindnet.py`**: Ideal für Docker-Healthchecks. -### 🟡 Hilfreich für Entwicklung & Debugging (Should-Have) -* **`payload_dryrun.py`**: Sehr wertvoll, wenn man an der `config/types.yaml` oder dem `chunker.py` arbeitet. Man sieht sofort, wie das JSON aussieht, ohne die Datenbank "zuzumüllen". -* **`edges_full_check.py`**: Wichtiges Diagnose-Tool, wenn der Graph im Frontend "komisch" aussieht oder Kanten fehlen. +* **🟡 Hilfreich für Entwicklung & Debugging (Should-Have):** + * **`payload_dryrun.py`**: Wertvoll, wenn man an der `config/types.yaml` arbeitet. + * **`edges_full_check.py`**: Wichtiges Diagnose-Tool für den Graphen. + +* **🔵 Wartung & Spezialfälle (Nice-to-Have):** + * **`resolve_unresolved_references.py`**: Sinnvoll in einem "Knowledge Garden", wo oft Links auf noch nicht existierende Notizen gesetzt werden ("Red Links"). Dieses Skript "heilt" den Graphen nachträglich. + * **`export_markdown.py`**: Ein Notfall-Tool. Da Mindnet nach dem Prinzip "Filesystem First" arbeitet, ist ein Export aus der DB selten nötig, kann aber bei versehentlichem Löschen von Dateien lebensrettend sein. -### 🔵 Wartung & Spezialfälle (Nice-to-Have) -* **`resolve_unresolved_references.py`**: Sinnvoll in einem "Knowledge Garden", wo oft Links auf noch nicht existierende Notizen gesetzt werden ("Red Links"). Dieses Skript "heilt" den Graphen nachträglich. -* **`export_markdown.py`**: Ein Notfall-Tool. Da Mindnet nach dem Prinzip "Filesystem First" arbeitet, ist ein Export aus der DB selten nötig, kann aber bei versehentlichem Löschen von Dateien lebensrettend sein. --- ## 5. Maintenance & "Kill List" @@ -280,12 +277,14 @@ Folgende Dateien wurden im Audit v2.6 als veraltet, redundant oder "Zombie-Code" | Datei | Diagnose | Empfohlene Aktion | | :--- | :--- | :--- | | `app/embed_server.py` | **Zombie.** Alter Standalone-Server. | 🗑️ Löschen | -| `app/embeddings.py` | **Zombie.** Veraltete lokale Lib. | 🗑️ Löschen | +| `app/embeddings.py` | **Zombie.** Veraltete lokale Lib. **(Achtung: Erst Importe in `main.py` entfernen!)** | 🗑️ Löschen | +| `app/routers/embed_router.py` | **Zombie.** Nutzt `embeddings.py`. | 🗑️ Löschen | +| `app/routers/qdrant_router.py`| **Deprecated.** Keine Logik, nur CRUD. | 🗑️ 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/` | +| `app/services/llm_ollama.py` | **Veraltet.** Ersetzt durch `llm_service.py`. | 🗑️ Löschen | --- @@ -432,6 +431,12 @@ python tests/test_feedback_smoke.py --url http://localhost:8002/query python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet_dev" --yes ``` +**Graphen reparieren (Red Links auflösen):** +Nutze dies, wenn Kanten im Graphen ins Leere zeigen (weil die Notiz beim Import noch nicht da war). +```bash +python3 -m scripts.resolve_unresolved_references --apply +``` + **Einen einzelnen File inspizieren (Parser-Sicht):** ```bash python3 tests/inspect_one_note.py --file ./vault/MeinFile.md