sarvamai 0.1.22a4__py3-none-any.whl → 0.1.23a1__py3-none-any.whl

sarvamai/core/http_client.py

@@ -5,7 +5,6 @@ import email.utils
 import re
 import time
 import typing
-import urllib.parse
 from contextlib import asynccontextmanager, contextmanager
 from random import random
 
@@ -14,13 +13,13 @@ from .file import File, convert_file_dict_to_httpx_tuples
 from .force_multipart import FORCE_MULTIPART
 from .jsonable_encoder import jsonable_encoder
 from .query_encoder import encode_query
-from .remove_none_from_dict import remove_none_from_dict
+from .remove_none_from_dict import remove_none_from_dict as remove_none_from_dict
 from .request_options import RequestOptions
 from httpx._types import RequestFiles
 
-INITIAL_RETRY_DELAY_SECONDS = 0.5
-MAX_RETRY_DELAY_SECONDS = 10
-MAX_RETRY_DELAY_SECONDS_FROM_HEADER = 30
+INITIAL_RETRY_DELAY_SECONDS = 1.0
+MAX_RETRY_DELAY_SECONDS = 60.0
+JITTER_FACTOR = 0.2  # 20% random jitter
 
 
 def _parse_retry_after(response_headers: httpx.Headers) -> typing.Optional[float]:
@@ -64,6 +63,38 @@ def _parse_retry_after(response_headers: httpx.Headers) -> typing.Optional[float
     return seconds
 
 
+def _add_positive_jitter(delay: float) -> float:
+    """Add positive jitter (0-20%) to prevent thundering herd."""
+    jitter_multiplier = 1 + random() * JITTER_FACTOR
+    return delay * jitter_multiplier
+
+
+def _add_symmetric_jitter(delay: float) -> float:
+    """Add symmetric jitter (±10%) for exponential backoff."""
+    jitter_multiplier = 1 + (random() - 0.5) * JITTER_FACTOR
+    return delay * jitter_multiplier
+
+
+def _parse_x_ratelimit_reset(response_headers: httpx.Headers) -> typing.Optional[float]:
+    """
+    Parse the X-RateLimit-Reset header (Unix timestamp in seconds).
+    Returns seconds to wait, or None if header is missing/invalid.
+    """
+    reset_time_str = response_headers.get("x-ratelimit-reset")
+    if reset_time_str is None:
+        return None
+
+    try:
+        reset_time = int(reset_time_str)
+        delay = reset_time - time.time()
+        if delay > 0:
+            return delay
+    except (ValueError, TypeError):
+        pass
+
+    return None
+
+
 def _retry_timeout(response: httpx.Response, retries: int) -> float:
     """
     Determine the amount of time to wait before retrying a request.
@@ -71,17 +102,19 @@ def _retry_timeout(response: httpx.Response, retries: int) -> float:
     with a jitter to determine the number of seconds to wait.
     """
 
-    # If the API asks us to wait a certain amount of time (and it's a reasonable amount), just do what it says.
+    # 1. Check Retry-After header first
     retry_after = _parse_retry_after(response.headers)
-    if retry_after is not None and retry_after <= MAX_RETRY_DELAY_SECONDS_FROM_HEADER:
-        return retry_after
+    if retry_after is not None and retry_after > 0:
+        return min(retry_after, MAX_RETRY_DELAY_SECONDS)
 
-    # Apply exponential backoff, capped at MAX_RETRY_DELAY_SECONDS.
-    retry_delay = min(INITIAL_RETRY_DELAY_SECONDS * pow(2.0, retries), MAX_RETRY_DELAY_SECONDS)
+    # 2. Check X-RateLimit-Reset header (with positive jitter)
+    ratelimit_reset = _parse_x_ratelimit_reset(response.headers)
+    if ratelimit_reset is not None:
+        return _add_positive_jitter(min(ratelimit_reset, MAX_RETRY_DELAY_SECONDS))
 
-    # Add a randomness / jitter to the retry delay to avoid overwhelming the server with retries.
-    timeout = retry_delay * (1 - 0.25 * random())
-    return timeout if timeout >= 0 else 0
+    # 3. Fall back to exponential backoff (with symmetric jitter)
+    backoff = min(INITIAL_RETRY_DELAY_SECONDS * pow(2.0, retries), MAX_RETRY_DELAY_SECONDS)
+    return _add_symmetric_jitter(backoff)
 
 
 def _should_retry(response: httpx.Response) -> bool:
@@ -89,6 +122,45 @@ def _should_retry(response: httpx.Response) -> bool:
     return response.status_code >= 500 or response.status_code in retryable_400s
 
 
+def _build_url(base_url: str, path: typing.Optional[str]) -> str:
+    """
+    Build a full URL by joining a base URL with a path.
+
+    This function correctly handles base URLs that contain path prefixes (e.g., tenant-based URLs)
+    by using string concatenation instead of urllib.parse.urljoin(), which would incorrectly
+    strip path components when the path starts with '/'.
+
+    Example:
+        >>> _build_url("https://cloud.example.com/org/tenant/api", "/users")
+        'https://cloud.example.com/org/tenant/api/users'
+
+    Args:
+        base_url: The base URL, which may contain path prefixes.
+        path: The path to append. Can be None or empty string.
+
+    Returns:
+        The full URL with base_url and path properly joined.
+    """
+    if not path:
+        return base_url
+    return f"{base_url.rstrip('/')}/{path.lstrip('/')}"
+
+
+def _maybe_filter_none_from_multipart_data(
+    data: typing.Optional[typing.Any],
+    request_files: typing.Optional[RequestFiles],
+    force_multipart: typing.Optional[bool],
+) -> typing.Optional[typing.Any]:
+    """
+    Filter None values from data body for multipart/form requests.
+    This prevents httpx from converting None to empty strings in multipart encoding.
+    Only applies when files are present or force_multipart is True.
+    """
+    if data is not None and isinstance(data, typing.Mapping) and (request_files or force_multipart):
+        return remove_none_from_dict(data)
+    return data
+
+
 def remove_omit_from_dict(
     original: typing.Dict[str, typing.Optional[typing.Any]],
     omit: typing.Optional[typing.Any],
@@ -143,8 +215,19 @@ def get_request_body(
         # If both data and json are None, we send json data in the event extra properties are specified
         json_body = maybe_filter_request_body(json, request_options, omit)
 
-    # If you have an empty JSON body, you should just send None
-    return (json_body if json_body != {} else None), data_body if data_body != {} else None
+    has_additional_body_parameters = bool(
+        request_options is not None and request_options.get("additional_body_parameters")
+    )
+
+    # Only collapse empty dict to None when the body was not explicitly provided
+    # and there are no additional body parameters. This preserves explicit empty
+    # bodies (e.g., when an endpoint has a request body type but all fields are optional).
+    if json_body == {} and json is None and not has_additional_body_parameters:
+        json_body = None
+    if data_body == {} and data is None and not has_additional_body_parameters:
+        data_body = None
+
+    return json_body, data_body
 
 
 class HttpClient:
@@ -188,7 +271,7 @@ class HttpClient:
         ] = None,
         headers: typing.Optional[typing.Dict[str, typing.Any]] = None,
         request_options: typing.Optional[RequestOptions] = None,
-        retries: int = 2,
+        retries: int = 0,
         omit: typing.Optional[typing.Any] = None,
         force_multipart: typing.Optional[bool] = None,
     ) -> httpx.Response:
@@ -210,9 +293,31 @@ class HttpClient:
         if (request_files is None or len(request_files) == 0) and force_multipart:
             request_files = FORCE_MULTIPART
 
+        data_body = _maybe_filter_none_from_multipart_data(data_body, request_files, force_multipart)
+
+        # Compute encoded params separately to avoid passing empty list to httpx
+        # (httpx strips existing query params from URL when params=[] is passed)
+        _encoded_params = encode_query(
+            jsonable_encoder(
+                remove_none_from_dict(
+                    remove_omit_from_dict(
+                        {
+                            **(params if params is not None else {}),
+                            **(
+                                request_options.get("additional_query_parameters", {}) or {}
+                                if request_options is not None
+                                else {}
+                            ),
+                        },
+                        omit,
+                    )
+                )
+            )
+        )
+
         response = self.httpx_client.request(
             method=method,
-            url=urllib.parse.urljoin(f"{base_url}/", path),
+            url=_build_url(base_url, path),
             headers=jsonable_encoder(
                 remove_none_from_dict(
                     {
@@ -222,23 +327,7 @@ class HttpClient:
                     }
                 )
             ),
-            params=encode_query(
-                jsonable_encoder(
-                    remove_none_from_dict(
-                        remove_omit_from_dict(
-                            {
-                                **(params if params is not None else {}),
-                                **(
-                                    request_options.get("additional_query_parameters", {}) or {}
-                                    if request_options is not None
-                                    else {}
-                                ),
-                            },
-                            omit,
-                        )
-                    )
-                )
-            ),
+            params=_encoded_params if _encoded_params else None,
             json=json_body,
             data=data_body,
             content=content,
@@ -246,9 +335,9 @@ class HttpClient:
             timeout=timeout,
         )
 
-        max_retries: int = request_options.get("max_retries", 0) if request_options is not None else 0
+        max_retries: int = request_options.get("max_retries", 2) if request_options is not None else 2
         if _should_retry(response=response):
-            if max_retries > retries:
+            if retries < max_retries:
                 time.sleep(_retry_timeout(response=response, retries=retries))
                 return self.request(
                     path=path,
@@ -285,7 +374,7 @@ class HttpClient:
         ] = None,
         headers: typing.Optional[typing.Dict[str, typing.Any]] = None,
         request_options: typing.Optional[RequestOptions] = None,
-        retries: int = 2,
+        retries: int = 0,
         omit: typing.Optional[typing.Any] = None,
         force_multipart: typing.Optional[bool] = None,
     ) -> typing.Iterator[httpx.Response]:
