chore(ci): migrate Python tooling to uv and standardize workflow execution (#7386)

# Description of Changes

This PR modernizes the project's Python tooling across GitHub Actions by
migrating CI workflows from pip-based dependency management to `uv` and
aligning Python execution with the engine project's managed environment.

### What was changed

- Replaced `actions/setup-python` and ad-hoc `pip install` steps with
`astral-sh/setup-uv` across CI workflows.
- Configured shared `uv` dependency caching using
`engine/pyproject.toml` and `engine/uv.lock`.
- Updated Python script execution to use `uv run --project engine
--locked` for a consistent runtime environment.
- Replaced package installation steps with `uv sync` for the required
dependency groups (e.g. `tools` and `cucumber`).
- Added Docker image build validation for both production and
development AI engine images.
- Updated workflow cache configuration and Docker build context where
required.
- Removed obsolete Python requirements files that are no longer needed
after the migration.
- Applied minor Python code modernizations, including import cleanup,
modern built-in generic type annotations (`list[...]`, `tuple[...]`,
`float | None`), and small style improvements.
- Removed unnecessary Python formatter/linter extensions from the
development container configuration.

### Why the change was made

- Standardize Python dependency management across the repository.
- Reduce duplicated dependency installation logic in CI.
- Improve workflow performance through shared dependency caching.
- Ensure all Python utilities execute against the same locked dependency
set managed by the engine project.
- Simplify long-term maintenance by eliminating legacy requirements
files and pip-specific workflow steps.


---

## Checklist

### General

- [ ] I have read the [Contribution
Guidelines](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/CONTRIBUTING.md)
- [ ] I have read the [Stirling-PDF Developer
Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/DeveloperGuide.md)
(if applicable)
- [ ] I have read the [How to add new languages to
Stirling-PDF](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md)
(if applicable)
- [ ] I have performed a self-review of my own code
- [ ] My changes generate no new warnings

### Documentation

- [ ] I have updated relevant docs on [Stirling-PDF's doc
repo](https://github.com/Stirling-Tools/Stirling-Tools.github.io/blob/main/docs/)
(if functionality has heavily changed)
- [ ] I have read the section [Add New Translation
Tags](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/devGuide/HowToAddNewLanguage.md#add-new-translation-tags)
(for new translation tags only)

### Translations (if applicable)

- [ ] I ran
[`scripts/counter_translation.py`](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/docs/counter_translation.md)

### UI Changes (if applicable)

- [ ] Screenshots or videos demonstrating the UI changes are attached
(e.g., as comments or direct attachments in the PR)

### Testing (if applicable)

- [ ] I have run `task check` to verify linters, typechecks, and tests
pass
- [ ] I have tested my changes locally. Refer to the [Testing
Guide](https://github.com/Stirling-Tools/Stirling-PDF/blob/main/DeveloperGuide.md#7-testing)
for more details.

---------

Signed-off-by: Carsten Drewes <c.drewes@stud.uni-hannover.de>
Co-authored-by: albanobattistella <34811668+albanobattistella@users.noreply.github.com>
Co-authored-by: kastenherri <116314318+kastenherri@users.noreply.github.com>
Co-authored-by: Anthony Stirling <77850077+Frooodle@users.noreply.github.com>
Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
Co-authored-by: James Brunton <jbrunton96@gmail.com>

.taskfiles/engine.yml

@@ -2,22 +2,49 @@ version: '3'
 
 tasks:
   install:
-    desc: "Install engine dependencies"
+    desc: "Install engine runtime and development dependencies"
     run: once
     cmds:
       - uv python install 3.13.8
-      - uv sync
+      - uv sync --locked --group engine --group engine-dev
     sources:
       - uv.lock
       - pyproject.toml
     status:
       - test -d .venv
 
+  lock:
+    desc: "Update the engine lockfile from project metadata"
+    cmds:
+      - uv lock
+
+  lock:upgrade:
+    desc: "Upgrade allowed engine dependencies and update the lockfile"
+    cmds:
+      - uv lock --upgrade
+
+  lock:check:
+    desc: "Check whether the engine lockfile is current"
+    cmds:
+      - uv lock --check
+
+  update:
+    desc: "Upgrade engine dependencies and synchronize the environment"
+    cmds:
+      - task: lock:upgrade
+      - uv sync --locked --group engine --group engine-dev
+
+  update:all:
+    desc: "Upgrade all Python dependency groups and synchronize the environment"
+    cmds:
+      - task: lock:upgrade
+      - uv sync --locked --all-groups
+
   prepare:
     desc: "Set up engine .env from template"
     deps: [install]
     cmds:
-      - uv run scripts/setup_env.py
+      - uv run --locked --group engine --group engine-dev scripts/setup_env.py
     sources:
       - scripts/setup_env.py
     generates:
@@ -33,7 +60,7 @@ tasks:
     env:
       PYTHONUNBUFFERED: "1"
     cmds:
-      - uv run uvicorn stirling.api.app:app --host 0.0.0.0 --port {{.PORT}} --workers "${STIRLING_ENGINE_WORKERS:-4}"
+      - uv run --locked --group engine uvicorn stirling.api.app:app --host 0.0.0.0 --port {{.PORT}} --workers "${STIRLING_ENGINE_WORKERS:-4}"
 
   dev:
     desc: "Start engine dev server with hot reload"
@@ -45,43 +72,43 @@ tasks:
     env:
       PYTHONUNBUFFERED: "1"
     cmds:
-      - uv run uvicorn stirling.api.app:app --host 0.0.0.0 --port {{.PORT}} --reload
+      - uv run --locked --group engine --group engine-dev uvicorn stirling.api.app:app --host 0.0.0.0 --port {{.PORT}} --reload
 
   lint:
     desc: "Run linting"
     deps: [install]
     cmds:
-      - uv run ruff check .
+      - uv run --locked --group engine --group engine-dev ruff check .
 
   lint:fix:
     desc: "Auto-fix lint issues"
     deps: [install]
     cmds:
-      - uv run ruff check . --fix
+      - uv run --locked --group engine --group engine-dev ruff check . --fix
 
   format:
     desc: "Auto-fix code formatting"
     deps: [install]
     cmds:
-      - uv run ruff format .
+      - uv run --locked --group engine --group engine-dev ruff format .
 
   format:check:
     desc: "Check code formatting"
     deps: [install]
     cmds:
-      - uv run ruff format . --diff
+      - uv run --locked --group engine --group engine-dev ruff format . --diff
 
   typecheck:
     desc: "Run type checking"
     deps: [install]
     cmds:
-      - uv run pyright . --warnings
+      - uv run --locked --group engine --group engine-dev pyright . --warnings
 
   test:
     desc: "Run tests"
     deps: [prepare]
     cmds:
-      - uv run pytest tests
+      - uv run --locked --group engine --group engine-dev pytest tests
 
   fix:
     desc: "Auto-fix lint + format"
@@ -102,7 +129,7 @@ tasks:
     desc: "Generate tool_models.py from Java OpenAPI spec (SwaggerDoc.json)"
     deps: [install, ":backend:swagger"]
     cmds:
-      - uv run python scripts/generate_tool_models.py --spec ../SwaggerDoc.json --output src/stirling/models/tool_models.py --io-output src/stirling/models/tool_io.py
+      - uv run --locked --group engine --group engine-dev python scripts/generate_tool_models.py --spec ../SwaggerDoc.json --output src/stirling/models/tool_models.py --io-output src/stirling/models/tool_io.py
     sources:
       - ../SwaggerDoc.json
       - scripts/generate_tool_models.py
@@ -114,7 +141,7 @@ tasks:
     desc: "Fail if the committed tool models are out of date"
     deps: [install, ":backend:swagger"]
     cmds:
-      - uv run python scripts/generate_tool_models.py --spec ../SwaggerDoc.json --output src/stirling/models/tool_models.py --io-output src/stirling/models/tool_io.py --check
+      - uv run --locked --group engine --group engine-dev python scripts/generate_tool_models.py --spec ../SwaggerDoc.json --output src/stirling/models/tool_models.py --io-output src/stirling/models/tool_io.py --check
 
   clean:
     desc: "Clean build artifacts"

.taskfiles/pre-commit.yml

@@ -45,6 +45,10 @@ vars:
   # which owns the version and caches the binary here.
   GITLEAKS_BIN: '.task/bin/gitleaks{{if eq OS "windows"}}.exe{{end}}'
 
+env:
+  # Keep repository-wide checks isolated from the engine runtime environment.
+  UV_PROJECT_ENVIRONMENT: '.venv-pre-commit'
+
 tasks:
   default:
     desc: "Check formatting, spelling, and secrets across the repo"
@@ -76,19 +80,19 @@ tasks:
     desc: "Install the pinned pre-commit Python tools"
     run: once
     cmds:
-      - uv sync --project scripts/pre-commit --locked
+      - uv sync --project engine --locked --group pre-commit
     sources:
-      - scripts/pre-commit/uv.lock
-      - scripts/pre-commit/pyproject.toml
+      - engine/uv.lock
+      - engine/pyproject.toml
     status:
-      - test -d scripts/pre-commit/.venv
+      - test -d engine/.venv-pre-commit
 
   clean:
-    desc: "Remove the cached gitleaks binary and the tool virtualenv"
+    desc: "Remove the cached gitleaks binary and the pre-commit virtualenv"
     cmds:
-      - cmd: rm -rf scripts/pre-commit/.venv .task/bin/gitleaks
+      - cmd: rm -rf engine/.venv-pre-commit .task/bin/gitleaks
         platforms: [linux, darwin]
-      - cmd: cmd /c "rmdir /s /q scripts\pre-commit\.venv & del /q .task\bin\gitleaks.exe"
+      - cmd: cmd /c "rmdir /s /q engine\.venv-pre-commit & del /q .task\bin\gitleaks.exe"
         platforms: [windows]
         ignore_error: true
 
@@ -97,26 +101,26 @@ tasks:
   ruff:
     deps: [install]
     cmds:
-      - uv run --project scripts/pre-commit --no-sync ruff check --line-length=127 {{if .FIX}}--fix {{end}}$(git ls-files {{.PY_FILES}})
+      - uv run --project engine --locked --group pre-commit ruff check --isolated --line-length=120 {{if .FIX}}--fix {{end}}$(git ls-files {{.PY_FILES}})
 
   ruff-format:
     deps: [install]
     cmds:
-      - uv run --project scripts/pre-commit --no-sync ruff format {{if .FIX}}{{else}}--check {{end}}$(git ls-files {{.PY_FILES}})
+      - uv run --project engine --locked --group pre-commit ruff format --isolated --line-length=120 {{if .FIX}}{{else}}--check {{end}}$(git ls-files {{.PY_FILES}})
 
   codespell:
     deps: [install]
     cmds:
-      - uv run --project scripts/pre-commit --no-sync codespell --ignore-words-list=thirdParty,tabEl,tabEls,Sie,ist,fulfilment --quiet-level=2 $(git ls-files {{.SPELL_FILES}})
+      - uv run --project engine --locked --group pre-commit codespell --ignore-words-list=thirdParty,tabEl,tabEls,Sie,ist,fulfilment --quiet-level=2 $(git ls-files {{.SPELL_FILES}})
 
   toml-sort:
     deps: [install]
     cmds:
-      - uv run --project scripts/pre-commit --no-sync python scripts/pre-commit/sort_locale_toml.py {{if .FIX}}--fix {{end}}{{.LOCALE_TOML}}
+      - uv run --project engine --locked --group pre-commit python scripts/pre-commit/sort_locale_toml.py {{if .FIX}}--fix {{end}}{{.LOCALE_TOML}}
 
   whitespace:
     cmds:
-      - uv run --no-project python scripts/pre-commit/whitespace.py {{if .FIX}}--fix {{end}}{{.WS_FILES}}
+      - uv run --project engine --locked --group pre-commit python scripts/pre-commit/whitespace.py {{if .FIX}}--fix {{end}}{{.WS_FILES}}
 
   gitleaks:
     deps: [gitleaks-bin]
@@ -130,4 +134,4 @@ tasks:
     internal: true
     desc: "Ensure the pinned, checksum-verified gitleaks binary is cached in .task/bin"
     cmds:
-      - uv run --no-project python scripts/pre-commit/install_gitleaks.py
+      - uv run --project engine --locked --group pre-commit python scripts/pre-commit/install_gitleaks.py