Migrate dependency management to uv (closes #38)

[aviv1ron1]

This PR switches the project from pip/venv to uv for dependency management.

What changed:

• pyproject.toml — added missing [tool.uv] conflict declarations for the tutorials extra (which transitively depends on vllm), fixing uv lock resolution
• uv.lock — universal lockfile for all non-conflicting extras (277 packages); covers vllm and vllm20 separately via the existing conflict declarations
• README.md — replaced pip/venv Quick Start install section with uv sync commands, added model pre-download tip using hf_transfer, fixed Python badge (3.9+ → 3.10+)
• CONTRIBUTING.md + docs/GIT_WORKFLOW.md — updated dev setup and test commands to use uv sync --extra dev and uv run pytest
• CLAUDE.md — updated installation section to uv commands
• tutorials/PREREQUISITES.md + tutorials/guides/ — replaced all pip install references with uv sync / uv pip install

CUDA note: the vllm/vllm20 extra split already handles the CUDA 12 vs 13 version requirement — the lockfile is universal and does not tie to a specific CUDA environment.

[aviv1ron1]

note: no need to change the tutorial notebooks code, since notebooks do not use uv. the notebooks will continue using pip install as currently

[antonpibm]

Is there a better way to handle the conflicts? see my question in the main discussion regarding that

[antonpibm]

One unique aspect of granite-switch is the fact that it's an infra library and should work with different environments.
Environments carry a lot of inherited dependencies such as the torch versions, which in turn limit/affect the version of packages we can install, one such example is the support of vllm 0.20.0 which is supported by Granite-Switch but causes a lot of compatibility problems on older environments.
This raises few points we should address:

1. Where did you build the lock file?
2. We should run the full test suite with dependencies built from this lock file on one (preferably two) different computation environments
3. We can potentially manage the dependency versions with uv groups, where vllm 0.19.1 suite will be the default and the other setups will be possible

[aviv1ron1]

One unique aspect of granite-switch is the fact that it's an infra library and should work with different environments. Environments carry a lot of inherited dependencies such as the torch versions, which in turn limit/affect the version of packages we can install, one such example is the support of vllm 0.20.0 which is supported by Granite-Switch but causes a lot of compatibility problems on older environments. This raises few points we should address:

1. Where did you build the lock file?
2. We should run the full test suite with dependencies built from this lock file on one (preferably two) different computation environments
3. We can potentially manage the dependency versions with uv groups, where vllm 0.19.1 suite will be the default and the other setups will be possible

just tested the uv branch on CCC and it worked out of the box. as a matter of fact the non uv branch did not work for me out of the box on CCC. But i only tried the HF dependency, not vllm.

[aviv1ron1]

One unique aspect of granite-switch is the fact that it's an infra library and should work with different environments. Environments carry a lot of inherited dependencies such as the torch versions, which in turn limit/affect the version of packages we can install, one such example is the support of vllm 0.20.0 which is supported by Granite-Switch but causes a lot of compatibility problems on older environments. This raises few points we should address:

1. Where did you build the lock file?
2. We should run the full test suite with dependencies built from this lock file on one (preferably two) different computation environments
3. We can potentially manage the dependency versions with uv groups, where vllm 0.19.1 suite will be the default and the other setups will be possible

just tested the uv branch on CCC and it worked out of the box. as a matter of fact the non uv branch did not work for me out of the box on CCC. But i only tried the HF dependency, not vllm.

My suggestion is this:

• Keep dev as a group with just pytest and dev tooling — no bundled vllm
• User composes: uv sync --group dev --extra vllm or uv sync --group dev --extra vllm20
• This eliminates dev-vllm20 entirely and reduces conflicts to just one: vllm vs vllm20

So [tool.uv] goes from 6 conflict pairs down to 1:

[dependency-groups]
dev = ["pytest", "granite-switch[hf,compose]"] # no vllm bundled
test = ["pytest", "bitsandbytes", "optimum-quanto"]

[tool.uv]
conflicts = [
[{ extra = "vllm" }, { extra = "vllm20" }],
]

[antonpibm]

@aviv1ron1 Thanks for looking into it. Couple of thoughts:

1. It is absolutely mandatory to run full test suite (including vllm and GPU tests) before we proceed with this
2. I really like the idea of working with groups, I suggest we add vllm as a default group and expel it on a custom vllm20 installation
3. I would prefer shorter and a solid default installation command and an explicit conflict handling in the pyproject.toml file than the opposite, so if removing conflict handling from the toml file moves the responsibility to the user I would not do it
4. I suggest we totally drop the usage of uv pip on the main README, first we should not enforce the usage of pip when someone installs granite-switch as a dependency and also uv pip is not the default way to work with pip
5. CONTRIBUTING.md should include instructions about how to install uv
6. The test group should also include the dev group (including vllm)

[aviv1ron1]

@antonpibm I am addressing all you comments:

What this branch changes

Migrates dependency management from pip extras to uv dependency groups in pyproject.toml. No library functionality changed — this is a developer tooling update.

Before:

pip install -e ".[hf,vllm,compose]"

After:

uv sync --group dev         # vllm 0.19.x
uv sync --group dev-vllm20  # vllm 0.20.x

What was tested

The full test suite was run on a GPU cluster (4× GPU, Python 3.12) against both supported vllm versions, using uv sync to install dependencies from uv.lock.

Suite	vllm19	vllm20
unit/ (86 tests)	✅ 86 passed	✅ 86 passed
hf/ (579 tests)	✅ 563 passed, 16 skipped	✅ 563 passed, 16 skipped
composer/ (240 tests)	✅ 239 passed, 1 skipped	✅ 239 passed, 1 skipped
vllm/ (427 tests)	✅ 425 passed, 2 skipped	✅ 425 passed, 2 skipped
integration/ (27 tests)	❌ 1 failed, 26 passed	❌ 1 failed, 26 passed

Known failure

tests/integration/test_switch_e2e_compose.py::test_hf_vllm_argmax_equivalence[granite-4.0-micro] fails on both vllm versions with identical output:

HF and vLLM disagree on top-1 token for 1 position(s) (base_model=ibm-granite/granite-4.0-micro):
    [early] mismatch at positions [2, 4]
      hf_argmax   = [1866, 334, 25, 842, 11, 279, 2163]
      vllm_argmax = [1866, 334, 284, 842, 596, 279, 2163]

The failure is not related to the uv migration — it reproduces on both vllm versions and is pre-existing in the branch. The error message points to a vLLM gain-compensation bug (wrong adapter_indices).

Conclusion

The uv migration works correctly. uv sync resolves and installs all dependencies cleanly under both vllm19 and vllm20. The one failing test is a pre-existing issue unrelated to this PR.

The uv branch was missing commit 1a6320a from main (Bugfix/107 argmax equivalence diagnostics) which fixes this exact test by replacing repeated token 50 filler with varied real sentence tokens — avoiding near-tied logit distributions that caused false argmax mismatches between HF and vLLM backends. The branch has since been rebased onto main so this fix is now included;

[antonpibm]

Thanks @aviv1ron1 !