Python client

Run a prepared workbook inside your own Python 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 the client library itself, so the fastest path to your own number installs no xplo package at all.

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

pip install -r examples/python/requirements.txt && python3 examples/python/run.py

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

lookup_total = 27
total = 4

examples/python/run.py was generated from the bundle's own manifest.json and interface.json, so its inputs and outputs are already your cells. Edit the values at the top and re-run. examples/README.md lists the equivalent one-liner for the CLI, Node, Go, and Java.

Nothing from xplo is downloaded. The client library is vendored at examples/python/xplo/, and requirements.txt pulls exactly one third-party package: wasmtime, the WebAssembly engine (prebuilt wheels — no compiler).

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 a notebook, a job, or a service	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

pip install xplo

Not on PyPI yet. pip install xplo fails today — the project has not been published to any public index. 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. Take the copy inside your bundle. examples/python/xplo/ is the complete library. Copy that directory into your project, or add it to sys.path the way the generated example does, and pip install wasmtime. Nothing else is needed.

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

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        # unpacks ./python
pip install ./python

The token is an xplo_ API token, the same one the Runtime API uses. Create or manage it in API Tokens. The zip is source only — pip still fetches the wasmtime wheel from PyPI.

3. Install from a checkout of the xplo repository, if you have one: pip install /path/to/explo/clients/python.

Requires Python 3.10+. The engine ships as prebuilt wheels, so there is no compiler step at install time.

Quickstart

Point the client at the unzipped bundle folder:

import xplo

model = xplo.load_bundle("./model-bundle")

print(model.manifest())        # the typed input/output contract
print(model.named_inputs())    # names you can set
print(model.named_outputs())   # names you can read

out = model.run({"loan_amount": 200_000}, ["monthly_payment"])
print(out["monthly_payment"].value)

