exa-js 2.21.0 → 2.22.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.
- package/README.md +6 -8
- package/dist/index.d.mts +100 -54
- package/dist/index.d.ts +100 -54
- package/dist/index.js +40 -37
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +38 -35
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
package/dist/index.d.ts
CHANGED
|
@@ -388,50 +388,49 @@ interface DeletedAgentMonitor {
|
|
|
388
388
|
deleted: true;
|
|
389
389
|
}
|
|
390
390
|
/**
|
|
391
|
-
* Params for a one-shot
|
|
392
|
-
*
|
|
393
|
-
*
|
|
394
|
-
* live web, and the result carries a warning when static fields are included.
|
|
391
|
+
* Params for a one-shot backtest of entities × fields over an explicit past
|
|
392
|
+
* news window. The backtest runs one monitor refresh over the requested
|
|
393
|
+
* window, then tears down its temporary monitor.
|
|
395
394
|
*/
|
|
396
|
-
interface
|
|
395
|
+
interface CreateAgentMonitorBacktestParams {
|
|
397
396
|
entities: CreateAgentMonitorEntityParams[];
|
|
398
397
|
fields: CreateAgentMonitorFieldParams[];
|
|
399
|
-
/** Start of the news window
|
|
400
|
-
|
|
401
|
-
/**
|
|
402
|
-
|
|
403
|
-
|
|
404
|
-
|
|
405
|
-
|
|
406
|
-
|
|
407
|
-
|
|
408
|
-
|
|
409
|
-
|
|
398
|
+
/** Start of the news window as an ISO-8601 UTC timestamp. */
|
|
399
|
+
startTime: string;
|
|
400
|
+
/** End of the news window as an ISO-8601 UTC timestamp. */
|
|
401
|
+
endTime: string;
|
|
402
|
+
}
|
|
403
|
+
/** One backtest cell: a value and its grounding citations. */
|
|
404
|
+
interface AgentMonitorBacktestContent {
|
|
405
|
+
value: unknown;
|
|
406
|
+
citations: AgentMonitorCitation[];
|
|
407
|
+
}
|
|
408
|
+
/** One entity's backtest result, with populated cells keyed by field name. */
|
|
409
|
+
interface AgentMonitorBacktestEntity {
|
|
410
410
|
name: string;
|
|
411
|
-
/** Populated
|
|
412
|
-
|
|
413
|
-
sourceUrls: string[];
|
|
411
|
+
/** Populated cells by field name; fields with no update are absent. */
|
|
412
|
+
contents: Record<string, AgentMonitorBacktestContent>;
|
|
414
413
|
}
|
|
415
|
-
/** The computed body of a finished
|
|
416
|
-
interface
|
|
417
|
-
data:
|
|
414
|
+
/** The computed body of a finished backtest, embedded in the job once it completes. */
|
|
415
|
+
interface AgentMonitorBacktestResult {
|
|
416
|
+
data: AgentMonitorBacktestEntity[];
|
|
418
417
|
failedEntities?: Array<{
|
|
419
418
|
name: string;
|
|
420
419
|
reason: string;
|
|
421
420
|
}>;
|
|
422
|
-
/** Caveats about how the
|
|
421
|
+
/** Caveats about how the backtest was computed. */
|
|
423
422
|
warnings?: string[];
|
|
424
423
|
}
|
|
425
|
-
type
|
|
424
|
+
type AgentMonitorBacktestStatus = "running" | "completed" | "failed";
|
|
426
425
|
/**
|
|
427
|
-
* A
|
|
426
|
+
* A backtest job: `create` returns it as `running`, and `get` polls it to
|
|
428
427
|
* `completed` (result fields present) or `failed`. Jobs expire and read as
|
|
429
428
|
* 404 after `expiresAt`.
|
|
430
429
|
*/
|
|
431
|
-
type
|
|
430
|
+
type AgentMonitorBacktest = {
|
|
432
431
|
id: string;
|
|
433
|
-
object: "agent_monitor.
|
|
434
|
-
/** The
|
|
432
|
+
object: "agent_monitor.backtest";
|
|
433
|
+
/** The backtested news window, echoed back as normalized ISO-8601 timestamps. */
|
|
435
434
|
startTime: string;
|
|
436
435
|
endTime: string;
|
|
437
436
|
createdAt: string;
|
|
@@ -440,11 +439,11 @@ type AgentMonitorSnapshot = {
|
|
|
440
439
|
status: "running";
|
|
441
440
|
} | ({
|
|
442
441
|
status: "completed";
|
|
443
|
-
} &
|
|
442
|
+
} & AgentMonitorBacktestResult) | {
|
|
444
443
|
status: "failed";
|
|
445
444
|
error: string;
|
|
446
445
|
});
|
|
447
|
-
interface
|
|
446
|
+
interface AgentMonitorBacktestWaitOptions {
|
|
448
447
|
pollInterval?: number;
|
|
449
448
|
timeoutMs?: number;
|
|
450
449
|
}
|
|
@@ -466,17 +465,17 @@ declare class AgentMonitorsBaseClient {
|
|
|
466
465
|
* Client for the Exa Agent Monitors API (`/agent/monitors`).
|
|
467
466
|
*/
|
|
468
467
|
|
|
469
|
-
type
|
|
468
|
+
type AgentMonitorTerminalBacktest = AgentMonitorBacktest & {
|
|
470
469
|
status: "completed" | "failed";
|
|
471
470
|
};
|
|
472
|
-
type
|
|
471
|
+
type AgentMonitorCompletedBacktest = AgentMonitorBacktest & {
|
|
473
472
|
status: "completed";
|
|
474
473
|
};
|
|
475
|
-
declare class
|
|
476
|
-
|
|
474
|
+
declare class AgentMonitorBacktestFailedError extends Error {
|
|
475
|
+
backtest: AgentMonitorBacktest & {
|
|
477
476
|
status: "failed";
|
|
478
477
|
};
|
|
479
|
-
constructor(
|
|
478
|
+
constructor(backtest: AgentMonitorBacktest & {
|
|
480
479
|
status: "failed";
|
|
481
480
|
});
|
|
482
481
|
}
|
|
@@ -517,27 +516,27 @@ declare class AgentMonitorChangesClient extends AgentMonitorsBaseClient {
|
|
|
517
516
|
*/
|
|
518
517
|
getAll(monitorId: string, options: ListAgentMonitorChangesParams & AgentMonitorsBetaOptions): Promise<AgentMonitorChange[]>;
|
|
519
518
|
}
|
|
520
|
-
declare class
|
|
519
|
+
declare class AgentMonitorBacktestsClient extends AgentMonitorsBaseClient {
|
|
521
520
|
/**
|
|
522
|
-
* Start an async
|
|
523
|
-
*
|
|
524
|
-
*
|
|
521
|
+
* Start an async backtest of entities × fields over an explicit past news
|
|
522
|
+
* window. Returns a `running` job; poll with `get` (or use `createAndWait`)
|
|
523
|
+
* for the result.
|
|
525
524
|
*/
|
|
526
|
-
create(params:
|
|
525
|
+
create(params: CreateAgentMonitorBacktestParams & AgentMonitorsBetaOptions): Promise<AgentMonitorBacktest>;
|
|
527
526
|
/**
|
|
528
|
-
* Poll a
|
|
527
|
+
* Poll a backtest job for its status and, once completed, its result.
|
|
529
528
|
* Jobs expire and read as 404 after `expiresAt`.
|
|
530
529
|
*/
|
|
531
|
-
get(
|
|
530
|
+
get(backtestId: string, options: AgentMonitorsBetaOptions): Promise<AgentMonitorBacktest>;
|
|
532
531
|
/**
|
|
533
|
-
* Poll a
|
|
532
|
+
* Poll a backtest job until it reaches a terminal status.
|
|
534
533
|
*/
|
|
535
|
-
pollUntilFinished(
|
|
534
|
+
pollUntilFinished(backtestId: string, options: AgentMonitorBacktestWaitOptions & AgentMonitorsBetaOptions): Promise<AgentMonitorTerminalBacktest>;
|
|
536
535
|
/**
|
|
537
|
-
* Start a
|
|
538
|
-
*
|
|
536
|
+
* Start a backtest and wait for its result. Throws
|
|
537
|
+
* AgentMonitorBacktestFailedError if the backtest fails.
|
|
539
538
|
*/
|
|
540
|
-
createAndWait(params:
|
|
539
|
+
createAndWait(params: CreateAgentMonitorBacktestParams & AgentMonitorsBetaOptions, options?: AgentMonitorBacktestWaitOptions): Promise<AgentMonitorCompletedBacktest>;
|
|
541
540
|
}
|
|
542
541
|
declare class AgentMonitorsClient extends AgentMonitorsBaseClient {
|
|
543
542
|
/**
|
|
@@ -549,9 +548,9 @@ declare class AgentMonitorsClient extends AgentMonitorsBaseClient {
|
|
|
549
548
|
*/
|
|
550
549
|
changes: AgentMonitorChangesClient;
|
|
551
550
|
/**
|
|
552
|
-
* Client for
|
|
551
|
+
* Client for one-shot backtest jobs.
|
|
553
552
|
*/
|
|
554
|
-
|
|
553
|
+
backtests: AgentMonitorBacktestsClient;
|
|
555
554
|
constructor(client: Exa);
|
|
556
555
|
/**
|
|
557
556
|
* Create an Agent Monitor from its entities, fields, and cadence.
|
|
@@ -4253,10 +4252,11 @@ declare const DYNAMIC_HIGHLIGHTS_BETA = "dynamic-highlights-2026-08-28";
|
|
|
4253
4252
|
* Options for retrieving page contents
|
|
4254
4253
|
* @typedef {Object} ContentsOptions
|
|
4255
4254
|
* @property {TextContentsOptions | boolean} [text] - Options for retrieving text contents.
|
|
4256
|
-
* @property {HighlightsContentsOptions | boolean} [highlights] -
|
|
4255
|
+
* @property {HighlightsContentsOptions | boolean} [highlights] - Recommended: `true`. Exa dynamically chooses the number of characters based on each document's relevance to your query.
|
|
4257
4256
|
* @property {SummaryContentsOptions | boolean} [summary] - Options for retrieving summary.
|
|
4258
4257
|
* @property {ContextOptions | boolean} [context] - DEPRECATED: Use `text` or `highlights` instead. Will be removed in a future version.
|
|
4259
4258
|
* @property {number} [maxAgeHours] - Maximum age of cached content in hours. If content is older, it will be fetched fresh. Special values: 0 = always fetch fresh content, -1 = never fetch fresh (use cached content only). Example: 168 = fetch fresh for pages older than 7 days.
|
|
4259
|
+
* @property {string} [snapshotAsOf] - ISO 8601 datetime. Return the newest stored version at or before this instant instead of live content.
|
|
4260
4260
|
* @property {boolean} [filterEmptyResults] - If true, filters out results with no contents. Default is true.
|
|
4261
4261
|
* @property {number} [subpages] - The number of subpages to return for each result, where each subpage is derived from an internal link for the result.
|
|
4262
4262
|
* @property {string | string[]} [subpageTarget] - Text used to match/rank subpages in the returned subpage list. You could use "about" to get *about* page for websites. Note that this is a fuzzy matcher.
|
|
@@ -4264,6 +4264,14 @@ declare const DYNAMIC_HIGHLIGHTS_BETA = "dynamic-highlights-2026-08-28";
|
|
|
4264
4264
|
*/
|
|
4265
4265
|
type ContentsOptions = {
|
|
4266
4266
|
text?: TextContentsOptions | true;
|
|
4267
|
+
/**
|
|
4268
|
+
* Recommended default: `true`. Exa dynamically chooses the number of
|
|
4269
|
+
* characters based on each document's relevance to your query.
|
|
4270
|
+
* Use this for concise AI context, RAG, and search previews without
|
|
4271
|
+
* choosing a character budget yourself. Read `result.highlights`.
|
|
4272
|
+
* Set `maxCharacters` only when your application has an explicit
|
|
4273
|
+
* character-limit requirement; it overrides the recommended default.
|
|
4274
|
+
*/
|
|
4267
4275
|
highlights?: HighlightsContentsOptions | true;
|
|
4268
4276
|
summary?: SummaryContentsOptions | true;
|
|
4269
4277
|
livecrawl?: LivecrawlOptions;
|
|
@@ -4274,6 +4282,7 @@ type ContentsOptions = {
|
|
|
4274
4282
|
context?: ContextOptions | true;
|
|
4275
4283
|
livecrawlTimeout?: number;
|
|
4276
4284
|
maxAgeHours?: number;
|
|
4285
|
+
snapshotAsOf?: string;
|
|
4277
4286
|
filterEmptyResults?: boolean;
|
|
4278
4287
|
subpages?: number;
|
|
4279
4288
|
subpageTarget?: string | string[];
|
|
@@ -4464,17 +4473,25 @@ type TextContentsOptions = {
|
|
|
4464
4473
|
excludeSections?: SectionTag[];
|
|
4465
4474
|
};
|
|
4466
4475
|
/**
|
|
4467
|
-
*
|
|
4476
|
+
* Overrides for highlights. Prefer `highlights: true`: Exa dynamically
|
|
4477
|
+
* chooses the number of characters based on each document's relevance
|
|
4478
|
+
* to your query. A request for concise context does not require setting
|
|
4479
|
+
* a fixed character budget.
|
|
4468
4480
|
* Deep search variants also support these options for returned highlights.
|
|
4469
4481
|
* @typedef {Object} HighlightsContentsOptions
|
|
4470
4482
|
* @property {string} [query] - The query string to use for highlights search.
|
|
4471
|
-
* @property {number} [maxCharacters] -
|
|
4483
|
+
* @property {number} [maxCharacters] - Explicit character-limit override. Prefer `highlights: true` unless your application requires a specific limit. Not compatible with `dynamic`.
|
|
4472
4484
|
* @property {boolean} [dynamic] - Enable Dynamic Highlights (research preview): allocates one shared context budget across all results instead of a per-document budget; the model sizes the output itself. Not compatible with `maxCharacters`. Beta: requires passing `betas: [DYNAMIC_HIGHLIGHTS_BETA]` to the request.
|
|
4473
4485
|
* @property {number} [numSentences] - DEPRECATED: Use maxCharacters instead.
|
|
4474
4486
|
* @property {number} [highlightsPerUrl] - DEPRECATED: Use maxCharacters instead.
|
|
4475
4487
|
*/
|
|
4476
4488
|
type HighlightsContentsOptions = {
|
|
4477
4489
|
query?: string;
|
|
4490
|
+
/**
|
|
4491
|
+
* Override for an explicit application character limit. Prefer
|
|
4492
|
+
* `highlights: true` to let Exa choose the length based on relevance.
|
|
4493
|
+
* A general need for concise context does not require a fixed limit.
|
|
4494
|
+
*/
|
|
4478
4495
|
maxCharacters?: number;
|
|
4479
4496
|
dynamic?: boolean;
|
|
4480
4497
|
/**
|
|
@@ -4691,6 +4708,7 @@ type Entity = CompanyEntity | PersonEntity;
|
|
|
4691
4708
|
* @property {string} id - The temporary ID for the document.
|
|
4692
4709
|
* @property {string} [image] - A representative image for the content, if any.
|
|
4693
4710
|
* @property {string} [favicon] - A favicon for the site, if any.
|
|
4711
|
+
* @property {string} [snapshotAt] - Crawl instant of the stored version served for a snapshotAsOf request.
|
|
4694
4712
|
* @property {Entity[]} [entities] - Structured entity data for company or person search results.
|
|
4695
4713
|
*/
|
|
4696
4714
|
type SearchResult<T extends ContentsOptions> = {
|
|
@@ -4702,6 +4720,7 @@ type SearchResult<T extends ContentsOptions> = {
|
|
|
4702
4720
|
id: string;
|
|
4703
4721
|
image?: string;
|
|
4704
4722
|
favicon?: string;
|
|
4723
|
+
snapshotAt?: string;
|
|
4705
4724
|
entities?: Entity[];
|
|
4706
4725
|
} & ContentsResultComponent<T>;
|
|
4707
4726
|
type DeepSearchOutputGroundingCitation = {
|
|
@@ -4884,7 +4903,15 @@ declare class Exa {
|
|
|
4884
4903
|
rawRequest(endpoint: string, method?: string, body?: Record<string, unknown>, queryParams?: Record<string, string | number | boolean | string[] | undefined>, headers?: Record<string, string>): Promise<Response>;
|
|
4885
4904
|
/**
|
|
4886
4905
|
* Performs a search with an Exa prompt-engineered query.
|
|
4887
|
-
*
|
|
4906
|
+
* For AI answers, RAG, and search previews, prefer query-relevant passages:
|
|
4907
|
+
* `exa.search(query, { contents: { highlights: true } })`.
|
|
4908
|
+
* `highlights: true` is the recommended default: Exa dynamically chooses
|
|
4909
|
+
* the number of characters based on each document's relevance to your query.
|
|
4910
|
+
* You do not need to choose `maxCharacters` to keep context concise;
|
|
4911
|
+
* use it only for an explicit application character-limit requirement.
|
|
4912
|
+
* Read each result's `highlights` array. Request `text` only when you need
|
|
4913
|
+
* the full page; use `contents: false` when you only need titles and URLs.
|
|
4914
|
+
* Omitting contents still returns text by default.
|
|
4888
4915
|
*
|
|
4889
4916
|
* @param {string} query - The query string.
|
|
4890
4917
|
* @returns {Promise<SearchResponse<{ text: { maxCharacters: 10_000 } }>>} A list of relevant search results with text contents.
|
|
@@ -4906,6 +4933,23 @@ declare class Exa {
|
|
|
4906
4933
|
}): Promise<SearchResponse<{}>>;
|
|
4907
4934
|
/**
|
|
4908
4935
|
* Performs a search with specific contents.
|
|
4936
|
+
* Prefer `{ contents: { highlights: true } }` for query-relevant passages
|
|
4937
|
+
* for AI answers, RAG, and search previews. Read `result.highlights`.
|
|
4938
|
+
* `highlights: true` is the recommended default: Exa dynamically chooses
|
|
4939
|
+
* the number of characters based on each document's relevance to your query.
|
|
4940
|
+
* No manual character budget is needed. Set `maxCharacters` only when
|
|
4941
|
+
* your application requires a specific numeric character limit; otherwise
|
|
4942
|
+
* keep `highlights: true`.
|
|
4943
|
+
* Use the boolean `true`; do not set the deprecated `numSentences` or
|
|
4944
|
+
* `highlightsPerUrl` options. Request `text` when you need the full page.
|
|
4945
|
+
*
|
|
4946
|
+
* @example
|
|
4947
|
+
* const response = await exa.search("recent advances in battery recycling", {
|
|
4948
|
+
* contents: { highlights: true },
|
|
4949
|
+
* });
|
|
4950
|
+
* for (const result of response.results) {
|
|
4951
|
+
* console.log(result.url, result.highlights);
|
|
4952
|
+
* }
|
|
4909
4953
|
*
|
|
4910
4954
|
* @param {string} query - The query string.
|
|
4911
4955
|
* @param {RegularSearchOptions & { contents: T }} options - Search options with specific contents
|
|
@@ -4917,6 +4961,8 @@ declare class Exa {
|
|
|
4917
4961
|
/**
|
|
4918
4962
|
* Performs a search with an Exa prompt-engineered query.
|
|
4919
4963
|
* When no contents option is specified, returns text contents by default.
|
|
4964
|
+
* For query-relevant passages, explicitly pass
|
|
4965
|
+
* `{ contents: { highlights: true } }` and read `result.highlights`.
|
|
4920
4966
|
*
|
|
4921
4967
|
* @param {string} query - The query string.
|
|
4922
4968
|
* @param {Omit<DeepSearchOptions, 'contents'> | Omit<NonDeepSearchOptions, 'contents'>} options - Search options without contents
|
|
@@ -5096,4 +5142,4 @@ declare class Exa {
|
|
|
5096
5142
|
private parseSSEStream;
|
|
5097
5143
|
}
|
|
5098
5144
|
|
|
5099
|
-
export { AGENT_BETA_HEADER, AGENT_MAX_EFFORT_BETA, AGENT_MONITORS_BETA_HEADER, type AddAgentMonitorEntitiesParams, AgentBetaClient, type AgentBetaOptions, type AgentBudget, AgentClient, type AgentConfidence, type AgentCostDollars, type AgentCreateOptions, type AgentDataSource, type AgentDataSourceProvider, type AgentEffort, type AgentError, type AgentEvent, type AgentGroundingCitation, type AgentGroundingEntry, type AgentInput, type AgentMonitor, type
|
|
5145
|
+
export { AGENT_BETA_HEADER, AGENT_MAX_EFFORT_BETA, AGENT_MONITORS_BETA_HEADER, type AddAgentMonitorEntitiesParams, AgentBetaClient, type AgentBetaOptions, type AgentBudget, AgentClient, type AgentConfidence, type AgentCostDollars, type AgentCreateOptions, type AgentDataSource, type AgentDataSourceProvider, type AgentEffort, type AgentError, type AgentEvent, type AgentGroundingCitation, type AgentGroundingEntry, type AgentInput, type AgentMonitor, type AgentMonitorBacktest, type AgentMonitorBacktestContent, type AgentMonitorBacktestEntity, AgentMonitorBacktestFailedError, type AgentMonitorBacktestResult, type AgentMonitorBacktestStatus, type AgentMonitorBacktestWaitOptions, AgentMonitorBacktestsClient, type AgentMonitorChange, type AgentMonitorChangeEntity, type AgentMonitorChangeField, AgentMonitorChangesClient, type AgentMonitorCitation, type AgentMonitorContent, type AgentMonitorCreation, AgentMonitorEntitiesClient, type AgentMonitorEntity, type AgentMonitorEntityView, type AgentMonitorField, type AgentMonitorFieldMode, type AgentMonitorFieldValueType, type AgentMonitorRefresh, type AgentMonitorStatus, type AgentMonitorUsage, type AgentMonitorsBetaOptions, AgentMonitorsClient, type AgentOutput, type AgentRun, AgentRunCancelledError, AgentRunEventsClient, AgentRunFailedError, type AgentRunStatus, type AgentRunTyped, AgentRunsClient, type AgentStopReason, type AgentUsage, type AgentWaitOptions, type AnswerOptions, type AnswerOptionsTyped, type AnswerResponse, type AnswerResponseTyped, type AnswerStreamChunk, type AnswerStreamResponse, type AnthropicToolResult, AnthropicTools, type ArticleEntity, type BaseSearchOptions, BetaClient, type BetaOptions, type CompanyEntity, type ContentsOptions, type ContentsResultComponent, type ContextOptions, type CostDollars, type CostDollarsContents, type CostDollarsSeearch, type CreateAgentMonitorBacktestParams, type CreateAgentMonitorEntityParams, type CreateAgentMonitorFieldParams, type CreateAgentMonitorOptions, type CreateAgentMonitorParams, type CreateAgentRunParams, type CreateAgentRunParamsTyped, type CreateCriterionParameters, type CreateEnrichmentParameters, CreateEnrichmentParametersFormat, type CreateImportParameters, CreateImportParametersFormat, type CreateImportResponse, type CreateImportWithCsvParameters, type CreateMonitorParameters, type CreateSearchMonitorParams, type CreateSearchMonitorResponse, type CreateWebhookParameters, type CreateWebsetParameters, type CreateWebsetSearchParameters, type CsvDataInput, type CustomEntity, DEFAULT_GET_CONTENTS_TOOL_DESCRIPTION, DEFAULT_WEB_SEARCH_TOOL_DESCRIPTION, DYNAMIC_HIGHLIGHTS_BETA, type DeepObjectOutputSchema, type DeepOutputSchema, type DeepSearchOutput, type DeepSearchOutputGrounding, type DeepSearchOutputGroundingCitation, type DeepSearchOutputGroundingConfidence, type DeepSearchType, type DeepTextOutputSchema, type Default, type DeletedAgentMonitor, type DeletedAgentRun, type EnrichmentResult, type Entity, type EntityCompanyProperties, type EntityCompanyPropertiesFinancials, type EntityCompanyPropertiesFundingRound, type EntityCompanyPropertiesHeadquarters, type EntityCompanyPropertiesWebTraffic, type EntityCompanyPropertiesWorkforce, type EntityDateRange, type EntityPersonProperties, type EntityPersonPropertiesCompanyRef, type EntityPersonPropertiesWorkHistoryEntry, type Event, EventType, EventsClient, Exa, ExaError, type ExaErrorEnvelope, type ExaToolSpec, type ExtrasOptions, type ExtrasResponse, type FindSimilarOptions, type GetContentsTool, type GetContentsToolConfig, type GetWebsetResponse, type GroundingCitation, type GroundingEntry, type HighlightsContentsOptions, type HighlightsResponse, HttpStatusCode, type Import, ImportFailedReason, ImportFormat, ImportObject, ImportStatus, ImportsClient, type JSONSchema, type ListAgentMonitorChangesParams, type ListAgentMonitorChangesResponse, type ListAgentMonitorEntitiesParams, type ListAgentMonitorEntitiesResponse, type ListAgentMonitorsParams, type ListAgentMonitorsResponse, type ListAgentRunEventsParams, type ListAgentRunEventsResponse, type ListAgentRunsParams, type ListAgentRunsResponse, type ListEventsResponse, type ListImportsResponse, type ListMonitorRunsResponse, type ListMonitorsOptions, type ListMonitorsResponse, type ListResearchRequest, type ListResearchResponse, type ListSearchMonitorRunsParams, type ListSearchMonitorRunsResponse, type ListSearchMonitorsParams, type ListSearchMonitorsResponse, type ListWebhookAttemptsResponse, type ListWebhooksResponse, type ListWebsetItemResponse, type ListWebsetItemsOptions, type ListWebsetsResponse, type LivecrawlOptions, type Monitor, type MonitorBehavior, type MonitorCadence, MonitorObject, type MonitorRun, MonitorRunObject, MonitorRunStatus, MonitorRunType, MonitorStatus, OpenAIResponsesTools, type OpenAIToolMessage, OpenAITools, type PersonEntity, type PreviewWebsetParameters, type PreviewWebsetResponse, type RegularSearchOptions, type Research, type ResearchCreateParamsTyped, type ResearchCreateRequest, type ResearchCreateResponse, type ResearchDefinitionEvent, type ResearchEvent, type ResearchOperation, type ResearchOutputEvent, type ResearchPaperEntity, type ResearchPlanDefinitionEvent, type ResearchPlanOperationEvent, type ResearchPlanOutputEvent, type ResearchStatus, type ResearchStreamEvent, type ResearchStreamEventTyped, type ResearchTaskDefinitionEvent, type ResearchTaskOperationEvent, type ResearchTaskOutputEvent, type ResearchTyped, type ResponsesFunctionCallOutput, type SearchMonitor, type SearchMonitorRun, type SearchMonitorRunFailReason, type SearchMonitorRunOutput, type SearchMonitorRunStatus, SearchMonitorRunsClient, type SearchMonitorSearch, type SearchMonitorStatus, type SearchMonitorTrigger, type SearchMonitorWebhook, type SearchMonitorWebhookEvent, SearchMonitorsClient, type SearchResponse, type SearchResult, type SearchStreamChunk, type SectionTag, type Status, type SubpagesResponse, type SummaryContentsOptions, type SummaryContentsOptionsTyped, type SummaryResponse, type TextContentsOptions, type TextResponse, type ToolDefinition, type ToolJsonSchema, type ToolNamespace, ToolRegistry, type TriggerSearchMonitorResponse, type UpdateEnrichmentParameters, type UpdateImport, type UpdateMonitor, UpdateMonitorStatus, type UpdateSearchMonitorParams, type UpdateWebhookParameters, type UpdateWebsetRequest, type VerbosityOptions, type WaitUntilCompletedOptions, type WebSearchTool, type WebSearchToolConfig, type Webhook, type WebhookAttempt, WebhookStatus, type Webset, type WebsetEnrichment, WebsetEnrichmentFormat, WebsetEnrichmentStatus, WebsetEnrichmentsClient, WebsetExcludeSource, type WebsetHeadersLike, WebsetImportSource, type WebsetItem, type WebsetItemArticleProperties, type WebsetItemCompanyProperties, type WebsetItemCustomProperties, type WebsetItemEvaluation, WebsetItemEvaluationSatisfied, type WebsetItemPersonProperties, type WebsetItemResearchPaperProperties, WebsetItemSource, WebsetItemsClient, WebsetMonitorsClient, type WebsetSearch, WebsetSearchBehavior, WebsetSearchCanceledReason, WebsetSearchScopeSource, WebsetSearchStatus, WebsetSearchesClient, WebsetStatus, WebsetWebhooksClient, WebsetsClient, createGetContentsTool, createWebSearchTool, Exa as default };
|
package/dist/index.js
CHANGED
|
@@ -35,10 +35,10 @@ __export(index_exports, {
|
|
|
35
35
|
AGENT_MONITORS_BETA_HEADER: () => AGENT_MONITORS_BETA_HEADER,
|
|
36
36
|
AgentBetaClient: () => AgentBetaClient,
|
|
37
37
|
AgentClient: () => AgentClient,
|
|
38
|
+
AgentMonitorBacktestFailedError: () => AgentMonitorBacktestFailedError,
|
|
39
|
+
AgentMonitorBacktestsClient: () => AgentMonitorBacktestsClient,
|
|
38
40
|
AgentMonitorChangesClient: () => AgentMonitorChangesClient,
|
|
39
41
|
AgentMonitorEntitiesClient: () => AgentMonitorEntitiesClient,
|
|
40
|
-
AgentMonitorSnapshotFailedError: () => AgentMonitorSnapshotFailedError,
|
|
41
|
-
AgentMonitorSnapshotsClient: () => AgentMonitorSnapshotsClient,
|
|
42
42
|
AgentMonitorsClient: () => AgentMonitorsClient,
|
|
43
43
|
AgentRunCancelledError: () => AgentRunCancelledError,
|
|
44
44
|
AgentRunEventsClient: () => AgentRunEventsClient,
|
|
@@ -100,7 +100,7 @@ var import_cross_fetch = __toESM(require("cross-fetch"));
|
|
|
100
100
|
// package.json
|
|
101
101
|
var package_default = {
|
|
102
102
|
name: "exa-js",
|
|
103
|
-
version: "2.
|
|
103
|
+
version: "2.22.1",
|
|
104
104
|
description: "Exa SDK for Node.js and the browser",
|
|
105
105
|
publishConfig: {
|
|
106
106
|
access: "public"
|
|
@@ -310,13 +310,13 @@ var AgentMonitorsBaseClient = class {
|
|
|
310
310
|
};
|
|
311
311
|
|
|
312
312
|
// src/agent/monitors/client.ts
|
|
313
|
-
var
|
|
314
|
-
var
|
|
315
|
-
var
|
|
316
|
-
constructor(
|
|
317
|
-
super(
|
|
318
|
-
this.name = "
|
|
319
|
-
this.
|
|
313
|
+
var DEFAULT_BACKTEST_POLL_INTERVAL_MS = 2e3;
|
|
314
|
+
var DEFAULT_BACKTEST_POLL_TIMEOUT_MS = 60 * 60 * 1e3;
|
|
315
|
+
var AgentMonitorBacktestFailedError = class extends Error {
|
|
316
|
+
constructor(backtest) {
|
|
317
|
+
super(backtest.error ?? `Agent monitor backtest ${backtest.id} failed`);
|
|
318
|
+
this.name = "AgentMonitorBacktestFailedError";
|
|
319
|
+
this.backtest = backtest;
|
|
320
320
|
}
|
|
321
321
|
};
|
|
322
322
|
var AgentMonitorEntitiesClient = class extends AgentMonitorsBaseClient {
|
|
@@ -426,66 +426,66 @@ var AgentMonitorChangesClient = class extends AgentMonitorsBaseClient {
|
|
|
426
426
|
return changes;
|
|
427
427
|
}
|
|
428
428
|
};
|
|
429
|
-
var
|
|
429
|
+
var AgentMonitorBacktestsClient = class extends AgentMonitorsBaseClient {
|
|
430
430
|
/**
|
|
431
|
-
* Start an async
|
|
432
|
-
*
|
|
433
|
-
*
|
|
431
|
+
* Start an async backtest of entities × fields over an explicit past news
|
|
432
|
+
* window. Returns a `running` job; poll with `get` (or use `createAndWait`)
|
|
433
|
+
* for the result.
|
|
434
434
|
*/
|
|
435
435
|
async create(params) {
|
|
436
436
|
const { betas, ...payload } = params;
|
|
437
437
|
return this.request(
|
|
438
|
-
"/
|
|
438
|
+
"/backtest",
|
|
439
439
|
betas,
|
|
440
440
|
"POST",
|
|
441
441
|
payload
|
|
442
442
|
);
|
|
443
443
|
}
|
|
444
444
|
/**
|
|
445
|
-
* Poll a
|
|
445
|
+
* Poll a backtest job for its status and, once completed, its result.
|
|
446
446
|
* Jobs expire and read as 404 after `expiresAt`.
|
|
447
447
|
*/
|
|
448
|
-
async get(
|
|
448
|
+
async get(backtestId, options) {
|
|
449
449
|
return this.request(
|
|
450
|
-
`/
|
|
450
|
+
`/backtest/${backtestId}`,
|
|
451
451
|
options.betas,
|
|
452
452
|
"GET"
|
|
453
453
|
);
|
|
454
454
|
}
|
|
455
455
|
/**
|
|
456
|
-
* Poll a
|
|
456
|
+
* Poll a backtest job until it reaches a terminal status.
|
|
457
457
|
*/
|
|
458
|
-
async pollUntilFinished(
|
|
459
|
-
const pollInterval = options.pollInterval ??
|
|
460
|
-
const timeoutMs = options.timeoutMs ??
|
|
458
|
+
async pollUntilFinished(backtestId, options) {
|
|
459
|
+
const pollInterval = options.pollInterval ?? DEFAULT_BACKTEST_POLL_INTERVAL_MS;
|
|
460
|
+
const timeoutMs = options.timeoutMs ?? DEFAULT_BACKTEST_POLL_TIMEOUT_MS;
|
|
461
461
|
const startTime = Date.now();
|
|
462
462
|
while (true) {
|
|
463
|
-
const
|
|
464
|
-
if (
|
|
465
|
-
return
|
|
463
|
+
const backtest = await this.get(backtestId, { betas: options.betas });
|
|
464
|
+
if (backtest.status !== "running") {
|
|
465
|
+
return backtest;
|
|
466
466
|
}
|
|
467
467
|
if (Date.now() - startTime > timeoutMs) {
|
|
468
468
|
throw new Error(
|
|
469
|
-
`Polling timeout: Agent monitor
|
|
469
|
+
`Polling timeout: Agent monitor backtest ${backtestId} did not complete within ${timeoutMs}ms`
|
|
470
470
|
);
|
|
471
471
|
}
|
|
472
472
|
await new Promise((resolve) => setTimeout(resolve, pollInterval));
|
|
473
473
|
}
|
|
474
474
|
}
|
|
475
475
|
/**
|
|
476
|
-
* Start a
|
|
477
|
-
*
|
|
476
|
+
* Start a backtest and wait for its result. Throws
|
|
477
|
+
* AgentMonitorBacktestFailedError if the backtest fails.
|
|
478
478
|
*/
|
|
479
479
|
async createAndWait(params, options) {
|
|
480
|
-
const
|
|
481
|
-
const
|
|
480
|
+
const backtest = await this.create(params);
|
|
481
|
+
const terminalBacktest = backtest.status === "running" ? await this.pollUntilFinished(backtest.id, {
|
|
482
482
|
...options,
|
|
483
483
|
betas: params.betas
|
|
484
|
-
}) :
|
|
485
|
-
if (
|
|
486
|
-
throw new
|
|
484
|
+
}) : backtest;
|
|
485
|
+
if (terminalBacktest.status === "failed") {
|
|
486
|
+
throw new AgentMonitorBacktestFailedError(terminalBacktest);
|
|
487
487
|
}
|
|
488
|
-
return
|
|
488
|
+
return terminalBacktest;
|
|
489
489
|
}
|
|
490
490
|
};
|
|
491
491
|
var AgentMonitorsClient = class extends AgentMonitorsBaseClient {
|
|
@@ -493,7 +493,7 @@ var AgentMonitorsClient = class extends AgentMonitorsBaseClient {
|
|
|
493
493
|
super(client);
|
|
494
494
|
this.entities = new AgentMonitorEntitiesClient(client);
|
|
495
495
|
this.changes = new AgentMonitorChangesClient(client);
|
|
496
|
-
this.
|
|
496
|
+
this.backtests = new AgentMonitorBacktestsClient(client);
|
|
497
497
|
}
|
|
498
498
|
/**
|
|
499
499
|
* Create an Agent Monitor from its entities, fields, and cadence.
|
|
@@ -2885,6 +2885,7 @@ var Exa2 = class {
|
|
|
2885
2885
|
livecrawl,
|
|
2886
2886
|
livecrawlTimeout,
|
|
2887
2887
|
maxAgeHours,
|
|
2888
|
+
snapshotAsOf,
|
|
2888
2889
|
// DEPRECATED FIELD: preserve legacy `context` only for backward compatibility.
|
|
2889
2890
|
context,
|
|
2890
2891
|
...rest
|
|
@@ -2913,6 +2914,8 @@ var Exa2 = class {
|
|
|
2913
2914
|
if (livecrawlTimeout !== void 0)
|
|
2914
2915
|
contentsOptions.livecrawlTimeout = livecrawlTimeout;
|
|
2915
2916
|
if (maxAgeHours !== void 0) contentsOptions.maxAgeHours = maxAgeHours;
|
|
2917
|
+
if (snapshotAsOf !== void 0)
|
|
2918
|
+
contentsOptions.snapshotAsOf = snapshotAsOf;
|
|
2916
2919
|
if (context !== void 0) contentsOptions.context = context;
|
|
2917
2920
|
return {
|
|
2918
2921
|
contentsOptions,
|
|
@@ -3387,10 +3390,10 @@ var index_default = Exa2;
|
|
|
3387
3390
|
AGENT_MONITORS_BETA_HEADER,
|
|
3388
3391
|
AgentBetaClient,
|
|
3389
3392
|
AgentClient,
|
|
3393
|
+
AgentMonitorBacktestFailedError,
|
|
3394
|
+
AgentMonitorBacktestsClient,
|
|
3390
3395
|
AgentMonitorChangesClient,
|
|
3391
3396
|
AgentMonitorEntitiesClient,
|
|
3392
|
-
AgentMonitorSnapshotFailedError,
|
|
3393
|
-
AgentMonitorSnapshotsClient,
|
|
3394
3397
|
AgentMonitorsClient,
|
|
3395
3398
|
AgentRunCancelledError,
|
|
3396
3399
|
AgentRunEventsClient,
|