langsmith 0.7.12 → 0.7.14

package/dist/sandbox/client.js

@@ -4,6 +4,7 @@
 import { getLangSmithEnvironmentVariable } from "../utils/env.js";
 import { _getFetchImplementation } from "../singletons/fetch.js";
 import { AsyncCaller } from "../utils/async_caller.js";
+import { Langsmith as OpenAPILangsmith } from "../_openapi_client/index.js";
 import { Sandbox } from "./sandbox.js";
 import { LangSmithResourceCreationError, LangSmithResourceNameConflictError, LangSmithResourceNotFoundError, LangSmithResourceTimeoutError, LangSmithSandboxAPIError, LangSmithValidationError, } from "./errors.js";
 import { handleClientHttpError, handleSandboxCreationError, validateTtl, } from "./helpers.js";
@@ -293,6 +294,12 @@ export class SandboxClient {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "_registriesClient", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         this._baseUrl = (config.apiEndpoint ?? getDefaultApiEndpoint()).replace(/\/$/, "");
         this._apiKey = config.apiKey ?? getDefaultApiKey();
         this._defaultHeaders = { ...(config.headers ?? {}) };
@@ -302,6 +309,51 @@ export class SandboxClient {
             maxConcurrency: config.maxConcurrency ?? Infinity,
         });
     }
