clerk-sdk 0.2.4__tar.gz → 0.2.6__tar.gz

{clerk_sdk-0.2.4/clerk_sdk.egg-info → clerk_sdk-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clerk-sdk
-Version: 0.2.4
+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.4 → clerk_sdk-0.2.6}/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_sdk-0.2.4 → clerk_sdk-0.2.6}/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_sdk-0.2.4 → clerk_sdk-0.2.6}/clerk/gui_automation/decorators/gui_automation.py

@@ -24,7 +24,9 @@ global_ws: Union[ClientConnection, None] = None
 clerk_client = RPAClerk()
 wss_uri = "wss://agent-manager.f-one.group/action"
 
-REMOTE_DEVICE_ALLOCATION_TIMEOUT = int(os.getenv("REMOTE_DEVICE_ALLOCATION_TIMEOUT", 1))
+REMOTE_DEVICE_ALLOCATION_TIMEOUT = int(
+    os.getenv("REMOTE_DEVICE_ALLOCATION_TIMEOUT", 60)
+)
 REMOTE_DEVICE_ALLOCATION_MAX_TRIES = int(
     os.getenv("REMOTE_DEVICE_ALLOCATION_MAX_TRIES", 60)
 )
@@ -48,13 +50,13 @@ def _allocate_remote_device(
 
         except NoClientsAvailable:
             logger.warning(
-                f"No clients are available for {group_name} group. Initiating a {REMOTE_DEVICE_ALLOCATION_TIMEOUT} minute wait. Retry count: {retries}"
+                f"No clients are available for {group_name} group. Initiating a {REMOTE_DEVICE_ALLOCATION_TIMEOUT} seconds wait. Retry count: {retries}"
             )
             if retries >= REMOTE_DEVICE_ALLOCATION_MAX_TRIES:
                 raise ClientAvailabilityTimeout(
-                    f"No clients available for {group_name} group after {REMOTE_DEVICE_ALLOCATION_TIMEOUT * REMOTE_DEVICE_ALLOCATION_MAX_TRIES} minutes"
+                    f"No clients available for {group_name} group after {REMOTE_DEVICE_ALLOCATION_TIMEOUT * REMOTE_DEVICE_ALLOCATION_MAX_TRIES} seconds"
                 )
-            time.sleep(REMOTE_DEVICE_ALLOCATION_TIMEOUT * 60)
+            time.sleep(REMOTE_DEVICE_ALLOCATION_TIMEOUT)
             retries += 1
 
 
@@ -93,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
@@ -120,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_sdk-0.2.6/clerk/gui_automation/ui_actions/support.py

@@ -0,0 +1,124 @@
+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 = {
+    "y": True,
+    "yes": True,
+    "t": True,
+    "true": True,
+    "on": True,
+    "1": True,
+    "n": False,
+    "no": False,
+    "f": False,
+    "false": False,
+    "off": False,
+    "0": False,
+}
+
+
+def strtobool(value):
+    try:
+        return _MAP[str(value).lower()]
+    except KeyError:
+        raise ValueError('"{}" is not a valid bool value'.format(value))
+
+
+def save_screenshot(filename: str, sub_folder: Optional[str] = None) -> str:
+    """
+    Save a screenshot into the process instance folder.
+
+    This function retrieves the base64 representation of the screen from the target environment using the 'get_screen' function.
+    Then, it saves the screenshot into the process instance folder using the 'save_file_into_instance_folder' function.
+
+    Args:
+        filename (str): The name of the file to save the screenshot as.
+        sub_folder (str, optional): The name of the subfolder within the instance folder where the screenshot will be saved. Defaults to None.
+
+    Returns:
+        str: The file path of the saved screenshot.
+
+    """
+    # get the base64 screen from target environment
+    screen_b64: str = get_screen()
+    return save_artifact(
+        filename=filename,
+        file_bytes=base64.b64decode(screen_b64),
+        subfolder=sub_folder,
+    )
+
+
+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.
+    :param details: A dictionary containing the details of the exception raised (https://pypi.org/project/backoff/)
+    :returns: 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
+    ui_operator_enabled = strtobool(os.getenv("_ui_operator_enabled", default="False"))
+
+    if not ui_operator_enabled:
+        raise details["exception"]  # type: ignore
+
+    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_sdk-0.2.4 → clerk_sdk-0.2.6}/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_sdk-0.2.6/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.4 → clerk_sdk-0.2.6/clerk_sdk.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: clerk-sdk
-Version: 0.2.4
+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.4 → clerk_sdk-0.2.6}/clerk_sdk.egg-info/SOURCES.txt

@@ -46,6 +46,7 @@ clerk/models/document_statuses.py
 clerk/models/file.py
 clerk/models/remote_device.py
 clerk/models/response_model.py
+clerk/models/ui_operator.py
 clerk/utils/__init__.py
 clerk/utils/logger.py
 clerk/utils/save_artifact.py

{clerk_sdk-0.2.4 → clerk_sdk-0.2.6}/setup.py

@@ -13,7 +13,7 @@ gui_requirements = get_requirements("./clerk/gui_automation")
 
 setup(
     name="clerk-sdk",
-    version="0.2.4",
+    version="0.2.6",
     description="Library for interacting with Clerk",
     long_description=open("README.md").read(),
     long_description_content_type="text/markdown",

clerk_sdk-0.2.4/clerk/gui_automation/ui_actions/support.py

@@ -1,69 +0,0 @@
-import os
-import base64
-from typing import Optional
-from backoff._typing import Details
-
-from clerk.utils.save_artifact import save_artifact
-from ..client_actor import get_screen
-
-
-_MAP = {
-    "y": True,
-    "yes": True,
-    "t": True,
-    "true": True,
-    "on": True,
-    "1": True,
-    "n": False,
-    "no": False,
-    "f": False,
-    "false": False,
-    "off": False,
-    "0": False,
-}
-
-
-def strtobool(value):
-    try:
-        return _MAP[str(value).lower()]
-    except KeyError:
-        raise ValueError('"{}" is not a valid bool value'.format(value))
-
-
-def save_screenshot(filename: str, sub_folder: Optional[str] = None) -> str:
-    """
-    Save a screenshot into the process instance folder.
-
-    This function retrieves the base64 representation of the screen from the target environment using the 'get_screen' function.
-    Then, it saves the screenshot into the process instance folder using the 'save_file_into_instance_folder' function.
-
-    Args:
-        filename (str): The name of the file to save the screenshot as.
-        sub_folder (str, optional): The name of the subfolder within the instance folder where the screenshot will be saved. Defaults to None.
-
-    Returns:
-        str: The file path of the saved screenshot.
-
-    """
-    # get the base64 screen from target environment
-    screen_b64: str = get_screen()
-    return save_artifact(
-        filename=filename,
-        file_bytes=base64.b64decode(screen_b64),
-        subfolder=sub_folder,
-    )
-
-
-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.
-    :param details: A dictionary containing the details of the exception raised (https://pypi.org/project/backoff/)
-    :returns: 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:
-        raise details["exception"]  # type: ignore
-
-    raise NotImplementedError("Feature not yet implemented")