notdiamond 2.0.0-rc5 → 2.1.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.
Files changed (144) hide show
  1. package/CHANGELOG.md +170 -0
  2. package/LICENSE +1 -1
  3. package/README.md +276 -148
  4. package/client.d.mts +16 -19
  5. package/client.d.mts.map +1 -1
  6. package/client.d.ts +16 -19
  7. package/client.d.ts.map +1 -1
  8. package/client.js +11 -14
  9. package/client.js.map +1 -1
  10. package/client.mjs +11 -14
  11. package/client.mjs.map +1 -1
  12. package/internal/tslib.js +17 -17
  13. package/package.json +3 -3
  14. package/resources/{pzn.d.mts → custom-router.d.mts} +16 -96
  15. package/resources/custom-router.d.mts.map +1 -0
  16. package/resources/{pzn.d.ts → custom-router.d.ts} +16 -96
  17. package/resources/custom-router.d.ts.map +1 -0
  18. package/resources/{pzn.js → custom-router.js} +13 -50
  19. package/resources/custom-router.js.map +1 -0
  20. package/resources/{pzn.mjs → custom-router.mjs} +11 -48
  21. package/resources/custom-router.mjs.map +1 -0
  22. package/resources/index.d.mts +4 -5
  23. package/resources/index.d.mts.map +1 -1
  24. package/resources/index.d.ts +4 -5
  25. package/resources/index.d.ts.map +1 -1
  26. package/resources/index.js +5 -7
  27. package/resources/index.js.map +1 -1
  28. package/resources/index.mjs +2 -3
  29. package/resources/index.mjs.map +1 -1
  30. package/resources/model-router.d.mts +6 -123
  31. package/resources/model-router.d.mts.map +1 -1
  32. package/resources/model-router.d.ts +6 -123
  33. package/resources/model-router.d.ts.map +1 -1
  34. package/resources/model-router.js +3 -32
  35. package/resources/model-router.js.map +1 -1
  36. package/resources/model-router.mjs +3 -32
  37. package/resources/model-router.mjs.map +1 -1
  38. package/resources/preferences.d.mts +4 -23
  39. package/resources/preferences.d.mts.map +1 -1
  40. package/resources/preferences.d.ts +4 -23
  41. package/resources/preferences.d.ts.map +1 -1
  42. package/resources/preferences.js +3 -25
  43. package/resources/preferences.js.map +1 -1
  44. package/resources/preferences.mjs +3 -25
  45. package/resources/preferences.mjs.map +1 -1
  46. package/resources/prompt-adaptation.d.mts +687 -0
  47. package/resources/prompt-adaptation.d.mts.map +1 -0
  48. package/resources/prompt-adaptation.d.ts +687 -0
  49. package/resources/prompt-adaptation.d.ts.map +1 -0
  50. package/resources/prompt-adaptation.js +258 -0
  51. package/resources/prompt-adaptation.js.map +1 -0
  52. package/resources/prompt-adaptation.mjs +254 -0
  53. package/resources/prompt-adaptation.mjs.map +1 -0
  54. package/src/client.ts +37 -44
  55. package/src/resources/{pzn.ts → custom-router.ts} +17 -122
  56. package/src/resources/index.ts +14 -16
  57. package/src/resources/model-router.ts +5 -139
  58. package/src/resources/preferences.ts +3 -34
  59. package/src/resources/prompt-adaptation.ts +780 -0
  60. package/src/version.ts +1 -1
  61. package/version.d.mts +1 -1
  62. package/version.d.mts.map +1 -1
  63. package/version.d.ts +1 -1
  64. package/version.d.ts.map +1 -1
  65. package/version.js +1 -1
  66. package/version.js.map +1 -1
  67. package/version.mjs +1 -1
  68. package/version.mjs.map +1 -1
  69. package/resources/prompt/adapt.d.mts +0 -352
  70. package/resources/prompt/adapt.d.mts.map +0 -1
  71. package/resources/prompt/adapt.d.ts +0 -352
  72. package/resources/prompt/adapt.d.ts.map +0 -1
  73. package/resources/prompt/adapt.js +0 -154
  74. package/resources/prompt/adapt.js.map +0 -1
  75. package/resources/prompt/adapt.mjs +0 -150
  76. package/resources/prompt/adapt.mjs.map +0 -1
  77. package/resources/prompt/index.d.mts +0 -3
  78. package/resources/prompt/index.d.mts.map +0 -1
  79. package/resources/prompt/index.d.ts +0 -3
  80. package/resources/prompt/index.d.ts.map +0 -1
  81. package/resources/prompt/index.js +0 -9
  82. package/resources/prompt/index.js.map +0 -1
  83. package/resources/prompt/index.mjs +0 -4
  84. package/resources/prompt/index.mjs.map +0 -1
  85. package/resources/prompt/prompt.d.mts +0 -338
  86. package/resources/prompt/prompt.d.mts.map +0 -1
  87. package/resources/prompt/prompt.d.ts +0 -338
  88. package/resources/prompt/prompt.d.ts.map +0 -1
  89. package/resources/prompt/prompt.js +0 -128
  90. package/resources/prompt/prompt.js.map +0 -1
  91. package/resources/prompt/prompt.mjs +0 -123
  92. package/resources/prompt/prompt.mjs.map +0 -1
  93. package/resources/prompt.d.mts +0 -2
  94. package/resources/prompt.d.mts.map +0 -1
  95. package/resources/prompt.d.ts +0 -2
  96. package/resources/prompt.d.ts.map +0 -1
  97. package/resources/prompt.js +0 -6
  98. package/resources/prompt.js.map +0 -1
  99. package/resources/prompt.mjs +0 -3
  100. package/resources/prompt.mjs.map +0 -1
  101. package/resources/pzn.d.mts.map +0 -1
  102. package/resources/pzn.d.ts.map +0 -1
  103. package/resources/pzn.js.map +0 -1
  104. package/resources/pzn.mjs.map +0 -1
  105. package/resources/report/index.d.mts +0 -3
  106. package/resources/report/index.d.mts.map +0 -1
  107. package/resources/report/index.d.ts +0 -3
  108. package/resources/report/index.d.ts.map +0 -1
  109. package/resources/report/index.js +0 -9
  110. package/resources/report/index.js.map +0 -1
  111. package/resources/report/index.mjs +0 -4
  112. package/resources/report/index.mjs.map +0 -1
  113. package/resources/report/metrics.d.mts +0 -87
  114. package/resources/report/metrics.d.mts.map +0 -1
  115. package/resources/report/metrics.d.ts +0 -87
  116. package/resources/report/metrics.d.ts.map +0 -1
  117. package/resources/report/metrics.js +0 -57
  118. package/resources/report/metrics.js.map +0 -1
  119. package/resources/report/metrics.mjs +0 -53
  120. package/resources/report/metrics.mjs.map +0 -1
  121. package/resources/report/report.d.mts +0 -10
  122. package/resources/report/report.d.mts.map +0 -1
  123. package/resources/report/report.d.ts +0 -10
  124. package/resources/report/report.d.ts.map +0 -1
  125. package/resources/report/report.js +0 -17
  126. package/resources/report/report.js.map +0 -1
  127. package/resources/report/report.mjs +0 -12
  128. package/resources/report/report.mjs.map +0 -1
  129. package/resources/report.d.mts +0 -2
  130. package/resources/report.d.mts.map +0 -1
  131. package/resources/report.d.ts +0 -2
  132. package/resources/report.d.ts.map +0 -1
  133. package/resources/report.js +0 -6
  134. package/resources/report.js.map +0 -1
  135. package/resources/report.mjs +0 -3
  136. package/resources/report.mjs.map +0 -1
  137. package/src/resources/prompt/adapt.ts +0 -402
  138. package/src/resources/prompt/index.ts +0 -16
  139. package/src/resources/prompt/prompt.ts +0 -398
  140. package/src/resources/prompt.ts +0 -3
  141. package/src/resources/report/index.ts +0 -4
  142. package/src/resources/report/metrics.ts +0 -99
  143. package/src/resources/report/report.ts +0 -19
  144. package/src/resources/report.ts +0 -3
