@withgateway/sdk 0.1.11 → 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 +44 -5
- package/dist/index.d.ts +44 -5
- package/dist/index.js +364 -37
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +348 -31
- 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 +309 -18
- package/dist/tracing/index.js.map +1 -1
- package/dist/tracing/index.mjs +303 -12
- package/dist/tracing/index.mjs.map +1 -1
- package/package.json +6 -1
package/README.md
CHANGED
|
@@ -152,6 +152,43 @@ experiments.clearExperimentContext() // Clear context (call after each request)
|
|
|
152
152
|
experiments.shutdown() // Cleanup (call on exit)
|
|
153
153
|
```
|
|
154
154
|
|
|
155
|
+
### Scores & Success Signals
|
|
156
|
+
|
|
157
|
+
Record evaluation scores and ROI-shaped **success signals** against a project.
|
|
158
|
+
A success signal is a score tagged with `gateway.success.signal`, which the
|
|
159
|
+
platform's **Success Metrics** feature aggregates into a metric's headline
|
|
160
|
+
count / pass-rate (the `HOOK` metric source). The score shape is identical to
|
|
161
|
+
the Python SDK's `run.success()`, so signals from either SDK aggregate the same.
|
|
162
|
+
|
|
163
|
+
```typescript
|
|
164
|
+
import { ScoresClient, success } from "@withgateway/sdk/scores";
|
|
165
|
+
|
|
166
|
+
// Env-based (GATEWAY_HOST / GATEWAY_PUBLIC_KEY / GATEWAY_SECRET_KEY):
|
|
167
|
+
await success("resolved_ticket", true, { agentId: "support-triage", sessionId });
|
|
168
|
+
await success("handle_time_s", 42, { agentId: "support-triage", sessionId });
|
|
169
|
+
|
|
170
|
+
// Explicit keys:
|
|
171
|
+
const scores = new ScoresClient({ host, publicKey, secretKey });
|
|
172
|
+
await scores.success("resolved_ticket", true, { agentId: "support-triage", sessionId });
|
|
173
|
+
await scores.score("rubric", 0.9, { sessionId }); // a plain (non-signal) score
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
A boolean `value` is recorded as a 1/0 **BOOLEAN** score (pass/fail); a number
|
|
177
|
+
is a **NUMERIC** score. `metricName` defaults to the signal `name`. Provide
|
|
178
|
+
exactly one target — `sessionId`, `traceId` (+ optional `observationId`), or
|
|
179
|
+
`datasetRunId`; when none is given the active OpenTelemetry trace id is used,
|
|
180
|
+
and if there is none the call is a fail-soft no-op. Every `score`/`success`
|
|
181
|
+
call is **fail-soft**: a bad key or transport failure warns and resolves, never
|
|
182
|
+
throwing into your run. (`postScore` is the raw variant that DOES throw.)
|
|
183
|
+
|
|
184
|
+
Under `tracing.initIsolated(...)`, the returned handle carries a `scores`
|
|
185
|
+
client bound to that provider's project keys:
|
|
186
|
+
|
|
187
|
+
```typescript
|
|
188
|
+
const handle = tracing.initIsolated({ host, publicKey, secretKey, agent: "support-agent" });
|
|
189
|
+
await handle.scores.success("resolved_ticket", true, { agentId: "support-agent", sessionId });
|
|
190
|
+
```
|
|
191
|
+
|
|
155
192
|
### Security Wrapper
|
|
156
193
|
|
|
157
194
|
Use the security wrapper when you want Gateway to control tool visibility,
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { Context, Tracer } from '@opentelemetry/api';
|
|
2
|
+
import { ScoresClient } from './scores/index.mjs';
|
|
2
3
|
import { SpanProcessor, Span, ReadableSpan } from '@opentelemetry/sdk-trace-base';
|
|
3
4
|
|
|
4
5
|
/**
|
|
@@ -186,6 +187,14 @@ interface TracingState {
|
|
|
186
187
|
*/
|
|
187
188
|
interface TracingHandle {
|
|
188
189
|
tracer: Tracer;
|
|
190
|
+
/**
|
|
191
|
+
* Scores/success-signal client bound to THIS provider's project keys. Emit
|
|
192
|
+
* ROI success signals into the same project the handle's spans export to —
|
|
193
|
+
* `handle.scores.success("resolved_ticket", true, { agentId, sessionId })` —
|
|
194
|
+
* without threading credentials through your own code. Fail-soft, like the
|
|
195
|
+
* rest of the client.
|
|
196
|
+
*/
|
|
197
|
+
scores: ScoresClient;
|
|
189
198
|
/** Force-flush pending spans for this provider only. */
|
|
190
199
|
flush(): Promise<void>;
|
|
191
200
|
/** Flush and shut down this provider only. */
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import { Context, Tracer } from '@opentelemetry/api';
|
|
2
|
+
import { ScoresClient } from './scores/index.js';
|
|
2
3
|
import { SpanProcessor, Span, ReadableSpan } from '@opentelemetry/sdk-trace-base';
|
|
3
4
|
|
|
4
5
|
/**
|
|
@@ -186,6 +187,14 @@ interface TracingState {
|
|
|
186
187
|
*/
|
|
187
188
|
interface TracingHandle {
|
|
188
189
|
tracer: Tracer;
|
|
190
|
+
/**
|
|
191
|
+
* Scores/success-signal client bound to THIS provider's project keys. Emit
|
|
192
|
+
* ROI success signals into the same project the handle's spans export to —
|
|
193
|
+
* `handle.scores.success("resolved_ticket", true, { agentId, sessionId })` —
|
|
194
|
+
* without threading credentials through your own code. Fail-soft, like the
|
|
195
|
+
* rest of the client.
|
|
196
|
+
*/
|
|
197
|
+
scores: ScoresClient;
|
|
189
198
|
/** Force-flush pending spans for this provider only. */
|
|
190
199
|
flush(): Promise<void>;
|
|
191
200
|
/** Flush and shut down this provider only. */
|
package/dist/index.d.mts
CHANGED
|
@@ -6,8 +6,9 @@ export { DriftError, LocalTool, MissPolicy, REPLAY_ENVIRONMENT, RecordedToolCall
|
|
|
6
6
|
export { GatewayAgentDescriptor, GatewaySecurity, GatewaySecurityConfig, GatewaySecurityContext, GatewaySecurityError, GatewayToolApprovalRequiredError, GatewayToolBlockedError, GatewayToolCallAuthorizeResponse, GatewayToolDescriptor, GatewayToolsetResolveResponse, SecureToolsOptions, gateway } from './security/index.mjs';
|
|
7
7
|
export { DEFAULT_TIMEOUT_SECONDS, ENV_GATEWAY_HOST, ENV_GATEWAY_PUBLIC_KEY, ENV_GATEWAY_SECRET_KEY, LoadSessionOptions, SessionLoadError, SessionObservation, SessionRecording, SessionTrace, basicAuthHeader, loadSession, sessionObservationFromApi, sessions } from './sessions/index.mjs';
|
|
8
8
|
export { UserEvent, UserEventOptions, UserProfile, UserProfileError, UserProfileUpdate, UsersClient, UsersClientConfig, UsersClientFromEnvConfig, users } from './users/index.mjs';
|
|
9
|
-
|
|
10
|
-
|
|
9
|
+
export { AGENT_ID_KEY, SUCCESS_METRIC_NAME_KEY, SUCCESS_SIGNAL_KEY, ScoreDataType, ScoreError, ScoreOptions, ScoresClient, ScoresClientConfig, ScoresClientFromEnvConfig, SuccessOptions, currentTraceId, scores, success } from './scores/index.mjs';
|
|
10
|
+
import { _ as _tracingModule } from './index-B5HUQQDE.mjs';
|
|
11
|
+
export { I as IdentifyOptions, i as identify, r as resolveUserId } from './index-B5HUQQDE.mjs';
|
|
11
12
|
import 'async_hooks';
|
|
12
13
|
import '@opentelemetry/api';
|
|
13
14
|
import '@opentelemetry/sdk-trace-base';
|
|
@@ -22,6 +23,18 @@ interface ToolIdentity {
|
|
|
22
23
|
/** Source location of the defineTool call ("src/tools/checkout.ts:42"). */
|
|
23
24
|
source?: string;
|
|
24
25
|
}
|
|
26
|
+
/** Any versioned artifact an agent is built from — tools, prompts, skills,
|
|
27
|
+
* datasets, guardrails, configs… `content` hashes locally (off-platform);
|
|
28
|
+
* `ref` pins a platform-hosted artifact ("prompt/system@label:production"). */
|
|
29
|
+
interface ArtifactIdentity {
|
|
30
|
+
kind: string;
|
|
31
|
+
name: string;
|
|
32
|
+
version?: string;
|
|
33
|
+
contentHash?: string;
|
|
34
|
+
ref?: string;
|
|
35
|
+
source?: string;
|
|
36
|
+
metadata?: Record<string, string>;
|
|
37
|
+
}
|
|
25
38
|
interface AgentBuildManifest {
|
|
26
39
|
agentId: string;
|
|
27
40
|
codeRef?: string;
|
|
@@ -29,6 +42,7 @@ interface AgentBuildManifest {
|
|
|
29
42
|
tools: ToolIdentity[];
|
|
30
43
|
prompts: Record<string, string>;
|
|
31
44
|
skills: Record<string, string>;
|
|
45
|
+
artifacts: ArtifactIdentity[];
|
|
32
46
|
}
|
|
33
47
|
/** Deterministic JSON: object keys sorted recursively, arrays kept in order. */
|
|
34
48
|
declare function canonicalJson(value: unknown): string;
|
|
@@ -61,14 +75,39 @@ declare function defineTool<T extends DefineToolInput>(tool: T): T;
|
|
|
61
75
|
* `const SYSTEM = registerPrompt("system", "You are…")`. Returns the content
|
|
62
76
|
* unchanged. Platform-served prompts don't need this — pin them by label.
|
|
63
77
|
*/
|
|
64
|
-
|
|
78
|
+
interface RegisterArtifactOptions {
|
|
79
|
+
/** Developer-declared version, e.g. "1.2" (v1: bumped manually). */
|
|
80
|
+
version?: string;
|
|
81
|
+
/** Local content — hashed into the identity (off-platform artifacts). */
|
|
82
|
+
content?: string;
|
|
83
|
+
/** Platform reference (on-platform artifacts): "prompt/system@label:production". */
|
|
84
|
+
ref?: string;
|
|
85
|
+
metadata?: Record<string, string>;
|
|
86
|
+
}
|
|
87
|
+
/**
|
|
88
|
+
* Version ANY artifact the agent is built from — the generic primitive
|
|
89
|
+
* behind registerPrompt/registerSkill. Works on- and off-platform:
|
|
90
|
+
*
|
|
91
|
+
* ```ts
|
|
92
|
+
* registerArtifact("guardrail", "pii-filter", { version: "2.0", content: RULES });
|
|
93
|
+
* registerArtifact("prompt", "planner", { ref: "planner@label:production" });
|
|
94
|
+
* ```
|
|
95
|
+
*/
|
|
96
|
+
declare function registerArtifact(kind: string, name: string, options?: RegisterArtifactOptions): ArtifactIdentity;
|
|
97
|
+
declare function registerPrompt(name: string, content: string, options?: {
|
|
98
|
+
version?: string;
|
|
99
|
+
}): string;
|
|
65
100
|
declare function getRegisteredTools(): ToolIdentity[];
|
|
66
101
|
/**
|
|
67
102
|
* Register a skill's identity — `registerSkill("triage", "1.0")` — so skills
|
|
68
103
|
* are versioned in the build like tools and prompts. The version string is
|
|
69
104
|
* whatever you bump (or a content hash for file-based skills).
|
|
70
105
|
*/
|
|
71
|
-
declare function registerSkill(name: string, version: string
|
|
106
|
+
declare function registerSkill(name: string, version: string, options?: {
|
|
107
|
+
content?: string;
|
|
108
|
+
ref?: string;
|
|
109
|
+
}): void;
|
|
110
|
+
declare function getRegisteredArtifacts(): ArtifactIdentity[];
|
|
72
111
|
declare function getRegisteredSkills(): Record<string, string>;
|
|
73
112
|
declare function getRegisteredPrompts(): Record<string, string>;
|
|
74
113
|
/** Test hook. */
|
|
@@ -86,4 +125,4 @@ declare function computeBuildHash(manifest: AgentBuildManifest): string;
|
|
|
86
125
|
*/
|
|
87
126
|
declare const tracing: typeof _tracingModule;
|
|
88
127
|
|
|
89
|
-
export { type AgentBuildManifest, type DefineToolInput, type ToolEffects, type ToolIdentity, assembleManifest, canonicalJson, computeBuildHash, defineTool, getRegisteredPrompts, getRegisteredSkills, getRegisteredTools, registerPrompt, registerSkill, resetBuildRegistry, tracing };
|
|
128
|
+
export { type AgentBuildManifest, type ArtifactIdentity, type DefineToolInput, type RegisterArtifactOptions, type ToolEffects, type ToolIdentity, assembleManifest, canonicalJson, computeBuildHash, defineTool, getRegisteredArtifacts, getRegisteredPrompts, getRegisteredSkills, getRegisteredTools, registerArtifact, registerPrompt, registerSkill, resetBuildRegistry, tracing };
|
package/dist/index.d.ts
CHANGED
|
@@ -6,8 +6,9 @@ export { DriftError, LocalTool, MissPolicy, REPLAY_ENVIRONMENT, RecordedToolCall
|
|
|
6
6
|
export { GatewayAgentDescriptor, GatewaySecurity, GatewaySecurityConfig, GatewaySecurityContext, GatewaySecurityError, GatewayToolApprovalRequiredError, GatewayToolBlockedError, GatewayToolCallAuthorizeResponse, GatewayToolDescriptor, GatewayToolsetResolveResponse, SecureToolsOptions, gateway } from './security/index.js';
|
|
7
7
|
export { DEFAULT_TIMEOUT_SECONDS, ENV_GATEWAY_HOST, ENV_GATEWAY_PUBLIC_KEY, ENV_GATEWAY_SECRET_KEY, LoadSessionOptions, SessionLoadError, SessionObservation, SessionRecording, SessionTrace, basicAuthHeader, loadSession, sessionObservationFromApi, sessions } from './sessions/index.js';
|
|
8
8
|
export { UserEvent, UserEventOptions, UserProfile, UserProfileError, UserProfileUpdate, UsersClient, UsersClientConfig, UsersClientFromEnvConfig, users } from './users/index.js';
|
|
9
|
-
|
|
10
|
-
|
|
9
|
+
export { AGENT_ID_KEY, SUCCESS_METRIC_NAME_KEY, SUCCESS_SIGNAL_KEY, ScoreDataType, ScoreError, ScoreOptions, ScoresClient, ScoresClientConfig, ScoresClientFromEnvConfig, SuccessOptions, currentTraceId, scores, success } from './scores/index.js';
|
|
10
|
+
import { _ as _tracingModule } from './index-Dpo-t8iO.js';
|
|
11
|
+
export { I as IdentifyOptions, i as identify, r as resolveUserId } from './index-Dpo-t8iO.js';
|
|
11
12
|
import 'async_hooks';
|
|
12
13
|
import '@opentelemetry/api';
|
|
13
14
|
import '@opentelemetry/sdk-trace-base';
|
|
@@ -22,6 +23,18 @@ interface ToolIdentity {
|
|
|
22
23
|
/** Source location of the defineTool call ("src/tools/checkout.ts:42"). */
|
|
23
24
|
source?: string;
|
|
24
25
|
}
|
|
26
|
+
/** Any versioned artifact an agent is built from — tools, prompts, skills,
|
|
27
|
+
* datasets, guardrails, configs… `content` hashes locally (off-platform);
|
|
28
|
+
* `ref` pins a platform-hosted artifact ("prompt/system@label:production"). */
|
|
29
|
+
interface ArtifactIdentity {
|
|
30
|
+
kind: string;
|
|
31
|
+
name: string;
|
|
32
|
+
version?: string;
|
|
33
|
+
contentHash?: string;
|
|
34
|
+
ref?: string;
|
|
35
|
+
source?: string;
|
|
36
|
+
metadata?: Record<string, string>;
|
|
37
|
+
}
|
|
25
38
|
interface AgentBuildManifest {
|
|
26
39
|
agentId: string;
|
|
27
40
|
codeRef?: string;
|
|
@@ -29,6 +42,7 @@ interface AgentBuildManifest {
|
|
|
29
42
|
tools: ToolIdentity[];
|
|
30
43
|
prompts: Record<string, string>;
|
|
31
44
|
skills: Record<string, string>;
|
|
45
|
+
artifacts: ArtifactIdentity[];
|
|
32
46
|
}
|
|
33
47
|
/** Deterministic JSON: object keys sorted recursively, arrays kept in order. */
|
|
34
48
|
declare function canonicalJson(value: unknown): string;
|
|
@@ -61,14 +75,39 @@ declare function defineTool<T extends DefineToolInput>(tool: T): T;
|
|
|
61
75
|
* `const SYSTEM = registerPrompt("system", "You are…")`. Returns the content
|
|
62
76
|
* unchanged. Platform-served prompts don't need this — pin them by label.
|
|
63
77
|
*/
|
|
64
|
-
|
|
78
|
+
interface RegisterArtifactOptions {
|
|
79
|
+
/** Developer-declared version, e.g. "1.2" (v1: bumped manually). */
|
|
80
|
+
version?: string;
|
|
81
|
+
/** Local content — hashed into the identity (off-platform artifacts). */
|
|
82
|
+
content?: string;
|
|
83
|
+
/** Platform reference (on-platform artifacts): "prompt/system@label:production". */
|
|
84
|
+
ref?: string;
|
|
85
|
+
metadata?: Record<string, string>;
|
|
86
|
+
}
|
|
87
|
+
/**
|
|
88
|
+
* Version ANY artifact the agent is built from — the generic primitive
|
|
89
|
+
* behind registerPrompt/registerSkill. Works on- and off-platform:
|
|
90
|
+
*
|
|
91
|
+
* ```ts
|
|
92
|
+
* registerArtifact("guardrail", "pii-filter", { version: "2.0", content: RULES });
|
|
93
|
+
* registerArtifact("prompt", "planner", { ref: "planner@label:production" });
|
|
94
|
+
* ```
|
|
95
|
+
*/
|
|
96
|
+
declare function registerArtifact(kind: string, name: string, options?: RegisterArtifactOptions): ArtifactIdentity;
|
|
97
|
+
declare function registerPrompt(name: string, content: string, options?: {
|
|
98
|
+
version?: string;
|
|
99
|
+
}): string;
|
|
65
100
|
declare function getRegisteredTools(): ToolIdentity[];
|
|
66
101
|
/**
|
|
67
102
|
* Register a skill's identity — `registerSkill("triage", "1.0")` — so skills
|
|
68
103
|
* are versioned in the build like tools and prompts. The version string is
|
|
69
104
|
* whatever you bump (or a content hash for file-based skills).
|
|
70
105
|
*/
|
|
71
|
-
declare function registerSkill(name: string, version: string
|
|
106
|
+
declare function registerSkill(name: string, version: string, options?: {
|
|
107
|
+
content?: string;
|
|
108
|
+
ref?: string;
|
|
109
|
+
}): void;
|
|
110
|
+
declare function getRegisteredArtifacts(): ArtifactIdentity[];
|
|
72
111
|
declare function getRegisteredSkills(): Record<string, string>;
|
|
73
112
|
declare function getRegisteredPrompts(): Record<string, string>;
|
|
74
113
|
/** Test hook. */
|
|
@@ -86,4 +125,4 @@ declare function computeBuildHash(manifest: AgentBuildManifest): string;
|
|
|
86
125
|
*/
|
|
87
126
|
declare const tracing: typeof _tracingModule;
|
|
88
127
|
|
|
89
|
-
export { type AgentBuildManifest, type DefineToolInput, type ToolEffects, type ToolIdentity, assembleManifest, canonicalJson, computeBuildHash, defineTool, getRegisteredPrompts, getRegisteredSkills, getRegisteredTools, registerPrompt, registerSkill, resetBuildRegistry, tracing };
|
|
128
|
+
export { type AgentBuildManifest, type ArtifactIdentity, type DefineToolInput, type RegisterArtifactOptions, type ToolEffects, type ToolIdentity, assembleManifest, canonicalJson, computeBuildHash, defineTool, getRegisteredArtifacts, getRegisteredPrompts, getRegisteredSkills, getRegisteredTools, registerArtifact, registerPrompt, registerSkill, resetBuildRegistry, tracing };
|