smart-spatial-system 0.2.7__tar.gz → 0.2.9__tar.gz

{smart_spatial_system-0.2.7 → smart_spatial_system-0.2.9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: smart_spatial_system
-Version: 0.2.7
+Version: 0.2.9
 Summary: Plugin-based GeoAI backend: natural-language questions become QuerySpecs, DAG plans, and map/table/report outputs.
 Author: Araz Shah
 License-Expression: MIT

{smart_spatial_system-0.2.7 → smart_spatial_system-0.2.9}/orchestrator/planning/llm_spec_generator.py

@@ -1056,6 +1056,22 @@ Important mappings:
   ones), never the annulus/gap BETWEEN two radii, which is what "ring" or
   "band" means here.
 
+- CRITICAL - spatial_join's params.cardinality defaults to "first": each
+  source feature is joined to only ONE matching target feature (the first
+  one found), even if it actually matches several. This silently
+  undercounts whenever the target layer's zones can overlap - most
+  commonly a spatial_join whose target is a ring_buffer output (or any
+  other layer with multiple zones generated from separate input
+  features, e.g. several stations' service areas). A point inside two
+  overlapping rings/zones would only be counted for one of them with the
+  default. Whenever the query means for a source feature matching several
+  zones to be counted under EACH of them (e.g. "for every station, which
+  points are within its rings", "for each amenity, list every zone it
+  falls into" - i.e. a point can legitimately belong to more than one
+  zone), set params={{"cardinality": "one_to_many", "include_target_properties": true}}
+  explicitly on that spatial_join. Do not leave cardinality unset and
+  rely on the default when the target can have overlapping zones.
+
 - "inside permitted/buildable polygon":
   op="filter_points_in_polygon"
   inputs={{"vector": "<points>", "polygon": "<polygon_layer>"}}
@@ -1268,6 +1284,18 @@ def _unique_ref(base: str, used: set[str]) -> str:
     return candidate
 
 
+# Operations known to be able to produce several overlapping output zones
+# from separate input features - e.g. ring_buffer builds one ring set per
+# input feature, and two features' rings routinely overlap (two metro
+# stations 1500m apart both have a 1200m ring covering the space between
+# them). A spatial_join whose target traces back to one of these needs
+# cardinality="one_to_many" or it silently drops every match after the
+# first for any source feature that falls inside more than one zone - see
+# _default_spatial_join_cardinality_for_overlapping_zones below. Currently
+# just ring_buffer; add here if a future op gains the same shape.
+_OVERLAP_PRONE_ZONE_OPS = frozenset({"ring_buffer"})
+
+
 def normalize_llm_query_spec_for_planning(spec: QuerySpec) -> QuerySpec:
     """
     Harden and improve LLM-produced QuerySpec before deterministic planning.
@@ -1276,6 +1304,11 @@ def normalize_llm_query_spec_for_planning(spec: QuerySpec) -> QuerySpec:
         - Remove unsupported input roles.
         - Add default scoring_spec when score_features misses it.
         - Add score_field/rank_field to rank_features when missing.
+        - Default spatial_join's cardinality to "one_to_many" when its
+          target traces back to an op that can produce overlapping zones
+          (see _OVERLAP_PRONE_ZONE_OPS) and the caller left cardinality
+          unset - the plugin's own default ("first") silently keeps only
+          one match per source feature otherwise.
         - If default scoring is used, inject enrichment nodes after spatial
           operations to create stable semantic scoring fields:
               distance_to_poi
@@ -1285,6 +1318,10 @@ def normalize_llm_query_spec_for_planning(spec: QuerySpec) -> QuerySpec:
     repairs: list[str] = []
     normalized_ops: list[OperationSpec] = []
 
+    ops_by_output: dict[str, OperationSpec] = {
+        op.output: op for op in spec.operations if op.output
+    }
+
     used_refs: set[str] = set()
     for op in spec.operations:
         if op.output:
@@ -1374,6 +1411,28 @@ def normalize_llm_query_spec_for_planning(spec: QuerySpec) -> QuerySpec:
                 clean_params["rank_field"] = "rank"
                 repairs.append("added rank_field='rank' to rank_features")
 
+        if op.op == "spatial_join" and "cardinality" not in clean_params:
+            target_ref = clean_inputs.get("target")
+            if target_ref is not None:
+                ancestors = _ancestor_refs(str(target_ref), ops_by_output)
+                traces_to_overlap_prone_op = any(
+                    ops_by_output.get(ref) is not None
+                    and ops_by_output[ref].op in _OVERLAP_PRONE_ZONE_OPS
+                    for ref in ancestors
+                )
+
+                if traces_to_overlap_prone_op:
+                    clean_params["cardinality"] = "one_to_many"
+                    repairs.append(
+                        f"set cardinality='one_to_many' on spatial_join "
+                        f"(output={op.output!r}) because its target "
+                        f"{target_ref!r} traces back to an operation that "
+                        "can produce overlapping zones - the plugin's own "
+                        "default cardinality='first' would silently keep "
+                        "only one match for any source feature that falls "
+                        "in more than one zone"
+                    )
+
         normalized_op = OperationSpec(
             op=op.op,
             inputs=clean_inputs,

{smart_spatial_system-0.2.7 → smart_spatial_system-0.2.9}/plugins/spatial_join.py

@@ -35,6 +35,20 @@ Engines:
     - python:
         Bbox-based fallback.
 
+Performance:
+    The shapely engine indexes target geometries in an STRtree (shapely's
+    own R-tree, no extra dependency) and narrows each source feature's
+    candidate targets by bounding-box overlap before evaluating the exact
+    predicate, instead of checking every source against every target.
+    This turns the join from O(n*m) into roughly O((n+m) * log(m)) for
+    the common case where every target geometry is valid - a large
+    difference at real-world scale (tens of thousands of source features
+    against hundreds of target zones). Falls back to the full O(n*m)
+    double loop automatically if shapely is unavailable, if engine is
+    forced to "python", or if any target geometry cannot be parsed by
+    shapely (that specific edge case keeps the previous per-pair error
+    handling instead of being silently skipped by the index).
+
 Important:
     The python engine is bbox-based and approximate. For production-grade
     spatial join, install shapely:
@@ -331,6 +345,44 @@ def _get_shapely_tools():
     return shape
 
 
+def _get_strtree_tools():
+    try:
+        from shapely.geometry import shape
+        from shapely.strtree import STRtree
+    except ImportError as exc:
+        raise SDKDependencyError(
+            "spatial_join requires 'shapely' for this engine. "
+            "Install it with: pip install shapely"
+        ) from exc
+
+    return shape, STRtree
+
+
+def _strtree_query_indices(tree: Any, geometry: Any, geometries: list[Any]) -> list[int]:
+    """
+    Query an STRtree and return integer indices into `geometries`.
+
+    Handles both STRtree.query() return shapes across shapely versions:
+        - shapely>=2.0: an array-like of integer positions into the list
+          the tree was built from.
+        - shapely<2.0: a list of the matched geometry objects themselves,
+          not indices - resolved back to positions by identity, since the
+          tree stores references to the exact objects it was built from.
+    """
+    result = tree.query(geometry)
+
+    if len(result) == 0:
+        return []
+
+    first = result[0]
+
+    if hasattr(first, "geom_type"):
+        id_to_index = {id(g): i for i, g in enumerate(geometries)}
+        return [id_to_index[id(g)] for g in result if id(g) in id_to_index]
+
+    return [int(i) for i in result]
+
+
 def _shapely_predicate(
     source_geometry: dict[str, Any] | None,
     target_geometry: dict[str, Any] | None,
@@ -656,12 +708,72 @@ def spatial_join_features(
     failed_pair_count = 0
     dropped_failed_count = 0
 
+    # Spatial-index fast path: an STRtree of target geometries narrows the
+    # O(n*m) naive double loop down to O(n*log(m) + m*log(m)) by ruling out
+    # target features whose bbox cannot possibly satisfy any predicate
+    # against a given source feature's bbox (a necessary condition for
+    # intersects/within/contains alike), before the exact predicate is
+    # evaluated on the surviving candidates only. Only attempted when the
+    # engine can use shapely at all, and only used when every target
+    # geometry is a valid, parseable dict - any invalid target bails the
+    # whole call back to the naive loop below, which already handles a
+    # malformed geometry per-pair via _evaluate_predicate's own try/except
+    # (failed_pair_count), so that edge case's behavior is unaffected.
+    shape_fn = None
+    target_tree = None
+    target_geometries: list[Any] = []
+
+    if final_engine in ("shapely", "auto"):
+        try:
+            shape_fn, STRtree = _get_strtree_tools()
+            built_target_geometries: list[Any] = []
+            all_targets_valid = True
+
+            for target_feature in target_items:
+                geometry = target_feature.get("geometry")
+                if not isinstance(geometry, dict):
+                    all_targets_valid = False
+                    break
+                try:
+                    built_target_geometries.append(shape_fn(geometry))
+                except Exception:
+                    all_targets_valid = False
+                    break
+
+            if all_targets_valid and built_target_geometries:
+                target_geometries = built_target_geometries
+                target_tree = STRtree(target_geometries)
+        except SDKDependencyError:
+            target_tree = None
+
     for source_index, source_feature in enumerate(source_items):
         matches: list[tuple[int, dict[str, Any], str]] = []
         last_engine_used = final_engine
         last_error: str | None = None
 
-        for target_index, target_feature in enumerate(target_items):
+        candidate_target_indices: list[int] | None = None
+
+        if target_tree is not None:
+            source_geometry = source_feature.get("geometry")
+            source_geom = None
+
+            if isinstance(source_geometry, dict):
+                try:
+                    source_geom = shape_fn(source_geometry)
+                except Exception:
+                    source_geom = None
+
+            if source_geom is not None:
+                candidate_target_indices = _strtree_query_indices(
+                    target_tree, source_geom, target_geometries
+                )
+
+        if candidate_target_indices is not None:
+            target_pairs = [(i, target_items[i]) for i in candidate_target_indices]
+        else:
+            target_pairs = list(enumerate(target_items))
+
+        for target_index, target_feature in target_pairs:
             pair_count += 1
 
             try:
@@ -758,6 +870,7 @@ def spatial_join_features(
         "operation": "spatial_join",
         "engine_requested": final_engine,
         "engines_used": sorted(engines_used),
+        "spatial_index_used": target_tree is not None,
         "predicate": final_predicate,
         "join_type": final_join_type,
         "cardinality": final_cardinality,

{smart_spatial_system-0.2.7 → smart_spatial_system-0.2.9}/pyproject.toml

@@ -12,7 +12,7 @@ build-backend = "setuptools.build_meta"
 # "Open design questions" for why a namespace migration was deliberately
 # not done here.
 name = "smart_spatial_system"
-version = "0.2.7"
+version = "0.2.9"
 description = "Plugin-based GeoAI backend: natural-language questions become QuerySpecs, DAG plans, and map/table/report outputs."
 readme = "README.md"
 requires-python = ">=3.11"

{smart_spatial_system-0.2.7 → smart_spatial_system-0.2.9}/smart_spatial_system.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: smart_spatial_system
-Version: 0.2.7
+Version: 0.2.9
 Summary: Plugin-based GeoAI backend: natural-language questions become QuerySpecs, DAG plans, and map/table/report outputs.
 Author: Araz Shah
 License-Expression: MIT

{smart_spatial_system-0.2.7 → smart_spatial_system-0.2.9}/smart_spatial_system.egg-info/SOURCES.txt

@@ -421,6 +421,8 @@ tests/test_service_structured_error_normalization.py
 tests/test_slope_aspect.py
 tests/test_spatial_intersection.py
 tests/test_spatial_join.py
+tests/test_spatial_join_ring_buffer_cardinality.py
+tests/test_spatial_join_strtree_performance.py
 tests/test_spatial_query_filter.py
 tests/test_spectral_indices.py
 tests/test_system_status_query_handler.py

smart_spatial_system-0.2.9/tests/test_spatial_join_ring_buffer_cardinality.py

@@ -0,0 +1,215 @@
+"""
+Regression tests for the spatial_join cardinality / overlapping-ring-buffer
+undercounting bug found in the smart-spatial-tehran-tod-gradient case
+study.
+
+spatial_join_features defaults params.cardinality to "first": a source
+feature matching several target features is only joined to the first one
+found, not all of them. When the target layer is a ring_buffer output (or
+any layer with multiple zones generated from separate input features),
+those zones routinely overlap - so a source feature inside more than one
+zone is silently undercounted with the default.
+
+Two things are tested here:
+    1. The underlying plugin behavior itself: with cardinality="first"
+       (the default), a point inside two overlapping station rings is
+       only counted once; with cardinality="one_to_many" it is counted
+       once per matching ring/station, as it should be.
+    2. That LLMQuerySpecGenerator.generate() now defaults cardinality to
+       "one_to_many" automatically when a spatial_join's target traces
+       back to a ring_buffer op and the caller left cardinality unset -
+       so this is fixed at the system level, not just documented in the
+       prompt.
+
+Run:
+    pytest tests/test_spatial_join_ring_buffer_cardinality.py -v
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import pytest
+
+PROJECT_ROOT = Path(__file__).resolve().parents[1]
+if str(PROJECT_ROOT) not in sys.path:
+    sys.path.insert(0, str(PROJECT_ROOT))
+
+pytest.importorskip("shapely")
+
+from orchestrator.planning.llm_spec_generator import (  # noqa: E402
+    LLMQuerySpecGenerator,
+    StaticLLMClient,
+)
+from plugins.ring_buffer_analysis import generate_ring_buffers  # noqa: E402
+from plugins.spatial_join import spatial_join_features  # noqa: E402
+
+
+def _two_overlapping_stations():
+    return [
+        {
+            "type": "Feature",
+            "geometry": {"type": "Point", "coordinates": [0.0, 0.0]},
+            "properties": {"station_id": "A"},
+        },
+        {
+            "type": "Feature",
+            "geometry": {"type": "Point", "coordinates": [1000.0, 0.0]},
+            "properties": {"station_id": "B"},
+        },
+    ]
+
+
+def _amenity_point_between_them():
+    return [
+        {
+            "type": "Feature",
+            "geometry": {"type": "Point", "coordinates": [500.0, 0.0]},
+            "properties": {"amenity_id": "cafe-1"},
+        }
+    ]
+
+
+# ------------------------------------------------------------------ #
+# 1. Plugin-level behavior: cardinality="first" undercounts overlapping
+#    ring-buffer zones; cardinality="one_to_many" does not.
+# ------------------------------------------------------------------ #
+
+def test_default_cardinality_undercounts_a_point_in_two_overlapping_rings():
+    stations = _two_overlapping_stations()
+    amenity = _amenity_point_between_them()
+
+    rings = generate_ring_buffers(
+        features=stations,
+        distances=[1200],
+        engine="shapely",
+    )
+
+    # Sanity check on the fixture: the amenity point (500m from each
+    # station, stations 1000m apart) must fall inside BOTH 1200m rings.
+    assert rings.metadata["output_feature_count"] == 2
+
+    joined = spatial_join_features(
+        source_features=amenity,
+        target_features=rings,
+        predicate="within",
+        # cardinality intentionally omitted - exercising the plugin's
+        # own default ("first").
+    )
+
+    assert joined.metadata["cardinality"] == "first"
+    assert len(joined.features) == 1
+
+    matched_station_ids = {
+        f["properties"]["_joined_target_properties"]["station_id"]
+        for f in joined.features
+    }
+    assert len(matched_station_ids) == 1
+
+
+def test_one_to_many_cardinality_counts_the_point_for_every_overlapping_ring():
+    stations = _two_overlapping_stations()
+    amenity = _amenity_point_between_them()
+
+    rings = generate_ring_buffers(
+        features=stations,
+        distances=[1200],
+        engine="shapely",
+    )
+
+    joined = spatial_join_features(
+        source_features=amenity,
+        target_features=rings,
+        predicate="within",
+        cardinality="one_to_many",
+        include_target_properties=True,
+    )
+
+    assert joined.metadata["cardinality"] == "one_to_many"
+    assert len(joined.features) == 2
+
+    matched_station_ids = {
+        f["properties"]["_joined_target_properties"]["station_id"]
+        for f in joined.features
+    }
+    assert matched_station_ids == {"A", "B"}
+
+
+# ------------------------------------------------------------------ #
+# 2. LLMQuerySpecGenerator: cardinality auto-defaults to "one_to_many"
+#    when spatial_join's target traces back to ring_buffer and the
+#    caller left cardinality unset.
+# ------------------------------------------------------------------ #
+
+def _tod_gradient_spec_json(*, include_cardinality: bool) -> dict:
+    join_params = {"predicate": "within", "include_target_properties": True}
+    if include_cardinality:
+        join_params["cardinality"] = "first"
+
+    return {
+        "raw_query": "for each amenity point, which station rings does it fall into",
+        "goal": "tod_gradient",
+        "entities": [
+            {"ref": "amenity", "kind": "vector"},
+            {"ref": "stations", "kind": "vector"},
+        ],
+        "operations": [
+            {
+                "op": "crs_transform",
+                "inputs": {"vector": "amenity"},
+                "params": {"source_crs": "EPSG:4326", "target_crs": "EPSG:32639"},
+                "output": "amenity_metric",
+            },
+            {
+                "op": "crs_transform",
+                "inputs": {"vector": "stations"},
+                "params": {"source_crs": "EPSG:4326", "target_crs": "EPSG:32639"},
+                "output": "stations_metric",
+            },
+            {
+                "op": "ring_buffer",
+                "inputs": {"vector": "stations_metric"},
+                "params": {"distances": [200, 500, 800, 1200]},
+                "output": "stations_rings",
+            },
+            {
+                "op": "spatial_join",
+                "inputs": {"source": "amenity_metric", "target": "stations_rings"},
+                "params": join_params,
+                "output": "amenity_with_zone",
+            },
+        ],
+        "outputs": [
+            {"kind": "vector_layer", "source": "amenity_with_zone", "config": {}}
+        ],
+    }
+
+
+def test_generate_defaults_cardinality_to_one_to_many_for_ring_buffer_target():
+    llm_json = _tod_gradient_spec_json(include_cardinality=False)
+
+    client = StaticLLMClient(json.dumps(llm_json, ensure_ascii=False))
+    generator = LLMQuerySpecGenerator(client)
+
+    spec = generator.generate(
+        "for each amenity point, which station rings does it fall into"
+    )
+
+    join_op = next(op for op in spec.operations if op.op == "spatial_join")
+    assert join_op.params["cardinality"] == "one_to_many"
+
+
+def test_generate_does_not_override_an_explicit_cardinality():
+    llm_json = _tod_gradient_spec_json(include_cardinality=True)
+
+    client = StaticLLMClient(json.dumps(llm_json, ensure_ascii=False))
+    generator = LLMQuerySpecGenerator(client)
+
+    spec = generator.generate(
+        "for each amenity point, which station rings does it fall into"
+    )
+
+    join_op = next(op for op in spec.operations if op.op == "spatial_join")
+    assert join_op.params["cardinality"] == "first"