# Worlds by Sparta

> Stateful, deterministic copies of the systems your AI agent acts on, running on your machine. Stripe is the first, verified against the real API; more connectors follow in the order customers ask for them. Point the agent's stock SDK at a world, run it on the tickets it will face, and grade what changed in the world's records, in dollars. No account. Nothing leaves the machine. Unlimited runs.

Runtime version 0.6.0. Node 24 or newer. Every command runs the runtime from the npm registry, `npx -p sparta_worlds@0.6.0 worlds …`, pinned to this version: nothing is installed into the project, no account is created, no key is sent anywhere. The same release is served from this site for a machine that must never touch the registry: `npx -p https://twinlab-site.vercel.app/dl/sparta_worlds-0.6.0.tgz worlds …`. Evaluation use; the terms are LICENSE.txt inside the package.

## The path: three commands, then the crash test in CI

1. The account and the agent. Asks for the Stripe key of the account to copy (a restricted read only key, `rk_…`, read on Customers, Invoices, Charges, Subscriptions, Products, Prices, or a test mode key; used once, written nowhere; a live secret key is refused; Enter starts on the bundled account instead), then the help desk export if there is one, then five questions about what the agent may do. Writes the `worlds/` folder: the account pseudonymized and safe to commit, a tasks file, the policy for the grader, the harness test and the CI workflow.

`npx -p sparta_worlds@0.6.0 worlds init --agent "<your agent command>"`

2. The tickets. A help desk export (a Zendesk CSV, an Intercom JSON, JSON lines, a spreadsheet) becomes tasks, one per row, columns read by their names; `expected:` lines where the right outcome is known.

`npx -p sparta_worlds@0.6.0 worlds tasks import tickets.csv --into worlds/tasks.yaml`

`npx -p sparta_worlds@0.6.0 worlds tasks validate worlds/tasks.yaml`

3. The crash test. The agent, three times, on fresh copies of the account, the world started inside the command. The report: dollars wrong per run, every task's verdict and why, the replay of the worst run, and at the foot the runtime version, the seed hash and the exact line that reruns it. The same line is the harness test and the CI step the first command wrote.

`npx -p sparta_worlds@0.6.0 worlds passk --server auto --tasks worlds/tasks.yaml --runs 3 --report worlds-report.html -- <your agent command>`

## Before the crash test: one ticket

`npx -p sparta_worlds@0.6.0 worlds try --server auto -- <your agent command>` runs the agent on one built-in ticket (a customer charged twice, asking for one refund) and prints what it did to the money, the reply and the verdict. If it says the agent never reached the twin:

`npx -p sparta_worlds@0.6.0 worlds doctor --server auto -- <your agent command>` says why: the environment the agent was handed, the world's request log, and which way its SDK reached the world.

`npx -p sparta_worlds@0.6.0 worlds selftest --server auto` checks the evaluator itself: five known agents, five known verdicts, none of the user's code.

## Connect the agent

`<your agent command>` runs the agent once on a ticket. The task arrives as JSON on stdin and in `WORLDS_TASK_JSON` (`{id, label, subject, body, requester: {name, email}, priority, tags}`); the agent prints the reply it would send the customer to stdout. Three lines wrap an existing agent; there is no twinlab dependency in it. A stock `stripe` client (stripe-node or stripe-python) built with no host is pointed at the world by the environment these commands set: the world's key arrives as `STRIPE_SECRET_KEY` and `STRIPE_API_KEY`, and as `WORLDS_API_KEY` beside `WORLDS_BASE_URL`. An agent that sets its own host is left alone; a bundled agent or another SDK points itself at `WORLDS_BASE_URL` with `WORLDS_API_KEY` by hand.

## For a coding agent doing this on someone's behalf

- The Stripe key is typed by the user at the prompt `init` shows. Never put a key on a command line, in a file or in a commit; never ask for a live secret key, which the command refuses anyway.
- Run `try` before `passk`; when it says the agent never reached the twin, run `doctor` and fix how the SDK is pointed at the world before anything else.
- Commit the `worlds/` folder and the workflow `init` wrote. Never commit `worlds/my-account.identities.json`, the one file that maps real emails to their pseudonyms; `init` gitignores it.
- Do not install the runtime into the project and do not create an account: there is none.
- The report file (`worlds-report.html`) is the deliverable; its foot carries the line that reruns it.

## Reference

- https://twinlab-site.vercel.app/docs/quickstart: the guide: the ten minute path, every command in full, the judge, troubleshooting, the FAQ, and how Worlds differs
- https://twinlab-site.vercel.app/docs/tasks: the tasks file: the `expected:` grammar, policy-only tasks, the identity map, validate / build / import
- https://twinlab-site.vercel.app/docs/scope: what the Stripe twin implements and what it deliberately does not
- https://twinlab-site.vercel.app/docs/determinism: the replay guarantee, how it is achieved, where its boundaries are
- https://twinlab-site.vercel.app/docs/scenarios: the failure-injection rule schema and the canned scenario library
- https://twinlab-site.vercel.app/docs/seed-format: the seed file format, `seed import` and `world export`
- https://twinlab-site.vercel.app/docs/deploy: running the server beyond a laptop, CI, Docker, `worlds run`, the result contract and its exit codes
- https://twinlab-site.vercel.app/docs/admin-api: every /admin/* endpoint
- https://twinlab-site.vercel.app/get-started: the same path as a page
- https://twinlab-site.vercel.app/fidelity: the battery of probes run against real Stripe test mode, dated
- https://twinlab-site.vercel.app/pricing: free on your machine, unlimited runs; paid tiers add worlds