Client library (Android)
:client (dev.kinherd.client, Java, minSdk 30, AAR) runs a model on the nearest gateway and falls back
to the app’s own code when none is available. Build it with ./gradlew :client:assembleRelease.
Path selection
Section titled “Path selection”For each run(modelId, bitmap):
- Same device (IPC): the gateway app is installed and verified genuine, this app holds the
USE_GATEWAYsignature permission, and the gateway lists the model. Pixels go over Binder in shared memory as raw ARGB_8888, so nothing is lost to JPEG. - The hub over HTTPS (JPEG at quality 95):
addHub(url, key)for a hub with a public certificate, oraddHub(url, token, certPem)for a LAN gateway trusting only its pinned self-signed certificate. - Your
Fallback, for example the model bundled in the app. - Otherwise
GatewayUnavailableException, listing what happened on each path.
The chosen path is cached per model for 5 minutes and dropped on failure or a network change.
GatewayClient gw = GatewayClient.builder(context) .addHub("https://<hub-host>", hubKey) // the only gateway a client knows .requireVersion("clip-l14-336", "1") .timeouts(3_000, 30_000) // connect/bind, read/call .fallback((id, bmp) -> Result.ofEmbedding(id, "1", localClip.embed(bmp), "app")) .build();
Result r = gw.run("clip-l14-336", bitmap); // off the main threadfloat[] v = r.embedding(); // or r.labels() for classifiersLog.i("app", "via " + r.path() + " on " + r.servedBy() + " (" + r.backend() + ", " + r.ms() + " ms)");Keep one GatewayClient for the app’s lifetime; it is thread-safe.
Adopting it in an existing app
Section titled “Adopting it in an existing app”The pattern (used to move a photo app off its own bundled 582 MB CLIP model):
- Pick the gateway model id and version that match the app’s model and preprocessing.
- Keep the app’s own runner as the
Fallback, so nothing breaks without a gateway. - Configure only the hub (
addHub). Clients never talk to nodes; node keys refuse client calls. - For same-device IPC, sign the app and the gateway with the same key (or pin the gateway signer with
.gatewaySigner(sha256)), and install the gateway first.
Embeddings are comparable on every path: the same model with the same preprocessing. Measured agreement between the gateway and an app’s on-device embedder: cosine 0.996.
| Situation | What happens |
|---|---|
| Gateway app missing, not genuine, or permission missing | IPC skipped (reason in logcat, tag GatewayClient) |
| The model is only on a node | the hub forwards it (via set) |
| Hub unreachable | 3 s connect timeout, then remembered as down for 30 s or until the network changes |
Version differs from requireVersion |
that gateway is skipped |
| Nothing works and no fallback | GatewayUnavailableException with one reason per path |