langsmith 0.10.7 → 0.10.9

package/dist/_openapi_client/resources/threads.js

@@ -1,67 +1,3 @@
 // @ts-nocheck
 // File generated from our OpenAPI spec by Stainless. See CONTRIBUTING.md for details.
-import { APIResource } from '../core/resource.js';
-import { ItemsCursorGetPagination, ItemsCursorPostPagination, } from '../core/pagination.js';
-import { path } from '../internal/utils/path.js';
-export class Threads extends APIResource {
-    /**
-     * Retrieve all traces belonging to a specific thread within a project.
-     *
-     * Self-hosted deployments require LangSmith `v0.16` or later.
-     *
-     * @example
-     * ```ts
-     * // Automatically fetches more pages as needed.
-     * for await (const threadTrace of client.threads.listTraces(
-     *   'thread_id',
-     *   { project_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e' },
-     * )) {
-     *   // ...
-     * }
-     * ```
-     */
-    listTraces(threadID, query, options) {
-        return this._client.getAPIList(path `/api/v2/threads/${threadID}/traces`, (ItemsCursorGetPagination), { query, ...options });
-    }
-    /**
-     * Query threads within a project (session), with cursor-based pagination. Returns
-     * threads matching the given time range and optional filters.
-     *
-     * Self-hosted deployments require LangSmith `v0.16` or later.
-     *
-     * @example
-     * ```ts
-     * // Automatically fetches more pages as needed.
-     * for await (const thread of client.threads.query()) {
-     *   // ...
-     * }
-     * ```
-     */
-    query(body, options) {
-        return this._client.getAPIList('/api/v2/threads/query', (ItemsCursorPostPagination), {
-            body,
-            method: 'post',
-            ...options,
-        });
-    }
-    /**
-     * Compute aggregate stats for a single thread (turn count, latency percentiles,
-     * token/cost sums, and detail breakdowns) within a project.
-     *
-     * Self-hosted deployments require LangSmith `v0.16` or later.
-     *
-     * @example
-     * ```ts
-     * const threadStats = await client.threads.stats(
-     *   'thread_id',
-     *   {
-     *     selects: ['TURNS'],
-     *     session_id: '182bd5e5-6e1a-4fe4-a799-aa6d9a6ab26e',
-     *   },
-     * );
-     * ```
-     */
-    stats(threadID, query, options) {
-        return this._client.get(path `/api/v2/threads/${threadID}/stats`, { query, ...options });
-    }
-}
+export * from './threads/index.js';

package/dist/_openapi_client/resources/traces.d.ts

