metergraph 0.1.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -18,7 +18,7 @@ setSession("ticket-123");
18
18
 
19
19
  let model = "gpt-4.1-mini";
20
20
  await route("ticket-classifier", async () => {
21
- model = modelFor("ticket-classifier", model);
21
+ model = modelFor("ticket-classifier", { default: model });
22
22
  await client.chat.completions.create({ model, messages: [] });
23
23
  }, { unit: "answer", captureText: true });
24
24
 
@@ -31,6 +31,12 @@ recordOutcome("ticket-classifier", {
31
31
  });
32
32
  ```
33
33
 
34
+ `modelFor(routeName, { default, sessionKey })` takes an options object.
35
+ **Breaking change from `metergraph@0.1.0`**, which took positional
36
+ `modelFor(routeName, fallback, sessionKey?)` arguments; `default` is
37
+ required and throws if missing so a caller error surfaces immediately
38
+ instead of an `undefined` model reaching a provider call.
39
+
34
40
  Set `METERGRAPH_APP_TOKEN`; `METERGRAPH_INGEST_URL` is only needed to override
35
41
  the hosted HTTPS endpoint. Content is metadata-only by default; set
36
42
  `METERGRAPH_CAPTURE_TEXT=1` globally or `captureText: true` on an individual
package/dist/config.d.ts CHANGED
@@ -19,6 +19,10 @@ export declare class ConfigPoller {
19
19
  private routes;
20
20
  private lastSuccess;
21
21
  private timer?;
22
+ private stopped;
23
+ private readonly failureLog;
24
+ /** Resolves once the constructor's initial poll attempt has completed (success or failure). Exposed primarily so tests can synchronize deterministically instead of guessing a delay; not required for normal use. */
25
+ readonly ready: Promise<boolean>;
22
26
  constructor(token: string, baseUrl: string, pollMs?: number, hardTtlMs?: number);
23
27
  poll(): Promise<boolean>;
24
28
  modelFor(route: string, fallback: string, sessionKey?: string): string;
package/dist/config.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { FailureLogger } from "./failure-log.js";
1
2
  function bucket(value) {
2
3
  let hash = 0xcbf29ce484222325n;
3
4
  for (const byte of new TextEncoder().encode(value)) {
@@ -26,16 +27,25 @@ export class ConfigPoller {
26
27
  routes = {};
27
28
  lastSuccess = 0;
28
29
  timer;
30
+ stopped = false;
31
+ failureLog = new FailureLogger();
32
+ /** Resolves once the constructor's initial poll attempt has completed (success or failure). Exposed primarily so tests can synchronize deterministically instead of guessing a delay; not required for normal use. */
33
+ ready;
29
34
  constructor(token, baseUrl, pollMs = 30_000, hardTtlMs = 120_000) {
30
35
  this.token = token;
31
36
  this.baseUrl = baseUrl;
32
37
  this.pollMs = pollMs;
33
38
  this.hardTtlMs = hardTtlMs;
34
- void this.poll();
35
- this.timer = setInterval(() => void this.poll(), Math.max(1_000, pollMs));
39
+ this.ready = this.poll();
40
+ this.timer = setInterval(() => {
41
+ if (!this.stopped)
42
+ void this.poll();
43
+ }, Math.max(1_000, pollMs));
36
44
  this.timer.unref?.();
37
45
  }
38
46
  async poll() {
47
+ if (this.stopped)
48
+ return false;
39
49
  try {
40
50
  const headers = { Authorization: `Bearer ${this.token}` };
41
51
  if (this.etag)
@@ -45,15 +55,23 @@ export class ConfigPoller {
45
55
  this.lastSuccess = Date.now();
46
56
  return true;
47
57
  }
48
- if (!response.ok)
58
+ if (response.status === 401 || response.status === 403) {
59
+ console.warn("Metergraph config authentication failed; using default models");
60
+ this.stop();
61
+ return false;
62
+ }
63
+ if (!response.ok) {
64
+ this.failureLog.report("config_poll_error", `config poll to ${this.baseUrl} failed with HTTP ${response.status}`);
49
65
  return false;
66
+ }
50
67
  const body = await response.json();
51
68
  this.routes = body.routes ?? {};
52
69
  this.etag = response.headers.get("etag") ?? undefined;
53
70
  this.lastSuccess = Date.now();
54
71
  return true;
55
72
  }
56
- catch {
73
+ catch (error) {
74
+ this.failureLog.report("config_poll_error", `config poll to ${this.baseUrl} failed: ${error instanceof Error ? error.message : String(error)}`);
57
75
  return false;
58
76
  }
59
77
  }
@@ -63,6 +81,7 @@ export class ConfigPoller {
63
81
  return chooseModel(route, fallback, sessionKey, this.routes[route]);
64
82
  }
65
83
  stop() {
84
+ this.stopped = true;
66
85
  if (this.timer)
67
86
  clearInterval(this.timer);
68
87
  }
@@ -0,0 +1,14 @@
1
+ /**
2
+ * Rate-limited failure logging. Logs the first occurrence of a failure kind
3
+ * immediately, then suppresses repeats within a quiet window and reports how
4
+ * many were suppressed on the next log line for that kind.
5
+ */
6
+ export declare class FailureLogger {
7
+ private readonly quietMs;
8
+ private readonly clock;
9
+ private readonly sink;
10
+ private readonly lastLogged;
11
+ private readonly suppressed;
12
+ constructor(quietMs?: number, clock?: () => number, sink?: (message: string) => void);
13
+ report(kind: string, message: string): void;
14
+ }
@@ -0,0 +1,32 @@
1
+ /**
2
+ * Rate-limited failure logging. Logs the first occurrence of a failure kind
3
+ * immediately, then suppresses repeats within a quiet window and reports how
4
+ * many were suppressed on the next log line for that kind.
5
+ */
6
+ export class FailureLogger {
7
+ quietMs;
8
+ clock;
9
+ sink;
10
+ lastLogged = new Map();
11
+ suppressed = new Map();
12
+ constructor(quietMs = 60_000, clock = Date.now, sink = (m) => console.warn(m)) {
13
+ this.quietMs = quietMs;
14
+ this.clock = clock;
15
+ this.sink = sink;
16
+ }
17
+ report(kind, message) {
18
+ const now = this.clock();
19
+ const last = this.lastLogged.get(kind);
20
+ if (last !== undefined && now - last < this.quietMs) {
21
+ this.suppressed.set(kind, (this.suppressed.get(kind) ?? 0) + 1);
22
+ return;
23
+ }
24
+ const suppressedCount = this.suppressed.get(kind) ?? 0;
25
+ this.suppressed.delete(kind);
26
+ const suffix = suppressedCount
27
+ ? ` (${suppressedCount} more suppressed in the last ${Math.round(this.quietMs / 1000)}s)`
28
+ : "";
29
+ this.sink(`metergraph: ${message}${suffix}`);
30
+ this.lastLogged.set(kind, now);
31
+ }
32
+ }
package/dist/index.d.ts CHANGED
@@ -17,6 +17,10 @@ export interface MetergraphOptions {
17
17
  configPollMs?: number;
18
18
  configHardTtlMs?: number;
19
19
  }
20
+ export interface ModelForOptions {
21
+ default: string;
22
+ sessionKey?: string;
23
+ }
20
24
  export interface OutcomeOptions {
21
25
  model: string;
22
26
  taskCompleted: boolean;
@@ -31,7 +35,7 @@ export interface OutcomeOptions {
31
35
  }
32
36
  export declare const DEFAULT_INGEST_URL = "https://d2xus7mp8zdv6t.cloudfront.net";
33
37
  export declare function init(options?: MetergraphOptions): void;
34
- export declare function modelFor(routeName: string, fallback: string, sessionKey?: string): string;
38
+ export declare function modelFor(routeName: string, options: ModelForOptions): string;
35
39
  export declare function recordOutcome(routeName: string, options: OutcomeOptions): boolean;
36
40
  export declare function bindWaitUntil(value: {
37
41
  waitUntil(promise: Promise<unknown>): void;
package/dist/index.js CHANGED
@@ -60,8 +60,11 @@ export function init(options = {}) {
60
60
  console.warn("Metergraph initialization failed; application is running uninstrumented");
61
61
  }
62
62
  }
63
- export function modelFor(routeName, fallback, sessionKey) {
64
- return config?.modelFor(routeName, fallback, sessionKey ?? contextSnapshot().sessionId) ?? fallback;
63
+ export function modelFor(routeName, options) {
64
+ if (typeof options?.default !== "string" || !options.default) {
65
+ throw new TypeError("modelFor requires options.default to be a non-empty string");
66
+ }
67
+ return config?.modelFor(routeName, options.default, options.sessionKey ?? contextSnapshot().sessionId) ?? options.default;
65
68
  }
66
69
  export function recordOutcome(routeName, options) {
67
70
  const routeNameClean = String(routeName).trim().slice(0, 512);
@@ -23,6 +23,7 @@ export declare class Transport {
23
23
  private errors;
24
24
  private retryAt;
25
25
  private backoffMs;
26
+ private readonly failureLog;
26
27
  constructor(token: string, baseUrl: string, options?: TransportOptions);
27
28
  bindWaitUntil(value: {
28
29
  waitUntil(promise: Promise<unknown>): void;
@@ -30,6 +31,7 @@ export declare class Transport {
30
31
  enqueue(row: Record<string, unknown>): boolean;
31
32
  private schedule;
32
33
  flush(timeoutMs?: number): Promise<boolean>;
34
+ private markTransientFailure;
33
35
  private deliver;
34
36
  shutdown(): Promise<void>;
35
37
  }
package/dist/transport.js CHANGED
@@ -1,3 +1,4 @@
1
+ import { FailureLogger } from "./failure-log.js";
1
2
  export const MAX_BATCH_BYTES = 512 * 1024;
2
3
  function detectedMode() {
3
4
  const env = typeof process === "undefined" ? {} : process.env;
@@ -28,6 +29,7 @@ export class Transport {
28
29
  errors = 0;
29
30
  retryAt = 0;
30
31
  backoffMs = 1_000;
32
+ failureLog = new FailureLogger();
31
33
  constructor(token, baseUrl, options = {}) {
32
34
  this.token = token;
33
35
  this.baseUrl = baseUrl;
@@ -86,6 +88,12 @@ export class Transport {
86
88
  });
87
89
  return this.queue.length === 0;
88
90
  }
91
+ markTransientFailure(rowCount) {
92
+ this.errors += 1;
93
+ this.dropped += rowCount;
94
+ this.retryAt = Date.now() + this.backoffMs;
95
+ this.backoffMs = Math.min(this.backoffMs * 2, 60_000);
96
+ }
89
97
  async deliver(rows) {
90
98
  if (this.fatal || Date.now() < this.retryAt) {
91
99
  this.dropped += rows.length;
@@ -125,16 +133,28 @@ export class Transport {
125
133
  console.warn("Metergraph authentication failed; capture disabled for this process");
126
134
  return;
127
135
  }
128
- if (response.status !== 202)
129
- throw new Error(`ingest returned ${response.status}`);
136
+ if (response.status === 413 && rows.length > 1) {
137
+ const midpoint = Math.floor(rows.length / 2);
138
+ await this.deliver(rows.slice(0, midpoint));
139
+ await this.deliver(rows.slice(midpoint));
140
+ return;
141
+ }
142
+ if ([400, 404, 413, 422].includes(response.status)) {
143
+ this.dropped += rows.length;
144
+ this.failureLog.report("client_error", `ingest rejected batch with HTTP ${response.status} against ${this.baseUrl}; dropping this batch (payload-specific, not a process-wide failure)`);
145
+ return;
146
+ }
147
+ if (response.status !== 202) {
148
+ this.markTransientFailure(rows.length);
149
+ this.failureLog.report("server_error", `ingest request failed with HTTP ${response.status} against ${this.baseUrl}`);
150
+ return;
151
+ }
130
152
  this.backoffMs = 1_000;
131
153
  this.retryAt = 0;
132
154
  }
133
- catch {
134
- this.errors += 1;
135
- this.dropped += rows.length;
136
- this.retryAt = Date.now() + this.backoffMs;
137
- this.backoffMs = Math.min(this.backoffMs * 2, 60_000);
155
+ catch (error) {
156
+ this.markTransientFailure(rows.length);
157
+ this.failureLog.report("transport_error", `ingest request to ${this.baseUrl} failed: ${error instanceof Error ? error.message : String(error)}`);
138
158
  }
139
159
  }
140
160
  async shutdown() {
package/dist/version.d.ts CHANGED
@@ -1 +1 @@
1
- export declare const SDK_VERSION = "0.1.0";
1
+ export declare const SDK_VERSION = "0.2.1";
package/dist/version.js CHANGED
@@ -1 +1 @@
1
- export const SDK_VERSION = "0.1.0";
1
+ export const SDK_VERSION = "0.2.1";
package/dist/wrap.d.ts CHANGED
@@ -1,6 +1,15 @@
1
1
  import { type CaptureRuntime } from "./capture.js";
2
2
  type AnyRecord = Record<PropertyKey, any>;
3
3
  export declare function setCaptureRuntime(value?: CaptureRuntime): void;
4
+ export interface Seam {
5
+ path: string;
6
+ method: string;
7
+ endpoint: string;
8
+ }
9
+ export declare const OPENAI_SEAMS: Seam[];
10
+ export declare const ANTHROPIC_SEAMS: Seam[];
11
+ export declare const GOOGLE_SEAMS: Seam[];
12
+ export declare const SEAM_TABLES: Record<string, Seam[]>;
4
13
  export declare function wrap<T extends AnyRecord>(client: T, provider?: "openai" | "anthropic" | "google"): T;
5
14
  export declare const wrapClient: typeof wrap;
6
15
  export {};
package/dist/wrap.js CHANGED
@@ -2,6 +2,15 @@ import { chunkText } from "./capture.js";
2
2
  import { contextSnapshot } from "./context.js";
3
3
  let runtime;
4
4
  const seenBatchItems = new Set();
5
+ // Tracks which resource *owners* (e.g. a specific chat.completions instance)
6
+ // currently have a wrapped call in flight synchronously, so a delegating
7
+ // method (like openai's .parse() calling .create() on the same owner
8
+ // before any await) can be told apart from an unrelated wrapped call that
9
+ // merely happens to be nested inside another's synchronous execution.
10
+ // Scoped per-owner, not global, so two independent clients invoked in the
11
+ // same synchronous window are never mistaken for one delegating into the
12
+ // other.
13
+ const reentrantOwners = new WeakSet();
5
14
  export function setCaptureRuntime(value) {
6
15
  runtime = value;
7
16
  }
@@ -281,6 +290,23 @@ function patch(owner, method, provider, endpoint) {
281
290
  const capture = runtime;
282
291
  if (!capture)
283
292
  return original.apply(owner, args);
293
+ if (reentrantOwners.has(owner)) {
294
+ // Some SDK methods delegate to another already-wrapped method on the
295
+ // *same owner* synchronously as part of building their return value
296
+ // (e.g. openai's chat.completions.parse calls .create(...) — on the
297
+ // same chat.completions instance — internally, then immediately
298
+ // chains its proprietary ._thenUnwrap() onto the result). Capturing
299
+ // this nested call too would both double-count a single underlying
300
+ // request and, worse, replace .create()'s return value with a plain
301
+ // Promise that lacks ._thenUnwrap, breaking the outer method
302
+ // entirely. Pass straight through untouched.
303
+ //
304
+ // Scoped to this specific owner (not a global flag): an unrelated
305
+ // wrapped call — a different resource, or a different client's
306
+ // instance entirely — invoked synchronously inside this one's
307
+ // execution must still be captured independently.
308
+ return original.apply(owner, args);
309
+ }
284
310
  const incoming = requestFrom(args);
285
311
  const patchUsage = typeof process === "undefined"
286
312
  || process.env.METERGRAPH_PATCH_STREAM_USAGE !== "0";
@@ -293,6 +319,7 @@ function patch(owner, method, provider, endpoint) {
293
319
  }
294
320
  const state = capture.start(provider, endpoint, requestFrom(args), new Error().stack);
295
321
  let result;
322
+ reentrantOwners.add(owner);
296
323
  try {
297
324
  result = original.apply(owner, args);
298
325
  }
@@ -300,6 +327,9 @@ function patch(owner, method, provider, endpoint) {
300
327
  capture.finish(state, undefined, { error });
301
328
  throw error;
302
329
  }
330
+ finally {
331
+ reentrantOwners.delete(owner);
332
+ }
303
333
  const complete = (response) => {
304
334
  const request = requestFrom(args);
305
335
  const streaming = endpoint.endsWith(".stream") || request.stream === true;
@@ -321,30 +351,102 @@ function patch(owner, method, provider, endpoint) {
321
351
  owner[method] = wrapped;
322
352
  return true;
323
353
  }
324
- export function wrap(client, provider) {
325
- const name = provider ?? (client.models?.generateContent
326
- ? "google"
327
- : client.chat || client.responses ? "openai" : "anthropic");
328
- let patched = 0;
329
- if (name === "google") {
330
- patched += Number(patch(client.models, "generateContent", name, "models.generate_content"));
331
- patched += Number(patch(client.models, "generateContentStream", name, "models.generate_content.stream"));
354
+ export const OPENAI_SEAMS = [
355
+ { path: "chat.completions", method: "create", endpoint: "chat.completions" },
356
+ { path: "chat.completions", method: "parse", endpoint: "chat.completions.parse" },
357
+ // beta.chat.completions.parse is v4.x-only — removed at the v4->v5
358
+ // boundary when .parse() moved to the stable chat.completions/responses
359
+ // namespaces (see metergraph-internal#9). Kept here anyway: a seam that
360
+ // doesn't exist on the installed client resolves to undefined and is
361
+ // silently skipped (see resolveSeam/applySeams below), so keeping this
362
+ // entry costs nothing on openai>=5 and restores real instrumentation for
363
+ // any consumer still on openai v4.
364
+ { path: "beta.chat.completions", method: "parse", endpoint: "chat.completions.parse" },
365
+ { path: "responses", method: "create", endpoint: "responses" },
366
+ { path: "responses", method: "stream", endpoint: "responses.stream" },
367
+ { path: "responses", method: "parse", endpoint: "responses.parse" },
368
+ { path: "beta.responses", method: "create", endpoint: "responses" },
369
+ // Note: as of openai (npm) v7.x, client.beta.responses has no .parse
370
+ // method. This table's reality-check test is pinned to latest openai, so
371
+ // beta.chat.completions.parse above is exempted from that check since it
372
+ // will correctly show as absent there — see the test for details.
373
+ ];
374
+ export const ANTHROPIC_SEAMS = [
375
+ { path: "messages", method: "create", endpoint: "messages" },
376
+ { path: "messages", method: "stream", endpoint: "messages.stream" },
377
+ ];
378
+ export const GOOGLE_SEAMS = [
379
+ { path: "models", method: "generateContent", endpoint: "models.generate_content" },
380
+ { path: "models", method: "generateContentStream", endpoint: "models.generate_content.stream" },
381
+ // Note: unlike the Python google-genai client, the JS/TS @google/genai
382
+ // client has no .aio namespace at all (verified directly against the
383
+ // installed package — client.aio is undefined; JS methods are already
384
+ // Promise-based) — do not add aio.models entries here.
385
+ ];
386
+ export const SEAM_TABLES = {
387
+ openai: OPENAI_SEAMS,
388
+ anthropic: ANTHROPIC_SEAMS,
389
+ google: GOOGLE_SEAMS,
390
+ };
391
+ function detectProvider(client) {
392
+ if (client.models?.generateContent)
393
+ return "google";
394
+ if (client.chat || client.responses)
395
+ return "openai";
396
+ return "anthropic";
397
+ }
398
+ function resolveSeam(client, path) {
399
+ let obj = client;
400
+ for (const part of path.split(".")) {
401
+ obj = obj?.[part];
402
+ if (obj === undefined || obj === null)
403
+ return undefined;
332
404
  }
333
- patched += Number(patch(client.chat?.completions, "create", name, "chat.completions"));
334
- patched += Number(patch(client.responses, "create", name, "responses"));
335
- patched += Number(patch(client.responses, "stream", name, "responses.stream"));
336
- patched += Number(patch(client.messages, "create", name, "messages"));
337
- patched += Number(patch(client.messages, "stream", name, "messages.stream"));
338
- if (name === "openai") {
405
+ return obj;
406
+ }
407
+ function applySeams(client, provider) {
408
+ const patched = [];
409
+ for (const seam of SEAM_TABLES[provider] ?? []) {
410
+ let owner;
411
+ try {
412
+ owner = resolveSeam(client, seam.path);
413
+ }
414
+ catch {
415
+ continue; // a pathological client property must never break wrap()
416
+ }
417
+ if (owner !== undefined && patch(owner, seam.method, provider, seam.endpoint)) {
418
+ patched.push(`${seam.path}.${seam.method}`);
419
+ }
420
+ }
421
+ return patched;
422
+ }
423
+ function applyBatchExtras(client, provider) {
424
+ let patched = 0;
425
+ if (provider === "openai") {
339
426
  patched += Number(patchOpenAIBatchContent(client.files, "content"));
340
427
  patched += Number(patchOpenAIBatchContent(client.files, "retrieveContent"));
341
428
  }
342
- else if (name === "anthropic") {
429
+ else if (provider === "anthropic") {
343
430
  patched += Number(patchAnthropicBatchResults(client.messages?.batches));
344
431
  patched += Number(patchAnthropicBatchResults(client.beta?.messages?.batches));
345
432
  }
346
- if (!patched)
347
- console.warn(`Metergraph found no supported methods on ${name} client`);
433
+ return patched;
434
+ }
435
+ export function wrap(client, provider) {
436
+ try {
437
+ const name = provider ?? detectProvider(client);
438
+ const patched = applySeams(client, name);
439
+ const patchedCount = patched.length + applyBatchExtras(client, name);
440
+ if (!patchedCount) {
441
+ console.warn(`Metergraph found no supported methods on ${name} client`);
442
+ }
443
+ else {
444
+ console.info(`Metergraph patched ${patchedCount} seam(s) on ${name} client: ${patched.join(", ") || "(batch-only)"}`);
445
+ }
446
+ }
447
+ catch (error) {
448
+ console.warn("Metergraph wrap() failed; client is unmodified and uninstrumented", error);
449
+ }
348
450
  return client;
349
451
  }
350
452
  export const wrapClient = wrap;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "metergraph",
3
- "version": "0.1.0",
3
+ "version": "0.2.1",
4
4
  "description": "Fire-and-forget LLM spend capture for Metergraph",
5
5
  "type": "module",
6
6
  "main": "./dist/index.js",
@@ -20,10 +20,24 @@
20
20
  "node": ">=18"
21
21
  },
22
22
  "license": "Apache-2.0",
23
+ "author": "Pioneer Square Labs",
24
+ "homepage": "https://www.metergraph.dev/",
25
+ "repository": {
26
+ "type": "git",
27
+ "url": "git+https://github.com/PioneerSquareLabs/metergraphsdk.git",
28
+ "directory": "typescript"
29
+ },
30
+ "bugs": {
31
+ "url": "https://github.com/PioneerSquareLabs/metergraphsdk/issues"
32
+ },
33
+ "keywords": ["llm", "observability", "openai", "anthropic", "gemini", "cost-tracking"],
23
34
  "dependencies": {},
24
35
  "devDependencies": {
25
36
  "@types/node": "^24.0.0",
26
- "typescript": "^5.8.0"
37
+ "typescript": "^5.8.0",
38
+ "openai": "^7",
39
+ "@anthropic-ai/sdk": "^0.30",
40
+ "@google/genai": "^1"
27
41
  },
28
42
  "peerDependencies": {
29
43
  "@anthropic-ai/sdk": ">=0.30",