toolpick 0.1.0

package/README.md

@@ -0,0 +1,140 @@
+# toolpick
+
+Your agent has 30 tools. The model sees all of them on every step — tool definitions eat thousands of tokens, the model picks the wrong one, and you're paying for context it doesn't need.
+
+toolpick fixes this. It picks the right 5 tools per step so the model only sees what matters.
+
+## Install
+
+```bash
+npm install toolpick
+```
+
+## Usage
+
+```ts
+import { generateText } from "ai";
+import { openai } from "@ai-sdk/openai";
+import { createToolIndex } from "toolpick";
+
+const index = createToolIndex(allTools, {
+  embeddingModel: openai.embeddingModel("text-embedding-3-small"),
+});
+
+const result = await generateText({
+  model: openai("gpt-4o"),
+  tools: allTools,
+  prepareStep: index.prepareStep(),
+  prompt: "ship it to prod",
+  maxSteps: 10,
+});
+```
+
+Every step, toolpick selects the most relevant tools and sets `activeTools` automatically. The model only sees what it needs. All tools remain available for execution.
+
+Works with `generateText`, `streamText`, and `Experimental_Agent`.
+
+## How it works
+
+Pass an embedding model and toolpick indexes your tool names, descriptions, and parameters. On each step it runs a combined search — fast keyword matching plus semantic embeddings — and returns the best matches.
+
+If the model can't find a useful tool, the next step automatically pages to a fresh set it hasn't seen yet. Two misses in a row? All tools get exposed as a fallback. Your agent never gets stuck.
+
+If the embedding API goes down, it silently falls back to keyword-only search. No crashes.
+
+## LLM re-ranking
+
+For maximum accuracy, add a `rerankerModel`. The combined search fetches candidates, then a cheap LLM picks the best ones using reasoning — handling slang, abbreviations, and context that embeddings alone miss.
+
+```ts
+const index = createToolIndex(allTools, {
+  embeddingModel: openai.embeddingModel("text-embedding-3-small"),
+  rerankerModel: openai("gpt-4o-mini"),
+});
+```
+
+This takes accuracy from 84% to 100% on blind user queries. Cost: ~$0.0001 per step (gpt-4o-mini).
+
+### Description enrichment
+
+For an extra boost, `enrichDescriptions` expands your tool descriptions with synonyms and alternative phrasings at startup. This is a one-time LLM call during `warmUp()`:
+
+```ts
+const index = createToolIndex(allTools, {
+  embeddingModel: openai.embeddingModel("text-embedding-3-small"),
+  rerankerModel: openai("gpt-4o-mini"),
+  enrichDescriptions: true,
+});
+
+await index.warmUp();
+```
+
+## Model-driven discovery
+
+For agents that need to discover tools outside the current selection, expose the built-in search tool:
+
+```ts
+const result = await generateText({
+  model: openai("gpt-4o"),
+  tools: {
+    ...allTools,
+    search_tools: index.searchTool(),
+  },
+  prepareStep: index.prepareStep({ alwaysActive: ["search_tools"] }),
+  maxSteps: 10,
+  prompt: "find and use the right tool",
+});
+```
+
+The model can call `search_tools` to browse the full catalog and request specific tools be activated. This mirrors how Anthropic's tool search works — but for any model.
+
+## Caching
+
+Tool description embeddings are computed once at startup. Cache them to skip the API call on restarts:
+
+```ts
+import { createToolIndex, fileCache } from "toolpick";
+
+const index = createToolIndex(allTools, {
+  embeddingModel: openai.embeddingModel("text-embedding-3-small"),
+  embeddingCache: fileCache(".toolpick-cache.json"),
+});
+
+await index.warmUp();
+```
+
+## Accuracy
+
+Tested with 19 blind user queries — slang, vague language, no keyword overlap — against 30 real SaaS tools:
+
+| Strategy | Top-5 accuracy | Cost per query |
+|---|---|---|
+| Keyword only | 31% | Free |
+| Embeddings only | 79% | ~$0.00002 |
+| Combined (default) | 84% | ~$0.00002 |
+| **Combined + LLM re-ranking** | **100%** | **~$0.0001** |
+
+Queries like "ship it", "ping the team", "file a bug", "get the CI running", and "compress this photo" all resolve to the correct tool.
+
+## Options
+
+```ts
+const index = createToolIndex(tools, {
+  embeddingModel: model,          // enables combined search (recommended)
+  rerankerModel: model,           // LLM re-ranking for max accuracy
+  enrichDescriptions: true,       // expand descriptions with synonyms at warmUp
+  embeddingCache: fileCache(path), // persist embeddings to disk
+  strategy: "hybrid",             // force keyword-only (free, no API calls)
+});
+
+await index.select(query, {
+  maxTools: 5,                    // ceiling, not fixed count
+  adaptive: true,                 // cut early when scores drop off
+  alwaysActive: ["search_tools"], // always include these
+  threshold: 0.3,                 // minimum relevance score
+});
+```
+
+## License
+
+MIT

package/dist/cache.d.ts

@@ -0,0 +1,17 @@
+import type { EmbeddingCacheOptions } from "./search/types";
+/**
+ * File-based embedding cache. Saves/loads tool embeddings as JSON
+ * so they survive restarts without re-calling the embedding API.
+ *
+ * @example
+ * ```ts
+ * import { createToolIndex, fileCache } from "toolpick";
+ *
+ * const index = createToolIndex(tools, {
+ *   embeddingModel: openai.embeddingModel("text-embedding-3-small"),
+ *   embeddingCache: fileCache(".toolpick-cache.json"),
+ * });
+ * await index.warmUp();
+ * ```
+ */
+export declare function fileCache(path: string): EmbeddingCacheOptions;

package/dist/cache.js

