ArXistant Android app (standalone)

The android/ directory contains an Android app that runs the complete ArXistant pipeline on the phone: fetching arXiv, ranking with the ML model, the SQLite paper database, and Nutstore cloud sync. It does not need a remote server or a desktop Mac.

Download

Prebuilt, signed APKs are attached to each GitHub release. For the latest published release (v0.4.4) the direct download is:

https://github.com/jyshangguan/ArXistant/releases/download/v0.4.4/arxistant-release.v0.4.4.apk

Once an APK is installed, the app can update itself: ⋯ → Check for Updates downloads the newest release APK and opens the installer.

Copy the APK to the phone and open it to install. If a debug build is already installed, uninstall it first (the debug and release builds use different signing keys). Building the APK from source is described under Build.

How it works

The app embeds the existing Python server with Chaquopy, which runs CPython (plus NumPy and scikit-learn) inside the Android process:

[Android app]
  ├─ ServerService (foreground service)
  │     └─ Chaquopy Python runtime
  │           └─ arxiv_db_server.run_server() on 127.0.0.1:8765
  │                ├─ fetch arXiv (urllib)
  │                ├─ ML rank (numpy + scikit-learn)
  │                ├─ SQLite paper DB (app-private storage)
  │                └─ Nutstore WebDAV sync (periodic auto-sync)
  └─ MainActivity
        ├─ TextToSpeech engine (native voice for the Listen button)
        └─ WebView -> http://127.0.0.1:8765/daily.html

The WebView renders the same HTML pages the server already generates, and the existing save buttons keep working because they POST /api/... to the embedded server. The ML model is not synced; the phone trains its own model from the Nutstore-synced saved papers, exactly like a second desktop install.

Mobile interface

Because the desktop pages were written for a wide browser window, the server injects a small mobile layer (CSS + JavaScript) only when it detects an Android WebView. It adds:

The app icon is the ArXistant logo, and MainActivity shows a loading page and polls the embedded server until it is ready, so the daily list appears as soon as the server has started.

Python-side changes that make this possible

Three small changes were made to the shared Python code (all backwards compatible with the desktop app):

  1. In-process tasks — src/arxistant_tasks.py runs training, feature-page generation, and daily/recent refresh. On desktop they still run as subprocesses; on Android (ARXISTANT_IN_PROCESS=1) they import the modules and call the functions directly, because Chaquopy cannot spawn Python subprocesses.
  2. Pluggable secret store — src/arxistant_secrets.py accepts a custom backend via set_backend(...). The Android app supplies a Keystore-backed backend (SecretStore.java) so the Nutstore app password is encrypted, not stored in plaintext.
  3. Configurable bind address — run_server() honors ARXISTANT_BIND (default localhost); the Android bootstrap sets it to 127.0.0.1.
  4. Native voice bridge — the Listen script injected into the Daily and Recent pages checks window.ArxistantAndroid.ttsSpeak at runtime: when present it drives the app’s TextToSpeech engine (same sentence chunking, announcements, and pauses as the desktop’s speechSynthesis path) and offers the inline voice settings row; when absent (older APK, desktop browser) the behavior is unchanged.

Prerequisites

Build

cd android
./copy_python.sh        # copy ../src/*.py into app/src/main/python/

# Debug APK:
./gradlew :app:assembleDebug
#   -> app/build/outputs/apk/debug/app-debug.apk

# Release APK (signed; see "Release build" below):
./gradlew :app:assembleRelease
#   -> app/build/outputs/apk/release/arxistant-release.v0.4.5.apk

The first build downloads Chaquopy, NumPy, and scikit-learn wheels for the target ABIs, so it is slow and produces a large APK (scikit-learn is the bulk of it).

Release build

The release APK is signed with a local keystore so it can be installed and updated over the debug build. The signing material is not committed:

Both are listed in android/.gitignore. To create them from scratch:

cd android
mkdir -p keystore
keytool -genkeypair -v \
  -keystore keystore/release.keystore \
  -alias arxistant \
  -keyalg RSA -keysize 2048 -validity 10000 \
  -storepass <store-password> -keypass <key-password> \
  -dname "CN=ArXistant, OU=Personal, O=ArXistant, C=CN"

then write keystore.properties:

storeFile=keystore/release.keystore
storePassword=<store-password>
keyAlias=arxistant
keyPassword=<key-password>

app/build.gradle reads keystore.properties when present and applies it to the release build type. Keep a backup of both files; without the same key you cannot push an update over an existing install. The current Android version is v0.4.7 (versionName "0.4.7", versionCode 15 in app/build.gradle); bump both whenever you publish a new release so the in-app update check can detect it.

CI builds (GitHub Actions)

The Build release assets workflow builds the signed APK automatically when a release is published — no local Android SDK needed. It requires four repository secrets (Settings → Secrets and variables → Actions), created from the local keystore:

Secret Value
ARXISTANT_KEYSTORE_BASE64 base64 -i android/keystore/release.keystore (macOS)
ARXISTANT_KEYSTORE_PASSWORD the store password from keystore.properties
ARXISTANT_KEY_ALIAS the key alias (arxistant if generated as above)
ARXISTANT_KEY_PASSWORD the key password from keystore.properties

If the secrets are missing, the workflow still builds the Debian package and the Chrome extension zip and simply skips the APK (an unsigned APK cannot be installed, so none is uploaded). To add the APK to an already-published release after configuring the secrets, run the workflow manually with the existing tag.

Install and run

Nutstore sync on the phone

Cloud sync is configured exactly as on desktop: open the ⋯ menu and choose Cloud Sync (or ☁️ Cloud Sync), select Nutstore WebDAV (坚果云), enter your email and the 第三方应用密码, and click Connect. The app password is stored encrypted via the Keystore backend.

Once connected, the phone syncs automatically every 30 minutes (the default interval_minutes), and also syncs before every manual refresh. Syncing uses the same last-write-wins versioned snapshot as desktop — saved papers, publications, custom keywords, and the Notebook’s folders and notes — so the phone and your Mac stay in step, reading list included.

Current limitations (to be aware of)