notdiamond 2.0.0-rc5 → 2.1.0

package/resources/prompt-adaptation.js

@@ -0,0 +1,258 @@
+"use strict";
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.PromptAdaptation = void 0;
+const resource_1 = require("../core/resource.js");
+const path_1 = require("../internal/utils/path.js");
+class PromptAdaptation extends resource_1.APIResource {
+    /**
+     * Adapt your prompt from one LLM to work optimally across different target LLMs.
+     *
+     * This endpoint automatically optimizes your prompt (system prompt + user message
+     * template) to improve accuracy on your use case across various models. Each model
+     * has unique characteristics, and what works well for GPT-5 might not work as well
+     * for Claude or Gemini.
+     *
+     * **How Prompt Adaptation Works:**
+     *
+     * 1. You provide your current prompt and optionally your current origin model
+     * 2. You specify the target models you want to adapt your prompt to
+     * 3. You provide evaluation examples (golden records) with expected answers
+     * 4. The system runs optimization to find the best prompt for each target model
+     * 5. You receive adapted prompts that perform well on your target models
+     *
+     * **Evaluation Metrics:** Choose either a standard metric or provide custom
+     * evaluation:
+     *
+     * - **Standard metrics**: LLMaaJ:Sem_Sim_1 (semantic similarity), JSON_Match
+     * - **Custom evaluation**: Provide evaluation_config with your own LLM judge,
+     *   prompt, and cutoff
+     *
+     * **Dataset Requirements:**
+     *
+     * - Minimum 25 examples in train_goldens (more examples = better adaptation)
+     * - **Prototype mode**: Set `prototype_mode: true` to use as few as 3 examples for
+     *   prototyping
+     *   - Recommended when you don't have enough data yet to build a proof-of-concept
+     *   - Note: Performance may be degraded compared to standard mode (25+ examples)
+     *   - Trade-off: Faster iteration with less data vs. potentially less
+     *     generalizability
+     * - Each example must have fields matching your template placeholders
+     * - Supervised evaluation requires 'answer' field in each golden record
+     * - Unsupervised evaluation can work without answers
+     *
+     * **Training Time:**
+     *
+     * - Processing is asynchronous and typically takes 10-30 minutes
+     * - Time depends on: number of target models, dataset size, model availability
+     * - Use the returned adaptation_run_id to check status and retrieve results
+     *
+     * **Example Workflow:**
+     *
+     * ```
+     * 1. POST /v2/prompt/adapt - Submit adaptation request
+     * 2. GET /v2/prompt/adaptStatus/{id} - Poll status until completed
+     * 3. GET /v2/prompt/adaptResults/{id} - Retrieve optimized prompts
+     * 4. Use optimized prompts in production with target models
+     * ```
+     *
+     * **Related Documentation:** See
+     * https://docs.notdiamond.ai/docs/adapting-prompts-to-new-models for detailed
+     * guide.
+     *
+     * @example
+     * ```ts
+     * const response = await client.promptAdaptation.adapt({
+     *   fields: ['question'],
+     *   system_prompt: 'You are a mathematical assistant that counts digits accurately.',
+     *   target_models: [
+     *     { model: 'claude-sonnet-4-5-20250929', provider: 'anthropic' },
+     *     { model: 'gemini-2.5-flash', provider: 'google' },
+     *   ],
+     *   template: 'Question: {question}\nAnswer:',
+     *   evaluation_metric: 'LLMaaJ:Sem_Sim_1',
+     *   prototype_mode: true,
+     *   test_goldens: [
+     *     {
+     *       fields: { ... },
+     *       answer: '15',
+     *     },
+     *     {
+     *       fields: { ... },
+     *       answer: '8',
+     *     },
+     *     {
+     *       fields: { ... },
+     *       answer: '1',
+     *     },
+     *     {
+     *       fields: { ... },
+     *       answer: '10',
+     *     },
+     *     {
+     *       fields: { ... },
+     *       answer: '11',
+     *     },
+     *   ],
+     *   train_goldens: [
+     *     {
+     *       fields: { ... },
+     *       answer: '20',
+     *     },
+     *     {
+     *       fields: { ... },
+     *       answer: '10',
+     *     },
+     *     {
+     *       fields: { ... },
+     *       answer: '0',
+     *     },
+     *     {
+     *       fields: { ... },
+     *       answer: '16',
+     *     },
+     *     {
+     *       fields: { ... },
+     *       answer: '2',
+     *     },
+     *   ],
+     * });
+     * ```
+     */
+    adapt(body, options) {
+        return this._client.post('/v2/prompt/adapt', { body, ...options });
+    }
+    /**
+     * Retrieve the complete results of a prompt adaptation run, including optimized
+     * prompts for all target models.
+     *
+     * This endpoint returns the adapted prompts and evaluation metrics for each target
+     * model in your adaptation request. Call this endpoint after the adaptation status
+     * is 'completed' to get your optimized prompts.
+     *
+     * **Response Structure:**
+     *
+     * - **origin_model**: Baseline performance of your original prompt on the origin
+     *   model
+     *   - Includes: system_prompt, user_message_template, score, evaluation metrics,
+     *     cost
+     * - **target_models**: Array of results for each target model
+     *   - Includes: optimized system_prompt, user_message_template, template_fields
+     *   - pre_optimization_score: Performance before adaptation
+     *   - post_optimization_score: Performance after adaptation
+     *   - Evaluation metrics and cost information
+     *
+     * **Using Adapted Prompts:**
+     *
+     * 1. Extract the `system_prompt` and `user_message_template` from each target
+     *    model result
+     * 2. Use `user_message_template_fields` to know which fields to substitute
+     * 3. Apply the optimized prompts when calling the respective target models
+     * 4. Compare pre/post optimization scores to see improvement
+     *
+     * **Status Handling:**
+     *
+     * - If adaptation is still processing, target model results will have
+     *   `result_status: "processing"`
+     * - Only completed target models will have system_prompt and template values
+     * - Failed target models will have `result_status: "failed"` with null values
+     *
+     * **Cost Information:**
+     *
+     * - Each model result includes cost in USD for the adaptation process
+     * - Costs vary based on model pricing and number of evaluation examples
+     * - Typical range: $0.10 - $2.00 per target model
+     *
+     * **Best Practices:**
+     *
+     * 1. Wait for status 'completed' before calling this endpoint
+     * 2. Check result_status for each target model
+     * 3. Validate that post_optimization_score > pre_optimization_score
+     * 4. Save optimized prompts for production use
+     * 5. A/B test adapted prompts against originals in production
+     *
+     * @example
+     * ```ts
+     * const response =
+     *   await client.promptAdaptation.getAdaptResults(
+     *     'adaptation_run_id',
+     *   );
+     * ```
+     */
+    getAdaptResults(adaptationRunID, options) {
+        return this._client.get((0, path_1.path) `/v2/prompt/adaptResults/${adaptationRunID}`, options);
+    }
+    /**
+     * Check the status of a prompt adaptation run.
+     *
+     * Use this endpoint to poll the status of your adaptation request. Processing is
+     * asynchronous, so you'll need to check periodically until the status indicates
+     * completion.
+     *
+     * **Status Values:**
+     *
+     * - `created`: Initial state, not yet processing
+     * - `queued`: Waiting for processing capacity (check queue_position)
+     * - `processing`: Currently optimizing prompts
+     * - `completed`: All target models have been processed successfully
+     * - `failed`: One or more target models failed to process
+     *
+     * **Polling Recommendations:**
+     *
+     * - Poll every 30-60 seconds during processing
+     * - Check queue_position if status is 'queued' to estimate wait time
+     * - Stop polling once status is 'completed' or 'failed'
+     * - Use GET /v2/prompt/adaptResults to retrieve results after completion
+     *
+     * **Queue Position:**
+     *
+     * - Only present when status is 'queued'
+     * - Lower numbers mean earlier processing (position 1 is next)
+     * - Typical wait time: 1-5 minutes per position
+     *
+     * **Note:** This endpoint only returns status information. To get the actual
+     * adapted prompts and evaluation results, use GET /v2/prompt/adaptResults once
+     * status is 'completed'.
+     *
+     * @example
+     * ```ts
+     * const response =
+     *   await client.promptAdaptation.getAdaptStatus(
+     *     'adaptation_run_id',
+     *   );
+     * ```
+     */
+    getAdaptStatus(adaptationRunID, options) {
+        return this._client.get((0, path_1.path) `/v2/prompt/adaptStatus/${adaptationRunID}`, options);
+    }
+    /**
+     * Get LLM usage costs for a specific prompt adaptation run.
+     *
+     * This endpoint returns the total cost and detailed usage records for all LLM
+     * requests made during a prompt adaptation run. Use this to track costs associated
+     * with optimizing prompts for different target models.
+     *
+     * **Cost Breakdown:**
+     *
+     * - Total cost across all models used in the adaptation
+     * - Individual usage records with provider, model, tokens, and costs
+     * - Timestamps for each LLM request
+     *
+     * **Access Control:**
+     *
+     * - Only accessible by the user who created the adaptation run
+     * - Requires prompt adaptation access
+     *
+     * @example
+     * ```ts
+     * const response = await client.promptAdaptation.getCost(
+     *   'adaptation_run_id',
+     * );
+     * ```
+     */
+    getCost(adaptationRunID, options) {
+        return this._client.get((0, path_1.path) `/v2/prompt/adapt/${adaptationRunID}/costs`, options);
+    }
+}
+exports.PromptAdaptation = PromptAdaptation;
+//# sourceMappingURL=prompt-adaptation.js.map

