refactor: rename 'keywords' to 'searchTerms' for semantic clarity

Author: gorango

packages/ai-tool-retriever/README.md

@@ -16,7 +16,7 @@ This library provides a lean core and a set of optional providers, allowing you
 - **Pluggable Architecture**: Explicitly choose and provide your embedding model and vector store.
 - **Default Local Providers**: Start with `@xenova/transformers` and an in-memory vector store.
 - **Bring Your Own Tech**: Implement your own `EmbeddingProvider` and `ToolStore` interfaces to use external services.
-- **Keyword Enhanced**: Improve search accuracy by adding custom `keywords` to your tool definitions.
+- **Search Term Enhanced**: Improve search accuracy by adding custom `searchTerms` to your tool definitions.
 - **Explicit Tool Forcing**: Users can force tool inclusion with a simple `[toolName]` syntax in their query.
 - **Configurable Retrieval**: Fine-tune results with similarity thresholds and control behavior for missing tools.
 - **Idempotent Syncing**: Built-in content hashing utilities to efficiently sync tools with vector stores.
@@ -61,7 +61,7 @@ const allMyTools: ToolDefinition[] = [
 			description: "Fetches the weather for a given location.",
 			parameters: z.object({ city: z.string() }),
 		}),
-		keywords: ["forecast", "temperature", "climate", "rain", "sun"],
+		searchTerms: ["forecast", "temperature", "climate", "rain", "sun"],
 	},
 	{
 		name: "searchFinancialNews",
@@ -70,7 +70,7 @@ const allMyTools: ToolDefinition[] = [
 				"Searches for financial news articles about a company.",
 			parameters: z.object({ ticker: z.string() }),
 		}),
-		keywords: ["stocks", "market", "earnings", "sec filings", "investing"],
+		searchTerms: ["stocks", "market", "earnings", "sec filings", "investing"],
 	},
 ];
 
@@ -198,13 +198,13 @@ To use a different vector database, implement the `ToolStore` interface. The `sy
 
 > **Best Practice: Crafting Text for High-Quality Embeddings**
 >
-> The quality of the semantic search is highly dependent on the text used to generate the embedding for each tool. For best results, your `ToolStore`'s `sync` method should create a single, rich string that includes the tool's name, its detailed description, and any relevant keywords.
+> The quality of the semantic search is highly dependent on the text used to generate the embedding for each tool. For best results, your `ToolStore`'s `sync` method should create a single, rich string that includes the tool's name, its detailed description, and any relevant searchTerms.
 >
 > The default `InMemoryStore` uses the following format as its best practice, and replicating this pattern in your custom store will ensure you get great search accuracy:
 >
 > ```ts
 > const textToEmbed =
