exa-py 1.13.0__tar.gz → 1.13.2__tar.gz

{exa_py-1.13.0/exa_py.egg-info → exa_py-1.13.2}/PKG-INFO

@@ -1,21 +1,25 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.3
 Name: exa-py
-Version: 1.13.0
+Version: 1.13.2
 Summary: Python SDK for Exa API.
-Home-page: https://github.com/exa-labs/exa-py
-Author: Exa
-Author-email: Exa AI <hello@exa.ai>
 License: MIT
+Author: Exa AI
+Author-email: hello@exa.ai
 Requires-Python: >=3.9
+Classifier: License :: OSI Approved :: MIT License
+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: httpx (>=0.28.1)
+Requires-Dist: openai (>=1.48)
+Requires-Dist: pydantic (>=2.10.6)
+Requires-Dist: pytest-mock (>=3.14.0)
+Requires-Dist: requests (>=2.32.3)
+Requires-Dist: typing-extensions (>=4.12.2)
 Description-Content-Type: text/markdown
-Requires-Dist: requests>=2.32.3
-Requires-Dist: typing-extensions>=4.12.2
-Requires-Dist: openai>=1.48
-Requires-Dist: pydantic>=2.10.6
-Requires-Dist: pytest-mock>=3.14.0
-Requires-Dist: httpx>=0.28.1
-Dynamic: author
-Dynamic: home-page
 
 # Exa
 
@@ -41,6 +45,7 @@ exa = Exa(api_key="your-api-key")
 ```
 
 ## Common requests
+
 ```python
 
   # basic search
@@ -59,9 +64,9 @@ exa = Exa(api_key="your-api-key")
   results = exa.search_and_contents("This is a Exa query:")
 
   # search and get contents with contents options
