bigtool-ts 0.1.0

package/dist/adapters/vercel-ai.js

@@ -0,0 +1,244 @@
+/**
+ * Vercel AI SDK adapter for bigtool-ts.
+ *
+ * Converts bigtool-ts tools to Vercel AI SDK format for use with
+ * generateText(), streamText(), and other SDK functions.
+ *
+ * @module adapters/vercel-ai
+ */
+import { z } from 'zod';
+// ═══════════════════════════════════════════════════════════════════
+// SEARCH RESULT SCHEMA
+// ═══════════════════════════════════════════════════════════════════
+const searchInputSchema = z.object({
+    query: z.string().describe('Natural language search query'),
+});
+const searchResultSchema = z.object({
+    name: z.string(),
+    description: z.string(),
+    score: z.number(),
+});
+const searchOutputSchema = z.array(searchResultSchema);
+// ═══════════════════════════════════════════════════════════════════
+// ADAPTER IMPLEMENTATION
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * Vercel AI SDK adapter for bigtool-ts.
+ *
+ * Converts bigtool-ts tools to Vercel AI SDK format. Tools are lazily
+ * loaded when executed, and the adapter handles abort signal propagation.
+ *
+ * @example Basic usage with streamText
+ * ```typescript
+ * import { streamText } from 'ai';
+ * import { openai } from '@ai-sdk/openai';
+ * import { createVercelAdapter } from '@repo/bigtool-ts/adapters';
+ *
+ * const adapter = createVercelAdapter({ catalog, loader, searchIndex });
+ *
+ * const result = await streamText({
+ *   model: openai('gpt-4o'),
+ *   tools: {
+ *     search_tools: adapter.createSearchTool(),
+ *     ...await adapter.getToolsAsRecord(['github:create_pr']),
+ *   },
+ *   prompt: 'Create a PR with title "Fix bug"',
+ * });
+ * ```
+ *
+ * @example With search tool for dynamic discovery
+ * ```typescript
+ * const result = await generateText({
+ *   model: openai('gpt-4o'),
+ *   tools: {
+ *     search_tools: adapter.createSearchTool({ limit: 10 }),
+ *   },
+ *   prompt: 'What tools are available for GitHub?',
+ * });
+ * ```
+ */
+export class VercelAIAdapter {
+    catalog;
+    loader;
+    searchIndex;
+    constructor(config) {
+        this.catalog = config.catalog;
+        this.loader = config.loader;
+        this.searchIndex = config.searchIndex;
+    }
+    /**
+     * Convert bigtool-ts metadata to a Vercel AI SDK tool.
+     *
+     * The returned tool lazily loads the implementation on first execute.
+     * Abort signals are checked before loading to fail fast on cancellation.
+     *
+     * @param metadata - Tool metadata from the catalog
+     * @returns Vercel AI SDK compatible tool
+     */
+    toFrameworkTool(metadata) {
+        const loader = this.loader;
+        return {
+            description: metadata.description,
+            inputSchema: createJsonSchema(metadata.parameters),
+            execute: async (args, options) => {
+                // Fail fast on abort before expensive loader call
+                options.abortSignal?.throwIfAborted();
+                const tool = await loader.load(metadata.id);
+                return tool.invoke(args);
+            },
+        };
+    }
+    /**
+     * Get tools by IDs as an array.
+     *
+     * Missing tools are silently skipped. Use this when you need an array
+     * of tools and don't care about the tool names.
+     *
+     * @param toolIds - Array of tool IDs to load
+     * @returns Array of Vercel AI SDK tools
+     */
+    async getTools(toolIds) {
+        const tools = [];
+        for (const id of toolIds) {
+            const metadata = this.catalog.getMetadata(id);
+            if (metadata === null) {
+                continue;
+            }
+            tools.push(this.toFrameworkTool(metadata));
+        }
+        return tools;
+    }
+    /**
+     * Get tools by IDs as a record (ToolSet).
+     *
+     * The record keys are the tool names from metadata. Missing tools are
+     * silently skipped. Use this for passing to generateText/streamText.
+     *
+     * @param toolIds - Array of tool IDs to load
+     * @returns Record of tools keyed by name
+     *
+     * @example
+     * ```typescript
+     * const tools = await adapter.getToolsAsRecord([
+     *   'github:create_pr',
+     *   'slack:send_message',
+     * ]);
+     *
+     * const result = await streamText({
+     *   model: openai('gpt-4o'),
+     *   tools,
+     *   prompt: 'Create a PR and notify the team',
+     * });
+     * ```
+     */
+    async getToolsAsRecord(toolIds) {
+        const tools = {};
+        for (const id of toolIds) {
+            const metadata = this.catalog.getMetadata(id);
+            if (metadata === null) {
+                continue;
+            }
+            tools[metadata.name] = this.toFrameworkTool(metadata);
+        }
+        return tools;
+    }
+    /**
+     * Create a search tool for discovering available tools.
+     *
+     * The search tool enables dynamic tool discovery in agentic workflows.
+     * The LLM can use this tool to find relevant tools before calling them.
+     *
+     * @param options - Search configuration options
+     * @returns Vercel AI SDK tool for searching the catalog
+     *
+     * @example
+     * ```typescript
+     * const searchTool = adapter.createSearchTool({
+     *   limit: 5,
+     *   threshold: 0.3,
+     *   categories: ['github'],
+     * });
+     *
+     * const result = await generateText({
+     *   model: openai('gpt-4o'),
+     *   tools: { search_tools: searchTool },
+     *   prompt: 'Find tools for creating pull requests',
+     * });
+     * ```
+     */
+    createSearchTool(options = {}) {
+        const limit = options.limit ?? 5;
+        const threshold = options.threshold ?? 0;
+        const categories = options.categories;
+        const searchIndex = this.searchIndex;
+        const catalog = this.catalog;
+        return {
+            description: 'Search for available tools by query. Use this to discover what tools are available before calling them.',
+            inputSchema: searchInputSchema,
+            outputSchema: searchOutputSchema,
+            execute: async (input) => {
+                // Input is validated by the framework via inputSchema before execute is called
+                const { query } = input;
+                const results = await searchIndex.search(query, {
+                    limit,
+                    threshold,
+                    categories,
+                });
+                return results.map((result) => {
+                    const meta = catalog.getMetadata(result.toolId);
+                    return {
+                        name: meta?.name ?? result.toolId,
+                        description: meta?.description ?? '',
+                        score: result.score,
+                    };
+                });
+            },
+        };
+    }
+}
+// ═══════════════════════════════════════════════════════════════════
+// FACTORY FUNCTION
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * Create a Vercel AI SDK adapter.
+ *
+ * Factory function for creating a VercelAIAdapter instance.
+ * Use this as the primary entry point for creating adapters.
+ *
+ * @param config - Adapter configuration with catalog, loader, and searchIndex
+ * @returns Configured VercelAIAdapter instance
+ *
+ * @example
+ * ```typescript
+ * import { createVercelAdapter } from '@repo/bigtool-ts/adapters';
+ *
+ * const adapter = createVercelAdapter({
+ *   catalog: new DefaultToolCatalog(),
+ *   loader: new DefaultToolLoader(catalog),
+ *   searchIndex: new OramaSearch(),
+ * });
+ * ```
+ */
+export function createVercelAdapter(config) {
+    return new VercelAIAdapter(config);
+}
+// ═══════════════════════════════════════════════════════════════════
+// HELPERS
+// ═══════════════════════════════════════════════════════════════════
+/**
+ * Create a JSON schema wrapper for Vercel AI SDK.
+ *
+ * The Vercel AI SDK accepts FlexibleSchema which includes raw JSON Schema.
+ * This function wraps the parameters to match the expected format.
+ *
+ * @param parameters - JSON Schema parameters from tool metadata
+ * @returns Wrapped schema for Vercel AI SDK
+ */
+function createJsonSchema(parameters) {
+    // Default to empty object schema if no parameters
+    const schema = parameters ?? { type: 'object', properties: {} };
+    // Return in a format compatible with Vercel AI SDK's jsonSchema() helper
+    // The SDK accepts raw JSON Schema objects directly
+    return schema;
+}
+//# sourceMappingURL=vercel-ai.js.map

