exa-js 1.7.0 → 1.7.1

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,17 @@ 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
 
 # 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

@@ -1644,23 +1644,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;
@@ -1828,6 +1830,7 @@ declare class Exa {
         text?: boolean;
         model?: "exa" | "exa-pro";
         systemPrompt?: string;
+        outputSchema?: Record<string, unknown>;
     }): AsyncGenerator<AnswerStreamChunk>;
     private processChunk;
     /**

package/dist/index.d.ts

@@ -1644,23 +1644,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;
@@ -1828,6 +1830,7 @@ declare class Exa {
         text?: boolean;
         model?: "exa" | "exa-pro";
         systemPrompt?: string;
+        outputSchema?: Record<string, unknown>;
     }): AsyncGenerator<AnswerStreamChunk>;
     private processChunk;
     /**

package/dist/index.js

@@ -915,7 +915,8 @@ var Exa2 = class {
       stream: false,
       text: options?.text ?? false,
       model: options?.model ?? "exa",
-      systemPrompt: options?.systemPrompt
+      systemPrompt: options?.systemPrompt,
+      outputSchema: options?.outputSchema
     };
     return await this.request("/answer", "POST", requestBody);
   }
@@ -944,7 +945,8 @@ var Exa2 = class {
       text: options?.text ?? false,
       stream: true,
       model: options?.model ?? "exa",
-      systemPrompt: options?.systemPrompt
+      systemPrompt: options?.systemPrompt,
+      outputSchema: options?.outputSchema
     };
     const response = await fetchImpl(this.baseURL + "/answer", {
       method: "POST",