@langchain/langgraph-api 1.1.8 → 1.1.10

package/dist/graph/parser/parser.mjs

@@ -0,0 +1,429 @@
+import * as ts from "typescript";
+import * as vfs from "@typescript/vfs";
+import * as path from "node:path";
+import dedent from "dedent";
+import { buildGenerator } from "./schema/types.mjs";
+import { fileURLToPath } from "node:url";
+const __dirname = fileURLToPath(new URL(".", import.meta.url));
+const OVERRIDE_RESOLVE = [
+    // Override `@langchain/langgraph` or `@langchain/langgraph/prebuilt`,
+    // but not `@langchain/langgraph-sdk`
+    new RegExp(`^@langchain\/langgraph(\/.+)?$`),
+    new RegExp(`^@langchain\/langgraph-checkpoint(\/.+)?$`),
+];
+const INFER_TEMPLATE_PATH = path.resolve(__dirname, "./schema/types.template.mts");
+export class SubgraphExtractor {
+    program;
+    checker;
+    sourceFile;
+    inferFile;
+    anyPregelType;
+    anyGraphType;
+    strict;
+    constructor(program, sourceFile, inferFile, options) {
+        this.program = program;
+        this.sourceFile = sourceFile;
+        this.inferFile = inferFile;
+        this.checker = program.getTypeChecker();
+        this.strict = options?.strict ?? false;
+        this.anyPregelType = this.findTypeByName("AnyPregel");
+        this.anyGraphType = this.findTypeByName("AnyGraph");
+    }
+    findTypeByName = (needle) => {
+        let result = undefined;
+        const visit = (node) => {
+            if (ts.isTypeAliasDeclaration(node)) {
+                const symbol = node.symbol;
+                if (symbol != null) {
+                    const name = this.checker
+                        .getFullyQualifiedName(symbol)
+                        .replace(/".*"\./, "");
+                    if (name === needle)
+                        result = this.checker.getTypeAtLocation(node);
+                }
+            }
+            if (result == null)
+                ts.forEachChild(node, visit);
+        };
+        ts.forEachChild(this.inferFile, visit);
+        if (!result)
+            throw new Error(`Failed to find "${needle}" type`);
+        return result;
+    };
+    find = (root, predicate) => {
+        let result = undefined;
+        const visit = (node) => {
+            if (predicate(node)) {
+                result = node;
+            }
+            else {
+                ts.forEachChild(node, visit);
+            }
+        };
+        if (predicate(root))
+            return root;
+        ts.forEachChild(root, visit);
+        return result;
+    };
+    findSubgraphs = (node, namespace = []) => {
+        const findAllAddNodeCalls = (acc, node) => {
+            if (ts.isCallExpression(node)) {
+                const firstChild = node.getChildAt(0);
+                if (ts.isPropertyAccessExpression(firstChild) &&
+                    this.getText(firstChild.name) === "addNode") {
+                    let nodeName = "unknown";
+                    let variables = [];
+                    const [subgraphNode, callArg] = node.arguments;
+                    if (subgraphNode && ts.isStringLiteralLike(subgraphNode)) {
+                        nodeName = this.getText(subgraphNode);
+                        if ((nodeName.startsWith(`"`) && nodeName.endsWith(`"`)) ||
+                            (nodeName.startsWith(`'`) && nodeName.endsWith(`'`))) {
+                            nodeName = nodeName.slice(1, -1);
+                        }
+                    }
+                    if (callArg) {
+                        if (ts.isFunctionLike(callArg) ||
+                            ts.isCallLikeExpression(callArg)) {
+                            variables = this.reduceChildren(callArg, this.findSubgraphIdentifiers, []);
+                        }
+                        else if (ts.isIdentifier(callArg)) {
+                            variables = this.findSubgraphIdentifiers([], callArg);
+                        }
+                    }
+                    if (variables.length > 0) {
+                        if (variables.length > 1) {
+                            const targetName = [...namespace, nodeName].join("|");
+                            const errMsg = `Multiple unique subgraph invocations found for "${targetName}"`;
+                            if (this.strict)
+                                throw new Error(errMsg);
+                            console.warn(errMsg);
+                        }
+                        acc.push({
+                            namespace: namespace,
+                            node: nodeName,
+                            subgraph: variables[0],
+                        });
+                    }
+                }
+            }
+            return acc;
+        };
+        let subgraphs = this.reduceChildren(node, findAllAddNodeCalls, []);
+        // TODO: make this more strict, only traverse the flow graph only
+        // if no `addNode` calls were found
+        if (!subgraphs.length) {
+            const candidate = this.find(node, (node) => node && "flowNode" in node && node.flowNode);
+            if (candidate?.flowNode &&
+                this.isGraphOrPregelType(this.checker.getTypeAtLocation(candidate.flowNode.node))) {
+                subgraphs = this.findSubgraphs(candidate.flowNode.node, namespace);
+            }
+        }
+        // handle recursive behaviour
+        if (subgraphs.length > 0) {
+            return [
+                ...subgraphs,
+                ...subgraphs.map(({ subgraph, node }) => this.findSubgraphs(subgraph.node, [...namespace, node])),
+            ].flat();
+        }
+        return subgraphs;
+    };
+    getSubgraphsVariables = (name) => {
+        const sourceSymbol = this.checker.getSymbolAtLocation(this.sourceFile);
+        const exports = this.checker.getExportsOfModule(sourceSymbol);
+        const targetExport = exports.find((item) => item.name === name);
+        if (!targetExport)
+            throw new Error(`Failed to find export "${name}"`);
+        const varDecls = (targetExport.declarations ?? []).filter(ts.isVariableDeclaration);
+        return varDecls.flatMap((varDecl) => {
+            if (!varDecl.initializer)
+                return [];
+            return this.findSubgraphs(varDecl.initializer, [name]);
+        });
+    };
+    getAugmentedSourceFile = (sourcePath, name, options) => {
+        function sanitize(input) {
+            return input.replace(/[^a-zA-Z0-9]/g, "_");
+        }
+        const vars = this.getSubgraphsVariables(name);
+        const ext = path.extname(sourcePath);
+        const suffix = sourcePath.slice(0, -ext.length);
+        let typeExports = [
+            {
+                typeName: sanitize(`__langgraph__${name}_${suffix}`),
+                valueName: name,
+                graphName: name,
+            },
+        ];
+        const seenTypeName = new Set();
+        for (const { subgraph, node, namespace } of vars) {
+            if (seenTypeName.has(subgraph.name))
+                continue;
+            seenTypeName.add(subgraph.name);
+            typeExports.push({
+                typeName: sanitize(`__langgraph__${namespace.join("_")}_${node}_${suffix}`),
+                valueName: subgraph.name,
+                graphName: [...namespace, node].join("|"),
+            });
+        }
+        typeExports = typeExports.map(({ typeName, ...rest }) => ({
+            ...rest,
+            typeName: sanitize(typeName),
+        }));
+        const sourceFilePath = `__langgraph__source_${sanitize(suffix)}${ext}`;
+        const sourceContents = [
+            this.getText(this.sourceFile),
+            typeExports.map((type) => `export type ${type.typeName} = typeof ${type.valueName}`),
+        ];
+        const inferFilePath = `__langgraph__infer_${sanitize(suffix)}${ext}`;
+        const sourceFileImportPath = options.allowImportingTsExtensions
+            ? sourceFilePath
+            : sourceFilePath.slice(0, -ext.length) + ext.replace("ts", "js");
+        const inferContents = [
+            typeExports.map((type) => `import type { ${type.typeName} } from "./${sourceFileImportPath}"`),
+            this.inferFile.getText(this.inferFile),
+            typeExports.map((type) => dedent `
+          type ${type.typeName}__reflect = Reflect<${type.typeName}>;
+          export type ${type.typeName}__state = Inspect<${type.typeName}__reflect["state"]>;
+          export type ${type.typeName}__update = Inspect<${type.typeName}__reflect["update"]>;
+
+          type ${type.typeName}__builder = BuilderReflect<${type.typeName}>;
+          export type ${type.typeName}__input = Inspect<FilterAny<${type.typeName}__builder["input"]>>;
+          export type ${type.typeName}__output = Inspect<FilterAny<${type.typeName}__builder["output"]>>;
+          export type ${type.typeName}__config = Inspect<FilterAny<${type.typeName}__builder["config"]>>;
+        `),
+        ];
+        return {
+            inferFile: {
+                fileName: inferFilePath,
+                contents: inferContents.flat(1).join("\n\n"),
+            },
+            sourceFile: {
+                fileName: sourceFilePath,
+                contents: sourceContents.flat(1).join("\n\n"),
+            },
+            exports: typeExports,
+        };
+    };
+    findSubgraphIdentifiers = (acc, node) => {
+        if (ts.isIdentifier(node)) {
+            const smb = this.checker.getSymbolAtLocation(node);
+            if (smb?.valueDeclaration &&
+                ts.isVariableDeclaration(smb.valueDeclaration)) {
+                const target = smb.valueDeclaration;
+                const targetType = this.checker.getTypeAtLocation(target);
+                if (this.isGraphOrPregelType(targetType)) {
+                    acc.push({ name: this.getText(target.name), node: target });
+                }
+            }
+            if (smb?.declarations) {
+                const target = smb.declarations.find(ts.isImportSpecifier);
+                if (target) {
+                    const targetType = this.checker.getTypeAtLocation(target);
+                    if (this.isGraphOrPregelType(targetType)) {
+                        acc.push({ name: this.getText(target.name), node: target });
+                    }
+                }
+            }
+        }
+        return acc;
+    };
+    isGraphOrPregelType = (type) => {
+        return (this.checker.isTypeAssignableTo(type, this.anyPregelType) ||
+            this.checker.isTypeAssignableTo(type, this.anyGraphType));
+    };
+    getText(node) {
+        return node.getText(this.sourceFile);
+    }
+    reduceChildren(node, fn, initial) {
+        let acc = initial;
+        function it(node) {
+            acc = fn(acc, node);
+            // @ts-expect-error
+            ts.forEachChild(node, it.bind(this));
+        }
+        ts.forEachChild(node, it.bind(this));
+        return acc;
+    }
+    static extractSchemas(target, options) {
+        if (!target.length)
+            throw new Error("No graphs found");
+        function getCommonPath(a, b) {
+            const aSeg = path.normalize(a).split(path.sep);
+            const bSeg = path.normalize(b).split(path.sep);
+            const maxIter = Math.min(aSeg.length, bSeg.length);
+            const result = [];
+            for (let i = 0; i < maxIter; ++i) {
+                if (aSeg[i] !== bSeg[i])
+                    break;
+                result.push(aSeg[i]);
+            }
+            return result.join(path.sep);
+        }
+        const isTestTarget = (check) => {
+            return check.every((x) => typeof x.sourceFile === "string");
+        };
+        const projectDirname = isTestTarget(target)
+            ? target.reduce((acc, item) => {
+                if (!acc)
+                    return path.dirname(item.sourceFile);
+                return getCommonPath(acc, path.dirname(item.sourceFile));
+            }, "")
+            : __dirname;
+        // This API is not well made for Windows, ensure that the paths are UNIX slashes
+        const fsMap = new Map();
+        const system = vfs.createFSBackedSystem(fsMap, projectDirname, ts);
+        // TODO: investigate if we should create a PR in @typescript/vfs
+        const oldReadFile = system.readFile.bind(system);
+        system.readFile = (fileName) => oldReadFile(fileName) ?? "// Non-existent file";
+        const vfsPath = (inputPath) => {
+            if (process.platform === "win32")
+                return inputPath.replace(/\\/g, "/");
+            return inputPath;
+        };
+        let compilerOptions = {
+            noEmit: true,
+            strict: true,
+            allowUnusedLabels: true,
+        };
+        // Find tsconfig.json file
+        const tsconfigPath = ts.findConfigFile(projectDirname, ts.sys.fileExists, "tsconfig.json");
+        // Read tsconfig.json file
+        if (tsconfigPath != null) {
+            const tsconfigFile = ts.readConfigFile(tsconfigPath, ts.sys.readFile);
+            const parsedTsconfig = ts.parseJsonConfigFileContent(tsconfigFile.config, ts.sys, path.dirname(tsconfigPath));
+            compilerOptions = {
+                ...parsedTsconfig.options,
+                ...compilerOptions,
+                ...(options?.tsConfigOptions ?? {}),
+            };
+        }
+        const vfsHost = vfs.createVirtualCompilerHost(system, compilerOptions, ts);
+        const host = vfsHost.compilerHost;
+        const targetPaths = [];
+        for (const item of target) {
+            if (typeof item.sourceFile === "string") {
+                targetPaths.push({ ...item, sourceFile: item.sourceFile });
+            }
+            else {
+                for (const { path: sourcePath, contents, main } of item.sourceFile ??
+                    []) {
+                    fsMap.set(vfsPath(path.resolve(projectDirname, sourcePath)), contents);
+                    if (main) {
+                        targetPaths.push({
+                            ...item,
+                            sourceFile: path.resolve(projectDirname, sourcePath),
+                        });
+                    }
+                }
+            }
+        }
+        const moduleCache = ts.createModuleResolutionCache(projectDirname, (x) => x);
+        host.resolveModuleNameLiterals = (entries, containingFile, redirectedReference, options) => entries.flatMap((entry) => {
+            const specifier = entry.text;
+            // Force module resolution to use @langchain/langgraph from the local project
+            // rather than from API/CLI.
+            let targetFile = containingFile;
+            if (OVERRIDE_RESOLVE.some((regex) => regex.test(specifier))) {
+                // check if we're not already importing from node_modules
+                if (!containingFile.split(path.sep).includes("node_modules")) {
+                    // Doesn't matter if the file exists, only used to nudge `ts.resolveModuleName`
+                    targetFile = path.resolve(projectDirname, "__langgraph__resolve.mts");
+                }
+            }
+            return [
+                ts.resolveModuleName(specifier, targetFile, options, host, moduleCache, redirectedReference),
+            ];
+        });
+        const research = ts.createProgram({
+            rootNames: [INFER_TEMPLATE_PATH, ...targetPaths.map((i) => i.sourceFile)],
+            options: compilerOptions,
+            host,
+        });
+        const researchTargets = [];
+        for (const targetPath of targetPaths) {
+            const extractor = new SubgraphExtractor(research, research.getSourceFile(targetPath.sourceFile), research.getSourceFile(INFER_TEMPLATE_PATH), options);
+            const graphDirname = path.dirname(targetPath.sourceFile);
+            const { sourceFile, inferFile, exports } = extractor.getAugmentedSourceFile(path.relative(projectDirname, targetPath.sourceFile), targetPath.exportSymbol, {
+                allowImportingTsExtensions: compilerOptions.allowImportingTsExtensions ?? false,
+            });
+            for (const { fileName, contents } of [sourceFile, inferFile]) {
+                system.writeFile(vfsPath(path.resolve(graphDirname, fileName)), contents);
+            }
+            researchTargets.push({
+                rootName: path.resolve(graphDirname, inferFile.fileName),
+                exports,
+            });
+        }
+        const extract = ts.createProgram({
+            rootNames: researchTargets.map((i) => i.rootName),
+            options: compilerOptions,
+            host,
+        });
+        // Print out any diagnostics file that were detected before emitting
+        // This may explain why sometimes the schema is invalid.
+        const allDiagnostics = ts.getPreEmitDiagnostics(extract);
+        for (const diagnostic of allDiagnostics) {
+            let message = ts.flattenDiagnosticMessageText(diagnostic.messageText, "\n") + "\n";
+            if (diagnostic.file) {
+                const fileName = diagnostic.file.fileName;
+                const { line, character } = ts.getLineAndCharacterOfPosition(diagnostic.file, diagnostic.start);
+                const fileLoc = `(${line + 1},${character + 1})`;
+                message = `${fileName} ${fileLoc}: ${message}`;
+            }
+            console.log(message);
+        }
+        const schemaGenerator = buildGenerator(extract);
+        const trySymbol = (symbol) => {
+            let schema = undefined;
+            try {
+                schema = schemaGenerator?.getSchemaForSymbol(symbol) ?? undefined;
+            }
+            catch (e) {
+                console.warn(`Failed to obtain symbol "${symbol}":`, e?.message);
+            }
+            if (schema == null)
+                return undefined;
+            const definitions = schema.definitions;
+            if (definitions == null)
+                return schema;
+            const toReplace = Object.keys(definitions).flatMap((key) => {
+                const replacedKey = key.includes("import(")
+                    ? key.replace(/import\(.+@langchain[\\/]core.+\)\./, "")
+                    : key;
+                if (key !== replacedKey && definitions[replacedKey] == null) {
+                    return [
+                        {
+                            source: key,
+                            target: replacedKey,
+                            sourceRef: `#/definitions/${key}`,
+                            targetRef: `#/definitions/${replacedKey}`,
+                        },
+                    ];
+                }
+                return [];
+            });
+            for (const { source, target } of toReplace) {
+                definitions[target] = definitions[source];
+                delete definitions[source];
+            }
+            const refMap = toReplace.reduce((acc, item) => {
+                acc[item.sourceRef] = item.targetRef;
+                return acc;
+            }, {});
+            return JSON.parse(JSON.stringify(schema, (_, value) => {
+                if (typeof value === "string" && refMap[value])
+                    return refMap[value];
+                return value;
+            }));
+        };
+        return researchTargets.map(({ exports }) => Object.fromEntries(exports.map(({ typeName, graphName }) => [
+            graphName,
+            {
+                state: trySymbol(`${typeName}__update`),
+                input: trySymbol(`${typeName}__input`),
+                output: trySymbol(`${typeName}__output`),
+                config: trySymbol(`${typeName}__config`),
+            },
+        ])));
+    }
+}

