@anthusai/papyrus 5.20.0 → 5.21.0

package/amplify/plugins/reader-steering/config.js

@@ -1,8 +1,12 @@
 export const READER_DIMENSION_NAME = /^[a-z][a-z0-9-]{0,23}$/;
 export const RESERVED_DIMENSIONS = ["up", "used-it"];
 export const READER_HANDLE_NAME = /^[a-z0-9_-]{3,24}$/;
+export const MODERATION_MODES = ["off", "human", "ai"];
+export const AI_KEY_PARAMETER = /^\/papyrus\/[a-z0-9][a-z0-9-]{0,62}\/openai-api-key$/;
+export const AI_MODEL_NAME = /^[a-z0-9][a-z0-9.-]{0,63}$/;
+export const SUBMISSION_KIND_NAME = /^[a-z][a-z0-9-]{0,23}$/;
 export const COMPUTE_ROLE_ARN = /^arn:aws:iam::[0-9]{12}:role\/[A-Za-z0-9+=,.@_/-]{1,512}$/;
-const KNOWN_KEYS = new Set(["name", "computeRoleArn", "dimensions", "limits", "reservedHandles", "karma", "ranking", "snapshot", "retirementPoll", "reservedConcurrency", "hypeGap"]);
+const KNOWN_KEYS = new Set(["name", "computeRoleArn", "dimensions", "limits", "reservedHandles", "karma", "ranking", "snapshot", "retirementPoll", "reservedConcurrency", "hypeGap", "submissions", "comments", "moderation"]);
 function object(raw, label, known) {
     if (raw === undefined)
         return {};
@@ -42,6 +46,12 @@ function names(raw, label, pattern) {
     }
     return [...new Set(raw)];
 }
