272 lines
8.1 KiB
Markdown
272 lines
8.1 KiB
Markdown
I wrote this bot in one night, while I'm recovering from two level cervical spinal surgery, CDA Cervical Discectomy and Disc Arthroplasty. Expect a lot of bugs.
|
|
|
|
# Matrix Bot
|
|
|
|
Matrix Bot is a Python-based chat bot designed to work with Matrix, an open network for secure, decentralized communication. This bot is built using the `simplematrixbotlib` library and provides various commands and functionalities for interacting with Matrix rooms.
|
|
|
|
## Features
|
|
|
|
- Modular architecture: Commands are implemented as separate plugins, making it easy to add or modify functionality.
|
|
- Command handling: The bot listens for specific commands prefixed with `!` and responds accordingly.
|
|
- Plugin system: Each command is implemented as a separate plugin module, allowing for easy customization and extension.
|
|
- Extensible: Users can add new commands by creating additional plugin modules.
|
|
|
|
## Automatic Installation
|
|
Run the installation script
|
|
1. `./install-funguy.sh`
|
|
|
|
2. Launch the bot:
|
|
`sudo systemctl start funguybot`
|
|
|
|
## Manual Installation
|
|
|
|
1. Create python venv
|
|
`python3 -m venv venv`
|
|
`source venv/bin/activate`
|
|
|
|
2. Clone the repository:
|
|
`git clone https://gitlab.com/Eggzy/funguybot.git`
|
|
|
|
3. Apply the patch
|
|
`cp api.py.patch simplematrixbotlib`
|
|
`git apply api.py.patch`
|
|
|
|
4. Install dependencies:
|
|
`cd simplematrixbotlib && pip install .`
|
|
`cd ../ && pip install -r requirements.txt`
|
|
|
|
3. Set up environment variables:
|
|
Create/Edit `.env` file in the root directory of the bot and add the following variables:
|
|
|
|
```
|
|
MATRIX_URL="https://matrix.org" (or another homeserver)
|
|
MATRIX_USER=""
|
|
MATRIX_PASS=""
|
|
OPENWEATHER_API_KEY="" # Optional: For weather plugin
|
|
```
|
|
|
|
4. Create systemd.service
|
|
Create `/etc/systemd/system/funguybot.service`
|
|
Replace `$working_directory` with your bot install path
|
|
|
|
```
|
|
[Unit]
|
|
Description=Funguy Bot Service
|
|
After=network.target
|
|
|
|
[Service]
|
|
Type=simple
|
|
User=$user
|
|
Group=$group
|
|
WorkingDirectory=$working_directory
|
|
ExecStart=$working_directory/start-funguy.sh
|
|
Restart=on-failure
|
|
StandardOutput=syslog
|
|
StandardError=syslog
|
|
SyslogIdentifier=funguybot
|
|
|
|
[Install]
|
|
WantedBy=multi-user.target
|
|
EOF
|
|
```
|
|
|
|
5. Launch Fungy
|
|
```
|
|
systemctl daemon-reload
|
|
systemctl enable funguybot
|
|
systemctl start funguybot
|
|
```
|
|
|
|
## Usage
|
|
|
|
To use the bot, invite it to a Matrix room and interact with it by sending commands prefixed with `!`. For example:
|
|
|
|
- `!date`: Display the current date and time.
|
|
- `!fortune`: Get a random fortune message.
|
|
- `!proxy`: Retrieve and test random SOCKS5 and HTTP proxies.
|
|
- `!isup <domain/ip>`: Check if the specified domain or IP address is reachable.
|
|
- `!karma <user>`: View or modify karma points for a user.
|
|
- `!funguy <prompt>` Talk to the Tech AI LLM
|
|
- `!music <prompt>` Talk to the music knowledge LLM
|
|
- `!yt <search terms>` Search Youtube
|
|
- `!weather New York` Get Weather information
|
|
- `!ud <term>` Get Urban Dictionary definition
|
|
- `!help` Get Help
|
|
For a complete list of available commands and their descriptions, use the `!commands` command.
|
|
|
|
# 🍄 Funguy Bot Commands 🍄
|
|
|
|
|
|
## Plugin Documentation
|
|
|
|
### Core Commands
|
|
|
|
**🍄 !help**
|
|
Displays comprehensive help documentation for all available commands with usage examples.
|
|
|
|
**🔌 !plugins**
|
|
Lists all loaded plugins along with their descriptions.
|
|
|
|
**⏰ !date**
|
|
Displays the current date and time with proper ordinal formatting.
|
|
|
|
**🃏 !fortune**
|
|
Returns a random fortune message using the fortune command.
|
|
|
|
### Utility Commands
|
|
|
|
**💻 !proxy**
|
|
Retrieves and tests random SOCKS5 proxies from public sources, showing latency and caching working proxies.
|
|
|
|
**📶 !isup [domain/ip]**
|
|
Checks if a website or server is reachable, including DNS resolution and HTTP/HTTPS service checks.
|
|
|
|
**☯ !karma [user] [up/down]**
|
|
Manages karma points for users. View karma with `!karma user`, increase with `!karma user up`, decrease with `!karma user down`.
|
|
|
|
**🌧️ !weather [location]**
|
|
Fetches current weather information for any location using OpenWeatherMap API.
|
|
*Requires OPENWEATHER_API_KEY environment variable*
|
|
|
|
**📖 !ud [term] [index]**
|
|
Fetches definitions from Urban Dictionary. Use without arguments for random definition, or specify term and optional index.
|
|
|
|
**🔍 !dns [domain]**
|
|
Performs comprehensive DNS reconnaissance on a domain. Shows A, AAAA, MX, NS, TXT, CNAME, SOA, and other DNS records.
|
|
|
|
**💰 !btc**
|
|
Fetches the current Bitcoin price in USD from bitcointicker.co API.
|
|
|
|
### AI & Generation Commands
|
|
|
|
**🤖 AI Commands (!tech, !music, !eth, etc.)**
|
|
Multiple AI model commands that interface with local AI API. Each command uses specialized prompts for different domains:
|
|
- `!tech` - Technology assistance
|
|
- `!music` - Music knowledge and recommendations
|
|
- `!weather` - Weather information
|
|
- And 100+ other specialized AI commands
|
|
|
|
**📸 !sd [prompt] [options]**
|
|
Generates images using self-hosted Stable Diffusion with customizable parameters:
|
|
- `--steps` - Number of generation steps (default: 4)
|
|
- `--cfg` - CFG scale (default: 2)
|
|
- `--h` - Image height (default: 512)
|
|
- `--w` - Image width (default: 512)
|
|
- `--neg` - Negative prompt
|
|
- `--sampler` - Sampler name (default: DPM++ SDE)
|
|
|
|
**📄 !text [prompt] [options]**
|
|
Generates text using Ollama's Mistral 7B Instruct model:
|
|
- `--max_tokens` - Maximum tokens to generate (default: 512)
|
|
- `--temperature` - Sampling temperature (default: 0.7)
|
|
|
|
### Media & Search Commands
|
|
|
|
**🎬 YouTube Commands**
|
|
- Automatic preview when YouTube links are posted
|
|
- `!yt [search terms]` - Search for YouTube videos
|
|
- Shows video info, description, and attempts to fetch lyrics
|
|
|
|
**📰 !xkcd**
|
|
Fetches and displays a random XKCD comic.
|
|
|
|
### Administration Commands
|
|
*Admin only - requires admin_user configuration*
|
|
|
|
**🔧 !set [option] [value]**
|
|
Set configuration options (admin_user, prefix)
|
|
|
|
**🔍 !get [option]**
|
|
Get configuration values
|
|
|
|
**💾 !saveconf**
|
|
Save current configuration
|
|
|
|
**📥 !loadconf**
|
|
Load saved configuration
|
|
|
|
**👁️ !show**
|
|
Display current configuration
|
|
|
|
**🔄 !reset**
|
|
Reset configuration to defaults
|
|
|
|
**📤 !load [plugin]**
|
|
Load a plugin
|
|
|
|
**📥 !unload [plugin]**
|
|
Unload a plugin
|
|
|
|
**🔄 !reload**
|
|
Reload all plugins
|
|
|
|
**🚫 !disable [plugin] [room_id]**
|
|
Disable a plugin for specific room
|
|
|
|
**✅ !enable [plugin] [room_id]**
|
|
Enable a plugin for specific room
|
|
|
|
**⚙️ !rehash**
|
|
Reload configuration
|
|
|
|
### Cron System
|
|
|
|
**⏱️ !cron [add|remove] [room_id] [cron_entry] [command]**
|
|
Schedule automated commands using cron syntax:
|
|
- `add` - Add a new cron job
|
|
- `remove` - Remove an existing cron job
|
|
|
|
## Full AI Command List
|
|
|
|
The bot includes over 100 specialized AI commands covering various domains:
|
|
|
|
**Creative & Writing**: !write, !script, !author, !poem, !rap, !story, !comic, !motiv, !debate
|
|
|
|
**Technical**: !tech, !dev, !py, !php, !regex, !math, !web, !it, !security, !ai, !ml, !data, !game
|
|
|
|
**Professional**: !seo, !recruit, !coach, !devrel, !sales, !ceo, !mgmt, !startup, !invest, !fin
|
|
|
|
**Educational**: !tutor, !teach, !edu, !acad, !hist, !astro, !chem, !math, !psych
|
|
|
|
**Lifestyle**: !fit, !health, !diet, !cook, !travel, !art, !music, !film, !gaming
|
|
|
|
**Specialized**: !legal, !medical, !realest, !auto, !fashion, !design, !interior
|
|
|
|
And many more! Use `!help` in chat to see the complete list with descriptions.
|
|
|
|
## Configuration
|
|
|
|
The bot uses a TOML configuration file (`funguy.conf`) for settings:
|
|
- `admin_user` - Matrix user ID with admin privileges
|
|
- `prefix` - Command prefix (default: "!")
|
|
- Plugin-specific settings in `plugins/ai.json` for AI commands
|
|
|
|
## Dependencies
|
|
|
|
- Python 3.7+
|
|
- simplematrixbotlib
|
|
- Various AI/ML services (Stable Diffusion, Ollama, etc.)
|
|
- Database support (SQLite)
|
|
- External APIs (OpenWeatherMap, Urban Dictionary, YouTube)
|
|
|
|
## Troubleshooting
|
|
|
|
- Ensure all environment variables are set correctly
|
|
- Check that required services are running (Stable Diffusion API, Ollama, etc.)
|
|
- Verify plugin permissions and whitelist settings
|
|
- Check logs for detailed error information
|
|
|
|
## Support
|
|
|
|
Join our Matrix room for support and community:
|
|
[Self-hosting | Security | Sysadmin | Homelab | Programming](https://matrix.to/#/#selfhosting:mozilla.org)
|
|
|
|
## Credits
|
|
|
|
**🧙♂️ Creator & Developer**: HB (@hashborgir:mozilla.org)
|
|
**🍄 Funguy Bot** - Created during recovery from cervical spinal surgery
|
|
|
|
---
|
|
|
|
*Note: This bot was created rapidly and may contain bugs. Please report issues and contribute improvements!*
|