margin-meter 0.1.0 → 0.3.0

package/dist/substrate.d.ts

@@ -0,0 +1,51 @@
+/**
+ * The SUBSTRATE a call travelled through to reach a model — the TypeScript twin
+ * of `margin_meter/substrate.py`.
+ *
+ * `provider` says who owns the model and who bills for it. `substrate` says which
+ * path the request actually took: the vendor's own API, a router like OpenRouter,
+ * a cloud reseller like Bedrock or Azure. The two are orthogonal, and comparing
+ * the same work across paths is the thing a single-substrate router structurally
+ * cannot do.
+ *
+ * Detection is EVIDENCE, not inference. A JS client carries the endpoint it will
+ * call (`baseURL` on the OpenAI and Anthropic SDKs), so an OpenAI client pointed
+ * at `openrouter.ai` is recorded as OpenRouter because that is literally where
+ * the request goes. Nothing is defaulted: a client whose endpoint cannot be read
+ * records NO path, which is the honest reading of an unmeasured dimension.
+ *
+ * Keep the host tables in step with the Python SDK and `margin/substrates.py`.
+ * Three copies of one rule is a real cost, and the alternative — a JS estate that
+ * cannot join the comparison at all — costs more.
+ */
+export declare const DIRECT = "direct";
+export declare const OPENROUTER = "openrouter";
+export declare const LITELLM = "litellm";
+export declare const AZURE = "azure";
+export declare const BEDROCK = "bedrock";
+export declare const VERTEX = "vertex";
+export declare const GATEWAY = "gateway";
+export type Substrate = "direct" | "openrouter" | "litellm" | "azure" | "bedrock" | "vertex" | "gateway";
+/**
+ * Map a client's base URL to a substrate, or `undefined` if unreadable.
+ *
+ * Accepts anything stringable (the OpenAI SDK carries a string, others a `URL`).
+ * An unparseable value returns `undefined` rather than a default — no evidence,
+ * no claim. A host we cannot name reads `gateway`, which says the path was not
+ * the vendor's own without inventing a vendor for it.
+ */
+export declare function fromBaseUrl(baseUrl: unknown): Substrate | undefined;
+/**
+ * Detect the substrate from a live SDK client or one of its resources.
+ *
+ * The JS instrumenters patch a method on a specific client INSTANCE, so the
+ * endpoint is in hand at patch time — a process holding a vendor client and a
+ * router client instruments each separately and each reports correctly. Both
+ * `baseURL` (the JS SDKs' spelling) and `base_url` are read, and the resource's
+ * private `_client` is tried before the object itself so a patched
+ * `chat.completions` resolves as well as a bare client. Every lookup is
+ * defensive: a shape change in a vendor SDK must degrade to "no substrate
+ * recorded", never break the host's call.
+ */
+export declare function fromClient(obj: unknown): Substrate | undefined;
+//# sourceMappingURL=substrate.d.ts.map

package/dist/substrate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"substrate.d.ts","sourceRoot":"","sources":["../src/substrate.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;GAmBG;AAEH,eAAO,MAAM,MAAM,WAAW,CAAC;AAC/B,eAAO,MAAM,UAAU,eAAe,CAAC;AACvC,eAAO,MAAM,OAAO,YAAY,CAAC;AACjC,eAAO,MAAM,KAAK,UAAU,CAAC;AAC7B,eAAO,MAAM,OAAO,YAAY,CAAC;AACjC,eAAO,MAAM,MAAM,WAAW,CAAC;AAC/B,eAAO,MAAM,OAAO,YAAY,CAAC;AAEjC,MAAM,MAAM,SAAS,GACjB,QAAQ,GACR,YAAY,GACZ,SAAS,GACT,OAAO,GACP,SAAS,GACT,QAAQ,GACR,SAAS,CAAC;AAoCd;;;;;;;GAOG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAuBnE;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,SAAS,GAAG,SAAS,CAgB9D"}

package/dist/substrate.js

