@withgateway/sdk 0.1.12 → 0.1.13
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 +37 -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 +3 -2
- package/dist/index.d.ts +3 -2
- package/dist/index.js +267 -29
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +253 -23
- 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 +236 -14
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +230 -8
- package/dist/tracing/index.mjs.map +1 -1
- package/package.json +6 -1
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.13",
|
|
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,11 @@ 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"
|
|
74
79
|
}
|
|
75
80
|
},
|
|
76
81
|
files: [
|
|
@@ -420,6 +425,216 @@ function debugLog(message, ...args) {
|
|
|
420
425
|
}
|
|
421
426
|
}
|
|
422
427
|
|
|
428
|
+
// src/scores/index.ts
|
|
429
|
+
import { isSpanContextValid as isSpanContextValid2, trace as trace2 } from "@opentelemetry/api";
|
|
430
|
+
var SUCCESS_SIGNAL_KEY = "gateway.success.signal";
|
|
431
|
+
var SUCCESS_METRIC_NAME_KEY = "gateway.success.metricName";
|
|
432
|
+
var AGENT_ID_KEY = "gateway.agent.id";
|
|
433
|
+
var ScoreError = class extends Error {
|
|
434
|
+
constructor(message, options) {
|
|
435
|
+
super(message);
|
|
436
|
+
this.name = "ScoreError";
|
|
437
|
+
this.cause = options?.cause;
|
|
438
|
+
}
|
|
439
|
+
};
|
|
440
|
+
function currentTraceId() {
|
|
441
|
+
try {
|
|
442
|
+
const span = trace2.getActiveSpan();
|
|
443
|
+
if (!span) return void 0;
|
|
444
|
+
const ctx = span.spanContext();
|
|
445
|
+
if (!ctx || !isSpanContextValid2(ctx)) return void 0;
|
|
446
|
+
return ctx.traceId;
|
|
447
|
+
} catch {
|
|
448
|
+
return void 0;
|
|
449
|
+
}
|
|
450
|
+
}
|
|
451
|
+
var ScoresClient = class _ScoresClient {
|
|
452
|
+
host;
|
|
453
|
+
publicKey;
|
|
454
|
+
secretKey;
|
|
455
|
+
timeoutSeconds;
|
|
456
|
+
debug;
|
|
457
|
+
constructor(config) {
|
|
458
|
+
this.host = config.host.replace(/\/$/, "");
|
|
459
|
+
this.publicKey = config.publicKey;
|
|
460
|
+
this.secretKey = config.secretKey;
|
|
461
|
+
this.timeoutSeconds = config.timeoutSeconds ?? 15;
|
|
462
|
+
this.debug = config.debug ?? false;
|
|
463
|
+
}
|
|
464
|
+
/** Create a client from GATEWAY_HOST / GATEWAY_PUBLIC_KEY / GATEWAY_SECRET_KEY. */
|
|
465
|
+
static fromEnv(config = {}) {
|
|
466
|
+
const host = config.host ?? process.env.GATEWAY_HOST;
|
|
467
|
+
const publicKey = config.publicKey ?? process.env.GATEWAY_PUBLIC_KEY;
|
|
468
|
+
const secretKey = config.secretKey ?? process.env.GATEWAY_SECRET_KEY;
|
|
469
|
+
const missing = [
|
|
470
|
+
["host", host],
|
|
471
|
+
["publicKey", publicKey],
|
|
472
|
+
["secretKey", secretKey]
|
|
473
|
+
].filter(([, value]) => !value).map(([name]) => name);
|
|
474
|
+
if (missing.length > 0) {
|
|
475
|
+
throw new ScoreError(
|
|
476
|
+
`Missing Gateway scores configuration: ${missing.join(", ")}`
|
|
477
|
+
);
|
|
478
|
+
}
|
|
479
|
+
return new _ScoresClient({
|
|
480
|
+
...config,
|
|
481
|
+
host,
|
|
482
|
+
publicKey,
|
|
483
|
+
secretKey
|
|
484
|
+
});
|
|
485
|
+
}
|
|
486
|
+
/**
|
|
487
|
+
* Post a score, throwing {@link ScoreError} on any failure. Builds the exact
|
|
488
|
+
* `POST /api/public/scores` body the Python SDK sends: exactly one of
|
|
489
|
+
* `sessionId` / `traceId` (+ optional `observationId`) / `datasetRunId`.
|
|
490
|
+
* When no target is provided, the active OTel trace id is used; if none is
|
|
491
|
+
* available the call is a no-op (returns without posting), matching Python.
|
|
492
|
+
*/
|
|
493
|
+
async postScore(name, value, options = {}) {
|
|
494
|
+
const body = this.buildScoreBody(name, value, options);
|
|
495
|
+
if (!body) {
|
|
496
|
+
this.log(
|
|
497
|
+
"score '%s' dropped: no sessionId, traceId or datasetRunId available",
|
|
498
|
+
name
|
|
499
|
+
);
|
|
500
|
+
return;
|
|
501
|
+
}
|
|
502
|
+
await this.request("POST", "/api/public/scores", body);
|
|
503
|
+
}
|
|
504
|
+
/**
|
|
505
|
+
* Build the score request body, or null when no target can be resolved.
|
|
506
|
+
* Split out so it is unit-testable and shared by score()/success().
|
|
507
|
+
*/
|
|
508
|
+
buildScoreBody(name, value, options = {}) {
|
|
509
|
+
const traceId = options.traceId ?? currentTraceId();
|
|
510
|
+
const target = {};
|
|
511
|
+
if (options.sessionId) {
|
|
512
|
+
target.sessionId = options.sessionId;
|
|
513
|
+
} else if (options.datasetRunId) {
|
|
514
|
+
target.datasetRunId = options.datasetRunId;
|
|
515
|
+
} else if (traceId) {
|
|
516
|
+
target.traceId = traceId;
|
|
517
|
+
if (options.observationId) target.observationId = options.observationId;
|
|
518
|
+
} else {
|
|
519
|
+
return null;
|
|
520
|
+
}
|
|
521
|
+
const metadata = {
|
|
522
|
+
source: "gatewaysdk",
|
|
523
|
+
...options.metadata ?? {}
|
|
524
|
+
};
|
|
525
|
+
return {
|
|
526
|
+
name,
|
|
527
|
+
value,
|
|
528
|
+
dataType: options.dataType ?? "NUMERIC",
|
|
529
|
+
environment: options.environment ?? "default",
|
|
530
|
+
...options.comment ? { comment: options.comment } : {},
|
|
531
|
+
metadata,
|
|
532
|
+
...target
|
|
533
|
+
};
|
|
534
|
+
}
|
|
535
|
+
/**
|
|
536
|
+
* Post a score, FAIL-SOFT: warns and resolves on any failure so a broken
|
|
537
|
+
* transport never throws into (or rejects out of) the caller.
|
|
538
|
+
*/
|
|
539
|
+
async score(name, value, options = {}) {
|
|
540
|
+
try {
|
|
541
|
+
await this.postScore(name, value, options);
|
|
542
|
+
} catch (error) {
|
|
543
|
+
this.warn(`score '${name}' failed`, error);
|
|
544
|
+
}
|
|
545
|
+
}
|
|
546
|
+
/**
|
|
547
|
+
* Emit a SUCCESS SIGNAL that feeds a Gateway Success Metric — a score tagged
|
|
548
|
+
* with `gateway.success.signal` + `gateway.success.metricName` (and the agent
|
|
549
|
+
* identity when `agentId` is set). A boolean `value` records a 1/0 BOOLEAN
|
|
550
|
+
* score (pass/fail); a number records a NUMERIC score. FAIL-SOFT.
|
|
551
|
+
*
|
|
552
|
+
* The metadata shape matches the Python SDK's `Run.success()` exactly, so the
|
|
553
|
+
* platform's Success Metrics aggregation counts signals from either SDK
|
|
554
|
+
* without change.
|
|
555
|
+
*
|
|
556
|
+
* @example
|
|
557
|
+
* ```ts
|
|
558
|
+
* await scores.success("resolved_ticket", true, { agentId: "support-triage", sessionId });
|
|
559
|
+
* await scores.success("handle_time_s", 42, { agentId: "support-triage", sessionId });
|
|
560
|
+
* ```
|
|
561
|
+
*/
|
|
562
|
+
async success(name, value = true, options = {}) {
|
|
563
|
+
const { numericValue, inferredType } = coerceSignalValue(value);
|
|
564
|
+
const { agentId, metricName, metadata, dataType, ...rest } = options;
|
|
565
|
+
const signalMetadata = {
|
|
566
|
+
...metadata ?? {},
|
|
567
|
+
[SUCCESS_SIGNAL_KEY]: true,
|
|
568
|
+
[SUCCESS_METRIC_NAME_KEY]: metricName ?? name,
|
|
569
|
+
...agentId ? { [AGENT_ID_KEY]: agentId } : {}
|
|
570
|
+
};
|
|
571
|
+
await this.score(name, numericValue, {
|
|
572
|
+
...rest,
|
|
573
|
+
dataType: dataType ?? inferredType,
|
|
574
|
+
metadata: signalMetadata
|
|
575
|
+
});
|
|
576
|
+
}
|
|
577
|
+
async request(method, path, payload) {
|
|
578
|
+
let response;
|
|
579
|
+
try {
|
|
580
|
+
response = await fetch(`${this.host}${path}`, {
|
|
581
|
+
method,
|
|
582
|
+
headers: {
|
|
583
|
+
Authorization: this.authHeader(),
|
|
584
|
+
"Content-Type": "application/json"
|
|
585
|
+
},
|
|
586
|
+
body: JSON.stringify(payload),
|
|
587
|
+
signal: AbortSignal.timeout(this.timeoutSeconds * 1e3)
|
|
588
|
+
});
|
|
589
|
+
} catch (error) {
|
|
590
|
+
throw new ScoreError(
|
|
591
|
+
`${method} ${path} failed: ${error instanceof Error ? error.message : String(error)}`,
|
|
592
|
+
{ cause: error }
|
|
593
|
+
);
|
|
594
|
+
}
|
|
595
|
+
const text = await response.text();
|
|
596
|
+
if (!response.ok) {
|
|
597
|
+
throw new ScoreError(
|
|
598
|
+
`${method} ${path} failed (${response.status}): ${text.slice(0, 500)}`
|
|
599
|
+
);
|
|
600
|
+
}
|
|
601
|
+
this.log("%s %s -> %s", method, path, response.status);
|
|
602
|
+
}
|
|
603
|
+
authHeader() {
|
|
604
|
+
return `Basic ${Buffer.from(`${this.publicKey}:${this.secretKey}`).toString(
|
|
605
|
+
"base64"
|
|
606
|
+
)}`;
|
|
607
|
+
}
|
|
608
|
+
log(message, ...args) {
|
|
609
|
+
if (this.debug) {
|
|
610
|
+
console.log(`[gateway.scores] ${message}`, ...args);
|
|
611
|
+
}
|
|
612
|
+
}
|
|
613
|
+
warn(message, ...args) {
|
|
614
|
+
console.warn(`[gateway.scores] ${message}`, ...args);
|
|
615
|
+
}
|
|
616
|
+
};
|
|
617
|
+
function coerceSignalValue(value) {
|
|
618
|
+
if (typeof value === "boolean") {
|
|
619
|
+
return { numericValue: value ? 1 : 0, inferredType: "BOOLEAN" };
|
|
620
|
+
}
|
|
621
|
+
return { numericValue: value, inferredType: "NUMERIC" };
|
|
622
|
+
}
|
|
623
|
+
async function success(name, value = true, options = {}) {
|
|
624
|
+
let client;
|
|
625
|
+
try {
|
|
626
|
+
client = ScoresClient.fromEnv();
|
|
627
|
+
} catch (error) {
|
|
628
|
+
console.warn(`[gateway.scores] success '${name}' skipped`, error);
|
|
629
|
+
return;
|
|
630
|
+
}
|
|
631
|
+
await client.success(name, value, options);
|
|
632
|
+
}
|
|
633
|
+
var scores = {
|
|
634
|
+
fromEnv: ScoresClient.fromEnv,
|
|
635
|
+
success
|
|
636
|
+
};
|
|
637
|
+
|
|
423
638
|
// src/build/index.ts
|
|
424
639
|
import { createHash } from "crypto";
|
|
425
640
|
function canonicalJson(value) {
|
|
@@ -824,12 +1039,19 @@ function initIsolated(config = {}) {
|
|
|
824
1039
|
const provider = built.provider;
|
|
825
1040
|
scheduleBuildRegistration(config, built);
|
|
826
1041
|
const tracer = provider.getTracer("@withgateway/sdk");
|
|
1042
|
+
const scores2 = new ScoresClient({
|
|
1043
|
+
host: built.connection.host,
|
|
1044
|
+
publicKey: built.connection.publicKey,
|
|
1045
|
+
secretKey: built.connection.secretKey,
|
|
1046
|
+
debug: config.debug ?? false
|
|
1047
|
+
});
|
|
827
1048
|
debugLog2(
|
|
828
1049
|
"Isolated tracing provider created (service=%s)",
|
|
829
1050
|
config.serviceName ?? "gatewaysdk-tracing"
|
|
830
1051
|
);
|
|
831
1052
|
return {
|
|
832
1053
|
tracer,
|
|
1054
|
+
scores: scores2,
|
|
833
1055
|
async flush() {
|
|
834
1056
|
try {
|
|
835
1057
|
await provider.forceFlush();
|
|
@@ -883,12 +1105,12 @@ function isGatewayConfigured() {
|
|
|
883
1105
|
}
|
|
884
1106
|
|
|
885
1107
|
// src/tracing/observe.ts
|
|
886
|
-
import { trace as
|
|
1108
|
+
import { trace as trace3, context, SpanStatusCode } from "@opentelemetry/api";
|
|
887
1109
|
function asAttr(value) {
|
|
888
1110
|
return typeof value === "string" ? value : JSON.stringify(value);
|
|
889
1111
|
}
|
|
890
1112
|
async function observe(name, fn, options = {}) {
|
|
891
|
-
const tracer = options.tracer ??
|
|
1113
|
+
const tracer = options.tracer ?? trace3.getTracer("@withgateway/sdk");
|
|
892
1114
|
const span = tracer.startSpan(name, {
|
|
893
1115
|
attributes: {
|
|
894
1116
|
"openinference.span.kind": options.kind ?? "AGENT",
|
|
@@ -898,7 +1120,7 @@ async function observe(name, fn, options = {}) {
|
|
|
898
1120
|
});
|
|
899
1121
|
try {
|
|
900
1122
|
const result = await context.with(
|
|
901
|
-
|
|
1123
|
+
trace3.setSpan(context.active(), span),
|
|
902
1124
|
fn
|
|
903
1125
|
);
|
|
904
1126
|
if (options.captureOutput !== false && result !== void 0) {
|
|
@@ -956,7 +1178,7 @@ function observeAnthropic(client) {
|
|
|
956
1178
|
|
|
957
1179
|
// src/tracing/claude.ts
|
|
958
1180
|
import {
|
|
959
|
-
trace as
|
|
1181
|
+
trace as trace4,
|
|
960
1182
|
context as context2,
|
|
961
1183
|
SpanStatusCode as SpanStatusCode2
|
|
962
1184
|
} from "@opentelemetry/api";
|
|
@@ -973,7 +1195,7 @@ function toolResultText(content) {
|
|
|
973
1195
|
}
|
|
974
1196
|
var TURN_INPUT_MAX = 4e3;
|
|
975
1197
|
async function* observeClaude(stream, options) {
|
|
976
|
-
const tracer = options.tracer ??
|
|
1198
|
+
const tracer = options.tracer ?? trace4.getTracer("@withgateway/sdk");
|
|
977
1199
|
const model = options.model ?? "claude";
|
|
978
1200
|
const openTools = /* @__PURE__ */ new Map();
|
|
979
1201
|
let root = null;
|
|
@@ -986,7 +1208,7 @@ async function* observeClaude(stream, options) {
|
|
|
986
1208
|
...options.attributes ?? {}
|
|
987
1209
|
}
|
|
988
1210
|
});
|
|
989
|
-
rootCtx =
|
|
1211
|
+
rootCtx = trace4.setSpan(context2.active(), root);
|
|
990
1212
|
}
|
|
991
1213
|
let turnRoot = null;
|
|
992
1214
|
let turnCtx = null;
|
|
@@ -1019,7 +1241,7 @@ async function* observeClaude(stream, options) {
|
|
|
1019
1241
|
...options.attributes ?? {}
|
|
1020
1242
|
}
|
|
1021
1243
|
});
|
|
1022
|
-
turnCtx =
|
|
1244
|
+
turnCtx = trace4.setSpan(context2.active(), turnRoot);
|
|
1023
1245
|
pendingTurnInput = "";
|
|
1024
1246
|
}
|
|
1025
1247
|
const childCtx = options.perTurn ? turnCtx : rootCtx;
|