Merge pull request #27 from Zipstack/feat/generated-transport

UN-4010 [FEAT] Support every API deployment request parameter via a generated transport

Author: chandrasekharan-zipstack

.gitattributes

@@ -0,0 +1 @@
+src/unstract/api_deployments/_sdk_docstudio/** linguist-generated=true

.github/workflows/test.yml

@@ -14,14 +14,14 @@ jobs:
       matrix:
         python-version: ["3.11", "3.12"]
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
         with:
           python-version: ${{ matrix.python-version }}
 
       - name: Install uv
-        uses: astral-sh/setup-uv@v6
+        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0
         with:
           version: "0.6.14"
           enable-cache: true
@@ -37,3 +37,31 @@ jobs:
 
       - name: Tests (pytest)
         run: uv run pytest tests/ -v
+
+  sdk-drift:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4.4.0
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5.6.0
+        with:
+          python-version: "3.12"
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@d0cc045d04ccac9d8b7881df0226f9e82c39688e # v6.8.0
+        with:
+          version: "0.6.14"
+          enable-cache: true
+
+      # The generated tree is committed, so an edit to it reviews like any
+      # other change and then disappears on the next regeneration. Same for a
+      # spec change that never had the generator run over it.
+      - name: Regenerate from the committed spec
+        run: ./tools/gen_sdk.sh
+
+      # `git add -N` first: a diff alone cannot see a file the generator has
+      # newly created, which is exactly what a spec growing an endpoint does.
+      - name: Fail if the committed SDK is not what the spec generates
+        run: |
+          git add -N -- src/unstract/api_deployments/_sdk_docstudio
+          git diff --exit-code -- src/unstract/api_deployments/_sdk_docstudio

.gitignore

@@ -114,6 +114,8 @@ celerybeat.pid
 # Environments
 .env
 .venv
+# Built inside the repo by tools/gen_sdk.sh.
+.gen-venv/
 env/
 venv/
 ENV/

README.md

@@ -65,15 +65,28 @@ except APIDeploymentsClientException as e:
 
 `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`.
+`api_timeout`: Backend execution mode sent with the request (see `timeout` on `structure_file`). `0` or below queues the execution and returns immediately; above it the call runs synchronously and the value bounds how long the backend waits. This is not a socket timeout — pass `transport_timeout` for that.
 `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.
+`transport_timeout`: Socket timeout in seconds (keyword-only). Left unset, a stalled connection blocks forever, which is what earlier releases did.
+
+## Closing the client
+
+The client reuses connections between calls, so release them when you are done
+with it — either by calling `close()`, or by using it as a context manager:
+
+```python
+with APIDeploymentsClient(api_url="url", api_key="your_api_key") as adc:
+    response = adc.structure_file(["<file>"])
+```
+
+A long-lived client can be left open; one built per job should be closed.
 
 ## 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.
+- **Async mode** (`api_timeout` of `0` or below): 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.
 
@@ -100,16 +113,24 @@ client = APIDeploymentsClient(
 The retry logic uses exponential backoff with full jitter and respects the `Retry-After` header on 429 responses.
 
 
-## Unstract CLI
+## Internals
+
+`unstract.api_deployments._sdk_docstudio` is generated from the deployment API's
+OpenAPI spec by `tools/gen_sdk.sh` and is an implementation detail of the
+transport. `APIDeploymentsClient` is the supported surface — import from it, not
+from the generated tree, which is regenerated wholesale whenever the spec moves.
+
+## Cloning an organization
 
-Installing `unstract-client` also provides the `unstract` command:
+Installing `unstract-client` also provides a clone command. This package no
+longer installs an `unstract` console script, so invoke it as a module:
 
 ```bash
 pip install unstract-client
-unstract --help
+python -m unstract.clone --help
 ```
 
-### `unstract clone`
+### `python -m unstract.clone clone`
 
 Clones an organization's resources to another org, on the same or a different
 deployment (e.g. promote **dev** → **QA** → **prod**). Covers adapters,
@@ -124,7 +145,7 @@ so keys never land in shell history:
 export UNSTRACT_SRC_PLATFORM_KEY="<source platform key>"
 export UNSTRACT_TGT_PLATFORM_KEY="<target platform key>"
 
-unstract clone \
+python -m unstract.clone clone \
   --source-url https://dev.example.com --source-org org_dev123 \
   --target-url https://qa.example.com --target-org org_qa456 \
   --dry-run
@@ -152,14 +173,14 @@ failed run can be resumed by re-running the same command.
 
 #### Compatibility
 
-`unstract clone` is capability-probed: each phase checks for its endpoint on the
+Cloning is capability-probed: each phase checks for its endpoint on the
 source and target, and clones only what both orgs support. A capability missing on
 either side is reported and skipped — the run never fails because of a version
 difference. Cloning a newer source into an older target therefore drops the entity
 types the target lacks (listed in the end-of-run report).
 
 - Run the source and target on the same (or a newer-target) Unstract build.
-- Use `unstract-client >= 1.4.0`, the first release that ships `unstract clone`.
+- Use `unstract-client >= 1.4.0`, the first release that ships the clone command.
 
 ## Questions and Feedback
 

pyproject.toml

@@ -6,6 +6,13 @@ authors = [
     {name = "Zipstack Inc", email = "devsupport@zipstack.com"},
 ]
 dependencies = [
+    # The transport layer is generated against httpx; attrs backs its models.
+    # Upper-bounded because the generated code is written against one minor
+    # series: a bump has to be regenerated and re-tested, not resolved into.
+    "httpx>=0.27,<0.29",
+    "attrs>=23.2",
+    # Still the transport for the `unstract.clone` subpackage, and the source of
+    # the exception classes callers catch by name around the deployment client.
     "requests>=2.32.3",
     "tenacity>=8.2.0",
     "click>=8.1",
@@ -27,9 +34,6 @@ classifiers = [
     "Topic :: Software Development :: Libraries :: Python Modules",
 ]
 
-[project.scripts]
-unstract = "unstract.cli:main"
-
 [build-system]
 requires = ["hatchling"]
 build-backend = "hatchling.build"
@@ -64,6 +68,9 @@ lint = [
 
 [tool.ruff]
 line-length = 88
+# Generated and vendored code is overwritten wholesale by its refresh script, so
+# a lint finding there can never be fixed in place.
+extend-exclude = ["src/unstract/api_deployments/_sdk_docstudio", "tests/baseline"]
 
 [tool.ruff.lint]
 select = ["E", "F", "W", "I"]