adb-mlkit 0.1.0__tar.gz

adb_mlkit-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,49 @@
+# Contributing and publishing
+
+## Local checks
+
+```text
+python -m pip install -e ".[dev]"
+python -m unittest discover -s tests -v
+# After building Android:
+python scripts/prepare_package.py
+python -m build
+python scripts/smoke_install.py dist/adb_mlkit-0.1.0-py3-none-any.whl
+```
+
+Android checks (from `android/`; use `gradlew.bat` on Windows):
+
+```text
+./gradlew :app:testDebugUnitTest :app:lintDebug :app:assembleDebug
+```
+
+Use the toolchain in `android/README.md`. Do not commit `local.properties`, signing keys, APK binaries, `.venv`, caches, private images or result files. Keep Gradle wrapper files in source control, including `gradle-wrapper.jar`.
+
+## Device smoke test
+
+The unit suite and a successful APK build do not prove device behavior. Use an authorized test device and a **synthetic non-sensitive image** for integration checks:
+
+1. Build and package the helper. On an authorized test device without the helper, run `adb-mlkit recognize --file synthetic.png` and verify automatic installation followed by OCR. Repeat recognition and verify that it does not reinstall. Use `adb-mlkit install ...` when explicitly testing updates or a custom APK.
+2. Use `adb-mlkit info` to verify device/helper setup.
+3. Recognize the same synthetic image with `--file` and `--device-file` after manually copying it to a readable shared folder. Compare text, dimensions, ROI and rotated geometry.
+4. Use a screen containing synthetic text for `--screenshot`; use optional `[ui]` dependencies for XPath.
+5. Test each script with corresponding synthetic text. Record device model/API, source image resolution and first/warm/end-to-end timing separately.
+6. Include invalid-image, out-of-bounds ROI, permission-denied, disconnected-device and multiple-device tests. Verify error messages and request cleanup.
+
+Never use production bank/customer images in CI or public issues. Do not infer multilingual accuracy from a single Latin image.
+
+## API changes
+
+Update Python result models, Android serialization, protocol documentation and tests together. Incompatible wire-format changes require a new schema version. Do not change coordinate semantics silently. Preserve error codes and avoid fabricating confidence values.
+
+## Publishing this repository
+
+The project is prepared locally; nothing is automatically pushed or published. Review all files and the license before creating a remote. Replace example paths/serials only in your local commands, not with real private data in documentation.
+
+The configured repository is https://github.com/zidonghua-source/ADB-MLKit. Commit and push only after reviewing `git status` and `git diff --cached`. Forks should update the project URLs and Trusted Publisher configuration for their own repository.
+
+GitHub Actions run tests/builds and produce artifacts. A separate **manual-only** PyPI/TestPyPI workflow is documented in [PUBLISHING.md](docs/PUBLISHING.md); configure protected environments and Trusted Publishing before using it. Nothing publishes automatically on push. Review permissions and current third-party dependency terms before distributing an APK. Debug signing on CI is ephemeral, so a CI APK may not update a locally signed installation without a signature conflict; use one controlled signing key for stable releases and never commit it. Do not uninstall an existing helper blindly to resolve a conflict if it contains data you need.
+
+## Scope
+
+ADB-MLKit is an OCR SDK/CLI and helper, not a general phone automation framework. Additional features should preserve offline execution, explicit device selection and least privilege. HTTP services, persistent Android daemons and cross-process request queues require separate threat-model and protocol design.

adb_mlkit-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ADB-MLKit contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

adb_mlkit-0.1.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include README.md README.vi.md LICENSE THIRD_PARTY_NOTICES.md SECURITY.md CONTRIBUTING.md
+recursive-include docs *.md
+recursive-include examples *.py
+recursive-include tests *.py
+recursive-include scripts *.py
+recursive-include src/adb_mlkit/assets *.apk *.json

adb_mlkit-0.1.0/PKG-INFO

