mindnet/docs/03_Technical_References/03_tech_configuration.md

---
doc_type: technical_reference
audience: developer, admin
scope: configuration, env, registry, scoring, resilience, modularization, agentic_rag, moe, lazy_prompts
status: active
version: 3.1.1
context: "Umfassende Referenztabellen für Umgebungsvariablen (inkl. Hybrid-Cloud & WP-76), YAML-Konfigurationen, Edge Registry Struktur, WP-25 Multi-Stream RAG, WP-25a Mixture of Experts (MoE) und WP-25b Lazy-Prompt-Orchestration unter Berücksichtigung von WP-14."
---

# Konfigurations-Referenz

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. Seit der Modularisierung in WP-14 unterstützen sie zudem die explizite Benennung von Vektoren für verschiedene Collections.

| Variable | Default | Beschreibung |
| :--- | :--- | :--- |
| `QDRANT_URL` | `http://localhost:6333` | URL zur Vektor-DB API. |
| `QDRANT_API_KEY` | *(leer)* | Optionaler Key für Absicherung. |
| `COLLECTION_PREFIX` | `mindnet` | Namensraum für Collections (erzeugt `{prefix}_notes` etc). |
| `MINDNET_PREFIX` | *(leer)* | **Alternative zu COLLECTION_PREFIX.** Falls gesetzt, wird dieser Wert verwendet. |
| `VECTOR_DIM` | `768` | **Muss 768 sein** (für Nomic Embeddings). |
| `MINDNET_DISTANCE` | `Cosine` | Metrik für Vektor-Ähnlichkeit (`Cosine`, `Euclidean`, `Dot`). |
| `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_master` | **Achtung:** Standard ist `./vault_master`, nicht `./vault`! Basis-Pfad für Datei-Operationen. |
| `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. |
| `MINDNET_PROMPTS_PATH` | `config/prompts.yaml` | Pfad zu LLM Prompts. |
| `MINDNET_LLM_PROVIDER` | `openrouter` | **Neu (WP-20):** Aktiver Provider (`openrouter`, `gemini`, `ollama`). |
| `MINDNET_LLM_FALLBACK` | `true` | **Neu (WP-20):** Aktiviert automatischen Ollama-Fallback bei Cloud-Fehlern. |
| `MINDNET_LLM_RATE_LIMIT_WAIT`| `60.0` | **Neu (WP-20):** Wartezeit in Sekunden bei HTTP 429 (Rate Limit). |
| `MINDNET_LLM_RATE_LIMIT_RETRIES`| `3` | **Neu (WP-20):** Anzahl Cloud-Retries vor lokalem Fallback. |
| `GOOGLE_API_KEY` | *(Key)* | API Key für Google AI Studio. |
| `MINDNET_GEMINI_MODEL` | `gemini-2.5-flash-lite` | **Update 2025:** Optimiertes Lite-Modell für hohe Quoten. |
| `OPENROUTER_API_KEY` | *(Key)* | API Key für OpenRouter Integration. |
| `OPENROUTER_MODEL` | `mistralai/mistral-7b-instruct:free` | **Update 2025:** Verifiziertes Free-Modell für strukturierte Extraktion. |
| `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. |
| `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. 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.  **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)

Das System euriert Informationen in drei funktionalen Streams. Wähle den Typ danach aus, in welchem Bereich deines „Digitalen Zwillings“ die Information wirken soll.

### 2.2.1 Identity Stream (Der Kern / Das „Warum“)
Dieser Stream definiert deine stabilen Merkmale und inneren Kompasse.

| Typ | Gewicht | Chunking Profil | Zweck & Inhalt |
| :--- | :--- | :--- | :--- |
| **`value`** | 1.00 | `structured_strict` | Fundamentale Werte und moralische Maßstäbe. |
| **`principle`** | 0.95 | `structured_strict_L3` | Handlungsleitlinien mit tiefer Hierarchie (H3-Split). |
| **`trait`** | 1.10 | `structured_strict` | Charakterliche Stärken und Talente. |
| **`belief`** | 0.90 | `sliding_short` | Tiefe Überzeugungen über dich und die Gesellschaft. |
| **`profile`** | 0.70 | `structured_strict` | Rollenidentitäten (z. B. Vater, Mentor, Unternehmer). |
| **`need`** | 1.05 | `sliding_smart_edges` | Psychologische Grundbedürfnisse (z. B. Autonomie, Bindung). |
| **`motivation`**| 0.95 | `sliding_smart_edges` | Innere Antreiber und Quellen deiner Energie. |
| **`boundary`** | 0.90 | `sliding_smart_edges` | Deine persönlichen Grenzen und Integritäts-Leitplanken. |
| **`bias`** | 0.80 | `sliding_short` | Bekannte kognitive Verzerrungen und Denkfallen. |

### 2.2.2 Action Stream (Die Dynamik / Das „Was“)
Dieser Stream umfasst alles, was auf Umsetzung, Planung und aktuelle Zustände zielt.

| Typ | Gewicht | Chunking Profil | Zweck & Inhalt |
| :--- | :--- | :--- | :--- |
| **`project`** | 0.97 | `sliding_smart_edges` | Aktive Vorhaben mit Mission und Zielsetzung. |
| **`goal`** | 0.95 | `sliding_smart_edges` | Strategische Nordsterne und Zielzustände. |
| **`decision`** | 1.00 | `structured_strict` | Getroffene Entscheidungen (ADR-Logik). |
| **`risk`** | 0.85 | `sliding_short` | Potenzielle Gefahren und Bedrohungsszenarien. |
| **`obstacle`** | 1.00 | `structured_strict` | Aktuelle Hürden, Ängste und Blockaden. |
| **`task`** | 0.80 | `sliding_short` | Operative Aufgaben und Definition of Done. |
| **`skill`** | 0.90 | `sliding_smart_edges` | Fertigkeiten, Lernpfade und Meisterschaft. |
| **`habit`** | 0.85 | `sliding_short` | Routinen, Automatismen und Verhaltensmuster. |
| **`idea`** | 0.70 | `sliding_short` | Flüchtige Einfälle und Rohmaterial für Projekte. |
| **`state`** | 0.60 | `sliding_short` | Momentane Verfassung, Stimmung und Energielevel. |

### 2.2.3 History & Basis Stream (Die Evidenz / Das „Wann“)
Dieser Stream speichert deine Erlebnisse, Fakten und externes Wissen als Belege.

| Typ | Gewicht | Chunking Profil | Zweck & Inhalt |
| :--- | :--- | :--- | :--- |
| **`insight`** | 1.20 | `sliding_smart_edges` | Hochrelevante Erkenntnisse und Verhaltensmuster. |
| **`experience`**| 1.10 | `sliding_smart_edges` | Biografische Lektionen und prägende Erlebnisse. |
| **`event`** | 0.60 | `sliding_standard` | Chronologische Protokolle und Ereignisse. |
| **`journal`** | 0.80 | `sliding_standard` | Tägliche Logs und ungefilterte Gedanken. |
| **`person`** | 0.50 | `sliding_standard` | Kontaktprofile und soziale Vernetzung. |
| **`source`** | 0.50 | `sliding_standard` | Externe Quellen wie Bücher, Videos oder Artikel. |
| **`concept`** | 0.60 | `sliding_smart_edges` | Fachbegriffe, Theorien und zeitloses Wissen. |
| **`glossary`** | 0.40 | `sliding_short` | Kurze Begriffsdefinitionen. |
| **`default`** | 1.00 | `sliding_standard` | Fallback für alle nicht klassifizierten Notizen. |

*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 und die neuen Lifecycle-Modifier. Seit WP-14 ist die mathematische Engine im Paket `app.core.retrieval` gekapselt.

```yaml
version: 1.2

