@rudderjs/ai 1.5.0 → 1.6.1

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 (163) hide show
  1. package/README.md +482 -4
  2. package/boost/guidelines.md +60 -0
  3. package/boost/skills/ai-agents/SKILL.md +7 -0
  4. package/boost/skills/ai-tools/SKILL.md +7 -0
  5. package/dist/agent.d.ts +35 -1
  6. package/dist/agent.d.ts.map +1 -1
  7. package/dist/agent.js +118 -16
  8. package/dist/agent.js.map +1 -1
  9. package/dist/budget/pricing.d.ts +124 -0
  10. package/dist/budget/pricing.d.ts.map +1 -0
  11. package/dist/budget/pricing.js +175 -0
  12. package/dist/budget/pricing.js.map +1 -0
  13. package/dist/budget/storage.d.ts +104 -0
  14. package/dist/budget/storage.d.ts.map +1 -0
  15. package/dist/budget/storage.js +0 -0
  16. package/dist/budget/storage.js.map +1 -0
  17. package/dist/budget/with-budget.d.ts +119 -0
  18. package/dist/budget/with-budget.d.ts.map +1 -0
  19. package/dist/budget/with-budget.js +175 -0
  20. package/dist/budget/with-budget.js.map +1 -0
  21. package/dist/budget-orm/index.d.ts +96 -0
  22. package/dist/budget-orm/index.d.ts.map +1 -0
  23. package/dist/budget-orm/index.js +177 -0
  24. package/dist/budget-orm/index.js.map +1 -0
  25. package/dist/commands/ai-eval.d.ts +93 -0
  26. package/dist/commands/ai-eval.d.ts.map +1 -0
  27. package/dist/commands/ai-eval.js +378 -0
  28. package/dist/commands/ai-eval.js.map +1 -0
  29. package/dist/computer-use/actions.d.ts +214 -0
  30. package/dist/computer-use/actions.d.ts.map +1 -0
  31. package/dist/computer-use/actions.js +48 -0
  32. package/dist/computer-use/actions.js.map +1 -0
  33. package/dist/computer-use/errors.d.ts +57 -0
  34. package/dist/computer-use/errors.d.ts.map +1 -0
  35. package/dist/computer-use/errors.js +76 -0
  36. package/dist/computer-use/errors.js.map +1 -0
  37. package/dist/computer-use/index.d.ts +53 -0
  38. package/dist/computer-use/index.d.ts.map +1 -0
  39. package/dist/computer-use/index.js +51 -0
  40. package/dist/computer-use/index.js.map +1 -0
  41. package/dist/computer-use/playwright.d.ts +76 -0
  42. package/dist/computer-use/playwright.d.ts.map +1 -0
  43. package/dist/computer-use/playwright.js +270 -0
  44. package/dist/computer-use/playwright.js.map +1 -0
  45. package/dist/computer-use/tool.d.ts +154 -0
  46. package/dist/computer-use/tool.d.ts.map +1 -0
  47. package/dist/computer-use/tool.js +210 -0
  48. package/dist/computer-use/tool.js.map +1 -0
  49. package/dist/eval/fixtures.d.ts +65 -0
  50. package/dist/eval/fixtures.d.ts.map +1 -0
  51. package/dist/eval/fixtures.js +110 -0
  52. package/dist/eval/fixtures.js.map +1 -0
  53. package/dist/eval/html-reporter.d.ts +25 -0
  54. package/dist/eval/html-reporter.d.ts.map +1 -0
  55. package/dist/eval/html-reporter.js +209 -0
  56. package/dist/eval/html-reporter.js.map +1 -0
  57. package/dist/eval/index.d.ts +271 -0
  58. package/dist/eval/index.d.ts.map +1 -0
  59. package/dist/eval/index.js +510 -0
  60. package/dist/eval/index.js.map +1 -0
  61. package/dist/eval/json-reporter.d.ts +43 -0
  62. package/dist/eval/json-reporter.d.ts.map +1 -0
  63. package/dist/eval/json-reporter.js +40 -0
  64. package/dist/eval/json-reporter.js.map +1 -0
  65. package/dist/fake.d.ts +36 -1
  66. package/dist/fake.d.ts.map +1 -1
  67. package/dist/fake.js +49 -2
  68. package/dist/fake.js.map +1 -1
  69. package/dist/file-search.d.ts +168 -0
  70. package/dist/file-search.d.ts.map +1 -0
  71. package/dist/file-search.js +158 -0
  72. package/dist/file-search.js.map +1 -0
  73. package/dist/index.d.ts +22 -2
  74. package/dist/index.d.ts.map +1 -1
  75. package/dist/index.js +17 -1
  76. package/dist/index.js.map +1 -1
  77. package/dist/mcp/client-tools.d.ts +39 -0
  78. package/dist/mcp/client-tools.d.ts.map +1 -0
  79. package/dist/mcp/client-tools.js +147 -0
  80. package/dist/mcp/client-tools.js.map +1 -0
  81. package/dist/mcp/index.d.ts +16 -0
  82. package/dist/mcp/index.d.ts.map +1 -0
  83. package/dist/mcp/index.js +15 -0
  84. package/dist/mcp/index.js.map +1 -0
  85. package/dist/mcp/server-from-agent.d.ts +24 -0
  86. package/dist/mcp/server-from-agent.d.ts.map +1 -0
  87. package/dist/mcp/server-from-agent.js +113 -0
  88. package/dist/mcp/server-from-agent.js.map +1 -0
  89. package/dist/mcp/types.d.ts +64 -0
  90. package/dist/mcp/types.d.ts.map +1 -0
  91. package/dist/mcp/types.js +6 -0
  92. package/dist/mcp/types.js.map +1 -0
  93. package/dist/memory-embedding/index.d.ts +121 -0
  94. package/dist/memory-embedding/index.d.ts.map +1 -0
  95. package/dist/memory-embedding/index.js +229 -0
  96. package/dist/memory-embedding/index.js.map +1 -0
  97. package/dist/memory-extract.d.ts +60 -0
  98. package/dist/memory-extract.d.ts.map +1 -0
  99. package/dist/memory-extract.js +163 -0
  100. package/dist/memory-extract.js.map +1 -0
  101. package/dist/memory-inject.d.ts +39 -0
  102. package/dist/memory-inject.d.ts.map +1 -0
  103. package/dist/memory-inject.js +135 -0
  104. package/dist/memory-inject.js.map +1 -0
  105. package/dist/memory-orm/index.d.ts +118 -0
  106. package/dist/memory-orm/index.d.ts.map +1 -0
  107. package/dist/memory-orm/index.js +187 -0
  108. package/dist/memory-orm/index.js.map +1 -0
  109. package/dist/memory.d.ts +55 -0
  110. package/dist/memory.d.ts.map +1 -0
  111. package/dist/memory.js +132 -0
  112. package/dist/memory.js.map +1 -0
  113. package/dist/observers.d.ts +22 -0
  114. package/dist/observers.d.ts.map +1 -1
  115. package/dist/observers.js.map +1 -1
  116. package/dist/provider-tools.d.ts +15 -1
  117. package/dist/provider-tools.d.ts.map +1 -1
  118. package/dist/provider-tools.js +21 -1
  119. package/dist/provider-tools.js.map +1 -1
  120. package/dist/providers/anthropic.d.ts.map +1 -1
  121. package/dist/providers/anthropic.js +61 -6
  122. package/dist/providers/anthropic.js.map +1 -1
  123. package/dist/providers/elevenlabs.d.ts +98 -0
  124. package/dist/providers/elevenlabs.d.ts.map +1 -0
  125. package/dist/providers/elevenlabs.js +229 -0
  126. package/dist/providers/elevenlabs.js.map +1 -0
  127. package/dist/providers/google.d.ts +83 -1
  128. package/dist/providers/google.d.ts.map +1 -1
  129. package/dist/providers/google.js +491 -8
  130. package/dist/providers/google.js.map +1 -1
  131. package/dist/providers/openai.d.ts +3 -1
  132. package/dist/providers/openai.d.ts.map +1 -1
  133. package/dist/providers/openai.js +209 -5
  134. package/dist/providers/openai.js.map +1 -1
  135. package/dist/providers/voyage.d.ts +91 -0
  136. package/dist/providers/voyage.d.ts.map +1 -0
  137. package/dist/providers/voyage.js +166 -0
  138. package/dist/providers/voyage.js.map +1 -0
  139. package/dist/queue-job.d.ts +69 -4
  140. package/dist/queue-job.d.ts.map +1 -1
  141. package/dist/queue-job.js +114 -11
  142. package/dist/queue-job.js.map +1 -1
  143. package/dist/registry.d.ts +3 -1
  144. package/dist/registry.d.ts.map +1 -1
  145. package/dist/registry.js +10 -0
  146. package/dist/registry.js.map +1 -1
  147. package/dist/server/provider.d.ts.map +1 -1
  148. package/dist/server/provider.js +23 -1
  149. package/dist/server/provider.js.map +1 -1
  150. package/dist/similarity-search.d.ts +163 -0
  151. package/dist/similarity-search.d.ts.map +1 -0
  152. package/dist/similarity-search.js +147 -0
  153. package/dist/similarity-search.js.map +1 -0
  154. package/dist/tool.d.ts.map +1 -1
  155. package/dist/tool.js +13 -4
  156. package/dist/tool.js.map +1 -1
  157. package/dist/types.d.ts +246 -0
  158. package/dist/types.d.ts.map +1 -1
  159. package/dist/vector-stores/index.d.ts +96 -0
  160. package/dist/vector-stores/index.d.ts.map +1 -0
  161. package/dist/vector-stores/index.js +153 -0
  162. package/dist/vector-stores/index.js.map +1 -0
  163. package/package.json +41 -3
