Python SDK - Plurai Simulation

The plurai SDK is the client side of Plurai Simulation. It runs your harness against the mock environment, drives each scenario turn by turn, and moves data to the Plurai backend after applying your anonymization posture locally. If you use the plugin, you already use the SDK: every flow calls it from your agent’s virtual environment. You don’t install it yourself: the first Plurai command installs the version the plugin was tested with into your project’s environment, after asking once. You never call it by hand for normal use.

What the SDK contains

Part	What it does
`plurai-run-simulation`	The runner. Plays each scenario of a suite against your harness and writes per-scenario artifacts. See Run simulations.
`plurai`	Sign-in (`login`, `logout`), local data handling and backend reads: `ingest-*` uploads, `stash-doc`, `fetch`, `job`, `backend`, `capabilities`. See CLI reference.
`plurai-scan-contract`	Checks the scan’s conclusions against your own files, on your machine, before generation spends anything. See CLI reference.
The `plurai` Python package	The API your `simulate.py` imports: `@plurai.mock`, `plurai.MockToolNode`, `plurai.HarnessFault` and more. See Write a harness and the API reference.
`plurai.observability`	Records Runs to LangSmith, Langfuse, Arize or Braintrust. See Trace sources.

When to use the SDK directly

Use the SDK on its own when:

You run the suite in CI. Call plurai-run-simulation with your scenario set and eval set ids, and fail the build on the result. See Run in CI.
You maintain your own harness. Write or edit simulate.py against the harness contract.
You script data delivery. Export traces or a corpus with plurai ingest-*, preview it with --plan-only, and check the audit log, without a coding agent in the loop.

The SDK uses the login the plugin saved. To sign in on its own, run:

plurai login            # opens your browser: sign in or sign up, pick your organization, approve
plurai login --status   # the backend, organization, user, and the key's name and expiry; never the key
plurai logout           # revokes the saved key and removes it from this machine

The SDK creates its own key and saves it in ~/.plurai/credentials.json. The key is never shown. For CI or a machine without a browser, export a key created in the Plurai dashboard, with the backend address Plurai gives you, instead:

export PLURAI_URL=https://<your-backend>
export PLURAI_TOKEN=<key from the dashboard>

The two variables are one pair, and they win over the saved login. A non-loopback backend with no key is refused before any request. Keep a dashboard key in your environment or secret store, never in code or logs. See Environment variables.

Stability contract

These stay compatible within a major version:

the names in plurai.__all__ and in plurai.observability.__all__,
the flags of the three command lines: plurai, plurai-run-simulation and plurai-scan-contract,
the exit codes,
the credentials file, ~/.plurai/credentials.json,
the PLURAI_* environment variable names,
the keys plurai capabilities prints.

Everything else is an implementation detail and may change in any release, including the individual plurai.observability submodules and the run files the plugin reads (run_summary.json, .last_run). The API reference lists exactly the supported names.

Versions and updates

The plugin pins the exact SDK version it was tested with. To move to a new SDK version, update the plugin. Don’t upgrade the SDK on its own unless a command asks you to.

Get help

Open an issue on the SDK’s GitHub page and paste the output of:

plurai diagnose

It lists the SDK version, installed extras, Python and OS versions, whether a login is present, the backend’s address and the latest Run’s name and error ids. It never includes a token or any file from your project. If the install itself failed, paste the output of pip install -v plurai-simulation-sdk, python --version and pip --version instead. Never paste ~/.plurai/credentials.json or a token.

Next steps

Install the SDK

Installed for you by the plugin, or from PyPI.

Run simulations

Use plurai-run-simulation directly.

​What the SDK contains

​When to use the SDK directly

​Sign in

​Stability contract

​Versions and updates

​Get help

​Next steps