feat: add support for folder scoped ephemeral index creation [ECS-1745] (#1574)

Author: gcuip

packages/uipath-platform/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "uipath-platform"
-version = "0.1.29"
+version = "0.1.30"
 description = "HTTP client library for programmatic access to UiPath Platform"
 readme = { file = "README.md", content-type = "text/markdown" }
 requires-python = ">=3.11"

packages/uipath-platform/src/uipath/platform/context_grounding/_context_grounding_service.py

@@ -598,20 +598,29 @@ async def create_index_async(
     @resource_override(resource_type="index")
     @traced(name="contextgrounding_create_ephemeral_index", run_type="uipath")
     def create_ephemeral_index(
-        self, usage: EphemeralIndexUsage, attachments: List[str]
+        self,
+        usage: EphemeralIndexUsage,
+        attachments: List[str],
+        folder_key: str | None = None,
+        folder_path: str | None = None,
     ) -> ContextGroundingIndex:
         """Create a new ephemeral context grounding index.
 
         Args:
             usage (EphemeralIndexUsage): The task type for the ephemeral index (DeepRAG or BatchRAG)
             attachments (list[str]): The list of attachments ids from which the ephemeral index will be created
+            folder_key (Optional[str]): The folder key to scope the ephemeral index to.
+            folder_path (Optional[str]): The folder path to scope the ephemeral index to (resolved to a key if folder_key is not provided).
 
         Returns:
             ContextGroundingIndex: The created index information.
         """
+        if folder_key is not None or folder_path is not None:
+            folder_key = self._resolve_folder_key(folder_key, folder_path)
         spec = self._create_ephemeral_spec(
             usage,
             attachments,
+            folder_key=folder_key,
         )
 
         response = self.request(
@@ -626,20 +635,29 @@ def create_ephemeral_index(
     @resource_override(resource_type="index")
     @traced(name="contextgrounding_create_ephemeral_index", run_type="uipath")
     async def create_ephemeral_index_async(
-        self, usage: EphemeralIndexUsage, attachments: List[str]
+        self,
+        usage: EphemeralIndexUsage,
+        attachments: List[str],
+        folder_key: str | None = None,
+        folder_path: str | None = None,
     ) -> ContextGroundingIndex:
         """Create a new ephemeral context grounding index.
 
         Args:
             usage (EphemeralIndexUsage): The task type for the ephemeral index (DeepRAG or BatchRAG)
             attachments (list[str]): The list of attachments ids from which the ephemeral index will be created
+            folder_key (Optional[str]): The folder key to scope the ephemeral index to.
+            folder_path (Optional[str]): The folder path to scope the ephemeral index to (resolved to a key if folder_key is not provided).
 
         Returns:
             ContextGroundingIndex: The created index information.
         """
+        if folder_key is not None or folder_path is not None:
+            folder_key = self._resolve_folder_key(folder_key, folder_path)
         spec = self._create_ephemeral_spec(
             usage,
             attachments,
+            folder_key=folder_key,
         )
 
         response = await self.request_async(
@@ -1991,12 +2009,14 @@ def _create_ephemeral_spec(
         self,
         usage: str,
         attachments: List[str],
+        folder_key: str | None = None,
     ) -> RequestSpec:
         """Create request spec for ephemeral index creation.
 
         Args:
             usage (str): The task in which the ephemeral index will be used for
             attachments (list[str]): The list of attachments ids from which the ephemeral index will be created
+            folder_key (Optional[str]): The folder key to scope the ephemeral index to.
 
         Returns:
             RequestSpec for the create index request
@@ -2012,7 +2032,7 @@ def _create_ephemeral_spec(
             method="POST",
             endpoint=Endpoint("/ecs_/v2/indexes/createephemeral"),
             json=payload.model_dump(by_alias=True, exclude_none=True),
-            headers={},
+            headers={**header_folder(folder_key, None)},
         )
 
     def _build_data_source(self, source: SourceConfig) -> Dict[str, Any]:

packages/uipath-platform/tests/services/test_context_grounding_service.py

@@ -2749,6 +2749,71 @@ async def test_create_ephemeral_index_async(
             == f"UiPath.Python.Sdk/UiPath.Python.Sdk.Activities.ContextGroundingService.create_ephemeral_index_async/{version}"
         )
 
+    def test_create_ephemeral_index_with_folder_key(
+        self,
+        httpx_mock: HTTPXMock,
+        service: ContextGroundingService,
+        base_url: str,
+        org: str,
+        tenant: str,
+    ) -> None:
+        import uuid
+
+        httpx_mock.add_response(
+            url=f"{base_url}{org}{tenant}/ecs_/v2/indexes/createephemeral",
+            status_code=200,
+            json={
+                "id": "ephemeral-index-id",
+                "name": "ephemeral-index",
+                "lastIngestionStatus": "Queued",
+            },
+        )
+
+        attachment_ids = [str(uuid.uuid4())]
+        service.create_ephemeral_index(
+            usage="DeepRAG",
+            attachments=attachment_ids,
+            folder_key="test-folder-key",
+        )
+
+        sent_requests = httpx_mock.get_requests()
+        assert sent_requests is not None
+        assert "x-uipath-folderkey" in sent_requests[0].headers
+        assert sent_requests[0].headers["x-uipath-folderkey"] == "test-folder-key"
+
+    @pytest.mark.anyio
+    async def test_create_ephemeral_index_async_with_folder_key(
+        self,
+        httpx_mock: HTTPXMock,
+        service: ContextGroundingService,
+        base_url: str,
+        org: str,
+        tenant: str,
+    ) -> None:
+        import uuid
+
+        httpx_mock.add_response(
+            url=f"{base_url}{org}{tenant}/ecs_/v2/indexes/createephemeral",
+            status_code=200,
+            json={
+                "id": "ephemeral-index-id",
+                "name": "ephemeral-index",
+                "lastIngestionStatus": "Queued",
+            },
+        )
+
+        attachment_ids = [str(uuid.uuid4())]
+        await service.create_ephemeral_index_async(
+            usage="DeepRAG",
+            attachments=attachment_ids,
+            folder_key="test-folder-key",
+        )
+
+        sent_requests = httpx_mock.get_requests()
+        assert sent_requests is not None
+        assert "x-uipath-folderkey" in sent_requests[0].headers
+        assert sent_requests[0].headers["x-uipath-folderkey"] == "test-folder-key"
+
     @pytest.mark.anyio
     async def test_download_batch_transform_result_async_creates_nested_directories(
         self,