chore: uv lock resolution (#7342)

## Summary

Adds native uv workspace/lockfile support to the LangGraph CLI's Docker
build pipeline. Instead of listing dependencies manually, users can
point at their existing `uv.lock` and the CLI will:

1. Discover workspace packages and their dependency graph
2. Export locked requirements via `uv export --package <name> --frozen`
3. Copy only the necessary workspace closure into the container
4. Install packages in dependency order with `--no-deps` for
reproducibility
5. Rewrite all import paths (graphs, auth, encryption, etc.) to
container paths

### New config field: `source`

Rather than using `pip` or `uv pip`, we add a new `uv_lock` installer.
The previous installers should still remain unchanged.

To avoid ambiguity, we discriminate by "source" field and **do not
permit** other arbitrary "dependencies". In this mode, we will treat the
provided root (defaults to the current directory) as the source of
truth.

This also would natively support uv workspaces, so you can specify the
target package within a larger workspace.

**Simple single-package project:**
```json
{
  "python_version": "3.11",
  "graphs": {
    "agent": "./agent.py:graph"
  },
  "source": {
    "kind": "uv"
  }
}
```

**Multi-package workspace with explicit package:**
```json
{
  "python_version": "3.11",
  "graphs": {
    "agent": "../../apps/agent/src/agent/graph.py:graph"
  },
  "source": {
    "kind": "uv",
    "root": "../..",
    "package": "agent"
  }
}
```

**Traditional pip deployment (unchanged):**
```json
{
  "python_version": "3.11",
  "dependencies": ["langgraph", "my-package"],
  "graphs": {
    "agent": "./agent.py:graph"
  }
}
```

Config validation enforces mutual exclusivity. you must use either
`dependencies` or `source`, not both.

---------

Co-authored-by: Will Fu-Hinthorn <will@langchain.dev>

libs/cli/langgraph_cli/config.py

@@ -3,6 +3,7 @@ import json
 import os
 import pathlib
 import re
+import shlex
 import textwrap
 from collections import Counter
 from typing import Literal, NamedTuple
@@ -10,6 +11,7 @@ from typing import Literal, NamedTuple
 import click
 
 from langgraph_cli.schemas import Config, Distros
+from langgraph_cli.uv_lock import python_config_to_docker_uv_lock
 
 MIN_NODE_VERSION = "20"
 DEFAULT_NODE_VERSION = "20"
@@ -139,6 +141,14 @@ def _is_node_graph(spec: str | dict) -> bool:
     ]
 
 
+def _get_source_kind(config: Config) -> str | None:
+    source = config.get("source")
+    if not isinstance(source, dict):
+        return None
+    kind = source.get("kind")
+    return kind if isinstance(kind, str) else None
+
+
 def validate_config(config: Config) -> Config:
     """Validate a configuration dictionary."""
 
@@ -157,6 +167,8 @@ def validate_config(config: Config) -> Config:
     image_distro = config.get("image_distro", DEFAULT_IMAGE_DISTRO)
     internal_docker_tag = config.get("_INTERNAL_docker_tag")
     api_version = config.get("api_version")
