exa-py 1.7.3__tar.gz → 1.8.4__tar.gz

exa_py-1.8.4/PKG-INFO

@@ -0,0 +1,104 @@
+Metadata-Version: 2.1
+Name: exa_py
+Version: 1.8.4
+Summary: Python SDK for Exa API.
+Home-page: https://github.com/exa-labs/exa-py
+Author: Exa
+Author-email: hello@exa.ai
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Typing :: Typed
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Description-Content-Type: text/markdown
+
+# Exa
+
+Exa (formerly Metaphor) API in Python
+
+Note: This API is basically the same as `metaphor-python` but reflects new
+features associated with Metaphor's rename to Exa. New site is https://exa.ai
+
+## Installation
+
+```bash
+pip install exa_py
+```
+
+## Usage
+
+Import the package and initialize the Exa client with your API key:
+
+```python
+from exa_py import Exa
+
+exa = Exa(api_key="your-api-key")
+```
+
+## Common requests
+```python
+
+  # basic search
+  results = exa.search("This is a Exa query:")
+
+  # autoprompted search
+  results = exa.search("autopromptable query", use_autoprompt=True)
+
+  # keyword search (non-neural)
+  results = exa.search("Google-style query", type="keyword")
+
+  # search with date filters
+  results = exa.search("This is a Exa query:", start_published_date="2019-01-01", end_published_date="2019-01-31")
+
+  # search with domain filters
+  results = exa.search("This is a Exa query:", include_domains=["www.cnn.com", "www.nytimes.com"])
+
+  # search and get text contents
+  results = exa.search_and_contents("This is a Exa query:")
+
+  # search and get highlights
+  results = exa.search_and_contents("This is a Exa query:", highlights=True)
+
+  # search and get contents with contents options
+  results = exa.search_and_contents("This is a Exa query:", 
+                                    text={"include_html_tags": True, "max_characters": 1000}, 
+                                    highlights={"highlights_per_url": 2, "num_sentences": 1, "query": "This is the highlight query:"})
+                                    
+  # find similar documents
+  results = exa.find_similar("https://example.com")
+
+  # find similar excluding source domain
+  results = exa.find_similar("https://example.com", exclude_source_domain=True)
+
+  # find similar with contents
+  results = exa.find_similar_and_contents("https://example.com", text=True, highlights=True)
+
+  # get text contents
+  results = exa.get_contents(["urls"])
+
+  # get highlights
+  results = exa.get_contents(["urls"], highlights=True)
+
+  # get contents with contents options
+  results = exa.get_contents(["urls"], 
+                             text={"include_html_tags": True, "max_characters": 1000}, 
+                             highlights={"highlights_per_url": 2, "num_sentences": 1, "query": "This is the highlight query:"})
+
+  # basic answer
+  response = exa.answer("This is a query to answer a question")
+
+  # answer with expanded queries and full text
+  response = exa.answer("This is a query to answer a question", expanded_queries_limit=3, include_text=True)
+
+  # answer with streaming
+  response = exa.answer("This is a query to answer with streaming:", stream=True)
+
+  # Print each chunk as it arrives when answer streaming is enabled
+  for chunk in response:
+    print(chunk)
+```
+

{exa_py-1.7.3 → exa_py-1.8.4}/README.md

@@ -69,5 +69,18 @@ exa = Exa(api_key="your-api-key")
   results = exa.get_contents(["urls"], 
                              text={"include_html_tags": True, "max_characters": 1000}, 
                              highlights={"highlights_per_url": 2, "num_sentences": 1, "query": "This is the highlight query:"})
