xplo
Try for free
AI-generated · Not human-reviewed

Local Runtime Clients

The Local Runtime Clients (the local SDKs/libraries) run a prepared workbook inside your Python, TypeScript, Go, or Java process. They load a model bundle you download from xplo and execute it locally with WebAssembly: no server call, no subprocess, no Excel installation, and no per-run metering.

Local or hosted? Use a Local Runtime Client when the model and its inputs must stay in your environment, or when you need low-latency repeated runs. Use the Hosted HTTP SDKs when you would rather keep the model on xplo's servers and call it over the network with a token. Neither family silently falls back to the other.

Run your first local calculation

  1. Prepare a workbook. Naming + Labelling is optional: confirm names if you want readable programmatic keys, or keep the generated cell references as-is.
  2. On the workbook page, open Ways to run it → Local Runtime Clients and choose Download the bundle.
  3. Unzip the bundle, then run one of its generated examples from the bundle root:
Language Command Requirements
TypeScript / Node node examples/node/run.mjs Node 18+; no install for a full bundle
Python pip install -r examples/python/requirements.txt && python3 examples/python/run.py Python 3.10+
Go cd examples/go && go run . Go
Java cd examples/java && mvn -q compile exec:java JDK 17+ and Maven

Each example is generated from that bundle's manifest.json and interface.json, so it already uses your workbook's inputs and outputs. Edit the input values near the top of the example and run the same command again. The output is one name = value line for each selected output.

The bundle includes the xplo client code used by each example. Python, Go, and Java may download their third-party WebAssembly runtime or supporting libraries; the Node example uses the built-in WebAssembly runtime and needs no dependency install. Once those dependencies are present, calculation does not contact xplo.

Use the client in your application

Choose the guide for your language. Each guide covers loading the bundle, running by programmatic name or raw cell address, inspecting the manifest, error handling, sweeps, concurrency, and deployment:

There is currently no Rust Local Runtime Client. Rust applications can call the Runtime API directly or use the Rust Hosted HTTP SDK.

All four clients follow the same basic lifecycle:

  1. Load an unzipped bundle.
  2. Inspect its named inputs and outputs when needed.
  3. Run with a map of input names and a list of output names.
  4. Keep the loaded model and reuse it for later runs.

Names come from the workbook's confirmed cell interface, but they are never required. If a bundle has no confirmed names, use the language guide's runRaw/run_raw API with canonical addresses such as Sheet1!B1. You can also add labels later and download a new bundle.

Installation and availability

Downloading a model bundle or standalone client source is part of the Local Runtime tier (Team plan and up).

The local packages are not yet published to PyPI, npm, the public Go module proxy, or Maven Central. Do not start with the future registry coordinates in a new integration. Today, use either:

  • the client source already vendored in a downloaded bundle; or
  • an authenticated source zip from GET /api/v2/clients/{language}, where language is python, typescript, go, or java.

The source-zip request needs an xplo_ API token; create or manage one in API Tokens.

For example:

curl -fsSL -H "Authorization: Bearer $XPLO_TOKEN" \
  "https://xplo.pythia.software/api/v2/clients/python" \
  -o xplo-client-python.zip
unzip -q xplo-client-python.zip
pip install ./python

The language guides give the equivalent source-zip and vendored-source steps for each toolchain.

What to deploy

A full bundle contains the workbook model, WebAssembly engine, names and typed manifest, generated examples, a JavaScript loader, and the vmrun CLI. Keep the bundle files together and point the client at the bundle directory.

An installable client can also load a slim bundle that omits the shared engine. In that case, warm the client cache with a full bundle first or set XPLO_RUNTIME_WASM to the matching vmruntime.wasm. The language guides cover the shared cache and the exact deployment options.

For local execution from a shell without embedding a library, use the bundle's bin/vmrun CLI instead. For execution without downloading or deploying model artifacts, use the Runtime API or Hosted HTTP SDKs.