minitap-mobile-use 2.2.0__py3-none-any.whl → 2.4.0__py3-none-any.whl

minitap/mobile_use/sdk/services/platform.py

@@ -0,0 +1,244 @@
+import json
+from datetime import UTC, datetime
+from typing import Any
+
+import httpx
+from pydantic import BaseModel, ValidationError
+
+from minitap.mobile_use.agents.planner.types import Subgoal, SubgoalStatus
+from minitap.mobile_use.config import LLMConfig, settings
+from minitap.mobile_use.sdk.types.exceptions import PlatformServiceError
+from minitap.mobile_use.sdk.types.platform import (
+    CreateTaskRunRequest,
+    LLMProfileResponse,
+    MobileUseSubgoal,
+    SubgoalState,
+    TaskResponse,
+    TaskRunPlanResponse,
+    TaskRunResponse,
+    TaskRunStatus,
+    UpdateTaskRunStatusRequest,
+    UpsertTaskRunAgentThoughtRequest,
+    UpsertTaskRunPlanRequest,
+)
+from minitap.mobile_use.sdk.types.task import (
+    AgentProfile,
+    PlatformTaskInfo,
+    PlatformTaskRequest,
+    TaskRequest,
+)
+from minitap.mobile_use.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+DEFAULT_PROFILE = "default"
+
+
+class PlatformService:
+    def __init__(self, api_key: str | None = None):
+        self._base_url = settings.MINITAP_API_BASE_URL
+
+        if api_key:
+            self._api_key = api_key
+        elif settings.MINITAP_API_KEY:
+            self._api_key = settings.MINITAP_API_KEY.get_secret_value()
+        else:
+            raise PlatformServiceError(
+                message="Please provide an API key or set MINITAP_API_KEY environment variable.",
+            )
+
+        self._timeout = httpx.Timeout(timeout=120)
+        self._client = httpx.AsyncClient(
+            base_url=f"{self._base_url}/api",
+            timeout=self._timeout,
+            headers={
+                "Authorization": f"Bearer {self._api_key}",
+                "Content-Type": "application/json",
+            },
+        )
+
+    async def create_task_run(self, request: PlatformTaskRequest) -> PlatformTaskInfo:
+        try:
+            logger.info(f"Getting task: {request.task}")
+            response = await self._client.get(url=f"v1/tasks/{request.task}")
+            response.raise_for_status()
+            task_data = response.json()
+            task = TaskResponse(**task_data)
+            profile, agent_profile = await self._get_profile(
+                profile_name=request.profile or DEFAULT_PROFILE,
+            )
+            task_request = TaskRequest(
+                # Remote configuration
+                max_steps=task.options.max_steps,
+                goal=task.input_prompt,
+                output_description=task.output_description,
+                enable_remote_tracing=task.options.enable_tracing,
+                profile=profile.name,
+                # Local configuration
+                record_trace=request.record_trace,
+                trace_path=request.trace_path,
+                llm_output_path=request.llm_output_path,
+                thoughts_output_path=request.thoughts_output_path,
+            )
+            task_run = await self._create_task_run(task=task, profile=profile)
+            return PlatformTaskInfo(
+                task_request=task_request,
+                llm_profile=agent_profile,
+                task_run=task_run,
+            )
+        except httpx.HTTPStatusError as e:
+            raise PlatformServiceError(message=f"Failed to get task: {e}")
+
+    async def update_task_run_status(
+        self,
+        task_run_id: str,
+        status: TaskRunStatus,
+        message: str | None = None,
+        output: Any | None = None,
+    ) -> None:
+        try:
+            logger.info(f"Updating task run status for task run: {task_run_id}")
+
+            sanitized_output: str | None = None
+            if isinstance(output, dict):
+                sanitized_output = json.dumps(output)
+            elif isinstance(output, list):
+                sanitized_output = json.dumps(output)
+            elif isinstance(output, BaseModel):
+                sanitized_output = output.model_dump_json()
+            elif isinstance(output, str):
+                sanitized_output = output
+            else:
+                sanitized_output = str(output)
+
+            update = UpdateTaskRunStatusRequest(
+                status=status,
+                message=message,
+                output=sanitized_output,
+            )
+            response = await self._client.patch(
+                url=f"v1/task-runs/{task_run_id}/status",
+                json=update.model_dump(),
+            )
+            response.raise_for_status()
+        except httpx.HTTPStatusError as e:
+            raise PlatformServiceError(message=f"Failed to update task run status: {e}")
+
+    async def upsert_task_run_plan(
+        self,
+        task_run_id: str,
+        started_at: datetime,
+        plan: list[Subgoal],
+        ended_at: datetime | None = None,
+        plan_id: str | None = None,
+    ) -> TaskRunPlanResponse:
+        try:
+            logger.info(f"Upserting task run plan for task run: {task_run_id}")
+            ended, subgoals = self._to_api_subgoals(plan)
+            if not ended_at and ended:
+                ended_at = datetime.now(UTC)
+            update = UpsertTaskRunPlanRequest(
+                started_at=started_at,
+                subgoals=subgoals,
+                ended_at=ended_at,
+            )
+            if plan_id:
+                response = await self._client.put(
+                    url=f"v1/task-runs/{task_run_id}/plans/{plan_id}",
+                    json=update.model_dump(),
+                )
+            else:
+                response = await self._client.post(
+                    url=f"v1/task-runs/{task_run_id}/plans",
+                    json=update.model_dump(),
+                )
+            response.raise_for_status()
+            return TaskRunPlanResponse(**response.json())
+
+        except ValidationError as e:
+            raise PlatformServiceError(message=f"API response validation error: {e}")
+        except httpx.HTTPStatusError as e:
+            raise PlatformServiceError(message=f"Failed to upsert task run plan: {e}")
+
+    async def add_agent_thought(self, task_run_id: str, agent: str, thought: str) -> None:
+        try:
+            logger.info(f"Adding agent thought for task run: {task_run_id}")
+            update = UpsertTaskRunAgentThoughtRequest(
+                agent=agent,
+                content=thought,
+                timestamp=datetime.now(UTC),
+            )
+            response = await self._client.post(
+                url=f"v1/task-runs/{task_run_id}/agent-thoughts",
+                json=update.model_dump(),
+            )
+            response.raise_for_status()
+        except httpx.HTTPStatusError as e:
+            raise PlatformServiceError(message=f"Failed to add agent thought: {e}")
+
+    def _to_api_subgoals(self, subgoals: list[Subgoal]) -> tuple[bool, list[MobileUseSubgoal]]:
+        """
+        Returns a tuple of (plan_ended, subgoal_models)
+        """
+        subgoal_models: list[MobileUseSubgoal] = []
+        plan_ended = True
+        for subgoal in subgoals:
+            if subgoal.status != SubgoalStatus.SUCCESS:
+                plan_ended = False
+            subgoal_models.append(self._to_api_subgoal(subgoal))
+        return plan_ended, subgoal_models
+
+    def _to_api_subgoal(self, subgoal: Subgoal) -> MobileUseSubgoal:
+        state: SubgoalState = "pending"
+        match subgoal.status:
+            case SubgoalStatus.SUCCESS:
+                state = "completed"
+            case SubgoalStatus.FAILURE:
+                state = "failed"
+            case SubgoalStatus.PENDING:
+                state = "started"
+            case SubgoalStatus.NOT_STARTED:
+                state = "pending"
+        return MobileUseSubgoal(
+            name=subgoal.description,
+            state=state,
+            started_at=subgoal.started_at,
+            ended_at=subgoal.ended_at,
+        )
+
+    async def _create_task_run(
+        self,
+        task: TaskResponse,
+        profile: LLMProfileResponse,
+    ) -> TaskRunResponse:
+        try:
+            logger.info(f"Creating task run for task: {task.name}")
+            task_run = CreateTaskRunRequest(
+                task_id=task.id,
+                llm_profile_id=profile.id,
+            )
+            response = await self._client.post(url="v1/task-runs", json=task_run.model_dump())
+            response.raise_for_status()
+            task_run_data = response.json()
+            return TaskRunResponse(**task_run_data)
+        except ValidationError as e:
+            raise PlatformServiceError(message=f"API response validation error: {e}")
+        except httpx.HTTPStatusError as e:
+            raise PlatformServiceError(message=f"Failed to create task run: {e}")
+
+    async def _get_profile(self, profile_name: str) -> tuple[LLMProfileResponse, AgentProfile]:
+        try:
+            logger.info(f"Getting agent profile: {profile_name}")
+            response = await self._client.get(url=f"v1/llm-profiles/{profile_name}")
+            response.raise_for_status()
+            profile_data = response.json()
+            profile = LLMProfileResponse(**profile_data)
+            agent_profile = AgentProfile(
+                name=profile.name,
+                llm_config=LLMConfig(**profile.llms),
+            )
+            return profile, agent_profile
+        except ValidationError as e:
+            raise PlatformServiceError(message=f"API response validation error: {e}")
+        except httpx.HTTPStatusError as e:
+            raise PlatformServiceError(message=f"Failed to get agent profile: {e}")

