# MindNet v3.0.0 - Release Notes: WP-25a

**Release Date:** 2026-01-02 
**Type:** Feature Release - Mixture of Experts (MoE) & Fallback-Kaskade  
**Version:** 3.1.0 (WP-25a)

---

## 🎯 Überblick

Mit WP-25a wurde MindNet von einer provider-basierten Steuerung auf eine **profilbasierte Experten-Architektur (Mixture of Experts)** umgestellt. Jede Systemaufgabe (Synthese, Ingestion-Validierung, Routing, Kompression) wird nun einem dedizierten Profil zugewiesen, das Modell, Provider und Parameter unabhängig von der globalen Konfiguration definiert.

Diese Version markiert einen fundamentalen Architektur-Sprung: Von einer monolithischen LLM-Konfiguration hin zu einer modularen, aufgabenspezifischen Experten-Steuerung mit automatischer Resilienz.

---

## ✨ Neue Features

### 1. Mixture of Experts (MoE) Architektur

**Zentrale Experten-Steuerung (`llm_profiles.yaml` v1.3.0):**
* Einführung von Experten-Profilen für spezifische Aufgaben:
  * `synthesis_pro`: Hochwertige Synthese für Chat-Antworten
  * `tech_expert`: Fachspezialist für Code & Technik (Claude 3.5 Sonnet)
  * `compression_fast`: Schnelle Kompression & Routing (Mistral 7B)
  * `ingest_validator`: Deterministische Validierung (Temperature 0.0)
  * `identity_safe`: Lokaler Anker (Ollama/Phi-3) für maximale Privacy
  * `embedding_expert`: Zentrale Steuerung des Embedding-Modells

**Vorteile:**
* **Aufgabenspezifische Optimierung:** Jede Aufgabe nutzt das optimale Modell
* **Hardware-Optimierung:** Lokaler Anker für kleine Hardware-Umgebungen
* **Wartbarkeit:** Zentrale Konfiguration statt verstreuter ENV-Variablen

### 2. Rekursive Fallback-Kaskade

**Implementierung (`app/services/llm_service.py` v3.5.2):**
* Automatische Fallback-Logik bei Provider-Fehlern:
  1. Versucht primäres Profil (z.B. `synthesis_pro`)
  2. Bei Fehler → `fallback_profile` (z.B. `synthesis_backup`)
  3. Bei weiterem Fehler → nächster Fallback (z.B. `identity_safe`)
  4. Terminaler Endpunkt: `identity_safe` hat keinen Fallback (lokales Modell)

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

### 3. Pre-Synthesis Kompression (Module A)

**Implementierung (`app/core/retrieval/decision_engine.py` v1.2.1):**
* Wissens-Streams, die den Schwellenwert (`compression_threshold`) überschreiten, werden **asynchron verdichtet**, bevor sie die Synthese erreichen
* **Konfigurierbar pro Stream:** Z.B. 2500 Zeichen für Values Stream, 3500 für Facts Stream
* **Profil-gesteuert:** Nutzt `compression_profile` (z.B. `compression_fast` für schnelle Zusammenfassung)
* **Parallelisierung:** Mehrere Streams können gleichzeitig komprimiert werden

**Vorteile:**
* Reduziert Token-Verbrauch bei langen Streams
* Beschleunigt Synthese durch kürzere Kontexte
* Erhält Relevanz durch intelligente Zusammenfassung

### 4. Profilgesteuerte Ingestion (Wissens-Gatekeeper)

**Implementierung:**
* `app/core/ingestion/ingestion_processor.py` v2.14.0
* `app/core/ingestion/ingestion_validation.py` v2.13.0

**Features:**
* Semantische Kanten-Validierung erfolgt zwingend über das MoE-Profil `ingest_validator` (Temperature 0.0 für Determinismus)
* **Embedding-Konsolidierung:** Der `EmbeddingsClient` (v2.6.0) bezieht Modellvorgaben und Dimensionen direkt aus dem Profil `embedding_expert`
* Entfernung der Embedding-Konfiguration aus der `.env` zugunsten zentraler Profil-Registry

### 5. Startup-Schutz & Audit-Fixes

**Implementierung (`app/main.py` v1.1.0):**
* Verifiziert beim Booten die Existenz und Validität von `llm_profiles.yaml` und `decision_engine.yaml`
* **Audit-Fix:** Behebung einer Sicherheitslücke in der `DecisionEngine`, durch die Fallback-Aufrufe bei Template-Fehlern die Profilsteuerung umgangen hätten
* **Circular Import Fix:** Ingestion-Module nutzen nun die neutrale `app.core.registry` für Text-Bereinigung und Registry-Lookups

---

## 🔧 Technische Änderungen

### Konfigurationsdateien

**Neue Datei:**
* `config/llm_profiles.yaml` v1.3.0: Zentrale Experten-Registry

