clerk-sdk 0.1.8__py3-none-any.whl → 0.2.0__py3-none-any.whl

clerk/gui_automation/ui_state_machine/ai_recovery.py

@@ -0,0 +1,110 @@
+from typing import Union, List, Optional, Type
+from pydantic import BaseModel, Field
+
+from clerk.gui_automation.client import CourseCorrectorClerk
+
+from ..client_actor.client_actor import get_screen
+from .models import ActionString
+
+
+class CourseCorrector(BaseModel):
+    """
+    Interface for a CourseCorrector class that can generate corrective actions based on a goal and feedback.
+    """
+
+    name: str
+    goal: str
+    custom_instructions: Optional[str] = None
+
+    def get_corrective_actions(
+        self, output_model: Type[ActionString] = ActionString
+    ) -> List[ActionString]:
+        """
+        Writes an action string based on the provided prompt.
+        Args:
+            action_prompt: The prompt for the action to write.
+            output_model: The model to use for the response.
+        Returns:
+            List of ActionString models.
+        """
+        raise NotImplementedError("get_corrective_action method is not implemented")
+
+    def add_feedback(self, feedback: str) -> None:
+        """
+        Adds feedback to the CourseCorrector instance.
+        Args:
+            feedback: The feedback to add.
+        """
+        raise NotImplementedError("add_feedback method is not implemented")
+
+    def get_latest_feedback(self) -> Optional[str]:
+        """
+        Gets the latest feedback added to the CourseCorrector instance.
+        Returns:
+            The latest feedback as a string, or None if no feedback has been added.
+        """
+        raise NotImplementedError("get_latest_feedback method is not implemented")
+
+    def reset_feedback(self) -> None:
+        """
+        Resets the latest feedback added to the CourseCorrector instance.
+        """
+        raise NotImplementedError("reset_feedback method is not implemented")
+
+
+class CourseCorrectorV1(CourseCorrector):
+    name: str = "CourseCorrectorV1"
+    use_ocr: bool = Field(
+        default=True,
+        description="Whether OCR of the screen should be included with in the model call (increases precision with "
+        "small details).",
+    )
+    clerk_client: CourseCorrectorClerk = CourseCorrectorClerk()
+
+    def get_corrective_actions(
+        self,
+        output_model: Type[ActionString] = ActionString,
+    ) -> List[ActionString]:
+        """
+        Writes an action string based on the provided prompt.
+        Args:
+            action_prompt: The prompt for the action to write.
+            output_model: The model to use for the response.
+        Returns:
+            List of ActionString models.
+        """
+        screen_b64 = get_screen()
+        action_string = self.clerk_client.get_corrective_actions(
+            screen_b64, self.use_ocr, self.goal, self.custom_instructions
+        )
+        assert isinstance(action_string, ActionString)
+        return [action_string]
+
+    def add_feedback(self, feedback: str) -> None:
+        """
+        Adds feedback to the CourseCorrector instance.
+        Args:
+            feedback: The feedback to add.
+        """
+        self.latest_feedback = feedback
+
+    def get_latest_feedback(self) -> Optional[str]:
+        """
+        Gets the latest feedback added to the CourseCorrector instance.
+        Returns:
+            The latest feedback as a string, or None if no feedback has been added.
+        """
+        return self.latest_feedback
+
+    def reset_feedback(self) -> None:
+        """
+        Resets the latest feedback added to the CourseCorrector instance.
+        """
+        self.latest_feedback = None
+
+
+def course_corrector_v1(
+    goal: str, custom_instructions: Union[str, None] = None
+) -> CourseCorrectorV1:
+    """Factory function for generating a CourseCorrector instance with the specified goal."""
+    return CourseCorrectorV1(goal=goal, custom_instructions=custom_instructions)

clerk/gui_automation/ui_state_machine/decorators.py

