github/context-mod
1
1
Fork 0
mirror of https://github.com/FoxxMD/context-mod.git synced 2026-01-12 23:28:08 -05:00
Code Issues Packages Projects Releases Wiki Activity
Files
0.10.13
context-mod/docs
History

README.md

Documentation

Table of Contents

Getting Started

Review at least the How It Works and Concepts below, then:

How It Works

Where possible Context Mod (CM) uses the same terminology as, and emulates the behavior, of automoderator so if you are familiar with that much of this may seem familiar to you.

Diagram

Expand the section below for a simplified flow diagram of how CM processes an incoming Activity. Then refer the text description of the diagram below as well as Concepts for descriptions of individual components.

Diagram

Flow Diagram

CM's lifecycle looks like this:

1) A new event in your subreddit is received by CM

The events CM watches for are configured by you. These can be new modqueue/unmoderated items, submissions, or comments.

2) CM sequentially processes each Run in your configuration

A Run is made up of a set of Checks

3) CM sequentially processes each Check in the current Run

A Check is a set of:

  • One or more Rules that define what conditions should trigger this Check
  • One or more Actions that define what the bot should do once the Check is triggered

4) Each Check is processed, in order, until a Check is triggered

In CM's default configuration, once a Check is triggered no more Checks will be processed. This means all subsequent Checks in this Run (in the order you listed them) are skipped.

5) All Actions from the triggered Check are executed

After all Actions from the triggered Check are executed CM begins processing the next Run

6) Rinse and Repeat from #3

Until all Runs have been processed.

Concepts

Core, high-level concepts regarding how CM works.

Runs

A Run is made up of a set of Checks that represent a group of related behaviors the bot should check for or perform -- that are independent of any other behaviors the Bot should perform.

An example of Runs:

  • A group of Checks that look for missing flairs on a user or a new submission and flair accordingly
  • A group of Checks that detect spam or self-promotion and then remove those activities