scoring:
  # W_sem: skaliert den Term (semantic_score * retriever_weight)
  # Empfehlung Startwert: 1.0  → Semantik bleibt Hauptsignal
  semantic_weight: 1.0

  # W_edge: skaliert edge_bonus aus dem Subgraph
  # Empfehlung: 0.8  → Graph ist deutlich spürbar, aber überstimmt Semantik nicht komplett
  edge_weight: 0.8

  # W_cent: skaliert centrality_bonus (Knoten-Zentralität im Subgraph)
  # Empfehlung: 0.5  → zentrale Knoten werden bevorzugt, aber moderat
  centrality_weight: 0.5

# WP-22 Stellschraube: Lifecycle (Status-basiertes Scoring)
# Bonus für verifiziertes Wissen, Malus für Entwürfe
lifecycle_weights:
  stable: 1.2   # +20% Bonus
  active: 1.0   # Standardwert
  draft: 0.5    # -50% Malus
  system: 0.0   # Hard Skip via Ingestion

# Die nachfolgenden Werte überschreiben die Defaults aus app/core/retriever_config.
edge_types:
  # --- KATEGORIE 1: LOGIK-BOOSTS (Relevanz-Treiber) ---
  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) ---
  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) ---
  similar_to: 0.4

  # --- KATEGORIE 4: SYSTEM-NUDGES (Technische Struktur) ---
  belongs_to: 0.2
  next: 0.1
  prev: 0.1

  # --- KATEGORIE 5: WEICHE ASSOZIATIONEN (Rausch-Unterdrückung) ---
  references: 0.1
  related_to: 0.05
