{"data":{"kind":"file","path":"README.md","version_id":"l87qe0e1blz8bc9etzbadwcb","entry":{"name":"README.md","path":"README.md","is_directory":false,"size":13129,"modified_at":"2026-09-19T19:11:14.251000","content_hash":"812864db9416deba7dbb46a5d435157c6e7aa1942a178f78a45ba57111ee2abd"},"entries":[],"content":"# Prime Intellect Android ADK RL Environment\n\nThis repository is a real mobile Android RL and evaluation environment built around the demo APK `com.primeintellect.dummyrl`.\n\nIt now includes:\n\n- real ADB-backed execution\n- optional AndroidWorld-backed interaction\n- spec-driven `mobile-rl` eval and benchmark CLI\n- pool-aware rollout and benchmark orchestration\n- snapshot-aware reset management\n- strict `pass@k` and reward-reporting helpers\n- structured rollout and benchmark artifacts\n- Prime / `verifiers` environment integration\n\n## Current Status\n\nThe codebase is implemented and test-covered, and the spec-driven CLI eval path was revalidated on a real emulator in this session.\n\nLive-validated on `2026-06-22`:\n\n- `mobile-rl health`: passed\n- `mobile-rl eval --task tasks/form_default.yaml --policy scripted`: passed\n- form task spec path: working on real emulator\n- benchmark math and reward calibration: unit-tested\n- ride specs: implemented, not revalidated live in this pass\n\nCurrent real-run results:\n\n- eval: structured JSON result with `harness_success=true` and `task_success=true`\n- OpenAI eval on `2026-06-23`: harness succeeded end to end, but the task did not reach success (`task_success=false`)\n\nThe runtime loop is:\n\n```text\nTask\n  -> Reset\n  -> Observation\n  -> Policy / model\n  -> Structured action\n  -> Device execution\n  -> Durable APK state read\n  -> Reward calculation\n  -> Artifact write\n```\n\n## Multi-App Environment Layout\n\nHosted V1 evaluation exposes only `peach_action_budget_v1`; legacy diagnostic rubrics are not selectable. Both Amazon tasks use `Android_Verifiers.core.registry` as the authoritative gesture-verification engine: task bindings select P01-P08 policies, and every bound action receives one evidenced baseline plus exactly five optimization receipts. The single publishable Prime package is `android_envs`; its `task_verification` package adapts task outcomes and evidence to the reusable `Android_Verifiers` policies. Application sources live under `Apps`, generated contracts and bindings under `Verifier_support`, lightweight discovery manifests under `tasks`, and hosted provisioning under `updated-prime-Infra/hosted`.\n\n```mermaid\nflowchart LR\n    T[Task manifest under tasks] --> S[Verifier_support contract and binding]\n    S --> R[android_envs Prime V1 environment]\n    R --> M[Policy or model]\n    M --> A[Strict action parser]\n    A --> D[ADB or AndroidWorld backend]\n    D --> U[Apps application]\n    U --> V[Shared Android verifiers]\n    V --> R[Reward and artifacts]\n```\n\nThe hosted launch workflow keeps typed task selection, machine provisioning, app execution, and gesture verification as separate boundaries:\n\n```mermaid\nsequenceDiagram\n    participant User\n    participant Task as tasks task contract\n    participant Runtime as android_envs Prime V1\n    participant Infra as updated-prime-Infra\n    participant App as Apps\n    participant Verify as Android verifiers\n    User->>Task: Select task\n    Task->>Runtime: Load typed task and verifier binding\n    Runtime->>Infra: Start hosted Android runtime\n    Infra->>App: Build, install, and reset APK\n    Runtime->>App: Execute structured actions\n    App-->>Runtime: UI and durable state evidence\n    Runtime->>Verify: Evaluate bound action policies\n    Verify-->>User: Reward, receipts, and artifacts\n```\n\n## Repo Structure\n\n```text\nandroid_adk_rl_env/\n  adb_device.py              Real device control and runtime hardening\n  apk_env.py                 Step-based APK RL environment\n  android_world_bridge.py    AndroidWorld-backed environment bridge\n  third_party/android_world/  Vendored AndroidWorld source tree\n  rollout_runner.py          Multi-task rollout and artifact generation\n  proof_benchmark.py         Repeatability / pass@k benchmark runner\n  cli.py                     Unified mobile-rl CLI\n  eval_runner.py             Shared spec-driven execution\n  benchmarking/              pass@k and reward-reporting helpers\n  device_pool.py             Pool-aware serial allocation\n  reset_manager.py           Snapshot/full reset orchestration\n  core/                      Actions, observations, reward, artifacts, safety, metrics\n  policies/                  Scripted, OpenAI, random, local RL policy code\n  tasks/                     Runnable task classes and registered checks\n\nApps/                              Android application sources\n  amazon_improved_001/              Nine-product catalog and exact-cart Java/SQLite implementation\n  amazon_improved_002/              Favorites, comparison, offer and demo-card implementation\n  shared_amazon/                    Shared XML resources and deterministic APK builder\nAndroid_Verifiers/                  Reusable Android action policies, core and schemas\nVerifier_support/                   Task contracts, generators and policy bindings\n  amazon_improved_001/\n    common/\n    instances.py                  Deterministic train/eval instance generator\n    verifier_binding/\n    tools/\n  amazon_improved_002/\n    common/\n    verifier_binding/\n    tools/\nandroid_envs/                       Publishable Prime runtime, harness and verification code\neval/                               Canonical three-rollout report and evidence ZIPs\n  evidence/<evaluation-id>/\nupdated-prime-Infra/hosted/         Hosted Android provisioning only\ntasks/                              Lightweight task discovery manifests\n  Amazon_Improved_clone/\n  Amazon_Improved_002/\nenvironments/mobile_android_rl/     Generic mobile environment package\nprime_android_adk_rl_env/           Prime/verifiers compatibility environment\nscripts/                            Build, install, run, AndroidWorld, Prime and Docker helpers\ndocs/                               Guides and implementation notes\ntests/                              Unit, integration, AndroidWorld and Prime tests\nartifacts/                          Ignored local run outputs\n```\n\n## Prime Hosted Task Selection\n\nThe public Prime environment is [devjangid-wootzapp/android-envs](https://app.primeintellect.ai/dashboard/environments/devjangid-wootzapp/android-envs). Version `1.1.27` is the cleaned native Verifiers V1 package: `android_envs` exports exactly one typed `AndroidTaskset`, `AndroidHarness`, and `AndroidEnv`. Its published source and wheel contain only the two Amazon tasks, their two APK sources, shared Amazon resources, reusable Android verifiers, task contracts, and hosted provisioning. Legacy generic mobile, Uber, ride-booking, form, and V0 compatibility packages are excluded from the release payload.\n\nTask bundles are discovered package-safely from `Verifier_support/<task-id>/common/task.json`; aliases remain explicit, but adding a canonical task no longer requires editing a Python registry. One-task evaluations must name `task_id`. `task_id=all` is the only multi-task mode and orders discovered tasks alphabetically. `amazon_improved_task_001` routes a deterministic seeded 2-4 item cart contract, generated action binding, APK, prompt, and cart verifier; `amazon_improved_task_002` routes the favorites/comparison bundle. A dry run validates configuration without creating an emulator, sandbox, tunnel, or model request:\n\n```bash\nuv run eval android-envs \\\n  --dry-run \\\n  --env.taskset.task-id amazon_improved_task_001 \\\n  --env.taskset.observation-mode a11y \\\n  --env.taskset.allow-eval false\n```\n\nA real V1 evaluation must opt into the billed Android VM explicitly, select one task, and remain sequential:\n\n```bash\nuv run eval android-envs \\\n  --model minimax/minimax-m3 \\\n  --num-tasks 1 \\\n  --num-rollouts 3 \\\n  --max-concurrent 1 \\\n  --sampling.temperature 0.5 \\\n  --sampling.max-tokens 4096 \\\n  --env.taskset.task-id amazon_improved_task_001 \\\n  --env.taskset.observation-mode both \\\n  --env.taskset.allow-eval true\n```\n\nTask 001 exposes disjoint deterministic train and eval seeds and defaults to 20 generated rows per split; every receipt records the seed, full generated contract, and contract hash. Task 002 remains one canonical row until its own generator exists. Observation mode is validated as `a11y`, `screenshot`, or `both` and controls both episode implementations. The environment measures observed outcomes; it never changes verifier results to force a target pass count. Use `amazon_improved_task_002` as the task ID for the second task. Local V1 runs configure `--env.taskset.*` directly; Prime hosted runs currently transport the same typed settings through `--env-args`, which `AndroidEnvConfig` validates and routes into the taskset.\n\n```mermaid\nflowchart TD\n    C[Verifiers V1 eval config] --> T[AndroidTaskset]\n    T --> S{validated discovered task_id}\n    S -->|amazon_improved_task_001| A1[Build and install Apps/amazon_improved_001]\n    S -->|amazon_improved_task_002| A2[Build and install Apps/amazon_improved_002]\n    A1 --> R[One framework-owned Prime VM per rollout]\n    A2 --> R\n    R --> H[Android worker and AndroidHarness share the VM]\n    H --> V1[Cart evidence and action-budget verifier]\n    H --> V2[Favorites, comparison, offer, card verifier]\n    V1 --> E[Signed verdict, V1 reward, metrics and evidence archive]\n    V2 --> E\n```\n\n## Fast Start\n\nUse the CLI as the main entrypoint:\n\n```bash\npython3 -m android_adk_rl_env.cli --help\n```\n\nRecommended environment:\n\n```bash\nexport ANDROID_SDK_ROOT=/data/Balram/android-sdk\nexport ANDROID_HOME=$ANDROID_SDK_ROOT\nexport ANDROID_AVD_HOME=/data/Balram/prime-intellect-android-adk-rl-environments/.deps/android_avd\nexport PATH=\"$ANDROID_SDK_ROOT/platform-tools:$PATH\"\nexport ADB_SERIAL=127.0.0.1:15555\nexport RESET_MODE=full\nexport ADB_CMD_TIMEOUT_S=60\n```\n\nPreflight:\n\n```bash\nPOOL_SIZE=1 MOBILE_REQUIRE_KVM=0 ./scripts/mobile_preflight.sh\n```\n\nHealth check:\n\n```bash\npython3 -m android_adk_rl_env.cli health\n```\n\nSpec-driven real eval:\n\n```bash\npython3 -m android_adk_rl_env.cli eval --task tasks/form_default.yaml --policy scripted\n```\n\nSpec-driven benchmark:\n\n```bash\npython3 -m android_adk_rl_env.cli benchmark --tasks-dir tasks --samples-per-task 10 --pass-k 1 2 3 5 10\n```\n\nUber clone AndroidWorld benchmark:\n\n```bash\ndocker exec \\\n  -e ADB_SERIAL=emulator-5554 \\\n  -e ADB_CMD_TIMEOUT_S=60 \\\n  -e ANDROID_WORLD_GRPC_PORT=8554 \\\n  -e ANDROID_WORLD_WAIT_TO_STABILIZE=0 \\\n  -e ANDROID_WORLD_RESOURCE_EXECUTOR=adb \\\n  -e ANDROID_WORLD_SKIP_UI_STATE=1 \\\n  -e RESET_MODE=full \\\n  -e POOL_SIZE=1 \\\n  androidworld-pipeline \\\n  bash -lc 'cd /workspace && PYTHONPATH=/workspace python3 -B -m android_adk_rl_env.proof_benchmark \\\n    --backend android_world \\\n    --policy scripted \\\n    --tasks-dir tasks/uber_clone \\\n    --attempts-per-instance 10 \\\n    --pass-k 1 2 3 5 10 \\\n    --max-steps 12 \\\n    --pool-size 1 \\\n    --output artifacts/benchmarks/uber30_androidworld'\n```\n\nPrime eval:\n\n```bash\n./scripts/mobile_rl.sh prime-eval --backend android_world --max-turns 15\n```\n\n## Generated Benchmark\n\nLive AndroidWorld Uber clone benchmark generated on `2026-06-24`:\n\n- artifact directory: `artifacts/benchmarks/uber30_androidworld/20260624_122413`\n- benchmark family: `tasks/uber_clone`\n- backend: `android_world`\n- policy: `scripted`\n- task count: `30`\n- samples per task: `10`\n- total attempts: `300`\n- exact successes: `300`\n- exact success rate: `1.0`\n- average reward: `1.0`\n- average steps: `7`\n- `pass@1 = 1.0`\n- `pass@2 = 1.0`\n- `pass@3 = 1.0`\n- `pass@5 = 1.0`\n- `pass@10 = 1.0`\n\nGenerated runtime artifacts are intentionally ignored by git. The benchmark summary is available locally at:\n\n```text\nartifacts/benchmarks/uber30_androidworld/20260624_122413/summary.json\n```\n\n## What Is Working\n\n- Unit and integration tests\n- AndroidWorld and Prime smoke tests in the repo test suite\n- Real demo-APK form spec execution on emulator through `mobile-rl eval`\n- Uber clone 30-task AndroidWorld benchmark with pass@1/2/3/5/10\n- Strict `pass@k` and reward-calibration test coverage\n- Spec-driven benchmark artifacts through the new CLI path\n- pool-aware execution logic\n- reset-mode switching with full-reset fallback\n\n## Known Gap\n\nThe scripted Uber clone ride-booking benchmark is live validated on AndroidWorld. Model-backed ride quality still depends on the configured provider/model and should be measured separately from the scripted benchmark.\n\n## Main Docs\n\n- [System Overview and Operations Guide](/data/Balram/prime-intellect-android-adk-rl-environments/docs/SYSTEM_OVERVIEW_AND_OPERATIONS.md)\n\n- [Docker Guide](/data/Balram/prime-intellect-android-adk-rl-environments/docs/DOCKER_GUIDE.md)\n- [Improvement Plan](/data/Balram/prime-intellect-android-adk-rl-environments/docs/MOBILE_RL_IMPROVEMENT_PLAN.md)\n- [Implementation Report](/data/Balram/prime-intellect-android-adk-rl-environments/docs/MOBILE_RL_IMPLEMENTATION_REPORT.md)\n- [CLI / Benchmark / Reward Upgrade](/data/Balram/prime-intellect-android-adk-rl-environments/docs/CLI_BENCHMARK_REWARD_UPGRADE.md)\n- [Reward Semantics](/data/Balram/prime-intellect-android-adk-rl-environments/docs/REWARDS.md)\n- [Observation / Action Schema](/data/Balram/prime-intellect-android-adk-rl-environments/docs/OBSERVATION_ACTION_SCHEMA.md)\n- [Complete Guide](/data/Balram/prime-intellect-android-adk-rl-environments/docs/MOBILE_RL_COMPLETE_GUIDE.md)\n","encoding":"utf-8","truncated":false,"total_bytes":13129},"status":null}