Merge pull request #12 from Zipstack/feat/UN-3230-FEAT_implement_backoff_retry_mechanism

UN-3230 [FEAT] Implement back-off retry mechanism for API deployment client

Author: jaseemjaskp

.github/workflows/main.yml

@@ -17,11 +17,14 @@ jobs:
         with:
           ref: ${{ github.event.release.tag_name }}
 
-      - name: Setup PDM
-        uses: pdm-project/setup-pdm@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v7
         with:
-          python-version: 3.11
-          version: 2.10.0
+          python-version: "3.12"
+          enable-cache: true
+
+      - name: Build package
+        run: uv build
 
       - name: Publish package distributions to PyPI
-        run: pdm publish
+        run: uv publish

.gitignore

@@ -101,18 +101,8 @@ ipython_config.py
 #   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
 #poetry.lock
 
-# pdm
-#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
-#pdm.lock
-#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
-#   in version control.
-#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
-.pdm.toml
-.pdm-python
-.pdm-build/
-
-# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
-__pypackages__/
+# uv
+.python-version
 
 # Celery stuff
 celerybeat-schedule

.pre-commit-config.yaml

@@ -4,9 +4,9 @@
 # - Added pkgs feature flag auto generated code to flake8 exclude list
 # Force all unspecified python hooks to run python 3.10
 default_language_version:
-  python: python3.9
+  python: python3
 default_stages:
-  - commit
+  - pre-commit
 repos:
   - repo: https://github.com/pre-commit/pre-commit-hooks
     rev: v4.5.0
@@ -48,46 +48,14 @@ repos:
     hooks:
       - id: actionlint-docker
         args: [-ignore, 'label ".+" is unknown']
-  - repo: https://github.com/psf/black
-    rev: 24.2.0
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.15.1
     hooks:
-      - id: black
-        args: [--config=pyproject.toml, -l 88]
-        language: system
-        exclude: |
-          (?x)^(
-              pkgs/unstract-flags/src/unstract/flags/evaluation_.*\.py|
-          )$
-  - repo: https://github.com/pycqa/flake8
-    rev: 7.0.0
-    hooks:
-      - id: flake8
-        args: [--max-line-length=88]
-        exclude: |
-          (?x)^(
-              .*migrations/.*\.py|
-              unstract-core/tests/.*|
-              pkgs/unstract-flags/src/unstract/flags/evaluation_.*\.py|
-          )$
-  - repo: https://github.com/pycqa/isort
-    rev: 5.13.2
-    hooks:
-      - id: isort
-        files: "\\.(py)$"
-        args:
-          [
-            "--profile",
-            "black",
-            "--filter-files",
-            --settings-path=pyproject.toml,
-          ]
-  - repo: https://github.com/hadialqattan/pycln
-    rev: v2.4.0
-    hooks:
-      - id: pycln
-        args: [--config=pyproject.toml]
+      - id: ruff
+        args: [--fix]
+      - id: ruff-format
   - repo: https://github.com/pycqa/docformatter
-    rev: v1.7.5
+    rev: v1.7.7
     hooks:
       - id: docformatter
   # - repo: https://github.com/MarcoGorelli/absolufy-imports
@@ -154,7 +122,7 @@ repos:
         args: [--disable, MD013]
       - id: markdownlint-fix
         args: [--disable, MD013]
-  - repo: https://github.com/pdm-project/pdm
-    rev: 2.12.3
+  - repo: https://github.com/astral-sh/uv-pre-commit
+    rev: 0.10.2
     hooks:
-      - id: pdm-lock-check
+      - id: uv-lock

README.md

@@ -29,6 +29,8 @@ Then, create an instance of the `APIDeploymentsClient`:
 client = APIDeploymentsClient(api_url="url", api_key="your_api_key")
 ```
 
+> **Note:** Pass the raw API key **without** the `"Bearer "` prefix — the client adds it automatically.
+
 Now, you can use the client to interact with the Unstract API deployments API:
 
 ```python
@@ -61,10 +63,42 @@ except APIDeploymentsClientException as e:
 
 ## Parameter Details
 
+`api_url`: The URL of the Unstract API deployment.
+`api_key`: Your raw API key. **Do not** include the `"Bearer "` prefix — the client adds it automatically.
 `api_timeout`: Set a timeout for API requests, e.g., `api_timeout=10`.
 `logging_level`: Set logging verbosity (e.g., "`DEBUG`").
 `include_metadata`: If set to `True`, the response will include additional metadata (cost, tokens consumed and context) for each call made by the Prompt Studio exported tool.
 
+## Retry Configuration
+
+The client includes built-in exponential backoff retry with the following behavior:
+
+- **Async mode** (`api_timeout=0`): POST requests are retried on transient failures (5xx, 429) and connection errors, since the server returns immediately after queuing.
+- **Sync mode** (`api_timeout > 0`, the default): POST requests are **not** retried, because the server blocks during processing — a failure may mean the request was processed but the response was lost.
+- **Status polling** (`check_execution_status`): GET requests are always retried, as they are idempotent.
+
+Retries are enabled by default and can be customized:
+
+```python
+client = APIDeploymentsClient(
+    api_url="url",
+    api_key="your_api_key",
+    max_retries=4,       # Max retry attempts (default: 4, set to 0 to disable)
+    initial_delay=2.0,   # Initial delay in seconds (default: 2.0)
+    max_delay=60.0,      # Maximum delay cap in seconds (default: 60.0)
+    backoff_factor=2.0,  # Multiplier per retry (default: 2.0)
+)
+```
+
+| Parameter | Default | Description |
+|-----------|---------|-------------|
+| `max_retries` | `4` | Maximum number of retry attempts. Set to `0` to disable retries. |
+| `initial_delay` | `2.0` | Initial delay in seconds before the first retry. |
+| `max_delay` | `60.0` | Maximum delay cap in seconds between retries. |
+| `backoff_factor` | `2.0` | Multiplier applied to the delay for each subsequent retry. |
+
+The retry logic uses exponential backoff with full jitter and respects the `Retry-After` header on 429 responses.
+
 
 ## Questions and Feedback