margin-meter 0.1.0 → 0.3.0

package/dist/batching.js

@@ -0,0 +1,181 @@
+/**
+ * The buffer that decides WHEN a metered row goes over the wire.
+ *
+ * The full contract, with the arithmetic behind every default, is
+ * `docs/reference/SDK_BATCHING.md`, and this file is the TS twin of
+ * `margin_meter/batching.py` — the two must agree, because they are one contract
+ * a customer integrates against, not two implementations.
+ *
+ * The short version: at 1M metered calls/day, one call per HTTP request is 30M
+ * Vercel invocations a month and the same traffic batched at 100 is 300K. 100x on
+ * a line item Margin pays. It lives in the SDK rather than the server because
+ * only the client can decide not to make the request.
+ *
+ * ⛔ Two properties are not negotiable, and both are about the customer's process
+ * rather than our data:
+ *
+ * 1. **Nothing blocks the caller.** `submit` pushes onto an array and returns.
+ *    There is no thread here and none is needed — the flush runs off the caller's
+ *    await chain, driven by an `unref`'d timer so it never holds a process open.
+ * 2. **The queue is BOUNDED and drops the NEWEST.** An unbounded buffer behind a
+ *    dead endpoint is an OOM with our name on it, and taking down a customer's
+ *    production agent because our meter was unavailable is the worst thing this
+ *    SDK could do. Drop-newest leaves a contiguous prefix and a gap at the tail,
+ *    which reads as "we stopped recording at 14:20"; drop-oldest leaves a hole in
+ *    the middle of history, which reads as "they spent less that hour" — an
+ *    under-count in the flattering direction wearing the costume of a measurement.
+ */
+export const BATCH_PATH = "/api/ingest/batch";
+/** Flush on 100 records OR 10 seconds, whichever comes first. The crossover is
+ *  100 ÷ 10 = 10 calls/sec: above it size fires first and invocations scale as
+ *  volume ÷ 100; below it the timer governs and invocations cap at 8,640/day
+ *  however quiet the customer is. Each trigger covers the other's failure — size
+ *  alone stalls forever on a low-volume customer, time alone spends a fixed
+ *  ~518K invocations/month whatever the traffic. */
+export const DEFAULT_MAX_RECORDS = 100;
+export const DEFAULT_FLUSH_MS = 10_000;
+/** ~14 minutes of buffered traffic at 11.6 calls/sec — enough to ride out a
+ *  deploy or a short outage of ours. A row is 400–1500 bytes, so the ceiling on
+ *  the host's memory is 4–15 MB, which is the number to quote a customer. */
+export const DEFAULT_MAX_QUEUE = 10_000;
+/** Bounded so a shutdown flush can never hang the host's exit. */
+export const SHUTDOWN_TIMEOUT_MS = 5_000;
+/** Read a positive tunable from the environment, ignoring nonsense.
+ *
+ *  A malformed or non-positive value falls back to the default rather than
+ *  throwing: a typo in a deployment variable must never stop a customer's process
+ *  from starting, and a zero flush interval would be a busy loop. */
+function envNumber(name, fallback, minimum) {
+    const env = (typeof process !== "undefined" && process.env) || {};
+    const raw = env[name];
+    if (raw === undefined)
+        return fallback;
+    const value = Number(raw);
+    if (!Number.isFinite(value) || value < minimum)
+        return fallback;
+    return value;
+}
+/**
+ * A bounded queue plus a timer that flushes it on size or time.
+ *
+ * `send` is awaited off the caller's path and is expected never to reject — it
+ * owns the POST, the retries and the accounting.
+ */
+export class Batcher {
+    maxRecords;
+    flushMs;
+    maxQueue;
+    queue = [];
+    timer = null;
+    inFlight = Promise.resolve();
+    /** True once `close()` has run. Public so a caller can report a refused emit
+     *  under the reason that actually caused it: "the meter was shut down" and "the
+     *  buffer is full" have opposite fixes, and filing one as the other sends the
+     *  reader hunting for a network problem that is not there. */
+    closed = false;
+    // ⚠️ Declared rather than written as a constructor parameter property: Node's
+    // strip-only TypeScript mode (which this SDK's own test runner uses) rejects
+    // parameter properties outright, and a package that cannot be loaded by the
+    // runtime its tests run on is not testable.
+    send;
+    constructor(send, options = {}) {
+        this.send = send;
+        this.maxRecords = Math.floor(options.maxRecords ?? envNumber("MARGIN_BATCH_MAX_RECORDS", DEFAULT_MAX_RECORDS, 1));
+        // The env var is in SECONDS so the two SDKs read the same variable the same
+        // way; a deployment should not have to remember which one wants milliseconds.
+        this.flushMs =
+            options.flushMs ??
+                envNumber("MARGIN_BATCH_FLUSH_SECONDS", DEFAULT_FLUSH_MS / 1000, 0.001) * 1000;
+        this.maxQueue = Math.floor(options.maxQueue ?? envNumber("MARGIN_BATCH_MAX_QUEUE", DEFAULT_MAX_QUEUE, 1));
+    }
+    /** Queue one record. `false` when the queue was full and it was DROPPED.
+     *
+     *  ⛔ A bounded push and a size check are the entire cost on the caller's path.
+     *  Nothing here is awaited. */
+    submit(record) {
+        if (this.closed)
+            return false;
+        if (this.queue.length >= this.maxQueue) {
+            // Drop the NEWEST — see the module comment. The rows already queued have
+            // waited longer and, under a sustained outage, are the ones whose loss
+            // would put a hole in the middle of the ledger rather than at its end.
+            return false;
+        }
+        this.queue.push(record);
+        if (this.queue.length >= this.maxRecords) {
+            void this.flush();
+            return true;
+        }
+        this.arm();
+        return true;
+    }
+    /** Start the interval timer if it is not already running.
+     *
+     *  ⭐ `unref`'d, which is what lets a short-lived script exit on its own
+     *  schedule instead of waiting out our timer — and what makes `beforeExit`
+     *  fire at all, since a ref'd timer would keep the event loop alive forever. */
+    arm() {
+        if (this.timer !== null || this.closed)
+            return;
+        const timer = setTimeout(() => {
+            this.timer = null;
+            void this.flush();
+        }, this.flushMs);
+        if (typeof timer.unref === "function") {
+            timer.unref();
+        }
+        this.timer = timer;
+    }
+    /** Send everything queued when this was called, and resolve when it has been
+     *  delivered or counted as dropped. Never rejects. */
+    async flush() {
+        if (this.timer !== null) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        // Chained rather than parallel: two overlapping flushes would interleave
+        // batches and make "everything queued when I called" unanswerable.
+        const previous = this.inFlight;
+        this.inFlight = (async () => {
+            await previous;
+            while (this.queue.length > 0) {
+                const batch = this.queue.splice(0, this.maxRecords);
+                try {
+                    await this.send(batch);
+                }
+                catch {
+                    /* `send` owns its own accounting; a throw here must not stop the drain */
+                }
+            }
+        })();
+        await this.inFlight;
+    }
+    /** Stop accepting, drain what is queued, and return anything left behind.
+     *
+     *  The stranded records are handed BACK rather than swallowed so the caller can
+     *  count them: an abandoned buffer nobody counts is exactly the invisible loss
+     *  the delivery accounting exists to make visible. */
+    async close(timeoutMs = SHUTDOWN_TIMEOUT_MS) {
+        this.closed = true;
+        if (this.timer !== null) {
+            clearTimeout(this.timer);
+            this.timer = null;
+        }
+        let timer;
+        const bounded = new Promise((resolve) => {
+            timer = setTimeout(resolve, timeoutMs);
+            if (typeof timer.unref === "function") {
+                timer.unref();
+            }
+        });
+        // ⛔ Raced against a timeout so a wedged endpoint can never hang the host's
+        // exit. Whatever is still queued when the race ends is returned, not lost.
+        await Promise.race([this.flush(), bounded]);
+        if (timer !== undefined)
+            clearTimeout(timer);
+        const stranded = this.queue;
+        this.queue = [];
+        return stranded;
+    }
+}
+//# sourceMappingURL=batching.js.map

