build(docker): reorg into docker/ and add cross-arch wheel builder

[saturley-hall]

Summary

• docker/Dockerfile.client-wheel — new multi-arch (linux/amd64, linux/arm64) builder on quay.io/pypa/manylinux_2_28_{x86_64,aarch64}. Per target platform it produces:
  • 4 manylinux_2_28 wheels (cp310, cp311, cp312, cp313), each compiling modelexpress.vmm._alloc_ext against the matching CPython ABI and hardened with auditwheel repair;
  • 1 py3-none-any pure-Python wheel built with MX_SKIP_EXT=1;
  • 1 sdist tarball.
• setup.py — new MX_SKIP_EXT env knob: when set, _ext_modules() returns [] so bdist_wheel produces a true py3-none-any wheel instead of a platform-tagged wheel that just happens to contain no compiled code.
• Reorg: Dockerfile → docker/Dockerfile, docker-compose.yml → docker/docker-compose.yml (context bumped to ..). README, CONTRIBUTING, docs/DEPLOYMENT.md, docs/ARCHITECTURE.md updated to match.

Motivation: the wheel currently on artifactory is tagged linux_x86_64 (no manylinux), only cp313, and the source pipeline for it lives outside this repo. This commit gives us an in-tree, reproducible cross-arch wheel builder that emits properly tagged manylinux wheels plus a pure-Python fallback and an sdist.

Test plan

• docker buildx build --platform linux/arm64 -f docker/Dockerfile.client-wheel --target export --output type=local,dest=./dist . → 6 artifacts (4× cp3{10..13} manylinux_2_24+manylinux_2_28_aarch64 wheels, 1× py3-none-any, 1× sdist) verified locally.
• docker buildx build --platform linux/amd64 -f docker/Dockerfile.client-wheel --target export --output type=local,dest=./dist . → same 6 artifacts for x86_64, verified locally (under QEMU on an Apple Silicon host).
• py3-none-any wheel contains no .so (only _alloc_ext.cpp source); manylinux wheels contain the compiled _alloc_ext.cpython-3XX-{aarch64,x86_64}-linux-gnu.so.
• docker compose -f docker/docker-compose.yml up --build (smoke test for the moved compose file).
• CI passes.

🤖 Generated with Claude Code

Summary by CodeRabbit

• Documentation

  • Updated Docker quick-start and deployment instructions in contributing, README, deployment, and architecture documentation to reflect the new directory structure and use explicit file paths for Docker compose and build commands.

• Chores

  • Reorganized Docker files into a dedicated docker/ directory with updated configuration references.
  • Added multi-architecture Python wheel builder for improved cross-platform distribution support.

[coderabbitai]

Walkthrough

Docker configuration files move into a dedicated docker/ subdirectory with updated build contexts and paths. Documentation across multiple files reflects the new structure. A new multi-arch Python wheel builder Dockerfile is introduced alongside conditional C++ extension disabling in setup.py.

Changes

Docker Infrastructure Reorganization and Python Wheel Building

Layer / File(s)	Summary
Docker file reorganization and documentation docker/docker-compose.yml, CONTRIBUTING.md, README.md, docs/ARCHITECTURE.md, docs/DEPLOYMENT.md	Docker files are reorganized into a docker/ subdirectory. Compose configuration updates build context from . to .. and Dockerfile reference from Dockerfile to docker/Dockerfile. User-facing documentation across multiple files is updated to reference explicit Docker file paths using -f docker/Dockerfile and -f docker/docker-compose.yml in all build and compose commands.
Python wheel builder and conditional extension support modelexpress_client/python/setup.py, docker/Dockerfile.client-wheel	setup.py conditionally disables C++ extension building when MX_SKIP_EXT environment variable is set. A new multi-stage, multi-arch Dockerfile.client-wheel builds manylinux_2_28-compatible wheels for CPython 3.10–3.13 via architecture-specific builder stages, applies auditwheel repair, and additionally builds a pure-Python variant with MX_SKIP_EXT=1, exporting all artifacts via a FROM scratch final stage.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