@@ -307,9 +396,31 @@ class HttpClient:
 
         json_body, data_body = get_request_body(json=json, data=data, request_options=request_options, omit=omit)
 
+        data_body = _maybe_filter_none_from_multipart_data(data_body, request_files, force_multipart)
+
+        # Compute encoded params separately to avoid passing empty list to httpx
+        # (httpx strips existing query params from URL when params=[] is passed)
+        _encoded_params = encode_query(
+            jsonable_encoder(
+                remove_none_from_dict(
+                    remove_omit_from_dict(
+                        {
+                            **(params if params is not None else {}),
+                            **(
+                                request_options.get("additional_query_parameters", {})
+                                if request_options is not None
+                                else {}
+                            ),
+                        },
+                        omit,
+                    )
+                )
+            )
+        )
+
         with self.httpx_client.stream(
             method=method,
-            url=urllib.parse.urljoin(f"{base_url}/", path),
+            url=_build_url(base_url, path),
             headers=jsonable_encoder(
                 remove_none_from_dict(
                     {
@@ -319,23 +430,7 @@ class HttpClient:
                     }
                 )
             ),
-            params=encode_query(
-                jsonable_encoder(
-                    remove_none_from_dict(
-                        remove_omit_from_dict(
-                            {
-                                **(params if params is not None else {}),
-                                **(
-                                    request_options.get("additional_query_parameters", {})
-                                    if request_options is not None
-                                    else {}
-                                ),
-                            },
-                            omit,
-                        )
-                    )
-                )
-            ),
+            params=_encoded_params if _encoded_params else None,
             json=json_body,
             data=data_body,
             content=content,
@@ -353,12 +448,19 @@ class AsyncHttpClient:
         base_timeout: typing.Callable[[], typing.Optional[float]],
         base_headers: typing.Callable[[], typing.Dict[str, str]],
         base_url: typing.Optional[typing.Callable[[], str]] = None,
+        async_base_headers: typing.Optional[typing.Callable[[], typing.Awaitable[typing.Dict[str, str]]]] = None,
     ):
         self.base_url = base_url
         self.base_timeout = base_timeout
         self.base_headers = base_headers
