adb-mlkit 0.1.0__py3-none-any.whl

adb_mlkit/__init__.py

@@ -0,0 +1,8 @@
+"""On-device multilingual OCR over ADB."""
+from .client import ADBMLKit
+from .models import ADBMLKitError, Device, OCRResult, TextBlock, TextLine, TextElement
+from .models import LANGUAGES, SCRIPTS, script_for_language
+
+__version__ = "0.1.0"
+__all__ = ["ADBMLKit", "ADBMLKitError", "Device", "OCRResult", "TextBlock", "TextLine",
+           "TextElement", "LANGUAGES", "SCRIPTS", "script_for_language"]

adb_mlkit/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())

adb_mlkit/assets/helper.json

@@ -0,0 +1,5 @@
+{
+  "package": "io.github.adbmlkit.helper",
+  "version": "0.1.0",
+  "sha256": "515118b49037a73b22245f309dd508cc3b19b2458e489f0c02375258a85fa904"
+}

adb_mlkit/cli.py

@@ -0,0 +1,96 @@
+"""Command-line interface; JSON goes to stdout, diagnostics to stderr."""
+import argparse
+from dataclasses import asdict
+import json
+from pathlib import Path
+import sys
+
+from .client import ADBMLKit
+from .models import ADBMLKitError, LANGUAGES, SCRIPTS
+
+
+def parser():
+    root = argparse.ArgumentParser(prog="adb-mlkit", description="Offline Android OCR over ADB")
+    root.add_argument("--serial", help="Device serial; required if multiple devices are authorized")
+    root.add_argument("--adb-path", help="ADB executable (otherwise ADB_PATH or PATH)")
+    root.add_argument("--timeout", type=float, default=30)
+    commands = root.add_subparsers(dest="command", required=True)
+    commands.add_parser("devices", help="List attached devices and authorization states")
+    commands.add_parser("info", help="Inspect selected device and helper installation")
+    commands.add_parser("languages", help="List scripts and convenience language aliases")
+    install = commands.add_parser("install", help="Explicitly install bundled helper or a custom APK")
+    install.add_argument("apk", type=Path, nargs="?", help="Optional custom APK; default is the bundled helper")
+    for name in ("recognize", "batch"):
+        command = commands.add_parser(name, description="Read text; automatically install the bundled helper if missing")
+        if name == "recognize":
+            source = command.add_mutually_exclusive_group(required=True)
+            source.add_argument("--file", type=Path)
+            source.add_argument("--device-file", help="Absolute path readable by Android shell")
+            source.add_argument("--screenshot", action="store_true")
+            source.add_argument("--xpath", help="Optional uiautomator2 lookup; OCR reads the text")
+        else:
+            command.add_argument("files", type=Path, nargs="+")
+        selection = command.add_mutually_exclusive_group()
+        selection.add_argument("--script", choices=SCRIPTS)
+        selection.add_argument("--language", choices=sorted(LANGUAGES))
+        command.add_argument("--roi", nargs=4, type=int, metavar=("LEFT", "TOP", "RIGHT", "BOTTOM"))
+        command.add_argument("--rotation", type=int, choices=(0, 90, 180, 270), default=0)
+        command.add_argument("--runs", type=int, choices=range(1, 31), default=1, metavar="1..30")
+        command.add_argument("--json", action="store_true", help="Structured result; human timing stays off stdout")
+        command.add_argument("--output", type=Path, help="Save result locally instead of stdout")
+        command.add_argument("--overwrite", action="store_true", help="Allow replacing an existing output file")
+    return root
+
+
+def main(argv=None):
+    args = parser().parse_args(argv)
+    try:
+        if args.command == "languages":
+            print(json.dumps({"scripts": SCRIPTS, "language_aliases": LANGUAGES}, indent=2))
+            return 0
+        if getattr(args, "output", None) and args.output.exists() and not args.overwrite:
+            raise FileExistsError(f"Output exists: {args.output}; choose another path or --overwrite")
+        client = ADBMLKit(serial=args.serial, adb_path=args.adb_path, timeout=args.timeout)
+        if args.command == "devices":
+            print(json.dumps([asdict(d) for d in client.devices()], ensure_ascii=False, indent=2))
+            return 0
+        if args.command == "info":
+            print(json.dumps(client.info(), ensure_ascii=False, indent=2))
+            return 0
+        if args.command == "install":
+            print(client.install(args.apk))
+            return 0
+        options = dict(script=args.script, language=args.language, roi=args.roi,
+                       rotation=args.rotation, runs=args.runs)
+        if args.command == "batch":
+            results = client.batch_files(args.files, **options)
+        elif args.file:
+            results = [client.recognize_file(args.file, **options)]
+        elif args.device_file:
+            results = [client.recognize_device_file(args.device_file, **options)]
+        elif args.screenshot:
+            results = [client.recognize_screenshot(**options)]
+        else:
+            results = [client.recognize_xpath(args.xpath, **options)]
+        if args.json:
+            data = [r.to_dict() for r in results]
+            text = json.dumps(data if args.command == "batch" else data[0], ensure_ascii=False, indent=2)
+        else:
+            text = "\n\n".join(r.text for r in results)
+            for result in results:
+                print(json.dumps({"id": result.id, "android_timing": result.timing,
+                                  "host_timing": result.host_timing}), file=sys.stderr)
+        if args.output:
+            mode = "w" if args.overwrite else "x"
+            with args.output.open(mode, encoding="utf-8") as stream:
+                stream.write(text + "\n")
+        else:
+            print(text)
+        return 0
+    except (ADBMLKitError, ValueError, OSError) as exc:
+        print(f"ERROR: {exc}", file=sys.stderr)
+        return 1
+
+
+if __name__ == "__main__":
+    sys.exit(main())

