exa-js 2.22.0 → 2.22.2
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 +102 -57
- package/dist/index.d.ts +102 -57
- package/dist/index.js +39 -37
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +37 -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.
|
|
@@ -3220,7 +3219,8 @@ declare enum CreateImportResponseStatus {
|
|
|
3220
3219
|
pending = "pending",
|
|
3221
3220
|
processing = "processing",
|
|
3222
3221
|
completed = "completed",
|
|
3223
|
-
failed = "failed"
|
|
3222
|
+
failed = "failed",
|
|
3223
|
+
canceled = "canceled"
|
|
3224
3224
|
}
|
|
3225
3225
|
declare enum WebsetImportSource {
|
|
3226
3226
|
import = "import",
|
|
@@ -3268,7 +3268,8 @@ declare enum ImportStatus {
|
|
|
3268
3268
|
pending = "pending",
|
|
3269
3269
|
processing = "processing",
|
|
3270
3270
|
completed = "completed",
|
|
3271
|
-
failed = "failed"
|
|
3271
|
+
failed = "failed",
|
|
3272
|
+
canceled = "canceled"
|
|
3272
3273
|
}
|
|
3273
3274
|
declare enum MonitorObject {
|
|
3274
3275
|
monitor = "monitor"
|
|
@@ -3354,7 +3355,8 @@ declare enum WebsetSearchBehavior {
|
|
|
3354
3355
|
}
|
|
3355
3356
|
declare enum WebsetSearchCanceledReason {
|
|
3356
3357
|
webset_deleted = "webset_deleted",
|
|
3357
|
-
webset_canceled = "webset_canceled"
|
|
3358
|
+
webset_canceled = "webset_canceled",
|
|
3359
|
+
out_of_credits = "out_of_credits"
|
|
3358
3360
|
}
|
|
3359
3361
|
|
|
3360
3362
|
/**
|
|
@@ -4253,7 +4255,7 @@ declare const DYNAMIC_HIGHLIGHTS_BETA = "dynamic-highlights-2026-08-28";
|
|
|
4253
4255
|
* Options for retrieving page contents
|
|
4254
4256
|
* @typedef {Object} ContentsOptions
|
|
4255
4257
|
* @property {TextContentsOptions | boolean} [text] - Options for retrieving text contents.
|
|
4256
|
-
* @property {HighlightsContentsOptions | boolean} [highlights] -
|
|
4258
|
+
* @property {HighlightsContentsOptions | boolean} [highlights] - Recommended: `true`. Exa dynamically chooses the number of characters based on each document's relevance to your query.
|
|
4257
4259
|
* @property {SummaryContentsOptions | boolean} [summary] - Options for retrieving summary.
|
|
4258
4260
|
* @property {ContextOptions | boolean} [context] - DEPRECATED: Use `text` or `highlights` instead. Will be removed in a future version.
|
|
4259
4261
|
* @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.
|
|
@@ -4265,6 +4267,14 @@ declare const DYNAMIC_HIGHLIGHTS_BETA = "dynamic-highlights-2026-08-28";
|
|
|
4265
4267
|
*/
|
|
4266
4268
|
type ContentsOptions = {
|
|
4267
4269
|
text?: TextContentsOptions | true;
|
|
4270
|
+
/**
|
|
4271
|
+
* Recommended default: `true`. Exa dynamically chooses the number of
|
|
4272
|
+
* characters based on each document's relevance to your query.
|
|
4273
|
+
* Use this for concise AI context, RAG, and search previews without
|
|
4274
|
+
* choosing a character budget yourself. Read `result.highlights`.
|
|
4275
|
+
* Set `maxCharacters` only when your application has an explicit
|
|
4276
|
+
* character-limit requirement; it overrides the recommended default.
|
|
4277
|
+
*/
|
|
4268
4278
|
highlights?: HighlightsContentsOptions | true;
|
|
4269
4279
|
summary?: SummaryContentsOptions | true;
|
|
4270
4280
|
livecrawl?: LivecrawlOptions;
|
|
@@ -4466,17 +4476,25 @@ type TextContentsOptions = {
|
|
|
4466
4476
|
excludeSections?: SectionTag[];
|
|
4467
4477
|
};
|
|
4468
4478
|
/**
|
|
4469
|
-
*
|
|
4479
|
+
* Overrides for highlights. Prefer `highlights: true`: Exa dynamically
|
|
4480
|
+
* chooses the number of characters based on each document's relevance
|
|
4481
|
+
* to your query. A request for concise context does not require setting
|
|
4482
|
+
* a fixed character budget.
|
|
4470
4483
|
* Deep search variants also support these options for returned highlights.
|
|
4471
4484
|
* @typedef {Object} HighlightsContentsOptions
|
|
4472
4485
|
* @property {string} [query] - The query string to use for highlights search.
|
|
4473
|
-
* @property {number} [maxCharacters] -
|
|
4486
|
+
* @property {number} [maxCharacters] - Explicit character-limit override. Prefer `highlights: true` unless your application requires a specific limit. Not compatible with `dynamic`.
|
|
4474
4487
|
* @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.
|
|
4475
4488
|
* @property {number} [numSentences] - DEPRECATED: Use maxCharacters instead.
|
|
4476
4489
|
* @property {number} [highlightsPerUrl] - DEPRECATED: Use maxCharacters instead.
|
|
4477
4490
|
*/
|
|
4478
4491
|
type HighlightsContentsOptions = {
|
|
4479
4492
|
query?: string;
|
|
4493
|
+
/**
|
|
4494
|
+
* Override for an explicit application character limit. Prefer
|
|
4495
|
+
* `highlights: true` to let Exa choose the length based on relevance.
|
|
4496
|
+
* A general need for concise context does not require a fixed limit.
|
|
4497
|
+
*/
|
|
4480
4498
|
maxCharacters?: number;
|
|
4481
4499
|
dynamic?: boolean;
|
|
4482
4500
|
/**
|
|
@@ -4888,7 +4906,15 @@ declare class Exa {
|
|
|
4888
4906
|
rawRequest(endpoint: string, method?: string, body?: Record<string, unknown>, queryParams?: Record<string, string | number | boolean | string[] | undefined>, headers?: Record<string, string>): Promise<Response>;
|
|
4889
4907
|
/**
|
|
4890
4908
|
* Performs a search with an Exa prompt-engineered query.
|
|
4891
|
-
*
|
|
4909
|
+
* For AI answers, RAG, and search previews, prefer query-relevant passages:
|
|
4910
|
+
* `exa.search(query, { contents: { highlights: true } })`.
|
|
4911
|
+
* `highlights: true` is the recommended default: Exa dynamically chooses
|
|
4912
|
+
* the number of characters based on each document's relevance to your query.
|
|
4913
|
+
* You do not need to choose `maxCharacters` to keep context concise;
|
|
4914
|
+
* use it only for an explicit application character-limit requirement.
|
|
4915
|
+
* Read each result's `highlights` array. Request `text` only when you need
|
|
4916
|
+
* the full page; use `contents: false` when you only need titles and URLs.
|
|
4917
|
+
* Omitting contents still returns text by default.
|
|
4892
4918
|
*
|
|
4893
4919
|
* @param {string} query - The query string.
|
|
4894
4920
|
* @returns {Promise<SearchResponse<{ text: { maxCharacters: 10_000 } }>>} A list of relevant search results with text contents.
|
|
@@ -4910,6 +4936,23 @@ declare class Exa {
|
|
|
4910
4936
|
}): Promise<SearchResponse<{}>>;
|
|
4911
4937
|
/**
|
|
4912
4938
|
* Performs a search with specific contents.
|
|
4939
|
+
* Prefer `{ contents: { highlights: true } }` for query-relevant passages
|
|
4940
|
+
* for AI answers, RAG, and search previews. Read `result.highlights`.
|
|
4941
|
+
* `highlights: true` is the recommended default: Exa dynamically chooses
|
|
4942
|
+
* the number of characters based on each document's relevance to your query.
|
|
4943
|
+
* No manual character budget is needed. Set `maxCharacters` only when
|
|
4944
|
+
* your application requires a specific numeric character limit; otherwise
|
|
4945
|
+
* keep `highlights: true`.
|
|
4946
|
+
* Use the boolean `true`; do not set the deprecated `numSentences` or
|
|
4947
|
+
* `highlightsPerUrl` options. Request `text` when you need the full page.
|
|
4948
|
+
*
|
|
4949
|
+
* @example
|
|
4950
|
+
* const response = await exa.search("recent advances in battery recycling", {
|
|
4951
|
+
* contents: { highlights: true },
|
|
4952
|
+
* });
|
|
4953
|
+
* for (const result of response.results) {
|
|
4954
|
+
* console.log(result.url, result.highlights);
|
|
4955
|
+
* }
|
|
4913
4956
|
*
|
|
4914
4957
|
* @param {string} query - The query string.
|
|
4915
4958
|
* @param {RegularSearchOptions & { contents: T }} options - Search options with specific contents
|
|
@@ -4921,6 +4964,8 @@ declare class Exa {
|
|
|
4921
4964
|
/**
|
|
4922
4965
|
* Performs a search with an Exa prompt-engineered query.
|
|
4923
4966
|
* When no contents option is specified, returns text contents by default.
|
|
4967
|
+
* For query-relevant passages, explicitly pass
|
|
4968
|
+
* `{ contents: { highlights: true } }` and read `result.highlights`.
|
|
4924
4969
|
*
|
|
4925
4970
|
* @param {string} query - The query string.
|
|
4926
4971
|
* @param {Omit<DeepSearchOptions, 'contents'> | Omit<NonDeepSearchOptions, 'contents'>} options - Search options without contents
|
|
@@ -5100,4 +5145,4 @@ declare class Exa {
|
|
|
5100
5145
|
private parseSSEStream;
|
|
5101
5146
|
}
|
|
5102
5147
|
|
|
5103
|
-
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
|
|
5148
|
+
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.22.
|
|
103
|
+
version: "2.22.2",
|
|
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.
|
|
@@ -1575,6 +1575,7 @@ var ImportStatus = /* @__PURE__ */ ((ImportStatus2) => {
|
|
|
1575
1575
|
ImportStatus2["processing"] = "processing";
|
|
1576
1576
|
ImportStatus2["completed"] = "completed";
|
|
1577
1577
|
ImportStatus2["failed"] = "failed";
|
|
1578
|
+
ImportStatus2["canceled"] = "canceled";
|
|
1578
1579
|
return ImportStatus2;
|
|
1579
1580
|
})(ImportStatus || {});
|
|
1580
1581
|
var MonitorObject = /* @__PURE__ */ ((MonitorObject2) => {
|
|
@@ -1673,6 +1674,7 @@ var WebsetSearchBehavior = /* @__PURE__ */ ((WebsetSearchBehavior2) => {
|
|
|
1673
1674
|
var WebsetSearchCanceledReason = /* @__PURE__ */ ((WebsetSearchCanceledReason2) => {
|
|
1674
1675
|
WebsetSearchCanceledReason2["webset_deleted"] = "webset_deleted";
|
|
1675
1676
|
WebsetSearchCanceledReason2["webset_canceled"] = "webset_canceled";
|
|
1677
|
+
WebsetSearchCanceledReason2["out_of_credits"] = "out_of_credits";
|
|
1676
1678
|
return WebsetSearchCanceledReason2;
|
|
1677
1679
|
})(WebsetSearchCanceledReason || {});
|
|
1678
1680
|
|
|
@@ -3390,10 +3392,10 @@ var index_default = Exa2;
|
|
|
3390
3392
|
AGENT_MONITORS_BETA_HEADER,
|
|
3391
3393
|
AgentBetaClient,
|
|
3392
3394
|
AgentClient,
|
|
3395
|
+
AgentMonitorBacktestFailedError,
|
|
3396
|
+
AgentMonitorBacktestsClient,
|
|
3393
3397
|
AgentMonitorChangesClient,
|
|
3394
3398
|
AgentMonitorEntitiesClient,
|
|
3395
|
-
AgentMonitorSnapshotFailedError,
|
|
3396
|
-
AgentMonitorSnapshotsClient,
|
|
3397
3399
|
AgentMonitorsClient,
|
|
3398
3400
|
AgentRunCancelledError,
|
|
3399
3401
|
AgentRunEventsClient,
|