Lars/mindnet
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases 21 Wiki Activity
main
mindnet/docs/99_Archive/WP25_release_notes.md
Lars 0d2469f8fa WP25-v3.0.0-Dokumentation
2026-01-01 20:24:09 +01:00

10 KiB
Raw Permalink Blame History

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):

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

ChatResponse (erweitert):

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:

    git pull origin main
source .venv/bin/activate
pip install -r requirements.txt

  2. Konfiguration prüfen:

    # 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:

    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