chore(compass-assistant): add explain plan entry point COMPASS-9606 #7208

gagik · 2025-08-18T13:13:10Z

Adds the explain plan entry point.

gagik · 2025-08-18T13:19:17Z

package-lock.json

        "mocha": "^10.2.0"
      }
    },
-    "packages/bson-transpilers/node_modules/@typescript-eslint/eslint-plugin": {


this is weird... I tried checking out main and re-running from a clean slate and this still happens... is main package-lock in a bad state?

It could be, but do double-check which version of npm you're running. I've seen it behave completely differently between versions recently giving me exactly this kind of behaviour.

Someone recently merged a pretty stale PR and this got in main, it's not great that these were duplicated, but also is not an issue really, this is a harmless cleanup, we're running checks in CI to make sure that package-lock in a good shape and doesn't have issues

Copilot

Pull Request Overview

This PR adds an AI Assistant integration to the Explain Plan modal, allowing users to interpret explain plan output through natural language. The feature includes a new "Interpret for me" button that opens the AI Assistant drawer and sends the explain plan data for interpretation.

Adds AI Assistant integration to the Explain Plan modal with conditional rendering based on preferences
Implements explain plan interpretation functionality that converts JSON data to natural language
Updates type definitions to support custom display text for AI Assistant messages

Reviewed Changes

Copilot reviewed 10 out of 11 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
packages/compass-explain-plan/src/components/explain-plan-modal.tsx	Adds "Interpret for me" button and AI Assistant integration to the modal header
packages/compass-explain-plan/src/components/explain-plan-modal.spec.tsx	Adds tests for AI Assistant button visibility based on preferences
packages/compass-explain-plan/package.json	Adds compass-assistant dependency
packages/compass-assistant/src/prompts.ts	Creates explain plan prompt template for AI interpretation
packages/compass-assistant/src/index.tsx	Exports useAssistantActions hook
packages/compass-assistant/src/compass-assistant-provider.tsx	Implements interpretExplainPlan action and extends message type with metadata
packages/compass-assistant/test/utils.tsx	Updates mock chat utility to use new AssistantMessage type
packages/compass-assistant/src/compass-assistant-provider.spec.tsx	Updates tests to use new AssistantMessage type
packages/compass-assistant/src/assistant-chat.tsx	Adds support for displaying custom text via message metadata
packages/compass-assistant/src/assistant-chat.spec.tsx	Adds tests for custom display text functionality

_{Tip: Customize your code reviews with copilot-instructions.md. Create the file or learn how to get started.
You can also share your feedback on Copilot code review for a chance to win a $100 gift card. Take the survey.}

Copilot · 2025-08-18T13:19:49Z

packages/compass-assistant/src/assistant-chat.tsx

+                ?.filter((part) => part.type === 'text')
+                .map((part) => part.text)
+                .join('') ||
+              ''}


[nitpick] The display logic uses a complex ternary expression that could be simplified for better readability. Consider extracting this into a helper function or variable to make the intent clearer.

Personally I would do this, but it is indeed nitpicky.

Copilot · 2025-08-18T13:19:50Z

packages/compass-assistant/src/compass-assistant-provider.tsx

