minitap-mobile-use 0.0.1.dev0__py3-none-any.whl

minitap/mobile_use/sdk/examples/smart_notification_assistant.py

@@ -0,0 +1,177 @@
+"""
+Smart Notification Assistant - Intermediate SDK Usage Example
+
+This example demonstrates more advanced SDK features including:
+- TaskRequestBuilder pattern
+- Multiple agent profiles for different reasoning tasks
+- Tracing for debugging/visualization
+- Structured output with Pydantic
+- Exception handling
+
+It performs a practical automation task:
+1. Checks notification panel for unread notifications
+2. Categorizes them by priority/app
+3. Performs actions based on notification content
+
+Run:
+- python src/mobile_use/sdk/examples/smart_notification_assistant.py
+"""
+
+import asyncio
+from datetime import datetime
+from enum import Enum
+from typing import List
+
+from pydantic import BaseModel, Field
+from minitap.mobile_use.config import LLM, LLMConfig, LLMConfigUtils, LLMWithFallback
+from minitap.mobile_use.sdk import Agent
+from minitap.mobile_use.sdk.builders import Builders
+from minitap.mobile_use.sdk.types import AgentProfile
+from minitap.mobile_use.sdk.types.exceptions import AgentError
+
+
+class NotificationPriority(str, Enum):
+    HIGH = "high"
+    MEDIUM = "medium"
+    LOW = "low"
+
+
+class Notification(BaseModel):
+    """Individual notification details."""
+
+    app_name: str = Field(..., description="Name of the app that sent the notification")
+    title: str = Field(..., description="Title/header of the notification")
+    message: str = Field(..., description="Message content of the notification")
+    priority: NotificationPriority = Field(
+        default=NotificationPriority.MEDIUM, description="Priority level of notification"
+    )
+
+
+class NotificationSummary(BaseModel):
+    """Summary of all notifications."""
+
+    total_count: int = Field(..., description="Total number of notifications found")
+    high_priority_count: int = Field(0, description="Count of high priority notifications")
+    notifications: List[Notification] = Field(
+        default_factory=list, description="List of individual notifications"
+    )
+
+
+def get_agent() -> Agent:
+    # Create two specialized profiles:
+    # 1. An analyzer profile for detailed inspection tasks
+    analyzer_profile = AgentProfile(
+        name="analyzer",
+        llm_config=LLMConfig(
+            planner=LLM(provider="openrouter", model="meta-llama/llama-4-scout"),
+            orchestrator=LLM(provider="openrouter", model="meta-llama/llama-4-scout"),
+            cortex=LLMWithFallback(
+                provider="openai",
+                model="o4-mini",
+                fallback=LLM(provider="openai", model="gpt-5"),
+            ),
+            executor=LLM(provider="openai", model="gpt-5-nano"),
+            utils=LLMConfigUtils(
+                outputter=LLM(provider="openai", model="gpt-5-nano"),
+                hopper=LLM(provider="openai", model="gpt-4.1"),
+            ),
+        ),
+        # from_file="/tmp/analyzer.jsonc"  # can be loaded from file
+    )
+
+    # 2. An action profile for handling easy & fast actions based on notifications
+    action_profile = AgentProfile(
+        name="note_taker",
+        llm_config=LLMConfig(
+            planner=LLM(provider="openai", model="o3"),
+            orchestrator=LLM(provider="google", model="gemini-2.5-flash"),
+            cortex=LLMWithFallback(
+                provider="openai",
+                model="o4-mini",
+                fallback=LLM(provider="openai", model="gpt-5"),
+            ),
+            executor=LLM(provider="openai", model="gpt-4o-mini"),
+            utils=LLMConfigUtils(
+                outputter=LLM(provider="openai", model="gpt-5-nano"),
+                hopper=LLM(provider="openai", model="gpt-4.1"),
+            ),
+        ),
+    )
+
+    # Configure default task settings with tracing
+    task_defaults = Builders.TaskDefaults.with_max_steps(200).build()
+
+    # Configure the agent
+    config = (
+        Builders.AgentConfig.add_profiles(profiles=[analyzer_profile, action_profile])
+        .with_default_profile(profile=action_profile)
+        .with_default_task_config(config=task_defaults)
+        .build()
+    )
+    return Agent(config=config)
+
+
+async def main():
+    # Set up traces directory with timestamp for uniqueness
+    timestamp = datetime.now().strftime("%Y%m%d_%H%M")
+    traces_dir = f"/tmp/notification_traces/{timestamp}"
+    agent = get_agent()
+
+    try:
+        # Initialize agent (finds a device, starts required servers)
+        agent.init()
+
+        print("Checking for notifications...")
+
+        # Task 1: Get and analyze notifications with analyzer profile
+        notification_task = (
+            agent.new_task(
+                goal="Open the notification panel (swipe down from top). "
+                "Scroll through the first 3 unread notifications. "
+                "For each notification, identify the app name, title, and content. "
+                "Tag messages from messaging apps or email as high priority."
+            )
+            .with_output_format(NotificationSummary)
+            .using_profile("analyzer")
+            .with_name("notification_scan")
+            .with_max_steps(400)
+            .with_trace_recording(enabled=True, path=traces_dir)
+            .build()
+        )
+
+        # Execute the task with proper exception handling
+        try:
+            notifications = await agent.run_task(request=notification_task)
+
+            # Display the structured results
+            if notifications:
+                print("\n=== Notification Summary ===")
+                print(f"Total notifications: {notifications.total_count}")
+                print(f"High priority: {notifications.high_priority_count}")
+
+                # Task 2: Create a note to store the notification summary
+                response = await agent.run_task(
+                    goal="Open my Notes app and create a new note summarizing the following "
+                    f"information:\n{notifications}",
+                    name="email_action",
+                    profile="note_taker",
+                )
+                print(f"Action result: {response}")
+
+            else:
+                print("Failed to retrieve notifications")
+
+        except AgentError as e:
+            print(f"Agent error occurred: {e}")
+        except Exception as e:
+            print(f"Unexpected error: {type(e).__name__}: {e}")
+            raise
+
+    finally:
+        # Clean up
+        agent.clean()
+        print(f"\nTraces saved to: {traces_dir}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

minitap/mobile_use/sdk/types/__init__.py

@@ -0,0 +1,49 @@
+"""Type definitions for the mobile-use SDK."""
+
+from minitap.mobile_use.sdk.types.agent import (
+    ApiBaseUrl,
+    AgentConfig,
+    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,
+    DeviceError,
+    MobileUseError,
+    ServerError,
+)
+
+__all__ = [
+    "ApiBaseUrl",
+    "AgentConfig",
+    "DevicePlatform",
+    "AgentProfile",
+    "ServerConfig",
+    "TaskRequest",
+    "TaskStatus",
+    "TaskResult",
+    "TaskRequestCommon",
+    "Task",
+    "AgentProfileNotFoundError",
+    "AgentTaskRequestError",
+    "DeviceNotFoundError",
+    "ServerStartupError",
+    "AgentError",
+    "AgentNotInitializedError",
+    "DeviceError",
+    "MobileUseError",
+    "ServerError",
+]

minitap/mobile_use/sdk/types/agent.py

@@ -0,0 +1,73 @@
+from typing import Dict, Literal, Optional
+from urllib.parse import urlparse
+from pydantic import BaseModel
+
+from minitap.mobile_use.context import DevicePlatform
+from minitap.mobile_use.sdk.types.task import AgentProfile, TaskRequestCommon
+
+
+class ApiBaseUrl(BaseModel):
+    """
+    Defines an API base URL.
+    """
+
+    scheme: Literal["http", "https"]
+    host: str
+    port: Optional[int] = None
+
+    def __eq__(self, other):
+        if not isinstance(other, ApiBaseUrl):
+            return False
+        return self.to_url() == other.to_url()
+
+    def to_url(self):
+        return (
+            f"{self.scheme}://{self.host}:{self.port}"
+            if self.port is not None
+            else f"{self.scheme}://{self.host}"
+        )
+
+    @classmethod
+    def from_url(cls, url: str) -> "ApiBaseUrl":
+        parsed_url = urlparse(url)
+        if parsed_url.scheme not in ["http", "https"]:
+            raise ValueError(f"Invalid scheme: {parsed_url.scheme}")
+        if parsed_url.hostname is None:
+            raise ValueError("Invalid hostname")
+        return cls(
+            scheme=parsed_url.scheme,  # type: ignore
+            host=parsed_url.hostname,
+            port=parsed_url.port,
+        )
+
+
+class ServerConfig(BaseModel):
+    """
+    Configuration for the required servers.
+    """
+
+    hw_bridge_base_url: ApiBaseUrl
+    screen_api_base_url: ApiBaseUrl
+    adb_host: str
+    adb_port: int
+
+
+class AgentConfig(BaseModel):
+    """
+    Mobile-use agent configuration.
+
+    Attributes:
+        agent_profiles: Map an agent profile name to its configuration.
+        task_config_defaults: Default task request configuration.
+        default_profile: default profile to use for tasks
+        device_id: Specific device to target (if None, first available is used).
+        device_platform: Platform of the device to target.
+        servers: Custom server configurations.
+    """
+
+    agent_profiles: Dict[str, AgentProfile]
+    task_request_defaults: TaskRequestCommon
+    default_profile: AgentProfile
+    device_id: Optional[str] = None
+    device_platform: Optional[DevicePlatform] = None
+    servers: ServerConfig

minitap/mobile_use/sdk/types/exceptions.py

@@ -0,0 +1,74 @@
+"""
+Exceptions for the Mobile-use SDK.
+
+This module defines the exception hierarchy used throughout the Mobile-use SDK.
+"""
+
+
+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")

minitap/mobile_use/sdk/types/task.py

@@ -0,0 +1,191 @@
+"""
+Task-related type definitions for the Mobile-use SDK.
+"""
+
+from datetime import datetime
+from enum import Enum
+from pathlib import Path
+from typing import Any, Generic, Optional, Type, TypeVar, overload
+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.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: Optional[LLMConfig] = None,
+        from_file: Optional[str] = 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}"
+
+
+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=Optional[BaseModel])
+
+
+class TaskRequestCommon(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: Optional[Path] = None
+    thoughts_output_path: Optional[Path] = None
+
+
+class TaskRequest(TaskRequestCommon, Generic[TOutput]):
+    """
+    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: Optional[str] = None
+    task_name: Optional[str] = None
+    output_description: Optional[str] = None
+    output_format: Optional[type[TOutput]] = 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: Optional[str] = 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: TaskStatus
+    request: TaskRequest
+    created_at: datetime
+    ended_at: Optional[datetime] = None
+    result: Optional[TaskResult] = None
+
+    def finalize(
+        self,
+        content: Optional[Any] = None,
+        state: Optional[dict] = None,
+        error: Optional[str] = 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
+        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:
+        return self.request.task_name or self.id

minitap/mobile_use/sdk/utils.py

@@ -0,0 +1,28 @@
+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, "r") 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}. Falling back to default config")
+        return default_config

minitap/mobile_use/servers/config.py

@@ -0,0 +1,19 @@
+from typing import Optional
+from dotenv import load_dotenv
+from minitap.mobile_use.servers.device_hardware_bridge import DEVICE_HARDWARE_BRIDGE_PORT
+from minitap.mobile_use.utils.logger import get_logger
+from pydantic_settings import BaseSettings
+
+load_dotenv(verbose=True)
+logger = get_logger(__name__)
+
+
+class ServerSettings(BaseSettings):
+    DEVICE_HARDWARE_BRIDGE_BASE_URL: str = f"http://localhost:{DEVICE_HARDWARE_BRIDGE_PORT}"
+    DEVICE_SCREEN_API_PORT: int = 9998
+    ADB_HOST: Optional[str] = None
+
+    model_config = {"env_file": ".env", "extra": "ignore"}
+
+
+server_settings = ServerSettings()