# Release Notes: Mindnet v3.0.0 (WP25)

**Release Date:** 2026-01-01  
**Type:** Feature Release - Agentic Multi-Stream RAG Orchestration  
**Branch:** WP25

---

## 🎯 Übersicht

Diese Version markiert den Übergang von Mindnet von einer klassischen, linearen RAG-Architektur zu einer **Agentic Multi-Stream Engine**. Das System agiert nun als intelligenter Orchestrator, der Nutzeranfragen analysiert, in parallele Wissens-Streams aufteilt und diese zu einer kontextreichen, wertebasierten Antwort synthetisiert.

---

## ✨ Neue Features

### Agentic Multi-Stream RAG Orchestration

Mindnet führt nun **parallele Abfragen** in spezialisierten Wissens-Streams aus, anstatt einer einzelnen Suche:

**Stream-Library:**
* **Values Stream:** Extrahiert Identität, Ethik und Prinzipien (`value`, `principle`, `belief`, `trait`, `boundary`, `need`, `motivation`).
* **Facts Stream:** Liefert operative Daten zu Projekten, Tasks und Status (`project`, `decision`, `task`, `goal`, `event`, `state`).
* **Biography Stream:** Greift auf persönliche Erfahrungen und Journal-Einträge zu (`experience`, `journal`, `profile`, `person`).
* **Risk Stream:** Identifiziert Hindernisse und potenzielle Gefahren (`risk`, `obstacle`, `bias`).
* **Tech Stream:** Bündelt technisches Wissen, Code und Dokumentation (`concept`, `source`, `glossary`, `idea`, `insight`, `skill`, `habit`).

**Vorteile:**
* **Präzise Kontext-Ladung:** Jeder Stream fokussiert auf spezifische Wissensbereiche.
* **Parallele Ausführung:** Alle Streams werden gleichzeitig abgefragt (asyncio.gather).
* **Stream-Tracing:** Jeder Treffer wird mit `stream_origin` markiert für Feedback-Optimierung.
* **Fehler-Resilienz:** Einzelne Stream-Fehler blockieren nicht die gesamte Anfrage.

### Intent-basiertes Routing ("The Brain")

Der Router wurde zu einem **hybriden System** erweitert, das Anfragen klassifiziert, bevor die Suche beginnt:

**Strategien:**
* **FACT_WHAT:** Wissen/Listen (z.B. "Was ist...", "Welche sind...").
* **FACT_WHEN:** Zeitpunkte (z.B. "Wann...", "Datum...").
* **DECISION:** Beratung (z.B. "Soll ich...", "Sollte ich...", "Empfehlung...").
* **EMPATHY:** Reflexion (z.B. "Fühle...", "Stress...", "Angst...").
* **CODING:** Technik (z.B. "Code...", "Python...", "Bug...").
* **INTERVIEW:** Datenerfassung (z.B. "Neues Projekt...", "Erfahrung...").

**Hybrid-Modus:**
* **Keyword Fast-Path:** Sofortige Erkennung von Triggern wie "Soll ich" oder "Wann" ohne LLM-Call.
* **LLM Slow-Path:** Komplexe semantische Analyse für unklare Anfragen.
* **Type Keywords:** Automatische Erkennung von Objekt-Typen für Interview-Modus.

**Vorteil:** Reduziert Latenz durch schnelle Keyword-Erkennung, nutzt LLM nur bei Bedarf.

### Wissens-Synthese

Die Zusammenführung der Daten erfolgt über spezialisierte Templates in der `prompts.yaml`:

**Template-Struktur:**
* Explizite Variablen für jeden Stream (z.B. `{values_stream}`, `{risk_stream}`).
* **Pre-Initialization:** Alle möglichen Stream-Variablen werden vorab initialisiert (verhindert KeyErrors).
* **Provider-spezifische Templates:** Separate Versionen für Ollama, Gemini und OpenRouter.

**Synthese-Strategien:**
* **FACT_WHAT/FACT_WHEN:** Kombiniert Fakten, Biographie und Technik.
* **DECISION:** Wägt Fakten gegen Werte ab, evaluiert Risiken.
* **EMPATHY:** Fokus auf Biographie und Werte.
* **CODING:** Technik und Fakten.

**Vorteil:** Ermöglicht dem LLM eine differenzierte Abwägung zwischen Fakten und persönlichen Werten.

