exa-py 1.7.2__tar.gz → 1.8.3__tar.gz

{exa_py-1.7.2/exa_py.egg-info → exa_py-1.8.3}/PKG-INFO

@@ -1,19 +1,19 @@
-Metadata-Version: 2.1
+Metadata-Version: 2.3
 Name: exa-py
-Version: 1.7.2
+Version: 1.8.3
 Summary: Python SDK for Exa API.
-Home-page: https://github.com/exa-labs/exa-py
-Author: Exa
+Author: Exa AI
 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
+Requires-Python: >=3.9,<4.0
+Classifier: Programming Language :: Python :: 3
 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
@@ -78,14 +78,28 @@ exa = Exa(api_key="your-api-key")
   results = exa.find_similar_and_contents("https://example.com", text=True, highlights=True)
 
   # get text contents
-  results = exa.get_contents(["ids"])
+  results = exa.get_contents(["urls"])
 
   # get highlights
-  results = exa.get_contents(["ids"], highlights=True)
+  results = exa.get_contents(["urls"], highlights=True)
 
   # get contents with contents options
-  results = exa.get_contents(["ids"], 
+  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.2 → exa_py-1.8.3}/README.md

@@ -60,14 +60,27 @@ exa = Exa(api_key="your-api-key")
   results = exa.find_similar_and_contents("https://example.com", text=True, highlights=True)
 
   # get text contents
-  results = exa.get_contents(["ids"])
+  results = exa.get_contents(["urls"])
 
   # get highlights
-  results = exa.get_contents(["ids"], highlights=True)
+  results = exa.get_contents(["urls"], highlights=True)
 
   # get contents with contents options
-  results = exa.get_contents(["ids"], 
+  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.2 → exa_py-1.8.3}/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"
 
@@ -100,13 +101,13 @@ SEARCH_OPTIONS_TYPES = {
     "exclude_domains": [list],  # Domains to omit; exclusive with 'include_domains'.
     "start_crawl_date": [str],  # Results after this crawl date. ISO 8601 format.
     "end_crawl_date": [str],  # Results before this crawl date. ISO 8601 format.
-    "start_published_date": [str],  # Results after this publish date; excludes links with no date.
-    "end_published_date": [str],  # Results before this publish date; excludes links with no date.
+    "start_published_date": [str],  # Results after this publish date; excludes links with no date. ISO 8601 format.
+    "end_published_date": [str],  # Results before this publish date; excludes links with no date. ISO 8601 format.
     "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' or 'neural' (Default: neural).
-    "category": [str],  # e.g. 'company'
+    "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
+    "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.
 }
 
@@ -130,7 +131,7 @@ FIND_SIMILAR_OPTIONS_TYPES = {
 LIVECRAWL_OPTIONS = Literal["always", "fallback", "never", "auto"]
 
 CONTENTS_OPTIONS_TYPES = {
-    "ids": [list],
+    "urls": [list],
     "text": [dict, bool],
     "highlights": [dict, bool],
     "summary": [dict, bool],
@@ -216,7 +217,6 @@ class SummaryContentsOptions(TypedDict, total=False):
 
     query: str
 
-
 class ExtrasOptions(TypedDict, total=False):
     """A class representing additional extraction fields (e.g. links, images)"""
 
@@ -273,7 +273,8 @@ class _Result:
             f"Published Date: {self.published_date}\n"
             f"Author: {self.author}\n"
             f"Image: {self.image}\n"
-            f"Extras {self.extras}\n"
+            f"Favicon: {self.favicon}\n"
+            f"Extras: {self.extras}\n"
             f"Subpages: {self.subpages}\n"
         )
 
@@ -494,6 +495,56 @@ class ResultWithTextAndHighlightsAndSummary(_Result):
             f"Summary: {self.summary}\n"
         )
 
+@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 +599,7 @@ class Exa:
         self,
         api_key: Optional[str],
         base_url: str = "https://api.exa.ai",
