@postalsys/email-content 0.1.8 → 0.1.9

package/dist/annotate/agreement.d.ts

@@ -0,0 +1,99 @@
+/**
+ * Agreement between annotators.
+ *
+ * `evaluate` scores the extractor against a reference. This scores an annotator against other
+ * annotators, which is the question a new annotator has to answer before its labels are worth
+ * anything: two strong models agree on 97.6 percent of blocks and a weak one on 80.5
+ * (docs/annotation.md), so a candidate's agreement with the strong models says which of those it
+ * resembles.
+ *
+ * Pure over rows, so it is testable without a database.
+ */
+import { type Label } from '../types';
+import { type LabelProbabilities } from './probabilities';
+export interface AnnotatedBlock {
+    path: string;
+    representation: string;
+    blockIndex: number;
+    mimePart: string | null;
+    blockStart: number | null;
+    blockEnd: number | null;
+    charCount: number;
+    label: Label;
+    probabilities: LabelProbabilities | null;
+    lang: string | null;
+}
+export interface PairCount {
+    reference: Label;
+    candidate: Label;
+    blocks: number;
+}
+export interface ReferenceAgreement {
+    name: string;
+    /** Blocks labelled by both the candidate and this reference. */
+    shared: number;
+    agreed: number;
+    sharedChars: number;
+    agreedChars: number;
+    /** The candidate would hide what this reference calls authored: the expensive direction. */
+    expensive: {
+        blocks: number;
+        chars: number;
+    };
+    /** The candidate leaves visible what this reference calls history: the cheap direction. */
+    cheap: {
+        blocks: number;
+        chars: number;
+    };
+    /** Most frequent disagreements, largest first. */
+    pairs: PairCount[];
+    perLabel: {
+        label: Label;
+        support: number;
+        agreed: number;
+    }[];
+    perLang: {
+        lang: string;
+        shared: number;
+        agreed: number;
+    }[];
+}
+export interface AgreementReport {
+    candidateBlocks: number;
+    /** Candidate blocks no reference has a label for, usually because segmentation changed. */
+    unmatched: number;
+    /** Cost ratio re-applied to the candidate's stored distributions, or null for stored labels. */
+    costRatio: number | null;
+    /** Candidate blocks whose label was recomputed from a stored distribution. */
+    rescored: number;
+    references: ReferenceAgreement[];
+    /**
+     * Blocks every reference calls authored and the candidate would hide. The gate number: an
+     * annotator that hides what all strong models agree was written by the sender cannot be used
+     * to size content loss, whatever its overall agreement.
+     */
+    consensusExpensive: {
+        blocks: number;
+        chars: number;
+        shared: number;
+    };
+}
+/**
+ * Identity of a block. Offsets as well as the index, because annotation runs made under different
+ * extractor versions can segment the same message differently, and pairing block 7 with a
+ * different block 7 would count a segmentation change as a disagreement.
+ */
+export declare function blockKey(block: Pick<AnnotatedBlock, 'path' | 'representation' | 'blockIndex' | 'mimePart' | 'blockStart' | 'blockEnd'>): string;
+/**
+ * Compare a candidate annotator against one or more references.
+ *
+ * @param candidate the candidate's labels, in run order
+ * @param references each reference's labels, in run order
+ * @param costRatio when set, re-derive the candidate's label from its stored distribution with
+ *   this ratio instead of using the stored label; blocks without a distribution keep their label
+ */
+export declare function compareAnnotators(candidate: readonly AnnotatedBlock[], references: readonly {
+    name: string;
+    blocks: readonly AnnotatedBlock[];
+}[], costRatio?: number | null): AgreementReport;
+//# sourceMappingURL=agreement.d.ts.map

