smart-spatial-system 0.1.0__py3-none-any.whl

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.",
+        )

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()

api/routers/data_source_connectors.py

@@ -0,0 +1,448 @@
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import (
+    APIRouter,
+    Body,
+    HTTPException,
+    Request,
+)
+
+from api.support import (
+    http_error_detail as _http_error_detail,
+)
+from api.support import (
+    json_safe as _json_safe,
+)
+from api.support import (
+    service as _service,
+)
+from orchestrator.service import OrchestratorServiceError
+
+router = APIRouter()
+
+
+def _resolve_service_capability(
+    svc: Any,
+    candidate_names: tuple[str, ...],
+) -> Any:
+    """
+    Resolve a callable capability through the service registry.
+
+    API routers must not import concrete plugin implementation modules.
+    They should go through the service/registry/capability boundary.
+    """
+    registry = getattr(svc, "registry", None)
+    if registry is None:
+        raise HTTPException(
+            status_code=400,
+            detail="Capability registry is not available.",
+        )
+
+    last_error: Exception | None = None
+
+    for capability_name in candidate_names:
+        try:
+            assert_enabled = getattr(svc, "_assert_capability_enabled", None)
+            if callable(assert_enabled):
+                assert_enabled(capability_name)
+
+            binding = registry.resolve(capability_name)
+            capability = getattr(binding, "callable", binding)
+            if callable(capability):
+                return capability
+
+        except Exception as exc:
+            last_error = exc
+            continue
+
+    detail = "Capability is not available: " + ", ".join(candidate_names)
+    if last_error is not None:
+        detail = f"{detail}. Last error: {last_error}"
+
+    raise HTTPException(
+        status_code=400,
+        detail=detail,
+    )
+
+
+@router.post("/data-sources/csv-table")
+def register_csv_table_source(
+    request: Request,
+    payload: dict[str, Any] = Body(...),
+) -> dict[str, Any]:
+    svc = _service(request)
+
+    try:
+        return _json_safe(svc.register_csv_table_source(payload))
+    except OrchestratorServiceError as exc:
+        raise HTTPException(
+            status_code=400,
+            detail=_http_error_detail(exc),
+        ) from exc
+
+
+@router.post("/data-sources/wms")
+def register_wms_source(
+    request: Request,
+    payload: dict[str, Any] = Body(...),
+) -> dict[str, Any]:
+    svc = _service(request)
+
+    try:
+        return _json_safe(svc.register_wms_source(payload))
+    except OrchestratorServiceError as exc:
+        raise HTTPException(
+            status_code=400,
+            detail=_http_error_detail(exc),
+        ) from exc
+
+
+@router.post("/data-sources/postgis")
+def register_postgis_source(
+    request: Request,
+    payload: dict[str, Any] = Body(...),
+) -> dict[str, Any]:
+    """
+    Connect to PostGIS, fetch a spatial table and register as a data source.
+
+    Expected body:
+        {
+            "project_id": "optional",
+            "display_name": "optional",
+            "table": "roads",
+            "schema": "public",
+            "geom_col": "geom",
+            "where": "optional SQL filter",
+            "limit": 1000,
+            "output_srid": 4326,
+            "dsn": "postgresql://user:pass@host/db",
+            "host": "localhost",
+            "port": 5432,
+            "database": "gis",
+            "user": "postgres",
+            "password": "secret",
+            "profile": "optional config profile"
+        }
+    """
+    svc = _service(request)
+
+    table = payload.get("table")
+    if not isinstance(table, str) or not table.strip():
+        raise HTTPException(
+            status_code=400,
+            detail="'table' must be a non-empty string.",
+        )
+
+    try:
+        fetch_postgis_layer = _resolve_service_capability(
+            svc,
+            (
+                "fetch_postgis_layer",
+                "query_database_postgis",
+                "load_postgis_layer",
+            ),
+        )
+
+        result = fetch_postgis_layer(
+            table=str(table).strip(),
+            profile=payload.get("profile"),
+            dsn=payload.get("dsn"),
+            schema=payload.get("schema"),
+            geom_col=payload.get("geom_col"),
+            where=payload.get("where"),
+            limit=payload.get("limit"),
+            output_srid=payload.get("output_srid"),
+            host=payload.get("host"),
+            port=payload.get("port"),
+            database=payload.get("database"),
+            user=payload.get("user"),
+            password=payload.get("password"),
+            connect_timeout=payload.get("connect_timeout"),
+        )
+
+    except HTTPException:
+        raise
+    except Exception as exc:
+        raise HTTPException(
+            status_code=400,
+            detail=f"PostGIS fetch failed: {exc}",
+        ) from exc
+
+    import json as _json
+
+    features = getattr(result, "features", None) or []
+    metadata = getattr(result, "metadata", None) or {}
+
+    geojson = {
+        "type": "FeatureCollection",
+        "features": features,
+        "metadata": metadata,
+    }
+
+    display_name = (
+        payload.get("display_name")
+        or f"{payload.get('schema', 'public')}.{table}"
+    )
+
+    content = _json.dumps(geojson, ensure_ascii=False).encode("utf-8")
+
+    try:
+        upload = svc.save_upload(
+            filename=f"{table}.geojson",
+            content=content,
+            content_type="application/geo+json",
+            kind="vector",
+            user_context={
+                "source": "postgis",
+                "source_type": "postgis",
+                "display_name": display_name,
+                "table": table,
+                "schema": payload.get("schema", "public"),
+                "postgis_metadata": metadata,
+            },
+            project_id=payload.get("project_id"),
+        )
+    except OrchestratorServiceError as exc:
+        raise HTTPException(
+            status_code=400,
+            detail=_http_error_detail(exc),
+        ) from exc
+
+    return _json_safe({
+        **upload,
+        "source_type": "postgis",
+        "feature_count": len(features),
+        "postgis_metadata": metadata,
+    })
+
+
+@router.post("/data-sources/wfs")
+def register_wfs_source(
+    request: Request,
+    payload: dict[str, Any] = Body(...),
+) -> dict[str, Any]:
+    """
+    Fetch features from WFS service and register as a data source.
+
+    Expected body:
+        {
+            "project_id": "optional",
+            "display_name": "optional",
+            "base_url": "https://...",
+            "type_name": "layer:name",
+            "layer": "alias from config",
+            "service": "config profile name",
+            "version": "2.0.0",
+            "output_format": "application/json",
+            "srs_name": "EPSG:4326",
+            "bbox": [minx, miny, maxx, maxy],
+            "max_features": 1000,
+            "timeout": 30
+        }
+    """
+    svc = _service(request)
+
+    base_url = payload.get("base_url")
+    type_name = payload.get("type_name") or payload.get("layer")
+
+    if not payload.get("service") and (
+        not isinstance(base_url, str) or not base_url.strip()
+    ):
+        raise HTTPException(
+            status_code=400,
+            detail="'base_url' or 'service' must be provided.",
+        )
+
+    if not payload.get("service") and (
+        not isinstance(type_name, str) or not str(type_name).strip()
+    ):
+        raise HTTPException(
+            status_code=400,
+            detail="'type_name' or 'layer' must be provided.",
+        )
+
+    try:
+        fetch_wfs_features = _resolve_service_capability(
+            svc,
+            (
+                "fetch_wfs_features",
+                "load_wfs_features",
+                "load_wfs_layer",
+            ),
+        )
+
+        result = fetch_wfs_features(
+            service=payload.get("service"),
+            base_url=base_url,
+            type_name=payload.get("type_name"),
+            layer=payload.get("layer"),
+            version=payload.get("version"),
+            output_format=payload.get("output_format"),
+            srs_name=payload.get("srs_name"),
+            bbox=payload.get("bbox"),
+            max_features=payload.get("max_features"),
+            property_name=payload.get("property_name"),
+            timeout=payload.get("timeout"),
+        )
+
+    except HTTPException:
+        raise
+    except Exception as exc:
+        raise HTTPException(
+            status_code=400,
+            detail=f"WFS fetch failed: {exc}",
+        ) from exc
+
+    import json as _json
+
+    features = getattr(result, "features", None) or []
+    metadata = getattr(result, "metadata", None) or {}
+
+    geojson = {
+        "type": "FeatureCollection",
+        "features": features,
+        "metadata": metadata,
+    }
+
+    display_name = (
+        payload.get("display_name")
+        or payload.get("type_name")
+        or payload.get("layer")
+        or "wfs_layer"
+    )
+
+    safe_name = str(display_name).replace(":", "_").replace("/", "_")
+    content = _json.dumps(geojson, ensure_ascii=False).encode("utf-8")
+
+    try:
+        upload = svc.save_upload(
+            filename=f"{safe_name}.geojson",
+            content=content,
+            content_type="application/geo+json",
+            kind="vector",
+            user_context={
+                "source": "wfs",
+                "source_type": "wfs",
+                "display_name": display_name,
+                "base_url": base_url,
+                "type_name": type_name,
+                "wfs_metadata": metadata,
+            },
+            project_id=payload.get("project_id"),
+        )
+    except OrchestratorServiceError as exc:
+        raise HTTPException(
+            status_code=400,
+            detail=_http_error_detail(exc),
+        ) from exc
+
+    return _json_safe({
+        **upload,
+        "source_type": "wfs",
+        "feature_count": len(features),
+        "wfs_metadata": metadata,
+    })
+
+
+@router.post("/data-sources/url")
+def register_url_source(
+    request: Request,
+    payload: dict[str, Any] = Body(...),
+) -> dict[str, Any]:
+    """
+    Fetch GeoJSON from a URL and register as a data source.
+
+    Expected body:
+        {
+            "project_id": "optional",
+            "display_name": "optional",
+            "url": "https://example.com/data.geojson",
+            "kind": "vector",
+            "timeout": 30,
+            "headers": {"Authorization": "Bearer ..."}
+        }
+    """
+    svc = _service(request)
+
+    url = payload.get("url")
+    if not isinstance(url, str) or not url.strip():
+        raise HTTPException(
+            status_code=400,
+            detail="'url' must be a non-empty string.",
+        )
+
+    url = url.strip()
+    timeout = int(payload.get("timeout") or 30)
+    kind = str(payload.get("kind") or "vector")
+    extra_headers = payload.get("headers") or {}
+
+    try:
+        import httpx
+        response = httpx.get(
+            url,
+            timeout=timeout,
+            headers=extra_headers,
+            follow_redirects=True,
+        )
+        response.raise_for_status()
+        content = response.content
+        content_type = response.headers.get("content-type", "application/json")
+    except Exception as exc:
+        raise HTTPException(
+            status_code=400,
+            detail=f"URL fetch failed: {exc}",
+        ) from exc
+
+    import json as _json
+    from urllib.parse import urlparse as _urlparse
+
+    try:
+        parsed_json = _json.loads(content)
+        if not isinstance(parsed_json, dict):
+            raise ValueError("Response is not a JSON object.")
+    except Exception as exc:
+        raise HTTPException(
+            status_code=422,
+            detail=f"Response is not valid JSON: {exc}",
+        ) from exc
+
+    url_path = _urlparse(url).path
+    raw_filename = url_path.split("/")[-1] or "remote_data.geojson"
+    display_name = payload.get("display_name") or raw_filename
+
+    feature_count = 0
+    if parsed_json.get("type") == "FeatureCollection":
+        feature_count = len(parsed_json.get("features") or [])
+    elif parsed_json.get("type") == "Feature":
+        feature_count = 1
+
+    try:
+        upload = svc.save_upload(
+            filename=raw_filename,
+            content=content,
+            content_type=content_type,
+            kind=kind,
+            user_context={
+                "source": "url",
+                "source_type": "url",
+                "display_name": display_name,
+                "original_url": url,
+                "feature_count": feature_count,
+            },
+            project_id=payload.get("project_id"),
+        )
+    except OrchestratorServiceError as exc:
+        raise HTTPException(
+            status_code=400,
+            detail=_http_error_detail(exc),
+        ) from exc
+
+    return _json_safe({
+        **upload,
+        "source_type": "url",
+        "feature_count": feature_count,
+        "original_url": url,
+    })
+