adb_mlkit/client.py

@@ -0,0 +1,244 @@
+"""ADB transport and synchronous OCR API. No device access at import time."""
+import base64
+from contextlib import contextmanager
+from io import BytesIO
+import json
+import os
+from pathlib import Path
+import shlex
+import shutil
+import subprocess
+import threading
+from time import perf_counter
+import uuid
+import warnings
+
+from .models import ADBMLKitError, Device, OCRResult, SCRIPTS, script_for_language
+
+PACKAGE = "io.github.adbmlkit.helper"
+RUNNER = f"{PACKAGE}/.OcrInstrumentation"
+MAX_INPUT_BYTES = 32 * 1024 * 1024
+
+
+class ADBMLKit:
+    """One client serializes its requests; use one client per device.
+
+    timeout controls ordinary ADB calls. Recognition allows at least
+    60 + runs * 35 seconds for Android process startup and engine timeouts.
+    Independent clients/processes must not invoke instrumentation concurrently
+    on the same device.
+    """
+    def __init__(self, serial=None, adb_path=None, timeout=30, script="latin"):
+        if timeout <= 0:
+            raise ValueError("timeout must be positive")
+        if script not in SCRIPTS:
+            raise ValueError(f"script must be one of {SCRIPTS}")
+        self.serial = serial
+        self.adb_path = str(adb_path or os.environ.get("ADB_PATH") or shutil.which("adb") or "adb")
+        self.timeout = timeout
+        self.script = script
+        self._lock = threading.RLock()
+
+    def _adb(self, args, payload=None, timeout=None, selected=True):
+        command = [self.adb_path]
+        if selected:
+            if not self.serial:
+                self._select_device()
+            command += ["-s", self.serial]
+        try:
+            result = subprocess.run(command + list(args), input=payload, stdout=subprocess.PIPE,
+                                    stderr=subprocess.PIPE, timeout=timeout or self.timeout, check=False)
+        except FileNotFoundError as exc:
+            raise ADBMLKitError("ADB not found. Install Android platform-tools or set ADB_PATH.") from exc
+        except subprocess.TimeoutExpired as exc:
+            raise ADBMLKitError(f"ADB timed out after {exc.timeout}s") from exc
+        if result.returncode:
+            message = (result.stderr + result.stdout).decode("utf-8", errors="replace").strip()
+            raise ADBMLKitError(f"ADB exit {result.returncode}: {message}")
+        return result.stdout
+
+    def _shell(self, *args, payload=None, timeout=None):
+        return self._adb(["shell", " ".join(shlex.quote(str(arg)) for arg in args)], payload, timeout)
+
+    def _exec(self, *args):
+        return self._adb(["exec-out", " ".join(shlex.quote(str(arg)) for arg in args)])
+
+    def devices(self):
+        output = self._adb(["devices", "-l"], selected=False).decode("utf-8", errors="replace")
+        result = []
+        for line in output.splitlines():
+            if not line.strip() or line.startswith(("List of devices", "*")):
+                continue
+            parts = line.split(maxsplit=2)
+            if len(parts) >= 2:
+                result.append(Device(parts[0], parts[1], parts[2] if len(parts) > 2 else ""))
+        return result
+
+    def _select_device(self):
+        devices = self.devices()
+        available = [d.serial for d in devices if d.state == "device"]
+        if self.serial:
+            if self.serial not in available:
+                raise ADBMLKitError(f"Device {self.serial!r} is not connected/authorized")
+        elif len(available) == 1:
+            self.serial = available[0]
+        else:
+            raise ADBMLKitError(f"Expected one authorized device, found {available}; specify serial")
+        return self.serial
+
+    def _helper_installed(self):
+        packages = self._shell("pm", "list", "packages", PACKAGE).splitlines()
+        return f"package:{PACKAGE}".encode() in packages
+
+    def _ensure_helper(self):
+        if not self._helper_installed():
+            self.install()
+
+    def info(self):
+        with self._lock:
+            self._select_device()
+            return {"serial": self.serial,
+                    "android_api": self._shell("getprop", "ro.build.version.sdk").decode().strip(),
+                    "model": self._shell("getprop", "ro.product.model").decode().strip(),
+                    "helper_installed": self._helper_installed(),
+                    "package": PACKAGE, "scripts": list(SCRIPTS), "protocol_version": 1}
+
+    def install(self, apk=None):
+        """Explicitly install the bundled helper, or a caller-supplied APK."""
+        if apk is None:
+            from .helper import bundled_apk
+            with bundled_apk() as path:
+                return self.install(path)
+        path = Path(apk).resolve()
+        if not path.is_file():
+            raise FileNotFoundError(path)
+        with self._lock:
+            self._select_device()
+            output = self._adb(["install", "-r", str(path)], timeout=max(180, self.timeout)).decode(errors="replace")
+            if "Success" not in output:
+                raise ADBMLKitError(f"APK installation not confirmed: {output}")
+            return output.strip()
+
+    @staticmethod
+    def _options(script, language, default_script, roi, rotation, runs):
+        if script is not None and language is not None:
+            raise ValueError("Choose script or language, not both")
+        script = script_for_language(language) if language else (script or default_script)
+        if script not in SCRIPTS:
+            raise ValueError(f"script must be one of {SCRIPTS}")
+        if type(rotation) is not int or rotation not in (0, 90, 180, 270):
+            raise ValueError("rotation must be 0, 90, 180 or 270")
+        if type(runs) is not int or not 1 <= runs <= 30:
+            raise ValueError("runs must be an integer from 1 to 30")
+        if roi is not None:
+            if len(roi) != 4 or any(type(v) is not int for v in roi):
+                raise ValueError("roi must contain four integer pixel coordinates")
+            l, t, r, b = roi
+            if not (0 <= l < r and 0 <= t < b):
+                raise ValueError("roi must be a nonempty positive rectangle")
+            roi = list(roi)
+        return script, roi
+
+    @contextmanager
+    def _stage(self, timings, name):
+        start = perf_counter()
+        try:
+            yield
+        finally:
+            timings[name] = (perf_counter() - start) * 1000
+
+    def _recognize(self, loader, *, script=None, language=None, roi=None, rotation=0, runs=1):
+        script, roi = self._options(script, language, self.script, roi, rotation, runs)
+        with self._lock:
+            started = perf_counter()
+            timing = {}
+            self._select_device()
+            request_id = uuid.uuid4().hex
+            directory = f"files/requests/{request_id}"
+            image_path = f"{directory}/input.png"
+            result = None
+            staged = False
+            try:
+                with self._stage(timing, "load_ms"):
+                    image, source_roi = loader()
+                    if source_roi is not None:
+                        if roi is not None:
+                            raise ValueError("An explicit ROI cannot be combined with XPath bounds")
+                        roi = list(source_roi)
+                    if not isinstance(image, bytes) or not 0 < len(image) <= MAX_INPUT_BYTES:
+                        raise ValueError("Input must contain 1..32 MiB of encoded image bytes")
+                with self._stage(timing, "setup_ms"):
+                    self._ensure_helper()
+                request = {"schema_version": 1, "id": request_id, "script": script,
+                           "source": {"type": "private", "path": image_path},
+                           "rotation": rotation, "roi": roi, "runs": runs}
+                with self._stage(timing, "transfer_ms"):
+                    self._shell("run-as", PACKAGE, "mkdir", "-p", directory)
+                    staged = True
+                    for path, data in ((image_path, image),
+                                       (f"{directory}/request.json", json.dumps(request).encode("utf-8"))):
+                        # ASCII transport avoids Windows binary-stdin conversion/truncation.
+                        self._shell("run-as", PACKAGE, "sh", "-c", f"base64 -d > {path}",
+                                    payload=base64.b64encode(data))
+                with self._stage(timing, "instrumentation_ms"):
+                    output = self._shell("am", "instrument", "-w", "-e", "request_id", request_id,
+                                         RUNNER, timeout=max(self.timeout, 60 + 35 * runs))
+                with self._stage(timing, "result_ms"):
+                    try:
+                        raw = self._exec("run-as", PACKAGE, "cat", f"{directory}/result.json")
+                    except ADBMLKitError as exc:
+                        raise ADBMLKitError("No result from helper: " + output.decode("utf-8", errors="replace")) from exc
+                    try:
+                        data = json.loads(raw.decode("utf-8"))
+                    except (UnicodeDecodeError, json.JSONDecodeError) as exc:
+                        raise ADBMLKitError("Helper returned invalid UTF-8 JSON") from exc
+                    result = OCRResult.from_dict(data, request_id)
+            finally:
+                if staged:
+                    with self._stage(timing, "cleanup_ms"):
+                        try:
+                            self._shell("run-as", PACKAGE, "rm", "-rf", directory)
+                        except ADBMLKitError as exc:
+                            warnings.warn(f"Could not remove own request {request_id}: {exc}", RuntimeWarning)
+                timing["total_ms"] = (perf_counter() - started) * 1000
+            result.host_timing = timing
+            return result
+
+    def recognize_bytes(self, data: bytes, **options) -> OCRResult:
+        return self._recognize(lambda: (data, None), **options)
+
+    def recognize_file(self, path, **options) -> OCRResult:
+        def load():
+            with Path(path).open("rb") as stream:
+                return stream.read(MAX_INPUT_BYTES + 1), None
+        return self._recognize(load, **options)
+
+    def recognize_device_file(self, path: str, **options) -> OCRResult:
+        if not isinstance(path, str) or not path.startswith("/") or "\x00" in path:
+            raise ValueError("device path must be an absolute Android path without NUL")
+        return self._recognize(lambda: (self._exec("cat", path), None), **options)
+
+    def recognize_screenshot(self, **options) -> OCRResult:
+        return self._recognize(lambda: (self._exec("screencap", "-p"), None), **options)
+
+    def recognize_xpath(self, xpath: str, xpath_timeout=10, **options) -> OCRResult:
+        if not xpath or xpath_timeout <= 0:
+            raise ValueError("xpath and a positive xpath_timeout are required")
+        if options.get("roi") is not None:
+            raise ValueError("XPath supplies its own ROI")
+        def load():
+            try:
+                import uiautomator2 as u2
+            except ImportError as exc:
+                raise ADBMLKitError('Install optional UI support: pip install "adb-mlkit[ui]"') from exc
+            device = u2.connect(self.serial)
+            bounds = tuple(device.xpath(xpath).get(timeout=xpath_timeout).bounds)
+            image = device.screenshot().convert("RGB")
+            buffer = BytesIO()
+            image.save(buffer, format="PNG")
+            return buffer.getvalue(), bounds
+        return self._recognize(load, **options)
+
+    def batch_files(self, paths, **options):
+        """Sequential fail-fast batch; each image has its own invocation/timing."""
+        return [self.recognize_file(path, **options) for path in paths]