package/dist/annotate/agreement.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agreement.d.ts","sourceRoot":"","sources":["../../src/annotate/agreement.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,EAAE,KAAK,KAAK,EAAE,MAAM,UAAU,CAAC;AACtC,OAAO,EAAkC,KAAK,kBAAkB,EAAE,MAAM,iBAAiB,CAAC;AAE1F,MAAM,WAAW,cAAc;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,cAAc,EAAE,MAAM,CAAC;IACvB,UAAU,EAAE,MAAM,CAAC;IACnB,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,UAAU,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,EAAE,KAAK,CAAC;IACb,aAAa,EAAE,kBAAkB,GAAG,IAAI,CAAC;IACzC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;CACvB;AAED,MAAM,WAAW,SAAS;IACtB,SAAS,EAAE,KAAK,CAAC;IACjB,SAAS,EAAE,KAAK,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,kBAAkB;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,gEAAgE;IAChE,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,4FAA4F;IAC5F,SAAS,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAC7C,2FAA2F;IAC3F,KAAK,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IACzC,kDAAkD;IAClD,KAAK,EAAE,SAAS,EAAE,CAAC;IACnB,QAAQ,EAAE;QAAE,KAAK,EAAE,KAAK,CAAC;QAAC,OAAO,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAC9D,OAAO,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC/D;AAED,MAAM,WAAW,eAAe;IAC5B,eAAe,EAAE,MAAM,CAAC;IACxB,2FAA2F;IAC3F,SAAS,EAAE,MAAM,CAAC;IAClB,gGAAgG;IAChG,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,8EAA8E;IAC9E,QAAQ,EAAE,MAAM,CAAC;IACjB,UAAU,EAAE,kBAAkB,EAAE,CAAC;IACjC;;;;OAIG;IACH,kBAAkB,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAC;CACzE;AAED;;;;GAIG;AACH,wBAAgB,QAAQ,CAAC,KAAK,EAAE,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,gBAAgB,GAAG,YAAY,GAAG,UAAU,GAAG,YAAY,GAAG,UAAU,CAAC,GAAG,MAAM,CAE/I;AA4ED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAC7B,SAAS,EAAE,SAAS,cAAc,EAAE,EACpC,UAAU,EAAE,SAAS;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,SAAS,cAAc,EAAE,CAAA;CAAE,EAAE,EAC1E,SAAS,GAAE,MAAM,GAAG,IAAW,GAChC,eAAe,CAoCjB"}

package/dist/annotate/agreement.js