```

---

## 4. Edge Typen & Registry Referenz

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:** `<MINDNET_VAULT_ROOT>/_system/dictionary/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. |
```

### 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 |

**ACHTUNG!** Die Kantentypen **belongs_to**, **next** und **prev** dürfen nicht vom Nutzer gesetzt werden.

---

## 5. Decision Engine (`decision_engine.yaml` v3.1.6)

Die Decision Engine fungiert als zentraler **Agentic Orchestrator** für die Intent-Erkennung und das dynamische Multi-Stream Retrieval-Routing (WP-25). Sie bestimmt, wie das System auf eine Nutzeranfrage reagiert, welche Wissens-Streams aktiviert werden und wie die Ergebnisse synthetisiert werden.

### 5.1 Intent Recognition: Hybrid-Routing (WP-25)
Das System nutzt einen **Hybrid-Modus** mit Keyword Fast-Path und LLM Slow-Path:

1.  **Fast Path (Keyword Trigger):** Das System scannt die Anfrage nach definierten `trigger_keywords`. Wird ein Treffer gefunden, wird die entsprechende Strategie sofort ohne LLM-Einsatz gewählt (z.B. "Soll ich" → `DECISION`).
2.  **Type Keywords:** Prüft `detection_keywords` aus `types.yaml` für Interview-Modus (z.B. "Projekt" + "neu" → `INTERVIEW`).
3.  **Slow Path (LLM Router):** Wenn kein Keyword matcht und `llm_fallback_enabled: true` gesetzt ist, analysiert ein LLM die Nachricht mittels Few-Shot Prompting (`intent_router_v1`).

#### LLM Router Konfiguration
Der Router nutzt den `llm_router_prompt`, um Anfragen in eine der fünf Kern-Strategien (`FACT`, `DECISION`, `EMPATHY`, `CODING`, `INTERVIEW`) zu klassifizieren.

| Einstellung | Wert | Beschreibung |
| :--- | :--- | :--- |
| `llm_fallback_enabled` | `true` | Aktiviert die KI-basierte Klassifizierung, falls Keywords fehlen. |
| `llm_router_prompt` | *(Template)* | Enthält die Strategie-Definitionen und Few-Shot Beispiele für den LLM-Entscheidungsweg. |

---

### 5.2 Multi-Stream Konfiguration (WP-25)

Seit WP-25 nutzt die Decision Engine eine **Stream-Library** mit spezialisierten Wissens-Streams:

**Stream-Library (`streams_library`):**
* **`values_stream`:** Identität, Ethik und Prinzipien (filter_types: `value`, `principle`, `belief`, `trait`, `boundary`, `need`, `motivation`)
* **`facts_stream`:** Operative Daten (filter_types: `project`, `decision`, `task`, `goal`, `event`, `state`)
* **`biography_stream`:** Persönliche Erfahrungen (filter_types: `experience`, `journal`, `profile`, `person`)
* **`risk_stream`:** Hindernisse und Gefahren (filter_types: `risk`, `obstacle`, `bias`)
* **`tech_stream`:** Technisches Wissen (filter_types: `concept`, `source`, `glossary`, `idea`, `insight`, `skill`, `habit`)

**Stream-Parameter:**
* **`query_template`:** Transformiert die ursprüngliche Anfrage für spezialisierte Suche (z.B. "Welche meiner Werte und Prinzipien betreffen: {query}")
* **`filter_types`:** Strikte Synchronisation mit `types.yaml` (v2.7.0)
* **`top_k`:** Anzahl der Treffer pro Stream (z.B. 5 für Values, 3 für Risk)
* **`edge_boosts`:** Individuelle Edge-Gewichtung pro Stream (z.B. `guides: 3.0` für Values Stream)

**Strategie-Komposition (`strategies`):**
Jede Strategie definiert, welche Streams aktiviert werden:

* **`use_streams`:** Liste der Stream-Keys, die parallel abgefragt werden (z.B. `["values_stream", "facts_stream", "risk_stream"]` für `DECISION`)
* **`prompt_template`:** Template-Key aus `prompts.yaml` für die Wissens-Synthese (z.B. `decision_synthesis_v1`)
* **`prepend_instruction`:** Optional: Zusätzliche Anweisung für das LLM (z.B. "Analysiere die Fakten vor dem Hintergrund meiner Werte")
* **`preferred_provider`:** Optional: Provider-Präferenz für diese Strategie (z.B. `gemini` für DECISION)

### 5.3 Strategie-Mechaniken (Graph Shaping)
Jede Strategie definiert mehrere Hebel, um das Ergebnis zu beeinflussen:

* **`use_streams`:** Aktiviert parallele Wissens-Streams (WP-25).
* **`edge_boosts`:** Erhöht die Gewichtung spezifischer Kanten-Typen in der Scoring-Formel. Dies ermöglicht es dem Graphen, die Textsuche situativ zu "überstimmen".
* **`prepend_instruction`:** Injiziert eine spezifische Systemanweisung in das LLM-Prompt, um den Antwortstil anzupassen (z. B. "Wäge Fakten gegen Werte ab").

---

### 5.4 Übersicht der Strategien (WP-25)

| Strategie | Fokus | Aktive Streams | Bevorzugte Kanten (`edge_boosts`) |
| :--- | :--- | :--- | :--- |
| **FACT_WHAT** | Wissensabfrage & Listen | `facts_stream`, `tech_stream`, `biography_stream` | `part_of` (2.0), `depends_on` (1.5), `implemented_in` (1.5) |
| **FACT_WHEN** | Zeitpunkte & Termine | `facts_stream`, `biography_stream`, `tech_stream` | `part_of` (2.0), `depends_on` (1.5) |
| **DECISION** | Rat, Strategie & Abwägung | `values_stream`, `facts_stream`, `risk_stream` | `blocks` (2.5), `impacts` (2.0), `risk_of` (2.5) |
| **EMPATHY** | Emotionale Resonanz | `biography_stream`, `values_stream` | `related_to` (1.5), `experienced_in` (2.0) |
| **CODING** | Programmierung & Syntax | `tech_stream`, `facts_stream` | `uses` (2.5), `implemented_in` (3.0) |
| **INTERVIEW** | Erfassung neuer Daten | *(Keine Streams)* | *(Keine)* |

---

### 5.5 Der Interview-Modus & Schemas
Die Strategie `INTERVIEW` dient der strukturierten Datenerfassung.

* **Trigger:** Aktiviert durch Phrasen wie "neue notiz", "festhalten" oder "dokumentieren" (Type Keywords aus `types.yaml`).
* **Schema-Logik:** Nutzt das `default`-Schema mit den Feldern `Titel`, `Thema/Inhalt` und `Tags`, sofern kein spezifisches Typ-Schema aus der `types.yaml` greift.
* **Dynamik:** In diesem Modus wird der Fokus vom Retrieval (Wissen finden) auf die Extraktion (Wissen speichern) verschoben.
* **Streams:** Keine Streams aktiviert (leere `use_streams` Liste).

> **Hinweis:** Da spezifische Schemas für Projekte oder Erfahrungen direkt in der `types.yaml` definiert werden, dient die `decision_engine.yaml` hier primär als Fallback für generische Datenaufnahmen.

### 5.6 Prompts-Konfiguration (`prompts.yaml` v3.2.2 - WP-25b)

Seit WP-25b nutzt MindNet eine **hierarchische Prompt-Struktur** mit Lazy-Loading. Prompts werden erst zur Laufzeit geladen, basierend auf dem exakt aktiven Modell.

**Hierarchische Template-Struktur:**
```yaml
decision_synthesis_v1:
  # Level 1: Modell-spezifisch (höchste Priorität)
  "google/gemini-2.0-flash-exp:free": |
    WERTE & PRINZIPIEN (Identität):
    {values_stream}
    
    OPERATIVE FAKTEN (Realität):
    {facts_stream}
    
    RISIKO-RADAR (Konsequenzen):
    {risk_stream}
    
    ENTSCHEIDUNGSFRAGE:
    {query}
    Nutze deine hohe Reasoning-Kapazität für eine tiefe Synthese.
  
  "meta-llama/llama-3.3-70b-instruct:free": |
    Erstelle eine fundierte Synthese für die Frage: "{query}"
    Nutze die Daten: {values_stream}, {facts_stream} und {risk_stream}.
    Trenne klare Fakten von Erfahrungen. Bleibe strikt beim bereitgestellten Kontext.
  
  # Level 2: Provider-Fallback (mittlere Priorität)
  openrouter: |
    WERTE & PRINZIPIEN (Identität):
    {values_stream}
    
    OPERATIVE FAKTEN (Realität):
    {facts_stream}
    
    RISIKO-RADAR (Konsequenzen):
    {risk_stream}
    
    ENTSCHEIDUNGSFRAGE:
    {query}
  
  ollama: |
    WERTE & PRINZIPIEN (Identität):
    {values_stream}
    
    OPERATIVE FAKTEN (Realität):
    {facts_stream}
    
    RISIKO-RADAR (Konsequenzen):
    {risk_stream}
    
    ENTSCHEIDUNGSFRAGE:
    {query}
  
  # Level 3: Global Default (niedrigste Priorität)
  default: |
    Synthetisiere die folgenden Informationen für: {query}
    {values_stream} | {facts_stream} | {risk_stream}
