feat(metabase): smartscalar KPI builders (sql + payload + dimension tag)

3 helpers puros para construir KPIs con display=smartscalar y comparacion
vs n-1 sin que Metabase v0.59 pida breakout temporal. Replican el patron
del dashboard Informe Lean (UNION ALL de 2 filas periodo/valor) y rellenan
la firma exacta de template-tags que el frontend MBQL5 acepta.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

python/functions/metabase/metabase_smartscalar_kpi_payload.md

@@ -0,0 +1,96 @@
+---
+name: metabase_smartscalar_kpi_payload
+kind: function
+lang: py
+domain: infra
+version: "1.0.0"
+purity: pure
+signature: "def metabase_smartscalar_kpi_payload(*, name: str, database_id: int, sql: str, template_tags: dict | None = None, description: str = '', collection_id: int = 0, currency: bool = False, currency_code: str = 'EUR', decimals: int = 0, comparison_label: str = 'vs n-1', extra_visualization_settings: dict | None = None) -> dict"
+description: "Construye el payload completo para POST /api/card de un KPI smartscalar con formato y comparacion previousValue. Combina SQL nativo (idealmente generado por metabase_smartscalar_kpi_sql) con template-tags y visualization_settings predefinidos. Listo para metabase_create_card_raw."
+tags: [metabase, smartscalar, kpi, card, payload, pure, builder]
+uses_functions: []
+uses_types: []
+returns: []
+returns_optional: false
+error_type: ""
+imports: []
+params:
+  - name: name
+    desc: "Nombre de la card mostrado en el dashboard"
+  - name: database_id
+    desc: "ID de la database de Metabase contra la que se ejecuta el SQL"
+  - name: sql
+    desc: "Query nativa que devuelve columnas periodo (DATE) y valor (numero) con 2 filas (n-1, actual). Generable con metabase_smartscalar_kpi_sql"
+  - name: template_tags
+    desc: "Dict {tag_name: tag_dict} para field-filters; None para card sin filtros. Construir con metabase_smartscalar_dimension_tag"
+  - name: description
+    desc: "Descripcion mostrada en la card; vacio = autorrellenada"
+  - name: collection_id
+    desc: "ID de la coleccion destino; 0 = Our analytics (root)"
+  - name: currency
+    desc: "Si True formatea valor como moneda con simbolo currency_code"
+  - name: currency_code
+    desc: "Codigo ISO de moneda. Default EUR. Solo aplica si currency=True"
+  - name: decimals
+    desc: "Decimales mostrados en valor"
+  - name: comparison_label
+    desc: "Etiqueta del bloque de comparacion bajo el numero principal. Default 'vs n-1'"
+  - name: extra_visualization_settings
+    desc: "Settings adicionales fusionados (top-level override) en visualization_settings; util para anadir scalar.title, card.title.alignment, etc."
+output: "dict con payload completo (name, description, type=question, display=smartscalar, dataset_query nativo, visualization_settings con scalar.field/scalar.comparisons/column_settings, [collection_id]) directamente posteable a /api/card"
+tested: false
+tests: []
+test_file_path: ""
+file_path: "python/functions/metabase/smartscalar.py"
+---
+
+## Por que existe
+
+Encapsular la combinacion exacta de campos que Metabase v0.59 necesita para
+un KPI ``smartscalar`` con comparacion ``previousValue``: ``scalar.field``,
+``scalar.comparisons`` con ``id``, ``type`` y ``label``, y ``column_settings``
+con la clave de columna serializada como JSON ``'["name","valor"]'``.
+
+Cualquier desviacion (clave de column_settings sin escapar, ausencia de
+``scalar.field``, ``type`` distinto de ``previousValue/anotherColumn/staticNumber``)
+hace que el frontend muestre el numero pero descarta silenciosamente la
+comparacion o pide breakout.
+
+## Ejemplo
+
+```python
+sql = metabase_smartscalar_kpi_sql(
+    act_expr="ROUND(SUM(v.venta_n), 2)",
+    n1_expr="ROUND(SUM(v.venta_n1), 2)",
+    body_sql=ventas_cte_sql,
+    date_expr="MIN(v.fecha)",
+)
+tags = {
+    "fecha": metabase_smartscalar_dimension_tag(
+        name="fecha", field_id=322392,
+        base_type="type/Date", widget_type="date/all-options",
+    ),
+}
+payload = metabase_smartscalar_kpi_payload(
+    name="Venta total",
+    database_id=6,
+    sql=sql,
+    template_tags=tags,
+    currency=True, decimals=0,
+    description="Venta del periodo seleccionado vs ano anterior.",
+    collection_id=583,
+)
+card = metabase_create_card_raw(client, payload)
+print(card["id"])
+```
+
+## Notas
+
+- ``visualization_settings.column_settings`` usa la clave con formato JSON
+  exacto ``'["name","valor"]'`` (sin espacios entre comillas y coma) — Metabase
+  no normaliza variaciones.
+- Si necesitas la card como ``model`` o ``metric`` en lugar de ``question``,
+  override via ``extra_visualization_settings`` no aplica — clona el resultado
+  y modifica ``payload["type"]`` antes de enviar.
+- Para reemplazar una card existente usa ``metabase_update_card`` con los
+  mismos campos del payload (display, dataset_query, visualization_settings).