change(knowledge): make vector the default search mode, hybrid opt-in

Every existing caller — workflow block, v1 API, copilot, guardrail RAG — keeps
its current ranking. Hybrid retrieval is now requested explicitly via
`searchMode: 'hybrid'`.

Also routes the copilot knowledge tool through the shared
`executeKnowledgeSearch` dispatch so all four callers share one retrieval path,
and documents `searchMode` on the public v1 search endpoint in the OpenAPI spec.

Author: waleedlatif1

apps/docs/openapi.json

@@ -6040,7 +6040,7 @@
       "post": {
         "operationId": "searchKnowledgeBase",
         "summary": "Search Knowledge Base",
-        "description": "Perform vector similarity search across one or more knowledge bases. Supports semantic search via query text, tag-based filtering, or a combination of both.",
+        "description": "Search across one or more knowledge bases. Supports semantic search via query text, tag-based filtering, or a combination of both. Set `searchMode` to `hybrid` to additionally run a full-text keyword leg and fuse it with the semantic results.",
         "tags": ["Knowledge Bases"],
         "x-codeSamples": [
           {
@@ -6095,14 +6095,21 @@
                     "items": {
                       "$ref": "#/components/schemas/TagFilter"
                     }
+                  },
+                  "searchMode": {
+                    "type": "string",
+                    "enum": ["vector", "hybrid"],
+                    "default": "vector",
+                    "description": "Retrieval strategy. `vector` ranks purely on embedding similarity. `hybrid` also runs a full-text keyword search and fuses the two rankings by reciprocal rank, which retrieves exact tokens — error codes, ticket keys, identifiers, rare product names — that embeddings alone rank poorly. Ignored when only tagFilters are provided."
                   }
                 }
               },
               "example": {
                 "workspaceId": "wsp_abc123",
                 "knowledgeBaseIds": ["d2c8f4a6-1b3e-4c5d-9e7f-8a0b2c4d6e1f"],
                 "query": "How do I reset my password?",
-                "topK": 5
+                "topK": 5,
+                "searchMode": "hybrid"
               }
             }
           }

apps/sim/app/api/knowledge/search/route.test.ts

@@ -22,13 +22,11 @@ import { afterAll, afterEach, beforeEach, describe, expect, it, vi } from 'vites
 const {
   mockGetDocumentTagDefinitions,
   mockExecuteKnowledgeSearch,
-  mockGetQueryStrategy,
   mockGenerateSearchEmbedding,
   mockGetDocumentMetadataByIds,
 } = vi.hoisted(() => ({
   mockGetDocumentTagDefinitions: vi.fn(),
   mockExecuteKnowledgeSearch: vi.fn(),
-  mockGetQueryStrategy: vi.fn(),
   mockGenerateSearchEmbedding: vi.fn(),
   mockGetDocumentMetadataByIds: vi.fn(),
 }))
