Skip to content

Plan Configuration#

This page describes configurations for plan, one run of the tool - setting processing rules through the configuration file (also referred to as Plan).

Some rules contain fields that worth a paragraph to explain, but if we put all the details into this single page, it will be too long. So here we just list all the available rules with a brief description, and leave the details in other corresponding pages.

The example configuration is written in yaml format (you may want to learn about yaml's syntax), but you can also use other supported formats like .toml, .ini, .json. In this page we'll use yaml format.

Currently, the tool only support processing Twitter accounts ("user_plan") (blocking accounts for example), but we left a place for processing tweets in the future (like deleting embarrassing past tweets).

How To Write A Plan#

One plan contains at most three types of rules, together they construct a processing pipeline:

  1. Source rules - Where to get source candidates (Twitter accounts or tweets)?
  2. Filter rules - (optional) What type(s) of candidates should be chosen from the source to take actions?
  3. Action rules - What actions to take on candidates that trigger filter rules?

One plan configuration file can contain several plans (under field plans). We tried to make plan configuration look natural, one of the simplest is:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
plans:
  # Name (explain) of this plan
  - user_plan: Do block on three users depend on their follower number
    from:
      # '@Alice', '@Bob' and '@Charlie'
      - names: [ 'Alice', 'Bob', 'Charlie' ]
    that:
      # who has less than 10 (0~9) followers
      - follower:
          less_than: 10
    do:
      # block them
      - block

The syntax structure is:

1
2
3
4
5
6
7
8
plans:
  [ - <plan> ]

# <plan>
<plan_type>: <string>
from: [ <source_rule> ]
that: [ <filter_rule> ]
do: [ <action_rule> ]

As the filter rule is optional, we can directly take action on every user in the source:

1
2
3
4
5
6
plans:
  - user_plan: Again
    from:
      - names: [ 'Alice', 'Bob', 'Charlie' ]
    do:
      - block

How Plans Are Executed#

Plans are executed in the order they are defined in the configuration file, one by one i.e. in parallel (so plans won't compete for limited API invocation resources).

For a single plan:

  1. The source rules are executed first, results are default union together as one final set.
  2. Users in the source set are judged by a chain of filter rules, results are default ORed together, so if any filter rule is matched, that user will be considered as the target.
  3. The action rules are executed on the target set of users, in the order they are defined in the configuration file.

In natural language, the summary is: Run all action_rules on targets from any source_rule that trigger any filter_rule.

You can arrange more complex but flexible execution order by nesting rule sets below.

Rule Sets#

Rule sets help us create a layer of abstraction by converting a "scattered" SET of rules of the same type into a single result. We can think of one single ruleset as a single rule of that type, so that we can write nested "trees" of rules with more "dynamic" judgment capabilities.

For now, we consider that only filter rules are worth writing various (user-usable) rule sets.

Rule Sets Inside Plan#

In fact, plans use rule sets internally to handle the execution and judgments of the rules contained in themselves, and there are currently two plan-specific rule sets that are not directly available to users:

  1. aggregating the candidate targets generated by all source rules into a single data stream and removing duplicate candidate targets.
  2. aggregating the results of all action rules into a result set.

As described in the plan execution part above, the plan also uses the any_of filter rule set to decide a final single filter result of all filter rules as a basis for determining whether to process candidate targets.

any_of (filter rule set)#

Logical OR:

  • If any filtering rule is triggered, the rule set is considered to be triggered.
  • Only if none of rules are triggered, the rule set is not triggered.

all_of (filter rule set)#

Logical AND:

  • Only if all filter rules are triggered, the rule set is considered to be triggered.
  • If any rule is not triggered, the rule set is not triggered.

User Source Rules#

ids#

1
2
from:
  - ids: [ 123456789, 987654321 ]

Specify users with a list of user id as source.

Details

names#

1
2
from:
  - names: [ 'Alice', 'Bob', 'Charlie' ]

Specify users with a list of username (also called "handle" by Twitter) as source. Usernames are easy to get, so this rule is pretty good for your first try with a handful usernames. Like the user id, manually typing down or parsing amount of usernames is awkward and not recommended.

User Filter Rules#

follower#

1
2
3
4
5
6
that:
  - follower:
      less_than: 10
      more_than: 5

  - follower_less_than: 10

Follower count itself doesn't tell much, but it's good to have a rule aiming at it. The follower-less-than is a shortcut for follower: { less_than: n }.

Details

following#

1
2
3
4
5
6
that:
  - following:
      less_than: 10
      more_than: 5

  - following_more_than: 5

Correspondingly... the following number filter rule.

Details

created#

1
2
3
4
5
6
that:
  - created:
      before: 2022-12-01 01:01:01
      after: 2022-01-01T01:01:01Z

  - created_after: 2022-01-01

The creation time of an account is a reflection of how much the Twitter platform trusts that user, and although the Twitter report&suspend mechanism has been unreliable, it is still working. In general, the longer the account is created, the more we "trust" that the user is a human rather than a bot.

Details about time type values

created_within_days#

1
2
that:
  - created_within_days: 90

Another flexible account creating time judging rule.

profile_text_matches#

1
2
that:
  - profile_text_matches: hate

It's actually check three parts of texts, ont only the profile. Check if any text below matches configured regular expression:

  1. user's name (the name you see aside the avatar, without "@")
  2. user's description (also the profile)
  3. pinned tweet's text

Details about regular expression

Make sure you've read tips about how to build a proper match.

following_count_ratio#

1
2
3
4
5
6
7
8
9
that:
  - following_count_ratio:
      # 1 follower / 10 following 
      more_than: 0.1
      # 10 follower / 1 following, wow pretty famous
      less_than: 10

  # 5 follower / 100 following
  - following_count_ratio_less_than: 0.05

What do you think when you see a user who has a dozen or single digit followers, but follows thousands of people? There's a good chance on just that this person only read and does not talk or interact with others often. But there is a pretty small possibility that this account is a hook or marker. When one user switches from public to protected state, the existing followers can still see the updates, this is the meaning of early following I can think of.

tweet_count#

1
2
3
4
5
6
that:
  - tweet_count:
      more_than: 10
      less_than: 1000

  - tweet_count_less_than: 1000

Low tweet count (including retweets) means the user doesn't post much, leave a rule for it.

User Action Rules#

block#

1
2
do:
  - block: {}

Block users that trigger the filter rules.