```

**Auflösungs-Logik:**
1. **Level 1:** Exakte Modell-ID (z.B. `google/gemini-2.0-flash-exp:free`)
2. **Level 2:** Provider-Fallback (z.B. `openrouter`, `ollama`, `gemini`)
3. **Level 3:** Global Default (`default` → `gemini` → `ollama` → `""`)

**Lazy-Loading:**
* Prompts werden erst zur Laufzeit geladen, wenn das aktive Modell bekannt ist
* **Parameter:** `prompt_key` und `variables` statt vorformatierter Strings
* **Vorteil:** Maximale Resilienz bei Modell-Fallbacks (Cloud → Local)

**Pre-Initialization:**
Alle möglichen Stream-Variablen werden vorab initialisiert (verhindert KeyErrors bei unvollständigen Konfigurationen).

**PROMPT-TRACE Logging:**
Das System protokolliert die genutzte Auflösungs-Ebene:
* `🎯 [PROMPT-TRACE] Level 1 Match: Model-specific`
* `📡 [PROMPT-TRACE] Level 2 Match: Provider-fallback`
* `⚓ [PROMPT-TRACE] Level 3 Match: Global Default`

---

## 6. LLM Profile Registry (`llm_profiles.yaml` v1.3.0)

Seit WP-25a nutzt MindNet eine **Mixture of Experts (MoE)** Architektur mit profilbasierter Experten-Steuerung. Jede Systemaufgabe (Synthese, Ingestion-Validierung, Routing, Kompression) wird einem dedizierten Profil zugewiesen, das Modell, Provider und Parameter unabhängig von der globalen Konfiguration definiert.

### 6.1 Profil-Struktur

Jedes Profil definiert:
* **`provider`:** Cloud-Provider (`openrouter`, `gemini`, `ollama`)
* **`model`:** Spezifisches Modell (z.B. `mistralai/mistral-7b-instruct:free`)
* **`temperature`:** Kreativität/Determinismus (0.0 = deterministisch, 1.0 = kreativ)
* **`fallback_profile`:** Optional: Name des Fallback-Profils bei Fehlern
* **`dimensions`:** Optional: Für Embedding-Profile (z.B. 768 für nomic-embed-text)

**Beispiel:**
```yaml
synthesis_pro:
  provider: "openrouter"
  model: "gemini-1.5-mistralai/mistral-7b-instruct:free"
  temperature: 0.7
  fallback_profile: "synthesis_backup"
