@hatk/hatk 0.0.1-alpha.97 → 0.0.1-alpha.99

package/dist/classifiers.js

@@ -1,370 +0,0 @@
-var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExtension) || function (path, preserveJsx) {
-    if (typeof path === "string" && /^\.\.?\//.test(path)) {
-        return path.replace(/\.(tsx)$|((?:\.d)?)((?:\.[^./]+?)?)\.([cm]?)ts$/i, function (m, tsx, d, ext, cm) {
-            return tsx ? preserveJsx ? ".jsx" : ".js" : d && (!ext || !cm) ? m : (d + ext + "." + cm.toLowerCase() + "js");
-        });
-    }
-    return path;
-};
-/**
- * Classifier system for scoring accounts and records with a System One model.
- *
- * A classifier is the moderation counterpart to a label rule: where a label rule
- * decides from the record alone, a classifier asks a model a set of narrow typed
- * questions and stores the probabilities. Nothing acts on a score — crossing a
- * threshold files a report into the same `_reports` queue a user report lands in,
- * so a person still makes every enforcement decision.
- *
- * Place classifier modules in the `classifiers/` directory.
- *
- * @example
- * ```ts
- * // classifiers/impersonation.ts
- * import { defineClassifier } from '$hatk'
- *
- * export default defineClassifier({
- *   subject: 'account',
- *   label: 'impersonation',
- *   threshold: 0.7,
- *   questions: {
- *     passing_as: {
- *       type: 'noul',
- *       instructions: 'Is this account trying to be mistaken for a famous person?',
- *     },
- *   },
- *   async buildState({ subject, db }) {
- *     const [p] = await db.query(`SELECT description FROM profile WHERE did = $1`, [subject.did])
- *     return { handle: subject.handle, bio: p?.description }
- *   },
- * })
- * ```
- */
-import { resolve } from 'node:path';
-import { readdirSync } from 'node:fs';
-import { createHash } from 'node:crypto';
-import { querySQL, runSQL, getSchema, upsertClassification, getClassificationFingerprints, findOpenReport, insertReport, } from "./database/db.js";
-import { log, emit } from "./logger.js";
-export function defineClassifier(module) {
-    return { __type: 'classifiers', ...module };
-}
-const classifiers = [];
-/** Discover and load classifier modules from the `classifiers/` directory. */
-export async function initClassifiers(classifiersDir) {
-    let files;
-    try {
-        files = readdirSync(classifiersDir)
-            .filter((f) => (f.endsWith('.ts') || f.endsWith('.js')) && !f.startsWith('_'))
-            .sort();
-    }
-    catch {
-        return;
-    }
-    for (const file of files) {
-        const name = file.replace(/\.(ts|js)$/, '');
-        const scriptPath = resolve(classifiersDir, file);
-        const mod = await import(__rewriteRelativeImportExtension(/* @vite-ignore */ `${scriptPath}?t=${Date.now()}`));
-        const handler = mod.default;
-        if (!handler?.buildState || !(handler.questions || handler.classify)) {
-            log(`[classifiers] skipped ${name}: needs buildState plus questions or classify`);
-            continue;
-        }
-        classifiers.push({ name, ...handler });
-        log(`[classifiers] discovered: ${name} (${handler.subject})`);
-    }
-}
-/**
- * Register a classifier directly, bypassing directory discovery.
- *
- * Mirrors {@link registerLabelModule}: tests and embedders that build their own
- * module graph have no `classifiers/` directory to read.
- */
-export function registerClassifier(name, module) {
-    classifiers.push({ name, ...module });
-}
-/** Clear all registered classifiers (for hot-reload). */
-export function clearClassifiers() {
-    classifiers.length = 0;
-}
-/** Names of all loaded classifiers. */
-export function listClassifiers() {
-    return classifiers.map((c) => c.name);
-}
-export function getClassifier(name) {
-    return classifiers.find((c) => c.name === name);
-}
-let systemOne = null;
-export function configureSystemOne(config) {
-    systemOne = config;
-}
-export function isSystemOneConfigured() {
-    return systemOne !== null;
-}
-const RETRYABLE = new Set([408, 429, 500, 502, 503, 504]);
-/**
- * Ask the model one request's worth of questions about one state.
- *
- * Retries on 429 and 5xx, honoring `retry-after` when the response carries one.
- * The caller's concurrency is what keeps us under the rate limit; this only
- * recovers the requests that still slip past it.
- */
-export async function askSystemOne(state, questions, opts = {}) {
-    if (!systemOne)
-        throw new Error('System One is not configured — set `typesafe` in hatk.config.ts');
-    const attempts = opts.attempts ?? 4;
-    const body = JSON.stringify({ state, model: systemOne.model, questions });
-    let lastError = null;
-    for (let attempt = 0; attempt < attempts; attempt++) {
-        try {
-            const res = await fetch(systemOne.endpoint, {
-                method: 'POST',
-                headers: { authorization: `Bearer ${systemOne.apiKey}`, 'content-type': 'application/json' },
-                body,
-                signal: opts.signal,
-            });
-            if (!res.ok) {
-                if (!RETRYABLE.has(res.status) || attempt === attempts - 1) {
-                    throw new Error(`System One ${res.status}: ${(await res.text()).slice(0, 200)}`);
-                }
-                const retryAfter = Number(res.headers.get('retry-after'));
-                const waitMs = Number.isFinite(retryAfter) && retryAfter > 0 ? retryAfter * 1000 : 2 ** attempt * 500;
-                await new Promise((r) => setTimeout(r, waitMs));
-                continue;
-            }
-            const json = (await res.json());
-            const answers = {};
-            for (const [key, a] of Object.entries(json.answers ?? {})) {
-                answers[key] = normalizeAnswer(a);
-            }
-            return { answers, model: json.model ?? systemOne.model, inputTokens: json.usage?.input_tokens ?? 0 };
-        }
-        catch (err) {
-            if (err?.name === 'AbortError')
-                throw err;
-            lastError = err;
-            if (attempt === attempts - 1)
-                break;
-            await new Promise((r) => setTimeout(r, 2 ** attempt * 500));
-        }
-    }
-    throw lastError ?? new Error('System One request failed');
-}
-/**
- * Collapse any answer type to one 0–1 number so a mixed question set can share a
- * threshold. A Noul is already a probability. A Choice reports the probability
- * of the option it picked, and a Score its position across the levels — both
- * keep the original answer alongside, because the number alone loses which
- * option was chosen.
- */
-function normalizeAnswer(a) {
-    if (a?.type === 'noul')
-        return { score: a.noul ?? 0, type: 'noul' };
-    if (a?.type === 'choice') {
-        const choice = a.choice;
-        return { score: a.probabilities?.[choice] ?? 0, type: 'choice', choice, confidence: a.confidence };
-    }
-    if (a?.type === 'score') {
-        const levels = a.probabilities ? Object.keys(a.probabilities).length : 0;
-        const raw = typeof a.score === 'number' ? a.score : 0;
-        return {
-            score: levels > 1 ? raw / (levels - 1) : raw,
-            type: 'score',
-            choice: String(a.score),
-            confidence: a.confidence,
-        };
-    }
-    return { score: 0, type: a?.type ?? 'unknown' };
-}
-function thresholdFor(c, signal) {
-    if (c.threshold == null)
-        return null;
-    if (typeof c.threshold === 'number')
-        return c.threshold;
-    return c.threshold[signal] ?? null;
-}
-function labelFor(c, signal, score) {
-    if (typeof c.label === 'function')
-        return c.label(signal, score);
-    return c.label ?? 'spam';
-}
-const dbCtx = {
-    query: (sql, params) => querySQL(sql, params),
-    run: (sql, ...params) => runSQL(sql, params).then(() => undefined),
-};
-/** Every subject a classifier applies to, as `{uri, did, handle, value}`. */
-async function enumerateSubjects(c) {
-    if (c.subject === 'account') {
-        const rows = (await querySQL(`SELECT did, handle FROM _repos WHERE status = 'active'`));
-        return rows.map((r) => ({ uri: r.did, did: r.did, handle: r.handle }));
-    }
-    const out = [];
-    for (const collection of c.collections ?? []) {
-        const schema = getSchema(collection);
-        if (!schema)
-            continue;
-        const rows = (await querySQL(`SELECT * FROM ${schema.tableName}`));
-        for (const row of rows) {
-            const value = {};
-            for (const col of schema.columns) {
-                let v = row[col.name];
-                if (v === null || v === undefined)
-                    continue;
-                if (col.isJson && typeof v === 'string') {
-                    try {
-                        v = JSON.parse(v);
-                    }
-                    catch { }
-                }
-                value[col.originalName] = v;
-            }
-            out.push({ uri: row.uri, did: row.did, collection, value });
-        }
-    }
-    return out;
-}
-let current = null;
-/** Progress of the scan in flight, or the last one to finish. */
-export function getScanProgress() {
-    return current;
-}
-/**
- * Score every subject a classifier applies to, storing results and filing a
- * report for each crossing signal.
- *
- * Subjects whose state is unchanged since the last scan are skipped unless
- * `force` is set, so a repeat scan costs only what actually moved.
- */
-export async function runScan(opts = {}) {
-    if (current?.running)
-        throw new Error('A scan is already running');
-    const selected = opts.classifier ? classifiers.filter((c) => c.name === opts.classifier) : classifiers;
-    if (!selected.length)
-        throw new Error(opts.classifier ? `No classifier named ${opts.classifier}` : 'No classifiers');
-    // Only the classifiers that actually ask a model need one configured. A
-    // host-local classifier runs with no API key at all.
-    if (selected.some((c) => !c.classify) && !isSystemOneConfigured())
-        throw new Error('System One is not configured');
-    const progress = {
-        scanned: 0,
-        skipped: 0,
-        scored: 0,
-        filed: 0,
-        errors: 0,
-        inputTokens: 0,
-        running: true,
-        startedAt: new Date().toISOString(),
-    };
-    current = progress;
-    try {
-        for (const c of selected) {
-            const subjects = await enumerateSubjects(c);
-            const seen = opts.force ? new Map() : await getClassificationFingerprints(c.name);
-            // The questions are part of what produced a score, so the fingerprint
-            // covers them as well as the state: rewording a classifier's criteria
-            // invalidates every score written under the old wording.
-            const questionsHash = createHash('sha256')
-                .update(JSON.stringify(c.questions ?? c.classify?.toString() ?? ''))
-                .digest('hex')
-                .slice(0, 16);
-            const queue = opts.limit ? subjects.slice(0, opts.limit) : subjects;
-            const concurrency = opts.concurrency ?? 8;
-            let cursor = 0;
-            const worker = async () => {
-                while (cursor < queue.length) {
-                    if (opts.signal?.aborted)
-                        return;
-                    const subject = queue[cursor++];
-                    progress.scanned++;
-                    try {
-                        const state = await c.buildState({ db: dbCtx, subject });
-                        if (!state) {
-                            progress.skipped++;
-                            continue;
-                        }
-                        const fingerprint = createHash('sha256')
-                            .update(questionsHash)
-                            .update(JSON.stringify(state))
-                            .digest('hex')
-                            .slice(0, 32);
-                        if (seen.get(subject.uri) === fingerprint) {
-                            progress.skipped++;
-                            continue;
-                        }
-                        let answers;
-                        let model;
-                        if (c.classify) {
-                            const raw = await c.classify(state, { db: dbCtx, subject });
-                            answers = Object.fromEntries(Object.entries(raw).map(([k, v]) => [k, typeof v === 'number' ? { score: v, type: 'local' } : v]));
-                            model = `local:${c.name}`;
-                        }
-                        else {
-                            const res = await askSystemOne(state, c.questions, { signal: opts.signal });
-                            answers = res.answers;
-                            model = res.model;
-                            progress.inputTokens += res.inputTokens;
-                        }
-                        let topSignal = null;
-                        let topScore = 0;
-                        for (const [name, sig] of Object.entries(answers)) {
-                            if (sig.score > topScore) {
-                                topScore = sig.score;
-                                topSignal = name;
-                            }
-                        }
-                        await upsertClassification({
-                            subjectUri: subject.uri,
-                            subjectDid: subject.did,
-                            classifier: c.name,
-                            signals: answers,
-                            state,
-                            topSignal,
-                            topScore,
-                            fingerprint,
-                            model,
-                        });
-                        progress.scored++;
-                        // File on the highest-scoring signal that crosses its own threshold —
-                        // a second report for the same subject would only split the review.
-                        let crossing = null;
-                        for (const [name, sig] of Object.entries(answers)) {
-                            const t = thresholdFor(c, name);
-                            if (t != null && sig.score >= t && (!crossing || sig.score > crossing.score)) {
-                                crossing = { signal: name, score: sig.score };
-                            }
-                        }
-                        if (crossing) {
-                            const label = labelFor(c, crossing.signal, crossing.score);
-                            if (!(await findOpenReport(subject.uri, label))) {
-                                await insertReport({
-                                    subjectUri: subject.uri,
-                                    subjectDid: subject.did,
-                                    label,
-                                    reason: `${c.name}: ${crossing.signal} ${crossing.score.toFixed(2)}`,
-                                    reportedBy: `system:${c.name}`,
-                                });
-                                progress.filed++;
-                            }
-                        }
-                    }
-                    catch (err) {
-                        if (err?.name === 'AbortError')
-                            return;
-                        progress.errors++;
-                        emit('classifiers', 'scan_error', { classifier: c.name, subject: subject.uri, error: err.message });
-                    }
-                }
-            };
-            await Promise.all(Array.from({ length: Math.min(concurrency, queue.length) }, worker));
-        }
-    }
-    catch (err) {
-        progress.error = err.message;
-        throw err;
-    }
-    finally {
-        progress.running = false;
-        progress.finishedAt = new Date().toISOString();
-        log(`[classifiers] scan: ${progress.scored} scored, ${progress.skipped} skipped, ` +
-            `${progress.filed} filed, ${progress.errors} errors, ${progress.inputTokens} tokens`);
-    }
-    return progress;
-}