---

## 🔧 Verbesserungen

### Stream-Konfiguration & Typ-Synchronisation

Jeder Stream nutzt individuelle **Edge-Boosts** und **Filter-Types**, die strikt mit der `types.yaml` (v2.7.0) synchronisiert sind:

**Beispiele:**
* **Values Stream:** `guides: 3.0`, `enforced_by: 2.5`, `based_on: 2.0`.
* **Facts Stream:** `part_of: 2.0`, `depends_on: 1.5`, `implemented_in: 1.5`.
* **Risk Stream:** `blocks: 2.5`, `impacts: 2.0`, `risk_of: 2.5`.

**Vorteil:** Präzise Gewichtung der Graph-Kanten je nach Wissensbereich.

### Template-Robustheit

**Pre-Initialization:** Automatische Vor-Initialisierung aller Stream-Variablen in der `DecisionEngine` verhindert `KeyError`-Abstürze bei unvollständigen Konfigurationen.

**Fallback-Mechanismus:** Bei Template-Fehlern wird ein vereinfachter Prompt mit allen verfügbaren Stream-Ergebnissen verwendet.

### Ollama Context-Throttling

Vor der Übergabe an Ollama prüft der Chat-Router, ob der Kontext (RAG-Hits) die Grenze von `MAX_OLLAMA_CHARS` überschreitet (Standard: 10.000) und kürzt diesen ggf.

**Vorteil:** Verhindert VRAM-Überlastung bei großen Kontexten.

---

## 🐛 Bugfixes

- ✅ **Behoben:** Vault-Import Performance - "Empty Response Guard" korrigiert, damit kurze Ingest-Antworten (YES/NO) nicht mehr fälschlicherweise langsame Fallbacks auslösen.
- ✅ **Behoben:** Cloud-Resilienz - Sicherheitscheck für das `choices`-Array in `_execute_openrouter` implementiert, um JSON-Errors bei überlasteten APIs zu verhindern.
- ✅ **Behoben:** Template-Robustheit - Automatische Vor-Initialisierung aller Stream-Variablen verhindert `KeyError`-Abstürze.
- ✅ **Behoben:** Intent-Kollision - Generische Begriffe (wie "Projekt") wurden aus den Keyword-Triggern entfernt, um sicherzustellen, dass strategische Fragen (z.B. "Soll ich...?") korrekt als `DECISION` geroutet werden.

---

## ⚠️ Breaking Changes & Migration

### Keine Migration erforderlich

**WICHTIG:** Diese Version ist **rückwärtskompatibel**. Bestehende Vaults funktionieren ohne Re-Import.

**Konfigurations-Updates:**
* `decision_engine.yaml` wurde auf v3.1.6 aktualisiert (Multi-Stream Struktur).
* `prompts.yaml` wurde auf v3.1.2 aktualisiert (Stream-Templates).
* **Empfehlung:** Backup der alten Konfigurationsdateien vor dem Update.

---

## 📚 API-Änderungen

### Erweiterte DTOs

**QueryHit (erweitert):**
```python
class QueryHit(BaseModel):
    # ... bestehende Felder ...
    stream_origin: Optional[str] = None  # Neu: Name des Ursprungs-Streams
```

**ChatResponse (erweitert):**
```python
class ChatResponse(BaseModel):
    # ... bestehende Felder ...
    intent: Optional[str] = "FACT"  # Neu: Die gewählte WP-25 Strategie
    intent_source: Optional[str] = "LLM_Router"  # Neu: Quelle der Intent-Erkennung
```

**Impact für API-Consumer:**
* Frontend kann `stream_origin` für visuelle Kennzeichnung der Quellen nutzen.
* `intent` und `intent_source` ermöglichen Debugging und Analytics.

---

## 📖 Dokumentation

Alle relevanten Dokumente wurden aktualisiert:

- ✅ `03_tech_chat_backend.md`: Agentic Multi-Stream RAG, Intent-basiertes Routing, Wissens-Synthese
- ✅ `03_tech_configuration.md`: decision_engine.yaml, prompts.yaml (Stream-Struktur)
- ✅ `03_tech_api_reference.md`: Erweiterte DTOs (stream_origin, intent)

---

## 🔄 Technische Details

### Geänderte Module

