@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/README.md +103 -14
- package/dist/cli.js +5 -1
- package/dist/index.cjs +339 -22
- package/dist/index.d.cts +172 -10
- package/dist/index.d.ts +172 -10
- package/dist/index.js +330 -21
- package/package.json +1 -1
package/dist/index.d.cts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/** Every code a PromptHelmError carries. The server checks fallback reports against this list. */
|
|
2
|
-
declare const ERROR_CODES: readonly ["unauthorized", "not_found", "missing_variables", "timeout", "network", "server"];
|
|
2
|
+
declare const ERROR_CODES: readonly ["unauthorized", "not_found", "missing_variables", "timeout", "network", "server", "api_mismatch"];
|
|
3
3
|
type PromptHelmErrorCode = (typeof ERROR_CODES)[number];
|
|
4
4
|
declare class PromptHelmError extends Error {
|
|
5
5
|
readonly code: PromptHelmErrorCode;
|
|
@@ -21,21 +21,89 @@ declare function render(template: string, vars?: Vars): string;
|
|
|
21
21
|
interface PromptPayload {
|
|
22
22
|
slug: string;
|
|
23
23
|
version: number;
|
|
24
|
+
/** The system message: every SDK serves it, and SDKs before 1.5 serve nothing else. */
|
|
24
25
|
content: string;
|
|
26
|
+
/** The variables `content` uses. */
|
|
25
27
|
variables: string[];
|
|
28
|
+
/** The user message, when the version has one; servers before SDK 1.5 send none. */
|
|
29
|
+
user?: PromptMessage;
|
|
26
30
|
/** The version's model settings; servers before SDK 1.4 send none. */
|
|
27
31
|
config?: PromptConfig;
|
|
28
32
|
/** An A/B test running on the prompt: the live version above is its control. */
|
|
29
33
|
experiment?: PromptExperiment;
|
|
30
34
|
}
|
|
35
|
+
/** A message besides the system one, with the variables it uses. */
|
|
36
|
+
interface PromptMessage {
|
|
37
|
+
content: string;
|
|
38
|
+
variables: string[];
|
|
39
|
+
}
|
|
40
|
+
/** The APIs a version can be called with, as `config.apis` and the `api` option name them. */
|
|
41
|
+
declare const PROMPT_APIS: readonly ["openai-responses", "chat-completions", "anthropic-messages", "gemini", "bedrock-converse"];
|
|
42
|
+
type PromptApi = (typeof PROMPT_APIS)[number];
|
|
43
|
+
/**
|
|
44
|
+
* Sent with each request for a slug a call asked for with `api`: the API the app calls the model
|
|
45
|
+
* with, so the prompt's page can warn before publishing a version for another one.
|
|
46
|
+
*/
|
|
47
|
+
declare const API_HEADER = "x-prompthelm-api";
|
|
31
48
|
/**
|
|
32
49
|
* Model settings published with a version, for your model call. Only the ones set in the
|
|
33
|
-
* dashboard are present; for the rest, your code's defaults apply.
|
|
50
|
+
* dashboard are present; for the rest, your code's defaults apply. The request builders
|
|
51
|
+
* (`toAnthropic` and the others) put them where each API wants them.
|
|
34
52
|
*/
|
|
35
53
|
interface PromptConfig {
|
|
36
54
|
model?: string;
|
|
37
55
|
temperature?: number;
|
|
38
56
|
maxTokens?: number;
|
|
57
|
+
/** How the model must answer; absent when it answers in text. Servers before SDK 1.5 send none. */
|
|
58
|
+
response?: PromptResponse;
|
|
59
|
+
/** Where the model is called: a provider id of PromptHelm's catalog, such as "azure". */
|
|
60
|
+
provider?: string;
|
|
61
|
+
/**
|
|
62
|
+
* The APIs the model can be called with there, as PromptHelm's catalog knows them (OpenAI's
|
|
63
|
+
* models take Responses and Chat Completions); absent when it doesn't know the model.
|
|
64
|
+
*/
|
|
65
|
+
apis?: PromptApi[];
|
|
66
|
+
/** How to reach the provider, for building your client (`clientOptions`). */
|
|
67
|
+
connection?: PromptConnection;
|
|
68
|
+
/** Where the model stops writing. */
|
|
69
|
+
stop?: string[];
|
|
70
|
+
/** How long your app waits for the model, in ms. */
|
|
71
|
+
timeoutMs?: number;
|
|
72
|
+
/** How many more times your app tries a failed model call. */
|
|
73
|
+
maxRetries?: number;
|
|
74
|
+
/** Parameters of your own, passed to the provider as written. */
|
|
75
|
+
extra?: {
|
|
76
|
+
[key: string]: unknown;
|
|
77
|
+
};
|
|
78
|
+
}
|
|
79
|
+
/** How to reach the provider; only the fields set in the dashboard are present. */
|
|
80
|
+
interface PromptConnection {
|
|
81
|
+
/** The API's address, for a proxy or a compatible server. */
|
|
82
|
+
baseUrl?: string;
|
|
83
|
+
/** Bedrock's endpoint of your own, or a Foundry resource's address. */
|
|
84
|
+
endpointUrl?: string;
|
|
85
|
+
/** Bedrock: the AWS Region. */
|
|
86
|
+
region?: string;
|
|
87
|
+
/** Bedrock: Runtime or Mantle. */
|
|
88
|
+
endpoint?: "runtime" | "mantle";
|
|
89
|
+
/** Bedrock Runtime: Converse or InvokeModel. */
|
|
90
|
+
api?: "converse" | "invoke-model";
|
|
91
|
+
/** Vertex AI: the location, such as "us-central1" or "global". */
|
|
92
|
+
location?: string;
|
|
93
|
+
/** Databricks: the workspace's address. */
|
|
94
|
+
workspaceUrl?: string;
|
|
95
|
+
}
|
|
96
|
+
/**
|
|
97
|
+
* An answer in JSON that matches `schema`: a JSON Schema (2020-12) kept inside what OpenAI,
|
|
98
|
+
* Anthropic, Gemini and Bedrock all accept. Hand it to your provider's structured output.
|
|
99
|
+
*/
|
|
100
|
+
interface PromptResponse {
|
|
101
|
+
type: "json";
|
|
102
|
+
/** A name for the schema, made from the prompt's slug; OpenAI and Bedrock ask for one. */
|
|
103
|
+
name: string;
|
|
104
|
+
schema: {
|
|
105
|
+
[key: string]: unknown;
|
|
106
|
+
};
|
|
39
107
|
}
|
|
40
108
|
interface PromptExperiment {
|
|
41
109
|
id: string;
|
|
@@ -45,9 +113,16 @@ interface PromptExperiment {
|
|
|
45
113
|
version: number;
|
|
46
114
|
content: string;
|
|
47
115
|
variables: string[];
|
|
116
|
+
user?: PromptMessage;
|
|
48
117
|
config?: PromptConfig;
|
|
49
118
|
};
|
|
50
119
|
}
|
|
120
|
+
/** A fallback with both messages, for a prompt that has a user message. */
|
|
121
|
+
interface PromptFallback {
|
|
122
|
+
system: string;
|
|
123
|
+
/** Left out: `user` is null when the fallback is served. */
|
|
124
|
+
user?: string;
|
|
125
|
+
}
|
|
51
126
|
/**
|
|
52
127
|
* Sent with the next request for a slug after `get()` couldn't serve its live text: the error's
|
|
53
128
|
* code alone, never any text or variable value. The server records it for the prompt page.
|
|
@@ -58,8 +133,9 @@ interface PromptListPayload {
|
|
|
58
133
|
prompts: PromptPayload[];
|
|
59
134
|
}
|
|
60
135
|
/**
|
|
61
|
-
* Body of `POST /v1/reports`: what an app counted under running A/B tests since its last report
|
|
62
|
-
* Numbers only, never any text,
|
|
136
|
+
* Body of `POST /v1/reports`: what an app counted under running A/B tests since its last report,
|
|
137
|
+
* and the model calls its provider refused. Numbers and error codes only, never any text,
|
|
138
|
+
* variable value or unit.
|
|
63
139
|
*/
|
|
64
140
|
interface ReportPayload {
|
|
65
141
|
experiments: {
|
|
@@ -69,6 +145,21 @@ interface ReportPayload {
|
|
|
69
145
|
/** By version number. */
|
|
70
146
|
versions: Record<string, ReportCounts>;
|
|
71
147
|
}[];
|
|
148
|
+
/** Model calls the provider refused, by version and error (`failed`, SDK 1.6). */
|
|
149
|
+
failures?: FailureCount[];
|
|
150
|
+
}
|
|
151
|
+
/** How many calls of a version the provider refused with one error. Never its message. */
|
|
152
|
+
interface FailureCount {
|
|
153
|
+
slug: string;
|
|
154
|
+
version: number;
|
|
155
|
+
/** The HTTP status the provider answered. */
|
|
156
|
+
status: number;
|
|
157
|
+
/** The error's type, as the provider's SDK gives it apart from the message. */
|
|
158
|
+
type?: string;
|
|
159
|
+
code?: string;
|
|
160
|
+
/** The parameter it refused, where the provider names it (OpenAI). */
|
|
161
|
+
param?: string;
|
|
162
|
+
count: number;
|
|
72
163
|
}
|
|
73
164
|
interface ReportCounts {
|
|
74
165
|
served: number;
|
|
@@ -109,6 +200,11 @@ interface PromptHelmOptions {
|
|
|
109
200
|
* `reportFallbacks`.
|
|
110
201
|
*/
|
|
111
202
|
reportResults?: boolean;
|
|
203
|
+
/**
|
|
204
|
+
* Whether `failed` tells PromptHelm, by HTTP status and error code only, that the provider
|
|
205
|
+
* refused a version's call. Defaults to `reportFallbacks`.
|
|
206
|
+
*/
|
|
207
|
+
reportFailures?: boolean;
|
|
112
208
|
/** Called on every `get` and `resolve`, so your analytics or traces can carry the version. */
|
|
113
209
|
onResolve?: (event: ResolveEvent) => void;
|
|
114
210
|
}
|
|
@@ -116,9 +212,10 @@ interface GetOptions {
|
|
|
116
212
|
vars?: Vars;
|
|
117
213
|
/**
|
|
118
214
|
* Served when PromptHelm can't be reached, the prompt doesn't exist, or the live
|
|
119
|
-
* version uses a variable this call doesn't pass. Without it those cases throw.
|
|
215
|
+
* version uses a variable this call doesn't pass. Without it those cases throw. A string is
|
|
216
|
+
* the system message; `{ system, user }` gives both, filled in like the live version.
|
|
120
217
|
*/
|
|
121
|
-
fallback?: string;
|
|
218
|
+
fallback?: string | PromptFallback;
|
|
122
219
|
/**
|
|
123
220
|
* Who the call is for, such as a user or conversation id: during an A/B test the same unit
|
|
124
221
|
* always gets the same version. Never sent to PromptHelm.
|
|
@@ -126,6 +223,12 @@ interface GetOptions {
|
|
|
126
223
|
unit?: string | number;
|
|
127
224
|
/** During an A/B test, serves this side, such as the variant to your own team. Never counted. */
|
|
128
225
|
force?: "control" | "variant";
|
|
226
|
+
/**
|
|
227
|
+
* The API your app calls the model with. A version whose model can't be called with it isn't
|
|
228
|
+
* served: the call gets its fallback (`api_mismatch`), and the prompt's page warns before
|
|
229
|
+
* publishing one.
|
|
230
|
+
*/
|
|
231
|
+
api?: PromptApi;
|
|
129
232
|
}
|
|
130
233
|
interface ResolveEvent {
|
|
131
234
|
slug: string;
|
|
@@ -137,7 +240,12 @@ interface ResolveEvent {
|
|
|
137
240
|
variant: boolean;
|
|
138
241
|
}
|
|
139
242
|
interface Resolved {
|
|
243
|
+
/** The system message, filled in: what `get` returns. */
|
|
140
244
|
text: string;
|
|
245
|
+
/** The same as `text`, named after the message it is. */
|
|
246
|
+
system: string;
|
|
247
|
+
/** The user message, filled in; null when the version has none, so your app sends its own. */
|
|
248
|
+
user: string | null;
|
|
141
249
|
/**
|
|
142
250
|
* The served version's model settings, such as `model`. Empty when the fallback was served,
|
|
143
251
|
* so your code's defaults apply.
|
|
@@ -145,6 +253,8 @@ interface Resolved {
|
|
|
145
253
|
config: PromptConfig;
|
|
146
254
|
/** The version served, or null when the fallback was. */
|
|
147
255
|
version: number | null;
|
|
256
|
+
/** The API the call asked for (`api`), which `clientOptions` builds for; null when it named none. */
|
|
257
|
+
api: PromptApi | null;
|
|
148
258
|
/**
|
|
149
259
|
* During an A/B test, names the test and the version this call got, so its outcome can be
|
|
150
260
|
* reported later from any process: `ph.outcome(ticket, true)`. No user in it. Null otherwise.
|
|
@@ -157,13 +267,24 @@ interface Resolved {
|
|
|
157
267
|
* else the time since `resolve` returned. The first report counts.
|
|
158
268
|
*/
|
|
159
269
|
usage(usage: object | null | undefined, ms?: number): void;
|
|
270
|
+
/**
|
|
271
|
+
* The provider refused the model call: pass its error. Only its HTTP status, type, code and the
|
|
272
|
+
* parameter it names are sent, never its message. The first report counts.
|
|
273
|
+
*/
|
|
274
|
+
failed(error: unknown): void;
|
|
160
275
|
}
|
|
161
276
|
declare class PromptHelm {
|
|
162
277
|
#private;
|
|
163
278
|
constructor(options?: PromptHelmOptions);
|
|
164
|
-
/**
|
|
279
|
+
/**
|
|
280
|
+
* The live version's system message with its variables filled in. It never needs the user
|
|
281
|
+
* message's variables: an app that calls `get` sends its own.
|
|
282
|
+
*/
|
|
165
283
|
get(slug: string, options?: GetOptions): Promise<string>;
|
|
166
|
-
/**
|
|
284
|
+
/**
|
|
285
|
+
* Like `get`, with the user message too, the model settings, and which version was served, so
|
|
286
|
+
* you can tag your logs or traces with it.
|
|
287
|
+
*/
|
|
167
288
|
resolve(slug: string, options?: GetOptions): Promise<Resolved>;
|
|
168
289
|
/** Reports the outcome of a call made earlier, by its `ticket`. Ignores anything else. */
|
|
169
290
|
outcome(ticket: string, value: boolean | number): void;
|
|
@@ -174,6 +295,47 @@ declare class PromptHelm {
|
|
|
174
295
|
flush(): Promise<void>;
|
|
175
296
|
}
|
|
176
297
|
|
|
298
|
+
/** The second argument of `create()` in the OpenAI and Anthropic SDKs. */
|
|
299
|
+
interface RequestOptions {
|
|
300
|
+
/** In ms. */
|
|
301
|
+
timeout?: number;
|
|
302
|
+
maxRetries?: number;
|
|
303
|
+
}
|
|
304
|
+
interface ModelRequest<T> {
|
|
305
|
+
/** Your request with the version's messages and settings in. */
|
|
306
|
+
params: T;
|
|
307
|
+
/** Empty unless the dashboard set a timeout or retries. */
|
|
308
|
+
options: RequestOptions;
|
|
309
|
+
}
|
|
310
|
+
/** OpenAI's Responses API (`client.responses.create`). It takes no stop sequences. */
|
|
311
|
+
declare function toOpenAIResponses<T extends object>(r: Resolved, base: T): ModelRequest<T>;
|
|
312
|
+
/**
|
|
313
|
+
* Chat Completions (`client.chat.completions.create`), OpenAI's and every compatible host's. Your
|
|
314
|
+
* own system message gives way to the version's.
|
|
315
|
+
*/
|
|
316
|
+
declare function toChatCompletions<T extends object>(r: Resolved, base: T): ModelRequest<T>;
|
|
317
|
+
/** Anthropic's Messages API (`client.messages.create`), on Anthropic or a cloud. */
|
|
318
|
+
declare function toAnthropic<T extends object>(r: Resolved, base: T): ModelRequest<T>;
|
|
319
|
+
/**
|
|
320
|
+
* Gemini's `generateContent` (`ai.models.generateContent`, `@google/genai`), on the Gemini API or
|
|
321
|
+
* Vertex AI. Everything goes in the request, timeout and extra parameters too; retries are the
|
|
322
|
+
* client's (`clientOptions`).
|
|
323
|
+
*/
|
|
324
|
+
declare function toGemini<T extends object>(r: Resolved, base: T): ModelRequest<T>;
|
|
325
|
+
/**
|
|
326
|
+
* Bedrock's Converse API: the input of `new ConverseCommand(…)`. The schema goes as text, as
|
|
327
|
+
* Converse takes it; extra parameters go in `additionalModelRequestFields`. Timeout and retries
|
|
328
|
+
* are the client's (`clientOptions`).
|
|
329
|
+
*/
|
|
330
|
+
declare function toBedrockConverse<T extends object>(r: Resolved, base: T): ModelRequest<T>;
|
|
331
|
+
/**
|
|
332
|
+
* Your client's options with what the dashboard set for reaching the provider: its address,
|
|
333
|
+
* Region or location, timeout and retries, in the names that API's official SDK uses. Keys stay
|
|
334
|
+
* yours. It builds for the API the call named (`resolve`'s `api`), else the first the version's
|
|
335
|
+
* model takes. Build a client from it when the version's `config.connection` changes.
|
|
336
|
+
*/
|
|
337
|
+
declare function clientOptions<T extends object>(r: Resolved, base: T): T;
|
|
338
|
+
|
|
177
339
|
declare const LATENCY_BUCKETS = 24;
|
|
178
340
|
/**
|
|
179
341
|
* Which of 24 latency buckets a model call's duration falls in, for its percentiles: bucket i
|
|
@@ -181,5 +343,5 @@ declare const LATENCY_BUCKETS = 24;
|
|
|
181
343
|
*/
|
|
182
344
|
declare function latencyBucket(ms: number): number;
|
|
183
345
|
|
|
184
|
-
export { ERROR_CODES, FALLBACK_HEADER, LATENCY_BUCKETS, PromptHelm, PromptHelmError, extractVariables, latencyBucket, render };
|
|
185
|
-
export type { GetOptions, PromptConfig, PromptExperiment, PromptHelmErrorCode, PromptHelmOptions, PromptListPayload, PromptPayload, ReportCounts, ReportPayload, ResolveEvent, Resolved, Vars };
|
|
346
|
+
export { API_HEADER, ERROR_CODES, FALLBACK_HEADER, LATENCY_BUCKETS, PROMPT_APIS, PromptHelm, PromptHelmError, clientOptions, extractVariables, latencyBucket, render, toAnthropic, toBedrockConverse, toChatCompletions, toGemini, toOpenAIResponses };
|
|
347
|
+
export type { FailureCount, GetOptions, ModelRequest, PromptApi, PromptConfig, PromptConnection, PromptExperiment, PromptFallback, PromptHelmErrorCode, PromptHelmOptions, PromptListPayload, PromptMessage, PromptPayload, PromptResponse, ReportCounts, ReportPayload, RequestOptions, ResolveEvent, Resolved, Vars };
|
package/dist/index.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/** Every code a PromptHelmError carries. The server checks fallback reports against this list. */
|
|
2
|
-
declare const ERROR_CODES: readonly ["unauthorized", "not_found", "missing_variables", "timeout", "network", "server"];
|
|
2
|
+
declare const ERROR_CODES: readonly ["unauthorized", "not_found", "missing_variables", "timeout", "network", "server", "api_mismatch"];
|
|
3
3
|
type PromptHelmErrorCode = (typeof ERROR_CODES)[number];
|
|
4
4
|
declare class PromptHelmError extends Error {
|
|
5
5
|
readonly code: PromptHelmErrorCode;
|
|
@@ -21,21 +21,89 @@ declare function render(template: string, vars?: Vars): string;
|
|
|
21
21
|
interface PromptPayload {
|
|
22
22
|
slug: string;
|
|
23
23
|
version: number;
|
|
24
|
+
/** The system message: every SDK serves it, and SDKs before 1.5 serve nothing else. */
|
|
24
25
|
content: string;
|
|
26
|
+
/** The variables `content` uses. */
|
|
25
27
|
variables: string[];
|
|
28
|
+
/** The user message, when the version has one; servers before SDK 1.5 send none. */
|
|
29
|
+
user?: PromptMessage;
|
|
26
30
|
/** The version's model settings; servers before SDK 1.4 send none. */
|
|
27
31
|
config?: PromptConfig;
|
|
28
32
|
/** An A/B test running on the prompt: the live version above is its control. */
|
|
29
33
|
experiment?: PromptExperiment;
|
|
30
34
|
}
|
|
35
|
+
/** A message besides the system one, with the variables it uses. */
|
|
36
|
+
interface PromptMessage {
|
|
37
|
+
content: string;
|
|
38
|
+
variables: string[];
|
|
39
|
+
}
|
|
40
|
+
/** The APIs a version can be called with, as `config.apis` and the `api` option name them. */
|
|
41
|
+
declare const PROMPT_APIS: readonly ["openai-responses", "chat-completions", "anthropic-messages", "gemini", "bedrock-converse"];
|
|
42
|
+
type PromptApi = (typeof PROMPT_APIS)[number];
|
|
43
|
+
/**
|
|
44
|
+
* Sent with each request for a slug a call asked for with `api`: the API the app calls the model
|
|
45
|
+
* with, so the prompt's page can warn before publishing a version for another one.
|
|
46
|
+
*/
|
|
47
|
+
declare const API_HEADER = "x-prompthelm-api";
|
|
31
48
|
/**
|
|
32
49
|
* Model settings published with a version, for your model call. Only the ones set in the
|
|
33
|
-
* dashboard are present; for the rest, your code's defaults apply.
|
|
50
|
+
* dashboard are present; for the rest, your code's defaults apply. The request builders
|
|
51
|
+
* (`toAnthropic` and the others) put them where each API wants them.
|
|
34
52
|
*/
|
|
35
53
|
interface PromptConfig {
|
|
36
54
|
model?: string;
|
|
37
55
|
temperature?: number;
|
|
38
56
|
maxTokens?: number;
|
|
57
|
+
/** How the model must answer; absent when it answers in text. Servers before SDK 1.5 send none. */
|
|
58
|
+
response?: PromptResponse;
|
|
59
|
+
/** Where the model is called: a provider id of PromptHelm's catalog, such as "azure". */
|
|
60
|
+
provider?: string;
|
|
61
|
+
/**
|
|
62
|
+
* The APIs the model can be called with there, as PromptHelm's catalog knows them (OpenAI's
|
|
63
|
+
* models take Responses and Chat Completions); absent when it doesn't know the model.
|
|
64
|
+
*/
|
|
65
|
+
apis?: PromptApi[];
|
|
66
|
+
/** How to reach the provider, for building your client (`clientOptions`). */
|
|
67
|
+
connection?: PromptConnection;
|
|
68
|
+
/** Where the model stops writing. */
|
|
69
|
+
stop?: string[];
|
|
70
|
+
/** How long your app waits for the model, in ms. */
|
|
71
|
+
timeoutMs?: number;
|
|
72
|
+
/** How many more times your app tries a failed model call. */
|
|
73
|
+
maxRetries?: number;
|
|
74
|
+
/** Parameters of your own, passed to the provider as written. */
|
|
75
|
+
extra?: {
|
|
76
|
+
[key: string]: unknown;
|
|
77
|
+
};
|
|
78
|
+
}
|
|
79
|
+
/** How to reach the provider; only the fields set in the dashboard are present. */
|
|
80
|
+
interface PromptConnection {
|
|
81
|
+
/** The API's address, for a proxy or a compatible server. */
|
|
82
|
+
baseUrl?: string;
|
|
83
|
+
/** Bedrock's endpoint of your own, or a Foundry resource's address. */
|
|
84
|
+
endpointUrl?: string;
|
|
85
|
+
/** Bedrock: the AWS Region. */
|
|
86
|
+
region?: string;
|
|
87
|
+
/** Bedrock: Runtime or Mantle. */
|
|
88
|
+
endpoint?: "runtime" | "mantle";
|
|
89
|
+
/** Bedrock Runtime: Converse or InvokeModel. */
|
|
90
|
+
api?: "converse" | "invoke-model";
|
|
91
|
+
/** Vertex AI: the location, such as "us-central1" or "global". */
|
|
92
|
+
location?: string;
|
|
93
|
+
/** Databricks: the workspace's address. */
|
|
94
|
+
workspaceUrl?: string;
|
|
95
|
+
}
|
|
96
|
+
/**
|
|
97
|
+
* An answer in JSON that matches `schema`: a JSON Schema (2020-12) kept inside what OpenAI,
|
|
98
|
+
* Anthropic, Gemini and Bedrock all accept. Hand it to your provider's structured output.
|
|
99
|
+
*/
|
|
100
|
+
interface PromptResponse {
|
|
101
|
+
type: "json";
|
|
102
|
+
/** A name for the schema, made from the prompt's slug; OpenAI and Bedrock ask for one. */
|
|
103
|
+
name: string;
|
|
104
|
+
schema: {
|
|
105
|
+
[key: string]: unknown;
|
|
106
|
+
};
|
|
39
107
|
}
|
|
40
108
|
interface PromptExperiment {
|
|
41
109
|
id: string;
|
|
@@ -45,9 +113,16 @@ interface PromptExperiment {
|
|
|
45
113
|
version: number;
|
|
46
114
|
content: string;
|
|
47
115
|
variables: string[];
|
|
116
|
+
user?: PromptMessage;
|
|
48
117
|
config?: PromptConfig;
|
|
49
118
|
};
|
|
50
119
|
}
|
|
120
|
+
/** A fallback with both messages, for a prompt that has a user message. */
|
|
121
|
+
interface PromptFallback {
|
|
122
|
+
system: string;
|
|
123
|
+
/** Left out: `user` is null when the fallback is served. */
|
|
124
|
+
user?: string;
|
|
125
|
+
}
|
|
51
126
|
/**
|
|
52
127
|
* Sent with the next request for a slug after `get()` couldn't serve its live text: the error's
|
|
53
128
|
* code alone, never any text or variable value. The server records it for the prompt page.
|
|
@@ -58,8 +133,9 @@ interface PromptListPayload {
|
|
|
58
133
|
prompts: PromptPayload[];
|
|
59
134
|
}
|
|
60
135
|
/**
|
|
61
|
-
* Body of `POST /v1/reports`: what an app counted under running A/B tests since its last report
|
|
62
|
-
* Numbers only, never any text,
|
|
136
|
+
* Body of `POST /v1/reports`: what an app counted under running A/B tests since its last report,
|
|
137
|
+
* and the model calls its provider refused. Numbers and error codes only, never any text,
|
|
138
|
+
* variable value or unit.
|
|
63
139
|
*/
|
|
64
140
|
interface ReportPayload {
|
|
65
141
|
experiments: {
|
|
@@ -69,6 +145,21 @@ interface ReportPayload {
|
|
|
69
145
|
/** By version number. */
|
|
70
146
|
versions: Record<string, ReportCounts>;
|
|
71
147
|
}[];
|
|
148
|
+
/** Model calls the provider refused, by version and error (`failed`, SDK 1.6). */
|
|
149
|
+
failures?: FailureCount[];
|
|
150
|
+
}
|
|
151
|
+
/** How many calls of a version the provider refused with one error. Never its message. */
|
|
152
|
+
interface FailureCount {
|
|
153
|
+
slug: string;
|
|
154
|
+
version: number;
|
|
155
|
+
/** The HTTP status the provider answered. */
|
|
156
|
+
status: number;
|
|
157
|
+
/** The error's type, as the provider's SDK gives it apart from the message. */
|
|
158
|
+
type?: string;
|
|
159
|
+
code?: string;
|
|
160
|
+
/** The parameter it refused, where the provider names it (OpenAI). */
|
|
161
|
+
param?: string;
|
|
162
|
+
count: number;
|
|
72
163
|
}
|
|
73
164
|
interface ReportCounts {
|
|
74
165
|
served: number;
|
|
@@ -109,6 +200,11 @@ interface PromptHelmOptions {
|
|
|
109
200
|
* `reportFallbacks`.
|
|
110
201
|
*/
|
|
111
202
|
reportResults?: boolean;
|
|
203
|
+
/**
|
|
204
|
+
* Whether `failed` tells PromptHelm, by HTTP status and error code only, that the provider
|
|
205
|
+
* refused a version's call. Defaults to `reportFallbacks`.
|
|
206
|
+
*/
|
|
207
|
+
reportFailures?: boolean;
|
|
112
208
|
/** Called on every `get` and `resolve`, so your analytics or traces can carry the version. */
|
|
113
209
|
onResolve?: (event: ResolveEvent) => void;
|
|
114
210
|
}
|
|
@@ -116,9 +212,10 @@ interface GetOptions {
|
|
|
116
212
|
vars?: Vars;
|
|
117
213
|
/**
|
|
118
214
|
* Served when PromptHelm can't be reached, the prompt doesn't exist, or the live
|
|
119
|
-
* version uses a variable this call doesn't pass. Without it those cases throw.
|
|
215
|
+
* version uses a variable this call doesn't pass. Without it those cases throw. A string is
|
|
216
|
+
* the system message; `{ system, user }` gives both, filled in like the live version.
|
|
120
217
|
*/
|
|
121
|
-
fallback?: string;
|
|
218
|
+
fallback?: string | PromptFallback;
|
|
122
219
|
/**
|
|
123
220
|
* Who the call is for, such as a user or conversation id: during an A/B test the same unit
|
|
124
221
|
* always gets the same version. Never sent to PromptHelm.
|
|
@@ -126,6 +223,12 @@ interface GetOptions {
|
|
|
126
223
|
unit?: string | number;
|
|
127
224
|
/** During an A/B test, serves this side, such as the variant to your own team. Never counted. */
|
|
128
225
|
force?: "control" | "variant";
|
|
226
|
+
/**
|
|
227
|
+
* The API your app calls the model with. A version whose model can't be called with it isn't
|
|
228
|
+
* served: the call gets its fallback (`api_mismatch`), and the prompt's page warns before
|
|
229
|
+
* publishing one.
|
|
230
|
+
*/
|
|
231
|
+
api?: PromptApi;
|
|
129
232
|
}
|
|
130
233
|
interface ResolveEvent {
|
|
131
234
|
slug: string;
|
|
@@ -137,7 +240,12 @@ interface ResolveEvent {
|
|
|
137
240
|
variant: boolean;
|
|
138
241
|
}
|
|
139
242
|
interface Resolved {
|
|
243
|
+
/** The system message, filled in: what `get` returns. */
|
|
140
244
|
text: string;
|
|
245
|
+
/** The same as `text`, named after the message it is. */
|
|
246
|
+
system: string;
|
|
247
|
+
/** The user message, filled in; null when the version has none, so your app sends its own. */
|
|
248
|
+
user: string | null;
|
|
141
249
|
/**
|
|
142
250
|
* The served version's model settings, such as `model`. Empty when the fallback was served,
|
|
143
251
|
* so your code's defaults apply.
|
|
@@ -145,6 +253,8 @@ interface Resolved {
|
|
|
145
253
|
config: PromptConfig;
|
|
146
254
|
/** The version served, or null when the fallback was. */
|
|
147
255
|
version: number | null;
|
|
256
|
+
/** The API the call asked for (`api`), which `clientOptions` builds for; null when it named none. */
|
|
257
|
+
api: PromptApi | null;
|
|
148
258
|
/**
|
|
149
259
|
* During an A/B test, names the test and the version this call got, so its outcome can be
|
|
150
260
|
* reported later from any process: `ph.outcome(ticket, true)`. No user in it. Null otherwise.
|
|
@@ -157,13 +267,24 @@ interface Resolved {
|
|
|
157
267
|
* else the time since `resolve` returned. The first report counts.
|
|
158
268
|
*/
|
|
159
269
|
usage(usage: object | null | undefined, ms?: number): void;
|
|
270
|
+
/**
|
|
271
|
+
* The provider refused the model call: pass its error. Only its HTTP status, type, code and the
|
|
272
|
+
* parameter it names are sent, never its message. The first report counts.
|
|
273
|
+
*/
|
|
274
|
+
failed(error: unknown): void;
|
|
160
275
|
}
|
|
161
276
|
declare class PromptHelm {
|
|
162
277
|
#private;
|
|
163
278
|
constructor(options?: PromptHelmOptions);
|
|
164
|
-
/**
|
|
279
|
+
/**
|
|
280
|
+
* The live version's system message with its variables filled in. It never needs the user
|
|
281
|
+
* message's variables: an app that calls `get` sends its own.
|
|
282
|
+
*/
|
|
165
283
|
get(slug: string, options?: GetOptions): Promise<string>;
|
|
166
|
-
/**
|
|
284
|
+
/**
|
|
285
|
+
* Like `get`, with the user message too, the model settings, and which version was served, so
|
|
286
|
+
* you can tag your logs or traces with it.
|
|
287
|
+
*/
|
|
167
288
|
resolve(slug: string, options?: GetOptions): Promise<Resolved>;
|
|
168
289
|
/** Reports the outcome of a call made earlier, by its `ticket`. Ignores anything else. */
|
|
169
290
|
outcome(ticket: string, value: boolean | number): void;
|
|
@@ -174,6 +295,47 @@ declare class PromptHelm {
|
|
|
174
295
|
flush(): Promise<void>;
|
|
175
296
|
}
|
|
176
297
|
|
|
298
|
+
/** The second argument of `create()` in the OpenAI and Anthropic SDKs. */
|
|
299
|
+
interface RequestOptions {
|
|
300
|
+
/** In ms. */
|
|
301
|
+
timeout?: number;
|
|
302
|
+
maxRetries?: number;
|
|
303
|
+
}
|
|
304
|
+
interface ModelRequest<T> {
|
|
305
|
+
/** Your request with the version's messages and settings in. */
|
|
306
|
+
params: T;
|
|
307
|
+
/** Empty unless the dashboard set a timeout or retries. */
|
|
308
|
+
options: RequestOptions;
|
|
309
|
+
}
|
|
310
|
+
/** OpenAI's Responses API (`client.responses.create`). It takes no stop sequences. */
|
|
311
|
+
declare function toOpenAIResponses<T extends object>(r: Resolved, base: T): ModelRequest<T>;
|
|
312
|
+
/**
|
|
313
|
+
* Chat Completions (`client.chat.completions.create`), OpenAI's and every compatible host's. Your
|
|
314
|
+
* own system message gives way to the version's.
|
|
315
|
+
*/
|
|
316
|
+
declare function toChatCompletions<T extends object>(r: Resolved, base: T): ModelRequest<T>;
|
|
317
|
+
/** Anthropic's Messages API (`client.messages.create`), on Anthropic or a cloud. */
|
|
318
|
+
declare function toAnthropic<T extends object>(r: Resolved, base: T): ModelRequest<T>;
|
|
319
|
+
/**
|
|
320
|
+
* Gemini's `generateContent` (`ai.models.generateContent`, `@google/genai`), on the Gemini API or
|
|
321
|
+
* Vertex AI. Everything goes in the request, timeout and extra parameters too; retries are the
|
|
322
|
+
* client's (`clientOptions`).
|
|
323
|
+
*/
|
|
324
|
+
declare function toGemini<T extends object>(r: Resolved, base: T): ModelRequest<T>;
|
|
325
|
+
/**
|
|
326
|
+
* Bedrock's Converse API: the input of `new ConverseCommand(…)`. The schema goes as text, as
|
|
327
|
+
* Converse takes it; extra parameters go in `additionalModelRequestFields`. Timeout and retries
|
|
328
|
+
* are the client's (`clientOptions`).
|
|
329
|
+
*/
|
|
330
|
+
declare function toBedrockConverse<T extends object>(r: Resolved, base: T): ModelRequest<T>;
|
|
331
|
+
/**
|
|
332
|
+
* Your client's options with what the dashboard set for reaching the provider: its address,
|
|
333
|
+
* Region or location, timeout and retries, in the names that API's official SDK uses. Keys stay
|
|
334
|
+
* yours. It builds for the API the call named (`resolve`'s `api`), else the first the version's
|
|
335
|
+
* model takes. Build a client from it when the version's `config.connection` changes.
|
|
336
|
+
*/
|
|
337
|
+
declare function clientOptions<T extends object>(r: Resolved, base: T): T;
|
|
338
|
+
|
|
177
339
|
declare const LATENCY_BUCKETS = 24;
|
|
178
340
|
/**
|
|
179
341
|
* Which of 24 latency buckets a model call's duration falls in, for its percentiles: bucket i
|
|
@@ -181,5 +343,5 @@ declare const LATENCY_BUCKETS = 24;
|
|
|
181
343
|
*/
|
|
182
344
|
declare function latencyBucket(ms: number): number;
|
|
183
345
|
|
|
184
|
-
export { ERROR_CODES, FALLBACK_HEADER, LATENCY_BUCKETS, PromptHelm, PromptHelmError, extractVariables, latencyBucket, render };
|
|
185
|
-
export type { GetOptions, PromptConfig, PromptExperiment, PromptHelmErrorCode, PromptHelmOptions, PromptListPayload, PromptPayload, ReportCounts, ReportPayload, ResolveEvent, Resolved, Vars };
|
|
346
|
+
export { API_HEADER, ERROR_CODES, FALLBACK_HEADER, LATENCY_BUCKETS, PROMPT_APIS, PromptHelm, PromptHelmError, clientOptions, extractVariables, latencyBucket, render, toAnthropic, toBedrockConverse, toChatCompletions, toGemini, toOpenAIResponses };
|
|
347
|
+
export type { FailureCount, GetOptions, ModelRequest, PromptApi, PromptConfig, PromptConnection, PromptExperiment, PromptFallback, PromptHelmErrorCode, PromptHelmOptions, PromptListPayload, PromptMessage, PromptPayload, PromptResponse, ReportCounts, ReportPayload, RequestOptions, ResolveEvent, Resolved, Vars };
|