@@ -0,0 +1,132 @@
+/**
+ * The SUBSTRATE a call travelled through to reach a model — the TypeScript twin
+ * of `margin_meter/substrate.py`.
+ *
+ * `provider` says who owns the model and who bills for it. `substrate` says which
+ * path the request actually took: the vendor's own API, a router like OpenRouter,
+ * a cloud reseller like Bedrock or Azure. The two are orthogonal, and comparing
+ * the same work across paths is the thing a single-substrate router structurally
+ * cannot do.
+ *
+ * Detection is EVIDENCE, not inference. A JS client carries the endpoint it will
+ * call (`baseURL` on the OpenAI and Anthropic SDKs), so an OpenAI client pointed
+ * at `openrouter.ai` is recorded as OpenRouter because that is literally where
+ * the request goes. Nothing is defaulted: a client whose endpoint cannot be read
+ * records NO path, which is the honest reading of an unmeasured dimension.
+ *
+ * Keep the host tables in step with the Python SDK and `margin/substrates.py`.
+ * Three copies of one rule is a real cost, and the alternative — a JS estate that
+ * cannot join the comparison at all — costs more.
+ */
+export const DIRECT = "direct";
+export const OPENROUTER = "openrouter";
+export const LITELLM = "litellm";
+export const AZURE = "azure";
+export const BEDROCK = "bedrock";
+export const VERTEX = "vertex";
+export const GATEWAY = "gateway";
+/** The vendors' own API hosts. A base URL on one of these is the direct path. */
+const DIRECT_HOSTS = [
+    "api.openai.com",
+    "api.anthropic.com",
+    "generativelanguage.googleapis.com",
+];
+/**
+ * Host patterns that name a substrate outright, most specific first. The third
+ * element allows a REGIONAL PREFIX joined by a hyphen — Vertex serves from
+ * `us-central1-aiplatform.googleapis.com`, a sibling label rather than a
+ * subdomain. Granted per entry, and only where the vendor controls the parent
+ * domain end to end.
+ */
+const HOST_SUBSTRATES = [
+    ["openrouter.ai", OPENROUTER, false],
+    ["openai.azure.com", AZURE, false],
+    ["azure.com", AZURE, false],
+    ["amazonaws.com", BEDROCK, false],
+    ["aiplatform.googleapis.com", VERTEX, true],
+];
+/**
+ * True when `host` IS `domain` or a subdomain of it — never a substring.
+ * `api.openrouter.ai` matches `openrouter.ai`; `openrouter.ai.evil.test` does
+ * not. Substring matching would let any host anyone can register be recorded as
+ * a trusted substrate, corrupting the exact comparison this dimension exists to
+ * make.
+ */
+function hostMatches(host, domain, regionalPrefix) {
+    if (host === domain || host.endsWith("." + domain))
+        return true;
+    return regionalPrefix && host.endsWith("-" + domain);
+}
+/**
+ * Map a client's base URL to a substrate, or `undefined` if unreadable.
+ *
+ * Accepts anything stringable (the OpenAI SDK carries a string, others a `URL`).
+ * An unparseable value returns `undefined` rather than a default — no evidence,
+ * no claim. A host we cannot name reads `gateway`, which says the path was not
+ * the vendor's own without inventing a vendor for it.
+ */
+export function fromBaseUrl(baseUrl) {
+    if (baseUrl == null)
+        return undefined;
+    let raw;
+    try {
+        raw = String(baseUrl).trim();
+    }
+    catch {
+        return undefined;
+    }
+    if (!raw)
+        return undefined;
+    let host;
+    try {
+        host = new URL(raw).hostname.toLowerCase();
+    }
+    catch {
+        return undefined;
+    }
+    if (!host)
+        return undefined;
+    for (const [domain, name, regionalPrefix] of HOST_SUBSTRATES) {
+        if (hostMatches(host, domain, regionalPrefix))
+            return name;
+    }
+    for (const domain of DIRECT_HOSTS) {
+        if (hostMatches(host, domain, false))
+            return DIRECT;
+    }
+    return GATEWAY;
+}
+/**
+ * Detect the substrate from a live SDK client or one of its resources.
+ *
+ * The JS instrumenters patch a method on a specific client INSTANCE, so the
+ * endpoint is in hand at patch time — a process holding a vendor client and a
+ * router client instruments each separately and each reports correctly. Both
+ * `baseURL` (the JS SDKs' spelling) and `base_url` are read, and the resource's
+ * private `_client` is tried before the object itself so a patched
+ * `chat.completions` resolves as well as a bare client. Every lookup is
+ * defensive: a shape change in a vendor SDK must degrade to "no substrate
+ * recorded", never break the host's call.
+ */
+export function fromClient(obj) {
+    if (obj == null)
+        return undefined;
+    const o = obj;
+    for (const candidate of [o._client, o.client, o]) {
+        if (candidate == null)
+            continue;
+        let base;
+        try {
+            const c = candidate;
+            base = c.baseURL ?? c.base_url;
+        }
+        catch {
+            continue;
+        }
+        const found = fromBaseUrl(base);
+        if (found !== undefined)
+            return found;
+    }
+    return undefined;
+}
+//# sourceMappingURL=substrate.js.map