package/resources/prompt-adaptation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-adaptation.js","sourceRoot":"","sources":["../src/resources/prompt-adaptation.ts"],"names":[],"mappings":";AAAA,sFAAsF;;;AAEtF,kDAA+C;AAI/C,oDAA8C;AAE9C,MAAa,gBAAiB,SAAQ,sBAAW;IAC/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiHG;IACH,KAAK,CACH,IAAiC,EACjC,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,kBAAkB,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACrE,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwDG;IACH,eAAe,CACb,eAAuB,EACvB,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,2BAA2B,eAAe,EAAE,EAAE,OAAO,CAAC,CAAC;IACrF,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACH,cAAc,CACZ,eAAuB,EACvB,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,0BAA0B,eAAe,EAAE,EAAE,OAAO,CAAC,CAAC;IACpF,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,OAAO,CAAC,eAAuB,EAAE,OAAwB;QACvD,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAA,WAAI,EAAA,oBAAoB,eAAe,QAAQ,EAAE,OAAO,CAAC,CAAC;IACpF,CAAC;CACF;AArQD,4CAqQC"}

package/resources/prompt-adaptation.mjs

@@ -0,0 +1,254 @@
+// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
+import { APIResource } from "../core/resource.mjs";
+import { path } from "../internal/utils/path.mjs";
+export class PromptAdaptation extends APIResource {
+    /**
+     * Adapt your prompt from one LLM to work optimally across different target LLMs.
+     *
+     * This endpoint automatically optimizes your prompt (system prompt + user message
+     * template) to improve accuracy on your use case across various models. Each model
+     * has unique characteristics, and what works well for GPT-5 might not work as well
+     * for Claude or Gemini.
+     *
+     * **How Prompt Adaptation Works:**
+     *
+     * 1. You provide your current prompt and optionally your current origin model
+     * 2. You specify the target models you want to adapt your prompt to
+     * 3. You provide evaluation examples (golden records) with expected answers
+     * 4. The system runs optimization to find the best prompt for each target model
+     * 5. You receive adapted prompts that perform well on your target models
+     *
+     * **Evaluation Metrics:** Choose either a standard metric or provide custom
+     * evaluation:
+     *
+     * - **Standard metrics**: LLMaaJ:Sem_Sim_1 (semantic similarity), JSON_Match
+     * - **Custom evaluation**: Provide evaluation_config with your own LLM judge,
+     *   prompt, and cutoff
+     *
+     * **Dataset Requirements:**
+     *
+     * - Minimum 25 examples in train_goldens (more examples = better adaptation)
+     * - **Prototype mode**: Set `prototype_mode: true` to use as few as 3 examples for
+     *   prototyping
+     *   - Recommended when you don't have enough data yet to build a proof-of-concept
+     *   - Note: Performance may be degraded compared to standard mode (25+ examples)
+     *   - Trade-off: Faster iteration with less data vs. potentially less
+     *     generalizability
+     * - Each example must have fields matching your template placeholders
+     * - Supervised evaluation requires 'answer' field in each golden record
+     * - Unsupervised evaluation can work without answers
+     *
+     * **Training Time:**
+     *
+     * - Processing is asynchronous and typically takes 10-30 minutes
+     * - Time depends on: number of target models, dataset size, model availability
+     * - Use the returned adaptation_run_id to check status and retrieve results
+     *
+     * **Example Workflow:**
+     *
+     * ```
+     * 1. POST /v2/prompt/adapt - Submit adaptation request
+     * 2. GET /v2/prompt/adaptStatus/{id} - Poll status until completed
+     * 3. GET /v2/prompt/adaptResults/{id} - Retrieve optimized prompts
+     * 4. Use optimized prompts in production with target models
+     * ```
+     *
+     * **Related Documentation:** See
+     * https://docs.notdiamond.ai/docs/adapting-prompts-to-new-models for detailed
+     * guide.
+     *
+     * @example
+     * ```ts
+     * const response = await client.promptAdaptation.adapt({
+     *   fields: ['question'],
+     *   system_prompt: 'You are a mathematical assistant that counts digits accurately.',
+     *   target_models: [
+     *     { model: 'claude-sonnet-4-5-20250929', provider: 'anthropic' },
+     *     { model: 'gemini-2.5-flash', provider: 'google' },
+     *   ],
+     *   template: 'Question: {question}\nAnswer:',
+     *   evaluation_metric: 'LLMaaJ:Sem_Sim_1',
+     *   prototype_mode: true,
+     *   test_goldens: [
+     *     {
+     *       fields: { ... },
+     *       answer: '15',
+     *     },
+     *     {
+     *       fields: { ... },
+     *       answer: '8',
+     *     },
+     *     {
+     *       fields: { ... },
+     *       answer: '1',
+     *     },
+     *     {
+     *       fields: { ... },
+     *       answer: '10',
+     *     },
+     *     {
+     *       fields: { ... },
+     *       answer: '11',
+     *     },
+     *   ],
+     *   train_goldens: [
+     *     {
+     *       fields: { ... },
+     *       answer: '20',
+     *     },
+     *     {
+     *       fields: { ... },
+     *       answer: '10',
+     *     },
+     *     {
+     *       fields: { ... },
+     *       answer: '0',
+     *     },
+     *     {
+     *       fields: { ... },
+     *       answer: '16',
+     *     },
+     *     {
+     *       fields: { ... },
+     *       answer: '2',
+     *     },
+     *   ],
+     * });
+     * ```
+     */
+    adapt(body, options) {
+        return this._client.post('/v2/prompt/adapt', { body, ...options });
+    }
+    /**
+     * Retrieve the complete results of a prompt adaptation run, including optimized
+     * prompts for all target models.
+     *
+     * This endpoint returns the adapted prompts and evaluation metrics for each target
+     * model in your adaptation request. Call this endpoint after the adaptation status
+     * is 'completed' to get your optimized prompts.
+     *
+     * **Response Structure:**
+     *
+     * - **origin_model**: Baseline performance of your original prompt on the origin
+     *   model
+     *   - Includes: system_prompt, user_message_template, score, evaluation metrics,
+     *     cost
+     * - **target_models**: Array of results for each target model
+     *   - Includes: optimized system_prompt, user_message_template, template_fields
+     *   - pre_optimization_score: Performance before adaptation
+     *   - post_optimization_score: Performance after adaptation
+     *   - Evaluation metrics and cost information
+     *
+     * **Using Adapted Prompts:**
+     *
+     * 1. Extract the `system_prompt` and `user_message_template` from each target
+     *    model result
+     * 2. Use `user_message_template_fields` to know which fields to substitute
+     * 3. Apply the optimized prompts when calling the respective target models
+     * 4. Compare pre/post optimization scores to see improvement
+     *
+     * **Status Handling:**
+     *
+     * - If adaptation is still processing, target model results will have
+     *   `result_status: "processing"`
+     * - Only completed target models will have system_prompt and template values
+     * - Failed target models will have `result_status: "failed"` with null values
+     *
+     * **Cost Information:**
+     *
+     * - Each model result includes cost in USD for the adaptation process
+     * - Costs vary based on model pricing and number of evaluation examples
+     * - Typical range: $0.10 - $2.00 per target model
+     *
+     * **Best Practices:**
+     *
+     * 1. Wait for status 'completed' before calling this endpoint
+     * 2. Check result_status for each target model
+     * 3. Validate that post_optimization_score > pre_optimization_score
+     * 4. Save optimized prompts for production use
+     * 5. A/B test adapted prompts against originals in production
+     *
+     * @example
+     * ```ts
+     * const response =
+     *   await client.promptAdaptation.getAdaptResults(
+     *     'adaptation_run_id',
+     *   );
+     * ```
+     */
+    getAdaptResults(adaptationRunID, options) {
+        return this._client.get(path `/v2/prompt/adaptResults/${adaptationRunID}`, options);
+    }
+    /**
+     * Check the status of a prompt adaptation run.
+     *
+     * Use this endpoint to poll the status of your adaptation request. Processing is
+     * asynchronous, so you'll need to check periodically until the status indicates
+     * completion.
+     *
+     * **Status Values:**
+     *
+     * - `created`: Initial state, not yet processing
+     * - `queued`: Waiting for processing capacity (check queue_position)
+     * - `processing`: Currently optimizing prompts
+     * - `completed`: All target models have been processed successfully
+     * - `failed`: One or more target models failed to process
+     *
+     * **Polling Recommendations:**
+     *
+     * - Poll every 30-60 seconds during processing
+     * - Check queue_position if status is 'queued' to estimate wait time
+     * - Stop polling once status is 'completed' or 'failed'
+     * - Use GET /v2/prompt/adaptResults to retrieve results after completion
+     *
+     * **Queue Position:**
+     *
+     * - Only present when status is 'queued'
+     * - Lower numbers mean earlier processing (position 1 is next)
+     * - Typical wait time: 1-5 minutes per position
+     *
+     * **Note:** This endpoint only returns status information. To get the actual
+     * adapted prompts and evaluation results, use GET /v2/prompt/adaptResults once
+     * status is 'completed'.
+     *
+     * @example
+     * ```ts
+     * const response =
+     *   await client.promptAdaptation.getAdaptStatus(
+     *     'adaptation_run_id',
+     *   );
+     * ```
+     */
+    getAdaptStatus(adaptationRunID, options) {
+        return this._client.get(path `/v2/prompt/adaptStatus/${adaptationRunID}`, options);
+    }
+    /**
+     * Get LLM usage costs for a specific prompt adaptation run.
+     *
+     * This endpoint returns the total cost and detailed usage records for all LLM
+     * requests made during a prompt adaptation run. Use this to track costs associated
+     * with optimizing prompts for different target models.
+     *
+     * **Cost Breakdown:**
+     *
+     * - Total cost across all models used in the adaptation
+     * - Individual usage records with provider, model, tokens, and costs
+     * - Timestamps for each LLM request
+     *
+     * **Access Control:**
+     *
+     * - Only accessible by the user who created the adaptation run
+     * - Requires prompt adaptation access
+     *
+     * @example
+     * ```ts
+     * const response = await client.promptAdaptation.getCost(
+     *   'adaptation_run_id',
+     * );
+     * ```
+     */
+    getCost(adaptationRunID, options) {
+        return this._client.get(path `/v2/prompt/adapt/${adaptationRunID}/costs`, options);
+    }
+}
+//# sourceMappingURL=prompt-adaptation.mjs.map

