computers/computer.py

import abc
import pydantic
from typing import Literal


class EnvState(pydantic.BaseModel):
    # The screenshot in PNG format.
    screenshot: bytes
    url: str


class Computer(abc.ABC):
    """Defines an interface for environments."""

    @abc.abstractmethod
    def screen_size(self) -> tuple[int, int]:
        """Returns the screen size of the environment."""

    @abc.abstractmethod
    def open_web_browser(self) -> EnvState:
        """Opens the web browser."""

    @abc.abstractmethod
    def click_at(self, x: int, y: int) -> EnvState:
        """Clicks at a specific x, y coordinate on the screen.

        The 'x' and 'y' values are absolute values, scaled to the height and width of the screen.
        """

    @abc.abstractmethod
    def hover_at(self, x: int, y: int) -> EnvState:
        """Hovers at a specific x, y coordinate on the screen.

        May be used to explore UI elements such as tooltips or sub-menus that appear on hover.
        The 'x' and 'y' values are absolute values, scaled to the height and width of the screen.
        """

    @abc.abstractmethod
    def type_text_at(
        self,
        x: int,
        y: int,
        text: str,
        press_enter: bool,
        clear_before_typing: bool,
    ) -> EnvState:
        """Types text at a specific x, y coordinate on the screen.

        The system automatically presses ENTER after typing. To disable this, set `press_enter` to False.
        The system automatically clears any existing content before typing the specified `text`. To disable this, set `clear_before_typing` to False.
        The 'x' and 'y' values are absolute values, scaled to the height and width of the screen.
        """

    @abc.abstractmethod
    def scroll_document(
        self, direction: Literal["up", "down", "left", "right"]
    ) -> EnvState:
        """Scrolls the active window or document in the specified direction.

        Direction can be "up", "down", "left", or "right".
        """

    @abc.abstractmethod
    def scroll_at(
        self,
        x: int,
        y: int,
        direction: Literal["up", "down", "left", "right"],
        magnitude: int = 5,
    ) -> EnvState:
        """Scrolls at a specific x, y coordinate in the specified direction by magnitude.

        The 'x' and 'y' values are absolute values, scaled to the height and width of the screen.
        The magnitude parameter controls the scroll amount (default: 5).
        """


    @abc.abstractmethod
    def wait(self, seconds: int = 5) -> EnvState:
        """Waits for a specified number of seconds.

        Args:
            seconds: Number of seconds to wait (default: 5)
        """

    @abc.abstractmethod
    def go_back(self) -> EnvState:
        """Navigates back to the previous page in the browser history."""

    @abc.abstractmethod
    def go_forward(self) -> EnvState:
        """Navigates forward to the next page in the browser history."""

    @abc.abstractmethod
    def search(self) -> EnvState:
        """Directly jumps to a search engine home page.

        Used when you need to start with a search. For example, this is used when
        the current page doesn't have the information needed or because a new
        task is being started.
        """

    @abc.abstractmethod
    def navigate(self, url: str) -> EnvState:
        """Navigates directly to a specified URL."""

    @abc.abstractmethod
    def key_combination(self, keys: list[str]) -> EnvState:
        """Executes keyboard key combinations.

        Examples: ["control", "c"], ["alt", "tab"], ["enter"]
        """

    @abc.abstractmethod
    def drag_and_drop(
        self, x: int, y: int, destination_x: int, destination_y: int
    ) -> EnvState:
        """Drag and drop an element from a x, y coordinate to a destination destination_y, destination_x coordinate.
        The 'x', 'y', 'destination_y' and 'destination_x' values are absolute values, scaled to the height and width of the screen.
        """

    @abc.abstractmethod
    def current_state(self) -> EnvState:
        """Returns the current state of the environment including screenshot and URL."""

    # ========== Shell Operations ==========

    @abc.abstractmethod
    def exec_command(self, command: str, timeout: int = 30):
        """Execute a shell command in the environment.

        Args:
            command: Shell command to execute
            timeout: Command timeout in seconds (default: 30)

        Returns:
            Command result with stdout, stderr, and exit code
        """

    @abc.abstractmethod
    def exec_script(self, script: str, timeout: int = 60):
        """Execute a multi-line bash script.

        Args:
            script: Multi-line bash script to execute
            timeout: Script timeout in seconds (default: 60)

        Returns:
            Command result with stdout, stderr, and exit code
        """

    # ========== File Operations ==========

    @abc.abstractmethod
    def read_file(self, path: str) -> str:
        """Read file contents from the environment.

        Args:
            path: File path to read

        Returns:
            File contents as string
        """

    @abc.abstractmethod
    def write_file(self, path: str, content: str) -> None:
        """Write content to a file in the environment.

        Args:
            path: File path to write
            content: Content to write to the file
        """

    @abc.abstractmethod
    def list_directory(self, path: str = ".") -> list[str]:
        """List contents of a directory.

        Args:
            path: Directory path to list (default: current directory)

        Returns:
            List of file and directory names
        """

    # ========== Code Execution Operations ==========

    @abc.abstractmethod
    def run_python(self, code: str, timeout: int = 60):
        """Execute Python code in the environment.

        Args:
            code: Python code to execute
            timeout: Execution timeout in seconds (default: 60)

        Returns:
            Code execution result with stdout, stderr, and exit code
        """

    @abc.abstractmethod
    def run_javascript(self, code: str, timeout: int = 60):
        """Execute JavaScript code in the environment.

        Args:
            code: JavaScript code to execute
            timeout: Execution timeout in seconds (default: 60)

        Returns:
            Code execution result with stdout, stderr, and exit code
        """

    @abc.abstractmethod
    def run_bash(self, code: str, timeout: int = 60):
        """Execute Bash code in the environment.

        Args:
            code: Bash code to execute
            timeout: Execution timeout in seconds (default: 60)

        Returns:
            Code execution result with stdout, stderr, and exit code
        """