@langchain/langgraph-cli 0.0.0-preview.4 → 0.0.0-preview.5

package/LICENSE

@@ -0,0 +1,93 @@
+Elastic License 2.0
+
+URL: https://www.elastic.co/licensing/elastic-license
+
+## Acceptance
+
+By using the software, you agree to all of the terms and conditions below.
+
+## Copyright License
+
+The licensor grants you a non-exclusive, royalty-free, worldwide,
+non-sublicensable, non-transferable license to use, copy, distribute, make
+available, and prepare derivative works of the software, in each case subject to
+the limitations and conditions below.
+
+## Limitations
+
+You may not provide the software to third parties as a hosted or managed
+service, where the service provides users with access to any substantial set of
+the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality
+in the software, and you may not remove or obscure any functionality in the
+software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices
+of the licensor in the software. Any use of the licensor’s trademarks is subject
+to applicable law.
+
+## Patents
+
+The licensor grants you a license, under any patent claims the licensor can
+license, or becomes able to license, to make, have made, use, sell, offer for
+sale, import and have imported the software, in each case subject to the
+limitations and conditions in this license. This license does not cover any
+patent claims that you cause to be infringed by modifications or additions to
+the software. If you or your company make any written claim that the software
+infringes or contributes to infringement of any patent, your patent license for
+the software granted under these terms ends immediately. If your company makes
+such a claim, your patent license ends immediately for work on behalf of your
+company.
+
+## Notices
+
+You must ensure that anyone who gets a copy of any part of the software from you
+also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the
+software prominent notices stating that you have modified the software.
+
+## No Other Rights
+
+These terms do not imply any licenses other than those expressly granted in
+these terms.
+
+## Termination
+
+If you use the software in violation of these terms, such use is not licensed,
+and your licenses will automatically terminate. If the licensor provides you
+with a notice of your violation, and you cease all violation of this license no
+later than 30 days after you receive that notice, your licenses will be
+reinstated retroactively. However, if you violate these terms after such
+reinstatement, any additional violation of these terms will cause your licenses
+to terminate automatically and permanently.
+
+## No Liability
+
+*As far as the law allows, the software comes as is, without any warranty or
+condition, and the licensor will not be liable to you for any damages arising
+out of these terms or the use or nature of the software, under any kind of
+legal claim.*
+
+## Definitions
+
+The **licensor** is the entity offering these terms, and the **software** is the
+software the licensor makes available under these terms, including any portion
+of it.
+
+**you** refers to the individual or entity agreeing to these terms.
+
+**your company** is any legal entity, sole proprietorship, or other kind of
+organization that you work for, plus all organizations that have control over,
+are under the control of, or are under common control with that
+organization. **control** means ownership of substantially all the assets of an
+entity, or the power to direct its management and policies by vote, contract, or
+otherwise. Control can be direct or indirect.
+
+**your licenses** are all the licenses granted to you for the software under
+these terms.
+
+**use** means anything you do with the software requiring one of your licenses.
+
+**trademark** means trademarks, service marks, and similar rights.

package/README.md

@@ -1,24 +1,69 @@
-# LangGraph.js API
+# LangGraph.js CLI
 
