bigtool-ts 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (116) hide show
  1. package/CHANGELOG.md +27 -0
  2. package/LICENSE +21 -0
  3. package/README.md +641 -0
  4. package/dist/adapters/agent-protocol.d.ts +149 -0
  5. package/dist/adapters/agent-protocol.d.ts.map +1 -0
  6. package/dist/adapters/agent-protocol.js +133 -0
  7. package/dist/adapters/agent-protocol.js.map +1 -0
  8. package/dist/adapters/index.d.ts +39 -0
  9. package/dist/adapters/index.d.ts.map +1 -0
  10. package/dist/adapters/index.js +42 -0
  11. package/dist/adapters/index.js.map +1 -0
  12. package/dist/adapters/inngest.d.ts +234 -0
  13. package/dist/adapters/inngest.d.ts.map +1 -0
  14. package/dist/adapters/inngest.js +276 -0
  15. package/dist/adapters/inngest.js.map +1 -0
  16. package/dist/adapters/mastra.d.ts +201 -0
  17. package/dist/adapters/mastra.d.ts.map +1 -0
  18. package/dist/adapters/mastra.js +250 -0
  19. package/dist/adapters/mastra.js.map +1 -0
  20. package/dist/adapters/types.d.ts +42 -0
  21. package/dist/adapters/types.d.ts.map +1 -0
  22. package/dist/adapters/types.js +6 -0
  23. package/dist/adapters/types.js.map +1 -0
  24. package/dist/adapters/vercel-ai.d.ts +176 -0
  25. package/dist/adapters/vercel-ai.d.ts.map +1 -0
  26. package/dist/adapters/vercel-ai.js +244 -0
  27. package/dist/adapters/vercel-ai.js.map +1 -0
  28. package/dist/catalog/index.d.ts +177 -0
  29. package/dist/catalog/index.d.ts.map +1 -0
  30. package/dist/catalog/index.js +244 -0
  31. package/dist/catalog/index.js.map +1 -0
  32. package/dist/graph/agent.d.ts +214 -0
  33. package/dist/graph/agent.d.ts.map +1 -0
  34. package/dist/graph/agent.js +196 -0
  35. package/dist/graph/agent.js.map +1 -0
  36. package/dist/graph/index.d.ts +5 -0
  37. package/dist/graph/index.d.ts.map +1 -0
  38. package/dist/graph/index.js +4 -0
  39. package/dist/graph/index.js.map +1 -0
  40. package/dist/graph/nodes.d.ts +100 -0
  41. package/dist/graph/nodes.d.ts.map +1 -0
  42. package/dist/graph/nodes.js +190 -0
  43. package/dist/graph/nodes.js.map +1 -0
  44. package/dist/graph/search-tool.d.ts +34 -0
  45. package/dist/graph/search-tool.d.ts.map +1 -0
  46. package/dist/graph/search-tool.js +54 -0
  47. package/dist/graph/search-tool.js.map +1 -0
  48. package/dist/graph/state.d.ts +26 -0
  49. package/dist/graph/state.d.ts.map +1 -0
  50. package/dist/graph/state.js +29 -0
  51. package/dist/graph/state.js.map +1 -0
  52. package/dist/index.d.ts +69 -0
  53. package/dist/index.d.ts.map +1 -0
  54. package/dist/index.js +85 -0
  55. package/dist/index.js.map +1 -0
  56. package/dist/loader/index.d.ts +172 -0
  57. package/dist/loader/index.d.ts.map +1 -0
  58. package/dist/loader/index.js +179 -0
  59. package/dist/loader/index.js.map +1 -0
  60. package/dist/loader/loader.d.ts +114 -0
  61. package/dist/loader/loader.d.ts.map +1 -0
  62. package/dist/loader/loader.js +185 -0
  63. package/dist/loader/loader.js.map +1 -0
  64. package/dist/search/cache.d.ts +76 -0
  65. package/dist/search/cache.d.ts.map +1 -0
  66. package/dist/search/cache.js +135 -0
  67. package/dist/search/cache.js.map +1 -0
  68. package/dist/search/index.d.ts +63 -0
  69. package/dist/search/index.d.ts.map +1 -0
  70. package/dist/search/index.js +122 -0
  71. package/dist/search/index.js.map +1 -0
  72. package/dist/search/normalize.d.ts +104 -0
  73. package/dist/search/normalize.d.ts.map +1 -0
  74. package/dist/search/normalize.js +211 -0
  75. package/dist/search/normalize.js.map +1 -0
  76. package/dist/search/orama.d.ts +256 -0
  77. package/dist/search/orama.d.ts.map +1 -0
  78. package/dist/search/orama.js +511 -0
  79. package/dist/search/orama.js.map +1 -0
  80. package/dist/search/types.d.ts +96 -0
  81. package/dist/search/types.d.ts.map +1 -0
  82. package/dist/search/types.js +8 -0
  83. package/dist/search/types.js.map +1 -0
  84. package/dist/sources/dynamic.d.ts +200 -0
  85. package/dist/sources/dynamic.d.ts.map +1 -0
  86. package/dist/sources/dynamic.js +194 -0
  87. package/dist/sources/dynamic.js.map +1 -0
  88. package/dist/sources/index.d.ts +11 -0
  89. package/dist/sources/index.d.ts.map +1 -0
  90. package/dist/sources/index.js +14 -0
  91. package/dist/sources/index.js.map +1 -0
  92. package/dist/sources/local.d.ts +128 -0
  93. package/dist/sources/local.d.ts.map +1 -0
  94. package/dist/sources/local.js +155 -0
  95. package/dist/sources/local.js.map +1 -0
  96. package/dist/sources/mcp.d.ts +438 -0
  97. package/dist/sources/mcp.d.ts.map +1 -0
  98. package/dist/sources/mcp.js +438 -0
  99. package/dist/sources/mcp.js.map +1 -0
  100. package/dist/sources/types.d.ts +16 -0
  101. package/dist/sources/types.d.ts.map +1 -0
  102. package/dist/sources/types.js +7 -0
  103. package/dist/sources/types.js.map +1 -0
  104. package/dist/sources/with-metadata.d.ts +7 -0
  105. package/dist/sources/with-metadata.d.ts.map +1 -0
  106. package/dist/sources/with-metadata.js +7 -0
  107. package/dist/sources/with-metadata.js.map +1 -0
  108. package/dist/types/index.d.ts +7 -0
  109. package/dist/types/index.d.ts.map +1 -0
  110. package/dist/types/index.js +8 -0
  111. package/dist/types/index.js.map +1 -0
  112. package/dist/types.d.ts +700 -0
  113. package/dist/types.d.ts.map +1 -0
  114. package/dist/types.js +97 -0
  115. package/dist/types.js.map +1 -0
  116. package/package.json +118 -0
