arex-python-sdk 0.2.1__py3-none-any.whl → 0.3.0__py3-none-any.whl

arex/_transport.py

@@ -38,14 +38,11 @@ def _prepare(
     base_url: str,
     api_key: str,
     path: str,
-    idempotency_key: str | None,
 ) -> tuple[str, dict[str, str]]:
     headers = {
         "Authorization": f"Bearer {api_key}",
         "Accept": "application/json",
     }
-    if idempotency_key is not None:
-        headers["Idempotency-Key"] = idempotency_key
     return base_url.rstrip("/") + path, headers
 
 
@@ -113,7 +110,7 @@ class _Base:
             return None
         if isinstance(error, RateLimitError):
             # `outstanding_run_limit` is a state, not a burst; retrying never helps.
-            if error.code not in {"rate_limit_exceeded", "idempotency_key_in_progress"}:
+            if error.code != "rate_limit_exceeded":
                 return None
         elif not self.retry_unavailable or error.code != "temporarily_unavailable":
             return None
@@ -178,9 +175,8 @@ class Transport(_Base):
         *,
         json: Any | None = None,
         timeout_ms: int,
-        idempotency_key: str | None = None,
     ) -> ApiResult:
-        url, headers = _prepare(self.base_url, self.api_key, path, idempotency_key)
+        url, headers = _prepare(self.base_url, self.api_key, path)
         deadline = time.monotonic() + timeout_ms / 1000
         attempt = 0
         while True:
@@ -245,9 +241,8 @@ class AsyncTransport(_Base):
         *,
         json: Any | None = None,
         timeout_ms: int,
-        idempotency_key: str | None = None,
     ) -> ApiResult:
