Meet Cardinal.

Cardinal is a Python Twisted IRC bot with a focus on ease of development. It features reloadable asynchronous plugins, Python decorators for commands and IRC events, simple persistent JSON data storage, and a well-documented API.

You can join #cardinal on the DarkScience IRC network for questions or support. (irc.darkscience.net/+6697 — SSL required)

What can Cardinal do?

Anything, if you're creative! Cardinal does come with some plugins to get you started...

Fetching URL titles
Wolfram Alpha calculations
Wikipedia definitions
Urban Dictionary definitions
Movie and TV show lookups
Weather reports
Reminders
Google searches
Now playing w/ Last.fm
Stock ticker
sed-like substitutions
... and more!

But the best part of Cardinal is how easy it is to add more!

Basic Usage

Configuration

Copy the config/config.example.json file to config/config.json (you can use another filename as well, such as config.freenode.json if you plan to run Cardinal on multiple networks).
Copy plugins/admin/config.example.json to plugins/admin/config.json and add your nick and vhost in order to take advantage of admin-only commands (such as reloading plugins, telling Cardinal to join a channel, or blacklisting plugins within a channel).

Running

Cardinal is run via Docker. To get started, install Docker and docker-compose.

If your config file is named something other than config/config.json, you will need to create a docker-compose.override.yml file like so:

version: "2.1"
services:
    cardinal:
        command: config/config_file_name.json

To start Cardinal, run docker-compose up -d. To restart Cardinal, run docker-compose restart. To stop Cardinal, run docker-compose down.

Writing Plugins

Cardinal was designed with ease of development in mind.

from cardinal.decorators import command, help

class HelloWorldPlugin:
    @command(['hello', 'hi'])
    @help("Responds to the user with a greeting.")
    @help("Syntax: .hello")
    def hello(self, cardinal, user, channel, msg):
        nick, ident, vhost = user
        cardinal.sendMsg(channel, "Hello {}!".format(nick))

entrypoint = HelloWorldPlugin

Cardinal also offers a lightweight database API. Visit the wiki for detailed information.

Contributing

Cardinal is a public, open-source project, licensed under the MIT License. Anyone may contribute.

When submitting a pull request, you may add your name to the CONTRIBUTORS file.

johnmaguire / Cardinal

readme