+
+  # basic answer
+  response = exa.answer("This is a query to answer a question")
+
+  # answer with expanded queries and full text
+  response = exa.answer("This is a query to answer a question", expanded_queries_limit=3, include_text=True)
+
+  # answer with streaming
+  response = exa.answer("This is a query to answer with streaming:", stream=True)
+
+  # Print each chunk as it arrives when answer streaming is enabled
+  for chunk in response:
+    print(chunk)
 ```
 

{exa_py-1.7.3 → exa_py-1.8.4}/exa_py/api.py

@@ -30,6 +30,7 @@ from exa_py.utils import (
     maybe_get_query,
 )
 import os
+from typing import Iterator
 
 is_beta = os.getenv("IS_BETA") == "True"
 
@@ -57,11 +58,13 @@ def to_camel_case(data: dict) -> dict:
     Returns:
         dict: The dictionary with keys converted to camelCase format.
     """
-    return {
-        snake_to_camel(k): to_camel_case(v) if isinstance(v, dict) else v
-        for k, v in data.items()
-        if v is not None
-    }
+    if isinstance(data, dict):
+        return {
+            snake_to_camel(k): to_camel_case(v) if isinstance(v, dict) else v
+            for k, v in data.items()
+            if v is not None
+        }
+    return data
 
 
 def camel_to_snake(camel_str: str) -> str:
@@ -87,10 +90,12 @@ def to_snake_case(data: dict) -> dict:
     Returns:
         dict: The dictionary with keys converted to snake_case format.
     """
-    return {
-        camel_to_snake(k): to_snake_case(v) if isinstance(v, dict) else v
-        for k, v in data.items()
-    }
+    if isinstance(data, dict):
+        return {
+            camel_to_snake(k): to_snake_case(v) if isinstance(v, dict) else v
+            for k, v in data.items()
+        }
+    return data
 
 
 SEARCH_OPTIONS_TYPES = {
@@ -105,9 +110,10 @@ SEARCH_OPTIONS_TYPES = {
     "include_text": [list],  # Must be present in webpage text. (One string, up to 5 words)
     "exclude_text": [list],  # Must not be present in webpage text. (One string, up to 5 words)
     "use_autoprompt": [bool],  # Convert query to Exa. (Default: false)
-    "type": [str],  # 'keyword', 'neural', or 'auto' (Default: auto).'neural' uses embeddings search, 'keyword' is SERP and 'auto' decides the best search type based on your query
+    "type": [str],  # 'keyword', 'neural', or 'auto' (Default: auto)
     "category": [str],  # A data category to focus on: 'company', 'research paper', 'news', 'pdf', 'github', 'tweet', 'personal site', 'linkedin profile', 'financial report'
-    "flags": [list],   # Experimental flags array for Exa usage.
+    "flags": [list],  # Experimental flags array for Exa usage.
+    "moderation": [bool],  # If true, moderate search results for safety.
 }
 
 FIND_SIMILAR_OPTIONS_TYPES = {
@@ -123,7 +129,7 @@ FIND_SIMILAR_OPTIONS_TYPES = {
     "exclude_text": [list],
     "exclude_source_domain": [bool],
     "category": [str],
-    "flags": [list],   # Experimental flags array for Exa usage.
+    "flags": [list],  # Experimental flags array for Exa usage.
 }
 
 # the livecrawl options
@@ -197,7 +203,7 @@ class HighlightsContentsOptions(TypedDict, total=False):
     """A class representing the options that you can specify when requesting highlights
 
     Attributes:
-        query (str): The query string for the highlights. 
+        query (str): The query string for the highlights.
         num_sentences (int): Size of highlights to return, in sentences. Default: 5
         highlights_per_url (int): Number of highlights to return per URL. Default: 1
     """
@@ -216,6 +222,7 @@ class SummaryContentsOptions(TypedDict, total=False):
 
     query: str
 
+
 class ExtrasOptions(TypedDict, total=False):
     """A class representing additional extraction fields (e.g. links, images)"""
 
@@ -495,6 +502,59 @@ class ResultWithTextAndHighlightsAndSummary(_Result):
         )
 
 
+@dataclass
+class AnswerResult:
+    """A class representing a source result for an answer.
+
+    Attributes:
+        title (str): The title of the search result.
+        url (str): The URL of the search result.
+        id (str): The temporary ID for the document.
+        published_date (str, optional): An estimate of the creation date, from parsing HTML content.
+        author (str, optional): If available, the author of the content.
+    """
+
+    url: str
+    id: str
+    title: Optional[str] = None
+    published_date: Optional[str] = None
+    author: Optional[str] = None
+
+    def __init__(self, **kwargs):
+        self.url = kwargs["url"]
+        self.id = kwargs["id"]
+        self.title = kwargs.get("title")
+        self.published_date = kwargs.get("published_date")
+        self.author = kwargs.get("author")
+
+    def __str__(self):
+        return (
+            f"Title: {self.title}\n"
+            f"URL: {self.url}\n"
+            f"ID: {self.id}\n"
+            f"Published Date: {self.published_date}\n"
+            f"Author: {self.author}\n"
+        )
+
+
+@dataclass
+class AnswerResponse:
+    """A class representing the response for an answer operation.
+
+    Attributes:
+        answer (str): The generated answer.
+        sources (List[AnswerResult]): A list of sources used to generate the answer.
+    """
+
+    answer: str
+    sources: List[AnswerResult]
+
+    def __str__(self):
+        output = f"Answer: {self.answer}\n\nSources:\n"
+        output += "\n\n".join(str(source) for source in self.sources)
+        return output
+
+
 T = TypeVar("T")
 
 
@@ -548,7 +608,7 @@ class Exa:
         self,
         api_key: Optional[str],
         base_url: str = "https://api.exa.ai",
-        user_agent: str = "exa-py 1.7.3",
+        user_agent: str = "exa-py 1.8.4",
     ):
         """Initialize the Exa client with the provided API key and optional base URL and user agent.
 
@@ -568,11 +628,28 @@ class Exa:
         self.headers = {"x-api-key": api_key, "User-Agent": user_agent}
 
     def request(self, endpoint: str, data):
+        """Send a POST request to the Exa API, optionally streaming if data['stream'] is True.
+
+        Args:
+            endpoint (str): The API endpoint (path).
+            data (dict): The JSON payload to send.
+
+        Returns:
+            Union[dict, Iterator[str]]: If streaming, returns an iterator of strings (line-by-line).
+            Otherwise, returns the JSON-decoded response as a dict.
+
+        Raises:
+            ValueError: If the request fails (non-200 status code).
+        """
+        if data.get("stream"):
+            res = requests.post(self.base_url + endpoint, json=data, headers=self.headers, stream=True)
+            if res.status_code != 200:
+                raise ValueError(f"Request failed with status code {res.status_code}: {res.text}")
+            return (line.decode("utf-8") for line in res.iter_lines() if line)
+
         res = requests.post(self.base_url + endpoint, json=data, headers=self.headers)
         if res.status_code != 200:
-            raise ValueError(
-                f"Request failed with status code {res.status_code}: {res.text}"
-            )
+            raise ValueError(f"Request failed with status code {res.status_code}: {res.text}")
         return res.json()
 
     def search(
@@ -592,6 +669,7 @@ class Exa:
         type: Optional[str] = None,
         category: Optional[str] = None,
         flags: Optional[List[str]] = None,
+        moderation: Optional[bool] = None,
     ) -> SearchResponse[_Result]:
         """Perform a search with a prompt-engineered query to retrieve relevant results.
 
@@ -610,6 +688,7 @@ class Exa:
             type (str, optional): 'keyword' or 'neural' (default 'neural').
             category (str, optional): e.g. 'company'
             flags (List[str], optional): Experimental flags for Exa usage.
+            moderation (bool, optional): If True, the search results will be moderated for safety.
 
         Returns:
             SearchResponse: The response containing search results, etc.
@@ -642,12 +721,13 @@ class Exa:
         use_autoprompt: Optional[bool] = None,
         type: Optional[str] = None,
         category: Optional[str] = None,
+        flags: Optional[List[str]] = None,
+        moderation: Optional[bool] = None,
         livecrawl_timeout: Optional[int] = None,
         livecrawl: Optional[LIVECRAWL_OPTIONS] = None,
         filter_empty_results: Optional[bool] = None,
         subpages: Optional[int] = None,
         extras: Optional[ExtrasOptions] = None,
-        flags: Optional[List[str]] = None,
     ) -> SearchResponse[ResultWithText]:
         ...
 
@@ -669,12 +749,13 @@ class Exa:
         use_autoprompt: Optional[bool] = None,
         type: Optional[str] = None,
         category: Optional[str] = None,
+        flags: Optional[List[str]] = None,
+        moderation: Optional[bool] = None,
         subpages: Optional[int] = None,
         livecrawl_timeout: Optional[int] = None,
         livecrawl: Optional[LIVECRAWL_OPTIONS] = None,
         filter_empty_results: Optional[bool] = None,
         extras: Optional[ExtrasOptions] = None,
-        flags: Optional[List[str]] = None,
     ) -> SearchResponse[ResultWithText]:
         ...
 
@@ -698,11 +779,12 @@ class Exa:
         category: Optional[str] = None,
         subpages: Optional[int] = None,
         subpage_target: Optional[Union[str, List[str]]] = None,
+        flags: Optional[List[str]] = None,
+        moderation: Optional[bool] = None,
         livecrawl_timeout: Optional[int] = None,
         livecrawl: Optional[LIVECRAWL_OPTIONS] = None,
         filter_empty_results: Optional[bool] = None,
         extras: Optional[ExtrasOptions] = None,
-        flags: Optional[List[str]] = None,
     ) -> SearchResponse[ResultWithHighlights]:
         ...
 
@@ -725,13 +807,14 @@ class Exa:
         use_autoprompt: Optional[bool] = None,
         type: Optional[str] = None,
         category: Optional[str] = None,
-        livecrawl_timeout: Optional[int] = None,
-        livecrawl: Optional[LIVECRAWL_OPTIONS] = None,
         subpages: Optional[int] = None,
         subpage_target: Optional[Union[str, List[str]]] = None,
+        flags: Optional[List[str]] = None,
+        moderation: Optional[bool] = None,
+        livecrawl_timeout: Optional[int] = None,
+        livecrawl: Optional[LIVECRAWL_OPTIONS] = None,
         filter_empty_results: Optional[bool] = None,
         extras: Optional[ExtrasOptions] = None,
-        flags: Optional[List[str]] = None,
     ) -> SearchResponse[ResultWithTextAndHighlights]:
         ...
 
@@ -755,11 +838,12 @@ class Exa:
         category: Optional[str] = None,
         subpages: Optional[int] = None,
         subpage_target: Optional[Union[str, List[str]]] = None,
+        flags: Optional[List[str]] = None,
+        moderation: Optional[bool] = None,
         livecrawl_timeout: Optional[int] = None,
         livecrawl: Optional[LIVECRAWL_OPTIONS] = None,
         filter_empty_results: Optional[bool] = None,
         extras: Optional[ExtrasOptions] = None,
-        flags: Optional[List[str]] = None,
     ) -> SearchResponse[ResultWithSummary]:
         ...
 
@@ -784,11 +868,12 @@ class Exa:
         category: Optional[str] = None,
         subpages: Optional[int] = None,
         subpage_target: Optional[Union[str, List[str]]] = None,
+        flags: Optional[List[str]] = None,
+        moderation: Optional[bool] = None,
         livecrawl_timeout: Optional[int] = None,
         livecrawl: Optional[LIVECRAWL_OPTIONS] = None,
         filter_empty_results: Optional[bool] = None,
         extras: Optional[ExtrasOptions] = None,
-        flags: Optional[List[str]] = None,
     ) -> SearchResponse[ResultWithTextAndSummary]:
         ...
 
@@ -813,11 +898,12 @@ class Exa:
         category: Optional[str] = None,
         subpages: Optional[int] = None,
         subpage_target: Optional[Union[str, List[str]]] = None,
+        flags: Optional[List[str]] = None,
+        moderation: Optional[bool] = None,
         livecrawl_timeout: Optional[int] = None,
         livecrawl: Optional[LIVECRAWL_OPTIONS] = None,
         filter_empty_results: Optional[bool] = None,
         extras: Optional[ExtrasOptions] = None,
-        flags: Optional[List[str]] = None,
     ) -> SearchResponse[ResultWithHighlightsAndSummary]:
         ...
 
@@ -841,13 +927,14 @@ class Exa:
         use_autoprompt: Optional[bool] = None,
         type: Optional[str] = None,
         category: Optional[str] = None,
+        flags: Optional[List[str]] = None,
+        moderation: Optional[bool] = None,
         livecrawl_timeout: Optional[int] = None,
         livecrawl: Optional[LIVECRAWL_OPTIONS] = None,
         subpages: Optional[int] = None,
         subpage_target: Optional[Union[str, List[str]]] = None,
         filter_empty_results: Optional[bool] = None,
         extras: Optional[ExtrasOptions] = None,
-        flags: Optional[List[str]] = None,
     ) -> SearchResponse[ResultWithTextAndHighlightsAndSummary]:
         ...
 
@@ -864,7 +951,11 @@ class Exa:
 
         validate_search_options(
             options,
-            {**SEARCH_OPTIONS_TYPES, **CONTENTS_OPTIONS_TYPES, **CONTENTS_ENDPOINT_OPTIONS_TYPES},
+            {
+                **SEARCH_OPTIONS_TYPES,
+                **CONTENTS_OPTIONS_TYPES,
+                **CONTENTS_ENDPOINT_OPTIONS_TYPES,
+            },
         )
 
         # Nest the appropriate fields under "contents"
@@ -1021,13 +1112,19 @@ class Exa:
         flags: Optional[List[str]] = None,
     ) -> SearchResponse[ResultWithTextAndHighlightsAndSummary]:
         ...
+
     def get_contents(self, urls: Union[str, List[str], List[_Result]], **kwargs):
         options = {
             k: v
             for k, v in {"urls": urls, **kwargs}.items()
             if k != "self" and v is not None
         }
-        if "text" not in options and "highlights" not in options and "summary" not in options and "extras" not in options:
+        if (
+            "text" not in options
+            and "highlights" not in options
+            and "summary" not in options
+            and "extras" not in options
+        ):
             options["text"] = True
 
         validate_search_options(
@@ -1038,9 +1135,9 @@ class Exa:
         data = self.request("/contents", options)
         return SearchResponse(
             [Result(**to_snake_case(result)) for result in data["results"]],
-            data["autopromptString"] if "autopromptString" in data else None,
-            data["resolvedSearchType"] if "resolvedSearchType" in data else None,
-            data["autoDate"] if "autoDate" in data else None,
+            data.get("autopromptString"),
+            data.get("resolvedSearchType"),
+            data.get("autoDate"),
         )
 
     def find_similar(
@@ -1060,15 +1157,35 @@ class Exa:
         category: Optional[str] = None,
         flags: Optional[List[str]] = None,
     ) -> SearchResponse[_Result]:
+        """Finds similar pages to a given URL, potentially with domain filters and date filters.
+
+        Args:
+            url (str): The URL to find similar pages for.
+            num_results (int, optional): Number of results to return. Default is None (server default).
+            include_domains (List[str], optional): Domains to include in the search.
+            exclude_domains (List[str], optional): Domains to exclude from the search.
+            start_crawl_date (str, optional): Only links crawled after this date.
+            end_crawl_date (str, optional): Only links crawled before this date.
+            start_published_date (str, optional): Only links published after this date.
+            end_published_date (str, optional): Only links published before this date.
+            include_text (List[str], optional): Strings that must appear in the page text.
+            exclude_text (List[str], optional): Strings that must not appear in the page text.
+            exclude_source_domain (bool, optional): Whether to exclude the source domain.
+            category (str, optional): A data category to focus on.
+            flags (List[str], optional): Experimental flags.
+
+        Returns:
+            SearchResponse[_Result]
+        """
         options = {k: v for k, v in locals().items() if k != "self" and v is not None}
         validate_search_options(options, FIND_SIMILAR_OPTIONS_TYPES)
         options = to_camel_case(options)
         data = self.request("/findSimilar", options)
         return SearchResponse(
             [Result(**to_snake_case(result)) for result in data["results"]],
-            data["autopromptString"] if "autopromptString" in data else None,
-            data["resolvedSearchType"] if "resolvedSearchType" in data else None,
-            data["autoDate"] if "autoDate" in data else None,
+            data.get("autopromptString"),
+            data.get("resolvedSearchType"),
+            data.get("autoDate"),
         )
 
     @overload
@@ -1087,13 +1204,13 @@ class Exa:
         exclude_text: Optional[List[str]] = None,
         exclude_source_domain: Optional[bool] = None,
         category: Optional[str] = None,
+        flags: Optional[List[str]] = None,
         livecrawl_timeout: Optional[int] = None,
         livecrawl: Optional[LIVECRAWL_OPTIONS] = None,
+        filter_empty_results: Optional[bool] = None,
         subpages: Optional[int] = None,
         subpage_target: Optional[Union[str, List[str]]] = None,
-        filter_empty_results: Optional[bool] = None,
         extras: Optional[ExtrasOptions] = None,
-        flags: Optional[List[str]] = None,
     ) -> SearchResponse[ResultWithText]:
         ...
 
@@ -1114,13 +1231,13 @@ class Exa:
         exclude_text: Optional[List[str]] = None,
         exclude_source_domain: Optional[bool] = None,
         category: Optional[str] = None,
+        flags: Optional[List[str]] = None,
         livecrawl_timeout: Optional[int] = None,
         livecrawl: Optional[LIVECRAWL_OPTIONS] = None,
+        filter_empty_results: Optional[bool] = None,
         subpages: Optional[int] = None,
         subpage_target: Optional[Union[str, List[str]]] = None,
-        filter_empty_results: Optional[bool] = None,
         extras: Optional[ExtrasOptions] = None,
-        flags: Optional[List[str]] = None,
     ) -> SearchResponse[ResultWithText]:
         ...
 
@@ -1141,13 +1258,13 @@ class Exa:
         exclude_text: Optional[List[str]] = None,
         exclude_source_domain: Optional[bool] = None,
         category: Optional[str] = None,
+        flags: Optional[List[str]] = None,
         subpages: Optional[int] = None,
         subpage_target: Optional[Union[str, List[str]]] = None,
         livecrawl_timeout: Optional[int] = None,
         livecrawl: Optional[LIVECRAWL_OPTIONS] = None,
         filter_empty_results: Optional[bool] = None,
         extras: Optional[ExtrasOptions] = None,
-        flags: Optional[List[str]] = None,
     ) -> SearchResponse[ResultWithHighlights]:
         ...
 
@@ -1169,13 +1286,13 @@ class Exa:
         exclude_text: Optional[List[str]] = None,
         exclude_source_domain: Optional[bool] = None,
         category: Optional[str] = None,
+        flags: Optional[List[str]] = None,
         livecrawl_timeout: Optional[int] = None,
         livecrawl: Optional[LIVECRAWL_OPTIONS] = None,
+        filter_empty_results: Optional[bool] = None,
         subpages: Optional[int] = None,
         subpage_target: Optional[Union[str, List[str]]] = None,
-        filter_empty_results: Optional[bool] = None,
         extras: Optional[ExtrasOptions] = None,
-        flags: Optional[List[str]] = None,
     ) -> SearchResponse[ResultWithTextAndHighlights]:
         ...
 
@@ -1196,13 +1313,13 @@ class Exa:
         exclude_text: Optional[List[str]] = None,
         exclude_source_domain: Optional[bool] = None,
         category: Optional[str] = None,
+        flags: Optional[List[str]] = None,
         livecrawl_timeout: Optional[int] = None,
         livecrawl: Optional[LIVECRAWL_OPTIONS] = None,
+        filter_empty_results: Optional[bool] = None,
         subpages: Optional[int] = None,
         subpage_target: Optional[Union[str, List[str]]] = None,
-        filter_empty_results: Optional[bool] = None,
         extras: Optional[ExtrasOptions] = None,
-        flags: Optional[List[str]] = None,
     ) -> SearchResponse[ResultWithSummary]:
         ...
 
@@ -1224,13 +1341,13 @@ class Exa:
         exclude_text: Optional[List[str]] = None,
         exclude_source_domain: Optional[bool] = None,
         category: Optional[str] = None,
+        flags: Optional[List[str]] = None,
         livecrawl_timeout: Optional[int] = None,
         livecrawl: Optional[LIVECRAWL_OPTIONS] = None,
+        filter_empty_results: Optional[bool] = None,
         subpages: Optional[int] = None,
         subpage_target: Optional[Union[str, List[str]]] = None,
-        filter_empty_results: Optional[bool] = None,
         extras: Optional[ExtrasOptions] = None,
-        flags: Optional[List[str]] = None,
     ) -> SearchResponse[ResultWithTextAndSummary]:
         ...
 
@@ -1252,13 +1369,13 @@ class Exa:
         exclude_text: Optional[List[str]] = None,
         exclude_source_domain: Optional[bool] = None,
         category: Optional[str] = None,
-        livecrawl_timeout: Optional[int] = None,
+        flags: Optional[List[str]] = None,
         subpages: Optional[int] = None,
         subpage_target: Optional[Union[str, List[str]]] = None,
+        livecrawl_timeout: Optional[int] = None,
         livecrawl: Optional[LIVECRAWL_OPTIONS] = None,
         filter_empty_results: Optional[bool] = None,
         extras: Optional[ExtrasOptions] = None,
-        flags: Optional[List[str]] = None,
     ) -> SearchResponse[ResultWithHighlightsAndSummary]:
         ...
 
@@ -1281,20 +1398,24 @@ class Exa:
         exclude_text: Optional[List[str]] = None,
         exclude_source_domain: Optional[bool] = None,
         category: Optional[str] = None,
+        flags: Optional[List[str]] = None,
         livecrawl_timeout: Optional[int] = None,
+        livecrawl: Optional[LIVECRAWL_OPTIONS] = None,
+        filter_empty_results: Optional[bool] = None,
         subpages: Optional[int] = None,
         subpage_target: Optional[Union[str, List[str]]] = None,
-        filter_empty_results: Optional[bool] = None,
-        livecrawl: Optional[LIVECRAWL_OPTIONS] = None,
         extras: Optional[ExtrasOptions] = None,
-        flags: Optional[List[str]] = None,
     ) -> SearchResponse[ResultWithTextAndHighlightsAndSummary]:
         ...
 
     def find_similar_and_contents(self, url: str, **kwargs):
         options = {k: v for k, v in {"url": url, **kwargs}.items() if v is not None}
         # Default to text if none specified
-        if "text" not in options and "highlights" not in options and "summary" not in options:
+        if (
+            "text" not in options
+            and "highlights" not in options
+            and "summary" not in options
+        ):
             options["text"] = True
 
         validate_search_options(
@@ -1324,9 +1445,9 @@ class Exa:
         data = self.request("/findSimilar", options)
         return SearchResponse(
             [Result(**to_snake_case(result)) for result in data["results"]],
-            data["autopromptString"] if "autopromptString" in data else None,
-            data["resolvedSearchType"] if "resolvedSearchType" in data else None,
-            data["autoDate"] if "autoDate" in data else None,
+            data.get("autopromptString"),
+            data.get("resolvedSearchType"),
+            data.get("autoDate"),
         )
 
     def wrap(self, client: OpenAI):
@@ -1400,7 +1521,7 @@ class Exa:
                 exa_kwargs=exa_kwargs,
             )
 
-        print("Wrapping OpenAI client with Exa functionality.", type(create_with_rag))
+        print("Wrapping OpenAI client with Exa functionality.")
         client.chat.completions.create = create_with_rag  # type: ignore
 
         return client
@@ -1444,6 +1565,7 @@ class Exa:
                 completion=completion, exa_result=None
             )
 
+        # We do a search_and_contents automatically
         exa_result = self.search_and_contents(query, **exa_kwargs)
         exa_str = format_exa_result(exa_result, max_len=max_len)
         new_messages = add_message_to_messages(completion, messages, exa_str)
@@ -1453,3 +1575,51 @@ class Exa:
             completion=completion, exa_result=exa_result
         )
         return exa_completion
+
+    @overload
+    def answer(
+        self,
+        query: str,
+        *,
+        expanded_queries_limit: Optional[int] = 1,
+        stream: Optional[bool] = False,
+        include_text: Optional[bool] = False,
+    ) -> Union[AnswerResponse, Iterator[Union[str, List[AnswerResult]]]]:
+        ...
+
+    def answer(
+        self,
+        query: str,
+        *,
+        expanded_queries_limit: Optional[int] = 1,
+        stream: Optional[bool] = False,
+        include_text: Optional[bool] = False,
+    ) -> Union[AnswerResponse, Iterator[Union[str, List[AnswerResult]]]]:
+        """Generate an answer to a query using Exa's search and LLM capabilities.
+
+        Args:
+            query (str): The query to answer.
+            expanded_queries_limit (int, optional): Maximum number of query variations (0-4). Defaults to 1.
+            stream (bool, optional): Whether to stream the response. Defaults to False.
+            include_text (bool, optional): Whether to include full text in the results. Defaults to False.
+
+        Returns:
+            Union[AnswerResponse, Iterator[Union[str, List[AnswerResult]]]]:
+                - If stream=False, returns an AnswerResponse object containing the answer and sources.
+                - If stream=True, returns an iterator that yields either answer chunks or sources.
+        """
+        options = {
+            k: v
+            for k, v in locals().items()
+            if k != "self" and v is not None
+        }
+        options = to_camel_case(options)
+        response = self.request("/answer", options)
+
+        if stream:
+            return response
+
+        return AnswerResponse(
+            response["answer"],
+            [AnswerResult(**to_snake_case(result)) for result in response["sources"]]
+        )

{exa_py-1.7.3 → exa_py-1.8.4/exa_py.egg-info}/PKG-INFO

@@ -1,19 +1,19 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.1
 Name: exa-py
-Version: 1.7.3
+Version: 1.8.4
 Summary: Python SDK for Exa API.
-Author: Exa AI
+Home-page: https://github.com/exa-labs/exa-py
+Author: Exa
 Author-email: hello@exa.ai
-Requires-Python: >=3.9,<4.0
-Classifier: Programming Language :: Python :: 3
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Typing :: Typed
+Classifier: Programming Language :: Python :: 3.8
 Classifier: Programming Language :: Python :: 3.9
 Classifier: Programming Language :: Python :: 3.10
 Classifier: Programming Language :: Python :: 3.11
 Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Requires-Dist: openai (>=1.48,<2.0)
-Requires-Dist: requests (>=2.32.3,<3.0.0)
-Requires-Dist: typing-extensions (>=4.12.2,<5.0.0)
 Description-Content-Type: text/markdown
 
 # Exa
@@ -87,6 +87,18 @@ exa = Exa(api_key="your-api-key")
   results = exa.get_contents(["urls"], 
                              text={"include_html_tags": True, "max_characters": 1000}, 
                              highlights={"highlights_per_url": 2, "num_sentences": 1, "query": "This is the highlight query:"})
-```
 