-        url, headers = _prepare(self.base_url, self.api_key, path, idempotency_key)
+        url, headers = _prepare(self.base_url, self.api_key, path)
         deadline = time.monotonic() + timeout_ms / 1000
         work = asyncio.ensure_future(
             self._send(method, url, headers, json, timeout_ms, deadline)

arex/_validate.py

@@ -5,7 +5,6 @@ from __future__ import annotations
 import re
 from typing import Any, get_args
 from urllib.parse import urlsplit
-from uuid import uuid4
 
 from arex._wire import WIRE_LIMITS, BrowseTier, ResearchModeRequest
 from arex.errors import InvalidRequestError
@@ -13,7 +12,6 @@ from arex.errors import InvalidRequestError
 __all__ = [
     "MAX_TIMEOUT_MS",
     "is_timeout_ms",
-    "resolve_idempotency_key",
     "validate_browse",
     "validate_research_create",
     "validate_research_wait",
@@ -140,17 +138,3 @@ def validate_timeout_ms(value: object) -> None:
             f"timeout_ms must be a positive integer of at most {MAX_TIMEOUT_MS}.",
             param="timeout_ms",
         )
-
-
-def resolve_idempotency_key(key: str | None) -> str:
-    """The caller's key once validated, else a fresh UUID4 for this one call."""
-    if key is None:
-        return str(uuid4())
-    pattern = WIRE_LIMITS["IdempotencyKey"]["pattern"]
-    # `fullmatch` so the pattern's `$` cannot accept a trailing newline.
-    if not isinstance(key, str) or not re.fullmatch(pattern, key):
-        raise InvalidRequestError(
-            "idempotency_key must be 1 to 255 characters from A-Z a-z 0-9 . _ -",
-            param="idempotency_key",
-        )
-    return key

arex/_wire.py

@@ -6,7 +6,7 @@ from typing import TYPE_CHECKING, Any, Literal, TypedDict
 if TYPE_CHECKING:
     from typing_extensions import Required
 
-ErrorCode = Literal['invalid_request', 'content_blocked', 'unauthorized', 'registration_required', 'account_deletion_pending', 'feature_not_enabled', 'not_found', 'method_not_allowed', 'run_not_cancellable', 'idempotency_key_in_progress', 'source_not_available', 'idempotency_key_reused', 'rate_limit_exceeded', 'outstanding_run_limit', 'daily_credits_exhausted', 'weekly_credits_exhausted', 'internal_error', 'temporarily_unavailable']
+ErrorCode = Literal['browser_session_limit', 'browser_session_busy', 'browser_session_expired', 'browser_stale_observation', 'browser_action_id_reused', 'browser_action_limit', 'browser_url_blocked', 'browser_result_unknown', 'invalid_request', 'content_blocked', 'unauthorized', 'registration_required', 'account_deletion_pending', 'feature_not_enabled', 'not_found', 'method_not_allowed', 'run_not_cancellable', 'source_not_available', 'rate_limit_exceeded', 'outstanding_run_limit', 'daily_credits_exhausted', 'weekly_credits_exhausted', 'internal_error', 'temporarily_unavailable']
 ResearchFailureCode = Literal['timeout', 'execution_failed', 'worker_unavailable', 'interrupted']
 BrowseTier = Literal['auto', 'flex']
 ResearchMode = Literal['fast', 'deep']
@@ -19,6 +19,13 @@ class BrowseRequest(TypedDict, total=False):
     livecrawl: bool
     livecrawl_timeout_ms: int
     max_characters: int
+    highlights: bool
+
+class BrowseResponseHighlights(TypedDict, total=False):
+    applied: Required[bool]
+    cached: Required[bool]
+    kept_chunks: Required[int]
+    total_chunks: Required[int]
 
 class BrowseResponse(TypedDict, total=False):
     url: Required[str]
@@ -28,6 +35,7 @@ class BrowseResponse(TypedDict, total=False):
     image_urls: list[str]
     content: Required[str]
     truncated: Required[bool]
+    highlights: BrowseResponseHighlights
 
 class ErrorError(TypedDict, total=False):
     code: Required[ErrorCode]
@@ -99,7 +107,8 @@ class UsageResponse(TypedDict, total=False):
     week: UsageResponseWeek
 
 
-WIRE_LIMITS: dict[str, Any] = {'BrowseRequest': {'livecrawl': {'default': False},
+WIRE_LIMITS: dict[str, Any] = {'BrowseRequest': {'highlights': {'default': False},
+                   'livecrawl': {'default': False},
                    'livecrawl_timeout_ms': {'maximum': 90000, 'minimum': 1000},
                    'max_characters': {'default': 12000,
                                       'maximum': 131072,
@@ -108,7 +117,6 @@ WIRE_LIMITS: dict[str, Any] = {'BrowseRequest': {'livecrawl': {'default': False}
                    'url': {'maxLength': 8192,
                            'pattern': '^[Hh][Tt][Tt][Pp][Ss]?://[^/@?#]+(?:[/?#]|$)'}},
  'BrowseResponse': {'image_urls': {'maxItems': 50}},
- 'IdempotencyKey': {'pattern': '^[A-Za-z0-9._-]{1,255}$', 'type': 'string'},
  'ResearchCreateRequest': {'mode': {'default': 'auto',
                                     'enum': ['fast', 'deep', 'auto']},
                            'query': {'maxLength': 2000, 'minLength': 1}},

arex/async_client.py

@@ -8,7 +8,7 @@ from typing import Any
 import httpx
 
 from arex._transport import AsyncTransport
-from arex._validate import resolve_idempotency_key, validate_browse, validate_search
+from arex._validate import validate_browse, validate_search
 from arex.client import (
     browse_body,
     browse_timeout_ms,
@@ -58,12 +58,10 @@ class AsyncArex:
         query: str,
         *,
         limit: int | None = None,
-        idempotency_key: str | None = None,
         timeout_ms: int | None = None,
     ) -> SearchResponse:
         """Run a web search."""
         validate_search(query, limit)
-        key = resolve_idempotency_key(idempotency_key)
         body: dict[str, Any] = {"query": query}
         if limit is not None:
             body["limit"] = limit
@@ -71,7 +69,6 @@ class AsyncArex:
             "POST",
             "/v1/search",
             json=body,
-            idempotency_key=key,
             timeout_ms=self._transport.resolve_timeout(SEARCH_TIMEOUT_MS, timeout_ms),
         )
         return SearchResponse.from_wire(result.data, require_credits(result.credits))
@@ -84,7 +81,6 @@ class AsyncArex:
         livecrawl: bool | None = None,
         livecrawl_timeout_ms: int | None = None,
         max_characters: int | None = None,
-        idempotency_key: str | None = None,
         timeout_ms: int | None = None,
     ) -> BrowseDocument:
         """Fetch and extract one page."""
@@ -95,12 +91,10 @@ class AsyncArex:
             livecrawl_timeout_ms=livecrawl_timeout_ms,
             max_characters=max_characters,
         )
-        key = resolve_idempotency_key(idempotency_key)
         default_ms = browse_timeout_ms(tier, livecrawl, livecrawl_timeout_ms)
         result = await self._transport.request(
             "POST",
             "/v1/browse",
-            idempotency_key=key,
             json=browse_body(
                 url, tier, livecrawl, livecrawl_timeout_ms, max_characters
             ),

arex/client.py

@@ -9,7 +9,7 @@ from typing import Any
 import httpx
 
 from arex._transport import Transport
-from arex._validate import resolve_idempotency_key, validate_browse, validate_search
+from arex._validate import validate_browse, validate_search
 from arex.errors import ArexNetworkError
 from arex.models import (
     BROWSE_AUTO_TIMEOUT_MS,
@@ -122,12 +122,10 @@ class Arex:
         query: str,
         *,
         limit: int | None = None,
-        idempotency_key: str | None = None,
         timeout_ms: int | None = None,
     ) -> SearchResponse:
         """Run a web search."""
         validate_search(query, limit)
-        key = resolve_idempotency_key(idempotency_key)
         body: dict[str, Any] = {"query": query}
         if limit is not None:
             body["limit"] = limit
@@ -135,7 +133,6 @@ class Arex:
             "POST",
             "/v1/search",
             json=body,
-            idempotency_key=key,
             timeout_ms=self._transport.resolve_timeout(SEARCH_TIMEOUT_MS, timeout_ms),
         )
         return SearchResponse.from_wire(result.data, require_credits(result.credits))
@@ -148,7 +145,6 @@ class Arex:
         livecrawl: bool | None = None,
         livecrawl_timeout_ms: int | None = None,
         max_characters: int | None = None,
-        idempotency_key: str | None = None,
         timeout_ms: int | None = None,
     ) -> BrowseDocument:
         """Fetch and extract one page."""
@@ -159,12 +155,10 @@ class Arex:
             livecrawl_timeout_ms=livecrawl_timeout_ms,
             max_characters=max_characters,
         )
-        key = resolve_idempotency_key(idempotency_key)
         default_ms = browse_timeout_ms(tier, livecrawl, livecrawl_timeout_ms)
         result = self._transport.request(
             "POST",
             "/v1/browse",
-            idempotency_key=key,
             json=browse_body(
                 url, tier, livecrawl, livecrawl_timeout_ms, max_characters
             ),

arex/errors.py

@@ -78,7 +78,7 @@ class PermissionDeniedError(ArexApiError):
 
 
 class InvalidRequestError(ArexApiError):
-    """Invalid request, blocked content, reused key, or client-side validation."""
+    """Invalid request, blocked content, or client-side validation."""
 
     def __init__(
         self,
@@ -113,7 +113,7 @@ class NotFoundError(ArexApiError):
 
 
 class RateLimitError(ArexApiError):
-    """Rate limits, outstanding runs, or an idempotent request still in progress."""
+    """Rate limits or outstanding runs."""
 
 
 class CreditsExhaustedError(ArexApiError):
@@ -210,11 +210,9 @@ class ResearchRunCancelledError(ArexError):
 _ERROR_CLASSES: dict[str, type[ArexApiError]] = {
     "invalid_request": InvalidRequestError,
     "content_blocked": InvalidRequestError,
-    "idempotency_key_reused": InvalidRequestError,
     "source_not_available": SourceNotAvailableError,
     "not_found": NotFoundError,
     "rate_limit_exceeded": RateLimitError,
-    "idempotency_key_in_progress": RateLimitError,
     "outstanding_run_limit": RateLimitError,
     "temporarily_unavailable": ServiceUnavailableError,
     "internal_error": ServiceUnavailableError,

arex/research.py

@@ -9,7 +9,6 @@ from dataclasses import replace
 from arex._poll import async_poll_until, poll_until
 from arex._transport import AsyncTransport, Transport
 from arex._validate import (
-    resolve_idempotency_key,
     validate_research_create,
     validate_research_wait,
     validate_run_id,
@@ -72,17 +71,14 @@ class Research:
         query: str,
         *,
         mode: ResearchModeRequest | None = None,
-        idempotency_key: str | None = None,
         timeout_ms: int | None = None,
     ) -> ResearchRun:
         """Start a research run. The returned run carries the credit counters."""
         validate_research_create(query, mode)
-        key = resolve_idempotency_key(idempotency_key)
         result = self._transport.request(
             "POST",
             "/v1/research",
             json=_create_body(query, mode),
-            idempotency_key=key,
             timeout_ms=self._timeout(timeout_ms),
         )
         return ResearchRun.from_wire(result.data, result.credits)
@@ -138,13 +134,12 @@ class Research:
         *,
         mode: ResearchModeRequest | None = None,
         poll_interval_ms: int = DEFAULT_POLL_INTERVAL_MS,
-        idempotency_key: str | None = None,
         timeout_ms: int | None = None,
     ) -> ResearchRun:
         """Create a run and poll until it completes. Errors raised after the
         create name the run in `run_id`."""
         validate_research_wait(poll_interval_ms, timeout_ms)
-        created = self.create(query, mode=mode, idempotency_key=idempotency_key)
+        created = self.create(query, mode=mode)
         return self._await_completion(
             created.id,
             created,
@@ -223,17 +218,14 @@ class AsyncResearch:
         query: str,
         *,
         mode: ResearchModeRequest | None = None,
-        idempotency_key: str | None = None,
         timeout_ms: int | None = None,
     ) -> ResearchRun:
         """Start a research run. The returned run carries the credit counters."""
         validate_research_create(query, mode)
-        key = resolve_idempotency_key(idempotency_key)
         result = await self._transport.request(
             "POST",
             "/v1/research",
             json=_create_body(query, mode),
-            idempotency_key=key,
             timeout_ms=self._timeout(timeout_ms),
         )
         return ResearchRun.from_wire(result.data, result.credits)
@@ -292,13 +284,12 @@ class AsyncResearch:
         *,
         mode: ResearchModeRequest | None = None,
         poll_interval_ms: int = DEFAULT_POLL_INTERVAL_MS,
-        idempotency_key: str | None = None,
         timeout_ms: int | None = None,
     ) -> ResearchRun:
         """Create a run and poll until it completes. Errors raised after the
         create name the run in `run_id`."""
         validate_research_wait(poll_interval_ms, timeout_ms)
-        created = await self.create(query, mode=mode, idempotency_key=idempotency_key)
+        created = await self.create(query, mode=mode)
         return await self._await_completion(
             created.id,
             created,

{arex_python_sdk-0.2.1.dist-info → arex_python_sdk-0.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: arex-python-sdk
-Version: 0.2.1
+Version: 0.3.0
 Summary: Python SDK for the AREX public APIs.
 Project-URL: Homepage, https://github.com/AREX-Research/arex-sdk
 Project-URL: Repository, https://github.com/AREX-Research/arex-sdk
@@ -26,10 +26,14 @@ Description-Content-Type: text/markdown
 
 Python client for the AREX public API, synchronous and asynchronous. Python >= 3.10; the only dependency is `httpx`.
 
+Install from PyPI:
+
 ```bash
 pip install arex-python-sdk
 ```
 
+Or download the `.whl` from [GitHub Releases](https://github.com/AREX-Research/arex-sdk/releases/latest) and run `pip install ./arex_python_sdk-*.whl`.
+
 ```python
 from arex import Arex
 
@@ -44,12 +48,12 @@ with Arex() as arex:  # reads AREX_API_KEY
 
 `AsyncArex` mirrors every call as a coroutine under `async with`.
 
-The SDK follows the checked-in v1 OpenAPI contract. Charged calls reuse an idempotency key across automatic retries. Supply `idempotency_key` when you need to retry the same operation across calls or process restarts. Keep API keys server-side.
+The SDK follows the checked-in v1 OpenAPI contract. Keep API keys server-side.
 
-Search, browse and research creation consume credits; consult your AREX account for current pricing. Usage checks, polling and other research lifecycle calls are free.
+Search, browse and research creation consume credits; consult your AREX account for current pricing. Usage checks, polling and other research lifecycle calls are free. Retries are new charged requests; failures are refunded and cancellations are charged.
 
 - [API reference](https://github.com/AREX-Research/arex-sdk/blob/main/python/docs/api.md): options, models, errors, exports.
-- [Behavior](https://github.com/AREX-Research/arex-sdk/blob/main/python/docs/behavior.md): credits, deadlines, retries, idempotency, polling, and recovery.
+- [Behavior](https://github.com/AREX-Research/arex-sdk/blob/main/python/docs/behavior.md): credits, deadlines, retries, polling, and recovery.
 - [Examples](https://github.com/AREX-Research/arex-sdk/tree/main/python/examples): runnable scripts.
 
 [Apache License 2.0](https://github.com/AREX-Research/arex-sdk/blob/main/LICENSE).

arex_python_sdk-0.3.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+arex/__init__.py,sha256=a2kMXiAuVzTOyHfQDriVZnf7gLtZiFYFcLaGxDKgk7I,3427
+arex/_poll.py,sha256=YvtqfwaNgP2caaQ9XwxA7zA--qGvZBcM33ZwhYh0zh8,3927
+arex/_transport.py,sha256=0esQx-Mn-zZVzmkV5ZHa2Aj4u2fPuQCGGAXq2_vqM-Q,9823
+arex/_validate.py,sha256=CBZhIIae37mxYSDE0K_wIwc3l8_-3-wxzXDvQ6UZJRc,5164
+arex/_wire.py,sha256=QZsa9jE-fPRHUxLJpjGtvqNKBRaTBt1zhuLyRNgP4b4,4996
+arex/async_client.py,sha256=Q9YLKpIsoMV58G5l6Iz13to8tJPNq5lzzjhDXe-iQEE,3794
+arex/client.py,sha256=vtuIaMDNV3eYWlBMn9bonHuQ3PRLAFNT7cZpVr4kiU4,5722
+arex/errors.py,sha256=x54kfbrYnhoJYNWaURUa2coOuYWBLhrBDRC-6wVtW-0,9976
+arex/models.py,sha256=9q5vL9_KlR0IHEr98Xg23GwrPCipsbnnIQlbBsiFhy0,11998
+arex/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+arex/research.py,sha256=p5WmS1IfdWvXs6C8cwPVUB4StXvr5CtZVRXJC8APCms,12164
+arex_python_sdk-0.3.0.dist-info/METADATA,sha256=hFHteeh8iS5F3BST5pBaWHy7_38KViaYlZ3xvot3v2E,2588
+arex_python_sdk-0.3.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+arex_python_sdk-0.3.0.dist-info/licenses/LICENSE,sha256=2cJfL27uSPe4DpI1sd6sctsmMLW9_PV-KKhUYkHKQyo,11354
+arex_python_sdk-0.3.0.dist-info/RECORD,,

arex_python_sdk-0.2.1.dist-info/RECORD

@@ -1,15 +0,0 @@
-arex/__init__.py,sha256=a2kMXiAuVzTOyHfQDriVZnf7gLtZiFYFcLaGxDKgk7I,3427
-arex/_poll.py,sha256=YvtqfwaNgP2caaQ9XwxA7zA--qGvZBcM33ZwhYh0zh8,3927
-arex/_transport.py,sha256=-UgC6UT0O30p44IV78ChXB-kbGmNaQT2tSuc3ETidLk,10104
-arex/_validate.py,sha256=jm9zX4SI7PCqTLMvJWOzbWyoW2KuYuqoOhGO8FZs970,5776
-arex/_wire.py,sha256=wn-L9oYaS1ftzm06fpZAT2ZYrv6EOgo762-ckCWB9-o,4634
-arex/async_client.py,sha256=Sn-P8wpyvV-cDqOixEeru8pOxjROCjraTmthKPf9PaQ,4083
-arex/client.py,sha256=ehYbPTxvMLtxkX3BpIRyTZZeb2bd--dIEoPnnN0_jM8,6011
-arex/errors.py,sha256=bxYqfZeFzKb8Qq5_W8tCYkyVrTdVy8Z8uznXiy0SwCI,10132
-arex/models.py,sha256=9q5vL9_KlR0IHEr98Xg23GwrPCipsbnnIQlbBsiFhy0,11998
-arex/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-arex/research.py,sha256=jBa2nmfnBS8TICSXHqYLaAoDZ3oVx5moEJ2J3IvBxRI,12611
-arex_python_sdk-0.2.1.dist-info/METADATA,sha256=O8hCp_zwVz9GlO74GiSobp_Q2cOHm-uEPvlL0H5qXio,2507
-arex_python_sdk-0.2.1.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
-arex_python_sdk-0.2.1.dist-info/licenses/LICENSE,sha256=2cJfL27uSPe4DpI1sd6sctsmMLW9_PV-KKhUYkHKQyo,11354
-arex_python_sdk-0.2.1.dist-info/RECORD,,