@@ -0,0 +1,700 @@
1
+ /**
2
+ * Core type definitions for bigtool-ts.
3
+ *
4
+ * This module defines the fundamental interfaces that power the tool discovery
5
+ * system: sources, catalogs, loaders, search, and events.
6
+ *
7
+ * @module types
8
+ */
9
+ import type { StructuredTool } from "@langchain/core/tools";
10
+ /**
11
+ * Handler function for events.
12
+ *
13
+ * Event handlers can be synchronous or asynchronous. Async handlers
14
+ * are awaited before the next handler is called.
15
+ *
16
+ * @typeParam T - The event payload type
17
+ *
18
+ * @example
19
+ * ```typescript
20
+ * const handler: EventHandler<ToolsChangedEvent> = async (event) => {
21
+ * console.log('Tools added:', event.added);
22
+ * await updateSearchIndex(event);
23
+ * };
24
+ * ```
25
+ */
26
+ export type EventHandler<T> = (event: T) => void | Promise<void>;
27
+ /**
28
+ * Function to unsubscribe from events.
29
+ *
30
+ * Calling this function removes the handler from the subscriber list.
31
+ * Safe to call multiple times (subsequent calls are no-ops).
32
+ *
33
+ * @example
34
+ * ```typescript
35
+ * const unsubscribe = emitter.subscribe(handler);
36
+ * // Later, when done listening:
37
+ * unsubscribe();
38
+ * ```
39
+ */
40
+ export type Unsubscribe = () => void;
41
+ /**
42
+ * Simple typed event emitter for tool system events.
43
+ *
44
+ * Provides pub/sub functionality for reacting to changes in the tool
45
+ * system, such as tools being added or removed from the catalog.
46
+ *
47
+ * @typeParam T - The event payload type
48
+ *
49
+ * @example
50
+ * ```typescript
51
+ * const emitter = createEventEmitter<ToolsChangedEvent>();
52
+ *
53
+ * const unsubscribe = emitter.subscribe(async (event) => {
54
+ * console.log('Added:', event.added.length);
55
+ * console.log('Removed:', event.removed.length);
56
+ * });
57
+ *
58
+ * await emitter.emit({ added: ['tool1'], removed: [] });
59
+ * unsubscribe();
60
+ * ```
61
+ */
62
+ export interface EventEmitter<T> {
63
+ /**
64
+ * Subscribe to events.
65
+ *
66
+ * @param handler - Function called when events are emitted
67
+ * @returns Unsubscribe function to remove the handler
68
+ */
69
+ subscribe(handler: EventHandler<T>): Unsubscribe;
70
+ /**
71
+ * Alias for subscribe.
72
+ *
73
+ * @param handler - Function called when events are emitted
74
+ * @returns Unsubscribe function to remove the handler
75
+ */
76
+ on(handler: EventHandler<T>): Unsubscribe;
77
+ /**
78
+ * Emit an event to all subscribers.
79
+ *
80
+ * Handlers are called sequentially and awaited. If a handler throws,
81
+ * subsequent handlers are not called.
82
+ *
83
+ * @param event - The event payload to emit
84
+ */
85
+ emit(event: T): Promise<void>;
86
+ /**
87
+ * Get the number of active subscribers.
88
+ *
89
+ * @returns Number of subscribed handlers
90
+ */
91
+ subscriberCount(): number;
92
+ /**
93
+ * Remove all subscribers.
94
+ *
95
+ * Call this when disposing of the emitter to prevent memory leaks.
96
+ */
97
+ clear(): void;
98
+ }
99
+ /**
100
+ * Creates a simple typed event emitter.
101
+ *
102
+ * @typeParam T - The event payload type
103
+ * @returns A new EventEmitter instance
104
+ *
105
+ * @example
106
+ * ```typescript
107
+ * interface MyEvent {
108
+ * type: string;
109
+ * data: unknown;
110
+ * }
111
+ *
112
+ * const emitter = createEventEmitter<MyEvent>();
113
+ *
114
+ * emitter.on((event) => {
115
+ * console.log(event.type, event.data);
116
+ * });
117
+ *
118
+ * await emitter.emit({ type: 'test', data: { foo: 'bar' } });
119
+ * ```
120
+ */
121
+ export declare function createEventEmitter<T>(): EventEmitter<T>;
122
+ /**
123
+ * Metadata describing a tool for search and discovery.
124
+ *
125
+ * This is the lightweight representation of a tool used for indexing
126
+ * and searching. It does not include the actual executable tool
127
+ * implementation, which is loaded on demand via the ToolLoader.
128
+ *
129
+ * @example
130
+ * ```typescript
131
+ * const metadata: ToolMetadata = {
132
+ * id: 'github:create_pr',
133
+ * name: 'create_pr',
134
+ * description: 'Creates a new pull request on GitHub',
135
+ * parameters: {
136
+ * type: 'object',
137
+ * properties: {
138
+ * title: { type: 'string' },
139
+ * body: { type: 'string' },
140
+ * },
141
+ * required: ['title'],
142
+ * },
143
+ * categories: ['github', 'git'],
144
+ * keywords: ['PR', 'pull request', 'merge'],
145
+ * source: 'mcp',
146
+ * sourceId: 'mcp:github',
147
+ * };
148
+ * ```
149
+ */
150
+ export interface ToolMetadata {
151
+ /**
152
+ * Unique identifier for the tool.
153
+ *
154
+ * Format is typically `sourceId:toolName` (e.g., 'local:calculator',
155
+ * 'mcp:github:create_pr').
156
+ */
157
+ id: string;
158
+ /**
159
+ * Human-readable tool name.
160
+ *
161
+ * This is the name passed to the LLM and used in tool calls.
162
+ */
163
+ name: string;
164
+ /**
165
+ * Description of what the tool does.
166
+ *
167
+ * Used for search matching and displayed to the LLM to help
168
+ * it decide when to use this tool.
169
+ */
170
+ description: string;
171
+ /**
172
+ * JSON Schema for tool parameters.
173
+ *
174
+ * Defines the expected input structure. Optional for tools
175
+ * that take no parameters.
176
+ */
177
+ parameters?: Record<string, unknown>;
178
+ /**
179
+ * Categories for organization and filtering.
180
+ *
181
+ * Used to group related tools and filter search results.
182
+ * Examples: ['github', 'git'], ['database', 'sql']
183
+ */
184
+ categories?: string[];
185
+ /**
186
+ * Additional keywords for improved search matching.
187
+ *
188
+ * Synonyms or related terms that help users find this tool.
189
+ * Examples: ['PR', 'pull request'] for a create_pr tool.
190
+ */
191
+ keywords?: string[];
192
+ /**
193
+ * Source type indicating where this tool comes from.
194
+ *
195
+ * - 'local': In-memory StructuredTool instances
196
+ * - 'mcp': Tools from an MCP (Model Context Protocol) server
197
+ * - 'dynamic': Lazy-loaded tools via custom loader
198
+ */
199
+ source: "local" | "mcp" | "dynamic";
200
+ /**
201
+ * Source identifier for loading the tool.
202
+ *
203
+ * References the ToolSource that can provide the executable
204
+ * tool implementation.
205
+ */
206
+ sourceId: string;
207
+ }
208
+ /**
209
+ * A source of tools (local, MCP server, dynamic loader).
210
+ *
211
+ * Tool sources are the providers of tools in the system. Each source
212
+ * can provide metadata for discovery and the actual tool implementations
213
+ * when requested.
214
+ *
215
+ * Built-in implementations:
216
+ * - {@link LocalSource}: In-memory StructuredTool instances
217
+ * - {@link MCPSource}: Tools from an MCP server
218
+ * - {@link DynamicSource}: Lazy-loaded tools via custom function
219
+ *
220
+ * @example Custom ToolSource implementation
221
+ * ```typescript
222
+ * class PluginSource implements ToolSource {
223
+ * readonly id = 'plugins';
224
+ *
225
+ * async getMetadata(): Promise<ToolMetadata[]> {
226
+ * const plugins = await loadPluginManifests();
227
+ * return plugins.map(p => ({
228
+ * id: `plugins:${p.name}`,
229
+ * name: p.name,
230
+ * description: p.description,
231
+ * source: 'dynamic',
232
+ * sourceId: this.id,
233
+ * }));
234
+ * }
235
+ *
236
+ * async getTool(id: string): Promise<StructuredTool | null> {
237
+ * const name = id.replace('plugins:', '');
238
+ * return loadPluginTool(name);
239
+ * }
240
+ * }
241
+ * ```
242
+ */
243
+ export interface ToolSource {
244
+ /**
245
+ * Unique identifier for this source.
246
+ *
247
+ * Used to namespace tool IDs and locate tools during loading.
248
+ * Examples: 'local', 'mcp:github', 'plugins'
249
+ */
250
+ readonly id: string;
251
+ /**
252
+ * Get metadata for all tools from this source.
253
+ *
254
+ * Called during catalog registration to index tools for search.
255
+ * Should return quickly - avoid heavy computation here.
256
+ *
257
+ * @returns Promise resolving to array of tool metadata
258
+ */
259
+ getMetadata(): Promise<ToolMetadata[]>;
260
+ /**
261
+ * Get an executable tool by ID.
262
+ *
263
+ * Called by the ToolLoader when a tool is needed for execution.
264
+ * May be called multiple times for the same tool (loader caches).
265
+ *
266
+ * @param id - The tool ID (may be prefixed with sourceId)
267
+ * @returns Promise resolving to the tool, or null if not found
268
+ */
269
+ getTool(id: string): Promise<StructuredTool | null>;
270
+ /**
271
+ * Optional event emitter for when tools are refreshed.
272
+ *
273
+ * Emit events when the tool list changes (e.g., MCP server
274
+ * reloads). The catalog listens and updates accordingly.
275
+ */
276
+ onRefresh?: EventEmitter<ToolMetadata[]>;
277
+ }
278
+ /**
279
+ * Event emitted when tools in the catalog change.
280
+ *
281
+ * Subscribe to catalog.onToolsChanged to react to tool additions
282
+ * or removals, such as updating a search index.
283
+ *
284
+ * @example
285
+ * ```typescript
286
+ * catalog.onToolsChanged.subscribe(async (event) => {
287
+ * if (event.added.length > 0) {
288
+ * await searchIndex.reindex();
289
+ * }
290
+ * console.log(`Added: ${event.added.length}, Removed: ${event.removed.length}`);
291
+ * });
292
+ * ```
293
+ */
294
+ export interface ToolsChangedEvent {
295
+ /**
296
+ * Tool IDs that were added.
297
+ *
298
+ * Empty array if no tools were added.
299
+ */
300
+ added: string[];
301
+ /**
302
+ * Tool IDs that were removed.
303
+ *
304
+ * Empty array if no tools were removed.
305
+ */
306
+ removed: string[];
307
+ }
308
+ /**
309
+ * The catalog is the source of truth for what tools exist.
310
+ *
311
+ * It aggregates tools from multiple sources and provides a unified
312
+ * view for search indexing and tool loading. The catalog does not
313
+ * store tool implementations—only metadata and source references.
314
+ *
315
+ * @example
316
+ * ```typescript
317
+ * const catalog = new DefaultToolCatalog();
318
+ *
319
+ * // Register sources
320
+ * await catalog.register(new LocalSource(myTools));
321
+ * await catalog.register(new MCPSource(mcpClient));
322
+ *
323
+ * // Query the catalog
324
+ * const allTools = catalog.getAllMetadata();
325
+ * const tool = catalog.getMetadata('local:calculator');
326
+ *
327
+ * // Listen for changes
328
+ * catalog.onToolsChanged.subscribe((event) => {
329
+ * console.log('Catalog updated:', event);
330
+ * });
331
+ * ```
332
+ */
333
+ export interface ToolCatalog {
334
+ /**
335
+ * Register a new tool source.
336
+ *
337
+ * Fetches metadata from the source and adds all tools to the catalog.
338
+ * Emits a ToolsChangedEvent with the added tool IDs.
339
+ *
340
+ * @param source - The tool source to register
341
+ * @throws Error if a source with the same ID is already registered
342
+ */
343
+ register(source: ToolSource): Promise<void>;
344
+ /**
345
+ * Unregister a tool source by ID.
346
+ *
347
+ * Removes all tools from that source and emits a ToolsChangedEvent.
348
+ * No-op if the source ID doesn't exist.
349
+ *
350
+ * @param sourceId - The source ID to unregister
351
+ */
352
+ unregister(sourceId: string): void;
353
+ /**
354
+ * Get all tool metadata in the catalog.
355
+ *
356
+ * Returns a snapshot of all currently registered tools.
357
+ *
358
+ * @returns Array of all tool metadata
359
+ */
360
+ getAllMetadata(): ToolMetadata[];
361
+ /**
362
+ * Get metadata for a specific tool.
363
+ *
364
+ * @param id - The tool ID to look up
365
+ * @returns Tool metadata, or null if not found
366
+ */
367
+ getMetadata(id: string): ToolMetadata | null;
368
+ /**
369
+ * Get the source for a tool by source ID.
370
+ *
371
+ * Used by the loader to retrieve tool implementations.
372
+ *
373
+ * @param sourceId - The source ID to look up
374
+ * @returns The tool source, or null if not found
375
+ */
376
+ getSource(sourceId: string): ToolSource | null;
377
+ /**
378
+ * Event emitter for tool changes.
379
+ *
380
+ * Subscribe to be notified when tools are added or removed.
381
+ */
382
+ onToolsChanged: EventEmitter<ToolsChangedEvent>;
383
+ }
384
+ /**
385
+ * Lazy loader for tool implementations with caching.
386
+ *
387
+ * The loader sits between the catalog (metadata) and tool sources
388
+ * (implementations). It caches loaded tools using an LRU policy
389
+ * to avoid repeated loading from sources.
390
+ *
391
+ * @example
392
+ * ```typescript
393
+ * const loader = new DefaultToolLoader(catalog, { maxSize: 50 });
394
+ *
395
+ * // Load a single tool
396
+ * const tool = await loader.load('github:create_pr');
397
+ *
398
+ * // Pre-warm cache for expected tools
399
+ * await loader.warmup(['github:create_pr', 'github:list_repos']);
400
+ *
401
+ * // Invalidate after changes
402
+ * loader.evict('github:create_pr');
403
+ * ```
404
+ */
405
+ export interface ToolLoader {
406
+ /**
407
+ * Load a tool by ID.
408
+ *
409
+ * Returns cached tool if available, otherwise loads from source.
410
+ * Concurrent requests for the same tool are deduplicated.
411
+ *
412
+ * @param id - The tool ID to load
413
+ * @returns Promise resolving to the loaded tool
414
+ * @throws Error if tool not found in catalog or source returns null
415
+ */
416
+ load(id: string): Promise<StructuredTool>;
417
+ /**
418
+ * Pre-load multiple tools in parallel.
419
+ *
420
+ * Useful for warming up the cache before a batch of operations.
421
+ * Errors are silently ignored—use load() for error handling.
422
+ *
423
+ * @param ids - Array of tool IDs to pre-load
424
+ */
425
+ warmup(ids: string[]): Promise<void>;
426
+ /**
427
+ * Remove a tool from the cache.
428
+ *
429
+ * The tool will be reloaded from source on next access.
430
+ *
431
+ * @param id - The tool ID to evict
432
+ */
433
+ evict(id: string): void;
434
+ /**
435
+ * Clear the entire cache.
436
+ *
437
+ * All tools will be reloaded from source on next access.
438
+ */
439
+ clear(): void;
440
+ }
441
+ /**
442
+ * Options for search queries.
443
+ *
444
+ * @example
445
+ * ```typescript
446
+ * const results = await searchIndex.search('github', {
447
+ * limit: 10,
448
+ * threshold: 0.3,
449
+ * categories: ['version-control'],
450
+ * });
451
+ * ```
452
+ */
453
+ export interface SearchOptions {
454
+ /**
455
+ * Maximum number of results to return.
456
+ *
457
+ * @default 5
458
+ */
459
+ limit?: number;
460
+ /**
461
+ * Minimum score threshold (0-1).
462
+ *
463
+ * Results with scores below this threshold are excluded.
464
+ *
465
+ * @default 0
466
+ */
467
+ threshold?: number;
468
+ /**
469
+ * Filter by categories.
470
+ *
471
+ * Only tools matching at least one category are returned.
472
+ */
473
+ categories?: string[];
474
+ }
475
+ /**
476
+ * A single search result.
477
+ *
478
+ * Contains the matched tool ID, relevance score, and the algorithm
479
+ * that produced the match.
480
+ */
481
+ export interface SearchResult {
482
+ /**
483
+ * Tool ID of the matched tool.
484
+ *
485
+ * Use this to load the tool via ToolLoader.
486
+ */
487
+ toolId: string;
488
+ /**
489
+ * Relevance score (0-1, normalized).
490
+ *
491
+ * Higher scores indicate better matches. Scores are normalized
492
+ * to [0, 1] range regardless of the underlying algorithm.
493
+ */
494
+ score: number;
495
+ /**
496
+ * How the match was made.
497
+ *
498
+ * - 'bm25': Text-based matching using BM25 algorithm
499
+ * - 'vector': Semantic matching using embeddings
500
+ * - 'hybrid': Combined BM25 and vector scores
501
+ */
502
+ matchType: "bm25" | "vector" | "hybrid";
503
+ }
504
+ /**
505
+ * Search index for finding tools by query.
506
+ *
507
+ * Provides fast tool discovery using text search (BM25), semantic
508
+ * search (vector embeddings), or a hybrid of both.
509
+ *
510
+ * @example BM25 search (default, no API keys)
511
+ * ```typescript
512
+ * const searchIndex = new OramaSearch({ mode: 'bm25' });
513
+ * await searchIndex.index(catalog.getAllMetadata());
514
+ *
515
+ * const results = await searchIndex.search('create pull request');
516
+ * console.log(results[0].toolId); // 'github:create_pr'
517
+ * ```
518
+ *
519
+ * @example Hybrid search (best quality)
520
+ * ```typescript
521
+ * const searchIndex = new OramaSearch({
522
+ * mode: 'hybrid',
523
+ * embeddings: new OpenAIEmbeddings(),
524
+ * weights: { bm25: 0.4, vector: 0.6 },
525
+ * });
526
+ * ```
527
+ */
528
+ export interface SearchIndex {
529
+ /**
530
+ * Index tools for search.
531
+ *
532
+ * Call this after registering sources with the catalog.
533
+ * Replaces any existing index.
534
+ *
535
+ * @param tools - Array of tool metadata to index
536
+ */
537
+ index(tools: ToolMetadata[]): Promise<void>;
538
+ /**
539
+ * Search for tools matching a query.
540
+ *
541
+ * @param query - Natural language search query
542
+ * @param options - Search options (limit, threshold, categories)
543
+ * @returns Array of search results sorted by relevance
544
+ */
545
+ search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
546
+ /**
547
+ * Re-index all tools.
548
+ *
549
+ * Call this when the catalog changes (tools added/removed).
550
+ * Uses the tools from the last index() call.
551
+ */
552
+ reindex(): Promise<void>;
553
+ }
554
+ /**
555
+ * Enhancement metadata that can be added to a tool.
556
+ *
557
+ * Use this to add search optimization hints to your tools,
558
+ * such as categories for filtering and keywords for better matching.
559
+ *
560
+ * @example
561
+ * ```typescript
562
+ * const enhancement: ToolEnhancement = {
563
+ * categories: ['github', 'version-control'],
564
+ * keywords: ['PR', 'pull request', 'merge', 'review'],
565
+ * };
566
+ * ```
567
+ */
568
+ export interface ToolEnhancement {
569
+ /**
570
+ * Categories for grouping and filtering.
571
+ *
572
+ * Tools can be filtered by category during search.
573
+ * Use consistent category names across related tools.
574
+ */
575
+ categories?: string[];
576
+ /**
577
+ * Keywords for improved search matching.
578
+ *
579
+ * Add synonyms, abbreviations, and related terms that
580
+ * users might search for.
581
+ */
582
+ keywords?: string[];
583
+ }
584
+ /**
585
+ * A tool with enhancement metadata attached.
586
+ *
587
+ * The metadata is stored in a private property and extracted
588
+ * during indexing by LocalSource.
589
+ */
590
+ export type EnhancedTool = StructuredTool & {
591
+ /** @internal Enhancement metadata for search optimization */
592
+ __bigtool_metadata?: ToolEnhancement;
593
+ };
594
+ /**
595
+ * Attach enhancement metadata to a tool.
596
+ *
597
+ * This is a fluent helper that adds search optimization hints
598
+ * to a StructuredTool. The metadata is used during indexing
599
+ * to improve search results.
600
+ *
601
+ * @typeParam T - The tool type (must extend StructuredTool)
602
+ * @param tool - The tool to enhance
603
+ * @param metadata - Enhancement metadata (categories, keywords)
604
+ * @returns The same tool instance with metadata attached
605
+ *
606
+ * @example
607
+ * ```typescript
608
+ * import { withMetadata } from '@repo/bigtool-ts';
609
+ *
610
+ * const createPRTool = new DynamicStructuredTool({
611
+ * name: 'create_pr',
612
+ * description: 'Creates a GitHub pull request',
613
+ * schema: z.object({ title: z.string() }),
614
+ * func: async (input) => { ... },
615
+ * });
616
+ *
617
+ * const enhanced = withMetadata(createPRTool, {
618
+ * categories: ['github', 'git'],
619
+ * keywords: ['PR', 'pull request', 'merge'],
620
+ * });
621
+ *
622
+ * // Use in a LocalSource
623
+ * const source = new LocalSource([enhanced]);
624
+ * ```
625
+ */
626
+ export declare function withMetadata<T extends StructuredTool>(tool: T, metadata: ToolEnhancement): T & EnhancedTool;
627
+ /**
628
+ * Cache interface for storing computed embeddings.
629
+ *
630
+ * Embedding computation is expensive (requires API calls). This cache
631
+ * stores embeddings by tool ID to avoid recomputation when the search
632
+ * index is rebuilt.
633
+ *
634
+ * @example In-memory implementation
635
+ * ```typescript
636
+ * class MemoryEmbeddingCache implements EmbeddingCache {
637
+ * private cache = new Map<string, number[]>();
638
+ *
639
+ * async get(toolId: string): Promise<number[] | null> {
640
+ * return this.cache.get(toolId) ?? null;
641
+ * }
642
+ *
643
+ * async set(toolId: string, embedding: number[]): Promise<void> {
644
+ * this.cache.set(toolId, embedding);
645
+ * }
646
+ *
647
+ * async invalidate(toolId: string): Promise<void> {
648
+ * this.cache.delete(toolId);
649
+ * }
650
+ *
651
+ * async clear(): Promise<void> {
652
+ * this.cache.clear();
653
+ * }
654
+ * }
655
+ * ```
656
+ */
657
+ export interface EmbeddingCache {
658
+ /**
659
+ * Retrieve a cached embedding by tool ID.
660
+ *
661
+ * @param toolId - The tool ID to look up
662
+ * @returns The cached embedding, or null if not found
663
+ */
664
+ get(toolId: string): Promise<number[] | null>;
665
+ /**
666
+ * Store an embedding for a tool ID.
667
+ *
668
+ * @param toolId - The tool ID to cache for
669
+ * @param embedding - The embedding vector to store
670
+ */
671
+ set(toolId: string, embedding: number[]): Promise<void>;
672
+ /**
673
+ * Remove a cached embedding.
674
+ *
675
+ * Call this when a tool's metadata changes.
676
+ *
677
+ * @param toolId - The tool ID to invalidate
678
+ */
679
+ invalidate(toolId: string): Promise<void>;
680
+ /**
681
+ * Clear all cached embeddings.
682
+ *
683
+ * Call this when performing a full reindex.
684
+ */
685
+ clear(): Promise<void>;
686
+ }
687
+ /**
688
+ * Event emitted when the catalog changes.
689
+ *
690
+ * Alias for {@link ToolsChangedEvent} for backwards compatibility.
691
+ */
692
+ export type CatalogChangeEvent = ToolsChangedEvent;
693
+ /**
694
+ * Event emitter for tool refreshes.
695
+ *
696
+ * Used by sources to notify the catalog when their tool list changes.
697
+ * Emits the new complete list of tool metadata.
698
+ */
699
+ export type ToolEventEmitter = EventEmitter<ToolMetadata[]>;
700
+ //# sourceMappingURL=types.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}