+        self.async_base_headers = async_base_headers
         self.httpx_client = httpx_client
 
+    async def _get_headers(self) -> typing.Dict[str, str]:
+        if self.async_base_headers is not None:
+            return await self.async_base_headers()
+        return self.base_headers()
+
     def get_base_url(self, maybe_base_url: typing.Optional[str]) -> str:
         base_url = maybe_base_url
         if self.base_url is not None and base_url is None:
@@ -386,7 +488,7 @@ class AsyncHttpClient:
         ] = None,
         headers: typing.Optional[typing.Dict[str, typing.Any]] = None,
         request_options: typing.Optional[RequestOptions] = None,
-        retries: int = 2,
+        retries: int = 0,
         omit: typing.Optional[typing.Any] = None,
         force_multipart: typing.Optional[bool] = None,
     ) -> httpx.Response:
@@ -408,36 +510,45 @@ class AsyncHttpClient:
 
         json_body, data_body = get_request_body(json=json, data=data, request_options=request_options, omit=omit)
 
+        data_body = _maybe_filter_none_from_multipart_data(data_body, request_files, force_multipart)
+
+        # Get headers (supports async token providers)
+        _headers = await self._get_headers()
+
+        # Compute encoded params separately to avoid passing empty list to httpx
+        # (httpx strips existing query params from URL when params=[] is passed)
+        _encoded_params = encode_query(
+            jsonable_encoder(
+                remove_none_from_dict(
+                    remove_omit_from_dict(
+                        {
+                            **(params if params is not None else {}),
+                            **(
+                                request_options.get("additional_query_parameters", {}) or {}
+                                if request_options is not None
+                                else {}
+                            ),
+                        },
+                        omit,
+                    )
+                )
+            )
+        )
+
         # Add the input to each of these and do None-safety checks
         response = await self.httpx_client.request(
             method=method,
-            url=urllib.parse.urljoin(f"{base_url}/", path),
+            url=_build_url(base_url, path),
             headers=jsonable_encoder(
                 remove_none_from_dict(
                     {
-                        **self.base_headers(),
+                        **_headers,
                         **(headers if headers is not None else {}),
                         **(request_options.get("additional_headers", {}) or {} if request_options is not None else {}),
                     }
                 )
             ),
-            params=encode_query(
-                jsonable_encoder(
-                    remove_none_from_dict(
-                        remove_omit_from_dict(
-                            {
-                                **(params if params is not None else {}),
-                                **(
-                                    request_options.get("additional_query_parameters", {}) or {}
-                                    if request_options is not None
-                                    else {}
-                                ),
-                            },
-                            omit,
-                        )
-                    )
-                )
-            ),
+            params=_encoded_params if _encoded_params else None,
             json=json_body,
             data=data_body,
             content=content,
@@ -445,9 +556,9 @@ class AsyncHttpClient:
             timeout=timeout,
         )
 
-        max_retries: int = request_options.get("max_retries", 0) if request_options is not None else 0
+        max_retries: int = request_options.get("max_retries", 2) if request_options is not None else 2
         if _should_retry(response=response):
-            if max_retries > retries:
+            if retries < max_retries:
                 await asyncio.sleep(_retry_timeout(response=response, retries=retries))
                 return await self.request(
                     path=path,
@@ -483,7 +594,7 @@ class AsyncHttpClient:
         ] = None,
         headers: typing.Optional[typing.Dict[str, typing.Any]] = None,
         request_options: typing.Optional[RequestOptions] = None,
