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

minitap/mobile_use/sdk/examples/app_lock_messaging.py

@@ -0,0 +1,54 @@
+import asyncio
+
+from pydantic import BaseModel, Field
+
+from minitap.mobile_use.sdk import Agent
+
+
+class MessageResult(BaseModel):
+    """Structured result from messaging task."""
+
+    messages_sent: int = Field(..., description="Number of messages successfully sent")
+    contacts: list[str] = Field(..., description="List of contacts messaged")
+    success: bool = Field(..., description="Whether all messages were sent successfully")
+
+
+async def main() -> None:
+    # Create agent with default configuration
+    agent = Agent()
+
+    try:
+        await agent.init()
+
+        # Use app lock to keep execution in WhatsApp
+        # This ensures the agent stays in the app and relaunches if needed
+        task = (
+            agent.new_task("Send 'Happy New Year!' message to Alice, Bob, and Charlie on WhatsApp")
+            .with_name("send_new_year_messages")
+            .with_locked_app_package("com.whatsapp")  # Lock to WhatsApp
+            .with_output_format(MessageResult)
+            .with_max_steps(600)  # Messaging tasks may need more steps
+            .build()
+        )
+
+        print("Sending messages with app lock enabled...")
+        print("The agent will stay in WhatsApp and relaunch if needed.\n")
+
+        result = await agent.run_task(request=task)
+
+        if result:
+            print("\n=== Messaging Complete ===")
+            print(f"Messages sent: {result.messages_sent}")
+            print(f"Contacts: {', '.join(result.contacts)}")
+            print(f"Success: {result.success}")
+        else:
+            print("Failed to send messages")
+
+    except Exception as e:
+        print(f"Error: {e}")
+    finally:
+        await agent.clean()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

minitap/mobile_use/sdk/examples/platform_manual_task_example.py

@@ -0,0 +1,67 @@
+"""
+Platform Usage - Manual Task Creation Example
+
+This example demonstrates how to use the mobile-use SDK with manual task creation:
+- Agent with minitap_api_key
+- PlatformTaskRequest with ManualTaskConfig instead of task_id
+- Task configuration provided directly in code (goal, output_description)
+- No need to pre-create task in platform UI
+
+Platform Model:
+- API key provides authentication and agent configuration
+- ManualTaskConfig creates task on-the-fly with:
+  - max_steps: 400 (fixed)
+  - enable_remote_tracing: True (fixed)
+  - profile: "default" (fixed)
+  - goal: provided by you
+  - output_description: provided by you (optional)
+
+Run:
+- python src/mobile_use/sdk/examples/platform_manual_task_example.py
+"""
+
+import asyncio
+
+from minitap.mobile_use.sdk import Agent
+from minitap.mobile_use.sdk.types import ManualTaskConfig, PlatformTaskRequest
+
+
+async def main() -> None:
+    """
+    Main execution function demonstrating manual task creation pattern.
+
+    Visit https://platform.minitap.ai to get your API key.
+    Set MINITAP_API_KEY and MINITAP_BASE_URL environment variables.
+    """
+    agent = Agent()
+    await agent.init()
+
+    # Example 1: Simple manual task
+    result = await agent.run_task(
+        request=PlatformTaskRequest(
+            task=ManualTaskConfig(
+                goal="Open the settings app and tell me the battery level",
+            ),
+            profile="default",  # Optional, defaults to "default"
+        )
+    )
+    print("Result 1:", result)
+
+    # Example 2: Manual task with output description
+    result = await agent.run_task(
+        request=PlatformTaskRequest(
+            task=ManualTaskConfig(
+                goal="Find the first 3 unread emails in Gmail",
+                output_description="A JSON array with sender and subject for each email",
+            ),
+        ),
+        # Lock gmail to ensure it is automatically started and locked during task execution
+        locked_app_package="com.google.android.gm",
+    )
+    print("Result 2:", result)
+
+    await agent.clean()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

minitap/mobile_use/sdk/examples/platform_minimal_example.py

@@ -0,0 +1,48 @@
+"""
+Platform Usage - Minitap SDK with API Key Example
+
+This example demonstrates how to use the mobile-use SDK via the Minitap platform:
+- Agent with minitap_api_key
+- PlatformTaskRequest with platform-provided task_id
+- All task configuration (goal, output format, etc.) managed by platform UI
+
+Platform Model:
+- API key provides authentication and agent configuration
+- task_id references pre-configured task from platform UI
+- No goal, output_format, profile selection needed in code
+- Everything bound to task_id + api_key combination
+
+Run:
+- python src/mobile_use/sdk/examples/platform_minimal_example.py
+"""
+
+import asyncio
+
+from minitap.mobile_use.sdk import Agent
+from minitap.mobile_use.sdk.types import PlatformTaskRequest
+
+
+async def main() -> None:
+    """
+    Main execution function demonstrating minitap platform usage pattern.
+
+    Visit https://platform.minitap.ai to create a task, customize your profiles,
+    and get your API key.
+    Pass the api_key parameter to the agent.init() method
+    ...or set MINITAP_API_KEY environment variable.
+    """
+    agent = Agent()
+    await agent.init(api_key="<your-minitap-api-key>")  # or set MINITAP_API_KEY env variable
+    result = await agent.run_task(
+        request=PlatformTaskRequest(
+            task="<your-task-name>",
+            profile="<your-profile-name>",
+        ),
+        locked_app_package="<locked-app-package>",  # optional
+    )
+    print(result)
+    await agent.clean()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

