diff --git a/docs/appendix.md b/docs/appendix.md index 0f0fc7e..e437a88 100644 --- a/docs/appendix.md +++ b/docs/appendix.md @@ -10,23 +10,27 @@ ## Anhang A: Typ-Registry Referenz (Default-Werte) -Diese Tabelle zeigt die Standard-Konfiguration der `types.yaml` (Stand v2.6). +Diese Tabelle zeigt die Standard-Konfiguration der `types.yaml` (Stand v2.6 / Config v1.6). | Typ (`type`) | Chunk Profile | Retriever Weight | Smart Edges? | Beschreibung | | :--- | :--- | :--- | :--- | :--- | -| **concept** | `medium` | 0.60 | Nein | Abstrakte Begriffe, Theorien. | -| **project** | `long` | 0.97 | Ja | Aktive Vorhaben. Hohe Priorität. | -| **decision** | `long` | 1.00 | Ja | Entscheidungen (ADRs). Höchste Prio. | +| **concept** | `sliding_smart_edges` | 0.60 | **Ja** | Abstrakte Begriffe, Theorien. | +| **project** | `sliding_smart_edges` | 0.97 | **Ja** | Aktive Vorhaben. Hohe Priorität. | +| **decision** | `structured_smart_edges` | 1.00 | **Ja** | Entscheidungen (ADRs). Höchste Prio. | | **experience** | `sliding_smart_edges` | 0.90 | **Ja** | Persönliche Learnings. Intensiv analysiert. | -| **journal** | `short` | 0.80 | Nein | Zeitgebundene Logs. Fein granular. | -| **person** | `short` | 0.50 | Nein | Personen-Profile. | -| **source** | `long` | 0.50 | Nein | Externe Quellen (Bücher, PDFs). | -| **event** | `short` | 0.60 | Nein | Meetings, Konferenzen. | -| **value** | `medium` | 1.00 | Ja | Persönliche Werte/Prinzipien. | -| **goal** | `medium` | 0.95 | Ja | Strategische Ziele. | -| **belief** | `medium` | 0.90 | Ja | Glaubenssätze. | -| **risk** | `short` | 0.90 | Ja | **NEU:** Risiken & Gefahren. | -| **default** | `medium` | 1.00 | Nein | Fallback, wenn Typ unbekannt. | +| **journal** | `sliding_standard` | 0.80 | Nein | Zeitgebundene Logs. Performance-optimiert. | +| **person** | `sliding_standard` | 0.50 | Nein | Personen-Profile. | +| **source** | `sliding_standard` | 0.50 | Nein | Externe Quellen (Bücher, PDFs). | +| **event** | `sliding_standard` | 0.60 | Nein | Meetings, Konferenzen. | +| **value** | `structured_smart_edges` | 1.00 | **Ja** | Persönliche Werte/Prinzipien. | +| **principle** | `structured_smart_edges` | 1.00 | **Ja** | Handlungsleitlinien. | +| **profile** | `structured_smart_edges` | 0.80 | **Ja** | Eigene Identitäts-Beschreibungen. | +| **goal** | `sliding_standard` | 0.95 | Nein | Strategische Ziele. | +| **belief** | `sliding_short` | 0.90 | Nein | Glaubenssätze. | +| **risk** | `sliding_short` | 0.90 | Nein | Risiken & Gefahren. | +| **task** | `sliding_short` | 0.70 | Nein | Aufgaben. | +| **glossary** | `sliding_short` | 0.50 | Nein | Begriffsdefinitionen. | +| **default** | `sliding_standard` | 1.00 | Nein | Fallback, wenn Typ unbekannt. | --- @@ -62,7 +66,7 @@ Diese sind die Felder, die effektiv in Qdrant gespeichert werden. "title": "string (text)", // Titel aus Frontmatter "type": "string (keyword)", // Typ (z.B. 'project') "retriever_weight": "float", // Numerische Wichtigkeit (0.0-1.0) - "chunk_profile": "string", // Genutztes Profil (z.B. 'long') + "chunk_profile": "string", // Genutztes Profil (z.B. 'sliding_smart_edges') "edge_defaults": ["string"], // Liste der aktiven Default-Kanten "tags": ["string"], // Liste von Tags "created": "string (iso-date)", // Erstellungsdatum diff --git a/docs/developer_guide.md b/docs/developer_guide.md index ec70910..f593d74 100644 --- a/docs/developer_guide.md +++ b/docs/developer_guide.md @@ -180,14 +180,15 @@ Eine Streamlit-App (WP10). ### 3.5 Embedding Service (`app.services.embeddings_client`) **Neu in v2.4:** -* Nutzt `httpx.AsyncClient` für non-blocking Calls an Ollama. +* Nutzt `httpx.AsyncClient` für non-blocking Calls an Ollama (Primary Mode). +* Besitzt einen **Fallback** auf `requests` (Synchron), falls Legacy-Skripte ihn nutzen. * Unterstützt dediziertes Embedding-Modell (`nomic-embed-text`) getrennt vom Chat-Modell. ### 3.6 Traffic Control (`app.services.llm_service`) -**Neu in v2.6:** +**Neu in v2.6 (Version 2.8.0):** * Stellt sicher, dass Batch-Prozesse (Import) den Live-Chat nicht ausbremsen. -* **Methode:** `generate_raw_response(..., priority="background")` aktiviert eine Semaphore (Limit default 2). -* **Config:** `MINDNET_LLM_BACKGROUND_LIMIT` in `.env`. +* **Methode:** `generate_raw_response(..., priority="background")` aktiviert eine Semaphore. +* **Limit:** Konfigurierbar über `MINDNET_LLM_BACKGROUND_LIMIT` (Default: 2) in der `.env`. --- @@ -240,10 +241,10 @@ Mindnet lernt nicht durch Training (Fine-Tuning), sondern durch **Konfiguration* Definiere die "Physik" des Typs (Import-Regeln und Basis-Wichtigkeit). risk: - chunk_profile: short # Risiken sind oft kurze Statements - retriever_weight: 0.90 # Sehr wichtig, fast so hoch wie Decisions - edge_defaults: ["blocks"] # Automatische Kante zu verlinkten Projekten - detection_keywords: ["risiko", "gefahr"] # Für Router + chunk_profile: sliding_short # Risiken sind oft kurze Statements + retriever_weight: 0.90 # Sehr wichtig + edge_defaults: ["blocks"] # Automatische Kante zu verlinkten Projekten + detection_keywords: ["gefahr", "risiko"] **2. Strategie-Ebene (`config/decision_engine.yaml`)** Damit dieser Typ aktiv geladen wird, musst du ihn einer Strategie zuordnen. @@ -272,7 +273,7 @@ Konfiguriere `edge_weights`, wenn Kausalität wichtiger ist als Ähnlichkeit. Wenn Mindnet neue Fragen stellen soll: **1. Schema erweitern (`config/types.yaml`)** -Füge das Feld in die Liste ein. +Füge das Feld in die Liste ein (Neu: Schemas liegen jetzt hier). project: schema: @@ -281,7 +282,7 @@ Füge das Feld in die Liste ein. - "Budget (Neu)" **2. Keine Code-Änderung nötig** -Der `One-Shot Extractor` liest diese Liste dynamisch. +Der `One-Shot Extractor` (Prompt Template) liest diese Liste dynamisch. ### Fazit * **Vault:** Liefert das Wissen. diff --git a/docs/mindnet_technical_architecture.md b/docs/mindnet_technical_architecture.md index 2a35743..893ef5f 100644 --- a/docs/mindnet_technical_architecture.md +++ b/docs/mindnet_technical_architecture.md @@ -1,17 +1,17 @@ -# Mindnet v2.4 – Technische Architektur +# Mindnet v2.6 – Technische Architektur **Datei:** `docs/mindnet_technical_architecture_v2.6.md` **Stand:** 2025-12-12 **Status:** **FINAL** (Integrierter Stand WP01–WP15: Smart Edges & Traffic Control) -**Quellen:** `Programmplan_V2.2.md`, `Handbuch.md`, `chunking_strategy.md`, `wp04_retriever_scoring.md`. +**Quellen:** `Programmplan_V2.6.md`, `Handbuch.md`, `chunking_strategy.md`, `wp04_retriever_scoring.md`. > **Ziel dieses Dokuments:** -> Vollständige Beschreibung der technischen Architektur inkl. Graph-Datenbank, Retrieval-Logik, der **RAG-Komponenten (Decision Engine & Hybrid Router)**, des **Interview-Modus** und dem **Frontend (Streamlit)**. +> Vollständige Beschreibung der technischen Architektur inkl. Graph-Datenbank, Retrieval-Logik, der **RAG-Komponenten (Decision Engine & Hybrid Router)**, des **Traffic Control Systems** und dem **Frontend (Streamlit)**. ---
📖 Inhaltsverzeichnis (Klicken zum Öffnen) -- [Mindnet v2.4 – Technische Architektur](#mindnet-v24--technische-architektur) +- [Mindnet v2.6 – Technische Architektur](#mindnet-v26--technische-architektur) - [](#) - [1. Systemüberblick](#1-systemüberblick) - [1.1 Architektur-Zielbild](#11-architektur-zielbild) @@ -63,12 +63,12 @@ Mindnet ist ein **lokales RAG-System (Retrieval Augmented Generation)** mit Web-Interface. 1. **Source:** Markdown-Notizen in einem Vault (Obsidian-kompatibel). 2. **Pipeline:** Ein Python-Importer transformiert diese in **Notes**, **Chunks** und **Edges**. - * **Neu in v2.6:** Intelligente Kanten-Zuweisung durch lokale LLMs (Smart Edges). + * **Neu in v2.6:** Intelligente Kanten-Zuweisung durch lokale LLMs (**Smart Edge Allocation**). 3. **Storage:** * **Qdrant:** Vektor-Datenbank für Graph und Semantik (Collections: notes, chunks, edges). * **Local Files (JSONL):** Append-Only Logs für Feedback und Search-History (Data Flywheel). 4. **Backend:** Eine FastAPI-Anwendung stellt Endpunkte für **Semantische** und **Hybride Suche** sowie **Feedback** bereit. - * **Update v2.6:** Der Core arbeitet nun vollständig **asynchron (AsyncIO)** mit **Traffic Control** (Semaphore), um Blockaden bei parallelem Import und Chat zu vermeiden. + * **Update v2.6:** Der Core arbeitet nun vollständig **asynchron (AsyncIO)** mit **Traffic Control** (Semaphore zur Lastverteilung). 5. **Frontend:** Streamlit-App (`ui.py`) für Interaktion und Visualisierung inkl. **Draft Editor**, **Active Intelligence** und **Healing Parser**. 6. **Inference:** Lokales LLM (Ollama: Phi-3 Mini) für RAG-Chat und Antwortgenerierung. Embedding via `nomic-embed-text`. @@ -99,7 +99,7 @@ Das System arbeitet **deterministisch** (stabile IDs) und ist **konfigurationsge │ │ ├── feedback.py # Feedback-Endpunkt (WP04c) │ │ └── ... │ ├── services/ - │ │ ├── llm_service.py # Ollama Chat Client mit Traffic Control + │ │ ├── llm_service.py # Ollama Chat Client mit Traffic Control (v2.8.0) │ │ ├── semantic_analyzer.py# NEU: LLM-Filter für Edges (WP15) │ │ ├── embeddings_client.py# NEU: Async Embeddings (HTTPX) │ │ ├── feedback_service.py # Logging (JSONL Writer) @@ -147,7 +147,7 @@ Repräsentiert die Metadaten einer Datei. ### 2.2 Chunks Collection (`_chunks`) Die atomaren Sucheinheiten. * **Zweck:** Vektorsuche (Embeddings), Granulares Ergebnis. -* **Update v2.3.10:** Vektor-Dimension ist jetzt **768** (für `nomic-embed-text`). +* **Update v2.4:** Vektor-Dimension ist jetzt **768** (für `nomic-embed-text`). * **Schema (Payload):** | Feld | Datentyp | Beschreibung | @@ -178,7 +178,7 @@ Gerichtete Kanten. Massiv erweitert in WP03 für Provenienz-Tracking. | `scope` | Keyword | Geltungsbereich. | Immer `"chunk"` (v2.2). | | `rule_id` | Keyword | Herkunftsregel. | `explicit:wikilink`, `inline:rel` | | `confidence` | Float | Vertrauenswürdigkeit (0.0-1.0). | 1.0, 0.95, 0.7 | - | `provenance` | Keyword | Quelle der Kante. | `explicit`, `rule`, **`smart`** (Neu v2.6). | + | `provenance` | Keyword | Quelle der Kante (Neu in v2.6). | `explicit`, `rule`, `smart` | --- @@ -196,7 +196,7 @@ Steuert den Import-Prozess. types: concept: - chunk_profile: medium + chunk_profile: sliding_standard edge_defaults: ["references", "related_to"] retriever_weight: 0.60 experience: @@ -233,7 +233,7 @@ Erweiterung für LLM-Steuerung und Embedding-Modell: MINDNET_API_TIMEOUT=300.0 # Neu: Timeout für Frontend-API (Smart Edges brauchen Zeit) MINDNET_DECISION_CONFIG="config/decision_engine.yaml" MINDNET_VAULT_ROOT="./vault" # Neu: Pfad für Write-Back - MINDNET_LLM_BACKGROUND_LIMIT=2 # Neu: Limit für parallele Import-Tasks + MINDNET_LLM_BACKGROUND_LIMIT=2 # Neu: Limit für parallele Hintergrund-Jobs (Traffic Control) --- @@ -244,16 +244,13 @@ Das Skript `scripts/import_markdown.py` orchestriert den Prozess. ### 4.1 Verarbeitungsschritte (Async + Smart) -1. **Discovery & Parsing:** - * Einlesen der `.md` Dateien. Hash-Vergleich (Body/Frontmatter) zur Erkennung von Änderungen. -2. **Typauflösung:** - * Bestimmung des `type` via `types.yaml`. -3. **Config Check:** - * Prüft `enable_smart_edge_allocation` in der `types.yaml`. +1. **Discovery & Parsing:** Hash-Vergleich zur Erkennung von Änderungen. +2. **Typauflösung:** Bestimmung des `type` via `types.yaml`. +3. **Config Check:** Laden des `chunk_profile` und `enable_smart_edge_allocation`. 4. **Chunking & Smart Edges (WP15):** * Zerlegung des Textes via `chunker.py`. * Wenn Smart Edges aktiv: Der `SemanticAnalyzer` sendet Chunks an das LLM. - * **Traffic Control:** Der Request nutzt `priority="background"`. Die Semaphore (default: 2) drosselt die Parallelität. + * **Traffic Control:** Der Request nutzt `priority="background"`. Die Semaphore (Limit: 2) drosselt die Parallelität. 5. **Kantenableitung (Edge Derivation):** * `derive_edges.py` erzeugt Inline-, Callout- und Default-Edges. 6. **Embedding (Async):** @@ -317,9 +314,9 @@ Die Behandlung einer Anfrage ist nicht mehr hartkodiert, sondern wird dynamisch * **Question Detection:** Unterscheidung Frage vs. Befehl. ### 6.2 Traffic Control (Priorisierung) -Um den Chat-Betrieb auch bei laufendem Import stabil zu halten, implementiert der `LLMService` Prioritäts-Warteschlangen: -* **Priority "realtime" (Chat):** Anfragen gehen sofort an Ollama. Keine Semaphore. -* **Priority "background" (Import):** Anfragen warten in einer Semaphore (Limit konfiguriert via `MINDNET_LLM_BACKGROUND_LIMIT`). +Der `LLMService` implementiert zwei Spuren basierend auf `app/services/llm_service.py` (v2.8.0): +* **Realtime (Chat):** `priority="realtime"`. Umgeht die Semaphore. Antwortet sofort. +* **Background (Import/Analyse):** `priority="background"`. Wartet in der Semaphore (`asyncio.Semaphore`), die lazy mit `MINDNET_LLM_BACKGROUND_LIMIT` initialisiert wird. ### 6.3 Schritt 1: Intent Detection (Question vs. Action) Der Router ermittelt die Absicht (`Intent`) des Nutzers. @@ -362,8 +359,12 @@ Das Frontend ist eine **Streamlit-Anwendung** (`app/frontend/ui.py`), die als se ### 7.1 Kommunikation * **Backend-URL:** Konfiguriert via `MINDNET_API_URL` (Default: `http://localhost:8002`). -* **Endpoints:** Nutzt `/chat` für Interaktion, `/feedback` für Bewertungen und `/ingest/analyze` für Intelligence. -* **Resilienz:** Das Frontend nutzt `MINDNET_API_TIMEOUT` (Default 300s), um auch bei langsamen Smart-Edge-Berechnungen im Backend nicht abzubrechen. +* **Endpoints:** + * `/chat` (Interaktion) + * `/feedback` (Bewertungen) + * `/ingest/analyze` (Active Intelligence / Link-Vorschläge) + * `/ingest/save` (Persistence / Speichern im Vault) +* **Resilienz:** Das Frontend nutzt `MINDNET_API_TIMEOUT` (300s), um auf langsame Backend-Prozesse (Smart Edges) zu warten. ### 7.2 Features & UI-Logik * **State Management:** Session-State speichert Chat-Verlauf und `query_id`. diff --git a/docs/pipeline_playbook.md b/docs/pipeline_playbook.md index e2f8811..492b9df 100644 --- a/docs/pipeline_playbook.md +++ b/docs/pipeline_playbook.md @@ -64,14 +64,19 @@ Seit v2.6 läuft der Import vollständig asynchron, nutzt intelligente Kantenval 4. **Note-Payload generieren:** Erstellen des JSON-Objekts für `mindnet_notes`. 5. **Chunking anwenden:** Zerlegung des Textes basierend auf dem `chunk_profile` des Typs (z.B. `sliding_smart_edges`). 6. **Smart Edge Allocation (Neu in WP15):** - * Prüfung: Ist für den Typ `enable_smart_edge_allocation: true` konfiguriert? - * Falls Ja: Der `SemanticAnalyzer` sendet jeden Chunk an das LLM (Ollama). - * **Traffic Control:** Der Request nutzt `priority="background"`. Die globale Semaphore (Limit: 2, konfigurierbar) verhindert Überlastung des Systems. + * Wenn in `types.yaml` aktiviert (`enable_smart_edge_allocation`): + * Der `SemanticAnalyzer` sendet jeden Chunk an das LLM. + * **Resilienz & Traffic Control:** + * **Priority:** Der Request nutzt `priority="background"`. + * **Semaphore:** Eine globale Semaphore (Limit: 2, konfigurierbar) verhindert System-Überlastung. + * **Retry & Backoff:** Bei Fehlern (Timeouts) wird bis zu 5-mal mit exponentieller Wartezeit wiederholt. + * **JSON Repair:** Der Analyzer erkennt fehlerhaftes JSON (z.B. Dict statt Liste) und repariert es automatisch. + * **Safety Fallback:** Schlagen alle Versuche fehl, werden die Kanten *allen* Chunks zugewiesen, um Datenverlust zu vermeiden. * Ergebnis: Das LLM filtert irrelevante Links aus dem Chunk ("Broadcasting" verhindern). 7. **Inline-Kanten finden:** Parsing von `[[rel:...]]` im Fließtext. 8. **Callout-Kanten finden:** Parsing von `> [!edge]` Blöcken. 9. **Default-Edges erzeugen:** Anwendung der `edge_defaults` aus der Typ-Registry. -10. **Strukturkanten erzeugen:** `belongs_to` (Chunk->Note), `next`/`prev` (Sequenz). +10. **Strukturkanten erzeugen:** `belongs_to`, `next`, `prev` (Sequenz). 11. **Embedding & Upsert (Async):** * Generierung der Vektoren via `nomic-embed-text` (768 Dim). 12. **Strict Mode:** Der Prozess bricht sofort ab, wenn ein Embedding leer ist oder die Dimension `0` hat. @@ -128,11 +133,10 @@ Das Chunking ist profilbasiert und typgesteuert. ### 3.1 Chunk-Profile In `types.yaml` definiert. Standard-Profile (in `chunk_config.py` implementiert): -* `short`: Max 128 Tokens (z.B. für Logs, Chats). -* `medium`: Max 256 Tokens (z.B. für Konzepte). -* `long`: Max 512 Tokens (z.B. für Essays, Projekte). -* `by_heading`: Trennt strikt an Überschriften. -* `sliding_smart_edges`: Sliding Window, das speziell für die nachgelagerte LLM-Analyse optimiert ist. +* `sliding_short`: Max 128 Tokens (z.B. für Logs, Chats). +* `sliding_standard`: Max 512 Tokens (Standard für Massendaten). +* `sliding_smart_edges`: Sliding Window, optimiert für LLM-Analyse (Fließtext). +* `structured_smart_edges`: Trennt strikt an Überschriften (für strukturierte Daten). ### 3.2 Payload-Felder Jeder Chunk erhält zwei Text-Felder: @@ -280,7 +284,7 @@ Aktueller Implementierungsstand der Module. | **WP07** | Interview Assistent | 🟢 Live | **One-Shot Extractor & Schemas aktiv.** | | **WP08** | Self-Tuning | 🔴 Geplant | Auto-Adjustment der Gewichte. | | **WP10** | Chat Interface | 🟢 Live | Web-Interface (Streamlit). | -| **WP10a**| Draft Editor | 🟢 Live | **Interaktives UI & Healing Parser.** | +| **WP10a**| Draft Editor | 🟢 Live | **Interaktives UI für WP07 Drafts.** | | **WP11** | Backend Intelligence | 🟢 Live | **Async Ingestion, Nomic Embeddings, Matrix Logic.** | | **WP15** | Smart Edge Allocation | 🟢 Live | **LLM-Filter & Traffic Control aktiv.** | | **WP16** | Auto-Discovery | 🟡 Geplant | UX & Retrieval Tuning. |