cue-ai 0.3.0

package/resources/skills/skills/nvidia/cuopt-numerical-optimization-api-python/resources/qp_examples.md

@@ -0,0 +1,198 @@
+# QP: Python API Examples
+
+## Portfolio Optimization
+
+```python
+"""
+Minimize portfolio variance (risk):
+    minimize    x^T * Q * x
+    subject to  sum(x) = 1         (fully invested)
+                r^T * x >= target  (minimum return)
+                x >= 0             (no short selling)
+
+Note: QP is beta and MUST use MINIMIZE (not MAXIMIZE)
+"""
+from cuopt.linear_programming.problem import Problem, CONTINUOUS, MINIMIZE
+from cuopt.linear_programming.solver_settings import SolverSettings
+
+problem = Problem("Portfolio")
+
+# Portfolio weights (decision variables)
+x1 = problem.addVariable(lb=0, ub=1, vtype=CONTINUOUS, name="stock_a")
+x2 = problem.addVariable(lb=0, ub=1, vtype=CONTINUOUS, name="stock_b")
+x3 = problem.addVariable(lb=0, ub=1, vtype=CONTINUOUS, name="stock_c")
+
+# Expected returns
+r1, r2, r3 = 0.12, 0.08, 0.05  # 12%, 8%, 5%
+target_return = 0.08
+
+# Covariance matrix Q:
+# [[0.04, 0.01, 0.005],
+#  [0.01, 0.02, 0.008],
+#  [0.005, 0.008, 0.01]]
+#
+# Quadratic objective: x^T * Q * x
+# Expanded: 0.04*x1² + 0.02*x2² + 0.01*x3² + 2*0.01*x1*x2 + 2*0.005*x1*x3 + 2*0.008*x2*x3
+
+problem.setObjective(
+    0.04*x1*x1 + 0.02*x2*x2 + 0.01*x3*x3 +
+    0.02*x1*x2 + 0.01*x1*x3 + 0.016*x2*x3,
+    sense=MINIMIZE  # MUST be MINIMIZE for QP!
+)
+
+# Linear constraints
+problem.addConstraint(x1 + x2 + x3 == 1, name="budget")
+problem.addConstraint(r1*x1 + r2*x2 + r3*x3 >= target_return, name="min_return")
+
+# Solve
+settings = SolverSettings()
+settings.set_parameter("time_limit", 60)
+problem.solve(settings)
+
+# Results
+if problem.Status.name in ["Optimal", "PrimalFeasible"]:
+    print(f"Portfolio variance: {problem.ObjValue:.6f}")
+    print(f"Portfolio std dev: {problem.ObjValue**0.5:.4f}")
+    print(f"\nAllocation:")
+    print(f"  Stock A: {x1.getValue()*100:.2f}%")
+    print(f"  Stock B: {x2.getValue()*100:.2f}%")
+    print(f"  Stock C: {x3.getValue()*100:.2f}%")
+
+    actual_return = r1*x1.getValue() + r2*x2.getValue() + r3*x3.getValue()
+    print(f"\nExpected return: {actual_return*100:.2f}%")
+```
+
+## Least Squares
+
+```python
+"""
+Minimize ||Ax - b||² = (Ax-b)^T(Ax-b)
+
+Example: Find point closest to (3, 4)
+minimize (x-3)² + (y-4)² = x² - 6x + 9 + y² - 8y + 16
+"""
+from cuopt.linear_programming.problem import Problem, CONTINUOUS, MINIMIZE
+from cuopt.linear_programming.solver_settings import SolverSettings
+
+problem = Problem("LeastSquares")
+
+x = problem.addVariable(lb=-100, ub=100, vtype=CONTINUOUS, name="x")
+y = problem.addVariable(lb=-100, ub=100, vtype=CONTINUOUS, name="y")
+
+# Quadratic objective: (x-3)² + (y-4)²
+# Expanded: x² + y² - 6x - 8y + 25
+problem.setObjective(
+    x*x + y*y - 6*x - 8*y + 25,
+    sense=MINIMIZE
+)
+
+result = problem.solve(SolverSettings())
+
+if problem.Status.name in ["Optimal", "PrimalFeasible"]:
+    print(f"x = {x.getValue():.4f}")  # Should be ~3
+    print(f"y = {y.getValue():.4f}")  # Should be ~4
+else:
+    raise RuntimeError(f"Solver failed with status: {problem.Status.name}")
+```
+
+## Quadratic with Linear Constraints
+
+```python
+"""
+minimize    x² + y² + z²
+subject to  x + y + z = 10
+            x >= 0, y >= 0, z >= 0
+"""
+from cuopt.linear_programming.problem import Problem, CONTINUOUS, MINIMIZE
+
+problem = Problem("QuadraticConstrained")
+
+x = problem.addVariable(lb=0, vtype=CONTINUOUS, name="x")
+y = problem.addVariable(lb=0, vtype=CONTINUOUS, name="y")
+z = problem.addVariable(lb=0, vtype=CONTINUOUS, name="z")
+
+problem.setObjective(x*x + y*y + z*z, sense=MINIMIZE)
+problem.addConstraint(x + y + z == 10)
+
+problem.solve()
+
+if problem.Status.name == "Optimal":
+    print(f"x = {x.getValue():.4f}")
+    print(f"y = {y.getValue():.4f}")
+    print(f"z = {z.getValue():.4f}")
+    print(f"Objective = {problem.ObjValue:.4f}")
+```
+
+## Maximization Workaround
+
+```python
+"""
+QP only supports MINIMIZE.
+To maximize f(x), minimize -f(x).
+
+Example: maximize -x² + 4x  (parabola with max at x=2)
+"""
+from cuopt.linear_programming.problem import Problem, CONTINUOUS, MINIMIZE
+
+problem = Problem("MaxWorkaround")
+
+x = problem.addVariable(lb=0, ub=10, vtype=CONTINUOUS, name="x")
+
+# Want to maximize: -x² + 4x
+# Instead minimize: -(-x² + 4x) = x² - 4x
+problem.setObjective(x*x - 4*x, sense=MINIMIZE)
+
+problem.solve()
+
+if problem.Status.name in ["Optimal", "PrimalFeasible"]:
+    print(f"x = {x.getValue():.4f}")  # Should be 2
+    print(f"Minimized value = {problem.ObjValue:.4f}")  # Should be -4
+    print(f"Original maximum = {-problem.ObjValue:.4f}")  # Should be 4
+else:
+    print(f"Solver did not find optimal solution. Status: {problem.Status.name}")
+```
+
+## Expanding Covariance Matrix
+
+Given covariance matrix Q and weight vector x:
+
+```python
+# Covariance matrix
+Q = [
+    [0.04, 0.01, 0.005],
+    [0.01, 0.02, 0.008],
+    [0.005, 0.008, 0.01]
+]
+
+# Expansion: x^T * Q * x
+# = Q[0,0]*x1² + Q[1,1]*x2² + Q[2,2]*x3²
+#   + 2*Q[0,1]*x1*x2 + 2*Q[0,2]*x1*x3 + 2*Q[1,2]*x2*x3
+#
+# = 0.04*x1*x1 + 0.02*x2*x2 + 0.01*x3*x3
+#   + 0.02*x1*x2 + 0.01*x1*x3 + 0.016*x2*x3
+
+objective = (
+    Q[0][0]*x1*x1 + Q[1][1]*x2*x2 + Q[2][2]*x3*x3 +
+    2*Q[0][1]*x1*x2 + 2*Q[0][2]*x1*x3 + 2*Q[1][2]*x2*x3
+)
+```
+
+## Critical Reminders
+
+1. **MINIMIZE only** - solver rejects MAXIMIZE for QP
+2. **Convexity** - Q should be positive semi-definite
+3. **Beta status** - API may change in future versions
+4. **Status checking** - use PascalCase: `"Optimal"` not `"OPTIMAL"`
+
+---
+
+## Additional References (tested in CI)
+
+For more complete examples, read these files:
+
+| Example | File | Description |
+|---------|------|-------------|
+| Simple QP | `docs/cuopt/source/cuopt-python/lp-qp-milp/examples/simple_qp_example.py` | Basic QP setup |
+| QP with Matrix | `docs/cuopt/source/cuopt-python/lp-qp-milp/examples/qp_matrix_example.py` | CSR matrix format for Q |
+
+These examples are tested by CI (`ci/test_doc_examples.sh`) and represent canonical usage.