-        user_agent: str = "exa-py 1.7.2",
+        user_agent: str = "exa-py 1.8.3",
     ):
         """Initialize the Exa client with the provided API key and optional base URL and user agent.
 
@@ -568,11 +619,15 @@ class Exa:
         self.headers = {"x-api-key": api_key, "User-Agent": user_agent}
 
     def request(self, endpoint: str, data):
+        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(
@@ -894,7 +949,7 @@ class Exa:
     @overload
     def get_contents(
         self,
-        ids: Union[str, List[str], List[_Result]],
+        urls: Union[str, List[str], List[_Result]],
         livecrawl_timeout: Optional[int] = None,
         livecrawl: Optional[LIVECRAWL_OPTIONS] = None,
         filter_empty_results: Optional[bool] = None,
@@ -908,7 +963,7 @@ class Exa:
     @overload
     def get_contents(
         self,
-        ids: Union[str, List[str], List[_Result]],
+        urls: Union[str, List[str], List[_Result]],
         *,
         text: Union[TextContentsOptions, Literal[True]],
         livecrawl_timeout: Optional[int] = None,
@@ -924,7 +979,7 @@ class Exa:
     @overload
     def get_contents(
         self,
-        ids: Union[str, List[str], List[_Result]],
+        urls: Union[str, List[str], List[_Result]],
         *,
         highlights: Union[HighlightsContentsOptions, Literal[True]],
         livecrawl_timeout: Optional[int] = None,
@@ -940,7 +995,7 @@ class Exa:
     @overload
     def get_contents(
         self,
-        ids: Union[str, List[str], List[_Result]],
+        urls: Union[str, List[str], List[_Result]],
         *,
         text: Union[TextContentsOptions, Literal[True]],
         highlights: Union[HighlightsContentsOptions, Literal[True]],
@@ -957,7 +1012,7 @@ class Exa:
     @overload
     def get_contents(
         self,
-        ids: Union[str, List[str], List[_Result]],
+        urls: Union[str, List[str], List[_Result]],
         *,
         summary: Union[SummaryContentsOptions, Literal[True]],
         livecrawl_timeout: Optional[int] = None,
@@ -973,7 +1028,7 @@ class Exa:
     @overload
     def get_contents(
         self,
-        ids: Union[str, List[str], List[_Result]],
+        urls: Union[str, List[str], List[_Result]],
         *,
         text: Union[TextContentsOptions, Literal[True]],
         summary: Union[SummaryContentsOptions, Literal[True]],
@@ -990,7 +1045,7 @@ class Exa:
     @overload
     def get_contents(
         self,
-        ids: Union[str, List[str], List[_Result]],
+        urls: Union[str, List[str], List[_Result]],
         *,
         highlights: Union[HighlightsContentsOptions, Literal[True]],
         summary: Union[SummaryContentsOptions, Literal[True]],
@@ -1007,7 +1062,7 @@ class Exa:
     @overload
     def get_contents(
         self,
-        ids: Union[str, List[str], List[_Result]],
+        urls: Union[str, List[str], List[_Result]],
         *,
         text: Union[TextContentsOptions, Literal[True]],
         highlights: Union[HighlightsContentsOptions, Literal[True]],
@@ -1021,16 +1076,13 @@ class Exa:
         flags: Optional[List[str]] = None,
     ) -> SearchResponse[ResultWithTextAndHighlightsAndSummary]:
         ...
-
-    def get_contents(self, ids: Union[str, List[str], List[_Result]], **kwargs):
-        options = {k: v for k, v in {"ids": ids, **kwargs}.items() if v is not None}
-        # Default to 'text' if none of text/highlights/summary are specified
-        if (
-            "text" not in options
-            and "highlights" not in options
-            and "summary" not in options
-            and "extras" not in options
-        ):
+    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:
             options["text"] = True
 
         validate_search_options(
@@ -1456,3 +1508,50 @@ 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]]]]: Either an AnswerResponse object containing the answer and sources,
+            or an iterator that yields either answer chunks or sources when streaming is enabled.
+        """
+        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.2 → exa_py-1.8.3}/pyproject.toml

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

exa_py-1.7.2/PKG-INFO

@@ -1,91 +0,0 @@
-Metadata-Version: 2.1
-Name: exa_py
-Version: 1.7.2
-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(["ids"])
-
-  # get highlights
-  results = exa.get_contents(["ids"], highlights=True)
-
-  # get contents with contents options
-  results = exa.get_contents(["ids"], 
-                             text={"include_html_tags": True, "max_characters": 1000}, 
-                             highlights={"highlights_per_url": 2, "num_sentences": 1, "query": "This is the highlight query:"})
-```
-

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

@@ -1,12 +0,0 @@
-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.7.2/exa_py.egg-info/dependency_links.txt

@@ -1 +0,0 @@
-

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

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

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

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

exa_py-1.7.2/setup.cfg

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

exa_py-1.7.2/setup.py

@@ -1,30 +0,0 @@
-from setuptools import setup, find_packages
-
-setup(
-    name="exa_py",
-    version="1.7.2",
-    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",
-    ],
-)