Dokumentation WP14&WP15b
This commit is contained in:
parent
7fa9ce81bd
commit
fa909e2e7d
|
|
@ -2,13 +2,13 @@
|
||||||
doc_type: glossary
|
doc_type: glossary
|
||||||
audience: all
|
audience: all
|
||||||
status: active
|
status: active
|
||||||
version: 2.8.0
|
version: 2.8.1
|
||||||
context: "Zentrales Glossar für Mindnet v2.8. Enthält Definitionen zu Hybrid-Cloud Resilienz, WP-76 Quoten-Steuerung und Mistral-safe Parsing."
|
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
|
# 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
|
## Kern-Entitäten
|
||||||
|
|
||||||
|
|
@ -21,11 +21,13 @@ context: "Zentrales Glossar für Mindnet v2.8. Enthält Definitionen zu Hybrid-C
|
||||||
## Komponenten
|
## 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.
|
* **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.
|
* **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`).
|
* **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.
|
* **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.
|
* **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.
|
* **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
|
## 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).
|
* `explicit`: Vom Mensch gesetzt (Prio 1).
|
||||||
* `semantic_ai`: Von der KI im Turbo-Mode extrahiert und validiert (Prio 2).
|
* `semantic_ai`: Von der KI im Turbo-Mode extrahiert und validiert (Prio 2).
|
||||||
* `structure`: Durch System-Regeln/Matrix erzeugt (Prio 3).
|
* `structure`: Durch System-Regeln/Matrix erzeugt (Prio 3).
|
||||||
* **Smart Edge Allocation:** KI-Verfahren zur Relevanzprüfung von Links für spezifische Textabschnitte.
|
* **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`).
|
* **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.
|
||||||
|
|
@ -1,19 +1,19 @@
|
||||||
---
|
---
|
||||||
doc_type: technical_reference
|
doc_type: technical_reference
|
||||||
audience: developer, admin
|
audience: developer, admin
|
||||||
scope: configuration, env, registry, scoring, resilience
|
scope: configuration, env, registry, scoring, resilience, modularization
|
||||||
status: active
|
status: active
|
||||||
version: 2.8.0
|
version: 2.9.1
|
||||||
context: "Umfassende Referenztabellen für Umgebungsvariablen (inkl. Hybrid-Cloud & WP-76), YAML-Konfigurationen und die Edge Registry Struktur."
|
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
|
# 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`)
|
## 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 |
|
| 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. |
|
| `QDRANT_API_KEY` | *(leer)* | Optionaler Key für Absicherung. |
|
||||||
| `COLLECTION_PREFIX` | `mindnet` | Namensraum für Collections (erzeugt `{prefix}_notes` etc). |
|
| `COLLECTION_PREFIX` | `mindnet` | Namensraum für Collections (erzeugt `{prefix}_notes` etc). |
|
||||||
| `VECTOR_DIM` | `768` | **Muss 768 sein** (für Nomic Embeddings). |
|
| `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_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_VAULT_ROOT` | `./vault` | Basis-Pfad für Datei-Operationen. |
|
||||||
| `MINDNET_TYPES_FILE` | `config/types.yaml` | Pfad zur Typ-Registry. |
|
| `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_LLM_MODEL` | `phi3:mini` | Name des lokalen Chat-Modells (Ollama). |
|
||||||
| `MINDNET_EMBEDDING_MODEL` | `nomic-embed-text` | Name des Embedding-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. |
|
| `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_LLM_TIMEOUT` | `300.0` | Timeout in Sekunden für LLM-Anfragen. |
|
||||||
| `MINDNET_API_TIMEOUT` | `300.0` | Globales API-Timeout für das Frontend. |
|
| `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_LL_BACKGROUND_LIMIT`| `2` | **Traffic Control:** Max. parallele Hintergrund-Tasks (Semaphore). |
|
||||||
| `MINDNET_CHANGE_DETECTION_MODE` | `full` | `full` (Text + Meta) oder `body` (nur Text). |
|
| `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`)
|
## 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)
|
### 2.1 Konfigurations-Hierarchie (Override-Logik)
|
||||||
Seit Version 2.7.0 gilt für `chunking_profile` und `retriever_weight` folgende Priorität:
|
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.
|
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`.
|
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)
|
## 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`)
|
## 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
|
```yaml
|
||||||
version: 1.2
|
version: 1.2
|
||||||
|
|
@ -140,43 +146,36 @@ lifecycle_weights:
|
||||||
system: 0.0 # Hard Skip via Ingestion
|
system: 0.0 # Hard Skip via Ingestion
|
||||||
|
|
||||||
# Die nachfolgenden Werte überschreiben die Defaults aus app/core/retriever_config.
|
# 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:
|
edge_types:
|
||||||
# --- KATEGORIE 1: LOGIK-BOOSTS (Relevanz-Treiber) ---
|
# --- KATEGORIE 1: LOGIK-BOOSTS (Relevanz-Treiber) ---
|
||||||
# Diese Kanten haben die Kraft, das semantische Ranking aktiv umzugestalten.
|
blocks: 1.6
|
||||||
blocks: 1.6 # Kritisch: Risiken/Blocker müssen sofort sichtbar sein.
|
solves: 1.5
|
||||||
solves: 1.5 # Zielführend: Lösungen sind primäre Suchziele.
|
depends_on: 1.4
|
||||||
depends_on: 1.4 # Logisch: Harte fachliche Abhängigkeit.
|
resulted_in: 1.4
|
||||||
resulted_in: 1.4 # Kausal: Ergebnisse und unmittelbare Konsequenzen.
|
followed_by: 1.3
|
||||||
followed_by: 1.3 # Sequenziell (User): Bewusst gesteuerte Wissenspfade.
|
caused_by: 1.2
|
||||||
caused_by: 1.2 # Kausal: Ursachen-Bezug (Basis für Intent-Boost).
|
preceded_by: 1.1
|
||||||
preceded_by: 1.1 # Sequenziell (User): Rückwärts-Bezug in Logik-Ketten.
|
|
||||||
|
|
||||||
# --- KATEGORIE 2: QUALITATIVER KONTEXT (Stabilitäts-Stützen) ---
|
# --- KATEGORIE 2: QUALITATIVER KONTEXT (Stabilitäts-Stützen) ---
|
||||||
# Diese Kanten liefern wichtigen Kontext, ohne das Ergebnis zu verfälschen.
|
guides: 1.1
|
||||||
guides: 1.1 # Qualitativ: Prinzipien oder Werte leiten das Thema.
|
part_of: 1.1
|
||||||
part_of: 1.1 # Strukturell: Zieht übergeordnete Kontexte (Parents) mit hoch.
|
based_on: 0.8
|
||||||
based_on: 0.8 # Fundament: Bezug auf Basis-Werte (kalibriert auf Safe-Retrieval).
|
derived_from: 0.6
|
||||||
derived_from: 0.6 # Historisch: Dokumentiert die Herkunft von Wissen.
|
uses: 0.6
|
||||||
uses: 0.6 # Instrumentell: Genutzte Werkzeuge, Methoden oder Ressourcen.
|
|
||||||
|
|
||||||
# --- KATEGORIE 3: THEMATISCHE NÄHE (Ähnlichkeits-Signal) ---
|
# --- KATEGORIE 3: THEMATISCHE NÄHE (Ähnlichkeits-Signal) ---
|
||||||
# Diese Werte verhindern den "Drift" in fachfremde Bereiche.
|
similar_to: 0.4
|
||||||
similar_to: 0.4 # Analytisch: Thematische Nähe (oft KI-generiert).
|
|
||||||
|
|
||||||
# --- KATEGORIE 4: SYSTEM-NUDGES (Technische Struktur) ---
|
# --- KATEGORIE 4: SYSTEM-NUDGES (Technische Struktur) ---
|
||||||
# Reine Orientierungshilfen für das System; fast kein Einfluss auf das Ranking.
|
belongs_to: 0.2
|
||||||
belongs_to: 0.2 # System: Verknüpft Chunks mit der Note (Metadaten-Träger).
|
next: 0.1
|
||||||
next: 0.1 # System: Technische Lesereihenfolge der Absätze.
|
prev: 0.1
|
||||||
prev: 0.1 # System: Technische Lesereihenfolge der Absätze.
|
|
||||||
|
|
||||||
# --- KATEGORIE 5: WEICHE ASSOZIATIONEN (Rausch-Unterdrückung) ---
|
# --- KATEGORIE 5: WEICHE ASSOZIATIONEN (Rausch-Unterdrückung) ---
|
||||||
# Verhindert, dass lose Verknüpfungen das Ergebnis "verwässern".
|
references: 0.1
|
||||||
references: 0.1 # Assoziativ: Einfacher Querverweis oder Erwähnung.
|
related_to: 0.05
|
||||||
related_to: 0.05 # Minimal: Schwächste thematische Verbindung.
|
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 4. Edge Typen & Registry Referenz
|
## 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
|
### 4.1 Dateistruktur & Speicherort
|
||||||
Die Registry erwartet eine Markdown-Datei an folgendem Ort:
|
Die Registry erwartet eine Markdown-Datei an folgendem Ort:
|
||||||
* **Standard-Pfad:** `<MINDNET_VAULT_ROOT>/01_User_Manual/01_edge_vocabulary.md`.
|
* **Standard-Pfad:** `<MINDNET_VAULT_ROOT>/_system/dictionary/edge_vocabulary.md`.
|
||||||
* **Custom-Pfad:** Kann via `.env` Variable `MINDNET_VOCAB_PATH` überschrieben werden.
|
* **Custom-Pfad:** Kann via `.env` Variable `MINDNET_VOCAB_PATH` überschrieben werden.
|
||||||
|
|
||||||
### 4.2 Aufbau des Dictionaries (Markdown-Schema)
|
### 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. |
|
| **`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)
|
### 4.3 Verfügbare Kanten-Typen (System-Standard)
|
||||||
|
|
||||||
| System-Typ (Canonical) | Erlaubte Aliasse (User) | Beschreibung |
|
| System-Typ (Canonical) | Erlaubte Aliasse (User) | Beschreibung |
|
||||||
| :--------------------- | :--------------------------------------------------- | :-------------------------------------- |
|
| :--- | :--- | :--- |
|
||||||
| **`caused_by`** | `ausgelöst_durch`, `wegen`, `ursache_ist` | Kausalität: A löst B aus. |
|
| **`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. |
|
| **`derived_from`** | `abgeleitet_von`, `quelle`, `inspiriert_durch` | Herkunft: A stammt von B. |
|
||||||
| **`based_on`** | `basiert_auf`, `fundament`, `grundlage` | Fundament: B baut auf A auf. |
|
| **`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. |
|
| **`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. |
|
| **`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. |
|
| **`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. |
|
| **`blocks`** | `blockiert`, `verhindert`, `risiko_für` | Blocker: A verhindert B. |
|
||||||
| **`uses`** | `nutzt`, `verwendet`, `tool` | Werkzeug: A nutzt B. |
|
| **`uses`** | `nutzt`, `verwendet`, `tool` | Werkzeug: A nutzt B. |
|
||||||
| **`guides`** | `steuert`, `leitet`, `orientierung` | Soft-Dependency: A gibt Richtung für B. |
|
| **`guides`** | `steuert`, `leitet`, `orientierung` | Soft-Dependency: A gibt Richtung für B. |
|
||||||
| **`followed_by`** | `danach`, `folgt`, `nachfolger`, `followed_by` | Prozess: A -> B. |
|
| **`followed_by`** | `danach`, `folgt`, `nachfolger`, `followed_by` | Prozess: A -> B. |
|
||||||
| **`preceeded_by`** | `davor`, `vorgänger`, `preceded_by` | Prozess: B <- A. |
|
| **`preceeded_by`** | `davor`, `vorgänger`, `preceded_by` | Prozess: B <- A. |
|
||||||
| **`related_to`** | `siehe_auch`, `kontext`, `thematisch` | Lose Assoziation. |
|
| **`related_to`** | `siehe_auch`, `kontext`, `thematisch` | Lose Assoziation. |
|
||||||
| **`similar_to`** | `ähnlich_wie`, `vergleichbar` | Synonym / Ähnlichkeit. |
|
| **`similar_to`** | `ähnlich_wie`, `vergleichbar` | Synonym / Ähnlichkeit. |
|
||||||
| **`references`** | *(Kein Alias)* | Standard-Verweis (Fallback). |
|
| **`references`** | *(Kein Alias)* | Standard-Verweis (Fallback). |
|
||||||
| **`resulted_in`** | `ergebnis`, `resultat`, `erzeugt` | Herkunft: A erzeugt Ergebnis B |
|
| **`resulted_in`** | `ergebnis`, `resultat`, `erzeugt` | Herkunft: A erzeugt Ergebnis B |
|
||||||
|
|
||||||
**ACHTUNG!** Die Kantentypen
|
**ACHTUNG!** Die Kantentypen **belongs_to**, **next** und **prev** dürfen nicht vom Nutzer gesetzt werden.
|
||||||
**belongs_to**, **next** und **prev** dürfen nicht vom Nutzer gesetzt werden
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
||||||
## 5. Decision Engine (`decision_engine.yaml`)
|
## 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.
|
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:
|
BITTE WÄGE FAKTEN GEGEN FOLGENDE WERTE, PRINZIPIEN UND ZIELE AB:
|
||||||
|
|
||||||
# 3. Empathie / "Ich"-Modus
|
# 3. Empathie / "Ich"-Modus
|
||||||
|
|
||||||
```
|
```
|
||||||
|
|
||||||
*Richtwert für Kanten-Boosts: 0.1 (Abwertung) bis 3.0+ (Dominanz gegenüber Text-Match).*
|
|
||||||
|
|
@ -3,15 +3,15 @@ doc_type: technical_reference
|
||||||
audience: developer, architect
|
audience: developer, architect
|
||||||
scope: database, qdrant, schema
|
scope: database, qdrant, schema
|
||||||
status: active
|
status: active
|
||||||
version: 2.7.0
|
version: 2.8.0
|
||||||
context: "Exakte Definition der Datenmodelle (Payloads) in Qdrant und Index-Anforderungen."
|
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)
|
# Technisches Datenmodell (Qdrant Schema)
|
||||||
|
|
||||||
## 1. Collections & Namenskonvention
|
## 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:
|
Das System nutzt folgende drei Collections:
|
||||||
* `{prefix}_notes`: Metadaten der Dateien.
|
* `{prefix}_notes`: Metadaten der Dateien.
|
||||||
|
|
@ -28,9 +28,10 @@ Repräsentiert die Metadaten einer Markdown-Datei (1:1 Beziehung).
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"note_id": "string (keyword)", // UUIDv5 (deterministisch) oder Slug
|
"note_id": "string (keyword)", // UUIDv5 (deterministisch via NAMESPACE_URL)
|
||||||
"title": "string (text)", // Titel aus Frontmatter
|
"title": "string (text)", // Titel aus Frontmatter
|
||||||
"type": "string (keyword)", // Logischer Typ (z.B. 'project', 'concept')
|
"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)
|
"retriever_weight": "float", // Effektive Wichtigkeit (Frontmatter > Type > Default)
|
||||||
"chunk_profile": "string", // Effektives Profil (Frontmatter > Type > Default)
|
"chunk_profile": "string", // Effektives Profil (Frontmatter > Type > Default)
|
||||||
"edge_defaults": ["string"], // Liste der aktiven Default-Kanten
|
"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)
|
"updated": "integer", // Timestamp (File Modification Time)
|
||||||
"fulltext": "string (no-index)", // Gesamter Text (nur für Recovery/Export)
|
"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": {
|
"hashes": {
|
||||||
"body:parsed:canonical": "string", // Hash nur über den Text-Body
|
"body:parsed:canonical": "string", // Hash nur über den Text-Body
|
||||||
"full:parsed:canonical": "string" // Hash über Text + Metadaten (Tags, Title, Config)
|
"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:
|
Es müssen Payload-Indizes für folgende Felder existieren:
|
||||||
* `note_id`
|
* `note_id`
|
||||||
* `type`
|
* `type`
|
||||||
|
* `status`
|
||||||
* `tags`
|
* `tags`
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
@ -61,7 +63,7 @@ Es müssen Payload-Indizes für folgende Felder existieren:
|
||||||
Die atomare Sucheinheit. Enthält den Vektor.
|
Die atomare Sucheinheit. Enthält den Vektor.
|
||||||
|
|
||||||
**Vektor-Konfiguration:**
|
**Vektor-Konfiguration:**
|
||||||
* Modell: `nomic-embed-text`
|
* Modell: `nomic-embed-text` (via Ollama oder Cloud)
|
||||||
* Dimension: **768**
|
* Dimension: **768**
|
||||||
* Metrik: Cosine Similarity
|
* Metrik: Cosine Similarity
|
||||||
|
|
||||||
|
|
@ -69,7 +71,7 @@ Die atomare Sucheinheit. Enthält den Vektor.
|
||||||
|
|
||||||
```json
|
```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
|
"note_id": "string (keyword)", // Foreign Key zur Note
|
||||||
"type": "string (keyword)", // Kopie aus Note (Denormalisiert für Filterung)
|
"type": "string (keyword)", // Kopie aus Note (Denormalisiert für Filterung)
|
||||||
"text": "string (text)", // Reintext für Anzeige (ohne Overlap)
|
"text": "string (text)", // Reintext für Anzeige (ohne Overlap)
|
||||||
|
|
@ -121,3 +123,4 @@ Es müssen Payload-Indizes für folgende Felder existieren:
|
||||||
* `kind`
|
* `kind`
|
||||||
* `scope`
|
* `scope`
|
||||||
* `note_id`
|
* `note_id`
|
||||||
|
```
|
||||||
|
|
@ -1,71 +1,77 @@
|
||||||
---
|
---
|
||||||
doc_type: technical_reference
|
doc_type: technical_reference
|
||||||
audience: developer, devops
|
audience: developer, devops
|
||||||
scope: backend, ingestion, smart_edges, edge_registry
|
scope: backend, ingestion, smart_edges, edge_registry, modularization
|
||||||
status: active
|
status: active
|
||||||
version: 2.8.1
|
version: 2.9.0
|
||||||
context: "Detaillierte technische Beschreibung der Import-Pipeline, Mistral-safe Parsing und Deep Fallback Resilienz."
|
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
|
# 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)
|
## 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:**
|
1. **Trigger & Async Dispatch:**
|
||||||
* **API (`/save`):** Nimmt Request entgegen, validiert und startet Background-Task ("Fire & Forget"). Antwortet sofort mit `202/Queued`.
|
* **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.
|
* **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):**
|
3. **Frontmatter Check & Hard Skip (WP-22):**
|
||||||
* Extraktion von `status` und `type`.
|
* 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.
|
* Validierung der Pflichtfelder (`id`, `title`) für alle anderen Dateien.
|
||||||
4. **Edge Registry Initialisierung (WP-22):**
|
4. **Edge Registry Initialisierung (WP-22):**
|
||||||
* Laden der Singleton-Instanz der `EdgeRegistry`.
|
* Laden der Singleton-Instanz der `EdgeRegistry`.
|
||||||
* Validierung der Vokabular-Datei unter `MINDNET_VOCAB_PATH`.
|
* Validierung der Vokabular-Datei unter `MINDNET_VOCAB_PATH`.
|
||||||
5. **Config Resolution:**
|
5. **Config Resolution (WP-14):**
|
||||||
* Bestimmung von `chunking_profile` und `retriever_weight`.
|
* Bestimmung von `chunking_profile` und `retriever_weight` via zentraler `TypeRegistry`.
|
||||||
* **Priorität:** 1. Frontmatter (Override) -> 2. `types.yaml` (Type) -> 3. Global Default.
|
* **Priorität:** 1. Frontmatter (Override) -> 2. `types.yaml` (Type) -> 3. Global Default.
|
||||||
6. **Note-Payload generieren:**
|
6. **LocalBatchCache & Summary Generation (WP-15b):**
|
||||||
* Erstellen des JSON-Objekts inklusive `status` (für Scoring).
|
* Erstellung von Kurz-Zusammenfassungen für jede Note.
|
||||||
* **Multi-Hash Calculation:** Berechnet Hashtabellen für `body` (nur Text) und `full` (Text + Metadaten).
|
* Speicherung im `batch_cache` als Referenzrahmen für die spätere Kantenvalidierung.
|
||||||
7. **Change Detection:**
|
|
||||||
* Vergleich des Hashes mit Qdrant.
|
### Phase 2: Semantic Processing & Persistence (Pass 2)
|
||||||
* Strategie wählbar via ENV `MINDNET_CHANGE_DETECTION_MODE` (`full` oder `body`).
|
7. **Note-Payload & Multi-Hash (WP-15b):**
|
||||||
8. **Chunking anwenden:** Zerlegung des Textes basierend auf dem ermittelten Profil (siehe Kap. 3).
|
* Erstellen des JSON-Objekts inklusive `status`.
|
||||||
9. **Smart Edge Allocation (WP-20):**
|
* **Multi-Hash Calculation:** Berechnet Hashtabellen für `body` (nur Text) und `full` (Text + Metadaten) zur präzisen Änderungskontrolle.
|
||||||
* Wenn `enable_smart_edge_allocation: true`: Der `SemanticAnalyzer` sendet Chunks an das LLM.
|
8. **Change Detection:**
|
||||||
* **Traffic Control:** Request nutzt `priority="background"`. Semaphore drosselt die Last.
|
* Vergleich des aktuellen Hashes mit den Daten in Qdrant (Collection `{prefix}_notes`).
|
||||||
* **Resilienz (Quota Handling):** Erkennt HTTP 429 (Rate-Limit) und pausiert kontrolliert (via `LLM_RATE_LIMIT_WAIT`), bevor ein Cloud-Retry erfolgt.
|
* Strategie wählbar via ENV `MINDNET_CHANGE_DETECTION_MODE` (`full` oder `body`). Unveränderte Dateien werden hier final übersprungen.
|
||||||
* **Mistral-safe Parsing:** Automatisierte Bereinigung von BOS-Tokens (`<s>`) und Framework-Tags (`[OUT]`) sowie Recovery-Logik für Dictionaries (Suche nach `edges`, `links`, `results`, `kanten`).
|
9. **Purge Old Artifacts (WP-14):**
|
||||||
* **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.
|
* Bei Änderungen löscht `purge_artifacts()` via `app.core.ingestion.ingestion_db` alle alten Chunks und Edges der Note.
|
||||||
10. **Inline-Kanten finden:** Parsing von `[[rel:...]]`.
|
* Die Namensauflösung erfolgt nun über das modularisierte `database`-Paket.
|
||||||
11. **Alias-Auflösung & Kanonisierung (WP-22):**
|
10. **Chunking anwenden:** Zerlegung des Textes basierend auf dem ermittelten Profil (siehe Kap. 3).
|
||||||
* Jede Kante wird via `edge_registry.resolve()` normalisiert.
|
11. **Smart Edge Allocation & Semantic Validation (WP-15b):**
|
||||||
* Aliase (z.B. `basiert_auf`) werden zu kanonischen Typen (z.B. `based_on`) aufgelöst.
|
* 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 (<s>, [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.
|
* Unbekannte Typen werden in `unknown_edges.jsonl` protokolliert.
|
||||||
12. **Callout-Kanten finden:** Parsing von `> [!edge]`.
|
14. **Default- & Strukturkanten:** Anwendung der `edge_defaults` und Erzeugung von Systemkanten (`belongs_to`, `next`, `prev`).
|
||||||
13. **Default- & Matrix-Edges erzeugen:** Anwendung der `edge_defaults` aus Registry und Matrix-Logik.
|
15. **Embedding (Async):** Generierung der Vektoren via `nomic-embed-text` (768 Dimensionen).
|
||||||
14. **Strukturkanten erzeugen:** `belongs_to`, `next`, `prev`.
|
16. **Database Sync (WP-14):** Batch-Upsert aller Points in die Collections `{prefix}_chunks` und `{prefix}_edges` über die zentrale Infrastruktur.
|
||||||
15. **Embedding (Async):** Generierung via `nomic-embed-text` (768 Dim).
|
|
||||||
16. **Diagnose:** Integritäts-Check nach dem Lauf.
|
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 2. Betrieb & CLI Befehle
|
## 2. Betrieb & CLI Befehle
|
||||||
|
|
||||||
### 2.1 Standard-Betrieb (Inkrementell)
|
### 2.1 Standard-Betrieb (Inkrementell)
|
||||||
Für regelmäßige Updates (Cronjob). Erkennt Änderungen via Hash.
|
Erkennt Änderungen via Multi-Hash.
|
||||||
|
|
||||||
```bash
|
```bash
|
||||||
export QDRANT_URL="http://localhost:6333"
|
export QDRANT_URL="http://localhost:6333"
|
||||||
export COLLECTION_PREFIX="mindnet"
|
export COLLECTION_PREFIX="mindnet"
|
||||||
# Steuert, wann eine Datei als "geändert" gilt
|
|
||||||
export MINDNET_CHANGE_DETECTION_MODE="full"
|
export MINDNET_CHANGE_DETECTION_MODE="full"
|
||||||
|
|
||||||
# Nutzt das Venv der Produktionsumgebung
|
# Nutzt das Venv der Produktionsumgebung
|
||||||
|
|
@ -78,20 +84,13 @@ export MINDNET_CHANGE_DETECTION_MODE="full"
|
||||||
```
|
```
|
||||||
|
|
||||||
> **[!WARNING] Purge-Before-Upsert**
|
> **[!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)
|
### 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
|
```bash
|
||||||
# 0. Modell sicherstellen
|
# --force ignoriert alle Hashes und erzwingt den vollständigen Two-Pass Workflow
|
||||||
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
|
|
||||||
python3 -m scripts.import_markdown --vault ./vault --prefix "mindnet" --apply --force
|
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
|
## 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 |
|
| Profil | Strategie | Parameter | Einsatzgebiet |
|
||||||
| :--- | :--- | :--- | :--- |
|
| :--- | :--- | :--- | :--- |
|
||||||
| `sliding_short` | `sliding_window` | Max: 350, Target: 200 | Kurze Logs, Chats, Risiken. |
|
| `sliding_short` | `sliding_window` | Max: 350, Target: 200 | Kurze Logs, Chats. |
|
||||||
| `sliding_standard` | `sliding_window` | Max: 650, Target: 450 | Massendaten (Journal, Quellen). |
|
| `sliding_standard` | `sliding_window` | Max: 650, Target: 450 | Standard-Wissen. |
|
||||||
| `sliding_smart_edges`| `sliding_window` | Max: 600, Target: 400 | Fließtexte mit hohem Wert (Projekte). |
|
| `sliding_smart_edges`| `sliding_window` | Max: 600, Target: 400 | Fließtexte (Projekte). |
|
||||||
| `structured_smart_edges` | `by_heading` | `strict: false` (Soft) | Strukturierte Texte, Merging erlaubt. |
|
| `structured_smart_edges` | `by_heading` | `strict: false` | Strukturierte Texte. |
|
||||||
| `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). |
|
|
||||||
|
|
||||||
### 3.2 Die `by_heading` Logik (v2.9 Hybrid)
|
### 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).
|
* **Split Level:** Definiert die Tiefe (z.B. `2` = H1 & H2 triggern Split).
|
||||||
* **Modus "Strict" (`strict_heading_split: true`):**
|
* **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.
|
* **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.
|
* *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)
|
## 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. |
|
| **1** | Wikilink | `explicit:wikilink` | **1.00** | Harte menschliche Setzung. |
|
||||||
| **2** | Inline | `inline:rel` | **0.95** | Typisierte menschliche Kante. |
|
| **2** | Inline | `inline:rel` | **0.95** | Typisierte menschliche Kante. |
|
||||||
| **3** | Callout | `callout:edge` | **0.90** | Explizite Meta-Information. |
|
| **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. |
|
| **5** | Type Default | `edge_defaults` | **0.70** | Heuristik aus der Registry. |
|
||||||
| **6** | Struktur | `structure` | **1.00** | System-interne Verkettung (`belongs_to`). |
|
| **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
|
## 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):**
|
**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.
|
||||||
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
|
|
||||||
```
|
|
||||||
|
|
@ -3,13 +3,13 @@ doc_type: technical_reference
|
||||||
audience: developer, data_scientist
|
audience: developer, data_scientist
|
||||||
scope: backend, retrieval, scoring, modularization
|
scope: backend, retrieval, scoring, modularization
|
||||||
status: active
|
status: active
|
||||||
version: 2.7.1
|
version: 2.9.0
|
||||||
context: "Detaillierte Dokumentation der Scoring-Algorithmen, inklusive WP-22 Lifecycle-Modifier, Intent-Boosting und Modularisierung."
|
context: "Detaillierte Dokumentation der Scoring-Algorithmen, inklusive WP-22 Lifecycle-Modifier, Intent-Boosting und WP-14 Modularisierung."
|
||||||
---
|
---
|
||||||
|
|
||||||
# Retrieval & Scoring Algorithmen
|
# 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)
|
## 1. Scoring Formel (v2.7.0)
|
||||||
|
|
||||||
|
|
@ -37,18 +37,19 @@ $$
|
||||||
* **Zweck:** Belohnt Chunks, die "im Thema" vernetzt sind.
|
* **Zweck:** Belohnt Chunks, die "im Thema" vernetzt sind.
|
||||||
|
|
||||||
**4. Centrality Bonus ($B_{cent}$):**
|
**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).
|
* **Logik:** Vereinfachte PageRank-Metrik (Degree Centrality).
|
||||||
* **Zweck:** Belohnt "Hubs" mit vielen Verbindungen zu anderen Treffern.
|
* **Zweck:** Belohnt "Hubs" mit vielen Verbindungen zu anderen Treffern.
|
||||||
|
|
||||||
### Die WP-22 Erweiterungen (v2.7.0)
|
### Die WP-22 Erweiterungen (v2.7.0)
|
||||||
|
|
||||||
**5. Status Modifier ($M_{status}$):**
|
**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.
|
* **Zweck:** Bestraft unfertiges Wissen (Drafts) oder bevorzugt stabiles Wissen.
|
||||||
* **Werte (Auftrag WP-22):** * `stable`: **1.2** (Bonus für Qualität).
|
* **Werte (Auftrag WP-22):** * `stable`: **1.2** (Belohnung für verifiziertes Wissen).
|
||||||
* `draft`: **0.5** (Malus für Entwürfe).
|
* `active`: **1.0** (Standard-Gewichtung).
|
||||||
* `system`: Exkludiert (siehe Ingestion).
|
* `draft`: **0.5** (Malus für unfertige Fragmente).
|
||||||
|
* `system`: Exkludiert (siehe Ingestion Lifecycle Filter).
|
||||||
|
|
||||||
**6. Intent Boost ($B_{intent}$):**
|
**6. Intent Boost ($B_{intent}$):**
|
||||||
* **Herkunft:** Dynamische Injektion durch die Decision Engine basierend auf der Nutzerfrage.
|
* **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)**
|
**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.
|
* Diese bilden die "Seeds" für den Graphen.
|
||||||
|
|
||||||
**Phase 2: Graph Expansion**
|
**Phase 2: Graph Expansion**
|
||||||
* Nutze `graph_adapter.expand(seeds, depth=1)`.
|
* Nutze die Fassade `app.core.graph_adapter.expand(seeds, depth=1)`.
|
||||||
* Lade direkte Nachbarn aus der `_edges` Collection.
|
* Diese delegiert an `app.core.graph.graph_subgraph`, um direkte Nachbarn aus der `_edges` Collection zu laden.
|
||||||
* Konstruiere einen `NetworkX`-Graphen im Speicher.
|
* Konstruktion eines in-memory Graphen zur Berechnung topologischer Boni.
|
||||||
|
|
||||||
**Phase 3: Re-Ranking (Modular)**
|
**Phase 3: Re-Ranking (Modular)**
|
||||||
* Der Orchestrator übergibt den Graphen und die Seeds an die `ScoringEngine`.
|
* Der Orchestrator übergibt den Graphen und die Seeds an die `ScoringEngine` (`retriever_scoring.py`).
|
||||||
* Berechne Boni ($B_{edge}$, $B_{cent}$) sowie die neuen Lifecycle- und Intent-Modifier.
|
* 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 Top-Resultate (z.B. 5).
|
* Sortierung absteigend nach `TotalScore` und Limitierung auf die angeforderten Top-Resultate.
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
## 3. Explanation Layer (WP-22 Update)
|
## 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:**
|
**Erweiterte JSON-Struktur:**
|
||||||
|
|
||||||
```json
|
```json
|
||||||
{
|
{
|
||||||
"score_breakdown": {
|
"score_breakdown": {
|
||||||
"semantic": 0.85,
|
"semantic_contribution": 0.85,
|
||||||
"type_boost": 1.0,
|
"edge_contribution": 0.4,
|
||||||
"lifecycle_modifier": 0.5,
|
"centrality_contribution": 0.1,
|
||||||
"edge_bonus": 0.4,
|
"raw_semantic": 0.85,
|
||||||
"intent_boost": 0.5,
|
"raw_edge_bonus": 0.3,
|
||||||
"centrality": 0.1
|
"raw_centrality": 0.1,
|
||||||
|
"node_weight": 1.0,
|
||||||
|
"status_multiplier": 1.2,
|
||||||
|
"graph_boost_factor": 1.5
|
||||||
},
|
},
|
||||||
"reasons": [
|
"reasons": [
|
||||||
"Hohe textuelle Übereinstimmung (>0.85).",
|
{
|
||||||
"Status 'draft' reduziert Relevanz (Modifier 0.5).",
|
"kind": "semantic",
|
||||||
"Wird referenziert via 'caused_by' (Intent-Bonus 0.5).",
|
"message": "Hohe textuelle Übereinstimmung (>0.85).",
|
||||||
"Bevorzugt, da Typ 'decision' (Gewicht 1.0)."
|
"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`)
|
## 4. Konfiguration (`retriever.yaml`)
|
||||||
|
|
||||||
Steuert die Gewichtung der mathematischen Komponenten.
|
Steuert die globale Gewichtung der mathematischen Komponenten.
|
||||||
|
|
||||||
```yaml
|
```yaml
|
||||||
scoring:
|
scoring:
|
||||||
semantic_weight: 1.0 # Basis-Relevanz
|
semantic_weight: 1.0 # Basis-Relevanz (W_sem)
|
||||||
edge_weight: 0.7 # Graphen-Einfluss
|
edge_weight: 0.7 # Graphen-Einfluss (W_edge)
|
||||||
centrality_weight: 0.5 # Hub-Einfluss
|
centrality_weight: 0.5 # Hub-Einfluss (W_cent)
|
||||||
|
|
||||||
# WP-22 Lifecycle Konfiguration (Abgleich mit Auftrag)
|
# WP-22 Lifecycle Konfiguration
|
||||||
lifecycle_weights:
|
lifecycle_weights:
|
||||||
stable: 1.2 # Bonus für Qualität
|
stable: 1.2 # Modifier für Qualität
|
||||||
draft: 0.5 # Malus für Entwürfe
|
draft: 0.5 # Modifier für Entwürfe
|
||||||
|
|
||||||
# Kanten-Gewichtung für den Edge-Bonus (Basis)
|
# Kanten-Gewichtung für den Edge-Bonus (Basis)
|
||||||
edge_weights:
|
edge_weights:
|
||||||
|
|
|
||||||
|
|
@ -1,10 +1,10 @@
|
||||||
---
|
---
|
||||||
doc_type: developer_guide
|
doc_type: developer_guide
|
||||||
audience: developer
|
audience: developer
|
||||||
scope: workflow, testing, architecture, modules
|
scope: workflow, testing, architecture, modules, modularization
|
||||||
status: active
|
status: active
|
||||||
version: 2.6.1
|
version: 2.9.1
|
||||||
context: "Umfassender Guide für Entwickler: Architektur, Modul-Interna (Deep Dive), Setup, Git-Workflow und Erweiterungs-Anleitungen."
|
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
|
# 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)
|
- [Kern-Philosophie](#kern-philosophie)
|
||||||
- [2. Architektur](#2-architektur)
|
- [2. Architektur](#2-architektur)
|
||||||
- [2.1 High-Level Übersicht](#21-high-level-übersicht)
|
- [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)
|
- [B. Retrieval (Read)](#b-retrieval-read)
|
||||||
- [C. Visualisierung (Graph)](#c-visualisierung-graph)
|
- [C. Visualisierung (Graph)](#c-visualisierung-graph)
|
||||||
- [3. Physische Architektur](#3-physische-architektur)
|
- [3. Physische Architektur](#3-physische-architektur)
|
||||||
|
|
@ -84,23 +82,28 @@ graph TD
|
||||||
API["main.py"]
|
API["main.py"]
|
||||||
RouterChat["Chat / RAG"]
|
RouterChat["Chat / RAG"]
|
||||||
RouterIngest["Ingest / Write"]
|
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
|
end
|
||||||
|
|
||||||
subgraph "Infrastructure & Services"
|
subgraph "Infrastructure & Services"
|
||||||
LLM["Ollama (Phi3/Nomic)"]
|
LLM["Ollama / Cloud (Hybrid)"]
|
||||||
DB[("Qdrant Vector DB")]
|
DB[("Qdrant Vector DB")]
|
||||||
FS["File System (.md)"]
|
FS["File System (.md)"]
|
||||||
end
|
end
|
||||||
|
|
||||||
User <--> UI
|
User <--> UI
|
||||||
UI -- "REST (Chat, Save, Feedback)" --> API
|
UI -- "REST Call" --> API
|
||||||
UI -. "Direct Read (Graph Viz Performance)" .-> DB
|
PkgRet -- "Direct Query" --> PkgDb
|
||||||
API -- "Embeddings & Completion" --> LLM
|
PkgIng -- "Process & Write" --> PkgDb
|
||||||
API -- "Read/Write" --> DB
|
PkgDb -- "API" --> DB
|
||||||
API -- "Read/Write (Source of Truth)" --> FS
|
API -- "Inference" --> LLM```
|
||||||
```
|
|
||||||
|
|
||||||
### 2.2 Datenfluss-Muster
|
### 2.2 Datenfluss-Muster
|
||||||
|
|
||||||
|
|
@ -108,14 +111,12 @@ graph TD
|
||||||
Vom Markdown zur Vektor-Datenbank.
|
Vom Markdown zur Vektor-Datenbank.
|
||||||
```mermaid
|
```mermaid
|
||||||
graph LR
|
graph LR
|
||||||
MD["Markdown File"] --> Parser("Parser")
|
MD["Markdown File"] --> Pass1["Pass 1: Pre-Scan"]
|
||||||
Parser --> Chunker("Chunker")
|
Pass1 --> Cache[("LocalBatchCache<br/>(Titles/Summaries)")]
|
||||||
Chunker -- "Text Chunks" --> SemAn{"SemanticAnalyzer<br/>(LLM)"}
|
MD --> Pass2["Pass 2: Processing"]
|
||||||
SemAn -- "Smart Edges" --> Embedder("Embedder")
|
Cache -- "Context" --> SmartEdges{"Smart Edge<br/>Validation"}
|
||||||
Embedder --> DB[("Qdrant<br/>Points")]
|
SmartEdges --> Embedder("Embedder")
|
||||||
|
Embedder --> DB[("Qdrant Points")]
|
||||||
style DB fill:#f9f,stroke:#333,stroke-width:2px
|
|
||||||
style SemAn fill:#ff9,stroke:#333,stroke-width:2px
|
|
||||||
```
|
```
|
||||||
|
|
||||||
#### B. Retrieval (Read)
|
#### B. Retrieval (Read)
|
||||||
|
|
@ -123,17 +124,10 @@ Die hybride Suche für Chat & RAG.
|
||||||
```mermaid
|
```mermaid
|
||||||
graph LR
|
graph LR
|
||||||
Query(["Query"]) --> Embed("Embedding")
|
Query(["Query"]) --> Embed("Embedding")
|
||||||
Embed --> Hybrid{"Hybrid Search"}
|
Embed --> Seed["Seed Search (Vector)"]
|
||||||
|
Seed --> Expand{"Graph Expansion"}
|
||||||
subgraph Search Components
|
Expand --> Scoring["Scoring Engine (WP-22)"]
|
||||||
Vec["Vector Score"]
|
Scoring --> Rank("Final Ranking")
|
||||||
Graph["Graph/Edge Bonus"]
|
|
||||||
end
|
|
||||||
|
|
||||||
Vec --> Hybrid
|
|
||||||
Graph --> Hybrid
|
|
||||||
|
|
||||||
Hybrid --> Rank("Re-Ranking")
|
|
||||||
Rank --> Ctx["LLM Context"]
|
Rank --> Ctx["LLM Context"]
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
@ -170,6 +164,12 @@ Das System ist modular aufgebaut. Hier ist die detaillierte Analyse aller Kompon
|
||||||
mindnet/
|
mindnet/
|
||||||
├── app/
|
├── app/
|
||||||
│ ├── core/ # Business Logic & Algorithms
|
│ ├── 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)
|
│ ├── routers/ # API Interface (FastAPI)
|
||||||
│ ├── services/ # External Integrations (LLM, DB)
|
│ ├── services/ # External Integrations (LLM, DB)
|
||||||
│ ├── models/ # Pydantic DTOs
|
│ ├── 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/type_registry.py` | **Redundant.** Logik in `ingestion.py` integriert. | 🗑️ Löschen |
|
||||||
| `app/core/env_vars.py` | **Veraltet.** Ersetzt durch `config.py`. | 🗑️ 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/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 |
|
||||||
|
|
||||||
---
|
---
|
||||||
|
|
||||||
|
|
|
||||||
|
|
@ -2,18 +2,14 @@
|
||||||
doc_type: roadmap
|
doc_type: roadmap
|
||||||
audience: product_owner, developer
|
audience: product_owner, developer
|
||||||
status: active
|
status: active
|
||||||
version: 2.8.0
|
version: 2.9.1
|
||||||
context: "Aktuelle Planung für kommende Features (ab WP16), Release-Strategie und Historie der abgeschlossenen WPs."
|
context: "Aktuelle Planung für kommende Features (ab WP16), Release-Strategie und Historie der abgeschlossenen WPs nach WP-14/15b."
|
||||||
---
|
---
|
||||||
|
|
||||||
# Mindnet Active Roadmap
|
# Mindnet Active Roadmap
|
||||||
|
|
||||||
**Aktueller Stand:** v2.8.0 (Post-WP20/WP76)
|
**Aktueller Stand:** v2.9.1 (Post-WP14 / WP-15b)
|
||||||
**Fokus:** Visualisierung, Exploration & Cloud-Resilienz.
|
**Fokus:** Modularisierung, Two-Pass Ingestion & Graph Intelligence.
|
||||||
|
|
||||||
## 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.
|
|
||||||
|
|
||||||
| Phase | Fokus | Status |
|
| 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-10** | Web UI | Streamlit-Frontend als Ersatz für das Terminal. |
|
||||||
| **WP-10a**| Draft Editor | GUI-Komponente zum Bearbeiten und Speichern generierter Notizen. |
|
| **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-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-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`.<br>**Graph Engines:** Parallelbetrieb von Cytoscape (COSE) und Agraph.<br>**Tools:** "Single Source of Truth" Editor, Persistenz via URL. |
|
| **WP-19** | Graph Visualisierung | **Frontend Modularisierung:** Umbau auf `ui_*.py`.<br>**Graph Engines:** Parallelbetrieb von Cytoscape (COSE) und Agraph.<br>**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. |
|
| **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.
|
* **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 (`<s>`, `[OUT]`) ein. Ein robuster Extraktor mit Recovery-Logik ist essentiell zur Vermeidung von Datenverlust.
|
* **Parser-Robustheit:** Cloud-Modelle betten JSON oft in technische Steuerzeichen (`<s>`, `[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)
|
## 3. Offene Workpackages (Planung)
|
||||||
|
|
@ -93,6 +95,20 @@ Diese Features stehen als nächstes an oder befinden sich in der Umsetzung.
|
||||||
- Aufwand: Mittel
|
- Aufwand: Mittel
|
||||||
- Komplexität: Niedrig/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
|
### WP-15b – Candidate-Based Edge Validation & Inheritance
|
||||||
**Phase:** B/E (Refactoring & Semantic)
|
**Phase:** B/E (Refactoring & Semantic)
|
||||||
**Status:** 🚀 Startklar (Ersatz für WP-15 Logik)
|
**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.
|
* **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).
|
* **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
|
### WP-16 – Auto-Discovery & Intelligent Ingestion
|
||||||
**Status:** 🟡 Geplant
|
**Status:** 🟡 Geplant
|
||||||
|
|
@ -153,10 +156,13 @@ Der bisherige WP-15 Ansatz litt unter Halluzinationen (erfundene Kantentypen), h
|
||||||
* **Feature:** Cronjob `check_graph_integrity.py`.
|
* **Feature:** Cronjob `check_graph_integrity.py`.
|
||||||
* **Funktion:** Findet "Dangling Edges" (Links auf gelöschte Notizen) und repariert/löscht sie.
|
* **Funktion:** Findet "Dangling Edges" (Links auf gelöschte Notizen) und repariert/löscht sie.
|
||||||
|
|
||||||
### WP-13 – MCP-Integration & Agenten-Layer
|
### WP-19a – Graph Intelligence & Discovery (Sprint-Fokus)
|
||||||
**Status:** 🟡 Geplant
|
**Status:** 🚀 Startklar
|
||||||
**Ziel:** mindnet als MCP-Server bereitstellen, damit Agenten (Claude Desktop, OpenAI) standardisierte Tools nutzen können.
|
**Ziel:** Vom "Anschauen" zum "Verstehen". Deep-Dive Werkzeuge für den Graphen.
|
||||||
* **Umfang:** MCP-Server mit Tools (`mindnet_query`, `mindnet_explain`, etc.).
|
* **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
|
### WP-21 – Semantic Graph Routing & Canonical Edges
|
||||||
**Status:** 🟡 Geplant
|
**Status:** 🟡 Geplant
|
||||||
|
|
|
||||||
|
|
@ -92,3 +92,22 @@ Dieses Dokument dient als Referenz für die Entstehungsgeschichte von Mindnet v2
|
||||||
* **Graph Explorer:** Einführung von `st-cytoscape` für stabile, nicht-überlappende Layouts (COSE) als Ergänzung zur Legacy-Engine (Agraph).
|
* **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.
|
* **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.
|
* **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).
|
||||||
Loading…
Reference in New Issue
Block a user