jarvis-core

Core functionality of JARVIS, shared by jarvis-bot and jarvis-tasks.

Versions

jarvis-bot, jarvis-tasks and jarvis-core are released together and share a version number: 3.x of each work with 3.x of the others. A change that needs matching releases of the other two bumps the major version of all three.

Modules

jarvis_core.db

Database connection (connect(), built on Beanie and PyMongo's async client) and the Beanie document models. Discord IDs are stored as BSON int64.

jarvis_core.db.migrations

One-off migration for databases written by jarvis-core 1.x (see below).

jarvis_core.filters

Regex filters for various functions

jarvis_core.log

Pre-configured Rich logger

jarvis_core.util

Quality of life utilities. jarvis_core.util.http provides public_session() and fetch(), which refuse to connect to non-public addresses; use them for any request made on behalf of a user.

Development

Requires Python 3.11+ and uv.

uv sync
uv run pytest

Database tests need a real MongoDB and are skipped otherwise. Every collection in the test database is dropped before and after each test, so point it at a scratch database:

export JARVIS_TEST_MONGO_URI="mongodb://user:pass@localhost:27017/?authSource=admin"
export JARVIS_TEST_MONGO_DB="jarvis_test"
uv run pytest

Upgrading from 1.x

jarvis-core 1.x stored Discord IDs as strings, which no query could match. 2.0 stores them as integers, so existing data must be migrated once, before deploying a bot or tasks build that depends on 2.0. Back up the database first.

uv run jarvis-migrate --uri "mongodb://user:pass@host:27017/?authSource=admin" --database jarvis --dry-run
uv run jarvis-migrate --uri "mongodb://user:pass@host:27017/?authSource=admin" --database jarvis

The migration is idempotent. Besides the ID conversion it rewrites the legacy "perma" ban type, normalizes ban discriminators, and backfills Ban.expires_at for temporary bans. Locks created before Lock.guild existed keep guild unset.