@prompt-helm/sdk 1.4.0 → 1.6.0

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/dist/index.js CHANGED
@@ -1,3 +1,207 @@
1
+ // src/adapters.ts
2
+ var obj = (value) => value !== null && typeof value === "object" && !Array.isArray(value) ? value : {};
3
+ function requestOptions(c) {
4
+ const options = {};
5
+ if (c.timeoutMs !== void 0) options.timeout = c.timeoutMs;
6
+ if (c.maxRetries !== void 0) options.maxRetries = c.maxRetries;
7
+ return options;
8
+ }
9
+ function put(target, values) {
10
+ for (const [key, value] of Object.entries(values)) if (value !== void 0) target[key] = value;
11
+ return target;
12
+ }
13
+ function turns(yours, user, wrap) {
14
+ if (user === null) return yours;
15
+ return Array.isArray(yours) ? [...yours, wrap(user)] : [wrap(user)];
16
+ }
17
+ function toOpenAIResponses(r, base) {
18
+ const c = r.config;
19
+ const yours = base;
20
+ const params = put(
21
+ { ...yours, ...c.extra },
22
+ {
23
+ model: c.model,
24
+ instructions: r.system,
25
+ // Input as text stays text; a list of items is history the user message follows.
26
+ input: r.user !== null && !Array.isArray(yours.input) ? r.user : turns(yours.input, r.user, userMessage),
27
+ max_output_tokens: c.maxTokens,
28
+ temperature: c.temperature,
29
+ text: c.response && {
30
+ ...obj(yours.text),
31
+ format: {
32
+ type: "json_schema",
33
+ name: c.response.name,
34
+ schema: c.response.schema,
35
+ strict: true
36
+ }
37
+ }
38
+ }
39
+ );
40
+ return { params, options: requestOptions(c) };
41
+ }
42
+ function toChatCompletions(r, base) {
43
+ const c = r.config;
44
+ const yours = base;
45
+ const history = (Array.isArray(yours.messages) ? yours.messages : []).filter((m) => {
46
+ const role = obj(m).role;
47
+ return role !== "system" && role !== "developer";
48
+ });
49
+ const own = c.provider === "openai" || c.provider === "azure";
50
+ const params = put(
51
+ { ...yours, ...c.extra },
52
+ {
53
+ model: c.model,
54
+ messages: [
55
+ { role: "system", content: r.system },
56
+ ...turns(history, r.user, userMessage)
57
+ ],
58
+ [own ? "max_completion_tokens" : "max_tokens"]: c.maxTokens,
59
+ temperature: c.temperature,
60
+ stop: c.stop,
61
+ response_format: c.response && {
62
+ type: "json_schema",
63
+ json_schema: { name: c.response.name, schema: c.response.schema, strict: true }
64
+ }
65
+ }
66
+ );
67
+ return { params, options: requestOptions(c) };
68
+ }
69
+ function toAnthropic(r, base) {
70
+ const c = r.config;
71
+ const yours = base;
72
+ const params = put(
73
+ { ...yours, ...c.extra },
74
+ {
75
+ model: c.model,
76
+ system: r.system,
77
+ messages: turns(yours.messages, r.user, userMessage),
78
+ max_tokens: c.maxTokens,
79
+ temperature: c.temperature,
80
+ stop_sequences: c.stop,
81
+ output_config: c.response && {
82
+ ...obj(yours.output_config),
83
+ format: { type: "json_schema", schema: c.response.schema }
84
+ }
85
+ }
86
+ );
87
+ return { params, options: requestOptions(c) };
88
+ }
89
+ function toGemini(r, base) {
90
+ const c = r.config;
91
+ const yours = base;
92
+ const config = obj(yours.config);
93
+ const http = obj(config.httpOptions);
94
+ const params = put(
95
+ { ...yours },
96
+ {
97
+ model: c.model,
98
+ contents: turns(yours.contents, r.user, (text) => ({ role: "user", parts: [{ text }] })),
99
+ config: put(
100
+ { ...config },
101
+ {
102
+ systemInstruction: r.system,
103
+ maxOutputTokens: c.maxTokens,
104
+ temperature: c.temperature,
105
+ stopSequences: c.stop,
106
+ responseMimeType: c.response && "application/json",
107
+ responseJsonSchema: c.response?.schema,
108
+ httpOptions: c.timeoutMs !== void 0 || c.extra ? put(
109
+ { ...http },
110
+ {
111
+ timeout: c.timeoutMs,
112
+ extraBody: c.extra && { ...obj(http.extraBody), ...c.extra }
113
+ }
114
+ ) : void 0
115
+ }
116
+ )
117
+ }
118
+ );
119
+ return { params, options: {} };
120
+ }
121
+ function toBedrockConverse(r, base) {
122
+ const c = r.config;
123
+ const yours = base;
124
+ const inference = obj(yours.inferenceConfig);
125
+ const params = put(
126
+ { ...yours },
127
+ {
128
+ modelId: c.model,
129
+ system: [{ text: r.system }],
130
+ messages: turns(yours.messages, r.user, (text) => ({ role: "user", content: [{ text }] })),
131
+ inferenceConfig: c.maxTokens !== void 0 || c.temperature !== void 0 || c.stop ? put(
132
+ { ...inference },
133
+ { maxTokens: c.maxTokens, temperature: c.temperature, stopSequences: c.stop }
134
+ ) : void 0,
135
+ outputConfig: c.response && {
136
+ ...obj(yours.outputConfig),
137
+ textFormat: {
138
+ type: "json_schema",
139
+ structure: {
140
+ jsonSchema: { name: c.response.name, schema: JSON.stringify(c.response.schema) }
141
+ }
142
+ }
143
+ },
144
+ additionalModelRequestFields: c.extra && {
145
+ ...obj(yours.additionalModelRequestFields),
146
+ ...c.extra
147
+ }
148
+ }
149
+ );
150
+ return { params, options: {} };
151
+ }
152
+ function clientOptions(r, base) {
153
+ const c = r.config;
154
+ const to = c.connection ?? {};
155
+ const out = { ...base };
156
+ const trimmed = (url) => url.replace(/\/+$/, "");
157
+ switch (r.api ?? c.apis?.[0]) {
158
+ case "openai-responses":
159
+ case "chat-completions": {
160
+ const baseURL = to.baseUrl ?? (c.provider === "azure" && to.endpointUrl ? withPath(trimmed(to.endpointUrl), "/openai/v1/") : c.provider === "databricks" && to.workspaceUrl ? withPath(trimmed(to.workspaceUrl), "/serving-endpoints") : void 0);
161
+ return put(out, { baseURL, ...requestOptions(c) });
162
+ }
163
+ case "anthropic-messages": {
164
+ const baseURL = to.baseUrl ?? (c.provider === "azure" && to.endpointUrl ? withPath(trimmed(to.endpointUrl), "/anthropic/") : void 0);
165
+ const region = c.provider === "google-vertex" ? to.location : void 0;
166
+ return put(out, { baseURL, region, ...requestOptions(c) });
167
+ }
168
+ case "gemini": {
169
+ const http = obj(out.httpOptions);
170
+ const httpOptions = to.baseUrl !== void 0 || c.timeoutMs !== void 0 || c.maxRetries !== void 0 ? put(
171
+ { ...http },
172
+ {
173
+ baseUrl: to.baseUrl,
174
+ timeout: c.timeoutMs,
175
+ retryOptions: c.maxRetries !== void 0 ? { ...obj(http.retryOptions), attempts: c.maxRetries + 1 } : void 0
176
+ }
177
+ ) : void 0;
178
+ const vertex = c.provider === "google-vertex";
179
+ return put(out, {
180
+ vertexai: vertex || void 0,
181
+ location: vertex ? to.location : void 0,
182
+ httpOptions
183
+ });
184
+ }
185
+ case "bedrock-converse": {
186
+ const handler = obj(out.requestHandler);
187
+ return put(out, {
188
+ region: to.region,
189
+ endpoint: to.endpointUrl,
190
+ maxAttempts: c.maxRetries !== void 0 ? c.maxRetries + 1 : void 0,
191
+ requestHandler: c.timeoutMs !== void 0 ? { ...handler, requestTimeout: c.timeoutMs, throwOnRequestTimeout: true } : void 0
192
+ });
193
+ }
194
+ default:
195
+ return out;
196
+ }
197
+ }
198
+ function withPath(url, path) {
199
+ return /^https?:\/\/[^/]+\/./.test(url) ? url : `${url}${path}`;
200
+ }
201
+ function userMessage(text) {
202
+ return { role: "user", content: text };
203
+ }
204
+
1
205
  // src/errors.ts
