exa-js 1.7.0 → 1.7.2

package/README.md

@@ -8,71 +8,91 @@ features associated with Metaphor's rename to Exa. New site is https://exa.ai
 https://www.npmjs.com/package/exa-js
 
 ## Installation
+
 ```
 npm install exa-js
 ```
 
-## Initialization 
+## Initialization
+
 ```js
-import Exa from "exa-js"
+import Exa from "exa-js";
 
-const exa = new Exa(process.env.EXA_API_KEY)
+const exa = new Exa(process.env.EXA_API_KEY);
 ```
 
 ### Common commands
 
 ```js
-
 // Basic search
 const basicResults = await exa.search("This is a Exa query:");
 
 // Search with date filters
 const dateFilteredResults = await exa.search("This is a Exa query:", {
   startPublishedDate: "2019-01-01",
-  endPublishedDate: "2019-01-31"
+  endPublishedDate: "2019-01-31",
 });
 
 // Search with domain filters
 const domainFilteredResults = await exa.search("This is a Exa query:", {
-  includeDomains: ["www.cnn.com", "www.nytimes.com"]
+  includeDomains: ["www.cnn.com", "www.nytimes.com"],
 });
 
 // Search and get text contents
-const searchAndTextResults = await exa.searchAndContents("This is a Exa query:", { text: true });
+const searchAndTextResults = await exa.searchAndContents(
+  "This is a Exa query:",
+  { text: true }
+);
 
 // Search and get contents with contents options
-const searchAndCustomContentsResults = await exa.searchAndContents("This is a Exa query:", {
-  text: { maxCharacters: 3000 }
-});
+const searchAndCustomContentsResults = await exa.searchAndContents(
+  "This is a Exa query:",
+  {
+    text: { maxCharacters: 3000 },
+  }
+);
 
 // Find similar documents
 const similarResults = await exa.findSimilar("https://example.com");
 
 // Find similar excluding source domain
-const similarExcludingSourceResults = await exa.findSimilar("https://example.com", { excludeSourceDomain: true });
+const similarExcludingSourceResults = await exa.findSimilar(
+  "https://example.com",
+  { excludeSourceDomain: true }
+);
 
 // Find similar with contents
-const similarWithContentsResults = await exa.findSimilarAndContents("https://example.com", { text: true });
+const similarWithContentsResults = await exa.findSimilarAndContents(
+  "https://example.com",
+  { text: true }
+);
 
 // Get text contents
 const textContentsResults = await exa.getContents(["urls"], { text: true });
 
 // Get contents with contents options
 const customContentsResults = await exa.getContents(["urls"], {
-  text: { includeHtmlTags: true, maxCharacters: 3000 }
+  text: { includeHtmlTags: true, maxCharacters: 3000 },
 });
 
 // Get an answer to a question
-const answerResult = await exa.answer("What is the population of New York City?");
-
-// Get answer with citation contents and use the exa-pro model, which passes 2 extra queries to exa to increase coverage of the search space. 
-const answerWithTextResults = await exa.answer("What is the population of New York City?", {
-  text: true,
-  model: "exa-pro"
-});
+const answerResult = await exa.answer(
+  "What is the population of New York City?"
+);
+
+// Get answer with citation contents and use the exa-pro model, which passes 2 extra queries to exa to increase coverage of the search space.
+const answerWithTextResults = await exa.answer(
+  "What is the population of New York City?",
+  {
+    text: true,
+    model: "exa-pro",
+  }
+);
 
 // Get an answer with streaming
-for await (const chunk of exa.streamAnswer("What is the population of New York City?")) {
+for await (const chunk of exa.streamAnswer(
+  "What is the population of New York City?"
+)) {
   if (chunk.content) {
     process.stdout.write(chunk.content);
   }
@@ -80,45 +100,72 @@ for await (const chunk of exa.streamAnswer("What is the population of New York C
     console.log("\nCitations:", chunk.citations);
   }
 }
+
+// Get an answer with output schema
+const answerResult = await exa.answer(
+  "What is the population of New York City?",
+  {
+    outputSchema: {
+      type: "object",
+      required: ["answer"],
+      additionalProperties: false,
+      properties: {
+        answer: {
+          type: "number",
+        },
+      },
+    },
+  }
+);
 ```
 
 ### `exa.search(query: string, options?: SearchOptions): Promise<SearchResponse>`
