Skip to content

LLM-Driven Extraction of Unstructured Data — Built for API Deployments & ETL Pipeline Workflows

UN-2443 [FEAT] Improved runner API reliability with retry and backoff mechanism to reduce job failures during scale and restarts (#1360)

alia084561213c8
diff --git a/unstract/core/src/unstract/core/network/__init__.py b/unstract/core/src/unstract/core/network/__init__.py
new file mode 100644
index 000000000..bc3e7960a
--- /dev/null
+++ b/unstract/core/src/unstract/core/network/__init__.py
@@ -0,0 +1,5 @@
+from unstract.core.network.enums import HTTPMethod
+from unstract.core.network.http_client import HttpClient
+from unstract.core.network.retry import get_retry_session
+
+__all__ = ["HTTPMethod", "get_retry_session", "HttpClient"]
diff --git a/unstract/core/src/unstract/core/network/enums.py b/unstract/core/src/unstract/core/network/enums.py
new file mode 100644
index 000000000..2055b6648
--- /dev/null
+++ b/unstract/core/src/unstract/core/network/enums.py
@@ -0,0 +1,8 @@
+from enum import Enum
+
+
+class HTTPMethod(str, Enum):
+ GET = "GET"
+ POST = "POST"
+ DELETE = "DELETE"
+ PUT = "PUT"
diff --git a/unstract/core/src/unstract/core/network/http_client.py b/unstract/core/src/unstract/core/network/http_client.py
new file mode 100644
index 000000000..f6fe98d1d
--- /dev/null
+++ b/unstract/core/src/unstract/core/network/http_client.py
@@ -0,0 +1,63 @@
+import logging
+
+import requests
+
+from unstract.core.network.enums import HTTPMethod
+
+logger = logging.getLogger(__name__)
+
+
+class HttpClient:
+ """Lightweight HTTP client wrapper around `requests.Session`, supporting retries and timeout.
+
+ Allows making API requests with configurable base URL and default timeout.
+ """
+
+ def __init__(
+ self, session: requests.Session, base_url: str, timeout: int | None = None
+ ):
+ """Initialize HttpClient with a session, base URL, and optional timeout.
+
+ Args:
+ session (requests.Session): Session object for making requests.
+ base_url (str): Base URL for the API.
+ timeout (int | None): Optional timeout for requests.
+ """
+ self.session = session
+ self.base_url = base_url.rstrip("/")
+ self.timeout = timeout
+
+ def request(
+ self,
+ method: HTTPMethod,
+ endpoint: str,
+ timeout: int | None = None,
+ raise_on_status: bool = True,
+ **kwargs,
+ ):
+ """Make api request using session with retry strategy.
+
+ Args:
+ method (HTTPMethod): HTTP method
+ endpoint (str): API endpoint
+ timeout (int | None): Override timeout for this request. Falls back to class-level timeout.
+ raise_on_status (bool): If True, raises HTTPError on non-2xx responses.
+ **kwargs: Additional keyword arguments to pass to requests.request
+
+ Returns:
+ requests.Response: Response object
+ """
+ url = f"{self.base_url}/{endpoint.lstrip('/')}"
+ timeout = timeout or self.timeout
+ try:
+ response = self.session.request(
+ method=method.value, url=url, timeout=timeout, **kwargs
+ )
+ if raise_on_status:
+ response.raise_for_status() # Raise HTTP errors
+ return response
+ except requests.exceptions.RequestException as e:
+ logger.error(f"{method} {url} failed :{e}")
+ raise
+
+ __call__ = request
diff --git a/unstract/core/src/unstract/core/network/retry.py b/unstract/core/src/unstract/core/network/retry.py
new file mode 100644
index 000000000..6e58bbef3
--- /dev/null
+++ b/unstract/core/src/unstract/core/network/retry.py
@@ -0,0 +1,68 @@
+import requests
+from requests.adapters import HTTPAdapter
+from urllib3.util import Retry
+
+from unstract.core.network.enums import HTTPMethod
+
+
+def get_retry_session(
+ retry_count: int = 5,
+ backoff_factor: int = 3,
+ status_forcelist: list[int] | None = None,
+ allowed_methods: list[str] | None = None,
+ raise_on_status: bool = False,
+ enable_http: bool = True,
+ enable_https: bool = True,
+) -> requests.Session:
+ """Get retry adapter for requests.
+
+ This function creates a requests session with a retry strategy.
+
+ Args:
+ retry_count (int, optional): Number of retries. Defaults to 5.
+ backoff_factor (int, optional): Base delay for exponential backoff.
+ The wait time before retry attempt N is:
+ backoff_factor * (2^(N-1)) seconds
+
+ Example (backoff_factor=3):
+ Attempt 1: 3 * 1 = 3s
+ Attempt 2: 3 * 2 = 6s
+ Attempt 3: 3 * 4 = 12s
+ Defaults to 3.
+ status_forcelist (list, optional): List of status codes to retry. Defaults to None.
+ allowed_methods (list, optional): List of allowed methods. Defaults to None.
+ raise_on_status (bool, optional): Whether to raise on status. Defaults to False.
+ enable_http (bool, optional): Whether to enable http. Defaults to True.
+ enable_https (bool, optional): Whether to enable https. Defaults to True.
+
+ Returns:
+ requests.Session: HTTP session with retry strategy.
+
+ Examples:
+ >>> session = get_retry_session(
+ retry_count=5,
+ backoff_factor=3,
+ status_forcelist=[429, 500, 502, 503, 504],
+ allowed_methods=[HTTPMethod.GET.value, HTTPMethod.POST.value],
+ raise_on_status=False,
+ enable_http=True,
+ enable_https=True,
+ )
+ >>> response = session.get("https://example.com")
+ """
+ status_forcelist = status_forcelist or [429, 500, 502, 503, 504]
+ allowed_methods = allowed_methods or [HTTPMethod.GET.value, HTTPMethod.POST.value]
+ retry_strategy = Retry(
+ total=retry_count,
+ backoff_factor=backoff_factor,
+ status_forcelist=status_forcelist,
+ allowed_methods=allowed_methods,
+ raise_on_status=raise_on_status,
+ )
+ adapter = HTTPAdapter(max_retries=retry_strategy)
+ session = requests.Session()
+ if enable_http:
+ session.mount("http://", adapter)
+ if enable_https:
+ session.mount("https://", adapter)
+ return session
diff --git a/unstract/tool-sandbox/src/unstract/tool_sandbox/helper.py b/unstract/tool-sandbox/src/unstract/tool_sandbox/helper.py
index fbb72eb87..60b1dc836 100644
--- a/unstract/tool-sandbox/src/unstract/tool_sandbox/helper.py
+++ b/unstract/tool-sandbox/src/unstract/tool_sandbox/helper.py
@@ -16,6 +16,7 @@ from unstract.core.file_execution_tracker import (
FileExecutionStageStatus,
FileExecutionStatusTracker,
)
+from unstract.core.network import HttpClient, HTTPMethod, get_retry_session
from unstract.core.runner.enum import ContainerStatus
from unstract.core.tool_execution_status import (
ToolExecutionData,
@@ -60,6 +61,18 @@ class ToolSandboxHelper:
self.execution_id = str(execution_id)
self.envs = environment_variables
self.messaging_channel = str(messaging_channel)
+ self.timeout = int(os.getenv("UNSTRACT_RUNNER_API_TIMEOUT", 120))
+ self.retry_count = int(os.getenv("UNSTRACT_RUNNER_API_RETRY_COUNT", 5))
+ self.backoff_factor = int(os.getenv("UNSTRACT_RUNNER_API_BACKOFF_FACTOR", 3))
+
+ self.session = get_retry_session(
+ retry_count=self.retry_count,
+ backoff_factor=self.backoff_factor,
+ raise_on_status=False,
+ )
+ self.http_client = HttpClient(
+ session=self.session, base_url=self.base_url, timeout=self.timeout
+ )
def convert_str_to_dict(self, data: str | dict[str, Any]) -> dict[str, Any]:
if isinstance(data, str):
@@ -311,12 +324,16 @@ class ToolSandboxHelper:
container_name: str,
file_execution_id: str,
) -> None:
- url = f"{self.base_url}{UnstractRunner.CLEANUP_TOOL_CONTAINER_API_ENDPOINT}"
headers = {
"X-Request-ID": file_execution_id,
}
data = self.cleanup_tool_container_request_data(container_name=container_name)
- response = requests.post(url, headers=headers, json=data)
+ response = self.http_client(
+ method=HTTPMethod.POST,
+ endpoint=UnstractRunner.CLEANUP_TOOL_CONTAINER_API_ENDPOINT,
+ headers=headers,
+ json=data,
+ )
if response.status_code != 200:
logger.error(
f"Error while calling tool {container_name} reason: {response.reason}"
@@ -390,7 +407,6 @@ class ToolSandboxHelper:
Returns:
Optional[dict[str, Any]]: tool response
"""
- url = f"{self.base_url}{UnstractRunner.RUN_API_ENDPOINT}"
headers = {
"X-Request-ID": file_execution_id,
}
@@ -400,7 +416,12 @@ class ToolSandboxHelper:
response: Response = Response()
try:
- response = requests.post(url, headers=headers, json=data)
+ response = self.http_client(
+ method=HTTPMethod.POST,
+ endpoint=UnstractRunner.RUN_API_ENDPOINT,
+ headers=headers,
+ json=data,
+ )
response.raise_for_status()
except ConnectionError as connect_err:
msg = "Unable to connect to unstract-runner."
@@ -469,8 +490,9 @@ class ToolSandboxHelper:
container_name: str,
) -> dict[str, Any] | None:
params = self._create_tool_run_status_check_request_data(container_name)
- response = requests.get(
- url=f"{self.base_url}{UnstractRunner.RUN_STATUS_API_ENDPOINT}",
+ response = self.http_client(
+ method=HTTPMethod.GET,
+ endpoint=UnstractRunner.RUN_STATUS_API_ENDPOINT,
params=params,
)
result: dict[str, Any] | None = None