Add multi-step conversion funnel support (#119)

* Add multi-step conversion funnel support

Extends type: conversion metrics to support N-step funnels via a steps
list field, generating per-entity BOOL_OR aggregation for each step.
Backwards compatible with existing base_event/conversion_event usage.

* Auto-update JSON schema

* Fix: monotonic funnel counts, entrant-only totals, validate conversion_window

* Fix: enforce chronological funnel order, normalize qualified filters

* Fix: derive step timestamps sequentially from prior-step completion

* Fix: alias timestamp expressions in step CTEs, parenthesize step predicates

* Fix: normalize timestamp expression in step source subqueries

* Fix: normalize step predicates to CTE source alias

* Fix: resolve {model} in filters, add metric-named output column

_strip_model_prefixes now replaces {model} with the actual model name
before sqlglot parsing, so placeholder-based filters no longer leak
literal {model} tokens into WHERE clauses.

Multistep funnel output now includes the last-step count aliased to
the metric name, so ORDER BY metric_name works without runtime errors.

* Fix: use sqlglot for model prefix stripping to preserve string literals

* Fix: parenthesize filters, always qualify step N with 's' alias

* Fix: resolve entity through model dimension sql_expr, normalize for each CTE alias

* Fix: qualify entity_sql_s with qualify_bare=True for step N

---------

Co-authored-by: github-actions[bot] <github-actions[bot]@users.noreply.github.com>

Author: nicosuave

sidemantic-schema.json

@@ -629,6 +629,22 @@
           "description": "SQL expression or formula (accepts 'expr' as alias)",
           "title": "Sql"
         },
+        "steps": {
+          "anyOf": [
+            {
+              "items": {
+                "type": "string"
+              },
+              "type": "array"
+            },
+            {
+              "type": "null"
+            }
+          ],
+          "default": null,
+          "description": "N-step funnel filter expressions (overrides base_event/conversion_event)",
+          "title": "Steps"
+        },
         "time_offset": {
           "anyOf": [
             {
@@ -1620,6 +1636,22 @@
             "description": "SQL expression or formula (accepts 'expr' as alias)",
             "title": "Sql"
           },
+          "steps": {
+            "anyOf": [
+              {
+                "items": {
+                  "type": "string"
+                },
+                "type": "array"
+              },
+              {
+                "type": "null"
+              }
+            ],
+            "default": null,
+            "description": "N-step funnel filter expressions (overrides base_event/conversion_event)",
+            "title": "Steps"
+          },
           "time_offset": {
             "anyOf": [
               {
@@ -2361,6 +2393,22 @@
                 "description": "SQL expression or formula (accepts 'expr' as alias)",
                 "title": "Sql"
               },
+              "steps": {
+                "anyOf": [
+                  {
+                    "items": {
+                      "type": "string"
+                    },
+                    "type": "array"
+                  },
+                  {
+                    "type": "null"
+                  }
+                ],
+                "default": null,
+                "description": "N-step funnel filter expressions (overrides base_event/conversion_event)",
+                "title": "Steps"
+              },
               "time_offset": {
                 "anyOf": [
                   {

sidemantic/adapters/sidemantic.py

@@ -296,6 +296,7 @@ def _parse_model(self, model_def: dict) -> Model | None:
                 base_event=measure_def.get("base_event"),
                 conversion_event=measure_def.get("conversion_event"),
                 conversion_window=measure_def.get("conversion_window"),
+                steps=measure_def.get("steps"),
                 offset_window=measure_def.get("offset_window"),
                 # Retention parameters
                 cohort_event=measure_def.get("cohort_event"),
@@ -419,6 +420,7 @@ def _parse_metric(self, metric_def: dict) -> Metric | None:
             base_event=metric_def.get("base_event"),
             conversion_event=metric_def.get("conversion_event"),
             conversion_window=metric_def.get("conversion_window"),
+            steps=metric_def.get("steps"),
             offset_window=metric_def.get("offset_window"),
             cohort_event=metric_def.get("cohort_event"),
             activity_event=metric_def.get("activity_event"),
@@ -585,6 +587,8 @@ def _export_model(self, model: Model) -> dict:
                     measure_def["conversion_event"] = measure.conversion_event
                 if measure.conversion_window:
                     measure_def["conversion_window"] = measure.conversion_window
+                if measure.steps:
+                    measure_def["steps"] = measure.steps
                 if measure.offset_window:
                     measure_def["offset_window"] = measure.offset_window
                 # Retention parameters
@@ -675,6 +679,8 @@ def _export_metric(self, measure: Metric, graph) -> dict:
             result["conversion_event"] = measure.conversion_event
         if measure.conversion_window:
             result["conversion_window"] = measure.conversion_window
+        if measure.steps:
+            result["steps"] = measure.steps
         if measure.offset_window:
             result["offset_window"] = measure.offset_window
         if measure.cohort_event:

sidemantic/core/metric.py

@@ -200,10 +200,16 @@ def validate_type_specific_fields(self):
         if self.type == "conversion":
             if not self.entity:
                 raise ValueError("conversion metric requires 'entity' field")
-            if not self.base_event:
-                raise ValueError("conversion metric requires 'base_event' field")
-            if not self.conversion_event:
-                raise ValueError("conversion metric requires 'conversion_event' field")
+            if self.steps:
+                if len(self.steps) < 2:
+                    raise ValueError("conversion metric 'steps' requires at least 2 steps")
+                if self.conversion_window:
+                    raise ValueError(
+                        "conversion metric cannot specify both 'steps' and 'conversion_window'; "
+                        "conversion_window is only supported for base_event/conversion_event funnels"
+                    )
+            elif not self.base_event or not self.conversion_event:
+                raise ValueError("conversion metric requires 'steps' or both 'base_event' and 'conversion_event'")
         if self.type == "retention":
             if not self.entity:
                 raise ValueError("retention metric requires 'entity' field")
@@ -256,6 +262,9 @@ def validate_type_specific_fields(self):
     base_event: str | None = Field(None, description="Starting event filter")
     conversion_event: str | None = Field(None, description="Target event filter")
     conversion_window: str | None = Field(None, description="Conversion time window")
+    steps: list[str] | None = Field(
+        None, description="N-step funnel filter expressions (overrides base_event/conversion_event)"
+    )
 
     # Retention parameters
     cohort_event: str | None = Field(