Repository navigation
feat(documents): extract with IXP models deployed to a folder - #2004
alexandrujircan wants to merge 6 commits into
Conversation
Add start_model_extraction, retrieve_model_extraction_result and
extract_with_model, each with an async twin, to DocumentsServiceV2.
They call the DU Framework v2 models/{name} routes with the folder key
header. The key comes from folder_key, from folder_path (looked up), or
from the job folder. extract_with_model is start_model_extraction
followed by polling retrieve_model_extraction_result.
Ported from #1933.
Co-authored-by: Thomas Lammers <thomas.lammers@uipath.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
There was a problem hiding this comment.
🟡 Changes recommended
Closing DocumentsServiceV2 leaves the cached folder service’s HTTP clients open, leaking its connection pools.
1 open issue
What changed in this PR
Adds folder-deployed IXP model extraction to the UiPath Python SDK through DocumentsServiceV2, while leaving the v1.1 document API unchanged. Validation and resume triggers remain follow-up work.
Changes:
- Adds sync and async start, retrieve, and blocking extraction methods with folder resolution and input validation.
- Introduces dedicated response models and tests for extraction flows, serialization, failures, and timeouts.
- Bumps
uipath-platformto 0.3.11 and updates both package lockfiles.
| File | Description |
|---|---|
packages/uipath/uv.lock |
Updates the local platform package version. |
packages/uipath-platform/uv.lock |
Aligns the lockfile with version 0.3.11. |
packages/uipath-platform/tests/services/test_documents_service_v2.py |
Adds folder-model extraction and error-path coverage. |
packages/uipath-platform/src/uipath/platform/documents/documents.py |
Defines folder-model start and result response types. |
packages/uipath-platform/src/uipath/platform/documents/_documents_service.py |
Shares URL-segment validation and encoding. |
packages/uipath-platform/src/uipath/platform/documents/_documents_service_v2.py |
Implements folder resolution and model extraction methods. |
packages/uipath-platform/src/uipath/platform/documents/__init__.py |
Exports the new response types. |
packages/uipath-platform/pyproject.toml |
Bumps the platform package to 0.3.11. |
Review effort: Balanced
Every other service that looks up folder keys gets its FolderService from UiPath, so DocumentsServiceV2 now takes an optional folders_service too, instead of creating its own. Without one, a folder path lookup raises a ValueError. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
🚨 Heads up:
|
start_model_extraction_async opened the file with a blocking open(). It now reads the file in a worker thread, like BucketsService uploads, and keeps the file name so the upload keeps its content type. The folder-model exception tests now make a single call inside each pytest.raises block. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
🚨 Heads up:
|
…der-models # Conflicts: # packages/uipath-platform/pyproject.toml # packages/uipath-platform/uv.lock # packages/uipath/uv.lock
StartOperationResponse and StartModelExtractionResponse both get operation_id, document_id and the alias config from a private _StartOperationBase. StartModelExtractionResponse still isn't a StartOperationResponse: a model deployed to a folder has no project or tag, and folder routes are API v2 only. The project start responses keep the same fields, order, JSON schema and serialized JSON. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
_wait_until_complete polls a single-check retrieve until it stops raising OperationNotCompleteException. extract_with_model waits through it on retrieve_model_extraction_result, and _wait_for_operation (digitization, extraction, classification, validation) is now a thin adapter over it. Changes for existing blocking methods: - no sleep after the last check, so each wait returns up to polling_interval (2 s) sooner; - a failure returned near the timeout raises the failure's RuntimeError, not TimeoutError. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
|




What
DocumentsServiceV2can now extract with IXP models deployed to an Orchestrator folder. These models have their own DU Framework v2 routes (du_/api/framework/models/{name}/…), addressed by model name and folder key, and can't be reached through a project and tag.New methods on
DocumentsServiceV2only, each with an_asynctwin:start_model_extraction(model_name, file | file_path, folder_key=None, folder_path=None): digitizes the document, then starts the extraction. It returns aStartModelExtractionResponse.retrieve_model_extraction_result(start_response): checks once. It raisesOperationNotCompleteExceptionwhile the extraction runs, andOperationFailedExceptionif it failed.extract_with_model(...):start_model_extraction, thenretrieve_model_extraction_resultuntil the result is ready. It returns aModelExtractionResponse.How the methods pick the folder:
folder_keyfirst. Otherwisefolder_path, whose key is looked up. Otherwise the job's folder (UIPATH_FOLDER_KEY, thenUIPATH_FOLDER_PATH).ValueErrorwhen no folder is available, when both a key and a path are given, or when the key isn't a GUID.model_nameis the model's URL name (for exampleinvoices-08963f00-ixp), not its display name. It gets the same encoding and./..checks as the project routes.UiPath().documents(API v1.1) is unchanged.Why separate methods instead of new
extractparametersFolder models differ from projects in more than how they are addressed:
Separate response types also mean a folder-model result can't be passed by mistake to the project-based validation methods or resume triggers, which build project and tag URLs.
The start/retrieve pair is what resume triggers will need. The blocking method is built on that pair, so there is one code path.
StartModelExtractionResponsesharesoperation_id,document_idand the alias config withStartOperationResponsethrough a private base. It doesn't inherit fromStartOperationResponse, because that requires a project and defaultsapi_versionto1.1. The project start responses are unchanged: same fields, order, JSON schema and JSON.One polling loop for all documents operations
Blocking methods now wait through one loop,
_wait_until_complete. It calls a single-check retrieve until that stops raisingOperationNotCompleteException.extract_with_modelwaits onretrieve_model_extraction_result. The existing_wait_for_operation, used for digitization, extraction, classification and validation on both API versions, is now an adapter over the same loop.Effects on existing blocking methods such as
extractandclassify:polling_interval(2 s) sooner, andextractwaits twice: for the digitization, then for the extraction.Failedstatus returned just before the deadline raisedTimeoutError. Now it raises the failure'sRuntimeError.Return values and exception types are otherwise unchanged.
Follow-ups
How it was tested
test_documents_service_v2.py, sync and async:documents(v1.1) doesn't get the new methods.uipath-platformsuite: 2341 passed, after merging the latestmain. New tests check that the shared loop sleeps only between checks and reports a failure near the timeout as the failure. Both fail against the old loop. ruff and mypy are clean.folder_keyfolder_pathUIPATH_FOLDER_KEYDefault.details.nameOperationFailedExceptionwithModelNotFoundErrorFolderAccessForbiddenErrorFolderNotFoundException, before any DU requestKnown issue (not new): a document passed as raw
bytesis rejected withUnsupportedContentTypeError, because it is uploaded without a file name or content type. The existingextractbehaves the same way on both API versions. A file path or an open file works. This will be fixed separately.uipath-platform0.3.12 → 0.3.13.Ported from #1933 by Thomas Lammers, which this replaces.
🤖 Generated with Claude Code