diff --git a/docs/00_General/00_glossary.md b/docs/00_General/00_glossary.md index 334278e..e14ead9 100644 --- a/docs/00_General/00_glossary.md +++ b/docs/00_General/00_glossary.md @@ -2,13 +2,13 @@ doc_type: glossary audience: all status: active -version: 2.8.0 -context: "Zentrales Glossar für Mindnet v2.8. Enthält Definitionen zu Hybrid-Cloud Resilienz, WP-76 Quoten-Steuerung und Mistral-safe Parsing." +version: 2.8.1 +context: "Zentrales Glossar für Mindnet v2.8. Enthält Definitionen zu Hybrid-Cloud Resilienz, WP-14 Modularisierung, WP-15b Two-Pass Ingestion und Mistral-safe Parsing." --- # Mindnet Glossar -**Quellen:** `01_edge_vocabulary.md`, `llm_service.py`, `ingestion.py`, `edge_registry.py` +**Quellen:** `01_edge_vocabulary.md`, `llm_service.py`, `ingestion.py`, `edge_registry.py`, `registry.py`, `qdrant.py` ## Kern-Entitäten @@ -21,11 +21,13 @@ context: "Zentrales Glossar für Mindnet v2.8. Enthält Definitionen zu Hybrid-C ## Komponenten * **Edge Registry:** Der zentrale Dienst (SSOT), der Kanten-Typen validiert und Aliase in kanonische Typen auflöst. Nutzt `01_edge_vocabulary.md` als Basis. -* **LLM Service:** Der Hybrid-Client (v3.3.6), der Anfragen zwischen OpenRouter, Google Gemini und lokalem Ollama routet. Verwaltet Cloud-Timeouts und Quoten-Management. -* **Retriever:** Besteht in v2.7+ aus der Orchestrierung (`retriever.py`) und der mathematischen Scoring-Engine (`retriever_scoring.py`). +* **LLM Service:** Der Hybrid-Client (v3.3.6), der Anfragen zwischen OpenRouter, Google Gemini und lokalem Ollama routet. Verwaltet Cloud-Timeouts und Quoten-Management. Nutzt zur Text-Bereinigung nun die neutrale `registry.py`, um Circular Imports zu vermeiden. +* **Retriever:** Besteht in v2.7+ aus der Orchestrierung (`retriever.py`) und der mathematischen Scoring-Engine (`retriever_scoring.py`). Seit WP-14 im Paket `app.core.retrieval` gekapselt. * **Decision Engine:** Teil des Routers, der Intents erkennt und entsprechende **Boost-Faktoren** für das Retrieval injiziert. * **Traffic Control:** Verwaltet Prioritäten und drosselt Hintergrund-Tasks (z.B. Smart Edges) mittels Semaphoren und Timeouts (45s) zur Vermeidung von System-Hangs. * **Unknown Edges Log:** Die Datei `unknown_edges.jsonl`, in der das System Kanten-Typen protokolliert, die nicht im Dictionary gefunden wurden. +* **Database Package (WP-14):** Zentralisiertes Infrastruktur-Paket (`app.core.database`), das den Qdrant-Client (`qdrant.py`) und das Point-Mapping (`qdrant_points.py`) verwaltet. +* **LocalBatchCache (WP-15b):** Ein globaler In-Memory-Index, der während des Pass 1 Scans aufgebaut wird und Metadaten (IDs, Titel, Summaries) aller Notizen für die Kantenvalidierung bereithält. ## Konzepte & Features @@ -40,5 +42,9 @@ context: "Zentrales Glossar für Mindnet v2.8. Enthält Definitionen zu Hybrid-C * `explicit`: Vom Mensch gesetzt (Prio 1). * `semantic_ai`: Von der KI im Turbo-Mode extrahiert und validiert (Prio 2). * `structure`: Durch System-Regeln/Matrix erzeugt (Prio 3). -* **Smart Edge Allocation:** KI-Verfahren zur Relevanzprüfung von Links für spezifische Textabschnitte. -* **Matrix Logic:** Bestimmung des Kanten-Typs basierend auf Quell- und Ziel-Entität (z.B. Erfahrung -> Wert = `based_on`). \ No newline at end of file +* **Smart Edge Allocation (WP-15b):** KI-Verfahren zur Relevanzprüfung von Links für spezifische Textabschnitte. Validiert Kandidaten semantisch gegen das Ziel im LocalBatchCache. +* **Matrix Logic:** Bestimmung des Kanten-Typs basierend auf Quell- und Ziel-Entität (z.B. Erfahrung -> Wert = `based_on`). +* **Two-Pass Workflow (WP-15b):** Optimiertes Ingestion-Verfahren: + * **Pass 1 (Pre-Scan):** Schnelles Scannen aller Dateien zur Befüllung des LocalBatchCache. + * **Pass 2 (Semantic Processing):** Tiefenverarbeitung (Chunking, Embedding, Validierung) nur für geänderte Dateien. +* **Circular Import Registry (WP-14):** Entkopplung von Kern-Logik (wie Textbereinigung) in eine neutrale `registry.py`, um Abhängigkeitsschleifen zwischen Diensten und Ingestion-Utilities zu verhindern. \ No newline at end of file diff --git a/docs/03_Technical_References/03_tech_configuration.md b/docs/03_Technical_References/03_tech_configuration.md index 150182a..77d4576 100644 --- a/docs/03_Technical_References/03_tech_configuration.md +++ b/docs/03_Technical_References/03_tech_configuration.md @@ -1,19 +1,19 @@ --- doc_type: technical_reference audience: developer, admin -scope: configuration, env, registry, scoring, resilience +scope: configuration, env, registry, scoring, resilience, modularization status: active -version: 2.8.0 -context: "Umfassende Referenztabellen für Umgebungsvariablen (inkl. Hybrid-Cloud & WP-76), YAML-Konfigurationen und die Edge Registry Struktur." +version: 2.9.1 +context: "Umfassende Referenztabellen für Umgebungsvariablen (inkl. Hybrid-Cloud & WP-76), YAML-Konfigurationen und die Edge Registry Struktur unter Berücksichtigung von WP-14." --- # Konfigurations-Referenz -Dieses Dokument beschreibt alle Steuerungsdateien von Mindnet. In der Version 2.8 wurde die Konfiguration professionalisiert, um die Edge Registry, dynamische Scoring-Parameter (Lifecycle & Intent) sowie die neue Hybrid-Cloud-Resilienz zu unterstützen. +Dieses Dokument beschreibt alle Steuerungsdateien von Mindnet. In der Version 2.9.1 wurde die Konfiguration professionalisiert, um die Edge Registry, dynamische Scoring-Parameter (Lifecycle & Intent), die neue Hybrid-Cloud-Resilienz sowie die modulare Datenbank-Infrastruktur (WP-14) zu unterstützen. ## 1. Environment Variablen (`.env`) -Diese Variablen steuern die Infrastruktur, Pfade und globale Timeouts. +Diese Variablen steuern die Infrastruktur, Pfade und globale Timeouts. Seit der Modularisierung in WP-14 unterstützen sie zudem die explizite Benennung von Vektoren für verschiedene Collections. | Variable | Default | Beschreibung | | :--- | :--- | :--- | @@ -21,6 +21,10 @@ Diese Variablen steuern die Infrastruktur, Pfade und globale Timeouts. | `QDRANT_API_KEY` | *(leer)* | Optionaler Key für Absicherung. | | `COLLECTION_PREFIX` | `mindnet` | Namensraum für Collections (erzeugt `{prefix}_notes` etc). | | `VECTOR_DIM` | `768` | **Muss 768 sein** (für Nomic Embeddings). | +| `MINDNET_VECTOR_NAME` | `default` | **Neu (WP-14):** Basis-Vektorname für Named Vectors Support. | +| `NOTES_VECTOR_NAME` | *(leer)* | **Neu (WP-14):** Spezifischer Vektorname für die Notes-Collection (Override). | +| `CHUNKS_VECTOR_NAME` | *(leer)* | **Neu (WP-14):** Spezifischer Vektorname für die Chunks-Collection (Override). | +| `EDGES_VECTOR_NAME` | *(leer)* | **Neu (WP-14):** Spezifischer Vektorname für die Edges-Collection (Override). | | `MINDNET_VOCAB_PATH` | *(Pfad)* | **Neu (WP-22):** Absoluter Pfad zur `01_edge_vocabulary.md`. Definiert den Ort des Dictionarys. | | `MINDNET_VAULT_ROOT` | `./vault` | Basis-Pfad für Datei-Operationen. | | `MINDNET_TYPES_FILE` | `config/types.yaml` | Pfad zur Typ-Registry. | @@ -38,23 +42,25 @@ Diese Variablen steuern die Infrastruktur, Pfade und globale Timeouts. | `MINDNET_LLM_MODEL` | `phi3:mini` | Name des lokalen Chat-Modells (Ollama). | | `MINDNET_EMBEDDING_MODEL` | `nomic-embed-text` | Name des Embedding-Modells (Ollama). | | `MINDNET_OLLAMA_URL` | `http://127.0.0.1:11434`| URL zum lokalen LLM-Server. | -| `MAX_OLLAMA_CHARS` | `10000`| Maximale Länge des Kontext-Strings, der an das lokale Modell gesendet wird. Verhindert Batch-Decoding-Fehler bei sehr großen Notiz-Historien. | +| `MAX_OLLAMA_CHARS` | `10000`| Maximale Länge des Kontext-Strings, der an das lokale Modell gesendet wird. | | `MINDNET_LLM_TIMEOUT` | `300.0` | Timeout in Sekunden für LLM-Anfragen. | | `MINDNET_API_TIMEOUT` | `300.0` | Globales API-Timeout für das Frontend. | | `MINDNET_LL_BACKGROUND_LIMIT`| `2` | **Traffic Control:** Max. parallele Hintergrund-Tasks (Semaphore). | | `MINDNET_CHANGE_DETECTION_MODE` | `full` | `full` (Text + Meta) oder `body` (nur Text). | +| `MINDNET_DEFAULT_RETRIEVER_WEIGHT` | `1.0` | **Neu (WP-22):** Systemweiter Standard für das Retriever-Gewicht einer Notiz. | --- ## 2. Typ-Registry (`types.yaml`) -Steuert das Import-Verhalten, Chunking und die Kanten-Logik pro Typ. +Steuert das Import-Verhalten, Chunking und die Kanten-Logik pro Typ. Die Auflösung erfolgt zentral über die modularisierte Registry in `app.core.registry`. ### 2.1 Konfigurations-Hierarchie (Override-Logik) Seit Version 2.7.0 gilt für `chunking_profile` und `retriever_weight` folgende Priorität: 1. **Frontmatter (Höchste Prio):** Ein Wert direkt in der Markdown-Datei überschreibt alles. 2. **Type Config:** Der Standardwert für den `type` aus `types.yaml`. -3. **Global Default:** Fallback aus `defaults` in `types.yaml`. +3. **Ingestion Settings (Neu WP-14):** Globale Konfiguration wie `default_chunk_profile` innerhalb des `ingestion_settings` Blocks. +4. **Global Default:** Fallback aus `defaults` in `types.yaml`. ## 2.2 Typ-Referenz & Stream-Logik (Vollständige Liste: 28 Typen) @@ -113,7 +119,7 @@ Dieser Stream speichert deine Erlebnisse, Fakten und externes Wissen als Belege. ## 3. Retriever Config (`retriever.yaml`) -Steuert die Gewichtung der Scoring-Formel und die neuen Lifecycle-Modifier. +Steuert die Gewichtung der Scoring-Formel und die neuen Lifecycle-Modifier. Seit WP-14 ist die mathematische Engine im Paket `app.core.retrieval` gekapselt. ```yaml version: 1.2 @@ -140,43 +146,36 @@ lifecycle_weights: system: 0.0 # Hard Skip via Ingestion # Die nachfolgenden Werte überschreiben die Defaults aus app/core/retriever_config. -# Wenn neue Kantentypen, z.B. durch Referenzierung innerhalb einer md-Datei im vault anders gewichtet werden sollen, dann muss hier die Konfiguration erfolgen edge_types: # --- KATEGORIE 1: LOGIK-BOOSTS (Relevanz-Treiber) --- - # Diese Kanten haben die Kraft, das semantische Ranking aktiv umzugestalten. - blocks: 1.6 # Kritisch: Risiken/Blocker müssen sofort sichtbar sein. - solves: 1.5 # Zielführend: Lösungen sind primäre Suchziele. - depends_on: 1.4 # Logisch: Harte fachliche Abhängigkeit. - resulted_in: 1.4 # Kausal: Ergebnisse und unmittelbare Konsequenzen. - followed_by: 1.3 # Sequenziell (User): Bewusst gesteuerte Wissenspfade. - caused_by: 1.2 # Kausal: Ursachen-Bezug (Basis für Intent-Boost). - preceded_by: 1.1 # Sequenziell (User): Rückwärts-Bezug in Logik-Ketten. + blocks: 1.6 + solves: 1.5 + depends_on: 1.4 + resulted_in: 1.4 + followed_by: 1.3 + caused_by: 1.2 + preceded_by: 1.1 # --- KATEGORIE 2: QUALITATIVER KONTEXT (Stabilitäts-Stützen) --- - # Diese Kanten liefern wichtigen Kontext, ohne das Ergebnis zu verfälschen. - guides: 1.1 # Qualitativ: Prinzipien oder Werte leiten das Thema. - part_of: 1.1 # Strukturell: Zieht übergeordnete Kontexte (Parents) mit hoch. - based_on: 0.8 # Fundament: Bezug auf Basis-Werte (kalibriert auf Safe-Retrieval). - derived_from: 0.6 # Historisch: Dokumentiert die Herkunft von Wissen. - uses: 0.6 # Instrumentell: Genutzte Werkzeuge, Methoden oder Ressourcen. + guides: 1.1 + part_of: 1.1 + based_on: 0.8 + derived_from: 0.6 + uses: 0.6 # --- KATEGORIE 3: THEMATISCHE NÄHE (Ähnlichkeits-Signal) --- - # Diese Werte verhindern den "Drift" in fachfremde Bereiche. - similar_to: 0.4 # Analytisch: Thematische Nähe (oft KI-generiert). + similar_to: 0.4 # --- KATEGORIE 4: SYSTEM-NUDGES (Technische Struktur) --- - # Reine Orientierungshilfen für das System; fast kein Einfluss auf das Ranking. - belongs_to: 0.2 # System: Verknüpft Chunks mit der Note (Metadaten-Träger). - next: 0.1 # System: Technische Lesereihenfolge der Absätze. - prev: 0.1 # System: Technische Lesereihenfolge der Absätze. + belongs_to: 0.2 + next: 0.1 + prev: 0.1 # --- KATEGORIE 5: WEICHE ASSOZIATIONEN (Rausch-Unterdrückung) --- - # Verhindert, dass lose Verknüpfungen das Ergebnis "verwässern". - references: 0.1 # Assoziativ: Einfacher Querverweis oder Erwähnung. - related_to: 0.05 # Minimal: Schwächste thematische Verbindung. + references: 0.1 + related_to: 0.05 ``` - --- ## 4. Edge Typen & Registry Referenz @@ -185,7 +184,7 @@ Die `EdgeRegistry` ist die **Single Source of Truth** für das Vokabular. ### 4.1 Dateistruktur & Speicherort Die Registry erwartet eine Markdown-Datei an folgendem Ort: -* **Standard-Pfad:** `/01_User_Manual/01_edge_vocabulary.md`. +* **Standard-Pfad:** `/_system/dictionary/edge_vocabulary.md`. * **Custom-Pfad:** Kann via `.env` Variable `MINDNET_VOCAB_PATH` überschrieben werden. ### 4.2 Aufbau des Dictionaries (Markdown-Schema) @@ -199,37 +198,30 @@ Die Datei muss eine Markdown-Tabelle enthalten, die vom Regex-Parser gelesen wir | **`caused_by`** | `ausgelöst_durch`, `wegen` | Kausalität: A löst B aus. | ``` -**Regeln für die Spalten:** -1. **Canonical:** Muss fett gedruckt sein (`**type**` oder `**`type`**`). Dies ist der Wert, der in der DB landet. -2. **Aliasse:** Kommagetrennte Liste von Synonymen. Diese werden beim Import automatisch zum Canonical aufgelöst. -3. **Beschreibung:** Rein informativ für den Nutzer. - ### 4.3 Verfügbare Kanten-Typen (System-Standard) -| System-Typ (Canonical) | Erlaubte Aliasse (User) | Beschreibung | -| :--------------------- | :--------------------------------------------------- | :-------------------------------------- | -| **`caused_by`** | `ausgelöst_durch`, `wegen`, `ursache_ist` | Kausalität: A löst B aus. | -| **`derived_from`** | `abgeleitet_von`, `quelle`, `inspiriert_durch` | Herkunft: A stammt von B. | -| **`based_on`** | `basiert_auf`, `fundament`, `grundlage` | Fundament: B baut auf A auf. | -| **`solves`** | `löst`, `beantwortet`, `fix_für` | Lösung: A ist Lösung für Problem B. | -| **`part_of`** | `teil_von`, `gehört_zu`, `cluster` | Hierarchie: Kind -> Eltern. | -| **`depends_on`** | `hängt_ab_von`, `braucht`, `requires`, `enforced_by` | Abhängigkeit: A braucht B. | -| **`blocks`** | `blockiert`, `verhindert`, `risiko_für` | Blocker: A verhindert B. | -| **`uses`** | `nutzt`, `verwendet`, `tool` | Werkzeug: A nutzt B. | -| **`guides`** | `steuert`, `leitet`, `orientierung` | Soft-Dependency: A gibt Richtung für B. | -| **`followed_by`** | `danach`, `folgt`, `nachfolger`, `followed_by` | Prozess: A -> B. | -| **`preceeded_by`** | `davor`, `vorgänger`, `preceded_by` | Prozess: B <- A. | -| **`related_to`** | `siehe_auch`, `kontext`, `thematisch` | Lose Assoziation. | -| **`similar_to`** | `ähnlich_wie`, `vergleichbar` | Synonym / Ähnlichkeit. | -| **`references`** | *(Kein Alias)* | Standard-Verweis (Fallback). | -| **`resulted_in`** | `ergebnis`, `resultat`, `erzeugt` | Herkunft: A erzeugt Ergebnis B | +| System-Typ (Canonical) | Erlaubte Aliasse (User) | Beschreibung | +| :--- | :--- | :--- | +| **`caused_by`** | `ausgelöst_durch`, `wegen`, `ursache_ist` | Kausalität: A löst B aus. | +| **`derived_from`** | `abgeleitet_von`, `quelle`, `inspiriert_durch` | Herkunft: A stammt von B. | +| **`based_on`** | `basiert_auf`, `fundament`, `grundlage` | Fundament: B baut auf A auf. | +| **`solves`** | `löst`, `beantwortet`, `fix_für` | Lösung: A ist Lösung für Problem B. | +| **`part_of`** | `teil_von`, `gehört_zu`, `cluster` | Hierarchie: Kind -> Eltern. | +| **`depends_on`** | `hängt_ab_von`, `braucht`, `requires`, `enforced_by` | Abhängigkeit: A braucht B. | +| **`blocks`** | `blockiert`, `verhindert`, `risiko_für` | Blocker: A verhindert B. | +| **`uses`** | `nutzt`, `verwendet`, `tool` | Werkzeug: A nutzt B. | +| **`guides`** | `steuert`, `leitet`, `orientierung` | Soft-Dependency: A gibt Richtung für B. | +| **`followed_by`** | `danach`, `folgt`, `nachfolger`, `followed_by` | Prozess: A -> B. | +| **`preceeded_by`** | `davor`, `vorgänger`, `preceded_by` | Prozess: B <- A. | +| **`related_to`** | `siehe_auch`, `kontext`, `thematisch` | Lose Assoziation. | +| **`similar_to`** | `ähnlich_wie`, `vergleichbar` | Synonym / Ähnlichkeit. | +| **`references`** | *(Kein Alias)* | Standard-Verweis (Fallback). | +| **`resulted_in`** | `ergebnis`, `resultat`, `erzeugt` | Herkunft: A erzeugt Ergebnis B | -**ACHTUNG!** Die Kantentypen -**belongs_to**, **next** und **prev** dürfen nicht vom Nutzer gesetzt werden +**ACHTUNG!** Die Kantentypen **belongs_to**, **next** und **prev** dürfen nicht vom Nutzer gesetzt werden. --- - ## 5. Decision Engine (`decision_engine.yaml`) Die Decision Engine fungiert als zentraler Orchestrator für die Intent-Erkennung und das dynamische Retrieval-Routing. Sie bestimmt, wie das System auf eine Nutzeranfrage reagiert, welche Informationstypen bevorzugt werden und wie der Wissensgraph für die spezifische Situation verformt wird. @@ -323,7 +315,4 @@ strategies: BITTE WÄGE FAKTEN GEGEN FOLGENDE WERTE, PRINZIPIEN UND ZIELE AB: # 3. Empathie / "Ich"-Modus - -``` - -*Richtwert für Kanten-Boosts: 0.1 (Abwertung) bis 3.0+ (Dominanz gegenüber Text-Match).* \ No newline at end of file +``` \ No newline at end of file diff --git a/docs/03_Technical_References/03_tech_data_model.md b/docs/03_Technical_References/03_tech_data_model.md index 00e63c2..6492522 100644 --- a/docs/03_Technical_References/03_tech_data_model.md +++ b/docs/03_Technical_References/03_tech_data_model.md @@ -3,15 +3,15 @@ doc_type: technical_reference audience: developer, architect scope: database, qdrant, schema status: active -version: 2.7.0 -context: "Exakte Definition der Datenmodelle (Payloads) in Qdrant und Index-Anforderungen." +version: 2.8.0 +context: "Exakte Definition der Datenmodelle (Payloads) in Qdrant und Index-Anforderungen. Berücksichtigt WP-14 Modularisierung und WP-15b Multi-Hashes." --- # Technisches Datenmodell (Qdrant Schema) ## 1. Collections & Namenskonvention -Mindnet speichert Daten in drei getrennten Qdrant-Collections. Der Prefix ist via ENV `COLLECTION_PREFIX` konfigurierbar (Default: `mindnet`). +Mindnet speichert Daten in drei getrennten Qdrant-Collections. Der Prefix ist via ENV `COLLECTION_PREFIX` konfigurierbar (Default: `mindnet`). Die Auflösung erfolgt zentral über `app.core.database.collection_names`. Das System nutzt folgende drei Collections: * `{prefix}_notes`: Metadaten der Dateien. @@ -28,9 +28,10 @@ Repräsentiert die Metadaten einer Markdown-Datei (1:1 Beziehung). ```json { - "note_id": "string (keyword)", // UUIDv5 (deterministisch) oder Slug + "note_id": "string (keyword)", // UUIDv5 (deterministisch via NAMESPACE_URL) "title": "string (text)", // Titel aus Frontmatter "type": "string (keyword)", // Logischer Typ (z.B. 'project', 'concept') + "status": "string (keyword)", // Lifecycle: 'stable', 'active', 'draft', 'system' (WP-22) "retriever_weight": "float", // Effektive Wichtigkeit (Frontmatter > Type > Default) "chunk_profile": "string", // Effektives Profil (Frontmatter > Type > Default) "edge_defaults": ["string"], // Liste der aktiven Default-Kanten @@ -40,7 +41,7 @@ Repräsentiert die Metadaten einer Markdown-Datei (1:1 Beziehung). "updated": "integer", // Timestamp (File Modification Time) "fulltext": "string (no-index)", // Gesamter Text (nur für Recovery/Export) - // NEU in v2.7: Multi-Hash für flexible Change Detection + // Multi-Hash für flexible Change Detection (WP-15b) "hashes": { "body:parsed:canonical": "string", // Hash nur über den Text-Body "full:parsed:canonical": "string" // Hash über Text + Metadaten (Tags, Title, Config) @@ -52,6 +53,7 @@ Repräsentiert die Metadaten einer Markdown-Datei (1:1 Beziehung). Es müssen Payload-Indizes für folgende Felder existieren: * `note_id` * `type` +* `status` * `tags` --- @@ -61,7 +63,7 @@ Es müssen Payload-Indizes für folgende Felder existieren: Die atomare Sucheinheit. Enthält den Vektor. **Vektor-Konfiguration:** -* Modell: `nomic-embed-text` +* Modell: `nomic-embed-text` (via Ollama oder Cloud) * Dimension: **768** * Metrik: Cosine Similarity @@ -69,7 +71,7 @@ Die atomare Sucheinheit. Enthält den Vektor. ```json { - "chunk_id": "string (keyword)", // Format: {note_id}#c{index} (z.B. 'abc-123#c01') + "chunk_id": "string (keyword)", // Format: UUIDv5 aus {note_id}#c{index} "note_id": "string (keyword)", // Foreign Key zur Note "type": "string (keyword)", // Kopie aus Note (Denormalisiert für Filterung) "text": "string (text)", // Reintext für Anzeige (ohne Overlap) @@ -120,4 +122,5 @@ Es müssen Payload-Indizes für folgende Felder existieren: * `target_id` * `kind` * `scope` -* `note_id` \ No newline at end of file +* `note_id` +``` \ No newline at end of file diff --git a/docs/03_Technical_References/03_tech_ingestion_pipeline.md b/docs/03_Technical_References/03_tech_ingestion_pipeline.md index 901a05d..146baa3 100644 --- a/docs/03_Technical_References/03_tech_ingestion_pipeline.md +++ b/docs/03_Technical_References/03_tech_ingestion_pipeline.md @@ -1,71 +1,77 @@ --- doc_type: technical_reference audience: developer, devops -scope: backend, ingestion, smart_edges, edge_registry +scope: backend, ingestion, smart_edges, edge_registry, modularization status: active -version: 2.8.1 -context: "Detaillierte technische Beschreibung der Import-Pipeline, Mistral-safe Parsing und Deep Fallback Resilienz." +version: 2.9.0 +context: "Detaillierte technische Beschreibung der Import-Pipeline, Two-Pass-Workflow (WP-15b) und modularer Datenbank-Architektur (WP-14). Integriert Mistral-safe Parsing und Deep Fallback." --- # Ingestion Pipeline & Smart Processing -**Quellen:** `pipeline_playbook.md`, `ingestion.py`, `edge_registry.py`, `01_edge_vocabulary.md`, `llm_service.py` +**Quellen:** `pipeline_playbook.md`, `ingestion_processor.py`, `ingestion_db.py`, `ingestion_validation.py`, `registry.py`, `edge_registry.py` + +Die Ingestion transformiert Markdown in den Graphen. Entrypoint: `scripts/import_markdown.py` (CLI) oder `routers/ingest.py` (API). Seit v2.9 nutzt dieser Prozess ein hocheffizientes **Two-Pass-Verfahren**, um globale Kontext-Informationen für die semantische Validierung bereitzustellen, ohne die Idempotenz oder die Change-Detection zu verletzen. + -Die Ingestion transformiert Markdown in den Graphen. Entrypoint: `scripts/import_markdown.py` (CLI) oder `routers/ingest.py` (API). Seit v2.8 integriert dieser Prozess eine **intelligente Quoten-Steuerung** (WP-20) und ein **robustes JSON-Parsing** für Cloud-Modelle (Mistral/Gemini). ## 1. Der Import-Prozess (16-Schritte-Workflow) -Der Prozess ist **asynchron** und **idempotent**. +Der Prozess ist **asynchron**, **idempotent** und wird nun in zwei logische Durchläufe (Passes) unterteilt, um die semantische Genauigkeit zu maximieren. +### Phase 1: Pre-Scan & Context (Pass 1) 1. **Trigger & Async Dispatch:** * **API (`/save`):** Nimmt Request entgegen, validiert und startet Background-Task ("Fire & Forget"). Antwortet sofort mit `202/Queued`. * **CLI:** Iteriert über Dateien und nutzt `asyncio.Semaphore` zur Drosselung. -2. **Markdown lesen:** Rekursives Scannen des Vaults. +2. **Markdown lesen:** Rekursives Scannen des Vaults zur Erstellung des Dateiinventars. 3. **Frontmatter Check & Hard Skip (WP-22):** * Extraktion von `status` und `type`. - * **Hard Skip Rule:** Wenn `status` in `['system', 'template', 'archive', 'hidden']` ist, wird die Datei **sofort übersprungen**. Sie wird weder vektorisiert noch in den Graphen aufgenommen. + * **Hard Skip Rule:** Wenn `status` in `['system', 'template', 'archive', 'hidden']` ist, wird die Datei für das Deep-Processing übersprungen, ihre Metadaten werden jedoch für den Kontext-Cache erfasst. * Validierung der Pflichtfelder (`id`, `title`) für alle anderen Dateien. 4. **Edge Registry Initialisierung (WP-22):** * Laden der Singleton-Instanz der `EdgeRegistry`. * Validierung der Vokabular-Datei unter `MINDNET_VOCAB_PATH`. -5. **Config Resolution:** - * Bestimmung von `chunking_profile` und `retriever_weight`. +5. **Config Resolution (WP-14):** + * Bestimmung von `chunking_profile` und `retriever_weight` via zentraler `TypeRegistry`. * **Priorität:** 1. Frontmatter (Override) -> 2. `types.yaml` (Type) -> 3. Global Default. -6. **Note-Payload generieren:** - * Erstellen des JSON-Objekts inklusive `status` (für Scoring). - * **Multi-Hash Calculation:** Berechnet Hashtabellen für `body` (nur Text) und `full` (Text + Metadaten). -7. **Change Detection:** - * Vergleich des Hashes mit Qdrant. - * Strategie wählbar via ENV `MINDNET_CHANGE_DETECTION_MODE` (`full` oder `body`). -8. **Chunking anwenden:** Zerlegung des Textes basierend auf dem ermittelten Profil (siehe Kap. 3). -9. **Smart Edge Allocation (WP-20):** - * Wenn `enable_smart_edge_allocation: true`: Der `SemanticAnalyzer` sendet Chunks an das LLM. - * **Traffic Control:** Request nutzt `priority="background"`. Semaphore drosselt die Last. - * **Resilienz (Quota Handling):** Erkennt HTTP 429 (Rate-Limit) und pausiert kontrolliert (via `LLM_RATE_LIMIT_WAIT`), bevor ein Cloud-Retry erfolgt. - * **Mistral-safe Parsing:** Automatisierte Bereinigung von BOS-Tokens (``) und Framework-Tags (`[OUT]`) sowie Recovery-Logik für Dictionaries (Suche nach `edges`, `links`, `results`, `kanten`). - * **Deep Fallback (v2.11.14):** Erkennt "Silent Refusals" (Data Policy Violations). Liefert die Cloud trotz erfolgreicher Verbindung keine verwertbaren Kanten, wird ein lokaler Fallback via Ollama erzwungen, um Kantenverlust zu vermeiden. -10. **Inline-Kanten finden:** Parsing von `[[rel:...]]`. -11. **Alias-Auflösung & Kanonisierung (WP-22):** - * Jede Kante wird via `edge_registry.resolve()` normalisiert. - * Aliase (z.B. `basiert_auf`) werden zu kanonischen Typen (z.B. `based_on`) aufgelöst. +6. **LocalBatchCache & Summary Generation (WP-15b):** + * Erstellung von Kurz-Zusammenfassungen für jede Note. + * Speicherung im `batch_cache` als Referenzrahmen für die spätere Kantenvalidierung. + +### Phase 2: Semantic Processing & Persistence (Pass 2) +7. **Note-Payload & Multi-Hash (WP-15b):** + * Erstellen des JSON-Objekts inklusive `status`. + * **Multi-Hash Calculation:** Berechnet Hashtabellen für `body` (nur Text) und `full` (Text + Metadaten) zur präzisen Änderungskontrolle. +8. **Change Detection:** + * Vergleich des aktuellen Hashes mit den Daten in Qdrant (Collection `{prefix}_notes`). + * Strategie wählbar via ENV `MINDNET_CHANGE_DETECTION_MODE` (`full` oder `body`). Unveränderte Dateien werden hier final übersprungen. +9. **Purge Old Artifacts (WP-14):** + * Bei Änderungen löscht `purge_artifacts()` via `app.core.ingestion.ingestion_db` alle alten Chunks und Edges der Note. + * Die Namensauflösung erfolgt nun über das modularisierte `database`-Paket. +10. **Chunking anwenden:** Zerlegung des Textes basierend auf dem ermittelten Profil (siehe Kap. 3). +11. **Smart Edge Allocation & Semantic Validation (WP-15b):** + * Der `SemanticAnalyzer` schlägt Kanten-Kandidaten vor. + * **Validierung:** Jeder Kandidat wird durch das LLM semantisch gegen das Ziel im **LocalBatchCache** geprüft. + * **Traffic Control:** Nutzung der neutralen `clean_llm_text` Funktion zur Bereinigung von Steuerzeichen (, [OUT]). + * **Deep Fallback (v2.11.14):** Erkennt "Silent Refusals". Liefert die Cloud keine verwertbaren Kanten, wird ein lokaler Fallback via Ollama erzwungen. +12. **Inline-Kanten finden:** Parsing von `[[rel:...]]` und Callouts. +13. **Alias-Auflösung & Kanonisierung (WP-22):** + * Jede Kante wird via `EdgeRegistry` normalisiert (z.B. `basiert_auf` -> `based_on`). * Unbekannte Typen werden in `unknown_edges.jsonl` protokolliert. -12. **Callout-Kanten finden:** Parsing von `> [!edge]`. -13. **Default- & Matrix-Edges erzeugen:** Anwendung der `edge_defaults` aus Registry und Matrix-Logik. -14. **Strukturkanten erzeugen:** `belongs_to`, `next`, `prev`. -15. **Embedding (Async):** Generierung via `nomic-embed-text` (768 Dim). -16. **Diagnose:** Integritäts-Check nach dem Lauf. +14. **Default- & Strukturkanten:** Anwendung der `edge_defaults` und Erzeugung von Systemkanten (`belongs_to`, `next`, `prev`). +15. **Embedding (Async):** Generierung der Vektoren via `nomic-embed-text` (768 Dimensionen). +16. **Database Sync (WP-14):** Batch-Upsert aller Points in die Collections `{prefix}_chunks` und `{prefix}_edges` über die zentrale Infrastruktur. --- ## 2. Betrieb & CLI Befehle ### 2.1 Standard-Betrieb (Inkrementell) -Für regelmäßige Updates (Cronjob). Erkennt Änderungen via Hash. +Erkennt Änderungen via Multi-Hash. ```bash export QDRANT_URL="http://localhost:6333" export COLLECTION_PREFIX="mindnet" -# Steuert, wann eine Datei als "geändert" gilt export MINDNET_CHANGE_DETECTION_MODE="full" # Nutzt das Venv der Produktionsumgebung @@ -78,20 +84,13 @@ export MINDNET_CHANGE_DETECTION_MODE="full" ``` > **[!WARNING] Purge-Before-Upsert** -> Das Flag `--purge-before-upsert` ist kritisch. Es löscht vor dem Schreiben einer Note ihre alten Chunks/Edges. Ohne dieses Flag entstehen **"Geister-Chunks"** (alte Textabschnitte, die im Markdown gelöscht wurden, aber im Index verbleiben). +> Das Flag `--purge-before-upsert` nutzt nun `ingestion_db.purge_artifacts`. Es ist kritisch, um "Geister-Chunks" (verwaiste Daten nach Textlöschung) konsistent aus den spezialisierten Collections zu entfernen. ### 2.2 Full Rebuild (Clean Slate) -Notwendig bei Änderungen an `types.yaml` (z.B. neue Chunking-Profile), der Registry oder Modell-Wechsel. +Notwendig bei Änderungen an `types.yaml`, der Registry oder Modell-Wechsel. ```bash -# 0. Modell sicherstellen -ollama pull nomic-embed-text - -# 1. Qdrant Collections löschen (Wipe) -python3 -m scripts.reset_qdrant --mode wipe --prefix "mindnet" --yes - -# 2. Vollständiger Import (Force) -# --force ignoriert alle Hashes und schreibt alles neu +# --force ignoriert alle Hashes und erzwingt den vollständigen Two-Pass Workflow python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force ``` @@ -99,22 +98,20 @@ python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply -- ## 3. Chunking & Payload -Das Chunking ist profilbasiert und in `types.yaml` konfiguriert. +Das Chunking ist profilbasiert und bezieht seine Konfiguration dynamisch aus der `TypeRegistry`. -### 3.1 Profile und Strategien (Vollständige Referenz) +### 3.1 Profile und Strategien | Profil | Strategie | Parameter | Einsatzgebiet | | :--- | :--- | :--- | :--- | -| `sliding_short` | `sliding_window` | Max: 350, Target: 200 | Kurze Logs, Chats, Risiken. | -| `sliding_standard` | `sliding_window` | Max: 650, Target: 450 | Massendaten (Journal, Quellen). | -| `sliding_smart_edges`| `sliding_window` | Max: 600, Target: 400 | Fließtexte mit hohem Wert (Projekte). | -| `structured_smart_edges` | `by_heading` | `strict: false` (Soft) | Strukturierte Texte, Merging erlaubt. | -| `structured_smart_edges_strict` | `by_heading` | `strict: true` (Hard) | **Atomare Einheiten**: Entscheidungen, Werte. | -| `structured_smart_edges_strict_L3`| `by_heading` | `strict: true`, `level: 3` | Tief geschachtelte Prinzipien (Tier 2/MP1). | +| `sliding_short` | `sliding_window` | Max: 350, Target: 200 | Kurze Logs, Chats. | +| `sliding_standard` | `sliding_window` | Max: 650, Target: 450 | Standard-Wissen. | +| `sliding_smart_edges`| `sliding_window` | Max: 600, Target: 400 | Fließtexte (Projekte). | +| `structured_smart_edges` | `by_heading` | `strict: false` | Strukturierte Texte. | ### 3.2 Die `by_heading` Logik (v2.9 Hybrid) -Die Strategie `by_heading` zerlegt Texte anhand ihrer Struktur (Überschriften). Sie unterstützt seit v2.9 ein "Safety Net" gegen zu große Chunks. +Die Strategie `by_heading` zerlegt Texte anhand ihrer Struktur (Überschriften). Sie unterstützt ein "Safety Net" gegen zu große Chunks. * **Split Level:** Definiert die Tiefe (z.B. `2` = H1 & H2 triggern Split). * **Modus "Strict" (`strict_heading_split: true`):** @@ -126,12 +123,6 @@ Die Strategie `by_heading` zerlegt Texte anhand ihrer Struktur (Überschriften). * **Füll-Logik:** Überschriften *auf* dem Split-Level lösen nur dann einen neuen Chunk aus, wenn der aktuelle Chunk die `target`-Größe erreicht hat. * *Safety Net:* Auch hier greift das `max` Token Limit. -### 3.3 Payload-Felder (Qdrant) - -* `text`: Der reine Inhalt (Anzeige im UI). -* `window`: Inhalt plus Overlap (für Embedding). -* `chunk_profile`: Das effektiv genutzte Profil (zur Nachverfolgung). - --- ## 4. Edge-Erzeugung & Prioritäten (Provenance) @@ -143,7 +134,7 @@ Kanten werden nach Vertrauenswürdigkeit (`provenance`) priorisiert. Die höhere | **1** | Wikilink | `explicit:wikilink` | **1.00** | Harte menschliche Setzung. | | **2** | Inline | `inline:rel` | **0.95** | Typisierte menschliche Kante. | | **3** | Callout | `callout:edge` | **0.90** | Explizite Meta-Information. | -| **4** | Semantic AI | `semantic_ai` | **0.90** | KI-extrahierte Verbindung (Mistral-safe). | +| **4** | Semantic AI | `semantic_ai` | **0.90** | KI-validiert gegen LocalBatchCache. | | **5** | Type Default | `edge_defaults` | **0.70** | Heuristik aus der Registry. | | **6** | Struktur | `structure` | **1.00** | System-interne Verkettung (`belongs_to`). | @@ -151,18 +142,8 @@ Kanten werden nach Vertrauenswürdigkeit (`provenance`) priorisiert. Die höhere ## 5. Quality Gates & Monitoring -In v2.7+ wurden Tools zur Überwachung der Datenqualität integriert: +**1. Registry Review (WP-14):** Prüfung der `data/logs/unknown_edges.jsonl`. Die zentrale Auflösung via `registry.py` verhindert Inkonsistenzen zwischen Import und Retrieval. -**1. Registry Review:** Prüfung der `data/logs/unknown_edges.jsonl`. Administratoren sollten hier gelistete Begriffe als Aliase in die `01_edge_vocabulary.md` aufnehmen. +**2. Mistral-safe Parsing:** Automatisierte Bereinigung von LLM-Antworten in `ingestion_validation.py`. Stellt sicher, dass semantische Entscheidungen ("YES"/"NO") nicht durch technische Header verfälscht werden. -**2. Payload Dryrun (Schema-Check):** -Simuliert Import, prüft JSON-Schema Konformität. -```bash -python3 -m scripts.payload_dryrun --vault ./test_vault -``` - -**3. Full Edge Check (Graph-Integrität):** -Prüft Invarianten (z.B. `next` muss reziprok zu `prev` sein). -```bash -python3 -m scripts.edges_full_check -``` \ No newline at end of file +**3. Purge Integrity:** Validierung, dass vor jedem Upsert alle assoziierten Artefakte in den Collections `{prefix}_chunks` und `{prefix}_edges` gelöscht wurden, um Daten-Duplikate zu vermeiden. \ No newline at end of file diff --git a/docs/03_Technical_References/03_tech_retrieval_scoring.md b/docs/03_Technical_References/03_tech_retrieval_scoring.md index f1a4bc7..b2cb15d 100644 --- a/docs/03_Technical_References/03_tech_retrieval_scoring.md +++ b/docs/03_Technical_References/03_tech_retrieval_scoring.md @@ -3,13 +3,13 @@ doc_type: technical_reference audience: developer, data_scientist scope: backend, retrieval, scoring, modularization status: active -version: 2.7.1 -context: "Detaillierte Dokumentation der Scoring-Algorithmen, inklusive WP-22 Lifecycle-Modifier, Intent-Boosting und Modularisierung." +version: 2.9.0 +context: "Detaillierte Dokumentation der Scoring-Algorithmen, inklusive WP-22 Lifecycle-Modifier, Intent-Boosting und WP-14 Modularisierung." --- # Retrieval & Scoring Algorithmen -Der Retriever unterstützt **Semantic Search** und **Hybrid Search**. Seit v2.4 nutzt Mindnet ein gewichtetes Scoring-Modell, das Semantik, Graphentheorie und Metadaten kombiniert. Mit Version 2.7 (WP-22) wurde dieses Modell um **Lifecycle-Faktoren** und **Intent-Boosting** erweitert sowie die Architektur modularisiert. +Der Retriever unterstützt **Semantic Search** und **Hybrid Search**. Seit v2.4 nutzt Mindnet ein gewichtetes Scoring-Modell, das Semantik, Graphentheorie und Metadaten kombiniert. Mit Version 2.7 (WP-22) wurde dieses Modell um **Lifecycle-Faktoren** und **Intent-Boosting** erweitert sowie die Architektur modularisiert (WP-14). ## 1. Scoring Formel (v2.7.0) @@ -37,18 +37,19 @@ $$ * **Zweck:** Belohnt Chunks, die "im Thema" vernetzt sind. **4. Centrality Bonus ($B_{cent}$):** -* **Kontext:** Berechnet im lokalen Subgraphen. +* **Kontext:** Berechnet im lokalen Subgraphen via `graph_subgraph.centrality_bonus`. * **Logik:** Vereinfachte PageRank-Metrik (Degree Centrality). * **Zweck:** Belohnt "Hubs" mit vielen Verbindungen zu anderen Treffern. ### Die WP-22 Erweiterungen (v2.7.0) **5. Status Modifier ($M_{status}$):** -* **Herkunft:** Feld `status` aus dem Frontmatter. +* **Herkunft:** Feld `status` aus dem Frontmatter (verarbeitet in `retriever_scoring.get_status_multiplier`). * **Zweck:** Bestraft unfertiges Wissen (Drafts) oder bevorzugt stabiles Wissen. -* **Werte (Auftrag WP-22):** * `stable`: **1.2** (Bonus für Qualität). - * `draft`: **0.5** (Malus für Entwürfe). - * `system`: Exkludiert (siehe Ingestion). +* **Werte (Auftrag WP-22):** * `stable`: **1.2** (Belohnung für verifiziertes Wissen). + * `active`: **1.0** (Standard-Gewichtung). + * `draft`: **0.5** (Malus für unfertige Fragmente). + * `system`: Exkludiert (siehe Ingestion Lifecycle Filter). **6. Intent Boost ($B_{intent}$):** * **Herkunft:** Dynamische Injektion durch die Decision Engine basierend auf der Nutzerfrage. @@ -56,47 +57,61 @@ $$ --- -## 2. Hybrid Retrieval Flow & Modularisierung +## 2. Hybrid Retrieval Flow & Modularisierung (WP-14) -In v2.7 wurde die Engine in einen Orchestrator (`retriever.py`) und eine Scoring-Engine (`retriever_scoring.py`) aufgeteilt. +Seit v2.9 ist die Retrieval-Engine im spezialisierten Paket `app.core.retrieval` gekapselt. Die Zuständigkeiten sind strikt zwischen Orchestrierung und mathematischer Bewertung getrennt. **Phase 1: Vector Search (Seed Generation)** -* Der Orchestrator sucht Top-K (Standard: 20) Kandidaten via Embeddings in Qdrant. +* Der Orchestrator (`retriever.py`) sucht Top-K (Standard: 20) Kandidaten via Embeddings in Qdrant über das modularisierte `app.core.database` Paket. * Diese bilden die "Seeds" für den Graphen. **Phase 2: Graph Expansion** -* Nutze `graph_adapter.expand(seeds, depth=1)`. -* Lade direkte Nachbarn aus der `_edges` Collection. -* Konstruiere einen `NetworkX`-Graphen im Speicher. +* Nutze die Fassade `app.core.graph_adapter.expand(seeds, depth=1)`. +* Diese delegiert an `app.core.graph.graph_subgraph`, um direkte Nachbarn aus der `_edges` Collection zu laden. +* Konstruktion eines in-memory Graphen zur Berechnung topologischer Boni. **Phase 3: Re-Ranking (Modular)** -* Der Orchestrator übergibt den Graphen und die Seeds an die `ScoringEngine`. -* Berechne Boni ($B_{edge}$, $B_{cent}$) sowie die neuen Lifecycle- und Intent-Modifier. -* Sortierung absteigend nach `TotalScore` und Limitierung auf Top-Resultate (z.B. 5). +* Der Orchestrator übergibt den Graphen und die Seeds an die `ScoringEngine` (`retriever_scoring.py`). +* Berechnung der finalen Scores unter Berücksichtigung von $B_{edge}$, $B_{cent}$ sowie der Lifecycle- und Intent-Modifier. +* Sortierung absteigend nach `TotalScore` und Limitierung auf die angeforderten Top-Resultate. --- ## 3. Explanation Layer (WP-22 Update) -Bei `explain=True` generiert das System eine detaillierte Begründung. +Bei `explain=True` generiert das System eine detaillierte Begründung inklusive Provenienz-Informationen. **Erweiterte JSON-Struktur:** ```json { "score_breakdown": { - "semantic": 0.85, - "type_boost": 1.0, - "lifecycle_modifier": 0.5, - "edge_bonus": 0.4, - "intent_boost": 0.5, - "centrality": 0.1 + "semantic_contribution": 0.85, + "edge_contribution": 0.4, + "centrality_contribution": 0.1, + "raw_semantic": 0.85, + "raw_edge_bonus": 0.3, + "raw_centrality": 0.1, + "node_weight": 1.0, + "status_multiplier": 1.2, + "graph_boost_factor": 1.5 }, "reasons": [ - "Hohe textuelle Übereinstimmung (>0.85).", - "Status 'draft' reduziert Relevanz (Modifier 0.5).", - "Wird referenziert via 'caused_by' (Intent-Bonus 0.5).", - "Bevorzugt, da Typ 'decision' (Gewicht 1.0)." + { + "kind": "semantic", + "message": "Hohe textuelle Übereinstimmung (>0.85).", + "score_impact": 0.85 + }, + { + "kind": "type", + "message": "Bevorzugt durch Typ-Profil.", + "score_impact": 0.1 + }, + { + "kind": "edge", + "message": "Bestätigte Kante 'caused_by' [Boost x1.5] von 'Note-A'.", + "score_impact": 0.4 + } ] } ``` @@ -105,18 +120,18 @@ Bei `explain=True` generiert das System eine detaillierte Begründung. ## 4. Konfiguration (`retriever.yaml`) -Steuert die Gewichtung der mathematischen Komponenten. +Steuert die globale Gewichtung der mathematischen Komponenten. ```yaml scoring: - semantic_weight: 1.0 # Basis-Relevanz - edge_weight: 0.7 # Graphen-Einfluss - centrality_weight: 0.5 # Hub-Einfluss + semantic_weight: 1.0 # Basis-Relevanz (W_sem) + edge_weight: 0.7 # Graphen-Einfluss (W_edge) + centrality_weight: 0.5 # Hub-Einfluss (W_cent) -# WP-22 Lifecycle Konfiguration (Abgleich mit Auftrag) +# WP-22 Lifecycle Konfiguration lifecycle_weights: - stable: 1.2 # Bonus für Qualität - draft: 0.5 # Malus für Entwürfe + stable: 1.2 # Modifier für Qualität + draft: 0.5 # Modifier für Entwürfe # Kanten-Gewichtung für den Edge-Bonus (Basis) edge_weights: diff --git a/docs/05_Development/05_developer_guide.md b/docs/05_Development/05_developer_guide.md index 17ed425..831f285 100644 --- a/docs/05_Development/05_developer_guide.md +++ b/docs/05_Development/05_developer_guide.md @@ -1,10 +1,10 @@ --- doc_type: developer_guide audience: developer -scope: workflow, testing, architecture, modules +scope: workflow, testing, architecture, modules, modularization status: active -version: 2.6.1 -context: "Umfassender Guide für Entwickler: Architektur, Modul-Interna (Deep Dive), Setup, Git-Workflow und Erweiterungs-Anleitungen." +version: 2.9.1 +context: "Umfassender Guide für Entwickler: Modularisierte Architektur (WP-14), Two-Pass Ingestion (WP-15b), Modul-Interna, Setup und Git-Workflow." --- # Mindnet Developer Guide & Workflow @@ -23,8 +23,6 @@ Dieser Guide ist die zentrale technische Referenz für Mindnet v2.6. Er vereint - [Kern-Philosophie](#kern-philosophie) - [2. Architektur](#2-architektur) - [2.1 High-Level Übersicht](#21-high-level-übersicht) - - [2.2 Datenfluss-Muster](#22-datenfluss-muster) - - [A. Ingestion (Write)](#a-ingestion-write) - [B. Retrieval (Read)](#b-retrieval-read) - [C. Visualisierung (Graph)](#c-visualisierung-graph) - [3. Physische Architektur](#3-physische-architektur) @@ -84,23 +82,28 @@ graph TD API["main.py"] RouterChat["Chat / RAG"] RouterIngest["Ingest / Write"] - CoreRet["Retriever Engine"] - CoreIngest["Ingestion Pipeline"] + + subgraph "Core Packages (WP-14)" + PkgRet["retrieval/ (Search)"] + PkgIng["ingestion/ (Import)"] + PkgGra["graph/ (Logic)"] + PkgDb["database/ (Infrastr.)"] + Registry["registry.py (Neutral)"] + end end subgraph "Infrastructure & Services" - LLM["Ollama (Phi3/Nomic)"] + LLM["Ollama / Cloud (Hybrid)"] DB[("Qdrant Vector DB")] FS["File System (.md)"] end User <--> UI - UI -- "REST (Chat, Save, Feedback)" --> API - UI -. "Direct Read (Graph Viz Performance)" .-> DB - API -- "Embeddings & Completion" --> LLM - API -- "Read/Write" --> DB - API -- "Read/Write (Source of Truth)" --> FS -``` + UI -- "REST Call" --> API + PkgRet -- "Direct Query" --> PkgDb + PkgIng -- "Process & Write" --> PkgDb + PkgDb -- "API" --> DB + API -- "Inference" --> LLM``` ### 2.2 Datenfluss-Muster @@ -108,14 +111,12 @@ graph TD Vom Markdown zur Vektor-Datenbank. ```mermaid graph LR - MD["Markdown File"] --> Parser("Parser") - Parser --> Chunker("Chunker") - Chunker -- "Text Chunks" --> SemAn{"SemanticAnalyzer
(LLM)"} - SemAn -- "Smart Edges" --> Embedder("Embedder") - Embedder --> DB[("Qdrant
Points")] - - style DB fill:#f9f,stroke:#333,stroke-width:2px - style SemAn fill:#ff9,stroke:#333,stroke-width:2px + MD["Markdown File"] --> Pass1["Pass 1: Pre-Scan"] + Pass1 --> Cache[("LocalBatchCache
(Titles/Summaries)")] + MD --> Pass2["Pass 2: Processing"] + Cache -- "Context" --> SmartEdges{"Smart Edge
Validation"} + SmartEdges --> Embedder("Embedder") + Embedder --> DB[("Qdrant Points")] ``` #### B. Retrieval (Read) @@ -123,17 +124,10 @@ Die hybride Suche für Chat & RAG. ```mermaid graph LR Query(["Query"]) --> Embed("Embedding") - Embed --> Hybrid{"Hybrid Search"} - - subgraph Search Components - Vec["Vector Score"] - Graph["Graph/Edge Bonus"] - end - - Vec --> Hybrid - Graph --> Hybrid - - Hybrid --> Rank("Re-Ranking") + Embed --> Seed["Seed Search (Vector)"] + Seed --> Expand{"Graph Expansion"} + Expand --> Scoring["Scoring Engine (WP-22)"] + Scoring --> Rank("Final Ranking") Rank --> Ctx["LLM Context"] ``` @@ -170,6 +164,12 @@ Das System ist modular aufgebaut. Hier ist die detaillierte Analyse aller Kompon mindnet/ ├── app/ │ ├── core/ # Business Logic & Algorithms +│ │ ├── database/ # WP-14: Qdrant Client & Point Mapping +│ │ ├── ingestion/ # WP-14: Pipeline, Multi-Hash, Validation +│ │ ├── retrieval/ # WP-14: Search Orchestrator & Scoring +│ │ ├── graph/ # WP-14: Subgraph-Logik & Weights +│ │ ├── registry.py # SSOT: Circular Import Fix & Text Cleanup +│ │ └── *.py (Proxy) # Legacy Bridges für Abwärtskompatibilität │ ├── routers/ # API Interface (FastAPI) │ ├── services/ # External Integrations (LLM, DB) │ ├── models/ # Pydantic DTOs @@ -285,6 +285,8 @@ Folgende Dateien wurden im Audit v2.6 als veraltet, redundant oder "Zombie-Code" | `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/services/llm_ollama.py` | **Veraltet.** Ersetzt durch `llm_service.py`. | 🗑️ Löschen | +| `app/core/type_registry.py` | **Redundant.** Logik in `app/core/registry.py` integriert. | 🗑️ Löschen | +| `app/core/ranking.py` | **Redundant.** Logik in `retrieval/retriever_scoring.py` integriert. | 🗑️ Löschen | --- diff --git a/docs/06_Roadmap/06_active_roadmap.md b/docs/06_Roadmap/06_active_roadmap.md index 59df0a0..7b9be49 100644 --- a/docs/06_Roadmap/06_active_roadmap.md +++ b/docs/06_Roadmap/06_active_roadmap.md @@ -2,18 +2,14 @@ doc_type: roadmap audience: product_owner, developer status: active -version: 2.8.0 -context: "Aktuelle Planung für kommende Features (ab WP16), Release-Strategie und Historie der abgeschlossenen WPs." +version: 2.9.1 +context: "Aktuelle Planung für kommende Features (ab WP16), Release-Strategie und Historie der abgeschlossenen WPs nach WP-14/15b." --- # Mindnet Active Roadmap -**Aktueller Stand:** v2.8.0 (Post-WP20/WP76) -**Fokus:** Visualisierung, Exploration & Cloud-Resilienz. - -## 1. Programmstatus - -Wir haben mit der Implementierung des Graph Explorers (WP19), der Smart Edge Allocation (WP15) und der hybriden Cloud-Resilienz (WP20) die Basis für ein intelligentes, robustes System gelegt. Der nächste Schritt (WP19a) vertieft die Analyse, während WP16 die "Eingangs-Intelligenz" erhöht. +**Aktueller Stand:** v2.9.1 (Post-WP14 / WP-15b) +**Fokus:** Modularisierung, Two-Pass Ingestion & Graph Intelligence. | Phase | Fokus | Status | | :--- | :--- | :--- | @@ -45,6 +41,8 @@ Eine Übersicht der implementierten Features zum schnellen Auffinden von Funktio | **WP-10** | Web UI | Streamlit-Frontend als Ersatz für das Terminal. | | **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-14** | **Modularisierung & Refactoring** | **Ergebnis:** Aufteilung in domänenspezifische Pakete (`database`, `ingestion`, `retrieval`, `graph`). Implementierung von Proxy-Adaptern für Abwärtskompatibilität und `registry.py` zur Lösung von Zirkelbezügen. | +| **WP-15b**| **Candidate-Based Validation** | **Ergebnis:** Implementierung des **Two-Pass Workflows**. Einführung des `LocalBatchCache` und binäre semantische Validierung von Kanten-Kandidaten zur Vermeidung von Halluzinationen. | | **WP-15** | Smart Edge Allocation | LLM-Filter für Kanten in Chunks + Traffic Control (Semaphore) + Strict Chunking. | | **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. | | **WP-20** | **Cloud Hybrid Mode & Resilienz** | **Ergebnis:** Integration von OpenRouter (Mistral 7B) & Gemini 2.5 Lite. Implementierung von WP-76 (Rate-Limit Wait) & Mistral-safe JSON Parsing. | @@ -59,6 +57,10 @@ Eine Übersicht der implementierten Features zum schnellen Auffinden von Funktio * **Quoten-Management:** Die Nutzung von Free-Tier Modellen (Mistral/OpenRouter) erfordert zwingend eine intelligente Rate-Limit-Erkennung (HTTP 429) mit automatisierten Wartezyklen, um Batch-Prozesse stabil zu halten. * **Parser-Robustheit:** Cloud-Modelle betten JSON oft in technische Steuerzeichen (``, `[OUT]`) ein. Ein robuster Extraktor mit Recovery-Logik ist essentiell zur Vermeidung von Datenverlust. +### 2.3 WP-14 & WP-15b Lessons Learned +* **Performance:** Der Pre-Scan (Pass 1) ist minimal invasiv, ermöglicht aber in Pass 2 eine drastische Reduktion der LLM-Kosten, da nur noch binär validiert werden muss, anstatt komplexe Extraktionen durchzuführen. +* **Wartbarkeit:** Durch die Paket-Struktur können DB-Adapter (z.B. für Qdrant) nun unabhängig von der Business-Logik (Scoring) aktualisiert werden. +* --- ## 3. Offene Workpackages (Planung) @@ -93,6 +95,20 @@ Diese Features stehen als nächstes an oder befinden sich in der Umsetzung. - Aufwand: Mittel - Komplexität: Niedrig/Mittel + + +### WP-13 – MCP-Integration & Agenten-Layer +**Status:** 🟡 Geplant +**Ziel:** mindnet als MCP-Server bereitstellen, damit Agenten (Claude Desktop, OpenAI) standardisierte Tools nutzen können. +* **Umfang:** MCP-Server mit Tools (`mindnet_query`, `mindnet_explain`, etc.). + +### WP-14 – Review / Refactoring / Dokumentation +**Status:** 🟡 Laufend (Phase E) +**Ziel:** Technische Schulden abbauen, die durch schnelle Feature-Entwicklung (WP15/WP19) entstanden sind. +* **Refactoring `chunker.py`:** Die Datei ist monolithisch geworden (Parsing, Strategien, LLM-Orchestrierung). + * *Lösung:* Aufteilung in ein Package `app/core/chunking/` mit Modulen (`strategies.py`, `orchestration.py`, `utils.py`). +* **Dokumentation:** Kontinuierliche Synchronisation von Code und Docs (v2.8 Stand). + ### WP-15b – Candidate-Based Edge Validation & Inheritance **Phase:** B/E (Refactoring & Semantic) **Status:** 🚀 Startklar (Ersatz für WP-15 Logik) @@ -113,19 +129,6 @@ Der bisherige WP-15 Ansatz litt unter Halluzinationen (erfundene Kantentypen), h * **Chunker-Update:** Implementierung einer `propagate_edges`-Logik für "by_heading" und "sliding_window" Strategien. * **Ingestion-Update:** Umstellung von `_perform_smart_edge_allocation` auf einen binären Validierungs-Prompt (VALID/INVALID). -### 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-14 – Review / Refactoring / Dokumentation -**Status:** 🟡 Laufend (Phase E) -**Ziel:** Technische Schulden abbauen, die durch schnelle Feature-Entwicklung (WP15/WP19) entstanden sind. -* **Refactoring `chunker.py`:** Die Datei ist monolithisch geworden (Parsing, Strategien, LLM-Orchestrierung). - * *Lösung:* Aufteilung in ein Package `app/core/chunking/` mit Modulen (`strategies.py`, `orchestration.py`, `utils.py`). -* **Dokumentation:** Kontinuierliche Synchronisation von Code und Docs (v2.8 Stand). ### WP-16 – Auto-Discovery & Intelligent Ingestion **Status:** 🟡 Geplant @@ -153,10 +156,13 @@ Der bisherige WP-15 Ansatz litt unter Halluzinationen (erfundene Kantentypen), h * **Feature:** Cronjob `check_graph_integrity.py`. * **Funktion:** Findet "Dangling Edges" (Links auf gelöschte Notizen) und repariert/löscht sie. -### WP-13 – MCP-Integration & Agenten-Layer -**Status:** 🟡 Geplant -**Ziel:** mindnet als MCP-Server bereitstellen, damit Agenten (Claude Desktop, OpenAI) standardisierte Tools nutzen können. -* **Umfang:** MCP-Server mit Tools (`mindnet_query`, `mindnet_explain`, etc.). +### 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-21 – Semantic Graph Routing & Canonical Edges **Status:** 🟡 Geplant diff --git a/docs/99_Archive/99_legacy_workpackages.md b/docs/99_Archive/99_legacy_workpackages.md index 7eed15f..dccb8da 100644 --- a/docs/99_Archive/99_legacy_workpackages.md +++ b/docs/99_Archive/99_legacy_workpackages.md @@ -91,4 +91,23 @@ Dieses Dokument dient als Referenz für die Entstehungsgeschichte von Mindnet v2 * **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 + * **UX:** Einführung von URL-Persistenz für Layout-Settings und CSS-basiertes Highlighting zur Vermeidung von Re-Renders. + + +## Phase E+: Architektur-Konsolidierung (WP-14) + +### WP-14 – Modularisierung & Paket-Struktur +* **Ziel:** Auflösung technischer Schulden und Beseitigung von Zirkelbezügen (Circular Imports). +* **Ergebnis:** + * **Domänen-Pakete:** Aufteilung der monolithischen `app/core/` Struktur in spezialisierte Pakete: `database/`, `ingestion/`, `retrieval/` und `graph/`. + * **Proxy-Pattern:** Einsatz von Fassaden-Modulen (z. B. `graph_adapter.py`) zur Aufrechterhaltung der Abwärtskompatibilität für bestehende API-Endpunkte. + * **Registry-Zentralisierung:** Auslagerung neutraler Hilfsfunktionen (wie `clean_llm_text`) in eine unabhängige `registry.py`, um Abhängigkeitsschleifen zwischen Diensten zu brechen. +* **Tech:** Einführung von `__init__.py` Exporten zur Definition sauberer Paket-Schnittstellen. + +### WP-15b – Two-Pass Ingestion & Candidate Validation +* **Problem:** Die ursprüngliche Smart Edge Extraktion (WP-15) war teuer und neigte zu Halluzinationen, da sie ohne globalen Kontext operierte. +* **Lösung:** Implementierung eines **Two-Pass Workflows**. + * **Pass 1 (Pre-Scan):** Schnelles Einlesen aller Notizen zur Erstellung eines `LocalBatchCache` (Metadaten & Summaries). + * **Pass 2 (Processing):** Gezielte semantische Verarbeitung nur für geänderte Dateien. +* **Feature:** **Binary Validation Gate**. Statt Kanten frei zu erfinden, validiert das LLM nun Kanten-Kandidaten aus einem Pool gegen den Kontext des `LocalBatchCache`. Dies garantiert 100% Konformität mit der Edge Registry. +* **Ergebnis:** Höhere Geschwindigkeit durch Reduktion komplexer LLM-Prompts auf binäre Entscheidungen (VALID/INVALID). \ No newline at end of file