matrix-biblebot 0.1.0

A simple Matrix bot that fetches Bible verses

Matrix BibleBot

A simple Matrix bot that fetches Bible verses using APIs from bible-api.com & esv.org

Supported Translations

• King James Version (KJV)
• English Standard Version (ESV) - requires an API key
• Easily extensible to support additional translations

Installation

Install from PyPI (Recommended)

pip install matrix-biblebot

For an isolated installation, you can use pipx:

pipx install matrix-biblebot

Install from Source

Clone the repository:

git clone https://github.com/jeremiah-k/matrix-biblebot.git
cd matrix-biblebot
pip install .

For development:

pip install -e .

Configuration

1. Create a .env file

Create a .env file in the same directory as your config file (e.g., ~/.config/matrix-biblebot/.env) with your Matrix access token and any API keys:

MATRIX_ACCESS_TOKEN="your_bots_matrix_access_token_here"
ESV_API_KEY="your_esv_api_key_here"  # Optional

The bot will first look for a .env file in the same directory as your config file. If not found, it will fall back to looking in the current working directory.

2. Create a config.yaml file

The bot looks for a configuration file at ~/.config/matrix-biblebot/config.yaml by default. You can generate a template configuration file with:

biblebot --generate-config

This will create a sample config file with the following structure:

matrix_homeserver: "https://your_homeserver_url_here"
matrix_user: "@your_bot_username:your_homeserver_domain"
matrix_room_ids:
  - "!your_room_id:your_homeserver_domain"
  - "!your_other_room_id:your_homeserver_domain"

Edit this file with your Matrix credentials and room IDs.

You can also specify a custom config location:

biblebot --config /path/to/your/config.yaml

Or generate a config at a custom location:

biblebot --generate-config --config /path/to/your/config.yaml

Usage

Running the Bot

After installation and configuration, you can run the bot with:

biblebot

Or with custom options:

biblebot --config /path/to/config.yaml --log-level debug

Command-line Options

usage: biblebot [-h] [--config CONFIG] [--log-level {error,warning,info,debug}] [--generate-config] [--version]

BibleBot for Matrix

options:
  -h, --help            show this help message and exit
  --config CONFIG       Path to config file (default: ~/.config/matrix-biblebot/config.yaml)
  --log-level {error,warning,info,debug}
                        Set logging level (default: info)
  --generate-config     Generate a sample config file at the specified path
  --version             show program's version number and exit

Interacting with the Bot

Invite the bot to rooms that are listed in the config.yaml file. The bot will respond to messages that match Bible verse references:

• Simple reference: John 3:16
• Range reference: 1 Cor 15:1-4
• With translation: John 3:16 esv

Development

Contributions are welcome! Feel free to open issues or submit pull requests.