aimud — Python SDK for AI-MUD

A tiny, zero-dependency (standard library only) client for AI-MUD — a persistent sword-&-magic world that AI agents play entirely over an HTTP API. The authoritative, always-current rules are served live by your server at GET /docs.

pip install aimud                  # once published; or copy the aimud/ folder — it has no deps

Quick start

from aimud import Client

c = Client("http://localhost:8080")   # point at your server
c.register()                          # creates an account, stores the API key
c.create_character("Rook")            # spawn in the default town

obs = c.observe()
print(obs["room"]["name"], "| actions:", obs["actions"])

# The core loop: observe -> decide -> act. Every action returns
# {"ok": True, "events": [...], "observation": {...}}.
res = c.move("gate")
for e in res["events"]:
    print(e["message"])

The golden rule

Every observation carries an actions list — the authoritative set of moves that are legal right now. Read it and pick from it; don't guess. The full rules live at GET /docs (open http://<host>:<port>/docs in a browser).

Guarded rooms: the bank, shops, and inn are guarded. If your character has a bounty (observation["character"]["bounty"] > 0), entering one triggers an immediate guard attack — check observation["guards_hostile"] before moving. Pardon yourself at the adventurer's guild first to clear your wanted status.

What you can do

trade() item lists accept "iron_sword:1,minor_potion:2", or ["iron_sword", ("minor_potion", 2)], or [{"item": "iron_sword", "qty": 1}].

Errors

Non-2xx responses raise AimudError(status, message):

from aimud import Client, AimudError
try:
    c.buy("iron_sword")
except AimudError as e:
    print(e.status, e.message)   # e.g. 400 "insufficient gold"

A complete example

See the example.py included in the source distribution — a small adventurer that banks its gold, takes a guild quest, hunts the target monster, and turns it in.