package/dist/adapters/vercel-ai.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"vercel-ai.js","sourceRoot":"","sources":["../../src/adapters/vercel-ai.ts"],"names":[],"mappings":"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"}

package/dist/catalog/index.d.ts

@@ -0,0 +1,177 @@
+/**
+ * ToolCatalog module.
+ *
+ * Provides the default implementation of the ToolCatalog interface,
+ * aggregating tools from multiple sources into a unified registry.
+ *
+ * @module catalog
+ */
+import type { ToolCatalog, ToolSource, ToolMetadata, ToolsChangedEvent } from '../types.js';
+import { type EventEmitter } from '../types.js';
+/**
+ * Default implementation of ToolCatalog.
+ *
+ * Maintains a registry of tools from multiple sources and provides
+ * a unified view of all available tool metadata. The catalog is the
+ * central source of truth for what tools exist in the system.
+ *
+ * Key responsibilities:
+ * - Registering and unregistering tool sources
+ * - Aggregating metadata from all sources
+ * - Emitting change events when tools are added or removed
+ * - Providing source references for tool loading
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { DefaultToolCatalog, LocalSource, MCPSource } from '@repo/bigtool-ts';
+ *
+ * const catalog = new DefaultToolCatalog();
+ *
+ * // Register sources
+ * await catalog.register(new LocalSource(myTools));
+ * await catalog.register(new MCPSource(mcpClient));
+ *
+ * // Query the catalog
+ * const allTools = catalog.getAllMetadata();
+ * console.log(`Total tools: ${allTools.length}`);
+ *
+ * // Get specific tool metadata
+ * const tool = catalog.getMetadata('local:calculator');
+ * ```
+ *
+ * @example Listening for changes
+ * ```typescript
+ * const catalog = new DefaultToolCatalog();
+ *
+ * catalog.onToolsChanged.subscribe(async (event) => {
+ *   if (event.added.length > 0) {
+ *     console.log('New tools:', event.added);
+ *     await searchIndex.reindex();
+ *   }
+ *   if (event.removed.length > 0) {
+ *     console.log('Removed tools:', event.removed);
+ *   }
+ * });
+ *
+ * await catalog.register(new LocalSource(tools));
+ * ```
+ */
+export declare class DefaultToolCatalog implements ToolCatalog {
+    /** @internal Map of source ID to source */
+    private sources;
+    /** @internal Map of source ID to its metadata */
+    private metadataBySource;
+    /** @internal Map of tool ID to metadata for fast lookup */
+    private metadataById;
+    /**
+     * Event emitter for tool changes.
+     *
+     * Subscribe to be notified when tools are added or removed
+     * from the catalog.
+     */
+    readonly onToolsChanged: EventEmitter<ToolsChangedEvent>;
+    /**
+     * Creates a new DefaultToolCatalog.
+     *
+     * The catalog starts empty. Call register() to add tool sources.
+     *
+     * @example
+     * ```typescript
+     * const catalog = new DefaultToolCatalog();
+     * ```
+     */
+    constructor();
+    /**
+     * Register a new tool source.
+     *
+     * Fetches metadata from the source and adds all tools to the catalog.
+     * Subscribes to the source's onRefresh event if available.
+     * Emits a ToolsChangedEvent with the added tool IDs.
+     *
+     * @param source - The tool source to register
+     * @throws Error if a source with the same ID is already registered
+     *
+     * @example
+     * ```typescript
+     * await catalog.register(new LocalSource(tools, 'my-tools'));
+     * ```
+     */
+    register(source: ToolSource): Promise<void>;
+    /**
+     * Unregister a tool source by ID.
+     *
+     * Removes all tools from that source and emits a ToolsChangedEvent.
+     * No-op if the source ID doesn't exist.
+     *
+     * @param sourceId - The source ID to unregister
+     *
+     * @example
+     * ```typescript
+     * // Remove a source
+     * catalog.unregister('mcp:github');
+     *
+     * // Safe to call even if not registered
+     * catalog.unregister('nonexistent'); // No-op
+     * ```
+     */
+    unregister(sourceId: string): void;
+    /**
+     * Get all tool metadata in the catalog.
+     *
+     * Returns a snapshot of all currently registered tools from
+     * all sources.
+     *
+     * @returns Array of all tool metadata
+     *
+     * @example
+     * ```typescript
+     * const allTools = catalog.getAllMetadata();
+     * console.log(`Catalog has ${allTools.length} tools`);
+     *
+     * // Use for search indexing
+     * await searchIndex.index(allTools);
+     * ```
+     */
+    getAllMetadata(): ToolMetadata[];
+    /**
+     * Get metadata for a specific tool.
+     *
+     * @param id - The tool ID to look up
+     * @returns Tool metadata, or null if not found
+     *
+     * @example
+     * ```typescript
+     * const meta = catalog.getMetadata('local:calculator');
+     * if (meta) {
+     *   console.log(`Found: ${meta.name} - ${meta.description}`);
+     * }
+     * ```
+     */
+    getMetadata(id: string): ToolMetadata | null;
+    /**
+     * Get the source for a tool by source ID.
+     *
+     * Used by the ToolLoader to retrieve tool implementations.
+     *
+     * @param sourceId - The source ID to look up
+     * @returns The tool source, or null if not found
+     *
+     * @example
+     * ```typescript
+     * const source = catalog.getSource('mcp:github');
+     * if (source) {
+     *   const tool = await source.getTool('create_pr');
+     * }
+     * ```
+     */
+    getSource(sourceId: string): ToolSource | null;
+    /**
+     * Handle a source refresh event.
+     *
+     * @internal
+     * @param sourceId - The source that refreshed
+     * @param newMetadata - The new metadata from the source
+     */
+    private handleSourceRefresh;
+}
+//# sourceMappingURL=index.d.ts.map