-        retries: int = 2,
+        retries: int = 0,
         omit: typing.Optional[typing.Any] = None,
         force_multipart: typing.Optional[bool] = None,
     ) -> typing.AsyncIterator[httpx.Response]:
@@ -505,35 +616,44 @@ class AsyncHttpClient:
 
         json_body, data_body = get_request_body(json=json, data=data, request_options=request_options, omit=omit)
 
+        data_body = _maybe_filter_none_from_multipart_data(data_body, request_files, force_multipart)
+
+        # Get headers (supports async token providers)
+        _headers = await self._get_headers()
+
+        # Compute encoded params separately to avoid passing empty list to httpx
+        # (httpx strips existing query params from URL when params=[] is passed)
+        _encoded_params = encode_query(
+            jsonable_encoder(
+                remove_none_from_dict(
+                    remove_omit_from_dict(
+                        {
+                            **(params if params is not None else {}),
+                            **(
+                                request_options.get("additional_query_parameters", {})
+                                if request_options is not None
+                                else {}
+                            ),
+                        },
+                        omit=omit,
+                    )
+                )
+            )
+        )
+
         async with self.httpx_client.stream(
             method=method,
-            url=urllib.parse.urljoin(f"{base_url}/", path),
+            url=_build_url(base_url, path),
             headers=jsonable_encoder(
                 remove_none_from_dict(
                     {
-                        **self.base_headers(),
+                        **_headers,
                         **(headers if headers is not None else {}),
                         **(request_options.get("additional_headers", {}) if request_options is not None else {}),
                     }
                 )
             ),
-            params=encode_query(
-                jsonable_encoder(
-                    remove_none_from_dict(
-                        remove_omit_from_dict(
-                            {
-                                **(params if params is not None else {}),
-                                **(
-                                    request_options.get("additional_query_parameters", {})
-                                    if request_options is not None
-                                    else {}
-                                ),
-                            },
-                            omit=omit,
-                        )
-                    )
-                )
-            ),
+            params=_encoded_params if _encoded_params else None,
             json=json_body,
             data=data_body,
             content=content,

sarvamai/core/http_response.py

@@ -4,8 +4,8 @@ from typing import Dict, Generic, TypeVar
 
 import httpx
 
+# Generic to represent the underlying type of the data wrapped by the HTTP response.
 T = TypeVar("T")
-"""Generic to represent the underlying type of the data wrapped by the HTTP response."""
 
 
 class BaseHttpResponse:

sarvamai/core/http_sse/__init__.py

@@ -0,0 +1,42 @@
+# This file was auto-generated by Fern from our API Definition.
+
+# isort: skip_file
+
+import typing
+from importlib import import_module
+
+if typing.TYPE_CHECKING:
+    from ._api import EventSource, aconnect_sse, connect_sse
+    from ._exceptions import SSEError
+    from ._models import ServerSentEvent
+_dynamic_imports: typing.Dict[str, str] = {
+    "EventSource": "._api",
+    "SSEError": "._exceptions",
+    "ServerSentEvent": "._models",
+    "aconnect_sse": "._api",
+    "connect_sse": "._api",
+}
+
+
+def __getattr__(attr_name: str) -> typing.Any:
+    module_name = _dynamic_imports.get(attr_name)
+    if module_name is None:
+        raise AttributeError(f"No {attr_name} found in _dynamic_imports for module name -> {__name__}")
+    try:
+        module = import_module(module_name, __package__)
+        if module_name == f".{attr_name}":
+            return module
+        else:
+            return getattr(module, attr_name)
+    except ImportError as e:
+        raise ImportError(f"Failed to import {attr_name} from {module_name}: {e}") from e
+    except AttributeError as e:
+        raise AttributeError(f"Failed to get {attr_name} from {module_name}: {e}") from e
+
+
+def __dir__():
+    lazy_attrs = list(_dynamic_imports.keys())
+    return sorted(lazy_attrs)
+
+
+__all__ = ["EventSource", "SSEError", "ServerSentEvent", "aconnect_sse", "connect_sse"]

sarvamai/core/http_sse/_api.py

@@ -0,0 +1,112 @@
+# This file was auto-generated by Fern from our API Definition.
+
+import re
+from contextlib import asynccontextmanager, contextmanager
+from typing import Any, AsyncGenerator, AsyncIterator, Iterator, cast
+
+import httpx
+from ._decoders import SSEDecoder
+from ._exceptions import SSEError
+from ._models import ServerSentEvent
+
+
+class EventSource:
+    def __init__(self, response: httpx.Response) -> None:
+        self._response = response
+
+    def _check_content_type(self) -> None:
+        content_type = self._response.headers.get("content-type", "").partition(";")[0]
+        if "text/event-stream" not in content_type:
+            raise SSEError(
+                f"Expected response header Content-Type to contain 'text/event-stream', got {content_type!r}"
+            )
+
+    def _get_charset(self) -> str:
+        """Extract charset from Content-Type header, fallback to UTF-8."""
+        content_type = self._response.headers.get("content-type", "")
+
+        # Parse charset parameter using regex
+        charset_match = re.search(r"charset=([^;\s]+)", content_type, re.IGNORECASE)
+        if charset_match:
+            charset = charset_match.group(1).strip("\"'")
+            # Validate that it's a known encoding
+            try:
+                # Test if the charset is valid by trying to encode/decode
+                "test".encode(charset).decode(charset)
+                return charset
+            except (LookupError, UnicodeError):
+                # If charset is invalid, fall back to UTF-8
+                pass
+
+        # Default to UTF-8 if no charset specified or invalid charset
+        return "utf-8"
+
+    @property
+    def response(self) -> httpx.Response:
+        return self._response
+
+    def iter_sse(self) -> Iterator[ServerSentEvent]:
+        self._check_content_type()
+        decoder = SSEDecoder()
+        charset = self._get_charset()
+
+        buffer = ""
+        for chunk in self._response.iter_bytes():
+            # Decode chunk using detected charset
+            text_chunk = chunk.decode(charset, errors="replace")
+            buffer += text_chunk
+
+            # Process complete lines
+            while "\n" in buffer:
+                line, buffer = buffer.split("\n", 1)
+                line = line.rstrip("\r")
+                sse = decoder.decode(line)
+                # when we reach a "\n\n" => line = ''
+                # => decoder will attempt to return an SSE Event
+                if sse is not None:
+                    yield sse
+
+        # Process any remaining data in buffer
+        if buffer.strip():
+            line = buffer.rstrip("\r")
+            sse = decoder.decode(line)
+            if sse is not None:
+                yield sse
+
+    async def aiter_sse(self) -> AsyncGenerator[ServerSentEvent, None]:
+        self._check_content_type()
+        decoder = SSEDecoder()
+        lines = cast(AsyncGenerator[str, None], self._response.aiter_lines())
+        try:
+            async for line in lines:
+                line = line.rstrip("\n")
+                sse = decoder.decode(line)
+                if sse is not None:
+                    yield sse
+        finally:
+            await lines.aclose()
+
+
+@contextmanager
+def connect_sse(client: httpx.Client, method: str, url: str, **kwargs: Any) -> Iterator[EventSource]:
+    headers = kwargs.pop("headers", {})
+    headers["Accept"] = "text/event-stream"
+    headers["Cache-Control"] = "no-store"
+
+    with client.stream(method, url, headers=headers, **kwargs) as response:
+        yield EventSource(response)
+
+
+@asynccontextmanager
+async def aconnect_sse(
+    client: httpx.AsyncClient,
+    method: str,
+    url: str,
+    **kwargs: Any,
+) -> AsyncIterator[EventSource]:
+    headers = kwargs.pop("headers", {})
+    headers["Accept"] = "text/event-stream"
+    headers["Cache-Control"] = "no-store"
+
+    async with client.stream(method, url, headers=headers, **kwargs) as response:
+        yield EventSource(response)