Poem

🐰 Docker files in folders neat,
Wheels built multi-arch, complete!
Extensions skip with env control,
Infrastructure finds new home,
Build pipelines dance—no stone unturned. 🐇

🚥 Pre-merge checks | ✅ 4 | ❌ 1

❌ Failed checks (1 warning)

Check name	Status	Explanation	Resolution
Docstring Coverage	⚠️ Warning	Docstring coverage is 0.00% which is insufficient. The required threshold is 80.00%.	Write docstrings for the functions missing them to satisfy the coverage threshold.

✅ Passed checks (4 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title directly and concisely summarizes the two main changes: Docker reorganization into a docker/ subdirectory and addition of a new cross-architecture wheel builder.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}

[coderabbitai]

Actionable comments posted: 3

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@docker/Dockerfile.client-wheel`:
- Around line 36-37: Add pinned packaging-tool ARGs and use them in the pip
install invocation so wheel outputs are reproducible; declare build-time args
like PIP_VERSION, BUILD_VERSION, and AUDITWHEEL_VERSION with sensible defaults
near the top of the Dockerfile, then replace the current "$PYBIN/pip" install
--upgrade pip build auditwheel call inside the client-wheel build stage to
install exact versions (e.g., pip==${PIP_VERSION}, build==${BUILD_VERSION},
auditwheel==${AUDITWHEEL_VERSION}) so the toolchain cannot drift or fail between
builds.

In `@docs/ARCHITECTURE.md`:
- Around line 67-70: Replace the ASCII repository tree block in ARCHITECTURE.md
with a Mermaid diagram: remove the 3-line ASCII snippet starting with "├──
docker/" and instead add a Mermaid code block (```mermaid```) that models the
same structure (root node "docker" with child nodes "Dockerfile",
"Dockerfile.client-wheel", and "docker-compose.yml") using a directed/top-down
graph (e.g., graph TD) and include brief labels matching the original comments;
ensure the new block follows markdown fenced code block syntax and adheres to
the repo's mermaid diagram conventions.

In `@docs/DEPLOYMENT.md`:
- Around line 234-236: The docs currently build the default (scratch) final
stage from docker/Dockerfile.client-wheel, so docker run mx-wheel-builder cp ...
fails because scratch has no cp; update the example to build the stage that
contains /dist by adding --target=export (or the appropriate stage name used in
docker/Dockerfile.client-wheel) to the docker build command (e.g., docker build
--target=export -f docker/Dockerfile.client-wheel -t mx-wheel-builder .) so the
subsequent docker run cp -r /dist/. /out/ works.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: 69039901-6d0e-4d9b-9468-4623f6e5a632

📥 Commits

Reviewing files that changed from the base of the PR and between 3dee097 and 092d10c.

📒 Files selected for processing (8)

• CONTRIBUTING.md
• README.md
• docker/Dockerfile
• docker/Dockerfile.client-wheel
• docker/docker-compose.yml
• docs/ARCHITECTURE.md
• docs/DEPLOYMENT.md
• modelexpress_client/python/setup.py

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

🧩 Analysis chain

🏁 Script executed:

#!/bin/bash
# Verify whether packaging tools are currently unpinned in the wheel builder Dockerfile.
rg -n 'pip" install --upgrade' docker/Dockerfile.client-wheel
rg -n 'pip==|build==|auditwheel==' docker/Dockerfile.client-wheel

Repository: ai-dynamo/modelexpress

Length of output: 132

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail
nl -ba docker/Dockerfile.client-wheel | sed -n '1,120p'

Repository: ai-dynamo/modelexpress

Length of output: 109

---

🏁 Script executed:

#!/bin/bash
set -euo pipefail
cat -n docker/Dockerfile.client-wheel | sed -n '1,140p'

Repository: ai-dynamo/modelexpress

Length of output: 2143

---

Pin packaging tool versions in docker/Dockerfile.client-wheel to keep wheel outputs reproducible.

docker/Dockerfile.client-wheel line 36 upgrades pip, build, and auditwheel with no version pins, so the toolchain can drift between builds and change wheel metadata/repair behavior. Ensure the pinned ARGs are set (or provide defaults) so the Docker build can’t fail.

Proposed fix

+ARG PIP_VERSION
+ARG BUILD_VERSION
+ARG AUDITWHEEL_VERSION
@@
-        "$PYBIN/pip" install --upgrade pip build auditwheel; \
+        "$PYBIN/pip" install --upgrade \
+            "pip==${PIP_VERSION}" \
+            "build==${BUILD_VERSION}" \
+            "auditwheel==${AUDITWHEEL_VERSION}"; \

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docker/Dockerfile.client-wheel` around lines 36 - 37, Add pinned
packaging-tool ARGs and use them in the pip install invocation so wheel outputs
are reproducible; declare build-time args like PIP_VERSION, BUILD_VERSION, and
AUDITWHEEL_VERSION with sensible defaults near the top of the Dockerfile, then
replace the current "$PYBIN/pip" install --upgrade pip build auditwheel call
inside the client-wheel build stage to install exact versions (e.g.,
pip==${PIP_VERSION}, build==${BUILD_VERSION}, auditwheel==${AUDITWHEEL_VERSION})
so the toolchain cannot drift or fail between builds.

