microbots 0.0.1__py3-none-any.whl

microbot/environment/local_docker/image_builder/ShellCommunicator.py

@@ -0,0 +1,261 @@
+#!/usr/bin/env python3
+"""
+Shell Communication Script
+A Python script to create and communicate with shell sessions.
+Supports interactive shell communication, command execution, and bidirectional data flow.
+"""
+
+import os
+import queue
+import subprocess
+import sys
+import threading
+import time
+import logging
+from typing import Callable, List, Optional
+from dataclasses import dataclass
+
+logger = logging.getLogger(__name__)
+
+@dataclass
+class CmdReturn:
+    stdout: str
+    stderr: str
+    return_code: int
+
+
+class ShellCommunicator:
+    """
+    A class to create and manage shell sessions with bidirectional communication.
+    """
+
+    def __init__(self, shell_type: str = "bash", encoding: str = "utf-8"):
+        """
+        Initialize the shell communicator.
+
+        Args:
+            shell_type: Type of shell ("powershell", "cmd", "bash", "python")
+            encoding: Text encoding for communication
+        """
+        self.shell_type = shell_type.lower()
+        self.encoding = encoding
+        self.process: Optional[subprocess.Popen] = None
+        self.output_queue = queue.Queue()
+        self.error_queue = queue.Queue()
+        self.is_running = False
+        self.output_thread: Optional[threading.Thread] = None
+        self.error_thread: Optional[threading.Thread] = None
+        self.output_callback: Optional[Callable] = None
+
+        # Define shell commands
+        self.shell_commands = {
+            "powershell": ["powershell.exe", "-NoLogo", "-NoExit"],
+            "cmd": ["cmd.exe", "/k"],
+            "bash": ["bash"],
+            "python": [sys.executable, "-i"],
+            "wsl": ["wsl.exe"],
+        }
+
+    def start_session(self) -> bool:
+        """
+        Start a new shell session.
+
+        Returns:
+            bool: True if session started successfully, False otherwise
+        """
+        try:
+            if self.shell_type not in self.shell_commands:
+                logger.error("🛑 Unsupported shell type: %s", self.shell_type)
+                return False
+
+            cmd = self.shell_commands[self.shell_type]
+
+            # Create the subprocess
+            self.process = subprocess.Popen(
+                cmd,
+                stdin=subprocess.PIPE,
+                stdout=subprocess.PIPE,
+                stderr=subprocess.PIPE,
+                text=True,
+                encoding=self.encoding,
+                bufsize=0,
+                universal_newlines=True,
+            )
+
+            self.is_running = True
+
+            # Start output monitoring threads
+            self.output_thread = threading.Thread(
+                target=self._monitor_output,
+                args=(self.process.stdout, self.output_queue, "OUTPUT"),
+                daemon=True,
+            )
+            self.error_thread = threading.Thread(
+                target=self._monitor_output,
+                args=(self.process.stderr, self.error_queue, "ERROR"),
+                daemon=True,
+            )
+
+            self.output_thread.start()
+            self.error_thread.start()
+
+            logger.info("🚀 %s session started successfully", self.shell_type.capitalize())
+            logger.debug("🆔 Process ID: %s", self.process.pid)
+            return True
+
+        except Exception as e:
+            logger.exception("❌ Failed to start shell session: %s", e)
+            return False
+
+    def _monitor_output(self, stream, output_queue: queue.Queue, stream_type: str):
+        """
+        Monitor shell output in a separate thread.
+
+        Args:
+            stream: The stream to monitor (stdout or stderr)
+            output_queue: Queue to store output
+            stream_type: Type of stream ("OUTPUT" or "ERROR")
+        """
+        try:
+            while self.is_running and self.process and self.process.poll() is None:
+                line = stream.readline()
+                if line:
+                    output_queue.put((stream_type, line.rstrip()))
+                    if self.output_callback:
+                        self.output_callback(stream_type, line.rstrip())
+                elif self.process.poll() is not None:
+                    break
+        except Exception as e:
+            output_queue.put((stream_type, f"Monitor error: {e}"))
+
+    def send_command(
+        self, command: str, wait_for_output: bool = True, timeout: float = 5.0
+    ) -> CmdReturn:
+        """
+        Send a command to the shell session.
+
+        Args:
+            command: Command to execute
+            wait_for_output: Whether to wait for command output
+            timeout: Timeout for waiting for output
+
+        Returns:
+            List of output lines
+        """
+        if not self.is_running or not self.process:
+            logger.warning("⚠️ No active shell session")
+            return CmdReturn(stdout="", stderr="No active shell session", return_code=1)
+
+        try:
+            self.process.stdin.write(command + "\n")
+            self.process.stdin.flush()
+            logger.debug("➡️ Sent command: %s", command)
+
+            if not wait_for_output:
+                return CmdReturn(stdout="", stderr="", return_code=0)
+
+            output_lines = []
+            start_time = time.time()
+
+            while time.time() - start_time < timeout:
+                try:
+                    # Check for output
+                    stream_type, line = self.output_queue.get(timeout=0.1)
+                    output_lines.append(f"{line}")
+                    if stream_type == "ERROR":
+                        logger.error("❌ %s", line)
+                    else:
+                        logger.debug("📤 %s", line)
+                except queue.Empty:
+                    continue
+                except Exception:
+                    logger.exception("❌ Unexpected error while reading output queue")
+                    break
+
+            # Check for errors
+            try:
+                while True:
+                    stream_type, line = self.error_queue.get_nowait()
+                    output_lines.append(f"{line}")
+                    if stream_type == "ERROR":
+                        logger.error("❌ %s", line)
+                    else:
+                        logger.debug("📤 %s", line)
+            except queue.Empty:
+                pass
+
+            return CmdReturn(stdout="\n".join(output_lines), stderr="", return_code=0)
+
+        except Exception as e:
+            logger.exception("❌ Failed to send command: %s", e)
+            return CmdReturn(stdout="", stderr=str(e), return_code=1)
+
+
+    def is_alive(self) -> bool:
+        """
+        Check if the shell session is still alive.
+
+        Returns:
+            bool: True if session is active, False otherwise
+        """
+        return (
+            self.is_running and self.process is not None and self.process.poll() is None
+        )
+
+    def get_shell_info(self) -> dict:
+        """
+        Get information about the current shell session.
+
+        Returns:
+            Dictionary with shell session information
+        """
+        if not self.process:
+            return {"status": "Not started"}
+
+        return {
+            "shell_type": self.shell_type,
+            "pid": self.process.pid,
+            "status": "Running" if self.is_alive() else "Stopped",
+            "encoding": self.encoding,
+            "return_code": self.process.returncode,
+        }
+
+    def close_session(self):
+        """
+        Close the shell session and cleanup resources.
+        """
+        logger.info("🛑 Closing shell session…")
+
+        self.is_running = False
+
+        if self.process:
+            try:
+                # Try to terminate gracefully
+                if self.shell_type == "powershell":
+                    self.send_command("exit", wait_for_output=False)
+                elif self.shell_type == "cmd":
+                    self.send_command("exit", wait_for_output=False)
+                else:
+                    self.send_command("exit", wait_for_output=False)
+
+                # Wait a bit for graceful shutdown
+                time.sleep(1)
+
+                # Force terminate if still running
+                if self.process.poll() is None:
+                    self.process.terminate()
+                    time.sleep(1)
+
+                    if self.process.poll() is None:
+                        self.process.kill()
+
+                logger.info("✅ Shell session closed")
+
+            except Exception as e:
+                logger.exception("⚠️ Error during cleanup: %s", e)
+
+        # Wait for threads to finish
+        if self.output_thread and self.output_thread.is_alive():
+            self.output_thread.join(timeout=2)
+        if self.error_thread and self.error_thread.is_alive():
+            self.error_thread.join(timeout=2)