```

### 6.2 Verfügbare Experten-Profile

| Profil | Provider | Modell | Temperature | Fallback | Zweck |
| :--- | :--- | :--- | :--- | :--- | :--- |
| **`synthesis_pro`** | openrouter | gemini-1.5-mistralai/mistral-7b-instruct:free | 0.7 | `synthesis_backup` | Hochwertige Synthese (Chat-Antworten) |
| **`synthesis_backup`** | openrouter | mistralai/mistral-large | 0.5 | `identity_safe` | Backup-Cloud-Experte (Resilienz) |
| **`tech_expert`** | openrouter | anthropic/claude-3.5-sonnet | 0.3 | `synthesis_pro` | Fachspezialist für Code & Technik |
| **`compression_fast`** | openrouter | mistralai/mistral-7b-instruct:free | 0.1 | `identity_safe` | Schnelle Kompression & Routing |
| **`ingest_extractor`** | openrouter | mistralai/mistral-7b-instruct:free | 0.2 | `synthesis_backup` | Extraktion komplexer Datenstrukturen |
| **`ingest_validator`** | openrouter | mistralai/mistral-7b-instruct:free | 0.0 | `compression_fast` | Binäre Prüfungen (YES/NO, deterministisch) |
| **`identity_safe`** | ollama | phi3:mini | 0.2 | *(kein Fallback)* | Lokaler Anker & Privacy (terminaler Endpunkt) |
| **`embedding_expert`** | ollama | nomic-embed-text | - | - | Embedding-Modell (dimensions: 768) |

### 6.3 Fallback-Kaskade (WP-25a)

Die Profile implementieren eine **rekursive Fallback-Kaskade**:

1. **Primäres Profil:** System versucht das angeforderte Profil (z.B. `synthesis_pro`)
2. **Fallback-Level 1:** Bei Fehler → `fallback_profile` (z.B. `synthesis_backup`)
3. **Fallback-Level 2:** Bei weiterem Fehler → nächster Fallback (z.B. `identity_safe`)
4. **Terminaler Endpunkt:** `identity_safe` hat keinen Fallback (lokales Modell als letzte Instanz)

**Schutzmechanismen:**
* **Zirkuläre Referenzen:** `visited_profiles`-Tracking verhindert Endlosschleifen
* **Background-Semaphore:** Parallele Tasks werden gedrosselt (konfigurierbar via `BACKGROUND_LIMIT`)

### 6.4 Integration in Decision Engine

Die `decision_engine.yaml` referenziert Profile über:
* **`router_profile`:** Profil für Intent-Erkennung (z.B. `compression_fast`)
* **`llm_profile`:** Profil für Strategie-spezifische Synthese (z.B. `tech_expert` für CODING)
* **`compression_profile`:** Profil für Stream-Kompression (z.B. `compression_fast`)

**Stream-Konfiguration:**
```yaml
values_stream:
  llm_profile: "identity_safe"  # Lokales Modell für Privacy
  compression_profile: "identity_safe"
  compression_threshold: 2500