[coderabbitai]

⚠️ Potential issue | 🟡 Minor | ⚡ Quick win

Replace the repository tree ASCII block with a Mermaid diagram.

These lines extend an ASCII tree in markdown; this should be represented as Mermaid to meet repo docs standards.

As per coding guidelines, **/*.md: Use mermaid diagrams instead of ASCII art in markdown files.

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/ARCHITECTURE.md` around lines 67 - 70, Replace the ASCII repository tree
block in ARCHITECTURE.md with a Mermaid diagram: remove the 3-line ASCII snippet
starting with "├── docker/" and instead add a Mermaid code block (```mermaid```)
that models the same structure (root node "docker" with child nodes
"Dockerfile", "Dockerfile.client-wheel", and "docker-compose.yml") using a
directed/top-down graph (e.g., graph TD) and include brief labels matching the
original comments; ensure the new block follows markdown fenced code block
syntax and adheres to the repo's mermaid diagram conventions.

[coderabbitai]

⚠️ Potential issue | 🟠 Major | ⚡ Quick win

The non-buildx example will fail with the default export stage image.

At Line 234 the build targets the Dockerfile default final stage (FROM scratch in docker/Dockerfile.client-wheel), so Line 235’s docker run ... cp ... has no cp binary to execute.

Proposed doc fix

-docker build -f docker/Dockerfile.client-wheel -t mx-wheel-builder .
-docker run --rm -v "$PWD/dist:/out" mx-wheel-builder cp -r /dist/. /out/
+docker build -f docker/Dockerfile.client-wheel --target builder -t mx-wheel-builder .
+docker run --rm -v "$PWD/dist:/out" mx-wheel-builder bash -lc 'cp -r /dist/. /out/'

📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change

	docker build -f docker/Dockerfile.client-wheel -t mx-wheel-builder .
	docker run --rm -v "$PWD/dist:/out" mx-wheel-builder cp -r /dist/. /out/
	```
	docker build -f docker/Dockerfile.client-wheel --target builder -t mx-wheel-builder .
	docker run --rm -v "$PWD/dist:/out" mx-wheel-builder bash -lc 'cp -r /dist/. /out/'

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@docs/DEPLOYMENT.md` around lines 234 - 236, The docs currently build the
default (scratch) final stage from docker/Dockerfile.client-wheel, so docker run
mx-wheel-builder cp ... fails because scratch has no cp; update the example to
build the stage that contains /dist by adding --target=export (or the
appropriate stage name used in docker/Dockerfile.client-wheel) to the docker
build command (e.g., docker build --target=export -f
docker/Dockerfile.client-wheel -t mx-wheel-builder .) so the subsequent docker
run cp -r /dist/. /out/ works.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!