package/dist/graph/parser/parser.worker.d.mts

@@ -0,0 +1 @@
+export {};

package/dist/graph/parser/parser.worker.mjs

@@ -0,0 +1,7 @@
+import { tsImport } from "tsx/esm/api";
+import { parentPort } from "node:worker_threads";
+parentPort?.on("message", async (payload) => {
+    const { SubgraphExtractor } = await tsImport("./parser.mjs", import.meta.url);
+    const result = SubgraphExtractor.extractSchemas(payload, { strict: false });
+    parentPort?.postMessage(result);
+});

package/dist/graph/parser/schema/types.d.mts

@@ -0,0 +1,154 @@
+import * as ts from "typescript";
+import type { JSONSchema7 } from "json-schema";
+type Args = {
+    ref: boolean;
+    aliasRef: boolean;
+    topRef: boolean;
+    titles: boolean;
+    defaultProps: boolean;
+    noExtraProps: boolean;
+    propOrder: boolean;
+    typeOfKeyword: boolean;
+    required: boolean;
+    strictNullChecks: boolean;
+    esModuleInterop: boolean;
+    experimentalDecorators: boolean;
+    out: string;
+    validationKeywords: string[];
+    include: string[];
+    excludePrivate: boolean;
+    uniqueNames: boolean;
+    rejectDateType: boolean;
+    id: string;
+    defaultNumberType: "number" | "integer";
+    constAsEnum: boolean;
+};
+type PartialArgs = Partial<Args>;
+type RedefinedFields = "items" | "additionalItems" | "contains" | "properties" | "patternProperties" | "additionalProperties" | "dependencies" | "propertyNames" | "if" | "then" | "else" | "allOf" | "anyOf" | "oneOf" | "not" | "definitions";
+type DefinitionOrBoolean = Definition | boolean;
+interface Definition extends Omit<JSONSchema7, RedefinedFields> {
+    propertyOrder?: string[];
+    defaultProperties?: string[];
+    typeof?: "function";
+    items?: DefinitionOrBoolean | DefinitionOrBoolean[];
+    additionalItems?: DefinitionOrBoolean;
+    contains?: JSONSchema7;
+    properties?: {
+        [key: string]: DefinitionOrBoolean;
+    };
+    patternProperties?: {
+        [key: string]: DefinitionOrBoolean;
+    };
+    additionalProperties?: DefinitionOrBoolean;
+    dependencies?: {
+        [key: string]: DefinitionOrBoolean | string[];
+    };
+    propertyNames?: DefinitionOrBoolean;
+    if?: DefinitionOrBoolean;
+    then?: DefinitionOrBoolean;
+    else?: DefinitionOrBoolean;
+    allOf?: DefinitionOrBoolean[];
+    anyOf?: DefinitionOrBoolean[];
+    oneOf?: DefinitionOrBoolean[];
+    not?: DefinitionOrBoolean;
+    definitions?: {
+        [key: string]: DefinitionOrBoolean;
+    };
+}
+type SymbolRef = {
+    name: string;
+    typeName: string;
+    fullyQualifiedName: string;
+    symbol: ts.Symbol;
+};
+declare class JsonSchemaGenerator {
+    private args;
+    private tc;
+    /**
+     * Holds all symbols within a custom SymbolRef object, containing useful
+     * information.
+     */
+    private symbols;
+    /**
+     * All types for declarations of classes, interfaces, enums, and type aliases
+     * defined in all TS files.
+     */
+    private allSymbols;
+    /**
+     * All symbols for declarations of classes, interfaces, enums, and type aliases
+     * defined in non-default-lib TS files.
+     */
+    private userSymbols;
+    /**
+     * Maps from the names of base types to the names of the types that inherit from
+     * them.
+     */
+    private inheritingTypes;
+    /**
+     * This map holds references to all reffed definitions, including schema
+     * overrides and generated definitions.
+     */
+    private reffedDefinitions;
+    /**
+     * This map only holds explicit schema overrides. This helps differentiate between
+     * user defined schema overrides and generated definitions.
+     */
+    private schemaOverrides;
+    /**
+     * This is a set of all the user-defined validation keywords.
+     */
+    private userValidationKeywords;
+    /**
+     * If true, this makes constants be defined as enums with a single value. This is useful
+     * for cases where constant values are not supported, such as OpenAPI.
+     */
+    private constAsEnum;
+    /**
+     * Types are assigned names which are looked up by their IDs.  This is the
+     * map from type IDs to type names.
+     */
+    private typeNamesById;
+    /**
+     * Whenever a type is assigned its name, its entry in this dictionary is set,
+     * so that we don't give the same name to two separate types.
+     */
+    private typeIdsByName;
+    constructor(symbols: SymbolRef[], allSymbols: {
+        [name: string]: ts.Type;
+    }, userSymbols: {
+        [name: string]: ts.Symbol;
+    }, inheritingTypes: {
+        [baseName: string]: string[];
+    }, tc: ts.TypeChecker, args?: Args);
+    get ReffedDefinitions(): {
+        [key: string]: Definition;
+    };
+    private isFromDefaultLib;
+    private resetSchemaSpecificProperties;
+    /**
+     * Parse the comments of a symbol into the definition and other annotations.
+     */
+    private parseCommentsIntoDefinition;
+    private getDefinitionForRootType;
+    private getReferencedTypeSymbol;
+    private getDefinitionForProperty;
+    private getEnumDefinition;
+    private getUnionDefinition;
+    private getIntersectionDefinition;
+    private getClassDefinition;
+    /**
+     * Gets/generates a globally unique type name for the given type
+     */
+    private getTypeName;
+    private makeTypeNameUnique;
+    private recursiveTypeRef;
+    private getTypeDefinition;
+    setSchemaOverride(symbolName: string, schema: Definition): void;
+    getSchemaForSymbol(symbolName: string, includeReffedDefinitions?: boolean, includeAllOverrides?: boolean): Definition;
+    getSchemaForSymbols(symbolNames: string[], includeReffedDefinitions?: boolean, includeAllOverrides?: boolean): Definition;
+    getSymbols(name?: string): SymbolRef[];
+    getUserSymbols(): string[];
+    getMainFileSymbols(program: ts.Program, onlyIncludeFiles?: string[]): string[];
+}
+export declare function buildGenerator(program: ts.Program, args?: PartialArgs): JsonSchemaGenerator | null;
+export {};