exa-py 1.0.1__tar.gz → 1.0.5__tar.gz

exa_py-1.0.5/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.1
+Name: exa_py
+Version: 1.0.5
+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.7
+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 API in Python
+
+## 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")
+```
+
+## Search Request
+
+```python
+
+response = exa.search("funny article about silicon valley tech culture",
+    num_results=5,
+    include_domains=["nytimes.com", "wsj.com"],
+    start_published_date="2023-06-12"
+)
+
+for result in response.results:
+    print(result.title, result.url)
+```
+
+## Find Similar
+
+```python
+response = exa.find_similar("https://waitbutwhy.com/2014/05/fermi-paradox.html", num_results=5)
+
+for result in response.results:
+    print(result.title, result.url)
+```
+
+## Retrieve Document Contents
+
+```python
+ids = ["8U71IlQ5DUTdsZFherhhYA", "X3wd0PbJmAvhu_DQjDKA7A"]
+response = exa.get_contents(ids)
+
+for content in response.contents:
+    print(content.title, content.url)
+```
+
+## Reference
+
+### `exa.search()`
+
+This function performs a search on the Exa API.
+
+#### Args
+
+- query (str): The search query.
+- **options**: Additional search options. Valid options are:
+  - `num_results` (int): The number of search results to return.
+  - `include_domains` (list): A list of domains to include in the search.
+  - `exclude_domains` (list): A list of domains to exclude from the search.
+  - `start_crawl_date` (str): The start date for the crawl (in YYYY-MM-DD format).
+  - `end_crawl_date` (str): The end date for the crawl (in YYYY-MM-DD format).
+  - `start_published_date` (str): The start date for when the document was published (in YYYY-MM-DD format).
+  - `end_published_date` (str): The end date for when the document was published (in YYYY-MM-DD format).
+  - `use_autoprompt` (bool): Whether to use autoprompt for the search.
+  - `type` (str): The type of search, 'keyword' or 'neural'. Default: neural
+
+#### Returns
+`SearchResponse`: A dataclass containing the search results.
+
+### `exa.find_similar()`
+
+#### Args:
+- url (str): The base url to find similar links with.
+- **options**: Additional search options. Valid options are:
+    - `num_results` (int): The number of search results to return.
+    - `include_domains` (list): A list of domains to include in the search.
+    - `exclude_domains` (list): A list of domains to exclude from the search.
+    - `start_crawl_date` (str): The start date for the crawl (in YYYY-MM-DD format).
+    - `end_crawl_date` (str): The end date for the crawl (in YYYY-MM-DD format).
+    - `start_published_date` (str): The start date for when the document was published (in YYYY-MM-DD format).
+    - `end_published_date` (str): The end date for when the document was published (in YYYY-MM-DD format).
+
+#### Returns
+`SearchResponse`: A dataclass containing the search results.
+
+# Contribution
+Contributions to exa-py are very welcome! Feel free to submit pull requests or raise issues.

{exa_py-1.0.1 → exa_py-1.0.5}/exa_py/api.py

@@ -1,4 +1,6 @@
 from __future__ import annotations
+from dataclasses import dataclass
+import dataclasses
 import re
 import requests
 from typing import (
@@ -13,6 +15,7 @@ from typing import (
     Literal,
 )
 
+
 def snake_to_camel(snake_str: str) -> str:
     """Convert snake_case string to camelCase.
 
@@ -25,6 +28,7 @@ def snake_to_camel(snake_str: str) -> str:
     components = snake_str.split("_")
     return components[0] + "".join(x.title() for x in components[1:])
 
+
 def to_camel_case(data: dict) -> dict:
     """Convert keys in a dictionary from snake_case to camelCase.
 
@@ -36,6 +40,7 @@ def to_camel_case(data: dict) -> dict:
     """
     return {snake_to_camel(k): v for k, v in data.items() if v is not None}
 
+
 def camel_to_snake(camel_str: str) -> str:
     """Convert camelCase string to snake_case.
 
@@ -48,6 +53,7 @@ def camel_to_snake(camel_str: str) -> str:
     snake_str = re.sub("(.)([A-Z][a-z]+)", r"\1_\2", camel_str)
     return re.sub("([a-z0-9])([A-Z])", r"\1_\2", snake_str).lower()
 
+
 def to_snake_case(data: dict) -> dict:
     """Convert keys in a dictionary from camelCase to snake_case.
 
@@ -59,8 +65,6 @@ def to_snake_case(data: dict) -> dict:
     """
     return {camel_to_snake(k): v for k, v in data.items()}
 
-from dataclasses import dataclass
-
 SEARCH_OPTIONS_TYPES = {
     "query": str,  # The query string.
     "num_results": int,  # Number of results (Default: 10, Max for basic: 10).
@@ -88,7 +92,8 @@ FIND_SIMILAR_OPTIONS_TYPES = {
     "category": str,
 }
 
-CONTENTS_OPTIONS_TYPES = {"ids": list, "text": dict | bool, "highlights": dict | bool}
+CONTENTS_OPTIONS_TYPES = {"ids": list, "text": Union[dict, bool], "highlights": Union[dict, bool]}
+
 
 def validate_search_options(
     options: Dict[str, Optional[object]], expected: dict
@@ -115,10 +120,10 @@ class TextContentsOptions(TypedDict, total=False):
     """A class representing the options that you can specify when requesting text
 
     Attributes:
-        max_length (int): The maximum number of characters to return. Default: None (no limit).
+        max_characters (int): The maximum number of characters to return. Default: None (no limit).
         include_html_tags (bool): If true, include HTML tags in the returned text. Default false.
     """
-    max_length: int
+    max_characters: int
     include_html_tags: bool
 
 
@@ -130,6 +135,7 @@ class HighlightsContentsOptions(TypedDict, total=False):
         num_sentences (int): Size of highlights to return, in sentences. Default: 5
         highlights_per_url (int): The number of highlights to return per URL. Default: 1
     """
+
     query: str
     num_sentences: int
     highlights_per_url: int
@@ -148,12 +154,12 @@ class _Result:
         author (str, optional): If available, the author of the content.
     """
 
-    title: str
     url: str
     id: str
-    score: Optional[float]
-    published_date: Optional[str]
-    author: Optional[str]
+    title: Optional[str] = None
+    score: Optional[float] = None
+    published_date: Optional[str] = None
+    author: Optional[str] = None
 
     def __str__(self):
         return (
@@ -198,7 +204,8 @@ class ResultWithText(_Result):
     Attributes:
         text (str): The text of the search result page.
     """
-    text: str
+
+    text: str = dataclasses.field(default_factory=str)
 
     def __str__(self):
         base_str = super().__str__()
@@ -214,8 +221,9 @@ class ResultWithHighlights(_Result):
         highlights (List[str]): The highlights of the search result.
         highlight_scores (List[float]): The scores of the highlights of the search result.
     """
-    highlights: List[str]
-    highlight_scores: List[float]
+
+    highlights: List[str] = dataclasses.field(default_factory=list)
+    highlight_scores: List[float] = dataclasses.field(default_factory=list)
 
     def __str__(self):
         base_str = super().__str__()
@@ -235,9 +243,10 @@ class ResultWithTextAndHighlights(_Result):
         highlights (List[str): The highlights of the search result.
         highlight_scores (List[float]): The scores of the highlights of the search result.
     """
-    text: str
-    highlights: List[str]
-    highlight_scores: List[float]
+
+    text: str = dataclasses.field(default_factory=str)
+    highlights: List[str] = dataclasses.field(default_factory=list)
+    highlight_scores: List[float] = dataclasses.field(default_factory=list)
 
     def __str__(self):
         base_str = super().__str__()
@@ -257,16 +266,16 @@ class SearchResponse(Generic[T]):
 
     Attributes:
         results (List[Result]): A list of search results.
-        autopromptString (str, optional): The Exa query created by the autoprompt functionality.
+        autoprompt_string (str, optional): The Exa query created by the autoprompt functionality.
     """
 
     results: List[T]
-    autopromptString: Optional[str]
+    autoprompt_string: Optional[str]
 
     def __str__(self):
         output = "\n\n".join(str(result) for result in self.results)
-        if self.autopromptString:
-            output += f"\n\nAutoprompt String: {self.autopromptString}"
+        if self.autoprompt_string:
+            output += f"\n\nAutoprompt String: {self.autoprompt_string}"
         return output
 
 
@@ -290,7 +299,7 @@ def nest_fields(original_dict: Dict, fields_to_nest: List[str], new_key: str):
 class Exa:
     """A client for interacting with Exa API."""
 
-    def __init__(self, api_key: Optional[str], base_url: str = "https://api.exa.ai"):
+    def __init__(self, api_key: Optional[str], base_url: str = "https://api.exa.ai", user_agent: str = "metaphor-python 1.0.2"):
         """Initialize the Exa client with the provided API key and optional base URL and user agent.
 
         Args:
@@ -306,7 +315,7 @@ class Exa:
                     "API key must be provided as argument or in EXA_API_KEY environment variable"
                 )
         self.base_url = base_url
-        self.headers = {"x-api-key": api_key}
+        self.headers = {"x-api-key": api_key, "User-Agent": user_agent}
 
     def request(self, endpoint: str, data):
         res = requests.post(self.base_url + endpoint, json=data, headers=self.headers)
@@ -362,8 +371,6 @@ class Exa:
         self,
         query: str,
         *,
-        text: Optional[Literal[False]] = None,
-        highlights: Optional[Literal[False]] = None,
         num_results: Optional[int] = None,
         include_domains: Optional[List[str]] = None,
         exclude_domains: Optional[List[str]] = None,
@@ -374,7 +381,7 @@ class Exa:
         use_autoprompt: Optional[bool] = None,
         type: Optional[str] = None,
         category: Optional[str] = None,
-    ) -> SearchResponse[_Result]:
+    ) -> SearchResponse[ResultWithText]:
         ...
 
     @overload
@@ -383,7 +390,6 @@ class Exa:
         query: str,
         *,
         text: Union[TextContentsOptions, Literal[True]],
-        highlights: Optional[Literal[False]] = None,
         num_results: Optional[int] = None,
         include_domains: Optional[List[str]] = None,
         exclude_domains: Optional[List[str]] = None,
@@ -402,7 +408,6 @@ class Exa:
         self,
         query: str,
         *,
-        text: Optional[Literal[False]] = None,
         highlights: Union[HighlightsContentsOptions, Literal[True]],
         num_results: Optional[int] = None,
         include_domains: Optional[List[str]] = None,
@@ -443,6 +448,8 @@ class Exa:
             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:
+            options["text"] = True
         validate_search_options(
             options, {**SEARCH_OPTIONS_TYPES, **CONTENTS_OPTIONS_TYPES}
         )
@@ -455,37 +462,32 @@ class Exa:
         )
 
     @overload
-    def contents(
+    def get_contents(
         self,
         ids: Union[str, List[str], List[_Result]],
-        *,
-        text: Optional[Literal[False]] = None,
-        highlights: Optional[Literal[False]] = None,
-    ) -> SearchResponse[_Result]:
+    ) -> SearchResponse[ResultWithText]:
         ...
 
     @overload
-    def contents(
+    def get_contents(
         self,
         ids: Union[str, List[str], List[_Result]],
         *,
         text: Union[TextContentsOptions, Literal[True]],
-        highlights: Optional[Literal[False]] = None,
     ) -> SearchResponse[ResultWithText]:
         ...
 
     @overload
-    def contents(
+    def get_contents(
         self,
         ids: Union[str, List[str], List[_Result]],
         *,
-        text: Optional[Literal[False]] = None,
         highlights: Union[HighlightsContentsOptions, Literal[True]],
     ) -> SearchResponse[ResultWithHighlights]:
         ...
 
     @overload
-    def contents(
+    def get_contents(
         self,
         ids: Union[str, List[str], List[_Result]],
         *,
@@ -494,12 +496,14 @@ class Exa:
     ) -> SearchResponse[ResultWithTextAndHighlights]:
         ...
 
-    def contents(self, ids: Union[str, List[str], List[_Result]], **kwargs):
+    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:
+            options["text"] = True
         validate_search_options(options, {**CONTENTS_OPTIONS_TYPES})
         options = to_camel_case(options)
         data = self.request("/contents", options)
@@ -536,8 +540,6 @@ class Exa:
         self,
         url: str,
         *,
-        text: Optional[Literal[False]] = None,
-        highlights: Optional[Literal[False]] = None,
         num_results: Optional[int] = None,
         include_domains: Optional[List[str]] = None,
         exclude_domains: Optional[List[str]] = None,
@@ -547,7 +549,7 @@ class Exa:
         end_published_date: Optional[str] = None,
         exclude_source_domain: Optional[bool] = None,
         category: Optional[str] = None,
-    ) -> SearchResponse[_Result]:
+    ) -> SearchResponse[ResultWithText]:
         ...
 
     @overload
@@ -556,7 +558,6 @@ class Exa:
         url: str,
         *,
         text: Union[TextContentsOptions, Literal[True]],
-        highlights: Optional[Literal[False]] = None,
         num_results: Optional[int] = None,
         include_domains: Optional[List[str]] = None,
         exclude_domains: Optional[List[str]] = None,
@@ -574,7 +575,6 @@ class Exa:
         self,
         url: str,
         *,
-        text: Optional[Literal[False]] = None,
         highlights: Union[HighlightsContentsOptions, Literal[True]],
         num_results: Optional[int] = None,
         include_domains: Optional[List[str]] = None,
@@ -613,6 +613,8 @@ class Exa:
             for k, v in {"url": url, **kwargs}.items()
             if k != "self" and v is not None
         }
+        if "text" not in options and "highlights" not in options:
+            options["text"] = True
         validate_search_options(
             options, {**FIND_SIMILAR_OPTIONS_TYPES, **CONTENTS_OPTIONS_TYPES}
         )

exa_py-1.0.5/exa_py.egg-info/PKG-INFO

@@ -0,0 +1,113 @@
+Metadata-Version: 2.1
+Name: exa-py
+Version: 1.0.5
+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.7
+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 API in Python
+
+## 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")
+```
+
+## Search Request
+
+```python
+
+response = exa.search("funny article about silicon valley tech culture",
+    num_results=5,
+    include_domains=["nytimes.com", "wsj.com"],
+    start_published_date="2023-06-12"
+)
+
+for result in response.results:
+    print(result.title, result.url)
+```
+
+## Find Similar
+
+```python
+response = exa.find_similar("https://waitbutwhy.com/2014/05/fermi-paradox.html", num_results=5)
+
+for result in response.results:
+    print(result.title, result.url)
+```
+
+## Retrieve Document Contents
+
+```python
+ids = ["8U71IlQ5DUTdsZFherhhYA", "X3wd0PbJmAvhu_DQjDKA7A"]
+response = exa.get_contents(ids)
+
+for content in response.contents:
+    print(content.title, content.url)
+```
+
+## Reference
+
+### `exa.search()`
+
+This function performs a search on the Exa API.
+
+#### Args
+
+- query (str): The search query.
+- **options**: Additional search options. Valid options are:
+  - `num_results` (int): The number of search results to return.
+  - `include_domains` (list): A list of domains to include in the search.
+  - `exclude_domains` (list): A list of domains to exclude from the search.
+  - `start_crawl_date` (str): The start date for the crawl (in YYYY-MM-DD format).
+  - `end_crawl_date` (str): The end date for the crawl (in YYYY-MM-DD format).
+  - `start_published_date` (str): The start date for when the document was published (in YYYY-MM-DD format).
+  - `end_published_date` (str): The end date for when the document was published (in YYYY-MM-DD format).
+  - `use_autoprompt` (bool): Whether to use autoprompt for the search.
+  - `type` (str): The type of search, 'keyword' or 'neural'. Default: neural
+
+#### Returns
+`SearchResponse`: A dataclass containing the search results.
+
+### `exa.find_similar()`
+
+#### Args:
+- url (str): The base url to find similar links with.
+- **options**: Additional search options. Valid options are:
+    - `num_results` (int): The number of search results to return.
+    - `include_domains` (list): A list of domains to include in the search.
+    - `exclude_domains` (list): A list of domains to exclude from the search.
+    - `start_crawl_date` (str): The start date for the crawl (in YYYY-MM-DD format).
+    - `end_crawl_date` (str): The end date for the crawl (in YYYY-MM-DD format).
+    - `start_published_date` (str): The start date for when the document was published (in YYYY-MM-DD format).
+    - `end_published_date` (str): The end date for when the document was published (in YYYY-MM-DD format).
+
+#### Returns
+`SearchResponse`: A dataclass containing the search results.
+
+# Contribution
+Contributions to exa-py are very welcome! Feel free to submit pull requests or raise issues.

{exa_py-1.0.1 → exa_py-1.0.5}/setup.py

@@ -2,8 +2,10 @@ from setuptools import setup, find_packages
 
 setup(
     name='exa_py',
-    version='1.0.1',
+    version='1.0.5',
     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"]},
@@ -17,7 +19,11 @@ setup(
         'Intended Audience :: Developers',
         'License :: OSI Approved :: MIT License',
         "Typing :: Typed",
+        'Programming Language :: Python :: 3.7',
         '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',
     ],
 )

exa_py-1.0.1/PKG-INFO

@@ -1,13 +0,0 @@
-Metadata-Version: 2.1
-Name: exa_py
-Version: 1.0.1
-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

exa_py-1.0.1/exa_py.egg-info/PKG-INFO

@@ -1,13 +0,0 @@
-Metadata-Version: 2.1
-Name: exa-py
-Version: 1.0.1
-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