Universal Chat Bot Framework

A production-ready, platform-agnostic Python bot framework with 100% decoupled plugin architecture. Currently implemented for SimpleX Chat with full Docker support. Features universal plugin system, automatic invite processing, daily logging, media downloads, and extensible command system that works across multiple chat platforms.

✅ Production Ready: 162/162 tests passing | 0 failed plugins | 100% platform decoupling achieved

Features

• Universal Plugin Architecture: 100% platform-agnostic design - works with SimpleX, Discord, Telegram, Matrix, and more
• Platform Service Abstraction: Unified interface for platform-specific functionality (message history, user management, etc.)
• Hot Reload Development: Real-time plugin updates without restarting the bot
• Daily Message Logging: Separate log files for each day with timestamps
• Media Downloads: Automatic download and storage of images, videos, and documents
• Custom Server Support: Uses your own SMP/XFTP servers (no official servers)
• Command Line Interface: Accept connections via CLI arguments
• Configuration Management: YAML-based configuration with environment variables
• Docker Support: Complete containerized setup with persistent storage
• Extensible Commands: !help and custom plugin framework with cross-platform compatibility

Universal Plugin Architecture

This bot framework uses a platform-agnostic design where plugins work across any supported chat platform without modification.

Core Components

1. Universal Plugin Base (plugins/universal_plugin_base.py) - Required for all plugins
2. Platform Adapters - Bridge between bot framework and specific platforms
3. Service Registry - Provides platform-specific functionality through unified interfaces
4. Command Context - Universal interface for handling commands across platforms

How It Works

Plugins inherit from UniversalBotPlugin with supported_platforms = [] (empty = supports all platforms):

from plugins.universal_plugin_base import UniversalBotPlugin, CommandContext

class MyPlugin(UniversalBotPlugin):
    def __init__(self):
        super().__init__("my_plugin")
        self.supported_platforms = []  # Works on ALL platforms
        
    async def handle_command(self, context: CommandContext):
        # Platform-agnostic command handling
        return f"Hello from {context.platform.value}!"

Platform Adapters translate between the universal framework and platform-specific APIs:

• SimpleX: Uses WebSocket CLI integration
• Discord: Would use discord.py library
• Telegram: Would use python-telegram-bot
• Matrix: Would use matrix-nio

Services provide platform-specific functionality through unified interfaces:

• message_history: Store/retrieve chat history
• user_management: Handle user permissions and profiles
• media_handling: Platform-specific file downloads

Current SimpleX Implementation

The bot currently implements SimpleX Chat through:

• SimpleX Adapter (simplex_platform_services.py) - Bridges to SimpleX Chat CLI
• SimpleX Services - WebSocket communication, XFTP downloads, contact management
• Universal Commands - All commands work identically across platforms

Prerequisites

1. Docker & Docker Compose: For containerized deployment
2. Universal Plugin Base: Required dependency for all plugins
3. Platform Plugin: REQUIRED - Platform-specific plugin for your chat platform
   • 📦 Available at: https://github.com/stephenmkbrady/universal-bot-plugins
   • ⚠️ The bot will not function without a platform plugin (e.g., SimpleX, Discord, Telegram)
4. Platform-Specific Requirements:
   • SimpleX: Custom SMP and XFTP server addresses
   • Discord: Bot token and guild permissions
   • Telegram: Bot API token from @BotFather
   • Matrix: Homeserver URL and access token
5. Configuration Files: config.yml and .env files (templates provided)

Implementation Guide

For New Platforms

To implement this bot framework for a new platform (Discord, Telegram, Matrix):

1. Create Platform Adapter - Implement BotAdapter interface:

from plugins.universal_plugin_base import BotAdapter, BotPlatform

class DiscordAdapter(BotAdapter):
    def __init__(self, discord_client):
        super().__init__(BotPlatform.DISCORD)
        self.client = discord_client
    
    async def send_message(self, chat_id: str, message: str):
        # Discord-specific message sending
        channel = self.client.get_channel(int(chat_id))
        await channel.send(message)

2. Create Platform Services - Implement required service interfaces:

from platform_services import MessageHistoryService

class DiscordMessageHistory(MessageHistoryService):
    async def get_recent_messages(self, chat_id: str, limit: int):
        # Discord-specific message retrieval
        pass

3. Register Services - Connect services to the universal framework:

service_registry.register_service('message_history', discord_message_service)
service_registry.register_service('user_management', discord_user_service)

4. All existing plugins work immediately - No plugin modifications needed!

Quick Start (SimpleX)

1. Clone and Setup

git clone <repository-url>
cd SIMPLEX_BOT

# Creates necessary folders, permissions, etc.
./setup.sh

# Configure your settings
vim config.yml
vim .env

# Start the bot
./compose.sh up -d
# Monitor the logs, first start takes a little longer
./compose.sh logs

# Simplex specific steps
# Create an invitation link for Simplex
./generate_invite.sh
#Paste your invite link into your client

2. Configure Your Setup

Edit config.yml with your custom servers:

servers:
  smp:
    - "smp://your-server.com"
  xftp:
    - "xftp://your-files-server.com"

Edit .env with your environment variables:

SMP_SERVER_1=smp://your-server.com
XFTP_SERVER_1=xftp://your-files-server.com
WEBSOCKET_URL=ws://simplex-chat:3030

3. Start the Bot

# Build and start the entire stack
./compose.sh up --build -d

# View logs
./compose.sh logs -f

# Connect to a SimpleX address
docker compose exec simplex-bot python bot.py --connect "simplex://invitation-link"

Configuration

config.yml Structure

# Server Configuration  
servers:
  smp:
    - "${SMP_SERVER_1}"
    - "${SMP_SERVER_2}"
  xftp:
    - "${XFTP_SERVER_1}" 
    - "${XFTP_SERVER_2}"

# Bot Settings
bot:
  name: "SimpleX Bot"
  websocket_url: "${WEBSOCKET_URL}"
  auto_accept_contacts: true
  
# Logging Configuration
logging:
  daily_rotation: true
  message_log_separate: true
  retention_days: 30
  
# Media Settings  
media:
  download_enabled: true
  max_file_size: "100MB"
  allowed_types: ["image", "video", "document"]
  storage_path: "./media"

Environment Variables (.env)

# Server Configuration
SMP_SERVER_1=smp://your-primary-server.com
SMP_SERVER_2=smp://your-backup-server.com  
XFTP_SERVER_1=xftp://your-files-server.com
XFTP_SERVER_2=xftp://your-backup-files-server.com

# Bot Configuration
WEBSOCKET_URL=ws://simplex-chat:3030
BOT_NAME=SimpleX Bot

# Security
AUTO_ACCEPT_CONTACTS=true
MAX_FILE_SIZE=104857600

Usage

Available Commands

• !help - Show comprehensive help with bot information and all available plugin commands

Command Line Options

# Connect to a specific SimpleX address
python bot.py --connect "simplex://address"

# Accept a one-time invitation link
python bot.py --connect "https://simplex.chat/invitation#..."

# Join a group via invite link
python bot.py --group "https://simplex.chat/contact#..."

# Display help
python bot.py --help

Daily Operations

View Logs:

# Application logs
tail -f logs/bot-$(date +%Y-%m-%d).log

# Message logs  
tail -f logs/messages-$(date +%Y-%m-%d).log

# Docker logs
docker-compose logs -f simplex-bot

Check Media Downloads:

ls -la media/

Bot Status:

docker-compose exec simplex-bot python -c "
import bot; 
bot.get_status()
"

File Structure

SIMPLEX_BOT/
├── bot.py                 # Main bot implementation
├── requirements.txt       # Python dependencies  
├── docker-compose.yml     # Docker orchestration
├── Dockerfile            # Bot container definition
├── config.yml.example   # Configuration template
├── config.yml           # Bot configuration
├── .env.example         # Environment template
├── .env                 # Environment variables
├── README.md            # This documentation
├── dev_log.md          # Development notes
├── bot_profile/        # SimpleX profile data (persistent)
├── logs/              # Daily log files
│   ├── bot-2025-01-01.log      # Application logs
│   ├── messages-2025-01-01.log # Message logs  
│   └── ...
├── media/             # Downloaded files
│   ├── images/
│   ├── videos/
│   └── documents/
└── scripts/           # Utility scripts
    ├── setup.sh       # Initial setup
    └── cleanup.sh     # Maintenance

Development

Current Implementation Status

Working Features:

• WebSocket connection to SimpleX Chat CLI with automatic reconnection
• Full command processing system with admin permissions
• YAML configuration loading with environment variable substitution
• Daily log rotation and separate message logging
• Media download via XFTP protocol with type validation
• Custom server configuration (SMP/XFTP)
• CLI argument processing for connections and invites
• Comprehensive admin commands (!contacts, !groups, !debug, !plugins, !commands)
• Plugin system with hot reload capability
• Contact and group management
• Invite generation and processing
• Async correlation system for CLI responses

Test Coverage:

• Test Suite: 5,001 lines across 24 test files
• Test Status: ✅ 162/162 tests passing (100%)
• Test Types: Unit tests, integration tests, plugin tests, configuration tests, architecture validation
• Core Functionality: ✅ FULLY VERIFIED (Universal Plugin Architecture, Platform Decoupling, Configuration Management, Message Processing, File Handling, Admin System)

Creating Universal Plugins

All plugins automatically work across platforms. Create them in plugins/external/:

# plugins/external/my_plugin/plugin.py
from plugins.universal_plugin_base import UniversalBotPlugin, CommandContext

class MyUniversalPlugin(UniversalBotPlugin):
    def __init__(self):
        super().__init__("my_plugin")
        self.version = "1.0.0"
        self.description = "Cross-platform plugin example"
        self.supported_platforms = []  # Empty = works on ALL platforms
    
    def get_commands(self):
        return ["hello", "status"]
    
    async def handle_command(self, context: CommandContext):
        if context.command == "hello":
            return f"Hello from {context.platform.value} platform!"
        elif context.command == "status":
            # Use platform services for advanced functionality
            user_service = self.require_service('user_management')
            if user_service:
                user_info = await user_service.get_user_info(context.user_id)
                return f"User: {user_info.get('display_name', 'Unknown')}"
            return "User service not available"
        return None
    
    async def handle_message(self, context: CommandContext):
        # Store non-command messages for context (optional)
        if not context.args_raw.startswith('!'):
            # Process regular messages for AI context, analytics, etc.
            pass
        return None

