From e00f7b6af17983ed115b9e1c6a308beade33a9e1 Mon Sep 17 00:00:00 2001 From: scosman Date: Thu, 8 Oct 2026 21:06:21 +0000 Subject: [PATCH 1/2] docs: add Stripe World to the environment catalog Add a docs page for Stripe World, a stateful copy of Stripe's Billing and Payments API that runs as an OpenEnv environment and is maintained outside this repository (HF Space scosman/stripe_world, source Kiln-AI/stripe_world). - docs/source/environments/stripe_world.md: what it models, how episodes are graded from the state() change log, an AutoEnv.from_hub(..., skip_install=True) quick start, and running the server locally - docs/source/environments.md: card under Community Environments - docs/source/_toctree.yml: sidebar entry under Environments Docs only; nothing is added under envs/. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Uxf3k6Fcyfm5Jmt8d4HDfA --- docs/source/_toctree.yml | 2 + docs/source/environments.md | 8 +++ docs/source/environments/stripe_world.md | 90 ++++++++++++++++++++++++ 3 files changed, 100 insertions(+) create mode 100644 docs/source/environments/stripe_world.md diff --git a/docs/source/_toctree.yml b/docs/source/_toctree.yml index 3c751dd395..6fa3c611a7 100644 --- a/docs/source/_toctree.yml +++ b/docs/source/_toctree.yml @@ -167,6 +167,8 @@ title: Pi (deprecated) - local: environments/sophistry_bench_sprint title: Sophistry Bench Sprint + - local: environments/stripe_world + title: Stripe World title: Environments - isExpanded: false sections: diff --git a/docs/source/environments.md b/docs/source/environments.md index 4f4a60a827..7be215facb 100644 --- a/docs/source/environments.md +++ b/docs/source/environments.md @@ -334,5 +334,13 @@ The OpenEnv community has built a catalog of ready-to-run environments that cove 🤗 HF +
+
Stripe World
+

Stateful copy of Stripe's Billing and Payments API with Stripe's MCP tools, a private account per episode, and a row-level change log in the state for grading.

