exa-py 1.12.1__tar.gz → 1.13.1__tar.gz

{exa_py-1.12.1 → exa_py-1.13.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: exa-py
-Version: 1.12.1
+Version: 1.13.1
 Summary: Python SDK for Exa API.
 License: MIT
 Author: Exa AI
@@ -50,9 +50,6 @@ exa = Exa(api_key="your-api-key")
   # 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")
 
@@ -65,13 +62,9 @@ exa = Exa(api_key="your-api-key")
   # 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:"})
+                                    text={"include_html_tags": True, "max_characters": 1000})
                                     
   # find similar documents
   results = exa.find_similar("https://example.com")
@@ -80,18 +73,14 @@ exa = Exa(api_key="your-api-key")
   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)
+  results = exa.find_similar_and_contents("https://example.com", text=True)
 
   # get text contents
-  results = exa.get_contents(["urls"])
-
-  # get highlights
-  results = exa.get_contents(["urls"], highlights=True)
+  results = exa.get_contents(["tesla.com"])
 
   # 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:"})
+                             text={"include_html_tags": True, "max_characters": 1000})
 
   # basic answer
   response = exa.answer("This is a query to answer a question")

{exa_py-1.12.1 → exa_py-1.13.1}/README.md

@@ -27,9 +27,6 @@ exa = Exa(api_key="your-api-key")
   # 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")
 
@@ -42,13 +39,9 @@ exa = Exa(api_key="your-api-key")
   # 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:"})
+                                    text={"include_html_tags": True, "max_characters": 1000})
                                     
   # find similar documents
   results = exa.find_similar("https://example.com")
@@ -57,18 +50,14 @@ exa = Exa(api_key="your-api-key")
   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)
+  results = exa.find_similar_and_contents("https://example.com", text=True)
 
   # get text contents
-  results = exa.get_contents(["urls"])
-
-  # get highlights
-  results = exa.get_contents(["urls"], highlights=True)
+  results = exa.get_contents(["tesla.com"])
 
   # 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:"})
+                             text={"include_html_tags": True, "max_characters": 1000})
 
   # basic answer
   response = exa.answer("This is a query to answer a question")

{exa_py-1.12.1 → exa_py-1.13.1}/exa_py/api.py

@@ -56,7 +56,7 @@ def snake_to_camel(snake_str: str) -> str:
         return "$schema"
     if snake_str == "not_":
         return "not"
-        
+
     components = snake_str.split("_")
     return components[0] + "".join(x.title() for x in components[1:])
 
@@ -261,6 +261,7 @@ class JSONSchema(TypedDict, total=False):
     """Represents a JSON Schema definition used for structured summary output.
     To learn more visit https://json-schema.org/overview/what-is-jsonschema.
     """
+
     schema_: str  # This will be converted to "$schema" in JSON
     title: str
     description: str
@@ -288,7 +289,7 @@ class SummaryContentsOptions(TypedDict, total=False):
 
     query: str
     schema: JSONSchema
-    
+
 
 class ExtrasOptions(TypedDict, total=False):
     """A class representing additional extraction fields (e.g. links, images)"""