api/routers/data_sources.py

@@ -0,0 +1,84 @@
+from __future__ import annotations
+
+from typing import Any
+
+from fastapi import APIRouter, Body, HTTPException, Request
+
+from api.support import (
+    http_error_detail as _http_error_detail,
+)
+from api.support import (
+    json_safe as _json_safe,
+)
+from api.support import (
+    service as _service,
+)
+from orchestrator.service import OrchestratorServiceError
+
+router = APIRouter()
+
+
+@router.get("/data-sources/{upload_id}")
+def get_data_source(
+    request: Request,
+    upload_id: str,
+) -> dict[str, Any]:
+    svc = _service(request)
+
+    try:
+        return _json_safe(svc.get_data_source(upload_id))
+    except OrchestratorServiceError as exc:
+        raise HTTPException(
+            status_code=404,
+            detail=_http_error_detail(exc),
+        ) from exc
+
+
+@router.delete("/data-sources/{upload_id}")
+def delete_data_source(
+    request: Request,
+    upload_id: str,
+) -> dict[str, Any]:
+    svc = _service(request)
+
+    try:
+        return _json_safe(svc.delete_data_source(upload_id))
+    except OrchestratorServiceError as exc:
+        raise HTTPException(
+            status_code=400,
+            detail=_http_error_detail(exc),
+        ) from exc
+
+
+@router.patch("/data-sources/{upload_id}")
+def update_data_source(
+    request: Request,
+    upload_id: str,
+    payload: dict[str, Any] = Body(...),
+) -> dict[str, Any]:
+    svc = _service(request)
+
+    try:
+        return _json_safe(svc.update_data_source(upload_id, payload))
+    except OrchestratorServiceError as exc:
+        raise HTTPException(
+            status_code=400,
+            detail=_http_error_detail(exc),
+        ) from exc
+
+
+@router.get("/data-sources/{upload_id}/preview")
+def preview_data_source(
+    request: Request,
+    upload_id: str,
+) -> dict[str, Any]:
+    svc = _service(request)
+
+    try:
+        return _json_safe(svc.preview_data_source(upload_id))
+    except OrchestratorServiceError as exc:
+        raise HTTPException(
+            status_code=404,
+            detail=_http_error_detail(exc),
+        ) from exc
+