minitap/mobile_use/sdk/types/__init__.py

@@ -1,29 +1,29 @@
 """Type definitions for the mobile-use SDK."""
 
 from minitap.mobile_use.sdk.types.agent import (
-    ApiBaseUrl,
     AgentConfig,
+    ApiBaseUrl,
     DevicePlatform,
     ServerConfig,
 )
-from minitap.mobile_use.sdk.types.task import (
-    AgentProfile,
-    TaskRequest,
-    TaskStatus,
-    TaskResult,
-    TaskRequestCommon,
-    Task,
-)
 from minitap.mobile_use.sdk.types.exceptions import (
-    AgentProfileNotFoundError,
-    AgentTaskRequestError,
-    DeviceNotFoundError,
-    ServerStartupError,
     AgentError,
     AgentNotInitializedError,
+    AgentProfileNotFoundError,
+    AgentTaskRequestError,
     DeviceError,
+    DeviceNotFoundError,
     MobileUseError,
     ServerError,
+    ServerStartupError,
+)
+from minitap.mobile_use.sdk.types.task import (
+    AgentProfile,
+    PlatformTaskRequest,
+    Task,
+    TaskRequest,
+    TaskRequestCommon,
+    TaskResult,
 )
 
 __all__ = [
@@ -33,7 +33,7 @@ __all__ = [
     "AgentProfile",
     "ServerConfig",
     "TaskRequest",
-    "TaskStatus",
+    "PlatformTaskRequest",
     "TaskResult",
     "TaskRequestCommon",
     "Task",

minitap/mobile_use/sdk/types/exceptions.py

@@ -4,6 +4,8 @@ Exceptions for the Mobile-use SDK.
 This module defines the exception hierarchy used throughout the Mobile-use SDK.
 """
 
+from typing import Literal
+
 
 class MobileUseError(Exception):
     """Base exception class for all Mobile-use SDK exceptions."""
@@ -72,3 +74,58 @@ class AgentProfileNotFoundError(AgentTaskRequestError):
 
     def __init__(self, profile_name: str):
         super().__init__(f"Agent profile {profile_name} not found")
+
+
+EXECUTABLES = Literal["adb", "maestro", "xcrun", "cli_tools"]
+
+
+class ExecutableNotFoundError(MobileUseError):
+    """Exception raised when a required executable is not found."""
+
+    def __init__(self, executable_name: EXECUTABLES):
+        install_instructions: dict[EXECUTABLES, str] = {
+            "adb": "https://developer.android.com/tools/adb",
+            "maestro": "https://docs.maestro.dev/getting-started/installing-maestro",
+            "xcrun": "Install with: xcode-select --install",
+        }
+        if executable_name == "cli_tools":
+            message = (
+                "ADB or Xcode Command Line Tools not found in PATH. "
+                "At least one of them is required to run mobile-use "
+                "depending on the device platform you wish to run (Android: adb, iOS: xcrun)."
+                "Refer to the following links for installation instructions :"
+                f"\n- ADB: {install_instructions['adb']}"
+                f"\n- Xcode Command Line Tools: {install_instructions['xcrun']}"
+            )
+        else:
+            message = f"Required executable '{executable_name}' not found in PATH."
+            if executable_name in install_instructions:
+                message += f"\nTo install it, please visit: {install_instructions[executable_name]}"
+        super().__init__(message)
+
+
+class AgentInvalidApiKeyError(AgentTaskRequestError):
+    """Exception raise when the API key could not have been found"""
+
+    def __init__(self):
+        super().__init__(
+            "Minitap API key is incorrect. Visit https://platform.minitap.ai/api-keys "
+            "to get your API key."
+        )
+
+
+class PlatformServiceUninitializedError(MobileUseError):
+    """Exception raised when a platform service call fails."""
+
+    def __init__(self):
+        super().__init__(
+            "Platform service is not initialized. "
+            "To use Minitap platform service, visit https://platform.minitap.ai.",
+        )
+
+
+class PlatformServiceError(MobileUseError):
+    """Exception raised when a platform service call fails."""
+
+    def __init__(self, message="A platform service-related error occurred"):
+        super().__init__(message)

minitap/mobile_use/sdk/types/platform.py

@@ -0,0 +1,125 @@
+from typing import Annotated, Any, Literal
+from pydantic import BaseModel, ConfigDict, Field, PlainSerializer
+from pydantic.v1.utils import to_lower_camel
+from datetime import datetime
+
+
+TaskRunStatus = Literal["pending", "running", "completed", "failed", "cancelled"]
+
+IsoDatetime = Annotated[
+    datetime,
+    PlainSerializer(
+        func=lambda v: v.isoformat() if v else None,
+        return_type=str,
+        when_used="unless-none",
+    ),
+]
+
+
+class BaseApiModel(BaseModel):
+    model_config = ConfigDict(
+        alias_generator=to_lower_camel,
+        populate_by_name=True,
+        str_strip_whitespace=True,
+    )
+
+
+class LLMProfileResponse(BaseApiModel):
+    """Response model for LLM profile."""
+
+    id: str = Field(..., description="Profile ID")
+    name: str = Field(..., description="Profile name")
+    description: str | None = Field(None, description="Profile description")
+    llms: dict[str, Any] = Field(..., description="LLM configuration")
+    created_at: str = Field(..., description="Creation timestamp (ISO format)")
+    updated_at: str = Field(..., description="Last update timestamp (ISO format)")
+
+
+class TaskOptionsResponse(BaseApiModel):
+    """Response model for task options."""
+
+    id: str = Field(..., description="Options ID")
+    enable_tracing: bool = Field(..., description="Whether tracing is enabled")
+    max_steps: int = Field(..., description="Maximum number of steps")
+    created_at: str = Field(..., description="Creation timestamp (ISO format)")
+    updated_at: str = Field(..., description="Last update timestamp (ISO format)")
+
+
+class TaskResponse(BaseApiModel):
+    """Response model for task."""
+
+    id: str = Field(..., description="Task ID")
+    name: str = Field(..., description="Task name")
+    description: str | None = Field(None, description="Task description")
+    input_prompt: str = Field(..., description="Input prompt")
+    output_description: str | None = Field(None, description="Output description")
+    options: TaskOptionsResponse = Field(..., description="Task options")
+    created_at: str = Field(..., description="Creation timestamp (ISO format)")
+    updated_at: str = Field(..., description="Last update timestamp (ISO format)")
+
+
+class CreateTaskRunRequest(BaseApiModel):
+    """Request model for creating a task run."""
+
+    task_id: str = Field(..., description="ID of the task to run")
+    llm_profile_id: str = Field(..., description="LLM profile ID to use")
+
+
+class UpdateTaskRunStatusRequest(BaseApiModel):
+    """Request model for updating task run status."""
+
+    status: TaskRunStatus = Field(..., description="New status of the task run")
+    message: str | None = Field(None, description="Message associated with the status")
+    output: str | None = Field(None, description="Output of the task run")
+
+
+class TaskRunResponse(BaseApiModel):
+    """Response model for a single task run."""
+
+    id: str = Field(..., description="Unique identifier for the task run")
+    task: TaskResponse = Field(..., description="ID of the task this run is for")
+    llm_profile: LLMProfileResponse = Field(..., description="LLM profile ID used for this run")
+    status: TaskRunStatus = Field(..., description="Current status of the task run")
+    input_prompt: str = Field(..., description="Input prompt for this task run")
+    output_description: str | None = Field(None, description="Description of expected output")
+    created_at: datetime = Field(..., description="When the task run was created")
+    started_at: datetime | None = Field(None, description="When the task run started")
+    finished_at: datetime | None = Field(None, description="When the task run finished")
+
+
+SubgoalState = Literal["pending", "started", "completed", "failed"]
+
+
+class MobileUseSubgoal(BaseModel):
+    """Upsert MobileUseSubgoal API model."""
+
+    name: str = Field(..., description="Name of the subgoal")
+    state: SubgoalState = Field(default="pending", description="Current state of the subgoal")
+    started_at: IsoDatetime | None = Field(default=None, description="When the subgoal started")
+    ended_at: IsoDatetime | None = Field(default=None, description="When the subgoal ended")
+
+
+class UpsertTaskRunPlanRequest(BaseApiModel):
+    """Upsert MobileUseSubgoal API model."""
+
+    started_at: IsoDatetime = Field(..., description="When the plan started")
+    subgoals: list[MobileUseSubgoal] = Field(..., description="Subgoals of the plan")
+    ended_at: IsoDatetime | None = Field(
+        default=None,
+        description="When the plan ended (replanned or completed)",
+    )
+
+
+class TaskRunPlanResponse(UpsertTaskRunPlanRequest):
+    """Response model for a task run plan."""
+
+    id: str = Field(..., description="Unique identifier for the task run plan")
+    task_run_id: str = Field(..., description="ID of the task run this plan is for")
+
+
+class UpsertTaskRunAgentThoughtRequest(BaseApiModel):
+    """Upsert MobileUseAgentThought request model."""
+
+    agent: str = Field(..., description="Agent that produced the thought")
+    content: str = Field(..., description="Content of the thought")
+    timestamp: IsoDatetime = Field(..., description="Timestamp of the thought (UTC)")

minitap/mobile_use/sdk/types/task.py

@@ -2,8 +2,8 @@
 Task-related type definitions for the Mobile-use SDK.
 """
 
+from collections.abc import Callable, Coroutine
 from datetime import datetime
-from enum import Enum
 from pathlib import Path
 from typing import Any, TypeVar, overload
 
@@ -12,6 +12,7 @@ from pydantic import BaseModel, Field
 from minitap.mobile_use.config import LLMConfig, get_default_llm_config
 from minitap.mobile_use.constants import RECURSION_LIMIT
 from minitap.mobile_use.context import DeviceContext
+from minitap.mobile_use.sdk.types.platform import TaskRunResponse, TaskRunStatus
 from minitap.mobile_use.sdk.utils import load_llm_config_override
 
 
@@ -54,21 +55,11 @@ class AgentProfile(BaseModel):
         return f"Profile {self.name}:\n{self.llm_config}"
 
 
-class TaskStatus(str, Enum):
-    """Task execution status enumeration."""
-
-    PENDING = "PENDING"
-    RUNNING = "RUNNING"
-    COMPLETED = "COMPLETED"
-    FAILED = "FAILED"
-    CANCELLED = "CANCELLED"
-
-
 T = TypeVar("T", bound=BaseModel)
 TOutput = TypeVar("TOutput", bound=BaseModel | None)
 
 
-class TaskRequestCommon(BaseModel):
+class TaskRequestBase(BaseModel):
     """
     Defines common parameters of a mobile automation task request.
     """
@@ -80,6 +71,14 @@ class TaskRequestCommon(BaseModel):
     thoughts_output_path: Path | None = None
 
 
+class TaskRequestCommon(TaskRequestBase):
+    """
+    Defines common parameters for any task request.
+    """
+
+    max_steps: int = RECURSION_LIMIT
+
+
 class TaskRequest[TOutput](TaskRequestCommon):
     """
     Defines the format of a mobile automation task request.
@@ -103,6 +102,23 @@ class TaskRequest[TOutput](TaskRequestCommon):
     task_name: str | None = None
     output_description: str | None = None
     output_format: type[TOutput] | None = None
+    enable_remote_tracing: bool = False
+
+
+class PlatformTaskRequest[TOutput](TaskRequestBase):
+    """
+    Minitap-specific task request for SDK usage via the gateway platform.
+
+    Attributes:
+        task: Required task name specified by the user on the platform
+        profile: Optional profile name specified by the user on the platform
+        api_key: Optional API key to authenticate with the platform
+                 (overrides MINITAP_API_KEY env variable)
+    """
+
+    task: str
+    profile: str | None = None
+    api_key: str | None = None
 
 
 class TaskResult(BaseModel):
@@ -156,22 +172,30 @@ class Task(BaseModel):
 
     id: str
     device: DeviceContext
-    status: TaskStatus
+    status: TaskRunStatus
+    status_message: str | None = None
+    on_status_changed: Callable[[TaskRunStatus, str | None, Any | None], Coroutine] | None = None
     request: TaskRequest
     created_at: datetime
     ended_at: datetime | None = None
     result: TaskResult | None = None
 
-    def finalize(
+    async def finalize(
         self,
         content: Any | None = None,
         state: dict | None = None,
         error: str | None = None,
         cancelled: bool = False,
     ):
-        self.status = TaskStatus.COMPLETED if error is None else TaskStatus.FAILED
-        if self.status == TaskStatus.FAILED and cancelled:
-            self.status = TaskStatus.CANCELLED
+        new_status: TaskRunStatus = "completed" if error is None else "failed"
+        if new_status == "failed" and cancelled:
+            new_status = "cancelled"
+        message = "Task completed successfully"
+        if new_status == "failed":
+            message = "Task failed" + (f": {error}" if error else "")
+        elif new_status == "cancelled":
+            message = "Task cancelled" + (f": {error}" if error else "")
+        await self.set_status(status=new_status, message=message, output=content or error)
         self.ended_at = datetime.now()
 
         duration = self.ended_at - self.created_at
@@ -189,4 +213,23 @@ class Task(BaseModel):
         )
 
     def get_name(self) -> str:
+        if isinstance(self.request, PlatformTaskRequest):
+            return self.request.task
         return self.request.task_name or self.id
+
+    async def set_status(
+        self,
+        status: TaskRunStatus,
+        message: str | None = None,
+        output: Any | None = None,
+    ):
+        self.status = status
+        self.status_message = message
+        if self.on_status_changed:
+            await self.on_status_changed(status, message, output)
+
+
+class PlatformTaskInfo(BaseModel):
+    task_request: TaskRequest = Field(..., description="Task request")
+    llm_profile: AgentProfile = Field(..., description="LLM profile")
+    task_run: TaskRunResponse = Field(..., description="Task run instance on the platform")

minitap/mobile_use/servers/device_hardware_bridge.py

@@ -6,6 +6,7 @@ import time
 from enum import Enum
 
 import requests
+
 from minitap.mobile_use.context import DevicePlatform
 from minitap.mobile_use.servers.utils import is_port_in_use
 
@@ -37,7 +38,7 @@ class DeviceHardwareBridge:
         try:
             creation_flags = 0
             if hasattr(subprocess, "CREATE_NO_WINDOW"):
-                creation_flags = subprocess.CREATE_NO_WINDOW
+                creation_flags = subprocess.CREATE_NO_WINDOW  # pyright: ignore[reportAttributeAccessIssue]
 
             maestro_platform = "android" if self.platform == DevicePlatform.ANDROID else "ios"
             cmd = ["maestro", "--device", self.device_id, "--platform", maestro_platform]
@@ -175,7 +176,7 @@ class DeviceHardwareBridge:
         ]
 
     def start(self):
-        if is_port_in_use(DEVICE_HARDWARE_BRIDGE_PORT):
+        if is_port_in_use(port=DEVICE_HARDWARE_BRIDGE_PORT):
             print("Maestro port already in use - assuming Maestro is running.")
             self.status = BridgeStatus.RUNNING
             return True