@@ -669,7 +670,7 @@ class AnswerResponse:
         citations (List[AnswerResult]): A list of citations used to generate the answer.
     """
 
-    answer: str
+    answer: Union[str, dict[str, Any]]
     citations: List[AnswerResult]
 
     def __str__(self):
@@ -765,9 +766,9 @@ class AsyncStreamAnswerResponse:
                         content = chunk["choices"][0]["delta"].get("content")
 
                 if (
-                        "citations" in chunk
-                        and chunk["citations"]
-                        and chunk["citations"] != "null"
+                    "citations" in chunk
+                    and chunk["citations"]
+                    and chunk["citations"] != "null"
                 ):
                     citations = [
                         AnswerResult(**to_snake_case(s)) for s in chunk["citations"]
@@ -776,6 +777,7 @@ class AsyncStreamAnswerResponse:
                 stream_chunk = StreamChunk(content=content, citations=citations)
                 if stream_chunk.has_data():
                     yield stream_chunk
+
         return generator()
 
     def close(self) -> None:
@@ -835,6 +837,37 @@ def nest_fields(original_dict: Dict, fields_to_nest: List[str], new_key: str):
     return original_dict
 
 
+@dataclass
+class ResearchTaskResponse:
+    """A class representing the response for a research task.
+
+    Attributes:
+        id (str): The unique identifier for the research request.
+        status (str): Status of the research request.
+        output (Optional[Dict[str, Any]]): The answer structured as JSON, if available.
+        citations (Optional[Dict[str, List[_Result]]]): List of citations used to generate the answer, grouped by root field in the output schema.
+    """
+
+    id: str
+    status: str
+    output: Optional[Dict[str, Any]]
+    citations: Dict[str, List[_Result]]
+
+    def __str__(self):
+        output_repr = (
+            json.dumps(self.output, indent=2, ensure_ascii=False)
+            if self.output is not None
+            else "None"
+        )
+        citations_str = "\n\n".join(str(src) for src in self.citations)
+        return (
+            f"ID: {self.id}\n"
+            f"Status: {self.status}\n"
+            f"Output: {output_repr}\n\n"
+            f"Citations:\n{citations_str}"
+        )
+
+
 class Exa:
     """A client for interacting with Exa API."""
 
@@ -859,10 +892,20 @@ class Exa:
                     "API key must be provided as an argument or in EXA_API_KEY environment variable"
                 )
         self.base_url = base_url
-        self.headers = {"x-api-key": api_key, "User-Agent": user_agent, "Content-Type": "application/json"}
+        self.headers = {
+            "x-api-key": api_key,
+            "User-Agent": user_agent,
+            "Content-Type": "application/json",
+        }
         self.websets = WebsetsClient(self)
 
-    def request(self, endpoint: str, data: Optional[Union[Dict[str, Any], str]] = None, method: str = "POST", params: Optional[Dict[str, Any]] = None) -> Union[Dict[str, Any], requests.Response]:
+    def request(
+        self,
+        endpoint: str,
+        data: Optional[Union[Dict[str, Any], str]] = None,
+        method: str = "POST",
+        params: Optional[Dict[str, Any]] = None,
+    ) -> Union[Dict[str, Any], requests.Response]:
         """Send a request to the Exa API, optionally streaming if data['stream'] is True.
 
         Args:
@@ -885,13 +928,13 @@ class Exa:
         else:
             # Otherwise, serialize the dictionary to JSON if it exists
             json_data = json.dumps(data, cls=ExaJSONEncoder) if data else None
-            
+
         if data and data.get("stream"):
             res = requests.post(
-                self.base_url + endpoint, 
+                self.base_url + endpoint,
                 data=json_data,
-                headers=self.headers, 
-                stream=True
+                headers=self.headers,
+                stream=True,
             )
             return res
 
@@ -901,20 +944,14 @@ class Exa:
             )
         elif method.upper() == "POST":
             res = requests.post(
-                self.base_url + endpoint, 
-                data=json_data,
-                headers=self.headers
+                self.base_url + endpoint, data=json_data, headers=self.headers
             )
         elif method.upper() == "PATCH":
             res = requests.patch(
-                self.base_url + endpoint, 
-                data=json_data,
-                headers=self.headers
+                self.base_url + endpoint, data=json_data, headers=self.headers
             )
         elif method.upper() == "DELETE":
-            res = requests.delete(
-                self.base_url + endpoint, headers=self.headers
-            )
+            res = requests.delete(self.base_url + endpoint, headers=self.headers)
         else:
             raise ValueError(f"Unsupported HTTP method: {method}")
 