microbot/environment/local_docker/image_builder/dockerShell.py

@@ -0,0 +1,28 @@
+import os
+
+import uvicorn
+from fastapi import FastAPI
+from pydantic import BaseModel
+from ShellCommunicator import ShellCommunicator
+
+shell = ShellCommunicator("bash")
+shell.start_session()
+
+
+class Message(BaseModel):
+    message: str
+
+
+app = FastAPI()
+
+
+@app.post("/")
+async def receive_message(message: Message):
+    command_output = shell.send_command(message.message)
+    return {"status": "success", "output": "\n".join(command_output)}
+
+
+if __name__ == "__main__":
+    # Prefer BOT_PORT, else default 8080
+    port = int(os.getenv("BOT_PORT") or 8080)
+    uvicorn.run(app, host="0.0.0.0", port=port)

microbot/environment/swe-rex/LocalDocker.py

@@ -0,0 +1,139 @@
+import asyncio
+import logging
+import os
+from enum import Enum
+from typing import Optional, Final
+
+from Environment.Environment import Environment, CmdReturn
+from swerex.deployment.docker import DockerDeployment
+from swerex.runtime.abstract import (
+    CreateBashSessionRequest,
+    CloseBashSessionRequest,
+    BashAction,
+    Observation,
+)
+
+PYTHON_IMAGE = "mcr.microsoft.com/devcontainers/python:3.11"
+
+logger = logging.getLogger(__name__)
+
+
+class Permission(str, Enum):
+    READ_ONLY = "READ_ONLY"
+    READ_WRITE = "READ_WRITE"
+
+
+class LocalDocker(Environment):
+    BASE_PATH: Final[str] = "/workdir"
+
+    def _validate_permission_args(
+        self,
+        folder_to_mount: Optional[str],
+        permission: Optional[Permission],
+    ):
+        if folder_to_mount is None and permission is not None:
+            raise ValueError("permission provided but folder_to_mount is None")
+        if permission is None and folder_to_mount is not None:
+            raise ValueError("folder_to_mount provided but permission is None")
+        if permission is not None and permission not in (
+            Permission.READ_ONLY,
+            Permission.READ_WRITE,
+        ):
+            raise ValueError(
+                "permission must be Permission.READ_ONLY or Permission.READ_WRITE when provided"
+            )
+
+    def _get_mount_args(
+        self,
+        folder_to_mount: Optional[str],
+        permission: Optional[Permission],
+    ) -> str:
+        self._validate_permission_args(folder_to_mount, permission)
+
+        mount_args = ""
+        if folder_to_mount and permission:
+            # TODO: Make overlay mount for read-only to allow llm to create intermediate files
+            sanitized = os.path.abspath(folder_to_mount).strip()
+            target_path = f"{LocalDocker.BASE_PATH}/{os.path.basename(sanitized)}"
+            mode = "ro" if permission == Permission.READ_ONLY else "rw"
+            mount_args = f"-v {sanitized}:{target_path}:{mode}"
+            logger.info("🥪 Volume mapping: %s -> %s (%s)", sanitized, target_path, mode)
+            logger.debug("🗻 Mount args: %r", mount_args)
+        return mount_args
+
+    def _get_docker_args(self, mount_args: str = "") -> list[str]:
+        # _get_mount_args returns either "" or a single string beginning with -v; split into tokens for DockerDeployment
+        docker_args = []
+
+        if mount_args:
+            if mount_args.startswith('-v '):
+                # split once: '-v src:dest:mode'
+                flag, rest = mount_args.split(' ', 1)
+                docker_args.extend([flag, rest])
+            else:
+                docker_args.append(mount_args)
+
+        return docker_args
+
+    def __init__(
+        self,
+        folder_to_mount: Optional[str] = None,
+        permission: Optional[Permission] = Permission.READ_WRITE,
+        image: str = PYTHON_IMAGE,
+    ):
+        mount_args = self._get_mount_args(folder_to_mount, permission)
+        docker_args = self._get_docker_args(mount_args)
+        self.deployment = DockerDeployment(image=image, docker_args=docker_args)
+        asyncio.run(self.deployment.start())
+        self.start()
+        logger.info("🚀 LocalDocker environment initialized successfully")
+
+    def start(self):  # type: ignore[override]
+        # Acquire runtime and open a bash session.
+        self.runtime = self.deployment.runtime
+        asyncio.run(self.runtime.create_session(CreateBashSessionRequest()))
+
+    def stop(self):
+        try:
+            asyncio.run(self.runtime.close_session(CloseBashSessionRequest()))
+        finally:
+            asyncio.run(self.deployment.stop())
+
+    async def execute(
+        self, command: str, timeout: Optional[int] = 300
+    ) -> CmdReturn:
+        """Execute a shell command inside the container.
+
+        We pass the command through bash -lc to support shell features (globbing, env vars, pipelines).
+        """
+        logger.debug("🔧 Executing command: %s", command)
+        try:
+            output: Observation = await asyncio.wait_for(
+                self.runtime.run_in_session(BashAction(command=command)), timeout
+            )
+            logger.debug("📋 Command '%s' completed:", command)
+            logger.debug("   ├─ 📤 Exit code: %s", output.exit_code)
+            logger.debug("   ├─ 📝 Output: %s", output.output[:100] + "..." if len(output.output) > 100 else output.output)
+            logger.debug("   └─ ⚠️ Error: %s", output.failure_reason if output.failure_reason else "(none)")
+            return CmdReturn(
+                stdout=output.output,
+                return_code=output.exit_code,
+                stderr=output.failure_reason if output.failure_reason else "",
+            )
+        except asyncio.TimeoutError:
+            # TODO: Consider killing the process if it exceeds timeout. Because session might be unusable after timeout.
+            logger.error("⏱️ Command timed out after %s seconds: '%s'", timeout, command)
+            return CmdReturn(
+            stdout="",
+            stderr=f"Command timed out after {timeout} seconds",
+            return_code=124,  # Standard timeout exit code
+            )
+        except Exception as e:
+            logger.error("❌ Error occurred while executing command '%s': %s", command, e)
+            return CmdReturn(
+            stdout="",
+            stderr=str(e),
+            return_code=1,
+            )
+
+

