Lars 62a00d1ac3 Update documentation and technical references for Mindnet v3.1.1: Revise versioning across all documents to reflect the latest updates, including the integration of Lazy-Prompt-Orchestration and enhancements in AI model capabilities. Update context descriptions to clarify new features and improvements in prompt management, ingestion validation, and decision engine processes.

2026-01-03 09:56:49 +01:00

37 KiB

Raw Blame History

doc_type	audience	scope	status	version	context
technical_reference	developer, admin	configuration, env, registry, scoring, resilience, modularization, agentic_rag, moe, lazy_prompts	active	3.1.1	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:

Frontmatter (Höchste Prio): Ein Wert direkt in der Markdown-Datei überschreibt alles.
Type Config: Der Standardwert für den type aus types.yaml.
Ingestion Settings (Neu WP-14): Globale Konfiguration wie default_chunk_profile innerhalb des ingestion_settings Blocks.
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.

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:

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

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).
Type Keywords: Prüft detection_keywords aus types.yaml für Interview-Modus (z.B. "Projekt" + "neu" → INTERVIEW).
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:

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:

Level 1: Exakte Modell-ID (z.B. google/gemini-2.0-flash-exp:free)
Level 2: Provider-Fallback (z.B. openrouter, ollama, gemini)
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:

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:

Primäres Profil: System versucht das angeforderte Profil (z.B. synthesis_pro)
Fallback-Level 1: Bei Fehler → fallback_profile (z.B. synthesis_backup)
Fallback-Level 2: Bei weiterem Fehler → nächster Fallback (z.B. identity_safe)
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:

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

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

settings:
  router_profile: "compression_fast"  # → llm_profiles.yaml
  router_prompt_key: "intent_router_v1"  # → prompts.yaml

Ablauf:

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

Schritt 2: Stream-Aktivierung

Datei: decision_engine.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:

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)

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

Values Stream: Sucht in Qdrant nach Notizen mit type IN ["value", "principle", "belief", ...] (definiert in types.yaml)
Facts Stream: Sucht nach Notizen mit type IN ["project", "decision", "task", ...] (definiert in types.yaml)
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

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:

Values Stream: Nutzt identity_safe → Ollama/phi3:mini (lokal, Privacy)
Facts Stream: Nutzt synthesis_pro → OpenRouter/Gemini 2.0 (Cloud)
Risk Stream: Nutzt synthesis_pro → OpenRouter/Gemini 2.0 (Cloud)
Kompression: Falls Stream > compression_threshold, nutzt compression_fast → OpenRouter/Mistral 7B

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

Datei: prompts.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:

System hat synthesis_pro Profil geladen → Modell: google/gemini-2.0-flash-exp:free
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
Prompt wird mit Stream-Variablen formatiert: {values_stream}, {facts_stream}, {risk_stream}, {query}

Schritt 6: Finale Synthese

Ablauf:

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
Falls Fehler (z.B. Rate-Limit 429):
- Fallback: synthesis_backup (Llama 3.3)
- Prompt: Automatisch Level-2 (openrouter) oder Level-3 (default) geladen
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

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

37 KiB Raw Blame History

Konfigurations-Referenz

1. Environment Variablen (.env)

2. Typ-Registry (types.yaml)

2.1 Konfigurations-Hierarchie (Override-Logik)

2.2 Typ-Referenz & Stream-Logik (Vollständige Liste: 28 Typen)

2.2.1 Identity Stream (Der Kern / Das „Warum“)

2.2.2 Action Stream (Die Dynamik / Das „Was“)

2.2.3 History & Basis Stream (Die Evidenz / Das „Wann“)

3. Retriever Config (retriever.yaml)

4. Edge Typen & Registry Referenz

4.1 Dateistruktur & Speicherort

4.2 Aufbau des Dictionaries (Markdown-Schema)

4.3 Verfügbare Kanten-Typen (System-Standard)

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

5.1 Intent Recognition: Hybrid-Routing (WP-25)

LLM Router Konfiguration

5.2 Multi-Stream Konfiguration (WP-25)

5.3 Strategie-Mechaniken (Graph Shaping)

5.4 Übersicht der Strategien (WP-25)

5.5 Der Interview-Modus & Schemas

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

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

6.1 Profil-Struktur

6.2 Verfügbare Experten-Profile

6.3 Fallback-Kaskade (WP-25a)

6.4 Integration in Decision Engine

6.5 Environment-Variablen

7. Konfigurations-Verbindungen & Datenfluss

7.1 Architektur-Übersicht

7.2 Verbindungs-Matrix

7.3 Praxisbeispiel: DECISION-Anfrage

Schritt 1: Intent-Erkennung

Schritt 2: Stream-Aktivierung

Schritt 3: Stream-Konfiguration & Typ-Filterung

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

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

Schritt 6: Finale Synthese

7.4 Konfigurations-Synchronisation Checkliste

7.5 Debugging-Tipps

37 KiB

Raw Blame History

1. Environment Variablen (`.env`)

2. Typ-Registry (`types.yaml`)

3. Retriever Config (`retriever.yaml`)

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

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

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