@@ -0,0 +1,163 @@
1
+ /**
2
+ * `similaritySearch({ model, column, embedWith, ... })` — agent-tool
3
+ * factory that wraps an `@rudderjs/orm` Model + a vector column into a
4
+ * drop-in `Tool` an agent can call to retrieve semantically similar
5
+ * rows (#B7 Phase 2).
6
+ *
7
+ * Composes B7 Phase 1's ORM primitives (`whereVectorSimilarTo` +
8
+ * `selectVectorDistance`) with `AI.embed()`. The model emits a
9
+ * natural-language `query`; the tool embeds it, runs a vector search,
10
+ * and returns the top-K rows ranked by similarity.
11
+ *
12
+ * @example
13
+ * ```ts
14
+ * import { similaritySearch } from '@rudderjs/ai'
15
+ * import { Document } from './app/Models/Document.js'
16
+ *
17
+ * class KnowledgeAgent extends Agent {
18
+ * tools() {
19
+ * return [
20
+ * similaritySearch({
21
+ * model: Document,
22
+ * column: 'embedding',
23
+ * embedWith: 'openai/text-embedding-3-small',
24
+ * minSimilarity: 0.7,
25
+ * limit: 10,
26
+ * }),
27
+ * ]
28
+ * }
29
+ * }
30
+ * ```
31
+ *
32
+ * Phase 2 limitations (lifted in Phase 2.5):
33
+ * - **Standalone queries only.** No `scope`/`.where()` chaining yet —
34
+ * the underlying `whereVectorSimilarTo` query must run alone. Agents
35
+ * see every row in the corpus that matches the vector. Phase 2.5
36
+ * adds a `scope: (q) => q.where(...)` callback.
37
+ * - **Cosine-centric similarity.** `similarity` is reported as
38
+ * `1 - distance` regardless of `metric`. For non-cosine metrics
39
+ * (`l2`, `inner-product`) the value is internally consistent with
40
+ * the `minSimilarity` filter applied by the adapter but isn't a
41
+ * meaningful normalized score on its own.
42
+ */
43
+ import type { ServerToolBuilder } from './tool.js';
44
+ /**
45
+ * Structural type for the model class similaritySearch accepts.
46
+ *
47
+ * Declared locally instead of importing `Model` from `@rudderjs/orm`
48
+ * so the main entry stays free of orm runtime — the tool calls
49
+ * `model.query()` and never references the `@rudderjs/orm` package
50
+ * itself. The user's app brings its own Model class.
51
+ */
52
+ export interface SimilaritySearchModel<TInstance> {
53
+ readonly name: string;
54
+ query(): SimilaritySearchQueryBuilder<TInstance>;
55
+ }
56
+ /**
57
+ * WhereOperator strings the `scope` callback may pass to `.where()`.
58
+ * Mirrors `@rudderjs/contracts`'s `WhereOperator`. Duplicated here so the
59
+ * main entry has no compile-time `@rudderjs/contracts` dep.
60
+ */
61
+ export type SimilaritySearchWhereOperator = '=' | '!=' | '>' | '>=' | '<' | '<=' | 'LIKE' | 'NOT LIKE' | 'IN' | 'NOT IN';
62
+ /**
63
+ * Structural type for the QueryBuilder methods similaritySearch needs.
64
+ * Mirrors a subset of `@rudderjs/contracts`'s `QueryBuilder<T>` so apps
65
+ * writing a `scope` callback get autocomplete on the methods that actually
66
+ * compose with `whereVectorSimilarTo` (#B7 Phase 2.5):
67
+ *
68
+ * - `.where()` / `.orWhere()` chains compose into the SQL with positional
69
+ * parameter binding.
70
+ * - `.with()` / `.orderBy()` / `.whereGroup()` / `.whereHas()` still throw
71
+ * when paired with a vector clause — out of scope for `scope`.
72
+ */
73
+ export interface SimilaritySearchQueryBuilder<TInstance> {
74
+ where(column: string, value: unknown): SimilaritySearchQueryBuilder<TInstance>;
75
+ where(column: string, operator: SimilaritySearchWhereOperator, value: unknown): SimilaritySearchQueryBuilder<TInstance>;
76
+ orWhere(column: string, value: unknown): SimilaritySearchQueryBuilder<TInstance>;
77
+ orWhere(column: string, operator: SimilaritySearchWhereOperator, value: unknown): SimilaritySearchQueryBuilder<TInstance>;
78
+ withTrashed?(): SimilaritySearchQueryBuilder<TInstance>;
79
+ onlyTrashed?(): SimilaritySearchQueryBuilder<TInstance>;
80
+ whereVectorSimilarTo?(column: string, query: number[] | string, opts?: {
81
+ metric?: 'cosine' | 'l2' | 'inner-product';
82
+ minSimilarity?: number;
83
+ embedWith?: string;
84
+ }): SimilaritySearchQueryBuilder<TInstance>;
85
+ selectVectorDistance?(column: string, query: number[], alias: string): SimilaritySearchQueryBuilder<TInstance>;
86
+ limit(n: number): SimilaritySearchQueryBuilder<TInstance>;
87
+ get(): Promise<TInstance[]>;
88
+ }
89
+ export interface SimilarityHit<TInstance> {
90
+ readonly row: TInstance;
91
+ /**
92
+ * Higher = closer. For `metric: 'cosine'` (default) this is
93
+ * `1 - distance` ∈ [-1, 1]. For other metrics see the JSDoc on
94
+ * {@link similaritySearch}.
95
+ */
96
+ readonly similarity: number;
97
+ }
98
+ export interface SimilaritySearchOptions<TInstance> {
99
+ /** The Model class whose rows will be searched. */
100
+ model: SimilaritySearchModel<TInstance>;
101
+ /** The column on `model` declared with the `vector({ dimensions })` cast. */
102
+ column: string;
103
+ /**
104
+ * Embedding model id (`<provider>/<model>`). Required — fails loud
105
+ * at factory construction time if missing so apps don't accidentally
106
+ * route to whatever `AiRegistry.getDefault()` happens to be.
107
+ */
108
+ embedWith: string;
109
+ /** Default `'cosine'`. */
110
+ metric?: 'cosine' | 'l2' | 'inner-product';
111
+ /**
112
+ * Drops rows whose `1 - distance` falls below this threshold. Cosine
113
+ * range is `[-1, 1]` so values near `0.7–0.9` are typical for
114
+ * "relevant" documents.
115
+ */
116
+ minSimilarity?: number;
117
+ /** Default `10`. */
118
+ limit?: number;
119
+ /**
120
+ * Pre-filter the query before the vector clause attaches. Receives a
121
+ * fresh `model.query()` builder; return the chained builder. Use for
122
+ * tenancy (`.where('tenantId', userId)`), publication state
123
+ * (`.where('published', true)`), or any flat predicate that should
124
+ * narrow the search corpus.
125
+ *
126
+ * **Phase 2.5 limits:** flat `.where()` / `.orWhere()` chains compose
127
+ * into the SQL. `whereGroup` / `whereHas` / `with()` still throw at
128
+ * terminal time — keep the scope flat.
129
+ *
130
+ * @example
131
+ * ```ts
132
+ * similaritySearch({
133
+ * model: KnowledgeArticle,
134
+ * column: 'embedding',
135
+ * embedWith: 'openai/text-embedding-3-small',
136
+ * scope: q => q.where('tenantId', currentTenant).where('published', true),
137
+ * })
138
+ * ```
139
+ */
140
+ scope?: (q: SimilaritySearchQueryBuilder<TInstance>) => SimilaritySearchQueryBuilder<TInstance>;
141
+ /**
142
+ * Override the tool name. Default
143
+ * `similarity_search_<model_name_lowercase>`.
144
+ */
145
+ name?: string;
146
+ /** Override the tool description. */
147
+ description?: string;
148
+ /**
149
+ * Custom string projection for each hit, replaces the default
150
+ * `(0.87) {"id":1,"content":"..."}` shape that the model sees on its
151
+ * next step. The structured array still flows to the UI via the
152
+ * `tool-result` chunk.
153
+ */
154
+ projectResult?: (row: TInstance, similarity: number) => string;
155
+ }
156
+ /**
157
+ * Build a `Tool` that embeds a natural-language query and returns the
158
+ * top-K similar rows from `model.column`.
159
+ */
160
+ export declare function similaritySearch<TInstance>(opts: SimilaritySearchOptions<TInstance>): ServerToolBuilder<{
161
+ query: string;
162
+ }, SimilarityHit<TInstance>[]>;
163
+ //# sourceMappingURL=similarity-search.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"similarity-search.d.ts","sourceRoot":"","sources":["../src/similarity-search.ts"],"names":[],"mappings":"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"}
@@ -0,0 +1,147 @@
1
+ /**
2
+ * `similaritySearch({ model, column, embedWith, ... })` — agent-tool
3
+ * factory that wraps an `@rudderjs/orm` Model + a vector column into a
4
+ * drop-in `Tool` an agent can call to retrieve semantically similar
5
+ * rows (#B7 Phase 2).
6
+ *
7
+ * Composes B7 Phase 1's ORM primitives (`whereVectorSimilarTo` +
8
+ * `selectVectorDistance`) with `AI.embed()`. The model emits a
9
+ * natural-language `query`; the tool embeds it, runs a vector search,
10
+ * and returns the top-K rows ranked by similarity.
11
+ *
12
+ * @example
13
+ * ```ts
14
+ * import { similaritySearch } from '@rudderjs/ai'
15
+ * import { Document } from './app/Models/Document.js'
16
+ *
17
+ * class KnowledgeAgent extends Agent {
18
+ * tools() {
19
+ * return [
20
+ * similaritySearch({
21
+ * model: Document,
22
+ * column: 'embedding',
23
+ * embedWith: 'openai/text-embedding-3-small',
24
+ * minSimilarity: 0.7,
25
+ * limit: 10,
26
+ * }),
27
+ * ]
28
+ * }
29
+ * }
30
+ * ```
31
+ *
32
+ * Phase 2 limitations (lifted in Phase 2.5):
33
+ * - **Standalone queries only.** No `scope`/`.where()` chaining yet —
34
+ * the underlying `whereVectorSimilarTo` query must run alone. Agents
35
+ * see every row in the corpus that matches the vector. Phase 2.5
36
+ * adds a `scope: (q) => q.where(...)` callback.
37
+ * - **Cosine-centric similarity.** `similarity` is reported as
38
+ * `1 - distance` regardless of `metric`. For non-cosine metrics
39
+ * (`l2`, `inner-product`) the value is internally consistent with
40
+ * the `minSimilarity` filter applied by the adapter but isn't a
41
+ * meaningful normalized score on its own.
42
+ */
43
+ import { z } from 'zod';
44
+ import { toolDefinition } from './tool.js';
45
+ import { AI } from './facade.js';
46
+ /** Internal alias used to read distance back off each row. */
47
+ const SIMILARITY_DISTANCE_ALIAS = '__rudderjs_similarity_distance__';
48
+ /**
49
+ * Build a `Tool` that embeds a natural-language query and returns the
50
+ * top-K similar rows from `model.column`.
51
+ */
52
+ export function similaritySearch(opts) {
53
+ const { model, column, embedWith, metric = 'cosine', minSimilarity, limit = 10, name, description, projectResult, scope, } = opts;
54
+ if (!embedWith || typeof embedWith !== 'string') {
55
+ throw new Error('[RudderJS AI] similaritySearch requires opts.embedWith (e.g. "openai/text-embedding-3-small"). ' +
56
+ 'No default — fail loud so embeddings never silently route through whichever provider happens to be the AI default.');
57
+ }
58
+ if (!column || typeof column !== 'string') {
59
+ throw new Error('[RudderJS AI] similaritySearch requires opts.column — the Model column declared with vector({ dimensions }).');
60
+ }
61
+ if (!model || typeof model.query !== 'function') {
62
+ throw new Error('[RudderJS AI] similaritySearch requires opts.model — a Model class with a static query() method.');
63
+ }
64
+ if (limit <= 0 || !Number.isFinite(limit)) {
65
+ throw new Error(`[RudderJS AI] similaritySearch limit must be a positive finite number; got ${String(limit)}.`);
66
+ }
67
+ const toolName = name ?? `similarity_search_${model.name.toLowerCase()}`;
68
+ const toolDescription = description ?? `Semantic search over ${model.name} records. Pass a natural-language \`query\` string; the most similar rows are returned.`;
69
+ return toolDefinition({
70
+ name: toolName,
71
+ description: toolDescription,
72
+ inputSchema: z.object({
73
+ query: z.string().min(1).describe('Natural-language query to search for.'),
74
+ }),
75
+ })
76
+ .server(async ({ query }) => {
77
+ const embedResult = await AI.embed(query, { model: embedWith });
78
+ const vector = embedResult.embeddings[0];
79
+ if (!vector || vector.length === 0) {
80
+ throw new Error(`[RudderJS AI] similaritySearch: AI.embed("${query}", { model: "${embedWith}" }) returned no embedding.`);
81
+ }
82
+ const baseQb = model.query();
83
+ const scopedQb = scope ? scope(baseQb) : baseQb;
84
+ const whereVec = scopedQb.whereVectorSimilarTo;
85
+ const selectDist = scopedQb.selectVectorDistance;
86
+ if (typeof whereVec !== 'function' || typeof selectDist !== 'function') {
87
+ throw new Error(`[RudderJS AI] similaritySearch: ${model.name}'s ORM adapter does not implement vector queries. ` +
88
+ 'Use @rudderjs/orm-prisma against a Postgres + pgvector connection.');
89
+ }
90
+ const vectorOpts = { metric };
91
+ if (minSimilarity !== undefined)
92
+ vectorOpts.minSimilarity = minSimilarity;
93
+ const filtered = whereVec.call(scopedQb, column, vector, vectorOpts);
94
+ const projected = selectDist.call(filtered, column, vector, SIMILARITY_DISTANCE_ALIAS);
95
+ const rows = await projected.limit(limit).get();
96
+ return rows.map((row) => {
97
+ const distance = readDistance(row);
98
+ return { row, similarity: 1 - distance };
99
+ });
100
+ })
101
+ .modelOutput((results) => {
102
+ if (results.length === 0) {
103
+ return `No similar ${model.name} records found.`;
104
+ }
105
+ if (projectResult) {
106
+ return results
107
+ .map(({ row, similarity }) => projectResult(row, similarity))
108
+ .join('\n');
109
+ }
110
+ return results
111
+ .map(({ row, similarity }) => {
112
+ const json = serializeRow(row);
113
+ return `(${similarity.toFixed(2)}) ${json}`;
114
+ })
115
+ .join('\n');
116
+ });
117
+ }
118
+ function readDistance(row) {
119
+ if (row === null || typeof row !== 'object')
120
+ return 0;
121
+ const raw = row[SIMILARITY_DISTANCE_ALIAS];
122
+ const n = typeof raw === 'number' ? raw : Number(raw);
123
+ return Number.isFinite(n) ? n : 0;
124
+ }
125
+ function serializeRow(row) {
126
+ if (row === null || typeof row !== 'object')
127
+ return JSON.stringify(row);
128
+ const candidate = row;
129
+ const toJSON = candidate.toJSON;
130
+ const data = typeof toJSON === 'function'
131
+ ? toJSON.call(candidate)
132
+ : sanitizeRow(row);
133
+ return JSON.stringify(data);
134
+ }
135
+ /**
136
+ * Strip the internal distance alias from rows whose `toJSON` we can't
137
+ * call (plain objects, fakes). `toJSON()`-bearing Models already
138
+ * filter their own internal fields.
139
+ */
140
+ function sanitizeRow(row) {
141
+ if (!(SIMILARITY_DISTANCE_ALIAS in row))
142
+ return row;
143
+ const { [SIMILARITY_DISTANCE_ALIAS]: _, ...rest } = row;
144
+ void _;
145
+ return rest;
146
+ }
147
+ //# sourceMappingURL=similarity-search.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"similarity-search.js","sourceRoot":"","sources":["../src/similarity-search.ts"],"names":[],"mappings":"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"}
@@ -1 +1 @@
1
- {"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"tool.d.ts","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"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"}
package/dist/tool.js CHANGED
@@ -80,11 +80,14 @@ export class ToolBuilder {
80
80
  }