@@ -1845,6 +1882,7 @@ class Exa:
         text: Optional[bool] = False,
         system_prompt: Optional[str] = None,
         model: Optional[Literal["exa", "exa-pro"]] = None,
+        output_schema: Optional[dict[str, Any]] = None,
     ) -> Union[AnswerResponse, StreamAnswerResponse]: ...
 
     def answer(
@@ -1855,6 +1893,7 @@ class Exa:
         text: Optional[bool] = False,
         system_prompt: Optional[str] = None,
         model: Optional[Literal["exa", "exa-pro"]] = None,
+        output_schema: Optional[dict[str, Any]] = None,
     ) -> Union[AnswerResponse, StreamAnswerResponse]:
         """Generate an answer to a query using Exa's search and LLM capabilities.
 
@@ -1863,6 +1902,7 @@ class Exa:
             text (bool, optional): Whether to include full text in the results. Defaults to False.
             system_prompt (str, optional): A system prompt to guide the LLM's behavior when generating the answer.
             model (str, optional): The model to use for answering. Either "exa" or "exa-pro". Defaults to None.
+            output_schema (dict[str, Any], optional): JSON schema describing the desired answer structure.
 
         Returns:
             AnswerResponse: An object containing the answer and citations.
@@ -1892,6 +1932,7 @@ class Exa:
         text: bool = False,
         system_prompt: Optional[str] = None,
         model: Optional[Literal["exa", "exa-pro"]] = None,
+        output_schema: Optional[dict[str, Any]] = None,
     ) -> StreamAnswerResponse:
         """Generate a streaming answer response.
 
@@ -1900,7 +1941,7 @@ class Exa:
             text (bool): Whether to include full text in the results. Defaults to False.
             system_prompt (str, optional): A system prompt to guide the LLM's behavior when generating the answer.
             model (str, optional): The model to use for answering. Either "exa" or "exa-pro". Defaults to None.
-
+            output_schema (dict[str, Any], optional): JSON schema describing the desired answer structure.
         Returns:
             StreamAnswerResponse: An object that can be iterated over to retrieve (partial text, partial citations).
                 Each iteration yields a tuple of (Optional[str], Optional[List[AnswerResult]]).
@@ -1911,6 +1952,37 @@ class Exa:
         raw_response = self.request("/answer", options)
         return StreamAnswerResponse(raw_response)
 
+    def researchTask(
+        self,
+        *,
+        input_instructions: str,
+        output_schema: Dict[str, Any],
+    ) -> ResearchTaskResponse:
+        """Submit a research request to Exa.
+
+        Args:
+            input_instructions (str): The instructions for the research task.
+            output_schema (Dict[str, Any]): JSON schema describing the desired answer structure.
+        """
+        # Build the request payload expected by the Exa API
+        options = {
+            "input": {"instructions": input_instructions},
+            "output": {"schema": output_schema},
+        }
+
+        response = self.request("/research/tasks", options)
+
+        return ResearchTaskResponse(
+            id=response["id"],
+            status=response["status"],
+            output=response.get("output"),
+            citations={
+                key: [_Result(**to_snake_case(citation)) for citation in citations_list]
+                for key, citations_list in response.get("citations", {}).items()
+            },
+        )
+
+
 class AsyncExa(Exa):
     def __init__(self, api_key: str, api_base: str = "https://api.exa.ai"):
         super().__init__(api_key, api_base)
@@ -1921,9 +1993,7 @@ class AsyncExa(Exa):
         # this may only be a
         if self._client is None:
             self._client = httpx.AsyncClient(
-                base_url=self.base_url,
-                headers=self.headers,
-                timeout=60
+                base_url=self.base_url, headers=self.headers, timeout=60
             )
         return self._client
 