+  # basic answer
+  response = exa.answer("This is a query to answer a question")
+
+  # answer with expanded queries and full text
+  response = exa.answer("This is a query to answer a question", expanded_queries_limit=3, include_text=True)
+
+  # answer with streaming
+  response = exa.answer("This is a query to answer with streaming:", stream=True)
+
+  # Print each chunk as it arrives when answer streaming is enabled
+  for chunk in response:
+    print(chunk)
+```
 

exa_py-1.8.4/exa_py.egg-info/SOURCES.txt

@@ -0,0 +1,12 @@
+README.md
+pyproject.toml
+setup.py
+exa_py/__init__.py
+exa_py/api.py
+exa_py/py.typed
+exa_py/utils.py
+exa_py.egg-info/PKG-INFO
+exa_py.egg-info/SOURCES.txt
+exa_py.egg-info/dependency_links.txt
+exa_py.egg-info/requires.txt
+exa_py.egg-info/top_level.txt

exa_py-1.8.4/exa_py.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

exa_py-1.8.4/exa_py.egg-info/requires.txt

@@ -0,0 +1,3 @@
+requests
+typing-extensions
+openai>=1.10.0

exa_py-1.8.4/exa_py.egg-info/top_level.txt

@@ -0,0 +1 @@
+exa_py

{exa_py-1.7.3 → exa_py-1.8.4}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "exa-py"
-version = "1.7.3"
+version = "1.8.3"
 description = "Python SDK for Exa API."
 authors = ["Exa AI <hello@exa.ai>"]
 readme = "README.md"

exa_py-1.8.4/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

exa_py-1.8.4/setup.py

@@ -0,0 +1,30 @@
+from setuptools import setup, find_packages
+
+setup(
+    name="exa_py",
+    version="1.8.4",
+    description="Python SDK for Exa API.",
+    long_description_content_type="text/markdown",
+    long_description=open("README.md").read(),
+    author="Exa",
+    author_email="hello@exa.ai",
+    package_data={"exa_py": ["py.typed"]},
+    url="https://github.com/exa-labs/exa-py",
+    packages=find_packages(),
+    install_requires=[
+        "requests",
+        "typing-extensions",
+        "openai>=1.10.0"
+    ],
+    classifiers=[
+        "Development Status :: 5 - Production/Stable",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: MIT License",
+        "Typing :: Typed",
+        "Programming Language :: Python :: 3.8",
+        "Programming Language :: Python :: 3.9",
+        "Programming Language :: Python :: 3.10",
+        "Programming Language :: Python :: 3.11",
+        "Programming Language :: Python :: 3.12",
+    ],
+)