Fix ai report docs and allow inheriting watermark for time range resolution

docs/docs/reference/project-files/alerts.md

@@ -119,37 +119,31 @@ _[oneOf]_ - Data source for the alert _(required)_
 
       - **`prompt`** - _[string]_ - Custom prompt to guide the AI analysis. If not provided, a default analysis prompt is used.
 
-      - **`time_range`** - _[object]_ - Time range for the analysis period
+      - **`time_range`** - _[object]_ - Time range for the analysis period. Use either a Rill time expression or fixed start and end timestamps.
 
-        - **`iso_duration`** - _[string]_ - ISO 8601 duration (e.g., P7D for 7 days, P1M for 1 month)
-
-        - **`iso_offset`** - _[string]_ - ISO 8601 offset from current time (e.g., P1D to start from yesterday)
+        - **`expression`** - _[string]_ - Rill time expression. Note that snapping excludes the period containing the reference point, so '1D as of latest/D' is the day before the latest data; use '1D as of latest/D+1D' for the last day with data.
 
         - **`start`** - _[string]_ - Start timestamp in ISO 8601 format
 
         - **`end`** - _[string]_ - End timestamp in ISO 8601 format
 
-        - **`expression`** - _[string]_ - Rill time expression (e.g., 'last 7 days', 'this month')
-
-      - **`comparison_time_range`** - _[object]_ - Optional comparison time range for period-over-period analysis
-
-        - **`iso_duration`** - _[string]_ - ISO 8601 duration for comparison period
+      - **`comparison_time_range`** - _[object]_ - Optional comparison time range for period-over-period analysis. Use either a Rill time expression or fixed start and end timestamps.
 
-        - **`iso_offset`** - _[string]_ - ISO 8601 offset for comparison period (e.g., P7D to compare with previous week)
+        - **`expression`** - _[string]_ - Rill time expression for the comparison period (e.g., '1D as of latest/D' when the time range is '1D as of latest/D+1D')
 
         - **`start`** - _[string]_ - Start timestamp in ISO 8601 format
 
         - **`end`** - _[string]_ - End timestamp in ISO 8601 format
 
-        - **`expression`** - _[string]_ - Rill time expression for comparison period
+      - **`time_zone`** - _[string]_ - IANA time zone used to evaluate the time range expressions (e.g., 'America/New_York'). Defaults to UTC.
 
-      - **`context`** - _[object]_ - Context to constrain the AI analysis
+      - **`explore`** - _[string]_ - Name of the explore dashboard to analyze. If provided, the analysis is limited to the metrics view of this dashboard. Combined with `watermark: inherit` on the report, time range expressions are resolved against the latest data in the metrics view instead of the report's trigger time.
 
-        - **`explore`** - _[string]_ - Name of the explore dashboard to analyze
+      - **`dimensions`** - _[array of string]_ - List of dimensions to include in the analysis
 
-        - **`dimensions`** - _[array of string]_ - List of dimensions to include in analysis
+      - **`measures`** - _[array of string]_ - List of measures to include in the analysis
 
-        - **`measures`** - _[array of string]_ - List of measures to include in analysis
+      - **`where`** - _[object]_ - Optional filter expression to apply to the analysis, in the same format as metrics view query filters
 
 ### `for`
 

docs/docs/reference/project-files/models.md

@@ -182,37 +182,31 @@ _[oneOf]_ - Refers to the explicitly defined state of your model, cannot be used
 
       - **`prompt`** - _[string]_ - Custom prompt to guide the AI analysis. If not provided, a default analysis prompt is used.
 
-      - **`time_range`** - _[object]_ - Time range for the analysis period
+      - **`time_range`** - _[object]_ - Time range for the analysis period. Use either a Rill time expression or fixed start and end timestamps.
 
-        - **`iso_duration`** - _[string]_ - ISO 8601 duration (e.g., P7D for 7 days, P1M for 1 month)
-
-        - **`iso_offset`** - _[string]_ - ISO 8601 offset from current time (e.g., P1D to start from yesterday)
+        - **`expression`** - _[string]_ - Rill time expression. Note that snapping excludes the period containing the reference point, so '1D as of latest/D' is the day before the latest data; use '1D as of latest/D+1D' for the last day with data.
 
         - **`start`** - _[string]_ - Start timestamp in ISO 8601 format
 
         - **`end`** - _[string]_ - End timestamp in ISO 8601 format
 
