smart-spatial-system 0.2.0__tar.gz → 0.2.2__tar.gz

{smart_spatial_system-0.2.0/smart_spatial_system.egg-info → smart_spatial_system-0.2.2}/PKG-INFO

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

@@ -971,9 +971,34 @@ Return ONLY one JSON object with this shape:
 """
 
 
+def _op_input_roles_reference() -> str:
+    """
+    Every supported operation's required input roles - the exact keys
+    "inputs" must use for that operation - generated directly from
+    OP_CATALOG's input_map rather than hand-written per-operation
+    examples.
+
+    This exists because a hand-written example is exactly how distance_to
+    went undocumented here: "Important mappings" below spells out
+    filter_by_distance, filter_points_in_polygon and enrich_risk by hand,
+    but nobody added an entry when distance_to (source_features/
+    target_features, i.e. inputs "vector"/"target") was added to the
+    catalog, and the LLM repeatedly omitted "target" as a result. Deriving
+    this list from OP_CATALOG means a future operation can't silently go
+    undocumented the same way.
+    """
+    lines = []
+    for name in list_supported_ops():
+        roles = list(get_op(name).input_map)
+        role_desc = ", ".join(roles) if roles else "(none)"
+        lines.append(f"- {name}: inputs keys = {{{role_desc}}}")
+    return "\n".join(lines)
+
+
 def _domain_guidance() -> str:
     supported = ", ".join(list_supported_ops())
     pending = ", ".join(list_pending_ops())
+    input_roles = _op_input_roles_reference()
 
     return f"""
 You are a planning assistant for a smart spatial analysis system.
@@ -988,6 +1013,12 @@ Your job:
 Supported operations:
 {supported}
 
+Every operation REQUIRES exactly these "inputs" keys - an operation with a
+missing key fails to plan. This list is generated from the operation
+catalog itself, so trust it over any example below if the two ever
+disagree:
+{input_roles}
+
 Pending operations, not executable yet:
 {pending}
 
@@ -1021,6 +1052,45 @@ Important mappings:
 - "score/rank":
   use score_features then rank_features.
 
+- 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
+  original base vector. score_features.inputs.vector must be the output of
+  the LAST computation in the chain - the only ref that actually carries
+  every field the scoring factors reference. A score_features op reading
+  from the base vector, or from any computation earlier than the last one,
+  is missing every field computed after that point, and every factor
+  referencing a missing field silently scores 0 - this does not raise an
+  error, so a degenerate all-zero/near-zero score on every feature is a
+  sign this happened.
+
+  WRONG - three computations all read "sites", so only one field ever
+  reaches score_features:
+    spatial_nearest(source="sites", target="metro") -> "sites_with_metro"
+    spatial_nearest(source="sites", target="schools") -> "sites_with_schools"
+    spatial_nearest(source="sites", target="parks") -> "sites_with_parks"
+    score_features(vector="sites") - WRONG: none of the three computed
+      distance fields are on "sites" itself.
+
+  CORRECT - each step reads the PREVIOUS step's output, so fields
+  accumulate onto one ref:
+    spatial_nearest(source="sites", target="metro",
+      params={{"distance_field": "distance_to_metro"}}) -> "sites_with_metro"
+    spatial_nearest(source="sites_with_metro", target="schools",
+      params={{"distance_field": "distance_to_schools"}}) -> "sites_with_schools"
+    spatial_nearest(source="sites_with_schools", target="parks",
+      params={{"distance_field": "distance_to_parks"}}) -> "sites_with_parks"
+    score_features(vector="sites_with_parks") - CORRECT: this ref alone
+      carries distance_to_metro, distance_to_schools AND distance_to_parks,
+      because each step's "source" was the previous step's output, not
+      "sites" again. Set params.distance_field on each spatial_nearest call
+      so the fields get distinct names instead of overwriting each other.
+
+  If two computations genuinely cannot be chained (they operate on
+  unrelated feature sets that must be merged by a shared key rather than
+  by being the same features), use join_feature_properties to merge them
+  before scoring instead of chaining.
+
 - If user asks for PDF/report but report plugin is not executable yet:
   include outputs with kind="report", format="pdf".
   Do not invent unsupported operation nodes.
@@ -1109,64 +1179,6 @@ def build_llm_messages(
     ]
 
 