package/dist/catalog/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/catalog/index.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,WAAW,EACX,UAAU,EACV,YAAY,EACZ,iBAAiB,EAClB,MAAM,aAAa,CAAC;AACrB,OAAO,EAAsB,KAAK,YAAY,EAAE,MAAM,aAAa,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AACH,qBAAa,kBAAmB,YAAW,WAAW;IACpD,2CAA2C;IAC3C,OAAO,CAAC,OAAO,CAAsC;IAErD,iDAAiD;IACjD,OAAO,CAAC,gBAAgB,CAA0C;IAElE,2DAA2D;IAC3D,OAAO,CAAC,YAAY,CAAwC;IAE5D;;;;;OAKG;IACH,QAAQ,CAAC,cAAc,EAAE,YAAY,CAAC,iBAAiB,CAAC,CAAC;IAEzD;;;;;;;;;OASG;;IAKH;;;;;;;;;;;;;;OAcG;IACG,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,IAAI,CAAC;IA4BjD;;;;;;;;;;;;;;;;OAgBG;IACH,UAAU,CAAC,QAAQ,EAAE,MAAM,GAAG,IAAI;IAmBlC;;;;;;;;;;;;;;;;OAgBG;IACH,cAAc,IAAI,YAAY,EAAE;IAIhC;;;;;;;;;;;;;OAaG;IACH,WAAW,CAAC,EAAE,EAAE,MAAM,GAAG,YAAY,GAAG,IAAI;IAI5C;;;;;;;;;;;;;;;OAeG;IACH,SAAS,CAAC,QAAQ,EAAE,MAAM,GAAG,UAAU,GAAG,IAAI;IAI9C;;;;;;OAMG;IACH,OAAO,CAAC,mBAAmB;CA+B5B"}

