F-Droid build without ML Kit (#29)

The fdroid flavor reads text with the open-source Tesseract engine instead of Google ML Kit, adds F-Droid/IzzyOnDroid fastlane metadata and docs/store/FDROID.md, and CI checks the F-Droid APK for proprietary Google classes.

Author: dineshsoudagar

.github/scripts/check_no_proprietary_classes.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python3
+"""Fail if an APK contains classes from proprietary Google libraries.
+
+Used on the F-Droid flavor, which must not ship Google ML Kit, Google Play Services or
+Firebase. Scans the type descriptors in every classes*.dex file of each APK given.
+"""
+import re
+import sys
+import zipfile
+
+FORBIDDEN = (
+    b"Lcom/google/mlkit/",
+    b"Lcom/google/android/gms/",
+    b"Lcom/google/firebase/",
+)
+DEX_NAME = re.compile(r"^classes\d*\.dex$")
+
+
+def scan(apk_path):
+    hits = {}
+    with zipfile.ZipFile(apk_path) as apk:
+        dex_names = [name for name in apk.namelist() if DEX_NAME.match(name)]
+        if not dex_names:
+            raise SystemExit(f"{apk_path}: no classes*.dex found")
+        for name in dex_names:
+            data = apk.read(name)
+            for prefix in FORBIDDEN:
+                for match in re.finditer(re.escape(prefix) + rb"[A-Za-z0-9_/$]*;", data):
+                    hits.setdefault(prefix.decode(), set()).add(f"{name}: {match.group().decode(errors='replace')}")
+    return hits
+
+
+def main(paths):
+    if not paths:
+        raise SystemExit("usage: check_no_proprietary_classes.py APK...")
+    failed = False
+    for path in paths:
+        hits = scan(path)
+        if hits:
+            failed = True
+            print(f"FAIL {path}")
+            for prefix, entries in sorted(hits.items()):
+                print(f"  {prefix} ({len(entries)} references)")
+                for entry in sorted(entries)[:20]:
+                    print(f"    {entry}")
+        else:
+            print(f"OK   {path}: no {', '.join(p.decode() for p in FORBIDDEN)} classes")
+    return 1 if failed else 0
+
+
+if __name__ == "__main__":
+    sys.exit(main(sys.argv[1:]))

.github/workflows/android-ci.yml

@@ -46,6 +46,9 @@ jobs:
       - name: Build debug APKs (GitHub, F-Droid, Play)
         run: bash ./gradlew assembleGithubDebug assembleFdroidDebug assemblePlayDebug --stacktrace
 
+      - name: Check F-Droid APK has no ML Kit, Play Services or Firebase classes
+        run: python3 ../.github/scripts/check_no_proprietary_classes.py app/build/outputs/apk/fdroid/debug/*.apk
+
       - name: Check 16 KB page support of native libraries
         continue-on-error: true
         run: python3 ../.github/scripts/check_16kb_pages.py app/build/outputs/apk/play/debug/*.apk

docs/store/FDROID.md

@@ -0,0 +1,82 @@
+# F-Droid and IzzyOnDroid release checklist
+
+The `fdroid` build flavor is the one meant for F-Droid and IzzyOnDroid. It contains no Google ML Kit, Google Play Services or Firebase code. CI checks this on every build (`.github/scripts/check_no_proprietary_classes.py` scans the dex files of the F-Droid debug APK).
+
+## Build
+
+```bash
+cd pocket_llm_src
+bash ./gradlew assembleFdroidRelease
+```
+
+- Output: `app/build/outputs/apk/fdroid/release/app-fdroid-release-unsigned.apk`. Sign it with your own release key (`apksigner sign --ks <keystore> ...`), or configure a `signingConfig` locally. Never commit the keystore.
+- Always sign F-Droid/IzzyOnDroid APKs with the **same key**. Users cannot update across keys without uninstalling.
+- Release builds fail until `src/main/res/values/legal_contact.xml` is filled in (see [docs/legal](../legal/README.md)).
+- Debug builds install side by side with the other flavors as `io.github.dineshsoudagar.pocketllm.debug.fdroid`.
+
+## What differs in the fdroid flavor
+
+| | github / play | fdroid |
+|---|---|---|
+| OCR engine | Google ML Kit text recognition (proprietary, model bundled, sends diagnostics to Google) | Tesseract 5 via Tesseract4Android (Apache-2.0) |
+| OCR language data | inside the ML Kit library | `eng.traineddata` from [tesseract-ocr/tessdata_fast](https://github.com/tesseract-ocr/tessdata_fast) tag `4.1.0`, about 4 MB, downloaded on first OCR use into `filesDir/ocr/tessdata`, size and SHA-256 pinned |
+| Code | `src/mlkit/java` (added to the github and play source sets) | `src/fdroid/java` |
+
+Both implement the `OcrEngine` interface in `src/main`. Callers (`OcrInput` for camera/gallery images, `AttachmentImporter` for scanned PDF pages) are the same in every flavor.
+
+If OCR data is missing and the phone is offline, OCR fails with "Text recognition needs its English language data (about 4 MB) once. Connect to the internet and try again." In the chat screen, download progress is shown as a short status message. The PDF importer runs in a background worker and shows the same error on the attachment if the download fails.
+
+Tesseract is noticeably slower than ML Kit and somewhat weaker on photos of curved or angled text. It is English-only for now; more languages can be added by pinning more `*.traineddata` files in `TesseractLanguageData.kt`.
+
+### Where Tesseract4Android is published
+
+Tesseract4Android (`cz.adaptech.tesseract4android:tesseract4android:4.9.0`, Tesseract 5.5.1 + Leptonica, Apache-2.0) is **only published on JitPack**, not on Maven Central. The build adds `https://jitpack.io` in `settings.gradle.kts`, restricted to the group `cz.adaptech.tesseract4android`.
+
+Trade-off:
+- IzzyOnDroid does not build from source, so a JitPack dependency is fine there; it only scans the APK.
+- F-Droid builds from source and dislikes binaries prebuilt by JitPack. For the main F-Droid repository, Tesseract4Android should be built from source as a `srclib` (it is a plain Gradle + CMake/NDK project, so this is feasible) and the JitPack repository removed in the recipe's `prebuild`.
+- The older `com.rmtheis:tess-two` is on Maven Central but unmaintained (Tesseract 3/4 era), so it was not chosen.
+
+## IzzyOnDroid (fastest route)
+
+IzzyOnDroid takes APKs straight from GitHub Releases and reads the store listing from `fastlane/metadata/android/` in this repository.
+
+1. Build and sign `assembleFdroidRelease`. Attach the APK to the GitHub release with a clear name, for example `pocket_llm_v1.6.0_fdroid.apk`. Keep the GitHub (ML Kit) APK as a separate asset; tell Izzy which file name pattern to pick.
+2. Keep `fastlane/metadata/android/en-US/` up to date: `title.txt`, `short_description.txt` (max 80 characters), `full_description.txt`, `images/icon.png`, and `changelogs/<versionCode>.txt` for every release (current versionCode: 15). Screenshots go into `images/phoneScreenshots/` (none added yet).
+3. Open a request at https://codeberg.org/IzzyOnDroid/repodata/issues with the repository URL, license, the APK asset name and a short description. Mention that the app downloads models from Hugging Face at runtime and that the F-Droid flavor uses Tesseract instead of ML Kit.
+4. **APK size:** IzzyOnDroid's general rule is about 30 MB per APK; larger apps need an exception. This APK is far larger (see blockers), so ask for an exception in the request, or ship a per-ABI `arm64-v8a` APK.
+5. Izzy's scanner checks for proprietary libraries and trackers. The CI check above covers ML Kit, Play Services and Firebase.
+
+## Main F-Droid repository
+
+1. Fork https://gitlab.com/fdroid/fdroiddata and add `metadata/io.github.dineshsoudagar.pocketllm.yml` with a build recipe: `subdir: pocket_llm_src/app`, `gradle: [fdroid]`, the release commit or tag, `AutoUpdateMode`/`UpdateCheckMode: Tags`, and `srclibs`/`prebuild` steps for every native dependency that must be built from source (see blockers).
+2. Test locally with `fdroid build -v -l io.github.dineshsoudagar.pocketllm` (fdroidserver) and `fdroid lint`.
+3. Open a merge request. Reviewers will run the scanner and ask about every prebuilt binary and non-standard Maven repository.
+
+F-Droid can also offer reproducible builds signed with the developer's key, if the build output matches byte for byte.
+
+## Open blockers for the main F-Droid repository
+
+These are not fixed in this branch; the fdroid flavor is free of ML Kit/Play Services but still ships prebuilt native code.
+
+| Dependency | Source | Problem for F-Droid |
+|---|---|---|
+| LiteRT-LM `com.google.ai.edge.litertlm:litertlm-android:0.17.1` | Google Maven | Prebuilt native AAR. Source is Apache-2.0 (google-ai-edge/LiteRT-LM) but built with Bazel; F-Droid would need to build it from source. Its transitive dependencies should also be checked for Google-only artifacts (the CI dex check would catch Play Services classes). This is the core inference engine, so it is the largest blocker. |
+| ONNX Runtime `com.microsoft.onnxruntime:onnxruntime-android:1.27.0` | Maven Central | MIT, but prebuilt `libonnxruntime.so` for 4 ABIs. Building from source is possible but heavy. |
+| sherpa-onnx `sherpa-onnx-static-link-onnxruntime-1.13.4.aar` | GitHub Releases via an Ivy repository in `settings.gradle.kts`, then stripped by `verifyOnnxRuntimeNativeCompatibility` in `app/build.gradle.kts` | Apache-2.0, but a prebuilt binary AAR from a non-Maven repository. The scanner flags both. Needs a from-source `srclib` build. |
+| Tesseract4Android 4.9.0 | JitPack | Apache-2.0, prebuilt by JitPack; build from source as a srclib (see above). |
+| APK size | | The universal APK is about 300 MB because of native libraries for 4 ABIs. Consider ABI splits for the fdroid flavor. |
+
+Other points reviewers may raise:
+- Models are not in the APK; they are downloaded at runtime from Hugging Face. Some built-in models (Gemma) use Google's Gemma terms rather than an OSI license, so reviewers may discuss an anti-feature label for downloaded non-free assets.
+- No other proprietary libraries were found: AndroidX, CameraX, Material Components, Markwon, PdfBox-Android, WorkManager and org.json (public domain since 2022; version 20240303 is used) are free software.
+
+## Test on a phone before submitting
+
+Install the fdroid debug APK (`app/build/outputs/apk/fdroid/debug/`) and check:
+
+1. **Gallery OCR** with mobile data/Wi-Fi on: the first use shows "Downloading OCR language data..." and then the recognized text.
+2. **Gallery OCR offline** after clearing app data: a clear error asking to connect once, no crash.
+3. **Camera OCR**: photo of a printed page, including a portrait photo (EXIF rotation).
+4. **Scanned PDF** attachment (pages without embedded text): text is extracted, and an offline first run fails with the same clear error.
+5. Repeat 1, 3 and 4 on the github or play debug build to confirm ML Kit behaviour did not change.

fastlane/metadata/android/en-US/changelogs/15.txt

@@ -0,0 +1,7 @@
+* Use your phone as a password-protected LLM server on your local network, with a browser chat UI and an OpenAI-compatible API
+* Import your own LiteRT-LM model (beta)
+* Text, PDF and audio attachments, including OCR for scanned PDF pages
+* Offline multilingual Whisper speech-to-text
+* Per-model context length setting
+* LiteRT-LM updated to 0.17.1
+* F-Droid build: open-source Tesseract OCR instead of Google ML Kit

fastlane/metadata/android/en-US/full_description.txt

@@ -0,0 +1,20 @@
+Pocket LLM runs large language models directly on your Android phone. Chats, prompts, attachments and model answers stay on the device. There are no accounts, no ads, no analytics and no server run by the developer.
+
+<b>How it works</b>
+The app itself does not contain a model. After installing, you choose a built-in model (Qwen2.5, Qwen3, DeepSeek R1 Distill Qwen or Gemma 4) and the app downloads it from Hugging Face (huggingface.co). Models are several hundred MB to a few GB, so use Wi-Fi. You can also import your own LiteRT-LM model file (beta). Once a model is installed, chatting works offline.
+
+<b>Features</b>
+* Streaming chat with multi-turn history, Markdown rendering and optional thinking mode on supported models
+* Attach text files and PDFs; scanned PDF pages are read with on-device OCR
+* Read text from photos and images with on-device OCR, or send images directly to models that support image input
+* Offline speech-to-text with multilingual Whisper (downloaded once from Hugging Face, about 100 MB)
+* Audio attachments for models with native audio support
+* Editable instructions, prompt presets and per-model context length
+
+<b>Local network server</b>
+Optionally turn the phone into a password-protected LLM server for your home network: open the built-in web chat in a computer browser, or connect OpenAI-compatible clients and scripts. Requests stay inside your local network. The server only runs while you keep it switched on.
+
+<b>Good to know</b>
+* Running LLMs needs a recent phone with plenty of RAM. Large models or long contexts can fail to load or crash on some devices.
+* This version uses the open-source Tesseract engine for text recognition. The first time you use OCR it downloads the English language data (about 4 MB) from GitHub.
+* Network access is used only for model and data downloads you start, and for the optional local network server.

fastlane/metadata/android/en-US/images/icon.png

@@ -0,0 +1 @@
+Private, offline AI chat on your phone, with a local network LLM server

fastlane/metadata/android/en-US/short_description.txt

@@ -0,0 +1 @@
+Pocket LLM

fastlane/metadata/android/en-US/title.txt

@@ -50,6 +50,18 @@ android {
         }
     }
 
+    // OCR: github and play share the Google ML Kit implementation in src/mlkit;
+    // fdroid uses the open-source Tesseract implementation in src/fdroid.
+    // AGP's built-in Kotlin compiles the kotlin source directories, so register the shared folder there.
+    sourceSets {
+        listOf("github", "play").forEach { flavor ->
+            getByName(flavor) {
+                java.srcDir("src/mlkit/java")
+                kotlin.srcDir("src/mlkit/java")
+            }
+        }
+    }
+
     buildTypes {
         release {
             isMinifyEnabled = false
@@ -123,7 +135,11 @@ dependencies {
     implementation("androidx.camera:camera-camera2:1.4.2")
     implementation("androidx.camera:camera-lifecycle:1.4.2")
     implementation("androidx.camera:camera-view:1.4.2")
-    implementation("com.google.mlkit:text-recognition:16.0.1")
+    // Proprietary ML Kit stays out of the fdroid flavor.
+    "githubImplementation"("com.google.mlkit:text-recognition:16.0.1")
+    "playImplementation"("com.google.mlkit:text-recognition:16.0.1")
+    // Tesseract OCR (Apache-2.0), JitPack-only; see docs/store/FDROID.md.
+    "fdroidImplementation"("cz.adaptech.tesseract4android:tesseract4android:4.9.0")
     implementation("com.google.ai.edge.litertlm:litertlm-android:$liteRtLmVersion")
     implementation("com.tom-roush:pdfbox-android:2.0.27.0")
     implementation("androidx.work:work-runtime-ktx:2.11.2")