@prompt-helm/sdk 1.5.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",
@@ -92,6 +306,10 @@ var PromptHelm = class {
92
306
  #inflight = /* @__PURE__ */ new Map();
93
307
  #reportFallbacks;
94
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();
95
313
  // Per slug, why the live text last couldn't be served, until a request carries it. An object,
96
314
  // so a report made while that request is in flight isn't cleared with the one it carried.
97
315
  #unreported = /* @__PURE__ */ new Map();
@@ -110,6 +328,7 @@ var PromptHelm = class {
110
328
  this.#onResolve = options.onResolve;
111
329
  this.#reportFallbacks = options.reportFallbacks ?? true;
112
330
  this.#reportResults = options.reportResults ?? this.#reportFallbacks;
331
+ this.#reportFailures = options.reportFailures ?? this.#reportFallbacks;
113
332
  }
114
333
  /**
115
334
  * The live version's system message with its variables filled in. It never needs the user
@@ -126,16 +345,20 @@ var PromptHelm = class {
126
345
  return this.#resolve(slug, options, true);
127
346
  }
128
347
  async #resolve(slug, options, withUser) {
129
- const { vars, fallback } = options;
348
+ const { vars, fallback, api } = options;
349
+ if (api) this.#apis.set(slug, api);
130
350
  try {
131
- return this.#pick(slug, await this.#entry(slug), options, withUser);
351
+ return { ...this.#pick(slug, await this.#entry(slug), options, withUser), api: api ?? null };
132
352
  } catch (error) {
133
353
  const failure = toPromptHelmError(error);
134
354
  this.#remember(slug, failure.code);
135
355
  if (fallback === void 0) throw failure;
136
356
  this.#onError(failure, slug);
137
357
  const own = typeof fallback === "string" ? { system: fallback } : fallback;
138
- return this.#served(slug, fill(own.system, own.user, vars, withUser), {}, null);
358
+ return {
359
+ ...this.#served(slug, fill(own.system, own.user, vars, withUser), {}, null),
360
+ api: api ?? null
361
+ };
139
362
  }
140
363
  }
141
364
  /** Reports the outcome of a call made earlier, by its `ticket`. Ignores anything else. */
@@ -152,8 +375,10 @@ var PromptHelm = class {
152
375
  clearTimeout(this.#timer);
153
376
  this.#timer = void 0;
154
377
  const sent = this.#pending;
155
- if (sent.size === 0) return;
378
+ const failures = this.#failures;
379
+ if (sent.size === 0 && failures.size === 0) return;
156
380
  this.#pending = /* @__PURE__ */ new Map();
381
+ this.#failures = /* @__PURE__ */ new Map();
157
382
  const body = {
158
383
  experiments: [...sent.values()].map(({ id, weight, versions }) => ({
159
384
  id,
@@ -169,6 +394,7 @@ var PromptHelm = class {
169
394
  )
170
395
  }))
171
396
  };
397
+ if (failures.size > 0) body.failures = [...failures.values()];
172
398
  try {
173
399
  const response = await this.#fetch(`${this.#baseUrl}/v1/reports`, {
174
400
  method: "POST",
@@ -179,6 +405,11 @@ var PromptHelm = class {
179
405
  if (response.status < 500) return;
180
406
  } catch {
181
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
+ }
182
413
  for (const { id, weight, versions } of sent.values()) {
183
414
  for (const [version, counts] of versions) {
184
415
  const total = this.#counts({ id, weight }, version);
@@ -189,13 +420,22 @@ var PromptHelm = class {
189
420
  }
190
421
  }
191
422
  #pick(slug, entry, options, withUser) {
192
- const { vars, unit, force } = options;
423
+ const { vars, unit, force, api } = options;
193
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
+ };
194
433
  const test = experiment && !force ? { id: experiment.id, weight: experiment.weight } : void 0;
195
434
  let skipped;
196
435
  if (experiment && (force ? force === "variant" : bucket(experiment.id, unit) < experiment.weight)) {
197
436
  const { version, content, user, config = {} } = experiment.variant;
198
437
  try {
438
+ check(version, config);
199
439
  return this.#served(
200
440
  slug,
201
441
  fill(content, user, vars, withUser),
@@ -209,6 +449,7 @@ var PromptHelm = class {
209
449
  skipped = toPromptHelmError(error);
210
450
  }
211
451
  }
452
+ check(entry.version, entry.config);
212
453
  const messages = fill(entry.content, entry.user, vars, withUser);
213
454
  if (skipped && experiment) {
214
455
  this.#onError(skipped, slug);
@@ -238,6 +479,11 @@ var PromptHelm = class {
238
479
  reported |= 1;
239
480
  this.#outcome(test, version, value);
240
481
  },
482
+ failed: (error) => {
483
+ if (version === null || reported & 4) return;
484
+ reported |= 4;
485
+ this.#failed(slug, version, error);
486
+ },
241
487
  usage: (usage, ms = Date.now() - started) => {
242
488
  if (!test || version === null || reported & 2) return;
243
489
  reported |= 2;
@@ -259,6 +505,18 @@ var PromptHelm = class {
259
505
  add(counts, SCORE, score);
260
506
  add(counts, SCORE_SQ, score * score);
261
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
+ }
262
520
  /** The counts to add a call to, kept until the next report; none when reporting is off. */
263
521
  #counts(test, version) {
264
522
  if (!this.#reportResults) return;
@@ -315,6 +573,8 @@ var PromptHelm = class {
315
573
  if (cached?.etag) headers["if-none-match"] = cached.etag;
316
574
  const report = this.#unreported.get(slug);
317
575
  if (report) headers[FALLBACK_HEADER] = report.code;
576
+ const api = this.#apis.get(slug);
577
+ if (api) headers[API_HEADER] = api;
318
578
  let response;
319
579
  try {
320
580
  response = await this.#fetch(`${this.#baseUrl}/v1/prompts/${encodeURIComponent(slug)}`, {
@@ -359,6 +619,27 @@ function tokens(usage, keys) {
359
619
  }
360
620
  return 0;
361
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
+ }
362
643
  function add(counts, index, amount) {
363
644
  if (counts) counts[index] = (counts[index] ?? 0) + amount;
364
645
  }
@@ -376,12 +657,20 @@ function toPromptHelmError(error) {
376
657
  return new PromptHelmError("server", error instanceof Error ? error.message : String(error));
377
658
  }
378
659
  export {
660
+ API_HEADER,
379
661
  ERROR_CODES,
380
662
  FALLBACK_HEADER,
381
663
  LATENCY_BUCKETS,
664
+ PROMPT_APIS,
382
665
  PromptHelm,
383
666
  PromptHelmError,
667
+ clientOptions,
384
668
  extractVariables,
385
669
  latencyBucket,
386
- render
670
+ render,
671
+ toAnthropic,
672
+ toBedrockConverse,
673
+ toChatCompletions,
674
+ toGemini,
675
+ toOpenAIResponses
387
676
  };
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@prompt-helm/sdk",
3
- "version": "1.5.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": {