package/dist/batching.js.map

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

package/dist/braintrust.d.ts

@@ -0,0 +1,153 @@
+/**
+ * margin-meter/braintrust — turn a Braintrust eval result file into outcomes.
+ *
+ * The TypeScript twin of `sdk/python/margin_meter/braintrust.py`. Braintrust is
+ * the eval platform funded AI teams most often already pay for, and the nearest
+ * competitor Margin has (`docs/growth/POSITIONING.md`): it ships "cost per
+ * successful eval" — the metric — but has no automated parity-gated
+ * promote/revert — the action. So this adapter is the neutral-auditor wedge in
+ * code: it hands a Braintrust customer the action layer they lack, over the
+ * evals they already run. Rung 2 of `docs/INTEGRATION_LADDER.md`.
+ *
+ *     import { MarginMeter, braintrust } from "margin-meter";
+ *     const meter = new MarginMeter();
+ *     const data = JSON.parse(await readFile("results.json", "utf8"));
+ *     await braintrust.recordResults(meter, data, "my-suite", { threshold: 0.7 });
+ *
+ * The mapping is identical to the Python adapter's, on purpose — one Braintrust
+ * result → one outcome:
+ *
+ *  - `qualityScore` ← the mean of the case's numeric scores in [0, 1] (Braintrust
+ *    reports a named score per scorer, not one per case).
+ *  - `passed`       ← Braintrust has NO intrinsic pass/fail (its scores are
+ *    continuous), so it is derived HONESTLY, never fabricated: (1) `threshold`
+ *    given → mean ≥ threshold; (2) no threshold but every scorer is binary
+ *    (0.0/1.0) → every scorer passed; (3) no threshold and continuous scores →
+ *    the row is SKIPPED with a warning.
+ *  - `qualityMethod`/`graderKind` ← DERIVED from the scorer names, never assumed
+ *    (weaker-claim-wins, see the honesty rule below).
+ *  - `judgeModelId` ← an opt-in `margin_judge_model` field, ridden only when the
+ *    grade is an LLM judge (rung 6 provenance). A bare `model` field is NOT used —
+ *    in a Braintrust record it is usually the generation model under test.
+ *  - `link`         ← the case id/span_id/root_span_id, else `braintrust:<index>` —
+ *    never its `input` (MAR-1548).
+ *  - `valueUsd`     ← opt-in via `metadata.margin_value` (rung 8); absent is the
+ *    cost-per-outcome default, never 0.
+ *  - a result with no numeric score at all is SKIPPED — recording a non-verdict
+ *    would fabricate an outcome the eval did not produce.
+ *
+ * ## The honesty rule
+ *
+ * Braintrust grades two ways and the adapter must not conflate them: code-graded
+ * scorers (ExactMatch, Levenshtein, NumericDiff, JSONDiff, …) are
+ * `ground_truth`/`code`; model-graded autoevals (Factuality, ClosedQA,
+ * AnswerRelevancy, Moderation, …) are `llm_judge`/`judge`. The WEAKER honest
+ * claim wins: any model-graded scorer makes the whole outcome a judge grade; a
+ * code scorer mixed with an unrecognised one is downgraded to `unknown`; nothing
+ * recognisable is `unknown`.
+ *
+ * Same two promises as the promptfoo adapter: it consumes a file the customer
+ * already produces, and it never fabricates and is fail-safe.
+ */
+import type { RecordOutcomeInput } from "./index.ts";
+/** Where a warning goes. Defaults to `process.emitWarning`; a test injects a
+ *  collector. */
+export type WarnFn = (message: string) => void;
+/** Grading provenance for one outcome. */
+export interface GraderSignature {
+    qualityMethod: string;
+    graderKind: string;
+}
+/** Normalise a scorer name for set membership: lower-case, keep only
+ *  alphanumerics (so `Answer Relevancy`/`answer_relevancy` collapse), strip a
+ *  leading `not` negation. Returns undefined for a missing/blank name. */
+export declare function normScorerName(raw: unknown): string | undefined;
+/** The per-scorer numeric scores of a case, as `{ [scorer]: score }`. Braintrust
+ *  records `scores` either as a mapping (`{name: score|null}`) or a list of
+ *  `{name, score}`. Both are read; a null/non-numeric/out-of-[0,1] score is
+ *  dropped (the ingest layer rejects a score outside [0,1] and a lost decimal
+ *  beats a lost row). */
+export declare function scoresOf(result: unknown): Record<string, number>;
+/** Derive `(qualityMethod, graderKind)` from the scorer names, weaker-claim-wins:
+ *   - any model-graded scorer  → llm_judge/judge
+ *   - only recognised code scorers → ground_truth/code
+ *   - anything else → unknown/unknown */
+export declare function scorerSignature(scorerNames: Iterable<unknown>): GraderSignature;
+/** The judging model, from an explicit `margin_judge_model` opt-in on the result
+ *  or its metadata, or undefined. A bare `model` field is deliberately NOT used. */
+export declare function judgeModelFromResult(result: unknown): string | undefined;
+/** Read an opt-in `margin_value` off a result's `metadata` (or a top-level key)
+ *  — the value-per-outcome numerator (rung 8). Returns the USD amount, or
+ *  undefined when absent. Throws on a malformed/implausible value so the
+ *  caller can warn and drop it. */
+export declare function valueFromResult(result: unknown): number | undefined;
+/** A traceable link back to the exact eval case: its id/span id, else the row
+ *  index. ⛔ Never the case's `input` (MAR-1548): /security says no prompt
+ *  reaches us. */
+export declare function linkFromResult(result: unknown, index: number): string;
+/** Derive the pass/fail for a case, or undefined when it cannot be derived
+ *  honestly (no scores, or continuous scores with no threshold). */
+export declare function passedFromScores(scores: Record<string, number>, threshold: number | undefined): boolean | undefined;
+/** Fields for {@link outcomeInput}. */
+export interface OutcomeInputArgs {
+    workflowId: string;
+    passed: boolean;
+    qualityScore: number;
+    scorerNames: Iterable<unknown>;
+    link: string;
+    judgeModelId?: string;
+    valueUsd?: number;
+    isSimulated?: boolean;
+}
+/** Translate one graded Braintrust result into `MarginMeter.recordOutcome` input.
+ *  `judgeModelId` rides only when the grade is an LLM judge and a model was named;
+ *  `valueUsd` rides only when a value was supplied. */
+export declare function outcomeInput(args: OutcomeInputArgs): RecordOutcomeInput;
+/** Options shared by the result-level translators. */
+export interface TranslateOptions {
+    workflowId: string;
+    index?: number;
+    threshold?: number;
+    isSimulated?: boolean;
+    onWarn?: WarnFn;
+}
+/** Full translation of one Braintrust result, or undefined if it is not a real
+ *  verdict (no numeric score, or an ambiguous continuous score with no
+ *  threshold). A malformed `margin_value` warns and drops the value while keeping
+ *  the pass/fail. */
+export declare function resultToOutcomeInput(result: unknown, opts: TranslateOptions): RecordOutcomeInput | undefined;
+/** Pull the flat list of per-case results out of parsed Braintrust output. It
+ *  reaches a file several ways: a bare list, the `EvalResultWithSummary` envelope
+ *  (`{summary, results}`), a `{results}` wrapper, or the experiment-fetch export
+ *  (`{events}`). This walks the known shapes rather than pinning one. */
+export declare function extractResults(data: unknown): Record<string, unknown>[];
+/** Yield `recordOutcome` inputs for every real verdict in parsed Braintrust
+ *  output (any envelope shape {@link extractResults} understands). */
+export declare function iterOutcomes(data: unknown, opts: {
+    workflowId: string;
+    threshold?: number;
+    isSimulated?: boolean;
+    onWarn?: WarnFn;
+}): RecordOutcomeInput[];
+/** The minimal meter surface {@link recordResults} needs — satisfied by
+ *  `MarginMeter`, kept as a structural type so this module imports no runtime
+ *  value from `index.ts`. */
+export interface OutcomeSink {
+    recordOutcome(input: RecordOutcomeInput): Promise<unknown>;
+    flush(): Promise<void>;
+}
+/** How one `recordResults` batch landed. */
+export interface RecordSummary {
+    recorded: number;
+    errors: number;
+    skipped: number;
+}
+/** Emit an outcome per verdict in parsed Braintrust output through `meter`.
+ *  Fail-safe: a delivery fault on one row warns and counts an error; it never
+ *  aborts the batch. Non-verdict rows are counted as skipped. */
+export declare function recordResults(meter: OutcomeSink, data: unknown, workflowId: string, opts?: {
+    threshold?: number;
+    isSimulated?: boolean;
+    onWarn?: WarnFn;
+}): Promise<RecordSummary>;
+//# sourceMappingURL=braintrust.d.ts.map

package/dist/braintrust.d.ts.map

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