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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: smart_spatial_system
-Version: 0.2.7
+Version: 0.2.8
 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.8}/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.8}/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.8"
 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.8}/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.8
 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.8}/smart_spatial_system.egg-info/SOURCES.txt

@@ -421,6 +421,7 @@ 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_query_filter.py
 tests/test_spectral_indices.py
 tests/test_system_status_query_handler.py

smart_spatial_system-0.2.8/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"