microbots 0.0.1__py3-none-any.whl

microbot/MicroBot.py

@@ -0,0 +1,173 @@
+import json
+import os
+import time
+from dataclasses import dataclass
+from enum import StrEnum
+from logging import getLogger
+from typing import Optional
+
+from microbot.constants import ModelProvider, PermissionLabels, PermissionMapping
+from microbot.environment.local_docker.LocalDockerEnvironment import LocalDockerEnvironment
+from microbot.llm.openai_api import OpenAIApi
+from microbot.tool_definitions.base_tool import BaseTool
+from microbot.utils.logger import LogLevelEmoji, dividerString
+from microbot.utils.network import get_free_port
+
+logger = getLogger(" MicroBot ")
+
+llm_output_format = """```json
+{
+    task_done: true | false,
+    command: "<command to run> | null",
+    result: str | null
+}
+```
+"""
+
+system_prompt_common = """There is a shell session open for you. 
+                I will provide a task to achieve using the shell. 
+                You will provide the commands to achieve the task in this particular below json format, Ensure all the time to respond in this format only and nothing else, also all the properties ( task_done, command, result ) are mandatory on each response
+                {llm_output_format}
+                after each command I will provide the output of the command. 
+                ensure to run only one command at a time.
+                I won't be able to intervene once I have given task. ."""
+
+
+class BotType(StrEnum):
+    READING_BOT = "READING_BOT"
+    WRITING_BOT = "WRITING_BOT"
+    BROWSING_BOT = "BROWSING_BOT"
+    CUSTOM_BOT = "CUSTOM_BOT"
+
+
+@dataclass
+class BotRunResult:
+    status: bool
+    result: str | None
+    error: Optional[str]
+
+
+class MicroBot:
+
+    def __init__(
+        self,
+        bot_type: BotType,
+        model: str,
+        system_prompt: Optional[str] = None,
+        environment: Optional[any] = None,
+        additional_tools: Optional[list[BaseTool]] = [],
+        folder_to_mount: Optional[str] = None,
+        permission: Optional[PermissionLabels] = None,
+    ):
+        # validate init values before assigning
+        self.permission = permission
+        self.permission = permission
+        if folder_to_mount is not None:
+            self.folder_to_mount_base_path = os.path.basename(folder_to_mount)  # TODO
+
+        self._validate_model_and_provider(model)
+        self._validate_model_and_provider(model)
+        self.permission_key = PermissionMapping.MAPPING.get(self.permission)
+        self.system_prompt = system_prompt
+        self.system_prompt = system_prompt
+        self.model = model
+        self.bot_type = bot_type
+        self.model_provider = model.split("/")[0]
+        self.deployment_name = model.split("/")[1]
+        self.environment = environment
+        self._create_environment(folder_to_mount)
+        self._create_llm()
+
+    def run(self, task, max_iterations=20, timeout_in_seconds=200) -> BotRunResult:
+
+        iteration_count = 1
+        # start timer
+        start_time = time.time()
+        timeout = timeout_in_seconds
+        llm_response = self.llm.ask(task)
+        return_value = BotRunResult(
+            status=False,
+            result=None,
+            error="Did not complete",
+        )
+        logger.info("%s TASK STARTED : %s...", LogLevelEmoji.INFO, task[0:15])
+        while llm_response.task_done is False:
+            print(dividerString)
+            logger.info(
+                " %s LLM Iteration Count : %d", LogLevelEmoji.INFO, iteration_count
+            )
+            logger.info(
+                " ➡️  LLM tool call : %s",
+                json.dumps(llm_response.command),
+            )
+            # increment iteration count
+            iteration_count += 1
+            if iteration_count >= max_iterations:
+                return_value.error = f"Max iterations {max_iterations} reached"
+                return return_value
+
+            # check if timeout has reached
+            current_time = time.time()
+            elapsed_time = current_time - start_time
+
+            if elapsed_time > timeout:
+                logger.error(
+                    "Iteration %d with response %s",
+                    iteration_count,
+                    json.dumps(llm_response),
+                )
+                return_value.error = f"Timeout of {timeout} seconds reached"
+                return return_value
+
+            llm_command_output = self.environment.execute(llm_response.command)
+            logger.info(
+                " ⬅️  Command Execution Output : %s",
+                llm_command_output,
+            )
+            # Convert CmdReturn to string for LLM
+            if llm_command_output.stdout:
+                output_text = llm_command_output.stdout
+            elif llm_command_output.stderr:
+                output_text = f"COMMUNICATION ERROR: {llm_command_output.stderr}"
+            else:
+                output_text = "No output received"
+
+            llm_response = self.llm.ask(output_text)
+
+        logger.info("🔚 TASK COMPLETED : %s...", task[0:15])
+        return BotRunResult(status=True, result=llm_response.result, error=None)
+
+    def _create_environment(self, folder_to_mount):
+        if self.environment is None:
+            # check for a free port in the system and assign to environment
+
+            free_port = get_free_port()
+
+            self.environment = LocalDockerEnvironment(
+                port=free_port,
+                folder_to_mount=folder_to_mount,
+                permission=self.permission,
+            )
+
+    def _create_llm(self):
+        if self.model_provider == ModelProvider.OPENAI:
+            self.llm = OpenAIApi(
+                system_prompt=self.system_prompt, deployment_name=self.deployment_name
+            )
+
+    def _validate_model_and_provider(self, model):
+        # Ensure it has only only slash
+        if model.count("/") != 1:
+            raise ValueError("Model should be in the format <provider>/<model_name>")
+        provider = model.split("/")[0]
+        if provider not in [e.value for e in ModelProvider]:
+            raise ValueError(f"Unsupported model provider: {provider}")
+
+    def __del__(self):
+        if self.environment:
+            try:
+                self.environment.stop()
+            except Exception as e:
+                logger.error(
+                    "%s Error while stopping environment: %s", LogLevelEmoji.ERROR, e
+                )