+
+ 📄 Docs + 🤗 HF +
+
diff --git a/docs/source/environments/stripe_world.md b/docs/source/environments/stripe_world.md new file mode 100644 index 0000000000..6c996f9f77 --- /dev/null +++ b/docs/source/environments/stripe_world.md @@ -0,0 +1,90 @@ +# Stripe World + +Stripe World is a stateful copy of Stripe's Billing and Payments API that runs as an OpenEnv +environment. Agents act through the same tools as Stripe's MCP server. Every connection gets its +own private Stripe account, which can start from a saved state, and every database row the episode +changed is returned by `state()` for grading. + +The environment is maintained outside this repository: + +- Hugging Face Space: [scosman/stripe_world](https://huggingface.co/spaces/scosman/stripe_world) +- Source: [Kiln-AI/stripe_world](https://github.com/Kiln-AI/stripe_world) + +It is built with [Seahaven](https://github.com/Kiln-AI/Seahaven). Stripe World is not affiliated +with Stripe. + +## What it models + +- **API surface:** 155 Stripe API operations across 24 tables, pinned to Stripe API version + `2026-08-26.dahlia`. Object shapes follow Stripe's OpenAPI spec. +- **Resources:** customers, payment methods, products, prices, coupons, promotion codes, tax rates, + payment intents, charges, refunds, disputes, setup intents, balance and balance transactions, + payouts, subscriptions, subscription items and schedules, invoices, invoice items, credit notes, + customer balance transactions and events. +- **Billing behaviour:** subscription status transitions, trials and cancellation; invoices that + move from draft to open to paid, void or uncollectible; proration; dunning; credit notes; and a + balance ledger. Stripe's test cards and tokens (`tok_visa`, + `tok_visa_chargeDeclinedInsufficientFunds`, ...) succeed, decline and dispute as they do in + Stripe's test mode. +- **Agent tools:** 8 of the 10 tools on Stripe's MCP server: `list_available_accounts_or_orgs`, + `get_stripe_account_info`, `manage_stripe_accounts`, `stripe_analytics`, `stripe_api_read`, + `stripe_api_write`, `stripe_api_search` and `stripe_api_details`. + +Webhook delivery and the parts of Stripe outside Billing and Payments are not modelled. + +## Episodes and grading + +- `reset()` creates a fresh account. Pass `fixture` to start from a saved state (the repository + ships `empty`), `seed` to make ids and timestamps reproducible, and + `startup={"livemode": False}` for a test-mode account. +- `step()` takes `list_tools` and `call_tool` actions. +- The environment does not compute a reward. `state()` returns the change log of the episode + under `["state"]["db"]["log"]`: one entry per changed row, with its table, operation, and the + row before and after. Grade the episode from those rows. + +## Quick start + +Connect to the Space with OpenEnv's generic client. Only the `openenv` package is needed on the +client side: + +```python +from openenv import AutoEnv + +with AutoEnv.from_hub("scosman/stripe_world", skip_install=True) as env: + env.reset(seed=7, startup={"livemode": False}) + tools = env.step({"type": "list_tools"}).observation["tools"] + account = env.step( + {"type": "call_tool", "tool_name": "list_available_accounts_or_orgs", "arguments": {}} + ).observation["result"]["accounts"][0] + created = env.step( + { + "type": "call_tool", + "tool_name": "stripe_api_write", + "arguments": { + "stripe_api_operation_id": "PostCustomers", + "parameters": {"email": "jenny@example.com"}, + "stripe_context": account["stripe_context"], + "livemode": account["livemode"], + }, + } + ).observation + print(created["result"], env.state()) +``` + +Pass `skip_install=True`. Without it, `from_hub` tries to install the Space's repository as a +Python package, which fails for this environment. For a server you run yourself, add +`base_url="http://localhost:8000"`. + +## Running the server locally + +```bash +git clone https://github.com/Kiln-AI/stripe_world.git +cd stripe_world +uv sync +uv run --extra serve seahaven serve +``` + +The server listens on port 8000. Open `http://127.0.0.1:8000/console` to drive an instance by +hand. The [Stripe World README](https://github.com/Kiln-AI/stripe_world#readme) has +an async example with the typed `SeahavenClient` that runs and grades 100 episodes in parallel, +and shows how to save your own fixtures. From 32704e27719bfab0c5dd6618abd07b1de4b1805d Mon Sep 17 00:00:00 2001 From: scosman Date: Sat, 17 Oct 2026 14:20:38 +0000 Subject: [PATCH 2/2] docs: describe Stripe World's small_co and big_co fixtures Stripe World now ships three fixtures (Kiln-AI/stripe_world#16). Add a Fixtures section listing empty, small_co (Wrenfield Labs, 45 customers) and big_co (Ostrander Systems, about 380 customers), how to select one with reset(fixture=...), and that a fixture keeps the mode it was saved in. Scope the livemode note to resets without a fixture, link the fixtures guide, and update the table count to 25. Co-Authored-By: Claude Opus 5.5 Claude-Session: https://claude.ai/code/session_01Uxf3k6Fcyfm5Jmt8d4HDfA --- docs/source/environments/stripe_world.md | 28 ++++++++++++++++++++---- 1 file changed, 24 insertions(+), 4 deletions(-) diff --git a/docs/source/environments/stripe_world.md b/docs/source/environments/stripe_world.md index 6c996f9f77..a60c1d2405 100644 --- a/docs/source/environments/stripe_world.md +++ b/docs/source/environments/stripe_world.md @@ -15,7 +15,7 @@ with Stripe. ## What it models -- **API surface:** 155 Stripe API operations across 24 tables, pinned to Stripe API version +- **API surface:** 155 Stripe API operations across 25 tables, pinned to Stripe API version `2026-08-26.dahlia`. Object shapes follow Stripe's OpenAPI spec. - **Resources:** customers, payment methods, products, prices, coupons, promotion codes, tax rates, payment intents, charges, refunds, disputes, setup intents, balance and balance transactions, @@ -34,14 +34,34 @@ Webhook delivery and the parts of Stripe outside Billing and Payments are not mo ## Episodes and grading -- `reset()` creates a fresh account. Pass `fixture` to start from a saved state (the repository - ships `empty`), `seed` to make ids and timestamps reproducible, and - `startup={"livemode": False}` for a test-mode account. +- `reset()` creates a fresh account. Pass `fixture` to start from a saved state (see + [Fixtures](#fixtures)) and `seed` to make ids and timestamps reproducible. Without a fixture the + account is empty and in live mode; pass `startup={"livemode": False}` for a test-mode account. - `step()` takes `list_tools` and `call_tool` actions. - The environment does not compute a reward. `state()` returns the change log of the episode under `["state"]["db"]["log"]`: one entry per changed row, with its table, operation, and the row before and after. Grade the episode from those rows. +## Fixtures + +Stripe World ships three fixtures, all frozen at `2026-09-01T14:00:00Z`: + +- **`empty`:** an account with no history, in live mode. +- **`small_co`:** Wrenfield Labs, a two-person company selling booking and payment tools to + tutors, music teachers and coaches. A test-mode account with 45 hand-written customers, from a + private beta through a public launch, with renewals, a failed payment in dunning, refunds and a + dispute. +- **`big_co`:** Ostrander Systems, a company selling field-service software to HVAC, plumbing and + electrical contractors. A test-mode account with about 380 simulated business customers over 18 + months, with per-technician seat plans, annual contracts invoiced on terms, sales tax, dunning, + refunds, disputes and credit notes. Suited to tasks that need pagination, search and + aggregation. + +Select one with `env.reset(fixture="small_co", seed=7)`. A fixture opens in the mode it was saved +in, so leave out `startup={"livemode": ...}`: asking for the other mode is refused. +[docs/fixtures.md](https://github.com/Kiln-AI/stripe_world/blob/main/docs/fixtures.md) describes +each company's catalog and its scripted loose ends, with queries that find them. + ## Quick start Connect to the Space with OpenEnv's generic client. Only the `openenv` package is needed on the