# 🤖 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**
- **Downloading and transparently decrypting files**
- **Sending images**
- **Sending videos with automatic thumbnail generation (requires `ffmpeg`)**

## 📦 Installation

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

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

Please inspect [`examples/image_bot.py`](examples/image_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.

## 🚀 Usage

If you use `mab`, your application will *most likely* be using **callbacks** to
react to user actions. `mab` uses filter-based callback system to avoid exposing
raw `nio-matrix` event objects.

This is the workflow you will most likely follow:
1. **Define the callback as `async` function that take 1 argument of type
   `EventContext`.** For example, this callback would print the caption of the
   message:
   ```python
   from mab import *

   async def on_media_with_body(ctx: EventContext):
       """To be called when a message with image/video and caption is received."""
       print(ctx[CTX_BODY])
   ```
2. **Define the conditions your callback must be called on.** For example, you
   may want your callback to be called when `the sender is not the bot` and
   `the message contains textual body` and (`the message is an image` or
   `the message is a video`).
3. **Define the conditions as `filters`.** Most of them are pretty
   straightforward. For example, if you want to use the conditions from above:
   ```python
   from mab import *

   filters = (
       ~SenderIsBotFilter()
       & MessageTypeFilter([MessageType.IMAGE, MessageType.VIDEO])
       & BodyExistsFilter()
   )
   ```
4. **Add the callback to your `MatrixBot` instance.** For example, if you would
   have used everything from above, then your code would look something like
   this:
   ```python
   from mab import *

   # let's assume you create your MatrixBot as `bot` variable here

   async def on_media_with_body(ctx: EventContext):
       """To be called when a message with image/video and caption is received."""
       print(ctx[CTX_BODY])
   
   filters = (
       ~SenderIsBotFilter()
       & MessageTypeFilter([MessageType.IMAGE, MessageType.VIDEO])
       & BodyExistsFilter()
   )
   bot.add_callback(filters, on_media_with_body)

   ...
   ```

Filters support bitwise operators to implement complex matching logic. Some
filters set context variables which can be accessed by
`context[CTX_KEY_NAME]`-like syntax. Possible variables are defined in
[this file](src/mab/context.py). Filters are implemented in
[files of this directory](src/mab/filters/).

## 🏷️ 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 .
```