+function lowercaseName(raw, label, fallback) {
+    const value = raw === undefined ? fallback : raw;
+    if (typeof value !== "string" || !SUBMISSION_KIND_NAME.test(value))
+        throw new Error(`reader-steering plugin ${label} must be a lowercase name matching ${SUBMISSION_KIND_NAME}`);
+    return value;
+}
 function resolveHypeGap(raw, dimensions) {
     if (raw === undefined)
         return undefined;
@@ -75,6 +85,28 @@ export function resolveReaderSteeringConfig(request) {
     const karma = object(raw.karma, "karma", ["upvoteWeight", "usedItWeight"]);
     const ranking = object(raw.ranking, "ranking", ["halfLifeHours", "risingWindowHours", "readerMinimum", "editorWeight"]);
     const snapshot = object(raw.snapshot, "snapshot", ["schedule", "intervalHours", "hypeMinimum"]);
+    const submissions = object(raw.submissions, "submissions", ["perDay", "similarHours", "kinds", "itemType", "section"]);
+    const moderation = object(raw.moderation, "moderation", ["mode", "preModeration", "reportsPerDay", "ai"]);
+    const mode = moderation.mode === undefined ? "human" : moderation.mode;
+    if (!MODERATION_MODES.includes(mode)) {
+        throw new Error(`reader-steering plugin moderation.mode must be one of: ${MODERATION_MODES.join(", ")}`);
+    }
+    const preModeration = flag(moderation.preModeration, "moderation.preModeration");
+    if (preModeration && mode === "off")
+        throw new Error("reader-steering plugin moderation.preModeration needs a moderation.mode other than off");
+    const ai = object(moderation.ai, "moderation.ai", ["model", "apiKeyParameter"]);
+    if (mode !== "ai" && moderation.ai !== undefined)
+        throw new Error("reader-steering plugin moderation.ai needs moderation.mode: ai");
+    if (mode === "ai") {
+        if (typeof ai.apiKeyParameter !== "string" || !AI_KEY_PARAMETER.test(ai.apiKeyParameter)) {
+            throw new Error("reader-steering plugin moderation.ai.apiKeyParameter must be the SSM SecureString name /papyrus/<site>/openai-api-key");
+        }
+        if (ai.model !== undefined && (typeof ai.model !== "string" || !AI_MODEL_NAME.test(ai.model))) {
+            throw new Error(`reader-steering plugin moderation.ai.model must be a model name matching ${AI_MODEL_NAME}`);
+        }
+    }
+    const kinds = names(submissions.kinds, "submissions.kinds", SUBMISSION_KIND_NAME);
+    const comments = object(raw.comments, "comments", ["perHour", "editWindowMinutes", "maximumLength", "maximumLinks"]);
     const hypeGap = resolveHypeGap(raw.hypeGap, dimensions);
     const retirementPoll = flag(raw.retirementPoll, "retirementPoll");
     if (retirementPoll && !flag(snapshot.schedule, "snapshot.schedule")) {
@@ -104,6 +136,25 @@ export function resolveReaderSteeringConfig(request) {
             intervalHours: integer(snapshot.intervalHours, "snapshot.intervalHours", 6, 1, 24),
             hypeMinimum: integer(snapshot.hypeMinimum, "snapshot.hypeMinimum", 5, 1, 10000),
         },
+        submissions: {
+            perDay: integer(submissions.perDay, "submissions.perDay", 10, 1, 1000),
+            similarHours: integer(submissions.similarHours, "submissions.similarHours", 48, 1, 24 * 30),
+            kinds: kinds.length > 0 ? kinds : ["link"],
+            itemType: lowercaseName(submissions.itemType, "submissions.itemType", "brief"),
+            section: lowercaseName(submissions.section, "submissions.section", "unsectioned"),
+        },
+        moderation: {
+            mode: mode,
+            preModeration,
+            reportsPerDay: integer(moderation.reportsPerDay, "moderation.reportsPerDay", 20, 1, 1000),
+            ...(mode === "ai" ? { ai: { model: ai.model ?? "gpt-6-luna", apiKeyParameter: ai.apiKeyParameter } } : {}),
+        },
+        comments: {
+            perHour: integer(comments.perHour, "comments.perHour", 30, 1, 1000),
+            editWindowMinutes: integer(comments.editWindowMinutes, "comments.editWindowMinutes", 10, 0, 24 * 60),
+            maximumLength: integer(comments.maximumLength, "comments.maximumLength", 2000, 1, 10000),
+            maximumLinks: integer(comments.maximumLinks, "comments.maximumLinks", 3, 0, 50),
+        },
         retirementPoll,
         ...(hypeGap ? { hypeGap } : {}),
         ...(raw.reservedConcurrency === undefined ? {} : { reservedConcurrency: integer(raw.reservedConcurrency, "reservedConcurrency", 1, 1, 1000) }),

package/amplify/plugins/reader-steering/config.ts

@@ -3,6 +3,10 @@ import type { PluginRequest } from "../types";
 export const READER_DIMENSION_NAME = /^[a-z][a-z0-9-]{0,23}$/;
 export const RESERVED_DIMENSIONS = ["up", "used-it"];
 export const READER_HANDLE_NAME = /^[a-z0-9_-]{3,24}$/;
+export const MODERATION_MODES = ["off", "human", "ai"] as const;
+export const AI_KEY_PARAMETER = /^\/papyrus\/[a-z0-9][a-z0-9-]{0,62}\/openai-api-key$/;
+export const AI_MODEL_NAME = /^[a-z0-9][a-z0-9.-]{0,63}$/;
+export const SUBMISSION_KIND_NAME = /^[a-z][a-z0-9-]{0,23}$/;
 export const COMPUTE_ROLE_ARN = /^arn:aws:iam::[0-9]{12}:role\/[A-Za-z0-9+=,.@_/-]{1,512}$/;
 
 export type ReaderSteeringConfig = {
@@ -37,6 +41,47 @@ export type ReaderSteeringConfig = {
     /** A hype gap needs at least this many ratings on every dimension involved. */
     hypeMinimum: number;
   };
+  submissions: {
+    /** Submissions one reader may make in a UTC day. Accounts younger than `limits.newAccountHours` get `perDay / limits.newAccountDivisor`. */
+    perDay: number;
+    /** Another submission from the same domain inside this many hours is returned as a `similar` warning. */
+    similarHours: number;
+    /** The kinds a reader may pick (a radio on the form). A single kind hides the radio. */
+    kinds: string[];
+    /** The item type of the draft an editor makes by promoting a submission. */
+    itemType: string;
+    /** The section of that draft. */
+    section: string;
+  };
+  moderation: {
+    /**
+     * `human`: new submissions and comments are public at once and wait in the Administration queue (the default for a pilot).
+     * `off`: no queue; moderators can still hide, ban and undo. Turning human review off is the whole of "trust graduation".
+     * `ai`: a worker asks a model to allow or hide each new item and logs it as the AI moderator; a human decision always stands.
+     */
+    mode: (typeof MODERATION_MODES)[number];
+    /** Hold new submissions and comments hidden until a moderator approves them. Needs a mode other than `off`. */
+    preModeration: boolean;
+    /** Reports one reader may file in a UTC day (a third of it for a new account). */
+    reportsPerDay: number;
+    /** Present when `mode` is `ai`. */
+    ai?: {
+      /** The model that judges each new item. */
+      model: string;
+      /** The SSM SecureString that holds the API key: `/papyrus/<site>/openai-api-key`. The plugin only grants read access to it. */
+      apiKeyParameter: string;
+    };
+  };
+  comments: {
+    /** Comments, replies and edits one reader may post in a clock hour (a third of it for new accounts). */
+    perHour: number;
+    /** The author may edit a comment for this many minutes after posting it. */
+    editWindowMinutes: number;
+    /** Most characters in a comment. */
+    maximumLength: number;
+    /** Most links (http, https or www) in a comment. */
+    maximumLinks: number;
+  };
   /**
    * The hype gap is `mean(plus dimensions) - mean(minus dimensions)`, computed for reader means and for editor scores.
    * Absent means no hype gap is published. Shipped sets plus = notable, novel and minus = real, useful.
@@ -54,7 +99,7 @@ export type ReaderSteeringConfig = {
   retirementPoll: boolean;
 };
 
-const KNOWN_KEYS = new Set(["name", "computeRoleArn", "dimensions", "limits", "reservedHandles", "karma", "ranking", "snapshot", "retirementPoll", "reservedConcurrency", "hypeGap"]);
+const KNOWN_KEYS = new Set(["name", "computeRoleArn", "dimensions", "limits", "reservedHandles", "karma", "ranking", "snapshot", "retirementPoll", "reservedConcurrency", "hypeGap", "submissions", "comments", "moderation"]);
 
 function object(raw: unknown, label: string, known: string[]): Record<string, unknown> {
   if (raw === undefined) return {};
@@ -94,6 +139,12 @@ function names(raw: unknown, label: string, pattern: RegExp): string[] {
   return [...new Set(raw as string[])];
 }
 
+function lowercaseName(raw: unknown, label: string, fallback: string): string {
+  const value = raw === undefined ? fallback : raw;
+  if (typeof value !== "string" || !SUBMISSION_KIND_NAME.test(value)) throw new Error(`reader-steering plugin ${label} must be a lowercase name matching ${SUBMISSION_KIND_NAME}`);
+  return value;
+}
+
 function resolveHypeGap(raw: unknown, dimensions: string[]): { plus: string[]; minus: string[] } | undefined {
   if (raw === undefined) return undefined;
   const groups = object(raw, "hypeGap", ["plus", "minus"]);
@@ -122,6 +173,26 @@ export function resolveReaderSteeringConfig(request: PluginRequest): ReaderSteer
   const karma = object(raw.karma, "karma", ["upvoteWeight", "usedItWeight"]);
   const ranking = object(raw.ranking, "ranking", ["halfLifeHours", "risingWindowHours", "readerMinimum", "editorWeight"]);
   const snapshot = object(raw.snapshot, "snapshot", ["schedule", "intervalHours", "hypeMinimum"]);
+  const submissions = object(raw.submissions, "submissions", ["perDay", "similarHours", "kinds", "itemType", "section"]);
+  const moderation = object(raw.moderation, "moderation", ["mode", "preModeration", "reportsPerDay", "ai"]);
+  const mode = moderation.mode === undefined ? "human" : moderation.mode;
+  if (!MODERATION_MODES.includes(mode as (typeof MODERATION_MODES)[number])) {
+    throw new Error(`reader-steering plugin moderation.mode must be one of: ${MODERATION_MODES.join(", ")}`);
+  }
+  const preModeration = flag(moderation.preModeration, "moderation.preModeration");
+  if (preModeration && mode === "off") throw new Error("reader-steering plugin moderation.preModeration needs a moderation.mode other than off");
+  const ai = object(moderation.ai, "moderation.ai", ["model", "apiKeyParameter"]);
+  if (mode !== "ai" && moderation.ai !== undefined) throw new Error("reader-steering plugin moderation.ai needs moderation.mode: ai");
+  if (mode === "ai") {
+    if (typeof ai.apiKeyParameter !== "string" || !AI_KEY_PARAMETER.test(ai.apiKeyParameter)) {
+      throw new Error("reader-steering plugin moderation.ai.apiKeyParameter must be the SSM SecureString name /papyrus/<site>/openai-api-key");
+    }
+    if (ai.model !== undefined && (typeof ai.model !== "string" || !AI_MODEL_NAME.test(ai.model))) {
+      throw new Error(`reader-steering plugin moderation.ai.model must be a model name matching ${AI_MODEL_NAME}`);
+    }
+  }
+  const kinds = names(submissions.kinds, "submissions.kinds", SUBMISSION_KIND_NAME);
+  const comments = object(raw.comments, "comments", ["perHour", "editWindowMinutes", "maximumLength", "maximumLinks"]);
   const hypeGap = resolveHypeGap(raw.hypeGap, dimensions);
   const retirementPoll = flag(raw.retirementPoll, "retirementPoll");
   if (retirementPoll && !flag(snapshot.schedule, "snapshot.schedule")) {
@@ -151,6 +222,25 @@ export function resolveReaderSteeringConfig(request: PluginRequest): ReaderSteer
       intervalHours: integer(snapshot.intervalHours, "snapshot.intervalHours", 6, 1, 24),
       hypeMinimum: integer(snapshot.hypeMinimum, "snapshot.hypeMinimum", 5, 1, 10000),
     },
+    submissions: {
+      perDay: integer(submissions.perDay, "submissions.perDay", 10, 1, 1000),
+      similarHours: integer(submissions.similarHours, "submissions.similarHours", 48, 1, 24 * 30),
+      kinds: kinds.length > 0 ? kinds : ["link"],
+      itemType: lowercaseName(submissions.itemType, "submissions.itemType", "brief"),
+      section: lowercaseName(submissions.section, "submissions.section", "unsectioned"),
+    },
+    moderation: {
+      mode: mode as (typeof MODERATION_MODES)[number],
+      preModeration,
+      reportsPerDay: integer(moderation.reportsPerDay, "moderation.reportsPerDay", 20, 1, 1000),
+      ...(mode === "ai" ? { ai: { model: (ai.model as string | undefined) ?? "gpt-6-luna", apiKeyParameter: ai.apiKeyParameter as string } } : {}),
+    },
+    comments: {
+      perHour: integer(comments.perHour, "comments.perHour", 30, 1, 1000),
+      editWindowMinutes: integer(comments.editWindowMinutes, "comments.editWindowMinutes", 10, 0, 24 * 60),
+      maximumLength: integer(comments.maximumLength, "comments.maximumLength", 2000, 1, 10000),
+      maximumLinks: integer(comments.maximumLinks, "comments.maximumLinks", 3, 0, 50),
+    },
     retirementPoll,
     ...(hypeGap ? { hypeGap } : {}),
     ...(raw.reservedConcurrency === undefined ? {} : { reservedConcurrency: integer(raw.reservedConcurrency, "reservedConcurrency", 1, 1, 1000) }),

package/amplify/plugins/reader-steering/function/ai_moderation.py

@@ -0,0 +1,230 @@
+"""AI moderation: a model reads each new submission and comment and answers allow or hide, with a reason.
+
+The decision is applied as an ordinary moderation action marked ``by: "ai"``, so it appears in the log, shows in the panel,
+and a human can undo it or decide differently. A human decision always stands: an item a person has acted on is never
+judged by the model again. A model that fails, times out or answers something that is not a valid verdict leaves the item
+in the human queue.
+
+Secrets: the API key is read from an SSM SecureString at the start of a run and lives only in the object that makes the
+request. It is never logged, never put in a returned value and never in an error message (errors are reported by class name).
+Tests stub the model; nothing in the tests, CI or this module's defaults makes a paid call.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import time
+import urllib.error
+import urllib.request
+from collections.abc import Callable
+from dataclasses import dataclass, field
+from typing import Any, Protocol
+
+import moderation as rules
+
+PROMPT_FILE = os.path.join(os.path.dirname(os.path.abspath(__file__)), "moderation-prompt.md")
+DEFAULT_MODEL = "gpt-6-luna"
+RESPONSES_URL = "https://api.openai.com/v1/responses"
+ALLOW, HIDE = "allow", "hide"
+MAXIMUM_REASON = 200
+MAXIMUM_TEXT = 4000
+BATCH_LIMIT = 25
+CONSECUTIVE_FAILURES_BEFORE_STOPPING = 3
+REQUEST_TIMEOUT_SECONDS = 20
+AI_ACTOR = "ai"
+REASON_PREFIX = "AI: "
+PARAMETER_NAME = re.compile(r"/papyrus/[a-z0-9][a-z0-9-]{0,62}/openai-api-key")
+
+
+class ModelOutputError(ValueError):
+    pass
+
+
+@dataclass(frozen=True)
+class Verdict:
+    decision: str
+    reason: str
+
+
+class ModerationModel(Protocol):
+    def judge(self, item: dict[str, Any]) -> Verdict: ...
+
+
+def load_prompt(path: str = PROMPT_FILE) -> str:
+    with open(path, encoding="utf-8") as handle:
+        return handle.read().strip()
+
+
+def parse_verdict(text: Any) -> Verdict:
+    """A strict reading of the model's answer: one JSON object, ``decision`` allow or hide, a short plain reason."""
+    if not isinstance(text, str):
+        raise ModelOutputError("the model answered nothing")
+    start, end = text.find("{"), text.rfind("}")
+    if start < 0 or end < start:
+        raise ModelOutputError("the model did not answer with a JSON object")
+    try:
+        data = json.loads(text[start : end + 1])
+    except ValueError as error:
+        raise ModelOutputError("the model's answer is not valid JSON") from error
+    decision, reason = data.get("decision") if isinstance(data, dict) else None, data.get("reason") if isinstance(data, dict) else None
+    if decision not in (ALLOW, HIDE):
+        raise ModelOutputError("the decision is neither allow nor hide")
+    if not isinstance(reason, str) or not reason.strip():
+        raise ModelOutputError("the model gave no reason")
+    return Verdict(decision, " ".join(reason.split())[:MAXIMUM_REASON])
+
+
+def response_text(body: Any) -> str | None:
+    """The text of a Responses API answer: ``output_text`` when present, else the text parts of the output messages."""
+    if not isinstance(body, dict):
+        return None
+    if isinstance(body.get("output_text"), str):
+        return body["output_text"]
+    parts = [
+        part.get("text")
+        for message in body.get("output") or []
+        if isinstance(message, dict)
+        for part in message.get("content") or []
+        if isinstance(part, dict) and isinstance(part.get("text"), str)
+    ]
+    return "".join(parts) if parts else None
+
+
+def urllib_transport(url: str, headers: dict[str, str], payload: dict[str, Any]) -> dict[str, Any]:
+    request = urllib.request.Request(url, data=json.dumps(payload).encode("utf-8"), headers=headers, method="POST")
+    with urllib.request.urlopen(request, timeout=REQUEST_TIMEOUT_SECONDS) as response:  # noqa: S310 - a fixed https endpoint
+        return json.loads(response.read().decode("utf-8"))
+
+
+class OpenAIModerationModel:
+    """GPT-6 Luna (``moderation.ai.model``) through the OpenAI Responses API. The key is held here and nowhere else."""
+
+    def __init__(
+        self,
+        api_key: str,
+        *,
+        model: str = DEFAULT_MODEL,
+        prompt: str | None = None,
+        transport: Callable[[str, dict[str, str], dict[str, Any]], dict[str, Any]] = urllib_transport,
+    ) -> None:
+        if not api_key:
+            raise ValueError("an API key is required")
+        self._api_key = api_key
+        self._model = model
+        self._prompt = prompt if prompt is not None else load_prompt()
+        self._transport = transport
+
+    def request_payload(self, item: dict[str, Any]) -> dict[str, Any]:
+        return {
+            "model": self._model,
+            "instructions": self._prompt,
+            "input": json.dumps(item, ensure_ascii=False, separators=(",", ":")),
+            "text": {"format": {"type": "json_object"}},
+            "max_output_tokens": 300,
+            "store": False,
+        }
+
+    def judge(self, item: dict[str, Any]) -> Verdict:
+        body = self._transport(RESPONSES_URL, {"authorization": f"Bearer {self._api_key}", "content-type": "application/json"}, self.request_payload(item))
+        return parse_verdict(response_text(body))
+
+
+def model_input(kind: str, row: dict[str, Any]) -> dict[str, Any]:
+    """What the model sees: the content, the automatic signals and the report count. Never a reader id, a handle or a siteSubject."""
+    signals = row.get("signals")
+    if isinstance(signals, str):
+        try:
+            signals = json.loads(signals)
+        except ValueError:
+            signals = []
+    listed = [
+        {"policy": str(signal.get("policy", ""))[:60], "detector": str(signal.get("detector", ""))[:60], "severity": str(signal.get("severity", ""))[:12]}
+        for signal in (signals if isinstance(signals, list) else [])
+        if isinstance(signal, dict)
+    ][:20]
+    if kind == rules.TARGET_SUBMISSION:
+        item: dict[str, Any] = {"kind": "submission", "title": row["title"], "url": row["canonicalUrl"], "domain": row["domain"], "text": row.get("note") or ""}
+    else:
+        item = {"kind": "comment", "text": row["body"]}
+    item["text"] = str(item["text"])[:MAXIMUM_TEXT]
+    item["signals"] = listed
+    item["reports"] = int(row.get("reportCount") or 0)
+    return item
+
+
+@dataclass
+class AiReport:
+    judged: int = 0
+    allowed: int = 0
+    hidden: int = 0
+    skipped_human: int = 0
+    errors: dict[str, int] = field(default_factory=dict)
+    stopped: bool = False
+
+    def to_dict(self) -> dict[str, Any]:
+        return {"judged": self.judged, "allowed": self.allowed, "hidden": self.hidden, "skippedHuman": self.skipped_human, "errors": dict(self.errors), "stopped": self.stopped}
+
+
+class AiStore(Protocol):
+    def new_content(self) -> list[tuple[str, dict[str, Any]]]: ...
+
+    def human_acted_on(self) -> set[str]: ...
+
+
+def run_ai_moderation(
+    store: Any,
+    model: ModerationModel,
+    *,
+    now: Callable[[], float],
+    settings: rules.ModerationSettings,
+    deadline: float,
+    limit: int = BATCH_LIMIT,
+    iso: Callable[[float], str],
+) -> AiReport:
+    """Judges the oldest new items first, until the batch limit, the deadline, or three failures in a row."""
+    report = AiReport()
+    human_targets = store.human_acted_on()
+    failures_in_a_row = 0
+    candidates = sorted(store.new_content(), key=lambda entry: (entry[1]["createdAt"], entry[1]["id"]))
+    for kind, row in candidates:
+        if report.judged >= limit or now() >= deadline:
+            break
+        if row["id"] in human_targets:
+            report.skipped_human += 1
+            continue
+        if row.get("state") == "deleted":
+            continue
+        try:
+            verdict = model.judge(model_input(kind, row))
+        except Exception as error:  # noqa: BLE001 - reported by class name only: a message could carry the key or the content
+            report.errors[type(error).__name__] = report.errors.get(type(error).__name__, 0) + 1
+            failures_in_a_row += 1
+            if failures_in_a_row >= CONSECUTIVE_FAILURES_BEFORE_STOPPING:
+                report.stopped = True
+                break
+            continue
+        failures_in_a_row = 0
+        action = rules.APPROVE if verdict.decision == ALLOW else rules.HIDE
+        outcome = rules.apply_action(
+            store,
+            action=action,
+            target_type=kind,
+            target=row["id"],
+            reason=REASON_PREFIX + verdict.reason,
+            undo_of=None,
+            actor_sub=AI_ACTOR,
+            by=rules.BY_AI,
+            now_iso=iso(now()),
+            settings=settings,
+        )
+        if outcome.status != "ok":
+            report.errors[outcome.error or "refused"] = report.errors.get(outcome.error or "refused", 0) + 1
+            continue
+        report.judged += 1
+        if action == rules.APPROVE:
+            report.allowed += 1
+        else:
+            report.hidden += 1
+    return report