stapel-moderation 0.1.0__tar.gz

stapel_moderation-0.1.0/CONFIG.MD

@@ -0,0 +1,126 @@
+# CONFIG.MD — stapel-moderation
+
+Config registry for **stapel-moderation** (`static-scaffold-and-config.md`
+§2). One row per configuration key the module reads, its **source** (`env` =
+the process environment / the `STAPEL_MODERATION` settings dict), what it is
+for, whether it is required, and its default.
+
+All keys are read through `moderation_settings`
+(`stapel_moderation.conf.AppSettings`, namespace `STAPEL_MODERATION`).
+Resolution order per key: `settings.STAPEL_MODERATION` dict → a flat Django
+setting of the same name → environment variable → the default below.
+
+Two notes on the `env` column, which is the manifest's vocabulary for "the
+process environment or the `STAPEL_MODERATION` settings dict" rather than a
+claim that every key is settable from a shell:
+
+- the **structured** keys (`TARGET_TYPES`, `REASONS`, `RULES`,
+  `SANCTION_LADDER`, `BLACKLIST_KINDS`, and the three `*_SCHEDULE` dicts)
+  carry shapes an environment string cannot express, so in practice they are
+  set in the settings dict and `AppSettings` never reads them from the
+  environment;
+- `SCREENER` is the module's only `import_strings` key. It names a callable
+  the process imports and runs, so it is **env-closed by policy** — a stray
+  export in an entrypoint must not get to choose which classifier decides
+  what gets published.
+
+## stapel-moderation
+
+### Registries (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| TARGET_TYPES | env | The flagship merge-registry: `{target_type: policy dict or None}`. Built-ins are EMPTY — the module ships knowing no targets, so a host declares what may be moderated. `None` removes a type. Checks `E001`–`E006` police it; `E004` refuses a policy with no `content_function`. | no | `{}` |
+| REASONS | env | Complaint taxonomy merged OVER a non-empty built-in set (spam, offensive, harassment, counterfeit, fraud, illegal, adult, personal_data, off_platform_payment, wrong_category, other). `None` removes. System reasons cannot be removed. | no | `{}` |
+| RULES | env | Deterministic pre-LLM screening rules, `{code: {pattern, decision, severity, reason_code, applies_to}}`. Ships EMPTY: a shipped keyword list is somebody else's speech policy. | no | `{}` |
+
+### Target policy defaults (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| GATE_DEFAULT | env | `pre` (target waits for a verdict) or `post` (target is live and can be taken down), for types that do not say. | no | `post` |
+
+### Screening (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| SCREENER | env | Dotted path to `(case, content, *, reports) -> ScreeningResult`. The seam a host ML provider plugs into instead of forking. Env-closed by `import_strings` policy. | no | `stapel_moderation.screening.default_screener` |
+| SCREEN_ENABLED | env | Master switch for the automatic stage. Off = every case goes straight to a person — the honest configuration with no model available. | no | `True` |
+| SCREEN_MAX_ATTEMPTS | env | Retries of the `moderation.screen` comm-Task before it parks FAILED. | no | `3` |
+| SCREEN_DEADLINE_SECONDS | env | Task deadline; `sweep_tasks` drops overdue ones. | no | `900` |
+| SCREEN_TIMEOUT_SECONDS | env | Timeout of the `llm.complete` call. Deliberately not core's 5s `FUNCTION_TIMEOUT` — a completion never finishes in five seconds. | no | `60` |
+| CONTENT_TIMEOUT_SECONDS | env | Timeout of a target's `content_function`. | no | `10` |
+| LLM_MODEL | env | Size passed to `llm.complete`: `small`/`medium`/`large`. | no | `medium` |
+| LLM_PROVIDER | env | Provider name; empty lets `llm.complete` pick its configured default. | no | `""` |
+| LLM_CONFIDENCE_FLOOR | env | Below it the decision is forced to `needs_review` whatever the model said. | no | `0.7` |
+| ON_SCREENING_FAILURE | env | `hold` \| `approve` \| `reject` when the screener could not answer. **Closed default `hold`**: the human queue IS the fallback. Anything else prints `moderation.W001`. | no | `hold` |
+| ON_SCREENING_UNAVAILABLE | env | Same vocabulary, for "no screener configured at all". | no | `hold` |
+| AUTO_RESOLVE_STALE_QUEUE | env | Seconds after which an unreviewed QUEUED case auto-approves. `None` = never, and never is the point. A number prints `moderation.W002`. | no | `None` |
+
+### Queue (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| CLAIM_LEASE_SECONDS | env | How long a moderator's claim holds before `sweep_stale_cases` returns the case to the queue. | no | `900` |
+| MAX_PAGE_SIZE | env | Server ceiling on any keyset page. | no | `100` |
+| APPLY_ACK_TIMEOUT_SECONDS | env | Seconds to wait for a target module's optional `moderation.applied` ack. `None` = do not wait; no released consumer emits one. | no | `None` |
+
+### Evidence and the wire (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| EVIDENCE_EXCERPT_CHARS | env | Length of the content excerpt STORED with a verdict (never emitted), so a statement of reasons stays checkable after the content is gone. | no | `512` |
+| VERDICT_NOTE_WIRE_CHARS | env | Truncation of the statement of reasons that DOES ride `moderation.completed`. | no | `200` |
+
+### Media screening (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| MEDIA_SCREEN_TIER | env | Largest CDN variant width handed to the model. | no | `1024` |
+| MAX_MEDIA_PER_CASE | env | Image prompts disable the provider's prompt cache, so every media screen is paid in full — this is the price control. | no | `4` |
+| MEDIA_TRANSPORT | env | `url` (the model vendor fetches it — needs publicly reachable CDN URLs) or `data_b64` (inlined, bounded by the broker's max payload). | no | `url` |
+
+### Complaint intake (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| ALLOW_ANONYMOUS_REPORTS | env | **Closed.** Opening it makes `contact_email` mandatory and demands a captcha; without one, prints `moderation.W003`. | no | `False` |
+| REPORT_THROTTLE | env | DRF scoped rate for the report endpoint. A library cannot own `DEFAULT_THROTTLE_RATES`, so the rate lives here. `None` disables — a conscious act. | no | `20/h` |
+
+### Appeals (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| APPEAL_REQUIRES_DIFFERENT_ACTOR | env | The moderator who decided may not decide the appeal. A one-moderator team turns it off knowingly. | no | `True` |
+| APPEAL_URL_TEMPLATE | env | Template with `{case_id}` for the `appeal_url` notification variable. Empty yields `""` rather than an invented address. | no | `""` |
+
+### Sanctions (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| SANCTION_LADDER | env | `{kind: [seconds, ...]}`; the n-th sanction of a kind takes the n-th rung, the last rung repeats, `None` = permanent. | no | `{"posting_restricted": [86400, 604800, 2592000], "suspended": [604800, 2592000, None]}` |
+| BLACKLIST_KINDS | env | Which sanction kinds kill live sessions through core's cross-service user blacklist. | no | `["suspended", "banned"]` |
+| BLACKLIST_TTL_SECONDS | env | TTL of that cache key. The row stays the truth; `rearm_active_sanctions` keeps the key alive. | no | `7200` |
+
+### Scheduled work (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| SWEEP_SCHEDULE | env | crontab kwargs for `sweep_stale_cases`. | no | `{"minute": "*/5"}` |
+| REARM_SCHEDULE | env | crontab kwargs for `rearm_active_sanctions` and `expire_sanctions`. Must be well inside `BLACKLIST_TTL_SECONDS`. | no | `{"minute": "*/30"}` |
+| PURGE_SCHEDULE | env | crontab kwargs for `purge_expired_cases`. | no | `{"hour": 4, "minute": 20}` |
+| RETENTION_DAYS | env | How long a resolved case is kept — one annual reporting cycle. | no | `365` |
+| SANCTION_RETENTION_DAYS | env | Longer than the case, because the progressive ladder IS memory. | no | `1095` |
+| EXPORT_PAGE_SIZE | env | Rows per page of the projection rebuild snapshot. | no | `500` |
+
+### Notifications (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| NOTIFY_COOLDOWN_SECONDS | env | One letter per (type, recipient) per window. Forty reports about one listing must not become forty letters to its author. | no | `600` |
+
+### Tenancy (source: env)
+
+| Key | Source | Purpose | Required | Default |
+|-----|--------|---------|----------|---------|
+| WORKSPACE_SCOPED | env | Declared and closed. The capability names ship on day one so role overlays never migrate; the branch is not built, so turning this on denies loudly rather than granting silently. | no | `False` |

stapel_moderation-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Stapel contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

stapel_moderation-0.1.0/PKG-INFO

@@ -0,0 +1,221 @@
+Metadata-Version: 2.4
+Name: stapel-moderation
+Version: 0.1.0
+Summary: Target-generic moderation queue: reports, verdicts, sanctions and appeals for the Stapel framework
+License: MIT
+Project-URL: Homepage, https://github.com/usestapel/stapel-moderation
+Project-URL: Repository, https://github.com/usestapel/stapel-moderation
+Project-URL: Documentation, https://github.com/usestapel/stapel-moderation#readme
+Project-URL: Changelog, https://github.com/usestapel/stapel-moderation/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/usestapel/stapel-moderation/issues
+Keywords: django,stapel,moderation,trust-and-safety,dsa
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Django
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: stapel-core<1.0,>=0.32.0
+Provides-Extra: all
+Dynamic: license-file
+
+<!-- Generated by stapel-readme from docs/readme.md + docs/*.json. Do not edit this file; edit docs/readme.md and re-run `make readme`. -->
+
+# stapel-moderation
+
+[![CI](https://img.shields.io/github/actions/workflow/status/usestapel/stapel-moderation/ci.yml?branch=main&logo=github&label=CI)](https://github.com/usestapel/stapel-moderation/actions/workflows/ci.yml?query=branch%3Amain)
+[![coverage](https://img.shields.io/codecov/c/github/usestapel/stapel-moderation?branch=main&logo=codecov&label=coverage)](https://app.codecov.io/gh/usestapel/stapel-moderation)
+[![pypi](https://img.shields.io/pypi/v/stapel-moderation?logo=pypi&logoColor=white&label=pypi)](https://pypi.org/project/stapel-moderation/)
+[![downloads](https://static.pepy.tech/badge/stapel-moderation/month)](https://pepy.tech/project/stapel-moderation)
+[![python](https://img.shields.io/pypi/pyversions/stapel-moderation?logo=python&logoColor=white)](https://pypi.org/project/stapel-moderation/)
+[![license](https://img.shields.io/github/license/usestapel/stapel-moderation)](https://github.com/usestapel/stapel-moderation/blob/main/LICENSE)
+[![llms.txt](https://img.shields.io/badge/llms.txt-blue)](https://github.com/usestapel/stapel-moderation/blob/main/docs/llms.txt)
+
+> The fleet's single producer of moderation verdicts: one target-generic queue over listings, reviews, chat messages and profiles, keyed by an opaque (target_type, target_key) and driven by a host-registered policy per type. One Case per target however many people complain, one status vocabulary in the whole module, an append-only Verdict and an append-only CaseEvent audit trail whose mutations are FORBIDDEN by mandate declaration. Screening is a comm-Task (deterministic rules, then schema-constrained llm.complete) with a closed hold-for-a-human default when the automation cannot answer. Resolution ACTS on the target by emitting moderation.completed, which stapel-listings and stapel-reviews already consume. Sanctions carry a kind, a scope, a reason, a clock, an appeal and an audit trail, and they bite through core's cross-service user blacklist — the hook every request path already checked and nobody had ever called. Plus DSA artefacts generated from the registries: a public policy disclosure, a statement of reasons on every takedown, an acknowledgement to every complainant, and an internal appeal heard by a different moderator.
+
+Part of the [Stapel framework](https://github.com/usestapel) — composable Django apps that deploy as a monolith or as microservices without changing module code.
+
+## Install
+
+```bash
+pip install stapel-moderation
+```
+
+## At a glance
+
+| Fact | Value |
+|---|---|
+| Version | `0.1.0` |
+| Python | `>=3.11` (3.11, 3.12, 3.13) |
+| HTTP operations | 18 |
+| Config axes | 11 |
+| Usage surface | 56 |
+| Extension points | 6 |
+| Error codes | 69 |
+| Fleet dependencies | [`stapel-agent`](https://github.com/usestapel/stapel-agent) (optional) · [`stapel-auth`](https://github.com/usestapel/stapel-auth) (optional) · [`stapel-cdn`](https://github.com/usestapel/stapel-cdn) (optional) · [`stapel-core`](https://github.com/usestapel/stapel-core) · [`stapel-notifications`](https://github.com/usestapel/stapel-notifications) (optional) |
+
+## Documentation
+
+[OpenAPI](https://github.com/usestapel/stapel-moderation/blob/main/docs/schema.json) · [capabilities.json](https://github.com/usestapel/stapel-moderation/blob/main/docs/capabilities.json) · [llms.txt (for agents)](https://github.com/usestapel/stapel-moderation/blob/main/docs/llms.txt)
+
+## What this is
+
+One **moderation queue** for everything a product publishes. A listing, a
+review, a chat message and an avatar are the same kind of work item here, and
+one moderator console works all of them.
+
+Three decisions carry the whole design.
+
+**The unit of work is a Case, not a complaint.** Forty people reporting one
+listing produce forty `Report` rows hanging off **one** `Case` with
+`report_count = 40`. The system this replaced kept forty queue rows, which is
+why its moderators saw the same listing forty times and why its queue page
+read two whole tables into memory before it could show anybody anything.
+
+**There is one status vocabulary in the module: `Case.state`.** A `Report` has
+no status of its own and inherits its case's; a `Verdict` has none because it
+is an append-only fact; a `Sanction` has an orthogonal lifecycle that never
+mixes with a case state. The predecessor had three near-identical unrelated
+status enums plus two more free copies in a serializer and an HTML template,
+and they could and did disagree.
+
+**Moderation never calls a host back to mutate it.** Resolving a case emits
+`moderation.completed`, and the target module applies the verdict to itself —
+[stapel-listings](https://github.com/usestapel/stapel-listings) 0.4.0 and
+[stapel-reviews](https://github.com/usestapel/stapel-reviews) 0.2.0 already
+consume it. The action IS the fact, so a new kind of moderated thing is a
+registry entry plus a consumer in its own repository, never a branch in here.
+
+## Quick start
+
+```bash
+pip install stapel-moderation
+```
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "stapel_moderation",
+]
+
+# urls.py
+path("moderation/", include("stapel_moderation.urls"))   # -> /moderation/api/v1/...
+
+# Declare what may be moderated. The module ships knowing NO target types.
+STAPEL_MODERATION = {
+    "TARGET_TYPES": {
+        "listing": {
+            "intake_events": ["listing.submitted"],
+            "id_field": "listing_id",
+            "content_function": "listings.moderation_content",
+            "notification_types": {"content_blocked": "listing_blocked"},
+        },
+        "review": {
+            "id_field": "review_id",
+            "content_function": "reviews.moderation_content",
+        },
+    },
+}
+
+# Moderator rights are staff roles + the core mandate. No allow-list.
+STAPEL_ACCESS = {"ROLES": {
+    "moderator": {"clearance": "low", "apps": {"moderation": "mid"}},   # read the queue
+    "ts_lead":   {"clearance": "mid", "apps": {"moderation": "high"}},  # decide and sanction
+}}
+
+# The scheduled half. Without it, long suspensions stop being enforced.
+from stapel_moderation.tasks import get_moderation_beat_schedule
+CELERY_BEAT_SCHEDULE = {**get_moderation_beat_schedule()}
+```
+
+## How a case moves
+
+```
+listing.submitted ──▶ open_case ──▶ comm-Task "moderation.screen"
+                                          │
+                     ┌────────────────────┼────────────────────┐
+                     ▼                    ▼                    ▼
+                 rules hit            llm.complete         unavailable
+              (no LLM billed)      (schema-constrained)   (retry ×3, then
+                     │                    │                ON_SCREENING_FAILURE)
+                     └────────┬───────────┘                    │
+                              ▼                                ▼
+                    approved / rejected              needs_review ──▶ human queue
+                              │                                          │
+                              ▼                                          ▼
+                    emit moderation.completed  ◀──────────────  moderator verdict
+                              │                                  (+ optional sanction)
+                              ▼
+                 the target module blocks itself
+```
+
+## The switches that ship closed
+
+Every setting that trades safety for availability is off by default, and the
+three that matter print a startup warning when a host turns them on — because
+each one is *invisible at runtime*, and the predecessor system had two of them
+silently enabled for years.
+
+| setting | default | what opening it costs |
+|---|---|---|
+| `ON_SCREENING_FAILURE` | `"hold"` | `"approve"` publishes content nobody screened; `"reject"` removes content nobody screened. Either prints `W001`. |
+| `AUTO_RESOLVE_STALE_QUEUE` | `None` | A number makes unreviewed cases approve themselves on a clock. Prints `W002`. |
+| `ALLOW_ANONYMOUS_REPORTS` | `False` | Requires a contact address and a captcha; without one, a complaint flood is a denial-of-service against the queue. Prints `W003`. |
+| `APPEAL_REQUIRES_DIFFERENT_ACTOR` | `True` | Off, the moderator who decided also hears the appeal. |
+
+## What a ban actually does
+
+`Sanction` is a row with a kind, a scope, a reason, a clock, an appeal and an
+audit trail — not a boolean. Its teeth are `stapel-core`'s cross-service user
+blacklist, which DRF authentication, the middleware (twice), channels and the
+auth refresh endpoint all already check on every request, and which **had no
+producer anywhere in the fleet** until this module. Deactivating the account
+instead would touch no live session at all: `is_active` is only consulted when
+a new token is issued.
+
+Two operational consequences, stated rather than discovered:
+
+- the blacklist is a cache key with a TTL, so `rearm_active_sanctions` must be
+  scheduled — otherwise a thirty-day suspension quietly stops being enforced
+  after two hours while the row still reads `active`. `W004` says so;
+- core fails **closed** when that cache is unreachable, so a Redis outage
+  locks everybody out, not just the sanctioned. That is a property of core's
+  blacklist, and it belongs in the runbook.
+
+## Notice-and-action artefacts
+
+The compliance surface is generated from the registries, not maintained as
+prose beside them:
+
+- `GET /moderation/api/v1/policy` — public, and assembled from the reason
+  registry, the rule registry and the actual screening settings, so it cannot
+  describe a system other than the one running;
+- every takedown carries a statement of reasons and an appeal link;
+- every complainant gets an acknowledgement and, later, the outcome;
+- an appeal reopens and re-decides its case rather than filing a letter — the
+  one backward edge in the state machine exists for exactly that.
+
+## The Django admin is read-only, on purpose
+
+Moderators *are* Django staff here, so the usual "different audience" argument
+does not apply. The reason is path integrity: in the predecessor, admin bulk
+actions flipped report statuses through `queryset.update()` — no audit row, no
+timestamp, and the reviewed content was never actually hidden. A second
+resolution path existed, invisible to the audit log. Read-only registration
+makes that path impossible by construction, and `CaseEvent` is declared
+`@access.ops`, whose mutations are `FORBIDDEN` even for a superuser.
+
+## License
+
+MIT — see [LICENSE](https://github.com/usestapel/stapel-moderation/blob/main/LICENSE).
+
+---
+
+<sub>This page is assembled by `stapel-readme` from `docs/readme.md` plus the contract artifacts in `docs/`. Edit the prose in `docs/readme.md`; the badges, facts and links above and below it are generated — do not hand-edit `README.md`.</sub>

stapel_moderation-0.1.0/README.md

@@ -0,0 +1,193 @@
+<!-- Generated by stapel-readme from docs/readme.md + docs/*.json. Do not edit this file; edit docs/readme.md and re-run `make readme`. -->
+
+# stapel-moderation
+
+[![CI](https://img.shields.io/github/actions/workflow/status/usestapel/stapel-moderation/ci.yml?branch=main&logo=github&label=CI)](https://github.com/usestapel/stapel-moderation/actions/workflows/ci.yml?query=branch%3Amain)
+[![coverage](https://img.shields.io/codecov/c/github/usestapel/stapel-moderation?branch=main&logo=codecov&label=coverage)](https://app.codecov.io/gh/usestapel/stapel-moderation)
+[![pypi](https://img.shields.io/pypi/v/stapel-moderation?logo=pypi&logoColor=white&label=pypi)](https://pypi.org/project/stapel-moderation/)
+[![downloads](https://static.pepy.tech/badge/stapel-moderation/month)](https://pepy.tech/project/stapel-moderation)
+[![python](https://img.shields.io/pypi/pyversions/stapel-moderation?logo=python&logoColor=white)](https://pypi.org/project/stapel-moderation/)
+[![license](https://img.shields.io/github/license/usestapel/stapel-moderation)](https://github.com/usestapel/stapel-moderation/blob/main/LICENSE)
+[![llms.txt](https://img.shields.io/badge/llms.txt-blue)](https://github.com/usestapel/stapel-moderation/blob/main/docs/llms.txt)
+
+> The fleet's single producer of moderation verdicts: one target-generic queue over listings, reviews, chat messages and profiles, keyed by an opaque (target_type, target_key) and driven by a host-registered policy per type. One Case per target however many people complain, one status vocabulary in the whole module, an append-only Verdict and an append-only CaseEvent audit trail whose mutations are FORBIDDEN by mandate declaration. Screening is a comm-Task (deterministic rules, then schema-constrained llm.complete) with a closed hold-for-a-human default when the automation cannot answer. Resolution ACTS on the target by emitting moderation.completed, which stapel-listings and stapel-reviews already consume. Sanctions carry a kind, a scope, a reason, a clock, an appeal and an audit trail, and they bite through core's cross-service user blacklist — the hook every request path already checked and nobody had ever called. Plus DSA artefacts generated from the registries: a public policy disclosure, a statement of reasons on every takedown, an acknowledgement to every complainant, and an internal appeal heard by a different moderator.
+
+Part of the [Stapel framework](https://github.com/usestapel) — composable Django apps that deploy as a monolith or as microservices without changing module code.
+
+## Install
+
+```bash
+pip install stapel-moderation
+```
+
+## At a glance
+
+| Fact | Value |
+|---|---|
+| Version | `0.1.0` |
+| Python | `>=3.11` (3.11, 3.12, 3.13) |
+| HTTP operations | 18 |
+| Config axes | 11 |
+| Usage surface | 56 |
+| Extension points | 6 |
+| Error codes | 69 |
+| Fleet dependencies | [`stapel-agent`](https://github.com/usestapel/stapel-agent) (optional) · [`stapel-auth`](https://github.com/usestapel/stapel-auth) (optional) · [`stapel-cdn`](https://github.com/usestapel/stapel-cdn) (optional) · [`stapel-core`](https://github.com/usestapel/stapel-core) · [`stapel-notifications`](https://github.com/usestapel/stapel-notifications) (optional) |
+
+## Documentation
+
+[OpenAPI](https://github.com/usestapel/stapel-moderation/blob/main/docs/schema.json) · [capabilities.json](https://github.com/usestapel/stapel-moderation/blob/main/docs/capabilities.json) · [llms.txt (for agents)](https://github.com/usestapel/stapel-moderation/blob/main/docs/llms.txt)
+
+## What this is
+
+One **moderation queue** for everything a product publishes. A listing, a
+review, a chat message and an avatar are the same kind of work item here, and
+one moderator console works all of them.
+
+Three decisions carry the whole design.
+
+**The unit of work is a Case, not a complaint.** Forty people reporting one
+listing produce forty `Report` rows hanging off **one** `Case` with
+`report_count = 40`. The system this replaced kept forty queue rows, which is
+why its moderators saw the same listing forty times and why its queue page
+read two whole tables into memory before it could show anybody anything.
+
+**There is one status vocabulary in the module: `Case.state`.** A `Report` has
+no status of its own and inherits its case's; a `Verdict` has none because it
+is an append-only fact; a `Sanction` has an orthogonal lifecycle that never
+mixes with a case state. The predecessor had three near-identical unrelated
+status enums plus two more free copies in a serializer and an HTML template,
+and they could and did disagree.
+
+**Moderation never calls a host back to mutate it.** Resolving a case emits
+`moderation.completed`, and the target module applies the verdict to itself —
+[stapel-listings](https://github.com/usestapel/stapel-listings) 0.4.0 and
+[stapel-reviews](https://github.com/usestapel/stapel-reviews) 0.2.0 already
+consume it. The action IS the fact, so a new kind of moderated thing is a
+registry entry plus a consumer in its own repository, never a branch in here.
+
+## Quick start
+
+```bash
+pip install stapel-moderation
+```
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "stapel_moderation",
+]
+
+# urls.py
+path("moderation/", include("stapel_moderation.urls"))   # -> /moderation/api/v1/...
+
+# Declare what may be moderated. The module ships knowing NO target types.
+STAPEL_MODERATION = {
+    "TARGET_TYPES": {
+        "listing": {
+            "intake_events": ["listing.submitted"],
+            "id_field": "listing_id",
+            "content_function": "listings.moderation_content",
+            "notification_types": {"content_blocked": "listing_blocked"},
+        },
+        "review": {
+            "id_field": "review_id",
+            "content_function": "reviews.moderation_content",
+        },
+    },
+}
+
+# Moderator rights are staff roles + the core mandate. No allow-list.
+STAPEL_ACCESS = {"ROLES": {
+    "moderator": {"clearance": "low", "apps": {"moderation": "mid"}},   # read the queue
+    "ts_lead":   {"clearance": "mid", "apps": {"moderation": "high"}},  # decide and sanction
+}}
+
+# The scheduled half. Without it, long suspensions stop being enforced.
+from stapel_moderation.tasks import get_moderation_beat_schedule
+CELERY_BEAT_SCHEDULE = {**get_moderation_beat_schedule()}
+```
+
+## How a case moves
+
+```
+listing.submitted ──▶ open_case ──▶ comm-Task "moderation.screen"
+                                          │
+                     ┌────────────────────┼────────────────────┐
+                     ▼                    ▼                    ▼
+                 rules hit            llm.complete         unavailable
+              (no LLM billed)      (schema-constrained)   (retry ×3, then
+                     │                    │                ON_SCREENING_FAILURE)
+                     └────────┬───────────┘                    │
+                              ▼                                ▼
+                    approved / rejected              needs_review ──▶ human queue
+                              │                                          │
+                              ▼                                          ▼
+                    emit moderation.completed  ◀──────────────  moderator verdict
+                              │                                  (+ optional sanction)
+                              ▼
+                 the target module blocks itself
+```
+
+## The switches that ship closed
+
+Every setting that trades safety for availability is off by default, and the
+three that matter print a startup warning when a host turns them on — because
+each one is *invisible at runtime*, and the predecessor system had two of them
+silently enabled for years.
+
+| setting | default | what opening it costs |
+|---|---|---|
+| `ON_SCREENING_FAILURE` | `"hold"` | `"approve"` publishes content nobody screened; `"reject"` removes content nobody screened. Either prints `W001`. |
+| `AUTO_RESOLVE_STALE_QUEUE` | `None` | A number makes unreviewed cases approve themselves on a clock. Prints `W002`. |
+| `ALLOW_ANONYMOUS_REPORTS` | `False` | Requires a contact address and a captcha; without one, a complaint flood is a denial-of-service against the queue. Prints `W003`. |
+| `APPEAL_REQUIRES_DIFFERENT_ACTOR` | `True` | Off, the moderator who decided also hears the appeal. |
+
+## What a ban actually does
+
+`Sanction` is a row with a kind, a scope, a reason, a clock, an appeal and an
+audit trail — not a boolean. Its teeth are `stapel-core`'s cross-service user
+blacklist, which DRF authentication, the middleware (twice), channels and the
+auth refresh endpoint all already check on every request, and which **had no
+producer anywhere in the fleet** until this module. Deactivating the account
+instead would touch no live session at all: `is_active` is only consulted when
+a new token is issued.
+
+Two operational consequences, stated rather than discovered:
+
+- the blacklist is a cache key with a TTL, so `rearm_active_sanctions` must be
+  scheduled — otherwise a thirty-day suspension quietly stops being enforced
+  after two hours while the row still reads `active`. `W004` says so;
+- core fails **closed** when that cache is unreachable, so a Redis outage
+  locks everybody out, not just the sanctioned. That is a property of core's
+  blacklist, and it belongs in the runbook.
+
+## Notice-and-action artefacts
+
+The compliance surface is generated from the registries, not maintained as
+prose beside them:
+
+- `GET /moderation/api/v1/policy` — public, and assembled from the reason
+  registry, the rule registry and the actual screening settings, so it cannot
+  describe a system other than the one running;
+- every takedown carries a statement of reasons and an appeal link;
+- every complainant gets an acknowledgement and, later, the outcome;
+- an appeal reopens and re-decides its case rather than filing a letter — the
+  one backward edge in the state machine exists for exactly that.
+
+## The Django admin is read-only, on purpose
+
+Moderators *are* Django staff here, so the usual "different audience" argument
+does not apply. The reason is path integrity: in the predecessor, admin bulk
+actions flipped report statuses through `queryset.update()` — no audit row, no
+timestamp, and the reviewed content was never actually hidden. A second
+resolution path existed, invisible to the audit log. Read-only registration
+makes that path impossible by construction, and `CaseEvent` is declared
+`@access.ops`, whose mutations are `FORBIDDEN` even for a superuser.
+
+## License
+
+MIT — see [LICENSE](https://github.com/usestapel/stapel-moderation/blob/main/LICENSE).
+
+---
+
+<sub>This page is assembled by `stapel-readme` from `docs/readme.md` plus the contract artifacts in `docs/`. Edit the prose in `docs/readme.md`; the badges, facts and links above and below it are generated — do not hand-edit `README.md`.</sub>

stapel_moderation-0.1.0/__init__.py

@@ -0,0 +1,48 @@
+"""stapel-moderation — the fleet's single producer of moderation verdicts.
+
+A target-generic queue over every kind of moderated thing (listings, reviews,
+chat messages, profiles): one ``Case`` per target, one status vocabulary, an
+append-only audit trail, LLM-first screening with a human always in the loop,
+and sanctions with a reason, a scope, a clock and an appeal.
+
+Public API (lazily exported, PEP 562 — importing this package never pulls in
+Django or requires configured settings):
+
+- ``moderation_settings`` — resolved app settings (``stapel_moderation.conf``);
+- ``register_target_type`` / ``register_reason`` / ``register_rule`` — the
+  three merge-registries (``stapel_moderation.registry``);
+- ``NotSanctioned`` — the DRF permission a HOST hangs on its own write views
+  to refuse a sanctioned user (``stapel_moderation.authz``).
+"""
+
+__all__ = [
+    "moderation_settings",
+    "register_reason",
+    "register_rule",
+    "register_target_type",
+    "NotSanctioned",
+]
+
+# name -> submodule that defines it. Resolution is deferred until first
+# attribute access so that `import stapel_moderation` stays Django-free.
+_LAZY_EXPORTS = {
+    "moderation_settings": ".conf",
+    "register_target_type": ".registry",
+    "register_reason": ".registry",
+    "register_rule": ".registry",
+    "NotSanctioned": ".authz",
+}
+
+
+def __getattr__(name):
+    if name in _LAZY_EXPORTS:
+        from importlib import import_module
+
+        value = getattr(import_module(_LAZY_EXPORTS[name], __name__), name)
+        globals()[name] = value  # cache for subsequent lookups
+        return value
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
+def __dir__():
+    return sorted(set(globals()) | set(__all__))