Both group of Checks are independent of each other (don't have any patterns or actions in common). Learn more about using Runs and Flow Control to control how CM behaves.

Checks

A Check is the main logical unit of behavior for the bot. It is equivalent to "if X then Y". A Check is comprised of:

  • One or more Rules that are tested against an Activity
  • One of more Actions that are performed when the Rules are satisfied

A Run can be made up of one or more Checks that are processed in the order they are listed in the Run.

Once a Check is triggered (its Rules are satisfied and Actions performed) all subsequent Checks are skipped.

Some other important concepts regarding Checks:

  • All Checks have a kind (defined in the configuration) that determine if they should run on Submissions or Comments
  • Checks have a condition property that determines when they are considered triggered
    • If the condition is AND then ALL of their Rules must be triggered for the Check to be triggered
    • If the condition is OR then if ANY Rules is triggered triggered then the Check is triggered

Examples of different types of Checks can be found in the subreddit-ready examples.

Rule

A Rule is some set of criteria (conditions) that are tested against an Activity (comment/submission), a User, or a User's history. A Rule is considered triggered when the criteria for that rule are found to be true for whatever is being tested against.

There are generally three main properties for a Rule:

  • Criteria -- The conditions/values you want to test for.
  • Activities Window -- If applicable, the range of activities that the criteria will be tested against.
  • Rule-specific options -- Any number of options that modify how the criteria are tested.

CM has different Rules that can test against different types of behavior and aspects of a User, their history, and the Activity (submission/common) being checked.

Available Rules

Find detailed descriptions of all the Rules, with examples, below:

Rule Set

A Rule Set is a "grouped" set of Rules with a trigger condition specified.

Rule Sets can be used interchangeably with other Rules and Rule Sets in the rules list of a Check.

They allow you to create more complex trigger behavior by combining multiple rules into one "parent rule".

It consists of:

  • condition -- Under what condition should the Rule Set be considered triggered?
    • AND -- ALL Rules in the Rule Set must trigger in order for the Rule Set to trigger.
    • OR -- ANY Rule in the Rule Set that is triggered will trigger the whole Rule Set.
  • rules -- The Rules for the Rule Set.

Example

YAML

condition: AND
# rules are an array
rules:
 - aRule

JSON

{
  "condition": "AND",
  "rules": [
    // all the rules go here
  ]
}

Rule Set Examples

Action

An Action is some action the bot can take against the checked Activity (comment/submission) or Author of the Activity. CM has Actions for most things a normal reddit user or moderator can do.

Available Actions

  • Remove (Comment/Submission)
  • Flair (Submission)
  • User Flair (Submission/Comment)
  • Ban (User)
  • Approve (Comment/Submission)
  • Comment (Reply to Comment/Submission)
  • Lock (Comment/Submission)
  • Report (Comment/Submission)
  • UserNote (User, when /r/Toolbox is used)

For detailed explanation and options of what individual Actions can do see the links in the actions property in the schema.

Filters

Runs, Checks, Rules, and Actions all have two additional (optional) criteria "tests". These tests behave differently than rule/check triggers in that:

  • When they pass the thing being tested continues to process as usual
  • When they fail the thing being tested is skipped, not failed.

For Runs, Checks, and Actions skipping means that the thing is not processed. The Action is not run, the Check is not triggered.

In the context of Rules (in a Check) skipping means the Rule does not get run BUT it does not fail. The Check will continue processing as if the Rule did not exist. However, if ALL Rules in a Check are skipped then the Check does "fail" (is not triggered).

Available Filters

Item Filter (itemIs)

This filter will test against the state of the Activity currently being run. Some criteria available to test against IE "Is the activity...":

  • removed
  • nsfw
  • locked
  • stickied
  • deleted
  • etc...

The itemIs filter is made up of an array (list) of State criteria objects. All criteria in the array must pass for this filter to pass.

There are two different State criteria depending on what type of Activity is being tested:

Author Filter (authorIs)

This filter will test against the Author of the Activity currently being run. Some criteria available to test against:

  • account age
  • comment, link, and total karma
  • subreddit flair text/css
  • name
  • User Notes
  • verified
  • etc...

The authorIs filter is made up two (optional) lists of AuthorCriteria criteria objects that define how the test behaves:

  • include list -- If any AuthorCriteria from this list passes then the authorIs test passes
  • exclude list -- If any AuthorCriteria from this list does not pass then the authorIs test passes. Note: This property is ignored if include is also present IE you cannot use both properties at the same time.

Refer to the app schema for AuthorCriteria for all available properties to test against.

Some examples of using authorIs can be found in the Author examples.

Configuration And Usage

Common Resources

Technical information on recurring, common data/patterns used in CM.

Activities window

Most Rules must define the range of Activities (submissions and/or comments) that will be used to check the criteria of the Rule. This range is defined wherever you see a window property in configuration.

Refer to the Activities Window documentation for a technical explanation with examples.

Thresholds and Comparisons

Most rules/filters have criteria that require you to define a specific condition to test against. This can be anything from repeats of activities to account age.

In all of these scenarios the condition is defined using a subset of comparison operators (very similar to how automoderator does things).

Available operators:

  • < -- less than => 5 < 6 => 5 is less than 6
  • > -- greater than => 6 > 5 => 6 is greater than 5
  • <= -- less than or equal to => 5 <= 5 => 5 is less than or equal to 5
  • >= -- greater than or equal to => 5 >= 5 => 5 is greater than or equal to 5

In the context of a rule/filter comparison you provide the comparison omitting the value that is being tested. An example...

The RepeatActivity rule has a threshold comparison to test against the number of repeat activities it finds

  • You want the rule to trigger if it finds 4 or more repeat activities
  • The rule would be configured like this "threshold": ">= 4"

Essentially what this is telling the rule is threshold: "x >= 4" where x is the largest repeat of activities it finds.

Other Comparison Types

Other than comparison numeric values there are two other values that can be compared (depending on the criteria)

Percentages

Some criteria accept an optional percentage to compare against:

"threshold": "> 20%"

Refer to the individual rule/criteria schema to see what this percentage is comparing against.

Durations

Some criteria accept an optional duration to compare against:

"threshold": "< 1 month"

The duration value compares a time range from now to duration value time in the past.

Refer to duration values in activity window documentation as well as the individual rule/criteria schema to see what this duration is comparing against.

Image Comparisons

ContextMod implements two methods for comparing image content, perceptual hashing and pixel-to-pixel comparisons. Comparisons can be used to filter activities in some activities.

See image comparison documentation for a full reference.

Best Practices

Named Rules

All Rules in a subreddit's configuration can be assigned a name that can then be referenced from any other Check.

Create general-use rules so they can be reused and de-clutter your configuration. Additionally, CM will automatically cache the result of a rule so there is a performance and api usage benefit to re-using Rules.

See ruleNameReuse.json5 for a detailed configuration with annotations.

Check Order

Checks are run in the order they appear in your configuration, therefore you should place your highest requirement/severe action checks at the top and lowest requirement/moderate actions at the bottom.

This is so that if an Activity warrants a more serious reaction that Check is triggered first rather than having a lower requirement check with less severe actions triggered and causing all subsequent Checks to be skipped.

  • Attribution >50% AND Repeat Activity 8x AND Recent Activity in 2 subs => remove submission + ban
  • Attribution >20% AND Repeat Activity 4x AND Recent Activity in 5 subs => remove submission + flair user restricted
  • Attribution >20% AND Repeat Activity 2x => remove submission
  • Attribution >20% AND History comments <30% => remove submission
  • Attribution >15% => report
  • Repeat Activity 2x => report
  • Recent Activity in 3 subs => report
  • Author not vetted => flair new user submission

Rule Order

The ordering of your Rules within a Check/RuleSet can have an impact on Check performance (speed) as well as API usage.

Consider these three rules:

  • Rule A -- Recent Activity => 3 subreddits => last 15 submissions
  • Rule B -- Repeat Activity => last 3 days
  • Rule C -- Attribution => >10% => last 90 days or 300 submissions

The first two rules are lightweight in their requirements -- Rule A can be completed in 1 API call, Rule B potentially completed in 1 Api call.

However, depending on how active the Author is, Rule C will take at least 3 API calls just to get all activities (Reddit limit 100 items per call).

If the Check is using AND condition for its rules (default) then if either Rule A or Rule B fail then Rule C will never run. This means 3 API calls never made plus the time waiting for each to return.

It is therefore advantageous to list your lightweight Rules first in each Check.

Caching

ContextMod implements caching functionality for:

  • author history (window criteria in rules)
  • authorIs results
  • content that uses wiki pages (on Comment/Report/Ban Actions)
  • and User Notes

All of these use api requests so caching them reduces api usage.

Cached results can be re-used if the criteria in configuration is identical to a previously cached result. So...

  • author history cache results are re-used if window criteria on a Rule is identical to the window on another Rule IE always use 7 Days or always use 50 Items for absolute counts.
  • authorIs criteria is identical to another authorIs elsewhere in configuration..
  • etc...

Re-use will result in less API calls and faster Check times.

PROTIP: You can monitor the re-use of cache in the Cache section of your subreddit on the web interface. See the tooltips in that section for a better breakdown of cache statistics.

FAQ

TODO

Reference in New Issue View Git Blame Copy Permalink