TypeScript client

Run a prepared workbook inside your own Node or browser process. The model is a data file; the engine is a shared WebAssembly module. No server call, no subprocess, no Excel.

This page is the Local Runtime Client. It runs the model in your process, on a bundle you downloaded: no network, no token, no per-run metering. The other family — the Hosted HTTP SDKs — calls xplo's servers over HTTP and never downloads model code. Neither silently falls back to the other. Pick by where the calculation runs.

It is the same evaluator that powers hosted execution and the vmrun CLI, so the same model and inputs give the same values in every WebAssembly host. See How closely the engines agree, below, for the one place that is not the whole truth.

Run it in one command

Every downloaded bundle carries a ready-to-run example, and for Node it needs nothing at all — no package install, no third-party dependency.

On your workbook page, open Ways to run it → Local Runtime Clients → Download the bundle, and unzip it.
From the bundle folder:

node examples/node/run.mjs

It prints one line per output — real names, real numbers, from this model:

lookup_total = 27
total = 4

examples/node/run.mjs was generated from the bundle's own manifest.json and interface.json, so its inputs and outputs are already your cells; it imports the bundle's dependency-free loader.mjs and Node's built-in WebAssembly. Edit the values at the top and re-run. examples/README.md lists the equivalent one-liner for the CLI, Python, Go, and Java.

Node is the only fully offline example. A slim bundle has no loader.mjs and therefore no examples/node/run.mjs — see What is in a bundle, and slim bundles below.

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

When to use it

You want to	Use
Run a model inside your own service, offline or in a hot loop	This client
Run a model without managing any artifacts	Runtime API or the Hosted HTTP SDKs
Explore a model from a terminal	The bundle's `bin/vmrun` CLI

The client is versioned against the engine contract, not against any workbook. Install it once and load as many models as you like — a new workbook is a new data file, not a new package.

Install

yarn add @xplo/runtime

Not on npm yet. yarn add @xplo/runtime 404s today — the package has not been published to any public registry. Until it is, use one of the three paths below; all three install the same code, and the coordinate above is what the command will be once released.

1. Skip the install. Every full bundle ships loader.mjs, a dependency-free ES module with the same run surface. This is the zero-install path the generated Node example uses:

// run.mjs
import { loadModel } from './model-bundle/loader.mjs';
const model = await loadModel();                 // loads ./model.wasm + ./plan.xvm
console.log(model.runRaw({ 'Sheet1!B1': 200000 }, ['Sheet1!B8']));

loader.mjs reads the bundle's own model.wasm, so it is a full-bundle-only path; the installable package below is the one that also handles slim bundles, names, and sweeps.

2. Download the client source from the API — the path for a team without npm access:

curl -fsSL -H "Authorization: Bearer $XPLO_TOKEN" \
  "https://xplo.pythia.software/api/v2/clients/typescript" -o xplo-client-ts.zip
unzip -q xplo-client-ts.zip                      # unpacks ./typescript
(cd typescript && yarn install && yarn build)    # dist/ is generated, not shipped
yarn add "file:$PWD/typescript"

The token is an xplo_ API token, the same one the Runtime API uses. Create or manage it in API Tokens.

3. Install from a checkout of the xplo repository, if you have one: build it once with (cd /path/to/explo/clients/typescript && yarn install && yarn build), then yarn add file:/path/to/explo/clients/typescript.

Requires Node 18+. It also runs in browsers, where WebAssembly is built in. The package is ESM-only, so the file that imports it must be .mjs or your package.json must set "type": "module".

Quickstart

Point the client at the unzipped bundle folder:

import { loadBundle } from '@xplo/runtime';

const model = await loadBundle('./model-bundle');

console.log(model.manifest());        // the typed input/output contract
console.log(model.namedInputs());     // names you can set
console.log(model.namedOutputs());    // names you can read

const out = model.run({ loan_amount: 200_000 }, ['monthly_payment']);
console.log(out.monthly_payment.value);

Names exist only once labels are confirmed on the workbook, and Naming + Labelling is optional. If model.namedInputs() is an empty array, this bundle has no names yet — use runRaw with addresses (model.runRaw({ 'Sheet1!B1': 5 }, ['Sheet1!B4'])). You can keep using cell references indefinitely, or add labels in the app and download the bundle again.

To load the pieces yourself — from a database, an object store, or memory:

import { loadModel } from '@xplo/runtime';

const model = await loadModel({
  wasm: './model.wasm',        // path (Node), bytes, or a compiled WebAssembly.Module
  blob: planXvmBytes,
  interface: interfaceJson,    // optional; an object, bytes, or a path. Enables names
});

What is in a bundle, and slim bundles

A full bundle contains plan.xvm (your model), model.wasm (the shared engine), interface.json (your names), manifest.json (the typed contract), loader.mjs + model.d.ts, an examples/ directory, and a bin/vmrun binary for the command line.

