[alnzng]

Linked issue: #xxx

Purpose of change

Recently we added onnxruntime>=1.24.1 requirement for Python 3.11+, but onnxruntime dropped macOS x86_64 wheel support since 1.24.1 (release notes).

This cause build failure when Python 3.11+ is built for x86_64:

Using CPython 3.11.9 interpreter at: /export/apps/python/3.11/bin/python3
Creating virtual environment at: .venv
Resolved 124 packages in 591ms
warning: `google-auth==2.46.0` is yanked (reason: "incompatibility with Python 3.8")
warning: `numpy==2.4.0` is yanked (reason: "Backward compatibility bug")
error: Distribution `onnxruntime==1.24.1 @ registry+https://pypi.org/simple` can't be installed because it doesn't have a source distribution or wheel for the current platform

hint: You're on macOS (`macosx_26_0_x86_64`), but `onnxruntime` (v1.24.1) only has wheels for the following platforms: `manylinux_2_27_aarch64`, `manylinux_2_27_x86_64`, `manylinux_2_28_aarch64`, `manylinux_2_28_x86_64`, `macosx_14_0_arm64`, `win_amd64`; consider adding "sys_platform == 'darwin' and platform_machine == 'x86_64'" to `tool.uv.required-environments` to ensure uv resolves to a version with compatible wheels
error: Distribution `onnxruntime==1.24.1 @ registry+https://pypi.org/simple` can't be installed because it doesn't have a source distribution or wheel for the current platform

hint: You're on macOS (`macosx_26_0_x86_64`), but `onnxruntime` (v1.24.1) only has wheels for the following platforms: `manylinux_2_27_aarch64`, `manylinux_2_27_x86_64`, `manylinux_2_28_aarch64`, `manylinux_2_28_x86_64`, `macosx_14_0_arm64`, `win_amd64`; consider adding "sys_platform == 'darwin' and platform_machine == 'x86_64'" to `tool.uv.required-environments` to ensure uv resolves to a version with compatible wheels
error: The wheel filename "*.whl" is invalid: Must have a version

Since onnxruntime is transitive dependency from chromadb, I think no need to pin minimum version. We can just let chromadb pull the compatible version.

Changes:

1. Remove onnxruntime>=1.24.1 floor for Python 3.11
2. Broaden required-environments from darwin + arm64 to darwin so uv lock consider all macOS
   architecture
3. Add uv lock step in build script before uv sync to make sure lockfile is regenerated

Tests

Run ./tools/build.sh on MacOS laptop

API

N / A

Documentation

• doc-needed
• doc-not-needed
• doc-included

[github-actions]

@alnzng Please add the following content to your PR description and select a checkbox:

- [ ] `doc-needed` 
- [ ] `doc-not-needed` <!-- Your PR changes do not impact docs -->
- [ ] `doc-included` 

[alnzng]

@wenjin272 Can you help take a look this PR?

[alnzng]

This PR has the dependency on this PR: #526

[wenjin272]

Actually, I didn't add onnxruntime>=1.24.1 for python 3.11 initially, but I found for python 3.11 in macOS & arm, uv will also use onnxruntime==1.23.2, even if onnxruntime==1.24.1 is available. So I finally add a minimum version requirement for onnxruntime in python 3.11.

But the minimum version requirement indeed break the build in macos & x86_64. Do you have any good solutions?

[alnzng]

uv will also use onnxruntime==1.23.2, even if onnxruntime==1.24.1 is available.

@wenjin272 Did you notice this in your local env or CI? Have you tried to remove .env folder and uv lock to start with a fresh build?

I currently don't have ARM version Python installed on my (Company)laptop, I can check if installing ARM version Python is accpetable in my side.

[alnzng]

It looks like all CI passed without this onnxruntime issue, seems we are good?

The current failed CI test seems to be not related to this change, it failed in maven test phrase: Failed to execute goal org.apache.maven.plugins:maven-surefire-plugin:3.5.2:test (default-test) on project flink-agents-end-to-end-tests-resource-cross-language:

[wenjin272]

uv will also use onnxruntime==1.23.2, even if onnxruntime==1.24.1 is available.

@wenjin272 Did you notice this in your local env or CI? Have you tried to remove .env folder and uv lock to start with a fresh build?

I currently don't have ARM version Python installed on my (Company)laptop, I can check if installing ARM version Python is accpetable in my side.

I noticed this both in my local env and CI, even if I remove the uv lock or try uv sync --upgrade.

For example, in ut test for python 3.11 on macos for this pr: https://github.com/apache/flink-agents/actions/runs/21851853229/job/63068025146?pr=525, the installed onnxruntime is 1.23.2

It actually won't cause any failure, but may be unexpected.

[alnzng]

It actually won't cause any failure, but may be unexpected.

@wenjin272 You are right on onnxruntime==1.23.2 is automatically resolved and picked up by uv. I think this is because of uv's universal resolver no longer needs to fork based on current constraints:

• Python <3.11: onnxruntime<1.24.1 (from pyproject.toml)
• Python >=3.11: onnxruntime with no version pin (from chromadb)

Since 1.23.2 satisfies both, uv unifies on a single version rather than forking. I would say this is expected from uv perspective, and the version 1.23.2 should work well with all Python versions we supported today.

Note: that the root cause here is upstream: chromadb declares https://github.com/chroma-core/chroma/blob/main/pyproject.toml#L10 with no upper bound and no platform markers. This means chromadb is unaware that newer onnxruntime releases may drop support for certain platforms (like macOS x86_64 in 1.24.1). Ideally, chromadb should handle this with appropriate version bounds or environment markers so that downstream projects don't need to independently work around these compatibility gaps.

---

I don't see a hard blocker that we had to to remove the support on macOS x86_64. That said, I think we should continue to support macOS x86_64. There are still users(like us internally) replies on the builds from macOS x86_64.

@wenjin272 @xintongsong WDYT?

[xintongsong]

Thanks for the nice discussion. Here are my two cents.

1. We should definitely support both x86 and arm on macos
2. IIUC, the two objective constraints that we need to strictly follow:

• onnxruntime 1.24.1 does not support python 3.10
• onnxruntime 1.24.1 does not support x86 on macos

3. There's no strong demand for using onnxruntime 1.24.1+ on python 3.11

Based on these, I think the changes @alnzng proposed in this PR make sense. WDYT, @wenjin272?

[wenjin272]

Thanks for the nice discussion. Here are my two cents.

1. We should definitely support both x86 and arm on macos
2. IIUC, the two objective constraints that we need to strictly follow:

• onnxruntime 1.24.1 does not support python 3.10
• onnxruntime 1.24.1 does not support x86 on macos

3. There's no strong demand for using onnxruntime 1.24.1+ on python 3.11

Based on these, I think the changes @alnzng proposed in this PR make sense. WDYT, @wenjin272?

make sense

[xintongsong]

LGTM

[xintongsong]

Ported to release-0.2 in dc81f79