package/resources/skills/skills/nvidia/cuopt-routing-api-python/SKILL.md

@@ -0,0 +1,103 @@
+---
+name: cuopt-routing-api-python
+version: "26.08.00"
+description: Vehicle routing (VRP, TSP, PDP) with cuOpt — Python API only. Use when the user is building or solving routing in Python.
+---
+
+
+# cuOpt Routing — Python API
+
+Confirm problem type (TSP, VRP, PDP) and data (locations, orders, fleet, constraints) before coding.
+
+This skill is **Python only**. Routing has no C API in cuOpt.
+
+## Minimal VRP Example
+
+```python
+import cudf
+from cuopt import routing
+
+cost_matrix = cudf.DataFrame([...], dtype="float32")
+dm = routing.DataModel(n_locations=4, n_fleet=2, n_orders=3)
+dm.add_cost_matrix(cost_matrix)
+dm.set_order_locations(cudf.Series([1, 2, 3], dtype="int32"))
+solution = routing.Solve(dm, routing.SolverSettings())
+
+if solution.get_status() == 0:
+    solution.display_routes()
+```
+
+## Adding Constraints
+
+```python
+# Time windows
+dm.add_transit_time_matrix(transit_time_matrix)
+dm.set_order_time_windows(earliest_series, latest_series)
+
+# Capacities
+dm.add_capacity_dimension("weight", demand_series, capacity_series)
+dm.set_order_service_times(service_times)
+dm.set_vehicle_locations(start_locations, end_locations)
+dm.set_vehicle_time_windows(earliest_start, latest_return)
+
+# Pickup-delivery pairs
+dm.set_pickup_delivery_pairs(pickup_indices, delivery_indices)
+
+# Precedence
+dm.add_order_precedence(node_id=2, preceding_nodes=np.array([0, 1]))
+```
+
+## Solution Checking
+
+```python
+status = solution.get_status()  # 0=SUCCESS, 1=FAIL, 2=TIMEOUT, 3=EMPTY
+if status == 0:
+    route_df = solution.get_route()
+    total_cost = solution.get_total_objective()
+else:
+    print(solution.get_error_message())
+    print(solution.get_infeasible_orders().to_list())
+```
+
+## Data Types (use explicit dtypes)
+
+```python
+cost_matrix = cost_matrix.astype("float32")
+order_locations = cudf.Series([...], dtype="int32")
+demand = cudf.Series([...], dtype="int32")
+```
+
+## Solver Settings
+
+```python
+ss = routing.SolverSettings()
+ss.set_time_limit(30)
+ss.set_verbose_mode(True)
+ss.set_error_logging_mode(True)
+```
+
+## Common Issues
+
+| Problem | Fix |
+|---------|-----|
+| Empty solution | Widen time windows or check travel times |
+| Infeasible orders | Increase fleet or capacity |
+| Status != 0 with time windows | Add `add_transit_time_matrix()` |
+| Wrong cost | Check cost_matrix is symmetric |
+| `compute_waypoint_sequence` alters route_df | It replaces the `location` column with waypoint ids in place — pass `route_df.copy()` if you still need cost-matrix indices (e.g. when iterating per truck) |
+
+## Debugging
+
+**When status != 0:** `print(solution.get_error_message())` and `print(solution.get_infeasible_orders().to_list())` to see which orders are infeasible.
+
+**Data types:** Use explicit dtypes (float32, int32) for matrices and series to avoid silent errors.
+
+## Examples
+
+- [examples.md](resources/examples.md) — VRP, PDP, multi-depot
+- [server_examples.md](resources/server_examples.md) — REST client (curl, Python)
+- **Reference models:** This skill's `assets/` — [vrp_basic](assets/vrp_basic/), [pdp_basic](assets/pdp_basic/). See [assets/README.md](assets/README.md).
+
+## Escalate
+
+For contribution or build-from-source, see the developer skill.