@@ -1943,15 +2013,14 @@ class AsyncExa(Exa):
         """
         if data.get("stream"):
             request = httpx.Request(
-                'POST',
-                self.base_url + endpoint,
-                json=data,
-                headers=self.headers
+                "POST", self.base_url + endpoint, json=data, headers=self.headers
             )
             res = await self.client.send(request, stream=True)
             return res
 
-        res = await self.client.post(self.base_url + endpoint, json=data, headers=self.headers)
+        res = await self.client.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}"
@@ -2189,6 +2258,7 @@ class AsyncExa(Exa):
         text: Optional[bool] = False,
         system_prompt: Optional[str] = None,
         model: Optional[Literal["exa", "exa-pro"]] = None,
+        output_schema: Optional[dict[str, Any]] = None,
     ) -> Union[AnswerResponse, StreamAnswerResponse]:
         """Generate an answer to a query using Exa's search and LLM capabilities.
 
@@ -2197,6 +2267,7 @@ class AsyncExa(Exa):
             text (bool, optional): Whether to include full text in the results. Defaults to False.
             system_prompt (str, optional): A system prompt to guide the LLM's behavior when generating the answer.
             model (str, optional): The model to use for answering. Either "exa" or "exa-pro". Defaults to None.
+            output_schema (dict[str, Any], optional): JSON schema describing the desired answer structure.
 
         Returns:
             AnswerResponse: An object containing the answer and citations.
@@ -2226,6 +2297,7 @@ class AsyncExa(Exa):
         text: bool = False,
         system_prompt: Optional[str] = None,
         model: Optional[Literal["exa", "exa-pro"]] = None,
+        output_schema: Optional[dict[str, Any]] = None,
     ) -> AsyncStreamAnswerResponse:
         """Generate a streaming answer response.
 
@@ -2234,7 +2306,7 @@ class AsyncExa(Exa):
             text (bool): Whether to include full text in the results. Defaults to False.
             system_prompt (str, optional): A system prompt to guide the LLM's behavior when generating the answer.
             model (str, optional): The model to use for answering. Either "exa" or "exa-pro". Defaults to None.
-
+            output_schema (dict[str, Any], optional): JSON schema describing the desired answer structure.
         Returns:
             AsyncStreamAnswerResponse: An object that can be iterated over to retrieve (partial text, partial citations).
                 Each iteration yields a tuple of (Optional[str], Optional[List[AnswerResult]]).
@@ -2244,3 +2316,36 @@ class AsyncExa(Exa):
         options["stream"] = True
         raw_response = await self.async_request("/answer", options)
         return AsyncStreamAnswerResponse(raw_response)
+
+    async def researchTask(
+        self,
+        *,
+        input_instructions: str,
+        output_schema: Dict[str, Any],
+    ) -> ResearchTaskResponse:
+        """Asynchronously submit a research request to Exa.
+
+        Args:
+            input_instructions (str): The instructions for the research task.
+            output_schema (Dict[str, Any]): JSON schema describing the desired answer structure.
+
+        Returns:
+            ResearchTaskResponse: The parsed response from the Exa API.
+        """
+        # Build the request payload expected by the Exa API
+        options = {
+            "input": {"instructions": input_instructions},
+            "output": {"schema": output_schema},
+        }
+
+        response = await self.async_request("/research/tasks", options)
+
+        return ResearchTaskResponse(
+            id=response["id"],
+            status=response["status"],
+            output=response.get("output"),
+            citations={
+                key: [_Result(**to_snake_case(citation)) for citation in citations_list]
+                for key, citations_list in response.get("citations", {}).items()
+            },
+        )

{exa_py-1.12.1 → exa_py-1.13.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [tool.poetry]
 name = "exa-py"
-version = "1.12.1"
+version = "1.13.0"
 description = "Python SDK for Exa API."
 authors = ["Exa AI <hello@exa.ai>"]
 readme = "README.md"
@@ -32,7 +32,7 @@ in-project = true
 
 [project]
 name = "exa-py"
-version = "1.12.1"
+version = "1.13.1"
 description = "Python SDK for Exa API."
 readme = "README.md"
 requires-python = ">=3.9"