-        - **`expression`** - _[string]_ - Rill time expression (e.g., 'last 7 days', 'this month')
-
-      - **`comparison_time_range`** - _[object]_ - Optional comparison time range for period-over-period analysis
-
-        - **`iso_duration`** - _[string]_ - ISO 8601 duration for comparison period
+      - **`comparison_time_range`** - _[object]_ - Optional comparison time range for period-over-period analysis. Use either a Rill time expression or fixed start and end timestamps.
 
-        - **`iso_offset`** - _[string]_ - ISO 8601 offset for comparison period (e.g., P7D to compare with previous week)
+        - **`expression`** - _[string]_ - Rill time expression for the comparison period (e.g., '1D as of latest/D' when the time range is '1D as of latest/D+1D')
 
         - **`start`** - _[string]_ - Start timestamp in ISO 8601 format
 
         - **`end`** - _[string]_ - End timestamp in ISO 8601 format
 
-        - **`expression`** - _[string]_ - Rill time expression for comparison period
+      - **`time_zone`** - _[string]_ - IANA time zone used to evaluate the time range expressions (e.g., 'America/New_York'). Defaults to UTC.
 
-      - **`context`** - _[object]_ - Context to constrain the AI analysis
+      - **`explore`** - _[string]_ - Name of the explore dashboard to analyze. If provided, the analysis is limited to the metrics view of this dashboard. Combined with `watermark: inherit` on the report, time range expressions are resolved against the latest data in the metrics view instead of the report's trigger time.
 
-        - **`explore`** - _[string]_ - Name of the explore dashboard to analyze
+      - **`dimensions`** - _[array of string]_ - List of dimensions to include in the analysis
 
-        - **`dimensions`** - _[array of string]_ - List of dimensions to include in analysis
+      - **`measures`** - _[array of string]_ - List of measures to include in the analysis
 
-        - **`measures`** - _[array of string]_ - List of measures to include in analysis
+      - **`where`** - _[object]_ - Optional filter expression to apply to the analysis, in the same format as metrics view query filters
 
 ```yaml
 state:
@@ -280,37 +274,31 @@ _[oneOf]_ - Refers to how your data is partitioned; cannot be used with state. (
 
       - **`prompt`** - _[string]_ - Custom prompt to guide the AI analysis. If not provided, a default analysis prompt is used.
 
-      - **`time_range`** - _[object]_ - Time range for the analysis period
+      - **`time_range`** - _[object]_ - Time range for the analysis period. Use either a Rill time expression or fixed start and end timestamps.
 
-        - **`iso_duration`** - _[string]_ - ISO 8601 duration (e.g., P7D for 7 days, P1M for 1 month)
-
-        - **`iso_offset`** - _[string]_ - ISO 8601 offset from current time (e.g., P1D to start from yesterday)
+        - **`expression`** - _[string]_ - Rill time expression. Note that snapping excludes the period containing the reference point, so '1D as of latest/D' is the day before the latest data; use '1D as of latest/D+1D' for the last day with data.
 
         - **`start`** - _[string]_ - Start timestamp in ISO 8601 format
 
         - **`end`** - _[string]_ - End timestamp in ISO 8601 format
 
-        - **`expression`** - _[string]_ - Rill time expression (e.g., 'last 7 days', 'this month')
-
-      - **`comparison_time_range`** - _[object]_ - Optional comparison time range for period-over-period analysis
-
-        - **`iso_duration`** - _[string]_ - ISO 8601 duration for comparison period
+      - **`comparison_time_range`** - _[object]_ - Optional comparison time range for period-over-period analysis. Use either a Rill time expression or fixed start and end timestamps.
 
-        - **`iso_offset`** - _[string]_ - ISO 8601 offset for comparison period (e.g., P7D to compare with previous week)
+        - **`expression`** - _[string]_ - Rill time expression for the comparison period (e.g., '1D as of latest/D' when the time range is '1D as of latest/D+1D')
 
         - **`start`** - _[string]_ - Start timestamp in ISO 8601 format
 
         - **`end`** - _[string]_ - End timestamp in ISO 8601 format
 
-        - **`expression`** - _[string]_ - Rill time expression for comparison period
+      - **`time_zone`** - _[string]_ - IANA time zone used to evaluate the time range expressions (e.g., 'America/New_York'). Defaults to UTC.
 
-      - **`context`** - _[object]_ - Context to constrain the AI analysis
+      - **`explore`** - _[string]_ - Name of the explore dashboard to analyze. If provided, the analysis is limited to the metrics view of this dashboard. Combined with `watermark: inherit` on the report, time range expressions are resolved against the latest data in the metrics view instead of the report's trigger time.
 
-        - **`explore`** - _[string]_ - Name of the explore dashboard to analyze
+      - **`dimensions`** - _[array of string]_ - List of dimensions to include in the analysis
 
-        - **`dimensions`** - _[array of string]_ - List of dimensions to include in analysis
+      - **`measures`** - _[array of string]_ - List of measures to include in the analysis
 
-        - **`measures`** - _[array of string]_ - List of measures to include in analysis
+      - **`where`** - _[object]_ - Optional filter expression to apply to the analysis, in the same format as metrics view query filters
 
 ```yaml
 partitions:

docs/docs/reference/project-files/reports.md

@@ -121,37 +121,31 @@ Supports ai resolvers only as of now.
 
       - **`prompt`** - _[string]_ - Custom prompt to guide the AI analysis. If not provided, a default analysis prompt is used.
 
-      - **`time_range`** - _[object]_ - Time range for the analysis period
+      - **`time_range`** - _[object]_ - Time range for the analysis period. Use either a Rill time expression or fixed start and end timestamps.
 
-        - **`iso_duration`** - _[string]_ - ISO 8601 duration (e.g., P7D for 7 days, P1M for 1 month)
-
-        - **`iso_offset`** - _[string]_ - ISO 8601 offset from current time (e.g., P1D to start from yesterday)
+        - **`expression`** - _[string]_ - Rill time expression. Note that snapping excludes the period containing the reference point, so '1D as of latest/D' is the day before the latest data; use '1D as of latest/D+1D' for the last day with data.
 
         - **`start`** - _[string]_ - Start timestamp in ISO 8601 format
 
         - **`end`** - _[string]_ - End timestamp in ISO 8601 format
 
-        - **`expression`** - _[string]_ - Rill time expression (e.g., 'last 7 days', 'this month')
-
-      - **`comparison_time_range`** - _[object]_ - Optional comparison time range for period-over-period analysis
-
-        - **`iso_duration`** - _[string]_ - ISO 8601 duration for comparison period
+      - **`comparison_time_range`** - _[object]_ - Optional comparison time range for period-over-period analysis. Use either a Rill time expression or fixed start and end timestamps.
 
-        - **`iso_offset`** - _[string]_ - ISO 8601 offset for comparison period (e.g., P7D to compare with previous week)
+        - **`expression`** - _[string]_ - Rill time expression for the comparison period (e.g., '1D as of latest/D' when the time range is '1D as of latest/D+1D')
 
         - **`start`** - _[string]_ - Start timestamp in ISO 8601 format
 
         - **`end`** - _[string]_ - End timestamp in ISO 8601 format
 
-        - **`expression`** - _[string]_ - Rill time expression for comparison period
+      - **`time_zone`** - _[string]_ - IANA time zone used to evaluate the time range expressions (e.g., 'America/New_York'). Defaults to UTC.
 
-      - **`context`** - _[object]_ - Context to constrain the AI analysis
+      - **`explore`** - _[string]_ - Name of the explore dashboard to analyze. If provided, the analysis is limited to the metrics view of this dashboard. Combined with `watermark: inherit` on the report, time range expressions are resolved against the latest data in the metrics view instead of the report's trigger time.
 
-        - **`explore`** - _[string]_ - Name of the explore dashboard to analyze
+      - **`dimensions`** - _[array of string]_ - List of dimensions to include in the analysis
 
-        - **`dimensions`** - _[array of string]_ - List of dimensions to include in analysis
+      - **`measures`** - _[array of string]_ - List of measures to include in the analysis
 
-        - **`measures`** - _[array of string]_ - List of measures to include in analysis
+      - **`where`** - _[object]_ - Optional filter expression to apply to the analysis, in the same format as metrics view query filters
 
 ### `query`
 
@@ -250,15 +244,15 @@ type: report
 display_name: Daily AI Insights
 refresh:
     cron: "0 8 * * *"
