clerk-sdk 0.4.16.dev0__py3-none-any.whl → 0.5.0__py3-none-any.whl

clerk/development/templates/main_gui.py.template

@@ -0,0 +1,52 @@
+from typing import Dict
+
+from clerk.decorator import clerk_code
+from clerk.decorator.models import ClerkCodePayload
+from clerk.gui_automation.decorators import gui_automation
+from clerk.gui_automation.ui_state_machine import ScreenPilot, SuccessfulCompletion
+from clerk.utils import logger
+
+from src.gui.states import *
+from src.gui.transitions import *
+from src.gui.rollbacks import *
+from src.schema import StructuredData  # use `clerk schema fetch` to update the schema
+
+@clerk_code()
+@gui_automation()
+def main(payload: ClerkCodePayload):
+    """Main program"""
+
+    data = StructuredData.model_validate(payload.structured_data)
+    logger.info("Custom code started")    
+
+    def goal_function(current_state: str, process_variables: StructuredData) -> None:
+        """
+        Goal function for the state machine.
+        Args:
+            current_state (str): The current state of the state machine
+            (you can provide additional arguments as needed, e.g. order: dict)
+        Raises:
+            ScreenPilotOutcome: The outcome of the state machine
+        """
+        if True:  # Use an actual condition based on state and/or process variables to complete the automation
+            raise SuccessfulCompletion()
+
+    ai_recovery_instructions = "\\n - ".join(
+        [
+            "Instructions on how to deal with possible issues using Clerk UI Actions.",            
+        ]
+    )
+
+    ScreenPilot.configure(ai_recovery_instructions=ai_recovery_instructions)
+    exit_reason = ScreenPilot.run(
+        goal_function, process_variables=process_variables, doc_id=payload.document.id
+    )
+        
+
+    logger.info("Custom code completed")
+    payload.structured_data = data.model_dump()  # Return variables to Clerk
+    return payload
+
+
+if __name__ == "__main__":
+    main()

clerk/development/templates/rollbacks.py.template

@@ -0,0 +1,17 @@
+"""
+# Instructions
+
+Use this file to define rollback procedures for ScreenPilot. Rollbacks behave like transitions, but are triggered in rollback mode when exceptions occur.
+
+# Example
+```python
+@rollback("State1", "State2")
+def perform_rollback():
+    # Perform necessary actions to revert from State1 to State2
+    # Optionally, save a screenshot or log information
+    raise RollbackCompleted()
+```
+
+"""
+
+from clerk.gui_automation.ui_state_machine import rollback, RollbackCompleted

clerk/development/templates/states.py.template

@@ -0,0 +1,15 @@
+"""
+# Instructions
+
+Use this file to define the various states of ScreenPilot's UI state machine. Each state represents a distinct screen or condition in the GUI automation process.
+
+# Example
+```python
+
+@state(start_allowed=False, end_allowed=False)
+class InvoiceReview:
+    description = "Detailed description of the Invoice Review state."
+
+"""
+
+from clerk.gui_automation.ui_state_machine import state

clerk/development/templates/transitions.py.template

@@ -0,0 +1,26 @@
+"""
+# Instructions
+
+Use this file to define transitions between different states in ScreenPilot's UI state machine. Each transition represents a change from one state to another.
+
+# Example: regular transition
+```python
+@transition("StateA", "StateB")
+def go_to_state_b() -> None:
+    # Actions to perform during the transition from StateA to StateB
+    pass
+```
+
+# Example: conditional transition
+```python
+def condition() -> bool:
+    return True  # or some condition logic
+
+@transition("StateA", "StateB", condition=condition)
+def conditional_transition() -> None:
+    # Actions to perform during the conditional transition from StateA to StateB
+    pass
+```
+"""
+
+from clerk.gui_automation.ui_state_machine import transition

clerk/gui_automation/requirements.txt

@@ -0,0 +1,2 @@
+networkx >=3.5.0, <4.0.0
+websockets >= 15.0.1

