doku
This commit is contained in:
1 parent
0d71f41a13
commit
2cd3605017
8 files changed
+334
-263
No files matched your search
@@ -1,19 +1,19 @@
|
||||
---
|
||||
doc_type: technical_reference
|
||||
audience: developer, admin
|
||||
scope: configuration, env
|
||||
scope: configuration, env, registry, scoring
|
||||
status: active
|
||||
version: 2.7.0
|
||||
context: "Referenztabellen für Umgebungsvariablen und YAML-Konfigurationen."
|
||||
version: 2.7.2
|
||||
context: "Umfassende Referenztabellen für Umgebungsvariablen, YAML-Konfigurationen und die Edge Registry Struktur."
|
||||
---
|
||||
|
||||
# Konfigurations-Referenz
|
||||
|
||||
Dieses Dokument beschreibt die Steuerungsdateien von Mindnet.
|
||||
Dieses Dokument beschreibt alle Steuerungsdateien von Mindnet. In der Version 2.7 wurde die Konfiguration professionalisiert, um die Edge Registry und dynamische Scoring-Parameter (Lifecycle & Intent) zu unterstützen.
|
||||
|
||||
## 1. Environment Variablen (`.env`)
|
||||
|
||||
Diese Variablen steuern die Infrastruktur, Timeouts und Feature-Flags.
|
||||
Diese Variablen steuern die Infrastruktur, Pfade und globale Timeouts.
|
||||
|
||||
| Variable | Default | Beschreibung |
|
||||
| :--- | :--- | :--- |
|
||||
@@ -21,6 +21,8 @@ Diese Variablen steuern die Infrastruktur, Timeouts und Feature-Flags.
|
||||
| `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_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. Dient als Fallback-Basis, falls `MINDNET_VOCAB_PATH` nicht gesetzt ist. |
|
||||
| `MINDNET_TYPES_FILE` | `config/types.yaml` | Pfad zur Typ-Registry. |
|
||||
| `MINDNET_RETRIEVER_CONFIG`| `config/retriever.yaml`| Pfad zur Scoring-Konfiguration. |
|
||||
| `MINDNET_DECISION_CONFIG` | `config/decision_engine.yaml` | Pfad zur Router & Intent Config. |
|
||||
@@ -30,9 +32,8 @@ Diese Variablen steuern die Infrastruktur, Timeouts und Feature-Flags.
|
||||
| `MINDNET_OLLAMA_URL` | `http://127.0.0.1:11434`| URL zum LLM-Server. |
|
||||
| `MINDNET_LLM_TIMEOUT` | `300.0` | Timeout in Sekunden (Erhöht für CPU Cold-Starts). |
|
||||
| `MINDNET_API_TIMEOUT` | `300.0` | Frontend Timeout (Erhöht für Smart Edge Wartezeiten). |
|
||||
| `MINDNET_LLM_BACKGROUND_LIMIT`| `2` | **Traffic Control (Neu):** Max. parallele Import-Tasks (Semaphore). |
|
||||
| `MINDNET_VAULT_ROOT` | `./vault` | Pfad für Write-Back Operationen (Drafts). |
|
||||
| `MINDNET_CHANGE_DETECTION_MODE` | `full` | **Change Detection (Neu):** `full` (Text + Meta) oder `body` (nur Text). |
|
||||
| `MINDNET_LLM_BACKGROUND_LIMIT`| `2` | **Traffic Control:** Max. parallele Hintergrund-Tasks (Semaphore). |
|
||||
| `MINDNET_CHANGE_DETECTION_MODE` | `full` | `full` (Text + Meta) oder `body` (nur Text). |
|
||||
|
||||
---
|
||||
|
||||
@@ -42,102 +43,119 @@ Steuert das Import-Verhalten, Chunking und die Kanten-Logik pro Typ.
|
||||
|
||||
### 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.
|
||||
* *Beispiel:* `chunking_profile: structured_smart_edges_strict` im Header einer Notiz erzwingt diesen Splitter, egal welcher Typ eingestellt ist.
|
||||
2. **Type Config:** Der Standardwert für den `type` (z.B. `concept`) aus `types.yaml`.
|
||||
2. **Type Config:** Der Standardwert für den `type` aus `types.yaml`.
|
||||
3. **Global Default:** Fallback aus `defaults` in `types.yaml`.
|
||||
|
||||
### 2.2 Typ-Referenztabelle
|
||||
### 2.2 Typ-Referenztabelle (Vollständig)
|
||||
|
||||
| Typ (`type`) | Chunk Profile (Standard) | Retriever Weight | Smart Edges? | Beschreibung |
|
||||
| Typ (`type`) | Chunk Profile (Standard) | Retriever Weight ($W_{type}$) | Smart Edges? | Beschreibung |
|
||||
| :--- | :--- | :--- | :--- | :--- |
|
||||
| **concept** | `sliding_smart_edges` | 0.60 | Ja | Abstrakte Begriffe. |
|
||||
| **project** | `sliding_smart_edges` | 0.97 | Ja | Aktive Vorhaben. |
|
||||
| **decision** | `structured_smart_edges_strict` | 1.00 | Ja | Entscheidungen (ADRs). Atomar. |
|
||||
| **experience** | `sliding_smart_edges` | 0.90 | Ja | Persönliche Learnings. |
|
||||
| **journal** | `sliding_standard` | 0.80 | Nein | Logs / Dailies. |
|
||||
| **value** | `structured_smart_edges_strict` | 1.00 | Ja | Werte/Prinzipien. Atomar. |
|
||||
| **decision** | `structured_strict` | 1.00 | Ja | Entscheidungen. Atomar. |
|
||||
| **value** | `structured_strict` | 1.00 | Ja | Werte/Prinzipien. Atomar. |
|
||||
| **project** | `sliding_smart` | 0.97 | Ja | Aktive Vorhaben. |
|
||||
| **experience** | `sliding_smart` | 0.90 | Ja | Persönliche Learnings. |
|
||||
| **concept** | `sliding_smart` | 0.60 | Ja | Abstrakte Begriffe. |
|
||||
| **principle** | `structured_L3` | 0.95 | Nein | Prinzipien (Tiefer Split). |
|
||||
| **belief** | `sliding_short` | 0.90 | Nein | Glaubenssätze. |
|
||||
| **risk** | `sliding_short` | 0.90 | Nein | Risiken. |
|
||||
| **journal** | `sliding_standard` | 0.80 | Nein | Logs / Dailies. |
|
||||
| **person** | `sliding_standard` | 0.50 | Nein | Profile. |
|
||||
| **source** | `sliding_standard` | 0.50 | Nein | Externe Quellen. |
|
||||
| **event** | `sliding_standard` | 0.60 | Nein | Meetings. |
|
||||
| **goal** | `sliding_smart_edges` | 0.95 | Nein | Strategische Ziele. |
|
||||
| **belief** | `sliding_short` | 0.90 | Nein | Glaubenssätze. |
|
||||
| **profile** | `structured_smart_edges_strict` | 0.70 | Nein | Rollenprofile. Strict Split. |
|
||||
| **principle** | `structured_smart_edges_strict_L3`| 0.95 | Nein | Prinzipien. Tiefer Split (H3) für Mikro-Prinzipien. |
|
||||
| **task** | `sliding_short` | 0.80 | Nein | Aufgaben. |
|
||||
| **glossary** | `sliding_short` | 0.40 | Nein | Begriffsdefinitionen. |
|
||||
| **default** | `sliding_standard` | 1.00 | Nein | Fallback. |
|
||||
| **default** | `sliding_standard` | 1.00 | Nein | Fallback für alle anderen. |
|
||||
|
||||
*Hinweis: `Smart Edges?` entspricht dem YAML-Key `enable_smart_edge_allocation: true`.*
|
||||
*Richtwert für $W_{type}$: 0.1 (minimale Relevanz/Filter) bis 1.0 (maximale Relevanz).*
|
||||
|
||||
---
|
||||
|
||||
## 3. Retriever Config (`retriever.yaml`)
|
||||
|
||||
Steuert die Gewichtung der Scoring-Formel (WP04a).
|
||||
|
||||
**Beispielkonfiguration:**
|
||||
Steuert die Gewichtung der Scoring-Formel und die neuen Lifecycle-Modifier.
|
||||
|
||||
```yaml
|
||||
scoring:
|
||||
semantic_weight: 1.0 # Basis-Relevanz (Cosine Similarity)
|
||||
edge_weight: 0.7 # Einfluss des Graphen (Bonus)
|
||||
centrality_weight: 0.5 # Einfluss von Hubs
|
||||
|
||||
centrality_weight: 0.5 # Einfluss von Hubs (Zentralität)
|
||||
|
||||
# WP-22 Lifecycle Modifier (Multiplikativ auf Semantik)
|
||||
lifecycle_weights:
|
||||
stable: 1.2 # Bonus: Geprüftes Wissen wird 20% höher gewichtet
|
||||
draft: 0.5 # Malus: Entwürfe werden auf 50% gedämpft
|
||||
system: 0.0 # Ausschluss aus dem Index
|
||||
|
||||
# Kanten-spezifische Basis-Gewichtung (Ohne Intent-Boost)
|
||||
edge_weights:
|
||||
# Multiplikatoren für den Edge-Bonus
|
||||
depends_on: 1.5 # Harte Abhängigkeiten stark gewichten
|
||||
blocks: 1.5 # Risiken stark gewichten
|
||||
caused_by: 1.2 # Kausalitäten stärken
|
||||
related_to: 0.5 # Weiche Themen schwächer gewichten
|
||||
blocks: 1.5 # Blocker/Risiken stark gewichten
|
||||
caused_by: 1.2 # Kausalitäten moderat stärken
|
||||
based_on: 1.3 # Werte-Bezug stärken
|
||||
related_to: 0.5 # Weiche Assoziation schwächen
|
||||
references: 0.8 # Standard-Referenzen
|
||||
based_on: 1.3 # Werte-Bezug
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 4. Edge Typen Referenz
|
||||
## 4. Edge Typen & Registry Referenz
|
||||
|
||||
Definiert die Semantik der `kind`-Felder in der Edge-Collection.
|
||||
Die `EdgeRegistry` ist die **Single Source of Truth** für das Vokabular.
|
||||
|
||||
| Kind | Symmetrisch? | Herkunft (Primär) | Bedeutung |
|
||||
### 4.1 Dateistruktur & Speicherort
|
||||
Die Registry erwartet eine Markdown-Datei an folgendem Ort:
|
||||
* **Standard-Pfad:** `<MINDNET_VAULT_ROOT>/01_User_Manual/01_edge_vocabulary.md`.
|
||||
* **Custom-Pfad:** Kann via `.env` Variable `MINDNET_VOCAB_PATH` überschrieben werden.
|
||||
|
||||
### 4.2 Aufbau des Dictionaries (Markdown-Schema)
|
||||
Die Datei muss eine Markdown-Tabelle enthalten, die vom Regex-Parser gelesen wird.
|
||||
|
||||
**Erwartetes Format:**
|
||||
```markdown
|
||||
| System-Typ (Canonical) | Erlaubte Aliasse (User) | Beschreibung |
|
||||
| :--- | :--- | :--- |
|
||||
| **`based_on`** | `basiert_auf`, `fundament` | Fundament: B baut auf A auf. |
|
||||
| **`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)
|
||||
|
||||
| Kind (Canonical) | Symmetrisch? | Herkunft | Bedeutung |
|
||||
| :--- | :--- | :--- | :--- |
|
||||
| `references` | Nein | Wikilink | Standard-Verweis. "Erwähnt X". |
|
||||
| `references` | Nein | Wikilink | Standard-Verweis ("Erwähnt X"). |
|
||||
| `belongs_to` | Nein | Struktur | Chunk gehört zu Note. |
|
||||
| `next` / `prev` | Ja | Struktur | Lesereihenfolge. |
|
||||
| `depends_on` | Nein | Inline / Default | Harte Abhängigkeit. |
|
||||
| `related_to` | Ja | Callout / Default | Thematische Nähe. |
|
||||
| `similar_to` | Ja | Inline | Inhaltliche Ähnlichkeit. |
|
||||
| `caused_by` | Nein | Inline | Kausalität. |
|
||||
| `solves` | Nein | Inline | Lösung für ein Problem. |
|
||||
| `blocks` | Nein | Inline | Blockade / Risiko. |
|
||||
| `derived_from` | Nein | Matrix | Herkunft (z.B. Prinzip -> Buch). |
|
||||
| `based_on` | Nein | Matrix | Fundament (z.B. Erfahrung -> Wert). |
|
||||
| `uses` | Nein | Matrix | Nutzung (z.B. Projekt -> Tool). |
|
||||
| `caused_by` | Nein | Inline | Kausalität: A löst B aus. |
|
||||
| `based_on` | Nein | Matrix | Fundament: A fußt auf B. |
|
||||
| `blocks` | Nein | Inline | Blocker: A verhindert B. |
|
||||
| `solves` | Nein | Inline | Lösung: A ist Lösung für Problem B. |
|
||||
| `next` / `prev` | Ja | Struktur | Sequenzielle Lesereihenfolge. |
|
||||
|
||||
---
|
||||
|
||||
## 5. Decision Engine (`decision_engine.yaml`)
|
||||
|
||||
Steuert den Hybrid Router (WP06). Definiert, welche Keywords welche Strategie auslösen.
|
||||
Steuert den Hybrid Router und das dynamische Intent-Boosting (WP-22).
|
||||
|
||||
**Beispielauszug:**
|
||||
**Beispielauszug für Intent-Boosting:**
|
||||
|
||||
```yaml
|
||||
# Strategie-Definitionen
|
||||
strategies:
|
||||
DECISION:
|
||||
description: "Hilfe bei Entscheidungen"
|
||||
inject_types: ["value", "principle", "goal", "risk"] # Strategic Retrieval
|
||||
llm_fallback_enabled: true
|
||||
|
||||
INTERVIEW:
|
||||
description: "Wissenserfassung"
|
||||
trigger_keywords: ["erstellen", "neu", "anlegen", "festhalten"]
|
||||
|
||||
intents:
|
||||
EMPATHY:
|
||||
description: "Emotionaler Support"
|
||||
description: "Emotionaler Support / Werte-Fokus"
|
||||
boost_edges:
|
||||
based_on: 2.0 # Verdoppelt den Einfluss von Werte-Kanten
|
||||
related_to: 1.5 # Stärkt assoziative Bezüge
|
||||
inject_types: ["experience", "belief"]
|
||||
```
|
||||
|
||||
WHY:
|
||||
description: "Ursachenanalyse (Kausalität)"
|
||||
boost_edges:
|
||||
caused_by: 2.5 # Massiver Boost für Kausalitätsketten
|
||||
derived_from: 1.8 # Fokus auf die Herkunft
|
||||
```
|
||||
|
||||
*Richtwert für Kanten-Boosts: 0.1 (Abwertung) bis 3.0+ (Dominanz gegenüber Text-Match).*
|
||||
Reference in new issue
Block a user