axorum-sandbox

The Axorum sandbox for Python: a world's agent plane served on 127.0.0.1, a clock that moves only when the test moves it, and the ledger to assert on. The wheel carries the axorum-sandbox binary; the axorum_sandbox module runs it.

pip install axorum-sandbox axorum-client

There is a wheel for Linux on x64 and arm64 (any libc), macOS on x64 and arm64, and Windows on x64.

An agent's test

from axorum import Agent, Amount, AxorumClient, Payment
from axorum_sandbox import Sandbox

BUYER = "agent://example.com/agent/buyer_01h455vb4pex5vsknk084sn02q"


def test_the_agent_stops_paying_a_suspended_vendor(tmp_path):
    with Sandbox.starter("agent-payments", tmp_path) as sandbox:
        # The agent's own client, unchanged but for where its requests go.
        axorum = AxorumClient(sandbox.url)
        agent = Agent(BUYER, lambda: sandbox.token(BUYER))
        pay = lambda minor, payee: axorum.authorize(agent, Payment.new(Amount(minor, "USD"), payee))

        assert pay(10_000, "api.anthropic.com").allowed
        sandbox.advance("7d")  # the vendor review suspends Anthropic
        assert not pay(100, "api.anthropic.com").allowed
        print(sandbox.report("exceptions")["text"])

A token lives a day of the sandbox's clock, so an agent that outlives a move of the clock takes a token source, Agent(uri, lambda: sandbox.token(uri)), rather than one token. A run reads no clock and no random source: one world and one seed give one run, on every machine.

Starter worlds

starters() lists them, new(starter, directory) writes one's world and policy to disk, and Sandbox.starter(name, directory) writes and serves it. The package's examples/ directory in the source repository has a test for each.

Checking a policy

check(policy, *, world=None, deny_warnings=False) compiles a policy file offline as axorum policy check does and, with a world file, judges it against that world: the currencies it declares, the mandates it opens and the agents it binds. It answers the verdict document, with the id each mandate and party name derives to and every warning by code, and raises SandboxError when the policy does not compile, the world cannot run it, or deny_warnings refuses a warning.

from axorum_sandbox import check

checked = check("spending-mandate.axp", world="spending-mandate.world.yaml")
assert checked["warnings"] == [], checked["warnings"]

What a run offers

A refusal raises SandboxError, with the status and code the sandbox answered, and its body. AXORUM_SANDBOX_BIN names a binary to run in place of the packaged one, such as one cargo build -p axorum-sandbox-cli built.

The same binary is the axorum-sandbox command: axorum-sandbox serve, run (replays saved scenarios in CI), new, inject, policy, save-run, token and pull. With AXORUM_SANDBOX_SINK and AXORUM_SANDBOX_TOKEN set from the console, axorum-sandbox serve --console-events serves the world attached to the sandbox there and reports each run back.