minitap-mobile-use 2.3.0__py3-none-any.whl → 2.5.0__py3-none-any.whl

minitap/mobile_use/sdk/services/platform.py

@@ -0,0 +1,307 @@
+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,
+    ManualTaskConfig,
+    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:
+            # Check if task is a string (fetch from platform) or ManualTaskConfig (create manually)
+            if isinstance(request.task, str):
+                # Fetch task from platform
+                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)
+            else:
+                # Create task manually from ManualTaskConfig
+                logger.info(f"Creating manual task with goal: {request.task.goal}")
+
+                profile, agent_profile = await self._get_profile(
+                    profile_name=request.profile or DEFAULT_PROFILE,
+                )
+
+                task_request = TaskRequest(
+                    # Manual configuration
+                    max_steps=400,
+                    goal=request.task.goal,
+                    output_description=request.task.output_description,
+                    enable_remote_tracing=True,
+                    profile=DEFAULT_PROFILE,
+                    # 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_manual_task_run(
+                    manual_config=request.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 _create_manual_task_run(
+        self,
+        manual_config: ManualTaskConfig,
+        profile: LLMProfileResponse,
+    ) -> TaskRunResponse:
+        """
+        Create an orphan task run from a manual task configuration.
+        This creates a task run without a pre-existing task using the /orphan endpoint.
+        """
+        try:
+            logger.info(f"Creating orphan task run with goal: {manual_config.goal}")
+
+            # Create an orphan task run directly
+            orphan_payload = {
+                "inputPrompt": manual_config.goal,
+                "outputDescription": manual_config.output_description,
+                "llmProfileId": profile.id,
+            }
+
+            response = await self._client.post(url="v1/task-runs/orphan", json=orphan_payload)
+            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 orphan 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,30 @@
 """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,
+    ManualTaskConfig,
+    PlatformTaskRequest,
+    Task,
+    TaskRequest,
+    TaskRequestCommon,
+    TaskResult,
 )
 
 __all__ = [
@@ -33,7 +34,8 @@ __all__ = [
     "AgentProfile",
     "ServerConfig",
     "TaskRequest",
-    "TaskStatus",
+    "ManualTaskConfig",
+    "PlatformTaskRequest",
     "TaskResult",
     "TaskRequestCommon",
     "Task",

minitap/mobile_use/sdk/types/exceptions.py

@@ -102,3 +102,30 @@ class ExecutableNotFoundError(MobileUseError):
             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,127 @@
+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")
+    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 | 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")
+
+
+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,37 @@ 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 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
+    """
+
+    goal: str
+    output_description: 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
+        api_key: Optional API key to authenticate with the platform
+                 (overrides MINITAP_API_KEY env variable)
+    """
+
+    task: str | ManualTaskConfig
+    profile: str | None = None
+    api_key: str | None = None
 
 
 class TaskResult(BaseModel):
@@ -156,22 +186,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 +227,27 @@ class Task(BaseModel):
         )
 
     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/servers/device_hardware_bridge.py

@@ -38,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]