-def _default_real_estate_scoring_spec() -> dict[str, Any]:
-    """
-    Default MVP scoring spec for real-estate ranking.
-
-    This is used as a safety fallback when LLM correctly asks for scoring
-    but forgets to provide scoring_spec.
-
-    Notes:
-        - Some fields may be created by previous plugins or future enrichment plugins.
-        - Missing fields simply receive factor score 0 by score_features.
-    """
-    return {
-        "output_field": "investment_score",
-        "scale": 100,
-        "normalize_weights": True,
-        "factors": [
-            {
-                "name": "near_poi",
-                "field": "distance_to_poi",
-                "type": "inverse_distance",
-                "max_distance": 500,
-                "weight": 0.30,
-            },
-            {
-                "name": "inside_buildable_zone",
-                "field": "inside_buildable_zone",
-                "type": "boolean",
-                "weight": 0.25,
-            },
-            {
-                "name": "near_main_road",
-                "field": "distance_to_road",
-                "type": "inverse_distance",
-                "max_distance": 1000,
-                "weight": 0.20,
-            },
-            {
-                "name": "low_flood_risk",
-                "field": "flood_risk",
-                "type": "risk_level",
-                "weight": 0.10,
-            },
-            {
-                "name": "low_earthquake_risk",
-                "field": "earthquake_risk",
-                "type": "risk_level",
-                "weight": 0.10,
-            },
-            {
-                "name": "low_fire_risk",
-                "field": "fire_risk",
-                "type": "risk_level",
-                "weight": 0.05,
-            },
-        ],
-    }
-
-
 def _semantic_distance_field(reference_ref: str) -> str:
     """
     Pick a semantic distance field based on the reference entity/output name.
@@ -1216,6 +1228,16 @@ def normalize_llm_query_spec_for_planning(spec: QuerySpec) -> QuerySpec:
 
     # Inject enrichment only when LLM did not provide its own scoring spec.
     # This keeps old explicit LLM specs stable, but improves weak/missing specs.
+    #
+    # NOTE: since a score_features op missing scoring_spec/factors now
+    # raises (see below) instead of getting a default injected, this flag
+    # can only be True for a spec that is about to raise before this
+    # function returns - so the enrichment-injection code below it is
+    # currently unreachable in any spec that completes normally. Left in
+    # place rather than removed with this fix: ripping it out means also
+    # removing _semantic_distance_field and updating the tests that
+    # exercise it, which is a larger, separate change from the two bugs
+    # this pass fixes.
     should_inject_enrichment = any(
         op.op == "score_features"
         and "scoring_spec" not in op.params
@@ -1250,8 +1272,23 @@ def normalize_llm_query_spec_for_planning(spec: QuerySpec) -> QuerySpec:
 
         if op.op == "score_features":
             if "scoring_spec" not in clean_params and "factors" not in clean_params:
-                clean_params["scoring_spec"] = _default_real_estate_scoring_spec()
-                repairs.append("added default scoring_spec to score_features")
+                # No safe generic default exists here: this used to inject
+                # a hardcoded real-estate scoring_spec (investment_score,
+                # inside_buildable_zone, flood_risk, ...) into ANY
+                # score_features op that omitted one, regardless of the
+                # query's actual domain. For a non-real-estate query that
+                # silently produced a nonsense score column, or crashed
+                # downstream when those fields didn't exist on the data -
+                # indistinguishable from a real real-estate query's own
+                # valid output. The LLM must describe its own domain's
+                # scoring, or this fails loudly right here instead.
+                raise LLMSpecGenerationError(
+                    f"score_features operation (output={op.output!r}) has "
+                    "neither 'scoring_spec' nor 'factors'. There is no "
+                    "domain-neutral default to fall back to - the LLM must "
+                    "supply a complete scoring specification for its own "
+                    "query."
+                )
 
             scoring_spec = clean_params.get("scoring_spec")
             if isinstance(scoring_spec, dict):
@@ -1495,11 +1532,18 @@ def _inject_report_pipeline(spec: QuerySpec) -> tuple[QuerySpec, list[str]]:
     """
     repairs: list[str] = []
 
-    # Find the last rank_features output.
+    # Find the last rank_features op, so build_report reuses the score/rank
+    # field names that op actually used - not a hardcoded guess. By this
+    # point base normalization has already ensured rank_features carries
+    # score_field/rank_field (either LLM-provided or defaulted from the
+    # upstream score_features op's own output_field), so these are always
+    # present here.
     last_rank_output: str | None = None
+    last_rank_op: OperationSpec | None = None
     for op in spec.operations:
         if op.op == "rank_features" and op.output:
             last_rank_output = op.output
+            last_rank_op = op
 
     if not last_rank_output:
         # Fallback: use the last operation output.