@@ -66,7 +64,6 @@ vi.mock('@/lib/knowledge/tags/service', () => ({
 
 vi.mock('./utils', () => ({
   executeKnowledgeSearch: mockExecuteKnowledgeSearch,
-  getQueryStrategy: mockGetQueryStrategy,
   generateSearchEmbedding: mockGenerateSearchEmbedding,
   getDocumentMetadataByIds: mockGetDocumentMetadataByIds,
   APIError: class APIError extends Error {
@@ -113,12 +110,6 @@ describe('Knowledge Search API Route', () => {
     setEnv({ OPENAI_API_KEY: 'test-api-key' })
 
     mockExecuteKnowledgeSearch.mockClear()
-    mockGetQueryStrategy.mockClear().mockReturnValue({
-      useParallel: false,
-      distanceThreshold: 1.0,
-      parallelLimit: 15,
-      singleQueryOptimized: true,
-    })
     mockGenerateSearchEmbedding
       .mockClear()
       .mockResolvedValue({ embedding: [0.1, 0.2, 0.3, 0.4, 0.5], isBYOK: false })
@@ -207,14 +198,14 @@ describe('Knowledge Search API Route', () => {
       expect(mockExecuteKnowledgeSearch).toHaveBeenCalledWith({
         knowledgeBaseIds: ['kb-123'],
         topK: 10,
-        searchMode: 'hybrid',
+        searchMode: 'vector',
         query: validSearchData.query,
         queryVector: JSON.stringify(mockEmbedding),
         structuredFilters: undefined,
       })
     })
 
-    it('should forward the searchMode opt-out to the retrieval layer', async () => {
+    it('should forward the hybrid searchMode opt-in to the retrieval layer', async () => {
       mockGetUserId.mockResolvedValue('user-123')
 
       mockCheckKnowledgeBaseAccess.mockResolvedValue({
@@ -239,12 +230,12 @@ describe('Knowledge Search API Route', () => {
           }),
       })
 
-      const req = createMockRequest('POST', { ...validSearchData, searchMode: 'vector' })
+      const req = createMockRequest('POST', { ...validSearchData, searchMode: 'hybrid' })
       const response = await POST(req)
 
       expect(response.status).toBe(200)
       expect(mockExecuteKnowledgeSearch).toHaveBeenCalledWith(
-        expect.objectContaining({ searchMode: 'vector' })
+        expect.objectContaining({ searchMode: 'hybrid' })
       )
     })
 
@@ -287,7 +278,7 @@ describe('Knowledge Search API Route', () => {
       expect(mockExecuteKnowledgeSearch).toHaveBeenCalledWith({
         knowledgeBaseIds: ['kb-123', 'kb-456'],
         topK: 10,
-        searchMode: 'hybrid',
+        searchMode: 'vector',
         query: multiKbData.query,
         queryVector: JSON.stringify(mockEmbedding),
         structuredFilters: undefined,
@@ -796,7 +787,7 @@ describe('Knowledge Search API Route', () => {
       expect(mockExecuteKnowledgeSearch).toHaveBeenCalledWith({
         knowledgeBaseIds: ['kb-123'],
         topK: 10,
-        searchMode: 'hybrid',
+        searchMode: 'vector',
         structuredFilters: [
           { tagSlot: 'tag1', fieldType: 'text', operator: 'eq', value: 'api', valueTo: undefined },
         ],
@@ -850,7 +841,7 @@ describe('Knowledge Search API Route', () => {
       expect(mockExecuteKnowledgeSearch).toHaveBeenCalledWith({
         knowledgeBaseIds: ['kb-123'],
         topK: 10,
-        searchMode: 'hybrid',
+        searchMode: 'vector',
         query: 'test search',
         queryVector: JSON.stringify(mockEmbedding),
         structuredFilters: [
@@ -1066,13 +1057,6 @@ describe('Knowledge Search API Route', () => {
         },
       ])
 
-      mockGetQueryStrategy.mockReturnValue({
-        useParallel: false,
-        distanceThreshold: 1.0,
-        parallelLimit: 15,
-        singleQueryOptimized: true,
-      })
-
       mockGenerateSearchEmbedding.mockResolvedValue({ embedding: [0.1, 0.2, 0.3], isBYOK: false })
       mockGetDocumentMetadataByIds.mockResolvedValue({
         'doc-active': {
@@ -1142,13 +1126,6 @@ describe('Knowledge Search API Route', () => {
         },
       ])
 
-      mockGetQueryStrategy.mockReturnValue({
-        useParallel: false,
-        distanceThreshold: 1.0,
-        parallelLimit: 15,
-        singleQueryOptimized: true,
-      })
-
       mockGetDocumentMetadataByIds.mockResolvedValue({
         'doc-active-tagged': { filename: 'Active Tagged Document.pdf', sourceUrl: null },
       })
@@ -1214,13 +1191,6 @@ describe('Knowledge Search API Route', () => {
         },
       ])
 
-      mockGetQueryStrategy.mockReturnValue({
-        useParallel: false,
-        distanceThreshold: 1.0,
-        parallelLimit: 15,
-        singleQueryOptimized: true,
-      })
-
       mockGenerateSearchEmbedding.mockResolvedValue({ embedding: [0.1, 0.2, 0.3], isBYOK: false })
       mockGetDocumentMetadataByIds.mockResolvedValue({
         'doc-active-combined': { filename: 'Active Combined Search.pdf', sourceUrl: null },

apps/sim/app/api/v1/knowledge/search/route.test.ts

@@ -13,7 +13,6 @@ import { beforeEach, describe, expect, it, vi } from 'vitest'
 
 const {
   mockExecuteKnowledgeSearch,
-  mockGetQueryStrategy,
   mockGenerateSearchEmbedding,
   mockGetDocumentMetadataByIds,
   mockAuthenticateRequest,
@@ -23,7 +22,6 @@ const {
   mockRecordSearchEmbeddingUsage,
 } = vi.hoisted(() => ({
   mockExecuteKnowledgeSearch: vi.fn(),
-  mockGetQueryStrategy: vi.fn(),
   mockGenerateSearchEmbedding: vi.fn(),
   mockGetDocumentMetadataByIds: vi.fn(),
   mockAuthenticateRequest: vi.fn(),
@@ -48,7 +46,6 @@ const SYSTEM_BILLING_ATTRIBUTION = {
 
 vi.mock('@/app/api/knowledge/search/utils', () => ({
   executeKnowledgeSearch: mockExecuteKnowledgeSearch,
-  getQueryStrategy: mockGetQueryStrategy,
   generateSearchEmbedding: mockGenerateSearchEmbedding,
   getDocumentMetadataByIds: mockGetDocumentMetadataByIds,
 }))
@@ -109,7 +106,6 @@ describe('v1 knowledge search route — per-KB embedding model', () => {
       rateLimit: {},
     })
     mockValidateWorkspaceAccess.mockResolvedValue(null)
-    mockGetQueryStrategy.mockReturnValue({ distanceThreshold: 0.5 })
     mockGenerateSearchEmbedding.mockResolvedValue({
       embedding: [0.1, 0.2, 0.3],
       isBYOK: false,

apps/sim/blocks/blocks/knowledge.ts

@@ -93,10 +93,10 @@ export const KnowledgeBlock: BlockConfig = {
       title: 'Retrieval Mode',
       type: 'dropdown',
       options: [
-        { label: 'Hybrid (full-text + vector)', id: 'hybrid' },
         { label: 'Vector only', id: 'vector' },
+        { label: 'Hybrid (full-text + vector)', id: 'hybrid' },
       ],
-      value: () => 'hybrid',
+      value: () => 'vector',
       mode: 'advanced',
       condition: { field: 'operation', value: 'search' },
     },
@@ -454,7 +454,7 @@ export const KnowledgeBlock: BlockConfig = {
     tagFilters: { type: 'string', description: 'Tag filter criteria' },
     searchMode: {
       type: 'string',
-      description: 'Retrieval mode: hybrid (full-text + vector) or vector only',
+      description: 'Retrieval mode: vector only (default) or hybrid (full-text + vector)',
     },
     rerankerEnabled: { type: 'boolean', description: 'Apply Cohere reranking to search results' },
     rerankerModel: { type: 'string', description: 'Cohere rerank model identifier' },

apps/sim/lib/api/contracts/knowledge/search.ts

@@ -10,15 +10,18 @@ export const knowledgeSearchTagFilterSchema = z.object({
   valueTo: z.union([z.string(), z.number()]).optional(),
 })
 
-export const KNOWLEDGE_SEARCH_MODES = ['hybrid', 'vector'] as const
+export const KNOWLEDGE_SEARCH_MODES = ['vector', 'hybrid'] as const
 
-/** Shared by the internal and v1 search contracts so both default to hybrid. */
+/**
+ * Shared by the internal and v1 search contracts. Defaults to `vector` so every
+ * existing caller keeps its current ranking; hybrid is opt-in.
+ */
 export const knowledgeSearchModeSchema = z
   .enum(KNOWLEDGE_SEARCH_MODES)
   .optional()
   .nullable()
-  .default('hybrid')
-  .transform((val) => val ?? 'hybrid')
+  .default('vector')
+  .transform((val) => val ?? 'vector')
 
 export const knowledgeSearchBodySchema = z
   .object({
@@ -45,9 +48,9 @@ export const knowledgeSearchBodySchema = z
       .nullable()
       .transform((val) => val || undefined),
     /**
-     * `hybrid` (default) fuses full-text and vector retrieval by reciprocal rank,
-     * which recovers exact tokens (error codes, ticket keys, identifiers) that
-     * embeddings alone rank poorly. `vector` opts out to semantic-only retrieval.
+     * `vector` (default) is semantic-only retrieval. `hybrid` additionally runs a
+     * full-text leg and fuses the two by reciprocal rank, which recovers exact
+     * tokens (error codes, ticket keys, identifiers) that embeddings rank poorly.
      */
     searchMode: knowledgeSearchModeSchema,
     rerankerEnabled: z.boolean().optional().default(false),

apps/sim/lib/api/contracts/v1/knowledge/index.ts

@@ -135,8 +135,8 @@ export const v1KnowledgeSearchBodySchema = z
     topK: z.number().min(1).max(100).default(10),
     tagFilters: z.array(v1SearchTagFilterSchema).optional(),
     /**
-     * `hybrid` (default) fuses full-text and vector retrieval by reciprocal rank;
-     * `vector` opts out to semantic-only retrieval.
+     * `vector` (default) is semantic-only retrieval; `hybrid` fuses a full-text
+     * leg with it by reciprocal rank.
      */
     searchMode: knowledgeSearchModeSchema,
   })

apps/sim/lib/copilot/tools/server/knowledge/knowledge-base.test.ts

@@ -74,8 +74,7 @@ vi.mock('@/lib/uploads/contexts/workspace/workspace-file-manager', () => ({
   resolveWorkspaceFileReference: vi.fn(),
 }))
 vi.mock('@/app/api/knowledge/search/utils', () => ({
-  getQueryStrategy: vi.fn(),
-  handleVectorOnlySearch: vi.fn(),
+  executeKnowledgeSearch: vi.fn(),
 }))
 vi.mock('@/app/api/knowledge/utils', () => ({
   checkDocumentWriteAccess: vi.fn(),

apps/sim/lib/copilot/tools/server/knowledge/knowledge-base.ts

@@ -50,7 +50,7 @@ import {
 } from '@/lib/knowledge/tags/service'
 import { StorageService } from '@/lib/uploads'
 import { resolveWorkspaceFileReference } from '@/lib/uploads/contexts/workspace/workspace-file-manager'
-import { getQueryStrategy, handleVectorOnlySearch } from '@/app/api/knowledge/search/utils'
+import { executeKnowledgeSearch } from '@/app/api/knowledge/search/utils'
 import {
   checkDocumentWriteAccess,
   checkKnowledgeBaseAccess,
@@ -264,13 +264,12 @@ export const knowledgeBaseServerTool: BaseServerTool<KnowledgeBaseArgs, Knowledg
             await generateSearchEmbedding(args.query, kb.embeddingModel, kb.workspaceId)
           const queryVector = JSON.stringify(queryEmbedding)
 
-          const strategy = getQueryStrategy(1, topK)
-
-          const results = await handleVectorOnlySearch({
+          const results = await executeKnowledgeSearch({
             knowledgeBaseIds: [args.knowledgeBaseId],
             topK,
+            searchMode: 'vector',
+            query: args.query,
             queryVector,
-            distanceThreshold: strategy.distanceThreshold,
           })
 
           await recordSearchEmbeddingUsage({

apps/sim/tools/knowledge/search.ts

@@ -47,7 +47,7 @@ export const knowledgeSearchTool: ToolConfig<any, KnowledgeSearchResponse> = {
       required: false,
       visibility: 'user-only',
       description:
-        "Retrieval mode: 'hybrid' (default) fuses full-text and vector search, 'vector' uses semantic similarity only",
+        "Retrieval mode: 'vector' (default) uses semantic similarity only, 'hybrid' also runs a full-text leg and fuses both",
     },
     rerankerEnabled: {
       type: 'boolean',
@@ -121,7 +121,7 @@ export const knowledgeSearchTool: ToolConfig<any, KnowledgeSearchResponse> = {
         query: params.query,
         topK: params.topK ? Math.max(1, Math.min(100, Number(params.topK))) : 10,
         ...(structuredFilters.length > 0 && { tagFilters: structuredFilters }),
-        ...(params.searchMode === 'vector' && { searchMode: 'vector' }),
+        ...(params.searchMode === 'hybrid' && { searchMode: 'hybrid' }),
         ...(rerankerEnabled && {
           rerankerEnabled: true,
           rerankerModel,