adb_mlkit/helper.py

@@ -0,0 +1,36 @@
+"""Version-matched Android helper resource. No network or device side effects."""
+from contextlib import contextmanager
+import hashlib
+from importlib.resources import as_file, files
+import json
+
+from .models import ADBMLKitError
+
+
+@contextmanager
+def bundled_apk():
+    """Yield a verified filesystem path, including from zip-based installations."""
+    root = files("adb_mlkit").joinpath("assets")
+    apk = root.joinpath("adb-mlkit.apk")
+    manifest = root.joinpath("helper.json")
+    if not apk.is_file() or not manifest.is_file():
+        raise ADBMLKitError(
+            "Bundled helper APK is missing. Install an official wheel, or build Android "
+            "and run scripts/prepare_package.py before packaging. "
+            "You can also use adb-mlkit install /path/to/helper.apk."
+        )
+    try:
+        metadata = json.loads(manifest.read_text(encoding="utf-8"))
+        from . import __version__
+        if metadata["package"] != "io.github.adbmlkit.helper" or metadata["version"] != __version__:
+            raise ValueError("helper/package version mismatch")
+        with as_file(apk) as path:
+            digest = hashlib.sha256()
+            with path.open("rb") as stream:
+                for chunk in iter(lambda: stream.read(1024 * 1024), b""):
+                    digest.update(chunk)
+            if digest.hexdigest() != metadata["sha256"]:
+                raise ValueError("helper APK checksum mismatch")
+            yield path
+    except (KeyError, ValueError, OSError) as exc:
+        raise ADBMLKitError(f"Cannot verify bundled helper: {exc}") from exc

