API Dispatch

Intent

Define how GeoPandas-facing methods should cross from pandas objects into repo-owned execution surfaces without paying avoidable object-construction cost or hiding which implementation actually ran.

Request Signals

  • api dispatch

  • method delegation

  • dispatch events

  • GeoPandas adapter

  • public method boundary

Open First

  • docs/architecture/api-dispatch.md

  • src/vibespatial/api/geometry_array.py

  • src/vibespatial/geometry/device_array.py

  • src/geopandas/init.py

  • tests/test_geopandas_dispatch.py

Verify

  • uv run pytest tests/test_geopandas_dispatch.py

  • uv run python scripts/check_docs.py --check

Risks

  • Reconstructing wrapper arrays inside delegate helpers adds avoidable overhead per call.

  • Caching owned conversions without invalidation on mutation leads to stale state.

  • Dispatch events that materialize host buffers defeat the purpose of lightweight metadata.

Decision

  • Reuse the existing GeometryArray already stored on GeoSeries / GeoDataFrame instead of rebuilding wrapper arrays inside delegate helpers.

  • Allow GeometryArray to cache its owned-geometry conversion for repo-owned kernels that need it repeatedly.

  • Make the CPU/GPU dispatch decision at the public method boundary, then keep the internal workflow inside that execution family unless an explicit, observable fallback boundary is crossed.

  • Record explicit dispatch events at the public method boundary for high-traffic surfaces (currently buffer, offset_curve, clip_by_rect, make_valid, dissolve, intersection, union, difference, symmetric_difference, boundary, convex_hull, area, length, hausdorff_distance, and frechet_distance). Unary constructive ops (rotate, scale, skew) route through owned paths directly without per-call dispatch events.

  • Keep host-competitive Shapely paths in place when owned host prototypes are slower, but make that choice visible.

Performance Notes

  • Reconstructing GeometryArray(...) inside delegate helpers is pure overhead on every public method call.

  • Caching owned conversions is important because owned-buffer construction is the real bridge cost between the extension-array surface and GPU-oriented kernels.

  • Re-planning CPU vs GPU at each internal step of a composite workflow adds orchestration cost and tends to shed residency. Prefer one boundary decision, then compose internal helpers inside the chosen execution shape.

  • Dispatch events should be lightweight metadata only; they must not materialize host buffers or alter row order.

Current Behavior

  • GeoSeries and GeoDataFrame delegate helpers now reuse the existing geometry extension array.

  • GeometryArray.to_owned() caches the owned-buffer conversion until mutation.

  • Public method dispatch is observable through geopandas.get_dispatch_events().

  • Host fallbacks remain explicit through the separate fallback-event stream.