LLM-Driven Extraction of Unstructured Data — Built for API Deployments & ETL Pipeline Workflows
Python ai-agentsdata-engineeringdocument-aigenerative-aiidpjson-extractionllmmcp-serverocrpdf-extractionprompt-engineeringstructured-output
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__.pynew file mode 100644index 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.pynew file mode 100644index 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.pynew file mode 100644index 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__ = requestdiff --git a/unstract/core/src/unstract/core/network/retry.py b/unstract/core/src/unstract/core/network/retry.pynew file mode 100644index 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 sessiondiff --git a/unstract/tool-sandbox/src/unstract/tool_sandbox/helper.py b/unstract/tool-sandbox/src/unstract/tool_sandbox/helper.pyindex 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_sessionfrom unstract.core.runner.enum import ContainerStatusfrom unstract.core.tool_execution_status import (ToolExecutionData,@@ -60,6 +61,18 @@ class ToolSandboxHelper:self.execution_id = str(execution_id)self.envs = environment_variablesself.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