Install the SDK

You normally don’t install the SDK yourself. The first Plurai command checks your project for it, and when it is missing it asks once and installs the exact version the plugin was tested with into the environment your agent runs in. This page is for installing it by hand, adding extras, and checking the install.

Requirements

Python 3.12 or 3.13, on macOS, Linux or Windows.
On Windows, an agent driven through Claude’s command-line tool (claude_agent_sdk) is not supported. Run it on macOS, Linux or WSL.

The SDK is published on PyPI as plurai-simulation-sdk. The import name and the command lines are plurai.

What the plugin installs

When no usable SDK is found, the plugin installs it into your project’s environment. It looks for that environment in this order:

The activated virtual environment, or the active conda environment (never conda’s base).
A virtual environment in the project folder.
The environment poetry (poetry.lock) or pipenv (Pipfile) names.

An environment activated for another project is skipped when your project has a venv of its own. When the plugin finds no environment for a Python project, it asks whether to use one you activate or to create .venv. A new .venv lacks your agent’s dependencies. It never creates .venv without asking, and it stops when the environment’s Python is older than 3.12.

Install it yourself

Every plugin release is tested with one SDK version. Print the exact install line for yours:

python3 <plugin root>/scripts/resolve_plurai.py --install-line

It prints, for example:

pip install "plurai-simulation-sdk==1.0.0"

Run it in your agent’s environment, with the installer that matches your project:

pip install "plurai-simulation-sdk==1.0.0"

.venv/bin/pip install "plurai-simulation-sdk==1.0.0"

uv pip install "plurai-simulation-sdk==1.0.0"

uv tool install "plurai-simulation-sdk==1.0.0"

You can also ask your coding agent: “Install the Plurai SDK into my agent’s venv.”

Required version

The plugin runs only the SDK version it was tested with. When the SDK in your environment is a different version, the plugin stops before a Run, with one line naming the version it found, the version it needs, and the install command. The plugin only runs a plurai that an installed plurai-simulation-sdk distribution provides: a hand-built wrapper script is not handed your login.

Extras

The base install is small. Install an extra only when you use it, with the same version pin, for example "plurai-simulation-sdk[langfuse]==1.0.0". The plugin installs the extras a command needs when it needs them.

Extra	Adds	Install it when
`readers`	Document readers (`.docx`, `.pptx`, `.xlsx`, `.pdf`)	Your harness previews documents your agent produces.
`extract`	Client-side corpus extraction	You build a knowledge base with `plurai ingest-corpus`.
`extract-pdf`, `extract-http`, `extract-vertex`, `extract-bigquery`, `extract-redshift`, `extract-azure-sql`, `extract-databricks`, `extract-snowflake`, `extract-bedrock`	The driver for one corpus source kind	Your knowledge base reads from that source.
`langsmith`	`langsmith`	You read traces from, or record Runs to, LangSmith.
`langfuse`	`langfuse` (4.x)	You read traces from, or record Runs to, Langfuse.
`arize`	`arize`, `arize-otel`, OpenInference conventions	You record Runs to Arize.
`braintrust`	`braintrust`	You record Runs to Braintrust.
`anonymize`	Presidio analyzer and anonymizer	Your workspace’s anonymization posture is `anonymized` (`anonymize: true` in `plurai.config.yaml`).
`anonymize-binary`	Presidio image redactor, `pdf2image`, `Pillow`	Your posture is `anonymized` and you upload images or PDFs.

plurai login, plurai --version and plurai capabilities need none of the extras.

Anonymization extras

The anonymize extra also needs a spaCy English model, which is not a Python dependency:

python -m spacy download en_core_web_lg   # en_core_web_md or en_core_web_sm also work

The anonymize-binary extra also needs two system programs on PATH: Tesseract (brew install tesseract, or tesseract-ocr) and Poppler (brew install poppler, or poppler-utils). Under the anonymized posture, ingestion fails closed: without the extra, the model or the system programs, it refuses to run rather than upload unscrubbed data. A workspace on the default raw posture needs none of them. See Data and privacy.

Verify the install

plurai --version          # plurai 1.0.0
plurai --identity         # which build is running (commit or content hash)
plurai capabilities       # this build's commands and features, as JSON
plurai login --status     # the backend, organization and user you are signed in as

plurai capabilities is what the plugin reads. Its commands list is read off the live CLI, and its features name behavior that command names do not reveal, such as export-dir-traces. plurai login --status never prints your key.

Agent and runner in different environments

The runner (plurai-run-simulation) and your agent can use different virtual environments, for example when your agent pins dependencies the runner’s environment cannot share. The agent runs in a child interpreter: the runner’s own Python by default, or the one PLURAI_CHILD_PYTHON names:

export PLURAI_CHILD_PYTHON=/path/to/agent-venv/bin/python

The agent’s environment must have the SDK installed too, because simulate.py imports plurai.

Upgrade

When you update the plugin, the next Plurai command finds the SDK at the old version and offers to install the new one. To do it yourself, run the line --install-line prints. Check the changelog for breaking changes first.

Next steps

Run simulations

Use plurai-run-simulation directly.

CLI reference

Every plurai command and flag.

Use the SDK

Reference

Requirements

What the plugin installs

Install it yourself

Required version

Extras

Anonymization extras

Verify the install

Agent and runner in different environments

Upgrade

Next steps

Run simulations

CLI reference

​Requirements

​What the plugin installs

​Install it yourself

​Required version

​Extras

​Anonymization extras

​Verify the install

​Agent and runner in different environments

​Upgrade

​Next steps

Run simulations

CLI reference

Requirements

What the plugin installs

Install it yourself

Required version

Extras

Anonymization extras

Verify the install

Agent and runner in different environments

Upgrade

Next steps