Auto Moderator

A Flarum extension.

Core Concept

The core idea is as follows:

When a user meets criteria X, do Y. When a user no longer meets criteria X, do Z.

Let's define some key terms:

• Criteria Group: The set of all criteria that a user meets.
• Criteria (singular Criterion): An arbitrary set of conditions. Criteria are paired with triggers and actions, and are composed of:
  • Metrics: A numerical condition. For example, post count or number of likes received. A criterion could require a range/minimum/maximum of metrics.
  • Requirement: An abstract boolean condition. For example, not being suspended, or having an email that matches a certain regex.
• Action: Something that happens automatically when a criteria is met or lost. This could include anything from adding/removing a group to sending an email to suspending a user.
• Triggers: A set of events that would cause a user's criteria groups to be reevaluated. These are associated with metrics and Requirements. LoggedIn is automatically a trigger for all criteria.

This makes for an extremely powerful extension. Furthermore, since extensions can add their own metrics, requirements, and actions, this extension can automate away a lot of moderation. Beyond the examples listed below, some things that could be possible are:

• Automating assignment of achievements / badges
• Sending emails/notifications to users when they reach thresholds (or just when they register)
• Establishing a system of "trust levels" like Discourse
• Onboard/offboard users to/from external systems when they receive/lose certain group membership
• And a bunch more! The possibilities are endless.

Evaluation

When a trigger event occurs:

• All metrics will be calculated for the relevant user (what is the numerical value of the metric?)
• All requirements will be calculated for the relevant user (does the user satisfy each of the requirements?)
• The user's new criteria group will be computed and diffed against the user's current criteria group. The two sets will be diffed. Only criteria triggered by the event will be adjusted.
• Actions will be executed for any gained and lost criteria.

You can also use the php flarum criteria:recalculate console command to recalculate criteria for all users. Note that this will be quite slow, and shouldn't usually be done.

Examples

Example 1: Group Management

Criteria: Users that receive 50 or more likes and have started at least 10 discussions should placed in the "Active" group.

Here, the metrics are "received 50 or more likes" and "have started at least 10 discussions". Unsurprisingly, they come with the triggers (PostWasLiked, PostWasUnliked) and (Discussion\Started) respectively.

The actions are:

• When the criteria is met, add the user to the "Active" group
• When the criteria is lost, remove the user from the "Active" group

Example 2: Suspension

Criteria: If a user gets 15 warnings or more and is not an admin, suspend them.

Here, the metrics are "gets 15 warnings or more" and the requirements are "is not an admin". The triggers would be a new warning for the metric. The requirement has no triggers.

The actions are:

• When the criteria is met, suspend them
• When the criteria is lost, unsuspend them

Example 3: Auto Activation

Criteria: If a user's email matches a regex, activate their email.

The requirement is "a user's email matches a regex". The triggers are saving a user.

The actions are:

• When the criteria is met, auto activate the user's email
• When the criteria are not met, don't

Example 4: Default Group

Criteria: Add a user to a group

There are no metrics or requirements, so this will be applied to all users on login.

The actions are:

• Add all users to a group on login

  Screenshots

Metrics vs Requirements

It's clear to see that any metric could be represented as a Requirement.

• A requirement must be specific. "More than 50 received likes" could be a requirement. However, metrics can allow for any range of values.
• Metrics can be stored and used for other purposes. For example, a planned feature is combining all metrics to provide a "reputation" score.

Settings

Requirements and actions can require settings in the admin dashboard. For example:

• The "add to group" action takes the group ID as a setting
• The "suspend" action takes the number of days and whether the suspension is indefinite as settings
• The "email matches regex" requirement takes the regex as a setting

Extensibility

This extension is extremely flexible. It can be considered a framework for automoderation actions.

Extensions can use the Askvortsov\AutoModerator\Extend\AutoModerator extender to add:

• Action drivers
• Metric drivers
• Requirement drivers

You should look at the source code of the default drivers for examples. They're fairly exhaustive of what's offered.

If your extension adds action or requirement drivers that consume settings, you have 2 options:

• Provide translation keys for the settings you need in the driver's availableSettings method. This is very easy, but also very restrictive. You can only use strings, and can't add any restrictions or UI.
• You can declare a settings form component for your driver. See js/src/admin/components/SuspendSelector for an example. The component should take a settings stream as this.attrs.settings. The contents of the stream should be an object that maps setting keys to values. The component is responsible for updating the stream on input. You can register a form component by adding its class to app.autoModeratorForms[DRIVER CATEGORY][TYPE], where DRIVER CATEGORY is "action" or "requirement", and TYPE is the type string you registered your driver with in extend.php. See js/src/admin/index.js for the underlying data structure and examples.

TODO:

• Add support for more metrics:
  • Posts read
  • Time spent on forum
  • Days visited
  • Days since account creation
  • Etc
• Add support for dated metrics (discussions created in the past X days)
• Introduce metric "weights", sum together to calculate a reputation. Make that reputation available as a metric.
• Develop a data collection extension, which could cache things such as like counts, to improve performance on large forums
• Investigate criterion "listeners": can we generalize stuff like removing links from posts of users without certain groups?

Contributions

Contributions and PRs are welcome! Any PRs adding new drivers should come with unit tests (like with all existing drivers).

Compatibility

Compatible starting with Flarum 1.0.

Installation

composer require askvortsov/flarum-auto-moderator:*

Updating

composer update askvortsov/flarum-auto-moderator

Links

• Packagist
• Github
• Discuss

v0.1.1

Small update, and no one's using it yet, but why not.

• Allow selecting icons for criteria.
• Generate criteria color

These changes make the automoderator page more colorful!

• Fix duplicate managed groups
• Make the criterion page a tiny bit prettier with some slight tweaks

luceos What happens if a depending extension is no longer installed.

All drivers (actions, metrics, and requirements) supply a list of extension dependencies. If those dependencies aren't met, you won't be able to create new criteria with those drivers. Existing criteria will be considered invalid, and gain/loss actions won't be executed while those criteria use drivers with missing dependencies. There will also be an error in the admin dashboard. Same goes if settings are missing / don't pass validation.

The error messages aren't ideal (they don't say which extension / which driver exactly has validation issues), but using them and common sense, admins should be able to figure it out. Plus this is something that can be improved in the future.

Pollux I suggest including more calculations, such as differences, ratios, and even mathematical functions. This could be very helpful in putting things in perspective.

Hmm, I wonder if this could be implemented as a requirement? All that would be needed is for the metric values to be provided to requirements. Then, a requirement could take such a string like you provided ($warnings > 2 * lg($posts)) as a setting, parse it out (inventing mini programming languages is fun!), and validate against the provided metric values.

Right now I need to focus on Flarum CLI, so this feature is going in the "eventual todo" list alongside content moderation.

For content moderation, the most trivial solution would be to allow "listeners". So if the user satisfies criterion X, a function would run on some events. This would handle stuff like FoF filter, but the listeners would have to be quite bulky.

What if metrics and requirements could be conceptually applied to various models? Then, we could create "rules" for members of criteria.

For example, take creation of posts.

If a user satisfies metrics M1 and requirements R1, and the post satisfies metrics M2 and requirements R2, do something to the post.

The part I'm struggling to reconcile is actions vs that "something". Anyone who has done hardware development can recognize that actions happen "on the edge" of group membership qualification:

(let one of those waveforms be qualification. When qualification state changes, on gain / on loss actions are executed)

On the other hand, this "something" for content moderation happens while qualification is active (users currently qualifying for a criteria would be affected).

Another way to consider this is that content created by users could be "mutated" on creation. This could be a generalization of the above "listener" idea that decouples the "when" (by having metrics and requirements for models beyond User) from the "what" (mutations applied to posts, discussions, messages, etc before they are created/edited).

Then, there's the question of whether "mutations" and "actions" are isomorphic: does it matter that "actions" are triggered on state change, and "mutations" modify models as they are created / edited? I feel like yet again, the "what" should be decoupled from the "when", and these should be treated as isomorphic. But more thinking is needed here.

Pollux In this case, shouldn't we retroactively auto-flag all previous posts that contain a link?

Hmm... If we lived in functional programming land, our "action" would be a pure function that takes a model (in this case a post) and returns a model instance with some modifications. While this would be clean and beautiful, PHP does not support something like this.

On the bright side, this means that an action could do anything. For example, instead of just mutating the post, it could do something to the post's author, or all posts of the post's author, or etc.

010101 gets 5 likes, they get a badge?

Yep, that's one possible application.

In theory, it's an abstraction of executing actions in response to events if certain criteria are met (or at least that's where I want to grow it in the future).