minitap-mobile-use 2.7.2__tar.gz → 2.8.0__tar.gz

{minitap_mobile_use-2.7.2 → minitap_mobile_use-2.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: minitap-mobile-use
-Version: 2.7.2
+Version: 2.8.0
 Summary: AI-powered multi-agent system that automates real Android and iOS devices through low-level control using LangGraph.
 Author: Pierre-Louis Favreau, Jean-Pierre Lo, Nicolas Dehandschoewercker
 License: MIT License

{minitap_mobile_use-2.7.2 → minitap_mobile_use-2.8.0}/minitap/mobile_use/main.py

@@ -43,7 +43,7 @@ async def run_automation(
         config.with_graph_config_callbacks(graph_config_callbacks)
 
     agent = Agent(config=config.build())
-    agent.init(
+    await agent.init(
         retry_count=int(os.getenv("MOBILE_USE_HEALTH_RETRIES", 5)),
         retry_wait_seconds=int(os.getenv("MOBILE_USE_HEALTH_DELAY", 2)),
     )
@@ -63,7 +63,7 @@ async def run_automation(
 
     await agent.run_task(request=task.build())
 
-    agent.clean()
+    await agent.clean()
 
 
 @app.command()

{minitap_mobile_use-2.7.2 → minitap_mobile_use-2.8.0}/minitap/mobile_use/sdk/agent.py

@@ -13,6 +13,7 @@ from typing import Any, TypeVar, overload
 from adbutils import AdbClient
 from dotenv import load_dotenv
 from langchain_core.messages import AIMessage
+from PIL import Image
 from pydantic import BaseModel
 
 from minitap.mobile_use.agents.outputter.outputter import outputter
@@ -37,12 +38,14 @@ from minitap.mobile_use.graph.state import State
 from minitap.mobile_use.sdk.builders.agent_config_builder import get_default_agent_config
 from minitap.mobile_use.sdk.builders.task_request_builder import TaskRequestBuilder
 from minitap.mobile_use.sdk.constants import DEFAULT_HW_BRIDGE_BASE_URL, DEFAULT_SCREEN_API_BASE_URL
+from minitap.mobile_use.sdk.services.cloud_mobile import CloudMobileService
 from minitap.mobile_use.sdk.services.platform import PlatformService
 from minitap.mobile_use.sdk.types.agent import AgentConfig
 from minitap.mobile_use.sdk.types.exceptions import (
     AgentNotInitializedError,
     AgentProfileNotFoundError,
     AgentTaskRequestError,
+    CloudMobileServiceUninitializedError,
     DeviceNotFoundError,
     ExecutableNotFoundError,
     PlatformServiceUninitializedError,
@@ -92,6 +95,7 @@ class Agent:
     _adb_client: AdbClient | None
     _current_task: asyncio.Task | None = None
     _task_lock: asyncio.Lock
+    _cloud_mobile_id: str | None = None
 
     def __init__(self, *, config: AgentConfig | None = None):
         self._config = config or get_default_agent_config()
@@ -105,19 +109,38 @@ class Agent:
             self._config.servers.screen_api_base_url == DEFAULT_SCREEN_API_BASE_URL
         )
         self._task_lock = asyncio.Lock()
+
         # Initialize platform service if API key is available in environment
-        # Note: Can also be initialized later with API key from request
+        # Note: Can also be initialized later with API key at agent .init()
         if settings.MINITAP_API_KEY:
             self._platform_service = PlatformService()
+            self._cloud_mobile_service = CloudMobileService()
         else:
             self._platform_service = None
+            self._cloud_mobile_service = None
 
-    def init(
+    async def init(
         self,
+        api_key: str | None = None,
         server_restart_attempts: int = 3,
         retry_count: int = 5,
         retry_wait_seconds: int = 5,
     ):
+        if api_key:
+            self._platform_service = PlatformService(api_key=api_key)
+            self._cloud_mobile_service = CloudMobileService(api_key=api_key)
+
+        # Skip initialization for cloud devices - no local setup required
+        if self._config.cloud_mobile_id_or_ref:
+            if not self._cloud_mobile_service:
+                raise CloudMobileServiceUninitializedError()
+            self._cloud_mobile_id = await self._cloud_mobile_service.resolve_cloud_mobile_id(
+                cloud_mobile_id_or_ref=self._config.cloud_mobile_id_or_ref,
+            )
+            logger.info("Cloud device configured - skipping local initialization")
+            self._initialized = True
+            return True
+
         if not which("adb") and not which("xcrun"):
             raise ExecutableNotFoundError("cli_tools")
         if self._is_default_hw_bridge and not which("maestro"):
@@ -233,25 +256,30 @@ class Agent:
         name: str | None = None,
         request: TaskRequest[TOutput] | PlatformTaskRequest[TOutput] | None = None,
     ) -> str | dict | TOutput | None:
+        # Check if cloud mobile is configured
+        if self._config.cloud_mobile_id_or_ref:
+            if request is None or not isinstance(request, PlatformTaskRequest):
+                raise AgentTaskRequestError(
+                    "When using a cloud mobile, only PlatformTaskRequest is supported. "
+                    "Use AgentConfigBuilder.for_cloud_mobile() only with PlatformTaskRequest."
+                )
+            # Use cloud mobile execution path
+            return await self._run_cloud_mobile_task(request=request)
+
+        # Normal local execution path
         if request is not None:
             task_info = None
-            platform_service = None
             if isinstance(request, PlatformTaskRequest):
-                # Initialize platform service with API key from request if provided
-                if request.api_key:
-                    platform_service = PlatformService(api_key=request.api_key)
-                elif self._platform_service:
-                    platform_service = self._platform_service
-                else:
+                if not self._platform_service:
                     raise PlatformServiceUninitializedError()
-                task_info = await platform_service.create_task_run(request=request)
+                task_info = await self._platform_service.create_task_run(request=request)
                 if isinstance(request, CloudDevicePlatformTaskRequest):
                     request.task_run_id = task_info.task_run.id
                     request.task_run_id_available_event.set()
                 self._config.agent_profiles[task_info.llm_profile.name] = task_info.llm_profile
                 request = task_info.task_request
             return await self._run_task(
-                request=request, task_info=task_info, platform_service=platform_service
+                request=request, task_info=task_info, platform_service=self._platform_service
             )
         if goal is None:
             raise AgentTaskRequestError("Goal is required")
@@ -267,6 +295,96 @@ class Agent:
             task_request.with_name(name=name)
         return await self._run_task(task_request.build())
 
+    async def _run_cloud_mobile_task(
+        self,
+        request: PlatformTaskRequest[TOutput],
+    ) -> str | dict | TOutput | None:
+        """
+        Execute a task on a cloud mobile.
+
+        This method triggers the task execution on the Platform and polls
+        for completion without running any agentic logic locally.
+        """
+        if not self._cloud_mobile_id:
+            raise AgentTaskRequestError("Cloud mobile ID is not configured")
+
+        if not self._cloud_mobile_service:
+            raise CloudMobileServiceUninitializedError()
+
+        # Start cloud mobile if not already started
+        logger.info(f"Starting cloud mobile '{self._cloud_mobile_id}'...")
+        await self._cloud_mobile_service.start_and_wait_for_ready(
+            cloud_mobile_id=self._cloud_mobile_id,
+        )
+        logger.info(
+            f"Starting cloud mobile task execution '{self._cloud_mobile_id}'",
+        )
+
+        def log_callback(message: str):
+            """Callback for logging timeline updates."""
+            logger.info(message)
+
+        def status_callback(
+            status: TaskRunStatus,
+            status_message: str | None,
+        ):
+            """Callback for status updates."""
+            logger.info(f"Task status update: [{status}] {status_message}")
+
+        async def _execute_cloud(cloud_mobile_service: CloudMobileService, cloud_mobile_id: str):
+            try:
+                # Execute task on cloud mobile and wait for completion
+                final_status, error, output = await cloud_mobile_service.run_task_on_cloud_mobile(
+                    cloud_mobile_id=cloud_mobile_id,
+                    request=request,
+                    on_status_update=status_callback,
+                    on_log=log_callback,
+                )
+                if final_status == "completed":
+                    logger.success("Cloud mobile task completed successfully")
+                    return output
+                if final_status == "failed":
+                    logger.error(f"Cloud mobile task failed: {error}")
+                    raise AgentTaskRequestError(
+                        f"Task execution failed on cloud mobile: {error}",
+                    )
+                if final_status == "cancelled":
+                    logger.warning("Cloud mobile task was cancelled")
+                    raise AgentTaskRequestError("Task execution was cancelled")
+                logger.error(f"Unknown cloud mobile task status: {final_status}")
+                raise AgentTaskRequestError(f"Unknown task status: {final_status}")
+            except asyncio.CancelledError:
+                # Propagate cancellation to parent coroutine.
+                logger.info("Task cancelled during execution, re-raising CancelledError")
+                raise
+            except AgentTaskRequestError:
+                # Re-raise known exceptions
+                raise
+            except Exception as e:
+                logger.error(f"Unexpected error during cloud mobile task execution: {e}")
+                raise AgentTaskRequestError(f"Unexpected error: {e}") from e
+
+        async with self._task_lock:
+            if self._current_task and not self._current_task.done():
+                logger.warning(
+                    "Another cloud task is running; cancelling it before starting new one.",
+                )
+                self.stop_current_task()
+                try:
+                    await self._current_task
+                except asyncio.CancelledError:
+                    pass
+            try:
+                self._current_task = asyncio.create_task(
+                    _execute_cloud(
+                        cloud_mobile_service=self._cloud_mobile_service,
+                        cloud_mobile_id=self._cloud_mobile_id,
+                    ),
+                )
+                return await self._current_task
+            finally:
+                self._current_task = None
+
     async def _run_task(
         self,
         request: TaskRequest[TOutput],
@@ -456,6 +574,9 @@ class Agent:
         Uses the configured Screen API base URL instead of hardcoding localhost.
         """
         try:
+            # In cloud mode, local streaming health is irrelevant.
+            if self._config.cloud_mobile_id_or_ref:
+                return True
             response = self._screen_api_client.get_with_retry("/streaming-status", timeout=2)
             if response.status_code == 200:
                 data = response.json()
@@ -465,7 +586,86 @@ class Agent:
         except Exception:
             return False
 
-    def clean(self, force: bool = False):
+    async def get_screenshot(self) -> Image.Image:
+        """
+        Capture a screenshot from the mobile device.
+
+        For cloud mobiles, this method calls the mobile-manager endpoint.
+        For local mobiles, it uses ADB (Android) or xcrun (iOS) directly.
+
+        Returns:
+            Screenshot as PIL Image
+
+        Raises:
+            AgentNotInitializedError: If the agent is not initialized
+            PlatformServiceUninitializedError: If cloud mobile service is not available
+            Exception: If screenshot capture fails
+        """
+        # Check if cloud mobile is configured
+        if self._cloud_mobile_id:
+            if not self._cloud_mobile_service:
+                raise CloudMobileServiceUninitializedError()
+            screenshot = await self._cloud_mobile_service.get_screenshot(
+                cloud_mobile_id=self._cloud_mobile_id,
+            )
+            return screenshot
+
+        # Local device - use ADB or xcrun directly
+        if not self._initialized:
+            raise AgentNotInitializedError()
+
+        if self._device_context.mobile_platform == DevicePlatform.ANDROID:
+            # Use ADB to capture screenshot
+            logger.info("Capturing screenshot from local Android device")
+            if not self._adb_client:
+                raise Exception("ADB client not initialized")
+
+            device = self._adb_client.device(serial=self._device_context.device_id)
+            screenshot = await asyncio.to_thread(device.screenshot)
+            logger.info("Screenshot captured from local Android device")
+            return screenshot
+
+        elif self._device_context.mobile_platform == DevicePlatform.IOS:
+            # Use xcrun to capture screenshot
+            import functools
+            import subprocess
+            from io import BytesIO
+
+            logger.info("Capturing screenshot from local iOS device")
+            try:
+                # xcrun simctl io <device> screenshot --type=png -
+                result = await asyncio.to_thread(
+                    functools.partial(
+                        subprocess.run,
+                        [
+                            "xcrun",
+                            "simctl",
+                            "io",
+                            self._device_context.device_id,
+                            "screenshot",
+                            "--type=png",
+                            "-",
+                        ],
+                        capture_output=True,
+                        check=True,
+                    )
+                )
+                # Convert bytes to PIL Image
+                screenshot = Image.open(BytesIO(result.stdout))
+                logger.info("Screenshot captured from local iOS device")
+                return screenshot
+            except subprocess.CalledProcessError as e:
+                logger.error(f"Failed to capture screenshot: {e}")
+                raise Exception(f"Failed to capture screenshot from iOS device: {e}")
+
+        else:
+            raise Exception(f"Unsupported platform: {self._device_context.mobile_platform}")
+
+    async def clean(self, force: bool = False):
+        if self._cloud_mobile_id:
+            self._initialized = False
+            logger.info("✅ Cloud-mode agent stopped.")
+            return
         if not self._initialized and not force:
             return
         screen_api_ok, hw_bridge_ok = stop_servers(

{minitap_mobile_use-2.7.2 → minitap_mobile_use-2.8.0}/minitap/mobile_use/sdk/builders/agent_config_builder.py

@@ -45,6 +45,7 @@ class AgentConfigBuilder:
         self._device_platform: DevicePlatform | None = None
         self._servers: ServerConfig = get_default_servers()
         self._graph_config_callbacks: Callbacks = None
+        self._cloud_mobile_id_or_ref: str | None = None
 
     def add_profile(self, profile: AgentProfile, validate: bool = True) -> "AgentConfigBuilder":
         """
@@ -95,10 +96,35 @@ class AgentConfigBuilder:
             platform: The device platform (ANDROID or IOS)
             device_id: The unique identifier for the device
         """
+        if self._cloud_mobile_id_or_ref is not None:
+            raise ValueError(
+                "Device ID cannot be set when a cloud mobile is already configured.\n"
+                "> for_device() and for_cloud_mobile() are mutually exclusive"
+            )
         self._device_id = device_id
         self._device_platform = platform
         return self
 
+    def for_cloud_mobile(self, cloud_mobile_id_or_ref: str) -> "AgentConfigBuilder":
+        """
+        Configure the mobile-use agent to use a cloud mobile.
+
+        When using a cloud mobile, tasks are executed remotely via the Platform API,
+        and only PlatformTaskRequest can be used.
+
+        Args:
+            cloud_mobile_id_or_ref: The unique identifier or reference name for the cloud mobile.
+                Can be either a UUID (e.g., '550e8400-e29b-41d4-a716-446655440000')
+                or a reference name (e.g., 'my-test-device')
+        """
+        if self._device_id is not None:
+            raise ValueError(
+                "Cloud mobile device ID cannot be set when a device is already configured.\n"
+                "> for_device() and for_cloud_mobile() are mutually exclusive"
+            )
+        self._cloud_mobile_id_or_ref = cloud_mobile_id_or_ref
+        return self
+
     def with_default_task_config(self, config: TaskRequestCommon) -> "AgentConfigBuilder":
         """
         Set the default task configuration.
@@ -217,6 +243,7 @@ class AgentConfigBuilder:
             device_platform=self._device_platform,
             servers=self._servers,
             graph_config_callbacks=self._graph_config_callbacks,
+            cloud_mobile_id_or_ref=self._cloud_mobile_id_or_ref,
         )
 
 

{minitap_mobile_use-2.7.2 → minitap_mobile_use-2.8.0}/minitap/mobile_use/sdk/examples/README.md

@@ -15,7 +15,7 @@ These examples demonstrate two different ways to use the SDK, each applying an a
 This script shows the simplest way to run minitap :
 
 - Visit https://platform.minitap.ai to create a task and get your API key.
-- Initialize the agent with your API key: Agent(minitap_api_key=...).
+- Initialize the agent with your API key: .init(api_key=...).
 - Ask the agent to run one of the tasks you’ve set up in the Minitap platform
   (e.g., "like-instagram-post").
 - The task’s goal and settings live in the Minitap platform, you don’t need

{minitap_mobile_use-2.7.2 → minitap_mobile_use-2.8.0}/minitap/mobile_use/sdk/examples/platform_manual_task_example.py

@@ -34,7 +34,7 @@ async def main() -> None:
     Set MINITAP_API_KEY and MINITAP_BASE_URL environment variables.
     """
     agent = Agent()
-    agent.init()
+    await agent.init()
 
     # Example 1: Simple manual task
     result = await agent.run_task(
@@ -58,7 +58,7 @@ async def main() -> None:
     )
     print("Result 2:", result)
 
-    agent.clean()
+    await agent.clean()
 
 
 if __name__ == "__main__":

{minitap_mobile_use-2.7.2 → minitap_mobile_use-2.8.0}/minitap/mobile_use/sdk/examples/platform_minimal_example.py

@@ -31,16 +31,15 @@ async def main() -> None:
     Set MINITAP_API_KEY and MINITAP_BASE_URL environment variables.
     """
     agent = Agent()
-    agent.init()
+    await agent.init(api_key="<api-key>")  # or set MINITAP_API_KEY env variable
     result = await agent.run_task(
         request=PlatformTaskRequest(
             task="your-task-name",
             profile="your-profile-name",
-            api_key="<api-key>",  # or set MINITAP_API_KEY env variable
         )
     )
     print(result)
-    agent.clean()
+    await agent.clean()
 
 
 if __name__ == "__main__":

{minitap_mobile_use-2.7.2 → minitap_mobile_use-2.8.0}/minitap/mobile_use/sdk/examples/simple_photo_organizer.py

@@ -33,7 +33,7 @@ async def main() -> None:
 
     try:
         # Initialize agent (finds a device, starts required servers)
-        agent.init()
+        await agent.init()
 
         # Calculate yesterday's date for the example
         yesterday = date.today() - timedelta(days=1)
@@ -69,7 +69,7 @@ async def main() -> None:
         print(f"Error: {e}")
     finally:
         # Always clean up resources
-        agent.clean()
+        await agent.clean()
 
 
 if __name__ == "__main__":

{minitap_mobile_use-2.7.2 → minitap_mobile_use-2.8.0}/minitap/mobile_use/sdk/examples/smart_notification_assistant.py

@@ -167,7 +167,7 @@ async def main():
 
     try:
         # Initialize agent (finds a device, starts required servers)
-        agent.init()
+        await agent.init()
 
         print("Checking for notifications...")
 
@@ -217,7 +217,7 @@ async def main():
 
     finally:
         # Clean up
-        agent.clean()
+        await agent.clean()
         print(f"\nTraces saved to: {traces_dir}")