## About

Cadbury is a friendly composable multi-purpose Matrix bot.

See `pyproject.toml` for the dependencies.
Note that each dependency provides a separate dedicated bot role.
Bots roles are composed with a couple lines of code in `app.py` before connecting to the Matrix server.

Although each bot role can run separately with separate credentials,
the purpose of `Cadbury` is to compose several together under a single Matrix bot login.

## Getting Started

Create a bot account on your Matrix server, and set the necessary environment variables: `MATRIX_SERVER`, `MATRIX_BOT`, `MATRIX_BOT_PWD`.

Set `MATRIX_DATA_DIR` to an existing directory path where you would like Cadbury to store any `sqlite3` databases.

Expect files such as `goals.db` and `chores.db` to appear there after you tell Cadbury `!chore setup` and `!goal setup`, etc.

Ensure that `python` and `sqlite3` are installed and available on the path.

> Tip: Cadbury has no use for email. Your Matrix server may allow creating the bot account without an email account, using a `token` registration type.

Run the bot with `make serve`,
or build a virtual environment and then run the bot with

Or run the following commands to create the virtual environment:

	python -m venv .venv
	.venv/bin/pip install .

Then use the following command to launch the bot:

	.venv/bin/python app.py

## Chatting

Invite you Cadbury bot to a Matrix channel, and it will accept automatically, if it can.

> Tip: Additional setup is required to add a Matrix bot to an encrypted channel.

Use `!goal help` and `!chore help`, to get started.

> Tip: Many bot roles require creating a sqlite3 database, and may require you to tell Cadbuary something like `!chore setup` one initial time to create the database file.

## Remixing

When creating your own unique mix of bot roles, consider creating a public fork of
this repository and modifying `app.py` and `pyproject.toml` as needed.

Note the AGPLv3 license, and please share your own modifications publicly, if you choose to use a modified version of this bot in a public setting.

## About the Name

Named for Cadbury C. Cadbury, or Herbert Arthur Runcible Cadbury.

    The Riches' butler who attends to the Rich estate. British born, Cadbury gives the image of propriety and service. When need demands however, he becomes a tough, man of action. Cadbury is also a master hypnotist, ventriloquist and wood-carver.