minitap-mobile-use 3.3.0__py3-none-any.whl

minitap/mobile_use/sdk/types/exceptions.py

@@ -0,0 +1,138 @@
+"""
+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."""
+
+    def __init__(self, message="An error occurred in the Mobile-use SDK"):
+        self.message = message
+        super().__init__(self.message)
+
+
+class DeviceError(MobileUseError):
+    """Exception raised for errors related to mobile devices."""
+
+    def __init__(self, message="A device-related error occurred"):
+        super().__init__(message)
+
+
+class DeviceNotFoundError(DeviceError):
+    """Exception raised when no mobile device is found."""
+
+    def __init__(self, message="No mobile device found"):
+        super().__init__(message)
+
+
+class ServerError(MobileUseError):
+    """Exception raised for errors related to Mobile-use servers."""
+
+    def __init__(self, message="A server-related error occurred"):
+        super().__init__(message)
+
+
+class ServerStartupError(ServerError):
+    """Exception raised when Mobile-use servers fail to start."""
+
+    def __init__(self, server_name=None, message=None):
+        if server_name and not message:
+            message = f"Failed to start {server_name}"
+        elif not message:
+            message = "Failed to start Mobile-use servers"
+        super().__init__(message)
+        self.server_name = server_name
+
+
+class AgentError(MobileUseError):
+    """Exception raised for errors related to the Mobile-use agent."""
+
+    def __init__(self, message="An agent-related error occurred"):
+        super().__init__(message)
+
+
+class AgentNotInitializedError(AgentError):
+    """Exception raised when attempting operations on an uninitialized agent."""
+
+    def __init__(self, message="Agent is not initialized. Call init() first"):
+        super().__init__(message)
+
+
+class AgentTaskRequestError(AgentError):
+    """Exception raised when a requested task is invalid."""
+
+    def __init__(self, message="An agent task-related error occurred"):
+        super().__init__(message)
+
+
+class AgentProfileNotFoundError(AgentTaskRequestError):
+    """Exception raised when an agent profile is not found."""
+
+    def __init__(self, profile_name: str):
+        super().__init__(f"Agent profile {profile_name} not found")
+
+
+EXECUTABLES = Literal["adb", "xcrun", "idb", "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",
+            "idb": "https://fbidb.io/docs/installation/",
+            "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 CloudMobileServiceUninitializedError(MobileUseError):
+    """Exception raised when a cloud mobile service call fails."""
+
+    def __init__(self):
+        super().__init__("Cloud mobile service is not initialized!")
+
+
+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,183 @@
+from datetime import datetime
+from typing import Annotated, Any, Literal
+
+from pydantic import BaseModel, ConfigDict, Field, PlainSerializer
+from pydantic.v1.utils import to_lower_camel
+
+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")
+    enable_video_tools: bool = Field(..., description="Whether video tools are enabled")
+    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")
+    virtual_mobile_id: str | None = Field(None, description="Virtual mobile ID to use")
+    locked_app_package: str | None = Field(None, description="App package to lock for the task run")
+    execution_origin: str | None = Field(None, description="Origin of the task execution")
+    enable_video_tools: bool = Field(
+        default=False,
+        description="Whether video tools are enabled for this task run",
+    )
+
+
+class CreateOrphanTaskRunRequest(BaseApiModel):
+    """Request model for creating an orphan task run (without a parent task)."""
+
+    input_prompt: str = Field(
+        ...,
+        description="Input prompt for the task run",
+    )
+    output_description: str | None = Field(
+        None,
+        description="Optional output description",
+    )
+    llm_profile_id: str = Field(
+        ...,
+        description="LLM profile ID to use",
+    )
+    virtual_mobile_id: str | None = Field(
+        None,
+        description="Optional virtual mobile ID on which it runs",
+    )
+    locked_app_package: str | None = Field(
+        None,
+        description="Optional app package to lock execution to",
+    )
+    execution_origin: str | None = Field(
+        None,
+        description="Origin of the task run execution",
+    )
+    max_steps: int | None = Field(
+        None,
+        description="Maximum number of steps for the task run",
+    )
+    enable_video_tools: bool = Field(
+        default=False,
+        description="Whether video tools are enabled for this task run",
+    )
+
+
+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 | None = Field(
+        ..., description="ID of the task this run is for or None if manually created"
+    )
+    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")
+    locked_app_package: str | None = Field(
+        None, description="The app package to lock for the task run"
+    )
+
+
+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)")
+
+
+class TrajectoryGifUploadResponse(BaseApiModel):
+    """Response containing trajectory GIF signed upload URL."""
+
+    signed_url: str = Field(..., description="Signed upload URL for the trajectory GIF")
+    task_run_id: str = Field(..., description="Task run ID for which the GIF URL was generated")
+    file_path: str = Field(..., description="Path where the GIF will be stored")