microbot/llm/openai_api.py

@@ -0,0 +1,78 @@
+import json
+import os
+from dataclasses import dataclass
+from logging import getLogger
+
+from dotenv import load_dotenv
+from openai import OpenAI
+from microbot.utils.logger import LogLevelEmoji
+
+logger = getLogger(__name__)
+
+
+load_dotenv()
+
+from openai import OpenAI
+
+endpoint = os.getenv("OPEN_AI_END_POINT")
+deployment_name = os.getenv("OPEN_AI_DEPLOYMENT_NAME")
+api_key = os.getenv("OPEN_AI_KEY")  # use the api_key
+
+
+@dataclass
+class llmAskResponse:
+    task_done: bool = False
+    command: str = ""
+    result: str | None = None
+
+
+class OpenAIApi:
+
+    def __init__(self, system_prompt, deployment_name=deployment_name):
+        self.ai_client = OpenAI(base_url=f"{endpoint}", api_key=api_key)
+        self.deployment_name = deployment_name
+        self.system_prompt = system_prompt
+        self.messages = [{"role": "system", "content": system_prompt}]
+
+    def ask(self, message) -> llmAskResponse:
+        self.messages.append({"role": "user", "content": message})
+        return_value = {}
+        while self._validate_llm_response(return_value) is False:
+            response = self.ai_client.responses.create(
+                model=self.deployment_name,
+                input=self.messages,
+            )
+            try:
+                return_value = json.loads(response.output_text)
+            except Exception as e:
+                logger.error(
+                    f"%s Error occurred while dumping JSON: {e}", LogLevelEmoji.ERROR
+                )
+                logger.error(
+                    "%s Failed to parse JSON from LLM response and the response is",
+                    LogLevelEmoji.ERROR,
+                )
+                logger.error(response.output_text)
+
+        self.messages.append({"role": "assistant", "content": json.dumps(return_value)})
+
+        return llmAskResponse(
+            task_done=return_value["task_done"],
+            result=return_value["result"],
+            command=return_value["command"],
+        )
+
+    def clear_history(self):
+        self.messages = [
+            {
+                "role": "system",
+                "content": self.system_prompt,
+            }
+        ]
+        return True
+
+    def _validate_llm_response(self, response: dict) -> bool:
+        if "task_done" in response and "command" in response and "result" in response:
+            logger.info("The llm response is %s ", response)
+            return True
+        return False