```

### 6.5 Environment-Variablen

| Variable | Default | Beschreibung |
| :--- | :--- | :--- |
| `MINDNET_LLM_PROFILES_PATH` | `config/llm_profiles.yaml` | Pfad zur Profil-Registry |

**Hinweis:** Die `.env` Variablen `MINDNET_LLM_PROVIDER`, `MINDNET_LLM_MODEL` etc. dienen nur noch als Fallback, wenn kein Profil angegeben wird.

---

## 7. Konfigurations-Verbindungen & Datenfluss

Die vier zentralen Konfigurationsdateien (`types.yaml`, `decision_engine.yaml`, `llm_profiles.yaml`, `prompts.yaml`) arbeiten eng zusammen, um das agentische Multi-Stream RAG System zu steuern. Diese Sektion erklärt die Verbindungen und zeigt einen konkreten Praxisablauf.

### 7.1 Architektur-Übersicht

```mermaid
graph TB
    subgraph "1. Typ-Definition (types.yaml)"
        T1[Typ: value<br/>chunking_profile: structured_strict<br/>retriever_weight: 1.00]
        T2[Typ: risk<br/>chunking_profile: sliding_short<br/>retriever_weight: 0.85]
        T3[Typ: project<br/>chunking_profile: sliding_smart_edges<br/>retriever_weight: 0.97]
    end
    
    subgraph "2. Stream-Konfiguration (decision_engine.yaml)"
        D1[values_stream<br/>filter_types: value, principle, belief...<br/>llm_profile: identity_safe<br/>compression_profile: identity_safe]
        D2[risk_stream<br/>filter_types: risk, obstacle, bias<br/>llm_profile: synthesis_pro<br/>compression_profile: compression_fast]
        D3[facts_stream<br/>filter_types: project, decision, task...<br/>llm_profile: synthesis_pro<br/>compression_profile: compression_fast]
    end
    
    subgraph "3. Strategie-Komposition (decision_engine.yaml)"
        S1[DECISION Strategie<br/>use_streams: values_stream, facts_stream, risk_stream<br/>llm_profile: synthesis_pro<br/>prompt_template: decision_synthesis_v1]
    end
    
    subgraph "4. Experten-Profile (llm_profiles.yaml)"
        P1[synthesis_pro<br/>provider: openrouter<br/>model: google/gemini-2.0-flash-exp:free<br/>temperature: 0.7<br/>fallback_profile: synthesis_backup]
        P2[compression_fast<br/>provider: openrouter<br/>model: mistralai/mistral-7b-instruct:free<br/>temperature: 0.1<br/>fallback_profile: identity_safe]
        P3[identity_safe<br/>provider: ollama<br/>model: phi3:mini<br/>temperature: 0.2<br/>fallback_profile: null]
    end
    
    subgraph "5. Prompt-Templates (prompts.yaml)"
        PR1[decision_synthesis_v1<br/>Level 1: google/gemini-2.0-flash-exp:free<br/>Level 2: openrouter<br/>Level 3: default]
    end
    
    T1 -->|filter_types| D1
    T2 -->|filter_types| D2
    T3 -->|filter_types| D3
    
    D1 -->|use_streams| S1
    D2 -->|use_streams| S1
    D3 -->|use_streams| S1
    
    S1 -->|llm_profile| P1
    D1 -->|llm_profile| P3
    D2 -->|compression_profile| P2
    D3 -->|compression_profile| P2
    
    S1 -->|prompt_template| PR1
    P1 -->|model lookup| PR1
    
    style T1 fill:#e1f5ff
    style T2 fill:#e1f5ff
    style T3 fill:#e1f5ff
    style D1 fill:#fff4e1
    style D2 fill:#fff4e1
    style D3 fill:#fff4e1
    style S1 fill:#ffe1f5
    style P1 fill:#e1ffe1
    style P2 fill:#e1ffe1
    style P3 fill:#e1ffe1
    style PR1 fill:#f5e1ff
```

### 7.2 Verbindungs-Matrix

| Von | Zu | Verbindung | Beschreibung |
| :--- | :--- | :--- | :--- |
| **`types.yaml`** | **`decision_engine.yaml`** | `filter_types` | Streams filtern Notizen basierend auf Typen aus `types.yaml`. Die Liste `filter_types: ["value", "principle", "belief"]` muss exakt den Typ-Namen aus `types.yaml` entsprechen. |
| **`types.yaml`** | **`decision_engine.yaml`** | `detection_keywords` | Keywords aus `types.yaml` werden für den Interview-Modus verwendet (z.B. "Projekt" + "neu" → `INTERVIEW`). |
| **`decision_engine.yaml`** | **`llm_profiles.yaml`** | `router_profile` | Intent-Erkennung nutzt das Profil `compression_fast` für schnelle Klassifizierung. |
| **`decision_engine.yaml`** | **`llm_profiles.yaml`** | `llm_profile` (Stream) | Jeder Stream definiert sein eigenes Profil für Retrieval und Kompression (z.B. `identity_safe` für Privacy). |
| **`decision_engine.yaml`** | **`llm_profiles.yaml`** | `llm_profile` (Strategie) | Die finale Synthese nutzt das Strategie-Profil (z.B. `synthesis_pro` für DECISION). |
| **`decision_engine.yaml`** | **`llm_profiles.yaml`** | `compression_profile` | Überlange Streams werden via `compression_profile` verdichtet (z.B. `compression_fast`). |
| **`decision_engine.yaml`** | **`prompts.yaml`** | `prompt_template` | Strategien referenzieren Template-Keys (z.B. `decision_synthesis_v1`). |
| **`llm_profiles.yaml`** | **`prompts.yaml`** | Hierarchische Auflösung | Das aktive Modell aus dem Profil bestimmt, welcher Prompt-Level geladen wird (Model-ID → Provider → Default). |
| **`llm_profiles.yaml`** | **`llm_profiles.yaml`** | `fallback_profile` | Rekursive Fallback-Kaskade bei Fehlern (z.B. `synthesis_pro` → `synthesis_backup` → `identity_safe`). |

### 7.3 Praxisbeispiel: DECISION-Anfrage

**User-Anfrage:** `"Soll ich das neue Projekt starten?"`

#### Schritt 1: Intent-Erkennung

**Datei:** `decision_engine.yaml`
```yaml
settings:
  router_profile: "compression_fast"  # → llm_profiles.yaml
  router_prompt_key: "intent_router_v1"  # → prompts.yaml