package/dist/substrate.js.map

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

package/dist/vitest.d.ts

@@ -0,0 +1,232 @@
+/**
+ * margin-meter/vitest — turn a vitest/jest JSON result file into outcomes.
+ *
+ * The TypeScript test-runner adapter, the analog of the Python
+ * `margin_meter.pytest_plugin`. A unit-test suite is already an eval harness:
+ * each test is a pass/fail verdict graded by code assertions against a
+ * known-correct expectation — a *ground-truth*, *code* grade, which is exactly
+ * the honest denominator Margin's outcome intake wants
+ * (`docs/INTEGRATION_LADDER.md` rung 2, and rung 6's grading provenance). So the
+ * whole of rung 2 — "their evals report pass/fail" — is available for the most
+ * common JS/TS grading path with no hand-written `POST`.
+ *
+ * ## One adapter, two frameworks
+ *
+ * This is a JSON-results CONSUMER, not a runtime reporter, because that reads a
+ * file the customer already produces and drags in no test-framework dependency —
+ * the same design as the promptfoo/braintrust/langsmith adapters. Both dominant
+ * JS test runners emit the SAME jest-compatible JSON, so one adapter covers
+ * both:
+ *
+ *     vitest run --reporter=json --outputFile=results.json   # vitest
+ *     jest --json --outputFile=results.json                  # jest
+ *
+ *     import { MarginMeter, vitest } from "margin-meter";
+ *     const meter = new MarginMeter();              // MARGIN_INGEST_URL/KEY from env
+ *     const data = JSON.parse(await readFile("results.json", "utf8"));
+ *     await vitest.recordResults(meter, data, "my-test-suite");
+ *
+ * The mapping mirrors the pytest plugin's, on purpose — the SDKs must not drift:
+ *
+ *  - `passed`        ← the assertion `status`: `passed` → true, `failed` →
+ *    false. Any other status (`skipped`/`todo`/`pending`/`disabled`) is NOT a
+ *    verdict and is SKIPPED — recording a skip as a pass or a fail would
+ *    fabricate an outcome the suite never produced.
+ *  - `qualityScore`  ← `1.0` / `0.0` (a binary ground-truth grade). Always
+ *    supplied: the ingest layer discards `quality_method`/`grader_kind` on a
+ *    scoreless outcome, so the score is what lights the grading provenance.
+ *  - `qualityMethod`/`graderKind` ← `ground_truth`/`code`, ASSERTED, never
+ *    inferred — a code assertion IS a ground-truth code grade, exactly as the
+ *    pytest plugin asserts. (Unlike promptfoo/braintrust, which grade several
+ *    ways and must derive the signature; a unit test is unambiguously code.)
+ *  - `link`          ← the assertion `fullName`, else its ancestor titles + its
+ *    title, else the file name + row index — for traceability back to the exact
+ *    test. Truncated to 512 (a lossy link beats a lost outcome).
+ *  - a test FILE that crashed on load/collection (a failing file status with no
+ *    per-test results) records no outcome — there is no honest count of the
+ *    tests it would have produced — but it WARNS, so a fully broken run is not
+ *    silently read as a clean one.
+ *
+ * ## The honest limit — rung 8 is not reachable here, and that is stated, not defaulted
+ *
+ * The jest/vitest JSON format carries no per-test value field, so a
+ * value-per-outcome numerator (rung 8) cannot ride this FILE path. Absent is
+ * the honest cost-per-outcome default — never coerced to `0`. The route to
+ * rung 8 from a test suite is the RUNTIME path (`@pytest.mark.margin_value` in
+ * Python), and it lives in this same module: {@link MarginVitestReporter} runs
+ * inside the suite and reads `task.meta.marginValue`. Use the file consumer
+ * when you already have a results file; use the reporter when you want value.
+ *
+ * Two design promises, same as the sibling adapters: it consumes the file the
+ * customer already produces (no new harness), and it is fail-safe — a delivery
+ * fault on one row warns and is counted, never aborting the batch.
+ */
+import type { RecordOutcomeInput } from "./index.ts";
+/** Where a warning goes. Defaults to `process.emitWarning` so a delivery
+ *  problem is visible without crashing the host; a test injects a collector. */
+export type WarnFn = (message: string) => void;
+/** Map a jest/vitest assertion `status` to a pass/fail verdict, or `undefined`
+ *  when the status is not a verdict at all (`skipped`/`todo`/`pending`/
+ *  `disabled`/unknown). A skip is neither a pass nor a fail, so it is dropped
+ *  rather than fabricated. */
+export declare function verdictFromStatus(status: unknown): boolean | undefined;
+/** A traceable link back to the exact test: the assertion's `fullName` if the
+ *  runner wrote one, else its ancestor titles joined with its title, else the
+ *  test file name plus the row index. */
+export declare function linkFromAssertion(assertion: unknown, fileName: unknown, index: number): string;
+/** One assertion result paired with the test file it came from (for the link
+ *  fallback). {@link extractAssertions} produces these. */
+export interface FlatAssertion {
+    assertion: Record<string, unknown>;
+    fileName?: string;
+}
+/** Flatten a parsed vitest/jest JSON output to a per-test list. The canonical
+ *  shape is `{ testResults: [{ name, assertionResults: [...] }] }` (jest's
+ *  `--json`, vitest's `--reporter=json`); a bare array is treated as an
+ *  already-flattened list of assertion results, for convenience and testing. */
+export declare function extractAssertions(data: unknown): FlatAssertion[];
+/** Names of test files that failed with no per-test results — a suite that
+ *  crashed on load/collection. These carry no recordable verdict (there is no
+ *  honest count of tests a crashed suite "would have" produced), so they are NOT
+ *  turned into outcomes; {@link recordResults} warns for each so a fully broken
+ *  run is not silently read as a clean one — the whole point of an honest
+ *  denominator. */
+export declare function failedEmptySuites(data: unknown): string[];
+/** Fields for {@link outcomeInput}. */
+export interface OutcomeInputArgs {
+    workflowId: string;
+    passed: boolean;
+    link: string;
+    isSimulated?: boolean;
+    /** Opt-in business value (rung 8). Reachable only from the runtime reporter
+     *  (`task.meta.marginValue`); the file-consumer path never supplies it, since
+     *  the jest/vitest JSON carries no value field. Absent stays absent. */
+    valueUsd?: number;
+}
+/** Translate one code-graded test verdict into `MarginMeter.recordOutcome`
+ *  input. The grader signature is asserted (`ground_truth`/`code`) because a
+ *  unit test is unambiguously a code grade. `valueUsd` rides only when supplied
+ *  (never defaulted to 0). */
+export declare function outcomeInput(args: OutcomeInputArgs): RecordOutcomeInput;
+/** Options shared by the assertion-level translators. */
+export interface TranslateOptions {
+    workflowId: string;
+    index?: number;
+    isSimulated?: boolean;
+}
+/** Full translation of one flattened assertion, or `undefined` if its status is
+ *  not a real verdict (a skip/todo/pending is dropped, never fabricated). */
+export declare function assertionToOutcomeInput(item: FlatAssertion, opts: TranslateOptions): RecordOutcomeInput | undefined;
+/** Yield `recordOutcome` inputs for every real verdict in a parsed vitest/jest
+ *  output (any envelope shape {@link extractAssertions} understands). */
+export declare function iterOutcomes(data: unknown, opts: {
+    workflowId: string;
+    isSimulated?: boolean;
+}): 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 a parsed vitest/jest output through `meter`.
+ *  Fail-safe: a delivery fault on one row warns and counts an error; it never
+ *  aborts the batch. Non-verdict rows (skips/todos/pending) are counted as
+ *  skipped. */
+export declare function recordResults(meter: OutcomeSink, data: unknown, workflowId: string, opts?: {
+    isSimulated?: boolean;
+    onWarn?: WarnFn;
+}): Promise<RecordSummary>;
+/** Read an opt-in `marginValue` off a task's `meta` — the value-per-outcome
+ *  numerator (rung 8). Returns the USD amount, or `undefined` when the key is
+ *  absent (the normal cost-per-outcome case). Throws on a malformed value
+ *  (including an explicit `null`, i.e. present-but-malformed) so the caller can
+ *  warn and drop it while keeping the pass/fail.
+ *
+ *  An explicit `undefined` (`meta.marginValue = undefined`) is treated as absent
+ *  — setting a meta key to `undefined` is not a value a customer meant to
+ *  supply. This is the one intentional divergence from the file-adapters'
+ *  `valueFrom*`, and it only ever drops-silently rather than fabricating. */
+export declare function valueFromTaskMeta(meta: unknown): number | undefined;
+/** A minimal structural view of a vitest task — duck-typed against vitest's
+ *  documented reporter task tree so this module imports NOTHING from vitest and
+ *  is not pinned to one of its versions. A suite carries child `tasks`; a test
+ *  carries a `result.state`. */
+export interface VitestTask {
+    type?: string;
+    name?: string;
+    result?: {
+        state?: string;
+    };
+    meta?: Record<string, unknown>;
+    tasks?: unknown[];
+}
+/** Map a vitest task result state to a pass/fail verdict, or `undefined` when it
+ *  is not a verdict (`skip`/`todo`/`queued`/absent — a skipped or not-yet-run
+ *  test is neither a pass nor a fail, so it is dropped, never fabricated). */
+export declare function verdictFromState(state: unknown): boolean | undefined;
+/** One leaf test found in the task tree, with the suite path that leads to it. */
+export interface WalkedTest {
+    task: Record<string, unknown>;
+    path: string[];
+}
+/** Depth-first walk of a vitest task tree, yielding every LEAF test together
+ *  with its ancestor suite names. A node is a CONTAINER (a suite, or a file
+ *  whose `tasks` are its top-level tests) exactly when it has a `tasks` array —
+ *  regardless of whether that array is empty — and is recursed into, never
+ *  recorded. Everything else is a leaf test.
+ *
+ *  ⛔ The container test is the PRESENCE of `tasks`, not its length. vitest emits
+ *  a file that CRASHED on collection as a suite node with `tasks: []` AND
+ *  `result.state: "fail"`; a length check would misread that as a failed leaf
+ *  test and fabricate a `passed:false` code-graded outcome for a file that ran
+ *  zero tests — the exact over-claim the file-consumer path refuses. A real test
+ *  never carries a `tasks` property, so this classification keeps every genuine
+ *  verdict while dropping the crashed/empty suite. */
+export declare function walkTasks(nodes: unknown, ancestors?: string[]): WalkedTest[];
+/** Yield `recordOutcome` inputs for every real verdict in a vitest `files` tree
+ *  (the argument vitest passes a reporter's `onFinished`). A test's value rides
+ *  from `task.meta.marginValue`; a malformed value warns and drops the value,
+ *  keeping the pass/fail. */
+export declare function iterTaskOutcomes(files: unknown, opts: {
+    workflowId: string;
+    isSimulated?: boolean;
+    onWarn?: WarnFn;
+}): RecordOutcomeInput[];
+/** Options for {@link MarginVitestReporter}. */
+export interface MarginVitestReporterOptions {
+    /** The workflow every test in this suite is recorded under. Falls back to
+     *  `MARGIN_VITEST_WORKFLOW` in the environment; with neither, the reporter is
+     *  a no-op (and warns once) — installing it never silently records to nowhere. */
+    workflowId?: string;
+    /** The sink outcomes are emitted through. Injected in tests; in production it
+     *  is left undefined and a real `MarginMeter` (reading `MARGIN_INGEST_URL`/
+     *  `MARGIN_INGEST_KEY` from the env) is lazily constructed on first finish. */
+    meter?: OutcomeSink;
+    isSimulated?: boolean;
+    onWarn?: WarnFn;
+}
+/** A vitest reporter that records every test as a code-graded outcome and reads
+ *  an opt-in per-test value off `task.meta.marginValue` (rung 8). It implements
+ *  only the `onFinished(files)` hook — the one vitest calls with the completed
+ *  task tree — and is fail-safe: a delivery or config fault warns, and NOTHING
+ *  it does throws into the test run. */
+export declare class MarginVitestReporter {
+    private readonly opts;
+    /** The last batch's summary — handy for a customer's own assertions and for
+     *  the hermetic tests. */
+    summary: RecordSummary;
+    constructor(opts?: MarginVitestReporterOptions);
+    private resolveWorkflow;
+    private resolveMeter;
+    /** vitest's end-of-run hook. `files` is the completed task tree. */
+    onFinished(files?: unknown): Promise<void>;
+}
+//# sourceMappingURL=vitest.d.ts.map

package/dist/vitest.d.ts.map

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