-> 	`${definition.name}: ${definition.tool.description}. Keywords: ${definition.keywords?.join(", ")}`.trim();
+> 	`${definition.name}: ${definition.tool.description}. Search Terms: ${definition.searchTerms?.join(", ")}`.trim();
 > ```
 
 For persistent stores (like Supabase or Pinecone), it's crucial to implement `sync` efficiently to avoid re-calculating embeddings for unchanged tools on every application restart. The library provides a `createToolContentHash` utility to help with this.
@@ -316,8 +316,8 @@ export class SupabaseStore implements ToolStore {
 			// Create the rich text for each tool to be embedded
 			const textsToEmbed = toolsToUpsert.map((t) => {
 				const description = t.tool.description || "";
-				const keywords = t.keywords?.join(", ") || "";
-				return `${t.name}: ${description}. Keywords: ${keywords}`.trim();
+				const searchTerms = t.searchTerms?.join(", ") || "";
+				return `${t.name}: ${description}. Search Terms: ${searchTerms}`.trim();
 			});
 
 			// Use the provided embedding provider to get embeddings

packages/ai-tool-retriever/package.json

@@ -1,7 +1,7 @@
 {
 	"name": "ai-tool-retriever",
 	"type": "module",
-	"version": "1.0.4",
+	"version": "1.1.0",
 	"description": "tool retriever for the ai-sdk lib",
 	"author": "gorango",
 	"license": "MIT",

packages/ai-tool-retriever/src/core/store.ts

@@ -11,7 +11,7 @@ export interface ToolWithMetadata {
 	 */
 	embedding: number[]
 	/**
-	 * A hash of the tool's content (description, keywords, etc.) to detect changes.
+	 * A hash of the tool's content (description, searchTerms, etc.) to detect changes.
 	 */
 	contentHash: string
 }

packages/ai-tool-retriever/src/core/types.ts

@@ -15,9 +15,9 @@ export interface ToolDefinition {
 	 */
 	tool: Tool<any, any>
 	/**
-	 * A list of keywords, synonyms, or example use cases.
+	 * A list of search terms, synonyms, or example use cases.
 	 * This text is combined with the tool's description to create
 	 * a richer embedding for semantic search.
 	 */
-	keywords?: string[]
+	searchTerms?: string[]
 }

packages/ai-tool-retriever/src/providers/store/in-memory.test.ts

@@ -8,12 +8,12 @@ import { InMemoryStore } from './in-memory'
 const toolADef: ToolDefinition = {
 	name: 'toolA',
 	tool: createTool({ description: 'Does A', inputSchema: z.object({}) }),
-	keywords: ['alpha', 'apple'],
+	searchTerms: ['alpha', 'apple'],
 }
 const toolBDef: ToolDefinition = {
 	name: 'toolB',
 	tool: createTool({ description: 'Does B', inputSchema: z.object({}) }),
-	keywords: ['bravo', 'banana'],
+	searchTerms: ['bravo', 'banana'],
 }
 const toolCDef: ToolDefinition = {
 	name: 'toolC',
@@ -121,19 +121,19 @@ describe('InMemoryStore', () => {
 		await store.sync([toolADef, toolBDef], mockEmbeddingProvider)
 		expect(mockEmbeddingProvider.getFloatEmbeddingsBatch).toHaveBeenCalledTimes(1)
 		expect(mockEmbeddingProvider.getFloatEmbeddingsBatch).toHaveBeenCalledWith([
-			'toolA: Does A. Keywords: alpha, apple',
-			'toolB: Does B. Keywords: banana, bravo',
+			'toolA: Does A. Search Terms: alpha, apple',
+			'toolB: Does B. Search Terms: banana, bravo',
 		])
 
 		vi.clearAllMocks()
 
-		const updatedToolADef = { ...toolADef, keywords: ['alpha', 'avocado'] } // Change toolA
+		const updatedToolADef = { ...toolADef, searchTerms: ['alpha', 'avocado'] } // Change toolA
 
 		// Second sync, should only re-embed the changed tool (toolA)
 		await store.sync([updatedToolADef, toolBDef], mockEmbeddingProvider)
 		expect(mockEmbeddingProvider.getFloatEmbeddingsBatch).toHaveBeenCalledTimes(1)
 		expect(mockEmbeddingProvider.getFloatEmbeddingsBatch).toHaveBeenCalledWith([
-			'toolA: Does A. Keywords: alpha, avocado',
+			'toolA: Does A. Search Terms: alpha, avocado',
 		])
 	})
 })

packages/ai-tool-retriever/src/providers/store/in-memory.ts

@@ -38,8 +38,8 @@ export class InMemoryStore implements ToolStore {
 		if (toolsToEmbed.length > 0) {
 			const textsToEmbed = toolsToEmbed.map((definition) => {
 				const description = definition.tool.description || ''
-				const keywords = definition.keywords?.join(', ') || ''
-				return `${definition.name}: ${description}. Keywords: ${keywords}`.trim()
+				const searchTerms = definition.searchTerms?.join(', ') || ''
+				return `${definition.name}: ${description}. Search Terms: ${searchTerms}`.trim()
 			})
 
 			const embeddings = await embeddingProvider.getFloatEmbeddingsBatch(textsToEmbed)

packages/ai-tool-retriever/src/utils/utils.test.ts

@@ -81,14 +81,14 @@ describe('createToolContentHash', () => {
 			description: 'A test tool',
 			inputSchema: z.object({ param: z.string() }),
 		}),
-		keywords: ['test', 'alpha'],
+		searchTerms: ['test', 'alpha'],
 	}
 
 	it('should be deterministic for the same tool definition', () => {
 		const hash1 = createToolContentHash(baseTool)
 		const hash2 = createToolContentHash(baseTool)
 		expect(hash1).toBe(hash2)
-		expect(hash1).toBe('9fcdb9d4de7269f1a936c267bb6eb8a54bf4f9999dea7117d5b8a652a49a8fce')
+		expect(hash1).toBe('dc843f3c4ed33aa68c4287504d5402eb5e55f215dca028f28e54e9fcaf0b7d3c')
 	})
 
 	it('should produce a different hash if the description changes', () => {
@@ -101,20 +101,20 @@ describe('createToolContentHash', () => {
 		expect(hash1).not.toBe(hash2)
 	})
 
-	it('should produce a different hash if keywords are added or changed', () => {
+	it('should produce a different hash if searchTerms are added or changed', () => {
 		const modifiedTool: ToolDefinition = {
 			...baseTool,
-			keywords: ['test', 'alpha', 'beta'],
+			searchTerms: ['test', 'alpha', 'beta'],
 		}
 		const hash1 = createToolContentHash(baseTool)
 		const hash2 = createToolContentHash(modifiedTool)
 		expect(hash1).not.toBe(hash2)
 	})
 
-	it('should produce the same hash regardless of keyword order', () => {
+	it('should produce the same hash regardless of search term order', () => {
 		const modifiedTool: ToolDefinition = {
 			...baseTool,
-			keywords: ['alpha', 'test'], // flipped order
+			searchTerms: ['alpha', 'test'], // flipped order
 		}
 		const hash1 = createToolContentHash(baseTool)
 		const hash2 = createToolContentHash(modifiedTool)

packages/ai-tool-retriever/src/utils/utils.ts

@@ -56,7 +56,7 @@ export function createToolContentHash(definition: ToolDefinition): string {
 		name: definition.name,
 		description: definition.tool.description,
 		parameters: definition.tool.inputSchema, // zod schema for the hash
-		keywords: definition.keywords?.sort(), // sort keywords for a stable hash
+		searchTerms: definition.searchTerms?.sort(), // sort searchTerms for a stable hash
 	})
 	return createHash('sha256').update(sourceText).digest('hex')
 }

packages/benchmark/src/search-scalability.ts

@@ -25,7 +25,7 @@ function createMockTools(count: number): ToolDefinition[] {
 			description: `This is mock tool #${i}`,
 			inputSchema: z.object({}),
 		}),
-		keywords: [randomBytes(4).toString('hex')],
+		searchTerms: [randomBytes(4).toString('hex')],
 	}))
 }
 

packages/benchmark/tsconfig.json

@@ -4,5 +4,5 @@
 		"rootDir": "src",
 		"outDir": "dist"
 	},
-	"include": ["./**/*.ts"]
+	"include": ["src/**/*.ts"]
 }