@@ -0,0 +1,687 @@
1
+ import { APIResource } from "../core/resource.js";
2
+ import * as PromptAdaptationAPI from "./prompt-adaptation.js";
3
+ import { APIPromise } from "../core/api-promise.js";
4
+ import { RequestOptions } from "../internal/request-options.js";
5
+ export declare class PromptAdaptation extends APIResource {
6
+ /**
7
+ * Adapt your prompt from one LLM to work optimally across different target LLMs.
8
+ *
9
+ * This endpoint automatically optimizes your prompt (system prompt + user message
10
+ * template) to improve accuracy on your use case across various models. Each model
11
+ * has unique characteristics, and what works well for GPT-5 might not work as well
12
+ * for Claude or Gemini.
13
+ *
14
+ * **How Prompt Adaptation Works:**
15
+ *
16
+ * 1. You provide your current prompt and optionally your current origin model
17
+ * 2. You specify the target models you want to adapt your prompt to
18
+ * 3. You provide evaluation examples (golden records) with expected answers
19
+ * 4. The system runs optimization to find the best prompt for each target model
20
+ * 5. You receive adapted prompts that perform well on your target models
21
+ *
22
+ * **Evaluation Metrics:** Choose either a standard metric or provide custom
23
+ * evaluation:
24
+ *
25
+ * - **Standard metrics**: LLMaaJ:Sem_Sim_1 (semantic similarity), JSON_Match
26
+ * - **Custom evaluation**: Provide evaluation_config with your own LLM judge,
27
+ * prompt, and cutoff
28
+ *
29
+ * **Dataset Requirements:**
30
+ *
31
+ * - Minimum 25 examples in train_goldens (more examples = better adaptation)
32
+ * - **Prototype mode**: Set `prototype_mode: true` to use as few as 3 examples for
33
+ * prototyping
34
+ * - Recommended when you don't have enough data yet to build a proof-of-concept
35
+ * - Note: Performance may be degraded compared to standard mode (25+ examples)
36
+ * - Trade-off: Faster iteration with less data vs. potentially less
37
+ * generalizability
38
+ * - Each example must have fields matching your template placeholders
39
+ * - Supervised evaluation requires 'answer' field in each golden record
40
+ * - Unsupervised evaluation can work without answers
41
+ *
42
+ * **Training Time:**
43
+ *
44
+ * - Processing is asynchronous and typically takes 10-30 minutes
45
+ * - Time depends on: number of target models, dataset size, model availability
46
+ * - Use the returned adaptation_run_id to check status and retrieve results
47
+ *
48
+ * **Example Workflow:**
49
+ *
50
+ * ```
51
+ * 1. POST /v2/prompt/adapt - Submit adaptation request
52
+ * 2. GET /v2/prompt/adaptStatus/{id} - Poll status until completed
53
+ * 3. GET /v2/prompt/adaptResults/{id} - Retrieve optimized prompts
54
+ * 4. Use optimized prompts in production with target models
55
+ * ```
56
+ *
57
+ * **Related Documentation:** See
58
+ * https://docs.notdiamond.ai/docs/adapting-prompts-to-new-models for detailed
59
+ * guide.
60
+ *
61
+ * @example
62
+ * ```ts
63
+ * const response = await client.promptAdaptation.adapt({
64
+ * fields: ['question'],
65
+ * system_prompt: 'You are a mathematical assistant that counts digits accurately.',
66
+ * target_models: [
67
+ * { model: 'claude-sonnet-4-5-20250929', provider: 'anthropic' },
68
+ * { model: 'gemini-2.5-flash', provider: 'google' },
69
+ * ],
70
+ * template: 'Question: {question}\nAnswer:',
71
+ * evaluation_metric: 'LLMaaJ:Sem_Sim_1',
72
+ * prototype_mode: true,
73
+ * test_goldens: [
74
+ * {
75
+ * fields: { ... },
76
+ * answer: '15',
77
+ * },
78
+ * {
79
+ * fields: { ... },
80
+ * answer: '8',
81
+ * },
82
+ * {
83
+ * fields: { ... },
84
+ * answer: '1',
85
+ * },
86
+ * {
87
+ * fields: { ... },
88
+ * answer: '10',
89
+ * },
90
+ * {
91
+ * fields: { ... },
92
+ * answer: '11',
93
+ * },
94
+ * ],
95
+ * train_goldens: [
96
+ * {
97
+ * fields: { ... },
98
+ * answer: '20',
99
+ * },
100
+ * {
101
+ * fields: { ... },
102
+ * answer: '10',
103
+ * },
104
+ * {
105
+ * fields: { ... },
106
+ * answer: '0',
107
+ * },
108
+ * {
109
+ * fields: { ... },
110
+ * answer: '16',
111
+ * },
112
+ * {
113
+ * fields: { ... },
114
+ * answer: '2',
115
+ * },
116
+ * ],
117
+ * });
118
+ * ```
119
+ */
120
+ adapt(body: PromptAdaptationAdaptParams, options?: RequestOptions): APIPromise<PromptAdaptationAdaptResponse>;
121
+ /**
122
+ * Retrieve the complete results of a prompt adaptation run, including optimized
123
+ * prompts for all target models.
124
+ *
125
+ * This endpoint returns the adapted prompts and evaluation metrics for each target
126
+ * model in your adaptation request. Call this endpoint after the adaptation status
127
+ * is 'completed' to get your optimized prompts.
128
+ *
129
+ * **Response Structure:**
130
+ *
131
+ * - **origin_model**: Baseline performance of your original prompt on the origin
132
+ * model
133
+ * - Includes: system_prompt, user_message_template, score, evaluation metrics,
134
+ * cost
135
+ * - **target_models**: Array of results for each target model
136
+ * - Includes: optimized system_prompt, user_message_template, template_fields
137
+ * - pre_optimization_score: Performance before adaptation
138
+ * - post_optimization_score: Performance after adaptation
139
+ * - Evaluation metrics and cost information
140
+ *
141
+ * **Using Adapted Prompts:**
142
+ *
143
+ * 1. Extract the `system_prompt` and `user_message_template` from each target
144
+ * model result
145
+ * 2. Use `user_message_template_fields` to know which fields to substitute
146
+ * 3. Apply the optimized prompts when calling the respective target models
147
+ * 4. Compare pre/post optimization scores to see improvement
148
+ *
149
+ * **Status Handling:**
150
+ *
151
+ * - If adaptation is still processing, target model results will have
152
+ * `result_status: "processing"`
153
+ * - Only completed target models will have system_prompt and template values
154
+ * - Failed target models will have `result_status: "failed"` with null values
155
+ *
156
+ * **Cost Information:**
157
+ *
158
+ * - Each model result includes cost in USD for the adaptation process
159
+ * - Costs vary based on model pricing and number of evaluation examples
160
+ * - Typical range: $0.10 - $2.00 per target model
161
+ *
162
+ * **Best Practices:**
163
+ *
164
+ * 1. Wait for status 'completed' before calling this endpoint
165
+ * 2. Check result_status for each target model
166
+ * 3. Validate that post_optimization_score > pre_optimization_score
167
+ * 4. Save optimized prompts for production use
168
+ * 5. A/B test adapted prompts against originals in production
169
+ *
170
+ * @example
171
+ * ```ts
172
+ * const response =
173
+ * await client.promptAdaptation.getAdaptResults(
174
+ * 'adaptation_run_id',
175
+ * );
176
+ * ```
177
+ */
178
+ getAdaptResults(adaptationRunID: string, options?: RequestOptions): APIPromise<PromptAdaptationGetAdaptResultsResponse>;
179
+ /**
180
+ * Check the status of a prompt adaptation run.
181
+ *
182
+ * Use this endpoint to poll the status of your adaptation request. Processing is
183
+ * asynchronous, so you'll need to check periodically until the status indicates
184
+ * completion.
185
+ *
186
+ * **Status Values:**
187
+ *
188
+ * - `created`: Initial state, not yet processing
189
+ * - `queued`: Waiting for processing capacity (check queue_position)
190
+ * - `processing`: Currently optimizing prompts
191
+ * - `completed`: All target models have been processed successfully
192
+ * - `failed`: One or more target models failed to process
193
+ *
194
+ * **Polling Recommendations:**
195
+ *
196
+ * - Poll every 30-60 seconds during processing
197
+ * - Check queue_position if status is 'queued' to estimate wait time
198
+ * - Stop polling once status is 'completed' or 'failed'
199
+ * - Use GET /v2/prompt/adaptResults to retrieve results after completion
200
+ *
201
+ * **Queue Position:**
202
+ *
203
+ * - Only present when status is 'queued'
204
+ * - Lower numbers mean earlier processing (position 1 is next)
205
+ * - Typical wait time: 1-5 minutes per position
206
+ *
207
+ * **Note:** This endpoint only returns status information. To get the actual
208
+ * adapted prompts and evaluation results, use GET /v2/prompt/adaptResults once
209
+ * status is 'completed'.
210
+ *
211
+ * @example
212
+ * ```ts
213
+ * const response =
214
+ * await client.promptAdaptation.getAdaptStatus(
215
+ * 'adaptation_run_id',
216
+ * );
217
+ * ```
218
+ */
219
+ getAdaptStatus(adaptationRunID: string, options?: RequestOptions): APIPromise<PromptAdaptationGetAdaptStatusResponse>;
220
+ /**
221
+ * Get LLM usage costs for a specific prompt adaptation run.
222
+ *
223
+ * This endpoint returns the total cost and detailed usage records for all LLM
224
+ * requests made during a prompt adaptation run. Use this to track costs associated
225
+ * with optimizing prompts for different target models.
226
+ *
227
+ * **Cost Breakdown:**
228
+ *
229
+ * - Total cost across all models used in the adaptation
230
+ * - Individual usage records with provider, model, tokens, and costs
231
+ * - Timestamps for each LLM request
232
+ *
233
+ * **Access Control:**
234
+ *
235
+ * - Only accessible by the user who created the adaptation run
236
+ * - Requires prompt adaptation access
237
+ *
238
+ * @example
239
+ * ```ts
240
+ * const response = await client.promptAdaptation.getCost(
241
+ * 'adaptation_run_id',
242
+ * );
243
+ * ```
244
+ */
245
+ getCost(adaptationRunID: string, options?: RequestOptions): APIPromise<PromptAdaptationGetCostResponse>;
246
+ }
247
+ /**
248
+ * A training or test example for prompt adaptation.
249
+ */
250
+ export interface GoldenRecord {
251
+ /**
252
+ * Dictionary mapping field names to their values. Keys must match the fields
253
+ * specified in the template
254
+ */
255
+ fields: {
256
+ [key: string]: string;
257
+ };
258
+ /**
259
+ * Expected answer for supervised evaluation. Required for supervised metrics,
260
+ * optional for unsupervised
261
+ */
262
+ answer?: string | null;
263
+ }
264
+ /**
265
+ * Status enum for asynchronous jobs (prompt adaptation, custom router training,
266
+ * etc.).
267
+ *
268
+ * Represents the current state of a long-running operation:
269
+ *
270
+ * - **created**: Job has been initialized but not yet queued
271
+ * - **queued**: Job is waiting in the queue to be processed
272
+ * - **processing**: Job is currently being executed
273
+ * - **completed**: Job finished successfully and results are available
274
+ * - **failed**: Job encountered an error and did not complete
275
+ * - **cancelled**: Job was cancelled due to a restart operation
276
+ */
277
+ export type JobStatus = 'created' | 'queued' | 'processing' | 'completed' | 'failed' | 'cancelled';
278
+ /**
279
+ * Model for specifying an LLM provider in API requests.
280
+ */
281
+ export interface RequestProvider {
282
+ /**
283
+ * Model name (e.g., 'gpt-4o', 'claude-sonnet-4-5-20250929')
284
+ */
285
+ model: string;
286
+ /**
287
+ * Provider name (e.g., 'openai', 'anthropic', 'google')
288
+ */
289
+ provider: string;
290
+ /**
291
+ * Maximum context length for the model (required for custom models)
292
+ */
293
+ context_length?: number | null;
294
+ /**
295
+ * Input token price per million tokens in USD (required for custom models)
296
+ */
297
+ input_price?: number | null;
298
+ /**
299
+ * Whether this is a custom model not in Not Diamond's supported model list
300
+ */
301
+ is_custom?: boolean;
302
+ /**
303
+ * Average latency in seconds (required for custom models)
304
+ */
305
+ latency?: number | null;
306
+ /**
307
+ * Output token price per million tokens in USD (required for custom models)
308
+ */
309
+ output_price?: number | null;
310
+ }
311
+ /**
312
+ * Response model for POST /v2/prompt/adapt endpoint.
313
+ *
314
+ * Returned immediately after submitting a prompt adaptation request. The
315
+ * adaptation process runs asynchronously, so use the returned adaptation_run_id to
316
+ * track progress and retrieve results when complete.
317
+ *
318
+ * **Next steps:**
319
+ *
320
+ * 1. Store the adaptation_run_id
321
+ * 2. Poll GET /v2/prompt/adaptStatus/{adaptation_run_id} to check progress
322
+ * 3. When status is 'completed', retrieve optimized prompts from GET
323
+ * /v2/prompt/adaptResults/{adaptation_run_id}
324
+ * 4. Use the optimized prompts with your target models
325
+ */
326
+ export interface PromptAdaptationAdaptResponse {
327
+ /**
328
+ * Unique identifier for this adaptation run. Use this to poll status and retrieve
329
+ * optimized prompts when complete
330
+ */
331
+ adaptation_run_id: string;
332
+ }
333
+ /**
334
+ * Response model for GET /v2/prompt/adaptResults/{adaptation_run_id} endpoint.
335
+ *
336
+ * Contains the complete results of a prompt adaptation run, including optimized
337
+ * prompts and evaluation metrics for all target models. Use this to retrieve your
338
+ * adapted prompts after the adaptation status is 'completed'.
339
+ *
340
+ * The response includes:
341
+ *
342
+ * - Baseline performance of your original prompt on the origin model
343
+ * - Optimized prompts for each target model with pre/post optimization scores
344
+ * - Evaluation metrics and cost information for each model
345
+ */
346
+ export interface PromptAdaptationGetAdaptResultsResponse {
347
+ /**
348
+ * Unique ID for this adaptation run
349
+ */
350
+ id: string;
351
+ /**
352
+ * Timestamp when this adaptation run was created
353
+ */
354
+ created_at: string;
355
+ /**
356
+ * Overall status of the adaptation run (queued, running, completed, failed)
357
+ */
358
+ job_status: JobStatus;
359
+ /**
360
+ * Results for each target model with optimized prompts and improvement scores
361
+ */
362
+ target_models: Array<PromptAdaptationGetAdaptResultsResponse.TargetModel>;
363
+ /**
364
+ * Timestamp of last update to this adaptation run
365
+ */
366
+ updated_at: string | null;
367
+ evaluation_config?: string | null;
368
+ evaluation_metric?: string | null;
369
+ /**
370
+ * Metrics for the LLM requests made during the adaptation run. List of {model:
371
+ * str, num_requests: int}.
372
+ */
373
+ llm_request_metrics?: Array<{
374
+ [key: string]: unknown;
375
+ }> | null;
376
+ /**
377
+ * Baseline results for the origin model in prompt adaptation.
378
+ *
379
+ * Part of AdaptationRunResultsResponse. Contains the performance metrics and
380
+ * prompt configuration for your original prompt on the origin model. This serves
381
+ * as the baseline to compare against optimized prompts for target models.
382
+ *
383
+ * **Fields include:**
384
+ *
385
+ * - Original system prompt and user message template
386
+ * - Baseline performance score and evaluation metrics
387
+ * - Cost of running the baseline evaluation
388
+ * - Job status for the origin model evaluation
389
+ */
390
+ origin_model?: PromptAdaptationGetAdaptResultsResponse.OriginModel | null;
391
+ /**
392
+ * Whether this adaptation run was created with prototype mode (3-24 training
393
+ * examples allowed). Prototype mode may have degraded performance compared to
394
+ * standard mode (25+ examples)
395
+ */
396
+ prototype_mode?: boolean;
397
+ }
398
+ export declare namespace PromptAdaptationGetAdaptResultsResponse {
399
+ /**
400
+ * Optimized prompt results for a single target model in prompt adaptation.
401
+ *
402
+ * Part of AdaptationRunResultsResponse. Contains the optimized system prompt and
403
+ * user message template for a specific target model, along with performance scores
404
+ * before and after optimization. Use these optimized prompts with the target model
405
+ * to achieve better performance than the original prompt.
406
+ *
407
+ * **Key metrics:**
408
+ *
409
+ * - **pre_optimization_score**: Performance with original prompt on this target
410
+ * model
411
+ * - **post_optimization_score**: Performance with optimized prompt on this target
412
+ * model
413
+ * - **Score improvement**: post - pre shows how much optimization helped
414
+ *
415
+ * **Usage:**
416
+ *
417
+ * 1. Extract the optimized system_prompt and user_message_template
418
+ * 2. Replace placeholders in user_message_template using fields from your data
419
+ * 3. Use these prompts when calling this target model
420
+ * 4. Compare pre/post scores to see improvement gained
421
+ */
422
+ interface TargetModel {
423
+ cost: number | null;
424
+ model_name: string;
425
+ post_optimization_evals: {
426
+ [key: string]: unknown;
427
+ } | null;
428
+ post_optimization_score: number | null;
429
+ pre_optimization_evals: {
430
+ [key: string]: unknown;
431
+ } | null;
432
+ pre_optimization_score: number | null;
433
+ task_type: string | null;
434
+ /**
435
+ * Status enum for asynchronous jobs (prompt adaptation, custom router training,
436
+ * etc.).
437
+ *
438
+ * Represents the current state of a long-running operation:
439
+ *
440
+ * - **created**: Job has been initialized but not yet queued
441
+ * - **queued**: Job is waiting in the queue to be processed
442
+ * - **processing**: Job is currently being executed
443
+ * - **completed**: Job finished successfully and results are available
444
+ * - **failed**: Job encountered an error and did not complete
445
+ * - **cancelled**: Job was cancelled due to a restart operation
446
+ */
447
+ result_status?: PromptAdaptationAPI.JobStatus | null;
448
+ /**
449
+ * Optimized system prompt for this target model. Use this as the system message in
450
+ * your LLM calls
451
+ */
452
+ system_prompt?: string | null;
453
+ /**
454
+ * Optimized user message template with placeholders. Substitute fields using your
455
+ * data before calling the LLM
456
+ */
457
+ user_message_template?: string | null;
458
+ /**
459
+ * List of field names to substitute in the template (e.g., ['question',
460
+ * 'context']). These match the curly-brace placeholders in user_message_template
461
+ */
462
+ user_message_template_fields?: Array<string> | null;
463
+ }
464
+ /**
465
+ * Baseline results for the origin model in prompt adaptation.
466
+ *
467
+ * Part of AdaptationRunResultsResponse. Contains the performance metrics and
468
+ * prompt configuration for your original prompt on the origin model. This serves
469
+ * as the baseline to compare against optimized prompts for target models.
470
+ *
471
+ * **Fields include:**
472
+ *
473
+ * - Original system prompt and user message template
474
+ * - Baseline performance score and evaluation metrics
475
+ * - Cost of running the baseline evaluation
476
+ * - Job status for the origin model evaluation
477
+ */
478
+ interface OriginModel {
479
+ cost: number | null;
480
+ evals: {
481
+ [key: string]: unknown;
482
+ } | null;
483
+ model_name: string | null;
484
+ score: number | null;
485
+ /**
486
+ * Status enum for asynchronous jobs (prompt adaptation, custom router training,
487
+ * etc.).
488
+ *
489
+ * Represents the current state of a long-running operation:
490
+ *
491
+ * - **created**: Job has been initialized but not yet queued
492
+ * - **queued**: Job is waiting in the queue to be processed
493
+ * - **processing**: Job is currently being executed
494
+ * - **completed**: Job finished successfully and results are available
495
+ * - **failed**: Job encountered an error and did not complete
496
+ * - **cancelled**: Job was cancelled due to a restart operation
497
+ */
498
+ result_status?: PromptAdaptationAPI.JobStatus | null;
499
+ /**
500
+ * Original system prompt used for the origin model
501
+ */
502
+ system_prompt?: string | null;
503
+ /**
504
+ * Original user message template used for the origin model
505
+ */
506
+ user_message_template?: string | null;
507
+ }
508
+ }
509
+ /**
510
+ * Response model for GET /v2/prompt/adaptStatus/{adaptation_run_id} endpoint.
511
+ *
512
+ * Returns the current status of an asynchronous prompt adaptation job. Poll this
513
+ * endpoint periodically to track progress. When status is 'completed', you can
514
+ * retrieve the optimized prompts using the /adaptResults endpoint.
515
+ *
516
+ * **Status values:**
517
+ *
518
+ * - **created**: Job has been initialized
519
+ * - **queued**: Waiting in queue (check queue_position for your place in line)
520
+ * - **processing**: Currently running optimization
521
+ * - **completed**: Finished successfully, results available via /adaptResults
522
+ * - **failed**: Encountered an error during processing
523
+ *
524
+ * **Polling recommendations:**
525
+ *
526
+ * - Poll every 30-60 seconds while status is incomplete
527
+ * - Stop polling once status is 'completed' or 'failed'
528
+ * - Adaptation typically takes 10-30 minutes total
529
+ */
530
+ export interface PromptAdaptationGetAdaptStatusResponse {
531
+ /**
532
+ * Unique identifier for this adaptation run. Use this to poll status and retrieve
533
+ * optimized prompts when complete
534
+ */
535
+ adaptation_run_id: string;
536
+ /**
537
+ * Current status of the adaptation run. Poll until this is 'completed' or 'failed'
538
+ */
539
+ status: JobStatus;
540
+ /**
541
+ * Position in queue when status is 'queued'. Lower numbers process sooner. Null
542
+ * when not queued
543
+ */
544
+ queue_position?: number | null;
545
+ }
546
+ /**
547
+ * Response model for GET /v2/prompt/adapt/{adaptation_run_id}/costs endpoint.
548
+ *
549
+ * Contains the total LLM costs and detailed usage records for a prompt adaptation
550
+ * run. Use this to track costs associated with optimizing prompts for different
551
+ * target models.
552
+ */
553
+ export interface PromptAdaptationGetCostResponse {
554
+ /**
555
+ * Unique identifier for the adaptation run
556
+ */
557
+ adaptation_run_id: string;
558
+ /**
559
+ * Total cost in USD across all LLM requests in this adaptation run
560
+ */
561
+ total_cost: number;
562
+ /**
563
+ * Detailed usage records for each LLM request made during the adaptation
564
+ */
565
+ usage_records: Array<PromptAdaptationGetCostResponse.UsageRecord>;
566
+ }
567
+ export declare namespace PromptAdaptationGetCostResponse {
568
+ /**
569
+ * Individual LLM usage record with token counts and cost breakdown.
570
+ *
571
+ * Returned by GET /llm-usage endpoint and included in AdaptationRunCostResponse.
572
+ * Each record represents a single LLM API call with detailed usage metrics.
573
+ */
574
+ interface UsageRecord {
575
+ /**
576
+ * Unique identifier for this usage record
577
+ */
578
+ id: string;
579
+ /**
580
+ * Adaptation run ID this usage is associated with
581
+ */
582
+ adaptation_run_id: string;
583
+ /**
584
+ * Cost of input tokens in USD
585
+ */
586
+ input_cost: number;
587
+ /**
588
+ * Number of input tokens consumed
589
+ */
590
+ input_tokens: number;
591
+ /**
592
+ * Model name (e.g., 'gpt-4', 'claude-3-opus-20240229')
593
+ */
594
+ model: string;
595
+ /**
596
+ * Organization ID associated with the request
597
+ */
598
+ organization_id: string;
599
+ /**
600
+ * Cost of output tokens in USD
601
+ */
602
+ output_cost: number;
603
+ /**
604
+ * Number of output tokens generated
605
+ */
606
+ output_tokens: number;
607
+ /**
608
+ * LLM provider (e.g., 'openai', 'anthropic', 'google')
609
+ */
610
+ provider: string;
611
+ /**
612
+ * Type of task: 'pre-optimization evaluation', 'optimization', or
613
+ * 'post-optimization evaluation'
614
+ */
615
+ task_type: string;
616
+ /**
617
+ * Unix timestamp when the request was made
618
+ */
619
+ timestamp: number;
620
+ /**
621
+ * Total cost (input + output) in USD
622
+ */
623
+ total_cost: number;
624
+ /**
625
+ * User ID who made the request
626
+ */
627
+ user_id: string;
628
+ }
629
+ }
630
+ export interface PromptAdaptationAdaptParams {
631
+ /**
632
+ * List of field names that will be substituted into the template. Must match keys
633
+ * in golden records
634
+ */
635
+ fields: Array<string>;
636
+ /**
637
+ * System prompt to use with the origin model. This sets the context and role for
638
+ * the LLM
639
+ */
640
+ system_prompt: string;
641
+ /**
642
+ * List of models to adapt the prompt for. Maximum count depends on your
643
+ * subscription tier (Free: 1, Starter: 3, Startup: 5, Enterprise: 10)
644
+ */
645
+ target_models: Array<RequestProvider>;
646
+ /**
647
+ * User message template with placeholders for fields. Use curly braces for field
648
+ * substitution
649
+ */
650
+ template: string;
651
+ evaluation_config?: string | null;
652
+ evaluation_metric?: string | null;
653
+ /**
654
+ * Training examples (legacy parameter). Use train_goldens and test_goldens for
655
+ * better control. Minimum 25 examples (or 3 with prototype_mode=true)
656
+ */
657
+ goldens?: Array<GoldenRecord> | null;
658
+ /**
659
+ * Model for specifying an LLM provider in API requests.
660
+ */
661
+ origin_model?: RequestProvider | null;
662
+ /**
663
+ * Optional baseline score for the origin model. If provided, can skip origin model
664
+ * evaluation
665
+ */
666
+ origin_model_evaluation_score?: number | null;
667
+ /**
668
+ * Enable prototype mode to use as few as 3 training examples (instead of 25).
669
+ * Note: Performance may be degraded with fewer examples. Recommended for
670
+ * prototyping AI applications when you don't have enough data yet
671
+ */
672
+ prototype_mode?: boolean;
673
+ /**
674
+ * Test examples for evaluation. Required if train_goldens is provided. Used to
675
+ * measure final performance on held-out data
676
+ */
677
+ test_goldens?: Array<GoldenRecord> | null;
678
+ /**
679
+ * Training examples for prompt optimization. Minimum 25 examples required (or 3
680
+ * with prototype_mode=true). Cannot be used with 'goldens' parameter
681
+ */
682
+ train_goldens?: Array<GoldenRecord> | null;
683
+ }
684
+ export declare namespace PromptAdaptation {
685
+ export { type GoldenRecord as GoldenRecord, type JobStatus as JobStatus, type RequestProvider as RequestProvider, type PromptAdaptationAdaptResponse as PromptAdaptationAdaptResponse, type PromptAdaptationGetAdaptResultsResponse as PromptAdaptationGetAdaptResultsResponse, type PromptAdaptationGetAdaptStatusResponse as PromptAdaptationGetAdaptStatusResponse, type PromptAdaptationGetCostResponse as PromptAdaptationGetCostResponse, type PromptAdaptationAdaptParams as PromptAdaptationAdaptParams, };
686
+ }
687
+ //# sourceMappingURL=prompt-adaptation.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"prompt-adaptation.d.ts","sourceRoot":"","sources":["../src/resources/prompt-adaptation.ts"],"names":[],"mappings":"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"}