minitap/mobile_use/sdk/examples/simple_photo_organizer.py

@@ -0,0 +1,76 @@
+"""
+Simple Photo Organizer - Basic SDK Usage Example
+
+This example demonstrates a straightforward way to use the mobile-use SDK
+without builders or advanced configuration. It performs a real-world automation task:
+1. Opens the photo gallery
+2. Finds photos from a specific date
+3. Creates an album and moves those photos into it
+
+Run:
+- python src/mobile_use/sdk/examples/simple_photo_organizer.py
+"""
+
+import asyncio
+from datetime import date, timedelta
+from pydantic import BaseModel, Field
+from minitap.mobile_use.sdk import Agent
+
+
+class PhotosResult(BaseModel):
+    """Structured result from photo search."""
+
+    found_photos: int = Field(..., description="Number of photos found")
+    date_range: str = Field(..., description="Date range of photos found")
+    album_created: bool = Field(..., description="Whether an album was created")
+    album_name: str = Field(..., description="Name of the created album")
+    photos_moved: int = Field(0, description="Number of photos moved to the album")
+
+
+async def main() -> None:
+    # Create a simple agent with default configuration
+    agent = Agent()
+
+    try:
+        # Initialize agent (finds a device, starts required servers)
+        await agent.init()
+
+        # Calculate yesterday's date for the example
+        yesterday = date.today() - timedelta(days=1)
+        formatted_date = yesterday.strftime("%B %d")  # e.g. "August 22"
+
+        print(f"Looking for photos from {formatted_date}...")
+
+        # First task: search for photos and organize them, with typed output
+        result = await agent.run_task(
+            goal=(
+                f"Open the Photos/Gallery app. Find photos taken on {formatted_date}. "
+                f"Create a new album named '{formatted_date} Memories' and "
+                f"move those photos into it. Count how many photos were moved."
+            ),
+            output=PhotosResult,
+            name="organize_photos",
+        )
+
+        # Handle and display the result
+        if result:
+            print("\n=== Photo Organization Complete ===")
+            print(f"Found: {result.found_photos} photos from {result.date_range}")
+
+            if result.album_created:
+                print(f"Created album: '{result.album_name}'")
+                print(f"Moved {result.photos_moved} photos to the album")
+            else:
+                print("No album was created")
+        else:
+            print("Failed to organize photos")
+
+    except Exception as e:
+        print(f"Error: {e}")
+    finally:
+        # Always clean up resources
+        await agent.clean()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

minitap/mobile_use/sdk/examples/smart_notification_assistant.py

