exa-py 1.14.7__tar.gz → 1.14.9__tar.gz

{exa_py-1.14.7 → exa_py-1.14.9}/PKG-INFO

@@ -1,24 +1,20 @@
-Metadata-Version: 2.3
+Metadata-Version: 2.4
 Name: exa-py
-Version: 1.14.7
+Version: 1.14.9
 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: 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: httpx>=0.28.1
+Dynamic: author
+Dynamic: home-page
 
 # Exa
 
@@ -130,4 +126,3 @@ exa = Exa(api_key="your-api-key")
       output_schema=OUTPUT_SCHEMA,
   )
 ```
-

{exa_py-1.14.7 → exa_py-1.14.9}/exa_py/api.py

@@ -134,7 +134,7 @@ SEARCH_OPTIONS_TYPES = {
         list
     ],  # Must not be present in webpage text. (One string, up to 5 words)
     "use_autoprompt": [bool],  # Convert query to Exa. (Default: false)
-    "type": [str],  # 'keyword', 'neural', or 'auto' (Default: auto)
+    "type": [str],  # 'keyword', 'neural', 'hybrid', or 'auto' (Default: auto)
     "category": [
         str
     ],  # A data category to focus on: 'company', 'research paper', 'news', 'pdf', 'github', 'tweet', 'personal site', 'linkedin profile', 'financial report'
@@ -874,7 +874,7 @@ class Exa:
         self,
         api_key: Optional[str],
         base_url: str = "https://api.exa.ai",
-        user_agent: str = "exa-py 1.12.4",
+        user_agent: str = "exa-py 1.14.9",
     ):
         """Initialize the Exa client with the provided API key and optional base URL and user agent.
 
@@ -995,7 +995,7 @@ class Exa:
             include_text (List[str], optional): Strings that must appear in the page text.
             exclude_text (List[str], optional): Strings that must not appear in the page text.
             use_autoprompt (bool, optional): Convert query to Exa (default False).
-            type (str, optional): 'keyword' or 'neural' (default 'neural').
+            type (str, optional): 'keyword', 'neural', or 'hybrid' (default 'neural').
             category (str, optional): e.g. 'company'
             flags (List[str], optional): Experimental flags for Exa usage.
             moderation (bool, optional): If True, the search results will be moderated for safety.
@@ -2040,7 +2040,7 @@ class AsyncExa(Exa):
             include_text (List[str], optional): Strings that must appear in the page text.
             exclude_text (List[str], optional): Strings that must not appear in the page text.
             use_autoprompt (bool, optional): Convert query to Exa (default False).
-            type (str, optional): 'keyword' or 'neural' (default 'neural').
+            type (str, optional): 'keyword', 'neural', or 'hybrid' (default 'neural').
             category (str, optional): e.g. 'company'
             flags (List[str], optional): Experimental flags for Exa usage.
             moderation (bool, optional): If True, the search results will be moderated for safety.

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

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: exa-py
+Version: 1.14.9
+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: httpx>=0.28.1
+Dynamic: author
+Dynamic: home-page
+
+# Exa
+
+Exa (formerly Metaphor) API in Python
+
+Note: This API is basically the same as `metaphor-python` but reflects new
+features associated with Metaphor's rename to Exa. New site is https://exa.ai
+
+## 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")
+```
+
+## Common requests
+
+```python
+
+  # basic search
+  results = exa.search("This is a Exa query:")
+
+  # keyword search (non-neural)
+  results = exa.search("Google-style query", type="keyword")
+
+  # search with date filters
+  results = exa.search("This is a Exa query:", start_published_date="2019-01-01", end_published_date="2019-01-31")
+
+  # search with domain filters
+  results = exa.search("This is a Exa query:", include_domains=["www.cnn.com", "www.nytimes.com"])
+
+  # search and get text contents
+  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:",
+                                    text={"include_html_tags": True, "max_characters": 1000})
+
+  # find similar documents
+  results = exa.find_similar("https://example.com")
+
+  # find similar excluding source domain
+  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)
+
+  # get text contents
+  results = exa.get_contents(["tesla.com"])
+
+  # get contents with contents options
+  results = exa.get_contents(["urls"],
+                             text={"include_html_tags": True, "max_characters": 1000})
+
+  # basic answer
+  response = exa.answer("This is a query to answer a question")
+
+  # answer with full text, using the exa-pro model (sends 2 expanded quries to exa search)
+  response = exa.answer("This is a query to answer a question", text=True, model="exa-pro")
+
+  # answer with streaming
+  response = exa.stream_answer("This is a query to answer:")
+
+  # Print each chunk as it arrives when using the stream_answer method
+  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(
+      instructions=QUESTION,
+      model="exa-research",
+      output_schema=OUTPUT_SCHEMA,
+  )
+```

