@hatk/hatk 0.0.1-alpha.11 → 0.0.1-alpha.111

package/dist/classifiers.d.ts

@@ -0,0 +1,228 @@
+/** A typed question in the shape Clef accepts. */
+export interface ClassifierQuestion {
+    type: 'noul' | 'choice' | 'score';
+    instructions: string | Record<string, unknown> | unknown[];
+    criteria?: unknown;
+}
+/** The thing being scored: an account (by DID) or a single record. */
+export interface ClassifierSubject {
+    /** `at://` URI for a record subject; the bare DID for an account subject. */
+    uri: string;
+    did: string;
+    handle?: string | null;
+    collection?: string;
+    value?: Record<string, any>;
+}
+export interface ClassifierContext {
+    db: {
+        query: (sql: string, params?: any[]) => Promise<any[]>;
+        run: (sql: string, ...params: any[]) => Promise<void>;
+    };
+    subject: ClassifierSubject;
+}
+export interface ClassifierModule {
+    /** `account` scans every indexed repo; `record` scans rows of `collections`. */
+    subject: 'account' | 'record';
+    /** Collections to scan. Required when `subject` is `record`. */
+    collections?: string[];
+    /** The questions to ask. Answers come back under the same keys. Omit when
+     *  the classifier supplies its own `classify`. */
+    questions?: Record<string, ClassifierQuestion>;
+    /**
+     * Produce signals without asking Clef.
+     *
+     * A classifier that runs its own model — an image classifier on the host, a
+     * hash lookup, a heuristic — sets this instead of `questions`. Everything
+     * downstream is unchanged: the same thresholds, the same report, the same
+     * review card. Return a bare number for a plain score.
+     */
+    classify?: (state: Record<string, unknown>, ctx: ClassifierContext) => Promise<Record<string, number | Signal>>;
+    /**
+     * Build the model `state` for this subject. Return `null` to skip it — a
+     * skipped subject costs no tokens. Gate on whatever makes the question
+     * answerable: an account with no content cannot be judged on its content.
+     */
+    buildState: (ctx: ClassifierContext) => Promise<Record<string, unknown> | null>;
+    /**
+     * URLs of images to show the model alongside `state`, at most four. hatk
+     * fetches each and embeds it in the request, since Clef takes images inline
+     * rather than by reference.
+     *
+     * Return small renditions. Clef's context window is counted on the encoded
+     * bytes, so a full-size photo can overflow it where a 512px one never does.
+     * The state should carry whatever identifies the image — a blob CID — so
+     * that a changed image changes the fingerprint and is scored again.
+     */
+    images?: (state: Record<string, unknown>, ctx: ClassifierContext) => Promise<string[]> | string[];
+    /**
+     * Score at or above which a signal files a report. A number applies to every
+     * question; a map sets it per question. Questions absent from the map never
+     * file, though their scores are still stored and shown.
+     */
+    threshold?: number | Record<string, number>;
+    /** Label the filed report carries. A function receives the crossing signal. */
+    label?: string | ((signal: string, score: number) => string);
+}
+export declare function defineClassifier(module: ClassifierModule): {
+    /** `account` scans every indexed repo; `record` scans rows of `collections`. */
+    subject: "account" | "record";
+    /** Collections to scan. Required when `subject` is `record`. */
+    collections?: string[];
+    /** The questions to ask. Answers come back under the same keys. Omit when
+     *  the classifier supplies its own `classify`. */
+    questions?: Record<string, ClassifierQuestion>;
+    /**
+     * Produce signals without asking Clef.
+     *
+     * A classifier that runs its own model — an image classifier on the host, a
+     * hash lookup, a heuristic — sets this instead of `questions`. Everything
+     * downstream is unchanged: the same thresholds, the same report, the same
+     * review card. Return a bare number for a plain score.
+     */
+    classify?: (state: Record<string, unknown>, ctx: ClassifierContext) => Promise<Record<string, number | Signal>>;
+    /**
+     * Build the model `state` for this subject. Return `null` to skip it — a
+     * skipped subject costs no tokens. Gate on whatever makes the question
+     * answerable: an account with no content cannot be judged on its content.
+     */
+    buildState: (ctx: ClassifierContext) => Promise<Record<string, unknown> | null>;
+    /**
+     * URLs of images to show the model alongside `state`, at most four. hatk
+     * fetches each and embeds it in the request, since Clef takes images inline
+     * rather than by reference.
+     *
+     * Return small renditions. Clef's context window is counted on the encoded
+     * bytes, so a full-size photo can overflow it where a 512px one never does.
+     * The state should carry whatever identifies the image — a blob CID — so
+     * that a changed image changes the fingerprint and is scored again.
+     */
+    images?: (state: Record<string, unknown>, ctx: ClassifierContext) => Promise<string[]> | string[];
+    /**
+     * Score at or above which a signal files a report. A number applies to every
+     * question; a map sets it per question. Questions absent from the map never
+     * file, though their scores are still stored and shown.
+     */
+    threshold?: number | Record<string, number>;
+    /** Label the filed report carries. A function receives the crossing signal. */
+    label?: string | ((signal: string, score: number) => string);
+    __type: "classifiers";
+};
+interface LoadedClassifier extends ClassifierModule {
+    name: string;
+}
+/** Discover and load classifier modules from the `classifiers/` directory. */
+export declare function initClassifiers(classifiersDir: string): Promise<void>;
+/**
+ * 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 declare function registerClassifier(name: string, module: ClassifierModule): void;
+/** Clear all registered classifiers (for hot-reload). */
+export declare function clearClassifiers(): void;
+/** Names of all loaded classifiers. */
+export declare function listClassifiers(): string[];
+export declare function getClassifier(name: string): LoadedClassifier | undefined;
+export interface ClefClientConfig {
+    apiToken: string;
+    model: string;
+    endpoint: string;
+}
+export declare function configureClef(config: ClefClientConfig | null): void;
+export declare function isClefConfigured(): boolean;
+/** A single answer, normalized to a 0–1 score regardless of question type. */
+export interface Signal {
+    score: number;
+    type: string;
+    /** Choice/Score only: the selected option and its confidence. */
+    choice?: string;
+    confidence?: number;
+}
+/**
+ * Ask Clef 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 declare function askClef(state: Record<string, unknown>, questions: Record<string, ClassifierQuestion>, opts?: {
+    images?: string[];
+    attempts?: number;
+    signal?: AbortSignal;
+}): Promise<{
+    answers: Record<string, Signal>;
+    model: string;
+    inputTokens: number;
+}>;
+export interface ScanProgress {
+    /** Subjects considered. */
+    scanned: number;
+    /** Gated out by `buildState` returning null, or unchanged since the last scan. */
+    skipped: number;
+    /** Sent to the model and stored. */
+    scored: number;
+    /** Reports filed for crossing a threshold. */
+    filed: number;
+    errors: number;
+    inputTokens: number;
+    running: boolean;
+    startedAt: string;
+    finishedAt?: string;
+    error?: string;
+}
+/** When a TID record key was minted, or null if the key is not a TID. */
+export declare function tidTime(rkey: string): Date | null;
+/** Progress of the scan in flight, or the last one to finish. */
+export declare function getScanProgress(): ScanProgress | null;
+/**
+ * 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 declare function runScan(opts?: {
+    classifier?: string;
+    force?: boolean;
+    limit?: number;
+    concurrency?: number;
+    signal?: AbortSignal;
+    /** Only subjects new after this ISO time; see {@link enumerateSubjects}. */
+    since?: string;
+}): Promise<ScanProgress>;
+/** For tests: run the boot catch-up after `ms` rather than a minute. */
+export declare function _setCatchUpDelayForTests(ms: number): void;
+/**
+ * Score new content as it is indexed, from the moment this was first switched
+ * on. What existed before then is never scored here — a pass over the existing
+ * library is a deliberate, manual scan from /admin.
+ *
+ * Starts with one catch-up pass over everything new since that moment, which
+ * picks up what a restart dropped from the queue; anything already scored is
+ * skipped on its fingerprint before it costs a model call.
+ */
+export declare function startScoringOnIndex(): Promise<void>;
+export declare function stopScoringOnIndex(): void;
+/**
+ * Called by the indexer with each batch it applied. Queues every new record for
+ * the record classifiers that cover its collection, and its author for the
+ * account classifiers once the author has settled. Returns immediately: the
+ * indexer never waits on a model.
+ */
+export declare function noteIndexed(items: Array<{
+    action: 'create' | 'delete';
+    collection: string;
+    uri: string;
+    authorDid: string;
+}>): void;
+/**
+ * Called by the indexer when a repo backfill lands. Its rows were written
+ * without passing through {@link noteIndexed} — a new account's first posts
+ * arrive this way — so queue whatever in it is new.
+ */
+export declare function noteBackfilled(did: string): void;
+/** Items waiting to be scored, for tests and the admin view. */
+export declare function pendingCount(): number;
+export {};
+//# sourceMappingURL=classifiers.d.ts.map

package/dist/classifiers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"classifiers.d.ts","sourceRoot":"","sources":["../src/classifiers.ts"],"names":[],"mappings":"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"}