+watermark: inherit # resolve "latest" against the explore's data instead of the trigger time
 data:
     ai:
         prompt: "Analyze key metrics and identify significant changes"
         time_range:
-            expression: "1D as of latest/D"
+            expression: "1D as of latest/D+1D" # the last day with data
         comparison_time_range:
-            expression: "1D as of latest/D offset -1D"
-        context:
-            explore: my_explore
+            expression: "1D as of latest/D" # the day before it
+        explore: my_explore
 notify:
     email:
         recipients:

runtime/parser/parse_partial_data.go

@@ -116,6 +116,11 @@ func (p *Parser) parseDataYAML(paths []string, raw *DataYAML, contextualConnecto
 		count++
 		resolver = "ai"
 		resolverProps = raw.AI
+		// The agent can access any metrics view, so the explore is the only dependency known up front.
+		// Adding it as a ref makes reports wait for it to reconcile and lets watermark: inherit resolve time ranges against its data.
+		if explore, ok := raw.AI["explore"].(string); ok && explore != "" {
+			refs = append(refs, ResourceName{Kind: ResourceKindExplore, Name: explore})
+		}
 	}
 
 	// Handle union resolver

runtime/parser/parser_test.go

@@ -1524,6 +1524,94 @@ annotations:
 	requireResourcesAndErrors(t, p, resources, nil)
 }
 
+func TestReportAIExploreRef(t *testing.T) {
+	ctx := context.Background()
+	repo := makeRepo(t, map[string]string{
+		`rill.yaml`: ``,
+		`reports/r1.yaml`: `
+type: report
+display_name: AI Report
+
+refresh:
+  cron: 0 8 * * *
+
+watermark: inherit
+
+data:
+  ai:
+    prompt: Analyze key metrics
+    time_range:
+      expression: 1D as of latest/D
+    explore: e1
+
+notify:
+  email:
+    recipients:
+      - user_1@example.com
+`,
+		// Without an explore, the report has no refs.
+		`reports/r2.yaml`: `
+type: report
+display_name: AI Report
+
+refresh:
+  cron: 0 8 * * *
+
+data:
+  ai:
+    prompt: Analyze key metrics
+
+notify:
+  email:
+    recipients:
+      - user_1@example.com
+`,
+	})
+
+	resources := []*Resource{
+		{
+			Name:  ResourceName{Kind: ResourceKindReport, Name: "r1"},
+			Paths: []string{"/reports/r1.yaml"},
+			Refs:  []ResourceName{{Kind: ResourceKindExplore, Name: "e1"}},
+			ReportSpec: &runtimev1.ReportSpec{
+				DisplayName:     "AI Report",
+				RefreshSchedule: &runtimev1.Schedule{Cron: "0 8 * * *"},
+				Resolver:        "ai",
+				ResolverProperties: must(structpb.NewStruct(map[string]any{
+					"prompt":     "Analyze key metrics",
+					"time_range": map[string]any{"expression": "1D as of latest/D"},
+					"explore":    "e1",
+				})),
+				Notifiers: []*runtimev1.Notifier{{
+					Connector:  "email",
+					Properties: must(structpb.NewStruct(map[string]any{"recipients": []any{"user_1@example.com"}})),
+				}},
+				WatermarkInherit: true,
+			},
+		},
+		{
+			Name:  ResourceName{Kind: ResourceKindReport, Name: "r2"},
+			Paths: []string{"/reports/r2.yaml"},
+			ReportSpec: &runtimev1.ReportSpec{
+				DisplayName:     "AI Report",
+				RefreshSchedule: &runtimev1.Schedule{Cron: "0 8 * * *"},
+				Resolver:        "ai",
+				ResolverProperties: must(structpb.NewStruct(map[string]any{
+					"prompt": "Analyze key metrics",
+				})),
+				Notifiers: []*runtimev1.Notifier{{
+					Connector:  "email",
+					Properties: must(structpb.NewStruct(map[string]any{"recipients": []any{"user_1@example.com"}})),
+				}},
+			},
+		},
+	}
+
+	p, err := Parse(ctx, repo, "", "", "duckdb", true)
+	require.NoError(t, err)
+	requireResourcesAndErrors(t, p, resources, nil)
+}
+
 func TestReportPdfValidation(t *testing.T) {
 	ctx := context.Background()
 	repo := makeRepo(t, map[string]string{