microbot/tool/tool.py

@@ -0,0 +1,74 @@
+from dataclasses import dataclass
+from typing import Optional, List
+from pathlib import Path
+from enum import IntEnum
+import yaml
+
+
+class FILE_PERMISSION(IntEnum):
+    READ = 4
+    WRITE = 2
+    EXECUTE = 1
+
+
+@dataclass
+class EnvFileCopies:
+    src: Path
+    dest: Path
+    permissions: int  # Use FILE_PERMISSION enum to set permissions
+
+
+@dataclass
+class Tool:
+    # TODO: Handle different instructions based on the platform (linux flavours, windows, mac)
+    # TODO: Add versioning to tools
+    name: str
+    description: str
+    parameters: dict | None
+
+    # This is the set of instructions that will be provided to the LLM on how to use this tool.
+    # This string will be appended to the LLM's system prompt.
+    # This instructions should be non-interactive
+    usage_instructions_to_llm: str
+
+    # This set of commands will be executed once the environment is up and running.
+    # These commands will be executed in the order they are provided.
+    install_commands: List[str]
+
+    # Mention what are the environment variables that need to be copied from your current environment
+    env_variables: Optional[str] = None
+
+    # Any files to be copied to the environment before the tool is installed.
+    files_to_copy: Optional[List[EnvFileCopies]] = None
+
+    # This set of commands will be executed to verify if the tool is installed correctly.
+    # If any of these commands fail, the tool installation is considered to have failed.
+    verify_commands: Optional[List[str]] = None
+
+    # This set of commands will be executed after the code is copied to the environment
+    # and before the llm is invoked.
+    # These commands will be executed inside the mounted folder.
+    setup_commands: Optional[List[str]] = None
+
+    # This set of commands will be executed when the environment is being torn down.
+    uninstall_commands: Optional[List[str]] = None
+
+
+def parse_tool_definition(yaml_path: Path) -> Tool:
+    """
+    Parse a tool definition from a YAML file.
+
+    Args:
+        yaml_path: The path to the YAML file containing the tool definition.
+                   If it is not an absolute path, it is relative to project_root/tool/tool_definition/
+
+    Returns:
+        A Tool object parsed from the YAML file.
+    """
+
+    if not yaml_path.is_absolute():
+        yaml_path = Path(__file__).parent / "tool_definition" / yaml_path
+
+    with open(yaml_path, "r") as f:
+        tool_dict = yaml.safe_load(f)
+    return Tool(**tool_dict)

