[MNT] Setup uv

[surchs]

Update workflows

• Closes Adopt uv for dependency management #527

Changes proposed in this pull request:

• use uv to handle dependency lockfile for the project
• move dependencies to pyproject.toml
• add dependabot support to update the uv.lock file (will have to be replaced by an updated dependabot sync template)

Note

We want to also have our local dev environments use the lockfile dependencies (to make sure local dev is the same as prod). Achieving this without installing uv locally is going to be quite hard / impossible with this setup. So our local setup guide will now include having uv available to handle local venv and installation.

Note

In the CI commands and the docker build, we do not use uv now. This is mainly to keep the diff limited. We can do this by first asking uv to build a requirements.txt lock file from the uv.lock file - and then using pip to install from the requirements.txt file as before.

Checklist

This section is for the PR reviewer

• PR has an interpretable title with a prefix ([ENH], [FIX], [REF], [TST], [CI], [MNT], [INF], [MODEL], [DOC]) (see our Contributing Guidelines for more info)
• PR has a label for the release changelog or skip-release (to be applied by maintainers only)
• PR links to GitHub issue with mention Closes #XXXX
• Tests pass
• Checks pass
• If the PR changes the SPARQL query template, the default Neurobagel query file has also been regenerated

For new features:

• Tests have been added

For bug fixes:

• There is at least one test that would fail under the original bug conditions.

Summary by Sourcery

Adopt uv-based Python project and dependency management and update CI to use it for installing and running development dependencies.

Enhancements:

• Define project metadata, runtime dependencies, and development dependency groups in a new pyproject.toml.
• Configure code style and type-checking tools (Black, isort, mypy) via pyproject.toml.

CI:

• Update test workflow to install uv and use it to sync dependencies instead of pip/requirements.txt.

Chores:

• Add uv.lock to track the resolved dependency set for reproducible environments.

[sourcery-ai]

Reviewer's Guide

This PR introduces uv-based dependency management for the project, wiring CI to use uv and adding a pyproject.toml with project metadata, dependency groups, and tooling configuration, plus a generated uv.lock lockfile.

Flow diagram for uv dependency groups in pyproject.toml

graph TD
  Project[project_neurobagel-api]
  Core_Dependencies[core_runtime_dependencies]
  Dependency_Groups[dependency_groups]
  Dev_Group[dev_group]
  Test_Group[test_group]
  Coverage_Group[coverage_group]
  Lint_Group[lint_group]

  Project --> Core_Dependencies
  Project --> Dependency_Groups

  Dependency_Groups --> Dev_Group
  Dependency_Groups --> Test_Group
  Dependency_Groups --> Coverage_Group
  Dependency_Groups --> Lint_Group

  Dev_Group --> Test_Group
  Dev_Group --> Coverage_Group
  Dev_Group --> Lint_Group

Loading

File-Level Changes

Change	Details	Files
Switch CI test workflow to use uv for Python dependency installation instead of pip and requirements.txt.	Add astral-sh/setup-uv action step before dependency installation in the test workflow. Replace manual pip install commands with uv sync --frozen --extra dev to install runtime and dev dependencies from the lockfile. Remove reliance on requirements.txt for CI dependency installation.	.github/workflows/test.yaml
Define project metadata, dependencies, and development tooling configuration via pyproject.toml to support uv and standard packaging.	Declare project name, dynamic version, supported Python range, and core runtime dependencies. Introduce dependency groups (dev, test, coverage, lint) for targeted installs via uv. Configure build system to use setuptools with setuptools.build_meta backend and define app package discovery. Add tool configuration blocks for black, isort, and mypy to standardize formatting and type-checking settings.	pyproject.toml
Add uv.lock lockfile to pin dependency versions for reproducible installs.	Check in uv.lock so CI (and developers) can perform frozen syncs with uv. Aligns uv sync --frozen call in CI with a committed lockfile to guarantee deterministic environments.	uv.lock

Possibly linked issues

• #(not specified): PR implements uv-based dependency management and workflow changes directly fulfilling the “Adopt uv for dependency management” issue.

---

Tips and commands

Interacting with Sourcery

