LXMFy

Easily create LXMF bots for the Reticulum Network with this extensible framework.

Docs | Road to V1

Features

• Spam protection (rate limiting, command cooldown, warnings, banning)
• Command prefix (set to None to process all messages as commands)
• Announcements (announce in seconds, set to 0 to disable)
• Extensible Storage Backend (JSON, SQLite)
• Permission System (Role-based)
• Middleware System
• Task Scheduler (Cron-style)
• Event System
• Help on first message
• LXMF Attachments (File, Image, Audio)
• Customizable Bot Icon (via LXMF Icon Appearance field)
• Threading support for commands.

Installation

pip install lxmfy

or pipx:

pipx install lxmfy

Usage

lxmfy

Create bots:

lxmfy create

Docker

Building Manually

To build the Docker image, navigate to the root of the project and run:

docker build -t lxmfy-test .

Once built, you can run the Docker image:

docker run -d \
    --name lxmfy-test-bot \
    -v $(pwd)/config:/bot/config \
    -v $(pwd)/.reticulum:/root/.reticulum \
    --restart unless-stopped \
    lxmfy-test

Auto-Interface support (network host):

docker run -d \
    --name lxmfy-test-bot \
    --network host \
    -v $(pwd)/config:/bot/config \
    -v $(pwd)/.reticulum:/root/.reticulum \
    --restart unless-stopped \
    lxmfy-test

Building Wheels with Dockerfile.Build

The Dockerfile.Build is used to build the lxmfy Python package into a wheel file within a Docker image.

docker build -f Dockerfile.Build -t lxmfy-wheel-builder .

This will create an image named lxmfy-wheel-builder. To extract the built wheel file from the image, you can run a container from this image and copy the dist directory:

docker run --rm -v "$(pwd)/dist_output:/output" lxmfy-wheel-builder

This command will create a dist_output directory in your current working directory and copy the built wheel file into it.

Example

from lxmfy import LXMFBot, load_cogs_from_directory

bot = LXMFBot(
    name="LXMFy Test Bot", # Name of the bot that appears on the network.
    announce=600, # Announce every 600 seconds, set to 0 to disable.
    announce_enabled=True, # Set to False to disable all announces (both initial and periodic)
    announce_immediately=True, # Set to False to disable initial announce
    admins=["your_lxmf_hash_here"], # List of admin hashes.
    hot_reloading=True, # Enable hot reloading.
    command_prefix="/", # Set to None to process all messages as commands.
    cogs_dir="cogs", # Specify cogs directory name.
    rate_limit=5, # 5 messages per minute
    cooldown=5, # 5 seconds cooldown
    max_warnings=3, # 3 warnings before ban
    warning_timeout=300, # Warnings reset after 5 minutes
)

# Dynamically load all cogs
load_cogs_from_directory(bot)

@bot.command(name="ping", description="Test if bot is responsive")
def ping(ctx):
    ctx.reply("Pong!")

# Admin Only Command
@bot.command(name="echo", description="Echo a message", admin_only=True)
def echo(ctx, message: str):
    ctx.reply(message)

bot.run()

Development

• poetry
• python 3.11 or higher

poetry install
poetry run lxmfy run echo

Contributing

Pull requests are welcome.

Part of Quad4

LXMFy is a Quad4 project.

License

MIT