automod brief docs/context

automod/README.md

@@ -0,0 +1 @@
+See `./doc.go`

automod/doc.go

@@ -1,8 +1,9 @@
 // Auto-Moderation rules engine for anti-spam and other moderation tasks.
 //
-// The code in this package includes an "engine" which processes atproto commit events (and identity updates), maintains caches and counters, and pushes moderation decisions to an external mod service (eg, appview). A framework for writing new "rules" for the engine to execute are also provided.
+// This package (`github.com/bluesky-social/indigo/automod`) contains a "rules engine" to augment human moderators in the atproto network. Batches of rules are processed for novel "events" such as a new post or update of an account handle. Counters and other statistics are collected, which can drive subsequent rule invocations. The outcome of rules can be moderation events like "report account for human review" or "label post". A lot of what this package does is collect and maintain caches of relevant metadata about accounts and pieces of content, so that rules have efficient access to this information.
 //
-// It does not provide label API endpoints like queryLabels; see labelmaker for a self-contained labeling service.
+// A primary design goal is to have a flexible framework to allow new rules to be written and deployed rapidly in response to new patterns of spam and abuse. Some examples rules are included in the `automod/rules` package, but the expectation is that some real-world rules will be kept secret.
 //
 // Code for subscribing to a firehose is not included here; see cmd/hepa for a complete service built on this library.
+// The `hepa` command is an example daemon which integrates this rules engine in to a stand-alone service.
 package automod

cmd/hepa/README.md

@@ -1,7 +1,22 @@
 
-HEPA
+hepa
 ====
 
 This is a simple auto-moderation daemon which wraps the automod package.
 
 The name is a reference to HEPA air filters, which help keep the local atmosphere clean and healthy for humans.
+
+Available commands, flags, and config are documented in the usage (`--help`).
+
+Current features and design decisions:
+
+- all state (counters) and caches stored in Redis
+- consumes from Relay firehose; no backfill functionality yet
+- which rules are included configured at compile time
+- admin access to fetch private account metadata, and to persist moderation actions, is optional. it is possible for anybody to run a `hepa` instance
+
+This is not a "labeling service" per say, in that it pushes labels in to an existing moderation service, and doesn't provide API endpoints or label streams. see `labelmaker` for a self-contained labeling service.
+
+Performance is generally slow when first starting up, because account-level metadata is being fetched (and cached) for every firehose event. After the caches have "warmed up", events are processed faster.
+
+See the `automod` package's README for more documentation.