```

**Ablauf:**
1. System prüft `trigger_keywords` in `DECISION` Strategie → findet `"soll ich"` → **Intent: DECISION**
2. Falls kein Keyword-Match: LLM-Router nutzt `compression_fast` Profil aus `llm_profiles.yaml`
3. Router lädt `intent_router_v1` aus `prompts.yaml` (hierarchisch basierend auf aktivem Modell)

#### Schritt 2: Stream-Aktivierung

**Datei:** `decision_engine.yaml`
```yaml
strategies:
  DECISION:
    use_streams: ["values_stream", "facts_stream", "risk_stream"]
    llm_profile: "synthesis_pro"  # → llm_profiles.yaml
    prompt_template: "decision_synthesis_v1"  # → prompts.yaml
```

**Ablauf:**
1. System aktiviert drei parallele Streams: `values_stream`, `facts_stream`, `risk_stream`

#### Schritt 3: Stream-Konfiguration & Typ-Filterung

**Datei:** `decision_engine.yaml` (Streams) + `types.yaml` (Typ-Definitionen)

```yaml
# decision_engine.yaml
values_stream:
  filter_types: ["value", "principle", "belief", "trait", "boundary", "need", "motivation"]
  llm_profile: "identity_safe"  # → llm_profiles.yaml
  compression_profile: "identity_safe"  # → llm_profiles.yaml
  query_template: "Welche meiner Werte und Prinzipien betreffen: {query}"

facts_stream:
  filter_types: ["project", "decision", "task", "goal", "event", "state"]
  llm_profile: "synthesis_pro"  # → llm_profiles.yaml
  compression_profile: "compression_fast"  # → llm_profiles.yaml
  query_template: "Status, Ressourcen und Fakten zu: {query}"

risk_stream:
  filter_types: ["risk", "obstacle", "bias"]
  llm_profile: "synthesis_pro"  # → llm_profiles.yaml
  compression_profile: "compression_fast"  # → llm_profiles.yaml
  query_template: "Gefahren, Hindernisse oder Risiken bei: {query}"
```

**Ablauf:**
1. **Values Stream:** Sucht in Qdrant nach Notizen mit `type IN ["value", "principle", "belief", ...]` (definiert in `types.yaml`)
2. **Facts Stream:** Sucht nach Notizen mit `type IN ["project", "decision", "task", ...]` (definiert in `types.yaml`)
3. **Risk Stream:** Sucht nach Notizen mit `type IN ["risk", "obstacle", "bias"]` (definiert in `types.yaml`)

#### Schritt 4: Profil-Auflösung & Modell-Auswahl

**Datei:** `llm_profiles.yaml`

```yaml
synthesis_pro:
  provider: "openrouter"
  model: "google/gemini-2.0-flash-exp:free"
  temperature: 0.7
  fallback_profile: "synthesis_backup"  # → Rekursiver Fallback

compression_fast:
  provider: "openrouter"
  model: "mistralai/mistral-7b-instruct:free"
  temperature: 0.1
  fallback_profile: "identity_safe"

identity_safe:
  provider: "ollama"
  model: "phi3:mini"
  temperature: 0.2
  fallback_profile: null  # Terminaler Endpunkt
```

**Ablauf:**
1. **Values Stream:** Nutzt `identity_safe` → Ollama/phi3:mini (lokal, Privacy)
2. **Facts Stream:** Nutzt `synthesis_pro` → OpenRouter/Gemini 2.0 (Cloud)
3. **Risk Stream:** Nutzt `synthesis_pro` → OpenRouter/Gemini 2.0 (Cloud)
4. **Kompression:** Falls Stream > `compression_threshold`, nutzt `compression_fast` → OpenRouter/Mistral 7B

#### Schritt 5: Prompt-Loading (Hierarchische Auflösung)

**Datei:** `prompts.yaml`

```yaml
decision_synthesis_v1:
  # Level 1: Modell-spezifisch (höchste Priorität)
  "google/gemini-2.0-flash-exp:free": |
    Agiere als strategischer Partner für: {query}
    WERTE: {values_stream} | FAKTEN: {facts_stream} | RISIKEN: {risk_stream}
    Prüfe die Fakten gegen meine Werte. Zeige Zielkonflikte auf. Gib eine klare Empfehlung.
  
  # Level 2: Provider-Fallback
  openrouter: |
    Strategische Multi-Stream Analyse für: {query}
    Werte-Basis: {values_stream} | Fakten: {facts_stream} | Risiken: {risk_stream}
    Bitte wäge ab und gib eine Empfehlung.
  
  # Level 3: Global Default
  default: "Prüfe {query} gegen Werte {values_stream} und Fakten {facts_stream}."