+    legacy_project_root = config.get("project_root")
+    legacy_package = config.get("package")
     if internal_docker_tag:
         if api_version:
             raise click.UsageError(
@@ -177,6 +189,7 @@ def validate_config(config: Config) -> Config:
         "python_version": python_version,
         "pip_config_file": config.get("pip_config_file"),
         "pip_installer": config.get("pip_installer", "auto"),
+        "source": config.get("source"),
         "base_image": config.get("base_image"),
         "image_distro": image_distro,
         "dependencies": config.get("dependencies", []),
@@ -212,6 +225,26 @@ def validate_config(config: Config) -> Config:
         except ValueError as e:
             raise click.UsageError(str(e)) from None
 
+    if pip_installer := config.get("pip_installer"):
+        if pip_installer == "uv_lock":
+            raise click.UsageError(
+                "pip_installer 'uv_lock' has been replaced. Use "
+                '`source: {"kind": "uv", "root": "..", '
+                '"package": "my-agent"}`.'
+            )
+        if pip_installer not in ["auto", "pip", "uv"]:
+            raise click.UsageError(
+                f"Invalid pip_installer: '{pip_installer}'. "
+                "Must be 'auto', 'pip', or 'uv'."
+            )
+
+    source = config.get("source")
+    source_kind = _get_source_kind(config)
+    if source is not None and not isinstance(source, dict):
+        raise click.UsageError("`source` must be an object.")
+    if source is not None and source_kind != "uv":
+        raise click.UsageError("Invalid source.kind. Supported values: 'uv'.")
+
     if config.get("python_version"):
         pyversion = config["python_version"]
         if not pyversion.count(".") == 1 or not all(
@@ -233,7 +266,7 @@ def validate_config(config: Config) -> Config:
                 "Please use 'bookworm' or 'debian' instead."
             )
 
-        if not config["dependencies"]:
+        if source_kind != "uv" and not config["dependencies"]:
             raise click.UsageError(
                 "No dependencies found in config. "
                 "Add at least one dependency to 'dependencies' list."
@@ -257,12 +290,42 @@ def validate_config(config: Config) -> Config:
                 "Must be one of 'debian', 'wolfi', or 'bookworm'."
             )
 
-    if pip_installer := config.get("pip_installer"):
-        if pip_installer not in ["auto", "pip", "uv"]:
-            raise click.UsageError(
-                f"Invalid pip_installer: '{pip_installer}'. "
-                "Must be 'auto', 'pip', or 'uv'."
+    if source_kind == "uv":
+        errors: list[str] = []
+        if not config.get("python_version"):
+            errors.append(
+                "source.kind 'uv' requires `python_version` — "
+                "it is a Python-only deployment mode. "
+                "Node.js-only graphs are not supported."
             )
+        if config["dependencies"]:
+            errors.append(
+                "Remove `dependencies` from your config. With "
+                '`source.kind = "uv"`, all dependencies '
+                "are read from your pyproject.toml and uv.lock instead."
+            )
+        root = source.get("root", ".") if source else "."
+        if not isinstance(root, str):
+            errors.append(f"`source.root` must be a string, got {type(root).__name__}.")
+        elif not root.strip():
+            errors.append('`source.root` must be a non-empty string. Use `"."`.')
+        package_name = source.get("package") if source else None
+        if package_name is not None and (
+            not isinstance(package_name, str) or not package_name.strip()
+        ):
+            errors.append("`source.package` must be a non-empty string.")
+        if errors:
+            detail = "\n".join(f"  - {e}" for e in errors)
+            raise click.UsageError(
+                "source.kind 'uv' requires a different "
+                f"config shape than dependency-based installs:\n{detail}"
+            )
+
+    if legacy_project_root or legacy_package:
+        raise click.UsageError(
+            "Top-level `project_root` and `package` are no longer supported. "
+            "Use `source.root` and `source.package` instead."
+        )
 
     # Validate auth config
     if auth_conf := config.get("auth"):
@@ -807,9 +870,65 @@ def _update_http_app_path(
         http_config["app"] = f"{module_str}:{attr_str}"
 
 
-def _get_node_pm_install_cmd(config_path: pathlib.Path, config: Config) -> str:
+def _build_python_install_commands(
+    config: Config, install_cmd: str
+) -> tuple[str, str, str]:
+    base_install = f"PYTHONDONTWRITEBYTECODE=1 {install_cmd} --no-cache-dir -c /api/constraints.txt"
+    local_reqs_pip_install = base_install
+    global_reqs_pip_install = base_install
+
+    if config.get("pip_config_file"):
+        local_reqs_pip_install = (
+            f"PIP_CONFIG_FILE=/pipconfig.txt {local_reqs_pip_install}"
+        )
+        global_reqs_pip_install = (
+            f"PIP_CONFIG_FILE=/pipconfig.txt {global_reqs_pip_install}"
+        )
+
+    pip_config_file_str = (
+        f"ADD {config['pip_config_file']} /pipconfig.txt"
+        if config.get("pip_config_file")
+        else ""
+    )
+    return local_reqs_pip_install, global_reqs_pip_install, pip_config_file_str
+
+
+def _build_runtime_env_vars(config: Config) -> list[str]:
+    env_vars = []
+
+    if (store_config := config.get("store")) is not None:
+        env_vars.append(f"ENV LANGGRAPH_STORE='{json.dumps(store_config)}'")
+
+    if (auth_config := config.get("auth")) is not None:
+        env_vars.append(f"ENV LANGGRAPH_AUTH='{json.dumps(auth_config)}'")
+
+    if (encryption_config := config.get("encryption")) is not None:
+        env_vars.append(f"ENV LANGGRAPH_ENCRYPTION='{json.dumps(encryption_config)}'")
+
+    if (http_config := config.get("http")) is not None:
+        env_vars.append(f"ENV LANGGRAPH_HTTP='{json.dumps(http_config)}'")
+
+    if (webhooks_config := config.get("webhooks")) is not None:
+        env_vars.append(f"ENV LANGGRAPH_WEBHOOKS='{json.dumps(webhooks_config)}'")
+
+    if (checkpointer_config := config.get("checkpointer")) is not None:
+        env_vars.append(
+            f"ENV LANGGRAPH_CHECKPOINTER='{json.dumps(checkpointer_config)}'"
+        )
+
+    if (ui := config.get("ui")) is not None:
+        env_vars.append(f"ENV LANGGRAPH_UI='{json.dumps(ui)}'")
+
+    if (ui_config := config.get("ui_config")) is not None:
+        env_vars.append(f"ENV LANGGRAPH_UI_CONFIG='{json.dumps(ui_config)}'")
+
+    env_vars.append(f"ENV LANGSERVE_GRAPHS='{json.dumps(config['graphs'])}'")
+    return env_vars
+
+
+def _get_node_pm_install_cmd(project_dir: pathlib.Path) -> str:
     def test_file(file_name):
-        full_path = config_path.parent / file_name
+        full_path = project_dir / file_name
         try:
             return full_path.is_file()
         except OSError:
@@ -818,7 +937,7 @@ def _get_node_pm_install_cmd(config_path: pathlib.Path, config: Config) -> str:
     # inspired by `package-manager-detector`
     def get_pkg_manager_name():
         try:
-            with open(config_path.parent / "package.json") as f:
+            with open(project_dir / "package.json") as f:
                 pkg = json.load(f)
 
                 if (pkg_manager_name := pkg.get("packageManager")) and isinstance(
@@ -914,8 +1033,17 @@ def python_config_to_docker(
     escape_variables: bool = False,
 ) -> tuple[str, dict[str, str]]:
     """Generate a Dockerfile from the configuration."""
+    source_kind = _get_source_kind(config)
     pip_installer = config.get("pip_installer", "auto")
     build_tools_to_uninstall = get_build_tools_to_uninstall(config)
+    if source_kind == "uv":
+        return python_config_to_docker_uv_lock(
+            config_path,
+            config,
+            base_image,
+            api_version=api_version,
+            build_tools_to_uninstall=build_tools_to_uninstall,
+        )
     if pip_installer == "auto":
         if _image_supports_uv(base_image):
             pip_installer = "uv"
@@ -928,21 +1056,11 @@ def python_config_to_docker(
     else:
         raise ValueError(f"Invalid pip_installer: {pip_installer}")
 
-    # configure pip
-    local_reqs_pip_install = f"PYTHONDONTWRITEBYTECODE=1 {install_cmd} --no-cache-dir -c /api/constraints.txt"
-    global_reqs_pip_install = f"PYTHONDONTWRITEBYTECODE=1 {install_cmd} --no-cache-dir -c /api/constraints.txt"
-    if config.get("pip_config_file"):
-        local_reqs_pip_install = (
-            f"PIP_CONFIG_FILE=/pipconfig.txt {local_reqs_pip_install}"
-        )
-        global_reqs_pip_install = (
-            f"PIP_CONFIG_FILE=/pipconfig.txt {global_reqs_pip_install}"
-        )
-    pip_config_file_str = (
-        f"ADD {config['pip_config_file']} /pipconfig.txt"
-        if config.get("pip_config_file")
-        else ""
-    )
+    (
+        local_reqs_pip_install,
+        global_reqs_pip_install,
+        pip_config_file_str,
+    ) = _build_python_install_commands(config, install_cmd)
 
     # collect dependencies
     pypi_deps = [dep for dep in config["dependencies"] if not dep.startswith(".")]
@@ -998,7 +1116,7 @@ RUN set -ex && \\
                 '[build-system]' \\
                 'requires = ["setuptools>=61"]' \\
                 'build-backend = "setuptools.build_meta"'; do \\
-        echo "$line" >> /deps/outer-{fullpath.name}/pyproject.toml; \\
+        echo "$line" >> {shlex.quote(f"/deps/outer-{fullpath.name}/pyproject.toml")}; \\
     done
 # -- End of non-package dependency {fullpath.name} --"""
         for fullpath, (relpath, destpath) in local_deps.faux_pkgs.items()
@@ -1017,56 +1135,50 @@ ADD {relpath} /deps/{name}
         for fullpath, (relpath, name) in local_deps.real_pkgs.items()
     )
 
+    additional_contexts: dict[str, str] = {}
+    additional_context_names: dict[pathlib.Path, str] = {}
+    used_context_names: set[str] = set()
+
+    def register_additional_context(path: pathlib.Path, preferred_name: str) -> str:
+        if path in additional_context_names:
+            return additional_context_names[path]
+
+        name = preferred_name
+        suffix = 1
+        while name in used_context_names:
+            name = f"{preferred_name}_{suffix}"
+            suffix += 1
+
+        used_context_names.add(name)
+        additional_context_names[path] = name
+        additional_contexts[name] = str(path)
+        return name
+
+    for p in local_deps.additional_contexts:
+        if p in local_deps.real_pkgs:
+            preferred_name = local_deps.real_pkgs[p][1]
+        elif p in local_deps.faux_pkgs:
+            preferred_name = f"outer-{p.name}"
+        else:
+            raise RuntimeError(f"Unknown additional context: {p}")
+        register_additional_context(p, preferred_name)
+
     install_node_str: str = (
         "RUN /storage/install-node.sh"
         if (config.get("ui") or config.get("node_version")) and local_deps.working_dir
         else ""
     )
 
+    install_steps = [install_node_str, pip_config_file_str, pip_pkgs_str, pip_reqs_str]
+    install_steps.extend([local_pkgs_str, faux_pkgs_str])
     installs = f"{os.linesep}{os.linesep}".join(
         filter(
             None,
-            [
-                install_node_str,
-                pip_config_file_str,
-                pip_pkgs_str,
-                pip_reqs_str,
-                local_pkgs_str,
-                faux_pkgs_str,
-            ],
+            install_steps,
         )
     )
 
-    env_vars = []
-
-    if (store_config := config.get("store")) is not None:
-        env_vars.append(f"ENV LANGGRAPH_STORE='{json.dumps(store_config)}'")
-
-    if (auth_config := config.get("auth")) is not None:
-        env_vars.append(f"ENV LANGGRAPH_AUTH='{json.dumps(auth_config)}'")
-
-    if (encryption_config := config.get("encryption")) is not None:
-        env_vars.append(f"ENV LANGGRAPH_ENCRYPTION='{json.dumps(encryption_config)}'")
-
-    if (http_config := config.get("http")) is not None:
-        env_vars.append(f"ENV LANGGRAPH_HTTP='{json.dumps(http_config)}'")
-
-    # Inject webhooks configuration if provided
-    if (webhooks_config := config.get("webhooks")) is not None:
-        env_vars.append(f"ENV LANGGRAPH_WEBHOOKS='{json.dumps(webhooks_config)}'")
-
-    if (checkpointer_config := config.get("checkpointer")) is not None:
-        env_vars.append(
-            f"ENV LANGGRAPH_CHECKPOINTER='{json.dumps(checkpointer_config)}'"
-        )
-
-    if (ui := config.get("ui")) is not None:
-        env_vars.append(f"ENV LANGGRAPH_UI='{json.dumps(ui)}'")
-
-    if (ui_config := config.get("ui_config")) is not None:
-        env_vars.append(f"ENV LANGGRAPH_UI_CONFIG='{json.dumps(ui_config)}'")
-
-    env_vars.append(f"ENV LANGSERVE_GRAPHS='{json.dumps(config['graphs'])}'")
+    env_vars = _build_runtime_env_vars(config)
 
     js_inst_str: str = ""
     if (config.get("ui") or config.get("node_version")) and local_deps.working_dir:
@@ -1074,7 +1186,8 @@ ADD {relpath} /deps/{name}
             [
                 "# -- Installing JS dependencies --",
                 f"ENV NODE_VERSION={config.get('node_version') or DEFAULT_NODE_VERSION}",
-                f"RUN cd {local_deps.working_dir} && {_get_node_pm_install_cmd(config_path, config)} && tsx /api/langgraph_api/js/build.mts",
+                f"WORKDIR {local_deps.working_dir}",
+                f"RUN {_get_node_pm_install_cmd(config_path.parent)} && tsx /api/langgraph_api/js/build.mts",
                 "# -- End of JS dependencies install --",
             ]
         )
@@ -1084,7 +1197,7 @@ ADD {relpath} /deps/{name}
     docker_file_contents = []
 
     # Add syntax directive if we have additional contexts (requires BuildKit frontend.contexts capability)
-    if local_deps.additional_contexts:
+    if additional_contexts:
         docker_file_contents.extend(
             [
                 "# syntax=docker/dockerfile:1.4",
@@ -1094,6 +1207,13 @@ ADD {relpath} /deps/{name}
 
     # Add main dockerfile content
     dep_vname = "$$dep" if escape_variables else "$dep"
+    local_deps_install_str = f"""RUN for dep in /deps/*; do \
+            echo "Installing {dep_vname}"; \
+            if [ -d "{dep_vname}" ]; then \
+                echo "Installing {dep_vname}"; \
+                (cd "{dep_vname}" && {global_reqs_pip_install} -e .); \
+            fi; \
+        done"""
     docker_file_contents.extend(
         [
             f"FROM {image_str}",
@@ -1103,13 +1223,7 @@ ADD {relpath} /deps/{name}
             installs,
             "",
             "# -- Installing all local dependencies --",
-            f"""RUN for dep in /deps/*; do \
-            echo "Installing {dep_vname}"; \
-            if [ -d "{dep_vname}" ]; then \
-                echo "Installing {dep_vname}"; \
-                (cd "{dep_vname}" && {global_reqs_pip_install} -e .); \
-            fi; \
-        done""",
+            local_deps_install_str,
             "# -- End of local dependencies install --",
             os.linesep.join(env_vars),
             "",
@@ -1126,16 +1240,6 @@ ADD {relpath} /deps/{name}
         ]
     )
 
-    additional_contexts: dict[str, str] = {}
-    for p in local_deps.additional_contexts:
-        if p in local_deps.real_pkgs:
-            name = local_deps.real_pkgs[p][1]
-        elif p in local_deps.faux_pkgs:
-            name = f"outer-{p.name}"
-        else:
-            raise RuntimeError(f"Unknown additional context: {p}")
-        additional_contexts[name] = str(p)
-
     return os.linesep.join(docker_file_contents), additional_contexts
 
 
@@ -1149,6 +1253,10 @@ def node_config_to_docker(
     build_context: str | None = None,
 ) -> tuple[str, dict[str, str]]:
     # Calculate paths for monorepo support
+    install_root = (
+        pathlib.Path(build_context).resolve() if build_context else config_path.parent
+    )
+    install_cmd = install_command or _get_node_pm_install_cmd(install_root)
     if build_context:
         relative_workdir = _calculate_relative_workdir(config_path, build_context)
         container_name = pathlib.Path(build_context).name
@@ -1160,60 +1268,32 @@ def node_config_to_docker(
         # Backward compatibility: use the original behavior
         faux_path = f"/deps/{config_path.parent.name}"
 
-    # Use custom install command or auto-detect
-    if install_command:
-        install_cmd = install_command
-    else:
-        install_cmd = _get_node_pm_install_cmd(config_path, config)
-
     image_str = docker_tag(config, base_image, api_version)
 
-    env_vars: list[str] = []
-
-    if (store_config := config.get("store")) is not None:
-        env_vars.append(f"ENV LANGGRAPH_STORE='{json.dumps(store_config)}'")
-
-    if (auth_config := config.get("auth")) is not None:
-        env_vars.append(f"ENV LANGGRAPH_AUTH='{json.dumps(auth_config)}'")
-
-    if (encryption_config := config.get("encryption")) is not None:
-        env_vars.append(f"ENV LANGGRAPH_ENCRYPTION='{json.dumps(encryption_config)}'")
-
-    if (http_config := config.get("http")) is not None:
-        env_vars.append(f"ENV LANGGRAPH_HTTP='{json.dumps(http_config)}'")
-
-    # Inject webhooks configuration if provided
-    if (webhooks_config := config.get("webhooks")) is not None:
-        env_vars.append(f"ENV LANGGRAPH_WEBHOOKS='{json.dumps(webhooks_config)}'")
-
-    if (checkpointer_config := config.get("checkpointer")) is not None:
-        env_vars.append(
-            f"ENV LANGGRAPH_CHECKPOINTER='{json.dumps(checkpointer_config)}'"
-        )
-
-    if ui := config.get("ui"):
-        env_vars.append(f"ENV LANGGRAPH_UI='{json.dumps(ui)}'")
-
-    if ui_config := config.get("ui_config"):
-        env_vars.append(f"ENV LANGGRAPH_UI_CONFIG='{json.dumps(ui_config)}'")
-
-    env_vars.append(f"ENV LANGSERVE_GRAPHS='{json.dumps(config['graphs'])}'")
+    env_vars = _build_runtime_env_vars(config)
 
     # For monorepo support, we need to handle install and build commands differently
     if build_context:
         # Monorepo case: install from root, build from config directory
         container_root = f"/deps/{pathlib.Path(build_context).name}"
-        install_step = f"RUN cd {container_root} && {install_cmd}"
+        install_workdir = container_root
+        install_step = f"RUN {install_cmd}"
 
         if build_command:
-            build_step = f"RUN cd {faux_path} && {build_command}"
+            build_step = f"RUN {build_command}"
         else:
             build_step = 'RUN (test ! -f /api/langgraph_api/js/build.mts && echo "Prebuild script not found, skipping") || tsx /api/langgraph_api/js/build.mts'
     else:
         # Original behavior: everything happens in the same directory
-        install_step = f"RUN cd {faux_path} && {install_cmd}"
+        install_workdir = faux_path
+        install_step = f"RUN {install_cmd}"
         build_step = 'RUN (test ! -f /api/langgraph_api/js/build.mts && echo "Prebuild script not found, skipping") || tsx /api/langgraph_api/js/build.mts'
 
+    if build_context:
+        build_workdir = faux_path
+    else:
+        build_workdir = faux_path
+
     docker_file_contents = [
         f"FROM {image_str}",
         "",
@@ -1221,11 +1301,13 @@ def node_config_to_docker(
         "",
         f"ADD . {faux_path if not build_context else container_root}",
         "",
+        f"WORKDIR {install_workdir}",
+        "",
         install_step,
         "",
         os.linesep.join(env_vars),
         "",
-        f"WORKDIR {faux_path}",
+        f"WORKDIR {build_workdir}",
         "",
         build_step,
     ]

libs/cli/langgraph_cli/schemas.py

@@ -1,5 +1,7 @@
 from typing import Any, Literal, TypedDict
 
+from typing_extensions import Required
+
 Distros = Literal["debian", "wolfi", "bookworm"]
 MiddlewareOrders = Literal["auth_first", "middleware_first"]
 
@@ -9,20 +11,20 @@ class TTLConfig(TypedDict, total=False):
 
     refresh_on_read: bool
     """Default behavior for refreshing TTLs on read operations (`GET` and `SEARCH`).
-    
+
     If `True`, TTLs will be refreshed on read operations (get/search) by default.
     This can be overridden per-operation by explicitly setting `refresh_ttl`.
     Defaults to `True` if not configured.
     """
     default_ttl: float | None
     """Optional. Default TTL (time-to-live) in minutes for new items.
-    
+
     If provided, all new items will have this TTL unless explicitly overridden.
     If omitted, items will have no TTL by default.
     """
     sweep_interval_minutes: int | None
     """Optional. Interval in minutes between TTL sweep iterations.
-    
+
     If provided, the store will periodically delete expired items based on the TTL.
     If omitted, no automatic sweeping will occur.
     """
@@ -36,10 +38,10 @@ class IndexConfig(TypedDict, total=False):
 
     dims: int
     """Required. Dimensionality of the embedding vectors you will store.
-    
+
     Must match the output dimension of your selected embedding model or custom embed function.
     If mismatched, you will likely encounter shape/size errors when inserting or querying vectors.
-    
+
     Common embedding model output dimensions:
         - openai:text-embedding-3-large: 3072
         - openai:text-embedding-3-small: 1536
@@ -52,7 +54,7 @@ class IndexConfig(TypedDict, total=False):
 
     embed: str
     """Required. Identifier or reference to the embedding model or a custom embedding function.
-    
+
     The format can vary:
       - "<provider>:<model_name>" for recognized providers (e.g., "openai:text-embedding-3-large")
       - "path/to/module.py:function_name" for your own local embedding function
@@ -62,17 +64,17 @@ class IndexConfig(TypedDict, total=False):
         - "openai:text-embedding-3-large"
         - "cohere:embed-multilingual-v3.0"
         - "src/app.py:embeddings"
-    
+
     Note: Must return embeddings of dimension `dims`.
     """
 
     fields: list[str] | None
     """Optional. List of JSON fields to extract before generating embeddings.
-    
+
     Defaults to ["$"], which means the entire JSON object is embedded as one piece of text.
     If you provide multiple fields (e.g. ["title", "content"]), each is extracted and embedded separately,
     often saving token usage if you only care about certain parts of the data.
-    
+
     Example:
         fields=["title", "abstract", "author.biography"]
     """
@@ -87,18 +89,18 @@ class StoreConfig(TypedDict, total=False):
 
     index: IndexConfig | None
     """Optional. Defines the vector-based semantic search configuration.
-    
+
     If provided, the store will:
       - Generate embeddings according to `index.embed`
       - Enforce the embedding dimension given by `index.dims`
       - Embed only specified JSON fields (if any) from `index.fields`
-    
+
     If omitted, no vector index is initialized.
     """
 
     ttl: TTLConfig | None
     """Optional. Defines the TTL (time-to-live) behavior configuration.
-    
+
     If provided, the store will apply TTL settings according to the configuration.
     If omitted, no TTL behavior is configured.
     """
@@ -129,11 +131,11 @@ class SerdeConfig(TypedDict, total=False):
 
     allowed_json_modules: list[list[str]] | bool | None
     """Optional. List of allowed python modules to de-serialize custom objects from JSON.
-    
+
     If provided, only the specified modules will be allowed to be deserialized.
     If omitted, no modules are allowed, and the object returned will simply be a json object OR
     a deserialized langchain object.
-    
+
     Example:
     {...
         "serde": {
@@ -178,11 +180,11 @@ class SerdeConfig(TypedDict, total=False):
             "allowed_msgpack_modules": null
         }
     }
-    
+
     """
     pickle_fallback: bool
     """Optional. Whether to allow pickling as a fallback for deserialization.
-    
+
     If True, pickling will be allowed as a fallback for deserialization.
     If False, pickling will not be allowed as a fallback for deserialization.
     Defaults to True if not configured."""
@@ -216,7 +218,7 @@ class CheckpointerConfig(TypedDict, total=False):
 
     ttl: ThreadTTLConfig | None
     """Optional. Defines the TTL (time-to-live) behavior configuration.
-    
+
     If provided, the checkpointer will apply TTL settings according to the configuration.
     If omitted, no TTL behavior is configured.
     """
@@ -239,7 +241,7 @@ class SecurityConfig(TypedDict, total=False):
 
     securitySchemes: dict[str, dict[str, Any]]
     """Describe each security scheme recognized by your OpenAPI spec.
-    
+
     Keys are scheme names (e.g. "OAuth2", "ApiKeyAuth") and values are their definitions.
     Example:
         {
@@ -256,7 +258,7 @@ class SecurityConfig(TypedDict, total=False):
     """
     security: list[dict[str, list[str]]]
     """Global security requirements across all endpoints.
-    
+
     Each element in the list maps a security scheme (e.g. "OAuth2") to a list of scopes (e.g. ["read", "write"]).
     Example:
         [
@@ -267,11 +269,11 @@ class SecurityConfig(TypedDict, total=False):
     # path => {method => security}
     paths: dict[str, dict[str, list[dict[str, list[str]]]]]
     """Path-specific security overrides.
-    
+
     Keys are path templates (e.g., "/items/{item_id}"), mapping to:
       - Keys that are HTTP methods (e.g., "GET", "POST"),
       - Values are lists of security definitions (just like `security`) for that method.
-    
+
     Example:
         {
             "/private_data": {
@@ -285,19 +287,19 @@ class SecurityConfig(TypedDict, total=False):
 class CacheConfig(TypedDict, total=False):
     cache_keys: list[str]
     """Optional. List of header keys to use for caching.
-    
+
     Example:
         ["user_id", "workspace_id"]
     """
     ttl_seconds: int
     """Optional. Time-to-live in seconds for cached items.
-    
+
     Example:
         3600
     """
     max_size: int
     """Optional. Maximum size of the cache.
-    
+
     Example:
         100
     """
@@ -308,19 +310,19 @@ class AuthConfig(TypedDict, total=False):
 
     path: str
     """Required. Path to an instance of the Auth() class that implements custom authentication.
-    
+
     Format: "path/to/file.py:my_auth"
     """
     disable_studio_auth: bool
-    """Optional. Whether to disable LangSmith API-key authentication for requests originating the Studio. 
-    
+    """Optional. Whether to disable LangSmith API-key authentication for requests originating the Studio.
+
     Defaults to False, meaning that if a particular header is set, the server will verify the `x-api-key` header
     value is a valid API key for the deployment's workspace. If `True`, all requests will go through your custom
     authentication logic, regardless of origin of the request.
     """
     openapi: SecurityConfig
     """The security configuration to include in your server's OpenAPI spec.
-    
+
     Example (OAuth2):
         {
             "securitySchemes": {
@@ -341,7 +343,7 @@ class AuthConfig(TypedDict, total=False):
     """
     cache: CacheConfig
     """Optional. Cache configuration for the server.
-    
+
     Example:
         {
             "cache_keys": ["user_id", "workspace_id"],
@@ -380,32 +382,32 @@ class CorsConfig(TypedDict, total=False):
 
     allow_origins: list[str]
     """Optional. List of allowed origins (e.g., "https://example.com").
-    
-    Default is often an empty list (no external origins). 
+
+    Default is often an empty list (no external origins).
     Use "*" only if you trust all origins, as that bypasses most restrictions.
     """
     allow_methods: list[str]
     """Optional. HTTP methods permitted for cross-origin requests (e.g. ["GET", "POST"]).
-    
+
     Default might be ["GET", "POST", "OPTIONS"] depending on your server framework.
     """
     allow_headers: list[str]
     """Optional. HTTP headers that can be used in cross-origin requests (e.g. ["Content-Type", "Authorization"])."""
     allow_credentials: bool
     """Optional. If `True`, cross-origin requests can include credentials (cookies, auth headers).
-    
+
     Default False to avoid accidentally exposing secured endpoints to untrusted sites.
     """
     allow_origin_regex: str
     """Optional. A regex pattern for matching allowed origins, used if you have dynamic subdomains.
-    
+
     Example: "^https://.*\\.mycompany\\.com$"
     """
     expose_headers: list[str]
     """Optional. List of headers that browsers are allowed to read from the response in cross-origin contexts."""
     max_age: int
     """Optional. How many seconds the browser may cache preflight responses.
-    
+
     Default might be 600 (10 minutes). Larger values reduce preflight requests but can cause stale configurations.
     """
 
@@ -442,61 +444,61 @@ class HttpConfig(TypedDict, total=False):
 
     app: str
     """Optional. Import path to a custom Starlette/FastAPI application to mount.
-    
+
     Format: "path/to/module.py:app_var"
     If provided, it can override or extend the default routes.
     """
     disable_assistants: bool
     """Optional. If `True`, /assistants routes are removed from the server.
-    
+
     Default is False (meaning /assistants is enabled).
     """
     disable_threads: bool
     """Optional. If `True`, /threads routes are removed.
-    
+
     Default is False.
     """
     disable_runs: bool
     """Optional. If `True`, /runs routes are removed.
-    
+
     Default is False.
     """
     disable_store: bool
     """Optional. If `True`, /store routes are removed, disabling direct store interactions via HTTP.
-    
+
     Default is False.
     """
     disable_mcp: bool
     """Optional. If `True`, /mcp routes are removed, disabling default support to expose the deployment as an MCP server.
-    
+
     Default is False.
     """
     disable_a2a: bool
     """Optional. If `True`, /a2a routes are removed, disabling default support to expose the deployment as an agent-to-agent (A2A) server.
-    
+
     Default is False.
     """
     disable_meta: bool
     """Optional. Remove meta endpoints.
-    
+
     Set to True to disable the following endpoints: /openapi.json, /info, /metrics, /docs.
     This will also make the /ok endpoint skip any DB or other checks, always returning {"ok": True}.
-    
+
     Default is False.
     """
     disable_ui: bool
     """Optional. If `True`, /ui routes are removed, disabling the UI server.
-    
+
     Default is False.
     """
     disable_webhooks: bool
     """Optional. If `True`, webhooks are disabled. Runs created with an associated webhook will
     still be executed, but the webhook event will not be sent.
-    
+
     Default is False.
     """
     cors: CorsConfig | None
-    """Optional. Defines CORS restrictions. If omitted, no special rules are set and 
+    """Optional. Defines CORS restrictions. If omitted, no special rules are set and
     cross-origin behavior depends on default server settings.
     """
     configurable_headers: ConfigurableHeaderConfig | None
@@ -527,7 +529,7 @@ class HttpConfig(TypedDict, total=False):
     """
     mount_prefix: str
     """Optional. URL prefix to prepend to all the routes.
-    
+
     Example:
         "/api"
     """
@@ -588,11 +590,33 @@ class WebhooksConfig(TypedDict, total=False):
     """
 
 
+class UvSource(TypedDict, total=False):
+    """Deployment source rooted at a uv project or workspace."""
+
+    kind: Required[Literal["uv"]]
+    """Discriminator for uv-backed deployment mode."""
+
+    root: str
+    """Relative path from langgraph.json to the authoritative uv project root.
+
+    The resolved directory must contain `pyproject.toml` and `uv.lock`. If the
+    root is a workspace, package discovery happens within this root.
+    """
+
+    package: str
+    """Optional. Workspace package name to deploy when the target is ambiguous.
+
+    If omitted, the CLI tries to infer the target package from the location of
+    `langgraph.json`, or falls back to the only package if the root contains
+    exactly one candidate.
+    """
+
+
 class Config(TypedDict, total=False):
     """Top-level config for langgraph-cli or similar deployment tooling."""
 
     python_version: str
-    """Optional. Python version in 'major.minor' format (e.g. '3.11'). 
+    """Optional. Python version in 'major.minor' format (e.g. '3.11').
     Must be at least 3.11 or greater for this deployment to function properly.
     """
 
@@ -603,7 +627,7 @@ class Config(TypedDict, total=False):
 
     api_version: str | None
     """Optional. Which semantic version of the LangGraph API server to use.
-    
+
     Defaults to latest. Check the
     [changelog](https://docs.langchain.com/langgraph-platform/langgraph-server-changelog)
     for more information."""
@@ -614,12 +638,12 @@ class Config(TypedDict, total=False):
 
     base_image: str | None
     """Optional. Base image to use for the LangGraph API server.
-    
+
     Defaults to langchain/langgraph-api or langchain/langgraphjs-api."""
 
     image_distro: Distros | None
     """Optional. Linux distribution for the base image.
-    
+
     Must be one of 'wolfi', 'debian', or 'bookworm'.
     If omitted, defaults to 'debian' ('latest').
     """
@@ -627,22 +651,30 @@ class Config(TypedDict, total=False):
     pip_config_file: str | None
     """Optional. Path to a pip config file (e.g., "/etc/pip.conf" or "pip.ini") for controlling
     package installation (custom indices, credentials, etc.).
-    
+
     Only relevant if Python dependencies are installed via pip. If omitted, default pip settings are used.
     """
 
     pip_installer: str | None
-    """Optional. Python package installer to use ('auto', 'pip', 'uv').
-    
+    """Optional. Python package installer to use ('auto', 'pip', or 'uv').
+
     - 'auto' (default): Use uv for supported base images, otherwise pip
     - 'pip': Force use of pip regardless of base image support
     - 'uv': Force use of uv (will fail if base image doesn't support it)
     """
 
+    source: UvSource | None
+    """Optional. Explicit deployment source configuration.
+
+    Use `{ "kind": "uv", "root": "." }` to deploy from a uv project rooted at
+    `root/pyproject.toml` and `root/uv.lock`. If `root` is a workspace and the
+    target is ambiguous, set `package` to the desired workspace member.
+    """
+
     dockerfile_lines: list[str]
     """Optional. Additional Docker instructions that will be appended to your base Dockerfile.
-    
-    Useful for installing OS packages, setting environment variables, etc. 
+
+    Useful for installing OS packages, setting environment variables, etc.
     Example:
         dockerfile_lines=[
             "RUN apt-get update && apt-get install -y libmagic-dev",
@@ -652,12 +684,14 @@ class Config(TypedDict, total=False):
 
     dependencies: list[str]
     """List of Python dependencies to install, either from PyPI or local paths.
-    
+
     Examples:
       - "." or "./src" if you have a local Python package
       - str (aka "anthropic") for a PyPI package
       - "git+https://github.com/org/repo.git@main" for a Git-based package
     Defaults to an empty list, meaning no additional packages installed beyond your base environment.
+
+    This field is not supported when `source.kind` is `uv`.
     """
 
     graphs: dict[str, str | GraphDef]
@@ -682,10 +716,10 @@ class Config(TypedDict, total=False):
 
     env: dict[str, str] | str
     """Optional. Environment variables to set for your deployment.
-    
+
     - If given as a dict, keys are variable names and values are their values.
     - If given as a string, it must be a path to a file containing lines in KEY=VALUE format.
-    
+
     Example as a dict:
         env={"API_TOKEN": "abc123", "DEBUG": "true"}
     Example as a file path:
@@ -694,13 +728,13 @@ class Config(TypedDict, total=False):
 
     store: StoreConfig | None
     """Optional. Configuration for the built-in long-term memory store, including semantic search indexing.
-    
+
     If omitted, no vector index is set up (the object store will still be present, however).
     """
 
     checkpointer: CheckpointerConfig | None
     """Optional. Configuration for the built-in checkpointer, which handles checkpointing of state.
-    
+
     If omitted, no checkpointer is set up (the object store will still be present, however).
     """
 
@@ -733,7 +767,7 @@ class Config(TypedDict, total=False):
 
     keep_pkg_tools: bool | list[str] | None
     """Optional. Control whether to retain Python packaging tools in the final image.
-    
+
     Allowed tools are: "pip", "setuptools", "wheel".
     You can also set to true to include all packaging tools.
     """