Metadata-Version: 2.5
Name: firedrill-cloud
Version: 0.1.10
Summary: Firedrill Python SDK — authenticated client for managed test worlds. Your agent stays in your runner.
Project-URL: Homepage, https://firedrill.run
Project-URL: Documentation, https://docs.firedrill.run/sdk/python
Project-URL: Repository, https://github.com/firedrill-tools/firedrill-sdk-python
Author: Reload Tech Inc.
License-Expression: Apache-2.0
License-File: LICENSE
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: keyring<26,>=25
Requires-Dist: pydantic>=2
Provides-Extra: aiohttp
Requires-Dist: httpx-aiohttp>=0.2.0; extra == 'aiohttp'
Provides-Extra: dev
Requires-Dist: build>=1.2; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: twine>=6; extra == 'dev'
Description-Content-Type: text/markdown

# Firedrill Python SDK and CLI

Firedrill gives your agent stateful synthetic Tools to work against, so you can
simulate tasks and check what actually changed. Tools run in Firedrill. Your agent,
application and model credentials stay in your own runner.

[Documentation](https://docs.firedrill.run/) · [Detailed guide](USER_GUIDE.md) ·
[Browser testing](CUSTOMER_BROWSER.md) · [API reference](https://docs.firedrill.run/api-reference/overview)

## Install

```sh
python -m pip install firedrill-cloud
firedrill init
```

Requires Python 3.10 or later. The package includes the `firedrill` CLI; Node is not required. `python -m firedrill_cloud` invokes the same client if another installation owns the command.

## Choose Tools

In an interactive terminal, `init` guides you through sign-in, project selection,
the Tool library and starting data. Then choose how to use them:

- **Use normally:** get a reusable Tool environment and connect your existing agent.
- **Automated tests:** save Tools and data, then add tasks and checks. Each independent
  case gets isolated Tool state when you run it.

Neither choice uploads or launches your agent. Add more Tools later:

```sh
firedrill library list
firedrill tools add --tool LIBRARY_ID --initial-state empty --use reusable
```

Use an actual library ID; repeat `--tool` for more Tools. Choose `starter` for
available synthetic starting data. The command prints readiness and connection
links. Acceptance is not readiness: `tools setup wait --setup ID` observes it.

## Connect your agent

Open the connection link for a ready reusable setup. Select the identity your
agent should use, then copy its scoped HTTP or MCP connection. Change your test
configuration or endpoint variables, not production agent logic. Only use
interfaces supported by the selected Tool.

Use Tools normally, inspect data, reset to starting state, or save tests.
Reusable environments keep evolving state; independent automated cases do not.
More than one named copy of the same Tool is supported.

Starting data can also be saved as versioned datasets and reused per Tool copy
or scenario. See [the detailed guide](USER_GUIDE.md#save-and-reuse-starting-data)
for selection and reset; saving data does not change a running connection.

## Run saved tests

From the setup's **Tests** page, save tasks, targets and checks. Create a separate
`firedrill.config.json` in your agent project:

```json
{
  "schemaVersion": 1,
  "drillIds": ["YOUR_SAVED_DRILL_ID"],
  "targets": {
    "YOUR_SAVED_TARGET_ID": {
      "command": "python",
      "arguments": ["tests/run_agent.py"],
      "bindings": ["mcp"]
    }
  }
}
```

Replace both IDs with actual saved test IDs and use your own executable.
The target receives task JSON on stdin and a scoped Tool connection in its
environment. It invokes your existing agent and writes a TargetResult JSON to
stdout; logs go to stderr. The [guide](USER_GUIDE.md) covers this test adapter,
endpoint-variable mapping and SDK callback alternatives.

```sh
firedrill run --setup YOUR_READY_SETUP_ID
```

The command prints the Results link and succeeds only when the simulation passes.
Agent completion or a browser check passing cannot override a failed Tool-state
check. Parallel cases and continuing sequences use the same Simulator and Results;
continuing steps deliberately retain evolving state.

## Browser tests and evidence

Use your browser driver with `customerBrowserTarget` (TypeScript) or
`customer_browser_target` / `customer_browser_target_async` (Python). The adapter
provides the exact case's connection, declared UI observations and optional logs,
screenshots, files and recordings. Your browser and app stay in your runner.
See [Browser testing](CUSTOMER_BROWSER.md) for preparation, cleanup and captures.

Results distinguish Firedrill's Tool-state checks from your runner's observations.
Evidence and captures are optional; choose what to record.

## Project API keys

Create or revoke a project key in **Settings → Credentials** in the web app, or
from the CLI after `firedrill login`:

```sh
firedrill credentials create --project "$PROJECT" --name "CI" --kind service --access run
firedrill credentials list --project "$PROJECT"
firedrill credentials revoke --project "$PROJECT" --id cred_... --confirm cred_...
```

Creation shows the key once. Store it in your CI secret manager; never put it in
the repository. Use `--json` for non-interactive creation. Revocation takes
effect immediately and does not change completed results.

## CI and coding agents

Use the same commands and configuration in CI. Put `FIREDRILL_CREDENTIAL` in its
secret manager and pass the project explicitly:

```sh
firedrill init --project "$PROJECT" --tool "$LIBRARY_ID" \
  --initial-state empty --use automated --idempotency-key "$SETUP_KEY" --wait --json
firedrill run --project "$PROJECT" --setup "$SETUP_ID" --json
```

Use the ready setup ID returned by `init`. CI never prompts or opens a browser.
Run tests on pull requests, pushes, schedules or manually.
The [guide](USER_GUIDE.md) covers the optional CI client and GitHub integration.

Interactive operations also have explicit arguments and JSON output for coding
agents. Help needs no login: `firedrill init --help`.

## Recovery and advanced controls

Interrupted setups or runs print a recovery file. Resume the exact request instead
of starting another one; project, Tool versions and request key stay unchanged.
Local files under `.firedrill/cloud/` are private and Git-ignored. Credentials
belong in the OS keychain or your secret manager.

The [detailed guide](USER_GUIDE.md) covers SDK callbacks, custom Tool publication,
scenario overrides, time advancement, full/selective resets, snapshots,
cancellation, history, evidence, concurrency and exact-request recovery.