@@ -1511,6 +1555,16 @@ def _inject_report_pipeline(spec: QuerySpec) -> tuple[QuerySpec, list[str]]:
     if not last_rank_output:
         return spec, []
 
+    # Previously hardcoded to "investment_score"/"rank" regardless of what
+    # the plan's own rank_features op used - a non-real-estate plan (e.g.
+    # score_field="accessibility_score") got a report referencing a column
+    # its data never had.
+    score_field = "score"
+    rank_field = "rank"
+    if last_rank_op is not None:
+        score_field = str(last_rank_op.params.get("score_field") or score_field)
+        rank_field = str(last_rank_op.params.get("rank_field") or rank_field)
+
     new_ops = list(spec.operations)
 
     # build_report node
@@ -1519,8 +1573,8 @@ def _inject_report_pipeline(spec: QuerySpec) -> tuple[QuerySpec, list[str]]:
         op="build_report",
         inputs={"vector": last_rank_output},
         params={
-            "score_field": "investment_score",
-            "rank_field": "rank",
+            "score_field": score_field,
+            "rank_field": rank_field,
         },
         output=report_output,
     ))
@@ -1575,6 +1629,197 @@ def _inject_report_pipeline(spec: QuerySpec) -> tuple[QuerySpec, list[str]]:
 
 
 