Names exist only once labels are confirmed on the workbook, and Naming + Labelling is optional. If model.named_inputs() is an empty list, this bundle has no names yet — use run_raw with addresses (model.run_raw({"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:

rt = xplo.Runtime.from_file("model.wasm")
model = rt.load(plan_xvm_bytes, interface_json)   # interface optional

interface accepts whatever spelling of interface.json you happen to have: a parsed dict, the file's text or bytes, a path to it, or an xplo.SemanticInterface. Passing nothing loads the model with cell addresses only.

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), 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 bin/vmrun (≈20 KB instead of ≈5.7 MB). It still runs, because the interpreter is identical for every model and the client caches it once per machine. Every client resolves the engine in this order:

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:

XploError: 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.run_raw({"Loan!B1": 200_000}, ["Loan!B8"])   # skip name resolution entirely

Mix them when a cell has no name yet:

from xplo import RunOptions

model.run(
    {"loan_amount": 200_000},
    ["monthly_payment"],
    RunOptions(raw_inputs={"Loan!C7": 0.02}, raw_outputs=["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. all_named_outputs returns each currently named one, and all_named_inputs echoes the inputs back:

model.run({"loan_amount": 200_000}, None, RunOptions(all_named_outputs=True))

named_inputs() and named_outputs() list canonical names only. To see aliases, review status, and long labels, read model.interface_labels().

Values

Inputs accept numbers, bool, str, and None. Whole numbers are widened for you, so 200_000 is fine — but an integer too large for exact floating-point (beyond 2^53) is refused rather than silently rounded, because Excel numbers are 64-bit floats.

None means leave that cell at its compiled baseline — it is not a blank-cell override, and it is indistinguishable from omitting the key. Pass "" if you want an empty string in the cell.

True and False stay boolean rather than becoming 1 and 0, so IF(A1=TRUE, …) behaves the way it does in Excel.

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

model.run_raw({"Sheet1!B1": "Yes"}, ["Sheet1!D1"])

Each result is a CellResult with .value and .error. .error is an Excel error string such as "#DIV/0!", or None:

cell = out["monthly_payment"]
if cell.error:
    print(f"Excel error: {cell.error}")
else:
    print(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:

sweep = model.prepare(["loan_amount", "rate"], ["monthly_payment"])

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

out.column("monthly_payment")      # one value per trial
out.at(0, "monthly_payment")       # one trial, one output

This pairs naturally with NumPy for the sampling and the statistics:

import numpy as np

trials = 100_000
samples = np.column_stack([
    np.random.normal(200_000, 25_000, trials),
    np.random.normal(0.05, 0.01, trials),
])
result = sweep.run(samples.ravel().tolist(), trials)
payments = np.array(result.column("monthly_payment"))
print(payments.mean(), np.percentile(payments, [5, 95]))

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. column() and at() refuse to hand you that NaN — they raise and name the failing trials, because one NaN would silently poison a mean() over 100,000 of them. column_raw() / at_raw() return the NaNs if you want them, result.errors() lists every failing (trial, output), and result.has_errors() is the cheap check. Re-run that one scenario through model.run to get the Excel error string.

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:

rt = xplo.Runtime.from_file("model.wasm")
pricing = rt.load_bundle("./pricing-bundle")
risk = rt.load_bundle("./risk-bundle")

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

When things fail

Almost every failure raises xplo.XploError, and the client prefers a clear error over a plausible number:

Situation	What happens
Unknown name	Raises, and says to pass a cell address
Retired or unreviewed name	Raises, and says which
Two names pointing at the same cell	Raises rather than letting one silently win
A cell the engine cannot evaluate	Raises — never a `None` 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	Raises, naming `XPLO_RUNTIME_WASM`
An integer beyond exact float range	Raises rather than rounding

Two exceptions are worth knowing: a wrong bundle path surfaces the underlying FileNotFoundError, and a batch built from a 2-D NumPy array raises TypeError from NumPy itself (flatten with .ravel().tolist() first).

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.named_inputs() first.

Running natively (the `native` target)

By default this client runs your model in process on vmruntime.wasm. 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:

model = xplo.load_bundle("./model-bundle", target="native")
# run, run_raw, prepare and every result reader work 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). Pass native_binary="/path/to/vmrun" to point at a specific binary (handy in development, or to run a slim bundle, which ships no binary and otherwise fails the native target with an actionable message). 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
`xplo.load_bundle(dir)`	Load a model from a bundle directory
`xplo.load_bundle(dir, target="native", native_binary=None)`	Load on the `wasm` (default) or `native` vmrun target
`xplo.Runtime.from_file(path)`	Compile the engine once
`rt.load(blob, interface=None)` / `rt.load_bundle(dir)`	Instantiate a model
`xplo.SemanticInterface.from_json(dict)`	Parse an `interface.json` document explicitly
`model.run(inputs=None, outputs=None, options=None)`	Run using names, with address fallbacks
`model.run_raw(inputs=None, outputs=None)`	Run using cell addresses only
`RunOptions(raw_inputs, raw_outputs, all_named_outputs, all_named_inputs)`	Mixed and bulk selectors
`model.manifest()`	Typed input/output contract
`model.named_inputs()` / `model.named_outputs()`	Canonical names callable today
`model.interface_labels()` / `model.interface_revision`	Aliases, labels, review status, revision
`model.sim_info()`	Cells a sweep may vary or watch
`model.prepare(inputs, outputs)`	Build a reusable sweep
`sweep.run(scenarios, scenario_count=None)`	Run trials; returns a `BatchResult`
`result.column(output)` / `result.at(trial, output)`	Read sweep results; raise on an errored trial
`result.column_raw(...)` / `result.at_raw(...)`	The same values with errored trials as `nan`
`result.errors()` / `result.has_errors()`	Trials whose output was an Excel error
`xplo.ENV_RUNTIME_WASM` / `xplo.ENV_RUNTIME_CACHE`	The engine-resolution environment variables