minitap/mobile_use/sdk/types/task.py

@@ -0,0 +1,269 @@
+"""
+Task-related type definitions for the Mobile-use SDK.
+"""
+
+import tempfile
+from asyncio import Event
+from collections.abc import Callable, Coroutine
+from datetime import datetime
+from pathlib import Path
+from typing import Any, TypeVar, overload
+
+from pydantic import BaseModel, ConfigDict, 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
+
+
+class AgentProfile(BaseModel):
+    """
+    Represents a mobile-use agent profile.
+
+    Attributes:
+        name: Name of the agent - used to reference the agent when running tasks.
+        llm_config: LLM configuration for the agent.
+    """
+
+    name: str
+    llm_config: LLMConfig = Field(default_factory=get_default_llm_config)
+
+    @overload
+    def __init__(self, *, name: str, llm_config: LLMConfig): ...
+
+    @overload
+    def __init__(self, *, name: str, from_file: str): ...
+
+    def __init__(
+        self,
+        *,
+        name: str,
+        llm_config: LLMConfig | None = None,
+        from_file: str | None = None,
+        **kwargs,
+    ):
+        kwargs["name"] = name
+        if from_file:
+            kwargs["llm_config"] = load_llm_config_override(Path(from_file))
+        elif llm_config:
+            kwargs["llm_config"] = llm_config
+        else:
+            raise ValueError("Either llm_config or from_file must be provided")
+        super().__init__(**kwargs)
+
+    def __str__(self):
+        return f"Profile {self.name}:\n{self.llm_config}"
+
+
+T = TypeVar("T", bound=BaseModel)
+TOutput = TypeVar("TOutput", bound=BaseModel | None)
+
+
+class TaskRequestBase(BaseModel):
+    """
+    Defines common parameters of a mobile automation task request.
+    """
+
+    max_steps: int = RECURSION_LIMIT
+    record_trace: bool = False
+    trace_path: Path = Path("mobile-use-traces")
+    llm_output_path: Path | None = None
+    thoughts_output_path: Path | None = None
+
+
+class TaskRequestCommon(TaskRequestBase):
+    """
+    Defines common parameters for any task request.
+    """
+
+    max_steps: int = RECURSION_LIMIT
+    locked_app_package: str | None = None
+
+
+class TaskRequest[TOutput](TaskRequestCommon):
+    """
+    Defines the format of a mobile automation task request.
+
+    Attributes:
+        goal: Natural language description of the goal to achieve
+        profile: Optional agent profile to use for executing the task
+        task_name: Optional name for the task
+        output_description: Optional natural language description of expected output format
+        output_format: Optional pydantic model for the output format of the task
+        max_steps: Maximum number of steps the agent can take (default: 20)
+        record_trace: Whether to record a trace (screenshots, actions) of the execution
+                      (default: False)
+        trace_path: Directory path to save trace data if recording is enabled
+        llm_output_path: Path to save LLM output data
+        thoughts_output_path: Path to save thoughts output data
+    """
+
+    goal: str
+    profile: str | None = None
+    task_name: str | None = None
+    output_description: str | None = None
+    output_format: type[TOutput] | None = None
+    enable_remote_tracing: bool = False
+
+
+class ManualTaskConfig(BaseModel):
+    """
+    Configuration for manually creating a task without fetching from the platform.
+
+    Attributes:
+        goal: Natural language description of the goal to achieve
+        output_description: Optional natural language description of expected output format
+        task_name: Optional name for the task
+    """
+
+    goal: str
+    output_description: str | None = None
+    task_name: str | None = None
+
+
+class PlatformTaskRequest[TOutput](TaskRequestBase):
+    """
+    Minitap-specific task request for SDK usage via the gateway platform.
+
+    Attributes:
+        task: Either a task name to fetch from the platform, or a
+              ManualTaskConfig to create manually
+        profile: Optional profile name specified by the user on the platform
+        execution_origin: Origin of the task execution (default: "sdk")
+        record_trace: Whether to record traces (default: True for platform tasks)
+        trace_path: Path to save traces (default: temp directory)
+    """
+
+    task: str | ManualTaskConfig
+    profile: str | None = None
+    execution_origin: str = "sdk"
+    record_trace: bool = True
+    trace_path: Path = Path(tempfile.gettempdir()) / "mobile-use-traces"
+
+
+class CloudDevicePlatformTaskRequest[TOutput](PlatformTaskRequest[TOutput]):
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+
+    task_run_id_available_event: Event = Event()
+    task_run_id: str | None = None
+    virtual_mobile_id: str | None = None
+
+
+class TaskResult(BaseModel):
+    """
+    Result of a mobile automation task.
+
+    Attributes:
+        content: Raw result content (could be text or structured data)
+        error: Error message if the task failed
+        execution_time_seconds: How long the task took to execute
+        steps_taken: Number of steps the agent took to complete the task
+    """
+
+    content: Any = None
+    error: str | None = None
+    execution_time_seconds: float
+    steps_taken: int
+
+    def get_as_model(self, model_class: type[T]) -> T:
+        """
+        Parse the content into a Pydantic model instance.
+
+        Args:
+            model_class: The Pydantic model class to parse the data into
+
+        Returns:
+            An instance of the specified model class
+
+        Raises:
+            ValueError: If content is None or not compatible with the model
+        """
+        if self.content is None:
+            raise ValueError("No content available to parse into a model")
+        if isinstance(self.content, model_class):
+            return self.content
+        return model_class.model_validate(self.content)
+
+
+class Task(BaseModel):
+    """
+    A mobile automation task to be executed.
+
+    Attributes:
+        id: Unique identifier for the task
+        device: Information about the target device
+        status: Current status of the task execution
+        request: User task request
+        created_at: ISO timestamp when the task was created
+        ended_at: ISO timestamp when the task ended
+    """
+
+    id: str
+    device: DeviceContext
+    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
+
+    async def finalize(
+        self,
+        content: Any | None = None,
+        state: dict | None = None,
+        error: str | None = None,
+        cancelled: bool = False,
+    ):
+        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
+        steps_taken = -1
+        if state is not None:
+            metadata = state.get("metadata", None)
+            if metadata:
+                steps_taken = metadata.get("step_count", -1)
+
+        self.result = TaskResult(
+            content=content,
+            error=error,
+            execution_time_seconds=duration.total_seconds(),
+            steps_taken=steps_taken,
+        )
+
+    def get_name(self) -> str:
+        if isinstance(self.request, PlatformTaskRequest):
+            if isinstance(self.request.task, str):
+                return self.request.task
+            else:
+                # ManualTaskConfig - use first 50 chars of goal
+                return f"Manual: {self.request.task.goal[:50]}"
+        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/sdk/utils.py

@@ -0,0 +1,29 @@
+import os
+from pathlib import Path
+
+from pydantic import ValidationError
+
+from minitap.mobile_use.config import LLMConfig, deep_merge_llm_config, get_default_llm_config
+from minitap.mobile_use.utils.file import load_jsonc
+from minitap.mobile_use.utils.logger import get_logger
+
+logger = get_logger(__name__)
+
+
+def load_llm_config_override(path: Path) -> LLMConfig:
+    default_config = get_default_llm_config()
+
+    override_config_dict = {}
+    if os.path.exists(path):
+        logger.info(f"Loading custom LLM config from {path.resolve()}...")
+        with open(path) as f:
+            override_config_dict = load_jsonc(f)
+    else:
+        logger.warning("Custom LLM config not found - using the default config")
+
+    try:
+        return deep_merge_llm_config(default_config, override_config_dict)
+    except ValidationError as e:
+        logger.error(f"Invalid LLM config: {e}")
+        logger.info("Falling back to default config")
+        return default_config