feat(seer): Add LLM context to widget builder page

Mihir-Mavalankar · claude · Mihir-Mavalankar · commit ec1ddd17c941 · 2026-04-10T11:16:16.000-07:00
Register a 'widget-builder' node in the LLM context tree so the Seer
Explorer agent understands what widget the user is configuring. Pushes
builder state (dataset, displayType, visualize, fields, query, sort,
thresholds, legendAlias) with readable condition transforms.

Also adds the widget builder routes to STRUCTURED_CONTEXT_ROUTES so
structured context is sent instead of ASCII when the builder is open.

Co-Authored-By: Claude Opus 4.6 &lt;noreply@anthropic.com&gt;
diff --git a/static/app/views/dashboards/widgetBuilder/components/newWidgetBuilder.tsx b/static/app/views/dashboards/widgetBuilder/components/newWidgetBuilder.tsx
@@ -18,6 +18,7 @@ import {usePageFilters} from 'sentry/components/pageFilters/usePageFilters';
 import {t} from 'sentry/locale';
 import {CustomMeasurementsProvider} from 'sentry/utils/customMeasurements/customMeasurementsProvider';
 import {EventView} from 'sentry/utils/discover/eventView';
+import {generateFieldAsString} from 'sentry/utils/discover/fields';
 import {MetricsCardinalityProvider} from 'sentry/utils/performance/contexts/metricsCardinality';
 import {MEPSettingProvider} from 'sentry/utils/performance/contexts/metricsEnhancedSetting';
 import {useDimensions} from 'sentry/utils/useDimensions';
@@ -48,9 +49,46 @@ import {
   useWidgetBuilderContext,
   WidgetBuilderProvider,
 } from 'sentry/views/dashboards/widgetBuilder/contexts/widgetBuilderContext';
+import {useIsEditingWidget} from 'sentry/views/dashboards/widgetBuilder/hooks/useIsEditingWidget';
 import type {OnDataFetchedParams} from 'sentry/views/dashboards/widgetCard';
 import {DashboardsMEPProvider} from 'sentry/views/dashboards/widgetCard/dashboardsMEPContext';
+import {readableConditions} from 'sentry/views/dashboards/widgetCard/widgetLLMContext';
 import {MetricsDataSwitcher} from 'sentry/views/performance/landing/metricsDataSwitcher';
