smart-spatial-system 0.1.0__tar.gz

smart_spatial_system-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Araz Shah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

smart_spatial_system-0.1.0/PKG-INFO

@@ -0,0 +1,180 @@
+Metadata-Version: 2.4
+Name: smart_spatial_system
+Version: 0.1.0
+Summary: Plugin-based GeoAI backend: natural-language questions become QuerySpecs, DAG plans, and map/table/report outputs.
+Author: Araz Shah
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/arazshah/smart_spatial_system
+Project-URL: Repository, https://github.com/arazshah/smart_spatial_system
+Project-URL: Issues, https://github.com/arazshah/smart_spatial_system/issues
+Keywords: geospatial,gis,geoai,spatial-analysis,postgis,natural-language
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Science/Research
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering :: GIS
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: geochat-sdk>=1.0.0
+Requires-Dist: geochat-kernel>=1.0.0
+Requires-Dist: fastapi
+Requires-Dist: uvicorn[standard]
+Requires-Dist: python-multipart
+Requires-Dist: python-dotenv
+Requires-Dist: pyyaml
+Requires-Dist: httpx
+Requires-Dist: jinja2
+Requires-Dist: shapely
+Requires-Dist: pyproj
+Requires-Dist: numpy
+Requires-Dist: geopandas
+Requires-Dist: requests
+Provides-Extra: postgis
+Requires-Dist: psycopg[binary]; extra == "postgis"
+Provides-Extra: raster
+Requires-Dist: rasterio; extra == "raster"
+Provides-Extra: pdf
+Requires-Dist: weasyprint; extra == "pdf"
+Provides-Extra: llm
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: ruff; extra == "dev"
+Dynamic: license-file
+
+# Smart Spatial System
+
+**Ask a geospatial question in plain language and get map layers, tables, reports and files back.**
+
+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.
+
+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:** active development, mid-refactor. Phase 6 moves logic 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.
+
+---
+
+## How a query runs
+
+```text
+natural-language question
+  → QuerySpec            LLM (OpenAI-compatible) or rule-based, with PostGIS semantic context
+  → DeterministicPlanner + OP_CATALOG
+  → DagPlan → DagExecutor
+  → CapabilityRegistry   weighted router, learns from user feedback
+  → geochat_sdk plugins  vector, raster, PostGIS, reporting, export
+  → outputs              map layers · tables · documents (PDF/HTML) · files · trace
+```
+
+Design decisions are recorded as ADRs in [`docs/`](docs): single kernel pipeline, artifact-based responses, a multilingual semantic layer (Persian queries today, language-neutral concepts inside), and a service-oriented modular backend.
+
+## What is in the box
+
+- **36 plugins**, including buffer, spatial join, intersection, predicates, dissolve, nearest neighbour, distance, area and perimeter, centroids, CRS transform, geometry validation, attribute statistics, zonal statistics, band math, NDVI and spectral indices, slope/aspect, raster clip/reclassify/threshold/statistics, raster-to-vector, geocoding, WMS/WFS fetcher, PostGIS connector, feature scoring and enrichment, local raster/vector loaders, report builder, PDF renderer and data export.
+- **Data sources:** raster and vector uploads, CSV tables, WMS, WFS, PostGIS and remote URLs, grouped into projects.
+- **Workflows:** real-estate site ranking with a generated PDF report, and NDVI analysis.
+- **Learning router:** capability weights adjust from user feedback, with reviewable weight proposals.
+- **Workbench:** React + Leaflet UI for queries, step-by-step progress, map layers, inspection, plugin settings and outputs.
+
+## Repository layout
+
+```text
+api/                     FastAPI app and routers
+orchestrator/            query parsing, planning (QuerySpec, OP_CATALOG, DAG), routing, services
+smart_spatial_system/    new layered package (application services; other layers being filled in)
+plugins/                 geochat_sdk capability plugins
+config/plugins/          per-plugin YAML config (*.example.yaml are the templates)
+templates/reports/       report templates (real-estate report)
+scripts/sql/             PostGIS views for the Tehran OSM demo
+examples/                small fake datasets for the real-estate workflow
+frontend/                React + Vite workbench
+tests/                   pytest suite (~150 modules)
+docs/                    architecture, ADRs, API contracts, phase reports
+```
+
+Runtime data (outputs, uploads, projects) is written to `var/` by default, or to `SMART_SPATIAL_RUNTIME_DIR`, and is not committed.
+
+## Getting started
+
+Requires Python 3.11+ (matches CI and the Docker image), Node.js 20+, and
+optionally PostgreSQL with PostGIS.
+
+```bash
+git clone https://github.com/arazshah/smart_spatial_system.git
+cd smart_spatial_system
+
+python -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+
+cp .env.example .env                  # add your LLM key
+uvicorn api.main:app --reload         # http://127.0.0.1:8000/docs
+```
+
+Frontend:
+
+```bash
+cd frontend
+cp .env.example .env
+npm install && npm run dev            # http://localhost:5173
+```
+
+PostGIS demo data (Tehran OpenStreetMap): see [data/README.md](data/README.md).
+
+Docker Compose (backend + frontend, PostGIS optional):
+
+```bash
+docker compose up --build
+```
+
+See [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) for the full deployment guide —
+environment variables, authentication, CORS, and PostGIS setup for running
+this beyond your own machine.
+
+### Installing as a package
+
+Alongside the `pip install -r requirements.txt` + `uvicorn` dev flow above,
+the backend also installs as a regular Python package (`pyproject.toml`),
+with optional extras for the heavier/domain-specific dependencies:
+
+```bash
+pip install -e ".[postgis,raster,pdf]"    # editable install for local dev
+# or: pip install ".[postgis,raster,pdf]" for a non-editable install
+
+smart-spatial-api serve --host 0.0.0.0 --port 8000
+# equivalent: python -m smart_spatial_system serve --host 0.0.0.0 --port 8000
+```
+
+Extras: `postgis` (`psycopg`), `raster` (`rasterio`, for NDVI/spectral-index
+plugins), `pdf` (`weasyprint`, for PDF report rendering), `llm` (reserved,
+currently no extra dependency), `dev` (`pytest`, `ruff`). Omitting an extra
+does not break the app — the affected plugins are simply unavailable
+(reported in the service's plugin registry), not a startup failure. See
+[docs/PHASE8_BACKEND_PACKAGING_CLI_PLAN.md](docs/PHASE8_BACKEND_PACKAGING_CLI_PLAN.md)
+for how this was verified.
+
+## API at a glance
+
+| Area | Endpoints |
+|---|---|
+| Query | `POST /query` · `POST /planner/intent` · `POST /feedback` |
+| Requests & outputs | `GET /requests` · `GET /requests/{id}` · `…/map-layers` · `…/outputs` · `…/outputs/files/{name}` · `…/documents/{name}` |
+| Projects & data | `/projects` · `/uploads/raster` · `/uploads/vector` · `/data-sources/{csv-table,wms,wfs,postgis,url}` |
+| Plugins & settings | `/plugins` · `/plugins/{id}/config` · `/settings/runtime` · `/settings/llm/smoke-test` |
+| Router weights | `/weights` · `/weights/save` · `/weights/reload` · `/weights/proposals/apply` |
+| System | `GET /health` |
+
+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.
+
+## Tests
+
+```bash
+pytest
+```
+
+## Author
+
+[Araz Shahkarami](https://github.com/arazshah) · [araz.me](https://araz.me)

smart_spatial_system-0.1.0/README.md

@@ -0,0 +1,132 @@
+# Smart Spatial System
+
+**Ask a geospatial question in plain language and get map layers, tables, reports and files back.**
+
+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.
+
+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:** active development, mid-refactor. Phase 6 moves logic 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.
+
+---
+
+## How a query runs
+
+```text
+natural-language question
+  → QuerySpec            LLM (OpenAI-compatible) or rule-based, with PostGIS semantic context
+  → DeterministicPlanner + OP_CATALOG
+  → DagPlan → DagExecutor
+  → CapabilityRegistry   weighted router, learns from user feedback
+  → geochat_sdk plugins  vector, raster, PostGIS, reporting, export
+  → outputs              map layers · tables · documents (PDF/HTML) · files · trace
+```
+
+Design decisions are recorded as ADRs in [`docs/`](docs): single kernel pipeline, artifact-based responses, a multilingual semantic layer (Persian queries today, language-neutral concepts inside), and a service-oriented modular backend.
+
+## What is in the box
+
+- **36 plugins**, including buffer, spatial join, intersection, predicates, dissolve, nearest neighbour, distance, area and perimeter, centroids, CRS transform, geometry validation, attribute statistics, zonal statistics, band math, NDVI and spectral indices, slope/aspect, raster clip/reclassify/threshold/statistics, raster-to-vector, geocoding, WMS/WFS fetcher, PostGIS connector, feature scoring and enrichment, local raster/vector loaders, report builder, PDF renderer and data export.
+- **Data sources:** raster and vector uploads, CSV tables, WMS, WFS, PostGIS and remote URLs, grouped into projects.
+- **Workflows:** real-estate site ranking with a generated PDF report, and NDVI analysis.
+- **Learning router:** capability weights adjust from user feedback, with reviewable weight proposals.
+- **Workbench:** React + Leaflet UI for queries, step-by-step progress, map layers, inspection, plugin settings and outputs.
+
+## Repository layout
+
+```text
+api/                     FastAPI app and routers
+orchestrator/            query parsing, planning (QuerySpec, OP_CATALOG, DAG), routing, services
+smart_spatial_system/    new layered package (application services; other layers being filled in)
+plugins/                 geochat_sdk capability plugins
+config/plugins/          per-plugin YAML config (*.example.yaml are the templates)
+templates/reports/       report templates (real-estate report)
+scripts/sql/             PostGIS views for the Tehran OSM demo
+examples/                small fake datasets for the real-estate workflow
+frontend/                React + Vite workbench
+tests/                   pytest suite (~150 modules)
+docs/                    architecture, ADRs, API contracts, phase reports
+```
+
+Runtime data (outputs, uploads, projects) is written to `var/` by default, or to `SMART_SPATIAL_RUNTIME_DIR`, and is not committed.
+
+## Getting started
+
+Requires Python 3.11+ (matches CI and the Docker image), Node.js 20+, and
+optionally PostgreSQL with PostGIS.
+
+```bash
+git clone https://github.com/arazshah/smart_spatial_system.git
+cd smart_spatial_system
+
+python -m venv .venv && source .venv/bin/activate
+pip install -r requirements.txt
+
+cp .env.example .env                  # add your LLM key
+uvicorn api.main:app --reload         # http://127.0.0.1:8000/docs
+```
+
+Frontend:
+
+```bash
+cd frontend
+cp .env.example .env
+npm install && npm run dev            # http://localhost:5173
+```
+
+PostGIS demo data (Tehran OpenStreetMap): see [data/README.md](data/README.md).
+
+Docker Compose (backend + frontend, PostGIS optional):
+
+```bash
+docker compose up --build
+```
+
+See [docs/DEPLOYMENT.md](docs/DEPLOYMENT.md) for the full deployment guide —
+environment variables, authentication, CORS, and PostGIS setup for running
+this beyond your own machine.
+
+### Installing as a package
+
+Alongside the `pip install -r requirements.txt` + `uvicorn` dev flow above,
+the backend also installs as a regular Python package (`pyproject.toml`),
+with optional extras for the heavier/domain-specific dependencies:
+
+```bash
+pip install -e ".[postgis,raster,pdf]"    # editable install for local dev
+# or: pip install ".[postgis,raster,pdf]" for a non-editable install
+
+smart-spatial-api serve --host 0.0.0.0 --port 8000
+# equivalent: python -m smart_spatial_system serve --host 0.0.0.0 --port 8000
+```
+
+Extras: `postgis` (`psycopg`), `raster` (`rasterio`, for NDVI/spectral-index
+plugins), `pdf` (`weasyprint`, for PDF report rendering), `llm` (reserved,
+currently no extra dependency), `dev` (`pytest`, `ruff`). Omitting an extra
+does not break the app — the affected plugins are simply unavailable
+(reported in the service's plugin registry), not a startup failure. See
+[docs/PHASE8_BACKEND_PACKAGING_CLI_PLAN.md](docs/PHASE8_BACKEND_PACKAGING_CLI_PLAN.md)
+for how this was verified.
+
+## API at a glance
+
+| Area | Endpoints |
+|---|---|
+| Query | `POST /query` · `POST /planner/intent` · `POST /feedback` |
+| Requests & outputs | `GET /requests` · `GET /requests/{id}` · `…/map-layers` · `…/outputs` · `…/outputs/files/{name}` · `…/documents/{name}` |
+| Projects & data | `/projects` · `/uploads/raster` · `/uploads/vector` · `/data-sources/{csv-table,wms,wfs,postgis,url}` |
+| Plugins & settings | `/plugins` · `/plugins/{id}/config` · `/settings/runtime` · `/settings/llm/smoke-test` |
+| Router weights | `/weights` · `/weights/save` · `/weights/reload` · `/weights/proposals/apply` |
+| System | `GET /health` |
+
+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.
+
+## Tests
+
+```bash
+pytest
+```
+
+## Author
+
+[Araz Shahkarami](https://github.com/arazshah) · [araz.me](https://araz.me)

smart_spatial_system-0.1.0/api/auth.py

@@ -0,0 +1,48 @@
+"""
+api.auth
+
+Minimal shared-secret API key authentication.
+
+This targets the "single team, self-hosted" deployment model documented in
+CLAUDE.md: one deployer runs one backend instance for their own team, so a
+single shared key is enough - there is no per-user login, session, or
+multi-tenant model here.
+
+Set SMART_SPATIAL_API_KEY to require every non-health request to send it
+back as the X-API-Key header. Leaving it unset keeps the API open, matching
+prior behavior, for local development and existing deployments that have
+not opted in yet.
+"""
+
+from __future__ import annotations
+
+import secrets
+
+from fastapi import HTTPException, Request, Security
+from fastapi.security import APIKeyHeader
+
+_API_KEY_HEADER_NAME = "X-API-Key"
+
+_api_key_header = APIKeyHeader(name=_API_KEY_HEADER_NAME, auto_error=False)
+
+
+def require_api_key(
+    request: Request,
+    provided_key: str | None = Security(_api_key_header),
+) -> None:
+    """
+    FastAPI dependency: reject the request unless it carries the
+    X-API-Key header matching the server's configured key.
+
+    No-op (request allowed) when the server has no api_key configured.
+    """
+    expected_key: str | None = getattr(request.app.state, "api_key", None)
+
+    if not expected_key:
+        return
+
+    if not provided_key or not secrets.compare_digest(provided_key, expected_key):
+        raise HTTPException(
+            status_code=401,
+            detail=f"Missing or invalid {_API_KEY_HEADER_NAME} header.",
+        )

smart_spatial_system-0.1.0/api/main.py

@@ -0,0 +1,115 @@
+"""
+FastAPI API for Smart Spatial System.
+
+This module owns the HTTP application factory, CORS setup, service wiring,
+and API router registration.
+
+Run:
+    uvicorn api.main:app --reload
+"""
+
+from __future__ import annotations
+
+from dotenv import load_dotenv
+
+load_dotenv()
+
+import os
+from dataclasses import dataclass, field
+
+from fastapi import Depends, FastAPI
+from fastapi.middleware.cors import CORSMiddleware
+
+from api.auth import require_api_key
+from api.routers.data_source_connectors import router as data_source_connectors_router
+from api.routers.data_sources import router as data_sources_router
+from api.routers.plugins_settings import router as plugins_settings_router
+from api.routers.projects import router as projects_router
+from api.routers.query_planner import router as query_planner_router
+from api.routers.requests_outputs import router as requests_outputs_router
+from api.routers.system import router as system_router
+from api.routers.uploads import router as uploads_router
+from api.routers.weights import router as weights_router
+from orchestrator.service import OrchestratorService, OrchestratorServiceConfig
+
+
+@dataclass(frozen=True)
+class APIConfig:
+    """
+    FastAPI application config.
+
+    For frontend development, default CORS allows localhost React/Vite ports.
+    In production, restrict allowed_origins.
+    """
+
+    title: str = "Smart Spatial System API"
+    version: str = "0.1.0"
+    description: str = "MVP API for natural geospatial query execution."
+
+    allow_origins: tuple[str, ...] = (
+        "http://localhost:3000",
+        "http://127.0.0.1:3000",
+        "http://localhost:5173",
+        "http://127.0.0.1:5173",
+    )
+    allow_credentials: bool = True
+    allow_methods: tuple[str, ...] = ("*",)
+    allow_headers: tuple[str, ...] = ("*",)
+
+    # When set, every route except "/" and "/health" requires the matching
+    # X-API-Key header (see api/auth.py). Defaults to the SMART_SPATIAL_API_KEY
+    # env var; leave both unset to keep the API open (local dev, or a
+    # deployment that has not opted in yet).
+    api_key: str | None = field(default_factory=lambda: os.environ.get("SMART_SPATIAL_API_KEY") or None)
+
+
+def create_app(
+    *,
+    service: OrchestratorService | None = None,
+    service_config: OrchestratorServiceConfig | None = None,
+    api_config: APIConfig | None = None,
+) -> FastAPI:
+    """
+    Create FastAPI app.
+
+    Tests can inject a service with tmp_path weights.
+    Production/dev can use default config.
+    """
+    final_api_config = api_config or APIConfig()
+
+    app = FastAPI(
+        title=final_api_config.title,
+        version=final_api_config.version,
+        description=final_api_config.description,
+    )
+
+    app.add_middleware(
+        CORSMiddleware,
+        allow_origins=list(final_api_config.allow_origins),
+        allow_credentials=final_api_config.allow_credentials,
+        allow_methods=list(final_api_config.allow_methods),
+        allow_headers=list(final_api_config.allow_headers),
+    )
+
+    app.state.service = service or OrchestratorService(
+        service_config or OrchestratorServiceConfig()
+    )
+    app.state.api_key = final_api_config.api_key
+
+    protected = [Depends(require_api_key)]
+
+    # "/" and "/health" stay open for monitoring/load-balancer liveness checks.
+    app.include_router(system_router)
+    app.include_router(projects_router, dependencies=protected)
+    app.include_router(uploads_router, dependencies=protected)
+    app.include_router(data_sources_router, dependencies=protected)
+    app.include_router(data_source_connectors_router, dependencies=protected)
+    app.include_router(plugins_settings_router, dependencies=protected)
+    app.include_router(requests_outputs_router, dependencies=protected)
+    app.include_router(weights_router, dependencies=protected)
+    app.include_router(query_planner_router, dependencies=protected)
+
+    return app
+
+
+app = create_app()