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/README.md +8 -0
- package/dist/index.d.mts +37 -8
- package/dist/index.d.ts +37 -8
- package/dist/index.js +56 -30
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +55 -30
- package/dist/index.mjs.map +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -93,6 +93,14 @@ Deep search variants that also support `additionalQueries`:
|
|
|
93
93
|
- `deep`
|
|
94
94
|
- `deep-reasoning`
|
|
95
95
|
|
|
96
|
+
### Raw body fields
|
|
97
|
+
|
|
98
|
+
Pass `requestOptions.body` as the third argument for per-call search body overrides.
|
|
99
|
+
|
|
100
|
+
```typescript
|
|
101
|
+
const result = await exa.search("AI research", undefined, { body: { futureField: true } });
|
|
102
|
+
```
|
|
103
|
+
|
|
96
104
|
## Contents
|
|
97
105
|
|
|
98
106
|
Get clean text, highlights, or summaries from any URL.
|
package/dist/index.d.mts
CHANGED
|
@@ -4016,6 +4016,7 @@ type ToolNamespace = {
|
|
|
4016
4016
|
};
|
|
4017
4017
|
type SearchArgs = {
|
|
4018
4018
|
query: string;
|
|
4019
|
+
objective?: string;
|
|
4019
4020
|
};
|
|
4020
4021
|
type GetContentsArgs = {
|
|
4021
4022
|
urls: string[];
|
|
@@ -4024,6 +4025,8 @@ type WebSearchTool = ExaToolSpec<SearchArgs, SearchResponse<ContentsOptions>>;
|
|
|
4024
4025
|
type GetContentsTool = ExaToolSpec<GetContentsArgs, SearchResponse<ContentsOptions>>;
|
|
4025
4026
|
declare const DEFAULT_WEB_SEARCH_TOOL_DESCRIPTION = "Search the web for up-to-date, relevant information. Describe the ideal page rather than listing keywords.";
|
|
4026
4027
|
declare const 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.";
|
|
4028
|
+
/** Model-facing description of the `objective` search tool parameter. */
|
|
4029
|
+
declare const 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.";
|
|
4027
4030
|
/** Create a `web_search` tool. Defaults to `type: "auto"` and highlights. */
|
|
4028
4031
|
declare function createWebSearchTool(exa: Exa, registry: ToolRegistry, config?: WebSearchToolConfig): WebSearchTool;
|
|
4029
4032
|
/**
|
|
@@ -4300,6 +4303,10 @@ type ContentsOptions = {
|
|
|
4300
4303
|
subpageTarget?: string | string[];
|
|
4301
4304
|
extras?: ExtrasOptions;
|
|
4302
4305
|
};
|
|
4306
|
+
type RequestOptions = {
|
|
4307
|
+
/** Per-call body overrides, except stream. */
|
|
4308
|
+
body?: Record<string, unknown>;
|
|
4309
|
+
};
|
|
4303
4310
|
/**
|
|
4304
4311
|
* Options for performing a search query
|
|
4305
4312
|
* @typedef {Object} SearchOptions
|
|
@@ -4340,6 +4347,14 @@ type BaseSearchOptions = {
|
|
|
4340
4347
|
* Base search options shared across all search types
|
|
4341
4348
|
*/
|
|
4342
4349
|
type BaseRegularSearchOptions = BaseSearchOptions & {
|
|
4350
|
+
/**
|
|
4351
|
+
* The broader goal this search serves: the task the caller is working on,
|
|
4352
|
+
* beyond the query itself. When an agent picks the query as one step of a
|
|
4353
|
+
* larger task, pass the goal of that step — which documents should rank
|
|
4354
|
+
* first, which should be excluded, and what to pull from them. Up to 4096
|
|
4355
|
+
* characters.
|
|
4356
|
+
*/
|
|
4357
|
+
objective?: string;
|
|
4343
4358
|
/**
|
|
4344
4359
|
* If true, the search results are moderated for safety.
|
|
4345
4360
|
*/
|
|
@@ -4776,10 +4791,17 @@ type SearchResponse<T extends ContentsOptions> = {
|
|
|
4776
4791
|
resolvedSearchType?: string;
|
|
4777
4792
|
searchTime?: number;
|
|
4778
4793
|
};
|
|
4794
|
+
/** Error details for a failed content retrieval. */
|
|
4795
|
+
type ContentStatusError = {
|
|
4796
|
+
tag?: string;
|
|
4797
|
+
httpStatusCode?: number | null;
|
|
4798
|
+
};
|
|
4799
|
+
/** Status information for a requested URL. */
|
|
4779
4800
|
type Status = {
|
|
4780
4801
|
id: string;
|
|
4781
4802
|
status: string;
|
|
4782
|
-
source
|
|
4803
|
+
source?: string;
|
|
4804
|
+
error?: ContentStatusError | null;
|
|
4783
4805
|
};
|
|
4784
4806
|
/**
|
|
4785
4807
|
* Options for the answer endpoint
|
|
@@ -4895,6 +4917,7 @@ declare class Exa {
|
|
|
4895
4917
|
* Helper method to separate out the contents-specific options from the rest.
|
|
4896
4918
|
*/
|
|
4897
4919
|
private extractContentsOptions;
|
|
4920
|
+
private mergeSearchRequestBody;
|
|
4898
4921
|
private buildSearchRequestBody;
|
|
4899
4922
|
/**
|
|
4900
4923
|
* Constructs the Exa API client.
|
|
@@ -4926,9 +4949,10 @@ declare class Exa {
|
|
|
4926
4949
|
* Omitting contents still returns text by default.
|
|
4927
4950
|
*
|
|
4928
4951
|
* @param {string} query - The query string.
|
|
4952
|
+
* @param {RequestOptions} [requestOptions] - Per-call body overrides.
|
|
4929
4953
|
* @returns {Promise<SearchResponse<{ text: { maxCharacters: 10_000 } }>>} A list of relevant search results with text contents.
|
|
4930
4954
|
*/
|
|
4931
|
-
search(query: string): Promise<SearchResponse<{
|
|
4955
|
+
search(query: string, options?: undefined, requestOptions?: RequestOptions): Promise<SearchResponse<{
|
|
4932
4956
|
text: {
|
|
4933
4957
|
maxCharacters: 10_000;
|
|
4934
4958
|
};
|
|
@@ -4938,11 +4962,12 @@ declare class Exa {
|
|
|
4938
4962
|
*
|
|
4939
4963
|
* @param {string} query - The query string.
|
|
4940
4964
|
* @param {RegularSearchOptions & { contents: false }} options - Search options with contents explicitly disabled
|
|
4965
|
+
* @param {RequestOptions} [requestOptions] - Per-call body overrides.
|
|
4941
4966
|
* @returns {Promise<SearchResponse<{}>>} A list of relevant search results without contents.
|
|
4942
4967
|
*/
|
|
4943
4968
|
search(query: string, options: RegularSearchOptions & BetaOptions & {
|
|
4944
4969
|
contents: false | null | undefined;
|
|
4945
|
-
}): Promise<SearchResponse<{}>>;
|
|
4970
|
+
}, requestOptions?: RequestOptions): Promise<SearchResponse<{}>>;
|
|
4946
4971
|
/**
|
|
4947
4972
|
* Performs a search with specific contents.
|
|
4948
4973
|
* Prefer `{ contents: { highlights: true } }` for query-relevant passages
|
|
@@ -4965,11 +4990,12 @@ declare class Exa {
|
|
|
4965
4990
|
*
|
|
4966
4991
|
* @param {string} query - The query string.
|
|
4967
4992
|
* @param {RegularSearchOptions & { contents: T }} options - Search options with specific contents
|
|
4993
|
+
* @param {RequestOptions} [requestOptions] - Per-call body overrides.
|
|
4968
4994
|
* @returns {Promise<SearchResponse<T>>} A list of relevant search results with requested contents.
|
|
4969
4995
|
*/
|
|
4970
4996
|
search<T extends ContentsOptions>(query: string, options: RegularSearchOptions & BetaOptions & {
|
|
4971
4997
|
contents: T;
|
|
4972
|
-
}): Promise<SearchResponse<T>>;
|
|
4998
|
+
}, requestOptions?: RequestOptions): Promise<SearchResponse<T>>;
|
|
4973
4999
|
/**
|
|
4974
5000
|
* Performs a search with an Exa prompt-engineered query.
|
|
4975
5001
|
* When no contents option is specified, returns text contents by default.
|
|
@@ -4978,9 +5004,10 @@ declare class Exa {
|
|
|
4978
5004
|
*
|
|
4979
5005
|
* @param {string} query - The query string.
|
|
4980
5006
|
* @param {Omit<DeepSearchOptions, 'contents'> | Omit<NonDeepSearchOptions, 'contents'>} options - Search options without contents
|
|
5007
|
+
* @param {RequestOptions} [requestOptions] - Per-call body overrides.
|
|
4981
5008
|
* @returns {Promise<SearchResponse<{ text: true }>>} A list of relevant search results with text contents.
|
|
4982
5009
|
*/
|
|
4983
|
-
search(query: string, options: (Omit<DeepSearchOptions, "contents"> | Omit<NonDeepSearchOptions, "contents">) & BetaOptions): Promise<SearchResponse<{
|
|
5010
|
+
search(query: string, options: (Omit<DeepSearchOptions, "contents"> | Omit<NonDeepSearchOptions, "contents">) & BetaOptions, requestOptions?: RequestOptions): Promise<SearchResponse<{
|
|
4984
5011
|
text: true;
|
|
4985
5012
|
}>>;
|
|
4986
5013
|
/**
|
|
@@ -4988,10 +5015,11 @@ declare class Exa {
|
|
|
4988
5015
|
*
|
|
4989
5016
|
* Each iteration yields a chunk with partial text (`content`) or new citations.
|
|
4990
5017
|
* Use this if you'd like to read synthesized search output incrementally.
|
|
5018
|
+
* @param {RequestOptions} [requestOptions] - Per-call body overrides.
|
|
4991
5019
|
*/
|
|
4992
5020
|
streamSearch(query: string, options?: RegularSearchOptions & {
|
|
4993
5021
|
contents?: ContentsOptions | false | null | undefined;
|
|
4994
|
-
}): AsyncGenerator<SearchStreamChunk>;
|
|
5022
|
+
}, requestOptions?: RequestOptions): AsyncGenerator<SearchStreamChunk>;
|
|
4995
5023
|
/**
|
|
4996
5024
|
* DEPRECATED: Use `search()` instead. This legacy wrapper will be removed in a future version.
|
|
4997
5025
|
* @deprecated Use `search()` instead. The search method now returns text contents by default.
|
|
@@ -5005,9 +5033,10 @@ declare class Exa {
|
|
|
5005
5033
|
*
|
|
5006
5034
|
* @param {string} query - The query string.
|
|
5007
5035
|
* @param {RegularSearchOptions & T} [options] - Additional search + contents options
|
|
5036
|
+
* @param {RequestOptions} [requestOptions] - Per-call body overrides.
|
|
5008
5037
|
* @returns {Promise<SearchResponse<T>>} A list of relevant search results with requested contents.
|
|
5009
5038
|
*/
|
|
5010
|
-
searchAndContents<T extends ContentsOptions>(query: string, options?: RegularSearchOptions & T): Promise<SearchResponse<T>>;
|
|
5039
|
+
searchAndContents<T extends ContentsOptions>(query: string, options?: RegularSearchOptions & T, requestOptions?: RequestOptions): Promise<SearchResponse<T>>;
|
|
5011
5040
|
/**
|
|
5012
5041
|
* DEPRECATED: Use `search()` for new discovery flows. There is no direct replacement for URL-based similarity.
|
|
5013
5042
|
* @deprecated Use `search()` for new discovery flows. This legacy URL-similarity method will be removed in a future version.
|
|
@@ -5154,4 +5183,4 @@ declare class Exa {
|
|
|
5154
5183
|
private parseSSEStream;
|
|
5155
5184
|
}
|
|
5156
5185
|
|
|
5157
|
-
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 };
|
|
5186
|
+
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 ContentStatusError, 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 RequestOptions, 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, SEARCH_OBJECTIVE_TOOL_DESCRIPTION, 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.d.ts
CHANGED
|
@@ -4016,6 +4016,7 @@ type ToolNamespace = {
|
|
|
4016
4016
|
};
|
|
4017
4017
|
type SearchArgs = {
|
|
4018
4018
|
query: string;
|
|
4019
|
+
objective?: string;
|
|
4019
4020
|
};
|
|
4020
4021
|
type GetContentsArgs = {
|
|
4021
4022
|
urls: string[];
|
|
@@ -4024,6 +4025,8 @@ type WebSearchTool = ExaToolSpec<SearchArgs, SearchResponse<ContentsOptions>>;
|
|
|
4024
4025
|
type GetContentsTool = ExaToolSpec<GetContentsArgs, SearchResponse<ContentsOptions>>;
|
|
4025
4026
|
declare const DEFAULT_WEB_SEARCH_TOOL_DESCRIPTION = "Search the web for up-to-date, relevant information. Describe the ideal page rather than listing keywords.";
|
|
4026
4027
|
declare const 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.";
|
|
4028
|
+
/** Model-facing description of the `objective` search tool parameter. */
|
|
4029
|
+
declare const 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.";
|
|
4027
4030
|
/** Create a `web_search` tool. Defaults to `type: "auto"` and highlights. */
|
|
4028
4031
|
declare function createWebSearchTool(exa: Exa, registry: ToolRegistry, config?: WebSearchToolConfig): WebSearchTool;
|
|
4029
4032
|
/**
|
|
@@ -4300,6 +4303,10 @@ type ContentsOptions = {
|
|
|
4300
4303
|
subpageTarget?: string | string[];
|
|
4301
4304
|
extras?: ExtrasOptions;
|
|
4302
4305
|
};
|
|
4306
|
+
type RequestOptions = {
|
|
4307
|
+
/** Per-call body overrides, except stream. */
|
|
4308
|
+
body?: Record<string, unknown>;
|
|
4309
|
+
};
|
|
4303
4310
|
/**
|
|
4304
4311
|
* Options for performing a search query
|
|
4305
4312
|
* @typedef {Object} SearchOptions
|
|
@@ -4340,6 +4347,14 @@ type BaseSearchOptions = {
|
|
|
4340
4347
|
* Base search options shared across all search types
|
|
4341
4348
|
*/
|
|
4342
4349
|
type BaseRegularSearchOptions = BaseSearchOptions & {
|
|
4350
|
+
/**
|
|
4351
|
+
* The broader goal this search serves: the task the caller is working on,
|
|
4352
|
+
* beyond the query itself. When an agent picks the query as one step of a
|
|
4353
|
+
* larger task, pass the goal of that step — which documents should rank
|
|
4354
|
+
* first, which should be excluded, and what to pull from them. Up to 4096
|
|
4355
|
+
* characters.
|
|
4356
|
+
*/
|
|
4357
|
+
objective?: string;
|
|
4343
4358
|
/**
|
|
4344
4359
|
* If true, the search results are moderated for safety.
|
|
4345
4360
|
*/
|
|
@@ -4776,10 +4791,17 @@ type SearchResponse<T extends ContentsOptions> = {
|
|
|
4776
4791
|
resolvedSearchType?: string;
|
|
4777
4792
|
searchTime?: number;
|
|
4778
4793
|
};
|
|
4794
|
+
/** Error details for a failed content retrieval. */
|
|
4795
|
+
type ContentStatusError = {
|
|
4796
|
+
tag?: string;
|
|
4797
|
+
httpStatusCode?: number | null;
|
|
4798
|
+
};
|
|
4799
|
+
/** Status information for a requested URL. */
|
|
4779
4800
|
type Status = {
|
|
4780
4801
|
id: string;
|
|
4781
4802
|
status: string;
|
|
4782
|
-
source
|
|
4803
|
+
source?: string;
|
|
4804
|
+
error?: ContentStatusError | null;
|
|
4783
4805
|
};
|
|
4784
4806
|
/**
|
|
4785
4807
|
* Options for the answer endpoint
|
|
@@ -4895,6 +4917,7 @@ declare class Exa {
|
|
|
4895
4917
|
* Helper method to separate out the contents-specific options from the rest.
|
|
4896
4918
|
*/
|
|
4897
4919
|
private extractContentsOptions;
|
|
4920
|
+
private mergeSearchRequestBody;
|
|
4898
4921
|
private buildSearchRequestBody;
|
|
4899
4922
|
/**
|
|
4900
4923
|
* Constructs the Exa API client.
|
|
@@ -4926,9 +4949,10 @@ declare class Exa {
|
|
|
4926
4949
|
* Omitting contents still returns text by default.
|
|
4927
4950
|
*
|
|
4928
4951
|
* @param {string} query - The query string.
|
|
4952
|
+
* @param {RequestOptions} [requestOptions] - Per-call body overrides.
|
|
4929
4953
|
* @returns {Promise<SearchResponse<{ text: { maxCharacters: 10_000 } }>>} A list of relevant search results with text contents.
|
|
4930
4954
|
*/
|
|
4931
|
-
search(query: string): Promise<SearchResponse<{
|
|
4955
|
+
search(query: string, options?: undefined, requestOptions?: RequestOptions): Promise<SearchResponse<{
|
|
4932
4956
|
text: {
|
|
4933
4957
|
maxCharacters: 10_000;
|
|
4934
4958
|
};
|
|
@@ -4938,11 +4962,12 @@ declare class Exa {
|
|
|
4938
4962
|
*
|
|
4939
4963
|
* @param {string} query - The query string.
|
|
4940
4964
|
* @param {RegularSearchOptions & { contents: false }} options - Search options with contents explicitly disabled
|
|
4965
|
+
* @param {RequestOptions} [requestOptions] - Per-call body overrides.
|
|
4941
4966
|
* @returns {Promise<SearchResponse<{}>>} A list of relevant search results without contents.
|
|
4942
4967
|
*/
|
|
4943
4968
|
search(query: string, options: RegularSearchOptions & BetaOptions & {
|
|
4944
4969
|
contents: false | null | undefined;
|
|
4945
|
-
}): Promise<SearchResponse<{}>>;
|
|
4970
|
+
}, requestOptions?: RequestOptions): Promise<SearchResponse<{}>>;
|
|
4946
4971
|
/**
|
|
4947
4972
|
* Performs a search with specific contents.
|
|
4948
4973
|
* Prefer `{ contents: { highlights: true } }` for query-relevant passages
|
|
@@ -4965,11 +4990,12 @@ declare class Exa {
|
|
|
4965
4990
|
*
|
|
4966
4991
|
* @param {string} query - The query string.
|
|
4967
4992
|
* @param {RegularSearchOptions & { contents: T }} options - Search options with specific contents
|
|
4993
|
+
* @param {RequestOptions} [requestOptions] - Per-call body overrides.
|
|
4968
4994
|
* @returns {Promise<SearchResponse<T>>} A list of relevant search results with requested contents.
|
|
4969
4995
|
*/
|
|
4970
4996
|
search<T extends ContentsOptions>(query: string, options: RegularSearchOptions & BetaOptions & {
|
|
4971
4997
|
contents: T;
|
|
4972
|
-
}): Promise<SearchResponse<T>>;
|
|
4998
|
+
}, requestOptions?: RequestOptions): Promise<SearchResponse<T>>;
|
|
4973
4999
|
/**
|
|
4974
5000
|
* Performs a search with an Exa prompt-engineered query.
|
|
4975
5001
|
* When no contents option is specified, returns text contents by default.
|
|
@@ -4978,9 +5004,10 @@ declare class Exa {
|
|
|
4978
5004
|
*
|
|
4979
5005
|
* @param {string} query - The query string.
|
|
4980
5006
|
* @param {Omit<DeepSearchOptions, 'contents'> | Omit<NonDeepSearchOptions, 'contents'>} options - Search options without contents
|
|
5007
|
+
* @param {RequestOptions} [requestOptions] - Per-call body overrides.
|
|
4981
5008
|
* @returns {Promise<SearchResponse<{ text: true }>>} A list of relevant search results with text contents.
|
|
4982
5009
|
*/
|
|
4983
|
-
search(query: string, options: (Omit<DeepSearchOptions, "contents"> | Omit<NonDeepSearchOptions, "contents">) & BetaOptions): Promise<SearchResponse<{
|
|
5010
|
+
search(query: string, options: (Omit<DeepSearchOptions, "contents"> | Omit<NonDeepSearchOptions, "contents">) & BetaOptions, requestOptions?: RequestOptions): Promise<SearchResponse<{
|
|
4984
5011
|
text: true;
|
|
4985
5012
|
}>>;
|
|
4986
5013
|
/**
|
|
@@ -4988,10 +5015,11 @@ declare class Exa {
|
|
|
4988
5015
|
*
|
|
4989
5016
|
* Each iteration yields a chunk with partial text (`content`) or new citations.
|
|
4990
5017
|
* Use this if you'd like to read synthesized search output incrementally.
|
|
5018
|
+
* @param {RequestOptions} [requestOptions] - Per-call body overrides.
|
|
4991
5019
|
*/
|
|
4992
5020
|
streamSearch(query: string, options?: RegularSearchOptions & {
|
|
4993
5021
|
contents?: ContentsOptions | false | null | undefined;
|
|
4994
|
-
}): AsyncGenerator<SearchStreamChunk>;
|
|
5022
|
+
}, requestOptions?: RequestOptions): AsyncGenerator<SearchStreamChunk>;
|
|
4995
5023
|
/**
|
|
4996
5024
|
* DEPRECATED: Use `search()` instead. This legacy wrapper will be removed in a future version.
|
|
4997
5025
|
* @deprecated Use `search()` instead. The search method now returns text contents by default.
|
|
@@ -5005,9 +5033,10 @@ declare class Exa {
|
|
|
5005
5033
|
*
|
|
5006
5034
|
* @param {string} query - The query string.
|
|
5007
5035
|
* @param {RegularSearchOptions & T} [options] - Additional search + contents options
|
|
5036
|
+
* @param {RequestOptions} [requestOptions] - Per-call body overrides.
|
|
5008
5037
|
* @returns {Promise<SearchResponse<T>>} A list of relevant search results with requested contents.
|
|
5009
5038
|
*/
|
|
5010
|
-
searchAndContents<T extends ContentsOptions>(query: string, options?: RegularSearchOptions & T): Promise<SearchResponse<T>>;
|
|
5039
|
+
searchAndContents<T extends ContentsOptions>(query: string, options?: RegularSearchOptions & T, requestOptions?: RequestOptions): Promise<SearchResponse<T>>;
|
|
5011
5040
|
/**
|
|
5012
5041
|
* DEPRECATED: Use `search()` for new discovery flows. There is no direct replacement for URL-based similarity.
|
|
5013
5042
|
* @deprecated Use `search()` for new discovery flows. This legacy URL-similarity method will be removed in a future version.
|
|
@@ -5154,4 +5183,4 @@ declare class Exa {
|
|
|
5154
5183
|
private parseSSEStream;
|
|
5155
5184
|
}
|
|
5156
5185
|
|
|
5157
|
-
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 };
|
|
5186
|
+
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 ContentStatusError, 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 RequestOptions, 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, SEARCH_OBJECTIVE_TOOL_DESCRIPTION, 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
|
@@ -68,6 +68,7 @@ __export(index_exports, {
|
|
|
68
68
|
MonitorStatus: () => MonitorStatus,
|
|
69
69
|
OpenAIResponsesTools: () => OpenAIResponsesTools,
|
|
70
70
|
OpenAITools: () => OpenAITools,
|
|
71
|
+
SEARCH_OBJECTIVE_TOOL_DESCRIPTION: () => SEARCH_OBJECTIVE_TOOL_DESCRIPTION,
|
|
71
72
|
SearchMonitorRunsClient: () => SearchMonitorRunsClient,
|
|
72
73
|
SearchMonitorsClient: () => SearchMonitorsClient,
|
|
73
74
|
ToolRegistry: () => ToolRegistry,
|
|
@@ -100,7 +101,7 @@ var import_cross_fetch = __toESM(require("cross-fetch"));
|
|
|
100
101
|
// package.json
|
|
101
102
|
var package_default = {
|
|
102
103
|
name: "exa-js",
|
|
103
|
-
version: "2.
|
|
104
|
+
version: "2.25.0",
|
|
104
105
|
description: "Exa SDK for Node.js and the browser",
|
|
105
106
|
publishConfig: {
|
|
106
107
|
access: "public"
|
|
@@ -2427,6 +2428,8 @@ var WebsetsClient = class extends WebsetsBaseClient {
|
|
|
2427
2428
|
var import_zod2 = require("zod");
|
|
2428
2429
|
var DEFAULT_WEB_SEARCH_TOOL_DESCRIPTION = "Search the web for up-to-date, relevant information. Describe the ideal page rather than listing keywords.";
|
|
2429
2430
|
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.";
|
|
2431
|
+
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.";
|
|
2432
|
+
var MAX_OBJECTIVE_LENGTH = 4096;
|
|
2430
2433
|
function formatResults(response, emptyMessage) {
|
|
2431
2434
|
const formatted = response.results.map((result) => {
|
|
2432
2435
|
const lines = [
|
|
@@ -2480,6 +2483,17 @@ function createTool(registry, params) {
|
|
|
2480
2483
|
};
|
|
2481
2484
|
return registerTool(registry, tool);
|
|
2482
2485
|
}
|
|
2486
|
+
var AdvertisedRequiredOptional = class extends import_zod2.z.ZodOptional {
|
|
2487
|
+
isOptional() {
|
|
2488
|
+
return false;
|
|
2489
|
+
}
|
|
2490
|
+
};
|
|
2491
|
+
function advertisedRequired(inner) {
|
|
2492
|
+
return new AdvertisedRequiredOptional({
|
|
2493
|
+
innerType: inner,
|
|
2494
|
+
typeName: import_zod2.z.ZodFirstPartyTypeKind.ZodOptional
|
|
2495
|
+
});
|
|
2496
|
+
}
|
|
2483
2497
|
function createWebSearchTool(exa, registry, config = {}) {
|
|
2484
2498
|
const {
|
|
2485
2499
|
name = "web_search",
|
|
@@ -2489,7 +2503,15 @@ function createWebSearchTool(exa, registry, config = {}) {
|
|
|
2489
2503
|
const inputSchema = import_zod2.z.object({
|
|
2490
2504
|
query: import_zod2.z.string().describe(
|
|
2491
2505
|
"Natural language search query. Should be a semantically rich description of the ideal page, not just keywords."
|
|
2492
|
-
)
|
|
2506
|
+
),
|
|
2507
|
+
// Length limits are validated but not advertised: strict tool use on some
|
|
2508
|
+
// providers rejects `minLength`/`maxLength` in the schema.
|
|
2509
|
+
objective: advertisedRequired(
|
|
2510
|
+
import_zod2.z.string().trim().refine((value) => value.length > 0, "objective must not be empty").refine(
|
|
2511
|
+
(value) => value.length <= MAX_OBJECTIVE_LENGTH,
|
|
2512
|
+
`objective must be at most ${MAX_OBJECTIVE_LENGTH} characters`
|
|
2513
|
+
)
|
|
2514
|
+
).describe(SEARCH_OBJECTIVE_TOOL_DESCRIPTION)
|
|
2493
2515
|
});
|
|
2494
2516
|
const jsonSchema = zodToJsonSchema(inputSchema);
|
|
2495
2517
|
delete jsonSchema.$schema;
|
|
@@ -2503,12 +2525,13 @@ function createWebSearchTool(exa, registry, config = {}) {
|
|
|
2503
2525
|
description,
|
|
2504
2526
|
parameters: jsonSchema
|
|
2505
2527
|
},
|
|
2506
|
-
execute: ({ query }) => {
|
|
2528
|
+
execute: ({ query, objective }) => {
|
|
2507
2529
|
const options = {
|
|
2508
2530
|
type: "auto",
|
|
2509
2531
|
numResults: 10,
|
|
2510
2532
|
contents: { highlights: true },
|
|
2511
|
-
...searchOptions
|
|
2533
|
+
...searchOptions,
|
|
2534
|
+
...objective !== void 0 && { objective }
|
|
2512
2535
|
};
|
|
2513
2536
|
return exa.search(query, options);
|
|
2514
2537
|
},
|
|
@@ -2923,30 +2946,27 @@ var Exa2 = class {
|
|
|
2923
2946
|
if (livecrawlTimeout !== void 0)
|
|
2924
2947
|
contentsOptions.livecrawlTimeout = livecrawlTimeout;
|
|
2925
2948
|
if (maxAgeHours !== void 0) contentsOptions.maxAgeHours = maxAgeHours;
|
|
2926
|
-
if (snapshotAsOf !== void 0)
|
|
2927
|
-
contentsOptions.snapshotAsOf = snapshotAsOf;
|
|
2949
|
+
if (snapshotAsOf !== void 0) contentsOptions.snapshotAsOf = snapshotAsOf;
|
|
2928
2950
|
if (context !== void 0) contentsOptions.context = context;
|
|
2929
2951
|
return {
|
|
2930
2952
|
contentsOptions,
|
|
2931
2953
|
restOptions: rest
|
|
2932
2954
|
};
|
|
2933
2955
|
}
|
|
2934
|
-
|
|
2935
|
-
const
|
|
2936
|
-
delete
|
|
2937
|
-
|
|
2956
|
+
mergeSearchRequestBody(body, requestOptions) {
|
|
2957
|
+
const merged = { ...body, ...requestOptions?.body };
|
|
2958
|
+
delete merged.stream;
|
|
2959
|
+
return merged;
|
|
2960
|
+
}
|
|
2961
|
+
buildSearchRequestBody(query, options, requestOptions) {
|
|
2962
|
+
const body = { ...options ?? {} };
|
|
2963
|
+
delete body.betas;
|
|
2938
2964
|
if (options === void 0 || !("contents" in options)) {
|
|
2939
|
-
|
|
2940
|
-
|
|
2941
|
-
|
|
2942
|
-
contents: { text: { maxCharacters: DEFAULT_MAX_CHARACTERS } }
|
|
2943
|
-
};
|
|
2965
|
+
body.contents = { text: { maxCharacters: DEFAULT_MAX_CHARACTERS } };
|
|
2966
|
+
} else if (options.contents === false || options.contents === null || options.contents === void 0) {
|
|
2967
|
+
delete body.contents;
|
|
2944
2968
|
}
|
|
2945
|
-
|
|
2946
|
-
delete requestOptions.contents;
|
|
2947
|
-
return { query, ...requestOptions };
|
|
2948
|
-
}
|
|
2949
|
-
return { query, ...requestOptions };
|
|
2969
|
+
return this.mergeSearchRequestBody({ query, ...body }, requestOptions);
|
|
2950
2970
|
}
|
|
2951
2971
|
/**
|
|
2952
2972
|
* Makes a request to the Exa API.
|
|
@@ -3081,14 +3101,14 @@ var Exa2 = class {
|
|
|
3081
3101
|
});
|
|
3082
3102
|
return response;
|
|
3083
3103
|
}
|
|
3084
|
-
async search(query, options) {
|
|
3104
|
+
async search(query, options, requestOptions) {
|
|
3085
3105
|
if (options?.stream) {
|
|
3086
3106
|
throw new ExaError(
|
|
3087
3107
|
"For streaming responses, please use streamSearch() instead:\n\nfor await (const chunk of exa.streamSearch(query)) {\n // Handle chunks\n}",
|
|
3088
3108
|
400 /* BadRequest */
|
|
3089
3109
|
);
|
|
3090
3110
|
}
|
|
3091
|
-
const body = this.buildSearchRequestBody(query, options);
|
|
3111
|
+
const body = this.buildSearchRequestBody(query, options, requestOptions);
|
|
3092
3112
|
const betaHeaders = headersForBetas(options?.betas);
|
|
3093
3113
|
return betaHeaders ? await this.request("/search", "POST", body, void 0, betaHeaders) : await this.request("/search", "POST", body);
|
|
3094
3114
|
}
|
|
@@ -3097,10 +3117,11 @@ var Exa2 = class {
|
|
|
3097
3117
|
*
|
|
3098
3118
|
* Each iteration yields a chunk with partial text (`content`) or new citations.
|
|
3099
3119
|
* Use this if you'd like to read synthesized search output incrementally.
|
|
3120
|
+
* @param {RequestOptions} [requestOptions] - Per-call body overrides.
|
|
3100
3121
|
*/
|
|
3101
|
-
streamSearch(query, options) {
|
|
3122
|
+
streamSearch(query, options, requestOptions) {
|
|
3102
3123
|
return this.streamChatCompletions("/search", {
|
|
3103
|
-
...this.buildSearchRequestBody(query, options),
|
|
3124
|
+
...this.buildSearchRequestBody(query, options, requestOptions),
|
|
3104
3125
|
stream: true
|
|
3105
3126
|
});
|
|
3106
3127
|
}
|
|
@@ -3117,20 +3138,24 @@ var Exa2 = class {
|
|
|
3117
3138
|
*
|
|
3118
3139
|
* @param {string} query - The query string.
|
|
3119
3140
|
* @param {RegularSearchOptions & T} [options] - Additional search + contents options
|
|
3141
|
+
* @param {RequestOptions} [requestOptions] - Per-call body overrides.
|
|
3120
3142
|
* @returns {Promise<SearchResponse<T>>} A list of relevant search results with requested contents.
|
|
3121
3143
|
*/
|
|
3122
|
-
async searchAndContents(query, options) {
|
|
3144
|
+
async searchAndContents(query, options, requestOptions) {
|
|
3123
3145
|
const { contentsOptions, restOptions } = options === void 0 ? {
|
|
3124
3146
|
contentsOptions: {
|
|
3125
3147
|
text: { maxCharacters: DEFAULT_MAX_CHARACTERS }
|
|
3126
3148
|
},
|
|
3127
3149
|
restOptions: {}
|
|
3128
3150
|
} : this.extractContentsOptions(options);
|
|
3129
|
-
return await this.request(
|
|
3130
|
-
|
|
3131
|
-
|
|
3132
|
-
|
|
3133
|
-
|
|
3151
|
+
return await this.request(
|
|
3152
|
+
"/search",
|
|
3153
|
+
"POST",
|
|
3154
|
+
this.mergeSearchRequestBody(
|
|
3155
|
+
{ query, contents: contentsOptions, ...restOptions },
|
|
3156
|
+
requestOptions
|
|
3157
|
+
)
|
|
3158
|
+
);
|
|
3134
3159
|
}
|
|
3135
3160
|
async findSimilar(url, options) {
|
|
3136
3161
|
if (options === void 0 || !("contents" in options)) {
|
|
@@ -3432,6 +3457,7 @@ var index_default = Exa2;
|
|
|
3432
3457
|
MonitorStatus,
|
|
3433
3458
|
OpenAIResponsesTools,
|
|
3434
3459
|
OpenAITools,
|
|
3460
|
+
SEARCH_OBJECTIVE_TOOL_DESCRIPTION,
|
|
3435
3461
|
SearchMonitorRunsClient,
|
|
3436
3462
|
SearchMonitorsClient,
|
|
3437
3463
|
ToolRegistry,
|