exa_py-1.14.9/exa_py.egg-info/SOURCES.txt

@@ -0,0 +1,38 @@
+README.md
+pyproject.toml
+setup.py
+exa_py/__init__.py
+exa_py/api.py
+exa_py/py.typed
+exa_py/utils.py
+exa_py.egg-info/PKG-INFO
+exa_py.egg-info/SOURCES.txt
+exa_py.egg-info/dependency_links.txt
+exa_py.egg-info/requires.txt
+exa_py.egg-info/top_level.txt
+exa_py/research/__init__.py
+exa_py/research/client.py
+exa_py/research/models.py
+exa_py/websets/__init__.py
+exa_py/websets/client.py
+exa_py/websets/types.py
+exa_py/websets/core/__init__.py
+exa_py/websets/core/base.py
+exa_py/websets/enrichments/__init__.py
+exa_py/websets/enrichments/client.py
+exa_py/websets/imports/__init__.py
+exa_py/websets/imports/client.py
+exa_py/websets/items/__init__.py
+exa_py/websets/items/client.py
+exa_py/websets/monitors/__init__.py
+exa_py/websets/monitors/client.py
+exa_py/websets/monitors/runs/__init__.py
+exa_py/websets/monitors/runs/client.py
+exa_py/websets/searches/__init__.py
+exa_py/websets/searches/client.py
+exa_py/websets/webhooks/__init__.py
+exa_py/websets/webhooks/client.py
+tests/test_search_api.py
+tests/test_websets.py
+tests/test_websets_imports.py
+tests/test_websets_monitors.py

exa_py-1.14.9/exa_py.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

exa_py-1.14.9/exa_py.egg-info/requires.txt

@@ -0,0 +1,5 @@
+requests>=2.32.3
+typing-extensions>=4.12.2
+openai>=1.48
+pydantic>=2.10.6
+httpx>=0.28.1

exa_py-1.14.9/exa_py.egg-info/top_level.txt

@@ -0,0 +1 @@
+exa_py

{exa_py-1.14.7 → exa_py-1.14.9}/pyproject.toml

@@ -25,7 +25,7 @@ in-project = true
 
 [project]
 name = "exa-py"
-version = "1.14.7"
+version = "1.14.9"
 description = "Python SDK for Exa API."
 readme = "README.md"
 requires-python = ">=3.9"

exa_py-1.14.9/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

exa_py-1.14.9/setup.py

@@ -0,0 +1,26 @@
+from setuptools import find_packages, setup
+
+setup(
+    name="exa_py",
+    version="1.14.9",
+    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"]},
+    url="https://github.com/exa-labs/exa-py",
+    packages=find_packages(),
+    install_requires=["requests", "typing-extensions", "openai>=1.10.0"],
+    classifiers=[
+        "Development Status :: 5 - Production/Stable",
+        "Intended Audience :: Developers",
+        "License :: OSI Approved :: MIT License",
+        "Typing :: Typed",
+        "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.14.9/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)