package/dist/catalog/index.js

@@ -0,0 +1,244 @@
+/**
+ * ToolCatalog module.
+ *
+ * Provides the default implementation of the ToolCatalog interface,
+ * aggregating tools from multiple sources into a unified registry.
+ *
+ * @module catalog
+ */
+import { createEventEmitter } from '../types.js';
+/**
+ * Default implementation of ToolCatalog.
+ *
+ * Maintains a registry of tools from multiple sources and provides
+ * a unified view of all available tool metadata. The catalog is the
+ * central source of truth for what tools exist in the system.
+ *
+ * Key responsibilities:
+ * - Registering and unregistering tool sources
+ * - Aggregating metadata from all sources
+ * - Emitting change events when tools are added or removed
+ * - Providing source references for tool loading
+ *
+ * @example Basic usage
+ * ```typescript
+ * import { DefaultToolCatalog, LocalSource, MCPSource } from '@repo/bigtool-ts';
+ *
+ * const catalog = new DefaultToolCatalog();
+ *
+ * // Register sources
+ * await catalog.register(new LocalSource(myTools));
+ * await catalog.register(new MCPSource(mcpClient));
+ *
+ * // Query the catalog
+ * const allTools = catalog.getAllMetadata();
+ * console.log(`Total tools: ${allTools.length}`);
+ *
+ * // Get specific tool metadata
+ * const tool = catalog.getMetadata('local:calculator');
+ * ```
+ *
+ * @example Listening for changes
+ * ```typescript
+ * const catalog = new DefaultToolCatalog();
+ *
+ * catalog.onToolsChanged.subscribe(async (event) => {
+ *   if (event.added.length > 0) {
+ *     console.log('New tools:', event.added);
+ *     await searchIndex.reindex();
+ *   }
+ *   if (event.removed.length > 0) {
+ *     console.log('Removed tools:', event.removed);
+ *   }
+ * });
+ *
+ * await catalog.register(new LocalSource(tools));
+ * ```
+ */
+export class DefaultToolCatalog {
+    /** @internal Map of source ID to source */
+    sources = new Map();
+    /** @internal Map of source ID to its metadata */
+    metadataBySource = new Map();
+    /** @internal Map of tool ID to metadata for fast lookup */
+    metadataById = new Map();
+    /**
+     * Event emitter for tool changes.
+     *
+     * Subscribe to be notified when tools are added or removed
+     * from the catalog.
+     */
+    onToolsChanged;
+    /**
+     * Creates a new DefaultToolCatalog.
+     *
+     * The catalog starts empty. Call register() to add tool sources.
+     *
+     * @example
+     * ```typescript
+     * const catalog = new DefaultToolCatalog();
+     * ```
+     */
+    constructor() {
+        this.onToolsChanged = createEventEmitter();
+    }
+    /**
+     * Register a new tool source.
+     *
+     * Fetches metadata from the source and adds all tools to the catalog.
+     * Subscribes to the source's onRefresh event if available.
+     * Emits a ToolsChangedEvent with the added tool IDs.
+     *
+     * @param source - The tool source to register
+     * @throws Error if a source with the same ID is already registered
+     *
+     * @example
+     * ```typescript
+     * await catalog.register(new LocalSource(tools, 'my-tools'));
+     * ```
+     */
+    async register(source) {
+        if (this.sources.has(source.id)) {
+            throw new Error(`ToolCatalog: Source with id '${source.id}' already registered`);
+        }
+        this.sources.set(source.id, source);
+        // Fetch and store metadata
+        const metadata = await source.getMetadata();
+        this.metadataBySource.set(source.id, metadata);
+        const added = [];
+        for (const tool of metadata) {
+            this.metadataById.set(tool.id, tool);
+            added.push(tool.id);
+        }
+        // Subscribe to refresh events if available
+        if (source.onRefresh) {
+            source.onRefresh.on((newMetadata) => {
+                this.handleSourceRefresh(source.id, newMetadata);
+            });
+        }
+        // Emit change event
+        this.onToolsChanged.emit({ added, removed: [] });
+    }
+    /**
+     * Unregister a tool source by ID.
+     *
+     * Removes all tools from that source and emits a ToolsChangedEvent.
+     * No-op if the source ID doesn't exist.
+     *
+     * @param sourceId - The source ID to unregister
+     *
+     * @example
+     * ```typescript
+     * // Remove a source
+     * catalog.unregister('mcp:github');
+     *
+     * // Safe to call even if not registered
+     * catalog.unregister('nonexistent'); // No-op
+     * ```
+     */
+    unregister(sourceId) {
+        const metadata = this.metadataBySource.get(sourceId);
+        if (!metadata) {
+            return;
+        }
+        const removed = [];
+        for (const tool of metadata) {
+            this.metadataById.delete(tool.id);
+            removed.push(tool.id);
+        }
+        this.sources.delete(sourceId);
+        this.metadataBySource.delete(sourceId);
+        // Emit change event
+        this.onToolsChanged.emit({ added: [], removed });
+    }
+    /**
+     * Get all tool metadata in the catalog.
+     *
+     * Returns a snapshot of all currently registered tools from
+     * all sources.
+     *
+     * @returns Array of all tool metadata
+     *
+     * @example
+     * ```typescript
+     * const allTools = catalog.getAllMetadata();
+     * console.log(`Catalog has ${allTools.length} tools`);
+     *
+     * // Use for search indexing
+     * await searchIndex.index(allTools);
+     * ```
+     */
+    getAllMetadata() {
+        return Array.from(this.metadataById.values());
+    }
+    /**
+     * Get metadata for a specific tool.
+     *
+     * @param id - The tool ID to look up
+     * @returns Tool metadata, or null if not found
+     *
+     * @example
+     * ```typescript
+     * const meta = catalog.getMetadata('local:calculator');
+     * if (meta) {
+     *   console.log(`Found: ${meta.name} - ${meta.description}`);
+     * }
+     * ```
+     */
+    getMetadata(id) {
+        return this.metadataById.get(id) ?? null;
+    }
+    /**
+     * Get the source for a tool by source ID.
+     *
+     * Used by the ToolLoader to retrieve tool implementations.
+     *
+     * @param sourceId - The source ID to look up
+     * @returns The tool source, or null if not found
+     *
+     * @example
+     * ```typescript
+     * const source = catalog.getSource('mcp:github');
+     * if (source) {
+     *   const tool = await source.getTool('create_pr');
+     * }
+     * ```
+     */
+    getSource(sourceId) {
+        return this.sources.get(sourceId) ?? null;
+    }
+    /**
+     * Handle a source refresh event.
+     *
+     * @internal
+     * @param sourceId - The source that refreshed
+     * @param newMetadata - The new metadata from the source
+     */
+    handleSourceRefresh(sourceId, newMetadata) {
+        const oldMetadata = this.metadataBySource.get(sourceId) ?? [];
+        const oldIds = new Set(oldMetadata.map(m => m.id));
+        const newIds = new Set(newMetadata.map(m => m.id));
+        const added = [];
+        const removed = [];
+        // Find removed tools
+        for (const id of oldIds) {
+            if (!newIds.has(id)) {
+                this.metadataById.delete(id);
+                removed.push(id);
+            }
+        }
+        // Find added/updated tools
+        for (const tool of newMetadata) {
+            if (!oldIds.has(tool.id)) {
+                added.push(tool.id);
+            }
+            this.metadataById.set(tool.id, tool);
+        }
+        this.metadataBySource.set(sourceId, newMetadata);
+        // Emit change event if anything changed
+        if (added.length > 0 || removed.length > 0) {
+            this.onToolsChanged.emit({ added, removed });
+        }
+    }
+}
+//# sourceMappingURL=index.js.map

package/dist/catalog/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/catalog/index.ts"],"names":[],"mappings":"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"}