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