Metadata-Version: 2.4
Name: opdroid
Version: 0.1.1
Summary: LLM-controlled Android device automation via ADB
Project-URL: Homepage, https://github.com/shikhr/android-use
Project-URL: Repository, https://github.com/shikhr/android-use
Project-URL: Issues, https://github.com/shikhr/android-use/issues
Author: Shikhar Mishra
License-Expression: MIT
Keywords: adb,ai-agent,android,automation,llm,vision
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: System :: Hardware :: Hardware Drivers
Requires-Python: >=3.10
Requires-Dist: adbutils>=2.0.0
Requires-Dist: litellm>=1.0.0
Requires-Dist: pillow>=10.0.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rich>=13.0.0
Requires-Dist: typer[all]>=0.9.0
Description-Content-Type: text/markdown

# opdroid

LLM-controlled Android device automation via ADB. Give natural language commands and watch an AI agent operate your Android device.

## How It Works

1. Captures a screenshot from your Android device
2. Overlays a labeled grid (columns A-Z, rows 1-N) on the screenshot
3. Sends the gridded image to an LLM with your objective
4. LLM responds with grid-based actions like `tap(cell="E10")`
5. Actions are converted to device coordinates and executed via ADB
6. Repeat until task is complete

The grid system significantly improves accuracy compared to having the LLM guess raw pixel coordinates.

## Requirements

- Python 3.10+
- Android device with USB debugging enabled
- ADB installed and device connected
- API key for an LLM provider (OpenAI, Anthropic, Groq, Gemini, etc.)

## Installation

```bash
# Install from PyPI
pip install opdroid

# Or clone and install locally
git clone https://github.com/shikhr/opdroid.git
cd opdroid
uv sync
```

## Configuration

Copy the example environment file and add your API keys:

```bash
cp .env.example .env
```

Edit `.env` and set at least one API key:

```
OPENAI_API_KEY=sk-...
ANTHROPIC_API_KEY=sk-ant-...
GROQ_API_KEY=gsk_...
GEMINI_API_KEY=...
```

## Usage

```bash
# Basic usage
opdroid "Open Settings and turn on WiFi"

# Specify a different model
opdroid --model "groq/llama-3.3-70b-versatile" "Open Chrome"
opdroid --model "gemini/gemini-2.0-flash" "Open YouTube and search for cats"

# Using as a module
uv run python -m android_controller "Open Settings"
```

### Available Tools

The agent can use these actions:

| Tool | Description |
|------|-------------|
| `tap(cell)` | Tap on a grid cell (e.g., "E10") |
| `swipe(start_cell, end_cell)` | Swipe between cells for scrolling |
| `input_text(text)` | Type text into focused field |
| `press_home()` | Press the home button |
| `press_back()` | Press the back button |
| `press_enter()` | Press enter/submit |
| `launch_app(package)` | Launch app by package name |
| `wait(seconds)` | Wait for content to load |
| `task_complete(summary)` | Mark task as done |
| `task_impossible(reason)` | Mark task as impossible |

## Demo

Capture a screenshot with grid overlay to see what the LLM sees:

```bash
uv run tests/demo_screenshot.py
```

This saves `screenshot_gridded.png` showing the labeled grid overlay.

## Supported Models

Any model supported by [LiteLLM](https://docs.litellm.ai/docs/providers) that has:
- Vision capability (to understand screenshots)
- Function/tool calling (to execute actions)

Tested with:
- `gpt-4o` (OpenAI)
- `claude-sonnet-4-20250514` (Anthropic)
- `gemini/gemini-2.0-flash` (Google)
- `groq/llama-3.3-70b-versatile` (Groq)

## License

MIT