```

**Ablauf:**
1. System hat `synthesis_pro` Profil geladen → Modell: `google/gemini-2.0-flash-exp:free`
2. System sucht in `prompts.yaml` nach `decision_synthesis_v1`:
   - **Level 1:** Findet exakten Match für `google/gemini-2.0-flash-exp:free` → **Verwendet diesen Prompt**
   - Falls nicht gefunden: **Level 2** → `openrouter` Fallback
   - Falls nicht gefunden: **Level 3** → `default` Fallback
3. Prompt wird mit Stream-Variablen formatiert: `{values_stream}`, `{facts_stream}`, `{risk_stream}`, `{query}`

#### Schritt 6: Finale Synthese

**Ablauf:**
1. System ruft LLM auf mit:
   - **Profil:** `synthesis_pro` (OpenRouter/Gemini 2.0, Temperature 0.7)
   - **Prompt:** Level-1 Template aus `prompts.yaml` (modell-spezifisch optimiert)
   - **Variablen:** Formatierte Stream-Inhalte
2. Falls Fehler (z.B. Rate-Limit 429):
   - **Fallback:** `synthesis_backup` (Llama 3.3)
   - **Prompt:** Automatisch Level-2 (`openrouter`) oder Level-3 (`default`) geladen
3. Antwort wird an User zurückgegeben

### 7.4 Konfigurations-Synchronisation Checkliste

Beim Ändern einer Konfigurationsdatei müssen folgende Abhängigkeiten geprüft werden:

**✅ `types.yaml` ändern:**
- [ ] Prüfe, ob `filter_types` in `decision_engine.yaml` Streams noch gültig sind
- [ ] Prüfe, ob `detection_keywords` für Interview-Modus noch passen
- [ ] Prüfe, ob `chunking_profile` noch existiert (in `types.yaml` definiert)

**✅ `decision_engine.yaml` ändern:**
- [ ] Prüfe, ob alle `filter_types` in Streams existieren in `types.yaml`
- [ ] Prüfe, ob alle `llm_profile` / `compression_profile` existieren in `llm_profiles.yaml`
- [ ] Prüfe, ob alle `prompt_template` Keys existieren in `prompts.yaml`

**✅ `llm_profiles.yaml` ändern:**
- [ ] Prüfe, ob `fallback_profile` Referenzen zirkulär sind (Schutz: `visited_profiles`)
- [ ] Prüfe, ob alle referenzierten Profile existieren
- [ ] Prüfe, ob Modell-IDs mit `prompts.yaml` Level-1 Keys übereinstimmen (optional, aber empfohlen)

**✅ `prompts.yaml` ändern:**
- [ ] Prüfe, ob alle `prompt_template` Keys aus `decision_engine.yaml` existieren
- [ ] Prüfe, ob Modell-spezifische Keys (Level 1) mit `llm_profiles.yaml` Modell-IDs übereinstimmen
- [ ] Prüfe, ob alle Stream-Variablen (`{values_stream}`, `{facts_stream}`, etc.) initialisiert werden

### 7.5 Debugging-Tipps

**Problem:** Stream findet keine Notizen
- **Prüfung:** `filter_types` in Stream stimmt mit Typ-Namen in `types.yaml` überein? (Case-sensitive!)
- **Prüfung:** Existieren Notizen mit diesen Typen im Vault?

**Problem:** Falsches Modell wird verwendet
- **Prüfung:** `llm_profile` in Stream/Strategie existiert in `llm_profiles.yaml`?
- **Prüfung:** `fallback_profile` Kaskade führt zu unerwartetem Modell?

**Problem:** Prompt wird nicht gefunden
- **Prüfung:** `prompt_template` Key existiert in `prompts.yaml`?
- **Prüfung:** Hierarchische Auflösung (Level 1 → 2 → 3) funktioniert? (Logs: `[PROMPT-TRACE]`)

**Problem:** Kompression wird nicht ausgelöst
- **Prüfung:** `compression_threshold` in Stream-Konfiguration gesetzt?
- **Prüfung:** `compression_profile` existiert in `llm_profiles.yaml`?

---

Auszug aus der decision_engine.yaml
```yaml
strategies:
  # 1. Fakten-Abfrage (Fallback & Default)
  FACT:
    description: "Reine Wissensabfrage."
    trigger_keywords: [] 
    inject_types: []
    # WP-22: Definitionen & Hierarchien bevorzugen
    edge_boosts:
      part_of: 2.0
      composed_of: 2.0
      similar_to: 1.5
      caused_by: 0.5
    prompt_template: "rag_template"
    prepend_instruction: null

  # 2. Entscheidungs-Frage
  DECISION:
    description: "Der User sucht Rat, Strategie oder Abwägung."
    trigger_keywords: 
      - "soll ich"
      - "meinung"
      - "besser"
      - "empfehlung"
      - "strategie"
      - "entscheidung"
      - "abwägung"
      - "vergleich"
    inject_types: ["value", "principle", "goal", "risk"]
    # WP-22: Risiken und Konsequenzen hervorheben
    edge_boosts:
      blocks: 2.5
      solves: 2.0
      depends_on: 1.5
      risk_of: 2.5
    prompt_template: "decision_template"
    prepend_instruction: |
      !!! ENTSCHEIDUNGS-MODUS !!!
      BITTE WÄGE FAKTEN GEGEN FOLGENDE WERTE, PRINZIPIEN UND ZIELE AB:

  # 3. Empathie / "Ich"-Modus
```