> ## Documentation Index
> Fetch the complete documentation index at: https://docs.plurai.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Python SDK

> The plurai Python package: the runner, the harness API and the local data-handling CLIs that the plugin uses, and that you can use directly.

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](https://docs.plurai.ai/sdk/run-simulations.md). |
| `plurai` | Sign-in (`login`, `logout`), local data handling and backend reads: `ingest-*` uploads, `stash-doc`, `fetch`, `job`, `backend`, `capabilities`. See [CLI reference](https://docs.plurai.ai/sdk/cli.md). |
| `plurai-scan-contract` | Checks the scan's conclusions against your own files, on your machine, before generation spends anything. See [CLI reference](https://docs.plurai.ai/sdk/cli.md#plurai-scan-contract). |
| The `plurai` Python package | The API your `simulate.py` imports: `@plurai.mock`, `plurai.MockToolNode`, `plurai.HarnessFault` and more. See [Write a harness](https://docs.plurai.ai/sdk/write-a-harness.md) and the [API reference](https://docs.plurai.ai/sdk/api-reference.md). |
| `plurai.observability` | Records Runs to LangSmith, Langfuse, Arize or Braintrust. See [Trace sources](https://docs.plurai.ai/integrations/trace-sources.md#record-runs). |

## 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](https://docs.plurai.ai/guides/ci.md).
* **You maintain your own harness.** Write or edit `simulate.py` against the [harness contract](https://docs.plurai.ai/sdk/write-a-harness.md).
* **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.

## Sign in

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

```bash theme={null}
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:

```bash theme={null}
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](https://docs.plurai.ai/reference/environment-variables.md#connect-to-the-backend).

## 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](https://docs.plurai.ai/sdk/run-simulations.md#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](https://docs.plurai.ai/sdk/api-reference.md) 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](https://github.com/plurai-ai/plurai-simulation-sdk/issues) and paste the output of:

```bash theme={null}
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

> [card] [Install the SDK](https://docs.plurai.ai/sdk/install.md)
>
> Installed for you by the plugin, or from PyPI.

> [card] [Run simulations](https://docs.plurai.ai/sdk/run-simulations.md)
>
> Use `plurai-run-simulation` directly.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.