microbot/__init__.py

@@ -0,0 +1,10 @@
+from microbot.bot import ReadingBot, WritingBot, BrowserBot, CustomBot
+
+__all__ = [
+    "ReadingBot",
+    "WritingBot",
+    "BrowserBot",
+    "CustomBot"
+]
+
+__version__ = "0.0.1"

microbot/bot/BrowserBot.py

@@ -0,0 +1,32 @@
+import os
+from typing import Optional
+
+from microbot.constants import PermissionLabels
+from microbot.MicroBot import BotType, MicroBot, system_prompt_common
+from microbot.tool_definitions.base_tool import BaseTool
+
+
+class BrowserBot(MicroBot):
+
+    def __init__(
+        self,
+        model: str,
+        environment: Optional[any] = None,
+        additional_tools: Optional[list[BaseTool]] = [],
+    ):
+        # validate init values before assigning
+        bot_type = BotType.BROWSING_BOT
+        permission = PermissionLabels.READ_WRITE
+        system_prompt = f"""
+        {system_prompt_common}
+        You are also provided access to internet to search for information.
+        """
+
+        super().__init__(
+            bot_type,
+            model,
+            system_prompt,
+            environment,
+            additional_tools,
+            permission,
+        )

microbot/bot/CustomBot.py

@@ -0,0 +1,31 @@
+import os
+from typing import Optional
+
+from microbot.constants import PermissionLabels
+from microbot.MicroBot import BotType, MicroBot
+from microbot.tool_definitions.base_tool import BaseTool
+
+
+class BrowserBot(MicroBot):
+
+    def __init__(
+        self,
+        model: str,
+        system_prompt: str,
+        folder_to_mount: Optional[str] = None,
+        environment: Optional[any] = None,
+        additional_tools: Optional[list[BaseTool]] = [],
+    ):
+        # validate init values before assigning
+        bot_type = BotType.BROWSING_BOT
+        permission = PermissionLabels.READ_WRITE
+
+        super().__init__(
+            bot_type,
+            model,
+            system_prompt,
+            environment,
+            additional_tools,
+            folder_to_mount,
+            permission,
+        )

microbot/bot/ReadingBot.py

@@ -0,0 +1,41 @@
+from pathlib import Path
+from typing import Optional
+
+from microbot.constants import DOCKER_WORKING_DIR, PermissionLabels
+from microbot.MicroBot import BotType, MicroBot, system_prompt_common
+from microbot.tool_definitions.base_tool import BaseTool
+
+
+class ReadingBot(MicroBot):
+
+    def __init__(
+        self,
+        model: str,
+        folder_to_mount: str,
+        environment: Optional[any] = None,
+        additional_tools: Optional[list[BaseTool]] = [],
+    ):
+        # validate init values before assigning
+        bot_type = BotType.READING_BOT
+        permission = PermissionLabels.READ_ONLY
+
+        base_name = Path(folder_to_mount).name
+
+        system_prompt = f"""
+        {system_prompt_common}
+        You are a reading bot. 
+        You are only provided access to read files inside the mounted directory.
+        The directory is mounted at /{DOCKER_WORKING_DIR}/{base_name} in your current environment.
+        You can access files using paths like /{DOCKER_WORKING_DIR}/{base_name}/filename.txt or by changing to that directory first.
+        Once all the commands are done, and task is verified finally give me the result.
+        """
+
+        super().__init__(
+            bot_type,
+            model,
+            system_prompt,
+            environment,
+            additional_tools,
+            folder_to_mount,
+            permission,
+        )