**Aktualisierte Dateien:**
* `config/decision_engine.yaml` v3.2.2: Decoupled MoE Logic, Integration von `compression_thresholds`

### Code-Komponenten

| Komponente | Version | Änderungen |
| :--- | :--- | :--- |
| `app/services/llm_service.py` | v3.5.2 | Rekursive Fallback-Kaskade, Profil-Auflösung |
| `app/core/retrieval/decision_engine.py` | v1.2.1 | Profile-Driven Orchestration, Pre-Synthesis Kompression |
| `app/core/ingestion/ingestion_processor.py` | v2.14.0 | Profilgesteuerte Validierung |
| `app/core/ingestion/ingestion_validation.py` | v2.13.0 | MoE-Profil `ingest_validator` |
| `app/services/embeddings_client.py` | v2.6.0 | Profil-basierte Modell-Auflösung |
| `app/main.py` | v1.1.0 | Startup-Validierung der YAML-Dateien |

### Environment-Variablen

**Neue Variable:**
* `MINDNET_LLM_PROFILES_PATH`: Pfad zur Profil-Registry (Default: `config/llm_profiles.yaml`)

**Legacy (nur noch Fallback):**
* `MINDNET_LLM_PROVIDER`, `MINDNET_LLM_MODEL`, etc. dienen nur noch als Fallback, wenn kein Profil angegeben wird

---

## 🐛 Behobene Probleme

- ✅ **Behoben:** Sicherheitslücke in der `DecisionEngine` - Fallback-Aufrufe nutzen nun korrekt `profile_name`
- ✅ **Behoben:** Circular Import zwischen Ingestion-Modulen und Registry
- ✅ **Behoben:** Fehlende Startup-Validierung der YAML-Konfigurationen

---

## 📚 Dokumentation

**Aktualisierte Dokumente:**
- ✅ `03_tech_configuration.md`: llm_profiles.yaml Dokumentation
- ✅ `03_tech_chat_backend.md`: MoE Architektur und Fallback-Kaskade
- ✅ `02_concept_ai_personality.md`: Mixture of Experts Konzept
- ✅ `03_tech_ingestion_pipeline.md`: Profilgesteuerte Validierung
- ✅ `00_glossary.md`: Neue Begriffe (MoE, Profile, Fallback-Kaskade)
- ✅ `05_developer_guide.md`: Teach-the-AI mit Profilen
- ✅ `04_admin_operations.md`: Konfigurations-Updates
- ✅ `06_active_roadmap.md`: WP25a als abgeschlossen markiert

---

## 🚀 Migration & Upgrade

### Für Administratoren

1. **Neue Konfigurationsdatei erstellen:**
   ```bash
   cp config/llm_profiles.yaml.example config/llm_profiles.yaml
   # Anpassen nach Bedarf
   ```

2. **Startup-Validierung prüfen:**
   ```bash
   # System startet nicht, wenn llm_profiles.yaml fehlt oder ungültig ist
   python3 -m app.main
   ```

3. **ENV-Variablen (optional):**
   Die `.env` Variablen `MINDNET_LLM_PROVIDER`, `MINDNET_LLM_MODEL` etc. dienen nur noch als Fallback. Die primäre Steuerung erfolgt über `llm_profiles.yaml`.

### Für Entwickler

**API-Änderungen:**
* `LLMService.generate_raw_response()` unterstützt nun `profile_name` Parameter
* Fallback-Kaskade erfolgt automatisch bei Fehlern
* `visited_profiles`-Tracking verhindert Zirkel-Referenzen

**Konfiguration:**
* Neue Profile können in `llm_profiles.yaml` definiert werden
* `decision_engine.yaml` referenziert Profile über `router_profile`, `llm_profile`, `compression_profile`

---

## 🔮 Ausblick (WP-25b: Prompt-Orchestration & Model-Specific Tuning)

- Pre-Synthesis: LLM-basierte Komprimierung überlanger Streams (✅ bereits implementiert)
- Kontext-Budgeting: Intelligente Token-Verteilung
- Stream-specific Provider: Unterschiedliche KI-Modelle pro Wissensbereich
- Prompt-Orchestration: Dynamische Prompt-Anpassung basierend auf Profil und Kontext

---

## 📊 Metriken & Performance

**Erwartete Verbesserungen:**
* **Resilienz:** Automatische Fallback-Kaskade reduziert Ausfallzeiten
* **Token-Effizienz:** Pre-Synthesis Kompression reduziert Token-Verbrauch bei langen Streams
* **Determinismus:** Profilgesteuerte Validierung (Temperature 0.0) erhöht Konsistenz
* **Wartbarkeit:** Zentrale Profil-Registry vereinfacht Konfigurations-Management

---

**Status:** ✅ WP-25a ist zu 100% implementiert und audit-geprüft.  
**Nächster Schritt:** WP-25b (Prompt-Orchestration & Model-Specific Tuning).