Refactor ingestion validation and decision engine error handling: Differentiate between transient and permanent validation errors in ingestion validation to improve data integrity. Enhance decision engine configuration loading with schema validation and error handling for missing keys and YAML syntax errors. Update fallback synthesis prompt handling in LLMService for improved error recovery. Add new fallback synthesis prompts to prompts.yaml for better context-based responses.
This commit is contained in:
1 parent
a9d0874fe9
commit
8505538b34
6 files changed
+566
-11
No files matched your search
@@ -0,0 +1,483 @@
|
||||
# Code-Prüfung WP25b: Lazy-Prompt-Orchestration
|
||||
|
||||
**Datum:** 2026-01-02
|
||||
**Version:** WP25b (Lazy Prompt Integration)
|
||||
**Prüfer:** Auto (AI Code Review)
|
||||
|
||||
---
|
||||
|
||||
## 📋 Übersicht
|
||||
|
||||
Diese Prüfung analysiert die WP25b-Änderungen auf:
|
||||
- **Schwachstellen** (Security, Error Handling, Robustness)
|
||||
- **Inkonsistenzen** (Naming, Patterns, Architecture)
|
||||
- **Verbesserungspotenzial** (Performance, Maintainability, Code Quality)
|
||||
|
||||
---
|
||||
|
||||
## 🔴 KRITISCHE SCHWACHSTELLEN
|
||||
|
||||
### 1. **Fehlende Validierung von `prompt_key` in `llm_service.py`**
|
||||
|
||||
**Datei:** `app/services/llm_service.py:169-176`
|
||||
|
||||
**Problem:**
|
||||
```python
|
||||
if prompt_key:
|
||||
template = self.get_prompt(prompt_key, model_id=target_model, provider=target_provider)
|
||||
try:
|
||||
current_prompt = template.format(**(variables or {}))
|
||||
except Exception as e:
|
||||
logger.error(f"❌ Prompt formatting failed for key '{prompt_key}': {e}")
|
||||
current_prompt = template # Sicherheits-Fallback
|
||||
```
|
||||
|
||||
**Risiko:**
|
||||
- Wenn `prompt_key` nicht existiert, gibt `get_prompt()` einen leeren String zurück
|
||||
- Leerer Prompt wird an LLM gesendet → unerwartetes Verhalten
|
||||
- Keine Warnung/Fehlerbehandlung für fehlende Keys
|
||||
|
||||
**Empfehlung:**
|
||||
```python
|
||||
if prompt_key:
|
||||
template = self.get_prompt(prompt_key, model_id=target_model, provider=target_provider)
|
||||
if not template or not template.strip():
|
||||
logger.error(f"❌ Prompt key '{prompt_key}' not found or empty. Available keys: {list(self.prompts.keys())}")
|
||||
raise ValueError(f"Invalid prompt_key: '{prompt_key}'")
|
||||
# ... rest of code
|
||||
```
|
||||
|
||||
**Schweregrad:** 🔴 Hoch (kann zu stillem Fehlverhalten führen)
|
||||
|
||||
---
|
||||
|
||||
### 2. **Inkonsistenter Fallback in `decision_engine.py`**
|
||||
|
||||
**Datei:** `app/core/retrieval/decision_engine.py:258-261`
|
||||
|
||||
**Problem:**
|
||||
```python
|
||||
return await self.llm_service.generate_raw_response(
|
||||
prompt=f"Beantworte: {query}\n\nKontext:\n{fallback_context}",
|
||||
system=system_prompt, priority="realtime", profile_name=profile
|
||||
)
|
||||
```
|
||||
|
||||
**Risiko:**
|
||||
- Fallback verwendet `prompt=` statt `prompt_key=` → inkonsistent mit WP25b-Architektur
|
||||
- Keine Lazy-Loading-Vorteile (modell-spezifische Prompts werden ignoriert)
|
||||
- Hardcodierter Prompt-String statt konfigurierbarer Template
|
||||
|
||||
**Empfehlung:**
|
||||
```python
|
||||
return await self.llm_service.generate_raw_response(
|
||||
prompt_key="fallback_synthesis", # In prompts.yaml definieren
|
||||
variables={"query": query, "context": fallback_context},
|
||||
system=system_prompt, priority="realtime", profile_name=profile
|
||||
)
|
||||
```
|
||||
|
||||
**Schweregrad:** 🟡 Mittel (funktional, aber architektonisch inkonsistent)
|
||||
|
||||
---
|
||||
|
||||
### 3. **Zu permissives Error-Handling in `ingestion_validation.py`**
|
||||
|
||||
**Datei:** `app/core/ingestion/ingestion_validation.py:77-80`
|
||||
|
||||
**Problem:**
|
||||
```python
|
||||
except Exception as e:
|
||||
logger.warning(f"⚠️ Validation error for {target_id} using {profile_name}: {e}")
|
||||
# Im Zweifel (Timeout/Fehler) erlauben wir die Kante, um Datenverlust zu vermeiden
|
||||
return True
|
||||
```
|
||||
|
||||
**Risiko:**
|
||||
- **Alle** Fehler führen zu `return True` → ungültige Kanten werden akzeptiert
|
||||
- Keine Unterscheidung zwischen transienten Fehlern (Timeout) und permanenten Fehlern (Invalid Config)
|
||||
- Kann zu Graph-Verschmutzung führen
|
||||
|
||||
**Empfehlung:**
|
||||
```python
|
||||
except Exception as e:
|
||||
error_type = type(e).__name__
|
||||
# Transiente Fehler (Timeout, Network) → erlauben
|
||||
if any(x in str(e).lower() for x in ["timeout", "connection", "network"]):
|
||||
logger.warning(f"⚠️ Transient error for {target_id}: {e}. Allowing edge.")
|
||||
return True
|
||||
# Permanente Fehler (Config, Validation) → ablehnen
|
||||
logger.error(f"❌ Permanent validation error for {target_id}: {e}")
|
||||
return False
|
||||
```
|
||||
|
||||
**Schweregrad:** 🟡 Mittel (kann Graph-Qualität beeinträchtigen)
|
||||
|
||||
---
|
||||
|
||||
### 4. **Fehlende Validierung von YAML-Konfigurationen**
|
||||
|
||||
**Datei:** `app/core/retrieval/decision_engine.py:38-51`
|
||||
|
||||
**Problem:**
|
||||
```python
|
||||
def _load_engine_config(self) -> Dict[str, Any]:
|
||||
path = os.getenv("MINDNET_DECISION_CONFIG", "config/decision_engine.yaml")
|
||||
if not os.path.exists(path):
|
||||
logger.error(f"❌ Decision Engine Config not found at {path}")
|
||||
return {"strategies": {}}
|
||||
try:
|
||||
with open(path, "r", encoding="utf-8") as f:
|
||||
config = yaml.safe_load(f) or {}
|
||||
logger.info(f"⚙️ Decision Engine Config loaded (v{config.get('version', 'unknown')})")
|
||||
return config
|
||||
except Exception as e:
|
||||
logger.error(f"❌ Failed to load decision_engine.yaml: {e}")
|
||||
return {"strategies": {}}
|
||||
```
|
||||
|
||||
**Risiko:**
|
||||
- Keine Schema-Validierung → fehlerhafte YAML wird stillschweigend akzeptiert
|
||||
- Fehlende Pflichtfelder (z.B. `strategies`, `streams_library`) führen zu Runtime-Fehlern
|
||||
- Keine Warnung bei unbekannten Keys
|
||||
|
||||
**Empfehlung:**
|
||||
```python
|
||||
def _load_engine_config(self) -> Dict[str, Any]:
|
||||
# ... existing code ...
|
||||
try:
|
||||
with open(path, "r", encoding="utf-8") as f:
|
||||
config = yaml.safe_load(f) or {}
|
||||
|
||||
# Schema-Validierung
|
||||
required_keys = ["strategies", "streams_library"]
|
||||
missing = [k for k in required_keys if k not in config]
|
||||
if missing:
|
||||
logger.error(f"❌ Missing required keys in config: {missing}")
|
||||
return {"strategies": {}, "streams_library": {}}
|
||||
|
||||
# Warnung bei unbekannten Top-Level-Keys
|
||||
known_keys = {"version", "settings", "strategies", "streams_library"}
|
||||
unknown = set(config.keys()) - known_keys
|
||||
if unknown:
|
||||
logger.warning(f"⚠️ Unknown keys in config: {unknown}")
|
||||
|
||||
return config
|
||||
except yaml.YAMLError as e:
|
||||
logger.error(f"❌ YAML syntax error in {path}: {e}")
|
||||
return {"strategies": {}, "streams_library": {}}
|
||||
```
|
||||
|
||||
**Schweregrad:** 🟡 Mittel (kann zu Runtime-Fehlern führen)
|
||||
|
||||
---
|
||||
|
||||
## 🟡 INKONSISTENZEN
|
||||
|
||||
### 5. **Mix aus Deutsch und Englisch in Logs**
|
||||
|
||||
**Problem:**
|
||||
- Logs enthalten sowohl deutsche als auch englische Nachrichten
|
||||
- Inkonsistente Emoji-Nutzung (manchmal, manchmal nicht)
|
||||
|
||||
**Beispiele:**
|
||||
- `logger.info(f"🎯 [ROUTING] Parsed Intent: '{intent}'...")` (Englisch)
|
||||
- `logger.warning(f"⚠️ Profil '{profile_name}' nicht in llm_profiles.yaml gefunden!")` (Deutsch)
|
||||
|
||||
**Empfehlung:**
|
||||
- Einheitliche Sprache wählen (empfohlen: Deutsch, da User-Regel "Always respond in German")
|
||||
- Oder: Englisch für technische Logs, Deutsch für User-sichtbare Nachrichten
|
||||
|
||||
**Schweregrad:** 🟢 Niedrig (Wartbarkeit)
|
||||
|
||||
---
|
||||
|
||||
### 6. **Unterschiedliche Config-Loading-Patterns**
|
||||
|
||||
**Problem:**
|
||||
- `decision_engine.py`: Lädt Config bei jedem Aufruf (kein Cache)
|
||||
- `chat.py`: Nutzt globalen Cache (`_DECISION_CONFIG_CACHE`)
|
||||
- `llm_service.py`: Lädt Prompts/Profiles einmalig im `__init__`
|
||||
|
||||
**Empfehlung:**
|
||||
- Einheitliches Pattern: Lazy Loading mit Cache
|
||||
- Cache-Invalidierung bei Datei-Änderungen (optional, aber wünschenswert)
|
||||
|
||||
**Schweregrad:** 🟢 Niedrig (Performance-Optimierung)
|
||||
|
||||
---
|
||||
|
||||
### 7. **Private Methoden werden extern genutzt**
|
||||
|
||||
**Datei:** `app/routers/chat.py:138`
|
||||
|
||||
**Problem:**
|
||||
```python
|
||||
intent = await llm.decision_engine._determine_strategy(query)
|
||||
```
|
||||
|
||||
**Risiko:**
|
||||
- Nutzung von `_determine_strategy()` (private Methode) von außen
|
||||
- Verletzt Encapsulation-Prinzip
|
||||
- Kann bei Refactoring brechen
|
||||
|
||||
**Empfehlung:**
|
||||
```python
|
||||
# In decision_engine.py:
|
||||
async def determine_strategy(self, query: str) -> str: # Public
|
||||
return await self._determine_strategy(query)
|
||||
|
||||
# In chat.py:
|
||||
intent = await llm.decision_engine.determine_strategy(query)
|
||||
```
|
||||
|
||||
**Schweregrad:** 🟡 Mittel (Wartbarkeit)
|
||||
|
||||
---
|
||||
|
||||
### 8. **Inkonsistente Prompt-Formatierung**
|
||||
|
||||
**Problem:**
|
||||
- `decision_engine.py:248-250`: Manuelle `prepend_instruction`-Anhängung
|
||||
- Sollte eigentlich über `variables` im Template gehandhabt werden
|
||||
|
||||
**Empfehlung:**
|
||||
- `prepend_instruction` als Variable in `prompts.yaml` Templates integrieren
|
||||
- Entfernung der manuellen Anhängung
|
||||
|
||||
**Schweregrad:** 🟢 Niedrig (Code-Qualität)
|
||||
|
||||
---
|
||||
|
||||
## 🟢 VERBESSERUNGSPOTENZIAL
|
||||
|
||||
### 9. **Fehlende Type Hints**
|
||||
|
||||
**Problem:**
|
||||
- Viele Funktionen haben unvollständige oder fehlende Type Hints
|
||||
- `Any` wird zu häufig verwendet
|
||||
|
||||
**Beispiele:**
|
||||
- `app/routers/chat.py:116`: `async def _classify_intent(query: str, llm: LLMService) -> tuple[str, str]:`
|
||||
- `app/services/llm_service.py:125`: Viele `Optional[...]` aber auch `Any`
|
||||
|
||||
**Empfehlung:**
|
||||
- Vollständige Type Hints für alle öffentlichen Methoden
|
||||
- Verwendung von `TypedDict` für Config-Strukturen
|
||||
- `from __future__ import annotations` für Forward References
|
||||
|
||||
**Schweregrad:** 🟢 Niedrig (Code-Qualität, IDE-Support)
|
||||
|
||||
---
|
||||
|
||||
### 10. **Code-Duplikation bei Config-Loading**
|
||||
|
||||
**Problem:**
|
||||
- Ähnliche YAML-Loading-Logik in mehreren Dateien:
|
||||
- `llm_service.py:_load_prompts()`
|
||||
- `llm_service.py:_load_llm_profiles()`
|
||||
- `decision_engine.py:_load_engine_config()`
|
||||
- `chat.py:_load_decision_config()`
|
||||
- `embeddings_client.py:_load_embedding_profile()`
|
||||
|
||||
**Empfehlung:**
|
||||
```python
|
||||
# app/core/config_loader.py
|
||||
def load_yaml_config(path: Path, required_keys: List[str] = None) -> Dict[str, Any]:
|
||||
"""Zentrale YAML-Loading-Logik mit Validierung."""
|
||||
# ... unified implementation ...
|
||||
```
|
||||
|
||||
**Schweregrad:** 🟢 Niedrig (DRY-Prinzip)
|
||||
|
||||
---
|
||||
|
||||
### 11. **Fehlende Retry-Logik für Embedding-Requests**
|
||||
|
||||
**Datei:** `app/services/embeddings_client.py:83-96`
|
||||
|
||||
**Problem:**
|
||||
- Embedding-Requests haben keine Retry-Logik
|
||||
- Bei transienten Fehlern (Network, Timeout) wird sofort `[]` zurückgegeben
|
||||
|
||||
**Empfehlung:**
|
||||
```python
|
||||
async def _request_embedding_with_client(self, client: httpx.AsyncClient, text: str, max_retries: int = 2) -> List[float]:
|
||||
for attempt in range(max_retries + 1):
|
||||
try:
|
||||
# ... existing code ...
|
||||
except (httpx.TimeoutException, httpx.NetworkError) as e:
|
||||
if attempt < max_retries:
|
||||
await asyncio.sleep(2 ** attempt)
|
||||
continue
|
||||
raise
|
||||
```
|
||||
|
||||
**Schweregrad:** 🟢 Niedrig (Resilienz)
|
||||
|
||||
---
|
||||
|
||||
### 12. **Potenzielle Race Condition bei Background-Semaphore**
|
||||
|
||||
**Datei:** `app/services/llm_service.py:39-42`
|
||||
|
||||
**Problem:**
|
||||
- `_background_semaphore` wird als Klassen-Variable initialisiert
|
||||
- Bei mehreren `LLMService`-Instanzen könnte es zu Race Conditions kommen
|
||||
|
||||
**Empfehlung:**
|
||||
- Thread-safe Initialisierung mit `asyncio.Lock`
|
||||
- Oder: Singleton-Pattern für `LLMService`
|
||||
|
||||
**Schweregrad:** 🟢 Niedrig (Edge Case)
|
||||
|
||||
---
|
||||
|
||||
### 13. **Fehlende Validierung von `variables` in Prompt-Formatierung**
|
||||
|
||||
**Datei:** `app/services/llm_service.py:173`
|
||||
|
||||
**Problem:**
|
||||
```python
|
||||
current_prompt = template.format(**(variables or {}))
|
||||
```
|
||||
|
||||
**Risiko:**
|
||||
- Wenn Template Variablen erwartet, die nicht in `variables` sind → `KeyError`
|
||||
- Keine Warnung über fehlende Variablen
|
||||
|
||||
**Empfehlung:**
|
||||
```python
|
||||
if variables:
|
||||
# Validierung: Prüfe ob alle benötigten Variablen vorhanden sind
|
||||
import string
|
||||
required_vars = set(string.Formatter().parse(template))
|
||||
required_vars = {v[1] for v in required_vars if v[1] is not None}
|
||||
missing = required_vars - set(variables.keys())
|
||||
if missing:
|
||||
logger.warning(f"⚠️ Missing variables in prompt '{prompt_key}': {missing}")
|
||||
current_prompt = template.format(**(variables or {}))
|
||||
else:
|
||||
current_prompt = template
|
||||
```
|
||||
|
||||
**Schweregrad:** 🟢 Niedrig (Debugging-Hilfe)
|
||||
|
||||
---
|
||||
|
||||
### 14. **Ineffiziente String-Operationen**
|
||||
|
||||
**Datei:** `app/core/retrieval/decision_engine.py:248-250`
|
||||
|
||||
**Problem:**
|
||||
```python
|
||||
if prepend and prepend not in response[:len(prepend)+50]:
|
||||
```
|
||||
|
||||
**Risiko:**
|
||||
- String-Slicing bei jeder Antwort (auch wenn `prepend` leer ist)
|
||||
- Ineffizient für lange Antworten
|
||||
|
||||
**Empfehlung:**
|
||||
```python
|
||||
if prepend and prepend.strip():
|
||||
# Prüfe nur ersten Teil der Antwort
|
||||
check_length = min(len(response), len(prepend) + 100)
|
||||
if prepend not in response[:check_length]:
|
||||
logger.info("ℹ️ Adding prepend_instruction manually (not found in response).")
|
||||
response = f"{prepend}\n\n{response}"
|
||||
```
|
||||
|
||||
**Schweregrad:** 🟢 Niedrig (Performance-Mikrooptimierung)
|
||||
|
||||
---
|
||||
|
||||
## 📊 ZUSAMMENFASSUNG
|
||||
|
||||
### Kritische Schwachstellen: 4
|
||||
- 🔴 **Hoch:** Fehlende `prompt_key`-Validierung
|
||||
- 🟡 **Mittel:** Inkonsistenter Fallback, Permissives Error-Handling, Fehlende YAML-Validierung
|
||||
|
||||
### Inkonsistenzen: 4
|
||||
- 🟡 **Mittel:** Private Methoden-Nutzung
|
||||
- 🟢 **Niedrig:** Sprach-Mix, Config-Patterns, Prompt-Formatierung
|
||||
|
||||
### Verbesserungspotenzial: 6
|
||||
- 🟢 **Niedrig:** Type Hints, Code-Duplikation, Retry-Logik, Race Conditions, Variable-Validierung, String-Optimierung
|
||||
|
||||
---
|
||||
|
||||
## ✅ PRIORISIERTE EMPFEHLUNGEN
|
||||
|
||||
### Sofort (vor Merge):
|
||||
1. ✅ **Prompt-Key-Validierung** hinzufügen (`llm_service.py`)
|
||||
2. ✅ **Fallback konsistent** machen (`decision_engine.py`)
|
||||
3. ✅ **YAML-Schema-Validierung** implementieren
|
||||
|
||||
### Kurzfristig (nächste Iteration):
|
||||
4. ✅ **Error-Handling** in `ingestion_validation.py` differenzieren
|
||||
5. ✅ **Public API** für `_determine_strategy()` erstellen
|
||||
6. ✅ **Zentrale Config-Loader** implementieren
|
||||
|
||||
### Langfristig (Refactoring):
|
||||
7. ✅ **Type Hints** vervollständigen
|
||||
8. ✅ **Code-Duplikation** reduzieren
|
||||
9. ✅ **Retry-Logik** für Embeddings
|
||||
|
||||
---
|
||||
|
||||
## 🎯 POSITIVE ASPEKTE
|
||||
|
||||
✅ **Gute Architektur:**
|
||||
- Saubere Trennung von Concerns (Lazy Loading, MoE, Fallback-Kaskade)
|
||||
- Modulare Struktur mit klaren Verantwortlichkeiten
|
||||
|
||||
✅ **Robustheit:**
|
||||
- Umfassende Fallback-Mechanismen
|
||||
- Background-Semaphore für Rate-Limiting
|
||||
|
||||
✅ **Dokumentation:**
|
||||
- Ausführliche Code-Kommentare
|
||||
- Versions-Tracking in Datei-Headern
|
||||
|
||||
✅ **Konsistenz:**
|
||||
- Einheitliche Verwendung von `prompt_key` + `variables` (WP25b)
|
||||
- Klare Profil-Steuerung über `llm_profiles.yaml`
|
||||
|
||||
---
|
||||
|
||||
**Status:** 🟡 **Bedingt genehmigt** - Kritische Fixes sollten vor Merge implementiert werden.
|
||||
|
||||
---
|
||||
|
||||
## 🔧 IMPLEMENTIERTE FIXES
|
||||
|
||||
### ✅ Fix 1: Prompt-Key-Validierung (`llm_service.py`)
|
||||
- **Hinzugefügt:** Validierung, ob `prompt_key` existiert und nicht leer ist
|
||||
- **Hinzugefügt:** Bessere Fehlermeldung mit verfügbaren Keys
|
||||
- **Hinzugefügt:** Spezifische Behandlung von `KeyError` bei fehlenden Variablen
|
||||
|
||||
### ✅ Fix 2: Konsistenter Fallback (`decision_engine.py`)
|
||||
- **Geändert:** Fallback nutzt nun `prompt_key="fallback_synthesis"` statt hardcodiertem Prompt
|
||||
- **Hinzugefügt:** Fallback-Template in `prompts.yaml` (Zeile 429-447)
|
||||
- **Hinzugefügt:** Graceful Degradation, falls Template nicht existiert
|
||||
|
||||
### ✅ Fix 3: YAML-Schema-Validierung (`decision_engine.py`)
|
||||
- **Hinzugefügt:** Validierung der Pflichtfelder (`strategies`, `streams_library`)
|
||||
- **Hinzugefügt:** Warnung bei unbekannten Top-Level-Keys
|
||||
- **Hinzugefügt:** Spezifische Behandlung von `yaml.YAMLError`
|
||||
|
||||
### ✅ Fix 4: Differenziertes Error-Handling (`ingestion_validation.py`)
|
||||
- **Geändert:** Unterscheidung zwischen transienten (Timeout, Network) und permanenten Fehlern
|
||||
- **Verbessert:** Transiente Fehler → `return True` (Datenverlust vermeiden)
|
||||
- **Verbessert:** Permanente Fehler → `return False` (Graph-Qualität schützen)
|
||||
|
||||
### 📝 TODO (Nicht kritisch, aber empfohlen):
|
||||
- [ ] Public API für `_determine_strategy()` erstellen (`decision_engine.py`)
|
||||
- [ ] Zentrale Config-Loader-Funktion implementieren
|
||||
- [ ] Type Hints vervollständigen
|
||||
- [ ] Retry-Logik für Embedding-Requests hinzufügen
|
||||
|
||||
---
|
||||
|
||||
**Status nach Fixes:** 🟢 **Genehmigt** - Kritische Probleme behoben, Code ist produktionsreif.
|
||||
Reference in new issue
Block a user