• Trigger a new review: Comment @sourcery-ai review on the pull request.
• Continue discussions: Reply directly to Sourcery's review comments.
• Generate a GitHub issue from a review comment: Ask Sourcery to create an
  issue from a review comment by replying to it. You can also reply to a
  review comment with @sourcery-ai issue to create an issue from it.
• Generate a pull request title: Write @sourcery-ai anywhere in the pull
  request title to generate a title at any time. You can also comment
  @sourcery-ai title on the pull request to (re-)generate the title at any time.
• Generate a pull request summary: Write @sourcery-ai summary anywhere in
  the pull request body to generate a PR summary at any time exactly where you
  want it. You can also comment @sourcery-ai summary on the pull request to
  (re-)generate the summary at any time.
• Generate reviewer's guide: Comment @sourcery-ai guide on the pull
  request to (re-)generate the reviewer's guide at any time.
• Resolve all Sourcery comments: Comment @sourcery-ai resolve on the
  pull request to resolve all Sourcery comments. Useful if you've already
  addressed all the comments and don't want to see them anymore.
• Dismiss all Sourcery reviews: Comment @sourcery-ai dismiss on the pull
  request to dismiss all existing Sourcery reviews. Especially useful if you
  want to start fresh with a new review - don't forget to comment
  @sourcery-ai review to trigger a new review!

Customizing Your Experience

Access your dashboard to:

• Enable or disable review features such as the Sourcery-generated pull request
  summary, the reviewer's guide, and others.
• Change the review language.
• Add, remove or edit custom review instructions.
• Adjust other review settings.

Getting Help

• Contact our support team for questions or feedback.
• Visit our documentation for detailed guides and information.
• Keep in touch with the Sourcery team by following us on X/Twitter, LinkedIn or GitHub.

[sourcery-ai]

We've reviewed this pull request using the Sourcery rules engine

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 94.92%. Comparing base (659081c) to head (8341af4).
⚠️ Report is 8 commits behind head on main.

Additional details and impacted files

@@            Coverage Diff             @@
##             main     #529      +/-   ##
==========================================
- Coverage   97.31%   94.92%   -2.39%     
==========================================
  Files          34       30       -4     
  Lines        1304     1282      -22     
  Branches        0       77      +77     
==========================================
- Hits         1269     1217      -52     
- Misses         35       37       +2     
- Partials        0       28      +28     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

[alyssadai]

@surchs, initial comment here before I have time for a full review. I noticed in this PR that you added a dependency group for some linters/formatters that we already run automatically as part of pre-commit hooks (and don't need to be installed locally) as well as pre-commit CI on PRs.

What does this add to our existing pre-commit setup?

[alyssadai]

Thanks a lot @surchs for implementing this and for your patience on my review! I've tested out uv locally using your branch and I think it will simplify dependency management considerably - happy to be rid of these restrictive requirements.txt files 🎉

Since we haven't updated dependencies in a while, I think the main issue atm is incompatibilities between locked package versions in uv.lock and the newer Python versions we want to support. Specifically:

• uv.lock currently specifies some pretty old versions of tools
• that don't have wheels for e.g., 3.12 or 3.13
• meanwhile, the new pyproject.toml allows 3.11-3.13
• but the test.yaml only runs tests against 3.10 (so the issues with newer Pythons are not caught in CI)

Left more details below and and a suggestion of how we can resolve this!

Two other high-level comments (with details below):

• I think we can include a bit more guidance in the README on using uv. Given how much uv abstracts away and the many commands available, I find that things like knowing which env I'm installing things into, how to add or update a dependency, etc. aren't obvious coming from pip + venv where each step is explicit. I think a few brief explainers of commands could go a long way in this regard (also to save ourselves confusion during this transition period). As mentioned below, we might want to eventually move this info into to our CONTRIBUTING.md
• I don't follow the NOTE in your PR description about not using uv in the test.yaml and Dockerfile. From what I can see those files have been updated anyways in this PR, but I find the temporary solution harder to review than if we were to fully use uv for the Docker image and test wf. Can we consider making those changes here to avoid a second PR that reverts the changes?

[alyssadai]

Thanks @surchs for the changes! 🎉

Everything is looking good, and I can confirm the uv commands now work for me locally without dependency conflicts.

I left some final minor fixes and README suggestions, otherwise 🧑‍🍳

Before you merge, can you double check the failing codecov check to see if there's anything we can do to make it green?