@@ -46,6 +46,12 @@ export declare class Traces extends APIResource {
 }
 export type TracesItemsCursorPostPagination = ItemsCursorPostPagination<Trace>;
 export interface Trace {
+    /**
+     * `query_metadata` describes why this trace matched the query, including
+     * `sem_filter_score` when a semantic filter is used. Returned automatically, or
+     * null when unavailable.
+     */
+    query_metadata?: unknown | null;
     /**
      * `root_run` is the trace's root run. Which properties are populated is controlled
      * by `selects` in the request.
@@ -111,7 +117,7 @@ export interface TraceListRunsParams {
      * (repeatable query parameter). Accepts any value of the `RunSelectField` enum. If
      * omitted, only `id` is returned.
      */
-    selects?: Array<'ID' | 'NAME' | 'RUN_TYPE' | 'STATUS' | 'START_TIME' | 'END_TIME' | 'LATENCY_SECONDS' | 'FIRST_TOKEN_TIME' | 'ERROR' | 'ERROR_PREVIEW' | 'EXTRA' | 'METADATA' | 'EVENTS' | 'INPUTS' | 'INPUTS_PREVIEW' | 'OUTPUTS' | 'OUTPUTS_PREVIEW' | 'MANIFEST' | 'PARENT_RUN_IDS' | 'PROJECT_ID' | 'TRACE_ID' | 'THREAD_ID' | 'DOTTED_ORDER' | 'IS_ROOT' | 'REFERENCE_EXAMPLE_ID' | 'REFERENCE_DATASET_ID' | 'TOTAL_TOKENS' | 'PROMPT_TOKENS' | 'COMPLETION_TOKENS' | 'TOTAL_COST' | 'PROMPT_COST' | 'COMPLETION_COST' | 'PROMPT_TOKEN_DETAILS' | 'COMPLETION_TOKEN_DETAILS' | 'PROMPT_COST_DETAILS' | 'COMPLETION_COST_DETAILS' | 'PRICE_MODEL_ID' | 'TAGS' | 'APP_PATH' | 'ATTACHMENTS' | 'THREAD_EVALUATION_TIME' | 'IS_IN_DATASET' | 'LAST_QUEUED_AT' | 'SHARE_URL' | 'FEEDBACK_STATS'>;
+    selects?: Array<'ID' | 'NAME' | 'RUN_TYPE' | 'STATUS' | 'START_TIME' | 'END_TIME' | 'LATENCY_SECONDS' | 'FIRST_TOKEN_TIME' | 'ERROR' | 'ERROR_PREVIEW' | 'EXTRA' | 'METADATA' | 'EVENTS' | 'INPUTS' | 'INPUTS_PREVIEW' | 'OUTPUTS' | 'OUTPUTS_PREVIEW' | 'MANIFEST' | 'PARENT_RUN_IDS' | 'PROJECT_ID' | 'TRACE_ID' | 'THREAD_ID' | 'DOTTED_ORDER' | 'IS_ROOT' | 'REFERENCE_EXAMPLE_ID' | 'REFERENCE_DATASET_ID' | 'TOTAL_TOKENS' | 'PROMPT_TOKENS' | 'COMPLETION_TOKENS' | 'TOTAL_COST' | 'PROMPT_COST' | 'COMPLETION_COST' | 'PROMPT_TOKEN_DETAILS' | 'COMPLETION_TOKEN_DETAILS' | 'PROMPT_COST_DETAILS' | 'COMPLETION_COST_DETAILS' | 'PRICE_MODEL_ID' | 'TAGS' | 'APP_PATH' | 'ATTACHMENTS' | 'THREAD_EVALUATION_TIME' | 'IS_IN_DATASET' | 'LAST_QUEUED_AT' | 'SHARE_URL' | 'FEEDBACK_STATS' | 'LS_USER_ID'>;
     /**
      * Header param: application/json
      */

package/dist/_openapi_client/version.cjs

@@ -2,4 +2,4 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.VERSION = void 0;
 // @ts-nocheck
-exports.VERSION = '0.0.1';
+exports.VERSION = '0.0.1'; // x-release-please-version

package/dist/_openapi_client/version.js

@@ -1,2 +1,2 @@
 // @ts-nocheck
-export const VERSION = '0.0.1';
+export const VERSION = '0.0.1'; // x-release-please-version

package/dist/address.cjs

@@ -1,33 +1,40 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.EnvAddressError = void 0;
-exports.normalizeAddress = normalizeAddress;
-exports.wireKeys = wireKeys;
+exports.EvaluatorAddress = exports.ExperimentAddress = exports.AgentAddress = exports.EnvAddressError = void 0;
+exports.ensureAgent = ensureAgent;
+exports.ensureAddress = ensureAddress;
 exports.envNames = envNames;
-exports.toPayload = toPayload;
-exports.toWire = toWire;
-exports.fromWire = fromWire;
-exports.addressFromEnv = addressFromEnv;
-exports.seed = seed;
-exports.sameAddress = sameAddress;
-// Wire key per field; env var is `LANGSMITH_<WIRE KEY>`.
-const FIELDS = {
-    agentId: "agent_id",
-    agentEnvironment: "agent_environment",
-};
+/**
+ * (beta) Addresses that name where runs are sent instead of a project.
+ * Enabled per workspace; a workspace without it rejects the runs.
+ *
+ * An `Address` names a tracing project held by a feature: an `AgentAddress`, an
+ * `ExperimentAddress` or the workspace's `EvaluatorAddress`. Any of them can be resolved to
+ * its project. Only an `AgentAddress` can receive traces, and ingestion rejects the
+ * others at its entry points.
+ *
+ * @example
+ * ```ts
+ * import { AgentAddress, traceable } from "langsmith";
+ *
+ * const support = new AgentAddress("customer-support", "production");
+ * const handle = traceable(fn, { address: support });
+ * ```
+ */
+const env_js_1 = require("./utils/env.cjs");
+const UUID_PATTERN = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 // The server's agent id rule: a DNS label, so a hostname can carry the id.
 const AGENT_ID_PATTERN = /^[a-z]([a-z0-9-]{0,61}[a-z0-9])?$/;
-// Not `utils/env`: it imports the package index, which imports this module.
-function getEnv(name) {
-    try {
-        // eslint-disable-next-line no-process-env
-        return typeof process !== "undefined" ? process.env?.[name] : undefined;
-    }
-    catch {
-        return undefined;
-    }
-}
-/** The `LANGSMITH_AGENT_*` / project env vars name half an address, or both. */
+const ENVIRONMENTS = [
+    "local",
+    "development",
+    "staging",
+    "production",
+];
+// The wire form of an agent address. The parts are validated by `AgentAddress`.
+const LRN_PATTERN = /^lrn:agents\/([^/]+)\/environments\/([^/]+)$/;
+const ENV_NAMES = ["LANGSMITH_AGENT_ID", "LANGSMITH_AGENT_ENVIRONMENT"];
+/** (beta) The `LANGSMITH_AGENT_*` / project env vars name half an address, or both. */
 class EnvAddressError extends Error {
     constructor(message) {
         super(message);
@@ -36,98 +43,168 @@ class EnvAddressError extends Error {
 }
 exports.EnvAddressError = EnvAddressError;
 /**
- * @internal Validate `value` and return a frozen copy of its fields.
- * @throws If it isn't an object with exactly the address fields, or a value is invalid.
+ * (beta) The address of an agent's environment.
+ *
+ * @example
+ * ```ts
+ * new AgentAddress("customer-support", "production");
+ * ```
  */
-function normalizeAddress(value) {
-    if (value == null || typeof value !== "object" || Array.isArray(value)) {
-        throw new Error("`address` must be an object: { agentId, agentEnvironment }.");
+class AgentAddress {
+    /**
+     * @param id 1 to 63 lowercase ASCII letters, digits or hyphens, starting
+     *   with a letter and ending with a letter or digit. The server creates the
+     *   agent on first use.
+     * @param environment One of `local`, `development`, `staging` or `production`, in
+     *   any case.
+     * @throws If a value is invalid.
+     */
+    constructor(id, environment) {
+        Object.defineProperty(this, "id", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        /** Always lowercase. */
+        Object.defineProperty(this, "environment", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        if (typeof id !== "string" || !AGENT_ID_PATTERN.test(id)) {
+            throw new Error("Address agent id must be 1 to 63 lowercase ASCII letters, digits, or " +
+                "hyphens, start with a letter, and end with a letter or digit, got " +
+                `${JSON.stringify(id)}. Use an id such as "support-agent".`);
+        }
+        const normalized = typeof environment === "string" ? environment.toLowerCase() : undefined;
+        if (normalized === undefined || !ENVIRONMENTS.includes(normalized)) {
+            throw new Error(`Address environment must be one of ${ENVIRONMENTS.join(", ")}, got ` +
+                `${JSON.stringify(environment)}.`);
+        }
+        this.id = id;
+        this.environment = normalized;
+        Object.freeze(this);
+    }
+    toApiAddress() {
+        return {
+            kind: "AGENT",
+            id: this.id,
+            environment: this.environment.toUpperCase(),
+        };
     }
-    const fields = value;
-    const unknown = Object.keys(fields).filter((key) => !(key in FIELDS));
-    if (unknown.length > 0) {
-        throw new Error(`Unknown address fields: ${unknown.join(", ")}.`);
+    /** @internal */
+    _toLrn() {
+        return `lrn:agents/${this.id}/environments/${this.environment}`;
     }
-    for (const name of Object.keys(FIELDS)) {
-        const field = fields[name];
-        if (typeof field !== "string" || field === "") {
-            throw new Error(`Address ${name} must be a non-empty string.`);
+    /**
+     * @internal Parse an LRN read from the wire, such as a `baggage` header. The
+     * value is untrusted, so it is not echoed in the error.
+     * @throws If `value` is not an agent LRN, or names an invalid id or environment.
+     */
+    static _fromLrn(value) {
+        const match = typeof value === "string" ? LRN_PATTERN.exec(value) : null;
+        if (match === null) {
+            throw new Error("Not an agent address.");
         }
+        return new AgentAddress(match[1], match[2]);
     }
-    const { agentId, agentEnvironment } = fields;
-    if (!AGENT_ID_PATTERN.test(agentId)) {
-        throw new Error("Address agentId must be 1 to 63 lowercase ASCII letters, digits, or " +
-            "hyphens, start with a letter, and end with a letter or digit, got " +
-            `${JSON.stringify(agentId)}. Use an id such as "support-agent".`);
+    /**
+     * Read the agent named by `LANGSMITH_AGENT_ID` and
+     * `LANGSMITH_AGENT_ENVIRONMENT`; `undefined` if neither is set.
+     * @throws {EnvAddressError} If only one is set, or a value is invalid.
+     */
+    static fromEnv() {
+        const values = ENV_NAMES.map((name) => (0, env_js_1.getEnvironmentVariable)(name));
+        if (!values.some(Boolean)) {
+            return undefined;
+        }
+        try {
+            const missing = ENV_NAMES.filter((_, i) => !values[i]);
+            if (missing.length > 0) {
+                throw new Error(`An address needs ${missing.join(" and ")} as well.`);
+            }
+            return new AgentAddress(values[0], values[1]);
+        }
+        catch (e) {
+            const present = ENV_NAMES.flatMap((name, i) => values[i] ? [`${name}=${JSON.stringify(values[i])}`] : []).join(", ");
+            throw new EnvAddressError(`The LANGSMITH_AGENT_* env vars can't address a run (${present}): ${e.message}`);
+        }
     }
-    return Object.freeze({ agentId, agentEnvironment });
 }
-/** @internal */
-function wireKeys() {
-    return Object.values(FIELDS);
+exports.AgentAddress = AgentAddress;
+/** (beta) The address of an experiment's tracing project. */
+class ExperimentAddress {
+    /**
+     * @param id The experiment's UUID.
+     * @throws If `id` is not a UUID.
+     */
+    constructor(id) {
+        /** Always lowercase. */
+        Object.defineProperty(this, "id", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        if (typeof id !== "string" || !UUID_PATTERN.test(id)) {
+            throw new Error(`Experiment id must be a UUID, got ${JSON.stringify(id)}.`);
+        }
+        this.id = id.toLowerCase();
+        Object.freeze(this);
+    }
+    toApiAddress() {
+        return { kind: "EXPERIMENT", id: this.id };
+    }
 }
-/** @internal */
-function envNames() {
-    return wireKeys().map((key) => `LANGSMITH_${key.toUpperCase()}`);
+exports.ExperimentAddress = ExperimentAddress;
+/** (beta) The address of the workspace's shared evaluators project. */
+class EvaluatorAddress {
+    constructor() {
+        Object.freeze(this);
+    }
+    toApiAddress() {
+        return { kind: "EVALUATOR" };
+    }
 }
+exports.EvaluatorAddress = EvaluatorAddress;
 /**
- * @internal The `address` object of a run / feedback payload. `kind` and
- * `environment` are uppercase and case-sensitive on the wire.
+ * @internal The ingestion entry-point guard: `value` must be an `AgentAddress` (or
+ * absent), and is returned as is. Other addresses and strings are rejected.
+ * @throws If `value` is not an `AgentAddress`.
  */
-function toPayload(address) {
-    return {
-        address: {
-            kind: "AGENT",
-            id: address.agentId,
-            environment: address.agentEnvironment.toUpperCase(),
-        },
-    };
-}
-/** @internal Header / replica fields. */
-function toWire(address) {
-    return {
-        [FIELDS.agentId]: address.agentId,
-        [FIELDS.agentEnvironment]: address.agentEnvironment,
-    };
-}
-/** @internal `undefined` if no field is set; throws if only some are. */
-function fromWire(values) {
-    const fields = Object.fromEntries(Object.entries(FIELDS).map(([name, key]) => [
-        name,
-        values[key] ?? undefined,
-    ]));
-    const missing = Object.entries(FIELDS)
-        .filter(([name]) => fields[name] === undefined)
-        .map(([, key]) => key);
-    if (missing.length === Object.keys(FIELDS).length) {
+function ensureAgent(value) {
+    if (value == null) {
         return undefined;
     }
-    if (missing.length > 0) {
-        throw new Error(`An address needs ${missing.join(" and ")} as well.`);
+    if (value instanceof AgentAddress) {
+        return value;
+    }
+    if (typeof value === "object" &&
+        typeof value.toApiAddress === "function") {
+        throw new Error(`Only an AgentAddress can receive traces, got ${value.constructor?.name ?? "an unknown address"}.`);
     }
-    return normalizeAddress(fields);
+    throw new Error("address must be an AgentAddress such as `new AgentAddress(id, environment)`, got " +
+        `${typeof value === "string" ? JSON.stringify(value) : typeof value}.`);
 }
 /**
- * @internal
- * @throws {EnvAddressError} If only some `LANGSMITH_AGENT_*` vars are set, or one is invalid.
+ * Return `value` if it is an `Address` of any kind, as a lookup takes it.
+ * For the calls that only resolve an address to its project, such as
+ * `getRunUrl`. Whatever receives traces takes `ensureAgent`.
  */
-function addressFromEnv() {
-    const values = Object.fromEntries(wireKeys().map((key, i) => [key, getEnv(envNames()[i]) || undefined]));
-    try {
-        return fromWire(values);
+function ensureAddress(value) {
+    if (value == null) {
+        return undefined;
     }
-    catch (e) {
-        throw new EnvAddressError(`The LANGSMITH_AGENT_* env vars can't address a run: ${e.message}`);
+    if (typeof value === "object" &&
+        typeof value.toApiAddress === "function") {
+        return value;
     }
+    throw new Error("address must be an AgentAddress, ExperimentAddress or EvaluatorAddress, got " +
+        `${typeof value === "string" ? JSON.stringify(value) : typeof value}.`);
 }
-/** @internal Replica id derivation seed. */
-function seed(address) {
-    return ["agent", ...Object.values(toWire(address))].join("/");
-}
-/** @internal */
-function sameAddress(a, b) {
-    if (!a || !b) {
-        return a === b;
-    }
-    return a.agentId === b.agentId && a.agentEnvironment === b.agentEnvironment;
+/** @internal The `LANGSMITH_AGENT_*` env var names an address reads. */
+function envNames() {
+    return ENV_NAMES;
 }

package/dist/address.d.ts

@@ -1,13 +1,68 @@
-/**
- * (beta) An address that runs are sent to instead of a project.
- * Enabled per workspace; a workspace without it rejects the runs.
- */
+/** (beta) An agent environment. */
+export type Environment = "local" | "development" | "staging" | "production";
+/** (beta) The backend's form of an address, as the resolve endpoint takes it. */
+export type ApiAddress = {
+    kind: "AGENT" | "EXPERIMENT" | "EVALUATOR";
+    id?: string;
+    environment?: Uppercase<Environment>;
+};
+/** (beta) A feature that holds traces in a tracing project. */
 export interface Address {
-    /** 1 to 63 lowercase ASCII letters, digits or hyphens; starts with a letter. */
-    agentId: string;
-    agentEnvironment: string;
+    /** The address in the backend's form. */
+    toApiAddress(): ApiAddress;
 }
-/** The `LANGSMITH_AGENT_*` / project env vars name half an address, or both. */
+/** (beta) The `LANGSMITH_AGENT_*` / project env vars name half an address, or both. */
 export declare class EnvAddressError extends Error {
     constructor(message: string);
 }
+/**
+ * (beta) The address of an agent's environment.
+ *
+ * @example
+ * ```ts
+ * new AgentAddress("customer-support", "production");
+ * ```
+ */
+export declare class AgentAddress implements Address {
+    readonly id: string;
+    /** Always lowercase. */
+    readonly environment: Environment;
+    /**
+     * @param id 1 to 63 lowercase ASCII letters, digits or hyphens, starting
+     *   with a letter and ending with a letter or digit. The server creates the
+     *   agent on first use.
+     * @param environment One of `local`, `development`, `staging` or `production`, in
+     *   any case.
+     * @throws If a value is invalid.
+     */
+    constructor(id: string, environment: Environment | (string & {}));
+    toApiAddress(): ApiAddress;
+    /**
+     * Read the agent named by `LANGSMITH_AGENT_ID` and
+     * `LANGSMITH_AGENT_ENVIRONMENT`; `undefined` if neither is set.
+     * @throws {EnvAddressError} If only one is set, or a value is invalid.
+     */
+    static fromEnv(): AgentAddress | undefined;
+}
+/** (beta) The address of an experiment's tracing project. */
+export declare class ExperimentAddress implements Address {
+    /** Always lowercase. */
+    readonly id: string;
+    /**
+     * @param id The experiment's UUID.
+     * @throws If `id` is not a UUID.
+     */
+    constructor(id: string);
+    toApiAddress(): ApiAddress;
+}
+/** (beta) The address of the workspace's shared evaluators project. */
+export declare class EvaluatorAddress implements Address {
+    constructor();
+    toApiAddress(): ApiAddress;
+}
+/**
+ * Return `value` if it is an `Address` of any kind, as a lookup takes it.
+ * For the calls that only resolve an address to its project, such as
+ * `getRunUrl`. Whatever receives traces takes `ensureAgent`.
+ */
+export declare function ensureAddress(value: unknown): Address | undefined;