exa-py 1.0.14__tar.gz → 1.0.16__tar.gz

{exa_py-1.0.14 → exa_py-1.0.16}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: exa_py
-Version: 1.0.14
+Version: 1.0.16
 Summary: Python SDK for Exa API.
 Home-page: https://github.com/exa-labs/exa-py
 Author: Exa

{exa_py-1.0.14 → exa_py-1.0.16}/exa_py/api.py

@@ -18,7 +18,6 @@ from typing import (
 )
 from typing_extensions import TypedDict
 
-import httpx
 from openai import OpenAI
 from openai.types.chat.chat_completion_message_param import ChatCompletionMessageParam
 from openai.types.chat_model import ChatModel
@@ -30,8 +29,6 @@ from exa_py.utils import (
 )
 
 
-
-
 def snake_to_camel(snake_str: str) -> str:
     """Convert snake_case string to camelCase.
 
@@ -97,6 +94,10 @@ SEARCH_OPTIONS_TYPES = {
     "end_published_date": [
         str
     ],  # Results before this publish date; excludes links with no date. ISO 8601 format.
+    "include_text": [
+        list
+    ],  # list of strings that must be present in webpage text of results. Currently, only one string is supported, up to 5 words.
+    "exclude_text": [list],  # list of strings that must not be present in webpage text of result. Currently, only one string is supported, up to 5 words.
     "use_autoprompt": [bool],  # Convert query to Exa (Higher latency, Default: false).
     "type": [
         str
@@ -115,6 +116,8 @@ FIND_SIMILAR_OPTIONS_TYPES = {
     "end_crawl_date": [str],
     "start_published_date": [str],
     "end_published_date": [str],
+    "include_text": [list],
+    "exclude_text": [list],
     "exclude_source_domain": [bool],
     "category": [str],
 }
@@ -123,6 +126,7 @@ CONTENTS_OPTIONS_TYPES = {
     "ids": [list],
     "text": [dict, bool],
     "highlights": [dict, bool],
+    "summary": [dict, bool],
 }
 
 
@@ -172,6 +176,14 @@ class HighlightsContentsOptions(TypedDict, total=False):
     num_sentences: int
     highlights_per_url: int
 
+class SummaryContentsOptions(TypedDict, total=False):
+    """A class representing the options that you can specify when requesting summary
+
+    Attributes:
+        query (str): The query string for the summary. Summary will bias towards answering the query.
+    """
+
+    query: str
 
 @dataclass
 class _Result:
@@ -213,11 +225,13 @@ class Result(_Result):
         text (str, optional): The text of the search result page.
         highlights (List[str], optional): The highlights of the search result.
         highlight_scores (List[float], optional): The scores of the highlights of the search result.
+        summary (str, optional): The summary of the search result.
     """
 
     text: Optional[str] = None
     highlights: Optional[List[str]] = None
     highlight_scores: Optional[List[float]] = None
+    summary: Optional[str] = None
 
     def __str__(self):
         base_str = super().__str__()
@@ -225,6 +239,7 @@ class Result(_Result):
             f"Text: {self.text}\n"
             f"Highlights: {self.highlights}\n"
             f"Highlight Scores: {self.highlight_scores}\n"
+            f"Summary: {self.summary}\n"
         )
 
 
@@ -288,6 +303,86 @@ class ResultWithTextAndHighlights(_Result):
             f"Highlight Scores: {self.highlight_scores}\n"
         )
 
