@langchain/langgraph-sdk 0.0.1-rc.1 → 0.0.1-rc.10

package/dist/client.d.mts

@@ -1,15 +1,17 @@
-import { Assistant, AssistantGraph, Config, GraphSchema, Metadata, Run, RunEvent, Thread, ThreadState } from "./schema.js";
+import { Assistant, AssistantGraph, Config, DefaultValues, GraphSchema, Metadata, Run, RunEvent, Thread, ThreadState } from "./schema.js";
 import { AsyncCaller, AsyncCallerParams } from "./utils/async_caller.mjs";
 import { RunsCreatePayload, RunsStreamPayload, RunsWaitPayload } from "./types.mjs";
 interface ClientConfig {
     apiUrl?: string;
     callerOptions?: AsyncCallerParams;
     timeoutMs?: number;
+    defaultHeaders?: Record<string, string | null | undefined>;
 }
 declare class BaseClient {
     protected asyncCaller: AsyncCaller;
     protected timeoutMs: number;
     protected apiUrl: string;
+    protected defaultHeaders: Record<string, string | null | undefined>;
     constructor(config?: ClientConfig);
     protected prepareFetchOptions(path: string, options?: RequestInit & {
         json?: unknown;
@@ -21,19 +23,51 @@ declare class BaseClient {
     }): Promise<T>;
 }
 declare class AssistantsClient extends BaseClient {
+    /**
+     * Get an assistant by ID.
+     *
+     * @param assistantId The ID of the assistant.
+     * @returns Assistant
+     */
     get(assistantId: string): Promise<Assistant>;
+    /**
+     * Get the JSON representation of the graph assigned to a runnable
+     * @param assistantId The ID of the assistant.
+     * @returns Serialized graph
+     */
     getGraph(assistantId: string): Promise<AssistantGraph>;
+    /**
+     * Get the state and config schema of the graph assigned to a runnable
+     * @param assistantId The ID of the assistant.
+     * @returns Graph schema
+     */
     getSchemas(assistantId: string): Promise<GraphSchema>;
+    /**
+     * Create a new assistant.
+     * @param payload Payload for creating an assistant.
+     * @returns The created assistant.
+     */
     create(payload: {
         graphId: string;
         config?: Config;
         metadata?: Metadata;
     }): Promise<Assistant>;
-    upsert(assistantId: string, payload: {
+    /**
+     * Update an assistant.
+     * @param assistantId ID of the assistant.
+     * @param payload Payload for updating the assistant.
+     * @returns The updated assistant.
+     */
+    update(assistantId: string, payload: {
         graphId: string;
         config?: Config;
         metadata?: Metadata;
     }): Promise<Assistant>;
+    /**
+     * List assistants.
+     * @param query Query options.
+     * @returns List of assistants.
+     */
     search(query?: {
         metadata?: Metadata;
         limit?: number;
@@ -54,7 +88,7 @@ declare class ThreadsClient extends BaseClient {
      * @param payload Payload for creating a thread.
      * @returns The created thread.
      */
-    create(payload: {
+    create(payload?: {
         /**
          * Metadata for the thread.
          */
@@ -67,7 +101,7 @@ declare class ThreadsClient extends BaseClient {
      * @param payload Payload for updating the thread.
      * @returns The updated thread.
      */
-    upsert(threadId: string, payload?: {
+    update(threadId: string, payload?: {
         /**
          * Metadata for the thread.
          */
@@ -106,20 +140,20 @@ declare class ThreadsClient extends BaseClient {
      * @param threadId ID of the thread.
      * @returns Thread state.
      */
-    getState(threadId: string): Promise<ThreadState>;
+    getState<ValuesType = DefaultValues>(threadId: string, checkpointId?: string): Promise<ThreadState<ValuesType>>;
     /**
      * Add state to a thread.
      *
-     * @param threadIdOrConfig Thread ID or config that identifies the state to start from.
-     * @param values The state update
-     * @param options Additional options.
+     * @param threadId The ID of the thread.
      * @returns
      */
-    updateState(threadIdOrConfig: string | Config, values: Record<string, unknown>, options?: {
+    updateState<ValuesType = DefaultValues>(threadId: string, options: {
+        values: ValuesType;
+        checkpointId?: string;
         asNode?: string;
     }): Promise<void>;
     /**
-     * Patch the state of a thread.
+     * Patch the metadata of a thread.
      *
      * @param threadIdOrConfig Thread ID or config to patch the state of.
      * @param metadata Metadata to patch the state with.
@@ -132,10 +166,11 @@ declare class ThreadsClient extends BaseClient {
      * @param options Additional options.
      * @returns List of thread states.
      */
-    getHistory(threadId: string, options?: {
+    getHistory<ValuesType = DefaultValues>(threadId: string, options?: {
         limit?: number;
         before?: Config;
-    }): Promise<ThreadState[]>;
+        metadata?: Metadata;
+    }): Promise<ThreadState<ValuesType>[]>;
 }
 declare class RunsClient extends BaseClient {
     /**
@@ -146,8 +181,8 @@ declare class RunsClient extends BaseClient {
      * @param payload Payload for creating a run.
      */
     stream(threadId: string, assistantId: string, payload?: RunsStreamPayload): AsyncGenerator<{
-        event: string;
-        data: unknown;
+        event: "events" | "metadata" | "debug" | "updates" | "values" | "messages/partial" | "messages/metadata" | "messages/complete" | (string & {});
+        data: any;
     }>;
     /**
      * Create a run.
@@ -216,8 +251,17 @@ declare class RunsClient extends BaseClient {
     }): Promise<RunEvent[]>;
 }
 export declare class Client {
+    /**
+     * The client for interacting with assistants.
+     */
     assistants: AssistantsClient;
+    /**
+     * The client for interacting with threads.
+     */
     threads: ThreadsClient;
+    /**
+     * The client for interacting with runs.
+     */
     runs: RunsClient;
     constructor(config?: ClientConfig);
 }

package/dist/client.mjs

@@ -21,16 +21,26 @@ class BaseClient {
             writable: true,
             value: void 0
         });
+        Object.defineProperty(this, "defaultHeaders", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
         this.asyncCaller = new AsyncCaller({
-            maxRetries: 5,
-            maxConcurrency: 5,
+            maxRetries: 4,
+            maxConcurrency: 4,
             ...config?.callerOptions,
         });
         this.timeoutMs = config?.timeoutMs || 12_000;
         this.apiUrl = config?.apiUrl || "http://localhost:8123";
+        this.defaultHeaders = config?.defaultHeaders || {};
     }
     prepareFetchOptions(path, options) {
-        const mutatedOptions = { ...options };
+        const mutatedOptions = {
+            ...options,
+            headers: { ...this.defaultHeaders, ...options?.headers },
+        };
         if (mutatedOptions.json) {
             mutatedOptions.body = JSON.stringify(mutatedOptions.json);
             mutatedOptions.headers = {
@@ -59,15 +69,36 @@ class BaseClient {
     }
 }
 class AssistantsClient extends BaseClient {
+    /**
+     * Get an assistant by ID.
+     *
+     * @param assistantId The ID of the assistant.
+     * @returns Assistant
+     */
     async get(assistantId) {
         return this.fetch(`/assistants/${assistantId}`);
     }
+    /**
+     * Get the JSON representation of the graph assigned to a runnable
+     * @param assistantId The ID of the assistant.
+     * @returns Serialized graph
+     */
     async getGraph(assistantId) {
         return this.fetch(`/assistants/${assistantId}/graph`);
     }
+    /**
+     * Get the state and config schema of the graph assigned to a runnable
+     * @param assistantId The ID of the assistant.
+     * @returns Graph schema
+     */
     async getSchemas(assistantId) {
         return this.fetch(`/assistants/${assistantId}/schemas`);
     }
+    /**
+     * Create a new assistant.
+     * @param payload Payload for creating an assistant.
+     * @returns The created assistant.
+     */
     async create(payload) {
         return this.fetch("/assistants", {
             method: "POST",
@@ -78,9 +109,15 @@ class AssistantsClient extends BaseClient {
             },
         });
     }
-    async upsert(assistantId, payload) {
+    /**
+     * Update an assistant.
+     * @param assistantId ID of the assistant.
+     * @param payload Payload for updating the assistant.
+     * @returns The updated assistant.
+     */
+    async update(assistantId, payload) {
         return this.fetch(`/assistants/${assistantId}`, {
-            method: "PUT",
+            method: "PATCH",
             json: {
                 graph_id: payload.graphId,
                 config: payload.config,
@@ -88,6 +125,11 @@ class AssistantsClient extends BaseClient {
             },
         });
     }
+    /**
+     * List assistants.
+     * @param query Query options.
+     * @returns List of assistants.
+     */
     async search(query) {
         return this.fetch("/assistants/search", {
             method: "POST",
@@ -118,7 +160,7 @@ class ThreadsClient extends BaseClient {
     async create(payload) {
         return this.fetch(`/threads`, {
             method: "POST",
-            json: { metadata: payload },
+            json: { metadata: payload?.metadata },
         });
     }
     /**
@@ -128,10 +170,10 @@ class ThreadsClient extends BaseClient {
      * @param payload Payload for updating the thread.
      * @returns The updated thread.
      */
-    async upsert(threadId, payload) {
+    async update(threadId, payload) {
         return this.fetch(`/threads/${threadId}`, {
-            method: "PUT",
-            json: { metadata: payload },
+            method: "PATCH",
+            json: { metadata: payload?.metadata },
         });
     }
     /**
@@ -166,38 +208,29 @@ class ThreadsClient extends BaseClient {
      * @param threadId ID of the thread.
      * @returns Thread state.
      */
-    async getState(threadId) {
-        return this.fetch(`/threads/${threadId}/state`);
+    async getState(threadId, checkpointId) {
+        return this.fetch(checkpointId != null
+            ? `/threads/${threadId}/state/${checkpointId}`
+            : `/threads/${threadId}/state`);
     }
     /**
      * Add state to a thread.
      *
-     * @param threadIdOrConfig Thread ID or config that identifies the state to start from.
-     * @param values The state update
-     * @param options Additional options.
+     * @param threadId The ID of the thread.
      * @returns
      */
-    async updateState(threadIdOrConfig, values, options) {
-        let config = undefined;
-        let threadId;
-        if (typeof threadIdOrConfig !== "string") {
-            config = threadIdOrConfig;
-            if (typeof config.configurable?.thread_id !== "string") {
-                throw new Error("Thread ID is required when updating state with a config.");
-            }
-            threadId = config.configurable.thread_id;
-        }
-        else {
-            config = undefined;
-            threadId = threadIdOrConfig;
-        }
+    async updateState(threadId, options) {
         return this.fetch(`/threads/${threadId}/state`, {
             method: "POST",
-            json: { values, config, as_node: options?.asNode },
+            json: {
+                values: options.values,
+                checkpoint_id: options.checkpointId,
+                as_node: options?.asNode,
+            },
         });
     }
     /**
-     * Patch the state of a thread.
+     * Patch the metadata of a thread.
      *
      * @param threadIdOrConfig Thread ID or config to patch the state of.
      * @param metadata Metadata to patch the state with.
@@ -227,9 +260,11 @@ class ThreadsClient extends BaseClient {
      */
     async getHistory(threadId, options) {
         return this.fetch(`/threads/${threadId}/history`, {
-            params: {
+            method: "POST",
+            json: {
                 limit: options?.limit ?? 10,
                 before: options?.before,
+                metadata: options?.metadata,
             },
         });
     }
@@ -250,17 +285,20 @@ class RunsClient extends BaseClient {
                 config: payload?.config,
                 metadata: payload?.metadata,
                 stream_mode: payload?.streamMode,
+                feedback_keys: payload?.feedbackKeys,
                 assistant_id: assistantId,
                 interrupt_before: payload?.interruptBefore,
                 interrupt_after: payload?.interruptAfter,
             },
+            signal: payload?.signal,
         }));
         let parser;
         const textDecoder = new TextDecoder();
         const stream = (response.body || new ReadableStream({ start: (ctrl) => ctrl.close() })).pipeThrough(new TransformStream({
             async start(ctrl) {
                 parser = createParser((event) => {
-                    if (event.type === "event" && event.data === "[DONE]") {
+                    if ((payload?.signal && payload.signal.aborted) ||
+                        (event.type === "event" && event.data === "[DONE]")) {
                         ctrl.terminate();
                         return;
                     }
@@ -298,6 +336,7 @@ class RunsClient extends BaseClient {
                 interrupt_after: payload?.interruptAfter,
                 webhook: payload?.webhook,
             },
+            signal: payload?.signal,
         });
     }
     /**
@@ -319,6 +358,7 @@ class RunsClient extends BaseClient {
                 interrupt_before: payload?.interruptBefore,
                 interrupt_after: payload?.interruptAfter,
             },
+            signal: payload?.signal,
         });
     }
     /**
@@ -365,18 +405,27 @@ class RunsClient extends BaseClient {
 }
 export class Client {
     constructor(config) {
+        /**
+         * The client for interacting with assistants.
+         */
         Object.defineProperty(this, "assistants", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /**
+         * The client for interacting with threads.
+         */
         Object.defineProperty(this, "threads", {
             enumerable: true,
             configurable: true,
             writable: true,
             value: void 0
         });
+        /**
+         * The client for interacting with runs.
+         */
         Object.defineProperty(this, "runs", {
             enumerable: true,
             configurable: true,

package/dist/index.d.mts

@@ -1 +1,2 @@
 export { Client } from "./client.mjs";
+export type { Assistant, AssistantGraph, Config, DefaultValues, GraphSchema, Metadata, Run, RunEvent, Thread, ThreadState, } from "./schema.js";

package/dist/schema.d.ts

@@ -1,3 +1,4 @@
+import type { JSONSchema7 } from "json-schema";
 type Optional<T> = T | null | undefined;
 export interface Config {
     /**
@@ -14,14 +15,30 @@ export interface Config {
      * Runtime values for attributes previously made configurable on this Runnable.
      */
     configurable: {
+        /**
+         * ID of the thread
+         */
         thread_id?: string;
+        /**
+         * Timestamp of the state checkpoint
+         */
+        thread_ts?: string;
         [key: string]: unknown;
     };
 }
 export interface GraphSchema {
+    /**
+     * The ID of the graph.
+     */
     graph_id: string;
-    state_schema: Record<string, unknown>;
-    config_schema: Record<string, unknown>;
+    /**
+     * The schema for the graph state
+     */
+    state_schema: JSONSchema7;
+    /**
+     * The schema for the graph config
+     */
+    config_schema: JSONSchema7;
 }
 export type Metadata = Optional<Record<string, unknown>>;
 export interface Assistant {
@@ -39,13 +56,14 @@ export interface Thread {
     updated_at: string;
     metadata: Metadata;
 }
-export interface ThreadState {
-    values: Record<string, unknown>[] | Record<string, unknown>;
+export type DefaultValues = Record<string, unknown>[] | Record<string, unknown>;
+export interface ThreadState<ValuesType = DefaultValues> {
+    values: ValuesType;
     next: string[];
-    config: Config;
+    checkpoint_id: string;
     metadata: Metadata;
     created_at: Optional<string>;
-    parent_config: Optional<Config>;
+    parent_checkpoint_id: Optional<string>;
 }
 export interface Run {
     run_id: string;

package/dist/types.d.mts

@@ -21,6 +21,10 @@ interface RunsInvokePayload {
      * Interrupt execution after leaving these nodes.
      */
     interruptAfter?: string[];
+    /**
+     * Abort controller signal to cancel the run.
+     */
+    signal?: AbortController["signal"];
 }
 export interface RunsStreamPayload extends RunsInvokePayload {
     /**
@@ -33,6 +37,11 @@ export interface RunsStreamPayload extends RunsInvokePayload {
      *               afterwards using the `client.runs.listEvents()` method.
      */
     streamMode?: StreamMode | Array<StreamMode>;
+    /**
+     * Pass one or more feedbackKeys if you want to request short-lived signed URLs
+     * for submitting feedback to LangSmith with this key for this run.
+     */
+    feedbackKeys?: string[];
 }
 export interface RunsCreatePayload extends RunsInvokePayload {
     /**

package/dist/utils/async_caller.d.mts

@@ -24,8 +24,8 @@ export interface AsyncCallerCallOptions {
  * Concurrent calls are limited by the `maxConcurrency` parameter, which defaults
  * to `Infinity`. This means that by default, all calls will be made in parallel.
  *
- * Retries are limited by the `maxRetries` parameter, which defaults to 6. This
- * means that by default, each call will be retried up to 6 times, with an
+ * Retries are limited by the `maxRetries` parameter, which defaults to 5. This
+ * means that by default, each call will be retried up to 5 times, with an
  * exponential backoff between each attempt.
  */
 export declare class AsyncCaller {

package/dist/utils/async_caller.mjs

@@ -9,10 +9,57 @@ const STATUS_NO_RETRY = [
     406, // Not Acceptable
     407, // Proxy Authentication Required
     408, // Request Timeout
+    422, // Unprocessable Entity
 ];
 const STATUS_IGNORE = [
     409, // Conflict
 ];
+/**
+ * Do not rely on globalThis.Response, rather just
+ * do duck typing
+ */
+function isResponse(x) {
+    if (x == null || typeof x !== "object")
+        return false;
+    return "status" in x && "statusText" in x && "text" in x;
+}
+/**
+ * Utility error to properly handle failed requests
+ */
+class HTTPError extends Error {
+    constructor(status, message, response) {
+        super(`HTTP ${status}: ${message}`);
+        Object.defineProperty(this, "status", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "text", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        Object.defineProperty(this, "response", {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: void 0
+        });
+        this.status = status;
+        this.text = message;
+        this.response = response;
+    }
+    static async fromResponse(response, options) {
+        try {
+            return new HTTPError(response.status, await response.text(), options?.includeResponse ? response : undefined);
+        }
+        catch {
+            return new HTTPError(response.status, response.statusText, options?.includeResponse ? response : undefined);
+        }
+    }
+}
 /**
  * A class that can be used to make async calls with concurrency and retry logic.
  *
@@ -22,8 +69,8 @@ const STATUS_IGNORE = [
  * Concurrent calls are limited by the `maxConcurrency` parameter, which defaults
  * to `Infinity`. This means that by default, all calls will be made in parallel.
  *
- * Retries are limited by the `maxRetries` parameter, which defaults to 6. This
- * means that by default, each call will be retried up to 6 times, with an
+ * Retries are limited by the `maxRetries` parameter, which defaults to 5. This
+ * means that by default, each call will be retried up to 5 times, with an
  * exponential backoff between each attempt.
  */
 export class AsyncCaller {
@@ -53,7 +100,7 @@ export class AsyncCaller {
             value: void 0
         });
         this.maxConcurrency = params.maxConcurrency ?? Infinity;
-        this.maxRetries = params.maxRetries ?? 6;
+        this.maxRetries = params.maxRetries ?? 4;
         if ("default" in PQueueMod) {
             // eslint-disable-next-line @typescript-eslint/no-explicit-any
             this.queue = new PQueueMod.default({
@@ -69,15 +116,15 @@ export class AsyncCaller {
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     call(callable, ...args) {
         const onFailedResponseHook = this.onFailedResponseHook;
-        return this.queue.add(() => pRetry(() => callable(...args).catch((error) => {
+        return this.queue.add(() => pRetry(() => callable(...args).catch(async (error) => {
             // eslint-disable-next-line no-instanceof/no-instanceof
-            console.error;
             if (error instanceof Error) {
                 throw error;
             }
-            else if (error instanceof Response) {
-                // TODO: try to parse the response body and throw a more informative error
-                throw new Error(`HTTP ${error.status}: ${error.statusText}`);
+            else if (isResponse(error)) {
+                throw await HTTPError.fromResponse(error, {
+                    includeResponse: !!onFailedResponseHook,
+                });
             }
             else {
                 throw new Error(error);
@@ -93,18 +140,15 @@ export class AsyncCaller {
                 if (error?.code === "ECONNABORTED") {
                     throw error;
                 }
-                // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                const response = error?.response;
-                const status = response?.status;
-                if (status) {
-                    if (STATUS_NO_RETRY.includes(+status)) {
+                if (error instanceof HTTPError) {
+                    if (STATUS_NO_RETRY.includes(error.status)) {
                         throw error;
                     }
-                    else if (STATUS_IGNORE.includes(+status)) {
+                    else if (STATUS_IGNORE.includes(error.status)) {
                         return;
                     }
-                    if (onFailedResponseHook) {
-                        await onFailedResponseHook(response);
+                    if (onFailedResponseHook && error.response) {
+                        await onFailedResponseHook(error.response);
                     }
                 }
             },

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@langchain/langgraph-sdk",
-  "version": "0.0.1-rc.1",
+  "version": "0.0.1-rc.10",
   "description": "Client library for interacting with the LangGraph API",
   "type": "module",
   "packageManager": "yarn@1.22.19",
@@ -9,11 +9,14 @@
     "build": "yarn clean && yarn build:esm && yarn build:cjs && node scripts/create-entrypoints.js",
     "build:esm": "rm -f src/package.json && tsc --outDir dist/ && rm -rf dist/tests dist/**/tests",
     "build:cjs": "echo '{}' > src/package.json && tsc --outDir dist-cjs/ -p tsconfig.cjs.json && node scripts/move-cjs-to-dist.js && rm -r dist-cjs src/package.json",
-    "prepublish": "yarn run build"
+    "prepublish": "yarn run build",
+    "format": "prettier --write src",
+    "lint": "prettier --check src && tsc --noEmit"
   },
   "main": "index.js",
   "license": "MIT",
   "dependencies": {
+    "@types/json-schema": "^7.0.15",
     "eventsource-parser": "^1.1.2",
     "p-queue": "^6.6.2",
     "p-retry": "4",
@@ -23,6 +26,7 @@
     "@tsconfig/recommended": "^1.0.2",
     "@types/node": "^20.12.12",
     "@types/uuid": "^9.0.1",
+    "prettier": "^3.2.5",
     "typescript": "^5.4.5"
   },
   "exports": {