@@ -0,0 +1,225 @@
+"""
+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 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=LLMWithFallback(
+                provider="openrouter",
+                model="meta-llama/llama-4-scout",
+                fallback=LLM(provider="openrouter", model="meta-llama/llama-4-maverick"),
+            ),
+            orchestrator=LLMWithFallback(
+                provider="openrouter",
+                model="meta-llama/llama-4-scout",
+                fallback=LLM(provider="openrouter", model="meta-llama/llama-4-maverick"),
+            ),
+            contextor=LLMWithFallback(
+                provider="openrouter",
+                model="meta-llama/llama-4-scout",
+                fallback=LLM(provider="openrouter", model="meta-llama/llama-4-maverick"),
+            ),
+            cortex=LLMWithFallback(
+                provider="openai",
+                model="o4-mini",
+                fallback=LLM(provider="openai", model="gpt-5"),
+            ),
+            executor=LLMWithFallback(
+                provider="openai",
+                model="gpt-5-nano",
+                fallback=LLM(provider="openai", model="gpt-5-mini"),
+            ),
+            utils=LLMConfigUtils(
+                outputter=LLMWithFallback(
+                    provider="openai",
+                    model="gpt-5-nano",
+                    fallback=LLM(provider="openai", model="gpt-5-mini"),
+                ),
+                hopper=LLMWithFallback(
+                    provider="openai",
+                    model="gpt-5-nano",
+                    fallback=LLM(provider="openai", model="gpt-5-mini"),
+                ),
+            ),
+        ),
+        # 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=LLMWithFallback(
+                provider="openai", model="o3", fallback=LLM(provider="openai", model="gpt-5")
+            ),
+            orchestrator=LLMWithFallback(
+                provider="google",
+                model="gemini-2.5-flash",
+                fallback=LLM(provider="openai", model="gpt-5"),
+            ),
+            contextor=LLMWithFallback(
+                provider="openai",
+                model="gpt-5-nano",
+                fallback=LLM(provider="openai", model="gpt-5-mini"),
+            ),
+            cortex=LLMWithFallback(
+                provider="openai",
+                model="o4-mini",
+                fallback=LLM(provider="openai", model="gpt-5"),
+            ),
+            executor=LLMWithFallback(
+                provider="openai",
+                model="gpt-4o-mini",
+                fallback=LLM(provider="openai", model="gpt-5-nano"),
+            ),
+            utils=LLMConfigUtils(
+                outputter=LLMWithFallback(
+                    provider="openai",
+                    model="gpt-5-nano",
+                    fallback=LLM(provider="openai", model="gpt-5-mini"),
+                ),
+                hopper=LLMWithFallback(
+                    provider="openai",
+                    model="gpt-5-nano",
+                    fallback=LLM(provider="openai", model="gpt-5-mini"),
+                ),
+            ),
+        ),
+    )
+
+    # 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)
+        await 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
+        await agent.clean()
+        print(f"\nTraces saved to: {traces_dir}")
+
+
+if __name__ == "__main__":
+    asyncio.run(main())

minitap/mobile_use/sdk/examples/video_transcription_example.py

@@ -0,0 +1,117 @@
+"""
+Video Transcription Example
+
+This example demonstrates how to use the video recording tools to capture
+and analyze video content from a mobile device screen.
+
+The agent can:
+1. Start a screen recording
+2. Perform actions while recording
+3. Stop the recording and analyze its content using Gemini models
+
+Use case: Recording a video playing on the screen and transcribing its content.
+"""
+
+import asyncio
+
+from minitap.mobile_use.config import LLM, LLMConfig, LLMConfigUtils, LLMWithFallback
+from minitap.mobile_use.sdk.agent import Agent
+from minitap.mobile_use.sdk.builders.agent_config_builder import AgentConfigBuilder
+from minitap.mobile_use.sdk.types.agent import AgentConfig
+from minitap.mobile_use.sdk.types.task import AgentProfile, TaskRequest
+
+
+def get_video_capable_llm_config() -> LLMConfig:
+    """
+    Returns an LLM config with video_analyzer configured.
+
+    The video_analyzer must use a video-capable Gemini model:
+    - gemini-3-flash-preview (recommended - fast and capable)
+    - gemini-3-pro-preview
+    - gemini-2.5-flash
+    - gemini-2.5-pro
+    - gemini-2.0-flash
+    """
+    return LLMConfig(
+        planner=LLMWithFallback(
+            provider="openai",
+            model="gpt-5-nano",
+            fallback=LLM(provider="openai", model="gpt-5-mini"),
+        ),
+        orchestrator=LLMWithFallback(
+            provider="openai",
+            model="gpt-5-nano",
+            fallback=LLM(provider="openai", model="gpt-5-mini"),
+        ),
+        contextor=LLMWithFallback(
+            provider="openai",
+            model="gpt-5-nano",
+            fallback=LLM(provider="openai", model="gpt-5-mini"),
+        ),
+        cortex=LLMWithFallback(
+            provider="openai",
+            model="gpt-5",
+            fallback=LLM(provider="openai", model="o4-mini"),
+        ),
+        executor=LLMWithFallback(
+            provider="openai",
+            model="gpt-5-nano",
+            fallback=LLM(provider="openai", model="gpt-5-mini"),
+        ),
+        utils=LLMConfigUtils(
+            outputter=LLMWithFallback(
+                provider="openai",
+                model="gpt-5-nano",
+                fallback=LLM(provider="openai", model="gpt-5-mini"),
+            ),
+            hopper=LLMWithFallback(
+                provider="openai",
+                model="gpt-5-nano",
+                fallback=LLM(provider="openai", model="gpt-5-mini"),
+            ),
+            video_analyzer=LLMWithFallback(
+                provider="google",
+                model="gemini-3-flash-preview",
+                fallback=LLM(provider="google", model="gemini-2.5-flash"),
+            ),
+        ),
+    )
+
+
+async def main():
+    config: AgentConfig = (
+        AgentConfigBuilder()
+        .add_profile(
+            AgentProfile(
+                name="VideoCapable",
+                llm_config=get_video_capable_llm_config(),
+            )
+        )
+        .with_video_recording_tools()
+        .build()
+    )
+
+    agent = Agent(config=config)
+    try:
+        await agent.init()
+
+        result = await agent.run_task(
+            request=TaskRequest(
+                goal="""
+                1. Open YouTube app
+                2. Search for "Python tutorial"
+                3. Start recording the screen
+                4. Play the first video
+                5. Wait for the first 30 seconds of the video to play
+                6. Stop recording and tell me what was said in the video
+                """,
+                profile="VideoCapable",
+            )
+        )
+        print(f"Task result: {result}")
+    finally:
+        await agent.clean()
+
+
+if __name__ == "__main__":
+    asyncio.run(main())