Metadata-Version: 2.5
Name: stateweave-sdk
Version: 0.3.0
Summary: Run your own AI agent on StateWeave: environments, tests, data of your own, and graded runs
Project-URL: Homepage, https://stateweave.net
Project-URL: Documentation, https://stateweave.net/docs/
Author-email: StateWeave <mikewei@stateweave.net>
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: agent evaluation,ai agents,digital twin,mcp,salesforce,shopify,slack,testing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Testing
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# stateweave-sdk

Run your own AI agent on [StateWeave](https://stateweave.net). StateWeave gives you working copies of the apps your
agent uses (Slack, Gmail, Google Calendar, Sheets and Drive, Salesforce, Shopify, Zendesk), filled with a company's
data, and tests with answer keys.
Your agent stays on your machine and connects to the apps over their real APIs or MCP. Every run is graded and shown,
call by call, on your StateWeave page.

```bash
pip install stateweave-sdk
```

This installs the `sw` command and the `stateweave` Python module. It uses only the standard library and needs
Python 3.10 or later. The full documentation is at [stateweave.net/docs](https://stateweave.net/docs/).

## Five minutes

```bash
sw login --url https://<you>.app.stateweave.net       # asks for an API key: make one under Connect an agent
sw env ls                                              # your scenarios
sw task ls                                             # the tests you can run
sw run t-3fa2c1 --agent my-agent@0.1 -- python my_agent.py
```

`sw run` starts a run, runs your command with the run in its environment, then grades it:

| variable | what it holds |
|---|---|
| `STATEWEAVE_PROMPT` | what to ask your agent |
| `STATEWEAVE_KIND` | `answer` (it finds something out) or `action` (it changes the apps) |
| `STATEWEAVE_ANSWER_FORMAT` | for an answer task, the JSON value to answer with |
| `STATEWEAVE_RUN_FILE` | the whole run as JSON: each app's `base_url`, `endpoints`, `credentials` and MCP server |
| `STATEWEAVE_MCP_CONFIG` | `{"mcpServers": {...}}`, for any MCP client |
| `STATEWEAVE_ANSWER_FILE` | where your agent writes its answer (JSON, or plain text); nothing for an action task |
| `STATEWEAVE_RUN` | the run's id |

The run is graded when your command exits, whatever its exit code. Ctrl-C gives the run up instead. `sw run` exits
0 when the run passed.

With Claude Code as the agent, on a test of Slack and Gmail:

```bash
sw run t-3fa2c1 --agent claude-code -- sh -c 'claude -p "$STATEWEAVE_PROMPT" \
  --mcp-config "$STATEWEAVE_MCP_CONFIG" --strict-mcp-config --allowedTools "mcp__slack__*" "mcp__gmail__*"'
```

In print mode Claude Code refuses any tool nobody approved, so `--allowedTools` must name each app the test uses.
`--strict-mcp-config` keeps your own MCP servers out of the run. The
[MCP servers](https://stateweave.net/docs/mcp.html#claude-code) page has a script that works out the apps by itself
and hands in the answer for answer tasks.

Give each version of your agent its own `--agent` label. The Runs page compares the labels.

## Your own scenarios, tests and data

```bash
sw env new --apps gmail,zendesk --describe "A 40-person logistics software company after a carrier outage"
sw task new p-9c41d2 --request "Which enterprise customers were hit by last week's outage?"
sw task new p-9c41d2 --request "Refund #1042." --criteria "Only order #1042 is refunded, in full."
sw task new p-9c41d2 --suggest 5 --focus "refunds promised but never processed" --random-faults
sw task faults p-9c41d2
sw data kinds p-9c41d2
sw data add p-9c41d2 gmail email --from dana@northwind.example --subject "Credit?" --body-file mail.txt
sw task recheck p-9c41d2
```

- **Your own requests.** A request you write is kept word for word. StateWeave builds its answer key and checker,
  or tells you why the request can't be a test as written and suggests a rewording. `--criteria` says, in your words,
  what a right outcome must meet.
- **Faults.** Tests can inject the failures real APIs have: presets (`--faults`, listed by `sw task faults`) or
  random ones (`--random-faults`).
- **Your own data.** Added data joins the app's data as if the scenario had generated it. Only the scenario's
  people and contacts may appear in it.
- **Re-checking.** After you add data, that app's tests need a re-check before they run again.

## In Python

```python
import stateweave

with stateweave.start("t-3fa2c1", agent="my-agent@0.1") as run:
    answer = my_agent(run.prompt, run.apps)     # run.apps: each app's URLs, credentials and MCP server
    result = run.finish(answer)
print(result.passed, result.reasons, result.url)
```

`stateweave.Client` also has `projects()`, `create_project()`, `data()`, `add_data()`, `write_tests()`,
`suggest_tests()`, `faults()`, `fault_targets()`, `job()` and `recheck()`.

## Where the address and key come from

The first of these that is set wins:

1. `Client(url=..., api_key=...)`
2. `STATEWEAVE_URL` and `STATEWEAVE_API_KEY`
3. What `sw login` kept in `~/.config/stateweave/config.json`, which only you can read

To forget it: `sw logout`.
