@chatwarden/core 0.1.6 → 0.1.7
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +50 -0
- package/dist/src/ai/agreement.d.ts +46 -0
- package/dist/src/ai/agreement.d.ts.map +1 -0
- package/dist/src/ai/agreement.js +71 -0
- package/dist/src/ai/agreement.js.map +1 -0
- package/dist/src/ai/breaker.d.ts +31 -0
- package/dist/src/ai/breaker.d.ts.map +1 -0
- package/dist/src/ai/breaker.js +62 -0
- package/dist/src/ai/breaker.js.map +1 -0
- package/dist/src/ai/budget.d.ts +26 -0
- package/dist/src/ai/budget.d.ts.map +1 -0
- package/dist/src/ai/budget.js +57 -0
- package/dist/src/ai/budget.js.map +1 -0
- package/dist/src/ai/case.d.ts +37 -0
- package/dist/src/ai/case.d.ts.map +1 -0
- package/dist/src/ai/case.js +30 -0
- package/dist/src/ai/case.js.map +1 -0
- package/dist/src/ai/casebook.d.ts +59 -0
- package/dist/src/ai/casebook.d.ts.map +1 -0
- package/dist/src/ai/casebook.js +47 -0
- package/dist/src/ai/casebook.js.map +1 -0
- package/dist/src/ai/ceilings.d.ts +42 -0
- package/dist/src/ai/ceilings.d.ts.map +1 -0
- package/dist/src/ai/ceilings.js +59 -0
- package/dist/src/ai/ceilings.js.map +1 -0
- package/dist/src/ai/fake.d.ts +41 -0
- package/dist/src/ai/fake.d.ts.map +1 -0
- package/dist/src/ai/fake.js +75 -0
- package/dist/src/ai/fake.js.map +1 -0
- package/dist/src/ai/hash.d.ts +13 -0
- package/dist/src/ai/hash.d.ts.map +1 -0
- package/dist/src/ai/hash.js +19 -0
- package/dist/src/ai/hash.js.map +1 -0
- package/dist/src/ai/inert.d.ts +5 -0
- package/dist/src/ai/inert.d.ts.map +1 -0
- package/dist/src/ai/inert.js +22 -0
- package/dist/src/ai/inert.js.map +1 -0
- package/dist/src/ai/injection.d.ts +8 -0
- package/dist/src/ai/injection.d.ts.map +1 -0
- package/dist/src/ai/injection.js +30 -0
- package/dist/src/ai/injection.js.map +1 -0
- package/dist/src/ai/lines.d.ts +64 -0
- package/dist/src/ai/lines.d.ts.map +1 -0
- package/dist/src/ai/lines.js +172 -0
- package/dist/src/ai/lines.js.map +1 -0
- package/dist/src/ai/prompt.d.ts +44 -0
- package/dist/src/ai/prompt.d.ts.map +1 -0
- package/dist/src/ai/prompt.js +185 -0
- package/dist/src/ai/prompt.js.map +1 -0
- package/dist/src/ai/redact.d.ts +29 -0
- package/dist/src/ai/redact.d.ts.map +1 -0
- package/dist/src/ai/redact.js +160 -0
- package/dist/src/ai/redact.js.map +1 -0
- package/dist/src/ai/schema.d.ts +6 -0
- package/dist/src/ai/schema.d.ts.map +1 -0
- package/dist/src/ai/schema.js +50 -0
- package/dist/src/ai/schema.js.map +1 -0
- package/dist/src/ai/service.d.ts +328 -0
- package/dist/src/ai/service.d.ts.map +1 -0
- package/dist/src/ai/service.js +749 -0
- package/dist/src/ai/service.js.map +1 -0
- package/dist/src/ai/types.d.ts +180 -0
- package/dist/src/ai/types.d.ts.map +1 -0
- package/dist/src/ai/types.js +23 -0
- package/dist/src/ai/types.js.map +1 -0
- package/dist/src/ai/validate.d.ts +30 -0
- package/dist/src/ai/validate.d.ts.map +1 -0
- package/dist/src/ai/validate.js +160 -0
- package/dist/src/ai/validate.js.map +1 -0
- package/dist/src/ai/worker.d.ts +74 -0
- package/dist/src/ai/worker.d.ts.map +1 -0
- package/dist/src/ai/worker.js +286 -0
- package/dist/src/ai/worker.js.map +1 -0
- package/dist/src/audit.d.ts +12 -3
- package/dist/src/audit.d.ts.map +1 -1
- package/dist/src/audit.js +30 -4
- package/dist/src/audit.js.map +1 -1
- package/dist/src/chatwarden.d.ts +16 -0
- package/dist/src/chatwarden.d.ts.map +1 -1
- package/dist/src/chatwarden.js +49 -1
- package/dist/src/chatwarden.js.map +1 -1
- package/dist/src/decide.d.ts +36 -1
- package/dist/src/decide.d.ts.map +1 -1
- package/dist/src/decide.js +62 -2
- package/dist/src/decide.js.map +1 -1
- package/dist/src/documents.d.ts +1 -1
- package/dist/src/documents.d.ts.map +1 -1
- package/dist/src/documents.js +4 -1
- package/dist/src/documents.js.map +1 -1
- package/dist/src/index.d.ts +27 -5
- package/dist/src/index.d.ts.map +1 -1
- package/dist/src/index.js +17 -2
- package/dist/src/index.js.map +1 -1
- package/dist/src/profile.d.ts +30 -1
- package/dist/src/profile.d.ts.map +1 -1
- package/dist/src/profile.js +43 -4
- package/dist/src/profile.js.map +1 -1
- package/dist/src/retention.d.ts +19 -0
- package/dist/src/retention.d.ts.map +1 -1
- package/dist/src/retention.js +33 -10
- package/dist/src/retention.js.map +1 -1
- package/dist/src/types.d.ts +269 -2
- package/dist/src/types.d.ts.map +1 -1
- package/dist/src/types.js.map +1 -1
- package/package.json +2 -2
- package/src/ai/agreement.ts +106 -0
- package/src/ai/breaker.ts +73 -0
- package/src/ai/budget.ts +65 -0
- package/src/ai/case.ts +74 -0
- package/src/ai/casebook.ts +75 -0
- package/src/ai/ceilings.ts +68 -0
- package/src/ai/fake.ts +105 -0
- package/src/ai/hash.ts +20 -0
- package/src/ai/inert.ts +26 -0
- package/src/ai/injection.ts +32 -0
- package/src/ai/lines.ts +216 -0
- package/src/ai/prompt.ts +208 -0
- package/src/ai/redact.ts +174 -0
- package/src/ai/schema.ts +51 -0
- package/src/ai/service.ts +955 -0
- package/src/ai/types.ts +165 -0
- package/src/ai/validate.ts +173 -0
- package/src/ai/worker.ts +364 -0
- package/src/audit.ts +31 -5
- package/src/chatwarden.ts +64 -1
- package/src/decide.ts +97 -4
- package/src/documents.ts +5 -2
- package/src/index.ts +52 -1
- package/src/profile.ts +68 -4
- package/src/retention.ts +47 -10
- package/src/types.ts +294 -2
package/src/decide.ts
CHANGED
|
@@ -1,3 +1,6 @@
|
|
|
1
|
+
import type { AiOutcomeHook } from './ai/casebook.js';
|
|
2
|
+
import { ROLES } from './audit.js';
|
|
3
|
+
import type { Role } from './audit.js';
|
|
1
4
|
import { sha256Hex } from './crypto.js';
|
|
2
5
|
import { safeWarn } from './log.js';
|
|
3
6
|
import { ownLines } from './notices.js';
|
|
@@ -6,7 +9,8 @@ import type { CommunityRules, RuleRef } from './rules.js';
|
|
|
6
9
|
import { SANCTION_KINDS, SANCTION_SOURCES, validateSanctionInput, writeSanction } from './sanctions.js';
|
|
7
10
|
import type { SanctionIndex } from './sanctions.js';
|
|
8
11
|
import type { SubjectIndex } from './subjects.js';
|
|
9
|
-
import
|
|
12
|
+
import { CONDUCT_LEVELS } from './types.js';
|
|
13
|
+
import type { AiOutcomeInsert, Clock, ConductLevel, Logger, ReportExcerptLine, ReportRecord, SanctionKind, SanctionRow, Source, Store, SubjectId } from './types.js';
|
|
10
14
|
|
|
11
15
|
// The one path every moderator decision on a report takes. A decision closes the report, writes each sanction and
|
|
12
16
|
// its player notice, and records itself, all in ONE store transaction: it lands whole or not at all. The same
|
|
@@ -82,6 +86,29 @@ export interface DecisionInput {
|
|
|
82
86
|
reason?: string;
|
|
83
87
|
/** Defaults to `'moderator'`. */
|
|
84
88
|
source?: Source;
|
|
89
|
+
/**
|
|
90
|
+
* AI levels 1 and 2. Optional: the casebook records how every decision compared with the report's AI read whether or not this is
|
|
91
|
+
* given (the server decides, from the stored read and the decision). It only tells the casebook which read the moderator saw, whether
|
|
92
|
+
* they clicked accept, the conduct level of their form and their role. It never changes the decision, its key or its answer, and a
|
|
93
|
+
* part that is not well formed is ignored. Agreement is computed from the stored read and the decision, never from this echo.
|
|
94
|
+
* @experimental
|
|
95
|
+
*/
|
|
96
|
+
ai?: DecisionAiEcho;
|
|
97
|
+
}
|
|
98
|
+
|
|
99
|
+
/**
|
|
100
|
+
* What a decision tells the casebook about the AI. `readId` (with `accepted`) is the echo of the read the moderator saw: an id that is
|
|
101
|
+
* not one of this report's finished reads falls back to the newest. `accepted` is a claim that they accepted the pre-fill in one click:
|
|
102
|
+
* it counts only when the decision is the pre-fill. `severity` is the conduct level their form settled on: it counts only when it fits
|
|
103
|
+
* the verdict. Without the echo no example text is kept. `role` is the moderator's, for the `ai.outcome` audit row (without it none is
|
|
104
|
+
* written).
|
|
105
|
+
* @experimental
|
|
106
|
+
*/
|
|
107
|
+
export interface DecisionAiEcho {
|
|
108
|
+
readId?: string;
|
|
109
|
+
accepted?: boolean;
|
|
110
|
+
severity?: ConductLevel;
|
|
111
|
+
role?: Role;
|
|
85
112
|
}
|
|
86
113
|
|
|
87
114
|
/**
|
|
@@ -120,6 +147,8 @@ export interface DecisionServiceDeps {
|
|
|
120
147
|
* nothing, and the people acted on are still told.
|
|
121
148
|
*/
|
|
122
149
|
reporterFeedback?: boolean;
|
|
150
|
+
/** AI casebook: the outcome row for a decision made with an AI echo. Fenced; null records nothing. */
|
|
151
|
+
aiOutcome?: AiOutcomeHook;
|
|
123
152
|
}
|
|
124
153
|
|
|
125
154
|
/**
|
|
@@ -146,7 +175,14 @@ export interface AppliedGroup {
|
|
|
146
175
|
*/
|
|
147
176
|
export interface DecisionOutcome {
|
|
148
177
|
result: DecisionResult;
|
|
149
|
-
committed: {
|
|
178
|
+
committed: {
|
|
179
|
+
reportId: string;
|
|
180
|
+
verdict: DecisionInput['verdict'];
|
|
181
|
+
at: number;
|
|
182
|
+
applied: AppliedGroup[];
|
|
183
|
+
/** The casebook recorded an outcome with this decision; `role` is the moderator's, for the audit row (null when the echo had none). */
|
|
184
|
+
aiOutcome: { agreement: AiOutcomeInsert['agreement']; role: Role | null; actor: string } | null;
|
|
185
|
+
} | null;
|
|
150
186
|
}
|
|
151
187
|
|
|
152
188
|
const VERDICTS: readonly DecisionInput['verdict'][] = ['upheld', 'noted', 'no_action', 'bad_faith'];
|
|
@@ -191,6 +227,26 @@ interface Normal {
|
|
|
191
227
|
source: Source;
|
|
192
228
|
/** Sorted by canonical subject, then kind. */
|
|
193
229
|
actions: NormalAction[];
|
|
230
|
+
/** The AI echo, or null when absent or not well formed. Not part of the key. */
|
|
231
|
+
ai: { readId: string | null; accepted: boolean; severity: ConductLevel | null; role: Role | null };
|
|
232
|
+
}
|
|
233
|
+
|
|
234
|
+
/** The longest read id an echo may carry. */
|
|
235
|
+
const AI_READ_ID_MAX = 128;
|
|
236
|
+
|
|
237
|
+
/**
|
|
238
|
+
* The AI echo of an input. Anything that is not well formed is ignored, never an error (the decision matters more): a malformed echo
|
|
239
|
+
* (a bad read id, or an `accepted` that is not a boolean) is as if there were none, but a good role is kept for the audit row.
|
|
240
|
+
*/
|
|
241
|
+
function normalizeAi(v: unknown): Normal['ai'] {
|
|
242
|
+
const none: Normal['ai'] = { readId: null, accepted: false, severity: null, role: null };
|
|
243
|
+
if (typeof v !== 'object' || v === null) return none;
|
|
244
|
+
const o = v as Record<string, unknown>;
|
|
245
|
+
const role = (ROLES as readonly unknown[]).includes(o['role']) ? (o['role'] as Role) : null;
|
|
246
|
+
const readId = o['readId'];
|
|
247
|
+
if (typeof readId !== 'string' || readId === '' || readId.length > AI_READ_ID_MAX || typeof o['accepted'] !== 'boolean') return { ...none, role };
|
|
248
|
+
const severity = (CONDUCT_LEVELS as readonly unknown[]).includes(o['severity']) ? (o['severity'] as ConductLevel) : null;
|
|
249
|
+
return { readId, accepted: o['accepted'], severity, role };
|
|
194
250
|
}
|
|
195
251
|
|
|
196
252
|
const byText = (a: string, b: string): number => (a < b ? -1 : a > b ? 1 : 0);
|
|
@@ -265,6 +321,7 @@ function normalize(subjects: SubjectIndex, input: DecisionInput): Normal {
|
|
|
265
321
|
evidence,
|
|
266
322
|
source: source as Source,
|
|
267
323
|
actions,
|
|
324
|
+
ai: normalizeAi(input.ai),
|
|
268
325
|
};
|
|
269
326
|
}
|
|
270
327
|
|
|
@@ -330,6 +387,7 @@ export class DecisionService {
|
|
|
330
387
|
private readonly index: SanctionIndex | undefined;
|
|
331
388
|
private readonly logger: Logger | undefined;
|
|
332
389
|
private readonly reporterFeedback: boolean;
|
|
390
|
+
private readonly aiOutcome: AiOutcomeHook | undefined;
|
|
333
391
|
|
|
334
392
|
constructor(deps: DecisionServiceDeps) {
|
|
335
393
|
this.store = deps.store;
|
|
@@ -340,6 +398,7 @@ export class DecisionService {
|
|
|
340
398
|
this.index = deps.index;
|
|
341
399
|
this.logger = deps.logger;
|
|
342
400
|
this.reporterFeedback = deps.reporterFeedback ?? true;
|
|
401
|
+
this.aiOutcome = deps.aiOutcome;
|
|
343
402
|
}
|
|
344
403
|
|
|
345
404
|
/**
|
|
@@ -442,6 +501,7 @@ export class DecisionService {
|
|
|
442
501
|
const pending = this.index !== undefined && !this.index.isEnabled();
|
|
443
502
|
const reporter = this.subjects.canonical(report.reporterSubject);
|
|
444
503
|
const status = isDismissal(norm.verdict) ? 'dismissed' : 'actioned';
|
|
504
|
+
const outcome = this.outcomeFor(norm, report, now);
|
|
445
505
|
|
|
446
506
|
const done = this.store.transaction(() => {
|
|
447
507
|
if (!this.store.closeReport(report.id, status, norm.verdict === 'bad_faith', norm.actor, now, norm.reason, norm.evidence)) {
|
|
@@ -491,7 +551,16 @@ export class DecisionService {
|
|
|
491
551
|
told.add(reporter);
|
|
492
552
|
}
|
|
493
553
|
this.store.insertDecision(key, report.id, now, JSON.stringify({ groups }));
|
|
494
|
-
|
|
554
|
+
// The casebook row lands with the decision or not at all. A casebook that cannot be written never fails the decision.
|
|
555
|
+
let recorded: AiOutcomeInsert['agreement'] | null = null;
|
|
556
|
+
if (outcome !== null) {
|
|
557
|
+
try {
|
|
558
|
+
if (this.store.insertAiOutcome?.(outcome) === true) recorded = outcome.agreement;
|
|
559
|
+
} catch (err) {
|
|
560
|
+
this.warn('decide.ai_outcome_failed', { error: errName(err) });
|
|
561
|
+
}
|
|
562
|
+
}
|
|
563
|
+
return { groups, applied, rows, told, recorded };
|
|
495
564
|
});
|
|
496
565
|
|
|
497
566
|
if (done === null) {
|
|
@@ -515,10 +584,34 @@ export class DecisionService {
|
|
|
515
584
|
}
|
|
516
585
|
return {
|
|
517
586
|
result: { ok: true, groups: done.groups, replay: false },
|
|
518
|
-
committed: {
|
|
587
|
+
committed: {
|
|
588
|
+
reportId: report.id,
|
|
589
|
+
verdict: norm.verdict,
|
|
590
|
+
at: now,
|
|
591
|
+
applied: done.applied,
|
|
592
|
+
aiOutcome: done.recorded === null ? null : { agreement: done.recorded, role: norm.ai.role, actor: norm.actor },
|
|
593
|
+
},
|
|
519
594
|
};
|
|
520
595
|
}
|
|
521
596
|
|
|
597
|
+
/** The casebook row for this decision, or null: no echo, no hook, no AI store method, or the hook declines or fails. */
|
|
598
|
+
private outcomeFor(norm: Normal, report: ReportRecord, now: number): AiOutcomeInsert | null {
|
|
599
|
+
if (this.aiOutcome === undefined || typeof this.store.insertAiOutcome !== 'function') return null;
|
|
600
|
+
try {
|
|
601
|
+
return this.aiOutcome({
|
|
602
|
+
report,
|
|
603
|
+
target: this.subjects.canonical(report.targetSubject),
|
|
604
|
+
verdict: norm.verdict,
|
|
605
|
+
actions: norm.actions.map((a) => ({ subject: a.subject, kind: a.kind, durationMs: a.durationMs, rule: a.rule, lineIds: a.lineIds })),
|
|
606
|
+
ai: { readId: norm.ai.readId, accepted: norm.ai.accepted, severity: norm.ai.severity },
|
|
607
|
+
now,
|
|
608
|
+
});
|
|
609
|
+
} catch (err) {
|
|
610
|
+
this.warn('decide.ai_outcome_failed', { error: errName(err) });
|
|
611
|
+
return null;
|
|
612
|
+
}
|
|
613
|
+
}
|
|
614
|
+
|
|
522
615
|
private replayOf(resultJson: string): DecisionResult {
|
|
523
616
|
const parsed: unknown = JSON.parse(resultJson);
|
|
524
617
|
const groups = (parsed as { groups?: unknown } | null)?.groups;
|
package/src/documents.ts
CHANGED
|
@@ -53,7 +53,7 @@ export interface ModeratorGuideOptions {
|
|
|
53
53
|
export interface PolicyJson {
|
|
54
54
|
version: 1;
|
|
55
55
|
/** With `durations` and `customDuration` filled in, so a profile written for 0.1.1 reads back with the two new keys. */
|
|
56
|
-
profile: ResolvedProfile
|
|
56
|
+
profile: Omit<ResolvedProfile, 'ai'>;
|
|
57
57
|
/** Every rule, retired ones included, in number order. */
|
|
58
58
|
rules: CommunityRule[];
|
|
59
59
|
}
|
|
@@ -705,7 +705,10 @@ export function agentBrief(policy: DocumentPolicy): string {
|
|
|
705
705
|
*/
|
|
706
706
|
export function policyJson(policy: DocumentPolicy): PolicyJson {
|
|
707
707
|
const snapshot = checkPolicy(policy);
|
|
708
|
-
|
|
708
|
+
// The AI settings are the moderator's runtime switch, not policy text: the document tools never carry them.
|
|
709
|
+
const profile: Omit<ResolvedProfile, 'ai'> & { ai?: unknown } = structuredClone(snapshot.profile);
|
|
710
|
+
delete profile.ai;
|
|
711
|
+
return { version: 1, profile, rules: snapshot.rules.all() };
|
|
709
712
|
}
|
|
710
713
|
|
|
711
714
|
/** The four documents bound to one policy, as `cw.documents` exposes them. */
|
package/src/index.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
export const VERSION = '0.1.
|
|
1
|
+
export const VERSION = '0.1.7';
|
|
2
2
|
|
|
3
3
|
export type {
|
|
4
4
|
Clock,
|
|
@@ -26,6 +26,19 @@ export type {
|
|
|
26
26
|
SanctionTargetType,
|
|
27
27
|
ReporterDecision,
|
|
28
28
|
ReporterOutcomeRow,
|
|
29
|
+
AiCallUsage,
|
|
30
|
+
AiErrorKind,
|
|
31
|
+
AiExampleRow,
|
|
32
|
+
AiOutcomeDetail,
|
|
33
|
+
AiOutcomeInsert,
|
|
34
|
+
AiOutcomeRow,
|
|
35
|
+
AiReadDone,
|
|
36
|
+
AiReadPending,
|
|
37
|
+
AiReadRow,
|
|
38
|
+
AiReadStatus,
|
|
39
|
+
AiReserveResult,
|
|
40
|
+
AiStatsRow,
|
|
41
|
+
AiVerdict,
|
|
29
42
|
ReporterTally,
|
|
30
43
|
ClaimAttempt,
|
|
31
44
|
ClaimMode,
|
|
@@ -276,6 +289,7 @@ export {
|
|
|
276
289
|
} from './decide.js';
|
|
277
290
|
export type {
|
|
278
291
|
DecisionAction,
|
|
292
|
+
DecisionAiEcho,
|
|
279
293
|
DecisionGroup,
|
|
280
294
|
DecisionInput,
|
|
281
295
|
DecisionResult,
|
|
@@ -293,6 +307,8 @@ export {
|
|
|
293
307
|
MAX_GUIDELINE_OUTCOME,
|
|
294
308
|
MAX_RULE_LIST,
|
|
295
309
|
MAX_WINDOW_DAYS,
|
|
310
|
+
AI_DAILY_CALLS_DEFAULT,
|
|
311
|
+
AI_DAILY_CALLS_MAX,
|
|
296
312
|
POLICY_SECTIONS,
|
|
297
313
|
PRESETS,
|
|
298
314
|
ProfileError,
|
|
@@ -313,6 +329,7 @@ export type {
|
|
|
313
329
|
GuidelineCover,
|
|
314
330
|
GuidelineTier,
|
|
315
331
|
LevelDescription,
|
|
332
|
+
AISettings,
|
|
316
333
|
ModerationProfile,
|
|
317
334
|
ModerationProfileBase,
|
|
318
335
|
Outcome,
|
|
@@ -327,3 +344,37 @@ export type {
|
|
|
327
344
|
ResolvedProfile,
|
|
328
345
|
RulesFlavour,
|
|
329
346
|
} from './profile.js';
|
|
347
|
+
|
|
348
|
+
// AI levels 1 and 2: the provider-free contract (@experimental). Kept apart from the rest so a bundler can drop it.
|
|
349
|
+
export { AI_PROMPT_VERSION, AIError } from './ai/types.js';
|
|
350
|
+
export type { AbortSignalLike, AIExample, AIExampleInput, AIPerson, AIRead, AIReadInput, AIReadResult, AIStoredRead, AIUsage, ModerationAI } from './ai/types.js';
|
|
351
|
+
export { AI_OUTPUT_SCHEMA } from './ai/schema.js';
|
|
352
|
+
export { validateAIOutput } from './ai/validate.js';
|
|
353
|
+
export type { AIValidation, AIValidationContext } from './ai/validate.js';
|
|
354
|
+
export { AI_MAX_KIND, AI_MAX_PREFILL_MS, AICeilingError, assertWithinCeilings, automationAllowed, isAllowedKind } from './ai/ceilings.js';
|
|
355
|
+
export { redactNote, redactText } from './ai/redact.js';
|
|
356
|
+
export { chooseLines, redactReportNote } from './ai/lines.js';
|
|
357
|
+
export type { ChosenLine, ChosenLines } from './ai/lines.js';
|
|
358
|
+
export { aiPolicyText, buildAIInput, PROMPT_VERSION, usedExampleIds } from './ai/prompt.js';
|
|
359
|
+
export type { BuildAIInputArgs } from './ai/prompt.js';
|
|
360
|
+
export { inputHash } from './ai/hash.js';
|
|
361
|
+
export { looksLikeInjection } from './ai/injection.js';
|
|
362
|
+
export { aiActorOf, AiService, READ_AGAIN_PER_MINUTE, SWEEP_BATCH, SWEEP_EVERY_MS } from './ai/service.js';
|
|
363
|
+
export { createInertAi } from './ai/inert.js';
|
|
364
|
+
export type {
|
|
365
|
+
AiBrief,
|
|
366
|
+
AiFacade,
|
|
367
|
+
AiOptions,
|
|
368
|
+
AiReadAgain,
|
|
369
|
+
AiReadView,
|
|
370
|
+
AiStatsRuleView,
|
|
371
|
+
AiStatsView,
|
|
372
|
+
AiStatus,
|
|
373
|
+
SuggestionStep,
|
|
374
|
+
} from './ai/service.js';
|
|
375
|
+
export { createFakeModerationAI, fakeRead, FAKE_USAGE } from './ai/fake.js';
|
|
376
|
+
export type { FakeCallContext, FakeModerationAI, FakeScript, FakeStep } from './ai/fake.js';
|
|
377
|
+
export { agreementOf, compareSteps } from './ai/agreement.js';
|
|
378
|
+
export type { Agreement, HumanDecision, StepLike } from './ai/agreement.js';
|
|
379
|
+
export { AI_EXAMPLES_MIN } from './ai/casebook.js';
|
|
380
|
+
export type { AiOutcomeArgs, AiOutcomeHook } from './ai/casebook.js';
|
package/src/profile.ts
CHANGED
|
@@ -144,8 +144,35 @@ export interface ModerationProfile extends ModerationProfileBase {
|
|
|
144
144
|
* {@link ReportingSettings}.
|
|
145
145
|
*/
|
|
146
146
|
reporting?: ReportingSettings;
|
|
147
|
+
/**
|
|
148
|
+
* The AI read, in the moderator's hands: `level` 0 is off (the default), 1 reads each report and shows a summary, 2 also
|
|
149
|
+
* recommends; `learn` (default true) lets decided cases teach the read. A level 3 or 4 is refused ("not available yet"). The
|
|
150
|
+
* hub edits this section; the code-side AI option sets the adapter and the highest level it may reach. See {@link AISettings}.
|
|
151
|
+
*/
|
|
152
|
+
ai?: Partial<AISettings>;
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/**
|
|
156
|
+
* The AI levels and the casebook switch, as the profile holds them. The level in force is also bounded by the adapter and the
|
|
157
|
+
* maximum level given in code, and is 0 when no adapter is configured.
|
|
158
|
+
* @experimental
|
|
159
|
+
*/
|
|
160
|
+
export interface AISettings {
|
|
161
|
+
/** 0 off, 1 read, 2 recommend. 3 and 4 are not available yet. */
|
|
162
|
+
level: 0 | 1 | 2;
|
|
163
|
+
/** Whether decided cases may be kept as pseudonymised examples for later reads. Default true. */
|
|
164
|
+
learn: boolean;
|
|
165
|
+
/**
|
|
166
|
+
* The most provider calls the AI may make in a UTC day, a second guard beside the spend cap in code (an adapter that reports no cost
|
|
167
|
+
* cannot run unbounded). A whole number from 1 to 100 000; default 5 000.
|
|
168
|
+
*/
|
|
169
|
+
dailyCalls: number;
|
|
147
170
|
}
|
|
148
171
|
|
|
172
|
+
/** The default and the largest value of {@link AISettings.dailyCalls}. */
|
|
173
|
+
export const AI_DAILY_CALLS_DEFAULT = 5000;
|
|
174
|
+
export const AI_DAILY_CALLS_MAX = 100_000;
|
|
175
|
+
|
|
149
176
|
/**
|
|
150
177
|
* What `defineProfile`, `resolveProfile`, `applyPolicyLayer`, `cw.profile` and `cw.policy.get()` return: a validated, deep-frozen
|
|
151
178
|
* profile with `durations` and `customDuration` filled in. It is a {@link ModerationProfile}, so it can be passed wherever one is
|
|
@@ -164,6 +191,8 @@ export interface ResolvedProfile extends ModerationProfileBase {
|
|
|
164
191
|
customDuration: boolean;
|
|
165
192
|
/** The reporting settings in force, every field filled in. */
|
|
166
193
|
reporting: ResolvedReporting;
|
|
194
|
+
/** The AI settings in force, every field filled in. */
|
|
195
|
+
ai: AISettings;
|
|
167
196
|
}
|
|
168
197
|
|
|
169
198
|
/** @deprecated The same as {@link ModerationProfile}, which now has the two fields optional. */
|
|
@@ -211,12 +240,14 @@ const TOP_KEYS = [
|
|
|
211
240
|
'durations',
|
|
212
241
|
'customDuration',
|
|
213
242
|
'reporting',
|
|
243
|
+
'ai',
|
|
214
244
|
'levels',
|
|
215
245
|
'guidelines',
|
|
216
246
|
] as const;
|
|
217
247
|
/** Top-level keys that may be left out (the kit falls back to its defaults). */
|
|
218
248
|
const RULE_LIST_KEYS: readonly string[] = ['areaRules', 'severeRules'];
|
|
219
|
-
const OPTIONAL_TOP_KEYS: readonly string[] = [...RULE_LIST_KEYS, 'durations', 'customDuration', 'reporting'];
|
|
249
|
+
const OPTIONAL_TOP_KEYS: readonly string[] = [...RULE_LIST_KEYS, 'durations', 'customDuration', 'reporting', 'ai'];
|
|
250
|
+
const AI_KEYS = ['level', 'learn', 'dailyCalls'] as const;
|
|
220
251
|
/** The most rule numbers `areaRules` or `severeRules` may list. */
|
|
221
252
|
export const MAX_RULE_LIST = 100;
|
|
222
253
|
const REPEAT_KEYS = ['windowDays', 'notes', 'distinctGames', 'outcome'] as const;
|
|
@@ -396,6 +427,23 @@ function lineOf(v: unknown, path: string, min: 0 | 1, max: number): void {
|
|
|
396
427
|
}
|
|
397
428
|
}
|
|
398
429
|
|
|
430
|
+
/** The `ai` section, in input shape (both fields optional). Levels 3 and 4 are designed but not built, so they are refused by name. */
|
|
431
|
+
function validateAI(v: unknown, path: string): void {
|
|
432
|
+
const ai = obj(v, path, AI_KEYS, AI_KEYS);
|
|
433
|
+
if (Object.hasOwn(ai, 'level')) {
|
|
434
|
+
const level = ai['level'];
|
|
435
|
+
if (level === 3 || level === 4) fail(`${path}.level`, 'AI levels 3 and 4 are not available yet');
|
|
436
|
+
if (level !== 0 && level !== 1 && level !== 2) fail(`${path}.level`, 'must be 0 (off), 1 (read) or 2 (recommend)');
|
|
437
|
+
}
|
|
438
|
+
if (Object.hasOwn(ai, 'learn') && typeof ai['learn'] !== 'boolean') fail(`${path}.learn`, 'must be true or false');
|
|
439
|
+
if (Object.hasOwn(ai, 'dailyCalls')) {
|
|
440
|
+
const n = ai['dailyCalls'];
|
|
441
|
+
if (typeof n !== 'number' || !Number.isInteger(n) || n < 1 || n > AI_DAILY_CALLS_MAX) {
|
|
442
|
+
fail(`${path}.dailyCalls`, `must be a whole number of calls from 1 to ${AI_DAILY_CALLS_MAX}`);
|
|
443
|
+
}
|
|
444
|
+
}
|
|
445
|
+
}
|
|
446
|
+
|
|
399
447
|
/** The `reporting` section, in input shape (every field optional, a reason needing only an id and a label). */
|
|
400
448
|
function validateReporting(v: unknown, path: string): void {
|
|
401
449
|
const rep = obj(v, path, REPORTING_KEYS, REPORTING_KEYS);
|
|
@@ -477,6 +525,7 @@ export function validateProfile(value: unknown): asserts value is ModerationProf
|
|
|
477
525
|
if (Object.hasOwn(p, 'durations')) validateDurations(p['durations'], 'profile.durations');
|
|
478
526
|
if (Object.hasOwn(p, 'customDuration') && typeof p['customDuration'] !== 'boolean') fail('profile.customDuration', 'must be true or false');
|
|
479
527
|
if (Object.hasOwn(p, 'reporting')) validateReporting(p['reporting'], 'profile.reporting');
|
|
528
|
+
if (Object.hasOwn(p, 'ai')) validateAI(p['ai'], 'profile.ai');
|
|
480
529
|
|
|
481
530
|
const prof = obj(p['profanity'], 'profile.profanity', PROFANITY_KEYS);
|
|
482
531
|
oneOf(prof['mode'], 'profile.profanity.mode', PROFANITY_MODES, "must be 'allow', 'star' or 'refuse'");
|
|
@@ -572,9 +621,16 @@ function dedupeReasonRules(copy: Record<string, unknown>): void {
|
|
|
572
621
|
});
|
|
573
622
|
}
|
|
574
623
|
|
|
575
|
-
/**
|
|
624
|
+
/** The AI settings with every field filled in; a value of the wrong shape is returned as it is, for the validator to name. */
|
|
625
|
+
function fillAI(value: unknown): unknown {
|
|
626
|
+
if (value === undefined) return { level: 0, learn: true, dailyCalls: AI_DAILY_CALLS_DEFAULT };
|
|
627
|
+
return isPlain(value) ? { level: 0, learn: true, dailyCalls: AI_DAILY_CALLS_DEFAULT, ...value } : value;
|
|
628
|
+
}
|
|
629
|
+
|
|
630
|
+
/** A profile written before `durations`, `customDuration`, `reporting` and `ai` existed gets their defaults. */
|
|
576
631
|
function fillDefaults(copy: unknown): void {
|
|
577
632
|
if (!isPlain(copy)) return;
|
|
633
|
+
setOwn(copy, 'ai', fillAI(copy['ai']));
|
|
578
634
|
if (!Object.hasOwn(copy, 'durations')) setOwn(copy, 'durations', [...DEFAULT_DURATIONS]);
|
|
579
635
|
if (!Object.hasOwn(copy, 'customDuration')) setOwn(copy, 'customDuration', true);
|
|
580
636
|
// A section of the wrong shape is left as it is, for the validator to name; one that checks out is filled in.
|
|
@@ -596,7 +652,13 @@ function finalize(value: unknown): ResolvedProfile {
|
|
|
596
652
|
* changed and the profile is not validated here (`validateProfile` does that). Used by the document functions.
|
|
597
653
|
*/
|
|
598
654
|
export function withDurationDefaults(p: ModerationProfile): ResolvedProfile {
|
|
599
|
-
return {
|
|
655
|
+
return {
|
|
656
|
+
...p,
|
|
657
|
+
durations: p.durations ?? [...DEFAULT_DURATIONS],
|
|
658
|
+
customDuration: p.customDuration ?? true,
|
|
659
|
+
reporting: resolveReporting(p.reporting),
|
|
660
|
+
ai: { level: 0, learn: true, dailyCalls: AI_DAILY_CALLS_DEFAULT, ...p.ai },
|
|
661
|
+
};
|
|
600
662
|
}
|
|
601
663
|
|
|
602
664
|
// ---------------------------------------------------------------------------------------------------------------
|
|
@@ -916,7 +978,7 @@ export function defineProfile(p: ModerationProfile): ResolvedProfile {
|
|
|
916
978
|
* The parts of a profile the hub may edit, and the order they are listed in. Everything else (identity, the written
|
|
917
979
|
* levels, the AI context, profanity handling) stays in code: changing profanity means rebuilding the filter.
|
|
918
980
|
*/
|
|
919
|
-
export const POLICY_SECTIONS = ['durations', 'customDuration', 'ladder', 'firstOffense', 'repeat', 'areaRules', 'severeRules', 'guidelines', 'reporting'] as const;
|
|
981
|
+
export const POLICY_SECTIONS = ['durations', 'customDuration', 'ladder', 'firstOffense', 'repeat', 'areaRules', 'severeRules', 'guidelines', 'reporting', 'ai'] as const;
|
|
920
982
|
export type PolicySection = (typeof POLICY_SECTIONS)[number];
|
|
921
983
|
|
|
922
984
|
/** One ladder cell as the editor sends it: the label may be left out and is then generated ("Restrict chat 6 hours"). */
|
|
@@ -950,6 +1012,8 @@ export interface PolicyLayer {
|
|
|
950
1012
|
guidelines?: Array<{ outcome: string } | null>;
|
|
951
1013
|
/** The reporting settings: `flow` and `thanks` replace the profile's; `reasons` replaces the whole list. Each is optional; a reason needs only `id` and `label`. */
|
|
952
1014
|
reporting?: ReportingSettings;
|
|
1015
|
+
/** The AI settings: `level` (0 off, 1 read, 2 recommend), `learn` and `dailyCalls` (the owner's ceiling on calls in a UTC day, a whole number from 1 to 100 000). Each is optional and merges onto the profile's. Levels 3 and 4 are refused. */
|
|
1016
|
+
ai?: Partial<AISettings>;
|
|
953
1017
|
}
|
|
954
1018
|
|
|
955
1019
|
/** The longest outcome text a layer may set on a guideline tier. */
|
package/src/retention.ts
CHANGED
|
@@ -25,6 +25,16 @@ export interface RetentionPolicy {
|
|
|
25
25
|
badFaithMs: number;
|
|
26
26
|
/** A staff audit entry is deleted once it is older than this. */
|
|
27
27
|
auditMs: number;
|
|
28
|
+
/**
|
|
29
|
+
* An AI outcome row (the agree-or-override record: ids and counts, no chat text) is kept this long. At least 90 days. A read
|
|
30
|
+
* itself goes with its report (`reportsMs`).
|
|
31
|
+
*/
|
|
32
|
+
aiOutcomesMs: number;
|
|
33
|
+
/**
|
|
34
|
+
* The pseudonymised example text kept with an AI outcome is deleted once it is older than this. It is the only chat text that
|
|
35
|
+
* outlives a report, so it is the shortest of the three; 0 keeps no text at all.
|
|
36
|
+
*/
|
|
37
|
+
aiExamplesMs: number;
|
|
28
38
|
}
|
|
29
39
|
|
|
30
40
|
export const RETENTION_DEFAULTS: Readonly<RetentionPolicy> = {
|
|
@@ -34,12 +44,14 @@ export const RETENTION_DEFAULTS: Readonly<RetentionPolicy> = {
|
|
|
34
44
|
noticesMs: 90 * DAY_MS,
|
|
35
45
|
badFaithMs: 30 * DAY_MS,
|
|
36
46
|
auditMs: 365 * DAY_MS,
|
|
47
|
+
aiOutcomesMs: 365 * DAY_MS,
|
|
48
|
+
aiExamplesMs: 180 * DAY_MS,
|
|
37
49
|
};
|
|
38
50
|
|
|
39
51
|
/** The ladder looks back 90 days and "My record" shows 90 days, so the rows behind them must outlive that. */
|
|
40
52
|
const RECORD_FLOOR_MS = 90 * DAY_MS;
|
|
41
53
|
|
|
42
|
-
const FIELDS = ['reportsMs', 'sanctionAfterEndMs', 'strikesMs', 'noticesMs', 'badFaithMs', 'auditMs'] as const;
|
|
54
|
+
const FIELDS = ['reportsMs', 'sanctionAfterEndMs', 'strikesMs', 'noticesMs', 'badFaithMs', 'auditMs', 'aiOutcomesMs', 'aiExamplesMs'] as const;
|
|
43
55
|
|
|
44
56
|
/**
|
|
45
57
|
* Refuse a retention policy that would delete rows the kit still reads. Only the fields present are checked (an
|
|
@@ -48,6 +60,8 @@ const FIELDS = ['reportsMs', 'sanctionAfterEndMs', 'strikesMs', 'noticesMs', 'ba
|
|
|
48
60
|
* - `noticesMs` at least 90 days: "My record" shows that far back
|
|
49
61
|
* - `badFaithMs` at least `suspendWindowMs`: a bad-faith dismissal weighs against its reporter for that long
|
|
50
62
|
* - `auditMs` at least 90 days: the staff trail is how a community answers "who did that"
|
|
63
|
+
* - `aiOutcomesMs` at least 90 days: the agree-or-override record is the data the AI's later gates read
|
|
64
|
+
* - `aiExamplesMs` at least 0 (0 keeps no example text at all)
|
|
51
65
|
*
|
|
52
66
|
* Every field present must also be a finite number (`reportsMs` and `strikesMs` have no floor, only this).
|
|
53
67
|
*
|
|
@@ -76,6 +90,12 @@ export function checkRetentionFloors(policy: Partial<RetentionPolicy>, suspendWi
|
|
|
76
90
|
if (below(policy.auditMs, RECORD_FLOOR_MS)) {
|
|
77
91
|
throw new ProfileError('retention.auditMs', 'must be at least 90 days: the audit trail answers who did what, and when');
|
|
78
92
|
}
|
|
93
|
+
if (below(policy.aiOutcomesMs, RECORD_FLOOR_MS)) {
|
|
94
|
+
throw new ProfileError('retention.aiOutcomesMs', 'must be at least 90 days: it is the record of how often the AI and the moderators agreed');
|
|
95
|
+
}
|
|
96
|
+
if (below(policy.aiExamplesMs, 0)) {
|
|
97
|
+
throw new ProfileError('retention.aiExamplesMs', 'must be 0 or more: 0 keeps no example text at all');
|
|
98
|
+
}
|
|
79
99
|
if (below(policy.badFaithMs, suspendWindowMs)) {
|
|
80
100
|
throw new ProfileError(
|
|
81
101
|
'retention.badFaithMs',
|
|
@@ -94,6 +114,10 @@ export interface PurgeResult {
|
|
|
94
114
|
notices: number;
|
|
95
115
|
audit: number;
|
|
96
116
|
webhookKeys: number;
|
|
117
|
+
/** AI reads deleted by the retention pass (a read also goes with its report). 0 for a store without the AI methods. */
|
|
118
|
+
aiReads: number;
|
|
119
|
+
/** AI casebook outcomes deleted. 0 for a store without the AI methods. */
|
|
120
|
+
aiOutcomes: number;
|
|
97
121
|
}
|
|
98
122
|
|
|
99
123
|
function checkWindow(name: string, ms: number): void {
|
|
@@ -114,6 +138,9 @@ function checkWindow(name: string, ms: number): void {
|
|
|
114
138
|
* term-editor rows written before the trail existed
|
|
115
139
|
* - webhook keys: `createdAt < now - 24 h` (incoming-webhook idempotency keys, pending or done)
|
|
116
140
|
* - mutes: `createdAt < now - 180 days`, the mute TTL (a mute past it is already ignored)
|
|
141
|
+
* - AI reads: `createdAt < now - reportsMs` (a read also goes with its report, in `purgeReports`); AI outcomes (agree-or-override
|
|
142
|
+
* record, no chat text): `decidedAt < now - aiOutcomesMs`; the pseudonymised example kept with an outcome:
|
|
143
|
+
* `decidedAt < now - aiExamplesMs`, the row stays with its counts. A store without the AI methods has none of these.
|
|
117
144
|
* - notices: withdrawn, or a seen warning / report outcome, with `createdAt < now - noticesMs`; or
|
|
118
145
|
* `until < now - noticesMs`. A notice for a permanent or running sanction is kept while it applies (agrees with
|
|
119
146
|
* `NoticeService.record`), and an unseen warning is kept until it is seen or withdrawn.
|
|
@@ -133,6 +160,8 @@ export async function purge(
|
|
|
133
160
|
noticesMs: policy.noticesMs ?? RETENTION_DEFAULTS.noticesMs,
|
|
134
161
|
badFaithMs: policy.badFaithMs ?? RETENTION_DEFAULTS.badFaithMs,
|
|
135
162
|
auditMs: policy.auditMs ?? RETENTION_DEFAULTS.auditMs,
|
|
163
|
+
aiOutcomesMs: policy.aiOutcomesMs ?? RETENTION_DEFAULTS.aiOutcomesMs,
|
|
164
|
+
aiExamplesMs: policy.aiExamplesMs ?? RETENTION_DEFAULTS.aiExamplesMs,
|
|
136
165
|
};
|
|
137
166
|
if (!Number.isFinite(now)) throw new Error('purge: invalid now');
|
|
138
167
|
checkWindow('reportsMs', p.reportsMs);
|
|
@@ -141,13 +170,21 @@ export async function purge(
|
|
|
141
170
|
checkWindow('noticesMs', p.noticesMs);
|
|
142
171
|
checkWindow('badFaithMs', p.badFaithMs);
|
|
143
172
|
checkWindow('auditMs', p.auditMs);
|
|
144
|
-
|
|
145
|
-
|
|
146
|
-
|
|
147
|
-
|
|
148
|
-
|
|
149
|
-
|
|
150
|
-
|
|
151
|
-
|
|
152
|
-
|
|
173
|
+
checkWindow('aiOutcomesMs', p.aiOutcomesMs);
|
|
174
|
+
checkWindow('aiExamplesMs', p.aiExamplesMs);
|
|
175
|
+
return store.transaction(() => {
|
|
176
|
+
const reports = store.purgeReports(now - p.reportsMs, now - p.badFaithMs);
|
|
177
|
+
const ai = store.purgeAi?.(now - p.reportsMs, now - p.aiOutcomesMs, now - p.aiExamplesMs) ?? { reads: 0, outcomes: 0 };
|
|
178
|
+
return {
|
|
179
|
+
reports,
|
|
180
|
+
sanctions: store.purgeSanctions(now - p.sanctionAfterEndMs),
|
|
181
|
+
strikes: store.purgeStrikes(now - p.strikesMs),
|
|
182
|
+
mutes: store.purgeMutes(now - MUTE_TTL_MS),
|
|
183
|
+
notices: store.purgeNotices(now - p.noticesMs),
|
|
184
|
+
audit: store.purgeAudit(now - p.auditMs),
|
|
185
|
+
webhookKeys: store.purgeWebhookKeys(now - WEBHOOK_KEY_TTL_MS),
|
|
186
|
+
aiReads: ai.reads,
|
|
187
|
+
aiOutcomes: ai.outcomes,
|
|
188
|
+
};
|
|
189
|
+
});
|
|
153
190
|
}
|