+import {useLLMContext} from 'sentry/views/seerExplorer/contexts/llmContext';
+import {registerLLMContext} from 'sentry/views/seerExplorer/contexts/registerLLMContext';
+
+/**
+ * Renderless component that registers a 'widget-builder' node in the LLM
+ * context tree and pushes the current builder state into it. Must be rendered
+ * inside WidgetBuilderProvider so useWidgetBuilderContext() is available.
+ */
+function WidgetBuilderLLMContextInner() {
+  const {state} = useWidgetBuilderContext();
+  const isEditing = useIsEditingWidget();
+
+  useLLMContext({
+    contextHint:
+      'Sentry widget builder. The user is configuring a dashboard widget. visualize is the y-axis metrics (timeseries) or the aggregate (big number/table). fields are group-by columns (timeseries) or visible columns (table). query filters the data and sort controls ordering.',
+    mode: isEditing ? 'editing' : 'creating',
+    title: state.title,
+    description: state.description,
+    dataset: state.dataset,
+    displayType: state.displayType,
+    visualize: state.yAxis?.map(generateFieldAsString),
+    fields: state.fields?.map(generateFieldAsString),
+    query: state.query?.map(readableConditions),
+    sort: state.sort?.map(s => (s.kind === 'desc' ? `-${s.field}` : s.field)),
+    thresholds: state.thresholds,
+    legendAlias: state.legendAlias,
+  });
+
+  return null;
+}
+
+const WidgetBuilderLLMContext = registerLLMContext(
+  'widget-builder',
+  WidgetBuilderLLMContextInner
+);
 
 export interface ThresholdMetaState {
   dataType?: string;
@@ -185,6 +223,7 @@ export function WidgetBuilderV2({
           />
           <Backdrop style={{opacity: 0.5, pointerEvents: 'auto'}} />
           <WidgetBuilderProvider>
+            <WidgetBuilderLLMContext />
             <CustomMeasurementsProvider organization={organization} selection={selection}>
               <ContainerWithoutSidebar
                 style={
diff --git a/static/app/views/dashboards/widgetBuilder/components/newWidgetBuilderLLMContext.spec.tsx b/static/app/views/dashboards/widgetBuilder/components/newWidgetBuilderLLMContext.spec.tsx
@@ -0,0 +1,232 @@
+import {render, waitFor} from 'sentry-test/reactTestingLibrary';
+
+import {DisplayType, WidgetType} from 'sentry/views/dashboards/types';
+import {
+  LLMContextProvider,
+  useLLMContext,
+} from 'sentry/views/seerExplorer/contexts/llmContext';
+import type {LLMContextSnapshot} from 'sentry/views/seerExplorer/contexts/llmContextTypes';
+
+import {WidgetBuilderV2} from './newWidgetBuilder';
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+function makeContextCapture() {
+  const ref: {current: (() => LLMContextSnapshot) | null} = {current: null};
+  function ContextCapture() {
+    const {getLLMContext} = useLLMContext();
+    ref.current = getLLMContext;
+    return null;
+  }
+  return {
+    ContextCapture,
+    getSnapshot: () => {
+      if (!ref.current) throw new Error('ContextCapture not mounted');
+      return ref.current();
+    },
+  };
+}
+
+const DASHBOARD = {
+  id: '1',
+  title: 'Test',
+  widgets: [],
+  filters: {},
+  dateCreated: '',
+  projects: undefined,
+};
+
+const NEW_PATH = '/organizations/org-slug/dashboard/1/widget-builder/widget/new/';
+const EDIT_PATH = '/organizations/org-slug/dashboard/1/widget-builder/widget/0/edit/';
+const EDIT_ROUTE =
+  '/organizations/:orgId/dashboard/:dashboardId/widget-builder/widget/:widgetIndex/edit/';
+
+/** Render the builder with the given URL query params, return the node data. */
+async function renderAndGetData(
+  query: Record<string, string | number | string[]>,
+  opts?: {isOpen?: boolean; path?: string; route?: string}
+) {
+  const {ContextCapture, getSnapshot} = makeContextCapture();
+  const isOpen = opts?.isOpen ?? true;
+
+  render(
+    <LLMContextProvider>
+      <ContextCapture />
+      <WidgetBuilderV2
+        isOpen={isOpen}
+        onClose={jest.fn()}
+        onSave={jest.fn()}
+        dashboard={DASHBOARD}
+        dashboardFilters={{}}
+        openWidgetTemplates={false}
+        setOpenWidgetTemplates={jest.fn()}
+      />
+    </LLMContextProvider>,
+    {
+      initialRouterConfig: {
+        location: {pathname: opts?.path ?? NEW_PATH, query},
+        ...(opts?.route ? {route: opts.route} : {}),
+      },
+    }
+  );
+
+  if (!isOpen) return undefined;
+
+  let data: Record<string, unknown> | undefined;
+  await waitFor(() => {
+    const node = getSnapshot().nodes.find(n => n.nodeType === 'widget-builder');
+    expect(node).toBeDefined();
+    data = node!.data as Record<string, unknown>;
+  });
+  return data!;
+}
+
+// ---------------------------------------------------------------------------
+// Mocks
+// ---------------------------------------------------------------------------
+
+const MOCK_URLS = [
+  '/organizations/org-slug/releases/',
+  '/organizations/org-slug/tags/',
+  '/organizations/org-slug/dashboard/1/',
+  '/organizations/org-slug/issues/',
+  '/organizations/org-slug/events/',
+  '/organizations/org-slug/releases/stats/',
+  '/organizations/org-slug/trace-items/attributes/',
+  '/organizations/org-slug/measurements-meta/',
+  '/organizations/org-slug/recent-searches/',
+];
+
+beforeEach(() => {
+  for (const url of MOCK_URLS) {
+    MockApiClient.addMockResponse({url, body: []});
+  }
+  MockApiClient.addMockResponse({
+    url: '/organizations/org-slug/events-stats/',
+    body: {data: [], start: 0, end: 0},
+  });
+});
+
+// ---------------------------------------------------------------------------
+// Tests
+// ---------------------------------------------------------------------------
+
+describe('WidgetBuilder LLM Context', () => {
+  it('registers node with full builder state', async () => {
+    const data = await renderAndGetData({
+      displayType: DisplayType.LINE,
+      dataset: WidgetType.ERRORS,
+      title: 'My Widget',
+      yAxis: 'count()',
+      field: 'browser.name',
+      query: 'browser.name:Firefox',
+    });
+
+    expect(data!.mode).toBe('creating');
+    expect(data!.title).toBe('My Widget');
+    expect(data!.dataset).toBe(WidgetType.ERRORS);
+    expect(data!.displayType).toBe(DisplayType.LINE);
+    expect(data!.visualize).toEqual(['count()']);
+    expect(data!.fields).toEqual(['browser.name']);
+    expect(data!.query).toEqual(['browser.name:Firefox']);
+    expect(data!.contextHint).toContain('widget builder');
+  });
+
+  it('sets mode to editing when widgetIndex param is present', async () => {
+    const data = await renderAndGetData(
+      {displayType: DisplayType.TABLE, dataset: WidgetType.SPANS},
+      {path: EDIT_PATH, route: EDIT_ROUTE}
+    );
+    expect(data!.mode).toBe('editing');
+  });
+
+  it('does not register a node when the builder is closed', async () => {
+    const data = await renderAndGetData({}, {isOpen: false});
+    expect(data).toBeUndefined();
+  });
+
+  it('applies readableConditions to query filters', async () => {
+    const data = await renderAndGetData({
+      displayType: DisplayType.TABLE,
+      dataset: WidgetType.ERRORS,
+      query: 'span.name:\uf00dContains\uf00dfoo',
+    });
+    expect(data!.query).toEqual(['span.name: contains foo']);
+  });
+
+  it('formats sort with desc prefix', async () => {
+    const data = await renderAndGetData({
+      displayType: DisplayType.TABLE,
+      dataset: WidgetType.ERRORS,
+      field: 'count()',
+      sort: '-count()',
+    });
+    expect(data!.sort).toEqual(['-count()']);
+  });
+
+  it('formats sort without prefix for asc', async () => {
+    const data = await renderAndGetData({
+      displayType: DisplayType.TABLE,
+      dataset: WidgetType.ERRORS,
+      field: 'count()',
+      sort: 'count()',
+    });
+    expect(data!.sort).toEqual(['count()']);
+  });
+
+  it('passes through thresholds config', async () => {
+    const thresholds = JSON.stringify({
+      max_values: {max1: 100, max2: 200},
+      unit: 'millisecond',
+    });
+    const data = await renderAndGetData({
+      displayType: DisplayType.BIG_NUMBER,
+      dataset: WidgetType.ERRORS,
+      thresholds,
+    });
+    expect(data!.thresholds).toEqual(expect.objectContaining({unit: 'millisecond'}));
+  });
+
+  it('passes through legendAlias', async () => {
+    const data = await renderAndGetData({
+      displayType: DisplayType.LINE,
+      dataset: WidgetType.ERRORS,
+      yAxis: 'count()',
+      legendAlias: 'Error count',
+    });
+    expect(data!.legendAlias).toEqual(['Error count']);
+  });
+
+  it('passes through description', async () => {
+    const data = await renderAndGetData({
+      displayType: DisplayType.LINE,
+      dataset: WidgetType.ERRORS,
+      description: 'Tracks error rate',
+    });
+    expect(data!.description).toBe('Tracks error rate');
+  });
+
+  it('handles multiple yAxis and fields', async () => {
+    const data = await renderAndGetData({
+      displayType: DisplayType.LINE,
+      dataset: WidgetType.ERRORS,
+      yAxis: ['count()', 'count_unique(user)'],
+      field: ['browser.name', 'os.name'],
+    });
+    expect(data!.visualize).toEqual(['count()', 'count_unique(user)']);
+    expect(data!.fields).toEqual(['browser.name', 'os.name']);
+  });
+
+  it('exposes fields as table columns for table display type', async () => {
+    const data = await renderAndGetData({
+      displayType: DisplayType.TABLE,
+      dataset: WidgetType.ERRORS,
+      field: ['title', 'count()', 'last_seen()'],
+    });
+    // For tables, fields holds all visible columns; yAxis defaults to empty
+    expect(data!.fields).toEqual(['title', 'count()', 'last_seen()']);
+    expect(data!.visualize).toEqual([]);
+  });
+});
diff --git a/static/app/views/seerExplorer/contexts/llmContextTypes.ts b/static/app/views/seerExplorer/contexts/llmContextTypes.ts
@@ -17,7 +17,7 @@
  * Known node types for the LLM context tree.
  * Add new types here as new context-aware components are registered.
  */
-export type LLMContextNodeType = 'chart' | 'dashboard' | 'widget';
+export type LLMContextNodeType = 'chart' | 'dashboard' | 'widget' | 'widget-builder';
 
 /**
  * A single node in the flat registry.
diff --git a/static/app/views/seerExplorer/hooks/useSeerExplorer.tsx b/static/app/views/seerExplorer/hooks/useSeerExplorer.tsx
@@ -52,7 +52,11 @@ type SeerExplorerChatResponse = {
 const POLL_INTERVAL = 500; // Poll every 500ms
 
 /** Routes where the LLMContext tree provides structured page context. */
-const STRUCTURED_CONTEXT_ROUTES = new Set(['/dashboard/:dashboardId/']);
+const STRUCTURED_CONTEXT_ROUTES = new Set([
+  '/dashboard/:dashboardId/',
+  '/dashboard/:dashboardId/widget-builder/widget/new/',
+  '/dashboard/:dashboardId/widget-builder/widget/:widgetIndex/edit/',
+]);
 
 const OPTIMISTIC_ASSISTANT_TEXTS = [
   'Looking around...',
