Skip to content

Commit 916025d

Browse files
authored
feat(cli): support compatible api version ranges (#8023)
Adds `api_version` ranges for LangGraph API base image tags. `~=0.11.0.dev5` resolves to the newest matching compatible image while freezing later dev prereleases until rc/final/patch tags exist; `>~=0.11.0.dev5` uses the same floor but can also float to future stable releases while ignoring future prereleases. Verified with `make format`, `make lint`, and `make test` from `libs/cli`. --------- Signed-off-by: Connor Braa <[email protected]>
1 parent 9732084 commit 916025d

3 files changed

Lines changed: 327 additions & 2 deletions

File tree

‎libs/cli/langgraph_cli/cli.py‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -159,7 +159,14 @@
159159
OPT_API_VERSION = click.option(
160160
"--api-version",
161161
type=str,
162-
help="API server version to use for the base image. If unspecified, the latest version will be used.",
162+
help=(
163+
"API server version to use for the base image. If unspecified, the "
164+
"latest stable version will be used. Compatible ranges like "
165+
"~=0.11.0.dev5 stay on 0.11.0.dev5 while only newer dev builds exist, "
166+
"then resolve to the newest matching rc or stable release, for example "
167+
"0.11.0rc1 or 0.11.0. Stable-floating ranges like >~=0.11.0.dev5 "
168+
"can also pick up future stable releases, for example 0.12.0."
169+
),
163170
)
164171

165172
OPT_ENGINE_RUNTIME_MODE = click.option(

‎libs/cli/langgraph_cli/config.py‎

Lines changed: 162 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -9,6 +9,7 @@
99
from typing import Literal, NamedTuple
1010

1111
import click
12+
import httpx
1213

1314
from langgraph_cli.schemas import Config, Distros
1415
from langgraph_cli.uv_lock import python_config_to_docker_uv_lock
@@ -41,6 +42,31 @@
4142
r"(?:\.(?P<patch>\d+))?"
4243
r"(?:(?:\.|)(?:[A-Za-z][0-9A-Za-z]*))?$"
4344
)
45+
_API_VERSION_RANGE_PATTERN = re.compile(r"^(?P<operator>~=|>~=)\s*(?P<version>.+)$")
46+
_API_VERSION_PART_PATTERN = re.compile(
47+
r"^(?P<major>\d+)"
48+
r"(?:\.(?P<minor>\d+))?"
49+
r"(?:\.(?P<patch>\d+))?"
50+
r"(?:(?:\.|)(?P<pre>dev|rc)(?P<pre_n>\d+))?$"
51+
)
52+
53+
54+
class _ParsedApiVersion(NamedTuple):
55+
release: tuple[int, ...]
56+
prerelease: str | None
57+
prerelease_number: int
58+
59+
60+
class _ApiVersionRange(NamedTuple):
61+
floor: _ParsedApiVersion
62+
allow_future_stable: bool
63+
64+
65+
_PRERELEASE_ORDER = {
66+
"dev": 0,
67+
"rc": 1,
68+
None: 2,
69+
}
4470

4571

4672
def has_disallowed_build_command_content(command: str) -> bool:
@@ -141,6 +167,133 @@ def _parse_api_version_parts(version_str: str) -> tuple[int, ...]:
141167
return tuple(int(part) for part in match.groups() if part is not None)
142168

143169

170+
def _parse_api_version(version_str: str) -> _ParsedApiVersion:
171+
match = _API_VERSION_PART_PATTERN.fullmatch(version_str)
172+
if not match:
173+
raise ValueError("Version must be major or major.minor or major.minor.patch.")
174+
release = tuple(
175+
int(part)
176+
for part in (
177+
match.group("major"),
178+
match.group("minor"),
179+
match.group("patch"),
180+
)
181+
if part is not None
182+
)
183+
prerelease = match.group("pre")
184+
prerelease_number = int(match.group("pre_n") or 0)
185+
return _ParsedApiVersion(release, prerelease, prerelease_number)
186+
187+
188+
def _api_version_sort_key(
189+
version: _ParsedApiVersion,
190+
) -> tuple[tuple[int, ...], int, int]:
191+
return (
192+
version.release,
193+
_PRERELEASE_ORDER[version.prerelease],
194+
version.prerelease_number,
195+
)
196+
197+
198+
def _api_version_upper_bound(version: _ParsedApiVersion) -> tuple[int, ...]:
199+
release = version.release
200+
if len(release) <= 2:
201+
return (release[0] + 1,)
202+
return (release[0], release[1] + 1)
203+
204+
205+
def _is_compatible_api_version_candidate(
206+
candidate: _ParsedApiVersion,
207+
version_range: _ApiVersionRange,
208+
upper_bound: tuple[int, ...],
209+
) -> bool:
210+
floor = version_range.floor
211+
if _api_version_sort_key(candidate) < _api_version_sort_key(floor):
212+
return False
213+
outside_compatible_range = candidate.release[: len(upper_bound)] >= upper_bound
214+
if outside_compatible_range and not version_range.allow_future_stable:
215+
return False
216+
if outside_compatible_range and candidate.prerelease is not None:
217+
return False
218+
if floor.prerelease == "dev" and candidate.prerelease == "dev":
219+
return candidate == floor
220+
return True
221+
222+
223+
def _ensure_compatible_api_version_base_image(base_image: str) -> None:
224+
if ":" in base_image:
225+
raise click.UsageError(
226+
"Compatible api_version ranges cannot be used with a tagged base_image."
227+
)
228+
229+
230+
def _get_pypi_versions(package_name: str) -> list[str]:
231+
try:
232+
response = httpx.get(
233+
f"https://pypi.org/pypi/{package_name}/json",
234+
timeout=10,
235+
)
236+
response.raise_for_status()
237+
except httpx.HTTPError as exc:
238+
raise click.UsageError(
239+
f"Failed to fetch PyPI versions for {package_name}: {exc}"
240+
) from None
241+
payload = response.json()
242+
releases = payload.get("releases", {})
243+
if not isinstance(releases, dict):
244+
raise click.UsageError(
245+
f"Failed to fetch PyPI versions for {package_name}: invalid response."
246+
)
247+
return [version for version in releases if isinstance(version, str)]
248+
249+
250+
def _resolve_compatible_api_version(
251+
api_version: str,
252+
base_image: str,
253+
version_distro_tag: str,
254+
) -> str:
255+
match = _API_VERSION_RANGE_PATTERN.fullmatch(api_version)
256+
if not match:
257+
return api_version
258+
259+
floor_str = match.group("version").strip()
260+
try:
261+
floor = _parse_api_version(floor_str)
262+
except ValueError:
263+
raise click.UsageError(
264+
f"Invalid compatible api_version range: {api_version}.\n\n"
265+
"Use a compatible version range, e.g.:\n"
266+
' "api_version": "~=0.11.0.dev5"\n'
267+
"or a stable-floating range, e.g.:\n"
268+
' "api_version": ">~=0.11.0.dev5"'
269+
) from None
270+
271+
version_range = _ApiVersionRange(
272+
floor=floor,
273+
allow_future_stable=match.group("operator") == ">~=",
274+
)
275+
_ensure_compatible_api_version_base_image(base_image)
276+
pypi_versions = _get_pypi_versions("langgraph-api")
277+
278+
candidates: list[tuple[_ParsedApiVersion, str]] = []
279+
upper_bound = _api_version_upper_bound(floor)
280+
for candidate_str in pypi_versions:
281+
try:
282+
candidate = _parse_api_version(candidate_str)
283+
except ValueError:
284+
continue
285+
if _is_compatible_api_version_candidate(candidate, version_range, upper_bound):
286+
candidates.append((candidate, candidate_str))
287+
288+
if not candidates:
289+
raise click.UsageError(
290+
f"No PyPI releases match compatible api_version range {api_version!r} "
291+
f"for {base_image} with {version_distro_tag!r}."
292+
)
293+
294+
return max(candidates, key=lambda item: _api_version_sort_key(item[0]))[1]
295+
296+
144297
def _is_node_graph(spec: str | dict) -> bool:
145298
"""Check if a graph is a Node.js graph based on the file extension."""
146299
if isinstance(spec, dict):
@@ -194,7 +347,12 @@ def validate_config(config: Config) -> Config:
194347
)
195348
if api_version:
196349
try:
197-
parts = _parse_api_version_parts(api_version)
350+
compatible_match = _API_VERSION_RANGE_PATTERN.fullmatch(api_version)
351+
parts = _parse_api_version_parts(
352+
compatible_match.group("version").strip()
353+
if compatible_match
354+
else api_version
355+
)
198356
if len(parts) > 3:
199357
raise ValueError(
200358
"Version must be major or major.minor or major.minor.patch."
@@ -1430,6 +1588,9 @@ def docker_tag(
14301588

14311589
# Prepend API version if provided
14321590
if api_version:
1591+
api_version = _resolve_compatible_api_version(
1592+
api_version, base_image, f"{language}{version_distro_tag}"
1593+
)
14331594
full_tag = f"{api_version}-{language}{version_distro_tag}"
14341595
elif "/langgraph-server" in base_image and version_distro_tag not in base_image:
14351596
return f"{base_image}-{language}{version_distro_tag}"

‎libs/cli/tests/unit_tests/test_config.py‎

Lines changed: 157 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2961,6 +2961,163 @@ def test_docker_tag_with_prerelease_api_version(version: str, in_config: bool):
29612961
assert tag == f"langchain/langgraph-api:{version}-py3.11"
29622962

29632963

2964+
def test_docker_tag_with_compatible_api_version_promotes_to_latest_patch():
2965+
config = validate_config(
2966+
{
2967+
"python_version": "3.12",
2968+
"dependencies": ["."],
2969+
"graphs": {"agent": "./agent.py:graph"},
2970+
"image_distro": "wolfi",
2971+
"api_version": "~=0.11.0.dev5",
2972+
}
2973+
)
2974+
2975+
with patch(
2976+
"langgraph_cli.config._get_pypi_versions",
2977+
return_value=[
2978+
"0.11.0.dev5",
2979+
"0.11.0.dev6",
2980+
"0.11.0rc1",
2981+
"0.11.0",
2982+
"0.11.1rc1",
2983+
"0.11.1",
2984+
"0.12.0rc1",
2985+
],
2986+
) as get_versions:
2987+
tag = docker_tag(config)
2988+
2989+
get_versions.assert_called_once_with("langgraph-api")
2990+
assert tag == "langchain/langgraph-api:0.11.1-py3.12-wolfi"
2991+
2992+
2993+
def test_docker_tag_with_compatible_api_version_freezes_dev_until_rc():
2994+
config = validate_config(
2995+
{
2996+
"python_version": "3.12",
2997+
"dependencies": ["."],
2998+
"graphs": {"agent": "./agent.py:graph"},
2999+
"api_version": "~=0.11.0.dev5",
3000+
}
3001+
)
3002+
3003+
with patch(
3004+
"langgraph_cli.config._get_pypi_versions",
3005+
return_value=[
3006+
"0.11.0.dev5",
3007+
"0.11.0.dev6",
3008+
"0.11.0.dev7",
3009+
],
3010+
):
3011+
tag = docker_tag(config)
3012+
3013+
assert tag == "langchain/langgraph-api:0.11.0.dev5-py3.12"
3014+
3015+
3016+
def test_docker_tag_with_stable_floating_api_version_promotes_to_future_stable():
3017+
config = validate_config(
3018+
{
3019+
"python_version": "3.12",
3020+
"dependencies": ["."],
3021+
"graphs": {"agent": "./agent.py:graph"},
3022+
"image_distro": "wolfi",
3023+
"api_version": ">~=0.11.0.dev5",
3024+
}
3025+
)
3026+
3027+
with patch(
3028+
"langgraph_cli.config._get_pypi_versions",
3029+
return_value=[
3030+
"0.11.0.dev5",
3031+
"0.11.0.dev6",
3032+
"0.11.0rc1",
3033+
"0.11.0",
3034+
"0.11.1",
3035+
"0.12.0rc1",
3036+
"0.12.0",
3037+
"0.13.0.dev1",
3038+
"0.13.0",
3039+
],
3040+
) as get_versions:
3041+
tag = docker_tag(config)
3042+
3043+
get_versions.assert_called_once_with("langgraph-api")
3044+
assert tag == "langchain/langgraph-api:0.13.0-py3.12-wolfi"
3045+
3046+
3047+
def test_docker_tag_with_stable_floating_api_version_ignores_future_prereleases():
3048+
config = validate_config(
3049+
{
3050+
"python_version": "3.12",
3051+
"dependencies": ["."],
3052+
"graphs": {"agent": "./agent.py:graph"},
3053+
"api_version": ">~=0.11.0.dev5",
3054+
}
3055+
)
3056+
3057+
with patch(
3058+
"langgraph_cli.config._get_pypi_versions",
3059+
return_value=[
3060+
"0.11.0.dev5",
3061+
"0.11.0",
3062+
"0.12.0rc1",
3063+
"0.12.0.dev1",
3064+
],
3065+
):
3066+
tag = docker_tag(config)
3067+
3068+
assert tag == "langchain/langgraph-api:0.11.0-py3.12"
3069+
3070+
3071+
def test_validate_config_rejects_unrecognized_api_version_range_operator():
3072+
with pytest.raises(click.UsageError, match="Invalid version format"):
3073+
validate_config(
3074+
{
3075+
"python_version": "3.12",
3076+
"dependencies": ["."],
3077+
"graphs": {"agent": "./agent.py:graph"},
3078+
"api_version": "~>=0.11.0.dev5",
3079+
}
3080+
)
3081+
3082+
3083+
def test_docker_tag_with_compatible_api_version_supports_node_images():
3084+
config = validate_config(
3085+
{
3086+
"node_version": "20",
3087+
"graphs": {"agent": "./agent.js:graph"},
3088+
"image_distro": "wolfi",
3089+
"api_version": "~=1.2.4",
3090+
}
3091+
)
3092+
3093+
with patch(
3094+
"langgraph_cli.config._get_pypi_versions",
3095+
return_value=[
3096+
"1.2.4",
3097+
"1.2.5",
3098+
"1.3.0",
3099+
],
3100+
) as get_versions:
3101+
tag = docker_tag(config)
3102+
3103+
get_versions.assert_called_once_with("langgraph-api")
3104+
assert tag == "langchain/langgraphjs-api:1.2.5-node20-wolfi"
3105+
3106+
3107+
def test_docker_tag_with_compatible_api_version_rejects_tagged_base_image():
3108+
config = validate_config(
3109+
{
3110+
"python_version": "3.11",
3111+
"dependencies": ["."],
3112+
"graphs": {"agent": "./agent.py:graph"},
3113+
"api_version": "~=0.11.0.dev5",
3114+
}
3115+
)
3116+
3117+
with pytest.raises(click.UsageError, match="tagged base_image"):
3118+
docker_tag(config, base_image="langchain/langgraph-api:0.11.0")
3119+
3120+
29643121
def test_config_to_docker_with_api_version():
29653122
"""Test config_to_docker function with api_version parameter."""
29663123

0 commit comments

Comments
 (0)