@withgateway/sdk 0.1.12 → 0.1.14
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 +115 -0
- package/dist/cli.d.mts +1 -0
- package/dist/cli.d.ts +1 -0
- package/dist/cli.js +1303 -0
- package/dist/cli.js.map +1 -0
- package/dist/cli.mjs +1290 -0
- package/dist/cli.mjs.map +1 -0
- package/dist/{index-CTc8iOrx.d.ts → index-B5HUQQDE.d.mts} +9 -0
- package/dist/{index-CTc8iOrx.d.mts → index-Dpo-t8iO.d.ts} +9 -0
- package/dist/index.d.mts +4 -2
- package/dist/index.d.ts +4 -2
- package/dist/index.js +878 -32
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +845 -25
- package/dist/index.mjs.map +1 -1
- package/dist/scores/index.d.mts +165 -0
- package/dist/scores/index.d.ts +165 -0
- package/dist/scores/index.js +252 -0
- package/dist/scores/index.js.map +1 -0
- package/dist/scores/index.mjs +223 -0
- package/dist/scores/index.mjs.map +1 -0
- package/dist/tracing/index.d.mts +2 -1
- package/dist/tracing/index.d.ts +2 -1
- package/dist/tracing/index.js +262 -15
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +256 -9
- package/dist/tracing/index.mjs.map +1 -1
- package/dist/worlds/index.d.mts +377 -0
- package/dist/worlds/index.d.ts +377 -0
- package/dist/worlds/index.js +584 -0
- package/dist/worlds/index.js.map +1 -0
- package/dist/worlds/index.mjs +578 -0
- package/dist/worlds/index.mjs.map +1 -0
- package/package.json +32 -2
package/dist/tracing/index.mjs
CHANGED
|
@@ -16,7 +16,7 @@ var require_package = __commonJS({
|
|
|
16
16
|
"package.json"(exports, module) {
|
|
17
17
|
module.exports = {
|
|
18
18
|
name: "@withgateway/sdk",
|
|
19
|
-
version: "0.1.
|
|
19
|
+
version: "0.1.14",
|
|
20
20
|
description: "Gateway SDK for TypeScript - A/B experiments, tracing, and observability",
|
|
21
21
|
main: "./dist/index.js",
|
|
22
22
|
module: "./dist/index.mjs",
|
|
@@ -71,6 +71,16 @@ var require_package = __commonJS({
|
|
|
71
71
|
types: "./dist/users/index.d.ts",
|
|
72
72
|
import: "./dist/users/index.mjs",
|
|
73
73
|
require: "./dist/users/index.js"
|
|
74
|
+
},
|
|
75
|
+
"./scores": {
|
|
76
|
+
types: "./dist/scores/index.d.ts",
|
|
77
|
+
import: "./dist/scores/index.mjs",
|
|
78
|
+
require: "./dist/scores/index.js"
|
|
79
|
+
},
|
|
80
|
+
"./worlds": {
|
|
81
|
+
types: "./dist/worlds/index.d.ts",
|
|
82
|
+
import: "./dist/worlds/index.mjs",
|
|
83
|
+
require: "./dist/worlds/index.js"
|
|
74
84
|
}
|
|
75
85
|
},
|
|
76
86
|
files: [
|
|
@@ -84,6 +94,7 @@ var require_package = __commonJS({
|
|
|
84
94
|
build: "tsup",
|
|
85
95
|
dev: "tsup --watch",
|
|
86
96
|
typecheck: "tsc --noEmit",
|
|
97
|
+
"typecheck:examples": "tsc -p tsconfig.examples.json --noEmit",
|
|
87
98
|
test: "vitest",
|
|
88
99
|
"test:run": "vitest run",
|
|
89
100
|
lint: "eslint src --ext .ts",
|
|
@@ -144,10 +155,29 @@ var require_package = __commonJS({
|
|
|
144
155
|
"@opentelemetry/sdk-trace-node": "^2.6.0",
|
|
145
156
|
"@opentelemetry/semantic-conventions": "^1.40.0",
|
|
146
157
|
"@types/node": "^20.0.0",
|
|
158
|
+
openai: "^4.70.0",
|
|
147
159
|
tsup: "^8.0.0",
|
|
148
160
|
tsx: "^4.0.0",
|
|
149
161
|
typescript: "^5.0.0",
|
|
150
|
-
vitest: "^2.
|
|
162
|
+
vitest: "^3.2.6"
|
|
163
|
+
},
|
|
164
|
+
overrides: {
|
|
165
|
+
protobufjs: "^8.4.1",
|
|
166
|
+
"vite@6": "^6.4.3",
|
|
167
|
+
postcss: "^8.5.18",
|
|
168
|
+
"picomatch@4": "^4.0.4"
|
|
169
|
+
},
|
|
170
|
+
pnpm: {
|
|
171
|
+
overrides: {
|
|
172
|
+
protobufjs: "^8.4.1",
|
|
173
|
+
vitest: "^3.2.6",
|
|
174
|
+
"vite@6": "^6.4.3",
|
|
175
|
+
postcss: "^8.5.18",
|
|
176
|
+
"picomatch@4": "^4.0.4"
|
|
177
|
+
}
|
|
178
|
+
},
|
|
179
|
+
bin: {
|
|
180
|
+
gateway: "./dist/cli.js"
|
|
151
181
|
}
|
|
152
182
|
};
|
|
153
183
|
}
|
|
@@ -420,6 +450,216 @@ function debugLog(message, ...args) {
|
|
|
420
450
|
}
|
|
421
451
|
}
|
|
422
452
|
|
|
453
|
+
// src/scores/index.ts
|
|
454
|
+
import { isSpanContextValid as isSpanContextValid2, trace as trace2 } from "@opentelemetry/api";
|
|
455
|
+
var SUCCESS_SIGNAL_KEY = "gateway.success.signal";
|
|
456
|
+
var SUCCESS_METRIC_NAME_KEY = "gateway.success.metricName";
|
|
457
|
+
var AGENT_ID_KEY = "gateway.agent.id";
|
|
458
|
+
var ScoreError = class extends Error {
|
|
459
|
+
constructor(message, options) {
|
|
460
|
+
super(message);
|
|
461
|
+
this.name = "ScoreError";
|
|
462
|
+
this.cause = options?.cause;
|
|
463
|
+
}
|
|
464
|
+
};
|
|
465
|
+
function currentTraceId() {
|
|
466
|
+
try {
|
|
467
|
+
const span = trace2.getActiveSpan();
|
|
468
|
+
if (!span) return void 0;
|
|
469
|
+
const ctx = span.spanContext();
|
|
470
|
+
if (!ctx || !isSpanContextValid2(ctx)) return void 0;
|
|
471
|
+
return ctx.traceId;
|
|
472
|
+
} catch {
|
|
473
|
+
return void 0;
|
|
474
|
+
}
|
|
475
|
+
}
|
|
476
|
+
var ScoresClient = class _ScoresClient {
|
|
477
|
+
host;
|
|
478
|
+
publicKey;
|
|
479
|
+
secretKey;
|
|
480
|
+
timeoutSeconds;
|
|
481
|
+
debug;
|
|
482
|
+
constructor(config) {
|
|
483
|
+
this.host = config.host.replace(/\/$/, "");
|
|
484
|
+
this.publicKey = config.publicKey;
|
|
485
|
+
this.secretKey = config.secretKey;
|
|
486
|
+
this.timeoutSeconds = config.timeoutSeconds ?? 15;
|
|
487
|
+
this.debug = config.debug ?? false;
|
|
488
|
+
}
|
|
489
|
+
/** Create a client from GATEWAY_HOST / GATEWAY_PUBLIC_KEY / GATEWAY_SECRET_KEY. */
|
|
490
|
+
static fromEnv(config = {}) {
|
|
491
|
+
const host = config.host ?? process.env.GATEWAY_HOST;
|
|
492
|
+
const publicKey = config.publicKey ?? process.env.GATEWAY_PUBLIC_KEY;
|
|
493
|
+
const secretKey = config.secretKey ?? process.env.GATEWAY_SECRET_KEY;
|
|
494
|
+
const missing = [
|
|
495
|
+
["host", host],
|
|
496
|
+
["publicKey", publicKey],
|
|
497
|
+
["secretKey", secretKey]
|
|
498
|
+
].filter(([, value]) => !value).map(([name]) => name);
|
|
499
|
+
if (missing.length > 0) {
|
|
500
|
+
throw new ScoreError(
|
|
501
|
+
`Missing Gateway scores configuration: ${missing.join(", ")}`
|
|
502
|
+
);
|
|
503
|
+
}
|
|
504
|
+
return new _ScoresClient({
|
|
505
|
+
...config,
|
|
506
|
+
host,
|
|
507
|
+
publicKey,
|
|
508
|
+
secretKey
|
|
509
|
+
});
|
|
510
|
+
}
|
|
511
|
+
/**
|
|
512
|
+
* Post a score, throwing {@link ScoreError} on any failure. Builds the exact
|
|
513
|
+
* `POST /api/public/scores` body the Python SDK sends: exactly one of
|
|
514
|
+
* `sessionId` / `traceId` (+ optional `observationId`) / `datasetRunId`.
|
|
515
|
+
* When no target is provided, the active OTel trace id is used; if none is
|
|
516
|
+
* available the call is a no-op (returns without posting), matching Python.
|
|
517
|
+
*/
|
|
518
|
+
async postScore(name, value, options = {}) {
|
|
519
|
+
const body = this.buildScoreBody(name, value, options);
|
|
520
|
+
if (!body) {
|
|
521
|
+
this.log(
|
|
522
|
+
"score '%s' dropped: no sessionId, traceId or datasetRunId available",
|
|
523
|
+
name
|
|
524
|
+
);
|
|
525
|
+
return;
|
|
526
|
+
}
|
|
527
|
+
await this.request("POST", "/api/public/scores", body);
|
|
528
|
+
}
|
|
529
|
+
/**
|
|
530
|
+
* Build the score request body, or null when no target can be resolved.
|
|
531
|
+
* Split out so it is unit-testable and shared by score()/success().
|
|
532
|
+
*/
|
|
533
|
+
buildScoreBody(name, value, options = {}) {
|
|
534
|
+
const traceId = options.traceId ?? currentTraceId();
|
|
535
|
+
const target = {};
|
|
536
|
+
if (options.sessionId) {
|
|
537
|
+
target.sessionId = options.sessionId;
|
|
538
|
+
} else if (options.datasetRunId) {
|
|
539
|
+
target.datasetRunId = options.datasetRunId;
|
|
540
|
+
} else if (traceId) {
|
|
541
|
+
target.traceId = traceId;
|
|
542
|
+
if (options.observationId) target.observationId = options.observationId;
|
|
543
|
+
} else {
|
|
544
|
+
return null;
|
|
545
|
+
}
|
|
546
|
+
const metadata = {
|
|
547
|
+
source: "gatewaysdk",
|
|
548
|
+
...options.metadata ?? {}
|
|
549
|
+
};
|
|
550
|
+
return {
|
|
551
|
+
name,
|
|
552
|
+
value,
|
|
553
|
+
dataType: options.dataType ?? "NUMERIC",
|
|
554
|
+
environment: options.environment ?? "default",
|
|
555
|
+
...options.comment ? { comment: options.comment } : {},
|
|
556
|
+
metadata,
|
|
557
|
+
...target
|
|
558
|
+
};
|
|
559
|
+
}
|
|
560
|
+
/**
|
|
561
|
+
* Post a score, FAIL-SOFT: warns and resolves on any failure so a broken
|
|
562
|
+
* transport never throws into (or rejects out of) the caller.
|
|
563
|
+
*/
|
|
564
|
+
async score(name, value, options = {}) {
|
|
565
|
+
try {
|
|
566
|
+
await this.postScore(name, value, options);
|
|
567
|
+
} catch (error) {
|
|
568
|
+
this.warn(`score '${name}' failed`, error);
|
|
569
|
+
}
|
|
570
|
+
}
|
|
571
|
+
/**
|
|
572
|
+
* Emit a SUCCESS SIGNAL that feeds a Gateway Success Metric — a score tagged
|
|
573
|
+
* with `gateway.success.signal` + `gateway.success.metricName` (and the agent
|
|
574
|
+
* identity when `agentId` is set). A boolean `value` records a 1/0 BOOLEAN
|
|
575
|
+
* score (pass/fail); a number records a NUMERIC score. FAIL-SOFT.
|
|
576
|
+
*
|
|
577
|
+
* The metadata shape matches the Python SDK's `Run.success()` exactly, so the
|
|
578
|
+
* platform's Success Metrics aggregation counts signals from either SDK
|
|
579
|
+
* without change.
|
|
580
|
+
*
|
|
581
|
+
* @example
|
|
582
|
+
* ```ts
|
|
583
|
+
* await scores.success("resolved_ticket", true, { agentId: "support-triage", sessionId });
|
|
584
|
+
* await scores.success("handle_time_s", 42, { agentId: "support-triage", sessionId });
|
|
585
|
+
* ```
|
|
586
|
+
*/
|
|
587
|
+
async success(name, value = true, options = {}) {
|
|
588
|
+
const { numericValue, inferredType } = coerceSignalValue(value);
|
|
589
|
+
const { agentId, metricName, metadata, dataType, ...rest } = options;
|
|
590
|
+
const signalMetadata = {
|
|
591
|
+
...metadata ?? {},
|
|
592
|
+
[SUCCESS_SIGNAL_KEY]: true,
|
|
593
|
+
[SUCCESS_METRIC_NAME_KEY]: metricName ?? name,
|
|
594
|
+
...agentId ? { [AGENT_ID_KEY]: agentId } : {}
|
|
595
|
+
};
|
|
596
|
+
await this.score(name, numericValue, {
|
|
597
|
+
...rest,
|
|
598
|
+
dataType: dataType ?? inferredType,
|
|
599
|
+
metadata: signalMetadata
|
|
600
|
+
});
|
|
601
|
+
}
|
|
602
|
+
async request(method, path, payload) {
|
|
603
|
+
let response;
|
|
604
|
+
try {
|
|
605
|
+
response = await fetch(`${this.host}${path}`, {
|
|
606
|
+
method,
|
|
607
|
+
headers: {
|
|
608
|
+
Authorization: this.authHeader(),
|
|
609
|
+
"Content-Type": "application/json"
|
|
610
|
+
},
|
|
611
|
+
body: JSON.stringify(payload),
|
|
612
|
+
signal: AbortSignal.timeout(this.timeoutSeconds * 1e3)
|
|
613
|
+
});
|
|
614
|
+
} catch (error) {
|
|
615
|
+
throw new ScoreError(
|
|
616
|
+
`${method} ${path} failed: ${error instanceof Error ? error.message : String(error)}`,
|
|
617
|
+
{ cause: error }
|
|
618
|
+
);
|
|
619
|
+
}
|
|
620
|
+
const text = await response.text();
|
|
621
|
+
if (!response.ok) {
|
|
622
|
+
throw new ScoreError(
|
|
623
|
+
`${method} ${path} failed (${response.status}): ${text.slice(0, 500)}`
|
|
624
|
+
);
|
|
625
|
+
}
|
|
626
|
+
this.log("%s %s -> %s", method, path, response.status);
|
|
627
|
+
}
|
|
628
|
+
authHeader() {
|
|
629
|
+
return `Basic ${Buffer.from(`${this.publicKey}:${this.secretKey}`).toString(
|
|
630
|
+
"base64"
|
|
631
|
+
)}`;
|
|
632
|
+
}
|
|
633
|
+
log(message, ...args) {
|
|
634
|
+
if (this.debug) {
|
|
635
|
+
console.log(`[gateway.scores] ${message}`, ...args);
|
|
636
|
+
}
|
|
637
|
+
}
|
|
638
|
+
warn(message, ...args) {
|
|
639
|
+
console.warn(`[gateway.scores] ${message}`, ...args);
|
|
640
|
+
}
|
|
641
|
+
};
|
|
642
|
+
function coerceSignalValue(value) {
|
|
643
|
+
if (typeof value === "boolean") {
|
|
644
|
+
return { numericValue: value ? 1 : 0, inferredType: "BOOLEAN" };
|
|
645
|
+
}
|
|
646
|
+
return { numericValue: value, inferredType: "NUMERIC" };
|
|
647
|
+
}
|
|
648
|
+
async function success(name, value = true, options = {}) {
|
|
649
|
+
let client;
|
|
650
|
+
try {
|
|
651
|
+
client = ScoresClient.fromEnv();
|
|
652
|
+
} catch (error) {
|
|
653
|
+
console.warn(`[gateway.scores] success '${name}' skipped`, error);
|
|
654
|
+
return;
|
|
655
|
+
}
|
|
656
|
+
await client.success(name, value, options);
|
|
657
|
+
}
|
|
658
|
+
var scores = {
|
|
659
|
+
fromEnv: ScoresClient.fromEnv,
|
|
660
|
+
success
|
|
661
|
+
};
|
|
662
|
+
|
|
423
663
|
// src/build/index.ts
|
|
424
664
|
import { createHash } from "crypto";
|
|
425
665
|
function canonicalJson(value) {
|
|
@@ -824,12 +1064,19 @@ function initIsolated(config = {}) {
|
|
|
824
1064
|
const provider = built.provider;
|
|
825
1065
|
scheduleBuildRegistration(config, built);
|
|
826
1066
|
const tracer = provider.getTracer("@withgateway/sdk");
|
|
1067
|
+
const scores2 = new ScoresClient({
|
|
1068
|
+
host: built.connection.host,
|
|
1069
|
+
publicKey: built.connection.publicKey,
|
|
1070
|
+
secretKey: built.connection.secretKey,
|
|
1071
|
+
debug: config.debug ?? false
|
|
1072
|
+
});
|
|
827
1073
|
debugLog2(
|
|
828
1074
|
"Isolated tracing provider created (service=%s)",
|
|
829
1075
|
config.serviceName ?? "gatewaysdk-tracing"
|
|
830
1076
|
);
|
|
831
1077
|
return {
|
|
832
1078
|
tracer,
|
|
1079
|
+
scores: scores2,
|
|
833
1080
|
async flush() {
|
|
834
1081
|
try {
|
|
835
1082
|
await provider.forceFlush();
|
|
@@ -883,12 +1130,12 @@ function isGatewayConfigured() {
|
|
|
883
1130
|
}
|
|
884
1131
|
|
|
885
1132
|
// src/tracing/observe.ts
|
|
886
|
-
import { trace as
|
|
1133
|
+
import { trace as trace3, context, SpanStatusCode } from "@opentelemetry/api";
|
|
887
1134
|
function asAttr(value) {
|
|
888
1135
|
return typeof value === "string" ? value : JSON.stringify(value);
|
|
889
1136
|
}
|
|
890
1137
|
async function observe(name, fn, options = {}) {
|
|
891
|
-
const tracer = options.tracer ??
|
|
1138
|
+
const tracer = options.tracer ?? trace3.getTracer("@withgateway/sdk");
|
|
892
1139
|
const span = tracer.startSpan(name, {
|
|
893
1140
|
attributes: {
|
|
894
1141
|
"openinference.span.kind": options.kind ?? "AGENT",
|
|
@@ -898,7 +1145,7 @@ async function observe(name, fn, options = {}) {
|
|
|
898
1145
|
});
|
|
899
1146
|
try {
|
|
900
1147
|
const result = await context.with(
|
|
901
|
-
|
|
1148
|
+
trace3.setSpan(context.active(), span),
|
|
902
1149
|
fn
|
|
903
1150
|
);
|
|
904
1151
|
if (options.captureOutput !== false && result !== void 0) {
|
|
@@ -956,7 +1203,7 @@ function observeAnthropic(client) {
|
|
|
956
1203
|
|
|
957
1204
|
// src/tracing/claude.ts
|
|
958
1205
|
import {
|
|
959
|
-
trace as
|
|
1206
|
+
trace as trace4,
|
|
960
1207
|
context as context2,
|
|
961
1208
|
SpanStatusCode as SpanStatusCode2
|
|
962
1209
|
} from "@opentelemetry/api";
|
|
@@ -973,7 +1220,7 @@ function toolResultText(content) {
|
|
|
973
1220
|
}
|
|
974
1221
|
var TURN_INPUT_MAX = 4e3;
|
|
975
1222
|
async function* observeClaude(stream, options) {
|
|
976
|
-
const tracer = options.tracer ??
|
|
1223
|
+
const tracer = options.tracer ?? trace4.getTracer("@withgateway/sdk");
|
|
977
1224
|
const model = options.model ?? "claude";
|
|
978
1225
|
const openTools = /* @__PURE__ */ new Map();
|
|
979
1226
|
let root = null;
|
|
@@ -986,7 +1233,7 @@ async function* observeClaude(stream, options) {
|
|
|
986
1233
|
...options.attributes ?? {}
|
|
987
1234
|
}
|
|
988
1235
|
});
|
|
989
|
-
rootCtx =
|
|
1236
|
+
rootCtx = trace4.setSpan(context2.active(), root);
|
|
990
1237
|
}
|
|
991
1238
|
let turnRoot = null;
|
|
992
1239
|
let turnCtx = null;
|
|
@@ -1019,7 +1266,7 @@ async function* observeClaude(stream, options) {
|
|
|
1019
1266
|
...options.attributes ?? {}
|
|
1020
1267
|
}
|
|
1021
1268
|
});
|
|
1022
|
-
turnCtx =
|
|
1269
|
+
turnCtx = trace4.setSpan(context2.active(), turnRoot);
|
|
1023
1270
|
pendingTurnInput = "";
|
|
1024
1271
|
}
|
|
1025
1272
|
const childCtx = options.perTurn ? turnCtx : rootCtx;
|