smart-spatial-system 0.2.3__tar.gz → 0.2.4__tar.gz

{smart_spatial_system-0.2.3/smart_spatial_system.egg-info → smart_spatial_system-0.2.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: smart_spatial_system
-Version: 0.2.3
+Version: 0.2.4
 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.3 → smart_spatial_system-0.2.4}/orchestrator/planning/llm_spec_generator.py

@@ -1071,6 +1071,21 @@ Important mappings:
 - "score/rank":
   use score_features then rank_features.
 
+- CRITICAL - every scoring factor MUST include an explicit "type". There is
+  NO default - a factor with no "type" is rejected, it does not fall back
+  to anything. (An earlier version of this system defaulted a missing
+  "type" to "boolean" silently; for a distance field that meant every
+  score came out 0.0 for every feature, with no error - that default no
+  longer exists.) Valid types: "boolean", "boolean_bonus",
+  "inverse_distance", "risk_level", "inverse_level", "threshold",
+  "condition", "direct", "numeric", "inverse_numeric". A distance field
+  (anything you computed with spatial_nearest/nearest_neighbor/distance_to)
+  needs "type": "inverse_distance" and a numeric "max_distance":
+    {{"name": "near_metro", "field": "distance_to_metro",
+      "type": "inverse_distance", "max_distance": 800, "weight": 1}}
+  WRONG (missing "type" - rejected, not defaulted):
+    {{"field": "distance_to_metro", "weight": -1}}
+
 - CRITICAL - scoring against MORE THAN ONE computed field (e.g. distance to
   several different amenities/references): each computation must be CHAINED
   onto the previous one's output, not all computed separately from the
@@ -1686,12 +1701,12 @@ def _validate_operation_input_roles(spec: QuerySpec) -> None:
 _NEAREST_OPS_WITH_DISTANCE_FIELD = {"spatial_nearest", "nearest_neighbor", "filter_by_distance"}
 
 
-def _extract_scoring_factor_fields(params: dict[str, Any]) -> list[str]:
+def _extract_scoring_factors(params: dict[str, Any]) -> list[dict[str, Any]]:
     """
-    Pull the "field" name out of every factor a score_features op's
-    params declare, across the shapes _normalize_scoring_spec (in
-    plugins/feature_scoring.py) accepts: top-level "factors", or
-    "scoring_spec.factors", or the older nested "scoring_spec.scoring.factors".
+    Pull the raw factor dicts out of a score_features op's params, across
+    the shapes _normalize_scoring_spec (in plugins/feature_scoring.py)
+    accepts: top-level "factors", or "scoring_spec.factors", or the older
+    nested "scoring_spec.scoring.factors".
     """
     factors = params.get("factors")
 
@@ -1707,10 +1722,19 @@ def _extract_scoring_factor_fields(params: dict[str, Any]) -> list[str]:
     if not isinstance(factors, list):
         return []
 
+    return [factor for factor in factors if isinstance(factor, dict)]
+
+
+def _extract_scoring_factor_fields(params: dict[str, Any]) -> list[str]:
+    """
+    Pull the "field" name out of every factor a score_features op's
+    params declare - see _extract_scoring_factors for the shapes this
+    covers.
+    """
     return [
         str(factor["field"])
-        for factor in factors
-        if isinstance(factor, dict) and factor.get("field")
+        for factor in _extract_scoring_factors(params)
+        if factor.get("field")
     ]
 
 
@@ -1770,6 +1794,64 @@ def _ancestor_refs(start_ref: str, ops_by_output: dict[str, OperationSpec]) -> s
     return seen
 
 