81
81
  /** Convert to provider-friendly JSON Schema format */
82
82
  toSchema() {
83
- return {
83
+ const schema = {
84
84
  name: this.options.name,
85
85
  description: this.options.description,
86
- parameters: zodToJsonSchema(this.options.inputSchema),
86
+ parameters: this.options.jsonSchema ?? zodToJsonSchema(this.options.inputSchema),
87
87
  };
88
+ if (this.options.providerHint)
89
+ schema.providerHint = this.options.providerHint;
90
+ return schema;
88
91
  }
89
92
  }
90
93
  /**
@@ -157,10 +160,16 @@ export function dynamicTool(options) {
157
160
  }
158
161
  /** Convert any Tool to a ToolDefinitionSchema for provider consumption */
159
162
  export function toolToSchema(tool) {
160
- return {
163
+ const schema = {
161
164
  name: tool.definition.name,
162
165
  description: tool.definition.description,
163
- parameters: zodToJsonSchema(tool.definition.inputSchema),
166
+ parameters: tool.definition.jsonSchema ?? zodToJsonSchema(tool.definition.inputSchema),
164
167
  };
168
+ // Propagate provider-specific hints so adapters that recognize the
169
+ // `providerHint.type` can substitute their native tool block (see
170
+ // `toAnthropicTools` for computer-use, `toOpenAITools` for file-search).
171
+ if (tool.definition.providerHint)
172
+ schema.providerHint = tool.definition.providerHint;
173
+ return schema;
165
174
  }
166
175
  //# sourceMappingURL=tool.js.map
package/dist/tool.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"tool.js","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"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"}
1
+ {"version":3,"file":"tool.js","sourceRoot":"","sources":["../src/tool.ts"],"names":[],"mappings":"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"}