An unstable (for now) Python framework for creating bots on the SimpleX chat platform.

This library was initially created as a somewhat direct port of TypeScript structures, but aims to provide a decorator-based interface familiar to users of libraries like discord.py.

Note: While functional, being a relatively direct conversion from the TypeScript structures means this does not always follow Python best practices and would benefit from further refinement

SimpX group

Come chat about bot development, the project, or even SimpleX in general.

• Decorator-based handlers for commands (@bot.command) and events (@bot.event).
• Profile management (BotProfile, ProfileManager) to handle bot identity.
• Built-in, customizable help command (!help).
• Optional automatic welcome message for new contacts.
• Extension classes (SimpleXBotExtensions) providing wrapper objects (ContactWrapper, GroupWrapper, ChatWrapper etc.) for more Pythonic interaction with the SimpleX API.
• Basic task scheduling.
• Support for sending and updating live messages.
• Automatic message reading.

git clone https://github.com/FailSpy/simpx-py
cd simpx-py
# Optional: Create and activate a virtual environment
# python -m venv venv
# source venv/bin/activate  # or venv\Scripts\activate on Windows

pip install .

You'll need the Terminal CLI to work with it. Presently, there is no interfacing that allows the Python code to run the daemon itself. You will need to implement this yourself for now.

You can get the simplex-chat CLI release here: https://github.com/simplex-chat/simplex-chat/releases/latest

You will want a non-"desktop" tagged version (desktop is a GUI on top)

To run the daemon for Python, use the port operator to tell it to operate in WebSockets mode:

./simplex-chat-ubuntu-22_04-x86-64 -p 5225

This will open a websocket on port 5225 which Python can access. If you want to use a different port, see BotProfile to configure the Python side of things.

• Improve profiles (allowing for multiple profiles at once)
• Improve typing and wrappers
  • Port all SimpleX haskell message types
  • File handling
• Directly integrate w/ CLI binary?
• Privacy configuration
• Exception handling
• Logging
• Always: documentation

See also example_bot.py

Here's a commented example of how to create and run a bot:

import asyncio
from simpx import BotProfile, SimpleXBot

# 1. Create a bot profile (can be saved/loaded)
# If a profile with this name exists, it will be loaded.
# Otherwise, a new one is created on the server.
profile = BotProfile(
    display_name="MySimpleBot",
    full_name="My Simple Bot",
    description="A bot built with simpx-py",
    # Optional: Welcome message for new contacts
    welcome_message="Hi {name}! Welcome to my bot.",
    # Optional: Set command prefix (default is "!")
    command_prefix="!"
)

# 2. Create the bot instance
# You can pass the profile directly or let the bot handle loading/creation
bot = SimpleXBot(profile)

# 3. Define commands using decorators
@bot.command(name="hello", help="Says hello back to you")
async def hello_command(chat_info):
    """A simple command that sends a greeting."""
    # Use bot.send_message to reply in the same chat
    await bot.send_message(chat_info, "Hello there!")

@bot.command(name="echo", help="Repeats your message")
async def echo_command(chat_info, args: str):
    """Echoes the arguments provided"""
    if args:
        await bot.send_message(chat_info, f"You said: {args}")
    else:
        await bot.send_message(chat_info, "You didn't say anything to echo!")

# 4. Define event handlers (optional)
@bot.event("contactConnected")
async def handle_connection(response):
  """Handles new contact connections (alternative to welcome_message)."""
  contact = response.get("contact", {})
  display_name = contact.get("profile", {}).get("displayName", "Unknown")
  print(f"{display_name} connected!")

# 5. Start the bot
if __name__ == "__main__":
    print("Starting bot...")
    # Ensure your SimpleX Chat Console (simplex-chat) backend is running
    # The bot will connect via WebSocket (default: ws://127.0.0.1:5225)
    # You can specify a different server_url in SimpleXBot constructor if needed
    try:
        asyncio.run(bot.start())
    except KeyboardInterrupt:
        print("Bot stopped.")
    finally:
        # Optional cleanup
        asyncio.run(bot.close())

1. Clone the repository:

   git clone https://github.com/FailSpy/simpx-py
   cd simpx-py

2. Install Dependencies:

   pip install -r requirements.txt

   NOTE: If you want to use !msg with an LLM provider: - Install openai as well - Configure API Key: Open example-bot.py and replace <API_KEY_HERE> with your actual OpenRouter API key (or adapt for a different LLM provider).
3. Ensure SimpleX Chat Console is running: The bot needs to connect to a running simplex-chat instance via its WebSocket interface (launch with arg i.e. -p 5225).
4. Run the bot:

   python example-bot.py

5. Connect to your bot: Use the bot's address (printed to the console as plaintext and QR code on run) in your SimpleX Chat client to connect and try the commands (!help, !info, !echo, !square, !add, !msg).

Feel free to open issues or pull requests. Given the origin of the library as a direct port, contributions focused on making the codebase more Pythonic, improving error handling, adding tests, or enhancing documentation are particularly welcome.