opik 2.0.45 → 2.0.47

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/index.d.cts CHANGED
@@ -3212,6 +3212,8 @@ interface AlertTriggerConfigPublic {
3212
3212
  alertTriggerId?: string;
3213
3213
  type: AlertTriggerConfigPublicType;
3214
3214
  configValue?: Record<string, string>;
3215
+ /** Groups configs within a trigger: same group_index means AND between configs, different group_index means OR between groups. Null means a legacy/singleton group of one config. Always null for scope:project configs. */
3216
+ groupIndex?: number;
3215
3217
  createdAt?: Date;
3216
3218
  createdBy?: string;
3217
3219
  lastUpdatedAt?: Date;
@@ -3231,6 +3233,8 @@ interface AlertTriggerConfigWrite {
3231
3233
  id?: string;
3232
3234
  type: AlertTriggerConfigWriteType;
3233
3235
  configValue?: Record<string, string>;
3236
+ /** Groups configs within a trigger: same group_index means AND between configs, different group_index means OR between groups. Null means a legacy/singleton group of one config. Always null for scope:project configs. */
3237
+ groupIndex?: number;
3234
3238
  }
3235
3239
 
3236
3240
  declare const AlertTriggerConfigWriteType: {
@@ -12142,10 +12146,23 @@ interface CreatePromptOptions extends CommonPromptOptions {
12142
12146
  projectName?: string;
12143
12147
  }
12144
12148
  /**
12145
- * Options for retrieving a specific prompt version
12146
- * Re-exported from REST API PromptVersionRetrieveDetail
12149
+ * Options for retrieving a specific prompt version.
12150
+ *
12151
+ * `commit` and `version` are mutually exclusive. If neither is provided,
12152
+ * the latest version is returned.
12147
12153
  */
12148
- type GetPromptOptions = PromptVersionRetrieveDetail;
12154
+ interface GetPromptOptions {
12155
+ /** Name of the prompt to retrieve. */
12156
+ name: string;
12157
+ /** @deprecated Use `version` instead. */
12158
+ commit?: string;
12159
+ /**
12160
+ * Sequential version identifier, e.g. `"v3"`. Mutually exclusive with `commit`.
12161
+ */
12162
+ version?: string;
12163
+ /** Optional project name to scope the lookup. */
12164
+ projectName?: string;
12165
+ }
12149
12166
  /**
12150
12167
  * Variables to be substituted into prompt template.
12151
12168
  */
@@ -12157,6 +12174,7 @@ interface PromptVersionData {
12157
12174
  name: string;
12158
12175
  prompt: string;
12159
12176
  commit: string;
12177
+ version?: string;
12160
12178
  promptId: string;
12161
12179
  versionId: string;
12162
12180
  type: PromptType;
@@ -12214,7 +12232,15 @@ declare class PromptVersion {
12214
12232
  readonly id: string;
12215
12233
  readonly name: string;
12216
12234
  readonly prompt: string;
12235
+ /**
12236
+ * @deprecated Legacy commit hash of this prompt version. Use {@link version} instead — `commit` is no longer surfaced in the Opik UI and is kept only for backwards compatibility with older SDK callers.
12237
+ */
12217
12238
  readonly commit: string;
12239
+ /**
12240
+ * Sequential version identifier of this prompt version (e.g. `"v3"`).
12241
+ * Undefined for mask versions, which do not carry a version number.
12242
+ */
12243
+ readonly version?: string;
12218
12244
  readonly type: PromptType;
12219
12245
  readonly metadata?: JsonNode;
12220
12246
  readonly changeDescription?: string;
@@ -12231,8 +12257,9 @@ declare class PromptVersion {
12231
12257
  */
12232
12258
  getVersionAge(): string;
12233
12259
  /**
12234
- * Get formatted version information string
12235
- * Format: "[commitHash] YYYY-MM-DD by user@email.com - Change description"
12260
+ * Get formatted version information string.
12261
+ * Format: "[v3] YYYY-MM-DD by user@email.com - Change description"
12262
+ * (falls back to the commit hash for mask versions, which have no version number).
12236
12263
  */
12237
12264
  getVersionInfo(): string;
12238
12265
  /**
@@ -12247,11 +12274,11 @@ declare class PromptVersion {
12247
12274
  *
12248
12275
  * @example
12249
12276
  * ```typescript
12250
- * const currentVersion = await prompt.getVersion("commit123");
12251
- * const previousVersion = await prompt.getVersion("commit456");
12277
+ * const versions = await prompt.getVersions();
12278
+ * const [current, previous] = versions;
12252
12279
  *
12253
12280
  * // Logs diff to terminal and returns it
12254
- * const diff = currentVersion.compareTo(previousVersion);
12281
+ * const diff = current.compareTo(previous);
12255
12282
  * ```
12256
12283
  */
12257
12284
  compareTo(other: PromptVersion): string;
@@ -12277,6 +12304,7 @@ interface BasePromptData {
12277
12304
  versionId?: string;
12278
12305
  name: string;
12279
12306
  commit?: string;
12307
+ version?: string;
12280
12308
  metadata?: JsonNode;
12281
12309
  type?: PromptType;
12282
12310
  changeDescription?: string;
@@ -12294,6 +12322,7 @@ declare abstract class BasePrompt {
12294
12322
  private _id;
12295
12323
  private _versionId;
12296
12324
  private _commit;
12325
+ private _version;
12297
12326
  private _synced;
12298
12327
  private _changeDescription;
12299
12328
  private _projectName;
@@ -12309,6 +12338,7 @@ declare abstract class BasePrompt {
12309
12338
  get id(): string | undefined;
12310
12339
  get versionId(): string | undefined;
12311
12340
  get commit(): string | undefined;
12341
+ get version(): string | undefined;
12312
12342
  /** Whether the prompt has been successfully synced with the backend. */
12313
12343
  get synced(): boolean;
12314
12344
  get changeDescription(): string | undefined;
@@ -12321,6 +12351,7 @@ declare abstract class BasePrompt {
12321
12351
  promptId?: string;
12322
12352
  versionId?: string;
12323
12353
  commit?: string;
12354
+ version?: string;
12324
12355
  changeDescription?: string;
12325
12356
  tags?: string[];
12326
12357
  projectName?: string;
@@ -12384,26 +12415,31 @@ declare abstract class BasePrompt {
12384
12415
  */
12385
12416
  protected restoreVersion(version: PromptVersion): Promise<PromptVersionDetail>;
12386
12417
  /**
12387
- * Helper method to retrieve a version by commit hash.
12388
- * Used by subclasses in their getVersion implementations.
12418
+ * Helper method to retrieve a version by its sequential version identifier
12419
+ * (e.g. `"v3"`) or, for backwards compatibility, by its commit hash.
12420
+ *
12421
+ * Input matching `/^v\d+$/` is dispatched to the `versionNumber` endpoint;
12422
+ * anything else is treated as a commit hash. Commit-based fetching is
12423
+ * deprecated — pass a `"v<N>"` identifier instead.
12389
12424
  *
12390
- * @param commit - Commit hash (8-char short form or full)
12425
+ * @param version - Sequential version (`"v3"`) or commit hash (deprecated)
12391
12426
  * @returns Promise resolving to the API response or null if not found
12392
12427
  */
12393
- protected retrieveVersionByCommit(commit: string): Promise<PromptVersionDetail | null>;
12428
+ protected retrieveVersion(version: string): Promise<PromptVersionDetail | null>;
12394
12429
  /**
12395
12430
  * Throws an error if the prompt has not been successfully synced with the backend.
12396
12431
  * Used internally before backend operations to ensure we have a valid prompt ID.
12397
12432
  */
12398
12433
  protected ensureSynced(operation: string): void;
12399
12434
  /**
12400
- * Get a specific version by commit hash.
12401
- * Returns a new instance of the appropriate prompt type.
12435
+ * Get a specific version by its sequential version identifier (e.g. `"v3"`)
12436
+ * or, for backwards compatibility, by its commit hash. Returns a new instance
12437
+ * of the appropriate prompt type.
12402
12438
  *
12403
- * @param commit - Commit hash (8-char short form or full)
12439
+ * @param version - Sequential version (`"v<N>"`) preferred; or commit hash (deprecated)
12404
12440
  * @returns Promise resolving to prompt instance or null if not found
12405
12441
  */
12406
- abstract getVersion(commit: string): Promise<BasePrompt | null>;
12442
+ abstract getVersion(version: string): Promise<BasePrompt | null>;
12407
12443
  /**
12408
12444
  * Restores a specific version by creating a new version with content from the specified version.
12409
12445
  *
@@ -13262,12 +13298,26 @@ declare class Prompt extends BasePrompt {
13262
13298
  */
13263
13299
  syncWithBackend(): Promise<Prompt>;
13264
13300
  /**
13265
- * Get a Prompt with a specific version by commit hash.
13301
+ * Get a Prompt at a specific version.
13266
13302
  *
13267
- * @param commit - Commit hash (8-char short form or full)
13303
+ * Accepts either the sequential version identifier (e.g. `"v3"`) preferred
13304
+ * or a commit hash for backwards compatibility. Inputs matching `/^v\d+$/`
13305
+ * are treated as version numbers; anything else is treated as a commit.
13306
+ *
13307
+ * @param version - Sequential version (`"v<N>"`) or commit hash
13308
+ * (commit input is **deprecated** — pass a `"v<N>"` identifier instead).
13268
13309
  * @returns Prompt instance representing that version, or null if not found
13310
+ *
13311
+ * @example
13312
+ * ```typescript
13313
+ * // Preferred
13314
+ * const v3 = await prompt.getVersion("v3");
13315
+ *
13316
+ * // @deprecated — commit-shaped input
13317
+ * const byCommit = await prompt.getVersion("abc123de");
13318
+ * ```
13269
13319
  */
13270
- getVersion(commit: string): Promise<Prompt | null>;
13320
+ getVersion(version: string): Promise<Prompt | null>;
13271
13321
  }
13272
13322
 
13273
13323
  interface EvaluateTestSuiteOptions<T = Record<string, unknown>> {
@@ -13807,12 +13857,26 @@ declare class ChatPrompt extends BasePrompt {
13807
13857
  */
13808
13858
  syncWithBackend(): Promise<ChatPrompt>;
13809
13859
  /**
13810
- * Get a ChatPrompt with a specific version by commit hash.
13860
+ * Get a ChatPrompt at a specific version.
13811
13861
  *
13812
- * @param commit - Commit hash (8-char short form or full)
13862
+ * Accepts either the sequential version identifier (e.g. `"v3"`) preferred
13863
+ * or a commit hash for backwards compatibility. Inputs matching `/^v\d+$/`
13864
+ * are treated as version numbers; anything else is treated as a commit.
13865
+ *
13866
+ * @param version - Sequential version (`"v<N>"`) or commit hash
13867
+ * (commit input is **deprecated** — pass a `"v<N>"` identifier instead).
13813
13868
  * @returns ChatPrompt instance representing that version, or null if not found
13869
+ *
13870
+ * @example
13871
+ * ```typescript
13872
+ * // Preferred
13873
+ * const v3 = await chatPrompt.getVersion("v3");
13874
+ *
13875
+ * // @deprecated — commit-shaped input
13876
+ * const byCommit = await chatPrompt.getVersion("abc123de");
13877
+ * ```
13814
13878
  */
13815
- getVersion(commit: string): Promise<ChatPrompt | null>;
13879
+ getVersion(version: string): Promise<ChatPrompt | null>;
13816
13880
  }
13817
13881
 
13818
13882
  interface AnnotationQueueData {
@@ -14221,24 +14285,36 @@ declare class OpikClient {
14221
14285
  */
14222
14286
  createChatPrompt: (options: CreateChatPromptOptions) => Promise<ChatPrompt>;
14223
14287
  /**
14224
- * Retrieves a text prompt by name and optional version.
14288
+ * Retrieves a text prompt by name, optionally targeting a specific `version`.
14225
14289
  * Results are cached client-side (TTL configurable via OPIK_PROMPT_CACHE_TTL_SECONDS,
14226
- * default 300s). Pinned commits are cached indefinitely. When called inside a track()
14227
- * context the prompt reference is injected into the active trace/span metadata.
14228
- *
14229
- * @param options - Prompt name and optional commit hash
14290
+ * default 300s). When called inside a track() context the prompt reference
14291
+ * is injected into the active trace/span metadata.
14292
+ *
14293
+ * @param options - Prompt name and optional version pin
14294
+ * @param options.name - Name of the prompt
14295
+ * @param options.version - Sequential version identifier (e.g. `"v3"`). If not
14296
+ * provided, the latest version is returned.
14297
+ * @param options.commit - **Deprecated.** Use `version` instead.
14298
+ * @param options.projectName - Optional project scope.
14230
14299
  * @returns Promise resolving to Prompt or null if not found
14300
+ * @throws Error if both `commit` and `version` are provided
14231
14301
  * @throws PromptTemplateStructureMismatch if prompt exists but is a chat prompt
14232
14302
  */
14233
14303
  getPrompt: (options: GetPromptOptions) => Promise<Prompt | null>;
14234
14304
  /**
14235
- * Retrieves a chat prompt by name and optional version.
14305
+ * Retrieves a chat prompt by name, optionally targeting a specific `version`.
14236
14306
  * Results are cached client-side (TTL configurable via OPIK_PROMPT_CACHE_TTL_SECONDS,
14237
- * default 300s). Pinned commits are cached indefinitely. When called inside a track()
14238
- * context the prompt reference is injected into the active trace/span metadata.
14239
- *
14240
- * @param options - Prompt name and optional commit hash
14307
+ * default 300s). When called inside a track() context the prompt reference
14308
+ * is injected into the active trace/span metadata.
14309
+ *
14310
+ * @param options - Prompt name and optional version pin
14311
+ * @param options.name - Name of the prompt
14312
+ * @param options.version - Sequential version identifier (e.g. `"v3"`). If not
14313
+ * provided, the latest version is returned.
14314
+ * @param options.commit - **Deprecated.** Use `version` instead.
14315
+ * @param options.projectName - Optional project scope.
14241
14316
  * @returns Promise resolving to ChatPrompt or null if not found
14317
+ * @throws Error if both `commit` and `version` are provided
14242
14318
  * @throws PromptTemplateStructureMismatch if prompt exists but is a text prompt
14243
14319
  *
14244
14320
  * @example
@@ -16557,6 +16633,10 @@ declare class OpikQueryLanguage {
16557
16633
  * Create an OpikQueryLanguage instance for prompt filtering
16558
16634
  */
16559
16635
  static forPrompts(queryString?: string): OpikQueryLanguage;
16636
+ /**
16637
+ * Create an OpikQueryLanguage instance for prompt version filtering
16638
+ */
16639
+ static forPromptVersions(queryString?: string): OpikQueryLanguage;
16560
16640
  /**
16561
16641
  * Returns the parsed filter expressions
16562
16642
  */
package/dist/index.d.ts CHANGED
@@ -3212,6 +3212,8 @@ interface AlertTriggerConfigPublic {
3212
3212
  alertTriggerId?: string;
3213
3213
  type: AlertTriggerConfigPublicType;
3214
3214
  configValue?: Record<string, string>;
3215
+ /** Groups configs within a trigger: same group_index means AND between configs, different group_index means OR between groups. Null means a legacy/singleton group of one config. Always null for scope:project configs. */
3216
+ groupIndex?: number;
3215
3217
  createdAt?: Date;
3216
3218
  createdBy?: string;
3217
3219
  lastUpdatedAt?: Date;
@@ -3231,6 +3233,8 @@ interface AlertTriggerConfigWrite {
3231
3233
  id?: string;
3232
3234
  type: AlertTriggerConfigWriteType;
3233
3235
  configValue?: Record<string, string>;
3236
+ /** Groups configs within a trigger: same group_index means AND between configs, different group_index means OR between groups. Null means a legacy/singleton group of one config. Always null for scope:project configs. */
3237
+ groupIndex?: number;
3234
3238
  }
3235
3239
 
3236
3240
  declare const AlertTriggerConfigWriteType: {
@@ -12142,10 +12146,23 @@ interface CreatePromptOptions extends CommonPromptOptions {
12142
12146
  projectName?: string;
12143
12147
  }
12144
12148
  /**
12145
- * Options for retrieving a specific prompt version
12146
- * Re-exported from REST API PromptVersionRetrieveDetail
12149
+ * Options for retrieving a specific prompt version.
12150
+ *
12151
+ * `commit` and `version` are mutually exclusive. If neither is provided,
12152
+ * the latest version is returned.
12147
12153
  */
12148
- type GetPromptOptions = PromptVersionRetrieveDetail;
12154
+ interface GetPromptOptions {
12155
+ /** Name of the prompt to retrieve. */
12156
+ name: string;
12157
+ /** @deprecated Use `version` instead. */
12158
+ commit?: string;
12159
+ /**
12160
+ * Sequential version identifier, e.g. `"v3"`. Mutually exclusive with `commit`.
12161
+ */
12162
+ version?: string;
12163
+ /** Optional project name to scope the lookup. */
12164
+ projectName?: string;
12165
+ }
12149
12166
  /**
12150
12167
  * Variables to be substituted into prompt template.
12151
12168
  */
@@ -12157,6 +12174,7 @@ interface PromptVersionData {
12157
12174
  name: string;
12158
12175
  prompt: string;
12159
12176
  commit: string;
12177
+ version?: string;
12160
12178
  promptId: string;
12161
12179
  versionId: string;
12162
12180
  type: PromptType;
@@ -12214,7 +12232,15 @@ declare class PromptVersion {
12214
12232
  readonly id: string;
12215
12233
  readonly name: string;
12216
12234
  readonly prompt: string;
12235
+ /**
12236
+ * @deprecated Legacy commit hash of this prompt version. Use {@link version} instead — `commit` is no longer surfaced in the Opik UI and is kept only for backwards compatibility with older SDK callers.
12237
+ */
12217
12238
  readonly commit: string;
12239
+ /**
12240
+ * Sequential version identifier of this prompt version (e.g. `"v3"`).
12241
+ * Undefined for mask versions, which do not carry a version number.
12242
+ */
12243
+ readonly version?: string;
12218
12244
  readonly type: PromptType;
12219
12245
  readonly metadata?: JsonNode;
12220
12246
  readonly changeDescription?: string;
@@ -12231,8 +12257,9 @@ declare class PromptVersion {
12231
12257
  */
12232
12258
  getVersionAge(): string;
12233
12259
  /**
12234
- * Get formatted version information string
12235
- * Format: "[commitHash] YYYY-MM-DD by user@email.com - Change description"
12260
+ * Get formatted version information string.
12261
+ * Format: "[v3] YYYY-MM-DD by user@email.com - Change description"
12262
+ * (falls back to the commit hash for mask versions, which have no version number).
12236
12263
  */
12237
12264
  getVersionInfo(): string;
12238
12265
  /**
@@ -12247,11 +12274,11 @@ declare class PromptVersion {
12247
12274
  *
12248
12275
  * @example
12249
12276
  * ```typescript
12250
- * const currentVersion = await prompt.getVersion("commit123");
12251
- * const previousVersion = await prompt.getVersion("commit456");
12277
+ * const versions = await prompt.getVersions();
12278
+ * const [current, previous] = versions;
12252
12279
  *
12253
12280
  * // Logs diff to terminal and returns it
12254
- * const diff = currentVersion.compareTo(previousVersion);
12281
+ * const diff = current.compareTo(previous);
12255
12282
  * ```
12256
12283
  */
12257
12284
  compareTo(other: PromptVersion): string;
@@ -12277,6 +12304,7 @@ interface BasePromptData {
12277
12304
  versionId?: string;
12278
12305
  name: string;
12279
12306
  commit?: string;
12307
+ version?: string;
12280
12308
  metadata?: JsonNode;
12281
12309
  type?: PromptType;
12282
12310
  changeDescription?: string;
@@ -12294,6 +12322,7 @@ declare abstract class BasePrompt {
12294
12322
  private _id;
12295
12323
  private _versionId;
12296
12324
  private _commit;
12325
+ private _version;
12297
12326
  private _synced;
12298
12327
  private _changeDescription;
12299
12328
  private _projectName;
@@ -12309,6 +12338,7 @@ declare abstract class BasePrompt {
12309
12338
  get id(): string | undefined;
12310
12339
  get versionId(): string | undefined;
12311
12340
  get commit(): string | undefined;
12341
+ get version(): string | undefined;
12312
12342
  /** Whether the prompt has been successfully synced with the backend. */
12313
12343
  get synced(): boolean;
12314
12344
  get changeDescription(): string | undefined;
@@ -12321,6 +12351,7 @@ declare abstract class BasePrompt {
12321
12351
  promptId?: string;
12322
12352
  versionId?: string;
12323
12353
  commit?: string;
12354
+ version?: string;
12324
12355
  changeDescription?: string;
12325
12356
  tags?: string[];
12326
12357
  projectName?: string;
@@ -12384,26 +12415,31 @@ declare abstract class BasePrompt {
12384
12415
  */
12385
12416
  protected restoreVersion(version: PromptVersion): Promise<PromptVersionDetail>;
12386
12417
  /**
12387
- * Helper method to retrieve a version by commit hash.
12388
- * Used by subclasses in their getVersion implementations.
12418
+ * Helper method to retrieve a version by its sequential version identifier
12419
+ * (e.g. `"v3"`) or, for backwards compatibility, by its commit hash.
12420
+ *
12421
+ * Input matching `/^v\d+$/` is dispatched to the `versionNumber` endpoint;
12422
+ * anything else is treated as a commit hash. Commit-based fetching is
12423
+ * deprecated — pass a `"v<N>"` identifier instead.
12389
12424
  *
12390
- * @param commit - Commit hash (8-char short form or full)
12425
+ * @param version - Sequential version (`"v3"`) or commit hash (deprecated)
12391
12426
  * @returns Promise resolving to the API response or null if not found
12392
12427
  */
12393
- protected retrieveVersionByCommit(commit: string): Promise<PromptVersionDetail | null>;
12428
+ protected retrieveVersion(version: string): Promise<PromptVersionDetail | null>;
12394
12429
  /**
12395
12430
  * Throws an error if the prompt has not been successfully synced with the backend.
12396
12431
  * Used internally before backend operations to ensure we have a valid prompt ID.
12397
12432
  */
12398
12433
  protected ensureSynced(operation: string): void;
12399
12434
  /**
12400
- * Get a specific version by commit hash.
12401
- * Returns a new instance of the appropriate prompt type.
12435
+ * Get a specific version by its sequential version identifier (e.g. `"v3"`)
12436
+ * or, for backwards compatibility, by its commit hash. Returns a new instance
12437
+ * of the appropriate prompt type.
12402
12438
  *
12403
- * @param commit - Commit hash (8-char short form or full)
12439
+ * @param version - Sequential version (`"v<N>"`) preferred; or commit hash (deprecated)
12404
12440
  * @returns Promise resolving to prompt instance or null if not found
12405
12441
  */
12406
- abstract getVersion(commit: string): Promise<BasePrompt | null>;
12442
+ abstract getVersion(version: string): Promise<BasePrompt | null>;
12407
12443
  /**
12408
12444
  * Restores a specific version by creating a new version with content from the specified version.
12409
12445
  *
@@ -13262,12 +13298,26 @@ declare class Prompt extends BasePrompt {
13262
13298
  */
13263
13299
  syncWithBackend(): Promise<Prompt>;
13264
13300
  /**
13265
- * Get a Prompt with a specific version by commit hash.
13301
+ * Get a Prompt at a specific version.
13266
13302
  *
13267
- * @param commit - Commit hash (8-char short form or full)
13303
+ * Accepts either the sequential version identifier (e.g. `"v3"`) preferred
13304
+ * or a commit hash for backwards compatibility. Inputs matching `/^v\d+$/`
13305
+ * are treated as version numbers; anything else is treated as a commit.
13306
+ *
13307
+ * @param version - Sequential version (`"v<N>"`) or commit hash
13308
+ * (commit input is **deprecated** — pass a `"v<N>"` identifier instead).
13268
13309
  * @returns Prompt instance representing that version, or null if not found
13310
+ *
13311
+ * @example
13312
+ * ```typescript
13313
+ * // Preferred
13314
+ * const v3 = await prompt.getVersion("v3");
13315
+ *
13316
+ * // @deprecated — commit-shaped input
13317
+ * const byCommit = await prompt.getVersion("abc123de");
13318
+ * ```
13269
13319
  */
13270
- getVersion(commit: string): Promise<Prompt | null>;
13320
+ getVersion(version: string): Promise<Prompt | null>;
13271
13321
  }
13272
13322
 
13273
13323
  interface EvaluateTestSuiteOptions<T = Record<string, unknown>> {
@@ -13807,12 +13857,26 @@ declare class ChatPrompt extends BasePrompt {
13807
13857
  */
13808
13858
  syncWithBackend(): Promise<ChatPrompt>;
13809
13859
  /**
13810
- * Get a ChatPrompt with a specific version by commit hash.
13860
+ * Get a ChatPrompt at a specific version.
13811
13861
  *
13812
- * @param commit - Commit hash (8-char short form or full)
13862
+ * Accepts either the sequential version identifier (e.g. `"v3"`) preferred
13863
+ * or a commit hash for backwards compatibility. Inputs matching `/^v\d+$/`
13864
+ * are treated as version numbers; anything else is treated as a commit.
13865
+ *
13866
+ * @param version - Sequential version (`"v<N>"`) or commit hash
13867
+ * (commit input is **deprecated** — pass a `"v<N>"` identifier instead).
13813
13868
  * @returns ChatPrompt instance representing that version, or null if not found
13869
+ *
13870
+ * @example
13871
+ * ```typescript
13872
+ * // Preferred
13873
+ * const v3 = await chatPrompt.getVersion("v3");
13874
+ *
13875
+ * // @deprecated — commit-shaped input
13876
+ * const byCommit = await chatPrompt.getVersion("abc123de");
13877
+ * ```
13814
13878
  */
13815
- getVersion(commit: string): Promise<ChatPrompt | null>;
13879
+ getVersion(version: string): Promise<ChatPrompt | null>;
13816
13880
  }
13817
13881
 
13818
13882
  interface AnnotationQueueData {
@@ -14221,24 +14285,36 @@ declare class OpikClient {
14221
14285
  */
14222
14286
  createChatPrompt: (options: CreateChatPromptOptions) => Promise<ChatPrompt>;
14223
14287
  /**
14224
- * Retrieves a text prompt by name and optional version.
14288
+ * Retrieves a text prompt by name, optionally targeting a specific `version`.
14225
14289
  * Results are cached client-side (TTL configurable via OPIK_PROMPT_CACHE_TTL_SECONDS,
14226
- * default 300s). Pinned commits are cached indefinitely. When called inside a track()
14227
- * context the prompt reference is injected into the active trace/span metadata.
14228
- *
14229
- * @param options - Prompt name and optional commit hash
14290
+ * default 300s). When called inside a track() context the prompt reference
14291
+ * is injected into the active trace/span metadata.
14292
+ *
14293
+ * @param options - Prompt name and optional version pin
14294
+ * @param options.name - Name of the prompt
14295
+ * @param options.version - Sequential version identifier (e.g. `"v3"`). If not
14296
+ * provided, the latest version is returned.
14297
+ * @param options.commit - **Deprecated.** Use `version` instead.
14298
+ * @param options.projectName - Optional project scope.
14230
14299
  * @returns Promise resolving to Prompt or null if not found
14300
+ * @throws Error if both `commit` and `version` are provided
14231
14301
  * @throws PromptTemplateStructureMismatch if prompt exists but is a chat prompt
14232
14302
  */
14233
14303
  getPrompt: (options: GetPromptOptions) => Promise<Prompt | null>;
14234
14304
  /**
14235
- * Retrieves a chat prompt by name and optional version.
14305
+ * Retrieves a chat prompt by name, optionally targeting a specific `version`.
14236
14306
  * Results are cached client-side (TTL configurable via OPIK_PROMPT_CACHE_TTL_SECONDS,
14237
- * default 300s). Pinned commits are cached indefinitely. When called inside a track()
14238
- * context the prompt reference is injected into the active trace/span metadata.
14239
- *
14240
- * @param options - Prompt name and optional commit hash
14307
+ * default 300s). When called inside a track() context the prompt reference
14308
+ * is injected into the active trace/span metadata.
14309
+ *
14310
+ * @param options - Prompt name and optional version pin
14311
+ * @param options.name - Name of the prompt
14312
+ * @param options.version - Sequential version identifier (e.g. `"v3"`). If not
14313
+ * provided, the latest version is returned.
14314
+ * @param options.commit - **Deprecated.** Use `version` instead.
14315
+ * @param options.projectName - Optional project scope.
14241
14316
  * @returns Promise resolving to ChatPrompt or null if not found
14317
+ * @throws Error if both `commit` and `version` are provided
14242
14318
  * @throws PromptTemplateStructureMismatch if prompt exists but is a text prompt
14243
14319
  *
14244
14320
  * @example
@@ -16557,6 +16633,10 @@ declare class OpikQueryLanguage {
16557
16633
  * Create an OpikQueryLanguage instance for prompt filtering
16558
16634
  */
16559
16635
  static forPrompts(queryString?: string): OpikQueryLanguage;
16636
+ /**
16637
+ * Create an OpikQueryLanguage instance for prompt version filtering
16638
+ */
16639
+ static forPromptVersions(queryString?: string): OpikQueryLanguage;
16560
16640
  /**
16561
16641
  * Returns the parsed filter expressions
16562
16642
  */
package/dist/index.js CHANGED
@@ -1 +1 @@
1
- import {Fa}from'./chunk-7EDVDI2X.js';export{sa as AgentTaskCompletionJudge,ra as AgentToolCorrectnessJudge,fa as AnswerRelevance,ba as BaseLLMJudgeMetric,C as BaseMetric,D as BaseSuiteEvaluator,p as ChatPrompt,ua as ComplianceRiskJudge,i as ConfigMismatchError,h as ConfigNotFoundError,_ as Contains,y as DEFAULT_EXECUTION_POLICY,j as Dataset,f as DatasetVersion,g as DatasetVersionNotFoundError,ma as DemographicBiasJudge,ka as DialogueHelpfulnessJudge,Z as ExactMatch,ga as GEval,ha as GEvalPreset,oa as GenderBiasJudge,ea as Hallucination,aa as IsJson,Q as LLMJudge,H as ModelConfigurationError,F as ModelError,G as ModelGenerationError,ca as Moderation,Ca as OPIK_PARENT_SPAN_ID_HEADER,Ba as OPIK_TRACE_ID_HEADER,Aa as Opik,E as OpikBaseModel,q as OpikQueryLanguage,d as OpikSpanType,na as PoliticalBiasJudge,o as Prompt,k as PromptType,ta as PromptUncertaintyJudge,la as QARelevanceJudge,$ as RegexMatch,qa as RegionalBiasJudge,pa as ReligiousBiasJudge,P as ResponseSchema,N as SYSTEM_PROMPT,ja as SummarizationCoherenceJudge,ia as SummarizationConsistencyJudge,B as TASK_ERROR_SCORE_NAME,ya as TestSuite,z as TestSuiteResult,s as ThreadsAnnotationQueue,r as TracesAnnotationQueue,O as USER_PROMPT_TEMPLATE,da as Usefulness,J as VercelAIChatModel,v as activateRunner,t as agentConfigContext,A as buildSuiteResult,K as createModel,L as createModelFromInstance,S as deserializeEvaluators,I as detectProvider,c as disableLogger,X as evaluate,Y as evaluatePrompt,V as evaluateTestSuite,u as flushAll,e as generateId,Da as getDistributedTraceHeaders,l as getGlobalClient,w as getTrackContext,a as logger,n as resetGlobalClient,va as resolveEvaluators,T as resolveExecutionPolicy,U as resolveItemExecutionPolicy,M as resolveModel,W as runTests,R as serializeEvaluators,m as setGlobalClient,b as setLoggerLevel,x as track,wa as validateEvaluators,xa as validateExecutionPolicy,Ea as z}from'./chunk-7EDVDI2X.js';Fa();
1
+ import {Fa}from'./chunk-5GE2OGBF.js';export{sa as AgentTaskCompletionJudge,ra as AgentToolCorrectnessJudge,fa as AnswerRelevance,ba as BaseLLMJudgeMetric,C as BaseMetric,D as BaseSuiteEvaluator,p as ChatPrompt,ua as ComplianceRiskJudge,i as ConfigMismatchError,h as ConfigNotFoundError,_ as Contains,y as DEFAULT_EXECUTION_POLICY,j as Dataset,f as DatasetVersion,g as DatasetVersionNotFoundError,ma as DemographicBiasJudge,ka as DialogueHelpfulnessJudge,Z as ExactMatch,ga as GEval,ha as GEvalPreset,oa as GenderBiasJudge,ea as Hallucination,aa as IsJson,Q as LLMJudge,H as ModelConfigurationError,F as ModelError,G as ModelGenerationError,ca as Moderation,Ca as OPIK_PARENT_SPAN_ID_HEADER,Ba as OPIK_TRACE_ID_HEADER,Aa as Opik,E as OpikBaseModel,q as OpikQueryLanguage,d as OpikSpanType,na as PoliticalBiasJudge,o as Prompt,k as PromptType,ta as PromptUncertaintyJudge,la as QARelevanceJudge,$ as RegexMatch,qa as RegionalBiasJudge,pa as ReligiousBiasJudge,P as ResponseSchema,N as SYSTEM_PROMPT,ja as SummarizationCoherenceJudge,ia as SummarizationConsistencyJudge,B as TASK_ERROR_SCORE_NAME,ya as TestSuite,z as TestSuiteResult,s as ThreadsAnnotationQueue,r as TracesAnnotationQueue,O as USER_PROMPT_TEMPLATE,da as Usefulness,J as VercelAIChatModel,v as activateRunner,t as agentConfigContext,A as buildSuiteResult,K as createModel,L as createModelFromInstance,S as deserializeEvaluators,I as detectProvider,c as disableLogger,X as evaluate,Y as evaluatePrompt,V as evaluateTestSuite,u as flushAll,e as generateId,Da as getDistributedTraceHeaders,l as getGlobalClient,w as getTrackContext,a as logger,n as resetGlobalClient,va as resolveEvaluators,T as resolveExecutionPolicy,U as resolveItemExecutionPolicy,M as resolveModel,W as runTests,R as serializeEvaluators,m as setGlobalClient,b as setLoggerLevel,x as track,wa as validateEvaluators,xa as validateExecutionPolicy,Ea as z}from'./chunk-5GE2OGBF.js';Fa();
@@ -1 +1 @@
1
- import {za}from'./chunk-7EDVDI2X.js';export{y as DEFAULT_EXECUTION_POLICY,ya as TestSuite,z as TestSuiteResult,A as buildSuiteResult,S as deserializeEvaluators,V as evaluateTestSuite,T as resolveExecutionPolicy,U as resolveItemExecutionPolicy,W as runTests,R as serializeEvaluators}from'./chunk-7EDVDI2X.js';za();
1
+ import {za}from'./chunk-5GE2OGBF.js';export{y as DEFAULT_EXECUTION_POLICY,ya as TestSuite,z as TestSuiteResult,A as buildSuiteResult,S as deserializeEvaluators,V as evaluateTestSuite,T as resolveExecutionPolicy,U as resolveItemExecutionPolicy,W as runTests,R as serializeEvaluators}from'./chunk-5GE2OGBF.js';za();
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "opik",
3
3
  "description": "Opik TypeScript and JavaScript SDK",
4
- "version": "2.0.45",
4
+ "version": "2.0.47",
5
5
  "repository": {
6
6
  "type": "git",
7
7
  "url": "git+https://github.com/comet-ml/opik.git",