@rudderjs/ai 1.4.0 → 1.6.0

package/dist/fake.d.ts

@@ -1,4 +1,4 @@
-import type { ProviderRequestOptions, ImageGenerationOptions, TextToSpeechOptions, SpeechToTextOptions, RerankingOptions, RerankingResult, FileUploadResult, ToolCall, FinishReason } from './types.js';
+import type { ProviderRequestOptions, ImageGenerationOptions, TextToSpeechOptions, SpeechToTextOptions, RerankingOptions, RerankingResult, FileUploadResult, ToolCall, FinishReason, TokenUsage } from './types.js';
 /**
  * One scripted provider response in a multi-step agent loop.
  *
@@ -17,6 +17,12 @@ export interface AiFakeStep {
     text?: string;
     toolCalls?: ToolCall[];
     finishReason?: FinishReason;
+    /**
+     * Token usage to surface on the `'usage'` / `'finish'` chunks. Defaults
+     * to all zeros — fine for most tests, but middlewares that depend on
+     * realistic usage (e.g. budget enforcement) need this set.
+     */
+    usage?: TokenUsage;
 }
 /**
  * Testing fake for @rudderjs/ai.
@@ -122,6 +128,35 @@ export declare class AiFake {
     respondWithRanking(results: RerankingResult['results']): void;
     /** Set the file upload result the fake will return */
     respondWithFileUpload(result: FileUploadResult): void;
+    /**
+     * Stub a `fileSearch` interaction. The hosted-OpenAI path runs the
+     * search server-side and the result lands in the assistant message —
+     * no agent-loop tool round-trip — so the simplest fake is a single
+     * scripted response carrying the synthesized text.
+     *
+     * Pass `hits` to auto-format the text or pass `text` to control the
+     * exact assistant reply. `usage` flows through to budget middleware.
+     *
+     * @example
+     * fake.respondWithFileSearchResults({ text: 'The policy expires in 2027.' })
+     *
+     * @example
+     * fake.respondWithFileSearchResults({
+     *   hits: [
+     *     { text: 'Policies are reviewed annually.', source: 'policy.pdf', score: 0.92 },
+     *     { text: 'The renewal date is March 1st.',   source: 'renewal.pdf', score: 0.88 },
+     *   ],
+     * })
+     */
+    respondWithFileSearchResults(opts: {
+        text?: string;
+        hits?: Array<{
+            text: string;
+            source?: string;
+            score?: number;
+        }>;
+        usage?: TokenUsage;
+    }): void;
     /** Install the fake — replaces all registered providers with a mock */
     static fake(): AiFake;
     /** Assert at least one prompt was sent, optionally matching a predicate */

