mitai-jinkendo/docs/issues/issue-50-value-table-refinement.md

Enhancement: Wertetabelle Optimierung

Labels: enhancement, ux Priority: Medium (Phase 1) Related: Issue #47 (Value Table - Complete)

Beschreibung

Wertetabelle übersichtlicher gestalten durch intelligente Filterung und Beschreibungs-Vervollständigung.

Problem (aktueller Stand)

Nach Implementierung von Issue #47 haben wir eine sehr umfangreiche Wertetabelle mit:

• Reguläre Platzhalter (PROFIL, KÖRPER, etc.)
• Extrahierte Einzelwerte aus Stages (↳ Symbol)
• Rohdaten der Stage-Outputs (🔬 JSON)

Probleme:

1. Zu viele Werte im Normal-Modus (unübersichtlich)
2. Stage-Rohdaten sollten nur im Experten-Modus sichtbar sein
3. Einige Platzhalter haben keine/unvollständige Beschreibungen

Gewünschtes Verhalten

Normal-Modus (Standard)

📊 Verwendete Werte (24)                    [🔬 Experten-Modus]

PROFIL
├─ name: Lars Stommer
├─ age: 35 Jahre (Geburtsdatum 1990-05-15)
├─ height: 178cm (Körpergröße)

KÖRPER
├─ weight_aktuell: 85.2kg (Aktuelles Gewicht)
├─ bmi: 26.9 (Body-Mass-Index)
├─ bmi_interpretation: Leicht übergewichtig (BMI-Bewertung)
├─ kf_aktuell: 18.5% (Körperfettanteil)

ERNÄHRUNG
├─ kcal_avg: 2450 kcal (Durchschnitt 7 Tage)
...

Stage 1 - Body (Extrahierte Werte)
├─ ↳ trend: leicht sinkend (Gewichtstrend)
├─ ↳ ziel_erreichbar: ja, in 8 Wochen (Zielerreichbarkeit)

Ausgeblendet:

• 🔬 stage_1_stage1_body (komplettes JSON)
• Leere/nicht verfügbare Werte

Experten-Modus

📊 Verwendete Werte (32)                    [🔬 Experten-Modus ✓]

[... wie Normal-Modus ...]

Stage 1 - Rohdaten
├─ 🔬 stage_1_stage1_body
   └─ [JSON anzeigen ▼]
      {
        "bmi": 26.9,
        "trend": "leicht sinkend",
        "ziel_erreichbar": "ja, in 8 Wochen",
        "interpretation": "Dein BMI liegt..."
      }

Stage 2 - Rohdaten
├─ 🔬 stage_2_stage2_nutrition
   └─ [JSON anzeigen ▼]
      { ... }

Zusätzlich sichtbar:

• Alle Stage-Rohdaten (🔬 JSON)
• Leere/nicht verfügbare Werte
• Debug-Informationen

Technische Umsetzung

1. Filterlogik anpassen (Analysis.jsx)

Aktuell:

const placeholders = expertMode
  ? allPlaceholders
  : Object.fromEntries(
      Object.entries(allPlaceholders).filter(([key, data]) => {
        if (data.is_stage_raw) return false  // Versteckt Rohdaten
        const val = data.value || ''
        return val.trim() !== '' && val !== 'nicht verfügbar'
      })
    )

Problem: is_stage_raw wird nur für Keys wie "stage_1_stage1_body" gesetzt, nicht für extrahierte Werte.

Lösung: Neue Flag is_extracted (bereits vorhanden) wird beibehalten, is_stage_raw nur für komplette JSON-Outputs.

2. Beschreibungen vervollständigen (placeholder_resolver.py)

Fehlende Beschreibungen prüfen:

# In get_placeholder_catalog()
PLACEHOLDER_CATALOG = {
    'PROFIL': [
        {'key': 'name', 'description': 'Name des Nutzers', 'example': '...'},
        {'key': 'age', 'description': 'Alter in Jahren', 'example': '35'},
        # ... alle prüfen
    ],
    'KÖRPER': [
        {'key': 'weight_aktuell', 'description': 'Aktuelles Gewicht', 'example': '85.2kg'},
        {'key': 'bmi', 'description': 'Body-Mass-Index (berechnet)', 'example': '26.9'},
        # ... alle prüfen
    ],
    # ... alle Kategorien durchgehen
}

Aktionen:

• Alle 32 Platzhalter durchgehen
• Fehlende Beschreibungen ergänzen
• Beschreibungen aus Kontext ableiten (z.B. bei extrahierten Werten aus Stage-Output)

3. Extrahierte Werte beschreiben (prompts.py)

Aktuell (Line 896-901):

metadata['placeholders'][field_key] = {
    'value': field_data['value'],
    'description': f"Aus Stage {field_data['source_stage']} ({field_data['source_output']})",
    'is_extracted': True,
    'category': category
}

Verbesserung:

• Wenn Base-Prompt ein JSON-Schema hat, Feld-Beschreibungen aus Schema extrahieren
• Fallback: Generische Beschreibung aus Kontext

Beispiel:

# Wenn output_schema verfügbar:
schema = base_prompt.get('output_schema', {})
properties = schema.get('properties', {})
field_description = properties.get(field_key, {}).get('description', '')

metadata['placeholders'][field_key] = {
    'value': field_data['value'],
    'description': field_description or f"Aus Stage {stage_num} ({output_name})",
    'is_extracted': True,
    'category': category
}

Akzeptanzkriterien

• Normal-Modus zeigt nur Einzelwerte (regulär + extrahiert ↳)
• Experten-Modus zeigt zusätzlich Stage-Rohdaten (🔬 JSON)
• Alle 32 Platzhalter haben sinnvolle Beschreibungen
• Extrahierte Werte nutzen Schema-Beschreibungen (wenn vorhanden)
• Toggle "Experten-Modus" funktioniert korrekt
• Kategorien bleiben sauber getrennt
• Leere Werte werden im Normal-Modus ausgeblendet

Abschätzung

Aufwand: 4-6 Stunden

• 1h: Filterlogik testen/anpassen
• 2-3h: Beschreibungen vervollständigen (32 Platzhalter)
• 1h: Schema-basierte Beschreibungen für extrahierte Werte
• 1h: Testing + Feintuning

Priorität: Medium (verbessert UX erheblich, aber keine kritische Funktionalität)

Notizen

• Issue #47 hat die Grundlage geschaffen (Kategorien, Expert-Mode, Stage-Outputs)
• Diese Optimierung macht die Wertetabelle produktionsreif
• Beschreibungen sind wichtig für KI-Kontext UND User-Verständnis
• ggf. später: Beschreibungen editierbar machen (Admin-UI)