A slim bundle carries only the model and its metadata — no model.wasm, no loader.mjs, no bin/vmrun (≈20 KB instead of ≈5.7 MB). It still runs through this package, because the interpreter is identical for every model and the client caches it once per machine. loadBundle resolves the engine in this order:

The wasmOverride argument, if you pass one: loadBundle(dir, './vmruntime.wasm') also accepts bytes or an already-compiled WebAssembly.Module, which is the fastest way to reuse one engine across many models.
XPLO_RUNTIME_WASM — an explicit path to a vmruntime.wasm.
The machine cache — XPLO_RUNTIME_CACHE, or the OS user-cache directory plus /xplo/runtime, keyed by the runtime_hash recorded in bundle.json.
The bundle's own model.wasm, which is then copied into the cache for next time.

The cache is shared across languages — the file names are identical — so loading one full bundle from any language warms it for all of them. A slim bundle with a cold cache fails loudly rather than confusingly:

Error: bundle at ./model-bundle ships no interpreter (slim bundle) and none is
cached: set XPLO_RUNTIME_WASM to a vmruntime.wasm, or load a full bundle once (it
caches the shared runtime automatically)

If the resolved engine is not the one the bundle was built against, the load fails with an interpreter hash mismatch rather than running a mismatched pair.

Names and cell addresses

Names come from the labels you set on the workbook, and are the stable way to call a model — a cell can move without breaking your code.

model.run({ loan_amount: 200_000 }, ['monthly_payment']);

Aliases work, and name matching is case-insensitive. Cell addresses are always available as an escape hatch, and any key containing ! is treated as one — addresses are matched exactly, including the sheet name, so sheet1!b1 is not Sheet1!B1:

model.run({ 'Loan!B1': 200_000 }, ['Loan!B8']);
model.runRaw({ 'Loan!B1': 200_000 }, ['Loan!B8']);   // skip name resolution entirely

Mix them when a cell has no name yet:

model.run({ loan_amount: 200_000 }, ['monthly_payment'], {
  rawInputs: { 'Loan!C7': 0.02 },
  rawOutputs: ['Loan!D9'],
});

Results are keyed by whatever you asked for, so a canonical name and an alias can both appear in one response.

Omitting outputs returns every terminal output. allNamedOutputs returns each currently named one, and allNamedInputs echoes the inputs back:

model.run({ loan_amount: 200_000 }, undefined, { allNamedOutputs: true });

namedInputs() and namedOutputs() list canonical names only. To see aliases, review status, and long labels, read model.interfaceLabels().

Values

Inputs accept a finite number, a boolean, or a string. null, undefined, NaN and Infinity are rejected rather than quietly ignored, because the VM would have left the cell at its baseline and returned a confident number for a scenario you did not ask for. To leave a cell at its baseline, omit the key.

Text works, which is what a text-keyed VLOOKUP or MATCH needs:

model.runRaw({ 'Sheet1!B1': 'Yes' }, ['Sheet1!D1']);

Each result is { value, error }. error is an Excel error string such as "#DIV/0!", or null:

const cell = out.monthly_payment;
if (cell.error) console.warn(`Excel error: ${cell.error}`);
else console.log(cell.value);

Monte-Carlo sweeps

To vary inputs across many trials, prepare a sweep once and run it repeatedly. The engine recomputes only the cells between the inputs you vary and the outputs you watch, so cost scales with that path rather than with the workbook:

const sweep = model.prepare(['loan_amount', 'rate'], ['monthly_payment']);

const out = sweep.run([
  [200_000, 0.05],
  [250_000, 0.06],
  [300_000, 0.07],
]);

out.column('monthly_payment');       // Float64Array, one value per trial
out.at(0, 'monthly_payment');        // one trial, one output

For large sweeps pass a flat scenario-major Float64Array and skip building rows:

const trials = 100_000;
const values = new Float64Array(trials * 2);
// fill: values[i * 2] = loanAmount, values[i * 2 + 1] = rate
const result = sweep.run(values);

Sweeps are numeric — every value is a number in both directions. Text overrides are not yet supported here; use run for those.

The batch wire format carries f64s and nothing else, so a trial whose watched output is an Excel error comes back as NaN in column() and at(). Excel has no NaN of its own, so a NaN is always an error and never an answer — check for it before averaging a column, and re-run that scenario through model.run to get the Excel error string.

Which cells a sweep may touch is narrower than the manifest: model.simInfo() reports i (varyable inputs), o (watchable outputs) and x (intermediates), each entry { a: address, n: blob cell index, b?: baseline }, plus the counts ic/oc/xc/tc and f (cells the VM does not cover, excluded from selection). Non-numeric and uncovered inputs are absent, so simInfo().ic can be well below manifest().input_count.

Sweeps are also deterministic. Workbooks whose results depend on RAND or RANDBETWEEN resampling per trial are not supported by this path.

