Skip to content

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.

For each run(modelId, bitmap):

  1. Same device (IPC): the gateway app is installed and verified genuine, this app holds the USE_GATEWAY signature permission, and the gateway lists the model. Pixels go over Binder in shared memory as raw ARGB_8888, so nothing is lost to JPEG.
  2. The hub over HTTPS (JPEG at quality 95): addHub(url, key) for a hub with a public certificate, or addHub(url, token, certPem) for a LAN gateway trusting only its pinned self-signed certificate.
  3. Your Fallback, for example the model bundled in the app.
  4. 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 thread
float[] v = r.embedding(); // or r.labels() for classifiers
Log.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.

The pattern (used to move a photo app off its own bundled 582 MB CLIP model):

  1. Pick the gateway model id and version that match the app’s model and preprocessing.
  2. Keep the app’s own runner as the Fallback, so nothing breaks without a gateway.
  3. Configure only the hub (addHub). Clients never talk to nodes; node keys refuse client calls.
  4. 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