-This package implements the LangGraph API for rapid development and testing. Build and iterate on LangGraph.js agents with a tight feedback loop. The server is backed by a predominently in-memory data store that is persisted to local disk.
-
-For production use, see the various [deployment options](https://langchain-ai.github.io/langgraph/concepts/deployment_options/) for the LangGraph API, which are backed by a production-grade database.
+The official command-line interface for LangGraph.js, providing tools to create, develop, and deploy LangGraph.js applications.
 
 ## Installation
 
-Install the `@langchain/langgraph-api` package via your package manager of choice.
+The `@langchain/langgraph-cli` is a CLI binary that can be run via `npx` or installed via your package manager of choice:
+
+```bash
+npx @langchain/langgraph-cli
+```
+
+## Commands
+
+### `langgraph dev`
+
+Run LangGraph.js API server in development mode with hot reloading.
+
+```bash
+langgraph dev
+```
+
+### `langgraph build`
+
+Build a Docker image for your LangGraph.js application.
+
+```bash
+langgraph build
+```
+
+### `langgraph up`
+
+Run LangGraph.js API server in Docker.
 
 ```bash
-npm install @langchain/langgraph-api
+langgraph up
 ```
 
-## Usage
+### `langgraph dockerfile`
 
-Start the development server:
+Generate a Dockerfile for custom deployments
 
 ```bash
-npm run langgraph dev
+langgraph dockerfile <save path>
 ```
 
-Your agent's state (threads, runs, assistants, store) persists in memory while the server is running - perfect for development and testing. Each run's state is tracked and can be inspected, making it easy to debug and improve your agent's behavior.
+## Configuration
+
+The CLI uses a `langgraph.json` configuration file with these key settings:
+
+```json5
+{
+  // Required: Graph definitions
+  "graphs": {
+    "graph": "./src/graph.ts:graph" 
+  },
+
+  // Optional: Node version (20 only at the moment)
+  "node_version": "20",
+
+  // Optional: Environment variables
+  "env": ".env",
+  
+  // Optional: Additional Dockerfile commands
+  "dockerfile_lines": []
+}
+```
 
+See the [full documentation](https://langchain-ai.github.io/langgraph/cloud/reference/cli) for detailed configuration options.

package/dist/cli/build.mjs

@@ -1,7 +1,7 @@
 import { getDockerCapabilities } from "../docker/compose.mjs";
-import { assembleLocalDeps, configToDocker, getBaseImage, } from "../docker/dockerfile.mjs";
+import { assembleLocalDeps, configToDocker, getBaseImage, } from "../docker/docker.mjs";
 import { getExecaOptions } from "../docker/shell.mjs";
-import { ConfigSchema } from "../utils/config.mjs";
+import { getConfig } from "../utils/config.mjs";
 import { builder } from "./utils/builder.mjs";
 import { getProjectPath } from "./utils/project.mjs";
 import { $ } from "execa";
@@ -24,7 +24,7 @@ builder
     const configPath = await getProjectPath(params.config);
     await getDockerCapabilities();
     const projectDir = path.dirname(configPath);
-    const config = ConfigSchema.parse(JSON.parse(await fs.readFile(configPath, "utf-8")));
+    const config = getConfig(await fs.readFile(configPath, "utf-8"));
     const opts = await getExecaOptions({
         cwd: projectDir,
         stderr: "inherit",

package/dist/cli/cli.mjs

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { builder } from "./utils/builder.mjs";
 import "./dev.mjs";
-import "./dockerfile.mjs";
+import "./docker.mjs";
 import "./build.mjs";
-// import "./up.mjs";
+import "./up.mjs";
 builder.parse();

package/dist/cli/dev.mjs

@@ -5,7 +5,7 @@ import { spawn } from "node:child_process";
 import open from "open";
 import * as dotenv from "dotenv";
 import { logger } from "../logging.mjs";
-import { ConfigSchema } from "../utils/config.mjs";
+import { getConfig } from "../utils/config.mjs";
 import { createIpcServer } from "./utils/ipc/server.mjs";
 import { z } from "zod";
 import { watch } from "chokidar";
@@ -70,7 +70,7 @@ For production use, please use LangGraph Cloud.
             await fs.appendFile(gitignorePath, "\n# LangGraph API\n.langgraph_api\n");
         }
         const prepareContext = async () => {
-            const config = ConfigSchema.parse(JSON.parse(await fs.readFile(configPath, "utf-8")));
+            const config = getConfig(await fs.readFile(configPath, "utf-8"));
             const newWatch = [configPath];
             const env = { ...process.env };
             const configEnv = config?.env;

package/dist/cli/docker.mjs

@@ -0,0 +1,107 @@
+import { assembleLocalDeps, configToCompose, configToDocker, } from "../docker/docker.mjs";
+import { createCompose, getDockerCapabilities } from "../docker/compose.mjs";
+import { getConfig } from "../utils/config.mjs";
+import { getProjectPath } from "./utils/project.mjs";
+import { builder } from "./utils/builder.mjs";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import dedent from "dedent";
+import { logger } from "../logging.mjs";
+const fileExists = async (path) => {
+    try {
+        await fs.access(path);
+        return true;
+    }
+    catch (e) {
+        return false;
+    }
+};
+builder
+    .command("dockerfile")
+    .description("Generate a Dockerfile for the LangGraph API server, with Docker Compose options.")
+    .argument("<save-path>", "Path to save the Dockerfile")
+    .option("--add-docker-compose", "Add additional files for running the LangGraph API server with docker-compose. These files include a docker-compose.yml, .env file, and a .dockerignore file.")
+    .option("-c, --config <path>", "Path to configuration file", process.cwd())
+    .action(async (savePath, options) => {
+    const configPath = await getProjectPath(options.config);
+    const config = getConfig(await fs.readFile(configPath, "utf-8"));
+    const localDeps = await assembleLocalDeps(configPath, config);
+    const dockerfile = await configToDocker(configPath, config, localDeps);
+    if (savePath === "-") {
+        process.stdout.write(dockerfile);
+        process.stdout.write("\n");
+        return;
+    }
+    const targetPath = path.resolve(process.cwd(), savePath);
+    await fs.writeFile(targetPath, dockerfile);
+    logger.info(`✅ Created: ${path.basename(targetPath)}`);
+    if (options.addDockerCompose) {
+        const { apiDef } = await configToCompose(configPath, config, {
+            watch: false,
+        });
+        const capabilities = await getDockerCapabilities();
+        const compose = createCompose(capabilities, { apiDef });
+        const composePath = path.resolve(path.dirname(targetPath), "docker-compose.yml");
+        await fs.writeFile(composePath, compose);
+        logger.info("✅ Created: .docker-compose.yml");
+        const dockerignorePath = path.resolve(path.dirname(targetPath), ".dockerignore");
+        if (!fileExists(dockerignorePath)) {
+            await fs.writeFile(dockerignorePath, dedent `
+            # Ignore node_modules and other dependency directories
+            node_modules
+            bower_components
+            vendor
+  
+            # Ignore logs and temporary files
+            *.log
+            *.tmp
+            *.swp
+  
+            # Ignore .env files and other environment files
+            .env
+            .env.*
+            *.local
+  
+            # Ignore git-related files
+            .git
+            .gitignore
+  
+            # Ignore Docker-related files and configs
+            .dockerignore
+            docker-compose.yml
+  
+            # Ignore build and cache directories
+            dist
+            build
+            .cache
+            __pycache__
+  
+            # Ignore IDE and editor configurations
+            .vscode
+            .idea
+            *.sublime-project
+            *.sublime-workspace
+            .DS_Store  # macOS-specific
+  
+            # Ignore test and coverage files
+            coverage
+            *.coverage
+            *.test.js
+            *.spec.js
+            tests
+          `);
+            logger.info(`✅ Created: ${path.basename(dockerignorePath)}`);
+        }
+        const envPath = path.resolve(path.dirname(targetPath), ".env");
+        if (!fileExists(envPath)) {
+            await fs.writeFile(envPath, dedent `
+            # Uncomment the following line to add your LangSmith API key
+            # LANGSMITH_API_KEY=your-api-key
+            # Or if you have a LangGraph Cloud license key, then uncomment the following line:
+            # LANGGRAPH_CLOUD_LICENSE_KEY=your-license-key
+            # Add any other environment variables go below...
+          `);
+            logger.info(`✅ Created: ${path.basename(envPath)}`);
+        }
+    }
+});

package/dist/cli/up.mjs

@@ -0,0 +1,126 @@
+import { builder } from "./utils/builder.mjs";
+import * as fs from "node:fs/promises";
+import * as path from "node:path";
+import { getConfig } from "../utils/config.mjs";
+import { getProjectPath } from "./utils/project.mjs";
+import { logger } from "../logging.mjs";
+import { createCompose, getDockerCapabilities } from "../docker/compose.mjs";
+import { configToCompose, getBaseImage } from "../docker/docker.mjs";
+import { getExecaOptions } from "../docker/shell.mjs";
+import { $ } from "execa";
+import { createHash } from "node:crypto";
+import dedent from "dedent";
+const sha256 = (input) => createHash("sha256").update(input).digest("hex");
+const getProjectName = (configPath) => {
+    const cwd = path.dirname(configPath).toLocaleLowerCase();
+    return `${path.basename(cwd)}-${sha256(cwd)}`;
+};
+const stream = (proc) => {
+    logger.debug(`Running "${proc.spawnargs.join(" ")}"`);
+    return proc;
+};
+const waitForHealthcheck = async (port) => {
+    const now = Date.now();
+    while (Date.now() - now < 10_000) {
+        const ok = await fetch(`http://localhost:${port}/ok`).then((res) => res.ok, () => false);
+        await new Promise((resolve) => setTimeout(resolve, 100));
+        if (ok)
+            return true;
+    }
+    throw new Error("Healthcheck timed out");
+};
+builder
+    .command("up")
+    .description("Launch LangGraph API server.")
+    .option("-c, --config <path>", "Path to configuration file", process.cwd())
+    .option("-d, --docker-compose <path>", "Advanced: Path to docker-compose.yml file with additional services to launch")
+    .option("-p, --port <port>", "Port to run the server on", "8000")
+    .option("--recreate", "Force recreate containers and volumes", false)
+    .option("--no-pull", "Running the server with locally-built images. By default LangGraph will pull the latest images from the registry")
+    .option("--watch", "Restart on file changes", false)
+    .option("--wait", "Wait for services to start before returning. Implies --detach", false)
+    .option("--postgres-uri <uri>", "Postgres URI to use for the database. Defaults to launching a local database")
+    .action(async (params) => {
+    logger.info("Starting LangGraph API server...");
+    logger.warn(dedent `
+        For local dev, requires env var LANGSMITH_API_KEY with access to LangGraph Cloud closed beta.
+        For production use, requires a license key in env var LANGGRAPH_CLOUD_LICENSE_KEY.
+      `);
+    const configPath = await getProjectPath(params.config);
+    const config = getConfig(await fs.readFile(configPath, "utf-8"));
+    const cwd = path.dirname(configPath);
+    const capabilities = await getDockerCapabilities();
+    const fullRestartFiles = [configPath];
+    if (typeof config.env === "string") {
+        fullRestartFiles.push(path.resolve(cwd, config.env));
+    }
+    const { apiDef } = await configToCompose(configPath, config, {
+        watch: capabilities.watchAvailable,
+    });
+    const name = getProjectName(configPath);
+    const execOpts = await getExecaOptions({
+        cwd,
+        stdout: "inherit",
+        stderr: "inherit",
+    });
+    const exec = $(execOpts);
+    if (!config._INTERNAL_docker_tag && params.pull) {
+        // pull the image
+        logger.info(`Pulling image ${getBaseImage(config)}...`);
+        await stream(exec `docker pull ${getBaseImage(config)}`);
+    }
+    // remove dangling images
+    logger.info(`Pruning dangling images...`);
+    await stream(exec `docker image prune -f --filter ${`label=com.docker.compose.project=${name}`}`);
+    // remove stale containers
+    logger.info(`Pruning stale containers...`);
+    await stream(exec `docker container prune -f --filter ${`label=com.docker.compose.project=${name}`}`);
+    const input = createCompose(capabilities, {
+        port: +params.port,
+        postgresUri: params.postgresUri,
+        apiDef,
+    });
+    const args = ["--remove-orphans"];
+    if (params.recreate) {
+        args.push("--force-recreate", "--renew-anon-volumes");
+        try {
+            await stream(exec `docker volume rm langgraph-data`);
+        }
+        catch (e) {
+            // ignore
+        }
+    }
+    if (params.watch) {
+        if (capabilities.watchAvailable) {
+            args.push("--watch");
+        }
+        else {
+            logger.warn("Watch mode is not available. Please upgrade your Docker Engine.");
+        }
+    }
+    else if (params.wait) {
+        args.push("--wait");
+    }
+    else {
+        args.push("--abort-on-container-exit");
+    }
+    logger.info(`Launching docker-compose...`);
+    const cmd = capabilities.composeType === "plugin"
+        ? ["docker", "compose"]
+        : ["docker-compose"];
+    cmd.push("--project-directory", cwd, "--project-name", name);
+    const userCompose = params.dockerCompose || config.docker_compose_file;
+    if (userCompose)
+        cmd.push("-f", userCompose);
+    cmd.push("-f", "-");
+    const up = stream($({ ...execOpts, input }) `${cmd} up ${args}`);
+    waitForHealthcheck(+params.port).then(() => {
+        logger.info(`
+          Ready!
+          - API: http://localhost:${params.port}
+          - Docs: http://localhost:${params.port}/docs
+          - LangGraph Studio: https://smith.langchain.com/studio/?baseUrl=http://127.0.0.1:${params.port}
+        `);
+    }, () => void 0);
+    await up.catch(() => void 0);
+});

package/dist/utils/config.mjs

@@ -14,7 +14,7 @@ const StoreConfigSchema = z.object({
 const BaseConfigSchema = z.object({
     docker_compose_file: z.string().optional(),
     dockerfile_lines: z.array(z.string()).default([]),
-    graphs: z.record(z.string()).default({}),
+    graphs: z.record(z.string()),
     env: z
         .union([z.array(z.string()), z.record(z.string()), z.string()])
         .default({}),
@@ -22,7 +22,7 @@ const BaseConfigSchema = z.object({
     _INTERNAL_docker_tag: z.string().optional(),
     auth: AuthConfigSchema.optional(),
 });
-export const PythonConfigSchema = BaseConfigSchema.merge(z.object({
+const PythonConfigSchema = BaseConfigSchema.merge(z.object({
     python_version: z
         .union([z.literal("3.11"), z.literal("3.12")])
         .default("3.11"),
@@ -31,5 +31,17 @@ export const PythonConfigSchema = BaseConfigSchema.merge(z.object({
         .array(z.string())
         .nonempty("You need to specify at least one dependency"),
 }));
-export const NodeConfigSchema = BaseConfigSchema.merge(z.object({ node_version: z.literal("20") }));
-export const ConfigSchema = z.union([NodeConfigSchema, PythonConfigSchema]);
+const NodeConfigSchema = BaseConfigSchema.merge(z.object({ node_version: z.literal("20").default("20") }));
+const ConfigSchema = z.union([NodeConfigSchema, PythonConfigSchema]);
+import * as path from "node:path";
+const PYTHON_EXTENSIONS = [".py", ".pyx", ".pyd", ".pyi"];
+// TODO: implement this in Python CLI
+export const getConfig = (config) => {
+    const rawConfig = typeof config === "string" ? JSON.parse(config) : config;
+    const { graphs } = BaseConfigSchema.parse(rawConfig);
+    const preferPython = Object.values(graphs).every((i) => PYTHON_EXTENSIONS.includes(path.extname(i.split(":")[0])));
+    if (preferPython) {
+        return z.union([PythonConfigSchema, NodeConfigSchema]).parse(rawConfig);
+    }
+    return z.union([NodeConfigSchema, PythonConfigSchema]).parse(rawConfig);
+};

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@langchain/langgraph-cli",
-  "version": "0.0.0-preview.4",
+  "version": "0.0.0-preview.5",
   "type": "module",
   "engines": {
     "node": ">=18"
   },
+  "license": "Elastic-2.0",
   "main": "./dist/server.mjs",
   "bin": {
     "langgraph": "dist/cli/cli.mjs"

package/dist/cli/dockerfile.mjs

@@ -1,35 +0,0 @@
-import { assembleLocalDeps, configToCompose, configToDocker, } from "../docker/dockerfile.mjs";
-import { createCompose, getDockerCapabilities } from "../docker/compose.mjs";
-import { ConfigSchema } from "../utils/config.mjs";
-import { getProjectPath } from "./utils/project.mjs";
-import { builder } from "./utils/builder.mjs";
-import * as fs from "node:fs/promises";
-import * as path from "node:path";
-builder
-    .command("dockerfile")
-    .description("Generate a Dockerfile for the LangGraph API server, with Docker Compose options.")
-    .argument("<save-path>", "Path to save the Dockerfile")
-    .option("--add-docker-compose", "Add additional files for running the LangGraph API server with docker-compose. These files include a docker-compose.yml, .env file, and a .dockerignore file.")
-    .option("-c, --config <path>", "Path to configuration file", process.cwd())
-    .action(async (savePath, options) => {
-    const configPath = await getProjectPath(options.config);
-    const config = ConfigSchema.parse(JSON.parse(await fs.readFile(configPath, "utf-8")));
-    const localDeps = await assembleLocalDeps(configPath, config);
-    const dockerfile = await configToDocker(configPath, config, localDeps);
-    if (savePath === "-") {
-        console.log(dockerfile);
-        return;
-    }
-    const targetPath = path.resolve(process.cwd(), savePath, "Dockerfile");
-    await fs.writeFile(targetPath, dockerfile);
-    if (options.addDockerCompose) {
-        const { apiDef } = await configToCompose(configPath, config, {
-            watch: false,
-        });
-        const capabilities = await getDockerCapabilities();
-        const compose = createCompose(capabilities, { apiDef });
-        const composePath = path.resolve(process.cwd(), savePath, "docker-compose.yml");
-        await fs.writeFile(composePath, compose);
-        // TODO: add .dockerignore and .env files
-    }
-});