+# Kept in sync by hand with plugins/feature_scoring.py's _score_factor -
+# there is no single source of truth to generate this from (unlike
+# OP_CATALOG for operations), so a new factor type added there needs
+# adding here too.
+_VALID_SCORING_FACTOR_TYPES = {
+    "boolean",
+    "boolean_bonus",
+    "inverse_distance",
+    "risk_level",
+    "inverse_level",
+    "threshold",
+    "condition",
+    "direct",
+    "numeric",
+    "inverse_numeric",
+}
+
+
+def _validate_score_features_factor_types(spec: QuerySpec) -> None:
+    """
+    Catch a score_features factor with no "type" before the plan is
+    returned, not when it silently scores everything 0.0.
+
+    plugins/feature_scoring.py's _score_factor has no default for a
+    missing "type" (it raises) - but that only fires at execution time,
+    several steps and possibly minutes of API-billed retries away from
+    the generation step that produced the bad spec. This catches the
+    identical condition immediately, with the same "there is no safe
+    default" reasoning, right where the LLM's output is still available
+    to name in the error.
+    """
+    for op in spec.operations:
+        if op.op != "score_features":
+            continue
+
+        for factor in _extract_scoring_factors(op.params):
+            factor_type = factor.get("type")
+            field_name = factor.get("field") or factor.get("name") or "<unnamed>"
+
+            if not factor_type:
+                raise LLMSpecGenerationError(
+                    f"score_features (output={op.output!r}) has a factor "
+                    f"for field {field_name!r} with no 'type'. There is no "
+                    "safe default - every factor must specify one "
+                    f"explicitly: {sorted(_VALID_SCORING_FACTOR_TYPES)!r}. "
+                    "A distance field almost always wants "
+                    "'inverse_distance' with 'max_distance' set."
+                )
+
+            if factor_type not in _VALID_SCORING_FACTOR_TYPES:
+                raise LLMSpecGenerationError(
+                    f"score_features (output={op.output!r}) has a factor "
+                    f"for field {field_name!r} with unsupported type "
+                    f"{factor_type!r}. Valid types: "
+                    f"{sorted(_VALID_SCORING_FACTOR_TYPES)!r}."
+                )
+
+
 def _validate_score_features_field_chaining(spec: QuerySpec) -> None:
     """
     Catch a score_features op reading from a ref that never accumulated a
@@ -1854,25 +1936,48 @@ def _crs_transform_target_crs(
     ref: str, ops_by_output: dict[str, OperationSpec]
 ) -> str | None:
     """