microbot/bot/WritingBot.py

@@ -0,0 +1,38 @@
+from typing import Optional
+
+from microbot.constants import PermissionLabels
+from microbot.MicroBot import BotType, MicroBot, system_prompt_common
+from microbot.tool_definitions.base_tool import BaseTool
+
+
+class WritingBot(MicroBot):
+
+    def __init__(
+        self,
+        model: str,
+        folder_to_mount: str,
+        environment: Optional[any] = None,
+        additional_tools: Optional[list[BaseTool]] = [],
+    ):
+        # validate init values before assigning
+        bot_type = BotType.WRITING_BOT
+        permission = PermissionLabels.READ_WRITE
+
+        system_prompt = f"""
+        {system_prompt_common}
+        You are a writing bot. 
+        You are only provided access to write files inside the mounted directory.
+        The directory is mounted at /app/{folder_to_mount} in your current environment.
+        You can access files using paths like /app/{folder_to_mount}/filename.txt or by changing to that directory first.
+        Once all the commands are done, and task is verified finally give me the result.
+        """
+
+        super().__init__(
+            bot_type,
+            model,
+            system_prompt,
+            environment,
+            additional_tools,
+            folder_to_mount,
+            permission,
+        )

microbot/bot/__init__.py

@@ -0,0 +1,4 @@
+from .ReadingBot import ReadingBot
+from .WritingBot import WritingBot
+
+__all__ = ["ReadingBot", "WritingBot"]

microbot/constants.py

@@ -0,0 +1,25 @@
+from enum import Enum, StrEnum
+from typing import Optional, TypedDict
+
+
+class ModelProvider(StrEnum):
+    OPENAI = "openai"
+
+
+class ModelEnum(StrEnum):
+    GPT_5 = "gpt-5"
+
+
+class PermissionLabels(StrEnum):
+    READ_ONLY = "READ_ONLY"
+    READ_WRITE = "READ_WRITE"
+
+
+class PermissionMapping:
+    MAPPING = {
+        PermissionLabels.READ_ONLY: "ro",
+        PermissionLabels.READ_WRITE: "rw",
+    }
+
+
+DOCKER_WORKING_DIR = "workdir"

microbot/environment/Environment.py

@@ -0,0 +1,22 @@
+from abc import ABC, abstractmethod
+from typing import Optional
+
+class CmdReturn:
+    def __init__(self, stdout: str, stderr: str, return_code: int):
+        self.stdout = stdout
+        self.stderr = stderr
+        self.return_code = return_code
+
+
+class Environment(ABC):
+    @abstractmethod
+    def start(self):
+        pass
+
+    @abstractmethod
+    def stop(self):
+        pass
+
+    @abstractmethod
+    def execute(self, command: str, timeout: Optional[int] = 300) -> CmdReturn:
+        pass

microbot/environment/local_docker/LocalDockerEnvironment.py