@@ -0,0 +1,38 @@
+import { readFile, writeFile, mkdir } from "node:fs/promises";
+import { dirname } from "node:path";
+/**
+ * File-based embedding cache. Saves/loads tool embeddings as JSON
+ * so they survive restarts without re-calling the embedding API.
+ *
+ * @example
+ * ```ts
+ * import { createToolIndex, fileCache } from "toolpick";
+ *
+ * const index = createToolIndex(tools, {
+ *   embeddingModel: openai.embeddingModel("text-embedding-3-small"),
+ *   embeddingCache: fileCache(".toolpick-cache.json"),
+ * });
+ * await index.warmUp();
+ * ```
+ */
+export function fileCache(path) {
+    return {
+        async load() {
+            try {
+                const data = await readFile(path, "utf-8");
+                const parsed = JSON.parse(data);
+                if (Array.isArray(parsed) && parsed.every(Array.isArray)) {
+                    return parsed;
+                }
+                return null;
+            }
+            catch {
+                return null;
+            }
+        },
+        async save(embeddings) {
+            await mkdir(dirname(path), { recursive: true });
+            await writeFile(path, JSON.stringify(embeddings), "utf-8");
+        },
+    };
+}

package/dist/eval/index.d.ts

@@ -0,0 +1,23 @@
+import type { ToolIndex } from "../tool-index";
+import type { EvalTestCase, EvalResult } from "../search/types";
+/**
+ * Evaluates a ToolIndex against test cases.
+ *
+ * Measures Top-1, Top-3, Top-5 accuracy and average latency.
+ * Returns misses for debugging.
+ *
+ * @example
+ * ```ts
+ * import { evalToolIndex } from "toolpick/eval";
+ *
+ * const result = evalToolIndex(index, [
+ *   { query: "create a ticket", expected: "createJiraTicket" },
+ *   { query: "send an email", expected: "sendEmail" },
+ * ]);
+ * console.log(`Top-1: ${result.top1}%, Top-3: ${result.top3}%`);
+ * ```
+ */
+export declare function evalToolIndex(index: ToolIndex, testCases: EvalTestCase[], options?: {
+    maxTools?: number;
+}): Promise<EvalResult>;
+export type { EvalTestCase, EvalResult } from "../search/types";

package/dist/eval/index.js

