feat: Enhance activity metrics documentation and registry updates
- Added details for Issue #53 regarding the audit of activity placeholders between Layer 1 and Layer 2a in `CLAUDE.md` and `README.md`. - Updated the `ACTIVITY_SESSION_METRICS_EAV_AGENT_GUIDE.md` to reflect the new registry checks and dynamic session metrics handling. - Revised the `placeholder_resolver.py` and `activity_metrics.py` to clarify the registration of activity metrics and session insights, ensuring consistency in the handling of dynamic keys and metrics. - Improved descriptions and semantic contracts in `activity_session_insights.py` to better outline the structure and limitations of session data.
This commit is contained in:
1 parent
680ecd1c06
commit
c3be745efa
7 files changed
+130
-47
No files matched your search
@@ -1,7 +1,7 @@
|
||||
"""
|
||||
Activity Metrics Placeholder Registrations
|
||||
|
||||
Registers 17 Aktivitäts-Platzhalter hier; 3 Session-/Erholungs-Keys in activity_session_insights.py (20 gesamt).
|
||||
Registers 17 Aktivitäts-Platzhalter hier; 3 weitere Keys in activity_session_insights.py (**20 gesamt** in PLACEHOLDER_MAP).
|
||||
|
||||
Evidence-based metadata with clear tagging of source.
|
||||
|
||||
@@ -43,7 +43,7 @@ def register_activity_group_1():
|
||||
category="Aktivität",
|
||||
description="Zusammenfassung der letzten 14 Tage Aktivität",
|
||||
resolver_module="backend/placeholder_resolver.py",
|
||||
resolver_function="_format_activity_summary",
|
||||
resolver_function="get_activity_summary",
|
||||
data_layer_module=None,
|
||||
data_layer_function=None,
|
||||
source_tables=["activity_log", "training_types"],
|
||||
@@ -127,17 +127,23 @@ def register_activity_group_1():
|
||||
activity_detail_metadata = PlaceholderMetadata(
|
||||
key="activity_detail",
|
||||
category="Aktivität",
|
||||
description="Detaillierte Liste der letzten 14 Tage Aktivität (Kopfzeile + EAV-Metriken)",
|
||||
description=(
|
||||
"Letzte 14 Tage: pro Session Kopfzeile (activity_log) plus gemergte Profil-Metriken "
|
||||
"(dynamische Keys je training_category / training_type_id)"
|
||||
),
|
||||
resolver_module="backend/placeholder_resolver.py",
|
||||
resolver_function="get_activity_detail",
|
||||
data_layer_module="backend/data_layer/activity_metrics.py",
|
||||
data_layer_function="get_activity_detail_data",
|
||||
source_tables=["activity_log", "activity_session_metrics", "training_parameters"],
|
||||
semantic_contract=(
|
||||
"Liefert bis zu 50 Einheiten (neueste zuerst) der letzten 14 Tage über "
|
||||
"get_activity_detail_data: activity_log-Spalten plus "
|
||||
"enrich_sessions_with_metrics (activity_session_metrics / Profil-EAV). "
|
||||
"Formatter hängt nicht-leere EAV-Werte als „| EAV: key=value; …“ an."
|
||||
"Layer 1: get_activity_detail_data lädt Sessions, enrich_sessions_with_metrics fügt "
|
||||
"session_metrics hinzu — effektive Liste aus merge_column_backed_and_eav_metrics: nur "
|
||||
"Parameter aus dem Attributschema (tcp/ttp), sortiert nach key. "
|
||||
"Leseregel Kanon: activity_log-Spalte (source_field, Registry-Feld, Legacy-Spalte für "
|
||||
"EAV-primäre Keys) schlägt EAV, wenn beide Werte liefern. "
|
||||
"Layer 2a: Zeilen mit „| EAV: key=value; …“ nur für nicht-leere session_metrics; "
|
||||
"die Menge der Keys ist admin-/profilabhängig, kein festes Prompt-Schema."
|
||||
),
|
||||
business_meaning=(
|
||||
"Detaillierte Trainingshistorie für KI-Prompts, die Muster, Progressionen "
|
||||
@@ -167,8 +173,10 @@ def register_activity_group_1():
|
||||
),
|
||||
known_limitations=(
|
||||
"Keine Profil-Qualitätsfilterung in dieser Liste. Max. 20 Zeilen im Prompt-Output "
|
||||
"(Hard-Limit Resolver). Doppelte Spalten (z.B. duration_min in Kopf und EAV) können "
|
||||
"in EAV wiederholt erscheinen — KI kann dominante Spalte nutzen."
|
||||
"(Hard-Limit Resolver). session_metrics kann leer sein (kein Typ, kein Profil, keine EAV-Zeilen). "
|
||||
"Keys und Anzahl Metriken variieren je Instanz/Admin — nicht von festen Platzhaltern in anderen "
|
||||
"Prompts ausgehen. Nur im effektiven Merge erscheinende Parameter; keine verwaisten EAV-Keys "
|
||||
"außerhalb des Schemas."
|
||||
),
|
||||
layer_1_decision="activity_metrics.get_activity_detail_data (+ enrich_sessions_with_metrics)",
|
||||
layer_2a_decision="get_activity_detail (Formatierung)",
|
||||
@@ -211,56 +219,47 @@ def register_activity_group_1():
|
||||
trainingstyp_verteilung_metadata = PlaceholderMetadata(
|
||||
key="trainingstyp_verteilung",
|
||||
category="Aktivität",
|
||||
description="Trainingstypen-Verteilung der letzten 14 Tage als JSON",
|
||||
description="Verteilung nach training_category (14 Tage): Top 3 als kompakte Prozent-Textzeile",
|
||||
resolver_module="backend/placeholder_resolver.py",
|
||||
resolver_function="_format_trainingstyp_verteilung",
|
||||
data_layer_module=None,
|
||||
data_layer_function=None,
|
||||
source_tables=["activity_log", "training_types"],
|
||||
resolver_function="get_trainingstyp_verteilung",
|
||||
data_layer_module="backend/data_layer/activity_metrics.py",
|
||||
data_layer_function="get_training_type_distribution_data",
|
||||
source_tables=["activity_log"],
|
||||
semantic_contract=(
|
||||
"Liefert eine JSON-Struktur mit der Verteilung der Trainingstypen über 14 Tage. "
|
||||
"Für jeden Trainingstyp: Anzahl Einheiten, Gesamtdauer (Minuten), "
|
||||
"Prozentanteil an Gesamtdauer. Sortiert nach Dauer absteigend."
|
||||
"Layer 1: get_training_type_distribution_data — Anteil je training_category am "
|
||||
"Gesamt-Session-Count im Fenster (auch unkategorisierte zählen im Nenner). "
|
||||
"Layer 2a: Top 3 Kategorien als „Name: p%“ kommagetrennt; bei fehlenden Daten Kurz-Hinweis."
|
||||
),
|
||||
business_meaning=(
|
||||
"Analyse-Placeholder für Trainingsvielfalt und -schwerpunkte. "
|
||||
"Erlaubt KI-Prompts, Imbalancen zu erkennen (z.B. nur Kraft, keine Ausdauer) "
|
||||
"oder Zielkonformität zu prüfen (z.B. 'zu wenig Mobilität')."
|
||||
),
|
||||
unit="json",
|
||||
unit="text",
|
||||
time_window="14d",
|
||||
output_type=OutputType.JSON,
|
||||
output_type=OutputType.TEXT_SUMMARY,
|
||||
placeholder_type=PlaceholderType.INTERPRETED,
|
||||
format_hint="JSON Object mit Trainingstyp als Key, Value: {count, duration_min, percentage}",
|
||||
example_output=(
|
||||
'{"Krafttraining": {"count": 5, "duration_min": 180, "percentage": 57}, '
|
||||
'"Ausdauer": {"count": 4, "duration_min": 90, "percentage": 29}, '
|
||||
'"Mobilität": {"count": 3, "duration_min": 45, "percentage": 14}}'
|
||||
),
|
||||
format_hint="Eine Zeile: bis zu drei „Kategorie: Prozent%“, durch Komma getrennt",
|
||||
example_output="cardio: 45%, strength: 30%, mobility: 15%",
|
||||
minimum_data_requirements=None,
|
||||
quality_filter_policy=None,
|
||||
confidence_logic="Keine Confidence-Berechnung. Aggregation basiert auf verfügbaren Daten.",
|
||||
confidence_logic="Wie get_training_type_distribution_data (calculate_confidence über categorized_count)",
|
||||
missing_value_policy=MissingValuePolicy(
|
||||
available=False,
|
||||
value_raw=None,
|
||||
missing_reason="no_data",
|
||||
legacy_display="{}"
|
||||
legacy_display="Keine kategorisierten Trainings"
|
||||
),
|
||||
known_limitations=(
|
||||
"OLD RESOLVER PATTERN: Keine Data Layer Funktion. "
|
||||
"Aggregation direkt im Resolver. "
|
||||
"CRITICAL: Keine Qualitätsfilterung - auch ungültige Einheiten werden aggregiert. "
|
||||
"JOIN mit training_types für Typ-Namen. "
|
||||
"EDGE CASE: Einheiten ohne training_type_id werden ignoriert (LEFT JOIN)."
|
||||
"Nur Sessions mit gesetztem training_category fließen in die Verteilungsliste; "
|
||||
"Prozente beziehen sich auf alle Sessions im Fenster (Nenner = total_sessions). "
|
||||
"Keine Qualitätsfilterung der Einheiten. Kein drill-down nach training_type_id in diesem Platzhalter."
|
||||
),
|
||||
layer_1_decision="NONE - Old resolver pattern (direct SQL aggregation in resolver)",
|
||||
layer_2a_decision="Placeholder Resolver (aggregation + JSON formatting)",
|
||||
layer_1_decision="activity_metrics.get_training_type_distribution_data",
|
||||
layer_2a_decision="get_trainingstyp_verteilung (Top 3 als Text)",
|
||||
layer_2b_reuse_possible=True,
|
||||
architecture_alignment=(
|
||||
"PARTIALLY ALIGNED: JSON output structure suitable for chart endpoints, "
|
||||
"but no data layer separation. Should be refactored."
|
||||
),
|
||||
issue_53_alignment="PARTIALLY ALIGNED - output format good, layer separation missing"
|
||||
architecture_alignment="Phase 0c — Layer 1 + Formatierung",
|
||||
issue_53_alignment="Layer 1"
|
||||
)
|
||||
|
||||
trainingstyp_verteilung_metadata.set_evidence("key", EvidenceType.CODE_DERIVED)
|
||||
|
||||
@@ -130,8 +130,8 @@ def register_activity_session_insights():
|
||||
key="training_sessions_recent_json",
|
||||
category="Aktivität",
|
||||
description=(
|
||||
"JSON: letzte ISO-Kalenderwochen mit Einheiten (Datum, Art, Dauer, kcal, HF Ø/max, RPE, Kategorie, "
|
||||
"session_id, session_metrics[] aus EAV)"
|
||||
"JSON: ISO-Wochen mit Sessions (activity_log-Kopf) plus session_metrics[] — gemergte Profil-Metriken "
|
||||
"(dynamische Keys)"
|
||||
),
|
||||
resolver_module="backend/placeholder_resolver.py",
|
||||
resolver_function="_safe_json",
|
||||
@@ -139,9 +139,15 @@ def register_activity_session_insights():
|
||||
data_layer_function="get_training_sessions_recent_weeks_data",
|
||||
source_tables=["activity_log", "training_types", "activity_session_metrics", "training_parameters"],
|
||||
semantic_contract=(
|
||||
"Struktur weeks[].week_iso, sessions[] mit Feldern für KI-Auswertung; "
|
||||
"session_metrics[] = Layer-1-EAV-Werte (key, data_type, unit, value) wenn konfiguriert/gespeichert. "
|
||||
"Default 4 ISO-Wochen zurück."
|
||||
"Root: weeks[] mit week_iso; sessions[] pro Einheit u. a. id, date, activity_type, "
|
||||
"duration_min, kcal_active, hr_avg, hr_max, rpe, training_category, training_type_name, "
|
||||
"session_metrics[]. "
|
||||
"session_metrics: effektive Liste nach merge_column_backed_and_eav_metrics — Einträge mit "
|
||||
"training_parameter_id, key, data_type, unit, value; nur Parameter aus Attributschema "
|
||||
"(training_category_parameter + training_type_parameter Overrides), keys sortiert. "
|
||||
"Kanon Lesen: activity_log-Spalte vor EAV bei Konflikt. "
|
||||
"meta: weeks_requested, days_loaded, session_count, confidence. "
|
||||
"Default ca. 4 ISO-Wochen (28 Tage Rohdatenfenster)."
|
||||
),
|
||||
business_meaning="Rohkontext für wochenweise Auswertung (Erholung, Intensität) in der KI",
|
||||
unit="JSON string",
|
||||
@@ -160,8 +166,11 @@ def register_activity_session_insights():
|
||||
legacy_display="{}",
|
||||
),
|
||||
known_limitations=(
|
||||
"Token-Länge bei vielen Sessions beachten. training_type_name nur bei gesetztem training_type_id. "
|
||||
"session_metrics nur befüllt, wenn Admin-Profile zugeordnet und Werte in EAV gespeichert sind."
|
||||
"Token-Länge bei vielen Sessions. training_type_name nur bei gesetztem training_type_id. "
|
||||
"session_metrics oft [] (kein Typ, kein Profil, keine gespeicherten Werte). "
|
||||
"Anzahl und Namen der Metrik-Keys sind instanz-/adminabhängig — JSON nicht als festes Schema "
|
||||
"für Downstream-Parsing harter Logik verwenden. "
|
||||
"Composite-Parameter (JSON in EAV) noch nicht im MVP expandiert; ggf. Roh-value_text in späterer Phase."
|
||||
),
|
||||
layer_1_decision="activity_metrics.get_training_sessions_recent_weeks_data",
|
||||
layer_2a_decision="_safe_json('training_sessions_recent_json')",
|
||||
|
||||
@@ -1524,7 +1524,7 @@ PLACEHOLDER_MAP: Dict[str, Callable[[str], str]] = {
|
||||
'{{intake_volatility}}': lambda pid: _safe_str('intake_volatility', pid),
|
||||
'{{nutrition_score}}': lambda pid: _safe_int('nutrition_score', pid),
|
||||
|
||||
# Training / Aktivität (17 Registry-Keys — gebündelt; activity_score hier, nicht unter Meta Scores)
|
||||
# Training / Aktivität (20 Keys: 17 activity_metrics + 3 activity_session_insights; activity_score hier, nicht unter Meta Scores)
|
||||
'{{activity_summary}}': get_activity_summary,
|
||||
'{{activity_detail}}': get_activity_detail,
|
||||
'{{trainingstyp_verteilung}}': get_trainingstyp_verteilung,
|
||||
|
||||
Reference in new issue
Block a user