Loading several models

Each model gets its own WebAssembly instance, so models are independent and safe to hold at the same time. Compile the engine once to avoid repeating that work:

import { readFile } from 'node:fs/promises';
import { loadModel } from '@xplo/runtime';

const engine = await WebAssembly.compile(await readFile('./model-bundle/model.wasm'));
const pricing = await loadModel({ wasm: engine, blob: './pricing.xvm' });
const risk    = await loadModel({ wasm: engine, blob: './risk.xvm' });

A fresh instance per model is required, not incidental — the program and the string interner are module-global — so every loadModel/loadBundle builds one. There is no way, and no need, to rebind an existing instance to another model.

When things fail

The client prefers a clear error over a plausible number:

Situation	What happens
Unknown name	Throws, and says to pass a cell address
Retired or unreviewed name	Throws, and says which
Two names pointing at the same cell	Throws rather than letting one silently win
A cell the engine cannot evaluate	Throws — never a `null` that looks like an answer
`interface.json` that does not match the model	Fails to load, rather than mislabelling cells
A slim bundle with no cached engine	Throws, naming `XPLO_RUNTIME_WASM`
`null`, `NaN` or a non-numeric value in a sweep	Throws rather than running a scenario you did not ask for

On a bundle with no confirmed labels, a name is not "unknown" — it is treated as a cell address, and you get no input/overridable cell at address loan_amount from the engine instead. Check model.namedInputs() first.

Running natively (the `native` target)

By default this client runs your model in process on WebAssembly. On Node, a full bundle also ships bin/vmrun, and you can run the model on that native binary instead — the same VM engine, a different execution target:

const model = await loadBundle('./model-bundle', { target: 'native' });
// model.run / model.runRaw / model.prepare stay synchronous, exactly as before.

WASM stays the default, and the two targets never fall back to one another — you choose explicitly, because they can differ in the last bits (see the next section). The native target is Node only: in the browser it throws immediately, and because every node:* import stays dynamic, browser bundling of the WebAssembly path is unaffected. Pass nativeBinary to point at a specific vmrun (handy in development, or to run a slim bundle, which ships no binary). Two things to know before you switch:

It is a downloaded executable. The native target runs bin/vmrun from the bundle, which is not sandboxed the way WebAssembly is — use only bundles from a source you trust.
It spawns a process per call. Each scalar run re-reads plan.xvm, so a loop of single runs can be slower end-to-end than in-process WASM even though native arithmetic is faster; a Monte-Carlo sweep pays that cost once for the whole batch.

How closely the engines agree

Every WebAssembly host runs the identical vmruntime.wasm: this client, the other three Local Runtime Clients, the browser calculator, and the bundle's own loader.mjs return bit-identical f64 values for the same model and inputs. That part of "the same everywhere" is exact, and it is checked mechanically for every client on every bundle.

The native vmrun CLI (and the hosted service, which runs the same binary) is a separate compilation of the same source, so it can differ in the last bits. On a 722-output finance workbook, 687 outputs matched the native oracle bit-for-bit, 34 differed by 1–2 ULP — the documented libm transcendental gap — and one cell differed materially: a near-total cancellation where native keeps a residue of 1.8189894035458565e-12 and WebAssembly returns exactly 0. That last one is an open engine bug, not a client bug, and it is the same in all four languages.

So: reconcile a client number against another WebAssembly surface and expect the bits to match; reconcile it against the native CLI or the hosted API and expect agreement to a few ULP, with cancellation-heavy cells as the known exception.

API reference

Member	Description
`loadBundle(dir, wasmOverride?)`	Load a model from a bundle directory (Node). `wasmOverride` is a path, bytes, or a compiled `WebAssembly.Module`
`loadBundle(dir, { target: 'native', nativeBinary? })`	Load on the `wasm` (default) or `native` vmrun target (Node only)
`loadModel({ wasm, blob, interface?, skipIdentityCheck? })`	Load from paths, bytes, or a compiled module
`model.run(inputs?, outputs?, options?)`	Run using names, with address fallbacks
`model.runRaw(inputs?, outputs?)`	Run using cell addresses only
`RunOptions { rawInputs, rawOutputs, allNamedOutputs, allNamedInputs }`	Mixed and bulk selectors
`model.manifest()`	Typed input/output contract
`model.namedInputs()` / `model.namedOutputs()`	Canonical names callable today
`model.interfaceLabels()` / `model.interfaceRevision`	Aliases, labels, review status, revision
`model.simInfo()`	Cells a sweep may vary or watch, with blob indices
`model.prepare(inputs, outputs)`	Build a reusable sweep
`sweep.run(scenarios, scenarioCount?)`	Run trials; returns a `BatchResult`
`result.column(output)` / `result.at(trial, output)`	Read sweep results (`NaN` = errored trial)