exa-js 2.23.0 → 2.25.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.
package/dist/index.mjs CHANGED
@@ -4,7 +4,7 @@ import fetch2, { Headers } from "cross-fetch";
4
4
  // package.json
5
5
  var package_default = {
6
6
  name: "exa-js",
7
- version: "2.23.0",
7
+ version: "2.25.0",
8
8
  description: "Exa SDK for Node.js and the browser",
9
9
  publishConfig: {
10
10
  access: "public"
@@ -2331,6 +2331,8 @@ var WebsetsClient = class extends WebsetsBaseClient {
2331
2331
  import { z } from "zod";
2332
2332
  var DEFAULT_WEB_SEARCH_TOOL_DESCRIPTION = "Search the web for up-to-date, relevant information. Describe the ideal page rather than listing keywords.";
2333
2333
  var DEFAULT_GET_CONTENTS_TOOL_DESCRIPTION = "Read the full contents of web pages you already have URLs for, such as pages returned by a search or mentioned by the user.";
2334
+ var SEARCH_OBJECTIVE_TOOL_DESCRIPTION = "Goal for this search turn; say which documents should rank first, which should be excluded, and what specific facts or figures to pull from them.";
2335
+ var MAX_OBJECTIVE_LENGTH = 4096;
2334
2336
  function formatResults(response, emptyMessage) {
2335
2337
  const formatted = response.results.map((result) => {
2336
2338
  const lines = [
@@ -2384,6 +2386,17 @@ function createTool(registry, params) {
2384
2386
  };
2385
2387
  return registerTool(registry, tool);
2386
2388
  }
2389
+ var AdvertisedRequiredOptional = class extends z.ZodOptional {
2390
+ isOptional() {
2391
+ return false;
2392
+ }
2393
+ };
2394
+ function advertisedRequired(inner) {
2395
+ return new AdvertisedRequiredOptional({
2396
+ innerType: inner,
2397
+ typeName: z.ZodFirstPartyTypeKind.ZodOptional
2398
+ });
2399
+ }
2387
2400
  function createWebSearchTool(exa, registry, config = {}) {
2388
2401
  const {
2389
2402
  name = "web_search",
@@ -2393,7 +2406,15 @@ function createWebSearchTool(exa, registry, config = {}) {
2393
2406
  const inputSchema = z.object({
2394
2407
  query: z.string().describe(
2395
2408
  "Natural language search query. Should be a semantically rich description of the ideal page, not just keywords."
2396
- )
2409
+ ),
2410
+ // Length limits are validated but not advertised: strict tool use on some
2411
+ // providers rejects `minLength`/`maxLength` in the schema.
2412
+ objective: advertisedRequired(
2413
+ z.string().trim().refine((value) => value.length > 0, "objective must not be empty").refine(
2414
+ (value) => value.length <= MAX_OBJECTIVE_LENGTH,
2415
+ `objective must be at most ${MAX_OBJECTIVE_LENGTH} characters`
2416
+ )
2417
+ ).describe(SEARCH_OBJECTIVE_TOOL_DESCRIPTION)
2397
2418
  });
2398
2419
  const jsonSchema = zodToJsonSchema(inputSchema);
2399
2420
  delete jsonSchema.$schema;
@@ -2407,12 +2428,13 @@ function createWebSearchTool(exa, registry, config = {}) {
2407
2428
  description,
2408
2429
  parameters: jsonSchema
2409
2430
  },
2410
- execute: ({ query }) => {
2431
+ execute: ({ query, objective }) => {
2411
2432
  const options = {
2412
2433
  type: "auto",
2413
2434
  numResults: 10,
2414
2435
  contents: { highlights: true },
2415
- ...searchOptions
2436
+ ...searchOptions,
2437
+ ...objective !== void 0 && { objective }
2416
2438
  };
2417
2439
  return exa.search(query, options);
2418
2440
  },
@@ -2827,30 +2849,27 @@ var Exa2 = class {
2827
2849
  if (livecrawlTimeout !== void 0)
2828
2850
  contentsOptions.livecrawlTimeout = livecrawlTimeout;
2829
2851
  if (maxAgeHours !== void 0) contentsOptions.maxAgeHours = maxAgeHours;
2830
- if (snapshotAsOf !== void 0)
2831
- contentsOptions.snapshotAsOf = snapshotAsOf;
2852
+ if (snapshotAsOf !== void 0) contentsOptions.snapshotAsOf = snapshotAsOf;
2832
2853
  if (context !== void 0) contentsOptions.context = context;
2833
2854
  return {
2834
2855
  contentsOptions,
2835
2856
  restOptions: rest
2836
2857
  };
2837
2858
  }
2838
- buildSearchRequestBody(query, options) {
2839
- const requestOptions = { ...options ?? {} };
2840
- delete requestOptions.stream;
2841
- delete requestOptions.betas;
2859
+ mergeSearchRequestBody(body, requestOptions) {
2860
+ const merged = { ...body, ...requestOptions?.body };
2861
+ delete merged.stream;
2862
+ return merged;
2863
+ }
2864
+ buildSearchRequestBody(query, options, requestOptions) {
2865
+ const body = { ...options ?? {} };
2866
+ delete body.betas;
2842
2867
  if (options === void 0 || !("contents" in options)) {
2843
- return {
2844
- query,
2845
- ...requestOptions,
2846
- contents: { text: { maxCharacters: DEFAULT_MAX_CHARACTERS } }
2847
- };
2868
+ body.contents = { text: { maxCharacters: DEFAULT_MAX_CHARACTERS } };
2869
+ } else if (options.contents === false || options.contents === null || options.contents === void 0) {
2870
+ delete body.contents;
2848
2871
  }
2849
- if (options.contents === false || options.contents === null || options.contents === void 0) {
2850
- delete requestOptions.contents;
2851
- return { query, ...requestOptions };
2852
- }
2853
- return { query, ...requestOptions };
2872
+ return this.mergeSearchRequestBody({ query, ...body }, requestOptions);
2854
2873
  }
2855
2874
  /**
2856
2875
  * Makes a request to the Exa API.
@@ -2985,14 +3004,14 @@ var Exa2 = class {
2985
3004
  });
2986
3005
  return response;
2987
3006
  }
2988
- async search(query, options) {
3007
+ async search(query, options, requestOptions) {
2989
3008
  if (options?.stream) {
2990
3009
  throw new ExaError(
2991
3010
  "For streaming responses, please use streamSearch() instead:\n\nfor await (const chunk of exa.streamSearch(query)) {\n // Handle chunks\n}",
2992
3011
  400 /* BadRequest */
2993
3012
  );
2994
3013
  }
2995
- const body = this.buildSearchRequestBody(query, options);
3014
+ const body = this.buildSearchRequestBody(query, options, requestOptions);
2996
3015
  const betaHeaders = headersForBetas(options?.betas);
2997
3016
  return betaHeaders ? await this.request("/search", "POST", body, void 0, betaHeaders) : await this.request("/search", "POST", body);
2998
3017
  }
@@ -3001,10 +3020,11 @@ var Exa2 = class {
3001
3020
  *
3002
3021
  * Each iteration yields a chunk with partial text (`content`) or new citations.
3003
3022
  * Use this if you'd like to read synthesized search output incrementally.
3023
+ * @param {RequestOptions} [requestOptions] - Per-call body overrides.
3004
3024
  */
3005
- streamSearch(query, options) {
3025
+ streamSearch(query, options, requestOptions) {
3006
3026
  return this.streamChatCompletions("/search", {
3007
- ...this.buildSearchRequestBody(query, options),
3027
+ ...this.buildSearchRequestBody(query, options, requestOptions),
3008
3028
  stream: true
3009
3029
  });
3010
3030
  }
@@ -3021,20 +3041,24 @@ var Exa2 = class {
3021
3041
  *
3022
3042
  * @param {string} query - The query string.
3023
3043
  * @param {RegularSearchOptions & T} [options] - Additional search + contents options
3044
+ * @param {RequestOptions} [requestOptions] - Per-call body overrides.
3024
3045
  * @returns {Promise<SearchResponse<T>>} A list of relevant search results with requested contents.
3025
3046
  */
3026
- async searchAndContents(query, options) {
3047
+ async searchAndContents(query, options, requestOptions) {
3027
3048
  const { contentsOptions, restOptions } = options === void 0 ? {
3028
3049
  contentsOptions: {
3029
3050
  text: { maxCharacters: DEFAULT_MAX_CHARACTERS }
3030
3051
  },
3031
3052
  restOptions: {}
3032
3053
  } : this.extractContentsOptions(options);
3033
- return await this.request("/search", "POST", {
3034
- query,
3035
- contents: contentsOptions,
3036
- ...restOptions
3037
- });
3054
+ return await this.request(
3055
+ "/search",
3056
+ "POST",
3057
+ this.mergeSearchRequestBody(
3058
+ { query, contents: contentsOptions, ...restOptions },
3059
+ requestOptions
3060
+ )
3061
+ );
3038
3062
  }
3039
3063
  async findSimilar(url, options) {
3040
3064
  if (options === void 0 || !("contents" in options)) {
@@ -3335,6 +3359,7 @@ export {
3335
3359
  MonitorStatus,
3336
3360
  OpenAIResponsesTools,
3337
3361
  OpenAITools,
3362
+ SEARCH_OBJECTIVE_TOOL_DESCRIPTION,
3338
3363
  SearchMonitorRunsClient,
3339
3364
  SearchMonitorsClient,
3340
3365
  ToolRegistry,