@@ -0,0 +1,161 @@
+Metadata-Version: 2.4
+Name: adb-mlkit
+Version: 0.1.0
+Summary: On-device multilingual ML Kit OCR from Python over ADB
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/zidonghua-source/ADB-MLKit
+Project-URL: Repository, https://github.com/zidonghua-source/ADB-MLKit
+Project-URL: Issues, https://github.com/zidonghua-source/ADB-MLKit/issues
+Project-URL: Documentation, https://github.com/zidonghua-source/ADB-MLKit/blob/main/README.md
+Keywords: adb,android,ocr,mlkit,vietnamese
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+License-File: THIRD_PARTY_NOTICES.md
+Provides-Extra: ui
+Requires-Dist: uiautomator2<4,>=3.0; extra == "ui"
+Requires-Dist: Pillow>=10; extra == "ui"
+Provides-Extra: dev
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: twine>=6; extra == "dev"
+Dynamic: license-file
+
+# ADB-MLKit
+
+**Read text on Android from Python, using Google's on-device ML Kit models over ADB.**
+
+ADB-MLKit consists of a Python SDK/CLI and a small, headless Android instrumentation helper. It is an independent community project, not an official Google product. No OCR cloud account or API key is required.
+
+[Tiếng Việt](README.vi.md) · [API reference](docs/API.md) · [Protocol](docs/PROTOCOL.md) · [Security](SECURITY.md)
+
+## Features
+
+- Read a local image, encoded image bytes, an image already on Android, or a screenshot.
+- Optional XPath-to-region lookup with uiautomator2; recognized text always comes from OCR.
+- Five bundled script models: **Latin (including Vietnamese), Chinese, Japanese, Korean and Devanagari**.
+- Crop ROI, clockwise rotation, block/line/element text and geometry, engine-provided confidence where available.
+- Multiple devices via explicit serial selection; sequential batch images.
+- Cold/first invocation and repeated-same-image OCR timings, plus host transfer/startup/cleanup timings.
+- Request-isolated temporary storage and best-effort cleanup; Base64-safe ADB input transport.
+- Structured JSON output, typed Python results, unit tests and GitHub Actions build configuration.
+
+## Requirements
+
+- Python 3.10+, Android platform-tools (`adb`) on PATH, and an authorized USB/TCP device.
+- Android 6.0 / API 23 or newer.
+- A distribution wheel includes the version-matched Android helper APK. End users do not need Java/Gradle/Android Studio.
+- ADB/platform-tools remains a separate prerequisite; pip never installs an APK on your phone automatically.
+- Optional XPath support: install the `[ui]` extra.
+
+This does **not** bypass Android screen-capture restrictions or private-storage permissions. Avoid enabling ADB on untrusted networks.
+
+## Quick start
+
+Install the built wheel (available locally in `dist/`; publication is a separate maintainer step):
+
+```powershell
+python -m pip install ./dist/adb_mlkit-0.1.0-py3-none-any.whl
+adb-mlkit devices
+```
+
+After the maintainer publishes this project to PyPI, installation by name becomes:
+
+```text
+python -m pip install adb-mlkit
+python -m pip install "adb-mlkit[ui]"
+```
+
+These package-index commands require an actual release; preparing this repository does not publish one. See [PyPI publishing](docs/PUBLISHING.md).
+
+Run OCR directly. Recognition commands and Python recognition methods automatically install the bundled, checksum-verified helper on the selected phone if it is missing:
+
+```powershell
+adb-mlkit recognize --screenshot --language vi --runs 3 --json
+adb-mlkit info
+```
+
+An existing helper is not automatically reinstalled or updated. Use `adb-mlkit install` to install/update it manually, or `adb-mlkit install path/to/custom.apk` for a custom APK. Installation errors stop recognition; the SDK never uninstalls an existing package to resolve a conflict.
+
+The new helper package is **`io.github.adbmlkit.helper`**, separate from the earlier `com.example.mlkitocrtest` prototype. The prototype APK cannot serve this protocol.
+
+### Images on Android
+
+```powershell
+adb-mlkit recognize --device-file "/sdcard/Download/example.png" --language vi --json
+```
+
+The Android shell must already be allowed to read the path. The host reads the encoded bytes over ADB and stages them in helper-private storage; this is not zero-copy device-only ingestion and does not require broad storage permissions.
+
+### Local images, crop and other scripts
+
+```powershell
+adb-mlkit recognize --file image.png --language vi --roi 60 100 1000 700 --runs 5
+adb-mlkit recognize --file japanese.png --script japanese --json
+adb-mlkit recognize --file rotated.jpg --rotation 90 --json --output result.json
+adb-mlkit batch first.png second.png --language vi --json --output batch.json
+adb-mlkit --serial DEVICE_SERIAL recognize --screenshot --script latin
+```
+
+Existing output files are protected unless `--overwrite` is given. Global options (`--serial`, `--adb-path`, `--timeout`) go **before** the subcommand. `python -m adb_mlkit` is equivalent to `adb-mlkit`.
+
+### Python API
+
+```python
+from adb_mlkit import ADBMLKit
+
+ocr = ADBMLKit(serial="DEVICE_SERIAL")
+result = ocr.recognize_device_file("/sdcard/Download/example.png", language="vi", runs=3)
+print(result.text)
+print(result.timing)       # Android decode/init/recognition durations
+print(result.host_timing)  # Host load/setup/transfer/instrumentation/result/cleanup/total
+
+for block in result.blocks:
+    for line in block.lines:
+        print(line.text, line.bounds, line.confidence)
+```
+
+See [API reference](docs/API.md) and [examples](examples/) for all entry points.
+
+## Languages versus scripts
+
+`--language vi` selects the **Latin model**, not a Vietnamese-only model. It does not translate, force output into Vietnamese, or provide a recognition hint. The SDK maps a documented set of aliases to the five supported scripts; `adb-mlkit languages` lists them. The alias list is not Google's exhaustive language list. Unsupported scripts (for example Arabic or Thai) are not automatically recognized by this integration.
+
+ML Kit may recognize mixed-script text supported by a selected model, but this project does not run all five recognizers automatically or promise arbitrary multilingual detection. For mixed documents, select and benchmark an appropriate model or process the image separately with multiple models.
+
+## Coordinate and timing semantics
+
+ROI is `[left, top, right, bottom]` in the original unrotated source image, with exclusive right/bottom edges. Crop precedes rotation. Output geometry uses the cropped, rotated image coordinate system, **not necessarily screen coordinates**. Explicit rotation is used; normalize EXIF orientation yourself when needed.
+
+`runs=N` recognizes **one image N times** using one recognizer in one invocation. The first run can include lazy model initialization; later values measure warm recognition. Each API call starts instrumentation again. Warm OCR time is not end-to-end latency. The host total includes image loading/capture, helper setup, transfers and cleanup. `host_timing.setup_ms` measures the package check and any automatic APK installation; the first call on a device without the helper therefore takes longer. No fixed speed or accuracy guarantee is made.
+
+## Development and verification
+
+```powershell
+python -m pip install -e ".[dev]"
+python -m unittest discover -s tests -v
+# Build Android first: see android/README.md
+python scripts/prepare_package.py
+python -m build
+python scripts/verify_wheel.py dist/adb_mlkit-0.1.0-py3-none-any.whl
+```
+
+Python unit tests mock ADB; they do not establish on-device accuracy. Build the Android helper separately. See [CONTRIBUTING.md](CONTRIBUTING.md) for synthetic-image device tests and publication notes. No device credentials or private images are included.
+
+## Limitations
+
+- One instrumentation invocation at a time per device. Use one client per device; separate processes must coordinate themselves.
+- No always-running HTTP daemon, streaming camera service, translation API or cloud fallback.
+- Image input limit: 32 MiB; decoded dimensions: at most 32 million pixels. Large input can still be memory-intensive.
+- Same-device screenshot and XPath lookup are sequential, not an atomic UI snapshot. Changing UI may move the target.
+- Debug APK is a developer tool, not a hardened Play Store app. Model libraries make the all-script APK substantially larger than a Latin-only helper.
+- ML Kit models/libraries have their own terms. This repository provides integration source, not source code for Google's recognition models.
+
+## License and upstream
+
+Project code: [MIT](LICENSE). See [third-party notices](THIRD_PARTY_NOTICES.md).
+
+- [Google ML Kit Android setup](https://developers.google.com/ml-kit/vision/text-recognition/v2/android)
+- [Supported languages](https://developers.google.com/ml-kit/vision/text-recognition/v2/languages)
+- [Official sample source](https://github.com/googlesamples/mlkit)

adb_mlkit-0.1.0/README.md

@@ -0,0 +1,137 @@
+# ADB-MLKit
+
+**Read text on Android from Python, using Google's on-device ML Kit models over ADB.**
+
+ADB-MLKit consists of a Python SDK/CLI and a small, headless Android instrumentation helper. It is an independent community project, not an official Google product. No OCR cloud account or API key is required.
+
+[Tiếng Việt](README.vi.md) · [API reference](docs/API.md) · [Protocol](docs/PROTOCOL.md) · [Security](SECURITY.md)
+
+## Features
+
+- Read a local image, encoded image bytes, an image already on Android, or a screenshot.
+- Optional XPath-to-region lookup with uiautomator2; recognized text always comes from OCR.
+- Five bundled script models: **Latin (including Vietnamese), Chinese, Japanese, Korean and Devanagari**.
+- Crop ROI, clockwise rotation, block/line/element text and geometry, engine-provided confidence where available.
+- Multiple devices via explicit serial selection; sequential batch images.
+- Cold/first invocation and repeated-same-image OCR timings, plus host transfer/startup/cleanup timings.
+- Request-isolated temporary storage and best-effort cleanup; Base64-safe ADB input transport.
+- Structured JSON output, typed Python results, unit tests and GitHub Actions build configuration.
+
+## Requirements
+
+- Python 3.10+, Android platform-tools (`adb`) on PATH, and an authorized USB/TCP device.
+- Android 6.0 / API 23 or newer.
+- A distribution wheel includes the version-matched Android helper APK. End users do not need Java/Gradle/Android Studio.
+- ADB/platform-tools remains a separate prerequisite; pip never installs an APK on your phone automatically.
+- Optional XPath support: install the `[ui]` extra.
+
+This does **not** bypass Android screen-capture restrictions or private-storage permissions. Avoid enabling ADB on untrusted networks.
+
+## Quick start
+
+Install the built wheel (available locally in `dist/`; publication is a separate maintainer step):
+
+```powershell
+python -m pip install ./dist/adb_mlkit-0.1.0-py3-none-any.whl
+adb-mlkit devices
+```
+
+After the maintainer publishes this project to PyPI, installation by name becomes:
+
+```text
+python -m pip install adb-mlkit
+python -m pip install "adb-mlkit[ui]"
+```
+
+These package-index commands require an actual release; preparing this repository does not publish one. See [PyPI publishing](docs/PUBLISHING.md).
+
+Run OCR directly. Recognition commands and Python recognition methods automatically install the bundled, checksum-verified helper on the selected phone if it is missing:
+
+```powershell
+adb-mlkit recognize --screenshot --language vi --runs 3 --json
+adb-mlkit info
+```
+
+An existing helper is not automatically reinstalled or updated. Use `adb-mlkit install` to install/update it manually, or `adb-mlkit install path/to/custom.apk` for a custom APK. Installation errors stop recognition; the SDK never uninstalls an existing package to resolve a conflict.
+
+The new helper package is **`io.github.adbmlkit.helper`**, separate from the earlier `com.example.mlkitocrtest` prototype. The prototype APK cannot serve this protocol.
+
+### Images on Android
+
+```powershell
+adb-mlkit recognize --device-file "/sdcard/Download/example.png" --language vi --json
+```
+
+The Android shell must already be allowed to read the path. The host reads the encoded bytes over ADB and stages them in helper-private storage; this is not zero-copy device-only ingestion and does not require broad storage permissions.
+
+### Local images, crop and other scripts
+
+```powershell
+adb-mlkit recognize --file image.png --language vi --roi 60 100 1000 700 --runs 5
+adb-mlkit recognize --file japanese.png --script japanese --json
+adb-mlkit recognize --file rotated.jpg --rotation 90 --json --output result.json
+adb-mlkit batch first.png second.png --language vi --json --output batch.json
+adb-mlkit --serial DEVICE_SERIAL recognize --screenshot --script latin
+```
+
+Existing output files are protected unless `--overwrite` is given. Global options (`--serial`, `--adb-path`, `--timeout`) go **before** the subcommand. `python -m adb_mlkit` is equivalent to `adb-mlkit`.
+
+### Python API
+
+```python
+from adb_mlkit import ADBMLKit
+
+ocr = ADBMLKit(serial="DEVICE_SERIAL")
+result = ocr.recognize_device_file("/sdcard/Download/example.png", language="vi", runs=3)
+print(result.text)
+print(result.timing)       # Android decode/init/recognition durations
+print(result.host_timing)  # Host load/setup/transfer/instrumentation/result/cleanup/total
+
+for block in result.blocks:
+    for line in block.lines:
+        print(line.text, line.bounds, line.confidence)
+```
+
+See [API reference](docs/API.md) and [examples](examples/) for all entry points.
+
+## Languages versus scripts
+
+`--language vi` selects the **Latin model**, not a Vietnamese-only model. It does not translate, force output into Vietnamese, or provide a recognition hint. The SDK maps a documented set of aliases to the five supported scripts; `adb-mlkit languages` lists them. The alias list is not Google's exhaustive language list. Unsupported scripts (for example Arabic or Thai) are not automatically recognized by this integration.
+
+ML Kit may recognize mixed-script text supported by a selected model, but this project does not run all five recognizers automatically or promise arbitrary multilingual detection. For mixed documents, select and benchmark an appropriate model or process the image separately with multiple models.
+
+## Coordinate and timing semantics
+
+ROI is `[left, top, right, bottom]` in the original unrotated source image, with exclusive right/bottom edges. Crop precedes rotation. Output geometry uses the cropped, rotated image coordinate system, **not necessarily screen coordinates**. Explicit rotation is used; normalize EXIF orientation yourself when needed.
+
+`runs=N` recognizes **one image N times** using one recognizer in one invocation. The first run can include lazy model initialization; later values measure warm recognition. Each API call starts instrumentation again. Warm OCR time is not end-to-end latency. The host total includes image loading/capture, helper setup, transfers and cleanup. `host_timing.setup_ms` measures the package check and any automatic APK installation; the first call on a device without the helper therefore takes longer. No fixed speed or accuracy guarantee is made.
+
+## Development and verification
+
+```powershell
+python -m pip install -e ".[dev]"
+python -m unittest discover -s tests -v
+# Build Android first: see android/README.md
+python scripts/prepare_package.py
+python -m build
+python scripts/verify_wheel.py dist/adb_mlkit-0.1.0-py3-none-any.whl
+```
+
+Python unit tests mock ADB; they do not establish on-device accuracy. Build the Android helper separately. See [CONTRIBUTING.md](CONTRIBUTING.md) for synthetic-image device tests and publication notes. No device credentials or private images are included.
+
+## Limitations
+
+- One instrumentation invocation at a time per device. Use one client per device; separate processes must coordinate themselves.
+- No always-running HTTP daemon, streaming camera service, translation API or cloud fallback.
+- Image input limit: 32 MiB; decoded dimensions: at most 32 million pixels. Large input can still be memory-intensive.
+- Same-device screenshot and XPath lookup are sequential, not an atomic UI snapshot. Changing UI may move the target.
+- Debug APK is a developer tool, not a hardened Play Store app. Model libraries make the all-script APK substantially larger than a Latin-only helper.
+- ML Kit models/libraries have their own terms. This repository provides integration source, not source code for Google's recognition models.
+
+## License and upstream
+
+Project code: [MIT](LICENSE). See [third-party notices](THIRD_PARTY_NOTICES.md).
+
+- [Google ML Kit Android setup](https://developers.google.com/ml-kit/vision/text-recognition/v2/android)
+- [Supported languages](https://developers.google.com/ml-kit/vision/text-recognition/v2/languages)
+- [Official sample source](https://github.com/googlesamples/mlkit)

adb_mlkit-0.1.0/README.vi.md

@@ -0,0 +1,98 @@
+# ADB-MLKit — OCR trên Android từ Python
+
+Project độc lập gồm **SDK/CLI Python** và **APK Android không có giao diện**, dùng Google ML Kit Text Recognition v2. Đây không phải sản phẩm chính thức của Google.
+
+## Có gì?
+
+- Đọc ảnh trên máy tính, bytes ảnh, ảnh có sẵn trong điện thoại và ảnh chụp màn hình.
+- Lấy vùng bằng XPath tùy chọn; XPath chỉ lấy tọa độ, không lấy text từ UI.
+- Năm bộ chữ: Latin (có tiếng Việt), Trung, Nhật, Hàn, Devanagari.
+- Cắt vùng, xoay ảnh, text theo block/dòng/từ, tọa độ và confidence khi engine cung cấp.
+- Đo riêng thời gian OCR và tổng thời gian xử lý; xuất JSON, đọc nhiều ảnh tuần tự.
+- Không gửi ảnh lên cloud; không cần API key hay root.
+
+## Chạy nhanh trên Windows
+
+```powershell
+cd D:\Github\ADB-MLKit
+python -m venv .venv
+.venv\Scripts\Activate.ps1
+python -m pip install .\dist\adb_mlkit-0.1.0-py3-none-any.whl
+```
+
+Wheel đã chứa APK và cả 5 model, không cần tự build Android. ADB/platform-tools vẫn phải cài riêng. Lệnh pip không tự cài app lên điện thoại; khi chạy lệnh đọc văn bản, SDK sẽ tự kiểm tra và cài APK đi kèm đã được xác minh checksum nếu thiết bị chưa có:
+
+```powershell
+adb-mlkit devices
+adb-mlkit recognize --screenshot --language vi --runs 3 --json
+```
+
+Không cần chạy `adb-mlkit install` trước. Cơ chế này áp dụng cho `recognize`, `batch` và các hàm đọc văn bản trong API Python. Nếu APK đã có thì không tự cài lại hay cập nhật. Vẫn có thể dùng `adb-mlkit install` để cài/cập nhật thủ công, hoặc `adb-mlkit install path/to/custom.apk` để chọn APK khác. Nếu cài thất bại, OCR dừng và báo lỗi; SDK không tự gỡ APK hiện có để xử lý xung đột.
+
+Sau khi chủ repo phát hành lên PyPI, người dùng sẽ cài bằng `pip install adb-mlkit` hoặc `pip install "adb-mlkit[ui]"`. Hiện việc chuẩn bị source/wheel chưa đồng nghĩa đã đăng lên PyPI. Xem [hướng dẫn phát hành](docs/PUBLISHING.md).
+
+Package mới là `io.github.adbmlkit.helper`, không dùng chung APK prototype `com.example.mlkitocrtest`.
+
+**Đọc ảnh nằm trong điện thoại:**
+
+```powershell
+adb-mlkit recognize --device-file "/sdcard/Download/anh.png" --language vi --json
+```
+
+ADB phải có quyền đọc đường dẫn đó. Ảnh được đọc về host rồi chuyển vào vùng lưu trữ riêng của APK, không phải xử lý trực tiếp không qua truyền ảnh. Không đọc được thư mục riêng của app khác nếu Android không cho phép.
+
+**Đọc ảnh máy tính, Nhật/Hàn/Trung:**
+
+```powershell
+adb-mlkit recognize --file anh.png --language vi
+adb-mlkit recognize --file japanese.png --script japanese --json
+adb-mlkit recognize --file korean.png --script korean --json
+adb-mlkit recognize --file chinese.png --script chinese --json
+```
+
+**Đọc bằng XPath:**
+
+```powershell
+python -m pip install -e ".[ui]"
+adb-mlkit recognize --xpath '//*[@resource-id="com.example:id/dialog"]/..' --language vi --runs 3
+```
+
+Thay XPath bằng phần tử trên app của bạn. Màn hình thay đổi giữa lúc lấy XPath và chụp ảnh có thể làm vùng không còn khớp.
+
+## API Python
+
+```python
+from adb_mlkit import ADBMLKit
+
+ocr = ADBMLKit()  # Chỉ tự chọn khi có đúng một thiết bị đã được cấp quyền ADB
+result = ocr.recognize_device_file("/sdcard/Download/anh.png", language="vi")
+print(result.text)
+print(result.to_json())
+
+result = ocr.recognize_screenshot(roi=(60, 100, 1000, 700), runs=5)
+print(result.timing)
+print(result.host_timing)
+```
+
+Chọn thiết bị cụ thể: `ADBMLKit(serial="SERIAL")` hoặc `adb-mlkit --serial SERIAL recognize ...`.
+
+## Lưu ý quan trọng
+
+- `language="vi"` chọn model Latin, không dịch hoặc ép đầu ra thành tiếng Việt. Không hỗ trợ mọi bộ chữ trên thế giới.
+- `runs=5` đọc **cùng một ảnh** 5 lần. Các lần sau đo model đã nạp; tổng thời gian thật còn có chụp ảnh, truyền ADB và khởi chạy APK. `host_timing.setup_ms` đo kiểm tra/cài APK; `total_ms` bao gồm cả bước này nên lần đầu có thể lâu hơn.
+- ROI là tọa độ ảnh gốc trước xoay; kết quả là tọa độ sau cắt và xoay, không mặc định là tọa độ màn hình.
+- Giới hạn ảnh 32 MiB/32 triệu pixel. Chất lượng phụ thuộc ảnh, bộ chữ và thiết bị.
+- Một phiên nhận dạng tại một thời điểm cho mỗi điện thoại. Các process riêng phải tự điều phối.
+- APK debug không xin quyền mạng, không bỏ qua `FLAG_SECURE` hay cơ chế bảo vệ của Android.
+- Dữ liệu tạm được cố gắng xóa sau mỗi request; mất kết nối hoặc dừng process đột ngột có thể để lại file.
+
+## Tài liệu
+
+- [Hướng dẫn đầy đủ](README.md)
+- [API và CLI](docs/API.md)
+- [Giao thức Python–Android](docs/PROTOCOL.md)
+- [Build APK](android/README.md)
+- [Bảo mật](SECURITY.md)
+- [Đóng góp và đưa lên GitHub](CONTRIBUTING.md)
+
+Mã project dùng MIT. Thư viện/model Google giữ điều khoản riêng. Không cam kết độ chính xác hay thời gian cố định khi chưa benchmark trên ảnh thực tế.

adb_mlkit-0.1.0/SECURITY.md

@@ -0,0 +1,23 @@
+# Security and privacy
+
+Use ADB-MLKit only with devices and images you are authorized to access.
+
+## Trust boundaries
+
+- The Android helper is a **debuggable developer tool**, not a hardened consumer app. An authorized ADB connection can access its private files through `run-as`.
+- Protect USB debugging authorization, your workstation, and any ADB TCP connection. Do not expose ADB or wrap this SDK in an unauthenticated public HTTP service.
+- The helper uses bundled ML Kit models and does not request network permissions. Images are processed on the selected Android device, not submitted to an OCR cloud endpoint.
+- Build tooling downloads Gradle, Maven libraries, and SDK components. Offline OCR does not mean an initial build is offline.
+- Google ML Kit and other dependencies retain their respective licenses and terms; the repository's MIT license covers this project's code, not Google's models.
+
+## Image handling
+
+Each request uses a unique helper-private directory. The Python client attempts to remove that directory after success and failure. Cleanup is not secure erasure, and a disconnected device, killed process, or power failure can leave data behind. Results printed to a terminal or explicitly written to a file remain there.
+
+Images already on a device are read with the shell user's existing permissions. Access to another app's private directory is not granted by this tool. It does not root devices, defeat `FLAG_SECURE`, or bypass Android storage restrictions. Device image bytes travel to the host before being staged in helper-private storage.
+
+Do not commit personal screenshots, financial data, APK signing secrets, device identifiers, or output JSON to a public repository. The ignore rules are a convenience, not a data-loss prevention system.
+
+## Reporting issues
+
+Before publishing, the repository owner should enable GitHub private vulnerability reporting. Use that mechanism when available. Do not post secrets, private screenshots, or exploitable details in a public issue; provide a synthetic reproduction and affected versions instead.

adb_mlkit-0.1.0/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,11 @@
+# Third-party components
+
+ADB-MLKit's MIT license covers the integration source written for this repository. It does not relicense external software, pretrained models, platform tooling, or generated wrapper components.
+
+- **Google ML Kit Text Recognition v2**: bundled Latin, Chinese, Devanagari, Japanese and Korean Android libraries, currently pinned in `android/app/build.gradle`. Google's license notices and [ML Kit terms](https://developers.google.com/ml-kit/terms) apply. Model implementation/source is not part of this project.
+- **Android SDK / ADB / Android Gradle Plugin**: Google/Android tooling, distributed separately under their applicable terms. Android SDK license acceptance is the builder's responsibility.
+- **Gradle wrapper**: generated upstream Gradle wrapper scripts/JAR; Gradle is Apache License 2.0. The wrapper downloads its pinned distribution from the official Gradle service.
+- **uiautomator2 and Pillow**: optional Python dependencies for XPath-assisted screenshot capture. Consult their upstream distributions for license details.
+- **JUnit**: Android JVM test dependency; consult the dependency's upstream license.
+
+Dependency notices included in artifacts must be preserved. Review the resolved dependency tree and vendor terms before redistributing APKs, especially for commercial use. This file is an inventory, not a substitute for those licenses.

adb_mlkit-0.1.0/docs/API.md

@@ -0,0 +1,88 @@
+# Python API and CLI
+
+## Client
+
+```python
+from adb_mlkit import ADBMLKit
+client = ADBMLKit(serial=None, adb_path=None, timeout=30, script="latin")
+```
+
+Construction/import does not contact a device. Without `serial`, exactly one authorized device must be connected. ADB is resolved from the explicit argument, `ADB_PATH`, then PATH. The client remembers the selected serial. `timeout` applies to ordinary ADB operations; instrumentation allows at least `60 + 35 * runs` seconds.
+
+| Method | Input / output |
+|---|---|
+| `devices()` | All discovered `Device(serial, state, details)` records, including unauthorized devices |
+| `info()` | Selected device model/API, helper installed flag and supported script list |
+| `install(apk=None)` | Explicitly install/update the bundled checksum-verified APK, or a custom local APK; returns confirmation |
+| `recognize_bytes(data, **options)` | Encoded image bytes; returns `OCRResult` |
+| `recognize_file(path, **options)` | Local file; returns `OCRResult` |
+| `recognize_device_file(path, **options)` | Absolute Android path readable by shell; returns `OCRResult` |
+| `recognize_screenshot(**options)` | Capture current display using ADB screencap; returns `OCRResult` |
+| `recognize_xpath(xpath, xpath_timeout=10, **options)` | Optional uiautomator2 lookup supplies screenshot ROI; returns `OCRResult` |
+| `batch_files(paths, **options)` | Sequential list of local files; returns list of results, stops on first error |
+
+All recognition methods (including batch) check for the helper on the selected device before staging input. If missing, they install the bundled checksum-verified APK automatically. An existing helper is not reinstalled or upgraded; use `install()` explicitly for updates or a custom APK. Package-query and installation failures abort recognition without staging a request. Construction, `devices()` and `info()` never install an APK.
+
+Every successful recognition deletes its own temporary request directory on the device. Cleanup is also attempted after errors; failures generate a warning without replacing the original error. Process termination/disconnection may leave residual data.
+
+## Common recognition options
+
+- `script=None`: one of `latin`, `chinese`, `devanagari`, `japanese`, `korean`; defaults to client setting.
+- `language=None`: convenience alias such as `vi`, `en`, `zh`, `ja`, `ko`, `hi`. Cannot combine with `script`. Use `script_for_language()` or `LANGUAGES` to inspect aliases.
+- `roi=None`: four integer pixels `(left, top, right, bottom)` before rotation. Must fit inside the image. Cannot combine with XPath's derived ROI.
+- `rotation=0`: clockwise degrees, one of 0/90/180/270.
+- `runs=1`: 1–30 repeated recognitions on the same image. Final run supplies output text.
+
+These options do not request translation or linguistic correction. Model choice is script-based.
+
+## Result
+
+`OCRResult` provides:
+
+- `id`, `schema_version`, `ok`, `text`, `script`.
+- `image`: original width/height, output width/height, rotation and ROI metadata.
+- `timing`: Android `decode_ms`, `init_ms`, `runs_ms`.
+- `host_timing`: host `load_ms`, `setup_ms`, `transfer_ms`, `instrumentation_ms`, `result_ms`, `cleanup_ms`, `total_ms`. Setup measures the helper-presence check and any automatic installation; total includes setup, so the first call may take longer. Host instrumentation time includes all runs plus process and ADB overhead. Timers overlap conceptually: do not add Android OCR times to host total.
+- `blocks`: `TextBlock` objects with text, geometry, language and `lines`.
+- `lines`: `TextLine` objects with nullable confidence and `elements`.
+- `elements`: `TextElement` objects with text, geometry, recognized language and nullable confidence.
+- `to_dict()` and `to_json(indent=2)` for export.
+
+Geometry: `bounds` may be null; otherwise `[left, top, right, bottom]`. `corner_points` contains `[x, y]` pairs. Coordinates belong to the cropped, rotated output image. Confidence is not fabricated when unavailable. Recognized language may be empty/undetermined.
+
+## Errors
+
+`ADBMLKitError` covers missing ADB, authorization/selection errors, command timeouts, invalid helper responses and Android OCR failures. Invalid arguments raise `ValueError`; unreadable local files may raise `OSError`. The JSON error categories from Android are documented in [PROTOCOL.md](PROTOCOL.md).
+
+```python
+from adb_mlkit import ADBMLKit, ADBMLKitError
+try:
+    result = ADBMLKit().recognize_screenshot(language="vi")
+except (ADBMLKitError, ValueError, OSError) as error:
+    print(f"OCR failed: {error}")
+```
+
+## CLI
+
+```text
+adb-mlkit [--serial SERIAL] [--adb-path PATH] [--timeout SECONDS] COMMAND
+
+COMMAND:
+  devices
+  info
+  languages
+  install [APK]
+  recognize (--file PATH | --device-file PATH | --screenshot | --xpath XPATH)
+  batch FILE [FILE ...]
+
+Recognition options:
+  --script SCRIPT | --language ALIAS
+  --roi LEFT TOP RIGHT BOTTOM
+  --rotation 0|90|180|270
+  --runs N
+  --json
+  --output PATH
+  --overwrite
+```
+
+`--json` produces structured output only on stdout; normal text output puts timing diagnostics on stderr. `--output` saves the chosen representation to UTF-8 instead of stdout. Existing output files require explicit `--overwrite`. Batch JSON is an array in the input order. Ordinary operational errors return exit code 1; argparse usage errors return 2. `recognize` and `batch` automatically install the bundled helper if missing, without adding installation output to stdout. `install [APK]` remains available for explicit installation/updates.