-  results = exa.search_and_contents("This is a Exa query:", 
+  results = exa.search_and_contents("This is a Exa query:",
                                     text={"include_html_tags": True, "max_characters": 1000})
-                                    
+
   # find similar documents
   results = exa.find_similar("https://example.com")
 
@@ -75,7 +80,7 @@ exa = Exa(api_key="your-api-key")
   results = exa.get_contents(["tesla.com"])
 
   # get contents with contents options
-  results = exa.get_contents(["urls"], 
+  results = exa.get_contents(["urls"],
                              text={"include_html_tags": True, "max_characters": 1000})
 
   # basic answer
@@ -91,5 +96,38 @@ exa = Exa(api_key="your-api-key")
   for chunk in response:
     print(chunk, end='', flush=True)
 
+  # research task example – answer a question with citations
+  # Example prompt & schema inspired by the TypeScript example.
+  QUESTION = (
+      "Summarize the history of San Francisco highlighting one or two major events "
+      "for each decade from 1850 to 1950"
+  )
+  OUTPUT_SCHEMA: Dict[str, Any] = {
+      "type": "object",
+      "required": ["timeline"],
+      "properties": {
+          "timeline": {
+              "type": "array",
+              "items": {
+                  "type": "object",
+                  "required": ["decade", "notableEvents"],
+                  "properties": {
+                      "decade": {
+                          "type": "string",
+                          "description": 'Decade label e.g. "1850s"',
+                      },
+                      "notableEvents": {
+                          "type": "string",
+                          "description": "A summary of notable events.",
+                      },
+                  },
+              },
+          },
+      },
+  }
+  resp = exa.research.create_task(
+      input_instructions=QUESTION,
+      output_schema=OUTPUT_SCHEMA,
+  )
 ```
 

exa_py-1.13.0/PKG-INFO → exa_py-1.13.2/README.md

@@ -1,22 +1,3 @@
-Metadata-Version: 2.4
-Name: exa-py
-Version: 1.13.0
-Summary: Python SDK for Exa API.
-Home-page: https://github.com/exa-labs/exa-py
-Author: Exa
-Author-email: Exa AI <hello@exa.ai>
-License: MIT
-Requires-Python: >=3.9
-Description-Content-Type: text/markdown
-Requires-Dist: requests>=2.32.3
-Requires-Dist: typing-extensions>=4.12.2
-Requires-Dist: openai>=1.48
-Requires-Dist: pydantic>=2.10.6
-Requires-Dist: pytest-mock>=3.14.0
-Requires-Dist: httpx>=0.28.1
-Dynamic: author
-Dynamic: home-page
-
 # Exa
 
 Exa (formerly Metaphor) API in Python
@@ -41,6 +22,7 @@ exa = Exa(api_key="your-api-key")
 ```
 
 ## Common requests
+
 ```python
 
   # basic search
@@ -59,9 +41,9 @@ exa = Exa(api_key="your-api-key")
   results = exa.search_and_contents("This is a Exa query:")
 
   # search and get contents with contents options
-  results = exa.search_and_contents("This is a Exa query:", 
+  results = exa.search_and_contents("This is a Exa query:",
                                     text={"include_html_tags": True, "max_characters": 1000})
-                                    
+
   # find similar documents
   results = exa.find_similar("https://example.com")
 
@@ -75,7 +57,7 @@ exa = Exa(api_key="your-api-key")
   results = exa.get_contents(["tesla.com"])
 
   # get contents with contents options
-  results = exa.get_contents(["urls"], 
+  results = exa.get_contents(["urls"],
                              text={"include_html_tags": True, "max_characters": 1000})
 
   # basic answer
@@ -91,5 +73,37 @@ exa = Exa(api_key="your-api-key")
   for chunk in response:
     print(chunk, end='', flush=True)
 
+  # research task example – answer a question with citations
+  # Example prompt & schema inspired by the TypeScript example.
+  QUESTION = (
+      "Summarize the history of San Francisco highlighting one or two major events "
+      "for each decade from 1850 to 1950"
+  )
+  OUTPUT_SCHEMA: Dict[str, Any] = {
+      "type": "object",
+      "required": ["timeline"],
+      "properties": {
+          "timeline": {
+              "type": "array",
+              "items": {
+                  "type": "object",
+                  "required": ["decade", "notableEvents"],
+                  "properties": {
+                      "decade": {
+                          "type": "string",
+                          "description": 'Decade label e.g. "1850s"',
+                      },
+                      "notableEvents": {
+                          "type": "string",
+                          "description": "A summary of notable events.",
+                      },
+                  },
+              },
+          },
+      },
+  }
+  resp = exa.research.create_task(
+      input_instructions=QUESTION,
+      output_schema=OUTPUT_SCHEMA,
+  )
 ```
-

{exa_py-1.13.0 → exa_py-1.13.2}/exa_py/api.py

@@ -38,6 +38,7 @@ from exa_py.utils import (
 )
 from .websets import WebsetsClient
 from .websets.core.base import ExaJSONEncoder
+from .research.client import ResearchClient, AsyncResearchClient
 
 is_beta = os.getenv("IS_BETA") == "True"
 
@@ -56,7 +57,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 +262,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 +290,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 +671,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 +767,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 +778,7 @@ class AsyncStreamAnswerResponse:
                 stream_chunk = StreamChunk(content=content, citations=citations)
                 if stream_chunk.has_data():
                     yield stream_chunk
+
         return generator()
 
     def close(self) -> None:
@@ -834,36 +837,6 @@ 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."""
@@ -872,7 +845,7 @@ class Exa:
         self,
         api_key: Optional[str],
         base_url: str = "https://api.exa.ai",
-        user_agent: str = "exa-py 1.12.1",
+        user_agent: str = "exa-py 1.12.4",
     ):
         """Initialize the Exa client with the provided API key and optional base URL and user agent.
 
@@ -889,10 +862,22 @@ 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)
+        # Research tasks client (new, mirrors Websets design)
+        self.research = ResearchClient(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:
@@ -915,13 +900,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
 
@@ -931,20 +916,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}")
 
@@ -1875,6 +1854,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(
@@ -1885,6 +1865,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.
 
@@ -1893,6 +1874,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.
@@ -1922,6 +1904,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.
 
@@ -1930,7 +1913,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]]).
@@ -1941,40 +1924,12 @@ 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)
+        # Override the synchronous ResearchClient with its async counterpart.
+        self.research = AsyncResearchClient(self)
         self._client = None
 
     @property
@@ -1982,9 +1937,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
 
@@ -2004,15 +1957,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}"
@@ -2250,6 +2202,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.
 
@@ -2258,6 +2211,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.
@@ -2287,6 +2241,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.
 
@@ -2295,7 +2250,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]]).
@@ -2305,36 +2260,3 @@ 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.13.2/exa_py/research/__init__.py

@@ -0,0 +1,9 @@
+from .client import ResearchClient, AsyncResearchClient
+from .models import ResearchTask
+
+__all__ = [
+    "ResearchClient",
+    "AsyncResearchClient",
+    "ResearchTaskId",
+    "ResearchTask",
+]