fix(aggregations): $rerank bug bash changes COMPASS-10696

packages/atlas-service/src/url-builders.spec.ts

@@ -73,6 +73,17 @@ describe('url-builders', function () {
         `${TEST_ORIGIN}/v2/proj123#/settings/groupSettings`
       );
     });
+
+    it('builds project settings url with highlight param', function () {
+      expect(
+        buildProjectSettingsUrl({
+          projectId: 'proj123',
+          highlight: 'nativeReranking',
+        })
+      ).to.equal(
+        `${TEST_ORIGIN}/v2/proj123#/settings/groupSettings?highlight=nativeReranking`
+      );
+    });
   });
 
   describe('buildMonitoringUrl', function () {

packages/atlas-service/src/url-builders.ts

@@ -16,9 +16,13 @@ export function buildPerformanceMetricsUrl({
 
 export function buildProjectSettingsUrl({
   projectId,
-}: Pick<AtlasClusterMetadata, 'projectId'>): string {
+  highlight,
+}: Pick<AtlasClusterMetadata, 'projectId'> & { highlight?: string }): string {
   const url = new URL(`/v2/${projectId}`, window.location.origin);
-  return `${url}#/settings/groupSettings`;
+  const hash = highlight
+    ? `/settings/groupSettings?highlight=${encodeURIComponent(highlight)}`
+    : `/settings/groupSettings`;
+  return `${url}#${hash}`;
 }
 
 export function buildMonitoringUrl({

packages/compass-aggregations/src/components/banner-button-styles.ts

@@ -0,0 +1,14 @@
+import { css } from '@mongodb-js/compass-components';
+
+// Shared styling for action buttons rendered inside banners. Keeps the label
+// contained on a single line within the button, and removes the underline that
+// the Banner applies to descendant anchors (a Button with an `href` renders as
+// an `<a>`). The `:any-link` selector is needed to outweigh the Banner's own
+// `a` rule.
+export const bannerButtonStyles = css({
+  flexShrink: 0,
+  whiteSpace: 'nowrap',
+  '&:any-link': {
+    textDecorationLine: 'none',
+  },
+});

packages/compass-aggregations/src/components/focus-mode/focus-mode-modal-header.tsx

@@ -3,6 +3,7 @@ import {
   Button,
   css,
   Icon,
+  Link,
   Menu,
   MenuItem,
   Option,
@@ -35,6 +36,8 @@ import {
 import type { ServerEnvironment } from '../../modules/env';
 import { getIsRerankFirstStage } from '../../modules/pipeline-builder/builder-helpers';
 import { useRerankInsight } from '../rerank-first-stage-banner';
+import { useConnectionInfo } from '@mongodb-js/compass-connections/provider';
+import { buildRerankTokenUsageUrl } from '@mongodb-js/atlas-service/provider';
 
 type Stage = {
   idxInStore: number;
@@ -119,6 +122,15 @@ export const FocusModeModalHeader: React.FunctionComponent<
 }) => {
   const [menuOpen, setMenuOpen] = useState(false);
   const showInsights = usePreference('showInsights');
+  const enableRerank = usePreference('enableRerank');
+  const { atlasMetadata } = useConnectionInfo();
+
+  const viewTokenUsageHref =
+    enableRerank && stage?.stageOperator === '$rerank'
+      ? atlasMetadata
+        ? buildRerankTokenUsageUrl(atlasMetadata)
+        : 'https://dochub.mongodb.org/core/$rerank#metrics'
+      : null;
 
   const performanceInsight = useMemo(() => {
     if (stage) {
@@ -354,6 +366,16 @@ export const FocusModeModalHeader: React.FunctionComponent<
         </Menu>
       </div>
 
+      {viewTokenUsageHref && (
+        <Link
+          href={viewTokenUsageHref}
+          target="_blank"
+          data-testid="focus-mode-view-token-usage-link"
+        >
+          View token usage
+        </Link>
+      )}
+
       {showInsights && insight && (
         <SignalPopover
           signals={insight}

packages/compass-aggregations/src/components/rerank-first-stage-banner.tsx

@@ -14,6 +14,7 @@ import { useAssistantActions } from '@mongodb-js/compass-assistant';
 import { useConnectionInfo } from '@mongodb-js/compass-connections/provider';
 import { buildAtlasSearchClustersUrl } from '@mongodb-js/atlas-service/provider';
 import { STAGE_HELP_BASE_URL } from '../constants';
+import { bannerButtonStyles } from './banner-button-styles';
 
 export const useRerankInsightAction = () => {
   const { tellMoreAboutInsight } = useAssistantActions();
@@ -132,19 +133,14 @@ const bannerContentStyles = css({
   display: 'flex',
   justifyContent: 'space-between',
   alignItems: 'flex-end',
+  gap: spacing[200],
 });
 
 const bannerTextStyles = css({
   flex: 1,
   minWidth: 0,
 });
 
-const bannerButtonStyles = css({
-  flexShrink: 0,
-  whiteSpace: 'nowrap',
-  marginLeft: spacing[200],
-});
-
 export const RerankFirstStageBanner = ({
   'data-testid': dataTestId,
 }: {

packages/compass-aggregations/src/components/rerank-tokens-banner.tsx

@@ -1,6 +1,16 @@
 import React from 'react';
-import { Banner, css, usePersistedState } from '@mongodb-js/compass-components';
+import {
+  Banner,
+  Button,
+  Icon,
+  css,
+  spacing,
+  usePersistedState,
+} from '@mongodb-js/compass-components';
 import { usePreference } from 'compass-preferences-model/provider';
+import { useConnectionInfo } from '@mongodb-js/compass-connections/provider';
+import { buildRerankTokenUsageUrl } from '@mongodb-js/atlas-service/provider';
+import { bannerButtonStyles } from './banner-button-styles';
 
 const bannerStyles = css({
   borderRadius: 0,
@@ -10,12 +20,19 @@ const bannerStyles = css({
   },
 });
 
+const bannerContentStyles = css({
+  display: 'flex',
+  alignItems: 'center',
+  gap: spacing[200],
+});
+
 export const RerankTokensBanner = ({
   'data-testid': dataTestId,
 }: {
   'data-testid'?: string;
 }) => {
   const enableRerank = usePreference('enableRerank');
+  const { atlasMetadata } = useConnectionInfo();
   const [isDismissed, setIsDismissed] = usePersistedState(
     'mongodb_compass_dismissed_rerank_tokens_banner',
     false
@@ -25,6 +42,10 @@ export const RerankTokensBanner = ({
     return null;
   }
 
+  const viewTokenUsageHref = atlasMetadata
+    ? buildRerankTokenUsageUrl(atlasMetadata)
+    : 'https://dochub.mongodb.org/core/$rerank#metrics';
+
   return (
     <Banner
       variant="info"
@@ -35,8 +56,21 @@ export const RerankTokensBanner = ({
     >
       <strong>$rerank consumes tokens</strong>
       <br />
-      Turn off the preview or disable the stage to avoid running $rerank while
-      editing.
+      <div className={bannerContentStyles}>
+        <span>
+          Turn off the preview or disable the stage to avoid running $rerank
+          while editing.
+        </span>
+        <Button
+          size="xsmall"
+          href={viewTokenUsageHref}
+          target="_blank"
+          rightGlyph={<Icon glyph="OpenNewTab" />}
+          className={bannerButtonStyles}
+        >
+          View token usage
+        </Button>
+      </div>
     </Banner>
   );
 };

packages/compass-aggregations/src/components/rerank-version-warning-banner.tsx

@@ -9,6 +9,7 @@ import {
 import { useConnectionInfo } from '@mongodb-js/compass-connections/provider';
 import { buildUpgradeClusterUrl } from '@mongodb-js/atlas-service/provider';
 import { RERANK_MIN_SERVER_VERSION } from '../utils/search-stage-errors';
+import { bannerButtonStyles } from './banner-button-styles';
 
 const bannerContentStyles = css({
   display: 'flex',
@@ -18,11 +19,6 @@ const bannerContentStyles = css({
   flexWrap: 'nowrap',
 });
 
-const bannerButtonStyles = css({
-  flexShrink: 0,
-  whiteSpace: 'nowrap',
-});
-
 export const RerankVersionWarningBanner = ({
   'data-testid': dataTestId,
 }: {

packages/compass-aggregations/src/components/server-error-banner.tsx

@@ -6,6 +6,7 @@ import {
   Icon,
   Link,
   css,
+  spacing,
   useDrawerActions,
 } from '@mongodb-js/compass-components';
 import {
@@ -21,16 +22,19 @@ import {
   type SearchExtensionType,
 } from '../utils/search-stage-errors';
 import RateLimitExceededBanner from './rate-limit-exceeded-banner';
+import { bannerButtonStyles } from './banner-button-styles';
+
+const RERANK_DOCS_URL =
+  'https://www.mongodb.com/docs/vector-search/query/aggregation-stages/rerank/#navigate-to-the-project-settings-page';
 
 const bannerStyles = css({
   textAlign: 'left',
 });
 
 const bannerContentStyles = css({
   display: 'flex',
-  justifyContent: 'space-between',
   alignItems: 'center',
-  width: '100%',
+  gap: spacing[200],
 });
 
 type ServerErrorBannerProps = {
@@ -53,13 +57,14 @@ export default function ServerErrorBanner({
   const track = useTelemetry();
   const { atlasMetadata } = useConnectionInfo();
   const rerankNotEnabled = isRerankNotEnabledError(message);
-  const description = rerankNotEnabled
-    ? 'Enable native reranking in project settings.'
-    : message;
-  const projectSettingsHref =
-    rerankNotEnabled && atlasMetadata
-      ? buildProjectSettingsUrl({ projectId: atlasMetadata.projectId })
-      : null;
+  const projectSettingsHref = rerankNotEnabled
+    ? atlasMetadata
+      ? buildProjectSettingsUrl({
+          projectId: atlasMetadata.projectId,
+          highlight: 'nativeReranking',
+        })
+      : RERANK_DOCS_URL
+    : null;
 
   const rateLimitInfo = getVoyageProjectRateLimitInfo(message);
   if (rateLimitInfo) {
@@ -79,13 +84,14 @@ export default function ServerErrorBanner({
           <strong>Native reranking not enabled</strong>
           <br />
           <div className={bannerContentStyles}>
-            <span>{description}</span>
+            <span>Enable native reranking in project settings.</span>
             {projectSettingsHref && (
               <Button
                 size="xsmall"
                 href={projectSettingsHref}
                 target="_blank"
                 rightGlyph={<Icon glyph="OpenNewTab" />}
+                className={bannerButtonStyles}
               >
                 Project Settings
               </Button>

packages/compass-assistant/src/prompts.ts

@@ -204,9 +204,17 @@ ${context.query}
       };
     case 'rerank-first-stage':
       return {
-        prompt: `Why you should use $rerank after a search stage`,
+        prompt: `The given MongoDB aggregation pipeline uses $rerank as the first stage. Provide a concise, human-readable explanation of best practices for using $rerank effectively and efficiently.
+Your explanation must cover the following points:
+
+- $rerank should follow an initial retrieval stage such as $vectorSearch or $search, and explain why.
+- Use $rerank.numDocsToRerank to limit how many documents are passed to the reranker, and explain the performance tradeoff of reranking more vs. fewer documents.
+- Only include fields in $rerank.path that are actually used for reranking — unnecessary fields increase payload size and latency without improving results.
+
+Where relevant, flag if the pipeline in question does not follow these practices.
+Respond with as much concision and clarity as possible. Do not recommend changes without briefly explaining the tradeoff.`,
         metadata: {
-          displayText: 'Why you should use $rerank after a search stage',
+          displayText: 'What are best practices for using $rerank?',
         },
       };
   }