[FEA] Enforce input types across the routing Python API (type hints + centralized validation)
Open
@chris-maes is already working on this.
Since Jul 9, 2026.
awaiting response
feature request
- Dominant language
- Cuda
- Stars
- 1k
- Forks
- 233
- Avg merge
- 4d 4h
- Merged PRs (30d)
- 95
Description
Is your feature request related to a problem? Please describe.
The routing Python API (DataModel setters, Solve, SolverSettings, Assignment) does not enforce input types consistently:
- Historically, inputs had to be cuDF but were only checked incidentally — e.g. a numpy/pandas input failed with a cryptic
AttributeError: 'numpy.ndarray' object has no attribute '__cuda_array_interface__'rather than a clear type error. - PR #1546 added numpy/pandas support via shared helpers (
type_cast/prepare_matrix) that normalize numpy/pandas/cuDF and reject Python lists — but enforcement is per-setter and easy to bypass. That work uncoveredset_order_prizessilently bypassing the sharedtype_cast(it called.astype()directly), which only surfaced through a comprehensive cross-backend test, not any type check. - There are no PEP 484 type annotations on the public API, so IDEs/mypy cannot catch wrong types, and error messages are inconsistent.
Describe the solution you'd like
Consistent, centralized type enforcement for the routing Python API:
- Route every array/scalar parameter through one shared validate-and-normalize helper — no setter may access the device pointer without going through it.
- Add PEP 484 type hints to the public classes/methods (
DataModel,SolverSettings,Solve,Assignment) declaring accepted types (numpy.ndarray,pandas.Series/DataFrame,cudf.Series/DataFrame), checkable by mypy/IDEs. - Fail fast with a consistent
TypeError/ValueErroron unsupported types (e.g. Python lists/tuples), wrong dtype, or wrong shape. - Add a test/lint guard that fails if a setter dereferences
__cuda_array_interface__/ builds a device pointer without going through the shared helper — preventing futureset_order_prizes-style bypasses.
Describe alternatives you've considered
- Docstring-only documentation of accepted types (current state) — not enforced, no tooling support.
- Per-setter ad-hoc
isinstancechecks — inconsistent and prone to drift (this is what caused theset_order_prizesgap). - Runtime validation decorator vs.
typing.get_type_hintsintrospection for the enforcement mechanism — to be decided during design.
Additional context
- Related PR: #1546 (numpy/pandas input support in routing
DataModel). - Shared helpers today:
type_cast/prepare_matrixinpython/cuopt/cuopt/routing/vehicle_routing_wrapper.pyx; validators inpython/cuopt/cuopt/routing/validation.py. - Consider extending the same policy to the LP/MILP/QP (numerical optimization) Python API for API consistency.
Contributor guide
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Assessment
This issue has not been assessed yet.