+    interpretExplainPlan: (explainPlan: string) => {
+      openDrawer(ASSISTANT_DRAWER_ID);
+      const { prompt, displayText } = buildExplainPlanPrompt(explainPlan);
+      void chat.sendMessage(


[nitpick] Using 'void' to ignore the promise is acceptable here, but consider adding error handling for the sendMessage call to provide better user feedback if the operation fails.

Suggested change

void chat.sendMessage(

chat.sendMessage(

this will be followed up later and handled with onError on useChat hook

gribnoysup · 2025-08-18T16:15:59Z

packages/compass-assistant/src/prompts.ts

+Explain output: 
+${explainPlan}`,
+    displayText:
+      'Given this MongoDB explain plan, provide a concise human readable explanation that explains the query execution plan and highlights aspects of the plan that might impact query performance.',


I wonder if for displaying purposes it's worth including something relevant to specific explain that was run, like a namespace or something?

we could if we get designs to use them but from my understanding for v1 we're just going to hide i.e. the explain plan and let the response include relevant enough context.

Ah, it could also be in the text, right, good idea. I will ask this to Misba and add it.

The explain might be very verbose to be converted to text, but I think even just adding a namespace to display text will go a long way here. I was playing around with this feature across multiple tabs and at some point it was not easy to navigate. To be very fair though this usage pattern is probably a corner case that doesn't matter that much 🙂

gribnoysup · 2025-08-18T16:17:11Z

packages/compass-explain-plan/src/components/explain-plan-modal.tsx

+  const isAiAssistantEnabled = usePreference('enableAIAssistant');
+  const { interpretExplainPlan } = useAssistantActions();


Might be a silly idea, but I wonder if we will almost always have these two together, maybe worth "re-exporting" the enabled prop as part of the useAssistant hook return value

gribnoysup · 2025-08-19T07:12:43Z

packages/compass-explain-plan/src/components/explain-plan-modal.tsx

+            <Button
+              size="small"
+              variant="default"
+              leftGlyph={
+                // TODO(COMPASS-9384): Will be replaced with Sparkle gradient icon once Leafygreen components are updated.
+                <Icon glyph="Sparkle" style={{ color: palette.green.dark1 }} />
+              }
+              data-testid="interpret-for-me-button"
+              onClick={() => {
+                onModalClose();
+                interpretExplainPlan(JSON.stringify(explainPlan));
+              }}
+            >
+              Interpret for me
+            </Button>


This button should be disabled / hidden while we're still running the explain, otherwise you're going to be explaining no plan

lerouxb · 2025-08-20T10:26:02Z

packages/compass-assistant/src/prompts.ts

+}) => {
+  return {
+    prompt: `Given the MongoDB explain plan output below, provide a concise human readable explanation that explains the query execution plan and highlights aspects of the plan that might impact query performance. Respond with as much concision and clarity as possible.
+If a clear optimization should be made, please suggest the optimization and describe how it can be accomplished in MongoDB Compass. Do not advise users to create indexes without weighing the pros and cons. 


I'm so skeptical about this 😆

packages/compass-explain-plan/src/components/explain-plan-modal.spec.tsx

lerouxb · 2025-08-20T11:30:56Z

Tested it locally and it works great!

Copilot AI review requested due to automatic review settings August 18, 2025 13:13

gagik requested a review from a team as a code owner August 18, 2025 13:13

gagik force-pushed the gagik/ai-entry-point branch 2 times, most recently from a0b2adf to 58624e8 Compare August 18, 2025 13:18

gagik commented Aug 18, 2025

View reviewed changes

Copilot AI reviewed Aug 18, 2025

View reviewed changes

gribnoysup reviewed Aug 19, 2025

View reviewed changes

gagik added 4 commits August 19, 2025 10:35

chore(compass-assistant): add explain plan entry point COMPASS-9606

261bfbc

chore: minor icon adjustment

efc4c44

fix: cleaner test

8ac11d5

chore: fix test, combine preference to hook

0e82ba8

gagik force-pushed the gagik/ai-entry-point branch from 87fd0ae to 0e82ba8 Compare August 19, 2025 08:35

gagik added 5 commits August 19, 2025 12:01

chore: fix test, combine preference to hook

b6bb19f

chore: make the namespace bold

d030b3d

chore: add props for explainplan

8c1436e

chore: remove namespace, update text

54dd010

chore: fix check

8831559

lerouxb reviewed Aug 20, 2025

View reviewed changes

packages/compass-explain-plan/src/components/explain-plan-modal.spec.tsx Show resolved Hide resolved

lerouxb approved these changes Aug 20, 2025

View reviewed changes

chore: add aria-disabled assertion

bc1906e

gagik merged commit dc1c477 into main Aug 20, 2025
54 of 58 checks passed

gagik deleted the gagik/ai-entry-point branch August 20, 2025 13:04

		const isAiAssistantEnabled = usePreference('enableAIAssistant');
		const { interpretExplainPlan } = useAssistantActions();

chore(compass-assistant): add explain plan entry point COMPASS-9606 #7208

chore(compass-assistant): add explain plan entry point COMPASS-9606 #7208

Uh oh!

Conversation

gagik commented Aug 18, 2025

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull Request Overview

Reviewed Changes

Uh oh!

Copilot AI Aug 18, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Copilot AI Aug 18, 2025

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

gagik Aug 19, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

lerouxb commented Aug 20, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

gagik Aug 19, 2025 •

edited

Loading