-    The target_crs a ref was reprojected to, if ref is literally the
-    output of a crs_transform operation - None otherwise (ref is a raw
-    entity, or the output of some other operation).
-
-    Deliberately not a full ancestor walk (contrast _ancestor_refs): this
-    only recognizes reprojection immediately before the distance op, which
-    is exactly the shape both the correct pattern
-    (accessibility_query_spec.py) and the observed bug produce - crs_transform
-    feeding straight into the distance operation. Walking further back
-    would let this claim to know a ref's CRS through operations that don't
-    preserve one (a join, a filter combining two layers), which is a
-    guess this module has no basis for making.
+    The target_crs a ref was reprojected to - either directly (ref is the
+    output of a crs_transform operation), or inherited by walking back
+    through a chain of distance/nearest-neighbor operations on their
+    source side, since those operations don't reproject and so preserve
+    whatever CRS their source input was already in.
+
+    That chain-walk matters for exactly the case
+    accessibility_query_spec.py's own multi-amenity chain produces (and
+    any equivalent LLM-generated chain): only the FIRST spatial_nearest
+    step's source is directly a crs_transform output -
+    "sites_metric" -> spatial_nearest(metro) -> "sites_with_metro" ->
+    spatial_nearest(schools, source="sites_with_metro") -> ... - every
+    later step's source is the previous step's output, not a
+    crs_transform output. An earlier version of this function checked
+    only the literal ref and treated every one of those later steps as
+    "not traceable", which made this validator raise on a plan that was
+    completely correct - caught by testing this exact function against
+    accessibility_query_spec.py's own generated chain, not by inspection.
+
+    Still deliberately narrow on the OTHER side, though: this only walks
+    through the vector-preserving "source" role of a chain of distance
+    ops, never through a join, a filter combining two layers, or any
+    other operation that doesn't obviously preserve a single input's CRS -
+    those remain untraceable (None), which is the conservative direction
+    to be wrong in.
     """
     op = ops_by_output.get(ref)
-    if op is None or op.op != "crs_transform":
+    if op is None:
         return None
 
-    target_crs = op.params.get("target_crs")
-    return str(target_crs) if target_crs else None
+    if op.op == "crs_transform":
+        target_crs = op.params.get("target_crs")
+        return str(target_crs) if target_crs else None
+
+    roles = _DISTANCE_OPS_VECTOR_ROLES.get(op.op)
+    if roles is not None:
+        this_role, _other_role = roles
+        upstream_ref = op.inputs.get(this_role)
+        if upstream_ref:
+            return _crs_transform_target_crs(str(upstream_ref), ops_by_output)
+
+    return None
 
 
 def _validate_distance_op_crs_symmetry(spec: QuerySpec) -> None:
@@ -1982,6 +2087,7 @@ class LLMQuerySpecGenerator:
         spec = query_spec_from_dict(data, raw_query_fallback=raw_query)
         spec = normalize_llm_query_spec_for_planning(spec)
         _validate_operation_input_roles(spec)
+        _validate_score_features_factor_types(spec)
         _validate_score_features_field_chaining(spec)
         _validate_distance_op_crs_symmetry(spec)
         return spec

{smart_spatial_system-0.2.3 → smart_spatial_system-0.2.4}/plugins/feature_scoring.py

@@ -228,7 +228,29 @@ def _score_factor(properties: dict[str, Any], factor: dict[str, Any]) -> tuple[f
     if not isinstance(factor, dict):
         raise ValueError("Each scoring factor must be a dict.")
 
-    factor_type = str(factor.get("type") or "boolean")
+    raw_factor_type = factor.get("type")
+    if not raw_factor_type:
+        # A missing "type" used to default to "boolean" silently. For any
+        # factor scoring a non-boolean field - a distance, most commonly -
+        # that produces a wrong, near-constant score (0.0 whenever the
+        # field is falsy, which for a distance means "exactly zero") with
+        # no error at all: this is how a whole batch of LLM-generated
+        # scoring specs that omitted "type" on a distance factor came out
+        # 0.0 for every feature, indistinguishable from a real degenerate
+        # result. "boolean" is a valid, explicit choice (still supported
+        # below) - it must never be the unstated default for a field whose
+        # actual meaning this function has no way to guess.
+        field_name = factor.get("field") or factor.get("name") or "<unnamed>"
+        raise ValueError(
+            f"Scoring factor for field {field_name!r} has no 'type'. There "
+            "is no safe default - specify one explicitly: 'boolean', "
+            "'boolean_bonus', 'inverse_distance', 'risk_level', "
+            "'inverse_level', 'threshold', 'condition', 'direct', "
+            "'numeric', or 'inverse_numeric'. A distance field almost "
+            "always wants 'inverse_distance' with 'max_distance' set."
+        )
+
+    factor_type = str(raw_factor_type)
     name = str(factor.get("name") or factor.get("field") or factor_type)
     field = str(factor.get("field") or "")
     value = _get_property(properties, field) if field else None

{smart_spatial_system-0.2.3 → smart_spatial_system-0.2.4}/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.3"
+version = "0.2.4"
 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.3 → smart_spatial_system-0.2.4/smart_spatial_system.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: smart_spatial_system
-Version: 0.2.3
+Version: 0.2.4
 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.3 → smart_spatial_system-0.2.4}/tests/test_feature_scoring.py

@@ -1,6 +1,8 @@
 import sys
 from pathlib import Path
 
+import pytest
+
 ROOT = Path(__file__).resolve().parents[1]
 if str(ROOT) not in sys.path:
     sys.path.insert(0, str(ROOT))
@@ -115,3 +117,45 @@ def test_op_catalog_contains_feature_scoring_ops():
 
     assert score_op.capability_name == "score_features"
     assert rank_op.capability_name == "rank_features"
+
+
+# ------------------------------------------------------------------ #
+# Missing "type" on a scoring factor: no silent default
+# ------------------------------------------------------------------ #
+
+def test_score_features_raises_when_a_factor_has_no_type():
+    """
+    Regression test: a missing "type" used to default to "boolean"
+    silently. For a distance field, _truthy(0.0) is False and
+    _truthy(any nonzero distance) is True, so every feature ended up with
+    a near-constant, meaningless score instead of an error - exactly how
+    a full batch of LLM-generated scoring specs that omitted "type" on a
+    distance factor came out 0.0 for every feature.
+    """
+    spec = {
+        "output_field": "score",
+        "factors": [
+            {"field": "distance_to_poi", "weight": 1},
+        ],
+    }
+
+    with pytest.raises(ValueError, match="distance_to_poi"):
+        score_features(_sample_features(), scoring_spec=spec)
+
+
+def test_score_features_boolean_type_still_works_when_explicit():
+    """
+    "boolean" itself is a perfectly valid, still-supported type - only an
+    UNSTATED type is rejected.
+    """
+    spec = {
+        "output_field": "score",
+        "factors": [
+            {"field": "__in_polygon__", "type": "boolean", "weight": 1},
+        ],
+    }
+
+    result = score_features(_sample_features(), scoring_spec=spec)
+    a = result.features[0]["properties"]
+    b = result.features[1]["properties"]
+    assert a["score"] > b["score"]

{smart_spatial_system-0.2.3 → smart_spatial_system-0.2.4}/tests/test_llm_spec_generator.py

@@ -1306,3 +1306,133 @@ def test_domain_guidance_documents_reprojecting_both_sides_of_a_distance_op():
 
     assert "needs BOTH of" in system_prompt
     assert "target_crs" in system_prompt
+
+
+# ------------------------------------------------------------------ #
+# Bug 6: a scoring factor with no "type" used to default to "boolean"
+# ------------------------------------------------------------------ #
+
+def _multi_amenity_chained_ops(factor_params: dict) -> list[dict]:
+    """
+    The exact plan shape from the reported case: four layers correctly
+    reprojected to the same CRS, three spatial_nearest steps correctly
+    chained (Bug 4's and Bug 5's fixes both satisfied) - only the
+    score_features factors are missing "type".
+    """
+    return [
+        {"op": "crs_transform", "inputs": {"vector": "sites"}, "params": {"target_crs": "EPSG:31256"}, "output": "sites_metric"},
+        {"op": "crs_transform", "inputs": {"vector": "metro"}, "params": {"target_crs": "EPSG:31256"}, "output": "metro_metric"},
+        {"op": "crs_transform", "inputs": {"vector": "schools"}, "params": {"target_crs": "EPSG:31256"}, "output": "schools_metric"},
+        {"op": "crs_transform", "inputs": {"vector": "parks"}, "params": {"target_crs": "EPSG:31256"}, "output": "parks_metric"},
+        {"op": "spatial_nearest", "inputs": {"source": "sites_metric", "target": "metro_metric"}, "params": {"distance_field": "distance_to_metro"}, "output": "sites_with_metro"},
+        {"op": "spatial_nearest", "inputs": {"source": "sites_with_metro", "target": "schools_metric"}, "params": {"distance_field": "distance_to_schools"}, "output": "sites_with_schools"},
+        {"op": "spatial_nearest", "inputs": {"source": "sites_with_schools", "target": "parks_metric"}, "params": {"distance_field": "distance_to_parks"}, "output": "sites_with_parks"},
+        {
+            "op": "score_features",
+            "inputs": {"vector": "sites_with_parks"},
+            "params": {
+                "factors": [
+                    {"field": "distance_to_metro", **factor_params},
+                    {"field": "distance_to_schools", **factor_params},
+                    {"field": "distance_to_parks", **factor_params},
+                ]
+            },
+            "output": "scored_sites",
+        },
+        {"op": "rank_features", "inputs": {"vector": "scored_sites"}, "params": {"score_field": "score", "rank_field": "rank"}, "output": "ranked_sites"},
+    ]
+
+
+def _multi_amenity_spec_json(factor_params: dict) -> dict:
+    return {
+        "raw_query": "rank sites by accessibility",
+        "goal": "score_accessibility",
+        "entities": [
+            {"ref": "sites", "kind": "vector"},
+            {"ref": "metro", "kind": "vector"},
+            {"ref": "schools", "kind": "vector"},
+            {"ref": "parks", "kind": "vector"},
+        ],
+        "operations": _multi_amenity_chained_ops(factor_params),
+        "outputs": [{"kind": "vector", "source": "ranked_sites"}],
+    }
+
+
+def test_generate_raises_when_a_scoring_factor_has_no_type():
+    """
+    Regression test for the exact reported case: a plan with correct
+    chaining (Bug 4) and correct, symmetric CRS reprojection (Bug 5) still
+    came back degenerate - all 20/20 runs in the batch that surfaced this
+    scored every feature 0.0, because every factor omitted "type" and it
+    silently defaulted to "boolean". Must now raise before the plan is
+    even returned.
+    """
+    llm_json = _multi_amenity_spec_json({"weight": -1})
+
+    client = StaticLLMClient(json.dumps(llm_json, ensure_ascii=False))
+    generator = LLMQuerySpecGenerator(client)
+
+    with pytest.raises(LLMSpecGenerationError, match="no 'type'"):
+        generator.generate("rank sites by accessibility")
+
+
+def test_generate_raises_on_an_unsupported_factor_type():
+    llm_json = _multi_amenity_spec_json({"type": "made_up_type", "weight": 1})
+
+    client = StaticLLMClient(json.dumps(llm_json, ensure_ascii=False))
+    generator = LLMQuerySpecGenerator(client)
+
+    with pytest.raises(LLMSpecGenerationError, match="unsupported type"):
+        generator.generate("rank sites by accessibility")
+
+
+def test_generate_accepts_a_correct_multi_amenity_chain_with_explicit_types():
+    """
+    The fully-correct equivalent of the reported plan: chained, CRS-matched,
+    and every factor carries an explicit type. This is also the regression
+    test for a real false positive found while verifying this fix: an
+    earlier version of _validate_distance_op_crs_symmetry only recognized
+    a ref as reprojected when it was DIRECTLY a crs_transform output, so it
+    incorrectly rejected the second and third spatial_nearest steps in
+    exactly this chain (their source is the previous step's output, not a
+    crs_transform output) - a plan structurally identical to
+    accessibility_query_spec.py's own generated chain.
+    """
+    llm_json = _multi_amenity_spec_json(
+        {"type": "inverse_distance", "max_distance": 1000, "weight": 1}
+    )
+
+    client = StaticLLMClient(json.dumps(llm_json, ensure_ascii=False))
+    spec = LLMQuerySpecGenerator(client).generate("rank sites by accessibility")
+
+    assert [op.op for op in spec.operations] == [
+        "crs_transform",
+        "crs_transform",
+        "crs_transform",
+        "crs_transform",
+        "spatial_nearest",
+        "spatial_nearest",
+        "spatial_nearest",
+        "score_features",
+        "rank_features",
+    ]
+
+    plan = DeterministicPlanner().build(spec)
+    assert [node.capability_name for node in plan.nodes] == [
+        "transform_vector_crs",
+        "transform_vector_crs",
+        "transform_vector_crs",
+        "transform_vector_crs",
+        "find_nearest_neighbors",
+        "find_nearest_neighbors",
+        "find_nearest_neighbors",
+        "score_features",
+        "rank_features",
+    ]
+
+
+def test_domain_guidance_documents_that_factor_type_has_no_default():
+    system_prompt = build_llm_messages("q")[0]["content"]
+
+    assert "NO default" in system_prompt
+    assert "inverse_distance" in system_prompt