clerk/gui_automation/ui_actions/base.py

@@ -11,7 +11,23 @@ from ..action_model.model import (
 import os
 
 ModalityType = Union[Literal["icon"], Literal["text"]]
-TARGET_IMAGES_PATH = os.path.join(os.getcwd(), "targets")
+
+
+def _find_child_dir(dir_name: str, root_dir: str) -> str:
+    """
+    Recursively search for a directory starting from current working directory.
+    Returns the first match found, or falls back to cwd/dir_name if none found.
+    """
+    # Walk through the directory tree starting from cwd
+    for root, dirs, _ in os.walk(root_dir):
+        if dir_name in dirs:
+            return os.path.join(root, dir_name)
+
+    # Fallback to default path if no targets directory found
+    return os.path.join(root_dir, dir_name)
+
+
+TARGET_IMAGES_PATH = _find_child_dir("targets", root_dir=os.getcwd())
 
 
 def to_full_img_path(img: Union[str, ImageB64]) -> str:

clerk/gui_automation/ui_state_machine/Readme.md

@@ -0,0 +1,79 @@
+# ScreenPilot 
+
+ScreenPilot is a state machine meant for operating UIs.
+- Accepts a state evaluation function and a goal function
+- Runs in a loop ("run" method) until the goal function returns True
+- Handles logging, error handling and attempts recovery on errors
+- The states and transitions are added to a directional multi-graph
+- "run" method performs anti-patter detection (repeated transitions, unplanned transitions) and exits on encountering them
+- Known states and transitions are provided with the respective decorators
+
+
+## Instructions
+
+- Use 'BusinessException' class to raise business exceptions
+- Evaluate the exit_reason returned by the run method to execution outcomes
+- Provide custom instructions to AI recovery to handle the UI's quirks
+
+## Usage example
+
+```python
+from f_one_core_utilities.ui_actions import Vision, ScreenPilot, state, transition, rollback, BusinessException, complete_ui_automation
+from f_one_core_utilities.ui_actions import LeftClick, SendKeys, PressKeys
+from f_one_core_utilities.camunda import raise_error, return_and_wait, raise_incident
+
+# Import states, transitions and rollbacks for them to be registered
+from .states import *
+from .transitions import *
+from .rollbacks import *
+
+# Configure states and transitions
+
+@state(end_allowed=False)
+class WindowOpen:
+    description = "Window is open"
+
+@state(start_allowed=False)
+class WindowClosed:
+    description = "Window is closed"
+
+@transition(from_state="WindowOpen", to_state="WindowClosed", condition=lambda payload: payload.message == "Closed")
+def close_window(payload):
+    # 'payload' is the order object passed to the run method
+    SendKeys(keys=f"{payload.message}").do()
+    LeftClick(target="Close").do()
+
+# Define rollbacks which will be triggered in case of runtime errors
+@rollback("WindowClosed", "WindowOpen")
+def teardown_app():
+    PressKeys(keys="Alt+F4").do()
+
+# Provide a goal function
+
+def goal_function(current_state: str, **kwargs) -> None:
+    """
+    Goal function for the state machine.
+    Args:
+        current_state (str): The current state of the state machine
+        **kwargs: (you can provide additional arguments as needed, e.g. order: dict)
+    Returns:
+        None
+    """
+    if current_state == "WindowClosed":
+        complete_ui_automation("Window closed")
+    else:
+        raise BusinessException("Window not closed")
+
+ScreenPilot.configure(
+   ai_recovery_instructions = "If the popup appears, click OK and interrupt the process",
+)
+
+# payload is a kwarg that will be propagated to all transitions and the goal function
+exit_reason = ScreenPilot.run(goal_function, payload=process_variables)
+
+# Exit status and messages can be used for graceful error handling
+if isinstance(exit_reason, BusinessException):
+    raise_error(message="Window still open", bpmn_error="WindowOpen")
+elif isinstance(exit_reason, SuccessfulCompletion):
+    process_variables.billable = True
+```

{clerk_sdk-0.4.16.dev0.dist-info → clerk_sdk-0.5.0.dist-info}/METADATA

@@ -1,39 +1,26 @@
 Metadata-Version: 2.4
 Name: clerk-sdk
-Version: 0.4.16.dev0
+Version: 0.5.0
 Summary: Library for interacting with Clerk
-Home-page: https://github.com/F-ONE-Group/clerk_pypi
-Author: F-ONE Group
-Author-email: admin@f-one.group
-Classifier: Programming Language :: Python :: 3
+Project-URL: Homepage, https://github.com/F-ONE-Group/clerk_pypi
+Author-email: F-One <contact@f-one.group>
+License-File: LICENSE
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
 Requires-Python: >=3.11
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: pydantic<3.0.0,>=2.0.0
 Requires-Dist: backoff<3.0.0,>=2.0.0
+Requires-Dist: pydantic<3.0.0,>=2.0.0
+Requires-Dist: python-dotenv>=1.0.0
 Requires-Dist: requests<3.0.0,>=2.32.3
+Requires-Dist: rich>=14.2.0
 Provides-Extra: all
-Requires-Dist: pydantic<3.0.0,>=2.0.0; extra == "all"
-Requires-Dist: backoff<3.0.0,>=2.0.0; extra == "all"
-Requires-Dist: requests<3.0.0,>=2.32.3; extra == "all"
-Requires-Dist: networkx<4.0.0,>=3.5.0; extra == "all"
-Requires-Dist: websockets>=15.0.1; extra == "all"
+Requires-Dist: networkx<4.0.0,>=3.5.0; extra == 'all'
+Requires-Dist: websockets>=15.0.1; extra == 'all'
 Provides-Extra: gui-automation
-Requires-Dist: networkx<4.0.0,>=3.5.0; extra == "gui-automation"
-Requires-Dist: websockets>=15.0.1; extra == "gui-automation"
-Dynamic: author
-Dynamic: author-email
-Dynamic: classifier
-Dynamic: description
-Dynamic: description-content-type
-Dynamic: home-page
-Dynamic: license-file
-Dynamic: provides-extra
-Dynamic: requires-dist
-Dynamic: requires-python
-Dynamic: summary
+Requires-Dist: networkx<4.0.0,>=3.5.0; extra == 'gui-automation'
+Requires-Dist: websockets>=15.0.1; extra == 'gui-automation'
+Description-Content-Type: text/markdown
 
 # Clerk Python SDK
 

{clerk_sdk-0.4.16.dev0.dist-info → clerk_sdk-0.5.0.dist-info}/RECORD

@@ -1,14 +1,26 @@
-clerk/__init__.py,sha256=6KE-7b4AAmpoWge6Ecko_0Spe4J7BC3YRdmmlEmsUFQ,56
+clerk/__init__.py,sha256=nmWUTp7gU2NpHDC4lwMx1k9CfI0znjuMuMgFNkrjad4,50
 clerk/base.py,sha256=lbFTdpdDfsmYIQUFH93S1aw0-L6GNJwAcubW1tdMFX4,3967
-clerk/client.py,sha256=RdOvC23WK9ZtIXDOYaoSFk9debh3UTmstBXjAswAH6E,4981
+clerk/client.py,sha256=m4d_DEpmTCPGP8gm3idREhcVzlvHDdvLrdbTc6J9AGk,5191
 clerk/decorator/__init__.py,sha256=yGGcS17VsZ7cZ-hVGCm3I3vGDJMiJIAqmDGzriIi0DI,65
 clerk/decorator/models.py,sha256=nFMdVSG3nJ4hrEXs9YbI_GgjHbVjhSWZokOCzUh-lqQ,521
 clerk/decorator/task_decorator.py,sha256=H8caRvNvvl-IRwyREP66gBGVM-SpQJ1W7oAFImO-6Jw,3769
+clerk/development/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+clerk/development/cli.py,sha256=-2VwjWiGHypxrOSCpFMXSAuJKvLfBqeCmaOXsUAOraE,3431
+clerk/development/init_project.py,sha256=pjEQKkpqStA-Z21sc4jswhIcOxJ3xgrxHLalNOsCiBU,10665
+clerk/development/gui/test_session.py,sha256=Lal3Q4kw9e-QXshE2v5zaV7aSWm4ilaWKyZzeHfAOJ4,10554
+clerk/development/schema/fetch_schema.py,sha256=jIGO2ZFvgVnFz5_pw1C2Nf48OR1skZEf7fTyOLJAg5A,12046
+clerk/development/templates/exceptions.py.template,sha256=BN9MhFhH435WX3e6HTd7bmakOD6Kh24bDPDMHBrArvQ,446
+clerk/development/templates/main_basic.py.template,sha256=9Cs5BC8FK2uFbxYEJfyHfpzbSz9tq2Q47XdUncbL0rM,550
+clerk/development/templates/main_gui.py.template,sha256=e06QKs54DAVUWtz7xiDq1IKnAPNA5ecmnBuKlk9wC30,1796
+clerk/development/templates/rollbacks.py.template,sha256=VeCVJhEwqol9LwRL5OfxIQUSOadbhGYYWrqjuqxO1bM,486
+clerk/development/templates/states.py.template,sha256=d0OjZTdP8DNMt4YE0PIBPQ8jSpgll4u31s6n9aSJ1Mw,404
+clerk/development/templates/transitions.py.template,sha256=PtkBbRxbEzqTqRa7zNDxrk8I1UhrithhBSKaO9r65uA,728
 clerk/exceptions/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 clerk/exceptions/exceptions.py,sha256=gSCma06b6W6c0NrA2rhzd5YjFhZGa6caShX07lo-_3E,1291
 clerk/exceptions/remote_device.py,sha256=R0Vfmk8ejibEFeV29A8Vqst2YA6yxdqEX9lP5wWubgM,134
 clerk/gui_automation/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 clerk/gui_automation/client.py,sha256=lLIim3i9PkdPlt5vmV4u2GoqQ571PHy7EvmRtTBv-JQ,5516
+clerk/gui_automation/requirements.txt,sha256=FpktaUbpvdMPCUArx5FgvTjJQxt2g6IN3zu2XpkfrFo,45
 clerk/gui_automation/action_model/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 clerk/gui_automation/action_model/model.py,sha256=yzaCyEMOH3YMkPBf6IwUMuu69-xyf78HzmthiewgWQY,3811
 clerk/gui_automation/action_model/utils.py,sha256=xzFxgN-bTK6HKGS7J-esQZ-ePj_yG72T-2ZVhcWvKjw,798
@@ -25,11 +37,12 @@ clerk/gui_automation/exceptions/modality/__init__.py,sha256=47DEQpj8HBSa-_TImW-5
 clerk/gui_automation/exceptions/modality/exc.py,sha256=P-dMuCTyVZYD3pbGpCf_1SYEgaETn13c51pmfbsXr5k,1436
 clerk/gui_automation/ui_actions/__init__.py,sha256=-EDQ5375HXrvG3sfFY7zOPC405YcBL6xXRACm2p-YyI,23
 clerk/gui_automation/ui_actions/actions.py,sha256=r_gVnAOGfv7XZyli8b8ru0nsMqn_JiTAMTNvgVf8T1I,28789
-clerk/gui_automation/ui_actions/base.py,sha256=oaUI3vIOoDwP_HdLu2GIG46-aMv0_Zv-PljMgSFeNmk,7329
+clerk/gui_automation/ui_actions/base.py,sha256=EXwjmX2gfksoWBGV6hW7MPkBSiSSK0X0DU6TZZvdo-o,7862
 clerk/gui_automation/ui_actions/support.py,sha256=Ulb8DBfwnrBMaYoMLDgldEy9V--NDUSdhIYXpuODZoU,5772
 clerk/gui_automation/ui_state_inspector/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 clerk/gui_automation/ui_state_inspector/gui_vision.py,sha256=Pk5nuFZnp_zNbqSOtndSmgqb6PLeADJfnC-eRIJMDZk,7736
 clerk/gui_automation/ui_state_inspector/models.py,sha256=qEbdrWGglOJH8QaOKoYp8ZKQMjnGk4JufpgYuTWoQ10,6082
+clerk/gui_automation/ui_state_machine/Readme.md,sha256=8_cOu7zSSpIRNCY4C2DCwVlBvbQwmbiRff1VbH4yLek,2916
 clerk/gui_automation/ui_state_machine/__init__.py,sha256=bTPZsPJkDLCwP2mdtBj4fU7C7ekOh0b-VPRKFEV3bPo,301
 clerk/gui_automation/ui_state_machine/ai_recovery.py,sha256=aw6a7QCioZdcqf11yTxQg-ZnXAlXa5nPXi_cOBAuoG4,3871
 clerk/gui_automation/ui_state_machine/decorators.py,sha256=gBOpIusjsXlA7FEiszDCFKTS6vXx3LBNMz_SQJNkMWg,2134
@@ -45,8 +58,8 @@ clerk/models/ui_operator.py,sha256=mKTJUFZgv7PeEt5oys28HVZxHOJsofmRQOcRpqj0dbU,2
 clerk/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 clerk/utils/logger.py,sha256=NrMIlJfVmRjjRw_N_Jngkl0qqv7btXUbg5wxcRmFEH4,3800
 clerk/utils/save_artifact.py,sha256=94aYkYNVGcSUaSWZmdjiY6Oc-3yCKb2XWCZ56IAXQqk,1158
-clerk_sdk-0.4.16.dev0.dist-info/licenses/LICENSE,sha256=GTVQl3vH6ht70wJXKC0yMT8CmXKHxv_YyO_utAgm7EA,1065
-clerk_sdk-0.4.16.dev0.dist-info/METADATA,sha256=U8QlEn0ANQxSkmowBLby6M8IJL-BKHkXxkQ5BL6lLhc,9942
-clerk_sdk-0.4.16.dev0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-clerk_sdk-0.4.16.dev0.dist-info/top_level.txt,sha256=99eQiU6d05_-f41tmSFanfI_SIJeAdh7u9m3LNSfcv4,6
-clerk_sdk-0.4.16.dev0.dist-info/RECORD,,
+clerk_sdk-0.5.0.dist-info/METADATA,sha256=wQkyLiNEMYSq7VZHGb9xr3teZ9BZsh4l-cUtOy37tj4,9597
+clerk_sdk-0.5.0.dist-info/WHEEL,sha256=WLgqFyCfm_KASv4WHyYy0P3pM_m7J5L9k2skdKLirC8,87
+clerk_sdk-0.5.0.dist-info/entry_points.txt,sha256=VoUmW07sRRSioms5pqQ4A6CYxNEyhGA93GtyBlB_wGw,53
+clerk_sdk-0.5.0.dist-info/licenses/LICENSE,sha256=GTVQl3vH6ht70wJXKC0yMT8CmXKHxv_YyO_utAgm7EA,1065
+clerk_sdk-0.5.0.dist-info/RECORD,,

{clerk_sdk-0.4.16.dev0.dist-info → clerk_sdk-0.5.0.dist-info}/WHEEL

@@ -1,5 +1,4 @@
 Wheel-Version: 1.0
-Generator: setuptools (80.9.0)
+Generator: hatchling 1.28.0
 Root-Is-Purelib: true
 Tag: py3-none-any
-

clerk_sdk-0.5.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+clerk = clerk.development.cli:main

clerk_sdk-0.4.16.dev0.dist-info/top_level.txt

@@ -1 +0,0 @@
-clerk