WP25-v3.0.0-Dokumentation
This commit is contained in:
1 parent
124849c580
commit
0d2469f8fa
13 files changed
+767
-164
No files matched your search
@@ -0,0 +1,138 @@
|
||||
# Branch Merge Commit Message: WP25
|
||||
|
||||
```
|
||||
feat: Agentic Multi-Stream RAG Orchestration (v3.0)
|
||||
|
||||
## Architektur-Transformation (WP-25)
|
||||
|
||||
### Agentic Multi-Stream RAG Orchestration
|
||||
- Übergang von linearer RAG-Architektur zu paralleler Multi-Stream Engine
|
||||
- Parallele Abfragen in spezialisierten Wissens-Streams (Values, Facts, Biography, Risk, Tech)
|
||||
- Stream-Tracing: Jeder Treffer wird mit `stream_origin` markiert
|
||||
- Fehler-Resilienz: Einzelne Stream-Fehler blockieren nicht die gesamte Anfrage
|
||||
|
||||
**Geänderte Dateien:**
|
||||
- `app/core/retrieval/decision_engine.py`: Multi-Stream Orchestrator (v1.0.3)
|
||||
- `app/routers/chat.py`: Hybrid Router Integration (v3.0.2)
|
||||
- `app/models/dto.py`: Stream-Tracing Support (v0.7.1)
|
||||
|
||||
### Intent-basiertes Routing ("The Brain")
|
||||
- Hybrid-Modus: Keyword Fast-Path + LLM Slow-Path
|
||||
- Strategien: FACT_WHAT, FACT_WHEN, DECISION, EMPATHY, CODING, INTERVIEW
|
||||
- Sofortige Erkennung von Triggern wie "Soll ich" oder "Wann" ohne LLM-Call
|
||||
- Komplexe semantische Analyse für unklare Anfragen
|
||||
|
||||
**Geänderte Dateien:**
|
||||
- `app/routers/chat.py`: Hybrid Router mit Keyword-Fast-Path (v3.0.2)
|
||||
- `app/core/retrieval/decision_engine.py`: LLM-basiertes Routing (v1.0.3)
|
||||
|
||||
### Wissens-Synthese
|
||||
- Spezialisierte Templates in `prompts.yaml` mit expliziten Stream-Variablen
|
||||
- Pre-Initialization aller Stream-Variablen (verhindert KeyErrors)
|
||||
- Provider-spezifische Templates für Ollama, Gemini und OpenRouter
|
||||
- Differenzierte Abwägung zwischen Fakten und persönlichen Werten
|
||||
|
||||
**Geänderte Dateien:**
|
||||
- `config/prompts.yaml`: Stream-Templates (v3.1.2)
|
||||
- `app/core/retrieval/decision_engine.py`: Synthese-Logik (v1.0.3)
|
||||
|
||||
## Stream-Konfiguration & Typ-Synchronisation
|
||||
|
||||
### Stream-Library (decision_engine.yaml v3.1.6)
|
||||
- **Values Stream:** Identität, Ethik und Prinzipien (filter_types: value, principle, belief, etc.)
|
||||
- **Facts Stream:** Operative Daten (filter_types: project, decision, task, etc.)
|
||||
- **Biography Stream:** Persönliche Erfahrungen (filter_types: experience, journal, profile)
|
||||
- **Risk Stream:** Hindernisse und Gefahren (filter_types: risk, obstacle, bias)
|
||||
- **Tech Stream:** Technisches Wissen (filter_types: concept, source, glossary, etc.)
|
||||
|
||||
**Edge-Boosts pro Stream:**
|
||||
- Values: `guides: 3.0`, `enforced_by: 2.5`, `based_on: 2.0`
|
||||
- Facts: `part_of: 2.0`, `depends_on: 1.5`, `implemented_in: 1.5`
|
||||
- Risk: `blocks: 2.5`, `impacts: 2.0`, `risk_of: 2.5`
|
||||
|
||||
**Geänderte Dateien:**
|
||||
- `config/decision_engine.yaml`: Multi-Stream Konfiguration (v3.1.6)
|
||||
|
||||
## Bugfixes & Optimierungen
|
||||
|
||||
### Vault-Import Performance
|
||||
- "Empty Response Guard" korrigiert: Kurze Ingest-Antworten (YES/NO) lösen nicht mehr fälschlicherweise langsame Fallbacks aus
|
||||
- Entfernung des <5-Zeichen Guards ermöglicht YES/NO Validierungen
|
||||
|
||||
**Geänderte Dateien:**
|
||||
- `app/services/llm_service.py`: Ingest-Stability Patch (v3.4.2)
|
||||
|
||||
### Cloud-Resilienz
|
||||
- Sicherheitscheck für das `choices`-Array in `_execute_openrouter` implementiert
|
||||
- Verhindert JSON-Errors bei überlasteten APIs
|
||||
|
||||
**Geänderte Dateien:**
|
||||
- `app/services/llm_service.py`: Empty Response Guard (v3.4.2)
|
||||
|
||||
### Template-Robustheit
|
||||
- Automatische Vor-Initialisierung aller Stream-Variablen in der `DecisionEngine`
|
||||
- Verhindert `KeyError`-Abstürze bei unvollständigen Konfigurationen
|
||||
- Fallback-Mechanismus bei Template-Fehlern
|
||||
|
||||
**Geänderte Dateien:**
|
||||
- `app/core/retrieval/decision_engine.py`: Pre-Initialization (v1.0.3)
|
||||
|
||||
### Intent-Kollision
|
||||
- Generische Begriffe (wie "Projekt") wurden aus den Keyword-Triggern entfernt
|
||||
- Sicherstellt, dass strategische Fragen (z.B. "Soll ich...?") korrekt als `DECISION` geroutet werden
|
||||
|
||||
**Geänderte Dateien:**
|
||||
- `config/decision_engine.yaml`: Keyword-Fix (v3.1.6)
|
||||
|
||||
## Ollama Context-Throttling
|
||||
|
||||
- Vor der Übergabe an Ollama prüft der Chat-Router, ob der Kontext die Grenze von `MAX_OLLAMA_CHARS` überschreitet (Standard: 10.000)
|
||||
- Automatische Kürzung bei großen Kontexten
|
||||
|
||||
**Geänderte Dateien:**
|
||||
- `app/routers/chat.py`: Context-Throttling (v3.0.2)
|
||||
|
||||
## Lifespan Management
|
||||
|
||||
- FastAPI-Anwendung implementiert Lifespan-Management für sauberen Startup und Shutdown
|
||||
- Integritäts-Check der WP-25 Konfiguration beim Startup
|
||||
- Ressourcen-Cleanup beim Shutdown
|
||||
- Globale Fehlerbehandlung für asynchrone Prozesse
|
||||
|
||||
**Geänderte Dateien:**
|
||||
- `app/main.py`: Lifespan Management (v1.0.0)
|
||||
|
||||
## Impact & Breaking Changes
|
||||
|
||||
### 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-Erweiterungen
|
||||
- `QueryHit.stream_origin`: Name des Ursprungs-Streams (optional)
|
||||
- `ChatResponse.intent`: Die gewählte WP-25 Strategie (optional)
|
||||
- `ChatResponse.intent_source`: Quelle der Intent-Erkennung (optional)
|
||||
|
||||
## Dokumentation
|
||||
|
||||
Alle relevanten Dokumente 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)
|
||||
|
||||
## Versionen
|
||||
|
||||
- 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
|
||||
|
||||
Closes #[issue-number]
|
||||
```
|
||||
@@ -0,0 +1,268 @@
|
||||
# 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)
|
||||
Reference in new issue
Block a user