package/dist/fake.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"fake.d.ts","sourceRoot":"","sources":["../src/fake.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"fake.d.ts","sourceRoot":"","sources":["../src/fake.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAGV,sBAAsB,EAMtB,sBAAsB,EAGtB,mBAAmB,EAGnB,mBAAmB,EAGnB,gBAAgB,EAChB,eAAe,EAGf,gBAAgB,EAGhB,QAAQ,EACR,YAAY,EACZ,UAAU,EACX,MAAM,YAAY,CAAA;AAEnB;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAA;IACtB,YAAY,CAAC,EAAE,YAAY,CAAA;IAC3B;;;;OAIG;IACH,KAAK,CAAC,EAAE,UAAU,CAAA;CACnB;AAED;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,qBAAa,MAAM;IACjB,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA+B;IACrD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAA+B;IAC1D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;IACrD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA4B;IACrD,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAyD;IACpF,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAyB;IACrD,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA+C;IACzE,OAAO,CAAC,SAAS,CAAkB;IACnC,OAAO,CAAC,SAAS,CAAmB;IACpC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAA2B;IACrD,OAAO,CAAC,aAAa,CAAQ;IAC7B,OAAO,CAAC,cAAc,CAAqB;IAC3C,OAAO,CAAC,YAAY,CAAoC;IACxD,OAAO,CAAC,YAAY,CAAuB;IAC3C,OAAO,CAAC,cAAc,CAAgC;IACtD,OAAO,CAAC,eAAe,CAAmC;IAC1D,OAAO,CAAC,mBAAmB,CAA2E;IAEtG,iDAAiD;IACjD,WAAW,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI/B;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,mBAAmB,IAAI,IAAI;IAK3B;;;;;;;;;;;;;OAaG;IACH,mBAAmB,CAAC,KAAK,EAAE,UAAU,EAAE,GAAG,IAAI;IAK9C;;;;;;;;OAQG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,KAAK,GAAG,IAAI;IAIjD,gDAAgD;IAChD,gBAAgB,CAAC,MAAM,EAAE,MAAM,GAAG,IAAI;IAItC,oDAAoD;IACpD,gBAAgB,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAIrC,0DAA0D;IAC1D,wBAAwB,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAI5C,8CAA8C;IAC9C,oBAAoB,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,GAAG,IAAI;IAIlD,qDAAqD;IACrD,kBAAkB,CAAC,OAAO,EAAE,eAAe,CAAC,SAAS,CAAC,GAAG,IAAI;IAI7D,sDAAsD;IACtD,qBAAqB,CAAC,MAAM,EAAE,gBAAgB,GAAG,IAAI;IAIrD;;;;;;;;;;;;;;;;;;;OAmBG;IACH,4BAA4B,CAAC,IAAI,EAAE;QACjC,IAAI,CAAC,EAAG,MAAM,CAAA;QACd,IAAI,CAAC,EAAG,KAAK,CAAC;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,MAAM,CAAC,EAAE,MAAM,CAAC;YAAC,KAAK,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;QAChE,KAAK,CAAC,EAAE,UAAU,CAAA;KACnB,GAAG,IAAI;IAOR,uEAAuE;IACvE,MAAM,CAAC,IAAI,IAAI,MAAM;IA+IrB,2EAA2E;IAC3E,cAAc,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,KAAK,OAAO,GAAG,IAAI;IAa5D,kCAAkC;IAClC,qBAAqB,IAAI,IAAI;IAM7B,oDAAoD;IACpD,oBAAoB,CAAC,SAAS,CAAC,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,GAAG,IAAI;IAQnE,kDAAkD;IAClD,oBAAoB,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,GAAG,IAAI;IAQjE,iDAAiD;IACjD,iBAAiB,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,mBAAmB,KAAK,OAAO,GAAG,IAAI;IAQ3E,sCAAsC;IACtC,QAAQ,IAAI,sBAAsB,EAAE;IAIpC,8CAA8C;IAC9C,aAAa,IAAI,sBAAsB,EAAE;IAIzC,iCAAiC;IACjC,WAAW,IAAI,mBAAmB,EAAE;IAIpC,iCAAiC;IACjC,WAAW,IAAI,mBAAmB,EAAE;IAIpC,6CAA6C;IAC7C,cAAc,CAAC,SAAS,CAAC,EAAE,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,KAAK,OAAO,GAAG,IAAI;IAQvE,6CAA6C;IAC7C,cAAc,CAAC,SAAS,CAAC,EAAE,CAAC,IAAI,EAAE,gBAAgB,KAAK,OAAO,GAAG,IAAI;IAQrE,uCAAuC;IACvC,aAAa,IAAI,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAInE,uCAAuC;IACvC,cAAc,IAAI,gBAAgB,EAAE;IAIpC,+CAA+C;IAC/C,kBAAkB,CAAC,SAAS,CAAC,EAAE,CAAC,QAAQ,EAAE,MAAM,KAAK,OAAO,GAAG,IAAI;IASnE,4CAA4C;IAC5C,YAAY,IAAI,KAAK,CAAC;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC;IAIxD,uEAAuE;IACvE,OAAO,IAAI,IAAI;CAGhB"}

package/dist/fake.js

@@ -125,6 +125,33 @@ export class AiFake {
     respondWithFileUpload(result) {
         this._fileUploadResponse = result;
     }
+    /**
+     * Stub a `fileSearch` interaction. The hosted-OpenAI path runs the
+     * search server-side and the result lands in the assistant message —
+     * no agent-loop tool round-trip — so the simplest fake is a single
+     * scripted response carrying the synthesized text.
+     *
+     * Pass `hits` to auto-format the text or pass `text` to control the
+     * exact assistant reply. `usage` flows through to budget middleware.
+     *
+     * @example
+     * fake.respondWithFileSearchResults({ text: 'The policy expires in 2027.' })
+     *
+     * @example
+     * fake.respondWithFileSearchResults({
+     *   hits: [
+     *     { text: 'Policies are reviewed annually.', source: 'policy.pdf', score: 0.92 },
+     *     { text: 'The renewal date is March 1st.',   source: 'renewal.pdf', score: 0.88 },
+     *   ],
+     * })
+     */
+    respondWithFileSearchResults(opts) {
+        const text = opts.text ?? formatFileSearchHits(opts.hits ?? []);
+        const step = { text };
+        if (opts.usage)
+            step.usage = opts.usage;
+        this.respondWithSequence([step]);
+    }
     /** Install the fake — replaces all registered providers with a mock */
     static fake() {
         const fake = new AiFake();
@@ -145,7 +172,7 @@ export class AiFake {
                             content: next.text ?? '',
                             ...(next.toolCalls ? { toolCalls: next.toolCalls } : {}),
                         },
-                        usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+                        usage: next.usage ?? { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
                         finishReason: next.finishReason ?? (next.toolCalls ? 'tool_calls' : 'stop'),
                     };
                 }
@@ -174,7 +201,7 @@ export class AiFake {
                     yield {
                         type: 'finish',
                         finishReason: next.finishReason ?? (next.toolCalls ? 'tool_calls' : 'stop'),
-                        usage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
+                        usage: next.usage ?? { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
                     };
                     return;
                 }
@@ -378,4 +405,24 @@ export class AiFake {
         AiRegistry.reset();
     }
 }
+/**
+ * Render canned file-search hits into a prose assistant reply for
+ * {@link AiFake.respondWithFileSearchResults}. Keeps tests readable
+ * without each app having to ad-hoc its own formatter.
+ */
+function formatFileSearchHits(hits) {
+    if (hits.length === 0)
+        return 'No relevant documents found.';
+    return hits
+        .map(h => {
+        const parts = [];
+        if (h.score !== undefined)
+            parts.push(`(${h.score.toFixed(2)})`);
+        parts.push(h.text);
+        if (h.source)
+            parts.push(`— ${h.source}`);
+        return parts.join(' ');
+    })
+        .join('\n');
+}
 //# sourceMappingURL=fake.js.map

package/dist/fake.js.map

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

package/dist/file-search.d.ts

@@ -0,0 +1,168 @@
+/**
+ * `fileSearch({ stores, where?, maxResults?, name?, description? })` — agent
+ * tool factory for hosted vector-store retrieval (#B8 Phase 2).
+ *
+ * Wraps OpenAI's native `file_search` tool. The tool object is tagged with
+ * `providerHint: { type: 'file-search', ... }`; the OpenAI adapter's
+ * `toOpenAITools` recognizes the hint and emits the native
+ * `{ type: 'file_search', vector_store_ids, filters, max_num_results }`
+ * block instead of a generic function-call shape. The model runs the search
+ * server-side and the results land in the assistant message — no agent-loop
+ * tool round-trip on the hosted path.
+ *
+ * # Hosted on OpenAI today
+ *
+ * Other providers see the tool as a regular function-call tool with the
+ * placeholder `{ query: string }` schema — without an `execute` they pause
+ * for client tools, which is degraded. Phase 3 will add a `fallback` opt
+ * that installs an `execute` delegating to `similaritySearch` over a local
+ * pgvector model.
+ *
+ * # Wiring
+ *
+ * ```ts
+ * import { Agent, fileSearch, VectorStores } from '@rudderjs/ai'
+ *
+ * const kb = await VectorStores.get('vs_abc123')
+ *
+ * class SupportAgent extends Agent {
+ *   model() { return 'openai/gpt-4o' }
+ *   tools() {
+ *     return [
+ *       fileSearch({
+ *         stores:     [kb.id],
+ *         where:      { author: 'Alice', year: 2026 },
+ *         maxResults: 10,
+ *       }),
+ *     ]
+ *   }
+ * }
+ * ```
+ *
+ * # Metadata filter sugar
+ *
+ * `where: { author: 'Alice', year: 2026 }` is shorthand for the typed
+ * OpenAI filter shape `{ type: 'and', filters: [{ type: 'eq', key: 'author',
+ * value: 'Alice' }, { type: 'eq', key: 'year', value: 2026 }] }`. Either
+ * shape works — pass the typed object form for `gt` / `lt` / `or`.
+ */
+import type { SimilaritySearchOptions } from './similarity-search.js';
+import type { Tool, ToolDefinitionOptions, ToolDefinitionSchema } from './types.js';
+/**
+ * Symbol-tagged marker identifying a file-search tool. Mirrors the
+ * `COMPUTER_USE_MARKER` pattern — `Symbol.for(...)` so cross-bundle /
+ * cross-realm checks succeed even when `@rudderjs/ai` loads twice.
+ */
+export declare const FILE_SEARCH_MARKER: unique symbol;
+/**
+ * Default tool name. OpenAI's native `file_search` tool expects calls to
+ * land on a tool literally named `file_search` — the model is trained on
+ * that identifier. Apps can override via `opts.name` but usually shouldn't.
+ */
+export declare const FILE_SEARCH_TOOL_NAME = "file_search";
+/** OpenAI vector-store metadata filter, typed form. */
+export type FileSearchFilter = {
+    type: 'eq' | 'ne' | 'gt' | 'gte' | 'lt' | 'lte';
+    key: string;
+    value: string | number | boolean;
+} | {
+    type: 'and' | 'or';
+    filters: FileSearchFilter[];
+};
+/** Sugar shape for `where` — `{ key: value }` pairs lowered to a typed `and` of `eq` filters. */
+export type FileSearchWhereSugar = Record<string, string | number | boolean>;
+/**
+ * Local pgvector fallback configuration (#B8 Phase 3). When set, the tool
+ * gains an `execute` that delegates to {@link similaritySearch} against
+ * the supplied Model. Forwards every {@link SimilaritySearchOptions} field
+ * except `name` / `description` (those flow from the outer `fileSearch`
+ * call so the agent prompt stays identical across providers).
+ */
+export type FileSearchFallback<TInstance = unknown> = Omit<SimilaritySearchOptions<TInstance>, 'name' | 'description'>;
+export interface FileSearchOptions<TInstance = unknown> {
+    /**
+     * Vector-store IDs the model should search. At least one required.
+     * Mixing providers (e.g. an OpenAI `vs_...` id with a Gemini cached-
+     * content id) is not supported in v1 — every id must come from the
+     * agent's configured provider.
+     */
+    stores: string[];
+    /**
+     * Metadata filter applied server-side. Accepts either the sugar
+     * `{ key: value }` form (lowered to an `and` of `eq` filters) or the
+     * typed {@link FileSearchFilter} shape directly.
+     */
+    where?: FileSearchWhereSugar | FileSearchFilter;
+    /** Maximum number of result chunks to return. Provider default applies when unset. */
+    maxResults?: number;
+    /** Override the tool name. Defaults to {@link FILE_SEARCH_TOOL_NAME}. */
+    name?: string;
+    /** Override the tool description shown to the model. Defaults to a generic phrasing. */
+    description?: string;
+    /**
+     * Local pgvector fallback (#B8 Phase 3). When set, the returned tool gains
+     * an `execute` that delegates to `similaritySearch` for providers that
+     * don't recognize the `'file-search'` `providerHint`.
+     *
+     * The cascade is automatic. On OpenAI the adapter emits the native
+     * `file_search` block — the search runs server-side, the model never
+     * invokes the function-call tool, and `execute` is dead weight. On any
+     * other provider (Anthropic, Gemini today, others) the tool serializes
+     * as a regular function-call schema, the model calls it, and `execute`
+     * delegates to `similaritySearch` against the local pgvector model.
+     *
+     * Same agent prompt across hosted and self-hosted RAG — ops can swap
+     * deployment targets without retraining.
+     *
+     * @example
+     * ```ts
+     * fileSearch({
+     *   stores: [vs_id],
+     *   fallback: {
+     *     model:     Document,
+     *     column:    'embedding',
+     *     embedWith: 'openai/text-embedding-3-small',
+     *   },
+     * })
+     * ```
+     */
+    fallback?: FileSearchFallback<TInstance>;
+}
+/**
+ * A `fileSearch` tool. Implements {@link Tool}; carries
+ * {@link FILE_SEARCH_MARKER} for typeguarding.
+ *
+ * `execute` is absent on the hosted-only path (no `fallback` opt) — the
+ * provider runs the search natively and the model gets results back
+ * inline. With a `fallback` opt configured (#B8 Phase 3), `execute` is
+ * present and delegates to `similaritySearch` so non-native providers
+ * (Anthropic, Gemini today, others) get a working RAG path against a
+ * local pgvector model.
+ */
+export interface FileSearchTool extends Tool<{
+    query: string;
+}, unknown> {
+    readonly [FILE_SEARCH_MARKER]: true;
+    readonly definition: ToolDefinitionOptions;
+    toSchema(): ToolDefinitionSchema;
+}
+/** Build the agent tool. See module JSDoc for usage. */
+export declare function fileSearch<TInstance = unknown>(opts: FileSearchOptions<TInstance>): FileSearchTool;
+/**
+ * Structural typeguard. Mirrors `isComputerUseTool` / `isHandoffTool` —
+ * tools are plain objects tagged with `Symbol.for(...)` markers so the
+ * loop and adapters can detect them without coupling to a class.
+ */
+export declare function isFileSearchTool(t: unknown): t is FileSearchTool;
+/**
+ * Lower the user-friendly `where` shape to OpenAI's typed filter object.
+ *
+ * - `{ author: 'Alice', year: 2026 }` → `{ type: 'and', filters: [eq, eq] }`
+ * - `{ type: 'eq' | ... }`           → pass-through
+ * - `{ type: 'and' | 'or', filters }` → pass-through
+ *
+ * A single-key sugar object short-circuits to the bare `eq` (no `and`
+ * wrapper), matching OpenAI's recommended shape.
+ */
+export declare function normalizeWhere(where: FileSearchWhereSugar | FileSearchFilter): FileSearchFilter;
+//# sourceMappingURL=file-search.d.ts.map

package/dist/file-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-search.d.ts","sourceRoot":"","sources":["../src/file-search.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA+CG;AAKH,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,wBAAwB,CAAA;AACrE,OAAO,KAAK,EAAgB,IAAI,EAAE,qBAAqB,EAAE,oBAAoB,EAAiB,MAAM,YAAY,CAAA;AAEhH;;;;GAIG;AACH,eAAO,MAAM,kBAAkB,EAAE,OAAO,MAA8C,CAAA;AAEtF;;;;GAIG;AACH,eAAO,MAAM,qBAAqB,gBAAgB,CAAA;AAMlD,uDAAuD;AACvD,MAAM,MAAM,gBAAgB,GACxB;IAAE,IAAI,EAAE,IAAI,GAAG,IAAI,GAAG,IAAI,GAAG,KAAK,GAAG,IAAI,GAAG,KAAK,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAA;CAAE,GAClG;IAAE,IAAI,EAAE,KAAK,GAAG,IAAI,CAAC;IAAC,OAAO,EAAE,gBAAgB,EAAE,CAAA;CAAE,CAAA;AAEvD,iGAAiG;AACjG,MAAM,MAAM,oBAAoB,GAAG,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC,CAAA;AAE5E;;;;;;GAMG;AACH,MAAM,MAAM,kBAAkB,CAAC,SAAS,GAAG,OAAO,IAChD,IAAI,CAAC,uBAAuB,CAAC,SAAS,CAAC,EAAE,MAAM,GAAG,aAAa,CAAC,CAAA;AAElE,MAAM,WAAW,iBAAiB,CAAC,SAAS,GAAG,OAAO;IACpD;;;;;OAKG;IACH,MAAM,EAAE,MAAM,EAAE,CAAA;IAChB;;;;OAIG;IACH,KAAK,CAAC,EAAE,oBAAoB,GAAG,gBAAgB,CAAA;IAC/C,sFAAsF;IACtF,UAAU,CAAC,EAAE,MAAM,CAAA;IACnB,yEAAyE;IACzE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,wFAAwF;IACxF,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,QAAQ,CAAC,EAAE,kBAAkB,CAAC,SAAS,CAAC,CAAA;CACzC;AAED;;;;;;;;;;GAUG;AACH,MAAM,WAAW,cAAe,SAAQ,IAAI,CAAC;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,EAAE,OAAO,CAAC;IACtE,QAAQ,CAAC,CAAC,kBAAkB,CAAC,EAAE,IAAI,CAAA;IACnC,QAAQ,CAAC,UAAU,EAAE,qBAAqB,CAAA;IAC1C,QAAQ,IAAI,oBAAoB,CAAA;CACjC;AAED,wDAAwD;AACxD,wBAAgB,UAAU,CAAC,SAAS,GAAG,OAAO,EAAE,IAAI,EAAE,iBAAiB,CAAC,SAAS,CAAC,GAAG,cAAc,CA4DlG;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,cAAc,CAIhE;AAED;;;;;;;;;GASG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,oBAAoB,GAAG,gBAAgB,GAAG,gBAAgB,CAS/F"}

package/dist/file-search.js

@@ -0,0 +1,158 @@
+/**
+ * `fileSearch({ stores, where?, maxResults?, name?, description? })` — agent
+ * tool factory for hosted vector-store retrieval (#B8 Phase 2).
+ *
+ * Wraps OpenAI's native `file_search` tool. The tool object is tagged with
+ * `providerHint: { type: 'file-search', ... }`; the OpenAI adapter's
+ * `toOpenAITools` recognizes the hint and emits the native
+ * `{ type: 'file_search', vector_store_ids, filters, max_num_results }`
+ * block instead of a generic function-call shape. The model runs the search
+ * server-side and the results land in the assistant message — no agent-loop
+ * tool round-trip on the hosted path.
+ *
+ * # Hosted on OpenAI today
+ *
+ * Other providers see the tool as a regular function-call tool with the
+ * placeholder `{ query: string }` schema — without an `execute` they pause
+ * for client tools, which is degraded. Phase 3 will add a `fallback` opt
+ * that installs an `execute` delegating to `similaritySearch` over a local
+ * pgvector model.
+ *
+ * # Wiring
+ *
+ * ```ts
+ * import { Agent, fileSearch, VectorStores } from '@rudderjs/ai'
+ *
+ * const kb = await VectorStores.get('vs_abc123')
+ *
+ * class SupportAgent extends Agent {
+ *   model() { return 'openai/gpt-4o' }
+ *   tools() {
+ *     return [
+ *       fileSearch({
+ *         stores:     [kb.id],
+ *         where:      { author: 'Alice', year: 2026 },
+ *         maxResults: 10,
+ *       }),
+ *     ]
+ *   }
+ * }
+ * ```
+ *
+ * # Metadata filter sugar
+ *
+ * `where: { author: 'Alice', year: 2026 }` is shorthand for the typed
+ * OpenAI filter shape `{ type: 'and', filters: [{ type: 'eq', key: 'author',
+ * value: 'Alice' }, { type: 'eq', key: 'year', value: 2026 }] }`. Either
+ * shape works — pass the typed object form for `gt` / `lt` / `or`.
+ */
+import { z } from 'zod';
+import { similaritySearch } from './similarity-search.js';
+/**
+ * Symbol-tagged marker identifying a file-search tool. Mirrors the
+ * `COMPUTER_USE_MARKER` pattern — `Symbol.for(...)` so cross-bundle /
+ * cross-realm checks succeed even when `@rudderjs/ai` loads twice.
+ */
+export const FILE_SEARCH_MARKER = Symbol.for('rudderjs.ai.file-search');
+/**
+ * Default tool name. OpenAI's native `file_search` tool expects calls to
+ * land on a tool literally named `file_search` — the model is trained on
+ * that identifier. Apps can override via `opts.name` but usually shouldn't.
+ */
+export const FILE_SEARCH_TOOL_NAME = 'file_search';
+const DEFAULT_DESCRIPTION = 'Search the configured knowledge base(s) for documents relevant to the query. ' +
+    'Returns the most relevant passages alongside the source document metadata.';
+/** Build the agent tool. See module JSDoc for usage. */
+export function fileSearch(opts) {
+    if (!Array.isArray(opts.stores) || opts.stores.length === 0) {
+        throw new Error('[RudderJS AI] fileSearch({ stores }) requires at least one vector-store id. ' +
+            'Create a store via `VectorStores.create(...)` and pass its `id`.');
+    }
+    const name = opts.name ?? FILE_SEARCH_TOOL_NAME;
+    const description = opts.description ?? DEFAULT_DESCRIPTION;
+    const filters = opts.where !== undefined ? normalizeWhere(opts.where) : undefined;
+    // The provider hint is the load-bearing piece — adapters recognizing
+    // `type === 'file-search'` substitute their native tool block.
+    const providerHint = { type: 'file-search', vector_store_ids: opts.stores };
+    if (filters)
+        providerHint['filters'] = filters;
+    if (opts.maxResults !== undefined)
+        providerHint['max_num_results'] = opts.maxResults;
+    const definition = {
+        name,
+        description,
+        // Placeholder schema. Non-OpenAI providers see this and treat the
+        // tool as a normal function-call. OpenAI's native block drops it.
+        inputSchema: z.object({ query: z.string().describe('Natural-language query.') }),
+        providerHint,
+    };
+    // Build the fallback execute when configured. The inner similaritySearch
+    // tool's name/description are overridden so structural identity stays on
+    // the outer fileSearch (the model still sees the same tool and prompt).
+    let execute;
+    let toModelOutput;
+    if (opts.fallback) {
+        const inner = similaritySearch({
+            ...opts.fallback,
+            name,
+            description,
+        });
+        execute = inner.execute;
+        toModelOutput = inner.toModelOutput;
+    }
+    const tool = {
+        [FILE_SEARCH_MARKER]: true,
+        definition,
+        ...(execute ? { execute } : {}),
+        ...(toModelOutput ? { toModelOutput } : {}),
+        toSchema() {
+            const schema = {
+                name,
+                description,
+                parameters: { type: 'object', properties: { query: { type: 'string' } }, required: ['query'] },
+                providerHint,
+            };
+            return schema;
+        },
+    };
+    return tool;
+}
+/**
+ * Structural typeguard. Mirrors `isComputerUseTool` / `isHandoffTool` —
+ * tools are plain objects tagged with `Symbol.for(...)` markers so the
+ * loop and adapters can detect them without coupling to a class.
+ */
+export function isFileSearchTool(t) {
+    if (t === null || typeof t !== 'object')
+        return false;
+    const marker = t[FILE_SEARCH_MARKER];
+    return marker === true;
+}
+/**
+ * Lower the user-friendly `where` shape to OpenAI's typed filter object.
+ *
+ * - `{ author: 'Alice', year: 2026 }` → `{ type: 'and', filters: [eq, eq] }`
+ * - `{ type: 'eq' | ... }`           → pass-through
+ * - `{ type: 'and' | 'or', filters }` → pass-through
+ *
+ * A single-key sugar object short-circuits to the bare `eq` (no `and`
+ * wrapper), matching OpenAI's recommended shape.
+ */
+export function normalizeWhere(where) {
+    if (isTypedFilter(where))
+        return where;
+    const entries = Object.entries(where);
+    if (entries.length === 0) {
+        throw new Error('[RudderJS AI] fileSearch({ where }) must contain at least one key.');
+    }
+    const eqs = entries.map(([key, value]) => ({ type: 'eq', key, value }));
+    return eqs.length === 1 ? eqs[0] : { type: 'and', filters: eqs };
+}
+function isTypedFilter(w) {
+    if (typeof w !== 'object' || w === null)
+        return false;
+    const t = w.type;
+    return typeof t === 'string'
+        && (t === 'eq' || t === 'ne' || t === 'gt' || t === 'gte' || t === 'lt' || t === 'lte' || t === 'and' || t === 'or');
+}
+//# sourceMappingURL=file-search.js.map

package/dist/file-search.js.map

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

package/dist/handoff.d.ts

@@ -0,0 +1,95 @@
+import { z } from 'zod';
+import type { ToolDefinitionOptions, ToolDefinitionSchema } from './types.js';
+import type { Agent } from './agent.js';
+/**
+ * Symbol-tagged marker identifying a handoff tool. Looked up via
+ * `Symbol.for(...)` so cross-bundle / cross-realm checks succeed even when
+ * `@rudderjs/ai` is loaded twice (rare, but possible in monorepo + linked
+ * setups).
+ */
+export declare const HANDOFF_MARKER: unique symbol;
+/**
+ * Internal spec attached to a handoff tool. The agent loop reads this when
+ * it sees a tool call that lands on a `HandoffTool` — it does NOT execute
+ * the tool's body (there isn't one). Instead it short-circuits the loop,
+ * synthesizes a tool result, and pivots control to a new instance of
+ * `AgentClass` for the rest of the conversation.
+ */
+export interface HandoffSpec {
+    readonly AgentClass: new (...args: unknown[]) => Agent;
+    readonly name: string;
+    readonly description: string;
+    readonly inputSchema: z.ZodType;
+}
+/**
+ * A tool returned by {@link handoff}. The loop recognizes it via the
+ * `HANDOFF_MARKER` symbol property and treats it as a control-transfer,
+ * not a normal server tool. Its `execute` is intentionally absent.
+ */
+export interface HandoffTool {
+    readonly [HANDOFF_MARKER]: true;
+    readonly __handoffSpec: HandoffSpec;
+    readonly definition: ToolDefinitionOptions;
+    readonly execute?: undefined;
+    toSchema(): ToolDefinitionSchema;
+}
+/**
+ * Options for {@link handoff}. All fields optional — by default, a handoff
+ * tool is named `handoffTo${AgentClass.name}` and accepts a single
+ * `message: string` argument that becomes the transition prompt seen by
+ * the new agent as its first user message.
+ */
+export interface HandoffOptions<TInput extends z.ZodType = z.ZodType> {
+    /** Override the tool name. Default: `handoffTo${AgentClass.name}`. */
+    name?: string;
+    /**
+     * Trigger guidance — a short phrase appended to the description so the
+     * model knows when to pick this handoff. Example: `'pricing or sales'`
+     * → "Hand off the conversation to SalesAgent for pricing or sales."
+     */
+    when?: string;
+    /** Override the entire description. If set, takes precedence over `when`. */
+    description?: string;
+    /**
+     * Zod schema for the handoff payload. Defaults to
+     * `z.object({ message: z.string() })` — the parent's model writes a
+     * transition prompt that becomes the child's first user message.
+     *
+     * Custom schemas are supported but the loop reads `args.message` (string)
+     * as the transition prompt. Schemas without a `message` string field will
+     * pass an empty transition message; the carried conversation history is
+     * still surfaced to the child.
+     */
+    inputSchema?: TInput;
+}
+/**
+ * Define a handoff tool — a control-transfer tool the parent agent's model
+ * can call to pivot the conversation to another agent. After the model
+ * calls it, the parent's loop ends and the child agent runs from the same
+ * message history with its own instructions, tools, and model.
+ *
+ * Distinct from {@link Agent.asTool} (which is call-and-return: the parent
+ * resumes after the child finishes and incorporates the child's text as a
+ * tool result). Handoffs do not return — the child owns the rest of the
+ * conversation.
+ *
+ * @example
+ * ```ts
+ * class TriageAgent extends Agent {
+ *   tools() {
+ *     return [
+ *       handoff(SalesAgent,    { when: 'pricing or sales questions' }),
+ *       handoff(SupportAgent,  { when: 'bug reports or technical issues' }),
+ *     ]
+ *   }
+ * }
+ * ```
+ */
+export declare function handoff(AgentClass: new (...args: never[]) => Agent, opts?: HandoffOptions): HandoffTool;
+/**
+ * Structural typeguard. Used by the agent loop to detect handoff tools
+ * without coupling to a class hierarchy — handoff tools are plain objects
+ * tagged with the {@link HANDOFF_MARKER} symbol.
+ */
+export declare function isHandoffTool(t: unknown): t is HandoffTool;
+//# sourceMappingURL=handoff.d.ts.map

package/dist/handoff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handoff.d.ts","sourceRoot":"","sources":["../src/handoff.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AAEvB,OAAO,KAAK,EAAE,qBAAqB,EAAE,oBAAoB,EAAE,MAAM,YAAY,CAAA;AAC7E,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,YAAY,CAAA;AAEvC;;;;;GAKG;AACH,eAAO,MAAM,cAAc,EAAE,OAAO,MAA0C,CAAA;AAE9E;;;;;;GAMG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,UAAU,EAAE,KAAK,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,KAAK,CAAA;IACtD,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;IAC5B,QAAQ,CAAC,WAAW,EAAE,CAAC,CAAC,OAAO,CAAA;CAChC;AAED;;;;GAIG;AACH,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,CAAC,cAAc,CAAC,EAAE,IAAI,CAAA;IAC/B,QAAQ,CAAC,aAAa,EAAE,WAAW,CAAA;IACnC,QAAQ,CAAC,UAAU,EAAE,qBAAqB,CAAA;IAC1C,QAAQ,CAAC,OAAO,CAAC,EAAE,SAAS,CAAA;IAC5B,QAAQ,IAAI,oBAAoB,CAAA;CACjC;AAED;;;;;GAKG;AACH,MAAM,WAAW,cAAc,CAAC,MAAM,SAAS,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO;IAClE,sEAAsE;IACtE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb;;;;OAIG;IACH,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,6EAA6E;IAC7E,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB;;;;;;;;;OASG;IACH,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAQD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,OAAO,CACrB,UAAU,EAAE,KAAK,GAAG,IAAI,EAAE,KAAK,EAAE,KAAK,KAAK,EAC3C,IAAI,CAAC,EAAE,cAAc,GACpB,WAAW,CA0Bb;AAOD;;;;GAIG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,OAAO,GAAG,CAAC,IAAI,WAAW,CAI1D"}