+    _apiRoot() {
+        const suffix = "/v2/sandboxes";
+        return this._baseUrl.endsWith(suffix)
+            ? this._baseUrl.slice(0, -suffix.length)
+            : this._baseUrl;
+    }
+    /**
+     * Manage sandbox image registries: create, list, retrieve, update, delete.
+     *
+     * A registry stores credentials for pulling private images. Create one, then
+     * pass its `id` as `registryId` when building a snapshot.
+     *
+     * @example
+     * ```typescript
+     * const registry = await client.registries.create({
+     *   name: "internal",
+     *   url: "registry.example.com",
+     *   username: "robot",
+     *   password: process.env.REGISTRY_PASSWORD,
+     * });
+     * const snapshot = await client.createSnapshot(
+     *   "internal-python",
+     *   "registry.example.com/internal/python:3.12",
+     *   2_147_483_648,
+     *   { registryId: registry.id },
+     * );
+     * ```
+     */
+    get registries() {
+        if (!this._registriesClient) {
+            const defaultHeaders = {
+                ...this._defaultHeaders,
+            };
+            if (this._apiKey === undefined) {
+                defaultHeaders["X-API-Key"] = null;
+            }
+            this._registriesClient = new OpenAPILangsmith({
+                apiKey: this._apiKey,
+                baseURL: this._apiRoot(),
+                defaultHeaders,
+                fetch: this._fetchImpl,
+            });
+        }
+        return this._registriesClient.sandboxes.registries;
+    }
     /**
      * Internal fetch method that adds authentication headers.
      *
@@ -616,11 +668,11 @@ export class SandboxClient {
      * @param name - Snapshot name.
      * @param dockerImage - Docker image to build from (e.g., "python:3.12-slim").
      * @param fsCapacityBytes - Filesystem capacity in bytes.
-     * @param options - Additional options (registry credentials, timeout).
+     * @param options - Additional options (registry ID, timeout).
      * @returns Snapshot in "ready" status.
      */
     async createSnapshot(name, dockerImage, fsCapacityBytes, options = {}) {
-        const { registryId, registryUrl, registryUsername, registryPassword, timeout = 60, signal, } = options;
+        const { registryId, timeout = 60, signal } = options;
         const url = `${this._baseUrl}/snapshots`;
         const payload = {
             name,
@@ -630,15 +682,6 @@ export class SandboxClient {
         if (registryId !== undefined) {
             payload.registry_id = registryId;
         }
-        if (registryUrl !== undefined) {
-            payload.registry_url = registryUrl;
-        }
-        if (registryUsername !== undefined) {
-            payload.registry_username = registryUsername;
-        }
-        if (registryPassword !== undefined) {
-            payload.registry_password = registryPassword;
-        }
         const response = await this._postJson(url, payload, { signal });
         const snapshot = (await response.json());
         return this.waitForSnapshot(snapshot.id, { timeout, signal });

package/dist/sandbox/sandbox.cjs

@@ -162,15 +162,16 @@ class Sandbox {
         this._client = client;
     }
     /**
-     * Validate and return the dataplane URL.
-     * @throws LangSmithSandboxNotReadyError if sandbox status is not "ready".
+     * Return the dataplane URL.
+     *
+     * The client does not gate on lifecycle status: a stopped sandbox is resumed
+     * by the platform when the dataplane request arrives, so only the presence of
+     * a URL is required here. A genuinely not-ready box surfaces the server's
+     * LangSmithSandboxNotReadyError from the request itself.
+     *
      * @throws LangSmithDataplaneNotConfiguredError if dataplane_url is not configured.
      */
     requireDataplaneUrl() {
-        if (this.status && this.status !== "ready") {
-            throw new errors_js_1.LangSmithSandboxNotReadyError(`Sandbox '${this.name}' is not ready (status: ${this.status}). ` +
-                "Use waitForSandbox() to wait for the sandbox to become ready.");
-        }
         if (!this.dataplane_url) {
             throw new errors_js_1.LangSmithDataplaneNotConfiguredError(`Sandbox '${this.name}' does not have a dataplane_url configured. ` +
                 "Runtime operations require a dataplane URL.");

package/dist/sandbox/sandbox.d.ts

@@ -64,8 +64,13 @@ export declare class Sandbox {
     readonly fs_capacity_bytes?: number;
     private _client;
     /**
-     * Validate and return the dataplane URL.
-     * @throws LangSmithSandboxNotReadyError if sandbox status is not "ready".
+     * Return the dataplane URL.
+     *
+     * The client does not gate on lifecycle status: a stopped sandbox is resumed
+     * by the platform when the dataplane request arrives, so only the presence of
+     * a URL is required here. A genuinely not-ready box surfaces the server's
+     * LangSmithSandboxNotReadyError from the request itself.
+     *
      * @throws LangSmithDataplaneNotConfiguredError if dataplane_url is not configured.
      */
     private requireDataplaneUrl;

package/dist/sandbox/sandbox.js

@@ -1,7 +1,7 @@
 /**
  * Sandbox class for interacting with a specific sandbox instance.
  */
-import { LangSmithDataplaneNotConfiguredError, LangSmithSandboxNotReadyError, } from "./errors.js";
+import { LangSmithDataplaneNotConfiguredError } from "./errors.js";
 import { handleSandboxHttpError } from "./helpers.js";
 import { CommandHandle } from "./command_handle.js";
 import { reconnectWsStream, runWsStream } from "./ws_execute.js";
@@ -159,15 +159,16 @@ export class Sandbox {
         this._client = client;
     }
     /**
-     * Validate and return the dataplane URL.
-     * @throws LangSmithSandboxNotReadyError if sandbox status is not "ready".
+     * Return the dataplane URL.
+     *
+     * The client does not gate on lifecycle status: a stopped sandbox is resumed
+     * by the platform when the dataplane request arrives, so only the presence of
+     * a URL is required here. A genuinely not-ready box surfaces the server's
+     * LangSmithSandboxNotReadyError from the request itself.
+     *
      * @throws LangSmithDataplaneNotConfiguredError if dataplane_url is not configured.
      */
     requireDataplaneUrl() {
-        if (this.status && this.status !== "ready") {
-            throw new LangSmithSandboxNotReadyError(`Sandbox '${this.name}' is not ready (status: ${this.status}). ` +
-                "Use waitForSandbox() to wait for the sandbox to become ready.");
-        }
         if (!this.dataplane_url) {
             throw new LangSmithDataplaneNotConfiguredError(`Sandbox '${this.name}' does not have a dataplane_url configured. ` +
                 "Runtime operations require a dataplane URL.");

package/dist/sandbox/types.d.ts

@@ -477,14 +477,8 @@ export interface CreateSandboxOptions {
  * Options for creating a snapshot from a Docker image.
  */
 export interface CreateSnapshotOptions {
-    /** Private registry ID (alternative to URL/credentials). */
+    /** Private registry ID. */
     registryId?: string;
-    /** Registry URL for private images. */
-    registryUrl?: string;
-    /** Registry username. */
-    registryUsername?: string;
-    /** Registry password. */
-    registryPassword?: string;
     /** Timeout in seconds when waiting for ready. Default: 60. */
     timeout?: number;
     /** AbortSignal for cancellation. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "langsmith",
-  "version": "0.7.12",
+  "version": "0.7.14",
   "description": "Client library to connect to the LangSmith Observability and Evaluation Platform.",
   "packageManager": "pnpm@10.33.0",
   "files": [

package/dist/_openapi_client/resources/datasets/experiments.cjs

@@ -1,16 +0,0 @@
-"use strict";
-// @ts-nocheck
-// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Experiments = void 0;
-const resource_js_1 = require("../../core/resource.cjs");
-const path_js_1 = require("../../internal/utils/path.cjs");
-class Experiments extends resource_js_1.APIResource {
-    /**
-     * Stream grouped and aggregated experiments.
-     */
-    grouped(datasetID, body, options) {
-        return this._client.post((0, path_js_1.path) `/api/v1/datasets/${datasetID}/experiments/grouped`, { body, ...options });
-    }
-}
-exports.Experiments = Experiments;

package/dist/_openapi_client/resources/datasets/experiments.d.ts

@@ -1,23 +0,0 @@
-import { APIResource } from '../../core/resource.js';
-import { APIPromise } from '../../core/api-promise.js';
-import { RequestOptions } from '../../internal/request-options.js';
-export declare class Experiments extends APIResource {
-    /**
-     * Stream grouped and aggregated experiments.
-     */
-    grouped(datasetID: string, body: ExperimentGroupedParams, options?: RequestOptions): APIPromise<unknown>;
-}
-export type ExperimentGroupedResponse = unknown;
-export interface ExperimentGroupedParams {
-    metadata_keys: Array<string>;
-    dataset_version?: string | null;
-    experiment_limit?: number;
-    filter?: string | null;
-    name_contains?: string | null;
-    stats_start_time?: string | null;
-    tag_value_id?: Array<string> | null;
-    use_approx_stats?: boolean;
-}
-export declare namespace Experiments {
-    export { type ExperimentGroupedResponse as ExperimentGroupedResponse, type ExperimentGroupedParams as ExperimentGroupedParams, };
-}

package/dist/_openapi_client/resources/datasets/experiments.js

@@ -1,12 +0,0 @@
-// @ts-nocheck
-// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
-import { APIResource } from '../../core/resource.js';
-import { path } from '../../internal/utils/path.js';
-export class Experiments extends APIResource {
-    /**
-     * Stream grouped and aggregated experiments.
-     */
-    grouped(datasetID, body, options) {
-        return this._client.post(path `/api/v1/datasets/${datasetID}/experiments/grouped`, { body, ...options });
-    }
-}

package/dist/_openapi_client/resources/datasets/group.cjs

@@ -1,17 +0,0 @@
-"use strict";
-// @ts-nocheck
-// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Group = void 0;
-const resource_js_1 = require("../../core/resource.cjs");
-const path_js_1 = require("../../internal/utils/path.cjs");
-class Group extends resource_js_1.APIResource {
-    /**
-     * Fetch examples for a dataset, and fetch the runs for each example if they are
-     * associated with the given session_ids.
-     */
-    runs(datasetID, body, options) {
-        return this._client.post((0, path_js_1.path) `/api/v1/datasets/${datasetID}/group/runs`, { body, ...options });
-    }
-}
-exports.Group = Group;

package/dist/_openapi_client/resources/datasets/group.d.ts

@@ -1,160 +0,0 @@
-import { APIResource } from '../../core/resource.js';
-import * as RunsAPI from './runs.js';
-import { APIPromise } from '../../core/api-promise.js';
-import { RequestOptions } from '../../internal/request-options.js';
-export declare class Group extends APIResource {
-    /**
-     * Fetch examples for a dataset, and fetch the runs for each example if they are
-     * associated with the given session_ids.
-     */
-    runs(datasetID: string, body: GroupRunsParams, options?: RequestOptions): APIPromise<GroupRunsResponse>;
-}
-/**
- * Response for grouped comparison view of dataset examples.
- *
- * Returns dataset examples grouped by a run metadata value (e.g., model='gpt-4').
- * Optional filters are applied to all runs before grouping.
- *
- * Shows:
- *
- * - Which examples were executed with each metadata value
- * - Per-session aggregate statistics for runs on those examples
- * - The actual example data with their associated runs
- *
- * Used for comparing how different sessions performed on the same set of examples.
- */
-export interface GroupRunsResponse {
-    groups: Array<GroupRunsResponse.Group>;
-}
-export declare namespace GroupRunsResponse {
-    /**
-     * Group of examples with a specific metadata value across multiple sessions.
-     *
-     * Extends RunGroupBase with:
-     *
-     * - group_key: metadata value that defines this group
-     * - sessions: per-session stats for runs matching this metadata value
-     * - examples: shared examples across all sessions (intersection logic) with flat
-     *   array of runs (each run has session_id field for frontend to determine column)
-     * - example_count: unique example count (pagination-aware, same across all
-     *   sessions due to intersection)
-     *
-     * Inherited from RunGroupBase:
-     *
-     * - filter: metadata filter for this group (e.g., "and(eq(is_root, true),
-     *   and(eq(metadata_key, 'model'), eq(metadata_value, 'gpt-4')))")
-     * - count: total run count across all sessions (includes duplicate runs)
-     * - total_tokens, total_cost: aggregate across sessions
-     * - min_start_time, max_start_time: time range across sessions
-     * - latency_p50, latency_p99: aggregate latency stats across sessions
-     * - feedback_stats: weighted average feedback across sessions
-     *
-     * Additional aggregate stats:
-     *
-     * - prompt_tokens, completion_tokens: separate token counts
-     * - prompt_cost, completion_cost: separate costs
-     * - error_rate: average error rate
-     */
-    interface Group {
-        example_count: number;
-        examples: Array<RunsAPI.ExampleWithRunsCh>;
-        filter: string;
-        group_key: string | number;
-        sessions: Array<Group.Session>;
-        completion_cost?: string | null;
-        completion_tokens?: number | null;
-        count?: number | null;
-        error_rate?: number | null;
-        feedback_stats?: {
-            [key: string]: unknown;
-        } | null;
-        latency_p50?: number | null;
-        latency_p99?: number | null;
-        max_start_time?: string | null;
-        min_start_time?: string | null;
-        prompt_cost?: string | null;
-        prompt_tokens?: number | null;
-        total_cost?: string | null;
-        total_tokens?: number | null;
-    }
-    namespace Group {
-        /**
-         * TracerSession stats filtered to runs matching a specific metadata value.
-         *
-         * Extends TracerSession with:
-         *
-         * - example_count: unique examples (vs run_count = total runs including
-         *   duplicates)
-         * - filter: ClickHouse filter for fetching runs in this session/group
-         * - min/max_start_time: time range for runs in this session/group
-         */
-        interface Session {
-            id: string;
-            filter: string;
-            tenant_id: string;
-            completion_cost?: string | null;
-            completion_tokens?: number | null;
-            default_dataset_id?: string | null;
-            description?: string | null;
-            end_time?: string | null;
-            error_rate?: number | null;
-            example_count?: number | null;
-            experiment_progress?: Session.ExperimentProgress | null;
-            extra?: {
-                [key: string]: unknown;
-            } | null;
-            feedback_stats?: {
-                [key: string]: unknown;
-            } | null;
-            first_token_p50?: number | null;
-            first_token_p99?: number | null;
-            last_run_start_time?: string | null;
-            last_run_start_time_live?: string | null;
-            latency_p50?: number | null;
-            latency_p99?: number | null;
-            max_start_time?: string | null;
-            min_start_time?: string | null;
-            name?: string;
-            prompt_cost?: string | null;
-            prompt_tokens?: number | null;
-            reference_dataset_id?: string | null;
-            run_count?: number | null;
-            run_facets?: Array<{
-                [key: string]: unknown;
-            }> | null;
-            session_feedback_stats?: {
-                [key: string]: unknown;
-            } | null;
-            start_time?: string;
-            streaming_rate?: number | null;
-            test_run_number?: number | null;
-            total_cost?: string | null;
-            total_tokens?: number | null;
-            trace_tier?: 'longlived' | 'shortlived' | null;
-        }
-        namespace Session {
-            interface ExperimentProgress {
-                evaluator_progress: {
-                    [key: string]: number;
-                };
-                expected_run_count: number;
-                run_progress: number;
-            }
-        }
-    }
-}
-export interface GroupRunsParams {
-    group_by: 'run_metadata' | 'example_metadata';
-    metadata_key: string;
-    session_ids: Array<string>;
-    filters?: {
-        [key: string]: Array<string>;
-    } | null;
-    limit?: number;
-    offset?: number;
-    per_group_limit?: number;
-    preview?: boolean;
-}
-export declare namespace Group {
-    export { type GroupRunsResponse as GroupRunsResponse, type GroupRunsParams as GroupRunsParams };
-}

package/dist/_openapi_client/resources/datasets/group.js

@@ -1,13 +0,0 @@
-// @ts-nocheck
-// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
-import { APIResource } from '../../core/resource.js';
-import { path } from '../../internal/utils/path.js';
-export class Group extends APIResource {
-    /**
-     * Fetch examples for a dataset, and fetch the runs for each example if they are
-     * associated with the given session_ids.
-     */
-    runs(datasetID, body, options) {
-        return this._client.post(path `/api/v1/datasets/${datasetID}/group/runs`, { body, ...options });
-    }
-}

package/dist/_openapi_client/resources/sessions/insights.cjs

@@ -1,54 +0,0 @@
-"use strict";
-// @ts-nocheck
-// File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Insights = void 0;
-const resource_js_1 = require("../../core/resource.cjs");
-const pagination_js_1 = require("../../core/pagination.cjs");
-const path_js_1 = require("../../internal/utils/path.cjs");
-class Insights extends resource_js_1.APIResource {
-    /**
-     * Create an insights job.
-     */
-    create(sessionID, body, options) {
-        return this._client.post((0, path_js_1.path) `/api/v1/sessions/${sessionID}/insights`, { body, ...options });
-    }
-    /**
-     * Update a session cluster job.
-     */
-    update(jobID, params, options) {
-        const { session_id, ...body } = params;
-        return this._client.patch((0, path_js_1.path) `/api/v1/sessions/${session_id}/insights/${jobID}`, { body, ...options });
-    }
-    /**
-     * Get all clusters for a session.
-     */
-    list(sessionID, query = {}, options) {
-        return this._client.getAPIList((0, path_js_1.path) `/api/v1/sessions/${sessionID}/insights`, (pagination_js_1.OffsetPaginationInsightsClusteringJobs), { query, ...options });
-    }
-    /**
-     * Delete a session cluster job.
-     */
-    delete(jobID, params, options) {
-        const { session_id } = params;
-        return this._client.delete((0, path_js_1.path) `/api/v1/sessions/${session_id}/insights/${jobID}`, options);
-    }
-    /**
-     * Get a specific cluster job for a session.
-     */
-    retrieveJob(jobID, params, options) {
-        const { session_id } = params;
-        return this._client.get((0, path_js_1.path) `/api/v1/sessions/${session_id}/insights/${jobID}`, options);
-    }
-    /**
-     * Get all runs for a cluster job, optionally filtered by cluster.
-     */
-    retrieveRuns(jobID, params, options) {
-        const { session_id, ...query } = params;
-        return this._client.get((0, path_js_1.path) `/api/v1/sessions/${session_id}/insights/${jobID}/runs`, {
-            query,
-            ...options,
-        });
-    }
-}
-exports.Insights = Insights;