# 🤖 mab

**mab** *(MAtrix Bot)* is a **very** simple Python package that can be used to
develop **very** simple Matrix bots. It does not aim to be the best library out
there, but it aims to be convenient and usable for relatively serious projects.

## ✨ Features

The library supports the following features:
- **Completely `asyncio` based**
- **Filter-based callback system**
- **Sending images**
- **Sending videos with automatic thumbnail generation (requires `ffmpeg`)**

## 🚀 Usage

Use `apt` to install required system packages and `pip` to install the package.
You may need to use `root` privileges to use `apt`. It's highly recommended you
use `venv` or another Python virtual environment. Here are the commands to
install the latest version of the library:

```bash
apt install libmagic1-dev libolm-dev
python -m pip install git+https://git.tyukalov.su/nikita/mab@v0.4.0
```

`libmagic1-dev` is needed for automatic file MIME type detection, `libolm-dev`
is needed for E2EE to work.

Please inspect [`examples/image_gen_bot.py`](examples/shell_bot.py),
[`examples/echo_bot.py`](examples/echo_bot.py) or open [`examples/`](examples/)
directory to find usage examples. Examples require that you set
`MATRIX_HOMESERVER` and `MATRIX_USERNAME` environment variables. Examples create
`session_storage` directory in working directory.

## 🏷️ Versioning

Releases are tagged in this repository using the `vX.Y.Z` format. If the commit
is not tagged, it must be treated as versionless and should not be used for your
application.
- `X` **(Major)**: Breaking architectiral changes or complete rewrites. Existing
  code will break. Note that `0.Y.Z` versions are considered **very unstable**,
  the API may change at any time and some features do not work as expected.
- `Y` **(Minor)**: Breaking API changes, feature removals, or behavioral
  modifications. Existing code will likely break.
- `Z` **(Patch)**: Backward-compatible feature additions, bug fixes, or internal
  changes. Existing code will not break.

## 🛠️ Development

Here's the list of commands you should execute to get started with development
(including cloning the repository and installing required packages). Please note
that your workflow may use something other than `venv`.
```bash
apt install libmagic1-dev libolm-dev
git clone https://git.tyukalov.su/nikita/mab
cd mab
python3 -m venv .venv
. .venv/bin/activate
pip install -e .
```