SDK correctness and resilience improvements (#336)

<!-- CURSOR_SUMMARY -->
> [!NOTE]
> **Medium Risk**
> Touches core split-PDF execution and retry/timeout cleanup logic;
mistakes could impact partition reliability or leak resources, though
changes are well-covered by expanded unit/integration tests and logging.
> 
> **Overview**
> Improves split-PDF correctness and debuggability by adding
**operation-aware observability** (plan/batch/chunk lifecycle logs) and
propagating split metadata via `X-Unstructured-Split-*` headers into
errors/logs.
> 
> Hardens split execution: per-operation state is isolated, transport
exceptions/cancellations are handled explicitly (with optional
partial-results behavior via `split_pdf_allow_failed`), and
timeout/cleanup paths now safely cancel in-flight work even when event
loops are closed.
> 
> Preserves chunk-level transport retries by deriving a split-specific
retry config that always retries `httpx.TransportError` for chunk calls,
even when SDK-level connection retries are disabled. CI/test tooling is
updated (new platform integration job/target, more verbose integration
output, and bumped GitHub Action versions), and the package is released
as `0.43.1`.
> 
> <sup>Reviewed by [Cursor Bugbot](https://cursor.com/bugbot) for commit
e65ce5b. Bugbot is set up for automated
code reviews on this repo. Configure
[here](https://www.cursor.com/dashboard/bugbot).</sup>
<!-- /CURSOR_SUMMARY -->

Author: PastelStorm

.github/workflows/ci.yaml

@@ -24,10 +24,10 @@ jobs:
         python-version: [ "3.11", "3.12", "3.13" ]
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
-    - uses: astral-sh/setup-uv@v6
+    - uses: actions/checkout@v5
+    - uses: astral-sh/setup-uv@v7
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: ${{ matrix.python-version }}
     - name: Install dependencies
@@ -44,10 +44,10 @@ jobs:
   lint:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v4
-    - uses: astral-sh/setup-uv@v6
+    - uses: actions/checkout@v5
+    - uses: astral-sh/setup-uv@v7
     - name: Set up Python 3.13
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: "3.13"
     - name: Install dependencies
@@ -68,10 +68,10 @@ jobs:
         python-version: [ "3.11", "3.12", "3.13" ]
     runs-on: opensource-linux-8core
     steps:
-    - uses: actions/checkout@v4
-    - uses: astral-sh/setup-uv@v6
+    - uses: actions/checkout@v5
+    - uses: astral-sh/setup-uv@v7
     - name: Set up Python ${{ matrix.python-version }}
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: ${{ matrix.python-version }}
     - name: Install dependencies
@@ -86,17 +86,38 @@ jobs:
       run: |
         make test-integration-docker
 
+  test_platform_integration:
+    runs-on: opensource-linux-8core
+    steps:
+    - uses: actions/checkout@v5
+    - uses: astral-sh/setup-uv@v7
+    - name: Set up Python 3.13
+      uses: actions/setup-python@v6
+      with:
+        python-version: "3.13"
+    - name: Install dependencies
+      env:
+        UV_LOCKED: "1"
+        UV_PYTHON: "3.13"
+      run: make install
+    - name: Run platform integration tests
+      env:
+        UV_PYTHON: "3.13"
+        UNSTRUCTURED_API_KEY: ${{ secrets.UNSTRUCTURED_API_KEY }}
+      run: |
+        make test-integration-platform
+
   test_contract:
     strategy:
       fail-fast: false
       matrix:
         python-version: [ "3.11", "3.12", "3.13" ]
     runs-on: opensource-linux-8core
     steps:
-      - uses: actions/checkout@v4
-      - uses: astral-sh/setup-uv@v6
+      - uses: actions/checkout@v5
+      - uses: astral-sh/setup-uv@v7
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies

CHANGELOG.md

@@ -1,3 +1,16 @@
+## 0.43.1
+
+### Enhancements
+* Add split-PDF observability with operation-aware batch planning, timeout, cancellation, and completion logs.
+* Make long-running integration tests stream live progress, timings, and backend failure context for split and single partition phases.
+
+### Features
+
+### Fixes
+* Preserve chunk-local transport retries for split-PDF execution even when SDK-level retries disable connection-error retries for top-level requests.
+* Harden split-PDF timeout and cleanup paths against closed event loops and cancelled chunk tasks.
+* Stabilize `hi_res` split integration coverage by using a smaller derived multi-page fixture instead of the flaky full `layout-parser-paper.pdf` path for equivalence and caching checks.
+
 ## 0.42.12
 
 ### Enhancements

Makefile

@@ -2,6 +2,9 @@ PACKAGE_NAME := unstructured-python-client
 CURRENT_DIR := $(shell pwd)
 ARCH := $(shell uname -m)
 DOCKER_IMAGE ?= downloads.unstructured.io/unstructured-io/unstructured-api:latest
+INTEGRATION_IGNORE_ARGS := --ignore=_test_unstructured_client/integration/test_platform_workflow_lifecycle.py
+INTEGRATION_PYTEST_ARGS := _test_unstructured_client -vv -k integration $(INTEGRATION_IGNORE_ARGS) -o log_cli=true -o log_cli_level=INFO -o log_cli_format="%(asctime)s %(levelname)s %(message)s" --capture=tee-sys --durations=20 --tb=long
+PLATFORM_INTEGRATION_PYTEST_ARGS := _test_unstructured_client/integration/test_platform_workflow_lifecycle.py -v -o log_cli=true -o log_cli_level=INFO --durations=20 --tb=long
 
 ###########
 # Install #
@@ -36,16 +39,34 @@ test-contract:
 # Assumes you have unstructured-api running on localhost:8000
 .PHONY: test-integration
 test-integration:
-	PYTHONPATH=. uv run pytest -n auto _test_unstructured_client -v -k "integration"
+	PYTHONPATH=. uv run pytest $(INTEGRATION_PYTEST_ARGS)
 
 # Runs the unstructured-api in docker for tests
 .PHONY: test-integration-docker
 test-integration-docker:
-	-docker stop unstructured-api && docker kill unstructured-api
-	docker run --name unstructured-api -p 8000:8000 -d --rm ${DOCKER_IMAGE} --host 0.0.0.0 && \
-	curl -s -o /dev/null --retry 10 --retry-delay 5 --retry-all-errors http://localhost:8000/general/docs && \
-	PYTHONPATH=. uv run pytest -n auto _test_unstructured_client -v -k "integration" && \
-	docker kill unstructured-api
+	@bash -lc 'set -euo pipefail; \
+	container_name=unstructured-api; \
+	image="${DOCKER_IMAGE}"; \
+	cleanup() { \
+		status=$$?; \
+		if [ $$status -ne 0 ]; then \
+			echo "integration diagnostics image=$$image container=$$container_name"; \
+			docker logs "$$container_name" --tail 200 || true; \
+		fi; \
+		docker kill "$$container_name" >/dev/null 2>&1 || true; \
+		exit $$status; \
+	}; \
+	trap cleanup EXIT; \
+	docker stop "$$container_name" >/dev/null 2>&1 || true; \
+	docker kill "$$container_name" >/dev/null 2>&1 || true; \
+	echo "starting integration api image=$$image"; \
+	docker run --name "$$container_name" -p 8000:8000 -d --rm "$$image" --host 0.0.0.0; \
+	curl -s -o /dev/null --retry 10 --retry-delay 5 --retry-all-errors http://localhost:8000/general/docs; \
+	PYTHONPATH=. uv run pytest $(INTEGRATION_PYTEST_ARGS)'
+
+.PHONY: test-integration-platform
+test-integration-platform:
+	PYTHONPATH=. uv run pytest $(PLATFORM_INTEGRATION_PYTEST_ARGS)
 
 .PHONY: lint
 lint: