Skip to content

feat(documents): extract with IXP models deployed to a folder - #2004

Open
alexandrujircan wants to merge 6 commits into
mainfrom
feat/documents-v2-folder-models
Open

alexandrujircan wants to merge 6 commits into
mainfrom
feat/documents-v2-folder-models

Conversation

@alexandrujircan

@alexandrujircan alexandrujircan commented Nov 19, 2026 •

Copy link
Copy Markdown
Collaborator

What

DocumentsServiceV2 can 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 DocumentsServiceV2 only, each with an _async twin:

  • start_model_extraction(model_name, file | file_path, folder_key=None, folder_path=None): digitizes the document, then starts the extraction. It returns a StartModelExtractionResponse.
  • retrieve_model_extraction_result(start_response): checks once. It raises OperationNotCompleteException while the extraction runs, and OperationFailedException if it failed.
  • extract_with_model(...): start_model_extraction, then retrieve_model_extraction_result until the result is ready. It returns a ModelExtractionResponse.
response = UiPath().documents_v2.extract_with_model(
    model_name="invoices-ixp",
    file_path="invoice.pdf",
    folder_path="Shared/Invoices",
)

How the methods pick the folder:

  • Order: folder_key first. Otherwise folder_path, whose key is looked up. Otherwise the job's folder (UIPATH_FOLDER_KEY, then UIPATH_FOLDER_PATH).
  • Errors: they raise ValueError when no folder is available, when both a key and a path are given, or when the key isn't a GUID.
  • Why a key: these routes accept only a GUID folder key, not a folder path.

model_name is the model's URL name (for example invoices-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 extract parameters

Folder models differ from projects in more than how they are addressed:

  • extraction is async only, and there is no classification;
  • results have no data projection, and nothing in them identifies the model;
  • validation is a separate flow.

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.

StartModelExtractionResponse shares operation_id, document_id and the alias config with StartOperationResponse through a private base. It doesn't inherit from StartOperationResponse, because that requires a project and defaults api_version to 1.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 raising OperationNotCompleteException. extract_with_model waits on retrieve_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 extract and classify:

  • No sleep after the last check. Each wait returns up to polling_interval (2 s) sooner, and extract waits twice: for the digitization, then for the extraction.
  • A failure near the timeout is reported as the failure. Before, a Failed status returned just before the deadline raised TimeoutError. Now it raises the failure's RuntimeError.

Return values and exception types are otherwise unchanged.

Follow-ups

How it was tested

  • Unit tests in test_documents_service_v2.py, sync and async:
    • the full flow, including the folder key header and the uploaded file;
    • PascalCase responses;
    • folder resolution from an explicit path, the job folder key and the job folder path;
    • invalid arguments: no folder, both a key and a path, a key that isn't a GUID, and dot or empty model names;
    • the start/retrieve pair, with the start response rebuilt from JSON as triggers will do;
    • failed and timed-out extractions;
    • documents (v1.1) doesn't get the new methods.
  • uipath-platform suite: 2341 passed, after merging the latest main. 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.
  • Live on alpha, with models deployed to a personal workspace folder:
Scenario Result
Sync, folder_key Extracted in about 11 s
Async, folder_path The path resolved to its key, then extracted
Start, then retrieve, with the job folder from UIPATH_FOLDER_KEY Not complete twice, then the result
Model with a field group Values with v2 field IDs, e.g. Default.details.name
Unknown model, or the right model in another folder OperationFailedException with ModelNotFoundError
Unknown folder key 403 FolderAccessForbiddenError
Unknown folder path FolderNotFoundException, before any DU request

Known issue (not new): a document passed as raw bytes is rejected with UnsupportedContentTypeError, because it is uploaded without a file name or content type. The existing extract behaves the same way on both API versions. A file path or an open file works. This will be fixed separately.

uipath-platform 0.3.12 → 0.3.13.

Ported from #1933 by Thomas Lammers, which this replaces.

🤖 Generated with Claude Code

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>
Copilot AI balanced review requested due to automatic review settings November 19, 2026 07:54
@github-actions github-actions Bot added test:uipath-langchain Triggers tests in the uipath-langchain-python repository test:uipath-integrations labels Nov 19, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 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-platform to 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>
@github-actions

Copy link
Copy Markdown

🚨 Heads up: uipath-langchain cross-tests are FAILING 🚨

Your changes may break the uipath-langchain-python integration.

⚠️ These checks are NOT enforced by branch protection rules. Please review the failures before merging.

🔍 Inspect the failed run →

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>
@github-actions

Copy link
Copy Markdown

🚨 Heads up: uipath-integrations cross-tests are FAILING 🚨

Your changes may break one or more integrations in uipath-integrations-python:

  • uipath-openai-agents
  • uipath-google-adk
  • uipath-agent-framework
  • uipath-llamaindex
  • uipath-pydantic-ai

⚠️ These checks are NOT enforced by branch protection rules. Please review the failures before merging.

🔍 Inspect the failed run →

alexandrujircan and others added 3 commits November 20, 2026 12:31
…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>
@sonarqubecloud

Copy link
Copy Markdown

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

test:uipath-integrations test:uipath-langchain Triggers tests in the uipath-langchain-python repository

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants