269 lines
10 KiB
Markdown
269 lines
10 KiB
Markdown
# 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)
|