feat(service): retrieve convert()/convert_all() results via presigned artifacts

[cau-git]

Summary

DoclingServiceClient.convert() and convert_all() now retrieve results over presigned artifact storage instead of always inlining them in the HTTP response. Inlining (InBodyTarget) returns the full document JSON and embedded images on every result fetch, which is too expensive in transport for hosted services. These high-level methods now use the same auto-target flow as submit(): PresignedUrlTarget first, falling back to InBodyTarget only when the server rejects presigned output for configuration/policy reasons. The presigned path is fully materialized back into a ConversionResult, so callers see no API change.

What changed

• Presigned materialization. When the server returns presigned artifacts, the client downloads them and rebuilds a self-contained ConversionResult. For a resource_bundle (REFERENCED image mode) the ZIP is downloaded and extracted, the document JSON is loaded, and referenced picture/page images are inlined into the document so the result has no on-disk dependency. For a json artifact (EMBEDDED/PLACEHOLDER) the self-contained JSON is loaded directly.
• Hardened downloads. Artifact fetches use a dedicated HTTP client (the service X-Api-Key is never sent to external storage), enforce a streamed size cap, and follow redirects manually so every hop is re-validated.
• SSRF guard. Artifact URLs (and each redirect target) must resolve to a globally-routable address; private, loopback, link-local, reserved, multicast and unspecified addresses are rejected. allow_private_artifact_urls=True opts into private/loopback storage endpoints (e.g. on-prem or local MinIO).
• Graceful failure. A failed download or reconstruction yields a FAILURE ConversionResult with an explanatory error item; convert_all() continues with the remaining inputs and convert() surfaces it via raises_on_error.
• Final API. Removed the experimental warning emitted by DoclingServiceClient and the matching notices in the SDK examples.
• Cleanup. Replaced the implicit "pass InBodyTarget to force JSON" pattern with an explicit _with_json_output_format helper used by every path that reconstructs a document.

Public API

• DoclingServiceClient(..., allow_private_artifact_urls=False, artifact_download_timeout=60.0, max_artifact_download_bytes=512 MiB) — new constructor options.
• ArtifactDownloadError — new exception type (exported), used internally for graceful degradation.
• submit() / submit_batch() / submit_and_retrieve_each() are unchanged and still return raw presigned responses.

Behaviour change

Against a server with artifact storage configured, convert()/convert_all() now route through presigned download instead of inline transport. Servers without artifact storage transparently fall back to InBodyTarget, so existing behaviour is preserved there.

[github-actions]

✅ DCO Check Passed

Thanks @cau-git, all your commits are properly signed off. 🎉

[mergify]

Merge Protections

Your pull request matches the following merge protections and will not be merged until they are valid.

🟢 Enforce conventional commit

Wonderful, this rule succeeded.

Make sure that we follow https://www.conventionalcommits.org/en/v1.0.0/

• title ~= ^(fix|feat|docs|style|refactor|perf|test|build|ci|chore|revert)(?:\(.+\))?(!)?:

[dolfim-ibm]

lgtm

[codecov]

Codecov Report

❌ Patch coverage is 68.62745% with 64 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
docling/service_client/client.py	68.47%	64 Missing ⚠️

📢 Thoughts on this report? Let us know!

[PeterStaar-IBM]

lgtm!