+@dataclass
+class ResultWithSummary(_Result):
+    """
+    A class representing a search result with summary present.
+
+    Attributes:
+        summary (str): The summary of the search result.
+    """
+
+    summary: str = dataclasses.field(default_factory=str)
+
+    def __str__(self):
+        base_str = super().__str__()
+        return base_str + f"Summary: {self.summary}\n"
+
+@dataclass
+class ResultWithTextAndSummary(_Result):
+    """
+    A class representing a search result with text and summary present.
+
+    Attributes:
+        text (str): The text of the search result page.
+        summary (str): The summary of the search result.
+    """
+
+    text: str = dataclasses.field(default_factory=str)
+    summary: str = dataclasses.field(default_factory=str)
+
+    def __str__(self):
+        base_str = super().__str__()
+        return base_str + f"Text: {self.text}\n" + f"Summary: {self.summary}\n"
+
+@dataclass
+class ResultWithHighlightsAndSummary(_Result):
+    """
+    A class representing a search result with highlights and summary present.
+
+    Attributes:
+        highlights (List[str]): The highlights of the search result.
+        highlight_scores (List[float]): The scores of the highlights of the search result.
+        summary (str): The summary of the search result.
+    """
+
+    highlights: List[str] = dataclasses.field(default_factory=list)
+    highlight_scores: List[float] = dataclasses.field(default_factory=list)
+    summary: str = dataclasses.field(default_factory=str)
+
+    def __str__(self):
+        base_str = super().__str__()
+        return base_str + (
+            f"Highlights: {self.highlights}\n"
+            f"Highlight Scores: {self.highlight_scores}\n"
+            f"Summary: {self.summary}\n"
+        )
+
+@dataclass
+class ResultWithTextAndHighlightsAndSummary(_Result):
+    """
+    A class representing a search result with text, highlights, and summary present.
+
+    Attributes:
+        text (str): The text of the search result page.
+        highlights (List[str]): The highlights of the search result.
+        highlight_scores (List[float]): The scores of the highlights of the search result.
+        summary (str): The summary of the search result.
+    """
+
+    text: str = dataclasses.field(default_factory=str)
+    highlights: List[str] = dataclasses.field(default_factory=list)
+    highlight_scores: List[float] = dataclasses.field(default_factory=list)
+    summary: str = dataclasses.field(default_factory=str)
+
+    def __str__(self):
+        base_str = super().__str__()
+        return base_str + (
+            f"Text: {self.text}\n"
+            f"Highlights: {self.highlights}\n"
+            f"Highlight Scores: {self.highlight_scores}\n"
+            f"Summary: {self.summary}\n"
+        )
 
 T = TypeVar("T")
 
@@ -335,7 +430,7 @@ class Exa:
         self,
         api_key: Optional[str],
         base_url: str = "https://api.exa.ai",
-        user_agent: str = "exa-py 1.0.14",
+        user_agent: str = "exa-py 1.0.16",
     ):
         """Initialize the Exa client with the provided API key and optional base URL and user agent.
 
@@ -373,6 +468,8 @@ class Exa:
         end_crawl_date: Optional[str] = None,
         start_published_date: Optional[str] = None,
         end_published_date: Optional[str] = None,
+        include_text: Optional[List[str]] = None,
+        exclude_text: Optional[List[str]] = None,
         use_autoprompt: Optional[bool] = None,
         type: Optional[str] = None,
         category: Optional[str] = None,
@@ -388,6 +485,8 @@ class Exa:
             end_crawl_date (str, optional): Results will only include links crawled before this date.
             start_published_date (str, optional): Results will only include links with a published date after this date.
             end_published_date (str, optional): Results will only include links with a published date before this date.
+            include_text (List[str], optional): List of strings that must be present in the webpage text of results. Currently, only one string is supported, up to 5 words.
+            exclude_text (List[str], optional): List of strings that must not be present in the webpage text of results. Currently, only one string is supported, up to 5 words.
             use_autoprompt (bool, optional): If true, convert query to a Exa query. Defaults to False.
             type (str, optional): The type of search, 'keyword' or 'neural'. Defaults to "neural".
             category (str, optional): A data category to focus on, with higher comprehensivity and data cleanliness. Currently, the only category is company.
@@ -415,6 +514,8 @@ class Exa:
         end_crawl_date: Optional[str] = None,
         start_published_date: Optional[str] = None,
         end_published_date: Optional[str] = None,
+        include_text: Optional[List[str]] = None,
+        exclude_text: Optional[List[str]] = None,
         use_autoprompt: Optional[bool] = None,
         type: Optional[str] = None,
         category: Optional[str] = None,
@@ -434,6 +535,8 @@ class Exa:
         end_crawl_date: Optional[str] = None,
         start_published_date: Optional[str] = None,
         end_published_date: Optional[str] = None,
+        include_text: Optional[List[str]] = None,
+        exclude_text: Optional[List[str]] = None,
         use_autoprompt: Optional[bool] = None,
         type: Optional[str] = None,
         category: Optional[str] = None,
@@ -453,6 +556,8 @@ class Exa:
         end_crawl_date: Optional[str] = None,
         start_published_date: Optional[str] = None,
         end_published_date: Optional[str] = None,
+        include_text: Optional[List[str]] = None,
+        exclude_text: Optional[List[str]] = None,
         use_autoprompt: Optional[bool] = None,
         type: Optional[str] = None,
         category: Optional[str] = None,
@@ -473,24 +578,114 @@ class Exa:
         end_crawl_date: Optional[str] = None,
         start_published_date: Optional[str] = None,
         end_published_date: Optional[str] = None,
+        include_text: Optional[List[str]] = None,
+        exclude_text: Optional[List[str]] = None,
         use_autoprompt: Optional[bool] = None,
         type: Optional[str] = None,
         category: Optional[str] = None,
     ) -> SearchResponse[ResultWithTextAndHighlights]:
         ...
 
+    @overload
+    def search_and_contents(
+        self,
+        query: str,
+        *,
+        summary: Union[SummaryContentsOptions, Literal[True]],
+        num_results: Optional[int] = None,
+        include_domains: Optional[List[str]] = None,
+        exclude_domains: Optional[List[str]] = None,
+        start_crawl_date: Optional[str] = None,
+        end_crawl_date: Optional[str] = None,
+        start_published_date: Optional[str] = None,
+        end_published_date: Optional[str] = None,
+        include_text: Optional[List[str]] = None,
+        exclude_text: Optional[List[str]] = None,
+        use_autoprompt: Optional[bool] = None,
+        type: Optional[str] = None,
+        category: Optional[str] = None,
+    ) -> SearchResponse[ResultWithSummary]:
+        ...
+
+    @overload
+    def search_and_contents(
+        self,
+        query: str,
+        *,
+        text: Union[TextContentsOptions, Literal[True]],
+        summary: Union[SummaryContentsOptions, Literal[True]],
+        num_results: Optional[int] = None,
+        include_domains: Optional[List[str]] = None,
+        exclude_domains: Optional[List[str]] = None,
+        start_crawl_date: Optional[str] = None,
+        end_crawl_date: Optional[str] = None,
+        start_published_date: Optional[str] = None,
+        end_published_date: Optional[str] = None,
+        include_text: Optional[List[str]] = None,
+        exclude_text: Optional[List[str]] = None,
+        use_autoprompt: Optional[bool] = None,
+        type: Optional[str] = None,
+        category: Optional[str] = None,
+    ) -> SearchResponse[ResultWithTextAndSummary]:
+        ...
+
+    @overload
+    def search_and_contents(
+        self,
+        query: str,
+        *,
+        highlights: Union[HighlightsContentsOptions, Literal[True]],
+        summary: Union[SummaryContentsOptions, Literal[True]],
+        num_results: Optional[int] = None,
+        include_domains: Optional[List[str]] = None,
+        exclude_domains: Optional[List[str]] = None,
+        start_crawl_date: Optional[str] = None,
+        end_crawl_date: Optional[str] = None,
+        start_published_date: Optional[str] = None,
+        end_published_date: Optional[str] = None,
+        include_text: Optional[List[str]] = None,
+        exclude_text: Optional[List[str]] = None,
+        use_autoprompt: Optional[bool] = None,
+        type: Optional[str] = None,
+        category: Optional[str] = None,
+    ) -> SearchResponse[ResultWithHighlightsAndSummary]:
+        ...
+
+    @overload
+    def search_and_contents(
+        self,
+        query: str,
+        *,
+        text: Union[TextContentsOptions, Literal[True]],
+        highlights: Union[HighlightsContentsOptions, Literal[True]],
+        summary: Union[SummaryContentsOptions, Literal[True]],
+        num_results: Optional[int] = None,
+        include_domains: Optional[List[str]] = None,
+        exclude_domains: Optional[List[str]] = None,
+        start_crawl_date: Optional[str] = None,
+        end_crawl_date: Optional[str] = None,
+        start_published_date: Optional[str] = None,
+        end_published_date: Optional[str] = None,
+        include_text: Optional[List[str]] = None,
+        exclude_text: Optional[List[str]] = None,
+        use_autoprompt: Optional[bool] = None,
+        type: Optional[str] = None,
+        category: Optional[str] = None,
+    ) -> SearchResponse[ResultWithTextAndHighlightsAndSummary]:
+        ...
+
     def search_and_contents(self, query: str, **kwargs):
         options = {
             k: v
             for k, v in {"query": query, **kwargs}.items()
             if k != "self" and v is not None
         }
-        if "text" not in options and "highlights" not in options:
+        if "text" not in options and "highlights" not in options and "summary" not in options:
             options["text"] = True
         validate_search_options(
             options, {**SEARCH_OPTIONS_TYPES, **CONTENTS_OPTIONS_TYPES}
         )
-        options = nest_fields(options, ["text", "highlights"], "contents")
+        options = nest_fields(options, ["text", "highlights", "summary"], "contents")
         options = to_camel_case(options)
         data = self.request("/search", options)
         return SearchResponse(
@@ -533,13 +728,53 @@ class Exa:
     ) -> SearchResponse[ResultWithTextAndHighlights]:
         ...
 
+    @overload
+    def get_contents(
+        self,
+        ids: Union[str, List[str], List[_Result]],
+        *,
+        summary: Union[SummaryContentsOptions, Literal[True]],
+    ) -> SearchResponse[ResultWithSummary]:
+        ...
+
+    @overload
+    def get_contents(
+        self,
+        ids: Union[str, List[str], List[_Result]],
+        *,
+        text: Union[TextContentsOptions, Literal[True]],
+        summary: Union[SummaryContentsOptions, Literal[True]],
+    ) -> SearchResponse[ResultWithTextAndSummary]:
+        ...
+
+    @overload
+    def get_contents(
+        self,
+        ids: Union[str, List[str], List[_Result]],
+        *,
+        highlights: Union[HighlightsContentsOptions, Literal[True]],
+        summary: Union[SummaryContentsOptions, Literal[True]],
+    ) -> SearchResponse[ResultWithHighlightsAndSummary]:
+        ...
+
+    @overload
+    def get_contents(
+        self,
+        ids: Union[str, List[str], List[_Result]],
+        *,
+        text: Union[TextContentsOptions, Literal[True]],
+        highlights: Union[HighlightsContentsOptions, Literal[True]],
+        summary: Union[SummaryContentsOptions, Literal[True]],
+    ) -> 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 k != "self" and v is not None
         }
-        if "text" not in options and "highlights" not in options:
+        if "text" not in options and "highlights" not in options and "summary" not in options:
             options["text"] = True
         validate_search_options(options, {**CONTENTS_OPTIONS_TYPES})
         options = to_camel_case(options)
@@ -560,6 +795,8 @@ class Exa:
         end_crawl_date: Optional[str] = None,
         start_published_date: Optional[str] = None,
         end_published_date: Optional[str] = None,
+        include_text: Optional[List[str]] = None,
+        exclude_text: Optional[List[str]] = None,
         exclude_source_domain: Optional[bool] = None,
         category: Optional[str] = None,
     ) -> SearchResponse[_Result]:
@@ -584,6 +821,8 @@ class Exa:
         end_crawl_date: Optional[str] = None,
         start_published_date: Optional[str] = None,
         end_published_date: Optional[str] = None,
+        include_text: Optional[List[str]] = None,
+        exclude_text: Optional[List[str]] = None,
         exclude_source_domain: Optional[bool] = None,
         category: Optional[str] = None,
     ) -> SearchResponse[ResultWithText]:
@@ -602,6 +841,8 @@ class Exa:
         end_crawl_date: Optional[str] = None,
         start_published_date: Optional[str] = None,
         end_published_date: Optional[str] = None,
+        include_text: Optional[List[str]] = None,
+        exclude_text: Optional[List[str]] = None,
         exclude_source_domain: Optional[bool] = None,
         category: Optional[str] = None,
     ) -> SearchResponse[ResultWithText]:
@@ -620,6 +861,8 @@ class Exa:
         end_crawl_date: Optional[str] = None,
         start_published_date: Optional[str] = None,
         end_published_date: Optional[str] = None,
+        include_text: Optional[List[str]] = None,
+        exclude_text: Optional[List[str]] = None,
         exclude_source_domain: Optional[bool] = None,
         category: Optional[str] = None,
     ) -> SearchResponse[ResultWithHighlights]:
@@ -639,11 +882,97 @@ class Exa:
         end_crawl_date: Optional[str] = None,
         start_published_date: Optional[str] = None,
         end_published_date: Optional[str] = None,
+        include_text: Optional[List[str]] = None,
+        exclude_text: Optional[List[str]] = None,
         exclude_source_domain: Optional[bool] = None,
         category: Optional[str] = None,
     ) -> SearchResponse[ResultWithTextAndHighlights]:
         ...
 
+    @overload
+    def find_similar_and_contents(
+        self,
+        url: str,
+        *,
+        summary: Union[SummaryContentsOptions, Literal[True]],
+        num_results: Optional[int] = None,
+        include_domains: Optional[List[str]] = None,
+        exclude_domains: Optional[List[str]] = None,
+        start_crawl_date: Optional[str] = None,
+        end_crawl_date: Optional[str] = None,
+        start_published_date: Optional[str] = None,
+        end_published_date: Optional[str] = None,
+        include_text: Optional[List[str]] = None,
+        exclude_text: Optional[List[str]] = None,
+        exclude_source_domain: Optional[bool] = None,
+        category: Optional[str] = None,
+    ) -> SearchResponse[ResultWithSummary]:
+        ...
+
+    @overload
+    def find_similar_and_contents(
+        self,
+        url: str,
+        *,
+        text: Union[TextContentsOptions, Literal[True]],
+        summary: Union[SummaryContentsOptions, Literal[True]],
+        num_results: Optional[int] = None,
+        include_domains: Optional[List[str]] = None,
+        exclude_domains: Optional[List[str]] = None,
+        start_crawl_date: Optional[str] = None,
+        end_crawl_date: Optional[str] = None,
+        start_published_date: Optional[str] = None,
+        end_published_date: Optional[str] = None,
+        include_text: Optional[List[str]] = None,
+        exclude_text: Optional[List[str]] = None,
+        exclude_source_domain: Optional[bool] = None,
+        category: Optional[str] = None,
+    ) -> SearchResponse[ResultWithTextAndSummary]:
+        ...
+
+    @overload
+    def find_similar_and_contents(
+        self,
+        url: str,
+        *,
+        highlights: Union[HighlightsContentsOptions, Literal[True]],
+        summary: Union[SummaryContentsOptions, Literal[True]],
+        num_results: Optional[int] = None,
+        include_domains: Optional[List[str]] = None,
+        exclude_domains: Optional[List[str]] = None,
+        start_crawl_date: Optional[str] = None,
+        end_crawl_date: Optional[str] = None,
+        start_published_date: Optional[str] = None,
+        end_published_date: Optional[str] = None,
+        include_text: Optional[List[str]] = None,
+        exclude_text: Optional[List[str]] = None,
+        exclude_source_domain: Optional[bool] = None,
+        category: Optional[str] = None,
+    ) -> SearchResponse[ResultWithHighlightsAndSummary]:
+        ...
+
+    @overload
+    def find_similar_and_contents(
+        self,
+        url: str,
+        *,
+        text: Union[TextContentsOptions, Literal[True]],
+        highlights: Union[HighlightsContentsOptions, Literal[True]],
+        summary: Union[SummaryContentsOptions, Literal[True]],
+        num_results: Optional[int] = None,
+        include_domains: Optional[List[str]] = None,
+        exclude_domains: Optional[List[str]] = None,
+        start_crawl_date: Optional[str] = None,
+        end_crawl_date: Optional[str] = None,
+        start_published_date: Optional[str] = None,
+        end_published_date: Optional[str] = None,
+        include_text: Optional[List[str]] = None,
+        exclude_text: Optional[List[str]] = None,
+        exclude_source_domain: Optional[bool] = None,
+        category: Optional[str] = None,
+    ) -> SearchResponse[ResultWithTextAndHighlightsAndSummary]:
+        ...
+
     def find_similar_and_contents(self, url: str, **kwargs):
         options = {
             k: v
@@ -656,12 +985,13 @@ class Exa:
             options, {**FIND_SIMILAR_OPTIONS_TYPES, **CONTENTS_OPTIONS_TYPES}
         )
         options = to_camel_case(options)
-        options = nest_fields(options, ["text", "highlights"], "contents")
+        options = nest_fields(options, ["text", "highlights", "summary"], "contents")
         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,
         )
+
     def wrap(self, client: OpenAI):
         """Wrap an OpenAI client with Exa functionality.
 
