# MindNet v3.1.1 - Release Notes: WP-25b

**Release Date:** 2026-01-02  
**Type:** Feature Release - Lazy-Prompt-Orchestration & Full Resilience  
**Version:** 3.1.1 (WP-25b)

---

## 🎯 Überblick

Mit WP-25b wurde MindNet von statischer Prompt-Formatierung auf eine **hierarchische Lazy-Prompt-Orchestration** umgestellt. Prompts werden erst im Moment des Modellaustauschs geladen, basierend auf dem exakt aktiven Modell. Dies ermöglicht modell-spezifisches Tuning und maximale Resilienz bei Modell-Fallbacks.

Diese Version markiert einen weiteren Architektur-Sprung: Von vorformatierter Prompt-Strings hin zu einer dynamischen, modell-spezifischen Prompt-Auflösung mit vollständiger Traceability.

---

## ✨ Neue Features

### 1. Hierarchisches Prompt-Resolution-System

**Implementierung (`app/services/llm_service.py` v3.5.5):**

Dreistufige Auflösungs-Logik für maximale Präzision und Resilienz:

1. **Level 1 (Modell-ID):** Exakte Übereinstimmung für spezifische Modelle
   * **Beispiel:** `google/gemini-2.0-flash-exp:free`, `meta-llama/llama-3.3-70b-instruct:free`
   * **Vorteil:** Modell-spezifische Optimierungen für maximale Präzision
   * **Logging:** `🎯 [PROMPT-TRACE] Level 1 Match: Model-specific`

2. **Level 2 (Provider):** Fallback auf Provider-Standards
   * **Beispiel:** `openrouter`, `ollama`, `gemini`
   * **Vorteil:** Bewährte Standards aus v3.1.2 bleiben erhalten
   * **Logging:** `📡 [PROMPT-TRACE] Level 2 Match: Provider-fallback`

3. **Level 3 (Default):** Globaler Sicherheits-Satz
   * **Fallback-Kette:** `default` → `gemini` → `ollama` → `""`
   * **Vorteil:** Vermeidung von Fehlern bei unbekannten Konfigurationen
   * **Logging:** `⚓ [PROMPT-TRACE] Level 3 Match: Global Default`

**Vorteile:**
* **Modell-spezifisches Tuning:** Jedes Modell kann optimierte Prompts erhalten
* **Maximale Resilienz:** Bei Modell-Fallbacks wird automatisch das passende Template geladen
* **Traceability:** Vollständige Transparenz über genutzte Instruktionen

### 2. Lazy-Prompt-Orchestration

**Implementierung (`app/services/llm_service.py` v3.5.5):**

* **Lazy Loading:** Prompts werden erst zur Laufzeit geladen, wenn das aktive Modell bekannt ist
* **Parameter:** `prompt_key` und `variables` statt vorformatierter Strings
* **Integration:** Vollständig in Chat, Ingestion und DecisionEngine integriert

**Vorteile:**
* **Dynamische Anpassung:** Prompt wird basierend auf aktivem Modell geladen
* **Fallback-Resilienz:** Bei Cloud → Local Fallback wird automatisch das passende Template verwendet
* **Wartbarkeit:** Zentrale Konfiguration in `prompts.yaml` statt verstreuter String-Formatierungen

### 3. Ultra-robustes Intent-Parsing

**Implementierung (`app/core/retrieval/decision_engine.py` v1.3.2):**

* **Regex-basierter Parser:** Bereinigt Modell-Artefakte zuverlässig
* **Beispiele:** `CODING[/S]` → `CODING`, `DECISION</s>` → `DECISION`
* **Robustheit:** Ignoriert Stop-Marker, Newlines oder Plaudereien des Modells

**Vorteile:**
* **Präzises Routing:** Strategie-Erkennung funktioniert auch bei freien Modellen mit Artefakten
* **Fehlerresistenz:** Systemabstürze durch fehlerhafte Modell-Antworten werden verhindert

### 4. Differenzierte Ingestion-Validierung

**Implementierung (`app/core/ingestion/ingestion_validation.py` v2.14.0):**

* **Fehler-Differenzierung:** Unterscheidung zwischen transienten und permanenten Fehlern
* **Transiente Fehler:** Timeout, Connection, Network → Kante wird erlaubt (Datenverlust vermeiden)
* **Permanente Fehler:** Config, Validation, Invalid Response → Kante wird abgelehnt (Graph-Qualität schützen)

**Vorteile:**
* **Datenintegrität:** Transiente Netzwerkfehler führen nicht zu Datenverlust
* **Graph-Qualität:** Permanente Konfigurationsfehler schützen vor fehlerhaften Kanten

### 5. PROMPT-TRACE Logging

**Implementierung (`app/services/llm_service.py` v3.5.5):**

* **Vollständige Transparenz:** Protokollierung der genutzten Prompt-Auflösungs-Ebene
* **Log-Format:** `[PROMPT-TRACE] Level X Match: ...`
* **Debugging:** Einfache Nachverfolgung von Prompt-Entscheidungen