microbot/tool/tool_definition/browser-use/browser.py

@@ -0,0 +1,40 @@
+#!/usr/bin/env python3
+
+import asyncio
+import sys
+from pprint import pprint
+
+from dotenv import load_dotenv
+load_dotenv()
+
+from browser_use import Agent, AgentHistoryList, Browser, ChatAzureOpenAI
+
+
+async def main(args: list[str]) -> int:
+    if len(args) > 1:
+        print("browse allows only one arg at a time.")
+        return 1
+
+    if not args:
+        print("Usage: browse <arg>")
+        return 1
+
+    what_to_browse = args[0]
+
+    browser = Browser(
+        headless=True
+        )
+
+    agent = Agent(
+        task=what_to_browse,
+        browser=browser,
+        llm=ChatAzureOpenAI(model="gpt-4.1"),
+        use_vision=False,
+    )
+    history: AgentHistoryList = await agent.run()
+    print("Final Result:")
+    pprint(history.final_result(), indent=4)
+
+
+if __name__ == "__main__":
+    sys.exit(asyncio.run(main(sys.argv[1:])))

microbot/tool_definitions/base_tool.py

@@ -0,0 +1,23 @@
+from abc import ABC, abstractmethod
+
+
+class BaseTool(ABC):
+    @property
+    @abstractmethod
+    def name(self) -> str:
+        pass
+
+    @property
+    @abstractmethod
+    def installation_command(self) -> str:
+        pass
+
+    @property
+    @abstractmethod
+    def verification_command(self) -> str:
+        pass
+
+    @property
+    @abstractmethod
+    def usage_instructions_to_llm(self) -> str:
+        pass

microbot/tool_definitions/ctags.py

@@ -0,0 +1,25 @@
+from microbot.tool_definitions.base_tool import BaseTool
+
+
+class Ctags(BaseTool):
+
+    _instance = None  # Class-level attribute to store the single instance
+    name = "ctags"
+    installation_command = "sudo apt install universal-ctags"
+    verification_command = "ctags --version"
+    usage_instructions_to_llm = (
+        "To use ctags, you can run 'ctags -R .' in your project directory"
+    )
+
+    def __new__(cls, *args, **kwargs):
+        if cls._instance is None:
+            cls._instance = super(Ctags, cls).__new__(cls)
+        return cls._instance
+
+    def __init__(self):
+        # We can still use __init__ for any additional setup if needed
+        if not hasattr(self, "initialized"):
+            self.initialized = True
+            print(f"Singleton instance initialized with name: {self.name}")
+        else:
+            print(f"Attempted to re-initialize an existing instance.")