Metadata-Version: 2.3
Name: jarvis-core
Version: 3.0.0
Summary: JARVIS core
Author: Zevaryx
Author-email: Zevaryx <zevaryx@gmail.com>
Requires-Dist: aiohttp>=3.14.5,<4
Requires-Dist: beanie>=2.2.0,<3
Requires-Dist: croniter>=6.2.4,<7
Requires-Dist: nanoid>=2.0.0,<3
Requires-Dist: pydantic>=2.14.2,<3
Requires-Dist: pymongo>=4.19.0,<5
Requires-Dist: regex>=2026.9.29
Requires-Dist: rich>=15.0.0
Requires-Python: >=3.11, <4
Description-Content-Type: text/markdown

# jarvis-core

Core functionality of [JARVIS](https://git.zevaryx.com/jarvis), shared by
[jarvis-bot](https://git.zevaryx.com/jarvis/jarvis-bot) and
[jarvis-tasks](https://git.zevaryx.com/jarvis/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](https://docs.astral.sh/uv/).

```sh
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:

```sh
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.

```sh
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.
