feat(Documents): add support for modern projects

Author: alexandrujircan

src/uipath/_services/documents_service.py

@@ -13,6 +13,7 @@
 from ..models.documents import (
     ActionPriority,
     ExtractionResponse,
+    ProjectType,
     ValidatedResult,
     ValidationAction,
 )
@@ -37,11 +38,13 @@ def _get_common_headers(self) -> Dict[str, str]:
             "X-UiPath-Internal-ConsumptionSourceType": "CodedAgents",
         }
 
-    def _get_project_id_by_name(self, project_name: str) -> str:
+    def _get_project_id_by_name(
+        self, project_name: str, project_type: ProjectType
+    ) -> str:
         response = self.request(
             "GET",
             url=Endpoint("/du_/api/framework/projects"),
-            params={"api-version": 1.1, "type": "IXP"},
+            params={"api-version": 1.1},
             headers=self._get_common_headers(),
         )
 
@@ -89,8 +92,10 @@ async def _get_project_tags_async(self, project_id: str) -> Set[str]:
         )
         return {tag["name"] for tag in response.json().get("tags", [])}
 
-    def _get_project_id_and_validate_tag(self, project_name: str, tag: str) -> str:
-        project_id = self._get_project_id_by_name(project_name)
+    def _get_project_id_and_validate_tag(
+        self, project_name: str, project_type: ProjectType, tag: str
+    ) -> str:
+        project_id = self._get_project_id_by_name(project_name, project_type)
         tags = self._get_project_tags(project_id)
         if tag not in tags:
             raise ValueError(
@@ -143,16 +148,39 @@ async def _start_digitization_async(
             )
         ).json()["documentId"]
 
+    def _get_document_type_id(
+        self, project_id: str, extractor_name: Optional[str]
+    ) -> str:
+        if extractor_name is None:
+            return str(UUID(int=0))
+
+        response = self.request(
+            "GET",
+            url=Endpoint(f"/du_/api/framework/projects/{project_id}/extractors"),
+            params={"api-version": 1.1},
+            headers=self._get_common_headers(),
+        )
+
+        try:
+            return next(
+                extractor["documentTypeId"]
+                for extractor in response.json().get("extractors", [])
+                if extractor["projectVersionName"] == extractor_name
+            )
+        except StopIteration:
+            raise ValueError(f"Extractor '{extractor_name}' not found.") from None
+
     def _start_extraction(
         self,
         project_id: str,
         tag: str,
+        document_type_id: str,
         document_id: str,
     ) -> str:
         return self.request(
             "POST",
             url=Endpoint(
-                f"/du_/api/framework/projects/{project_id}/{tag}/document-types/{UUID(int=0)}/extraction/start"
+                f"/du_/api/framework/projects/{project_id}/{tag}/document-types/{document_type_id}/extraction/start"
             ),
             params={"api-version": 1.1},
             headers=self._get_common_headers(),
@@ -179,7 +207,7 @@ async def _start_extraction_async(
 
     def _wait_for_operation(
         self,
-        result_getter: Callable[[], Tuple[str, Any]],
+        result_getter: Callable[[], Tuple[str, dict, Any]],
         wait_statuses: List[str],
         success_status: str,
     ) -> Any:
@@ -191,13 +219,15 @@ def _wait_for_operation(
             status in wait_statuses
             and (time.monotonic() - start_time) < POLLING_TIMEOUT
         ):
-            status, result = result_getter()
+            status, error, result = result_getter()
             time.sleep(POLLING_INTERVAL)
 
         if status != success_status:
             if time.monotonic() - start_time >= POLLING_TIMEOUT:
                 raise TimeoutError("Operation timed out.")
-            raise RuntimeError(f"Operation failed with status: {status}")
+            raise RuntimeError(
+                f"Operation failed with status: {status}, error: {error}"
+            )
 
         return result
 
@@ -226,20 +256,21 @@ async def _wait_for_operation_async(
         return result
 
     def _wait_for_extraction(
-        self, project_id: str, tag: str, operation_id: str
+        self, project_id: str, tag: str, document_type_id: str, operation_id: str
     ) -> ExtractionResponse:
         extraction_response = self._wait_for_operation(
             result_getter=lambda: (
                 (
                     result := self.request(
                         method="GET",
                         url=Endpoint(
-                            f"/du_/api/framework/projects/{project_id}/{tag}/document-types/{UUID(int=0)}/extraction/result/{operation_id}"
+                            f"/du_/api/framework/projects/{project_id}/{tag}/document-types/{document_type_id}/extraction/result/{operation_id}"
                         ),
                         params={"api-version": 1.1},
                         headers=self._get_common_headers(),
                     ).json()
                 )["status"],
+                result.get("error", None),
                 result.get("result", None),
             ),
             wait_statuses=["NotStarted", "Running"],
@@ -248,12 +279,13 @@ def _wait_for_extraction(
 
         extraction_response["projectId"] = project_id
         extraction_response["tag"] = tag
+        extraction_response["documentTypeId"] = document_type_id
         return ExtractionResponse.model_validate(extraction_response)
 
     async def _wait_for_extraction_async(
         self, project_id: str, tag: str, operation_id: str
     ) -> ExtractionResponse:
-        async def result_getter() -> Tuple[str, Any]:
+        async def result_getter() -> Tuple[str, str, Any]:
             result = await self.request_async(
                 method="GET",
                 url=Endpoint(
@@ -263,7 +295,11 @@ async def result_getter() -> Tuple[str, Any]:
                 headers=self._get_common_headers(),
             )
             json_result = result.json()
-            return json_result["status"], json_result.get("result", None)
+            return (
+                json_result["status"],
+                json_result.get("error", None),
+                json_result.get("result", None),
+            )
 
         extraction_response = await self._wait_for_operation_async(
             result_getter=result_getter,
@@ -282,14 +318,18 @@ def extract(
         tag: str,
         file: Optional[FileContent] = None,
         file_path: Optional[str] = None,
+        project_type: ProjectType = ProjectType.IXP,
+        extractor_name: Optional[str] = None,
     ) -> ExtractionResponse:
         """Extract predicted data from a document using an IXP project.
 
         Args:
-            project_name (str): Name of the IXP project. Details about IXP projects can be found in the [official documentation](https://docs.uipath.com/ixp/automation-cloud/latest/overview/managing-projects#creating-a-new-project).
+            project_name (str): Name of the [IXP](https://docs.uipath.com/ixp/automation-cloud/latest/overview/managing-projects#creating-a-new-project)/[DU Modern](https://docs.uipath.com/document-understanding/automation-cloud/latest/user-guide/about-document-understanding) project.
             tag (str): Tag of the published project version.
             file (FileContent, optional): The document file to be processed.
             file_path (str, optional): Path to the document file to be processed.
+            project_type (ProjectType, optional): Type of the project. Defaults to `ProjectType.IXP`.
+            extractor_name (str, optional): Name of the extractor to be used. Necessary only for DU Modern projects.
 
         Note:
             Either `file` or `file_path` must be provided, but not both.
@@ -313,7 +353,7 @@ def extract(
             raise ValueError("`file` and `file_path` are mutually exclusive")
 
         project_id = self._get_project_id_and_validate_tag(
-            project_name=project_name, tag=tag
+            project_name=project_name, project_type=project_type, tag=tag
         )
 
         if file_path is not None:
@@ -324,12 +364,22 @@ def extract(
         else:
             document_id = self._start_digitization(project_id=project_id, file=file)  # type: ignore
 
+        document_type_id = self._get_document_type_id(
+            project_id=project_id, extractor_name=extractor_name
+        )
+
         operation_id = self._start_extraction(
-            project_id=project_id, tag=tag, document_id=document_id
+            project_id=project_id,
+            tag=tag,
+            document_type_id=document_type_id,
+            document_id=document_id,
         )
 
         return self._wait_for_extraction(
-            project_id=project_id, tag=tag, operation_id=operation_id
+            project_id=project_id,
+            tag=tag,
+            document_type_id=document_type_id,
+            operation_id=operation_id,
         )
 
     @traced(name="documents_extract_async", run_type="uipath")
@@ -373,6 +423,7 @@ def _start_validation(
         self,
         project_id: str,
         tag: str,
+        document_type_id: str,
         action_title: str,
         action_priority: ActionPriority,
         action_catalog: str,
@@ -384,7 +435,7 @@ def _start_validation(
         return self.request(
             "POST",
             url=Endpoint(
-                f"/du_/api/framework/projects/{project_id}/{tag}/document-types/{UUID(int=0)}/validation/start"
+                f"/du_/api/framework/projects/{project_id}/{tag}/document-types/{document_type_id}/validation/start"
             ),
             params={"api-version": 1.1},
             headers=self._get_common_headers(),
@@ -471,6 +522,7 @@ def _wait_for_create_validation_action(
                         project_id=project_id, tag=tag, operation_id=operation_id
                     )
                 )["status"],
+                result.get("error", None),
                 result.get("result", None),
             ),
             wait_statuses=["NotStarted", "Running"],
@@ -485,11 +537,15 @@ def _wait_for_create_validation_action(
     async def _wait_for_create_validation_action_async(
         self, project_id: str, tag: str, operation_id: str
     ) -> ValidationAction:
-        async def result_getter() -> Tuple[str, Any]:
+        async def result_getter() -> Tuple[str, str, Any]:
             result = await self._get_validation_result_async(
                 project_id=project_id, tag=tag, operation_id=operation_id
             )
-            return result["status"], result.get("result", None)
+            return (
+                result["status"],
+                result.get("error", None),
+                result.get("result", None),
+            )
 
         response = await self._wait_for_operation_async(
             result_getter=result_getter,
@@ -542,7 +598,8 @@ def create_validation_action(
         """
         operation_id = self._start_validation(
             project_id=extraction_response.project_id,
-            tag=extraction_response.tag,  # should I validate tag again?
+            tag=extraction_response.tag,
+            document_type_id=extraction_response.document_type_id,
             action_title=action_title,
             action_priority=action_priority,
             action_catalog=action_catalog,
@@ -573,7 +630,7 @@ async def create_validation_action_async(
         # Add reference to sync method docstring
         operation_id = await self._start_validation_async(
             project_id=extraction_response.project_id,
-            tag=extraction_response.tag,  # should I validate tag again?
+            tag=extraction_response.tag,
             action_title=action_title,
             action_priority=action_priority,
             action_catalog=action_catalog,
@@ -618,6 +675,7 @@ def get_validation_result(
                         operation_id=validation_action.operation_id,
                     )
                 )["result"]["actionStatus"],
+                None,
                 result["result"].get("validatedExtractionResults", None),
             ),
             wait_statuses=["Unassigned", "Pending"],

src/uipath/models/documents.py

@@ -24,6 +24,11 @@ class ActionPriority(str, Enum):
     CRITICAL = "Critical"
 
 
+class ProjectType(str, Enum):
+    IXP = "IXP"
+    MODERN = "Modern"
+
+
 class FieldValueProjection(BaseModel):
     model_config = ConfigDict(
         serialize_by_alias=True,
@@ -71,9 +76,9 @@ class ExtractionResponse(BaseModel):
 
     Attributes:
         extraction_result (ExtractionResult): The result of the extraction process.
-        data_projection (List[FieldGroupValueProjection]): A simplified projection of the extracted data.
         project_id (str): The ID of the project associated with the extraction.
         tag (str): The tag associated with the published model version.
+        document_type_id (str): The ID of the document type associated with the extraction.
     """
 
     model_config = ConfigDict(
@@ -82,9 +87,19 @@ class ExtractionResponse(BaseModel):
     )
 
     extraction_result: ExtractionResult = Field(alias="extractionResult")
-    data_projection: List[FieldGroupValueProjection] = Field(alias="dataProjection")
     project_id: str = Field(alias="projectId")
     tag: str
+    document_type_id: str = Field(alias="documentTypeId")
+
+
+class ExtractionResponseIXP(ExtractionResponse):
+    """A model representing the response from a document extraction process for IXP projects.
+
+    Attributes:
+        data_projection (List[FieldGroupValueProjection]): A simplified projection of the extracted data.
+    """
+
+    data_projection: List[FieldGroupValueProjection] = Field(alias="dataProjection")
 
 
 class ValidationAction(BaseModel):