clerk-sdk 0.2.5__py3-none-any.whl → 0.2.6__py3-none-any.whl

clerk/gui_automation/client.py

@@ -11,6 +11,7 @@ from clerk.gui_automation.ui_state_inspector.models import (
     TargetWithAnchor,
 )
 from clerk.models.remote_device import RemoteDevice
+from clerk.models.ui_operator import UiOperatorTask
 
 
 class RPAClerk(BaseClerk):
@@ -46,6 +47,16 @@ class RPAClerk(BaseClerk):
             raise RuntimeError("No coordinates found in the response.")
         return Coords(**res.data[0])
 
+    def create_ui_operator_task(self, payload: Dict) -> UiOperatorTask:
+        endpoint = "/ui_operator"
+        res = self.post_request(endpoint=endpoint, json=payload)
+        return UiOperatorTask(**res.data[0])
+
+    def get_ui_operator_task(self, id: str) -> UiOperatorTask:
+        endpoint = "/ui_operator"
+        res = self.get_request(endpoint=endpoint, params={"task_id": id})
+        return UiOperatorTask(**res.data[0])
+
 
 class GUIVisionClerk(BaseClerk):
     root_endpoint: str = "/gui_automation/vision"

clerk/gui_automation/client_actor/client_actor.py

@@ -66,7 +66,7 @@ async def _get_screen_async() -> str:
         and returns the base64 encoded image of the screen captured.
     """
     payload = {
-        "proc_inst_id": os.getenv("PROC_ID"),
+        "proc_inst_id": os.getenv("_run_id"),
         "client_name": os.getenv("REMOTE_DEVICE_NAME"),
         "headless": True,
         "action": {"action_type": "screenshot"},
@@ -132,7 +132,7 @@ async def _perform_action_async(
         PerformActionException: If the action fails with an error message.
     """
     req_payload: Dict = {
-        "proc_inst_id": os.getenv("PROC_ID"),
+        "proc_inst_id": os.getenv("_run_id"),
         "client_name": os.getenv("REMOTE_DEVICE_NAME"),
         "headless": (
             True if os.getenv("HEADLESS", "True").lower() == "true" else False

clerk/gui_automation/decorators/gui_automation.py

@@ -95,7 +95,8 @@ def gui_automation(
         def wrapper(payload: ClerkCodePayload, *args, **kwargs):
             global global_ws
             force_deallocate = False
-            os.environ["PROC_ID"] = payload.run_id
+            os.environ["_document_id"] = payload.document.id
+            os.environ["_run_id"] = payload.run_id
 
             remote_device = _allocate_remote_device(
                 clerk_client, group_name, payload.run_id
@@ -122,12 +123,17 @@ def gui_automation(
                     raise WebSocketConnectionFailed()
 
             except Exception as e:
-                os.environ.pop("PROC_ID", None)
                 force_deallocate = True
                 raise
             finally:
+                os.environ.pop("_run_id", None)
+                os.environ.pop("_document_id", None)
                 if not reserve_client or force_deallocate:
                     _deallocate_target(clerk_client, remote_device, payload.run_id)
+                else:
+                    logger.warning(
+                        f"The client stayed reserved for the this run id: {payload.run_id}"
+                    )
 
                 if global_ws and global_ws.state is State.OPEN:
                     close_task = event_loop.create_task(close_ws_connection(global_ws))

clerk/gui_automation/ui_actions/support.py

@@ -1,10 +1,16 @@
+from datetime import timedelta, datetime
 import os
 import base64
+import time
 from typing import Optional
 from backoff._typing import Details
 
+from clerk.models.ui_operator import TaskStatuses, UiOperatorTask
 from clerk.utils.save_artifact import save_artifact
+from clerk.utils import logger
 from ..client_actor import get_screen
+from ..ui_actions.base import BaseAction
+from ..decorators.gui_automation import clerk_client
 
 
 _MAP = {
@@ -54,6 +60,23 @@ def save_screenshot(filename: str, sub_folder: Optional[str] = None) -> str:
     )
 
 
+def _format_action_string(action: BaseAction) -> str:
+    """
+    Formats action in the same format as the one used in task modules.
+    """
+    action_string = (
+        f"{action.__class__.__name__}(target='{action.target_name or action.target}')"
+    )
+    for anchor in action.anchors:
+        action_string += f".{anchor.relation}('{anchor.value}')"
+    if action.click_offset != [0, 0]:
+        action_string += (
+            f".offset(x={action.click_offset[0]}, y={action.click_offset[1]})"
+        )
+    action_string += ".do()"
+    return action_string
+
+
 def maybe_engage_operator_ui_action(details: Details) -> None:
     """
     Makes a call to the operator queue server to create an issue and waits for the allotted time for it to be resolved.
@@ -62,8 +85,40 @@ def maybe_engage_operator_ui_action(details: Details) -> None:
     :raises: The exception raised by the action if the issue is not resolved within the allotted time
     """
     # Determine if the operator should be engaged
-    use_operator = strtobool(os.getenv("USE_OPERATOR", default="False"))
-    if not use_operator:
+    ui_operator_enabled = strtobool(os.getenv("_ui_operator_enabled", default="False"))
+
+    if not ui_operator_enabled:
         raise details["exception"]  # type: ignore
 
-    raise NotImplementedError("Feature not yet implemented")
+    ui_operator_pooling_interval = int(os.getenv("_ui_operator_pooling_interval", "1"))
+    ui_operator_timeout = int(os.getenv("_ui_operator_timeout", "3600"))
+    resolution_deadline = datetime.now() + timedelta(seconds=ui_operator_timeout)
+
+    # Extract the action object from the details dictionary
+    action: BaseAction = details["args"][0]
+    issue_description = _format_action_string(action)
+
+    # create ui operator task
+    payload = {
+        "document_id": os.getenv("_document_id"),
+        "remote_device_id": os.getenv("REMOTE_DEVICE_ID"),
+        "issue_description": issue_description,
+    }
+    task: UiOperatorTask = clerk_client.create_ui_operator_task(payload)
+    while datetime.now() < resolution_deadline:
+        task: UiOperatorTask = clerk_client.get_ui_operator_task(task.id)
+        if task.status == TaskStatuses.COMPLETED:
+            logger.debug(
+                f"The ui operator task {task.id} has been resolved by {task.assignee_name}"
+            )
+            return
+        elif task.status == TaskStatuses.CANCELLED:
+            logger.warning(f"The ui operator task {task.id} has been cancelled")
+            raise details["exception"]
+
+        time.sleep(ui_operator_pooling_interval)
+
+    logger.warning(
+        f"The ui operator task {task.id} was not resolved after {ui_operator_timeout} seconds"
+    )
+    raise details["exception"]

clerk/gui_automation/ui_state_machine/state_machine.py

@@ -44,6 +44,9 @@ class ScreenPilot:
         tolerate_repeat_transitions (int): Number of repeated transitions to tolerate before breaking the execution. Default 5.
         tolerate_repeat_states (int): Number of repeated states to tolerate before breaking the execution. Default 5.
         enable_force_close_app_process (bool): If true, terminates the application process via `taskkill` command. Default False.
+        ui_operator_enabled (bool): if true, enables the creation of ui operator task which needs to be resolved in Clerk.
+        ui_operator_pooling_interval (int): in seconds, defines the time pooling interval for ui operator task. Default 1.
+        ui_operator_timeout (int): in seconds, defines the max waiting time for the ui operator task to be resolved before raising and exception.
         process_name (Optional[str]): Name of the process that needs to be closed (ie. process.exe). Required attribute if `enable_force_close_app_process` is True
 
     Methods:
@@ -63,6 +66,9 @@ class ScreenPilot:
     tolerate_repeat_transitions: int = 5
     tolerate_repeat_states: int = 5
     enable_force_close_app_process: bool = False
+    ui_operator_enabled: bool = False
+    ui_operator_pooling_interval: int = 1  # seconds
+    ui_operator_timeout: int = 3600  # seconds (1 hour)
     process_name: Optional[str] = None
     _acted_since_state_eval: bool = False
     _ai_recovery_agent: Optional[CourseCorrector] = None
@@ -716,6 +722,14 @@ class ScreenPilot:
         """
         return None
 
+    @classmethod
+    def _initialize_env_variables(cls):
+        os.environ["_ui_operator_enabled"] = str(cls.ui_operator_enabled)
+        os.environ["_ui_operator_pooling_interval"] = str(
+            cls.ui_operator_pooling_interval
+        )
+        os.environ["_ui_operator_timeout"] = str(cls.ui_operator_timeout)
+
     @classmethod
     def run(
         cls, goal_function: Optional[Callable] = None, **kwargs
@@ -732,6 +746,8 @@ class ScreenPilot:
         Returns:
                 - Exit reason (ScreenPilotOutcome): Exception class that interrupted the state machine execution.
         """
+        cls._initialize_env_variables()
+
         if not goal_function:
             goal_function = cls._default_goal_function
         cls._act_on_start()

clerk/models/ui_operator.py

@@ -0,0 +1,15 @@
+from enum import Enum
+from typing import Optional
+from pydantic import BaseModel
+
+
+class TaskStatuses(str, Enum):
+    OPEN = "open"
+    COMPLETED = "completed"
+    CANCELLED = "cancelled"
+
+
+class UiOperatorTask(BaseModel):
+    id: str
+    status: TaskStatuses
+    assignee_name: Optional[str]

{clerk_sdk-0.2.5.dist-info → clerk_sdk-0.2.6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clerk-sdk
-Version: 0.2.5
+Version: 0.2.6
 Summary: Library for interacting with Clerk
 Home-page: https://github.com/F-ONE-Group/clerk_pypi
 Author: F-ONE Group

{clerk_sdk-0.2.5.dist-info → clerk_sdk-0.2.6.dist-info}/RECORD

@@ -5,16 +5,16 @@ clerk/decorator/__init__.py,sha256=4VCGOFNq7pA7iJS410V_R9eWfjxP7mwxwa4thwaUTf8,3
 clerk/decorator/models.py,sha256=JWFOJuUh3F40iOL0aoNgUC9GRHU3Fcq3GOjSXA7Gwng,394
 clerk/decorator/task_decorator.py,sha256=srb8AC3tNj1RWC4iNkkwkUuG33B8TtxfTpOm1Oi373Y,2169
 clerk/gui_automation/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-clerk/gui_automation/client.py,sha256=LJFHdWreH0pZnRUZJ6jd4Xp3kYJjOjNLEUfHD0ly2Y0,4405
+clerk/gui_automation/client.py,sha256=LqrUQtC-4pjUJYDDn_s3t073K066j_p0vf4kXLChBc0,4891
 clerk/gui_automation/action_model/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 clerk/gui_automation/action_model/model.py,sha256=sbTySgOq4Xv_r2p7q_ji1bGCHgRS1HXC9Z39thwCQ9c,3829
 clerk/gui_automation/action_model/utils.py,sha256=xzFxgN-bTK6HKGS7J-esQZ-ePj_yG72T-2ZVhcWvKjw,798
 clerk/gui_automation/client_actor/__init__.py,sha256=SVuL6-oo1Xc0oJkjMKrO6mJwpPGjrCLKhDV6r2Abtf8,66
-clerk/gui_automation/client_actor/client_actor.py,sha256=Me3NHc0nMA7Y5CUcnE0ZHT1P7dQRGR6duCAKwn0Tg6g,5081
+clerk/gui_automation/client_actor/client_actor.py,sha256=YVYBgDQ89NkgdlWSk_AvDtEO_BJe5YIHU5OJK4cUs28,5081
 clerk/gui_automation/client_actor/exception.py,sha256=zdnImHZ88yf52Xq3aMHivEU3aJg-r2c-r8x8XZnI3ic,407
 clerk/gui_automation/client_actor/model.py,sha256=wVpFCi1w2kh4kAV8oNx489vf_SLUQnqhc02rFD5NIJA,6335
 clerk/gui_automation/decorators/__init__.py,sha256=OCgXStEumscgT-RyVy5OKS7ml1w9y-lEnjCVnxuRnQs,43
-clerk/gui_automation/decorators/gui_automation.py,sha256=0p83i6bu6f2syxfOy96oRnNMVc2ZBKYfNJIE1sE1xYA,5064
+clerk/gui_automation/decorators/gui_automation.py,sha256=7p3xU2biyHN43hgEAGj34QJjHF2SeBDM6FRCx_eqewM,5350
 clerk/gui_automation/exceptions/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 clerk/gui_automation/exceptions/agent_manager.py,sha256=KFWFWQ7X_8Z9XG__SMzb1jKI3yNoVTPJAXzW5O-fSXc,101
 clerk/gui_automation/exceptions/websocket.py,sha256=-MdwSwlf1hbnu55aDgk3L1znkTZ6xJS6po5VpEGD9ck,117
@@ -23,7 +23,7 @@ clerk/gui_automation/exceptions/modality/exc.py,sha256=P-dMuCTyVZYD3pbGpCf_1SYEg
 clerk/gui_automation/ui_actions/__init__.py,sha256=-EDQ5375HXrvG3sfFY7zOPC405YcBL6xXRACm2p-YyI,23
 clerk/gui_automation/ui_actions/actions.py,sha256=hhxl5VMDNSXdqm2L0tZqs6IhJHVXtlSVSdwsiz2BbDI,27449
 clerk/gui_automation/ui_actions/base.py,sha256=4CjOkMZNLt8W0tLO91tOkz8CCea0m2IRBIOpWNMOZUA,7230
-clerk/gui_automation/ui_actions/support.py,sha256=BS9QReyP_F9-oGPt0fuy5BD9kC9-E5mOE05Zk0M1Hzw,2176
+clerk/gui_automation/ui_actions/support.py,sha256=83D-oVmZxD507kh9-8PsoXt5zD4o225TmkmS0Kh_8Zo,4330
 clerk/gui_automation/ui_state_inspector/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 clerk/gui_automation/ui_state_inspector/gui_vision.py,sha256=lRnF3IMLViOB-UE447A4kc8BO7NKqqLV1NZKRswRKWg,7707
 clerk/gui_automation/ui_state_inspector/models.py,sha256=uuzYhE9is4Z-TmsVMA1mwf0mQGs_PDLqdSZKbe8dHSs,5691
@@ -32,18 +32,19 @@ clerk/gui_automation/ui_state_machine/ai_recovery.py,sha256=3_Gu_RPxta4eXmXWH3WA
 clerk/gui_automation/ui_state_machine/decorators.py,sha256=gBOpIusjsXlA7FEiszDCFKTS6vXx3LBNMz_SQJNkMWg,2134
 clerk/gui_automation/ui_state_machine/exceptions.py,sha256=9KWg20dnCssMdMu632E0nP5vkndgYNI4cDCDW-vMkQA,1436
 clerk/gui_automation/ui_state_machine/models.py,sha256=1fpNYPsff0dyLg1wNJl-xQyMYvy4cSDy4OLxa0ej-0U,1395
-clerk/gui_automation/ui_state_machine/state_machine.py,sha256=6WJQ5NsI9hOqN-VM0lYf_mv-xOQd0UjolGXJ0M58L1I,35230
+clerk/gui_automation/ui_state_machine/state_machine.py,sha256=2OfN17N_8dzhul2X19koqGWDZbgjeJu7ExTLpVzf1OA,36130
 clerk/models/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 clerk/models/document.py,sha256=Bbt3YSvGcOrJJjJBYjbDGXpZIaQAYdq_-uIr2urwy5s,525
 clerk/models/document_statuses.py,sha256=ytTQhgACs2m22qz51_7Ti0IxzbVyl-fl7uF7CnDEyLA,279
 clerk/models/file.py,sha256=7n6bV6ukRA-uh7MFxUx_TEMNpVAdNe5O0nKIeneCQhg,459
 clerk/models/remote_device.py,sha256=2jijS-9WWq7y6xIbAaDaPnzZo3-tjp2-dCQvNKP8YSU,109
 clerk/models/response_model.py,sha256=R62daUN1YVOwgnrh_epvFRsQcOwT7R4u97l73egvm-c,232
+clerk/models/ui_operator.py,sha256=mKTJUFZgv7PeEt5oys28HVZxHOJsofmRQOcRpqj0dbU,293
 clerk/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 clerk/utils/logger.py,sha256=_jYOSEc1WCsY9DvU8cIWUPmz41QNjpHTEZ7WrUnmFPA,3650
 clerk/utils/save_artifact.py,sha256=Lwl3l3QqKnSFLFpfEEa-dJ-dV9OxvCU3ADkuYZ18U-Q,1117
-clerk_sdk-0.2.5.dist-info/licenses/LICENSE,sha256=GTVQl3vH6ht70wJXKC0yMT8CmXKHxv_YyO_utAgm7EA,1065
-clerk_sdk-0.2.5.dist-info/METADATA,sha256=5X609M2WJHnk6rKf0diLFtkS42gDhJ4zi5ZCYMPsxXY,3508
-clerk_sdk-0.2.5.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-clerk_sdk-0.2.5.dist-info/top_level.txt,sha256=99eQiU6d05_-f41tmSFanfI_SIJeAdh7u9m3LNSfcv4,6
-clerk_sdk-0.2.5.dist-info/RECORD,,
+clerk_sdk-0.2.6.dist-info/licenses/LICENSE,sha256=GTVQl3vH6ht70wJXKC0yMT8CmXKHxv_YyO_utAgm7EA,1065
+clerk_sdk-0.2.6.dist-info/METADATA,sha256=mC8t5huCNbfWuHZ2dy4O3d0-XMHx8yy8n1cFCgLbhzk,3508
+clerk_sdk-0.2.6.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+clerk_sdk-0.2.6.dist-info/top_level.txt,sha256=99eQiU6d05_-f41tmSFanfI_SIJeAdh7u9m3LNSfcv4,6
+clerk_sdk-0.2.6.dist-info/RECORD,,