From 62a00d1ac3e0a546de7dd2a1fd7e73e4e336d7d0 Mon Sep 17 00:00:00 2001 From: Lars Date: Sat, 3 Jan 2026 09:56:49 +0100 Subject: [PATCH] Update documentation and technical references for Mindnet v3.1.1: Revise versioning across all documents to reflect the latest updates, including the integration of Lazy-Prompt-Orchestration and enhancements in AI model capabilities. Update context descriptions to clarify new features and improvements in prompt management, ingestion validation, and decision engine processes. --- docs/00_General/00_documentation_map.md | 6 +- docs/00_General/00_glossary.md | 11 +- docs/02_concepts/02_concept_ai_personality.md | 6 +- .../03_tech_chat_backend.md | 45 ++- .../03_tech_configuration.md | 323 +++++++++++++++++- .../03_tech_ingestion_pipeline.md | 13 +- docs/04_Operations/04_admin_operations.md | 6 +- docs/05_Development/05_developer_guide.md | 30 +- docs/06_Roadmap/06_active_roadmap.md | 52 +-- docs/99_Archive/WP25b_merge_commit.md | 97 ++++++ docs/99_Archive/WP25b_release_notes.md | 205 +++++++++++ docs/README.md | 4 +- 12 files changed, 732 insertions(+), 66 deletions(-) create mode 100644 docs/99_Archive/WP25b_merge_commit.md create mode 100644 docs/99_Archive/WP25b_release_notes.md diff --git a/docs/00_General/00_documentation_map.md b/docs/00_General/00_documentation_map.md index 97d9265..49c3ece 100644 --- a/docs/00_General/00_documentation_map.md +++ b/docs/00_General/00_documentation_map.md @@ -51,7 +51,7 @@ Das Repository ist in **logische Domänen** unterteilt. | `03_tech_retrieval_scoring.md` | **Suche.** Die mathematischen Formeln für Scoring, Hybrid Search und Explanation Layer. | | `03_tech_chat_backend.md` | **API & LLM.** Implementation des Routers, Traffic Control (Semaphore) und Feedback-Traceability. | | `03_tech_frontend.md` | **UI & Graph.** Architektur des Streamlit-Frontends, State-Management, Cytoscape-Integration und Editor-Logik. | -| `03_tech_configuration.md` | **Config.** Referenztabellen für `.env`, `types.yaml` und `retriever.yaml`. | +| `03_tech_configuration.md` | **Config.** Referenztabellen für `.env`, `types.yaml`, `decision_engine.yaml`, `llm_profiles.yaml`, `prompts.yaml`. **Neu:** Verbindungen zwischen Config-Dateien, Praxisbeispiel und Mermaid-Grafik. | | `03_tech_api_reference.md` | **API-Referenz.** Vollständige Dokumentation aller Endpunkte (`/query`, `/chat`, `/ingest`, `/graph`, etc.). | ### 📂 04_Operations (Betrieb) @@ -151,8 +151,8 @@ Damit dieses System wartbar bleibt (auch für KI-Agenten wie NotebookLM), gelten ## 6. Dokumentations-Status -**Aktuelle Version:** 2.9.3 -**Letzte Aktualisierung:** 2025-12-31 +**Aktuelle Version:** 3.1.1 +**Letzte Aktualisierung:** 2026-01-02 **Status:** ✅ Vollständig und aktiv gepflegt **Hinweis:** Diese Dokumentation wird kontinuierlich aktualisiert. Bei Fragen oder Verbesserungsvorschlägen bitte im Repository melden. \ No newline at end of file diff --git a/docs/00_General/00_glossary.md b/docs/00_General/00_glossary.md index 449ae61..1e29c47 100644 --- a/docs/00_General/00_glossary.md +++ b/docs/00_General/00_glossary.md @@ -2,8 +2,8 @@ doc_type: glossary audience: all status: active -version: 3.0.0 -context: "Zentrales Glossar für Mindnet v3.0.0. Enthält Definitionen zu Hybrid-Cloud Resilienz, WP-14 Modularisierung, WP-15b Two-Pass Ingestion, WP-15c Multigraph-Support, WP-25 Agentic Multi-Stream RAG, WP-25a Mixture of Experts (MoE) und Mistral-safe Parsing." +version: 3.1.1 +context: "Zentrales Glossar für Mindnet v3.1.1. Enthält Definitionen zu Hybrid-Cloud Resilienz, WP-14 Modularisierung, WP-15b Two-Pass Ingestion, WP-15c Multigraph-Support, WP-25 Agentic Multi-Stream RAG, WP-25a Mixture of Experts (MoE), WP-25b Lazy-Prompt-Orchestration und Mistral-safe Parsing." --- # Mindnet Glossar @@ -59,4 +59,9 @@ context: "Zentrales Glossar für Mindnet v3.0.0. Enthält Definitionen zu Hybrid * **LLM-Profil:** Zentrale Definition in `llm_profiles.yaml`, die Provider, Modell, Temperature und Fallback-Profil für eine spezifische Aufgabe festlegt (z.B. `synthesis_pro`, `tech_expert`, `ingest_validator`). * **Fallback-Kaskade (WP-25a):** Rekursive Fallback-Logik, bei der bei Fehlern automatisch auf das `fallback_profile` umgeschaltet wird, bis der terminale Endpunkt (`identity_safe`) erreicht wird. Schutz gegen Zirkel-Referenzen via `visited_profiles`-Tracking. * **Pre-Synthesis Kompression (WP-25a):** Asynchrone Verdichtung überlanger Wissens-Streams vor der Synthese, um Token-Verbrauch zu reduzieren und die Synthese zu beschleunigen. Nutzt `compression_profile` (z.B. `compression_fast`). -* **Profilgesteuerte Validierung (WP-25a):** Semantische Kanten-Validierung in der Ingestion erfolgt zwingend über das MoE-Profil `ingest_validator` (Temperature 0.0 für Determinismus), unabhängig von der globalen Provider-Konfiguration. \ No newline at end of file +* **Profilgesteuerte Validierung (WP-25a):** Semantische Kanten-Validierung in der Ingestion erfolgt zwingend über das MoE-Profil `ingest_validator` (Temperature 0.0 für Determinismus), unabhängig von der globalen Provider-Konfiguration. +* **Lazy-Prompt-Orchestration (WP-25b):** Hierarchisches Prompt-Resolution-System, das Prompts erst im Moment des Modellaustauschs lädt, basierend auf dem exakt aktiven Modell. Ermöglicht modell-spezifisches Tuning und maximale Resilienz bei Modell-Fallbacks. +* **Hierarchische Prompt-Resolution (WP-25b):** Dreistufige Auflösungs-Logik: Level 1 (Modell-ID) → Level 2 (Provider) → Level 3 (Default). Gewährleistet, dass jedes Modell das optimale Template erhält. +* **PROMPT-TRACE (WP-25b):** Logging-Mechanismus, der die genutzte Prompt-Auflösungs-Ebene protokolliert (`🎯 Level 1`, `📡 Level 2`, `⚓ Level 3`). Bietet vollständige Transparenz über die genutzten Instruktionen. +* **Ultra-robustes Intent-Parsing (WP-25b):** Regex-basierter Intent-Parser in der DecisionEngine, der Modell-Artefakte wie `[/S]`, `` oder Newlines zuverlässig bereinigt, um präzises Strategie-Routing zu gewährleisten. +* **Differenzierte Ingestion-Validierung (WP-25b):** Unterscheidung zwischen transienten Fehlern (Netzwerk, Timeout) und permanenten Fehlern (Config, Validation). Transiente Fehler erlauben die Kante (Datenverlust vermeiden), permanente Fehler lehnen sie ab (Graph-Qualität schützen). \ No newline at end of file diff --git a/docs/02_concepts/02_concept_ai_personality.md b/docs/02_concepts/02_concept_ai_personality.md index d074523..ca4108b 100644 --- a/docs/02_concepts/02_concept_ai_personality.md +++ b/docs/02_concepts/02_concept_ai_personality.md @@ -1,10 +1,10 @@ --- doc_type: concept audience: architect, product_owner -scope: ai, router, personas, resilience, agentic_rag, moe +scope: ai, router, personas, resilience, agentic_rag, moe, lazy_prompts status: active -version: 3.0.0 -context: "Fachkonzept der hybriden KI-Persönlichkeit, Agentic Multi-Stream RAG, WP-25a Mixture of Experts (MoE), Provider-Kaskade und kognitiven Resilienz (Deep Fallback)." +version: 3.1.1 +context: "Fachkonzept der hybriden KI-Persönlichkeit, Agentic Multi-Stream RAG, WP-25a Mixture of Experts (MoE), WP-25b Lazy-Prompt-Orchestration, Provider-Kaskade und kognitiven Resilienz (Deep Fallback)." --- # Konzept: KI-Persönlichkeit & Router diff --git a/docs/03_Technical_References/03_tech_chat_backend.md b/docs/03_Technical_References/03_tech_chat_backend.md index bb6e2e3..9766654 100644 --- a/docs/03_Technical_References/03_tech_chat_backend.md +++ b/docs/03_Technical_References/03_tech_chat_backend.md @@ -1,10 +1,10 @@ --- doc_type: technical_reference audience: developer, architect -scope: backend, chat, llm_service, traffic_control, resilience, agentic_rag, moe +scope: backend, chat, llm_service, traffic_control, resilience, agentic_rag, moe, lazy_prompts status: active -version: 3.0.0 -context: "Technische Implementierung des FastAPI-Routers, des hybriden LLMService (v3.5.2), WP-25 Agentic Multi-Stream RAG, WP-25a Mixture of Experts (MoE) und WP-20 Resilienz-Logik." +version: 3.1.1 +context: "Technische Implementierung des FastAPI-Routers, des hybriden LLMService (v3.5.5), WP-25 Agentic Multi-Stream RAG, WP-25a Mixture of Experts (MoE), WP-25b Lazy-Prompt-Orchestration und WP-20 Resilienz-Logik." --- # Chat Backend & Agentic Multi-Stream RAG @@ -13,7 +13,7 @@ context: "Technische Implementierung des FastAPI-Routers, des hybriden LLMServic Der zentrale Einstiegspunkt für jede Chatanfrage ist der **Hybrid Router** (`app/routers/chat.py`). Seit WP-25 agiert das System als **Agentic Orchestrator**, der Nutzeranfragen analysiert, in parallele Wissens-Streams aufteilt und diese zu einer kontextreichen, wertebasierten Antwort synthetisiert. -### 1.1 Intent-Erkennung (Hybrid-Modus) +### 1.1 Intent-Erkennung (Hybrid-Modus - WP-25b) Der Router nutzt einen **Hybrid-Modus** mit Keyword-Fast-Path und LLM-Slow-Path: @@ -24,9 +24,11 @@ Der Router nutzt einen **Hybrid-Modus** mit Keyword-Fast-Path und LLM-Slow-Path: 2. **Type Keywords (Interview-Modus):** * Lädt `types.yaml` und prüft `detection_keywords` für Objekt-Erkennung. * Wenn Match und keine Frage: **INTERVIEW Modus** (Datenerfassung). -3. **LLM Slow-Path (Semantische Analyse):** +3. **LLM Slow-Path (Semantische Analyse - WP-25b):** * Wenn unklar: Anfrage an `DecisionEngine._determine_strategy()` zur LLM-basierten Klassifizierung. - * Nutzt `intent_router_v1` Prompt aus `prompts.yaml`. + * **Lazy-Prompt-Loading:** Nutzt `prompt_key="intent_router_v1"` mit `variables={"query": query}` + * **Ultra-robustes Parsing:** Regex-basierter Intent-Parser bereinigt Modell-Artefakte (z.B. `CODING[/S]` → `CODING`) + * **Fallback:** Bei unklarem Intent → `FACT_WHAT` ### 1.2 Mixture of Experts (MoE) Architektur (WP-25a) @@ -52,13 +54,32 @@ Der `LLMService` (v3.5.2) implementiert eine automatische Fallback-Logik: * **Synthese:** Nutzt `llm_profile` aus Strategie-Konfiguration * **Ingestion:** Nutzt `ingest_validator` für binäre Validierungen -### 1.3 Prompt-Auflösung (Bulletproof Resolution) +### 1.3 Hierarchisches Prompt-Resolution-System (WP-25b) -Um Kompatibilitätsprobleme mit verschachtelten YAML-Prompts zu vermeiden, nutzt der Router die Methode `llm.get_prompt()`. Diese implementiert eine **Provider-Kaskade**: -* **Spezifischer Provider:** Das System sucht zuerst nach einem Prompt für den aktiv konfigurierten Provider (z.B. `openrouter`). -* **Cloud-Stil Fallback:** Existiert dieser nicht, erfolgt ein Fallback auf das `gemini`-Template. -* **Basis-Fallback:** Als letzte Instanz wird das `ollama`-Template geladen. -* **String-Garantie:** Die Methode garantiert die Rückgabe eines Strings (selbst bei verschachtelten YAML-Dicts), was 500-Fehler bei String-Operationen wie `.replace()` oder `.format()` verhindert. +Seit WP-25b nutzt MindNet eine **dreistufige hierarchische Prompt-Auflösung** mit Lazy-Loading. Prompts werden erst im Moment des Modellaustauschs geladen, basierend auf dem exakt aktiven Modell. + +**Hierarchische Auflösung (`llm_service.py` v3.5.5):** + +1. **Level 1 (Modell-ID):** Suche nach exakten Übereinstimmungen für die Modell-ID (z.B. `google/gemini-2.0-flash-exp:free`). + * **Vorteil:** Modell-spezifische Optimierungen (z.B. für Gemini 2.0, Llama 3.3, Qwen 2.5) + * **Logging:** `🎯 [PROMPT-TRACE] Level 1 Match: Model-specific` + +2. **Level 2 (Provider):** Fallback auf allgemeine Provider-Anweisungen (z.B. `openrouter` oder `ollama`). + * **Vorteil:** Bewährte Standards aus v3.1.2 bleiben erhalten + * **Logging:** `📡 [PROMPT-TRACE] Level 2 Match: Provider-fallback` + +3. **Level 3 (Default):** Globaler Sicherheits-Satz zur Vermeidung von Fehlern bei unbekannten Konfigurationen. + * **Fallback-Kette:** `default` → `gemini` → `ollama` → `""` + * **Logging:** `⚓ [PROMPT-TRACE] Level 3 Match: Global Default` + +**Lazy-Prompt-Orchestration:** +* **Lazy Loading:** Prompts werden erst zur Laufzeit geladen, wenn das aktive Modell bekannt ist +* **Parameter:** `prompt_key` und `variables` statt vorformatierter Strings +* **Vorteil:** Maximale Resilienz bei Modell-Fallbacks (Cloud → Local) +* **Traceability:** Vollständige Transparenz über genutzte Instruktionen via `[PROMPT-TRACE]` Logs + +**String-Garantie:** +Die Methode garantiert die Rückgabe eines Strings (selbst bei verschachtelten YAML-Dicts), was 500-Fehler bei String-Operationen wie `.replace()` oder `.format()` verhindert. ### 1.4 Multi-Stream Retrieval (WP-25) diff --git a/docs/03_Technical_References/03_tech_configuration.md b/docs/03_Technical_References/03_tech_configuration.md index fb35a5f..1f0b2d7 100644 --- a/docs/03_Technical_References/03_tech_configuration.md +++ b/docs/03_Technical_References/03_tech_configuration.md @@ -1,10 +1,10 @@ --- doc_type: technical_reference audience: developer, admin -scope: configuration, env, registry, scoring, resilience, modularization, agentic_rag, moe +scope: configuration, env, registry, scoring, resilience, modularization, agentic_rag, moe, lazy_prompts status: active -version: 3.0.0 -context: "Umfassende Referenztabellen für Umgebungsvariablen (inkl. Hybrid-Cloud & WP-76), YAML-Konfigurationen, Edge Registry Struktur, WP-25 Multi-Stream RAG und WP-25a Mixture of Experts (MoE) unter Berücksichtigung von WP-14." +version: 3.1.1 +context: "Umfassende Referenztabellen für Umgebungsvariablen (inkl. Hybrid-Cloud & WP-76), YAML-Konfigurationen, Edge Registry Struktur, WP-25 Multi-Stream RAG, WP-25a Mixture of Experts (MoE) und WP-25b Lazy-Prompt-Orchestration unter Berücksichtigung von WP-14." --- # Konfigurations-Referenz @@ -302,13 +302,47 @@ Die Strategie `INTERVIEW` dient der strukturierten Datenerfassung. > **Hinweis:** Da spezifische Schemas für Projekte oder Erfahrungen direkt in der `types.yaml` definiert werden, dient die `decision_engine.yaml` hier primär als Fallback für generische Datenaufnahmen. -### 5.6 Prompts-Konfiguration (`prompts.yaml` v3.1.2) +### 5.6 Prompts-Konfiguration (`prompts.yaml` v3.2.2 - WP-25b) -Seit WP-25 nutzen die Synthese-Templates explizite Stream-Variablen: +Seit WP-25b nutzt MindNet eine **hierarchische Prompt-Struktur** mit Lazy-Loading. Prompts werden erst zur Laufzeit geladen, basierend auf dem exakt aktiven Modell. -**Template-Struktur:** +**Hierarchische Template-Struktur:** ```yaml decision_synthesis_v1: + # Level 1: Modell-spezifisch (höchste Priorität) + "google/gemini-2.0-flash-exp:free": | + WERTE & PRINZIPIEN (Identität): + {values_stream} + + OPERATIVE FAKTEN (Realität): + {facts_stream} + + RISIKO-RADAR (Konsequenzen): + {risk_stream} + + ENTSCHEIDUNGSFRAGE: + {query} + Nutze deine hohe Reasoning-Kapazität für eine tiefe Synthese. + + "meta-llama/llama-3.3-70b-instruct:free": | + Erstelle eine fundierte Synthese für die Frage: "{query}" + Nutze die Daten: {values_stream}, {facts_stream} und {risk_stream}. + Trenne klare Fakten von Erfahrungen. Bleibe strikt beim bereitgestellten Kontext. + + # Level 2: Provider-Fallback (mittlere Priorität) + openrouter: | + WERTE & PRINZIPIEN (Identität): + {values_stream} + + OPERATIVE FAKTEN (Realität): + {facts_stream} + + RISIKO-RADAR (Konsequenzen): + {risk_stream} + + ENTSCHEIDUNGSFRAGE: + {query} + ollama: | WERTE & PRINZIPIEN (Identität): {values_stream} @@ -321,13 +355,31 @@ decision_synthesis_v1: ENTSCHEIDUNGSFRAGE: {query} + + # Level 3: Global Default (niedrigste Priorität) + default: | + Synthetisiere die folgenden Informationen für: {query} + {values_stream} | {facts_stream} | {risk_stream} ``` +**Auflösungs-Logik:** +1. **Level 1:** Exakte Modell-ID (z.B. `google/gemini-2.0-flash-exp:free`) +2. **Level 2:** Provider-Fallback (z.B. `openrouter`, `ollama`, `gemini`) +3. **Level 3:** Global Default (`default` → `gemini` → `ollama` → `""`) + +**Lazy-Loading:** +* Prompts werden erst zur Laufzeit geladen, wenn das aktive Modell bekannt ist +* **Parameter:** `prompt_key` und `variables` statt vorformatierter Strings +* **Vorteil:** Maximale Resilienz bei Modell-Fallbacks (Cloud → Local) + **Pre-Initialization:** Alle möglichen Stream-Variablen werden vorab initialisiert (verhindert KeyErrors bei unvollständigen Konfigurationen). -**Provider-spezifische Templates:** -Separate Versionen für Ollama, Gemini und OpenRouter. +**PROMPT-TRACE Logging:** +Das System protokolliert die genutzte Auflösungs-Ebene: +* `🎯 [PROMPT-TRACE] Level 1 Match: Model-specific` +* `📡 [PROMPT-TRACE] Level 2 Match: Provider-fallback` +* `⚓ [PROMPT-TRACE] Level 3 Match: Global Default` --- @@ -404,6 +456,261 @@ values_stream: --- +## 7. Konfigurations-Verbindungen & Datenfluss + +Die vier zentralen Konfigurationsdateien (`types.yaml`, `decision_engine.yaml`, `llm_profiles.yaml`, `prompts.yaml`) arbeiten eng zusammen, um das agentische Multi-Stream RAG System zu steuern. Diese Sektion erklärt die Verbindungen und zeigt einen konkreten Praxisablauf. + +### 7.1 Architektur-Übersicht + +```mermaid +graph TB + subgraph "1. Typ-Definition (types.yaml)" + T1[Typ: value
chunking_profile: structured_strict
retriever_weight: 1.00] + T2[Typ: risk
chunking_profile: sliding_short
retriever_weight: 0.85] + T3[Typ: project
chunking_profile: sliding_smart_edges
retriever_weight: 0.97] + end + + subgraph "2. Stream-Konfiguration (decision_engine.yaml)" + D1[values_stream
filter_types: value, principle, belief...
llm_profile: identity_safe
compression_profile: identity_safe] + D2[risk_stream
filter_types: risk, obstacle, bias
llm_profile: synthesis_pro
compression_profile: compression_fast] + D3[facts_stream
filter_types: project, decision, task...
llm_profile: synthesis_pro
compression_profile: compression_fast] + end + + subgraph "3. Strategie-Komposition (decision_engine.yaml)" + S1[DECISION Strategie
use_streams: values_stream, facts_stream, risk_stream
llm_profile: synthesis_pro
prompt_template: decision_synthesis_v1] + end + + subgraph "4. Experten-Profile (llm_profiles.yaml)" + P1[synthesis_pro
provider: openrouter
model: google/gemini-2.0-flash-exp:free
temperature: 0.7
fallback_profile: synthesis_backup] + P2[compression_fast
provider: openrouter
model: mistralai/mistral-7b-instruct:free
temperature: 0.1
fallback_profile: identity_safe] + P3[identity_safe
provider: ollama
model: phi3:mini
temperature: 0.2
fallback_profile: null] + end + + subgraph "5. Prompt-Templates (prompts.yaml)" + PR1[decision_synthesis_v1
Level 1: google/gemini-2.0-flash-exp:free
Level 2: openrouter
Level 3: default] + end + + T1 -->|filter_types| D1 + T2 -->|filter_types| D2 + T3 -->|filter_types| D3 + + D1 -->|use_streams| S1 + D2 -->|use_streams| S1 + D3 -->|use_streams| S1 + + S1 -->|llm_profile| P1 + D1 -->|llm_profile| P3 + D2 -->|compression_profile| P2 + D3 -->|compression_profile| P2 + + S1 -->|prompt_template| PR1 + P1 -->|model lookup| PR1 + + style T1 fill:#e1f5ff + style T2 fill:#e1f5ff + style T3 fill:#e1f5ff + style D1 fill:#fff4e1 + style D2 fill:#fff4e1 + style D3 fill:#fff4e1 + style S1 fill:#ffe1f5 + style P1 fill:#e1ffe1 + style P2 fill:#e1ffe1 + style P3 fill:#e1ffe1 + style PR1 fill:#f5e1ff +``` + +### 7.2 Verbindungs-Matrix + +| Von | Zu | Verbindung | Beschreibung | +| :--- | :--- | :--- | :--- | +| **`types.yaml`** | **`decision_engine.yaml`** | `filter_types` | Streams filtern Notizen basierend auf Typen aus `types.yaml`. Die Liste `filter_types: ["value", "principle", "belief"]` muss exakt den Typ-Namen aus `types.yaml` entsprechen. | +| **`types.yaml`** | **`decision_engine.yaml`** | `detection_keywords` | Keywords aus `types.yaml` werden für den Interview-Modus verwendet (z.B. "Projekt" + "neu" → `INTERVIEW`). | +| **`decision_engine.yaml`** | **`llm_profiles.yaml`** | `router_profile` | Intent-Erkennung nutzt das Profil `compression_fast` für schnelle Klassifizierung. | +| **`decision_engine.yaml`** | **`llm_profiles.yaml`** | `llm_profile` (Stream) | Jeder Stream definiert sein eigenes Profil für Retrieval und Kompression (z.B. `identity_safe` für Privacy). | +| **`decision_engine.yaml`** | **`llm_profiles.yaml`** | `llm_profile` (Strategie) | Die finale Synthese nutzt das Strategie-Profil (z.B. `synthesis_pro` für DECISION). | +| **`decision_engine.yaml`** | **`llm_profiles.yaml`** | `compression_profile` | Überlange Streams werden via `compression_profile` verdichtet (z.B. `compression_fast`). | +| **`decision_engine.yaml`** | **`prompts.yaml`** | `prompt_template` | Strategien referenzieren Template-Keys (z.B. `decision_synthesis_v1`). | +| **`llm_profiles.yaml`** | **`prompts.yaml`** | Hierarchische Auflösung | Das aktive Modell aus dem Profil bestimmt, welcher Prompt-Level geladen wird (Model-ID → Provider → Default). | +| **`llm_profiles.yaml`** | **`llm_profiles.yaml`** | `fallback_profile` | Rekursive Fallback-Kaskade bei Fehlern (z.B. `synthesis_pro` → `synthesis_backup` → `identity_safe`). | + +### 7.3 Praxisbeispiel: DECISION-Anfrage + +**User-Anfrage:** `"Soll ich das neue Projekt starten?"` + +#### Schritt 1: Intent-Erkennung + +**Datei:** `decision_engine.yaml` +```yaml +settings: + router_profile: "compression_fast" # → llm_profiles.yaml + router_prompt_key: "intent_router_v1" # → prompts.yaml +``` + +**Ablauf:** +1. System prüft `trigger_keywords` in `DECISION` Strategie → findet `"soll ich"` → **Intent: DECISION** +2. Falls kein Keyword-Match: LLM-Router nutzt `compression_fast` Profil aus `llm_profiles.yaml` +3. Router lädt `intent_router_v1` aus `prompts.yaml` (hierarchisch basierend auf aktivem Modell) + +#### Schritt 2: Stream-Aktivierung + +**Datei:** `decision_engine.yaml` +```yaml +strategies: + DECISION: + use_streams: ["values_stream", "facts_stream", "risk_stream"] + llm_profile: "synthesis_pro" # → llm_profiles.yaml + prompt_template: "decision_synthesis_v1" # → prompts.yaml +``` + +**Ablauf:** +1. System aktiviert drei parallele Streams: `values_stream`, `facts_stream`, `risk_stream` + +#### Schritt 3: Stream-Konfiguration & Typ-Filterung + +**Datei:** `decision_engine.yaml` (Streams) + `types.yaml` (Typ-Definitionen) + +```yaml +# decision_engine.yaml +values_stream: + filter_types: ["value", "principle", "belief", "trait", "boundary", "need", "motivation"] + llm_profile: "identity_safe" # → llm_profiles.yaml + compression_profile: "identity_safe" # → llm_profiles.yaml + query_template: "Welche meiner Werte und Prinzipien betreffen: {query}" + +facts_stream: + filter_types: ["project", "decision", "task", "goal", "event", "state"] + llm_profile: "synthesis_pro" # → llm_profiles.yaml + compression_profile: "compression_fast" # → llm_profiles.yaml + query_template: "Status, Ressourcen und Fakten zu: {query}" + +risk_stream: + filter_types: ["risk", "obstacle", "bias"] + llm_profile: "synthesis_pro" # → llm_profiles.yaml + compression_profile: "compression_fast" # → llm_profiles.yaml + query_template: "Gefahren, Hindernisse oder Risiken bei: {query}" +``` + +**Ablauf:** +1. **Values Stream:** Sucht in Qdrant nach Notizen mit `type IN ["value", "principle", "belief", ...]` (definiert in `types.yaml`) +2. **Facts Stream:** Sucht nach Notizen mit `type IN ["project", "decision", "task", ...]` (definiert in `types.yaml`) +3. **Risk Stream:** Sucht nach Notizen mit `type IN ["risk", "obstacle", "bias"]` (definiert in `types.yaml`) + +#### Schritt 4: Profil-Auflösung & Modell-Auswahl + +**Datei:** `llm_profiles.yaml` + +```yaml +synthesis_pro: + provider: "openrouter" + model: "google/gemini-2.0-flash-exp:free" + temperature: 0.7 + fallback_profile: "synthesis_backup" # → Rekursiver Fallback + +compression_fast: + provider: "openrouter" + model: "mistralai/mistral-7b-instruct:free" + temperature: 0.1 + fallback_profile: "identity_safe" + +identity_safe: + provider: "ollama" + model: "phi3:mini" + temperature: 0.2 + fallback_profile: null # Terminaler Endpunkt +``` + +**Ablauf:** +1. **Values Stream:** Nutzt `identity_safe` → Ollama/phi3:mini (lokal, Privacy) +2. **Facts Stream:** Nutzt `synthesis_pro` → OpenRouter/Gemini 2.0 (Cloud) +3. **Risk Stream:** Nutzt `synthesis_pro` → OpenRouter/Gemini 2.0 (Cloud) +4. **Kompression:** Falls Stream > `compression_threshold`, nutzt `compression_fast` → OpenRouter/Mistral 7B + +#### Schritt 5: Prompt-Loading (Hierarchische Auflösung) + +**Datei:** `prompts.yaml` + +```yaml +decision_synthesis_v1: + # Level 1: Modell-spezifisch (höchste Priorität) + "google/gemini-2.0-flash-exp:free": | + Agiere als strategischer Partner für: {query} + WERTE: {values_stream} | FAKTEN: {facts_stream} | RISIKEN: {risk_stream} + Prüfe die Fakten gegen meine Werte. Zeige Zielkonflikte auf. Gib eine klare Empfehlung. + + # Level 2: Provider-Fallback + openrouter: | + Strategische Multi-Stream Analyse für: {query} + Werte-Basis: {values_stream} | Fakten: {facts_stream} | Risiken: {risk_stream} + Bitte wäge ab und gib eine Empfehlung. + + # Level 3: Global Default + default: "Prüfe {query} gegen Werte {values_stream} und Fakten {facts_stream}." +``` + +**Ablauf:** +1. System hat `synthesis_pro` Profil geladen → Modell: `google/gemini-2.0-flash-exp:free` +2. System sucht in `prompts.yaml` nach `decision_synthesis_v1`: + - **Level 1:** Findet exakten Match für `google/gemini-2.0-flash-exp:free` → **Verwendet diesen Prompt** + - Falls nicht gefunden: **Level 2** → `openrouter` Fallback + - Falls nicht gefunden: **Level 3** → `default` Fallback +3. Prompt wird mit Stream-Variablen formatiert: `{values_stream}`, `{facts_stream}`, `{risk_stream}`, `{query}` + +#### Schritt 6: Finale Synthese + +**Ablauf:** +1. System ruft LLM auf mit: + - **Profil:** `synthesis_pro` (OpenRouter/Gemini 2.0, Temperature 0.7) + - **Prompt:** Level-1 Template aus `prompts.yaml` (modell-spezifisch optimiert) + - **Variablen:** Formatierte Stream-Inhalte +2. Falls Fehler (z.B. Rate-Limit 429): + - **Fallback:** `synthesis_backup` (Llama 3.3) + - **Prompt:** Automatisch Level-2 (`openrouter`) oder Level-3 (`default`) geladen +3. Antwort wird an User zurückgegeben + +### 7.4 Konfigurations-Synchronisation Checkliste + +Beim Ändern einer Konfigurationsdatei müssen folgende Abhängigkeiten geprüft werden: + +**✅ `types.yaml` ändern:** +- [ ] Prüfe, ob `filter_types` in `decision_engine.yaml` Streams noch gültig sind +- [ ] Prüfe, ob `detection_keywords` für Interview-Modus noch passen +- [ ] Prüfe, ob `chunking_profile` noch existiert (in `types.yaml` definiert) + +**✅ `decision_engine.yaml` ändern:** +- [ ] Prüfe, ob alle `filter_types` in Streams existieren in `types.yaml` +- [ ] Prüfe, ob alle `llm_profile` / `compression_profile` existieren in `llm_profiles.yaml` +- [ ] Prüfe, ob alle `prompt_template` Keys existieren in `prompts.yaml` + +**✅ `llm_profiles.yaml` ändern:** +- [ ] Prüfe, ob `fallback_profile` Referenzen zirkulär sind (Schutz: `visited_profiles`) +- [ ] Prüfe, ob alle referenzierten Profile existieren +- [ ] Prüfe, ob Modell-IDs mit `prompts.yaml` Level-1 Keys übereinstimmen (optional, aber empfohlen) + +**✅ `prompts.yaml` ändern:** +- [ ] Prüfe, ob alle `prompt_template` Keys aus `decision_engine.yaml` existieren +- [ ] Prüfe, ob Modell-spezifische Keys (Level 1) mit `llm_profiles.yaml` Modell-IDs übereinstimmen +- [ ] Prüfe, ob alle Stream-Variablen (`{values_stream}`, `{facts_stream}`, etc.) initialisiert werden + +### 7.5 Debugging-Tipps + +**Problem:** Stream findet keine Notizen +- **Prüfung:** `filter_types` in Stream stimmt mit Typ-Namen in `types.yaml` überein? (Case-sensitive!) +- **Prüfung:** Existieren Notizen mit diesen Typen im Vault? + +**Problem:** Falsches Modell wird verwendet +- **Prüfung:** `llm_profile` in Stream/Strategie existiert in `llm_profiles.yaml`? +- **Prüfung:** `fallback_profile` Kaskade führt zu unerwartetem Modell? + +**Problem:** Prompt wird nicht gefunden +- **Prüfung:** `prompt_template` Key existiert in `prompts.yaml`? +- **Prüfung:** Hierarchische Auflösung (Level 1 → 2 → 3) funktioniert? (Logs: `[PROMPT-TRACE]`) + +**Problem:** Kompression wird nicht ausgelöst +- **Prüfung:** `compression_threshold` in Stream-Konfiguration gesetzt? +- **Prüfung:** `compression_profile` existiert in `llm_profiles.yaml`? + +--- + Auszug aus der decision_engine.yaml ```yaml strategies: diff --git a/docs/03_Technical_References/03_tech_ingestion_pipeline.md b/docs/03_Technical_References/03_tech_ingestion_pipeline.md index 00497cc..3371b2e 100644 --- a/docs/03_Technical_References/03_tech_ingestion_pipeline.md +++ b/docs/03_Technical_References/03_tech_ingestion_pipeline.md @@ -1,10 +1,10 @@ --- doc_type: technical_reference audience: developer, devops -scope: backend, ingestion, smart_edges, edge_registry, modularization, moe +scope: backend, ingestion, smart_edges, edge_registry, modularization, moe, lazy_prompts status: active version: 2.14.0 -context: "Detaillierte technische Beschreibung der Import-Pipeline, Two-Pass-Workflow (WP-15b), modularer Datenbank-Architektur (WP-14) und WP-25a profilgesteuerte Validierung. Integriert Mistral-safe Parsing und Deep Fallback." +context: "Detaillierte technische Beschreibung der Import-Pipeline, Two-Pass-Workflow (WP-15b), modularer Datenbank-Architektur (WP-14), WP-25a profilgesteuerte Validierung und WP-25b Lazy-Prompt-Orchestration. Integriert Mistral-safe Parsing und Deep Fallback." --- # Ingestion Pipeline & Smart Processing @@ -50,10 +50,15 @@ Der Prozess ist **asynchron**, **idempotent** und wird nun in zwei logische Durc * Bei Änderungen löscht `purge_artifacts()` via `app.core.ingestion.ingestion_db` alle alten Chunks und Edges der Note. * Die Namensauflösung erfolgt nun über das modularisierte `database`-Paket. 10. **Chunking anwenden:** Zerlegung des Textes basierend auf dem ermittelten Profil (siehe Kap. 3). -11. **Smart Edge Allocation & Semantic Validation (WP-15b / WP-25a):** +11. **Smart Edge Allocation & Semantic Validation (WP-15b / WP-25a / WP-25b):** * Der `SemanticAnalyzer` schlägt Kanten-Kandidaten vor. - * **Validierung (WP-25a):** Jeder Kandidat wird durch das LLM semantisch gegen das Ziel im **LocalBatchCache** geprüft. + * **Validierung (WP-25a/25b):** Jeder Kandidat wird durch das LLM semantisch gegen das Ziel im **LocalBatchCache** geprüft. * **Profilgesteuerte Validierung:** Nutzt das MoE-Profil `ingest_validator` (Temperature 0.0 für maximale Determinismus). + * **Lazy-Prompt-Loading (WP-25b):** Nutzt `prompt_key="edge_validation"` mit `variables` statt vorformatierter Strings. + * **Hierarchische Resolution:** Level 1 (Modell-ID) → Level 2 (Provider) → Level 3 (Default) + * **Differenzierte Fehlerbehandlung (WP-25b):** Unterscheidung zwischen transienten (Netzwerk) und permanenten (Config) Fehlern: + * **Transiente Fehler:** Timeout, Connection, Network → Kante wird erlaubt (Datenverlust vermeiden) + * **Permanente Fehler:** Config, Validation, Invalid Response → Kante wird abgelehnt (Graph-Qualität schützen) * **Fallback-Kaskade:** Bei Fehlern erfolgt automatischer Fallback via `fallback_profile` (z.B. `compression_fast` → `identity_safe`). * **Traffic Control:** Nutzung der neutralen `clean_llm_text` Funktion zur Bereinigung von Steuerzeichen (, [OUT]). * **Deep Fallback (v2.11.14):** Erkennt "Silent Refusals". Liefert die Cloud keine verwertbaren Kanten, wird ein lokaler Fallback via Ollama erzwungen. diff --git a/docs/04_Operations/04_admin_operations.md b/docs/04_Operations/04_admin_operations.md index b8f8bbb..73780aa 100644 --- a/docs/04_Operations/04_admin_operations.md +++ b/docs/04_Operations/04_admin_operations.md @@ -1,10 +1,10 @@ --- doc_type: operations_manual audience: admin, devops -scope: deployment, maintenance, backup, edge_registry, moe +scope: deployment, maintenance, backup, edge_registry, moe, lazy_prompts status: active -version: 3.0.0 -context: "Installationsanleitung, Systemd-Units und Wartungsprozesse für Mindnet v3.0.0 inklusive WP-25a Mixture of Experts (MoE) Konfiguration." +version: 3.1.1 +context: "Installationsanleitung, Systemd-Units und Wartungsprozesse für Mindnet v3.1.1 inklusive WP-25a Mixture of Experts (MoE) und WP-25b Lazy-Prompt-Orchestration Konfiguration." --- # Admin Operations Guide diff --git a/docs/05_Development/05_developer_guide.md b/docs/05_Development/05_developer_guide.md index cd8a4df..3fced84 100644 --- a/docs/05_Development/05_developer_guide.md +++ b/docs/05_Development/05_developer_guide.md @@ -1,10 +1,10 @@ --- doc_type: developer_guide audience: developer -scope: workflow, testing, architecture, modules, modularization, agentic_rag +scope: workflow, testing, architecture, modules, modularization, agentic_rag, lazy_prompts status: active -version: 2.9.3 -context: "Umfassender Guide für Entwickler: Modularisierte Architektur (WP-14), Two-Pass Ingestion (WP-15b), WP-25 Agentic Multi-Stream RAG, Modul-Interna, Setup und Git-Workflow." +version: 3.1.1 +context: "Umfassender Guide für Entwickler: Modularisierte Architektur (WP-14), Two-Pass Ingestion (WP-15b), WP-25 Agentic Multi-Stream RAG, WP-25a MoE, WP-25b Lazy-Prompt-Orchestration, Modul-Interna, Setup und Git-Workflow." --- # Mindnet Developer Guide & Workflow @@ -406,12 +406,34 @@ Mindnet lernt nicht durch Training (Fine-Tuning), sondern durch **Konfiguration* ```yaml synthesis_pro: provider: "openrouter" - model: "gemini-1.5-mistralai/mistral-7b-instruct:free" + model: "google/gemini-2.0-flash-exp:free" temperature: 0.7 fallback_profile: "synthesis_backup" ``` *Ergebnis (WP-25a):* Zentrale Steuerung von Provider, Modell und Temperature pro Aufgabe. Automatische Fallback-Kaskade bei Fehlern. +4. **Prompt-Template (`config/prompts.yaml` v3.2.2, WP-25b):** + ```yaml + decision_synthesis_v1: + # Level 1: Modell-spezifisch (höchste Priorität) + "google/gemini-2.0-flash-exp:free": | + WERTE & PRINZIPIEN (Identität): + {values_stream} + ... + + # Level 2: Provider-Fallback + openrouter: | + WERTE & PRINZIPIEN (Identität): + {values_stream} + ... + + # Level 3: Global Default + default: | + Synthetisiere die folgenden Informationen für: {query} + ... + ``` + *Ergebnis (WP-25b):* Hierarchische Prompt-Resolution mit Lazy-Loading. Prompts werden erst zur Laufzeit geladen, basierend auf aktivem Modell. Maximale Resilienz bei Modell-Fallbacks. + ### Workflow B: Graph-Farben ändern 1. Öffne `app/frontend/ui_config.py`. 2. Bearbeite das Dictionary `GRAPH_COLORS`. diff --git a/docs/06_Roadmap/06_active_roadmap.md b/docs/06_Roadmap/06_active_roadmap.md index 0ff199f..6456809 100644 --- a/docs/06_Roadmap/06_active_roadmap.md +++ b/docs/06_Roadmap/06_active_roadmap.md @@ -2,14 +2,14 @@ doc_type: roadmap audience: product_owner, developer status: active -version: 2.9.3 -context: "Aktuelle Planung für kommende Features (ab WP16), Release-Strategie und Historie der abgeschlossenen WPs nach WP-14/15b/15c/25." +version: 3.1.1 +context: "Aktuelle Planung für kommende Features (ab WP16), Release-Strategie und Historie der abgeschlossenen WPs nach WP-14/15b/15c/25/25a/25b." --- # Mindnet Active Roadmap -**Aktueller Stand:** v2.9.3 (Post-WP25: Agentic Multi-Stream RAG) -**Fokus:** Agentic Orchestration, Multi-Stream Retrieval & Wissens-Synthese. +**Aktueller Stand:** v3.1.1 (Post-WP25b: Lazy-Prompt-Orchestration & Full Resilience) +**Fokus:** Hierarchische Prompt-Resolution, Modell-spezifisches Tuning & maximale Resilienz. | Phase | Fokus | Status | | :--- | :--- | :--- | @@ -50,6 +50,8 @@ Eine Übersicht der implementierten Features zum schnellen Auffinden von Funktio | **WP-22** | **Content Lifecycle & Registry** | **Ergebnis:** SSOT via `01_edge_vocabulary.md`, Alias-Mapping, Status-Scoring (`stable`/`draft`) und Modularisierung der Scoring-Engine. | | **WP-15c** | **Multigraph-Support & Diversity Engine** | **Ergebnis:** Section-basierte Links, Note-Level Diversity Pooling, Super-Edge Aggregation, Provenance Firewall. Transformation zu einem hochpräzisen Multigraphen. | | **WP-25** | **Agentic Multi-Stream RAG Orchestration** | **Ergebnis:** Übergang von linearer RAG-Architektur zu paralleler Multi-Stream Engine. Intent-basiertes Routing (Hybrid Fast/Slow-Path), parallele Wissens-Streams (Values, Facts, Biography, Risk, Tech), Stream-Tracing und Template-basierte Wissens-Synthese. | +| **WP-25a** | **Mixture of Experts (MoE) & Fallback-Kaskade** | **Ergebnis:** Profilbasierte Experten-Architektur, rekursive Fallback-Kaskade, Pre-Synthesis Kompression, profilgesteuerte Ingestion und Embedding-Konsolidierung. | +| **WP-25b** | **Lazy-Prompt-Orchestration & Full Resilience** | **Ergebnis:** Hierarchisches Prompt-Resolution-System (3-stufig), Lazy-Prompt-Loading, ultra-robustes Intent-Parsing, differenzierte Ingestion-Validierung und PROMPT-TRACE Logging. | ### 2.1 WP-22 Lessons Learned * **Architektur:** Die Trennung von `retriever.py` und `retriever_scoring.py` war notwendig, um LLM-Context-Limits zu wahren und die Testbarkeit der mathematischen Formeln zu erhöhen. @@ -197,25 +199,9 @@ Der bisherige WP-15 Ansatz litt unter Halluzinationen (erfundene Kantentypen), h **Status:** ✅ Fertig (v3.0.0) ### WP-25a: Mixture of Experts (MoE) & Fallback-Kaskade -**Status:** ✅ Fertig (v3.0.0) +**Status:** ✅ Fertig (v3.1.0) -**Ergebnis:** Transformation 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. - -**Kern-Features:** -1. **Intent-basiertes Routing:** Hybrid-Modus mit Keyword Fast-Path und LLM Slow-Path -2. **Multi-Stream Retrieval:** Parallele Abfragen in spezialisierten Streams (Values, Facts, Biography, Risk, Tech) -3. **Stream-Tracing:** Jeder Treffer wird mit `stream_origin` markiert -4. **Wissens-Synthese:** Template-basierte Zusammenführung mit expliziten Stream-Variablen -5. **Fehler-Resilienz:** Einzelne Stream-Fehler blockieren nicht die gesamte Anfrage - -**Technische Details:** -- Decision Engine v1.0.3: Multi-Stream Orchestrator -- Chat Router v3.0.2: Hybrid Router Integration -- LLM Service v3.4.2: Ingest-Stability Patch -- decision_engine.yaml v3.1.6: Multi-Stream Konfiguration -- prompts.yaml v3.1.2: Stream-Templates - -**Ergebnis (WP-25a):** Transformation von MindNet von einer provider-basierten Steuerung auf eine **profilbasierte Experten-Architektur (Mixture of Experts)**. Jede Systemaufgabe wird einem dedizierten Profil zugewiesen, das Modell, Provider und Parameter unabhängig definiert. +**Ergebnis:** Transformation von MindNet von einer provider-basierten Steuerung auf eine **profilbasierte Experten-Architektur (Mixture of Experts)**. Jede Systemaufgabe wird einem dedizierten Profil zugewiesen, das Modell, Provider und Parameter unabhängig definiert. **Kern-Features:** 1. **Experten-Steuerung:** Zentrale Profile-Registry (`llm_profiles.yaml`) für alle LLM-Aufgaben @@ -233,10 +219,28 @@ Der bisherige WP-15 Ansatz litt unter Halluzinationen (erfundene Kantentypen), h - llm_profiles.yaml v1.3.0: Zentrale Experten-Registry - decision_engine.yaml v3.2.2: Decoupled MoE Logic -**Ausblick (WP-25b):** -- Prompt-Orchestration & Model-Specific Tuning +### WP-25b: Lazy-Prompt-Orchestration & Full Resilience +**Status:** ✅ Fertig (v3.1.1) + +**Ergebnis:** Umstellung von statischer Prompt-Formatierung auf eine **hierarchische Lazy-Prompt-Orchestration**. Prompts werden erst im Moment des Modellaustauschs geladen, basierend auf dem exakt aktiven Modell. Dies ermöglicht modell-spezifisches Tuning und maximale Resilienz bei Modell-Fallbacks. + +**Kern-Features:** +1. **Hierarchisches Prompt-Resolution-System:** Dreistufige Auflösung (Modell-ID → Provider → Default) +2. **Lazy-Loading:** Prompts werden erst zur Laufzeit geladen, wenn das aktive Modell bekannt ist +3. **Ultra-robustes Intent-Parsing:** Regex-basierter Parser bereinigt Modell-Artefakte (z.B. `CODING[/S]` → `CODING`) +4. **Differenzierte Ingestion-Validierung:** Unterscheidung zwischen transienten (Netzwerk) und permanenten (Config) Fehlern +5. **PROMPT-TRACE Logging:** Vollständige Transparenz über genutzte Instruktionen + +**Technische Details:** +- LLM Service v3.5.5: Hierarchische Prompt-Resolution mit Lazy-Loading +- Decision Engine v1.3.2: Ultra-robustes Intent-Parsing via Regex +- Ingestion Validation v2.14.0: Lazy-Prompt-Integration, differenzierte Fehlerbehandlung +- prompts.yaml v3.2.2: Hierarchische Struktur mit Modell-spezifischen Overrides + +**Ausblick (WP-25c):** - Kontext-Budgeting: Intelligente Token-Verteilung - Stream-specific Provider: Unterschiedliche KI-Modelle pro Wissensbereich +- Erweiterte Prompt-Optimierung: Dynamische Anpassung basierend auf Kontext und Historie --- ### WP-24 – Proactive Discovery & Agentic Knowledge Mining diff --git a/docs/99_Archive/WP25b_merge_commit.md b/docs/99_Archive/WP25b_merge_commit.md new file mode 100644 index 0000000..9efa15e --- /dev/null +++ b/docs/99_Archive/WP25b_merge_commit.md @@ -0,0 +1,97 @@ +# Branch Merge Commit: WP-25b + +**Branch:** `WP25b` +**Target:** `main` +**Version:** v3.1.1 +**Date:** 2026-01-02 + +--- + +## Commit Message + +``` +feat: Lazy-Prompt-Orchestration & Full Resilience (v3.1.1) + +### Hierarchisches Prompt-Resolution-System +- Dreistufige Auflösungs-Logik: Level 1 (Modell-ID) → Level 2 (Provider) → Level 3 (Default) +- Modell-spezifische Optimierungen für Gemini 2.0, Llama 3.3, Qwen 2.5 +- PROMPT-TRACE Logging für vollständige Transparenz +- Implementierung in `app/services/llm_service.py` (v3.5.5) + +### Lazy-Prompt-Orchestration +- Prompts werden erst zur Laufzeit geladen, basierend auf aktivem Modell +- Parameter: `prompt_key` und `variables` statt vorformatierter Strings +- Maximale Resilienz bei Modell-Fallbacks (Cloud → Local) +- Vollständige Integration in Chat, Ingestion und DecisionEngine + +### Ultra-robustes Intent-Parsing +- Regex-basierter Parser bereinigt Modell-Artefakte (z.B. `CODING[/S]` → `CODING`) +- Implementierung in `app/core/retrieval/decision_engine.py` (v1.3.2) +- Fehlerresistenz gegen Stop-Marker, Newlines oder Modell-Plaudereien + +### Differenzierte Ingestion-Validierung +- Unterscheidung zwischen transienten (Netzwerk) und permanenten (Config) Fehlern +- Transiente Fehler erlauben Kante (Datenverlust vermeiden) +- Permanente Fehler lehnen Kante ab (Graph-Qualität schützen) +- Implementierung in `app/core/ingestion/ingestion_validation.py` (v2.14.0) + +### Code-Komponenten +- `app/services/llm_service.py`: v3.5.5 (Hierarchische Prompt-Resolution, Lazy-Loading) +- `app/core/retrieval/decision_engine.py`: v1.3.2 (Ultra-robustes Intent-Parsing) +- `app/core/ingestion/ingestion_validation.py`: v2.14.0 (Lazy-Prompt-Integration) +- `app/routers/chat.py`: v3.0.3 (Lazy-Prompt-Loading für Chat-Synthese) + +### Konfiguration +- `config/prompts.yaml`: v3.2.2 (Hierarchische Struktur mit Modell-spezifischen Overrides) + - 100% Erhalt der Original-Prompts aus v3.1.2 für Provider-Ebene + - Integration von Modell-spezifischen Overrides + - Hinzufügen von `compression_template` + +### Dokumentation +- `03_tech_chat_backend.md`: Hierarchisches Prompt-Resolution-System +- `03_tech_configuration.md`: prompts.yaml hierarchische Struktur +- `02_concept_ai_personality.md`: Lazy-Prompt-Orchestration Konzept +- `03_tech_ingestion_pipeline.md`: Differenzierte Validierung +- `00_glossary.md`: Neue Begriffe (Lazy-Prompt, PROMPT-TRACE) +- `05_developer_guide.md`: Lazy-Prompt-Orchestration für Entwickler +- `06_active_roadmap.md`: WP25b als abgeschlossen markiert + +### Breaking Changes +- Keine Breaking Changes für Endbenutzer +- Vorformatierte Prompts werden weiterhin unterstützt (Abwärtskompatibilität) +- Neue API-Parameter `prompt_key` und `variables` optional + +### Migration +- Keine Migration erforderlich +- System funktioniert ohne Änderungen +- Optional: Modell-spezifische Prompts können in `prompts.yaml` definiert werden + +--- + +**Status:** ✅ WP-25b ist zu 100% implementiert und audit-geprüft. +**Nächster Schritt:** WP-25c (Kontext-Budgeting & Erweiterte Prompt-Optimierung). +``` + +--- + +## Zusammenfassung + +Dieser Merge führt die **Lazy-Prompt-Orchestration** in MindNet ein. Das System nutzt nun eine hierarchische Prompt-Auflösung mit Lazy-Loading, die Prompts erst zur Laufzeit lädt, basierend auf dem exakt aktiven Modell. + +**Kern-Features:** +- Hierarchisches Prompt-Resolution-System (3-stufig) +- Lazy-Prompt-Orchestration mit modell-spezifischem Tuning +- Ultra-robustes Intent-Parsing via Regex +- Differenzierte Ingestion-Validierung +- PROMPT-TRACE Logging für vollständige Transparenz + +**Technische Integrität:** +- Alle LLM-Aufrufe nutzen nun Lazy-Prompt-Loading +- Modell-Artefakte werden zuverlässig bereinigt +- Fehlerbehandlung differenziert zwischen transienten und permanenten Fehlern + +**Dokumentation:** +- Vollständige Aktualisierung aller relevanten Dokumente +- Neue Begriffe im Glossar +- Konfigurations-Referenz erweitert +- Developer Guide aktualisiert diff --git a/docs/99_Archive/WP25b_release_notes.md b/docs/99_Archive/WP25b_release_notes.md new file mode 100644 index 0000000..062eed1 --- /dev/null +++ b/docs/99_Archive/WP25b_release_notes.md @@ -0,0 +1,205 @@ +# MindNet v3.1.1 - Release Notes: WP-25b + +**Release Date:** 2026-01-02 +**Type:** Feature Release - Lazy-Prompt-Orchestration & Full Resilience +**Version:** 3.1.1 (WP-25b) + +--- + +## 🎯 Überblick + +Mit WP-25b wurde MindNet von statischer Prompt-Formatierung auf eine **hierarchische Lazy-Prompt-Orchestration** umgestellt. Prompts werden erst im Moment des Modellaustauschs geladen, basierend auf dem exakt aktiven Modell. Dies ermöglicht modell-spezifisches Tuning und maximale Resilienz bei Modell-Fallbacks. + +Diese Version markiert einen weiteren Architektur-Sprung: Von vorformatierter Prompt-Strings hin zu einer dynamischen, modell-spezifischen Prompt-Auflösung mit vollständiger Traceability. + +--- + +## ✨ Neue Features + +### 1. Hierarchisches Prompt-Resolution-System + +**Implementierung (`app/services/llm_service.py` v3.5.5):** + +Dreistufige Auflösungs-Logik für maximale Präzision und Resilienz: + +1. **Level 1 (Modell-ID):** Exakte Übereinstimmung für spezifische Modelle + * **Beispiel:** `google/gemini-2.0-flash-exp:free`, `meta-llama/llama-3.3-70b-instruct:free` + * **Vorteil:** Modell-spezifische Optimierungen für maximale Präzision + * **Logging:** `🎯 [PROMPT-TRACE] Level 1 Match: Model-specific` + +2. **Level 2 (Provider):** Fallback auf Provider-Standards + * **Beispiel:** `openrouter`, `ollama`, `gemini` + * **Vorteil:** Bewährte Standards aus v3.1.2 bleiben erhalten + * **Logging:** `📡 [PROMPT-TRACE] Level 2 Match: Provider-fallback` + +3. **Level 3 (Default):** Globaler Sicherheits-Satz + * **Fallback-Kette:** `default` → `gemini` → `ollama` → `""` + * **Vorteil:** Vermeidung von Fehlern bei unbekannten Konfigurationen + * **Logging:** `⚓ [PROMPT-TRACE] Level 3 Match: Global Default` + +**Vorteile:** +* **Modell-spezifisches Tuning:** Jedes Modell kann optimierte Prompts erhalten +* **Maximale Resilienz:** Bei Modell-Fallbacks wird automatisch das passende Template geladen +* **Traceability:** Vollständige Transparenz über genutzte Instruktionen + +### 2. Lazy-Prompt-Orchestration + +**Implementierung (`app/services/llm_service.py` v3.5.5):** + +* **Lazy Loading:** Prompts werden erst zur Laufzeit geladen, wenn das aktive Modell bekannt ist +* **Parameter:** `prompt_key` und `variables` statt vorformatierter Strings +* **Integration:** Vollständig in Chat, Ingestion und DecisionEngine integriert + +**Vorteile:** +* **Dynamische Anpassung:** Prompt wird basierend auf aktivem Modell geladen +* **Fallback-Resilienz:** Bei Cloud → Local Fallback wird automatisch das passende Template verwendet +* **Wartbarkeit:** Zentrale Konfiguration in `prompts.yaml` statt verstreuter String-Formatierungen + +### 3. Ultra-robustes Intent-Parsing + +**Implementierung (`app/core/retrieval/decision_engine.py` v1.3.2):** + +* **Regex-basierter Parser:** Bereinigt Modell-Artefakte zuverlässig +* **Beispiele:** `CODING[/S]` → `CODING`, `DECISION` → `DECISION` +* **Robustheit:** Ignoriert Stop-Marker, Newlines oder Plaudereien des Modells + +**Vorteile:** +* **Präzises Routing:** Strategie-Erkennung funktioniert auch bei freien Modellen mit Artefakten +* **Fehlerresistenz:** Systemabstürze durch fehlerhafte Modell-Antworten werden verhindert + +### 4. Differenzierte Ingestion-Validierung + +**Implementierung (`app/core/ingestion/ingestion_validation.py` v2.14.0):** + +* **Fehler-Differenzierung:** Unterscheidung zwischen transienten und permanenten Fehlern +* **Transiente Fehler:** Timeout, Connection, Network → Kante wird erlaubt (Datenverlust vermeiden) +* **Permanente Fehler:** Config, Validation, Invalid Response → Kante wird abgelehnt (Graph-Qualität schützen) + +**Vorteile:** +* **Datenintegrität:** Transiente Netzwerkfehler führen nicht zu Datenverlust +* **Graph-Qualität:** Permanente Konfigurationsfehler schützen vor fehlerhaften Kanten + +### 5. PROMPT-TRACE Logging + +**Implementierung (`app/services/llm_service.py` v3.5.5):** + +* **Vollständige Transparenz:** Protokollierung der genutzten Prompt-Auflösungs-Ebene +* **Log-Format:** `[PROMPT-TRACE] Level X Match: ...` +* **Debugging:** Einfache Nachverfolgung von Prompt-Entscheidungen + +**Vorteile:** +* **Debugging:** Schnelle Identifikation von Prompt-Problemen +* **Optimierung:** Verständnis, welche Prompts tatsächlich genutzt werden +* **Audit:** Vollständige Nachvollziehbarkeit der System-Entscheidungen + +--- + +## 🔧 Technische Änderungen + +### Konfigurationsdateien + +**Aktualisierte Dateien:** +* `config/prompts.yaml` v3.2.2: Hierarchische Struktur mit Modell-spezifischen Overrides + * **Erhalt:** 100% der Original-Prompts aus v3.1.2 für die Provider-Ebene + * **Neu:** Modell-spezifische Overrides für Gemini 2.0, Llama 3.3, Qwen 2.5 + * **Neu:** `compression_template` für DecisionEngine v1.3.0 + +### Code-Komponenten + +| Komponente | Version | Änderungen | +| :--- | :--- | :--- | +| `app/services/llm_service.py` | v3.5.5 | Hierarchische Prompt-Resolution, Lazy-Loading, PROMPT-TRACE | +| `app/core/retrieval/decision_engine.py` | v1.3.2 | Ultra-robustes Intent-Parsing via Regex | +| `app/core/ingestion/ingestion_validation.py` | v2.14.0 | Lazy-Prompt-Integration, differenzierte Fehlerbehandlung | +| `app/routers/chat.py` | v3.0.3 | Lazy-Prompt-Loading für Chat-Synthese | + +### API-Änderungen + +**Neue Parameter:** +* `prompt_key`: Schlüssel für Lazy-Loading (statt vorformatierter Strings) +* `variables`: Daten-Dict für Prompt-Formatierung + +**Veraltete Parameter:** +* Vorformatierte `prompt` Strings werden weiterhin unterstützt (Abwärtskompatibilität) + +--- + +## 🐛 Behobene Probleme + +- ✅ **Behoben:** Modell-Artefakte in Intent-Router (z.B. `CODING[/S]` → `CODING`) +- ✅ **Behoben:** Fehlende modell-spezifische Prompt-Optimierungen +- ✅ **Behoben:** Fehlerhafte Prompt-Auflösung bei Modell-Fallbacks +- ✅ **Behoben:** Undifferenzierte Fehlerbehandlung in Ingestion-Validierung + +--- + +## 📚 Dokumentation + +**Aktualisierte Dokumente:** +- ✅ `03_tech_chat_backend.md`: Hierarchisches Prompt-Resolution-System und Lazy-Prompt-Orchestration +- ✅ `03_tech_configuration.md`: prompts.yaml hierarchische Struktur dokumentiert +- ✅ `02_concept_ai_personality.md`: Lazy-Prompt-Orchestration Konzept +- ✅ `03_tech_ingestion_pipeline.md`: Differenzierte Validierung +- ✅ `00_glossary.md`: Neue Begriffe (Lazy-Prompt, PROMPT-TRACE, hierarchische Resolution) +- ✅ `05_developer_guide.md`: Lazy-Prompt-Orchestration für Entwickler +- ✅ `06_active_roadmap.md`: WP25b als abgeschlossen markiert + +--- + +## 🚀 Migration & Upgrade + +### Für Administratoren + +1. **Keine Breaking Changes:** + * Vorformatierte Prompts werden weiterhin unterstützt + * System funktioniert ohne Änderungen + +2. **Optional: Modell-spezifische Optimierungen:** + ```yaml + # config/prompts.yaml + decision_synthesis_v1: + "google/gemini-2.0-flash-exp:free": | + # Modell-spezifische Optimierung + ... + ``` + +3. **PROMPT-TRACE aktivieren:** + * Logs zeigen automatisch die genutzte Auflösungs-Ebene + * Keine zusätzliche Konfiguration erforderlich + +### Für Entwickler + +**API-Änderungen:** +* `LLMService.generate_raw_response()` unterstützt nun `prompt_key` und `variables` +* Vorformatierte `prompt` Strings bleiben für Abwärtskompatibilität erhalten + +**Best Practice:** +* Nutze `prompt_key` und `variables` für neue Implementierungen +* Lazy-Loading ermöglicht automatische Modell-Anpassung + +**Konfiguration:** +* Neue Modell-spezifische Prompts können in `prompts.yaml` definiert werden +* Hierarchische Struktur: Modell-ID → Provider → Default + +--- + +## 🔮 Ausblick (WP-25c) + +- Kontext-Budgeting: Intelligente Token-Verteilung +- Stream-specific Provider: Unterschiedliche KI-Modelle pro Wissensbereich +- Erweiterte Prompt-Optimierung: Dynamische Anpassung basierend auf Kontext und Historie + +--- + +## 📊 Metriken & Performance + +**Erwartete Verbesserungen:** +* **Präzision:** Modell-spezifische Prompts erhöhen Antwortqualität +* **Resilienz:** Automatische Prompt-Anpassung bei Modell-Fallbacks +* **Debugging:** PROMPT-TRACE vereinfacht Fehleranalyse +* **Wartbarkeit:** Zentrale Prompt-Konfiguration statt verstreuter Strings + +--- + +**Status:** ✅ WP-25b ist zu 100% implementiert und audit-geprüft. +**Nächster Schritt:** WP-25c (Kontext-Budgeting & Erweiterte Prompt-Optimierung). diff --git a/docs/README.md b/docs/README.md index a4de11d..f90b8f6 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,13 +2,13 @@ doc_type: documentation_index audience: all status: active -version: 2.9.3 +version: 3.1.1 context: "Zentraler Einstiegspunkt für die Mindnet-Dokumentation" --- # Mindnet Dokumentation -Willkommen in der Dokumentation von Mindnet v2.9.3! Diese Dokumentation hilft dir dabei, das System zu verstehen, zu nutzen und weiterzuentwickeln. +Willkommen in der Dokumentation von Mindnet v3.1.1! Diese Dokumentation hilft dir dabei, das System zu verstehen, zu nutzen und weiterzuentwickeln. ## 🚀 Schnellstart