+
 Performs a search on the Exa system with the given parameters.
 
 ```javascript
-const response = await exa.search('funny article about tech culture', {
+const response = await exa.search("funny article about tech culture", {
   numResults: 5,
-  includeDomains: ['nytimes.com', 'wsj.com'], 
-  startPublishedDate: '2023-06-12'
+  includeDomains: ["nytimes.com", "wsj.com"],
+  startPublishedDate: "2023-06-12",
 });
 ```
 
 ### `exa.findSimilar(url: string, options?: FindSimilarOptions): Promise<SearchResponse>`
+
 Finds content similar to the specified URL.
 
 ```javascript
-const response = await exa.findSimilar('https://waitbutwhy.com/2014/05/fermi-paradox.html', {
-  numResults: 10
-});
+const response = await exa.findSimilar(
+  "https://waitbutwhy.com/2014/05/fermi-paradox.html",
+  {
+    numResults: 10,
+  }
+);
 ```
 
 ### `exa.getContents(urls: string[] | Result[]): Promise<GetContentsResponse>`
+
 Retrieves the contents of the specified documents.
 
 ```javascript
-const response = await exa.getContents(['https://blog.samaltman.com/how-to-be-successful']);
+const response = await exa.getContents([
+  "https://blog.samaltman.com/how-to-be-successful",
+]);
 ```
 
 ### `exa.answer(query: string, options?: AnswerOptions): Promise<AnswerResponse>`
+
 Generates an answer to a query using search results as context.
 
 ```javascript
-const response = await exa.answer('What is the population of New York City?', {
-  text: true
+const response = await exa.answer("What is the population of New York City?", {
+  text: true,
 });
 ```
 
 ### `exa.streamAnswer(query: string, options?: { text?: boolean }): AsyncGenerator<AnswerStreamChunk>`
+
 Streams an answer as it's being generated, yielding chunks of text and citations. This is useful for providing real-time updates in chat interfaces or displaying partial results as they become available.
 
 ```javascript
@@ -132,13 +179,44 @@ for await (const chunk of exa.streamAnswer("What is quantum computing?")) {
   }
 }
 
-for await (const chunk of exa.streamAnswer("What is quantum computing?", { text: true })) {
+for await (const chunk of exa.streamAnswer("What is quantum computing?", {
+  text: true,
+})) {
 }
 ```
 
 Each chunk contains:
+
 - `content`: A string containing the next piece of generated text
 - `citations`: An array of citation objects containing source information
 
+### `exa.research.createTask(input: object, options?: { schema?: object }): Promise<ResearchTaskResponse>`
+
+Exa's research agent can autonomously gather information and return a structured JSON object that conforms to a schema you provide.
+
+```javascript
+import Exa from "exa-js";
+
+const exa = new Exa(process.env.EXA_API_KEY);
+
+const schema = {
+  type: "object",
+  required: ["answer"],
+  properties: {
+    answer: { type: "string" },
+  },
+};
+
+const response = await exa.research.createTask(
+  {
+    instructions: "In ≤3 sentences, explain quantum computing.",
+  },
+  { schema }
+);
+```
+
+Use the `status` field to poll long-running tasks if needed (a future `getTask` helper will be added when the async API is released).
+
 # Contributing
+
 Pull requests are welcome! For major changes, please open an issue first to discuss what you would like to change.

package/dist/index.d.mts

@@ -5,11 +5,11 @@
 /**
  * Type for API query parameters
  */