@@ -0,0 +1,156 @@
+import logging
+import os
+import time
+from pathlib import Path
+from typing import Optional
+
+from microbot.environment.Environment import Environment, CmdReturn
+
+import docker
+import requests
+
+logger = logging.getLogger(__name__)
+
+WORKING_DIR = str(Path.home() / "MICROBOT_WORKDIR")
+DOCKER_WORKING_DIR = "/workdir"
+
+
+class LocalDockerEnvironment(Environment):
+    def __init__(
+        self,
+        port: int,
+        folder_to_mount: Optional[str] = None,
+        permission: Optional[str] = None,
+        image: str = "kavyasree261002/shell_server:latest",
+    ):
+        if folder_to_mount is None and permission is not None:
+            raise ValueError("permission provided but folder_to_mount is None")
+        elif 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 ["READ_ONLY", "READ_WRITE"]:
+            raise ValueError(
+                "permission must be 'READ_ONLY' or 'READ_WRITE' when provided"
+            )
+
+        self.image = image
+        self.folder_to_mount = folder_to_mount
+        self.permission = permission
+        self.container = None
+        self.client = docker.from_env()
+        self.port = port  # required host port
+        self.container_port = 8080
+        self._create_working_dir()
+        self.start()
+
+    def _create_working_dir(self):
+        if not os.path.exists(WORKING_DIR):
+            os.makedirs(WORKING_DIR)
+            logger.info("🗂️ Created working directory at %s", WORKING_DIR)
+        else:
+            logger.info("🗂️ Working directory already exists at %s", WORKING_DIR)
+
+    def start(self):
+        mode_map = {"READ_ONLY": "ro", "READ_WRITE": "rw"}
+        volumes_config = {WORKING_DIR: {"bind": DOCKER_WORKING_DIR, "mode": "rw"}}
+        if self.folder_to_mount and self.permission:
+            if self.permission == "READ_ONLY":
+                volumes_config[self.folder_to_mount] = {
+                    "bind": f"/ro/{os.path.basename(self.folder_to_mount)}",
+                    "mode": mode_map[self.permission],
+                }
+                logger.info(
+                    "📦 Volume mapping: %s → /ro/%s",
+                    self.folder_to_mount,
+                    os.path.basename(self.folder_to_mount),
+                )
+            else:
+                volumes_config[self.folder_to_mount] = {
+                    "bind": f"/{DOCKER_WORKING_DIR}/{os.path.basename(self.folder_to_mount)}",
+                    "mode": mode_map[self.permission],
+                }
+                logger.debug(
+                    "📦 Volume mapping: %s → /{DOCKER_WORKING_DIR}/%s",
+                    self.folder_to_mount,
+                    os.path.basename(self.folder_to_mount),
+                )
+
+        # Port mapping
+        port_mapping = {f"{self.container_port}/tcp": self.port}
+
+        self.container = self.client.containers.run(
+            self.image,
+            volumes=volumes_config,
+            ports=port_mapping,
+            detach=True,
+            working_dir="/app",
+            privileged=True,  # Required for mounting overlayfs
+            environment={"BOT_PORT": str(self.container_port)},
+        )
+        logger.info(
+            "🚀 Started container %s with image %s on host port %s",
+            self.container.id[:12],
+            self.image,
+            self.port,
+        )
+        time.sleep(2)  # Give some time for the server to start
+
+        if self.permission == "READ_ONLY":
+            self._setup_overlay_mount(self.folder_to_mount)
+
+    def _setup_overlay_mount(self, folder_to_mount: str):
+        path_name = os.path.basename(os.path.abspath(folder_to_mount))
+        # Mount /ro/path_name to /{WORKING_DIR}/path_name using overlayfs
+        mount_command = (
+            f"mkdir -p /overlaydir && "
+            f"mkdir -p /{DOCKER_WORKING_DIR}/{path_name} /{DOCKER_WORKING_DIR}/overlay/{path_name}/upper /{DOCKER_WORKING_DIR}/overlay/{path_name}/work && "
+            f"mount -t overlay overlay -o lowerdir=/ro/{path_name},upperdir=/{DOCKER_WORKING_DIR}/overlay/{path_name}/upper,workdir=/{DOCKER_WORKING_DIR}/overlay/{path_name}/work /{DOCKER_WORKING_DIR}/{path_name}"
+        )
+        self.execute(mount_command)
+        logger.info(
+            "🔒 Set up overlay mount for read-only directory at /{DOCKER_WORKING_DIR}/%s",
+            path_name,
+        )
+
+    def stop(self):
+        """Stop and remove the container"""
+        if self.container:
+            self.container.stop()
+            self.container.remove()
+            self.container = None
+
+        # Remove working directory
+        if os.path.exists(WORKING_DIR):
+            try:
+                import shutil
+
+                shutil.rmtree(WORKING_DIR)
+                logger.info("🗑️ Removed working directory at %s", WORKING_DIR)
+            except Exception as e:
+                logger.error("❌ Failed to remove working directory: %s", e)
+
+    def execute(self, command: str, timeout: Optional[int] = 10) -> CmdReturn: # TODO: Need proper return value
+        logger.debug("➡️  Executing command in container: %s", command)
+        try:
+            response = requests.post(
+                f"http://localhost:{self.port}/",
+                json={"message": command},
+                timeout=timeout,
+            )
+            response.raise_for_status()
+            logger.debug("⬅️  Command output: %s", response.json().get("output", ""))
+            output = response.json().get("output", "")
+            return CmdReturn(
+                stdout=output, stderr="", return_code=0
+            )
+            self.container.reload()
+            logger.info("ℹ️ Container status: %s", self.container.status)
+            if self.container.status != "running":
+                logs = self.container.logs().decode("utf-8", errors="replace")
+                logger.error("🛑 Container not running. Recent logs below:\n%s", logs)
+            return CmdReturn(stdout="", stderr="Connection error", return_code=1)
+        except requests.exceptions.RequestException as e:
+            logger.exception("❌ Request failed while executing command: %s", e)
+            return CmdReturn(stdout="", stderr=str(e), return_code=1)
+        except Exception as e:
+            logger.exception("❌ Unexpected error while executing command: %s", e)
+            return CmdReturn(stdout="", stderr="Unexpected error", return_code=1)

microbot/environment/local_docker/__init__.py

@@ -0,0 +1 @@
+from .LocalDockerEnvironment import LocalDockerEnvironment