**Vorteile:**
* **Debugging:** Schnelle Identifikation von Prompt-Problemen
* **Optimierung:** Verständnis, welche Prompts tatsächlich genutzt werden
* **Audit:** Vollständige Nachvollziehbarkeit der System-Entscheidungen

---

## 🔧 Technische Änderungen

### Konfigurationsdateien

**Aktualisierte Dateien:**
* `config/prompts.yaml` v3.2.2: Hierarchische Struktur mit Modell-spezifischen Overrides
  * **Erhalt:** 100% der Original-Prompts aus v3.1.2 für die Provider-Ebene
  * **Neu:** Modell-spezifische Overrides für Gemini 2.0, Llama 3.3, Qwen 2.5
  * **Neu:** `compression_template` für DecisionEngine v1.3.0

### Code-Komponenten

| Komponente | Version | Änderungen |
| :--- | :--- | :--- |
| `app/services/llm_service.py` | v3.5.5 | Hierarchische Prompt-Resolution, Lazy-Loading, PROMPT-TRACE |
| `app/core/retrieval/decision_engine.py` | v1.3.2 | Ultra-robustes Intent-Parsing via Regex |
| `app/core/ingestion/ingestion_validation.py` | v2.14.0 | Lazy-Prompt-Integration, differenzierte Fehlerbehandlung |
| `app/routers/chat.py` | v3.0.3 | Lazy-Prompt-Loading für Chat-Synthese |

### API-Änderungen

**Neue Parameter:**
* `prompt_key`: Schlüssel für Lazy-Loading (statt vorformatierter Strings)
* `variables`: Daten-Dict für Prompt-Formatierung

**Veraltete Parameter:**
* Vorformatierte `prompt` Strings werden weiterhin unterstützt (Abwärtskompatibilität)

---

## 🐛 Behobene Probleme

- ✅ **Behoben:** Modell-Artefakte in Intent-Router (z.B. `CODING[/S]` → `CODING`)
- ✅ **Behoben:** Fehlende modell-spezifische Prompt-Optimierungen
- ✅ **Behoben:** Fehlerhafte Prompt-Auflösung bei Modell-Fallbacks
- ✅ **Behoben:** Undifferenzierte Fehlerbehandlung in Ingestion-Validierung

---

## 📚 Dokumentation

**Aktualisierte Dokumente:**
- ✅ `03_tech_chat_backend.md`: Hierarchisches Prompt-Resolution-System und Lazy-Prompt-Orchestration
- ✅ `03_tech_configuration.md`: prompts.yaml hierarchische Struktur dokumentiert
- ✅ `02_concept_ai_personality.md`: Lazy-Prompt-Orchestration Konzept
- ✅ `03_tech_ingestion_pipeline.md`: Differenzierte Validierung
- ✅ `00_glossary.md`: Neue Begriffe (Lazy-Prompt, PROMPT-TRACE, hierarchische Resolution)
- ✅ `05_developer_guide.md`: Lazy-Prompt-Orchestration für Entwickler
- ✅ `06_active_roadmap.md`: WP25b als abgeschlossen markiert

---

## 🚀 Migration & Upgrade

### Für Administratoren

1. **Keine Breaking Changes:**
   * Vorformatierte Prompts werden weiterhin unterstützt
   * System funktioniert ohne Änderungen

2. **Optional: Modell-spezifische Optimierungen:**
   ```yaml
   # config/prompts.yaml
   decision_synthesis_v1:
     "google/gemini-2.0-flash-exp:free": |
       # Modell-spezifische Optimierung
       ...
   ```

3. **PROMPT-TRACE aktivieren:**
   * Logs zeigen automatisch die genutzte Auflösungs-Ebene
   * Keine zusätzliche Konfiguration erforderlich

### Für Entwickler

**API-Änderungen:**
* `LLMService.generate_raw_response()` unterstützt nun `prompt_key` und `variables`
* Vorformatierte `prompt` Strings bleiben für Abwärtskompatibilität erhalten

**Best Practice:**
* Nutze `prompt_key` und `variables` für neue Implementierungen
* Lazy-Loading ermöglicht automatische Modell-Anpassung

**Konfiguration:**
* Neue Modell-spezifische Prompts können in `prompts.yaml` definiert werden
* Hierarchische Struktur: Modell-ID → Provider → Default

---

## 🔮 Ausblick (WP-25c)

- Kontext-Budgeting: Intelligente Token-Verteilung
- Stream-specific Provider: Unterschiedliche KI-Modelle pro Wissensbereich
- Erweiterte Prompt-Optimierung: Dynamische Anpassung basierend auf Kontext und Historie

---

## 📊 Metriken & Performance

**Erwartete Verbesserungen:**
* **Präzision:** Modell-spezifische Prompts erhöhen Antwortqualität
* **Resilienz:** Automatische Prompt-Anpassung bei Modell-Fallbacks
* **Debugging:** PROMPT-TRACE vereinfacht Fehleranalyse
* **Wartbarkeit:** Zentrale Prompt-Konfiguration statt verstreuter Strings

---

**Status:** ✅ WP-25b ist zu 100% implementiert und audit-geprüft.  
**Nächster Schritt:** WP-25c (Kontext-Budgeting & Erweiterte Prompt-Optimierung).