@@ -693,6 +1023,8 @@ class Exa:
             end_crawl_date: Optional[str] = None,
             start_published_date: Optional[str] = None,
             end_published_date: Optional[str] = None,
+            include_text: Optional[List[str]] = None,
+            exclude_text: Optional[List[str]] = None,
             use_autoprompt: Optional[bool] = True,
             type: Optional[str] = None,
             category: Optional[str] = None,
@@ -709,6 +1041,8 @@ class Exa:
                 "end_crawl_date": end_crawl_date,
                 "start_published_date": start_published_date,
                 "end_published_date": end_published_date,
+                "include_text": include_text,
+                "exclude_text": exclude_text,
                 "use_autoprompt": use_autoprompt,
                 "type": type,
                 "category": category,
@@ -767,7 +1101,7 @@ class Exa:
         create_kwargs["tools"] = tools
 
         completion = create_fn(messages=messages, **create_kwargs)
-    
+
         query = maybe_get_query(completion)
 
         if not query:

{exa_py-1.0.14 → exa_py-1.0.16}/exa_py.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: exa-py
-Version: 1.0.14
+Version: 1.0.16
 Summary: Python SDK for Exa API.
 Home-page: https://github.com/exa-labs/exa-py
 Author: Exa

{exa_py-1.0.14 → exa_py-1.0.16}/setup.py

@@ -2,7 +2,7 @@ from setuptools import setup, find_packages
 
 setup(
     name="exa_py",
-    version="1.0.14",
+    version="1.0.16",
     description="Python SDK for Exa API.",
     long_description_content_type="text/markdown",
     long_description=open("README.md").read(),