@@ -0,0 +1,126 @@
+"use strict";
+/**
+ * Agreement between annotators.
+ *
+ * `evaluate` scores the extractor against a reference. This scores an annotator against other
+ * annotators, which is the question a new annotator has to answer before its labels are worth
+ * anything: two strong models agree on 97.6 percent of blocks and a weak one on 80.5
+ * (docs/annotation.md), so a candidate's agreement with the strong models says which of those it
+ * resembles.
+ *
+ * Pure over rows, so it is testable without a database.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.blockKey = blockKey;
+exports.compareAnnotators = compareAnnotators;
+const probabilities_1 = require("./probabilities");
+/**
+ * Identity of a block. Offsets as well as the index, because annotation runs made under different
+ * extractor versions can segment the same message differently, and pairing block 7 with a
+ * different block 7 would count a segmentation change as a disagreement.
+ */
+function blockKey(block) {
+    return [block.path, block.representation, block.mimePart ?? '', block.blockIndex, block.blockStart ?? '', block.blockEnd ?? ''].join('\u0000');
+}
+function byKey(blocks) {
+    // Later entries win, so callers pass rows in run order and get the latest label per block.
+    return new Map(blocks.map(block => [blockKey(block), block]));
+}
+function tally(map, key, agreed) {
+    const entry = map.get(key) ?? { total: 0, agreed: 0 };
+    entry.total++;
+    entry.agreed += agreed ? 1 : 0;
+    map.set(key, entry);
+}
+function compareOne(name, candidate, reference) {
+    const result = {
+        name,
+        shared: 0,
+        agreed: 0,
+        sharedChars: 0,
+        agreedChars: 0,
+        expensive: { blocks: 0, chars: 0 },
+        cheap: { blocks: 0, chars: 0 },
+        pairs: [],
+        perLabel: [],
+        perLang: []
+    };
+    const pairs = new Map();
+    const byLabel = new Map();
+    const byLang = new Map();
+    for (const [key, { label, charCount }] of candidate) {
+        const ref = reference.get(key);
+        if (!ref) {
+            continue;
+        }
+        const agreed = label === ref.label;
+        result.shared++;
+        result.sharedChars += charCount;
+        tally(byLabel, ref.label, agreed);
+        tally(byLang, ref.lang ?? 'unknown', agreed);
+        if (agreed) {
+            result.agreed++;
+            result.agreedChars += charCount;
+            continue;
+        }
+        const pairKey = `${ref.label}|${label}`;
+        const pair = pairs.get(pairKey) ?? { reference: ref.label, candidate: label, blocks: 0 };
+        pair.blocks++;
+        pairs.set(pairKey, pair);
+        if (label === 'REPLY_HISTORY' && probabilities_1.AUTHORED_LABELS.has(ref.label)) {
+            result.expensive.blocks++;
+            result.expensive.chars += charCount;
+        }
+        else if (ref.label === 'REPLY_HISTORY' && probabilities_1.AUTHORED_LABELS.has(label)) {
+            result.cheap.blocks++;
+            result.cheap.chars += charCount;
+        }
+    }
+    result.pairs = [...pairs.values()].sort((a, b) => b.blocks - a.blocks || `${a.reference}${a.candidate}`.localeCompare(`${b.reference}${b.candidate}`));
+    result.perLabel = [...byLabel].map(([label, { total, agreed }]) => ({ label, support: total, agreed })).sort((a, b) => b.support - a.support);
+    result.perLang = [...byLang].map(([lang, { total, agreed }]) => ({ lang, shared: total, agreed })).sort((a, b) => b.shared - a.shared);
+    return result;
+}
+/**
+ * Compare a candidate annotator against one or more references.
+ *
+ * @param candidate the candidate's labels, in run order
+ * @param references each reference's labels, in run order
+ * @param costRatio when set, re-derive the candidate's label from its stored distribution with
+ *   this ratio instead of using the stored label; blocks without a distribution keep their label
+ */
+function compareAnnotators(candidate, references, costRatio = null) {
+    const judged = new Map();
+    let rescored = 0;
+    for (const [key, block] of byKey(candidate)) {
+        const rescore = costRatio !== null && block.probabilities !== null;
+        rescored += rescore ? 1 : 0;
+        judged.set(key, { label: rescore ? (0, probabilities_1.applyCostRule)(block.probabilities, costRatio) : block.label, charCount: block.charCount });
+    }
+    const referenceMaps = references.map(reference => ({ name: reference.name, blocks: byKey(reference.blocks) }));
+    let unmatched = 0;
+    const consensusExpensive = { blocks: 0, chars: 0, shared: 0 };
+    for (const [key, { label, charCount }] of judged) {
+        const refs = referenceMaps.map(reference => reference.blocks.get(key));
+        if (!refs.some(Boolean)) {
+            unmatched++;
+        }
+        if (!referenceMaps.length || !refs.every(Boolean)) {
+            continue;
+        }
+        consensusExpensive.shared++;
+        if (label === 'REPLY_HISTORY' && refs.every(ref => probabilities_1.AUTHORED_LABELS.has(ref.label))) {
+            consensusExpensive.blocks++;
+            consensusExpensive.chars += charCount;
+        }
+    }
+    return {
+        candidateBlocks: judged.size,
+        unmatched,
+        costRatio,
+        rescored,
+        references: referenceMaps.map(reference => compareOne(reference.name, judged, reference.blocks)),
+        consensusExpensive
+    };
+}
+//# sourceMappingURL=agreement.js.map

package/dist/annotate/agreement.js.map

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

package/dist/annotate/client.d.ts

@@ -5,24 +5,14 @@
  * Adding a vendor SDK for one optional command would change that materially, and the surface used
  * here is a single POST with a JSON schema response format.
  *