+def _validate_operation_input_roles(spec: QuerySpec) -> None:
+    """
+    Validate every operation's inputs against OP_CATALOG's input_map before
+    handing the spec back to the caller.
+
+    DeterministicPlanner.build() already performs this exact check
+    (_map_inputs in planner.py) and raises PlanningError - so a spec that
+    fails this check was always going to fail anyway. Duplicating the
+    check here means it fails right where the spec was generated, as a
+    specific LLMSpecGenerationError naming the missing role, rather than
+    as a generic PlanningError raised later out of the planner - the same
+    failure, several call frames away from its cause, indistinguishable
+    from any other planning error.
+
+    Every input_map key is a required role: the planner has no notion of
+    an optional one today (see the real_estate_spatial_enrich note in
+    op_catalog.py), so this mirrors _map_inputs's missing_roles check
+    exactly rather than inventing separate required/optional semantics.
+    """
+    for op in spec.operations:
+        if not is_supported(op.op):
+            continue
+
+        required_roles = get_op(op.op).input_map
+        missing_roles = [role for role in required_roles if role not in op.inputs]
+
+        if missing_roles:
+            raise LLMSpecGenerationError(
+                f"operation {op.op!r} (output={op.output!r}) is missing "
+                f"required input role(s) {missing_roles!r}. It supplied "
+                f"{sorted(op.inputs)!r}; {op.op!r} requires "
+                f"{sorted(required_roles)!r}."
+            )
+
+
+_NEAREST_OPS_WITH_DISTANCE_FIELD = {"spatial_nearest", "nearest_neighbor", "filter_by_distance"}
+
+
+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, 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")
+
+    if not isinstance(factors, list):
+        scoring_spec = params.get("scoring_spec")
+        if isinstance(scoring_spec, dict):
+            inner = scoring_spec.get("scoring")
+            if isinstance(inner, dict) and isinstance(inner.get("factors"), list):
+                factors = inner["factors"]
+            elif isinstance(scoring_spec.get("factors"), list):
+                factors = scoring_spec["factors"]
+
+    if not isinstance(factors, list):
+        return []
+
+    return [
+        str(factor["field"])
+        for factor in factors
+        if isinstance(factor, dict) and factor.get("field")
+    ]
+
+
+def _op_declared_output_fields(op: OperationSpec) -> list[str]:
+    """
+    Field names an operation declares it writes, from the two mechanisms
+    the system currently has for naming a computed field: an explicit
+    "distance_field" param (spatial_nearest/nearest_neighbor/
+    filter_by_distance), or enrich_feature_properties's rule targets.
+
+    Deliberately narrow: these are the only field-naming mechanisms an LLM
+    plan can currently use, so this stays a precise signal rather than a
+    guess. An op not covered here is simply not a candidate producer -
+    see _validate_score_features_field_chaining's docstring for why that
+    makes this check conservative rather than exhaustive.
+    """
+    if op.op in _NEAREST_OPS_WITH_DISTANCE_FIELD:
+        field = op.params.get("distance_field")
+        return [str(field)] if field else []
+
+    if op.op == "enrich_feature_properties":
+        rules = op.params.get("rules")
+        if isinstance(rules, list):
+            return [
+                str(rule["target"])
+                for rule in rules
+                if isinstance(rule, dict) and rule.get("target")
+            ]
+
+    return []
+
+
+def _ancestor_refs(start_ref: str, ops_by_output: dict[str, OperationSpec]) -> set[str]:
+    """
+    Every ref start_ref transitively depends on, by walking operation
+    inputs backward. Stops at any ref that isn't a known operation output
+    (an entity or an initial input), rather than erroring - this function
+    only needs to answer "was this ref produced upstream of start_ref?".
+    """
+    seen: set[str] = set()
+    stack = [start_ref]
+
+    while stack:
+        ref = stack.pop()
+        if ref in seen:
+            continue
+        seen.add(ref)
+
+        op = ops_by_output.get(ref)
+        if op is None:
+            continue
+
+        for dependency_ref in op.inputs.values():
+            if dependency_ref not in seen:
+                stack.append(str(dependency_ref))
+
+    return seen
+
+
+def _validate_score_features_field_chaining(spec: QuerySpec) -> None:
+    """
+    Catch a score_features op reading from a ref that never accumulated a
+    field its own scoring factors need.
+
+    This is the fan-out/chaining gap: an LLM asked to score against
+    distance to several different amenities routinely computes each
+    distance as its own operation off the SAME original vector (a fan-out)
+    instead of chaining each computation onto the previous one's output
+    (an accumulating chain - see the worked example in _domain_guidance).
+    The result plans and executes without error - every required input
+    role is present - but every factor referencing a field that landed on
+    a sibling branch instead of the scored ref silently scores 0. A
+    all-zero/degenerate score on every feature is exactly what that looks
+    like from the outside, with no exception to point at the cause.
+
+    Deliberately conservative to avoid false positives: only fields this
+    module can trace to a specific producing operation (see
+    _op_declared_output_fields) are checked. A factor field that already
+    exists on the raw input data, or that this function doesn't recognize
+    as a producible field, is left unvalidated rather than guessed at -
+    under-catching is the safe failure mode for a check like this, not
+    over-catching.
+    """
+    ops_by_output: dict[str, OperationSpec] = {
+        op.output: op for op in spec.operations if op.output
+    }
+
+    field_producers: dict[str, list[OperationSpec]] = {}
+    for op in spec.operations:
+        for field in _op_declared_output_fields(op):
+            field_producers.setdefault(field, []).append(op)
+
+    for op in spec.operations:
+        if op.op != "score_features":
+            continue
+
+        needed_fields = _extract_scoring_factor_fields(op.params)
+        if not needed_fields:
+            continue
+
+        scored_ref = op.inputs.get("vector")
+        if not scored_ref:
+            continue
+
+        ancestors = _ancestor_refs(str(scored_ref), ops_by_output)
+
+        for field in needed_fields:
+            producers = field_producers.get(field)
+            if not producers:
+                # Not a field this module can trace to an operation -
+                # could be a pre-existing attribute on the raw data.
+                continue
+
+            if not any(producer.output in ancestors for producer in producers):
+                producer_outputs = [p.output for p in producers]
+                raise LLMSpecGenerationError(
+                    f"score_features (output={op.output!r}) scores on field "
+                    f"{field!r}, but that field is produced by "
+                    f"{producer_outputs!r}, none of which is chained into "
+                    f"its input {scored_ref!r} (or anything {scored_ref!r} "
+                    "depends on). Each computed field must be chained onto "
+                    "the previous operation's output before scoring - see "
+                    "the 'scoring against MORE THAN ONE computed field' "
+                    "guidance - otherwise this field is silently absent and "
+                    "its factor scores 0 for every feature."
+                )
+
+
 class LLMQuerySpecGenerator:
     def __init__(
         self,
@@ -1621,7 +1866,10 @@ class LLMQuerySpecGenerator:
         data = _pre_normalize_query_spec_json(data, context=context)
 
         spec = query_spec_from_dict(data, raw_query_fallback=raw_query)
-        return normalize_llm_query_spec_for_planning(spec)
+        spec = normalize_llm_query_spec_for_planning(spec)
+        _validate_operation_input_roles(spec)
+        _validate_score_features_field_chaining(spec)
+        return spec
 
 
 # ------------------------------------------------------------------ #

{smart_spatial_system-0.2.0 → smart_spatial_system-0.2.2}/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.0"
+version = "0.2.2"
 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.0 → smart_spatial_system-0.2.2/smart_spatial_system.egg-info}/PKG-INFO

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