aurival 0.1.7

Write a bot for Aurival. Declare commands, call run(), and the SDK holds the socket.

from aurival import Bot, Context

bot = Bot()

@bot.command("ping", "Check that the bot is alive")
async def ping(ctx: Context):
    await ctx.reply("pong")

bot.run()

Python 3.10+.

A bot can declare up to 50 commands, the SDK refuses to connect past that.

Getting started

Create a virtual environment.

python3 -m venv .venv

Activate it.

. .venv/bin/activate

The venv matters on current Debian, Ubuntu and Fedora, whose system Python refuses pip install outside a virtual environment (PEP 668).

Install the SDK.

pip install aurival

Scaffold a starter bot.

aurival init

aurival init pairs this machine and writes the bot.py above for you. Run python bot.py when it's done.

First run

There is nothing to configure. The first run() pairs this machine:

aurival: pairing code    K7QP-2M4X
aurival: fingerprint     018R-6WAC
Compare the fingerprint in the app, then approve. Waiting...

Compare the fingerprint in the app before you approve — it is what makes a stolen code useless. The key lands in ./.aurival/machine.json (mode 0600, in a 0700 directory, with a .gitignore beside it so it can never be committed). Every later run just starts.

The key deploys with the project, like a .env. Each bot has its own. A leaked key is one machine you revoke; a leaked token would be the bot.

What a handler gets

@bot.command("say")
async def say(ctx: Context):
    ctx.command    # "say"
    ctx.arguments  # the raw rest of the line, unparsed, possibly ""
    ctx.chat       # Chat(id, type, name)
    ctx.sender     # User(id, handle, name)
    await ctx.reply("…")

ctx.message is the id of the message that invoked the command, or None for an event that carries none. ctx.reply() quotes that message by default, so an answer never floats free in a busy chat — there is no flag; on the rare event with no message id it sends a plain message instead.

Handlers run concurrently, and an event is acked only after its handler returns — so a crash mid-handler redelivers rather than loses. Do not block inside a handler. A synchronous call (requests.get, time.sleep, a busy loop) starves the heartbeat on the same event loop, and the server reaps a socket that has gone quiet for three intervals. Use await, or hand the work to a thread.

An exception in a handler is logged with its traceback, the bot stays up, and the event is still acked:

@bot.on_error
async def on_error(error, ctx: Context | None):
    ...   # ctx is None for anything that did not come from a handler

The hook also sees the two things that are not a handler's fault: a problem frame from the server (your socket stays open), and a backlog.overflowed event telling you how many events you missed while you were away and where delivery resumed. Neither reaches a command handler.

Shadowed commands

Every run() syncs your command list, and the server answers with the chats where another bot already holds one of your names. Yours never fires there. The SDK logs one warning line per shadowed chat, through the standard aurival logger:

WARNING:aurival:command 'ping' is shadowed in chat chat_01j… by another bot's command with the same name, and will never fire there

Rename the command, or get the other bot out of that chat. Nothing else in the SDK reacts to it — a shadowed command in one chat is still live in every other.

Environment

Errors

One class per error type, one subclass per code the SDK acts on, and code and doc_url on every instance:

from aurival import RateLimitError, KeyRevoked

try:
    await ctx.reply("…")
except RateLimitError as exc:
    print(exc.code, exc.retry_after, exc.doc_url)

KeyRevoked, SessionSuperseded and BotSuspended end the process on purpose — each one means something a reconnect cannot fix. Everything else the SDK handles for you: token expiry, deploys, network faults, redelivery.

Dependencies

Two, and each is here for a reason:

Development only: pytest 9.1.1, pytest-asyncio 1.4.0, ruff 0.16.6, build 1.6.0, setuptools 84.0.0.

Every version was resolved from PyPI at build time (2026-09-05) and pinned. None came from memory.

Tests

pytest tests

The end-to-end test runs a real bot against the real Go service through backend-go/cmd/bot-api-testbed, which needs a throwaway Postgres:

MIGRATE_TEST_DATABASE_URL='postgres://postgres@127.0.0.1:5432/postgres?sslmode=disable' \
  pytest tests

Without that variable the end-to-end test announces that it skipped. It never passes quietly — a suite reporting green when it never reached the service is worse than no suite.

License

Apache-2.0, see LICENSE. The Aurival name, wordmark, and mascot are trademarks of Nullspire LLC and are not covered by the license, see NOTICE.