Installation Requirements

1. Universal Plugin Base: All plugins must inherit from UniversalBotPlugin
2. Platform Plugin: REQUIRED - Install from https://github.com/stephenmkbrady/universal-bot-plugins
   • Copy the appropriate platform plugin (e.g., simplex/, discord/, telegram/) to plugins/external/
   • The bot framework requires at least one platform plugin to function
3. Platform Services: Optional - use self.require_service() for advanced features
4. Docker Environment: Recommended for consistent plugin execution
5. Hot Reload Support: Automatic plugin updates during development

Testing

The framework includes a comprehensive test suite with 162 tests covering all aspects of the universal plugin architecture.

Running Tests

All Tests:

# Run complete test suite (162 tests)
./compose.sh exec simplex-bot-v2 python3 -m pytest tests/ -v

# Or using Docker profile
docker compose --profile testing run --rm simplex-bot-test-v2 python3 -m pytest tests/ -v

Specific Test Categories:

# Configuration tests (22 tests)
python3 -m pytest tests/test_config_manager.py tests/test_config_validation.py tests/test_environment_vars.py -v

# Plugin architecture tests (15 tests)  
python3 -m pytest tests/test_plugins.py tests/test_command_registry.py -v

# Message processing tests (6 tests)
python3 -m pytest tests/test_message_handler.py -v

# Integration tests (14 tests)
python3 -m pytest tests/test_bot_integration.py -v

# Health and stability tests (16 tests)
python3 -m pytest tests/test_bot_health.py -v

Test Coverage Verification:

# Run with coverage report
python3 -m pytest tests/ --cov=. --cov-report=term-missing --cov-report=html

# Quick validation (core tests only)
python3 -m pytest tests/test_config_manager.py tests/test_plugins.py tests/test_bot_integration.py

Test Results Summary

✅ 162/162 tests passing (100%)

Test Categories:

• Configuration Management (36 tests): YAML parsing, environment variables, validation
• Universal Plugin System (15 tests): Plugin loading, hot reload, command handling
• Bot Integration (14 tests): Component initialization, dependency injection
• Message Processing (6 tests): Universal message pipeline, command routing
• Health & Stability (16 tests): Error handling, resource cleanup, resilience
• File Operations (36 tests): XFTP client, WebSocket manager, file downloads
• Platform Services (25 tests): Service registry, platform abstraction
• Specialized Tests (14 tests): Edge cases, specific configurations

Key Validations:

• ✅ Universal plugin architecture working across all platforms
• ✅ Zero platform coupling detected
• ✅ All 7 plugins load successfully (homeassistant, loupe, youtube, core, ai, simplex, stt_openai)
• ✅ Hot reloading functional
• ✅ Configuration system robust
• ✅ Message processing pipeline complete
• ✅ Admin system integrated
• ✅ Error handling comprehensive

Troubleshooting

Common Issues

1. Configuration Problems

   • Check config.yml syntax and environment variable substitution
   • Verify .env file contains all required variables
   • Ensure custom server addresses are correct

2. Docker Issues

   • Run docker-compose logs to check service startup
   • Verify volume mounts with docker-compose config
   • Check network connectivity between containers

3. Connection Problems

   • Verify SimpleX Chat CLI starts with custom server configuration
   • Check WebSocket connectivity on port 3030
   • Review bot connection logs for specific errors

4. Media Download Issues

   • Check XFTP server configuration
   • Verify media directory permissions
   • Review file size limits in configuration

Debug Commands

# Check container status  
./compose.sh ps

# View detailed logs
./compose.sh logs --tail=100

# Test configuration
docker compose config

# Access bot container  
docker compose exec simplex-bot-v2 bash

# Run specific test categories for debugging
docker compose --profile testing run --rm simplex-bot-test-v2 python3 -m pytest tests/test_plugins.py -v -s

# Test plugin loading
docker compose exec simplex-bot-v2 python3 -c "
from bot import SimplexChatBot
bot = SimplexChatBot('config.yml')
print('Plugin system status:', 'loaded' if bot.plugin_manager else 'failed')
"

# Validate configuration
docker compose exec simplex-bot-v2 python3 -c "
from config_manager import ConfigManager
config = ConfigManager('config.yml')
print('Config valid:', config.get_bot_config() is not None)
"

Important Links

• SimpleX Chat CLI Documentation
• SimpleX Chat GitHub
• Bot Examples
• Advanced Bot Examples

Support

For development questions and support:

1. Review dev_log.md for detailed technical analysis
2. Check the SimpleX Chat documentation
3. Examine the official bot examples
4. Join SimpleX development groups for community support