From cb520814d8f35e952763f63e43cbc6c756bf750e Mon Sep 17 00:00:00 2001
From: nikita <nikita@dowow.su>
Date: Sat, 12 Sep 2026 22:49:55 +0300
Subject: [PATCH] Added description of filter system to README.md

---
 README.md | 62 ++++++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 61 insertions(+), 1 deletion(-)

diff --git a/README.md b/README.md
index 0537afc..923444f 100644
--- a/README.md
+++ b/README.md
@@ -12,7 +12,7 @@ The library supports the following features:
 - **Sending images**
 - **Sending videos with automatic thumbnail generation (requires `ffmpeg`)**
 
-## 🚀 Usage
+## 📦 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
@@ -33,6 +33,66 @@ 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