-type QueryParams = Record<string, string | number | boolean | string[] | undefined>;
+type QueryParams$1 = Record<string, string | number | boolean | string[] | undefined>;
 /**
  * Type for API request body
  */
-interface RequestBody {
+interface RequestBody$1 {
     [key: string]: unknown;
 }
 /**
@@ -44,13 +44,13 @@ declare class WebsetsBaseClient {
      * @returns The response JSON
      * @throws ExaError with API error details if the request fails
      */
-    protected request<T = unknown>(endpoint: string, method?: string, data?: RequestBody, params?: QueryParams): Promise<T>;
+    protected request<T = unknown>(endpoint: string, method?: string, data?: RequestBody$1, params?: QueryParams$1): Promise<T>;
     /**
      * Helper to build pagination parameters
      * @param pagination The pagination parameters
      * @returns QueryParams object with pagination parameters
      */
-    protected buildPaginationParams(pagination?: PaginationParams): QueryParams;
+    protected buildPaginationParams(pagination?: PaginationParams): QueryParams$1;
 }
 
 interface components {
@@ -1340,6 +1340,93 @@ declare class WebsetsClient extends WebsetsBaseClient {
     } | number): Promise<Webset>;
 }
 
+/**
+ * Enum representing the status of a research task.
+ */
+declare enum ResearchStatus {
+    /** The research request has finished successfully. */
+    completed = "completed",
+    /** The research request failed. */
+    failed = "failed"
+}
+/**
+ * Response object returned from the research API.
+ */
+type ResearchTaskResponse = {
+    /** Unique identifier for the task. */
+    id: string;
+    /** Current status (may include future enum values served by the API). */
+    status: ResearchStatus | string;
+    /** Structured output that follows the user-provided schema (null while running). */
+    output: Record<string, any> | null;
+    /**
+     * Citations collected while deriving each top-level field in `output`.
+     * The key is the field name, the value is the list of `SearchResult`s that
+     * were used to compute that field.
+     */
+    citations: Record<string, SearchResult<{}>[]>;
+};
+
+type QueryParams = Record<string, string | number | boolean | string[] | undefined>;
+interface RequestBody {
+    [key: string]: unknown;
+}
+/**
+ * Base client class for all Research-related API clients
+ */
+declare class ResearchBaseClient {
+    protected client: Exa;
+    /**
+     * Initialize a new Research base client
+     * @param client The Exa client instance
+     */
+    constructor(client: Exa);
+    /**
+     * Make a request to the Research API (prefixes all paths with `/research`).
+     * @param endpoint The endpoint path, beginning with a slash (e.g. "/tasks").
+     * @param method The HTTP method. Defaults to "POST".
+     * @param data Optional request body
+     * @param params Optional query parameters
+     * @returns The parsed JSON response
+     */
+    protected request<T = unknown>(endpoint: string, method?: string, data?: RequestBody, params?: QueryParams): Promise<T>;
+}
+
+/**
+ * Client for interacting with the Research Tasks API.
+ */
+declare class ResearchClient extends ResearchBaseClient {
+    constructor(client: Exa);
+    /**
+     * Create and run a research task (blocking call).
+     *
+     * Both parameters are required and have fixed shapes:
+     * 1. `input`
+     *      `{ instructions: string }`
+     *     • `instructions` – High-level guidance that tells the research agent what to do.
+     * 2. `output`
+     *    defines the exact structure you expect back, and guides the research conducted by the agent.
+     *      `{ schema: JSONSchema }`.
+     *    The agent's response will be validated against this schema.
+     *
+     * @param input  Object containing high-level research instructions.
+     * @param output Object containing the expected output schema.
+     * @returns The ResearchTaskResponse returned by the API.
+     */
+    createTask(input: {
+        instructions: string;
+    }, output: {
+        schema: JSONSchema;
+    }): Promise<ResearchTaskResponse>;
+    /**
+     * Retrieve a research task by ID.
+     *
+     * Not yet implemented server-side. Calling this will throw until the API is
+     * available.
+     */
+    getTask(): Promise<ResearchTaskResponse>;
+}
+
 /**
  * HTTP status codes
  */
