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

{smart_spatial_system-0.2.4 → smart_spatial_system-0.2.6}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: smart_spatial_system
-Version: 0.2.4
+Version: 0.2.6
 Summary: Plugin-based GeoAI backend: natural-language questions become QuerySpecs, DAG plans, and map/table/report outputs.
 Author: Araz Shah
 License-Expression: MIT
@@ -49,14 +49,48 @@ Dynamic: license-file
 
 # Smart Spatial System
 
+[![PyPI](https://img.shields.io/pypi/v/smart-spatial-system)](https://pypi.org/project/smart-spatial-system/)
+[![CI](https://github.com/arazshah/smart_spatial_system/actions/workflows/ci.yml/badge.svg)](https://github.com/arazshah/smart_spatial_system/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](pyproject.toml)
+
 **Ask a geospatial question in plain language and get map layers, tables, reports and files back.**
 
+**[s3geo.com](https://s3geo.com)** — project site, plugin catalog and case-study index.
+
 Smart Spatial System is a plugin-based GeoAI backend with a React workbench. A question such as *"rank these candidate properties by distance to metro stations, malls and main roads"* is turned into a structured `QuerySpec`, planned as a DAG of spatial operations, executed by plugins against uploaded files or PostGIS, and returned as map-ready outputs with a full execution trace.
 
+![Running the rule-based accessibility example end to end: the planned DAG, then the ranked output](docs/assets/demo.gif)
+
+Real, unedited terminal output from [`examples/accessibility_analysis.py`](examples/accessibility_analysis.py) — no server, no LLM, deterministic by construction. Run it yourself after installing below.
+
 It is the application built on top of [geochat-platform](https://github.com/arazshah/geochat-platform): plugins are written with `geochat_sdk` and executed through `geochat_kernel`.
 
 > **Status:** published and usable, still refactoring internally. Logic is moving out of `orchestrator/` into the layered `smart_spatial_system/` package (see [docs/ARCHITECTURE_TARGET.md](docs/ARCHITECTURE_TARGET.md)); the `orchestrator/*_service.py` modules are compatibility shims during that move. The public surface - the CLI, the HTTP API and the documented entry points below - is stable.
 
+## Why this, not a general-purpose LLM agent with a GIS tool belt
+
+The natural alternative is: give an LLM function-calling access to some GIS
+functions and let it decide what to call. This project deliberately doesn't
+stop there, for reasons that turned out to matter in practice, not just in
+theory - see [`smart-spatial-vienna-accessibility`](https://github.com/arazshah/smart-spatial-vienna-accessibility)'s
+case study and [`CHANGELOG.md`](CHANGELOG.md)'s `0.2.1`-`0.2.4` entries for
+five real bugs this surfaced and fixed:
+
+- **A deterministic path exists alongside the LLM path**, built from the same
+  operation catalog (`OP_CATALOG`). The same analysis can be run by rule and
+  by LLM, so "is the LLM's plan reliable" is a measurable question (Plan
+  Agreement Rate, Rank Stability - see [docs/CASE_STUDIES.md](docs/CASE_STUDIES.md)), not
+  a leap of faith.
+- **Every LLM-generated plan is validated before execution**, not just before
+  syntax errors: missing input roles, an unchained multi-factor scoring step,
+  an asymmetric CRS reprojection, an untyped scoring factor - each is a
+  distinct, previously-silent failure mode this system now catches and raises
+  a specific error for, before spending a single second executing.
+- **Every plugin carries a full execution trace** - which operations ran, in
+  what order, with what parameters - so a wrong answer is debuggable, not a
+  black box.
+
 ---
 
 ## How a query runs
@@ -265,6 +299,15 @@ Full deployment guide - environment variables, authentication, CORS, PostGIS:
 
 Full request and response contracts are in [docs/phase5_query_api_contract.md](docs/phase5_query_api_contract.md) and the other `docs/phase5_*` files.
 
+## Research and case studies
+
+Looking for a study to build on this system, or to see one already done?
+[docs/CASE_STUDIES.md](docs/CASE_STUDIES.md) has a catalog of suggested
+studies (accessibility, risk-aware siting, vegetation change, zoning
+compliance, and a reproducibility-methodology replication) plus what's
+*not* a good fit yet. If you use this software in published work, see
+[CITATION.cff](CITATION.cff).
+
 ## Development
 
 ```bash
@@ -272,6 +315,10 @@ pytest                # full suite
 ruff check .          # lint
 ```
 
+Contributions are welcome - see [CONTRIBUTING.md](CONTRIBUTING.md). Found a
+security issue? See [SECURITY.md](SECURITY.md) rather than opening a public
+issue.
+
 ## Author
 
 [Araz Shahkarami](https://github.com/arazshah) · [araz.me](https://araz.me)

{smart_spatial_system-0.2.4 → smart_spatial_system-0.2.6}/README.md

@@ -1,13 +1,47 @@
 # Smart Spatial System
 
+[![PyPI](https://img.shields.io/pypi/v/smart-spatial-system)](https://pypi.org/project/smart-spatial-system/)
+[![CI](https://github.com/arazshah/smart_spatial_system/actions/workflows/ci.yml/badge.svg)](https://github.com/arazshah/smart_spatial_system/actions/workflows/ci.yml)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-blue)](pyproject.toml)
+
 **Ask a geospatial question in plain language and get map layers, tables, reports and files back.**
 
+**[s3geo.com](https://s3geo.com)** — project site, plugin catalog and case-study index.
+
 Smart Spatial System is a plugin-based GeoAI backend with a React workbench. A question such as *"rank these candidate properties by distance to metro stations, malls and main roads"* is turned into a structured `QuerySpec`, planned as a DAG of spatial operations, executed by plugins against uploaded files or PostGIS, and returned as map-ready outputs with a full execution trace.
 
+![Running the rule-based accessibility example end to end: the planned DAG, then the ranked output](docs/assets/demo.gif)
+
+Real, unedited terminal output from [`examples/accessibility_analysis.py`](examples/accessibility_analysis.py) — no server, no LLM, deterministic by construction. Run it yourself after installing below.
+
 It is the application built on top of [geochat-platform](https://github.com/arazshah/geochat-platform): plugins are written with `geochat_sdk` and executed through `geochat_kernel`.
 
 > **Status:** published and usable, still refactoring internally. Logic is moving out of `orchestrator/` into the layered `smart_spatial_system/` package (see [docs/ARCHITECTURE_TARGET.md](docs/ARCHITECTURE_TARGET.md)); the `orchestrator/*_service.py` modules are compatibility shims during that move. The public surface - the CLI, the HTTP API and the documented entry points below - is stable.
 
+## Why this, not a general-purpose LLM agent with a GIS tool belt
+
+The natural alternative is: give an LLM function-calling access to some GIS
+functions and let it decide what to call. This project deliberately doesn't
+stop there, for reasons that turned out to matter in practice, not just in
+theory - see [`smart-spatial-vienna-accessibility`](https://github.com/arazshah/smart-spatial-vienna-accessibility)'s
+case study and [`CHANGELOG.md`](CHANGELOG.md)'s `0.2.1`-`0.2.4` entries for
+five real bugs this surfaced and fixed:
+
+- **A deterministic path exists alongside the LLM path**, built from the same
+  operation catalog (`OP_CATALOG`). The same analysis can be run by rule and
+  by LLM, so "is the LLM's plan reliable" is a measurable question (Plan
+  Agreement Rate, Rank Stability - see [docs/CASE_STUDIES.md](docs/CASE_STUDIES.md)), not
+  a leap of faith.
+- **Every LLM-generated plan is validated before execution**, not just before
+  syntax errors: missing input roles, an unchained multi-factor scoring step,
+  an asymmetric CRS reprojection, an untyped scoring factor - each is a
+  distinct, previously-silent failure mode this system now catches and raises
+  a specific error for, before spending a single second executing.
+- **Every plugin carries a full execution trace** - which operations ran, in
+  what order, with what parameters - so a wrong answer is debuggable, not a
+  black box.
+
 ---
 
 ## How a query runs
@@ -216,6 +250,15 @@ Full deployment guide - environment variables, authentication, CORS, PostGIS:
 
 Full request and response contracts are in [docs/phase5_query_api_contract.md](docs/phase5_query_api_contract.md) and the other `docs/phase5_*` files.
 
+## Research and case studies
+
+Looking for a study to build on this system, or to see one already done?
+[docs/CASE_STUDIES.md](docs/CASE_STUDIES.md) has a catalog of suggested
+studies (accessibility, risk-aware siting, vegetation change, zoning
+compliance, and a reproducibility-methodology replication) plus what's
+*not* a good fit yet. If you use this software in published work, see
+[CITATION.cff](CITATION.cff).
+
 ## Development
 
 ```bash
@@ -223,6 +266,10 @@ pytest                # full suite
 ruff check .          # lint
 ```
 
+Contributions are welcome - see [CONTRIBUTING.md](CONTRIBUTING.md). Found a
+security issue? See [SECURITY.md](SECURITY.md) rather than opening a public
+issue.
+
 ## Author
 
 [Araz Shahkarami](https://github.com/arazshah) · [araz.me](https://araz.me)

smart_spatial_system-0.2.6/config/plugins/ring_buffer_analysis.example.yaml

@@ -0,0 +1,16 @@
+default_distances: null
+default_units: m
+default_quad_segs: 8
+default_engine: auto
+
+preserve_properties: true
+
+allowed_geometry_types:
+  - Point
+  - MultiPoint
+  - LineString
+  - MultiLineString
+  - Polygon
+  - MultiPolygon
+
+metadata: {}

smart_spatial_system-0.2.6/config/plugins/ring_buffer_analysis.yaml

@@ -0,0 +1,16 @@
+default_distances: null
+default_units: m
+default_quad_segs: 8
+default_engine: auto
+
+preserve_properties: true
+
+allowed_geometry_types:
+  - Point
+  - MultiPoint
+  - LineString
+  - MultiLineString
+  - Polygon
+  - MultiPolygon
+
+metadata: {}

{smart_spatial_system-0.2.4 → smart_spatial_system-0.2.6}/orchestrator/planning/llm_spec_generator.py

@@ -1047,11 +1047,41 @@ Important mappings:
   inputs={{"vector": "<source>", "reference": "<poi>"}}
   params={{"max_distance_m": X, "k": 1, "drop_unmatched": true}}
 
+- "multiple rings/distance bands around a point/line/polygon" (e.g.
+  "200m, 500m and 800m rings around each station", concentric zones, a
+  gradient outward from a feature):
+  use op="ring_buffer" with params={{"distances": [200, 500, 800]}} - do
+  NOT chain op="buffer" multiple times for this. Chaining buffer only ever
+  produces nested full-circle disks (each one containing all the smaller
+  ones), never the annulus/gap BETWEEN two radii, which is what "ring" or
+  "band" means here.
+
 - "inside permitted/buildable polygon":
   op="filter_points_in_polygon"
   inputs={{"vector": "<points>", "polygon": "<polygon_layer>"}}
   params={{"predicate": "within", "drop_outside": true}}
 
+- CRITICAL - "points inside a polygon/zone" has TWO different shapes that
+  need DIFFERENT operations - picking the wrong one plans successfully and
+  runs without error, but silently loses the information the user asked
+  for:
+  * User only wants a boolean keep/drop filter (e.g. "keep only points
+    inside the permitted area", "drop points outside the buildable zone"):
+    use op="filter_points_in_polygon". It returns nothing but a
+    __in_polygon__ true/false flag - it does NOT record which polygon
+    matched.
+  * User wants to know WHICH specific zone/polygon/ring each point falls
+    into (e.g. "for each point, tell me which zone it falls into", "label
+    each point by its zone", "group points by distance band/ring"):
+    do NOT use op="filter_points_in_polygon" for this - it has no way to
+    carry the matched polygon's identity, so the output would have no
+    zone information at all. Use op="spatial_join" instead:
+    inputs={{"source": "<points>", "target": "<zones/polygons>"}}
+    params={{"predicate": "within", "include_target_properties": true}}
+    include_target_properties=true is what copies the matched polygon's
+    own properties (id, name, zone label, ring_label, etc.) onto each
+    output point.
+
 - After a distance operation, if the resulting distance field should be used for scoring,
   use enrich_feature_properties to copy/rename it to a semantic field like:
   distance_to_poi or distance_to_road.

{smart_spatial_system-0.2.4 → smart_spatial_system-0.2.6}/orchestrator/planning/op_catalog.py

@@ -129,6 +129,17 @@ _BUFFER_PARAM_MAP = {
     "metadata": "metadata",
 }
 
+_RING_BUFFER_PARAM_MAP = {
+    "distances": "distances",
+    "units": "units",
+    "quad_segs": "quad_segs",
+    "engine": "engine",
+    "cap_style": "cap_style",
+    "join_style": "join_style",
+    "mitre_limit": "mitre_limit",
+    "metadata": "metadata",
+}
+
 
 OP_CATALOG: dict[str, OpDescriptor] = {
     # ---------------------------------------------------------------------
@@ -474,6 +485,30 @@ OP_CATALOG: dict[str, OpDescriptor] = {
         ),
     ),
 
+    "ring_buffer": OpDescriptor(
+        op_name="ring_buffer",
+        capability_name="generate_ring_buffers",
+        input_map={
+            "vector": "features",
+        },
+        input_types={
+            "vector": "vector",
+        },
+        param_map=_RING_BUFFER_PARAM_MAP,
+        output_type="vector",
+        notes=(
+            "Create concentric ring (annulus) polygons around input features at "
+            "multiple distances, e.g. params.distances=[200, 500, 800, 1200]. "
+            "Returns the area BETWEEN consecutive radii (a true ring/annulus), "
+            "not cumulative full-circle disks. Use this instead of chaining "
+            "buffer multiple times whenever the user asks for distance bands, "
+            "zonal rings, or a gradient outward from a point/line/polygon - "
+            "chaining buffer only ever produces nested full disks, never the "
+            "gap between two radii. Use metric CRS when distances are in "
+            "meters."
+        ),
+    ),
+
     # ---------------------------------------------------------------------
     # Raster operations
     # ---------------------------------------------------------------------

{smart_spatial_system-0.2.4 → smart_spatial_system-0.2.6}/orchestrator/plugin_modules.py

@@ -30,6 +30,7 @@ DEFAULT_SAFE_PLUGIN_MODULES = [
     "plugins.slope_aspect",
     "plugins.zonal_statistics",
     "plugins.buffer_analysis",
+    "plugins.ring_buffer_analysis",
     "plugins.centroid_extractor",
     "plugins.geometry_validator",
     "plugins.spatial_query_filter",