metergraph 0.6.16 → 0.6.18
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 +26 -2
- package/dist/capture.js +13 -2
- package/dist/context.d.ts +4 -0
- package/dist/context.js +84 -7
- package/dist/index.d.ts +2 -2
- package/dist/index.js +2 -1
- package/dist/index.mjs +2 -0
- package/dist/version.d.ts +1 -1
- package/dist/version.js +1 -1
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -28,7 +28,7 @@ active; later explicit calls are ignored and produce one generic warning
|
|
|
28
28
|
without option names, token values, or other secrets.
|
|
29
29
|
|
|
30
30
|
```ts
|
|
31
|
-
import { init, wrap, route, trace, modelFor, recordOutcome, withSession } from "metergraph";
|
|
31
|
+
import { init, wrap, route, trace, modelFor, recordOutcome, withContext, withSession } from "metergraph";
|
|
32
32
|
import OpenAI from "openai";
|
|
33
33
|
|
|
34
34
|
init({ repository: "owner/repository" });
|
|
@@ -54,13 +54,37 @@ await withSession("ticket-123", async () => {
|
|
|
54
54
|
});
|
|
55
55
|
```
|
|
56
56
|
|
|
57
|
-
Use `withContext({ sessionId,
|
|
57
|
+
Use `withContext({ userId, sessionId, metadata }, fn)`, `withSession(sessionId, fn)`, or
|
|
58
58
|
`withTags(tags, fn)` for request and job identity. These callback scopes follow
|
|
59
59
|
Node's asynchronous execution and isolate concurrent jobs. Legacy
|
|
60
60
|
`setSession()` and `setTags()` remain available inside an active Metergraph
|
|
61
61
|
scope, but warn and do nothing when called outside one. Use `setDefaultTags()`
|
|
62
62
|
only for deliberate process-wide tags; sessions are always execution-scoped.
|
|
63
63
|
|
|
64
|
+
```ts
|
|
65
|
+
await withContext({
|
|
66
|
+
userId: "user-123",
|
|
67
|
+
sessionId: "ticket-123",
|
|
68
|
+
metadata: { customer_id: "customer-123" },
|
|
69
|
+
}, async () => client.chat.completions.create({ model, messages: [] }));
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
`setUser("user-123")` updates an active scope; `setUser()` clears it until that
|
|
73
|
+
scope exits. Omitted user/session arguments inherit. User identity is never
|
|
74
|
+
process-wide. `metadata` accepts flat string pairs and shares the existing
|
|
75
|
+
`tags` wire field. Valid local metadata overrides local tags and inherited or
|
|
76
|
+
default values; legacy tags still stringify. Captured calls hold copied maps.
|
|
77
|
+
|
|
78
|
+
Invalid attribution is omitted with one generic warning that contains no
|
|
79
|
+
submitted values. User IDs are nonblank strings of at most 512 Unicode code
|
|
80
|
+
points. Metadata keeps up to 32 valid pairs in Unicode key order, keys up to
|
|
81
|
+
200 and values up to 1,000 code points, within 64 KiB compact UTF-8 JSON. NUL,
|
|
82
|
+
lone surrogates and credential-like keys are omitted. Attribution remains when
|
|
83
|
+
prompt capture is off and is not added to provider requests. Historical batch
|
|
84
|
+
downloads leave `user_id` unset because submission identity is unknown;
|
|
85
|
+
existing batch tags are unchanged. Deploy compatible ingestion before relying
|
|
86
|
+
on user attribution; older collectors may ignore the optional `user_id` field.
|
|
87
|
+
|
|
64
88
|
## OpenRouter
|
|
65
89
|
|
|
66
90
|
Point an OpenAI client at `https://openrouter.ai/api/v1` and `wrap()` auto-detects
|
package/dist/capture.js
CHANGED
|
@@ -81,7 +81,7 @@ function usageValue(value) {
|
|
|
81
81
|
const aiInputDetails = get(value, "inputTokenDetails");
|
|
82
82
|
const aiOutputDetails = get(value, "outputTokenDetails");
|
|
83
83
|
const cacheCreation = get(value, "cache_creation") ?? get(value, "cacheCreation");
|
|
84
|
-
|
|
84
|
+
const counts = {
|
|
85
85
|
input_tokens: number(get(value, "prompt_tokens") ?? get(value, "input_tokens")
|
|
86
86
|
?? get(value, "promptTokenCount") ?? get(aiInput, "total") ?? aiInput),
|
|
87
87
|
output_tokens: number(get(value, "completion_tokens") ?? get(value, "output_tokens")
|
|
@@ -101,6 +101,14 @@ function usageValue(value) {
|
|
|
101
101
|
?? get(value, "thoughtsTokenCount") ?? get(aiOutput, "reasoning")
|
|
102
102
|
?? get(aiOutputDetails, "reasoningTokens")),
|
|
103
103
|
};
|
|
104
|
+
// Native Gemini reports tool context and thinking outside its prompt/candidate counts.
|
|
105
|
+
if (number(get(value, "promptTokenCount")) !== undefined) {
|
|
106
|
+
counts.input_tokens = number(get(value, "promptTokenCount")) + (number(get(value, "toolUsePromptTokenCount")) ?? 0);
|
|
107
|
+
}
|
|
108
|
+
if (number(get(value, "candidatesTokenCount")) !== undefined) {
|
|
109
|
+
counts.output_tokens = number(get(value, "candidatesTokenCount")) + (number(get(value, "thoughtsTokenCount")) ?? 0);
|
|
110
|
+
}
|
|
111
|
+
return counts;
|
|
104
112
|
}
|
|
105
113
|
function usage(response) {
|
|
106
114
|
const value = get(response, "usage") ?? get(response, "usage_metadata")
|
|
@@ -680,7 +688,7 @@ class CaptureRuntime {
|
|
|
680
688
|
provider,
|
|
681
689
|
endpoint,
|
|
682
690
|
request,
|
|
683
|
-
context,
|
|
691
|
+
context: { ...context, tags: { ...context.tags } },
|
|
684
692
|
started: performance.now(),
|
|
685
693
|
ts: new Date().toISOString(),
|
|
686
694
|
frames: frames(stack, this.options.appRoot, this.options.skipFrames, this.options.repoRoot),
|
|
@@ -833,6 +841,9 @@ class CaptureRuntime {
|
|
|
833
841
|
stream_chunks: extra.evidenceChunks ?? extra.responseChunks, stream_complete: extra.stream === true && extra.error === undefined && extra.status !== "error" && extra.status !== "abandoned" }),
|
|
834
842
|
session_id: state.context.sessionId,
|
|
835
843
|
conversation_id: state.context.sessionId,
|
|
844
|
+
// Downloading historical batch results does not establish their owner.
|
|
845
|
+
...(state.context.userId !== undefined && !state.endpoint.startsWith("batch.")
|
|
846
|
+
? { user_id: state.context.userId } : {}),
|
|
836
847
|
trace_id: state.traceId,
|
|
837
848
|
span_id: state.spanId,
|
|
838
849
|
parent_span_id: state.parentSpanId,
|
package/dist/context.d.ts
CHANGED
|
@@ -3,6 +3,7 @@ export interface CaptureContext {
|
|
|
3
3
|
/** "explicit" when the developer named the route, "derived" when filled in. */
|
|
4
4
|
routeSource?: "explicit" | "derived";
|
|
5
5
|
sessionId?: string;
|
|
6
|
+
userId?: string;
|
|
6
7
|
tags: Record<string, string>;
|
|
7
8
|
unitName?: string;
|
|
8
9
|
unitCount?: number;
|
|
@@ -29,6 +30,8 @@ export interface ContextOptions {
|
|
|
29
30
|
refusalSignal?: boolean;
|
|
30
31
|
sessionId?: string;
|
|
31
32
|
tags?: Record<string, unknown>;
|
|
33
|
+
userId?: string;
|
|
34
|
+
metadata?: Record<string, string>;
|
|
32
35
|
}
|
|
33
36
|
export declare function contextSnapshot(): CaptureContext;
|
|
34
37
|
export declare function runWithContext<T>(context: CaptureContext, fn: () => T): T;
|
|
@@ -38,5 +41,6 @@ export declare function withTags<T>(tags: Record<string, unknown>, fn: () => T):
|
|
|
38
41
|
export declare function setDefaultTags(tags: Record<string, unknown>): void;
|
|
39
42
|
export declare function route<T>(name: string, fn: () => T | Promise<T>, options?: RouteOptions): Promise<T>;
|
|
40
43
|
export declare function trace<T>(name: string, fn: () => T | Promise<T>, options?: TraceOptions): T | Promise<T>;
|
|
44
|
+
export declare function setUser(userId?: string): void;
|
|
41
45
|
export declare function setSession(sessionId?: string): void;
|
|
42
46
|
export declare function setTags(tags: Record<string, unknown>): void;
|
package/dist/context.js
CHANGED
|
@@ -8,6 +8,7 @@ exports.withTags = withTags;
|
|
|
8
8
|
exports.setDefaultTags = setDefaultTags;
|
|
9
9
|
exports.route = route;
|
|
10
10
|
exports.trace = trace;
|
|
11
|
+
exports.setUser = setUser;
|
|
11
12
|
exports.setSession = setSession;
|
|
12
13
|
exports.setTags = setTags;
|
|
13
14
|
const node_async_hooks_1 = require("node:async_hooks");
|
|
@@ -16,8 +17,70 @@ const storage = new node_async_hooks_1.AsyncLocalStorage();
|
|
|
16
17
|
let defaultTags = {};
|
|
17
18
|
let warnedSessionOutsideScope = false;
|
|
18
19
|
let warnedTagsOutsideScope = false;
|
|
20
|
+
let warnedUserOutsideScope = false;
|
|
21
|
+
let warnedAttribution = false;
|
|
22
|
+
const badText = /[\x00\uD800-\uDFFF]/u;
|
|
23
|
+
const credentialKey = /(?:accesskey|apikey|auth|authorization|bearer|clientsecret|cookie|credentials?|encryptionkey|jwt|passwd|password|privatekey|secretkey|secret|sessionkey|signingkey|token)$/;
|
|
24
|
+
// Python/hosted whitespace semantics, including U+0085 and excluding U+FEFF.
|
|
25
|
+
const whitespaceOnly = /^[\u0009-\u000d\u001c-\u0020\u0085\u00a0\u1680\u2000-\u200a\u2028\u2029\u202f\u205f\u3000]*$/u;
|
|
26
|
+
function omitted() {
|
|
27
|
+
if (!warnedAttribution) {
|
|
28
|
+
warnedAttribution = true;
|
|
29
|
+
console.warn("Metergraph omitted invalid or excess attribution; use bounded string identifiers and metadata.");
|
|
30
|
+
}
|
|
31
|
+
}
|
|
32
|
+
function user(value) {
|
|
33
|
+
if (typeof value === "string" && [...value].length <= 512 && !whitespaceOnly.test(value) && !badText.test(value))
|
|
34
|
+
return value;
|
|
35
|
+
if (value !== undefined)
|
|
36
|
+
omitted();
|
|
37
|
+
return undefined;
|
|
38
|
+
}
|
|
39
|
+
function tagValues(values, legacy = false) {
|
|
40
|
+
if (values == null)
|
|
41
|
+
return {};
|
|
42
|
+
if (typeof values !== "object" || Array.isArray(values)) {
|
|
43
|
+
omitted();
|
|
44
|
+
return {};
|
|
45
|
+
}
|
|
46
|
+
const entries = [];
|
|
47
|
+
for (const [key, raw] of Object.entries(values)) {
|
|
48
|
+
let value = raw;
|
|
49
|
+
if (legacy) {
|
|
50
|
+
try {
|
|
51
|
+
value = String(raw);
|
|
52
|
+
}
|
|
53
|
+
catch {
|
|
54
|
+
omitted();
|
|
55
|
+
continue;
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
if (key.length > 0 && [...key].length <= 200 && !badText.test(key)
|
|
59
|
+
&& !credentialKey.test(key.toLowerCase().replace(/[^a-z0-9]/g, ""))
|
|
60
|
+
&& typeof value === "string" && [...value].length <= 1000 && !badText.test(value))
|
|
61
|
+
entries.push([key, value]);
|
|
62
|
+
else
|
|
63
|
+
omitted();
|
|
64
|
+
}
|
|
65
|
+
return Object.fromEntries(entries);
|
|
66
|
+
}
|
|
67
|
+
function boundTags(values) {
|
|
68
|
+
const entries = [];
|
|
69
|
+
let size = 2;
|
|
70
|
+
// UTF-8 byte order equals Unicode codepoint order for valid strings.
|
|
71
|
+
for (const [key, value] of Object.entries(values).sort(([a], [b]) => Buffer.compare(Buffer.from(a), Buffer.from(b)))) {
|
|
72
|
+
const added = Buffer.byteLength(JSON.stringify({ [key]: value })) - 2 + (entries.length ? 1 : 0);
|
|
73
|
+
if (entries.length === 32 || size + added > 65536) {
|
|
74
|
+
omitted();
|
|
75
|
+
break;
|
|
76
|
+
}
|
|
77
|
+
entries.push([key, value]);
|
|
78
|
+
size += added;
|
|
79
|
+
}
|
|
80
|
+
return Object.fromEntries(entries);
|
|
81
|
+
}
|
|
19
82
|
function normalizeTags(tags) {
|
|
20
|
-
return
|
|
83
|
+
return tagValues(tags, true);
|
|
21
84
|
}
|
|
22
85
|
function contextSnapshot() {
|
|
23
86
|
const value = storage.getStore() ?? { tags: defaultTags };
|
|
@@ -31,8 +94,9 @@ function withContext(options, fn) {
|
|
|
31
94
|
const child = {
|
|
32
95
|
...parent,
|
|
33
96
|
sessionId: options.sessionId ?? parent.sessionId,
|
|
97
|
+
userId: options.userId === undefined ? parent.userId : user(options.userId) ?? parent.userId,
|
|
34
98
|
refusalSignal: options.refusalSignal ?? parent.refusalSignal,
|
|
35
|
-
tags: { ...parent.tags, ...normalizeTags(options.tags ?? {}) },
|
|
99
|
+
tags: boundTags({ ...parent.tags, ...normalizeTags(options.tags ?? {}), ...tagValues(options.metadata) }),
|
|
36
100
|
};
|
|
37
101
|
return storage.run(child, fn);
|
|
38
102
|
}
|
|
@@ -43,7 +107,7 @@ function withTags(tags, fn) {
|
|
|
43
107
|
return withContext({ tags }, fn);
|
|
44
108
|
}
|
|
45
109
|
function setDefaultTags(tags) {
|
|
46
|
-
defaultTags = normalizeTags(tags);
|
|
110
|
+
defaultTags = boundTags(normalizeTags(tags));
|
|
47
111
|
}
|
|
48
112
|
async function route(name, fn, options = {}) {
|
|
49
113
|
const parent = contextSnapshot();
|
|
@@ -51,10 +115,10 @@ async function route(name, fn, options = {}) {
|
|
|
51
115
|
...parent,
|
|
52
116
|
route: name,
|
|
53
117
|
routeSource: "explicit",
|
|
54
|
-
tags: {
|
|
118
|
+
tags: boundTags({
|
|
55
119
|
...parent.tags,
|
|
56
|
-
...
|
|
57
|
-
},
|
|
120
|
+
...normalizeTags(options.tags ?? {}),
|
|
121
|
+
}),
|
|
58
122
|
unitName: options.unit ?? parent.unitName,
|
|
59
123
|
unitCount: options.unit ? (options.unitCount ?? 1) : parent.unitCount,
|
|
60
124
|
captureText: options.captureText ?? parent.captureText,
|
|
@@ -75,6 +139,19 @@ function trace(name, fn, options = {}) {
|
|
|
75
139
|
};
|
|
76
140
|
return storage.run(child, fn);
|
|
77
141
|
}
|
|
142
|
+
function setUser(userId) {
|
|
143
|
+
const store = storage.getStore();
|
|
144
|
+
if (!store) {
|
|
145
|
+
if (!warnedUserOutsideScope) {
|
|
146
|
+
warnedUserOutsideScope = true;
|
|
147
|
+
console.warn("Metergraph setUser() requires an active Metergraph context; use withContext().");
|
|
148
|
+
}
|
|
149
|
+
return;
|
|
150
|
+
}
|
|
151
|
+
const value = user(userId);
|
|
152
|
+
if (userId === undefined || value !== undefined)
|
|
153
|
+
storage.enterWith({ ...store, userId: value, tags: { ...store.tags } });
|
|
154
|
+
}
|
|
78
155
|
function setSession(sessionId) {
|
|
79
156
|
const store = storage.getStore();
|
|
80
157
|
if (!store) {
|
|
@@ -95,5 +172,5 @@ function setTags(tags) {
|
|
|
95
172
|
}
|
|
96
173
|
return;
|
|
97
174
|
}
|
|
98
|
-
storage.enterWith({ ...store, tags: { ...store.tags, ...normalizeTags(tags) } });
|
|
175
|
+
storage.enterWith({ ...store, tags: boundTags({ ...store.tags, ...normalizeTags(tags) }) });
|
|
99
176
|
}
|
package/dist/index.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
import { route, setDefaultTags, setSession, setTags, trace, withContext, withSession, withTags, type ContextOptions, type RouteOptions, type TraceOptions } from "./context.js";
|
|
1
|
+
import { route, setDefaultTags, setSession, setUser, setTags, trace, withContext, withSession, withTags, type ContextOptions, type RouteOptions, type TraceOptions } from "./context.js";
|
|
2
2
|
import { BatchFirstIneligibleError, batchFirst, type BatchFirstMetadata, type BatchFirstPolicy, type BatchFirstProvider, type BatchFirstRequest, type BatchFirstResult, type BatchFirstSource, type LateBatchInfo } from "./batch-first.js";
|
|
3
3
|
import { track } from "./track.js";
|
|
4
4
|
import { type TransportMode, type WaitUntil } from "./transport.js";
|
|
@@ -67,7 +67,7 @@ export declare const wrapClient: typeof wrap;
|
|
|
67
67
|
*/
|
|
68
68
|
export declare function vercelAISDKMiddleware(options: MetergraphOptions & VercelAISDKMiddlewareVersionOptions): VercelAISDKMiddleware<"v2">;
|
|
69
69
|
export declare function vercelAISDKMiddleware<TVersion extends VercelAISDKSpecificationVersion = "v3">(options?: MetergraphOptions & VercelAISDKMiddlewareSpecificationOptions<TVersion>): VercelAISDKMiddleware<TVersion>;
|
|
70
|
-
export { route, setDefaultTags, setSession, setTags, trace, track, withContext, withSession, withTags, };
|
|
70
|
+
export { route, setDefaultTags, setSession, setUser, setTags, trace, track, withContext, withSession, withTags, };
|
|
71
71
|
export type { ContextOptions, RouteOptions, TraceOptions, TransportMode, VercelAISDKMiddleware, VercelAISDKSpecificationVersion, WrapOptions, };
|
|
72
72
|
/**
|
|
73
73
|
* Explicit, opt-in batch-first execution over a provider's Batch API —
|
package/dist/index.js
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
"use strict";
|
|
2
2
|
Object.defineProperty(exports, "__esModule", { value: true });
|
|
3
|
-
exports.BatchFirstIneligibleError = exports.batchFirst = exports.withTags = exports.withSession = exports.withContext = exports.track = exports.trace = exports.setTags = exports.setSession = exports.setDefaultTags = exports.route = exports.wrapClient = exports.DEFAULT_INGEST_URL = void 0;
|
|
3
|
+
exports.BatchFirstIneligibleError = exports.batchFirst = exports.withTags = exports.withSession = exports.withContext = exports.track = exports.trace = exports.setTags = exports.setUser = exports.setSession = exports.setDefaultTags = exports.route = exports.wrapClient = exports.DEFAULT_INGEST_URL = void 0;
|
|
4
4
|
exports.init = init;
|
|
5
5
|
exports.modelFor = modelFor;
|
|
6
6
|
exports.recordOutcome = recordOutcome;
|
|
@@ -16,6 +16,7 @@ const context_js_1 = require("./context.js");
|
|
|
16
16
|
Object.defineProperty(exports, "route", { enumerable: true, get: function () { return context_js_1.route; } });
|
|
17
17
|
Object.defineProperty(exports, "setDefaultTags", { enumerable: true, get: function () { return context_js_1.setDefaultTags; } });
|
|
18
18
|
Object.defineProperty(exports, "setSession", { enumerable: true, get: function () { return context_js_1.setSession; } });
|
|
19
|
+
Object.defineProperty(exports, "setUser", { enumerable: true, get: function () { return context_js_1.setUser; } });
|
|
19
20
|
Object.defineProperty(exports, "setTags", { enumerable: true, get: function () { return context_js_1.setTags; } });
|
|
20
21
|
Object.defineProperty(exports, "trace", { enumerable: true, get: function () { return context_js_1.trace; } });
|
|
21
22
|
Object.defineProperty(exports, "withContext", { enumerable: true, get: function () { return context_js_1.withContext; } });
|
package/dist/index.mjs
CHANGED
package/dist/version.d.ts
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
export declare const SDK_VERSION = "0.6.
|
|
1
|
+
export declare const SDK_VERSION = "0.6.18";
|
package/dist/version.js
CHANGED
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "metergraph",
|
|
3
|
-
"version": "0.6.
|
|
3
|
+
"version": "0.6.18",
|
|
4
4
|
"description": "Zero-dependency TypeScript SDK for function-level LLM cost attribution across major LLM providers and frameworks, including OpenAI, Anthropic, Gemini, and Vercel AI SDK.",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|