@@ -1644,23 +1731,25 @@ type SearchResponse<T extends ContentsOptions> = {
  * @property {boolean} [text] - Whether to include text in the source results. Default false.
  * @property {"exa" | "exa-pro"} [model] - The model to use for generating the answer. Default "exa".
  * @property {string} [systemPrompt] - A system prompt to guide the LLM's behavior when generating the answer.
+ * @property {Object} [outputSchema] - A JSON Schema specification for the structure you expect the output to take
  */
 type AnswerOptions = {
     stream?: boolean;
     text?: boolean;
     model?: "exa" | "exa-pro";
     systemPrompt?: string;
+    outputSchema?: Record<string, unknown>;
 };
 /**
  * Represents an answer response object from the /answer endpoint.
  * @typedef {Object} AnswerResponse
- * @property {string} answer - The generated answer text.
+ * @property {string | Object} answer - The generated answer text (or an object matching `outputSchema`, if provided)
  * @property {SearchResult<{}>[]} citations - The sources used to generate the answer.
  * @property {CostDollars} [costDollars] - The cost breakdown for this request.
  * @property {string} [requestId] - Optional request ID for the answer.
  */
 type AnswerResponse = {
-    answer: string;
+    answer: string | Record<string, unknown>;
     citations: SearchResult<{}>[];
     requestId?: string;
     costDollars?: CostDollars;
@@ -1692,29 +1781,6 @@ type AnswerStreamResponse = {
     answer?: string;
     citations?: SearchResult<{}>[];
 };
-/**
- * Enum representing the status of a research task.
- */
-declare enum ResearchStatus {
-    /** The research request has finished successfully. */
-    completed = "completed",
-    /** The research request failed. */
-    failed = "failed"
-}
-/**
- * @typedef {Object} ResearchTaskResponse
- * @property {string} id - The unique identifier of the research request.
- * @property {ResearchStatus | string} status - The current status of the research request.
- * @property {Record<string, any> | null} output - The structured output, if the research has completed.
- * @property {SearchResult<{}>[]} citations - References used for the research.
- */
-type ResearchTaskResponse = {
-    id: string;
-    status: ResearchStatus | string;
-    output: Record<string, any> | null;
-    citations: SearchResult<{}>[];
-};
-
 /**
  * The Exa class encapsulates the API's endpoints.
  */
@@ -1725,6 +1791,10 @@ declare class Exa {
      * Websets API client
      */
     websets: WebsetsClient;
+    /**
+     * Research API client
+     */
+    research: ResearchClient;
     /**
      * Helper method to separate out the contents-specific options from the rest.
      */
@@ -1828,44 +1898,10 @@ declare class Exa {
         text?: boolean;
         model?: "exa" | "exa-pro";
         systemPrompt?: string;
+        outputSchema?: Record<string, unknown>;
     }): AsyncGenerator<AnswerStreamChunk>;
     private processChunk;
-    /**
-     * Creates and runs a research task in a blocking manner.
-     *
-     * Both parameters are required and have fixed shapes:
-     * 1. `input`
-     *      `{ instructions: string }`
-     *     • `instructions` – High-level guidance that tells the research agent what to do.
-     * 2. `output`
-     *    defines the exact structure you expect back, and guides the research conducted by the agent.
-     *      `{ schema: JSONSchema }`.
-     *    The agent’s response will be validated against this schema.
-     *
-     * @param {{ instructions: string }} input   The research prompt.
-     * @param {{ schema: JSONSchema }}                output  The desired output schema.
-     * @returns {Promise<ResearchTaskResponse>}                     The research response.
-     *
-     * @example
-     * const response = await exa.researchTask(
-     *   { instructions: "I need a few key facts about honey pot ants." },
-     *   {
-     *     schema: {
-     *       type: "object",
-     *       required: ["scientificName", "primaryRegions"],
-     *       properties: {
-     *         scientificName: { type: "string" },
-     *         primaryRegions:  { type: "string" },
-     *       },
-     *     },
-     *   },
-     * );
-     */
-    researchTask(input: {
-        instructions: string;
-    }, output: {
-        schema: JSONSchema;
-    }): Promise<ResearchTaskResponse>;
+    private parseSSEStream;
 }
 
-export { type AnswerOptions, type AnswerResponse, type AnswerStreamChunk, type AnswerStreamResponse, type BaseSearchOptions, type ContentsOptions, type ContentsResultComponent, type CostDollars, type CostDollarsContents, type CostDollarsSeearch, type CreateEnrichmentParameters, CreateEnrichmentParametersFormat, type CreateWebhookParameters, type CreateWebsetParameters, type CreateWebsetSearchParameters, CreateWebsetSearchParametersBehaviour, type Default, type EnrichmentResult, type Event, EventType, Exa, ExaError, type ExtrasOptions, type ExtrasResponse, type FindSimilarOptions, type GetWebsetResponse, type HighlightsContentsOptions, type HighlightsResponse, HttpStatusCode, type JSONSchema, type ListEventsResponse, type ListWebhooksOptions, type ListWebhooksResponse, type ListWebsetItemResponse, type ListWebsetsOptions, type ListWebsetsResponse, type LivecrawlOptions, type RegularSearchOptions, ResearchStatus, type ResearchTaskResponse, type SearchResponse, type SearchResult, type SubpagesResponse, type SummaryContentsOptions, type SummaryResponse, type TextContentsOptions, type TextResponse, type UpdateWebhookParameters, type UpdateWebsetRequest, type Webhook, WebhookStatus, type Webset, type WebsetEnrichment, WebsetEnrichmentFormat, WebsetEnrichmentStatus, WebsetEnrichmentsClient, type WebsetItem, WebsetItemEvaluationSatisfied, WebsetItemSource, WebsetItemsClient, type WebsetSearch, WebsetSearchCanceledReason, WebsetSearchStatus, WebsetSearchesClient, WebsetStatus, WebsetWebhooksClient, WebsetsClient, Exa as default };
+export { type AnswerOptions, type AnswerResponse, type AnswerStreamChunk, type AnswerStreamResponse, type BaseSearchOptions, type ContentsOptions, type ContentsResultComponent, type CostDollars, type CostDollarsContents, type CostDollarsSeearch, type CreateEnrichmentParameters, CreateEnrichmentParametersFormat, type CreateWebhookParameters, type CreateWebsetParameters, type CreateWebsetSearchParameters, CreateWebsetSearchParametersBehaviour, type Default, type EnrichmentResult, type Event, EventType, Exa, ExaError, type ExtrasOptions, type ExtrasResponse, type FindSimilarOptions, type GetWebsetResponse, type HighlightsContentsOptions, type HighlightsResponse, HttpStatusCode, type JSONSchema, type ListEventsResponse, type ListWebhooksOptions, type ListWebhooksResponse, type ListWebsetItemResponse, type ListWebsetsOptions, type ListWebsetsResponse, type LivecrawlOptions, type RegularSearchOptions, ResearchClient, ResearchStatus, type ResearchTaskResponse, type SearchResponse, type SearchResult, type SubpagesResponse, type SummaryContentsOptions, type SummaryResponse, type TextContentsOptions, type TextResponse, type UpdateWebhookParameters, type UpdateWebsetRequest, type Webhook, WebhookStatus, type Webset, type WebsetEnrichment, WebsetEnrichmentFormat, WebsetEnrichmentStatus, WebsetEnrichmentsClient, type WebsetItem, WebsetItemEvaluationSatisfied, WebsetItemSource, WebsetItemsClient, type WebsetSearch, WebsetSearchCanceledReason, WebsetSearchStatus, WebsetSearchesClient, WebsetStatus, WebsetWebhooksClient, WebsetsClient, Exa as default };