**Decision Engine:**
- `app/core/retrieval/decision_engine.py`: Multi-Stream Orchestrator (v1.0.3)
  - Paralleles Retrieval via `_execute_parallel_streams()`
  - Stream-Tracing mit `stream_origin`
  - Pre-Initialization der Stream-Variablen

**Chat Router:**
- `app/routers/chat.py`: Hybrid Router Integration (v3.0.2)
  - Keyword Fast-Path + LLM Slow-Path
  - Multi-Stream Orchestrierung
  - Ollama Context-Throttling

**LLM Service:**
- `app/services/llm_service.py`: Ingest-Stability Patch (v3.4.2)
  - Entfernung des <5-Zeichen Guards
  - Empty Response Guard für OpenRouter
  - Lazy Initialization der DecisionEngine

**DTOs:**
- `app/models/dto.py`: Stream-Tracing Support (v0.7.1)
  - `stream_origin` in `QueryHit`
  - `intent` und `intent_source` in `ChatResponse`

**Main:**
- `app/main.py`: Lifespan Management (v1.0.0)
  - Startup-Integritäts-Check
  - Ressourcen-Cleanup beim Shutdown
  - Globale Fehlerbehandlung

**Konfiguration:**
- `config/decision_engine.yaml`: Multi-Stream Konfiguration (v3.1.6)
- `config/prompts.yaml`: Stream-Templates (v3.1.2)

### Versionsnummern

- Decision Engine: **v1.0.3**
- Chat Router: **v3.0.2**
- LLM Service: **v3.4.2**
- DTOs: **v0.7.1**
- Main: **v1.0.0**
- decision_engine.yaml: **v3.1.6**
- prompts.yaml: **v3.1.2**

---

## 🚀 Upgrade-Pfad

### Für Administratoren

1. **Code aktualisieren:**
   ```bash
   git pull origin main
   source .venv/bin/activate
   pip install -r requirements.txt
   ```

2. **Konfiguration prüfen:**
   ```bash
   # Backup der alten Konfigurationen
   cp config/decision_engine.yaml config/decision_engine.yaml.backup
   cp config/prompts.yaml config/prompts.yaml.backup
   
   # Prüfen, ob neue Konfigurationen vorhanden sind
   ls -la config/decision_engine.yaml config/prompts.yaml
   ```

3. **Services neu starten:**
   ```bash
   sudo systemctl restart mindnet-prod
   sudo systemctl restart mindnet-ui-prod
   ```

### Für Entwickler

- Keine Code-Änderungen erforderlich, wenn nur API genutzt wird
- Frontend kann neue Felder (`stream_origin`, `intent`, `intent_source`) optional nutzen
- Stream-Tracing ermöglicht Feedback-Optimierung pro Wissensbereich

---

## 📝 Bekannte Einschränkungen

- **Stream-Parallelität:** Maximale Anzahl paralleler Streams ist durch asyncio-Limits begrenzt (typischerweise 5-10 Streams).
- **Kontext-Größe:** Große Kontexte (>10.000 Zeichen) werden bei Ollama automatisch gekürzt.

---

## 🔮 Ausblick (WP-25a: Agentic Refinement)

Auf Basis des stabilen WP-25 Fundaments sind folgende Erweiterungen geplant:

* **Pre-Synthesis:** LLM-basierte Komprimierung überlanger Streams vor der finalen Antwortgenerierung.
* **Kontext-Budgeting:** Intelligente Verteilung der verfügbaren Token auf die aktivierten Streams.
* **Stream-specific Provider:** Zuweisung unterschiedlicher KI-Modelle pro Wissensbereich (z.B. lokales Ollama für Identitäts-Werte, Gemini für technische Fakten).

---

## 🙏 Danksagungen

Diese Version wurde durch umfangreiche Architektur-Überarbeitung ermöglicht. Besonderer Fokus lag auf:
- Transformation zu einer Agentic Multi-Stream Engine
- Intelligente Intent-Erkennung mit Hybrid-Routing
- Parallele Wissens-Synthese mit wertebasierter Abwägung
- Robustheit und Fehler-Resilienz

---

**Vollständige Changelog:** Siehe Git-Commits für detaillierte Änderungen  
**Support:** Bei Fragen siehe [Admin Operations Guide](../04_Operations/04_admin_operations.md)