package/resources/skills/skills/nvidia/cuopt-routing-api-python/assets/README.md

@@ -0,0 +1,10 @@
+# Assets — reference routing models
+
+Routing reference implementations (Python). Use as reference when building new applications; do not edit in place.
+
+| Model | Type | Description |
+|-------|------|-------------|
+| [vrp_basic](vrp_basic/) | VRP | Minimal VRP: 4 locations, 1 vehicle, 3 orders |
+| [pdp_basic](pdp_basic/) | PDP | Pickup-delivery pairs, capacity dimension |
+
+**Run:** From each subdir, `python model.py` (requires cuOpt and cudf). See [resources/examples.md](../resources/examples.md) for more patterns (time windows, multi-depot).

package/resources/skills/skills/nvidia/cuopt-routing-api-python/assets/pdp_basic/README.md

@@ -0,0 +1,7 @@
+# Pickup-Delivery (PDP)
+
+2 pickup-delivery pairs (4 orders), 2 vehicles. Pickup must occur before delivery; capacity dimension.
+
+**Run:** `python model.py`
+
+**See also:** [resources/examples.md](../../resources/examples.md) for more PDP and VRP patterns.

package/resources/skills/skills/nvidia/cuopt-routing-api-python/assets/pdp_basic/model.py

@@ -0,0 +1,56 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+PDP: 2 pickup-delivery pairs, 2 vehicles. Pickup before delivery; capacity dimension.
+"""
+
+import cudf
+from cuopt import routing
+
+cost_matrix = cudf.DataFrame(
+    [
+        [0, 10, 20, 30, 40],
+        [10, 0, 15, 25, 35],
+        [20, 15, 0, 10, 20],
+        [30, 25, 10, 0, 15],
+        [40, 35, 20, 15, 0],
+    ],
+    dtype="float32",
+)
+
+transit_time_matrix = cost_matrix.copy(deep=True)
+n_fleet = 2
+n_orders = 4
+
+order_locations = cudf.Series([1, 2, 3, 4], dtype="int32")
+pickup_indices = cudf.Series([0, 2])
+delivery_indices = cudf.Series([1, 3])
+demand = cudf.Series([10, -10, 15, -15], dtype="int32")
+vehicle_capacity = cudf.Series([50, 50], dtype="int32")
+
+dm = routing.DataModel(
+    n_locations=cost_matrix.shape[0],
+    n_fleet=n_fleet,
+    n_orders=n_orders,
+)
+dm.add_cost_matrix(cost_matrix)
+dm.add_transit_time_matrix(transit_time_matrix)
+dm.set_order_locations(order_locations)
+dm.add_capacity_dimension("load", demand, vehicle_capacity)
+dm.set_pickup_delivery_pairs(pickup_indices, delivery_indices)
+dm.set_vehicle_locations(
+    cudf.Series([0, 0], dtype="int32"),
+    cudf.Series([0, 0], dtype="int32"),
+)
+
+ss = routing.SolverSettings()
+ss.set_time_limit(10)
+solution = routing.Solve(dm, ss)
+
+print(f"Status: {solution.get_status()}")
+if solution.get_status() == 0:
+    solution.display_routes()
+    print(f"Total cost: {solution.get_total_objective()}")
+else:
+    print(solution.get_error_message())

package/resources/skills/skills/nvidia/cuopt-routing-api-python/assets/vrp_basic/README.md

@@ -0,0 +1,7 @@
+# Minimal VRP
+
+4 locations (depot 0 + 3 customers), 1 vehicle, 3 orders. Cost matrix only; no time windows or capacity.
+
+**Run:** `python model.py`
+
+**See also:** [resources/examples.md](../../resources/examples.md) for VRP with time windows, capacity, and multi-depot.

package/resources/skills/skills/nvidia/cuopt-routing-api-python/assets/vrp_basic/model.py

@@ -0,0 +1,31 @@
+# SPDX-FileCopyrightText: Copyright (c) 2025-2026, NVIDIA CORPORATION & AFFILIATES. All rights reserved.
+# SPDX-License-Identifier: Apache-2.0
+
+"""
+Minimal VRP: 4 locations, 1 vehicle, 3 orders. Cost matrix only.
+"""
+
+import cudf
+from cuopt import routing
+
+cost_matrix = cudf.DataFrame(
+    [
+        [0, 10, 15, 20],
+        [10, 0, 12, 18],
+        [15, 12, 0, 10],
+        [20, 18, 10, 0],
+    ],
+    dtype="float32",
+)
+
+dm = routing.DataModel(n_locations=4, n_fleet=1, n_orders=3)
+dm.add_cost_matrix(cost_matrix)
+dm.set_order_locations(cudf.Series([1, 2, 3], dtype="int32"))
+
+solution = routing.Solve(dm, routing.SolverSettings())
+
+if solution.get_status() == 0:
+    solution.display_routes()
+    print(f"Total cost: {solution.get_total_objective()}")
+else:
+    print(f"Status: {solution.get_status()}", solution.get_error_message())

package/resources/skills/skills/nvidia/cuopt-routing-api-python/resources/examples.md

@@ -0,0 +1,249 @@
+# Routing: Python API Examples
+
+## VRP with Time Windows & Capacities
+
+```python
+"""
+Vehicle Routing Problem with:
+- 1 depot (location 0)
+- 5 customer locations (1-5)
+- 2 vehicles with capacity 100 each
+- Time windows for each location
+- Demand at each customer
+"""
+import cudf
+from cuopt import routing
+
+# Cost/distance matrix (6x6: depot + 5 customers)
+cost_matrix = cudf.DataFrame([
+    [0,  10, 15, 20, 25, 30],  # From depot
+    [10,  0, 12, 18, 22, 28],  # From customer 1
+    [15, 12,  0, 10, 15, 20],  # From customer 2
+    [20, 18, 10,  0,  8, 15],  # From customer 3
+    [25, 22, 15,  8,  0, 10],  # From customer 4
+    [30, 28, 20, 15, 10,  0],  # From customer 5
+], dtype="float32")
+
+# Also use as transit time matrix (same values for simplicity)
+transit_time_matrix = cost_matrix.copy(deep=True)
+
+# Order data (customers 1-5)
+order_locations = cudf.Series([1, 2, 3, 4, 5], dtype="int32")  # Location indices for orders
+
+# Demand at each customer (single capacity dimension)
+demand = cudf.Series([20, 30, 25, 15, 35], dtype="int32")
+
+# Vehicle capacities (must match demand dimensions)
+vehicle_capacity = cudf.Series([100, 100], dtype="int32")
+
+# Time windows for orders [earliest, latest]
+order_earliest = cudf.Series([0,  10, 20,  0, 30], dtype="int32")
+order_latest = cudf.Series([50, 60, 70, 80, 90], dtype="int32")
+
+# Service time at each customer
+service_times = cudf.Series([5, 5, 5, 5, 5], dtype="int32")
+
+# Fleet configuration
+n_fleet = 2
+
+# Vehicle start/end locations (both start and return to depot)
+vehicle_start = cudf.Series([0, 0], dtype="int32")
+vehicle_end = cudf.Series([0, 0], dtype="int32")
+
+# Vehicle time windows (operating hours)
+vehicle_earliest = cudf.Series([0, 0], dtype="int32")
+vehicle_latest = cudf.Series([200, 200], dtype="int32")
+
+# Build the data model
+dm = routing.DataModel(
+    n_locations=cost_matrix.shape[0],
+    n_fleet=n_fleet,
+    n_orders=len(order_locations)
+)
+
+# Add matrices
+dm.add_cost_matrix(cost_matrix)
+dm.add_transit_time_matrix(transit_time_matrix)
+
+# Add order data
+dm.set_order_locations(order_locations)
+dm.set_order_time_windows(order_earliest, order_latest)
+dm.set_order_service_times(service_times)
+
+# Add capacity dimension (name, demand_per_order, capacity_per_vehicle)
+dm.add_capacity_dimension("weight", demand, vehicle_capacity)
+
+# Add fleet data
+dm.set_vehicle_locations(vehicle_start, vehicle_end)
+dm.set_vehicle_time_windows(vehicle_earliest, vehicle_latest)
+
+# Configure solver
+ss = routing.SolverSettings()
+ss.set_time_limit(10)  # seconds
+
+# Solve
+solution = routing.Solve(dm, ss)
+
+# Check solution status
+print(f"Status: {solution.get_status()}")
+
+# Display routes
+if solution.get_status() == 0:  # Success
+    print("\n--- Solution Found ---")
+    solution.display_routes()
+
+    # Get detailed route data
+    route_df = solution.get_route()
+    print("\nDetailed route data:")
+    print(route_df)
+
+    # Get objective value (total cost)
+    print(f"\nTotal cost: {solution.get_total_objective()}")
+else:
+    print("No feasible solution found (status != 0).")
+```
+
+## Pickup and Delivery Problem (PDP)
+
+```python
+"""
+Pickup and Delivery Problem:
+- Items must be picked up from one location and delivered to another
+- Same vehicle must do both pickup and delivery
+- Pickup must occur before delivery
+"""
+import cudf
+from cuopt import routing
+
+# Cost matrix (depot + 4 locations)
+cost_matrix = cudf.DataFrame([
+    [0, 10, 20, 30, 40],
+    [10, 0, 15, 25, 35],
+    [20, 15, 0, 10, 20],
+    [30, 25, 10, 0, 15],
+    [40, 35, 20, 15, 0],
+], dtype="float32")
+
+transit_time_matrix = cost_matrix.copy(deep=True)
+
+n_fleet = 2
+n_orders = 4  # 2 pickup-delivery pairs = 4 orders
+
+# Orders: pickup at loc 1 -> deliver at loc 2, pickup at loc 3 -> deliver at loc 4
+order_locations = cudf.Series([1, 2, 3, 4], dtype="int32")
+
+# Pickup and delivery pairs (indices into order array)
+# Order 0 (pickup) pairs with Order 1 (delivery)
+# Order 2 (pickup) pairs with Order 3 (delivery)
+pickup_indices = cudf.Series([0, 2])
+delivery_indices = cudf.Series([1, 3])
+
+# Demand: positive for pickup, negative for delivery (must sum to 0 per pair)
+demand = cudf.Series([10, -10, 15, -15], dtype="int32")
+vehicle_capacity = cudf.Series([50, 50], dtype="int32")
+
+# Build model
+dm = routing.DataModel(
+    n_locations=cost_matrix.shape[0],
+    n_fleet=n_fleet,
+    n_orders=n_orders
+)
+
+dm.add_cost_matrix(cost_matrix)
+dm.add_transit_time_matrix(transit_time_matrix)
+dm.set_order_locations(order_locations)
+
+# Add capacity dimension
+dm.add_capacity_dimension("load", demand, vehicle_capacity)
+
+# Set pickup and delivery constraints
+dm.set_pickup_delivery_pairs(pickup_indices, delivery_indices)
+
+# Fleet setup
+dm.set_vehicle_locations(
+    cudf.Series([0, 0]),  # Start at depot
+    cudf.Series([0, 0])   # Return to depot
+)
+
+# Solve
+ss = routing.SolverSettings()
+ss.set_time_limit(10)
+solution = routing.Solve(dm, ss)
+
+print(f"Status: {solution.get_status()}")
+if solution.get_status() == 0:
+    solution.display_routes()
+```
+
+## Minimal VRP (Quick Start)
+
+```python
+import cudf
+from cuopt import routing
+
+# Minimal 4-location problem
+cost_matrix = cudf.DataFrame([
+    [0, 10, 15, 20],
+    [10, 0, 12, 18],
+    [15, 12, 0, 10],
+    [20, 18, 10, 0],
+], dtype="float32")
+
+dm = routing.DataModel(n_locations=4, n_fleet=1, n_orders=3)
+dm.add_cost_matrix(cost_matrix)
+dm.set_order_locations(cudf.Series([1, 2, 3], dtype="int32"))
+
+solution = routing.Solve(dm, routing.SolverSettings())
+
+if solution.get_status() == 0:
+    solution.display_routes()
+```
+
+## Multi-Depot VRP
+
+```python
+import cudf
+from cuopt import routing
+
+# 6 locations: 2 depots (0, 1) + 4 customers (2, 3, 4, 5)
+cost_matrix = cudf.DataFrame([
+    [0, 5, 10, 15, 20, 25],
+    [5, 0, 12, 8, 18, 22],
+    [10, 12, 0, 6, 14, 16],
+    [15, 8, 6, 0, 10, 12],
+    [20, 18, 14, 10, 0, 8],
+    [25, 22, 16, 12, 8, 0],
+], dtype="float32")
+
+n_fleet = 2
+
+dm = routing.DataModel(n_locations=6, n_fleet=n_fleet, n_orders=4)
+dm.add_cost_matrix(cost_matrix)
+dm.set_order_locations(cudf.Series([2, 3, 4, 5], dtype="int32"))
+
+# Vehicle 0 starts/ends at depot 0, Vehicle 1 at depot 1
+dm.set_vehicle_locations(
+    cudf.Series([0, 1]),  # start locations
+    cudf.Series([0, 1])   # end locations
+)
+
+solution = routing.Solve(dm, routing.SolverSettings())
+if solution.get_status() == 0:
+    solution.display_routes()
+```
+
+---
+
+## Additional References (tested in CI)
+
+For more complete examples, read these files:
+
+| Example | File | Description |
+|---------|------|-------------|
+| Basic Routing | `docs/cuopt/source/cuopt-server/examples/routing/examples/basic_routing_example.py` | Server-based routing |
+| Initial Solution | `docs/cuopt/source/cuopt-server/examples/routing/examples/initial_solution_example.py` | Warm starting |
+| Smoke Test | `docs/cuopt/source/cuopt-python/routing/examples/smoke_test_example.sh` | Quick validation |
+
+These examples are tested by CI and represent canonical usage.
+
+**Note:** The Python routing API documentation is in `python/cuopt/cuopt/routing/vehicle_routing.py` (docstrings).