feat(LAB-4585): designate workflow steps by id, or by name and group

[aurelienlombard]

Closes LAB-4585.

Step names are unique per group only. A step is now given by step_id, or by step_name with group_name when several groups use the name, never both; the SDK resolves names to ids before sending.

Changes (one commit each)

1. Workflow methods designate a step by id, or by name and group: add/remove_reviewers_to_step, add/remove_labelers_to_step (and projects.workflow.*), update_labeling_step_properties, update_review_step_properties, rename_step. update_project_workflow resolves updates and deletes given by name (a delete can be {"name", "group_name"}); create_steps takes step_group_id; get_steps lists each step's group.
2. add_review_step takes group_name: the step is added at the end of that group, and send_back_to_step is found within it.
3. Labels on a step given by id, or by name and group: append_labels, its shapefile/GeoJSON variants and labels.create_*, sent as stepId. labels.create_default no longer forces the step named "Default".
4. Filters by step id: step_id_in, step_id_not_in, step_id_and_status_in, step_id_and_status_not_in, and asset_step_id_in on labels. They are keyword-only and exclusive with the name filters. A name several groups use now matches each group's step (step_name_and_status_in kept only the last one); group_name_in narrows it.
5. copy_workflow_from_project refuses a source with several groups instead of flattening them.
6. Docs: a group's allowed jobs are enforced by the labeling app only, not on labels created through the SDK; consensus can only be set on the labeling step of the first group.

Compatibility

• Existing calls keep working: step_name stays positional, and the arguments after it get a default with a required check.
• Release once the backend accepts the stepId input: creating labels on a step sends it.

🤖 Generated with Claude Code

[aurelienlombard]

🧪 Local test — LAB-4585

Summary: the step designation (step_id, or step_name + group_name, never both) works on every method the matrix called, against a local Kili backend; the name filters now cover every group and group_name_in narrows them. CI's Pylint job is red on three messages this PR introduces.

✅ What works

Unit tests: 842 passed, 1 skipped (pytest tests --ignore tests/e2e); pyright 0 errors. CI: tests, pyright, pre-commit, build and docs green; Pylint red (below); markdown-link-check red on main too.

Test data: a workflow V3 project with two groups Team 1 / Team 2, both named Label / Review, on a local Kili backend; one asset per case, walked through the interface's requests.

Call	Expected	Observed
add_reviewers_to_step(step_id=<Team 2/Review>)	on Team 2/Review only	✅
add_labelers_to_step("Label", …, group_name="Team 2")	on Team 2/Label only	✅
add_labelers_to_step("Label", …)	refused, asks for the group	✅
step_id and step_name together	refused	✅
update_project_workflow(update_steps=[{name, group_name, step_coverage}])	that group's step only	✅
append_labels(step_name="Label", group_name="Team 1"), no project_id	label added, asset moves to Team 1/Review	✅
assets(step_name_and_status_in=[("Label","TO_DO")])	the Team 1 and the Team 2 asset	✅
same + group_name_in=["Team 2"] / step_id_in=[<Team 2/Label>]	the Team 2 asset	✅ / ✅
step_id_in + step_name_in	refused	✅
copy_workflow_from_project from two groups	refused	✅

Released 26.2.0 against the new backend: a step name two groups share is refused with "give its id" (append_labels, update_project_workflow); a single-group project works as before.

🐛 Bug: Pylint fails in CI

R0916 too-many-boolean-expressions at presentation/client/label.py:153 and :531 (the asset_step_id_in added to the condition makes 6/5), R0912 too-many-branches at use_cases/project_workflow/__init__.py:178 (the multi-group refusal makes 13/12). Pylint is green on main's latest run.

Not tested

• copy_project(copy_labels=True) on two groups fails on the backend side (copyLabels), a backend bug, since fixed.

_{tested at e64be2f}

[aurelienlombard]

Review Summary

Verdict: Needs changes

Severity	Count
Required	1
Suggestion	1

Tested locally: 842 passed · 10-call matrix against kili!14636, 10/10 as expected · released SDK 3/3 — report

The designation by id, or by name and group, behaves as specified on every call the matrix made; CI's Pylint is red on three messages this PR adds.

_{reviewing-feature · e64be2f}

[aurelienlombard]

🧪 Local test — LAB-4585 (re-review)

• ✔ fixed in aaa8f65 — Pylint: green in CI (3.10, 3.12, 3.13); locally 10.00/10 on the changed files.
• ✔ fixed in aaa8f65 — the step id filters are keyword-only, after every existing parameter.

Regression: 842 passed, 1 skipped; pyright 0 errors. CI: tests, pyright, Pylint, pre-commit, build and docs green; markdown-link-check red as on main. The SDK's copy_project(copy_labels=True) on two groups — the backend bug reported above — now copies labels and positions faithfully against a local Kili backend carrying the fix.

_{tested at aaa8f65}

[aurelienlombard]

Review Summary

Verdict: Ready to merge

Tested locally: 842 passed · both findings re-checked, Pylint green in CI — report

Both findings of the first pass are addressed; release after kili!14636 is deployed.

_{reviewing-feature · aaa8f65}

[aurelienlombard]

🧪 Local test — LAB-4585 (third pass)

• add_review_step takes group_name (the group to add the step to, at its end) and resolves send_back_to_step within it; the step property methods keep step_id / step_name + group_name, and now work on workflow V3 against a local Kili backend. Checked on a two-group project: each call acts on Team 2's step only.
• A step given twice to update_project_workflow(delete_steps=…) is deleted once; the step_id_* filters follow the rules of the name ones; get_steps lists each step's group; every name filter documents that a name several groups use matches each of them.
• 848 passed, 1 skipped; pyright 0 errors; Pylint (CI config) 10.00/10.

Release notes: release once the backend accepts the stepId input (label creation on a step sends it). labels.create_default no longer sends a step named "Default".

_{tested at df0afca}