- * This is the one place in the codebase that sends message content off the machine. It is only
- * reachable from `email-content annotate`, never from `extract()` or the corpus scanner. See
+ * This is one of the two places in the codebase that send message content off the machine, the
+ * other being `typesafe-client.ts`. Both are only reachable from `email-content annotate`, never
+ * from `extract()` or the corpus scanner. See
  * docs/threat-model.md, "Configured exception: LLM annotation".
  */
-export interface OpenAIConfig {
-    apiKey: string;
-    baseUrl: string;
-    model: string;
-    /** Per request timeout in milliseconds. */
-    timeoutMs: number;
-    maxRetries: number;
-}
-export interface Usage {
-    promptTokens: number;
-    completionTokens: number;
-    totalTokens: number;
-    requests: number;
-}
+import { ApiError, type ApiConfig, type Usage } from './http';
+export type { Usage } from './http';
+export type OpenAIConfig = ApiConfig;
 export interface CompletionRequest {
     system: string;
     user: string;
@@ -40,9 +30,7 @@ export interface CompletionClient {
     readonly model: string;
     complete<T>(request: CompletionRequest): Promise<T>;
 }
-export declare class OpenAIError extends Error {
-    readonly status: number;
-    readonly retryable: boolean;
+export declare class OpenAIError extends ApiError {
     constructor(message: string, status: number, retryable: boolean);
 }
 /** Load configuration from the environment, after process.loadEnvFile(). */

package/dist/annotate/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/annotate/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,MAAM,WAAW,YAAY;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;IACd,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACtB;AAED,MAAM,WAAW,KAAK;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED,MAAM,WAAW,iBAAiB;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACvD;AAED,qBAAa,WAAY,SAAQ,KAAK;IAClC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;gBAEhB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO;CAMlE;AAED,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,GAAE,OAAO,CAAC,YAAY,CAAM,GAAG,YAAY,CAahG;AAMD,qBAAa,YAAa,YAAW,gBAAgB;IACjD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAyE;gBAElF,MAAM,EAAE,YAAY;IAIhC,IAAI,KAAK,IAAI,MAAM,CAElB;IAED;;;;;;OAMG;IACG,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,CAAC,CAAC;CAoF5D"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/annotate/client.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,EAAE,QAAQ,EAA8B,KAAK,SAAS,EAAE,KAAK,KAAK,EAAE,MAAM,QAAQ,CAAC;AAE1F,YAAY,EAAE,KAAK,EAAE,MAAM,QAAQ,CAAC;AAEpC,MAAM,MAAM,YAAY,GAAG,SAAS,CAAC;AAErC,MAAM,WAAW,iBAAiB;IAC9B,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,UAAU,EAAE,MAAM,CAAC;IACnB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC;AAED;;;;;;GAMG;AACH,MAAM,WAAW,gBAAgB;IAC7B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;CACvD;AAED,qBAAa,WAAY,SAAQ,QAAQ;gBACzB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO;CAIlE;AAED,4EAA4E;AAC5E,wBAAgB,aAAa,CAAC,KAAK,EAAE,MAAM,EAAE,SAAS,GAAE,OAAO,CAAC,YAAY,CAAM,GAAG,YAAY,CAEhG;AAED,qBAAa,YAAa,YAAW,gBAAgB;IACjD,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAe;IACtC,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAyE;gBAElF,MAAM,EAAE,YAAY;IAIhC,IAAI,KAAK,IAAI,MAAM,CAElB;IAED;;;;;;OAMG;IACG,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,iBAAiB,GAAG,OAAO,CAAC,CAAC,CAAC;CA2C5D"}

package/dist/annotate/client.js

@@ -6,41 +6,25 @@
  * Adding a vendor SDK for one optional command would change that materially, and the surface used
  * here is a single POST with a JSON schema response format.
  *
- * This is the one place in the codebase that sends message content off the machine. It is only
- * reachable from `email-content annotate`, never from `extract()` or the corpus scanner. See
+ * This is one of the two places in the codebase that send message content off the machine, the
+ * other being `typesafe-client.ts`. Both are only reachable from `email-content annotate`, never
+ * from `extract()` or the corpus scanner. See
  * docs/threat-model.md, "Configured exception: LLM annotation".
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.OpenAIClient = exports.OpenAIError = void 0;
 exports.configFromEnv = configFromEnv;
-class OpenAIError extends Error {
-    status;
-    retryable;
+const http_1 = require("./http");
+class OpenAIError extends http_1.ApiError {
     constructor(message, status, retryable) {
-        super(message);
+        super(message, status, retryable);
         this.name = 'OpenAIError';
-        this.status = status;
-        this.retryable = retryable;
     }
 }
 exports.OpenAIError = OpenAIError;
 /** Load configuration from the environment, after process.loadEnvFile(). */
 function configFromEnv(model, overrides = {}) {
-    const apiKey = process.env.OPENAI_API_KEY;
-    if (!apiKey) {
-        throw new Error('OPENAI_API_KEY is not set. Copy .env.example to .env and fill it in.');
-    }
-    return {
-        apiKey,
-        baseUrl: process.env.OPENAI_BASE_URL || 'https://api.openai.com/v1',
-        model,
-        timeoutMs: 120000,
-        maxRetries: 5,
-        ...overrides
-    };
-}
-function sleep(ms) {
-    return new Promise(resolve => setTimeout(resolve, ms));
+    return (0, http_1.apiConfigFromEnv)({ keyVar: 'OPENAI_API_KEY', urlVar: 'OPENAI_BASE_URL', defaultUrl: 'https://api.openai.com/v1' }, model, overrides);
 }
 class OpenAIClient {
     config;
@@ -59,55 +43,27 @@ class OpenAIClient {
      * contract, and a retry would usually fail the same way.
      */
     async complete(request) {
-        let lastError = null;
-        for (let attempt = 0; attempt <= this.config.maxRetries; attempt++) {
-            if (attempt > 0) {
-                // Full jitter, capped, so a burst of workers does not retry in lockstep.
-                const backoff = Math.min(30000, 500 * 2 ** (attempt - 1));
-                await sleep(Math.random() * backoff);
-            }
-            const controller = new AbortController();
-            const timer = setTimeout(() => controller.abort(), this.config.timeoutMs);
-            try {
-                const response = await fetch(`${this.config.baseUrl}/chat/completions`, {
-                    method: 'POST',
-                    signal: controller.signal,
-                    headers: {
-                        Authorization: `Bearer ${this.config.apiKey}`,
-                        'Content-Type': 'application/json'
-                    },
-                    body: JSON.stringify({
-                        model: this.config.model,
-                        messages: [
-                            { role: 'system', content: request.system },
-                            { role: 'user', content: request.user }
-                        ],
-                        response_format: {
-                            type: 'json_schema',
-                            json_schema: { name: request.schemaName, strict: true, schema: request.schema }
-                        }
-                    })
-                });
-                if (!response.ok) {
-                    const retryable = response.status === 429 || response.status >= 500;
-                    let detail = `HTTP ${response.status}`;
-                    try {
-                        const body = (await response.json());
-                        if (body.error?.message) {
-                            detail = body.error.message.slice(0, 300);
-                        }
-                    }
-                    catch {
-                        // Body was not JSON. The status alone is enough.
-                    }
-                    const error = new OpenAIError(detail, response.status, retryable);
-                    if (!retryable) {
-                        throw error;
-                    }
-                    lastError = error;
-                    continue;
+        return (0, http_1.postJson)({
+            url: `${this.config.baseUrl}/chat/completions`,
+            apiKey: this.config.apiKey,
+            policy: this.config,
+            payload: {
+                model: this.config.model,
+                messages: [
+                    { role: 'system', content: request.system },
+                    { role: 'user', content: request.user }
+                ],
+                response_format: {
+                    type: 'json_schema',
+                    json_schema: { name: request.schemaName, strict: true, schema: request.schema }
                 }
-                const body = (await response.json());
+            },
+            httpError: (status, body) => {
+                const message = body?.error?.message;
+                return new OpenAIError(message ? message.slice(0, 300) : `HTTP ${status}`, status, status === 429 || status >= 500);
+            },
+            parse: raw => {
+                const body = raw;
                 this.usage.requests++;
                 this.usage.promptTokens += body.usage?.prompt_tokens ?? 0;
                 this.usage.completionTokens += body.usage?.completion_tokens ?? 0;
@@ -122,17 +78,7 @@ class OpenAIClient {
                 }
                 return JSON.parse(content);
             }
-            catch (err) {
-                if (err instanceof OpenAIError && !err.retryable) {
-                    throw err;
-                }
-                lastError = err instanceof Error ? err : new Error(String(err));
-            }
-            finally {
-                clearTimeout(timer);
-            }
-        }
-        throw lastError ?? new Error('request failed');
+        });
     }
 }
 exports.OpenAIClient = OpenAIClient;

package/dist/annotate/client.js.map

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

package/dist/annotate/http.d.ts

@@ -0,0 +1,57 @@
+/**
+ * Retrying JSON POST shared by the annotator clients.
+ *
+ * Both providers need the same thing: one authenticated POST, exponential backoff on rate limits
+ * and overload, and no retry once the provider has said the request itself is wrong. Keeping that
+ * loop in one place means a fix to it cannot land in one client and not the other.
+ */
+export interface RetryPolicy {
+    /** Per request timeout in milliseconds. */
+    timeoutMs: number;
+    maxRetries: number;
+}
+/** What every provider client needs: where, who, which model, and how hard to retry. */
+export interface ApiConfig extends RetryPolicy {
+    apiKey: string;
+    baseUrl: string;
+    model: string;
+}
+/**
+ * Load a provider's configuration from the environment, after process.loadEnvFile().
+ *
+ * Throws when the key is missing. That is the fail closed guarantee in docs/threat-model.md: a
+ * provider without a configured key never gets as far as reading a message.
+ */
+export declare function apiConfigFromEnv(env: {
+    keyVar: string;
+    urlVar: string;
+    defaultUrl: string;
+}, model: string, overrides?: Partial<ApiConfig>): ApiConfig;
+/** Token accounting, in one shape for every provider. */
+export interface Usage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+    requests: number;
+}
+/** An HTTP or protocol failure from an annotation provider. */
+export declare class ApiError extends Error {
+    readonly status: number;
+    readonly retryable: boolean;
+    constructor(message: string, status: number, retryable: boolean);
+}
+export interface PostJsonOptions<T> {
+    url: string;
+    apiKey: string;
+    payload: unknown;
+    policy: RetryPolicy;
+    /** Build the error for a non 2xx response. Decides what, if anything, of the body is surfaced. */
+    httpError(status: number, body: unknown): ApiError;
+    /**
+     * Turn a 2xx body into the result. Runs inside the retry loop: throwing an ApiError with
+     * `retryable: false` stops immediately, any other error is retried like a network failure.
+     */
+    parse(body: unknown): T;
+}
+export declare function postJson<T>(options: PostJsonOptions<T>): Promise<T>;
+//# sourceMappingURL=http.d.ts.map

package/dist/annotate/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/annotate/http.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,WAAW,WAAW;IACxB,2CAA2C;IAC3C,SAAS,EAAE,MAAM,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACtB;AAED,wFAAwF;AACxF,MAAM,WAAW,SAAU,SAAQ,WAAW;IAC1C,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,KAAK,EAAE,MAAM,CAAC;CACjB;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE;IAAE,MAAM,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,MAAM,CAAC;IAAC,UAAU,EAAE,MAAM,CAAA;CAAE,EAAE,KAAK,EAAE,MAAM,EAAE,SAAS,GAAE,OAAO,CAAC,SAAS,CAAM,GAAG,SAAS,CAa1J;AAED,yDAAyD;AACzD,MAAM,WAAW,KAAK;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,WAAW,EAAE,MAAM,CAAC;IACpB,QAAQ,EAAE,MAAM,CAAC;CACpB;AAED,+DAA+D;AAC/D,qBAAa,QAAS,SAAQ,KAAK;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;gBAEhB,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,OAAO;CAMlE;AAED,MAAM,WAAW,eAAe,CAAC,CAAC;IAC9B,GAAG,EAAE,MAAM,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,WAAW,CAAC;IACpB,kGAAkG;IAClG,SAAS,CAAC,MAAM,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,QAAQ,CAAC;IACnD;;;OAGG;IACH,KAAK,CAAC,IAAI,EAAE,OAAO,GAAG,CAAC,CAAC;CAC3B;AAMD,wBAAsB,QAAQ,CAAC,CAAC,EAAE,OAAO,EAAE,eAAe,CAAC,CAAC,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAqDzE"}

package/dist/annotate/http.js

@@ -0,0 +1,99 @@
+"use strict";
+/**
+ * Retrying JSON POST shared by the annotator clients.
+ *
+ * Both providers need the same thing: one authenticated POST, exponential backoff on rate limits
+ * and overload, and no retry once the provider has said the request itself is wrong. Keeping that
+ * loop in one place means a fix to it cannot land in one client and not the other.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ApiError = void 0;
+exports.apiConfigFromEnv = apiConfigFromEnv;
+exports.postJson = postJson;
+/**
+ * Load a provider's configuration from the environment, after process.loadEnvFile().
+ *
+ * Throws when the key is missing. That is the fail closed guarantee in docs/threat-model.md: a
+ * provider without a configured key never gets as far as reading a message.
+ */
+function apiConfigFromEnv(env, model, overrides = {}) {
+    const apiKey = process.env[env.keyVar];
+    if (!apiKey) {
+        throw new Error(`${env.keyVar} is not set. Copy .env.example to .env and fill it in.`);
+    }
+    return {
+        apiKey,
+        baseUrl: process.env[env.urlVar] || env.defaultUrl,
+        model,
+        timeoutMs: 120000,
+        maxRetries: 5,
+        ...overrides
+    };
+}
+/** An HTTP or protocol failure from an annotation provider. */
+class ApiError extends Error {
+    status;
+    retryable;
+    constructor(message, status, retryable) {
+        super(message);
+        this.name = 'ApiError';
+        this.status = status;
+        this.retryable = retryable;
+    }
+}
+exports.ApiError = ApiError;
+function sleep(ms) {
+    return new Promise(resolve => setTimeout(resolve, ms));
+}
+async function postJson(options) {
+    let lastError = null;
+    // Payloads run to hundreds of kilobytes, and nothing about them changes between attempts.
+    const body = JSON.stringify(options.payload);
+    for (let attempt = 0; attempt <= options.policy.maxRetries; attempt++) {
+        if (attempt > 0) {
+            // Full jitter, capped, so a burst of workers does not retry in lockstep.
+            const backoff = Math.min(30000, 500 * 2 ** (attempt - 1));
+            await sleep(Math.random() * backoff);
+        }
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), options.policy.timeoutMs);
+        try {
+            const response = await fetch(options.url, {
+                method: 'POST',
+                signal: controller.signal,
+                headers: {
+                    Authorization: `Bearer ${options.apiKey}`,
+                    'Content-Type': 'application/json'
+                },
+                body
+            });
+            if (!response.ok) {
+                let detail = null;
+                try {
+                    detail = await response.json();
+                }
+                catch {
+                    // Body was not JSON. The status alone is enough.
+                }
+                const error = options.httpError(response.status, detail);
+                if (!error.retryable) {
+                    throw error;
+                }
+                lastError = error;
+                continue;
+            }
+            return options.parse(await response.json());
+        }
+        catch (err) {
+            if (err instanceof ApiError && !err.retryable) {
+                throw err;
+            }
+            lastError = err instanceof Error ? err : new Error(String(err));
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+    throw lastError ?? new Error('request failed');
+}
+//# sourceMappingURL=http.js.map

package/dist/annotate/http.js.map

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