exa-py 1.14.3__tar.gz → 1.14.5__tar.gz

{exa_py-1.14.3 → exa_py-1.14.5}/PKG-INFO

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

{exa_py-1.14.3 → exa_py-1.14.5}/exa_py/api.py

@@ -166,6 +166,7 @@ CONTENTS_OPTIONS_TYPES = {
     "text": [dict, bool],
     "highlights": [dict, bool],
     "summary": [dict, bool],
+    "context": [dict, bool],
     "metadata": [dict, bool],
     "livecrawl_timeout": [int],
     "livecrawl": [LIVECRAWL_OPTIONS],
@@ -292,6 +293,16 @@ class SummaryContentsOptions(TypedDict, total=False):
     schema: JSONSchema
 
 
+class ContextContentsOptions(TypedDict, total=False):
+    """Options for retrieving aggregated context from a set of search results.
+
+    Attributes:
+        max_characters (int): The maximum number of characters to include in the context string.
+    """
+
+    max_characters: int
+
+
 class ExtrasOptions(TypedDict, total=False):
     """A class representing additional extraction fields (e.g. links, images)"""
 
@@ -788,6 +799,15 @@ class AsyncStreamAnswerResponse:
 
 T = TypeVar("T")
 
+@dataclass
+class ContentStatus:
+    """A class representing the status of a content retrieval operation."""
+
+    id: str
+    status: str
+    source: str
+
+
 
 @dataclass
 class SearchResponse(Generic[T]):
@@ -798,16 +818,23 @@ class SearchResponse(Generic[T]):
         autoprompt_string (str, optional): The Exa query created by autoprompt.
         resolved_search_type (str, optional): 'neural' or 'keyword' if auto.
         auto_date (str, optional): A date for filtering if autoprompt found one.
+        context (str, optional): Combined context string when requested via contents.context.
+        statuses (List[ContentStatus], optional): Status list from get_contents.
+        cost_dollars (CostDollars, optional): Cost breakdown.
     """
 
     results: List[T]
     autoprompt_string: Optional[str]
     resolved_search_type: Optional[str]
     auto_date: Optional[str]
+    context: Optional[str] = None
+    statuses: Optional[List[ContentStatus]] = None
     cost_dollars: Optional[CostDollars] = None
 
     def __str__(self):
         output = "\n\n".join(str(result) for result in self.results)
+        if self.context:
+            output += f"\nContext: {self.context}"
         if self.autoprompt_string:
             output += f"\n\nAutoprompt String: {self.autoprompt_string}"
         if self.resolved_search_type:
@@ -818,6 +845,8 @@ class SearchResponse(Generic[T]):
                 output += f"\n  - search: {self.cost_dollars.search}"
             if self.cost_dollars.contents:
                 output += f"\n  - contents: {self.cost_dollars.contents}"
+        if self.statuses:
+            output += f"\nStatuses: {self.statuses}"
         return output
 
 
@@ -1242,6 +1271,7 @@ class Exa:
                 "text",
                 "highlights",
                 "summary",
+                "context",
                 "subpages",
                 "subpage_target",
                 "livecrawl",
@@ -1258,6 +1288,7 @@ class Exa:
             data["autopromptString"] if "autopromptString" in data else None,
             data["resolvedSearchType"] if "resolvedSearchType" in data else None,
             data["autoDate"] if "autoDate" in data else None,
+            context=data.get("context"),
             cost_dollars=cost_dollars,
         )
 
@@ -1405,12 +1436,15 @@ class Exa:
         options = to_camel_case(options)
         data = self.request("/contents", options)
         cost_dollars = parse_cost_dollars(data.get("costDollars"))
+        statuses = [ContentStatus(**status) for status in data.get("statuses", [])]
         return SearchResponse(
             [Result(**to_snake_case(result)) for result in data["results"]],
             data.get("autopromptString"),
             data.get("resolvedSearchType"),
             data.get("autoDate"),
+            context=data.get("context"),
             cost_dollars=cost_dollars,
+            statuses=statuses,
         )
 
     def find_similar(
@@ -1700,6 +1734,7 @@ class Exa:
                 "text",
                 "highlights",
                 "summary",
+                "context",
                 "subpages",
                 "subpage_target",
                 "livecrawl",
@@ -1716,6 +1751,7 @@ class Exa:
             data.get("autopromptString"),
             data.get("resolvedSearchType"),
             data.get("autoDate"),
+            context=data.get("context"),
             cost_dollars=cost_dollars,
         )
 
@@ -2052,6 +2088,7 @@ class AsyncExa(Exa):
                 "text",
                 "highlights",
                 "summary",
+                "context",
                 "subpages",
                 "subpage_target",
                 "livecrawl",
@@ -2068,6 +2105,7 @@ class AsyncExa(Exa):
             data["autopromptString"] if "autopromptString" in data else None,
             data["resolvedSearchType"] if "resolvedSearchType" in data else None,
             data["autoDate"] if "autoDate" in data else None,
+            context=data.get("context"),
             cost_dollars=cost_dollars,
         )
 
@@ -2092,12 +2130,15 @@ class AsyncExa(Exa):
         options = to_camel_case(options)
         data = await self.async_request("/contents", options)
         cost_dollars = parse_cost_dollars(data.get("costDollars"))
+        statuses = [ContentStatus(**status) for status in data.get("statuses", [])]
         return SearchResponse(
             [Result(**to_snake_case(result)) for result in data["results"]],
             data.get("autopromptString"),
             data.get("resolvedSearchType"),
             data.get("autoDate"),
+            context=data.get("context"),
             cost_dollars=cost_dollars,
+            statuses=statuses,
         )
 
     async def find_similar(
@@ -2175,6 +2216,7 @@ class AsyncExa(Exa):
                 "text",
                 "highlights",
                 "summary",
+                "context",
                 "subpages",
                 "subpage_target",
                 "livecrawl",
@@ -2191,6 +2233,7 @@ class AsyncExa(Exa):
             data.get("autopromptString"),
             data.get("resolvedSearchType"),
             data.get("autoDate"),
+            context=data.get("context"),
             cost_dollars=cost_dollars,
         )
 

{exa_py-1.14.3 → exa_py-1.14.5}/exa_py.egg-info/PKG-INFO

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

{exa_py-1.14.3 → exa_py-1.14.5}/exa_py.egg-info/SOURCES.txt

@@ -31,4 +31,5 @@ exa_py/websets/searches/client.py
 exa_py/websets/webhooks/__init__.py
 exa_py/websets/webhooks/client.py
 tests/test_monitors.py
+tests/test_search_api.py
 tests/test_websets.py

{exa_py-1.14.3 → exa_py-1.14.5}/pyproject.toml

@@ -1,10 +1,3 @@
-[tool.poetry]
-name = "exa-py"
-version = "1.14.2"
-description = "Python SDK for Exa API."
-authors = ["Exa AI <hello@exa.ai>"]
-readme = "README.md"
-
 [tool.poetry.dependencies]
 python = "^3.9"
 requests = "^2.32.3"
@@ -32,7 +25,7 @@ in-project = true
 
 [project]
 name = "exa-py"
-version = "1.14.3"
+version = "1.14.5"
 description = "Python SDK for Exa API."
 readme = "README.md"
 requires-python = ">=3.9"

{exa_py-1.14.3 → exa_py-1.14.5}/setup.py

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

exa_py-1.14.5/tests/test_search_api.py

@@ -0,0 +1,136 @@
+import os
+from unittest.mock import AsyncMock, patch
+
+import httpx
+import pytest
+
+from exa_py import Exa, AsyncExa, api as exa_api
+
+API_KEY = os.getenv("EXA_API_KEY", "test-key")
+
+
+def _have_real_key() -> bool:
+    return API_KEY != "test-key" and len(API_KEY) > 10
+
+########################################
+# Offline unit tests (no network)
+########################################
+
+def test_contentstatus_parsing_offline():
+    payload_status = {"id": "u", "status": "success", "source": "cached"}
+    cs = exa_api.ContentStatus(**payload_status)
+    assert cs.id == "u" and cs.status == "success" and cs.source == "cached"
+
+
+def test_answerresponse_accepts_dict():
+    dummy = exa_api.AnswerResult(id="1", url="u", title="t")
+    resp = exa_api.AnswerResponse(answer={"foo": "bar"}, citations=[dummy])
+    assert isinstance(resp.answer, dict) and resp.answer["foo"] == "bar"
+
+
+@pytest.mark.asyncio
+async def test_async_request_accepts_201():
+    ax = AsyncExa(API_KEY)
+
+    async def _fake_post(url, json, headers):
+        return httpx.Response(201, json={"ok": True})
+
+    with patch.object(ax.client, "post", new=AsyncMock(side_effect=_fake_post)):
+        data = await ax.async_request("/dummy", {})
+    assert data == {"ok": True}
+
+
+########################################
+# Live integration tests (skipped without key)
+########################################
+
+@pytest.mark.skipif(not _have_real_key(), reason="EXA_API_KEY not provided")
+def test_user_agent_header():
+    exa = Exa(API_KEY)
+    assert exa.headers["User-Agent"] == "exa-py 1.12.4"
+
+
+@pytest.mark.skipif(not _have_real_key(), reason="EXA_API_KEY not provided")
+def test_research_client_attrs():
+    exa = Exa(API_KEY)
+    aexa = AsyncExa(API_KEY)
+    assert hasattr(exa, "research") and hasattr(aexa, "research")
+
+
+# ---- Core live endpoint smoke checks ----
+
+@pytest.mark.skipif(not _have_real_key(), reason="EXA_API_KEY not provided")
+def test_get_contents_live_preferred():
+    exa = Exa(API_KEY)
+    resp = exa.get_contents(urls=["https://techcrunch.com"], text=True, livecrawl="preferred")
+    assert isinstance(resp, exa_api.SearchResponse)
+    # statuses may be empty when cached – still fine
+    assert len(resp.results) >= 1
+
+
+@pytest.mark.skipif(not _have_real_key(), reason="EXA_API_KEY not provided")
+def test_search_and_contents_live():
+    exa = Exa(API_KEY)
+    resp = exa.search_and_contents("openai", num_results=1, text=True)
+    assert resp.results and resp.results[0].text
+
+
+@pytest.mark.skipif(not _have_real_key(), reason="EXA_API_KEY not provided")
+def test_find_similar_live():
+    exa = Exa(API_KEY)
+    resp = exa.find_similar("https://www.openai.com", num_results=1)
+    assert resp.results
+
+
+@pytest.mark.skipif(not _have_real_key(), reason="EXA_API_KEY not provided")
+def test_get_contents_sync_live():
+    exa = Exa(API_KEY)
+    resp = exa.get_contents(urls=["https://example.com"], text=True, livecrawl="never")
+    assert resp.results
+
+
+@pytest.mark.asyncio
+@pytest.mark.skipif(not _have_real_key(), reason="EXA_API_KEY not provided")
+async def test_get_contents_async_live():
+    ax = AsyncExa(API_KEY)
+    resp = await ax.get_contents(urls=["https://example.com"], text=True, livecrawl="never")
+    assert resp.results
+
+
+# researchTask endpoint is still beta; mark as xfail if 404 returned
+@pytest.mark.skipif(not _have_real_key(), reason="EXA_API_KEY not provided")
+@pytest.mark.xfail(strict=False)
+def test_research_task_live():
+    exa = Exa(API_KEY)
+    schema = {"type": "object", "properties": {"answer": {"type": "string"}}, "required": ["answer"]}
+    resp = exa.researchTask(input_instructions="Return the string 'pong'", output_schema=schema)
+    assert resp.id
+
+########################################
+# Live tests for new context / statuses features
+########################################
+
+@pytest.mark.skipif(not _have_real_key(), reason="EXA_API_KEY not provided")
+def test_search_and_contents_context_live():
+    """search_and_contents with context=True should return non-empty context string."""
+    exa = Exa(API_KEY)
+    resp = exa.search_and_contents("openai research", num_results=3, context=True, text=False)
+    assert resp.context is not None and isinstance(resp.context, str) and len(resp.context) > 0
+
+
+@pytest.mark.skipif(not _have_real_key(), reason="EXA_API_KEY not provided")
+def test_find_similar_and_contents_context_live():
+    """find_similar_and_contents with context flag should include context string."""
+    exa = Exa(API_KEY)
+    resp = exa.find_similar_and_contents("https://www.openai.com", num_results=3, context=True, text=False)
+    # context may be empty depending on backend, but attribute should exist (None or str)
+    assert hasattr(resp, "context")
+
+
+@pytest.mark.skipif(not _have_real_key(), reason="EXA_API_KEY not provided")
+def test_get_contents_statuses_live():
+    """get_contents should expose statuses list (possibly empty)."""
+    exa = Exa(API_KEY)
+    resp = exa.get_contents(urls=["https://techcrunch.com"], text=True, livecrawl="never")
+    # statuses attribute exists; ensure it's a list
+    assert isinstance(resp.statuses, list)