adb_mlkit/models.py

@@ -0,0 +1,100 @@
+"""Typed, lossless wrappers for protocol-v1 OCR results."""
+from dataclasses import dataclass, field, asdict
+import json
+from typing import Any
+
+
+class ADBMLKitError(RuntimeError):
+    """Transport, device selection, protocol or OCR error."""
+
+
+SCRIPTS = ("latin", "chinese", "devanagari", "japanese", "korean")
+LANGUAGES = {
+    "vi": "latin", "en": "latin", "fr": "latin", "de": "latin",
+    "es": "latin", "it": "latin", "pt": "latin", "id": "latin",
+    "ms": "latin", "tr": "latin", "nl": "latin", "pl": "latin",
+    "zh": "chinese", "zh-hans": "chinese", "zh-hant": "chinese",
+    "ja": "japanese", "ko": "korean", "hi": "devanagari",
+    "mr": "devanagari", "ne": "devanagari",
+}
+
+
+def script_for_language(language: str) -> str:
+    """Resolve a documented convenience alias; this is not language detection."""
+    key = language.lower().replace("_", "-")
+    if key not in LANGUAGES:
+        raise ValueError(f"Unsupported language alias {language!r}; choose a script explicitly.")
+    return LANGUAGES[key]
+
+
+@dataclass(frozen=True)
+class Device:
+    serial: str
+    state: str
+    details: str = ""
+
+
+@dataclass
+class TextElement:
+    text: str
+    bounds: list[int] | None = None
+    corner_points: list[list[int]] = field(default_factory=list)
+    recognized_language: str = ""
+    confidence: float | None = None
+
+
+@dataclass
+class TextLine(TextElement):
+    elements: list[TextElement] = field(default_factory=list)
+
+
+@dataclass
+class TextBlock(TextElement):
+    lines: list[TextLine] = field(default_factory=list)
+
+
+@dataclass
+class OCRResult:
+    id: str
+    text: str
+    script: str
+    image: dict[str, Any]
+    timing: dict[str, Any]
+    blocks: list[TextBlock]
+    host_timing: dict[str, float] = field(default_factory=dict)
+    schema_version: int = 1
+    ok: bool = True
+
+    def to_dict(self) -> dict[str, Any]:
+        return asdict(self)
+
+    def to_json(self, indent: int | None = 2) -> str:
+        return json.dumps(self.to_dict(), ensure_ascii=False, indent=indent)
+
+    @classmethod
+    def from_dict(cls, data: dict, request_id: str) -> "OCRResult":
+        if (not isinstance(data, dict) or type(data.get("schema_version")) is not int
+                or data.get("schema_version") != 1 or data.get("id") != request_id):
+            raise ADBMLKitError("Invalid response version or request ID")
+        if data.get("ok") is False:
+            error = data.get("error", {})
+            if not isinstance(error, dict):
+                raise ADBMLKitError("Malformed error response")
+            raise ADBMLKitError(f"{error.get('code', 'OCR_FAILED')}: {error.get('message', error)}")
+        if data.get("ok") is not True:
+            raise ADBMLKitError("Missing success status in response")
+        def fields(item):
+            return {k: item[k] for k in ("text", "bounds", "corner_points", "recognized_language", "confidence") if k in item}
+        try:
+            if not isinstance(data["text"], str) or data["script"] not in SCRIPTS:
+                raise ValueError("Invalid text/script")
+            if not isinstance(data["image"], dict) or not isinstance(data["timing"], dict):
+                raise ValueError("Invalid image/timing")
+            blocks = []
+            for block in data["blocks"]:
+                lines = [TextLine(**fields(line), elements=[TextElement(**fields(e)) for e in line["elements"]])
+                         for line in block["lines"]]
+                blocks.append(TextBlock(**fields(block), lines=lines))
+            return cls(data["id"], data["text"], data["script"], data["image"], data["timing"], blocks)
+        except (KeyError, TypeError, ValueError, AttributeError) as exc:
+            raise ADBMLKitError(f"Malformed OCR response: {exc}") from exc