package/resources/prompt-adaptation.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"prompt-adaptation.mjs","sourceRoot":"","sources":["../src/resources/prompt-adaptation.ts"],"names":[],"mappings":"AAAA,sFAAsF;OAE/E,EAAE,WAAW,EAAE;OAIf,EAAE,IAAI,EAAE;AAEf,MAAM,OAAO,gBAAiB,SAAQ,WAAW;IAC/C;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiHG;IACH,KAAK,CACH,IAAiC,EACjC,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,IAAI,CAAC,kBAAkB,EAAE,EAAE,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,CAAC;IACrE,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAwDG;IACH,eAAe,CACb,eAAuB,EACvB,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,2BAA2B,eAAe,EAAE,EAAE,OAAO,CAAC,CAAC;IACrF,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACH,cAAc,CACZ,eAAuB,EACvB,OAAwB;QAExB,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,0BAA0B,eAAe,EAAE,EAAE,OAAO,CAAC,CAAC;IACpF,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,OAAO,CAAC,eAAuB,EAAE,OAAwB;QACvD,OAAO,IAAI,CAAC,OAAO,CAAC,GAAG,CAAC,IAAI,CAAA,oBAAoB,eAAe,QAAQ,EAAE,OAAO,CAAC,CAAC;IACpF,CAAC;CACF"}