@@ -0,0 +1,71 @@
+from typing import Callable, Optional
+from .state_machine import ScreenPilot
+
+
+def state(*args, start_allowed=True, end_allowed=True):
+    """
+    Register a state class with the ScreenPilot state machine.
+
+    Parameters:
+    - start_allowed (bool): Whether the process may start from this state.
+    - end_allowed (bool): Whether the process may end in this state.
+
+    Returns:
+    - None
+
+    Example:
+    @state(start_allowed=True, end_allowed=False)
+    """
+    if args and callable(args[0]):
+        # It's used as @state without arguments, args[0] is the class
+        cls = args[0]
+        return state()(cls)  # Apply default arguments
+    else:
+
+        def class_decorator(cls):
+            ScreenPilot.register_state(
+                cls, start_allowed=start_allowed, end_allowed=end_allowed
+            )
+            return cls
+
+        return class_decorator
+
+
+def transition(from_state: str, to_state: str, condition: Optional[Callable] = None):
+    """
+    Register a transition between two states with the ScreenPilot state machine.
+
+    Parameters:
+    - from_state (str): The name of the state to transition from.
+    - to_state (str): The name of the state to transition to.
+    - condition (Callable): Condition to disambiguate between multiple transitions. Must return a boolean.
+
+    Returns:
+    - None
+
+    Example:
+    @transition('StateA', 'StateB')
+    """
+    return ScreenPilot.register_transition(
+        from_state, to_state, mode="planned", condition=condition
+    )
+
+
+def rollback(from_state: str, to_state: str, condition: Optional[Callable] = None):
+    """
+    Register a rollback transition between two states with the ScreenPilot state machine.
+
+    Parameters:
+    - from_state (str): The name of the state to transition from.
+    - to_state (str): The name of the state to transition to.
+    - condition (Callable): Condition to disambiguate between multiple rollbacks. Must return a boolean.
+
+    Returns:
+    - None
+
+    Example:
+    @rollback('StateA', 'StateB')
+    """
+    return ScreenPilot.register_transition(
+        from_state, to_state, mode="rollback", condition=condition
+    )

clerk/gui_automation/ui_state_machine/exceptions.py

@@ -0,0 +1,42 @@
+from typing import Optional
+
+
+class ScreenPilotOutcome(Exception):
+    """Base class for all exceptions and conditions raised by the ScreenPilot state machine."""
+
+
+class ScreenPilotException(Exception):
+    """Base class for all exceptions raised by the ScreenPilot state machine."""
+
+
+class BusinessException(ScreenPilotOutcome):
+    """Raised from inside transitions to indicate a business process condition."""
+
+
+class UnplannedTransitionsError(ScreenPilotException):
+    """Raised when a transition occurs that is not planned in the state machine."""
+
+
+class RepeatStatesError(ScreenPilotException):
+    """Raised when an attempt is made to re-enter a state that should not be repeated."""
+
+
+class RepeatTransitions(ScreenPilotException):
+    """Raised when the same transition is attempted to be repeated in an invalid context."""
+
+
+class CourseCorrectionImpossible(ScreenPilotException):
+    """Raised when the state machine cannot determine a course correction."""
+
+
+class SuccessfulCompletion(ScreenPilotOutcome):
+    """Raised when the state machine has completed successfully."""
+
+
+class RollbackCompleted(ScreenPilotOutcome):
+    """Raised when the state machine has completed a rollback successfully."""
+
+
+def complete_ui_automation(message: Optional[str] = None):
+    """Raise an exception to interrupt ScreenPilot and indicate that the UI automation has completed successfully."""
+    raise SuccessfulCompletion(message)

clerk/gui_automation/ui_state_machine/models.py

@@ -0,0 +1,40 @@
+from typing import Optional
+from pydantic import BaseModel, field_validator, model_validator
+
+
+class ActionString(BaseModel):
+    """
+    ActionString class represents a string that represents an action in an application.
+
+    Attributes:
+        action_string (str): The string representation of the action.
+        comment (str, optional): An optional comment or description for the action.
+        interrupt_process (bool, optional): A flag indicating whether the action should interrupt the process.
+
+    Methods:
+        ensure_format(v: str) -> str:
+            Validator function that ensures the action string has the correct format.
+
+    """
+
+    action_string: str
+    action_comment: Optional[str] = None
+    observation: Optional[str] = None
+    interrupt_process: Optional[bool] = False
+
+    @field_validator("action_string", mode="before")
+    @classmethod
+    def ensure_format(cls, v):
+        if not isinstance(v, str):
+            raise ValueError("Action string must be a string")
+        if not v.endswith(".do()") and not v.startswith("NoAction"):
+            raise ValueError("Action string must end with '.do()'")
+        return v
+
+    @field_validator("interrupt_process", mode="before")
+    def convert_to_bool(cls, v):
+        if v is None:
+            return False
+        elif isinstance(v, str):
+            return v.lower() in ["true", "1", "yes"]
+        return v