adb_mlkit-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,15 @@
+adb_mlkit/__init__.py,sha256=7GJdytVoeRb3vK2iDmMLDJX-5snMpGzjJifgHpP4LgM,403
+adb_mlkit/__main__.py,sha256=k1ocEWawweo1qCJWNFAAvyxz3tcY13dzvCenHszij30,48
+adb_mlkit/cli.py,sha256=0yfDv0E_E2WVV4Xkc3uGwPYORXnOz5v-EfKh7rJJT0w,5047
+adb_mlkit/client.py,sha256=k64_ygOjIEswfd1Tx_3-vuSgMwxAbgVW43waeuPYpMA,11643
+adb_mlkit/helper.py,sha256=7Wr-y1weoRfrLwVAK5xWmMXNYyPLYvVyByQuf9BpGWQ,1584
+adb_mlkit/models.py,sha256=womXrra4M9uNlqqc8-7VYDEmv5rhYz6s1cyi0SswnF0,3731
+adb_mlkit/assets/adb-mlkit.apk,sha256=UVEYtJA3pzsiJF8wndUIzDsZskWOSJ8MAjdSWKhfqQQ,49023571
+adb_mlkit/assets/helper.json,sha256=5OmeWwV2htiBKF00Kq03ACWE5hhAz6xmOqpJuoFf3po,147
+adb_mlkit-0.1.0.dist-info/licenses/LICENSE,sha256=sFwJWN9s8IeEH7yUs3MAi_3DseBgWZ-KCYX5aTSiIzc,1079
+adb_mlkit-0.1.0.dist-info/licenses/THIRD_PARTY_NOTICES.md,sha256=3tGIKlVdX4l4-sm5dw27uoWF4Na6M2MPmTV8kUkmFX0,1385
+adb_mlkit-0.1.0.dist-info/METADATA,sha256=ft9ie4xesCwV1j8VeivQyPwV2rZ6LnbE9nd3xc6hGHk,8909
+adb_mlkit-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+adb_mlkit-0.1.0.dist-info/entry_points.txt,sha256=6nVeByvRo8kUMuQ-J37fz00RgidtL-HSyDzwCMAF9GE,49
+adb_mlkit-0.1.0.dist-info/top_level.txt,sha256=qlRKEftco-pYTrJYMd6ARHVjRUlfikDNdoaIEHpQaNE,10
+adb_mlkit-0.1.0.dist-info/RECORD,,

adb_mlkit-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

adb_mlkit-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+adb-mlkit = adb_mlkit.cli:main

adb_mlkit-0.1.0.dist-info/licenses/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.dist-info/licenses/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.dist-info/top_level.txt

@@ -0,0 +1 @@
+adb_mlkit