feat: add analyst agent support for canvas dashboard (#8669)

* feat: add chat support in canvas preview mode

* Improve component identification

* Add context to canvas

* Fix context not being honoured

* Improve chart labels

* Add tests for canvas context

* Fix issues

* Fix CI

* Address PR comments

* Add missing chat toggle in cloud

* Fix incorrect filters being sent

* Fix lint

* Improve typing

Author: AdityaHegde

proto/gen/rill/admin/v1/openapi.yaml

@@ -2307,7 +2307,7 @@ externalDocs:
 info:
     description: Rill Admin API enables programmatic management of Rill Cloud resources, including organizations, projects, and user access. It provides endpoints for creating, updating, and deleting these resources, as well as managing authentication and permissions.
     title: Rill Admin API
-    version: v0.80.0
+    version: v0.79.5
 openapi: 3.0.3
 paths:
     /v1/ai/complete:

proto/gen/rill/admin/v1/public.openapi.yaml

@@ -2307,7 +2307,7 @@ externalDocs:
 info:
     description: Rill Admin API enables programmatic management of Rill Cloud resources, including organizations, projects, and user access. It provides endpoints for creating, updating, and deleting these resources, as well as managing authentication and permissions.
     title: Rill Admin API
-    version: v0.80.0
+    version: v0.79.5
 openapi: 3.0.3
 paths:
     /v1/ai/complete: {}

proto/gen/rill/runtime/v1/api.pb.go

@@ -4049,6 +4049,12 @@ definitions:
       explore:
         type: string
         description: Optional explore dashboard.
+      canvas:
+        type: string
+        description: Optional canvas dashboard.
+      canvasComponent:
+        type: string
+        description: Optional canvas component within a dashboard.
       dimensions:
         type: array
         items:
@@ -4062,6 +4068,14 @@ definitions:
       where:
         $ref: '#/definitions/v1Expression'
         description: Optional filters.
+      wherePerMetricsView:
+        type: object
+        additionalProperties:
+          $ref: '#/definitions/v1Expression'
+        title: |-
+          Filter expressions as key-value pairs for the canvas.
+          Key: Metrics view name
+          Value: Expression object
       timeStart:
         type: string
         format: date-time

proto/gen/rill/runtime/v1/api.pb.validate.go

@@ -1066,12 +1066,20 @@ message Message {
 message AnalystAgentContext {
   // Optional explore dashboard.
   string explore = 4;
+  // Optional canvas dashboard.
+  string canvas = 10;
+  // Optional canvas component within a dashboard.
+  string canvas_component = 11;
   // Optional dimensions.
   repeated string dimensions = 5;
   // Optional measures.
   repeated string measures = 6;
   // Optional filters.
   rill.runtime.v1.Expression where = 7;
+  // Filter expressions as key-value pairs for the canvas.
+  // Key: Metrics view name
+  // Value: Expression object
+  map<string, rill.runtime.v1.Expression> where_per_metrics_view = 12;
   // Optional start of a time range.
   google.protobuf.Timestamp time_start = 8;
   // Optional end of a time range.

proto/gen/rill/runtime/v1/runtime.swagger.yaml

@@ -52,6 +52,7 @@ func NewRunner(rt *runtime.Runtime, activity *activity.Client) *Runner {
 
 	RegisterTool(r, &ListMetricsViews{Runtime: rt})
 	RegisterTool(r, &GetMetricsView{Runtime: rt})
+	RegisterTool(r, &GetCanvas{Runtime: rt})
 	RegisterTool(r, &QueryMetricsViewSummary{Runtime: rt})
 	RegisterTool(r, &QueryMetricsView{Runtime: rt})
 	RegisterTool(r, &CreateChart{Runtime: rt})

proto/rill/runtime/v1/api.proto

@@ -24,13 +24,18 @@ type AnalystAgent struct {
 var _ Tool[*AnalystAgentArgs, *AnalystAgentResult] = (*AnalystAgent)(nil)
 
 type AnalystAgentArgs struct {
-	Prompt     string                  `json:"prompt"`
-	Explore    string                  `json:"explore" yaml:"explore" jsonschema:"Optional explore dashboard name. If provided, the exploration will be limited to this dashboard."`
-	Dimensions []string                `json:"dimensions" yaml:"dimensions" jsonschema:"Optional list of dimensions for queries. If provided, the queries will be limited to these dimensions."`
-	Measures   []string                `json:"measures" yaml:"measures" jsonschema:"Optional list of measures for queries. If provided, the queries will be limited to these measures."`
-	Where      *metricsview.Expression `json:"where" yaml:"where" jsonschema:"Optional filter for queries. If provided, this filter will be applied to all queries."`
-	TimeStart  time.Time               `json:"time_start" yaml:"time_start" jsonschema:"Optional start time for queries. time_end must be provided if time_start is provided."`
-	TimeEnd    time.Time               `json:"time_end" yaml:"time_end" jsonschema:"Optional end time for queries. time_start must be provided if time_end is provided."`
+	Prompt     string   `json:"prompt"`
+	Explore    string   `json:"explore" yaml:"explore" jsonschema:"Optional explore dashboard name. If provided, the exploration will be limited to this dashboard."`
+	Dimensions []string `json:"dimensions" yaml:"dimensions" jsonschema:"Optional list of dimensions for queries. If provided, the queries will be limited to these dimensions."`
+	Measures   []string `json:"measures" yaml:"measures" jsonschema:"Optional list of measures for queries. If provided, the queries will be limited to these measures."`
+
+	Canvas              string                             `json:"canvas" yaml:"canvas" jsonschema:"Optional canvas name. If provided, the exploration will be limited to this canvas."`
+	CanvasComponent     string                             `json:"canvas_component" yaml:"canvas_component" jsonschema:"Optional canvas component name. If provided, the exploration will be limited to this canvas component."`
+	WherePerMetricsView map[string]*metricsview.Expression `json:"where_per_metrics_view" yaml:"where_per_metrics_view" jsonschema:"Optional filter for queries per metrics view. If provided, this filter will be applied to queries for each metrics view."`
+
+	Where     *metricsview.Expression `json:"where" yaml:"where" jsonschema:"Optional filter for queries. If provided, this filter will be applied to all queries."`
+	TimeStart time.Time               `json:"time_start" yaml:"time_start" jsonschema:"Optional start time for queries. time_end must be provided if time_start is provided."`
+	TimeEnd   time.Time               `json:"time_end" yaml:"time_end" jsonschema:"Optional end time for queries. time_start must be provided if time_end is provided."`
 }
 
 func (a *AnalystAgentArgs) ToLLM() *aiv1.ContentBlock {
@@ -97,31 +102,53 @@ func (t *AnalystAgent) Handler(ctx context.Context, args *AnalystAgentArgs) (*An
 
 	// If a specific dashboard is being explored, we pre-invoke some relevant tool calls for that dashboard.
 	// TODO: This uses `first`, but that may not be safe if the user has navigated to another dashboard. We probably need some more sophisticated de-duplication here.
-	var metricsViewName string
-	if first && args.Explore != "" {
-		_, metricsView, err := t.getValidExploreAndMetricsView(ctx, args.Explore)
-		if err != nil {
-			return nil, err
-		}
-		metricsViewName = metricsView.Meta.Name.Name
+	var metricsViewNames []string
+	if first {
+		if args.Explore != "" {
+			_, metricsView, err := t.getValidExploreAndMetricsView(ctx, args.Explore)
+			if err != nil {
+				return nil, err
+			}
+			metricsViewNames = append(metricsViewNames, metricsView.Meta.Name.Name)
+		} else if args.Canvas != "" {
+			// Pre-invoke the get_canvas tool to get the canvas definition.
+			_, err := s.CallTool(ctx, RoleAssistant, GetCanvasName, nil, &GetCanvasArgs{
+				Canvas: args.Canvas,
+			})
+			if err != nil {
+				return nil, err
+			}
 
-		_, err = s.CallTool(ctx, RoleAssistant, QueryMetricsViewSummaryName, nil, &QueryMetricsViewSummaryArgs{
-			MetricsView: metricsViewName,
-		})
-		if err != nil {
-			return nil, err
+			_, metricsViews, err := t.getValidCanvasAndMetricsViews(ctx, args.Canvas)
+			if err != nil {
+				return nil, err
+			}
+
+			for _, res := range metricsViews {
+				metricsViewNames = append(metricsViewNames, res.Meta.Name.Name)
+			}
 		}
 
-		_, err = s.CallTool(ctx, RoleAssistant, GetMetricsViewName, nil, &GetMetricsViewArgs{
-			MetricsView: metricsViewName,
-		})
-		if err != nil {
-			return nil, err
+		// Pre-invoke the query_metrics_view tool for each metrics view tied to the explore/canvas.
+		for _, mvName := range metricsViewNames {
+			_, err := s.CallTool(ctx, RoleAssistant, QueryMetricsViewSummaryName, nil, &QueryMetricsViewSummaryArgs{
+				MetricsView: mvName,
+			})
+			if err != nil {
+				return nil, err
+			}
+
+			_, err = s.CallTool(ctx, RoleAssistant, GetMetricsViewName, nil, &GetMetricsViewArgs{
+				MetricsView: mvName,
+			})
+			if err != nil {
+				return nil, err
+			}
 		}
 	}
 
 	// If no specific dashboard is being explored, we pre-invoke the list_metrics_views tool.
-	if first && args.Explore == "" {
+	if first && len(metricsViewNames) == 0 {
 		_, err := s.CallTool(ctx, RoleAssistant, ListMetricsViewsName, nil, &ListMetricsViewsArgs{})
 		if err != nil {
 			return nil, err
@@ -131,12 +158,12 @@ func (t *AnalystAgent) Handler(ctx context.Context, args *AnalystAgentArgs) (*An
 	// Determine tools that can be used
 	tools := []string{}
 	if args.Explore == "" {
-		tools = append(tools, ListMetricsViewsName, GetMetricsViewName)
+		tools = append(tools, ListMetricsViewsName, GetMetricsViewName, GetCanvasName)
 	}
 	tools = append(tools, QueryMetricsViewSummaryName, QueryMetricsViewName, CreateChartName)
 
 	// Build completion messages
-	systemPrompt, err := t.systemPrompt(ctx, metricsViewName, args)
+	systemPrompt, err := t.systemPrompt(ctx, metricsViewNames, args)
 	if err != nil {
 		return nil, err
 	}
@@ -170,22 +197,30 @@ func (t *AnalystAgent) Handler(ctx context.Context, args *AnalystAgentArgs) (*An
 	return &AnalystAgentResult{Response: response}, nil
 }
 
-func (t *AnalystAgent) systemPrompt(ctx context.Context, metricsViewName string, args *AnalystAgentArgs) (string, error) {
+func (t *AnalystAgent) systemPrompt(ctx context.Context, metricsViewNames []string, args *AnalystAgentArgs) (string, error) {
 	// Prepare template data.
 	// NOTE: All the template properties are optional and may be empty.
 	session := GetSession(ctx)
 	ff, err := t.Runtime.FeatureFlags(ctx, session.InstanceID(), session.Claims())
 	if err != nil {
 		return "", fmt.Errorf("failed to get feature flags: %w", err)
 	}
+
+	metricsViewsQuoted := make([]string, len(metricsViewNames))
+	for i, mv := range metricsViewNames {
+		metricsViewsQuoted[i] = fmt.Sprintf("`%s`", mv)
+	}
+
 	data := map[string]any{
-		"ai_instructions": session.ProjectInstructions(),
-		"metrics_view":    metricsViewName,
-		"explore":         args.Explore,
-		"dimensions":      strings.Join(args.Dimensions, ", "),
-		"measures":        strings.Join(args.Measures, ", "),
-		"feature_flags":   ff,
-		"now":             time.Now(),
+		"ai_instructions":  session.ProjectInstructions(),
+		"metrics_views":    strings.Join(metricsViewsQuoted, ", "),
+		"explore":          args.Explore,
+		"canvas":           args.Canvas,
+		"canvas_component": args.CanvasComponent,
+		"dimensions":       strings.Join(args.Dimensions, ", "),
+		"measures":         strings.Join(args.Measures, ", "),
+		"feature_flags":    ff,
+		"now":              time.Now(),
 	}
 
 	if !args.TimeStart.IsZero() && !args.TimeEnd.IsZero() {
@@ -199,6 +234,18 @@ func (t *AnalystAgent) systemPrompt(ctx context.Context, metricsViewName string,
 			return "", err
 		}
 	}
+
+	if args.WherePerMetricsView != nil {
+		wherePerMetricsView := map[string]string{}
+		for metricsViewName, whereExpr := range args.WherePerMetricsView {
+			wherePerMetricsView[metricsViewName], err = metricsview.ExpressionToSQL(whereExpr)
+			if err != nil {
+				return "", err
+			}
+		}
+		data["where_per_metrics_view"] = wherePerMetricsView
+	}
+
 	data["forked"] = session.Forked()
 
 	// Generate the system prompt
@@ -218,7 +265,7 @@ Today's date is {{ .now.Format "Monday, January 2, 2006" }} ({{ .now.Format "200
 <process>
 **Phase 1: discovery (setup)**
 {{ if .explore }}
-Your goal is to analyze the contents of the dashboard "{{ .explore }}", which is powered by the metrics view "{{ .metrics_view }}".
+Your goal is to analyze the contents of the dashboard "{{ .explore }}", which is powered by the metrics view(s) {{ .metrics_views }}.
 The user is actively viewing this dashboard, and it's what you they refer to if they use expressions like "this dashboard", "the current view", etc.
 The metrics view's definition and time range of available data has been provided in your tool calls.
 
@@ -231,6 +278,22 @@ Here is an overview of the settings the user has currently applied to the dashbo
 You should:
 1. Carefully study the metrics view definition to understand the measures and dimensions available for analysis.
 2. Remember the time range of available data and use it to inform and filter your queries.
+{{ else if .canvas }}
+Your goal is to analyze the contents of the canvas "{{ .canvas }}", which is powered by the metrics view(s) {{ .metrics_views }}.
+The user is actively viewing this dashboard, and it's what you they refer to if they use expressions like "this dashboard", "the current view", etc.
+The metrics views and canvas definitions have been provided in your tool calls.
+
+Here is an overview of the settings the user has currently applied to the dashboard (Merge component's dimension_filters with "and"):
+{{ if (and .time_start .time_end) }}Use time range: start={{.time_start}}, end={{.time_end}}{{ end }}
+{{ if .where_per_metrics_view }}{{range $mv, $filter := .where_per_metrics_view}}Use where filters for metrics view "{{ $mv }}": "{{ $filter }}"
+{{end}}{{ end }}
+
+You should:
+1. Carefully study the canvas and metrics view definition to understand the measures and dimensions available for analysis.
+2. Remember the time range of available data and use it to inform and filter your queries.
+{{ if .canvas_component }}
+The user is looking at "{{ .canvas_component }}".
+{{ end }}
 {{ else }}
 Follow these steps in order:
 1. **Discover**: Use "list_metrics_views" to identify available datasets
@@ -391,3 +454,27 @@ func (t *AnalystAgent) getValidExploreAndMetricsView(ctx context.Context, explor
 
 	return explore, metricsView, nil
 }
+
+func (t *AnalystAgent) getValidCanvasAndMetricsViews(ctx context.Context, canvasName string) (*runtimev1.Resource, map[string]*runtimev1.Resource, error) {
+	session := GetSession(ctx)
+
+	resolvedCanvas, err := t.Runtime.ResolveCanvas(ctx, session.InstanceID(), canvasName, session.Claims())
+	if err != nil {
+		return nil, nil, err
+	}
+
+	if resolvedCanvas == nil || resolvedCanvas.Canvas == nil {
+		return nil, nil, fmt.Errorf("canvas %q not found", canvasName)
+	}
+
+	metricsViews := map[string]*runtimev1.Resource{}
+	for mv, res := range resolvedCanvas.ReferencedMetricsViews {
+		metricsView := res.GetMetricsView()
+		if metricsView == nil || metricsView.State.ValidSpec == nil {
+			continue
+		}
+		metricsViews[mv] = res
+	}
+
+	return resolvedCanvas.Canvas, metricsViews, nil
+}