2
206
  var ERROR_CODES = [
3
207
  "unauthorized",
@@ -5,7 +209,9 @@ var ERROR_CODES = [
5
209
  "missing_variables",
6
210
  "timeout",
7
211
  "network",
8
- "server"
212
+ "server",
213
+ // The version is for another API than the one the call asked for (`api`, SDK 1.6).
214
+ "api_mismatch"
9
215
  ];
10
216
  var PromptHelmError = class extends Error {
11
217
  constructor(code, message, status) {
@@ -51,6 +257,14 @@ function render(template, vars = {}) {
51
257
 
52
258
  // src/client.ts
53
259
  var DEFAULT_BASE_URL = "https://prompthelm.app";
260
+ var PROMPT_APIS = [
261
+ "openai-responses",
262
+ "chat-completions",
263
+ "anthropic-messages",
264
+ "gemini",
265
+ "bedrock-converse"
266
+ ];
267
+ var API_HEADER = "x-prompthelm-api";
54
268
  var FALLBACK_HEADER = "x-prompthelm-fallback";
55
269
  var FIELDS = [
56
270
  "served",
@@ -73,6 +287,13 @@ var TOKENS_IN = 6;
73
287
  var TOKENS_OUT = 7;
74
288
  var LATENCY = 8;
75
289
  var BUCKETS = FIELDS.length;
290
+ function fill(system, user, vars, withUser) {
291
+ const text = typeof user === "string" ? user : user?.content;
292
+ return {
293
+ system: render(system, vars),
294
+ user: withUser && text !== void 0 ? render(text, vars) : null
295
+ };
296
+ }
76
297
  var PromptHelm = class {
77
298
  #apiKey;
78
299
  #baseUrl;
@@ -85,6 +306,10 @@ var PromptHelm = class {
85
306
  #inflight = /* @__PURE__ */ new Map();
86
307
  #reportFallbacks;
87
308
  #reportResults;
309
+ #reportFailures;
310
+ // Per slug, the API a call last asked for, sent with its requests (`API_HEADER`).
311
+ #apis = /* @__PURE__ */ new Map();
312
+ #failures = /* @__PURE__ */ new Map();
88
313
  // Per slug, why the live text last couldn't be served, until a request carries it. An object,
89
314
  // so a report made while that request is in flight isn't cleared with the one it carried.
90
315
  #unreported = /* @__PURE__ */ new Map();
@@ -103,22 +328,37 @@ var PromptHelm = class {
103
328
  this.#onResolve = options.onResolve;
104
329
  this.#reportFallbacks = options.reportFallbacks ?? true;
105
330
  this.#reportResults = options.reportResults ?? this.#reportFallbacks;
331
+ this.#reportFailures = options.reportFailures ?? this.#reportFallbacks;
106
332
  }
107
- /** The live version of a prompt with its variables filled in. */
333
+ /**
334
+ * The live version's system message with its variables filled in. It never needs the user
335
+ * message's variables: an app that calls `get` sends its own.
336
+ */
108
337
  async get(slug, options = {}) {
109
- return (await this.resolve(slug, options)).text;
338
+ return (await this.#resolve(slug, options, false)).text;
110
339
  }
111
- /** Like `get`, and says which version was served, so you can tag your logs or traces with it. */
112
- async resolve(slug, options = {}) {
113
- const { vars, fallback } = options;
340
+ /**
341
+ * Like `get`, with the user message too, the model settings, and which version was served, so
342
+ * you can tag your logs or traces with it.
343
+ */
344
+ resolve(slug, options = {}) {
345
+ return this.#resolve(slug, options, true);
346
+ }
347
+ async #resolve(slug, options, withUser) {
348
+ const { vars, fallback, api } = options;
349
+ if (api) this.#apis.set(slug, api);
114
350
  try {
115
- return this.#pick(slug, await this.#entry(slug), options);
351
+ return { ...this.#pick(slug, await this.#entry(slug), options, withUser), api: api ?? null };
116
352
  } catch (error) {
117
353
  const failure = toPromptHelmError(error);
118
354
  this.#remember(slug, failure.code);
119
355
  if (fallback === void 0) throw failure;
120
356
  this.#onError(failure, slug);
121
- return this.#served(slug, render(fallback, vars), {}, null);
357
+ const own = typeof fallback === "string" ? { system: fallback } : fallback;
358
+ return {
359
+ ...this.#served(slug, fill(own.system, own.user, vars, withUser), {}, null),
360
+ api: api ?? null
361
+ };
122
362
  }
123
363
  }
124
364
  /** Reports the outcome of a call made earlier, by its `ticket`. Ignores anything else. */
@@ -135,8 +375,10 @@ var PromptHelm = class {
135
375
  clearTimeout(this.#timer);
136
376
  this.#timer = void 0;
137
377
  const sent = this.#pending;
138
- if (sent.size === 0) return;
378
+ const failures = this.#failures;
379
+ if (sent.size === 0 && failures.size === 0) return;
139
380
  this.#pending = /* @__PURE__ */ new Map();
381
+ this.#failures = /* @__PURE__ */ new Map();
140
382
  const body = {
141
383
  experiments: [...sent.values()].map(({ id, weight, versions }) => ({
142
384
  id,
@@ -152,6 +394,7 @@ var PromptHelm = class {
152
394
  )
153
395
  }))
154
396
  };
397
+ if (failures.size > 0) body.failures = [...failures.values()];
155
398
  try {
156
399
  const response = await this.#fetch(`${this.#baseUrl}/v1/reports`, {
157
400
  method: "POST",
@@ -162,6 +405,11 @@ var PromptHelm = class {
162
405
  if (response.status < 500) return;
163
406
  } catch {
164
407
  }
408
+ for (const [key, failure] of failures) {
409
+ const now = this.#failures.get(key);
410
+ if (now) now.count += failure.count;
411
+ else this.#failures.set(key, failure);
412
+ }
165
413
  for (const { id, weight, versions } of sent.values()) {
166
414
  for (const [version, counts] of versions) {
167
415
  const total = this.#counts({ id, weight }, version);
@@ -171,17 +419,26 @@ var PromptHelm = class {
171
419
  }
172
420
  }
173
421
  }
174
- #pick(slug, entry, options) {
175
- const { vars, unit, force } = options;
422
+ #pick(slug, entry, options, withUser) {
423
+ const { vars, unit, force, api } = options;
176
424
  const { experiment } = entry;
425
+ const check = (version, config) => {
426
+ if (api && config.apis && !config.apis.includes(api)) {
427
+ throw new PromptHelmError(
428
+ "api_mismatch",
429
+ `v${version} is called with ${config.apis.join(" or ")}, not ${api}`
430
+ );
431
+ }
432
+ };
177
433
  const test = experiment && !force ? { id: experiment.id, weight: experiment.weight } : void 0;
178
434
  let skipped;
179
435
  if (experiment && (force ? force === "variant" : bucket(experiment.id, unit) < experiment.weight)) {
180
- const { version, content, config = {} } = experiment.variant;
436
+ const { version, content, user, config = {} } = experiment.variant;
181
437
  try {
438
+ check(version, config);
182
439
  return this.#served(
183
440
  slug,
184
- render(content, vars),
441
+ fill(content, user, vars, withUser),
185
442
  config,
186
443
  version,
187
444
  experiment.id,
@@ -192,15 +449,16 @@ var PromptHelm = class {
192
449
  skipped = toPromptHelmError(error);
193
450
  }
194
451
  }
195
- const text = render(entry.content, vars);
452
+ check(entry.version, entry.config);
453
+ const messages = fill(entry.content, entry.user, vars, withUser);
196
454
  if (skipped && experiment) {
197
455
  this.#onError(skipped, slug);
198
456
  if (test) add(this.#counts(test, experiment.variant.version), SKIPPED, 1);
199
457
  }
200
- return this.#served(slug, text, entry.config, entry.version, experiment?.id, test);
458
+ return this.#served(slug, messages, entry.config, entry.version, experiment?.id, test);
201
459
  }
202
- /** Counts the call, tells `onResolve`, and hands the caller its text, settings and what to report. */
203
- #served(slug, text, config, version, experiment, test, variant = false) {
460
+ /** Counts the call, tells `onResolve`, and hands the caller its messages, settings and what to report. */
461
+ #served(slug, { system, user }, config, version, experiment, test, variant = false) {
204
462
  if (test && version !== null) add(this.#counts(test, version), SERVED, 1);
205
463
  try {
206
464
  this.#onResolve?.({ slug, version, experiment: experiment ?? null, variant });
@@ -209,9 +467,11 @@ var PromptHelm = class {
209
467
  const started = Date.now();
210
468
  let reported = 0;
211
469
  return {
212
- text,
213
- // A copy: the cached one serves every later call.
214
- config: { ...config },
470
+ text: system,
471
+ system,
472
+ user,
473
+ // A copy, schema and all: the cached one serves every later call.
474
+ config: structuredClone(config),
215
475
  version,
216
476
  ticket: test && version !== null ? `${test.id}.${version}.${test.weight}` : null,
217
477
  outcome: (value) => {
@@ -219,6 +479,11 @@ var PromptHelm = class {
219
479
  reported |= 1;
220
480
  this.#outcome(test, version, value);
221
481
  },
482
+ failed: (error) => {
483
+ if (version === null || reported & 4) return;
484
+ reported |= 4;
485
+ this.#failed(slug, version, error);
486
+ },
222
487
  usage: (usage, ms = Date.now() - started) => {
223
488
  if (!test || version === null || reported & 2) return;
224
489
  reported |= 2;
@@ -240,6 +505,18 @@ var PromptHelm = class {
240
505
  add(counts, SCORE, score);
241
506
  add(counts, SCORE_SQ, score * score);
242
507
  }
508
+ /** Counts a refused model call by its HTTP status and codes; anything else is ignored. */
509
+ #failed(slug, version, error) {
510
+ if (!this.#reportFailures) return;
511
+ const failure = refusal(error);
512
+ if (!failure) return;
513
+ const { status, type, code, param } = failure;
514
+ const key = JSON.stringify([slug, version, status, type, code, param]);
515
+ const counted = this.#failures.get(key);
516
+ if (counted) counted.count += 1;
517
+ else this.#failures.set(key, { slug, version, ...failure, count: 1 });
518
+ this.#schedule();
519
+ }
243
520
  /** The counts to add a call to, kept until the next report; none when reporting is off. */
244
521
  #counts(test, version) {
245
522
  if (!this.#reportResults) return;
@@ -296,6 +573,8 @@ var PromptHelm = class {
296
573
  if (cached?.etag) headers["if-none-match"] = cached.etag;
297
574
  const report = this.#unreported.get(slug);
298
575
  if (report) headers[FALLBACK_HEADER] = report.code;
576
+ const api = this.#apis.get(slug);
577
+ if (api) headers[API_HEADER] = api;
299
578
  let response;
300
579
  try {
301
580
  response = await this.#fetch(`${this.#baseUrl}/v1/prompts/${encodeURIComponent(slug)}`, {
@@ -321,6 +600,7 @@ var PromptHelm = class {
321
600
  const entry = {
322
601
  version: payload.version,
323
602
  content: payload.content,
603
+ user: payload.user,
324
604
  config: payload.config ?? {},
325
605
  experiment: payload.experiment,
326
606
  etag: response.headers.get("etag"),
@@ -339,6 +619,27 @@ function tokens(usage, keys) {
339
619
  }
340
620
  return 0;
341
621
  }
622
+ var CODE = /^[A-Za-z0-9_.:[\]-]{1,64}$/;
623
+ var word = (value) => typeof value === "string" && CODE.test(value) ? value : void 0;
624
+ function refusal(error) {
625
+ if (error === null || typeof error !== "object") return null;
626
+ const e = error;
627
+ const meta = e.$metadata;
628
+ const response = e.response;
629
+ const status = [e.status, e.statusCode, meta?.httpStatusCode, response?.status].find(
630
+ (value) => Number.isInteger(value) && Number(value) >= 400 && Number(value) < 600
631
+ );
632
+ if (status === void 0) return null;
633
+ const nested = e.error !== null && typeof e.error === "object" ? e.error : {};
634
+ const failure = { status };
635
+ const type = word(e.type) ?? word(nested.type) ?? (meta ? word(e.name) : void 0);
636
+ const code = word(e.code) ?? word(e.errorCode) ?? word(nested.code);
637
+ const param = word(e.param) ?? word(nested.param);
638
+ if (type) failure.type = type;
639
+ if (code) failure.code = code;
640
+ if (param) failure.param = param;
641
+ return failure;
642
+ }
342
643
  function add(counts, index, amount) {
343
644
  if (counts) counts[index] = (counts[index] ?? 0) + amount;
344
645
  }
@@ -356,12 +657,20 @@ function toPromptHelmError(error) {
356
657
  return new PromptHelmError("server", error instanceof Error ? error.message : String(error));
357
658
  }
358
659
  export {
660
+ API_HEADER,
359
661
  ERROR_CODES,
360
662
  FALLBACK_HEADER,
361
663
  LATENCY_BUCKETS,
664
+ PROMPT_APIS,
362
665
  PromptHelm,
363
666
  PromptHelmError,
667
+ clientOptions,
364
668
  extractVariables,
365
669
  latencyBucket,
366
- render
670
+ render,
671
+ toAnthropic,
672
+ toBedrockConverse,
673
+ toChatCompletions,
674
+ toGemini,
675
+ toOpenAIResponses
367
676
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@prompt-helm/sdk",
3
- "version": "1.4.0",
3
+ "version": "1.6.0",
4
4
  "description": "Fetch your PromptHelm prompts at runtime, so changing a prompt needs no redeploy.",
5
5
  "homepage": "https://prompthelm.app/quickstart",
6
6
  "repository": {