@@ -0,0 +1,59 @@
+/**
+ * Evaluates a ToolIndex against test cases.
+ *
+ * Measures Top-1, Top-3, Top-5 accuracy and average latency.
+ * Returns misses for debugging.
+ *
+ * @example
+ * ```ts
+ * import { evalToolIndex } from "toolpick/eval";
+ *
+ * const result = evalToolIndex(index, [
+ *   { query: "create a ticket", expected: "createJiraTicket" },
+ *   { query: "send an email", expected: "sendEmail" },
+ * ]);
+ * console.log(`Top-1: ${result.top1}%, Top-3: ${result.top3}%`);
+ * ```
+ */
+export async function evalToolIndex(index, testCases, options = {}) {
+    const { maxTools = 5 } = options;
+    let top1 = 0;
+    let top3 = 0;
+    let top5 = 0;
+    let totalLatency = 0;
+    const misses = [];
+    for (const tc of testCases) {
+        const start = performance.now();
+        const results = await index.select(tc.query, { maxTools: Math.max(maxTools, 5) });
+        const elapsed = performance.now() - start;
+        totalLatency += elapsed;
+        const accepted = new Set([tc.expected, ...(tc.alternatives ?? [])]);
+        const isHit = (slice) => slice.some((name) => accepted.has(name));
+        if (isHit(results.slice(0, 1)))
+            top1++;
+        if (isHit(results.slice(0, 3)))
+            top3++;
+        if (isHit(results.slice(0, 5)))
+            top5++;
+        if (!isHit(results.slice(0, 5))) {
+            misses.push({
+                query: tc.query,
+                expected: tc.expected,
+                got: results.slice(0, 5),
+            });
+        }
+    }
+    const total = testCases.length;
+    if (total === 0) {
+        return { top1: 0, top3: 0, top5: 0, avgLatencyMs: 0, total: 0, misses: [] };
+    }
+    const pct = (n) => Math.round((n / total) * 100);
+    return {
+        top1: pct(top1),
+        top3: pct(top3),
+        top5: pct(top5),
+        avgLatencyMs: Math.round(totalLatency / total * 100) / 100,
+        total,
+        misses,
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { createToolIndex } from "./tool-index";
+export type { ToolIndex } from "./tool-index";
+export type { SearchStrategy, SelectOptions, ToolIndexOptions, SearchResult, ToolDescription, EmbeddingCacheOptions, } from "./search/types";
+export { extractQuery } from "./query-extractor";
+export { fileCache } from "./cache";

package/dist/index.js

@@ -0,0 +1,3 @@
+export { createToolIndex } from "./tool-index";
+export { extractQuery } from "./query-extractor";
+export { fileCache } from "./cache";

package/dist/integrations/middleware.d.ts

@@ -0,0 +1,10 @@
+import type { LanguageModelMiddleware } from "ai";
+import type { SearchEngine, SelectOptions } from "../search/types";
+/**
+ * Creates a LanguageModelMiddleware that filters tools via transformParams.
+ *
+ * Secondary integration path. Operates at the provider level where the prompt
+ * is in internal format, making query extraction less precise than prepareStep.
+ * Best for single-step generateText/streamText calls.
+ */
+export declare function createMiddleware(engine: SearchEngine, toolNames: string[], options?: SelectOptions): LanguageModelMiddleware;

package/dist/integrations/middleware.js

@@ -0,0 +1,58 @@
+/**
+ * Creates a LanguageModelMiddleware that filters tools via transformParams.
+ *
+ * Secondary integration path. Operates at the provider level where the prompt
+ * is in internal format, making query extraction less precise than prepareStep.
+ * Best for single-step generateText/streamText calls.
+ */
+export function createMiddleware(engine, toolNames, options = {}) {
+    const { maxTools = 5, alwaysActive = [] } = options;
+    return {
+        specificationVersion: "v3",
+        transformParams: async ({ params }) => {
+            const query = extractQueryFromPrompt(params.prompt);
+            if (!query || !params.tools || params.tools.length === 0) {
+                return params;
+            }
+            const results = await engine.search(query, maxTools);
+            const selected = new Set([
+                ...results.map((r) => r.name),
+                ...alwaysActive,
+            ]);
+            const filteredTools = params.tools.filter((t) => {
+                const name = "name" in t ? t.name : undefined;
+                return name ? selected.has(name) : true;
+            });
+            return { ...params, tools: filteredTools };
+        },
+    };
+}
+/**
+ * Extracts user query from provider-level prompt format.
+ * This is messier than extracting from ModelMessage[] because
+ * the prompt is in LanguageModelV4Prompt format.
+ */
+function extractQueryFromPrompt(prompt) {
+    if (!Array.isArray(prompt))
+        return "";
+    for (let i = prompt.length - 1; i >= 0; i--) {
+        const msg = prompt[i];
+        if (msg && typeof msg === "object" && "role" in msg && msg.role === "user") {
+            if ("content" in msg) {
+                const content = msg.content;
+                if (typeof content === "string")
+                    return content;
+                if (Array.isArray(content)) {
+                    const texts = content
+                        .filter((p) => {
+                        return p && typeof p === "object" && "type" in p && p.type === "text";
+                    })
+                        .map((p) => p.text);
+                    if (texts.length > 0)
+                        return texts.join(" ");
+                }
+            }
+        }
+    }
+    return "";
+}

package/dist/integrations/prepare-step.d.ts

@@ -0,0 +1,12 @@
+import type { PrepareStepFunction, ToolSet } from "ai";
+import type { SearchEngine, SelectOptions } from "../search/types";
+/**
+ * Creates a prepareStep function that dynamically selects tools per step.
+ * Returns `{ activeTools }` to limit which tools the model sees.
+ *
+ * Includes automatic escalation: if the model produced no tool calls in the
+ * previous step, the next step shifts to the *next page* of ranked tools
+ * (positions maxTools+1 through maxTools*2) instead of repeating the same set.
+ * After two consecutive misses, all tools are exposed.
+ */
+export declare function createPrepareStep<TOOLS extends ToolSet>(engine: SearchEngine, toolNames: (keyof TOOLS & string)[], options?: SelectOptions): PrepareStepFunction<TOOLS>;

package/dist/integrations/prepare-step.js

@@ -0,0 +1,49 @@
+import { extractQuery } from "../query-extractor";
+function asActiveTools(names) {
+    return names;
+}
+/**
+ * Creates a prepareStep function that dynamically selects tools per step.
+ * Returns `{ activeTools }` to limit which tools the model sees.
+ *
+ * Includes automatic escalation: if the model produced no tool calls in the
+ * previous step, the next step shifts to the *next page* of ranked tools
+ * (positions maxTools+1 through maxTools*2) instead of repeating the same set.
+ * After two consecutive misses, all tools are exposed.
+ */
+export function createPrepareStep(engine, toolNames, options = {}) {
+    const { maxTools = 5, alwaysActive = [] } = options;
+    const toolNameSet = new Set(toolNames);
+    return async ({ messages, steps, stepNumber }) => {
+        const query = extractQuery(messages, steps, stepNumber);
+        if (!query) {
+            return alwaysActive.length > 0
+                ? { activeTools: asActiveTools(alwaysActive) }
+                : undefined;
+        }
+        let consecutiveFailures = 0;
+        if (stepNumber > 0 && steps.length > 0) {
+            for (let i = steps.length - 1; i >= 0; i--) {
+                if (steps[i].toolCalls.length === 0) {
+                    consecutiveFailures++;
+                }
+                else {
+                    break;
+                }
+            }
+        }
+        if (consecutiveFailures >= 2) {
+            const activeTools = [...new Set([...toolNames, ...alwaysActive])];
+            return { activeTools: asActiveTools(activeTools) };
+        }
+        const page = consecutiveFailures;
+        const windowSize = maxTools * (page + 1);
+        const results = await engine.search(query, windowSize);
+        const offset = page * maxTools;
+        const pageResults = results.slice(offset, offset + maxTools);
+        const selected = pageResults.map((r) => r.name);
+        const merged = [...new Set([...selected, ...alwaysActive])];
+        const activeTools = merged.filter((name) => toolNameSet.has(name));
+        return { activeTools: asActiveTools(activeTools) };
+    };
+}

package/dist/integrations/search-tool.d.ts

@@ -0,0 +1,18 @@
+import type { SearchEngine, ToolDescription } from "../search/types";
+/**
+ * Creates a meta-tool that agents can call to discover tools
+ * not in the current activeTools selection.
+ *
+ * When the agent can't find a tool it needs, it calls search_tools
+ * to discover relevant tools by name and description.
+ */
+export declare function createSearchTool(engine: SearchEngine, toolDescriptions: ToolDescription[]): import("ai").Tool<{
+    query: string;
+}, {
+    tools: {
+        name: string;
+        description: string;
+        relevance: number;
+    }[];
+    hint: string;
+}>;

package/dist/integrations/search-tool.js

@@ -0,0 +1,32 @@
+import { tool, zodSchema } from "ai";
+import { z } from "zod";
+const SEARCH_RESULTS = 5;
+/**
+ * Creates a meta-tool that agents can call to discover tools
+ * not in the current activeTools selection.
+ *
+ * When the agent can't find a tool it needs, it calls search_tools
+ * to discover relevant tools by name and description.
+ */
+export function createSearchTool(engine, toolDescriptions) {
+    const descriptionMap = new Map(toolDescriptions.map((t) => [t.name, t.text]));
+    return tool({
+        description: "Search for available tools by describing what you need. " +
+            "Use this when you need a capability that isn't in your current tools.",
+        inputSchema: zodSchema(z.object({
+            query: z.string().describe("Natural language description of the tool you need"),
+        })),
+        execute: async ({ query }) => {
+            const results = await engine.search(query, SEARCH_RESULTS);
+            const tools = results.map((r) => ({
+                name: r.name,
+                description: descriptionMap.get(r.name) ?? "",
+                relevance: Math.round(r.score * 100) / 100,
+            }));
+            return {
+                tools,
+                hint: "The tools listed above are available. Call the one that best matches your need.",
+            };
+        },
+    });
+}

package/dist/query-extractor.d.ts

@@ -0,0 +1,9 @@
+import type { ModelMessage, StepResult, ToolSet } from "ai";
+/**
+ * Extracts the best search query from conversation context for tool selection.
+ *
+ * - Step 0: uses the original user prompt
+ * - Step N with assistant text: uses the assistant's last text (contains next-action intent)
+ * - Step N without text: combines original prompt with completed tool names for context shift
+ */
+export declare function extractQuery<TOOLS extends ToolSet>(messages: ModelMessage[], steps: ReadonlyArray<StepResult<TOOLS>>, stepNumber: number): string;

package/dist/query-extractor.js

@@ -0,0 +1,44 @@
+/**
+ * Extracts the best search query from conversation context for tool selection.
+ *
+ * - Step 0: uses the original user prompt
+ * - Step N with assistant text: uses the assistant's last text (contains next-action intent)
+ * - Step N without text: combines original prompt with completed tool names for context shift
+ */
+export function extractQuery(messages, steps, stepNumber) {
+    if (stepNumber === 0 || steps.length === 0) {
+        return getLastUserMessage(messages);
+    }
+    const lastStep = steps[steps.length - 1];
+    // If the model produced text, it likely describes its next intent
+    // e.g. "Ticket created. Now I'll notify the team on Slack."
+    if (lastStep.text && lastStep.text.trim().length > 0) {
+        return lastStep.text;
+    }
+    // If only tool calls happened, combine original prompt with
+    // what already executed to shift context
+    if (lastStep.toolCalls.length > 0) {
+        const completedTools = lastStep.toolCalls.map((tc) => tc.toolName).join(" ");
+        const originalQuery = getLastUserMessage(messages);
+        return `${originalQuery} — ${completedTools}`;
+    }
+    return getLastUserMessage(messages);
+}
+function getLastUserMessage(messages) {
+    for (let i = messages.length - 1; i >= 0; i--) {
+        const msg = messages[i];
+        if (msg.role === "user") {
+            if (typeof msg.content === "string") {
+                return msg.content;
+            }
+            if (Array.isArray(msg.content)) {
+                const textParts = msg.content
+                    .filter((p) => p.type === "text")
+                    .map((p) => p.text);
+                if (textParts.length > 0)
+                    return textParts.join(" ");
+            }
+        }
+    }
+    return "";
+}

package/dist/reranker.d.ts

@@ -0,0 +1,13 @@
+import type { LanguageModel } from "ai";
+import type { SearchResult, ToolDescription } from "./search/types";
+/**
+ * Re-ranks tools using a cheap LLM. When there are <=50 tools,
+ * the LLM sees all of them (not just pre-filtered candidates).
+ * This adds reasoning that pure embedding similarity can't do.
+ */
+export declare function rerank(model: LanguageModel, query: string, candidates: SearchResult[], descriptions: Map<string, string>, maxResults: number): Promise<SearchResult[]>;
+/**
+ * Enriches tool descriptions with synonyms and common phrasings
+ * using a cheap LLM. Called once during warmUp, results are cached.
+ */
+export declare function enrichDescriptions(model: LanguageModel, descriptions: ToolDescription[]): Promise<ToolDescription[]>;

package/dist/reranker.js

@@ -0,0 +1,92 @@
+import { generateText, Output } from "ai";
+import { z } from "zod";
+const RERANK_TOOL_LIMIT = 50;
+/**
+ * Re-ranks tools using a cheap LLM. When there are <=50 tools,
+ * the LLM sees all of them (not just pre-filtered candidates).
+ * This adds reasoning that pure embedding similarity can't do.
+ */
+export async function rerank(model, query, candidates, descriptions, maxResults) {
+    if (candidates.length <= maxResults)
+        return candidates;
+    const allNames = Array.from(descriptions.keys());
+    const useFullSet = allNames.length <= RERANK_TOOL_LIMIT;
+    const toolList = useFullSet
+        ? allNames.map((n) => `- ${n}: ${descriptions.get(n) ?? ""}`).join("\n")
+        : candidates.map((c) => `- ${c.name}: ${descriptions.get(c.name) ?? ""}`).join("\n");
+    const validNames = new Set(useFullSet ? allNames : candidates.map((c) => c.name));
+    try {
+        const result = await generateText({
+            model,
+            output: Output.object({
+                schema: z.object({
+                    tools: z.array(z.string()).describe("Tool names ranked by relevance, most relevant first"),
+                }),
+            }),
+            prompt: `A user said: "${query}"
+
+This may be informal, slang, or abbreviated. Pick the ${maxResults} tools most likely to fulfill what the user actually wants, ranked best-first:
+
+${toolList}
+
+Return ONLY tool names from the list above. Think about what the user means, not just keyword matches.`,
+        });
+        const ranked = [];
+        const seen = new Set();
+        for (const name of result.output.tools) {
+            if (seen.has(name))
+                continue;
+            seen.add(name);
+            if (validNames.has(name)) {
+                ranked.push({ name, score: 1 - ranked.length * 0.1 });
+            }
+            if (ranked.length >= maxResults)
+                break;
+        }
+        return ranked;
+    }
+    catch (err) {
+        if (process.env.TOOLPICK_DEBUG) {
+            console.error("[toolpick rerank] LLM re-ranking failed, falling back to search results:", err);
+        }
+        return candidates.slice(0, maxResults);
+    }
+}
+/**
+ * Enriches tool descriptions with synonyms and common phrasings
+ * using a cheap LLM. Called once during warmUp, results are cached.
+ */
+export async function enrichDescriptions(model, descriptions) {
+    const toolList = descriptions
+        .map((d) => `- ${d.name}: ${d.text}`)
+        .join("\n");
+    try {
+        const result = await generateText({
+            model,
+            output: Output.object({
+                schema: z.object({
+                    tools: z.array(z.object({
+                        name: z.string(),
+                        text: z.string(),
+                    })),
+                }),
+            }),
+            prompt: `For each tool below, expand the description by adding common synonyms, slang, and alternative phrasings that users might say when they want this tool. Keep the original description and append the alternatives. Be concise — just add key synonyms, not full sentences.
+
+${toolList}
+
+Return every tool with its expanded description.`,
+        });
+        const enriched = new Map(result.output.tools.map((t) => [t.name, t.text]));
+        return descriptions.map((d) => ({
+            name: d.name,
+            text: enriched.get(d.name) ?? d.text,
+        }));
+    }
+    catch (err) {
+        if (process.env.TOOLPICK_DEBUG) {
+            console.error("[toolpick enrich] Description enrichment failed, using originals:", err);
+        }
+        return descriptions;
+    }
+}

package/dist/search/combined.d.ts

@@ -0,0 +1,9 @@
+import type { EmbeddingCacheOptions, SearchEngine, ToolDescription } from "./types";
+import type { EmbeddingModel } from "ai";
+export declare class CombinedSearch implements SearchEngine {
+    private hybrid;
+    private semantic;
+    constructor(tools: ToolDescription[], model: EmbeddingModel, cache?: EmbeddingCacheOptions);
+    init(): Promise<void>;
+    search(query: string, maxResults: number): Promise<import("./types").SearchResult[]>;
+}

package/dist/search/combined.js

@@ -0,0 +1,28 @@
+import { HybridSearch } from "./hybrid";
+import { SemanticSearch } from "./semantic";
+import { fuseResults } from "./fusion";
+const SEMANTIC_WEIGHT = 0.7;
+const HYBRID_WEIGHT = 0.3;
+export class CombinedSearch {
+    hybrid;
+    semantic;
+    constructor(tools, model, cache) {
+        this.hybrid = new HybridSearch(tools);
+        this.semantic = new SemanticSearch(tools, model, cache);
+    }
+    async init() {
+        await this.semantic.init();
+    }
+    async search(query, maxResults) {
+        try {
+            const [hybridResults, semanticResults] = await Promise.all([
+                this.hybrid.search(query, maxResults * 3),
+                this.semantic.search(query, maxResults * 3),
+            ]);
+            return fuseResults(hybridResults, semanticResults, HYBRID_WEIGHT, SEMANTIC_WEIGHT, maxResults);
+        }
+        catch {
+            return this.hybrid.search(query, maxResults);
+        }
+    }
+}

package/dist/search/fusion.d.ts

@@ -0,0 +1,7 @@
+import type { SearchResult } from "./types";
+/**
+ * Normalizes two scored result sets to [0,1] and fuses them
+ * with a weighted sum. Used by both HybridSearch (BM25 + TF-IDF)
+ * and CombinedSearch (hybrid + semantic).
+ */
+export declare function fuseResults(resultsA: SearchResult[], resultsB: SearchResult[], weightA: number, weightB: number, maxResults: number): SearchResult[];

package/dist/search/fusion.js

@@ -0,0 +1,26 @@
+/**
+ * Normalizes two scored result sets to [0,1] and fuses them
+ * with a weighted sum. Used by both HybridSearch (BM25 + TF-IDF)
+ * and CombinedSearch (hybrid + semantic).
+ */
+export function fuseResults(resultsA, resultsB, weightA, weightB, maxResults) {
+    const maxA = resultsA[0]?.score ?? 1;
+    const maxB = resultsB[0]?.score ?? 1;
+    const scoreMap = new Map();
+    for (const r of resultsA) {
+        const entry = scoreMap.get(r.name) ?? { a: 0, b: 0 };
+        entry.a = maxA > 0 ? r.score / maxA : 0;
+        scoreMap.set(r.name, entry);
+    }
+    for (const r of resultsB) {
+        const entry = scoreMap.get(r.name) ?? { a: 0, b: 0 };
+        entry.b = maxB > 0 ? r.score / maxB : 0;
+        scoreMap.set(r.name, entry);
+    }
+    const fused = [];
+    for (const [name, scores] of scoreMap) {
+        fused.push({ name, score: weightA * scores.a + weightB * scores.b });
+    }
+    fused.sort((a, b) => b.score - a.score);
+    return fused.slice(0, maxResults);
+}

package/dist/search/hybrid.d.ts

@@ -0,0 +1,7 @@
+import type { SearchEngine, SearchResult, ToolDescription } from "./types";
+export declare class HybridSearch implements SearchEngine {
+    private bm25;
+    private tfidf;
+    constructor(tools: ToolDescription[]);
+    search(query: string, maxResults: number): SearchResult[];
+}

package/dist/search/hybrid.js

@@ -0,0 +1,150 @@
+import { tokenize } from "../utils";
+import { fuseResults } from "./fusion";
+// ── BM25 ────────────────────────────────────────────────────────
+const BM25_K1 = 1.2;
+const BM25_B = 0.75;
+class BM25Index {
+    docs = [];
+    df = new Map();
+    avgDl = 0;
+    totalLength = 0;
+    n = 0;
+    add(name, text) {
+        const tokens = tokenize(text);
+        const tf = new Map();
+        for (const t of tokens) {
+            tf.set(t, (tf.get(t) ?? 0) + 1);
+        }
+        const seen = new Set(tokens);
+        for (const t of seen) {
+            this.df.set(t, (this.df.get(t) ?? 0) + 1);
+        }
+        this.docs.push({ name, tokens, length: tokens.length, tf });
+        this.n++;
+        this.totalLength += tokens.length;
+        this.avgDl = this.totalLength / this.n;
+    }
+    search(query, maxResults) {
+        const queryTokens = tokenize(query);
+        const scores = [];
+        for (const doc of this.docs) {
+            let score = 0;
+            for (const qt of queryTokens) {
+                const dfVal = this.df.get(qt) ?? 0;
+                const idf = Math.log(1 + (this.n - dfVal + 0.5) / (dfVal + 0.5));
+                const tfVal = doc.tf.get(qt) ?? 0;
+                const num = tfVal * (BM25_K1 + 1);
+                const denom = tfVal + BM25_K1 * (1 - BM25_B + BM25_B * (doc.length / this.avgDl));
+                score += idf * (num / denom);
+            }
+            if (score > 0) {
+                scores.push({ name: doc.name, score });
+            }
+        }
+        scores.sort((a, b) => b.score - a.score);
+        return scores.slice(0, maxResults);
+    }
+}
+// ── TF-IDF with cosine similarity ───────────────────────────────
+class TfidfIndex {
+    termToId = new Map();
+    nextTermId = 0;
+    docVectors = [];
+    df = new Map();
+    n = 0;
+    getTermId(term) {
+        let id = this.termToId.get(term);
+        if (id === undefined) {
+            id = this.nextTermId++;
+            this.termToId.set(term, id);
+        }
+        return id;
+    }
+    add(name, text) {
+        const tokens = tokenize(text);
+        const tf = new Map();
+        const seen = new Set();
+        for (const t of tokens) {
+            const id = this.getTermId(t);
+            tf.set(id, (tf.get(id) ?? 0) + 1);
+            if (!seen.has(id)) {
+                seen.add(id);
+                this.df.set(id, (this.df.get(id) ?? 0) + 1);
+            }
+        }
+        const vector = new Map();
+        const len = tokens.length || 1;
+        for (const [termId, count] of tf) {
+            vector.set(termId, count / len);
+        }
+        this.docVectors.push({ name, vector });
+        this.n++;
+    }
+    search(query, maxResults) {
+        const tokens = tokenize(query);
+        const queryTf = new Map();
+        for (const t of tokens) {
+            const id = this.termToId.get(t);
+            if (id !== undefined) {
+                queryTf.set(id, (queryTf.get(id) ?? 0) + 1);
+            }
+        }
+        if (queryTf.size === 0)
+            return [];
+        // Build query TF-IDF vector
+        const queryVector = new Map();
+        const qLen = tokens.length || 1;
+        for (const [termId, count] of queryTf) {
+            const dfVal = this.df.get(termId) ?? 0;
+            const idf = Math.log((this.n + 1) / (dfVal + 1)) + 1;
+            queryVector.set(termId, (count / qLen) * idf);
+        }
+        const scores = [];
+        for (const doc of this.docVectors) {
+            // Apply IDF to doc vector on the fly and compute cosine similarity
+            let dot = 0;
+            let docMag = 0;
+            for (const [termId, tfVal] of doc.vector) {
+                const dfVal = this.df.get(termId) ?? 0;
+                const idf = Math.log((this.n + 1) / (dfVal + 1)) + 1;
+                const tfidf = tfVal * idf;
+                docMag += tfidf * tfidf;
+                const qVal = queryVector.get(termId);
+                if (qVal !== undefined) {
+                    dot += tfidf * qVal;
+                }
+            }
+            if (dot <= 0)
+                continue;
+            let queryMag = 0;
+            for (const v of queryVector.values()) {
+                queryMag += v * v;
+            }
+            const magnitude = Math.sqrt(docMag) * Math.sqrt(queryMag);
+            if (magnitude === 0)
+                continue;
+            scores.push({ name: doc.name, score: dot / magnitude });
+        }
+        scores.sort((a, b) => b.score - a.score);
+        return scores.slice(0, maxResults);
+    }
+}
+// ── Hybrid (BM25 + TF-IDF) ─────────────────────────────────────
+const HYBRID_ALPHA = 0.2; // 20% BM25, 80% TF-IDF
+const NAME_BOOST_REPEAT = 3;
+export class HybridSearch {
+    bm25 = new BM25Index();
+    tfidf = new TfidfIndex();
+    constructor(tools) {
+        for (const t of tools) {
+            const boosted = `${Array(NAME_BOOST_REPEAT).fill(t.name).join(" ")} ${t.text}`;
+            this.bm25.add(t.name, boosted);
+            this.tfidf.add(t.name, boosted);
+        }
+    }
+    search(query, maxResults) {
+        const bm25Results = this.bm25.search(query, maxResults * 3);
+        const tfidfResults = this.tfidf.search(query, maxResults * 3);
+        return fuseResults(bm25Results, tfidfResults, HYBRID_ALPHA, 1 - HYBRID_ALPHA, maxResults);
+    }
+}

package/dist/search/semantic.d.ts

@@ -0,0 +1,13 @@
+import type { EmbeddingModel } from "ai";
+import type { EmbeddingCacheOptions, SearchEngine, SearchResult, ToolDescription } from "./types";
+export declare class SemanticSearch implements SearchEngine {
+    private tools;
+    private embeddings;
+    private toolNames;
+    private model;
+    private cache?;
+    private initPromise;
+    constructor(tools: ToolDescription[], model: EmbeddingModel, cache?: EmbeddingCacheOptions);
+    init(): Promise<void>;
+    search(query: string, maxResults: number): Promise<SearchResult[]>;
+}

package/dist/search/semantic.js

@@ -0,0 +1,55 @@
+import { embed, embedMany, cosineSimilarity } from "ai";
+export class SemanticSearch {
+    tools;
+    embeddings = [];
+    toolNames = [];
+    model;
+    cache;
+    initPromise = null;
+    constructor(tools, model, cache) {
+        this.tools = tools;
+        this.model = model;
+        this.cache = cache;
+        this.toolNames = tools.map((t) => t.name);
+    }
+    async init() {
+        if (this.initPromise)
+            return this.initPromise;
+        this.initPromise = (async () => {
+            if (this.cache) {
+                const cached = await this.cache.load();
+                if (cached && cached.length === this.tools.length) {
+                    this.embeddings = cached;
+                    return;
+                }
+            }
+            const values = this.tools.map((t) => `${t.name}: ${t.text}`);
+            const { embeddings } = await embedMany({
+                model: this.model,
+                values,
+            });
+            this.embeddings = embeddings;
+            if (this.cache) {
+                await this.cache.save(embeddings);
+            }
+        })().catch((err) => {
+            this.initPromise = null;
+            throw err;
+        });
+        return this.initPromise;
+    }
+    async search(query, maxResults) {
+        await this.init();
+        const { embedding: queryEmbedding } = await embed({
+            model: this.model,
+            value: query,
+        });
+        const scores = [];
+        for (let i = 0; i < this.embeddings.length; i++) {
+            const score = cosineSimilarity(queryEmbedding, this.embeddings[i]);
+            scores.push({ name: this.toolNames[i], score });
+        }
+        scores.sort((a, b) => b.score - a.score);
+        return scores.slice(0, maxResults);
+    }
+}

package/dist/search/types.d.ts

@@ -0,0 +1,49 @@
+import type { EmbeddingModel, LanguageModel } from "ai";
+export type SearchStrategy = "hybrid" | "semantic" | "combined";
+export interface SelectOptions {
+    maxTools?: number;
+    alwaysActive?: string[];
+    threshold?: number;
+    /** When true, returns fewer than maxTools if there's a large score gap. Default: true */
+    adaptive?: boolean;
+}
+export interface SearchResult {
+    name: string;
+    score: number;
+}
+export interface SearchEngine {
+    search(query: string, maxResults: number): SearchResult[] | Promise<SearchResult[]>;
+    init?(): Promise<void>;
+}
+export interface EmbeddingCacheOptions {
+    load(): Promise<number[][] | null>;
+    save(embeddings: number[][]): Promise<void>;
+}
+export interface ToolIndexOptions {
+    strategy?: SearchStrategy;
+    embeddingModel?: EmbeddingModel;
+    embeddingCache?: EmbeddingCacheOptions;
+    rerankerModel?: LanguageModel;
+    enrichDescriptions?: boolean;
+}
+export interface ToolDescription {
+    name: string;
+    text: string;
+}
+export interface EvalTestCase {
+    query: string;
+    expected: string;
+    alternatives?: string[];
+}
+export interface EvalResult {
+    top1: number;
+    top3: number;
+    top5: number;
+    avgLatencyMs: number;
+    total: number;
+    misses: Array<{
+        query: string;
+        expected: string;
+        got: string[];
+    }>;
+}

package/dist/tool-index.d.ts

@@ -0,0 +1,39 @@
+import type { LanguageModelMiddleware, PrepareStepFunction, ToolSet } from "ai";
+import type { SelectOptions, ToolIndexOptions } from "./search/types";
+import { createSearchTool } from "./integrations/search-tool";
+export interface ToolIndex<TOOLS extends ToolSet = ToolSet> {
+    /** Pre-compute embeddings eagerly so the first select() is fast. */
+    warmUp(): Promise<void>;
+    /** Select the most relevant tool names for a query. Returns string[] for activeTools. */
+    select(query: string, options?: SelectOptions): Promise<string[]>;
+    /** Returns a prepareStep function for ToolLoopAgent / generateText / streamText. */
+    prepareStep(options?: SelectOptions): PrepareStepFunction<TOOLS>;
+    /** Returns a LanguageModelMiddleware for transparent integration via wrapLanguageModel. */
+    middleware(options?: SelectOptions): LanguageModelMiddleware;
+    /** Returns a meta-tool agents can call to discover tools outside the current selection. */
+    searchTool(): ReturnType<typeof createSearchTool>;
+    /** The tool names in this index. */
+    readonly toolNames: (keyof TOOLS & string)[];
+}
+/**
+ * Creates a tool index for dynamic tool selection.
+ *
+ * When an embeddingModel is provided, defaults to "combined" strategy
+ * (hybrid keyword + semantic embeddings) for the best accuracy at minimal cost.
+ * Falls back to "hybrid" (free, no API calls) when no model is given.
+ *
+ * @param tools - A ToolSet (Record<string, Tool>) to index
+ * @param options - Strategy configuration
+ *
+ * @example
+ * ```ts
+ * import { createToolIndex } from "toolpick";
+ * import { openai } from "@ai-sdk/openai";
+ *
+ * const index = createToolIndex(allTools, {
+ *   embeddingModel: openai.embeddingModel("text-embedding-3-small"),
+ * });
+ * const activeTools = await index.select("ship it to prod", { maxTools: 5 });
+ * ```
+ */
+export declare function createToolIndex<TOOLS extends ToolSet>(tools: TOOLS, options?: ToolIndexOptions): ToolIndex<TOOLS>;

package/dist/tool-index.js

@@ -0,0 +1,159 @@
+import { HybridSearch } from "./search/hybrid";
+import { SemanticSearch } from "./search/semantic";
+import { CombinedSearch } from "./search/combined";
+import { createPrepareStep } from "./integrations/prepare-step";
+import { createMiddleware } from "./integrations/middleware";
+import { createSearchTool } from "./integrations/search-tool";
+import { rerank, enrichDescriptions } from "./reranker";
+function extractParamNames(toolDef) {
+    if (!toolDef || typeof toolDef !== "object")
+        return [];
+    const def = toolDef;
+    const inputSchema = def.inputSchema;
+    if (!inputSchema || typeof inputSchema !== "object")
+        return [];
+    const schema = inputSchema;
+    if (schema.properties && typeof schema.properties === "object") {
+        return Object.keys(schema.properties);
+    }
+    if (schema.jsonSchema && typeof schema.jsonSchema === "object" &&
+        !(schema.jsonSchema instanceof Promise)) {
+        const resolved = schema.jsonSchema;
+        if (resolved.properties && typeof resolved.properties === "object") {
+            return Object.keys(resolved.properties);
+        }
+    }
+    if ("shape" in schema && schema.shape && typeof schema.shape === "object") {
+        return Object.keys(schema.shape);
+    }
+    return [];
+}
+const GAP_RATIO = 0.4;
+const MIN_ADAPTIVE = 2;
+/**
+ * Finds the natural cutoff point in ranked results.
+ * Looks for the largest relative score drop — if result[i+1] drops
+ * by more than GAP_RATIO relative to result[0], cut there.
+ */
+function findElbow(results, max) {
+    if (results.length <= MIN_ADAPTIVE)
+        return results.slice(0, max);
+    const topScore = results[0].score;
+    if (topScore <= 0)
+        return results.slice(0, max);
+    for (let i = 0; i < results.length - 1 && i < max - 1; i++) {
+        const drop = results[i].score - results[i + 1].score;
+        if (drop / topScore >= GAP_RATIO && i + 1 >= MIN_ADAPTIVE) {
+            return results.slice(0, i + 1);
+        }
+    }
+    return results.slice(0, max);
+}
+function buildToolDescription(name, toolDef) {
+    const parts = [];
+    if (toolDef.description) {
+        parts.push(toolDef.description);
+    }
+    const paramNames = extractParamNames(toolDef);
+    if (paramNames.length > 0) {
+        parts.push(paramNames.join(" "));
+    }
+    return parts.join(" ");
+}
+/**
+ * Creates a tool index for dynamic tool selection.
+ *
+ * When an embeddingModel is provided, defaults to "combined" strategy
+ * (hybrid keyword + semantic embeddings) for the best accuracy at minimal cost.
+ * Falls back to "hybrid" (free, no API calls) when no model is given.
+ *
+ * @param tools - A ToolSet (Record<string, Tool>) to index
+ * @param options - Strategy configuration
+ *
+ * @example
+ * ```ts
+ * import { createToolIndex } from "toolpick";
+ * import { openai } from "@ai-sdk/openai";
+ *
+ * const index = createToolIndex(allTools, {
+ *   embeddingModel: openai.embeddingModel("text-embedding-3-small"),
+ * });
+ * const activeTools = await index.select("ship it to prod", { maxTools: 5 });
+ * ```
+ */
+export function createToolIndex(tools, options = {}) {
+    const { embeddingModel, embeddingCache, rerankerModel, enrichDescriptions: shouldEnrich = false, } = options;
+    const strategy = options.strategy
+        ?? (embeddingModel ? "combined" : "hybrid");
+    const toolNames = Object.keys(tools);
+    const toolNameSet = new Set(toolNames);
+    let descriptions = toolNames.map((name) => ({
+        name,
+        text: buildToolDescription(name, tools[name]),
+    }));
+    const descriptionMap = new Map();
+    for (const d of descriptions) {
+        descriptionMap.set(d.name, d.text);
+    }
+    let engine;
+    let enriched = false;
+    function buildEngine(descs) {
+        if (strategy === "combined") {
+            if (!embeddingModel) {
+                throw new Error('toolpick: embeddingModel is required when using strategy "combined". ' +
+                    'Example: createToolIndex(tools, { embeddingModel: openai.embeddingModel("text-embedding-3-small") })');
+            }
+            return new CombinedSearch(descs, embeddingModel, embeddingCache);
+        }
+        else if (strategy === "semantic") {
+            if (!embeddingModel) {
+                throw new Error('toolpick: embeddingModel is required when using strategy "semantic". ' +
+                    'Example: createToolIndex(tools, { strategy: "semantic", embeddingModel: openai.embeddingModel("text-embedding-3-small") })');
+            }
+            return new SemanticSearch(descs, embeddingModel, embeddingCache);
+        }
+        return new HybridSearch(descs);
+    }
+    engine = buildEngine(descriptions);
+    return {
+        toolNames,
+        async warmUp() {
+            if (shouldEnrich && rerankerModel && !enriched) {
+                descriptions = await enrichDescriptions(rerankerModel, descriptions);
+                for (const d of descriptions) {
+                    descriptionMap.set(d.name, d.text);
+                }
+                engine = buildEngine(descriptions);
+                enriched = true;
+            }
+            if (engine.init)
+                await engine.init();
+        },
+        async select(query, selectOptions = {}) {
+            const { maxTools = 5, alwaysActive = [], threshold, adaptive = true } = selectOptions;
+            const fetchCount = rerankerModel ? maxTools * 3 : maxTools;
+            let results = await engine.search(query, fetchCount);
+            if (threshold !== undefined) {
+                results = results.filter((r) => r.score >= threshold);
+            }
+            if (rerankerModel) {
+                results = await rerank(rerankerModel, query, results, descriptionMap, maxTools);
+            }
+            if (adaptive) {
+                results = findElbow(results, maxTools);
+            }
+            const selected = results.map((r) => r.name);
+            const merged = [...new Set([...selected, ...alwaysActive])];
+            return merged.filter((name) => toolNameSet.has(name));
+        },
+        prepareStep(stepOptions) {
+            return createPrepareStep(engine, toolNames, stepOptions);
+        },
+        middleware(mwOptions) {
+            return createMiddleware(engine, toolNames, mwOptions);
+        },
+        searchTool() {
+            return createSearchTool(engine, descriptions);
+        },
+    };
+}

package/dist/utils.d.ts

@@ -0,0 +1,2 @@
+export declare function splitCompound(word: string): string[];
+export declare function tokenize(text: string): string[];

package/dist/utils.js

@@ -0,0 +1,35 @@
+const STOPWORDS = new Set([
+    "a", "an", "the", "and", "or", "but", "if", "then", "else",
+    "for", "of", "in", "on", "to", "from", "by", "with", "as",
+    "at", "is", "are", "was", "were", "be", "been", "it", "this",
+    "that", "these", "those", "not", "no", "can", "could", "should",
+    "would", "may", "might", "do", "does", "did", "have", "has",
+    "had", "you", "your",
+]);
+export function splitCompound(word) {
+    if (word.includes("_")) {
+        return word.split("_").filter((s) => s.length > 0).map((s) => s.toLowerCase());
+    }
+    const parts = word.replace(/([a-z])([A-Z])/g, "$1 $2")
+        .replace(/([A-Z]+)([A-Z][a-z])/g, "$1 $2")
+        .toLowerCase()
+        .split(/\s+/)
+        .filter((s) => s.length > 0);
+    return parts.length > 1 ? parts : [word.toLowerCase()];
+}
+export function tokenize(text) {
+    const raw = text
+        .replace(/[^\p{L}\p{N}_\s]/gu, " ")
+        .split(/\s+/)
+        .filter((t) => t.length > 0);
+    const tokens = [];
+    for (const t of raw) {
+        for (const part of splitCompound(t)) {
+            const lower = part.toLowerCase();
+            if (!STOPWORDS.has(lower)) {
+                tokens.push(lower);
+            }
+        }
+    }
+    return tokens;
+}

package/package.json

@@ -0,0 +1,62 @@
+{
+  "name": "toolpick",
+  "version": "0.1.0",
+  "description": "Dynamic tool selection for the Vercel AI SDK. Automatically picks the right tools per step.",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/pontusab/directories"
+  },
+  "keywords": [
+    "ai",
+    "ai-sdk",
+    "tools",
+    "tool-selection",
+    "activeTools",
+    "vercel",
+    "llm",
+    "agent"
+  ],
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./eval": {
+      "types": "./dist/eval/index.d.ts",
+      "import": "./dist/eval/index.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsc --watch",
+    "test": "bun test src/test"
+  },
+  "peerDependencies": {
+    "ai": ">=4.0",
+    "zod": ">=3.25 || >=4.0"
+  },
+  "peerDependenciesMeta": {
+    "ai": {
+      "optional": false
+    },
+    "zod": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@ai-sdk/openai": "^3.0.47",
+    "@types/node": "^25.5.0",
+    "ai": "^6.0.134",
+    "typescript": "^5.9.3"
+  }
+}