gispulse 2.0.0__tar.gz → 2.2.0__tar.gz

{gispulse-2.0.0/src/gispulse.egg-info → gispulse-2.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: gispulse
-Version: 2.0.0
+Version: 2.2.0
 Summary: Modular geospatial engine with business rules, triggers, and dual operating modes (DuckDB/PostGIS)
 Author-email: ImagoData <contact@imagodata.com>
 License-Expression: AGPL-3.0-or-later
@@ -34,6 +34,7 @@ Requires-Dist: pydantic<3.0,>=2.0
 Requires-Dist: pydantic-settings<3.0,>=2.0
 Requires-Dist: PyYAML<7.0,>=6.0
 Requires-Dist: httpx<1.0,>=0.24
+Requires-Dist: openpyxl<4.0,>=3.1
 Provides-Extra: postgis
 Requires-Dist: sqlalchemy<3.0,>=2.0; extra == "postgis"
 Requires-Dist: geoalchemy2<1.0,>=0.14; extra == "postgis"
@@ -60,7 +61,7 @@ Requires-Dist: mapclassify<3.0,>=2.5; extra == "classification"
 Provides-Extra: pointcloud
 Requires-Dist: laspy<3.0,>=2.5; extra == "pointcloud"
 Provides-Extra: redis
-Requires-Dist: redis<8.0,>=5.0; extra == "redis"
+Requires-Dist: redis<9.0,>=5.0; extra == "redis"
 Provides-Extra: s3
 Requires-Dist: boto3<2.0,>=1.28; extra == "s3"
 Provides-Extra: scheduling

{gispulse-2.0.0 → gispulse-2.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "gispulse"
-version = "2.0.0"
+version = "2.2.0"
 description = "Modular geospatial engine with business rules, triggers, and dual operating modes (DuckDB/PostGIS)"
 license = "AGPL-3.0-or-later"
 requires-python = ">=3.10"
@@ -36,6 +36,7 @@ dependencies = [
     "pydantic-settings>=2.0,<3.0",
     "PyYAML>=6.0,<7.0",
     "httpx>=0.24,<1.0",
+    "openpyxl>=3.1,<4.0",
 ]
 
 [project.scripts]
@@ -61,7 +62,7 @@ raster = ["rasterio>=1.3,<2.0", "rasterstats>=0.19,<1.0"]
 network = ["networkx>=3.0,<4.0"]
 classification = ["mapclassify>=2.5,<3.0"]
 pointcloud = ["laspy>=2.5,<3.0"]
-redis = ["redis>=5.0,<8.0"]
+redis = ["redis>=5.0,<9.0"]
 s3 = ["boto3>=1.28,<2.0"]
 scheduling = ["croniter>=1.3,<7.0"]
 sso = ["PyJWT[crypto]>=2.8,<3.0", "httpx>=0.24,<1.0"]

{gispulse-2.0.0 → gispulse-2.2.0}/src/gispulse/__init__.py

@@ -31,10 +31,18 @@ from gispulse import _compat as _compat
 
 _compat.install()
 
-__all__ = ["__version__", "GISPulseApp", "get_app", "apply", "run"]
+__all__ = [
+    "__version__",
+    "GISPulseApp",
+    "get_app",
+    "apply",
+    "load",
+    "publish",
+    "run",
+]
 
 if TYPE_CHECKING:  # pragma: no cover - typing only
-    from gispulse.app import GISPulseApp, apply, get_app, run
+    from gispulse.app import GISPulseApp, apply, get_app, load, publish, run
 
 
 def __getattr__(name: str):
@@ -43,7 +51,7 @@ def __getattr__(name: str):
     Keeps ``import gispulse`` free of heavy imports — ``gispulse.app`` and
     its subsystems are pulled only when the façade is first accessed.
     """
-    if name in {"GISPulseApp", "get_app", "apply", "run"}:
+    if name in {"GISPulseApp", "get_app", "apply", "load", "publish", "run"}:
         from gispulse import app as _app
 
         return getattr(_app, name)

{gispulse-2.0.0 → gispulse-2.2.0}/src/gispulse/_compat.py

@@ -36,17 +36,39 @@ _warned: set[str] = set()
 
 
 class _AliasLoader(Loader):
-    """Loader that resolves a legacy name to its ``gispulse.*`` module."""
+    """Loader that aliases a legacy name to its ``gispulse.*`` module.
+
+    CRITICAL — class identity (see imagodata/gispulse#333): legacy and
+    canonical names MUST point to the *same* module object so that
+    ``from persistence.storage import StorageError`` yields the same class
+    as ``from gispulse.persistence.storage import StorageError``. Without
+    this, ``isinstance(err, StorageError)`` and ``pytest.raises(...)``
+    silently fail across the namespace boundary.
+
+    Implementation: ``exec_module`` overwrites ``sys.modules[spec.name]``
+    with the canonical module *after* Python's import machinery has placed
+    its freshly-created (empty) module there. This is the only point at
+    which the override sticks — doing it in ``create_module`` is reverted
+    by the import system because the returned module's ``__name__`` is the
+    canonical one, not ``spec.name``.
+    """
 
     def __init__(self, target: str) -> None:
         self._target = target
 
-    def create_module(self, spec: importlib.machinery.ModuleSpec) -> ModuleType:
-        return importlib.import_module(self._target)
+    def create_module(self, spec: importlib.machinery.ModuleSpec) -> ModuleType | None:
+        # Returning None lets Python allocate a default empty module under
+        # ``spec.name``; we replace it in ``exec_module``.
+        return None
 
     def exec_module(self, module: ModuleType) -> None:
-        # ``import_module`` in ``create_module`` already executed the module.
-        return None
+        # Resolve the canonical module (may already be cached) and
+        # overwrite the sys.modules entry the import machinery just
+        # installed. From this point on, ``import <legacy>`` and
+        # ``import gispulse.<legacy>`` resolve to the same object, so
+        # class identity holds across both namespaces.
+        target = importlib.import_module(self._target)
+        sys.modules[module.__name__] = target
 
 
 class _LegacyTopLevelFinder(MetaPathFinder):
@@ -76,9 +98,21 @@ class _LegacyTopLevelFinder(MetaPathFinder):
 
 
 def install() -> None:
-    """Append the legacy finder to ``sys.meta_path`` (idempotent)."""
+    """Insert the legacy finder at the front of ``sys.meta_path`` (idempotent).
+
+    The finder MUST run before ``PathFinder``: once we alias
+    ``sys.modules['persistence'] = gispulse.persistence``, the legacy
+    package inherits ``__path__`` from the canonical one. If a standard
+    ``PathFinder`` reached a sub-import (``persistence.storage``) before
+    our shim, it would discover ``gispulse/persistence/storage.py`` via
+    the parent's ``__path__`` and execute it a *second* time under the
+    legacy name — duplicating every class (StorageError, …) and breaking
+    ``isinstance()`` checks (imagodata/gispulse#333).
+
+    Prepending guarantees the alias hook intercepts every legacy import
+    before any path-based finder runs, so ``sys.modules`` ends up with
+    one shared module object per (root, sub) tuple.
+    """
     if any(isinstance(finder, _LegacyTopLevelFinder) for finder in sys.meta_path):
         return
-    # Appended last: real packages always win; the shim only catches names
-    # that no genuine finder could resolve.
-    sys.meta_path.append(_LegacyTopLevelFinder())
+    sys.meta_path.insert(0, _LegacyTopLevelFinder())

gispulse-2.2.0/src/gispulse/adapters/rest/__init__.py

@@ -0,0 +1,15 @@
+"""REST service adapters — GeoJSON and tabular-JSON over HTTP.
+
+Importing this package self-registers the core REST transport adapters in
+:data:`core.sources.PROTOCOLS`, so the ETL fetch path has real fetchers to
+dispatch to: ``rest-api`` (GeoJSON FeatureCollection, #192) and
+``rest-table`` (paginated tabular JSON, #196).
+"""
+
+from __future__ import annotations
+
+# Side-effect imports: each fetcher registers itself on import.
+from gispulse.adapters.rest import rest_fetcher  # noqa: F401
+from gispulse.adapters.rest import rest_table_fetcher  # noqa: F401
+
+__all__ = ["rest_fetcher", "rest_table_fetcher"]

gispulse-2.2.0/src/gispulse/adapters/rest/rest_table_fetcher.py

@@ -0,0 +1,364 @@
+"""Paginated tabular-JSON REST fetcher — ``AccessProtocol.REST_TABLE``.
+
+Issue #196. Sibling of :class:`RestGeoJsonFetcher` (#192): where that
+adapter reads a GeoJSON ``FeatureCollection``, this one reads a tabular
+JSON REST API that answers ``{"data": [...], "next": ...}`` — the shape
+served by Géorisques (``/api/v1/...``), BAN and RNB.
+
+The fetcher is **materialize-only**: a paginated REST API has no
+zero-copy DuckDB scan, so :attr:`~core.plugin_model.FetchMode.REFERENCE`
+raises. Rows are streamed to newline-delimited JSON (JSONL): local file
+by default, or S3/Garage when ``s3_uri`` / ``s3_key`` is supplied.
+
+Like :class:`RestGeoJsonFetcher`, importing this module self-registers
+the fetcher in the process-wide :data:`core.sources.PROTOCOLS` registry
+(idempotent), so the ETL fetch path has a real ``rest-table`` adapter to
+dispatch to.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass, field
+from os import PathLike
+import tempfile
+import time
+from typing import Any, BinaryIO
+from urllib.parse import urlencode, urljoin, urlsplit
+
+from gispulse.core.config import settings
+from gispulse.core.logging import get_logger
+from gispulse.core.plugin_model import (
+    AccessProtocol,
+    AccessSpec,
+    FetchMode,
+    Payload,
+    SourceResult,
+)
+
+log = get_logger(__name__)
+
+_DEFAULT_TIMEOUT_S = 20.0
+#: Hard ceiling on pages followed when the AccessSpec does not set one —
+#: a tabular API with a runaway ``next`` must never loop unbounded.
+_DEFAULT_MAX_PAGES = 1000
+_ROW_SOURCE_KEY = "key"
+_ROW_SOURCE_BODY = "body"
+
+
+def _same_origin(a: str, b: str) -> bool:
+    """True if ``a`` and ``b`` share scheme + host + port.
+
+    A paginated ``next`` link must not steer the fetch to another host —
+    a malicious catalogue entry could otherwise exfiltrate the request or
+    pivot to an internal service across pages.
+    """
+    sa, sb = urlsplit(a), urlsplit(b)
+    return (sa.scheme, sa.netloc) == (sb.scheme, sb.netloc)
+
+
+def _get_json(url: str, timeout: float) -> dict[str, Any]:
+    """GET ``url`` and return the parsed JSON body."""
+    import httpx
+
+    # follow_redirects is OFF: httpx would otherwise chase a 3xx to an
+    # arbitrary host *after* the SSRF/same-origin guard has cleared the
+    # original URL, re-opening the very hole the guard closes (#199).
+    resp = httpx.get(
+        url,
+        timeout=timeout,
+        follow_redirects=False,
+        headers={"Accept": "application/json"},
+    )
+    resp.raise_for_status()
+    return resp.json()
+
+
+def _normalize_row_source(value: Any) -> str:
+    if value in {_ROW_SOURCE_BODY, "object"}:
+        return _ROW_SOURCE_BODY
+    return _ROW_SOURCE_KEY
+
+
+@dataclass(frozen=True)
+class PaginationSpec:
+    """Typed REST_TABLE pagination recipe compiled from ``AccessSpec.params``."""
+
+    data_key: Any = "data"
+    next_key: Any | None = None
+    row_source: str = _ROW_SOURCE_KEY
+    empty_statuses: frozenset[Any] = field(default_factory=frozenset)
+    empty_body_is_empty: bool = False
+    max_pages: int = _DEFAULT_MAX_PAGES
+    max_rows: int | None = None
+    max_total_seconds: float | None = None
+
+    @classmethod
+    def from_params(cls, params: dict[str, Any]) -> PaginationSpec:
+        pagination = dict(params.get("pagination") or {})
+        row_source = pagination.get("row_source", pagination.get("row_shape"))
+        max_rows = pagination.get("max_rows")
+        max_total_seconds = pagination.get("max_total_seconds")
+        return cls(
+            data_key=pagination.get("data_key", "data"),
+            next_key=pagination.get("next_key"),
+            row_source=_normalize_row_source(row_source),
+            empty_statuses=frozenset(pagination.get("empty_statuses") or []),
+            empty_body_is_empty=bool(pagination.get("empty_body_is_empty", False)),
+            max_pages=int(pagination.get("max_pages", _DEFAULT_MAX_PAGES)),
+            max_rows=int(max_rows) if max_rows is not None else None,
+            max_total_seconds=(
+                float(max_total_seconds) if max_total_seconds is not None else None
+            ),
+        )
+
+
+def _rows_from_body(body: dict[str, Any], spec: PaginationSpec) -> list[Any]:
+    if spec.row_source == _ROW_SOURCE_BODY:
+        return [body]
+    page_rows = body.get(spec.data_key)
+    if isinstance(page_rows, list):  # ignore a non-list data_key
+        return page_rows
+    return []
+
+
+def _next_page_url(
+    body: dict[str, Any],
+    current_url: str,
+    origin: str,
+    seen: set[str],
+    spec: PaginationSpec,
+) -> str | None:
+    nxt = body.get(spec.next_key) if spec.next_key else None
+    if not nxt:
+        return None
+    # Resolve a relative ``next`` ("?page=2") against the current page URL,
+    # then re-guard the absolute result before the next request.
+    candidate = urljoin(current_url, str(nxt))
+    if candidate not in seen and _same_origin(origin, candidate):
+        return candidate
+    return None
+
+
+def _write_jsonl(
+    rows: list[Any],
+    local_path: str | PathLike[str] | None,
+) -> tuple[str | PathLike[str], str, int]:
+    if not local_path:
+        handle = tempfile.NamedTemporaryFile(suffix=".jsonl", delete=False)
+        handle.close()
+        local_path = handle.name
+    digest = hashlib.sha256()
+    row_count = 0
+    with open(local_path, "wb") as fh:
+        for row in rows:
+            line = (json.dumps(row, separators=(",", ":")) + "\n").encode("utf-8")
+            digest.update(line)
+            fh.write(line)
+            row_count += 1
+    return local_path, digest.hexdigest(), row_count
+
+
+def _resolve_s3_materialize_uri(params: dict[str, Any]) -> str | None:
+    s3_uri = str(params.get("s3_uri", "") or "").strip()
+    if s3_uri:
+        return s3_uri
+
+    s3_key = str(params.get("s3_key", "") or "").strip().lstrip("/")
+    if not s3_key:
+        return None
+
+    bucket = str(params.get("s3_bucket", "") or "").strip() or settings.s3.bucket
+    return f"s3://{bucket}/{s3_key}"
+
+
+def _write_jsonl_row(row: Any, fh: BinaryIO, digest: Any) -> int:
+    line = (json.dumps(row, separators=(",", ":")) + "\n").encode("utf-8")
+    digest.update(line)
+    fh.write(line)
+    return 1
+
+
+def _run_async(coro: Any) -> Any:
+    import asyncio
+    import threading
+
+    try:
+        asyncio.get_running_loop()
+    except RuntimeError:
+        return asyncio.run(coro)
+
+    result: dict[str, Any] = {}
+
+    def runner() -> None:
+        try:
+            result["value"] = asyncio.run(coro)
+        except BaseException as exc:  # noqa: BLE001 - propagate from worker
+            result["error"] = exc
+
+    thread = threading.Thread(target=runner)
+    thread.start()
+    thread.join()
+    if "error" in result:
+        raise result["error"]
+    return result.get("value")
+
+
+def _upload_jsonl_to_s3(s3_uri: str, body: BinaryIO) -> None:
+    parsed = urlsplit(s3_uri)
+    bucket = parsed.netloc
+    key = parsed.path.lstrip("/")
+    if parsed.scheme != "s3" or not bucket or not key:
+        raise ValueError(f"Invalid REST_TABLE S3 destination: {s3_uri!r}")
+    if not settings.s3.endpoint:
+        raise ValueError("REST_TABLE S3 materialization requires GISPULSE_S3_ENDPOINT")
+
+    from gispulse.persistence.storage import S3Storage
+    from gispulse.persistence.tier import check_tier
+
+    check_tier("pro")
+    storage = S3Storage(
+        endpoint_url=settings.s3.endpoint,
+        bucket=bucket,
+        access_key=settings.s3.access_key,
+        secret_key=settings.s3.secret_key,
+        region=settings.s3.region,
+    )
+    _run_async(storage.upload(key, body, content_type="application/x-ndjson"))
+
+
+class RestTableFetcher:
+    """:class:`~core.sources.Fetcher` for ``AccessProtocol.REST_TABLE``."""
+
+    protocol = AccessProtocol.REST_TABLE
+    payload = Payload.TABLE
+
+    def fetch(
+        self,
+        access: AccessSpec,
+        *,
+        extent: Any | None = None,
+        mode: FetchMode = FetchMode.MATERIALIZE,
+    ) -> SourceResult:
+        if mode is FetchMode.REFERENCE:
+            raise NotImplementedError("REST_TABLE is materialize-only")
+
+        params = dict(access.params or {})
+        timeout = float(params.get("timeout", _DEFAULT_TIMEOUT_S))
+        pagination = PaginationSpec.from_params(params)
+        deadline = (
+            time.monotonic() + pagination.max_total_seconds
+            if pagination.max_total_seconds is not None
+            else None
+        )
+
+        import httpx
+
+        from gispulse.core.ssrf import guard_outbound_url
+
+        query = dict(params.get("query") or {})
+        origin = access.endpoint
+        if query:
+            sep = "&" if "?" in origin else "?"
+            origin = f"{origin}{sep}{urlencode(query)}"
+        s3_uri = _resolve_s3_materialize_uri(params)
+        local_path = params.get("local_path")
+        if s3_uri:
+            fh: BinaryIO = tempfile.SpooledTemporaryFile(
+                max_size=64 * 1024 * 1024,
+                mode="w+b",
+            )
+        else:
+            if not local_path:
+                handle = tempfile.NamedTemporaryFile(suffix=".jsonl", delete=False)
+                handle.close()
+                local_path = handle.name
+            fh = open(local_path, "wb")
+
+        digest = hashlib.sha256()
+        row_count = 0
+        page_count = 0
+        seen: set[str] = set()
+        url: str | None = origin
+        try:
+            while url:
+                guard_outbound_url(url)
+                seen.add(url)
+                try:
+                    body = _get_json(url, timeout)
+                except httpx.HTTPStatusError as exc:
+                    if exc.response.status_code in pagination.empty_statuses:
+                        break  # "no data here" — leave the result empty
+                    raise
+                except json.JSONDecodeError:
+                    if pagination.empty_body_is_empty:
+                        break  # empty/malformed body configured as "no data here"
+                    raise
+                page_count += 1
+                for row in _rows_from_body(body, pagination):
+                    if (
+                        pagination.max_rows is not None
+                        and row_count >= pagination.max_rows
+                    ):
+                        break
+                    row_count += _write_jsonl_row(row, fh, digest)
+                if (
+                    pagination.max_rows is not None
+                    and row_count >= pagination.max_rows
+                ):
+                    break
+                if page_count >= pagination.max_pages:
+                    break
+                if deadline is not None and time.monotonic() >= deadline:
+                    break
+                url = _next_page_url(body, url, origin, seen, pagination)
+
+            if s3_uri:
+                fh.seek(0)
+                _upload_jsonl_to_s3(s3_uri, fh)
+        finally:
+            fh.close()
+
+        log.info(
+            "rest_table_materialized",
+            endpoint=access.endpoint,
+            row_count=row_count,
+            page_count=page_count,
+        )
+        data = s3_uri if s3_uri else local_path
+        metadata = {
+            "row_count": row_count,
+            "page_count": page_count,
+            "source_url": access.endpoint,
+            "sha256": digest.hexdigest(),
+        }
+        if s3_uri:
+            metadata["s3_uri"] = s3_uri
+        return SourceResult(
+            payload=Payload.TABLE,
+            mode=FetchMode.MATERIALIZE,
+            data=data,
+            reference=s3_uri,
+            metadata=metadata,
+        )
+
+
+def register_rest_table_fetcher(registry: Any | None = None) -> None:
+    """Register a :class:`RestTableFetcher` under ``REST_TABLE`` — idempotent."""
+    from gispulse.core.sources import PROTOCOLS, ProtocolNotSupported
+
+    target = registry if registry is not None else PROTOCOLS
+    try:
+        target.get_fetcher(AccessProtocol.REST_TABLE)
+        return  # already registered
+    except ProtocolNotSupported:
+        pass
+    target.register(RestTableFetcher())
+
+
+# Importing this module wires the fetcher into the global registry (#192 pattern).
+register_rest_table_fetcher()
+
+
+__all__ = ["RestTableFetcher", "register_rest_table_fetcher"]

{gispulse-2.0.0 → gispulse-2.2.0}/src/gispulse/app.py

@@ -37,6 +37,8 @@ if TYPE_CHECKING:  # pragma: no cover - typing only
     import geopandas as gpd
 
     from gispulse.catalog.models import CatalogEntry
+    from gispulse.core.explain import ManifestExplanation
+    from gispulse.core.manifest_v3 import ManifestV3
     from gispulse.core.pipeline import PipelineSpec
     from gispulse.core.plugin_model import PluginRecord
     from gispulse.runtime.headless_runtime import HeadlessRuntime
@@ -148,6 +150,78 @@ class GISPulseApp:
     # ------------------------------------------------------------------
     # Datasets
     # ------------------------------------------------------------------
+    def load(
+        self,
+        source: "str | Path | Any",
+        *,
+        bbox: "tuple[float, float, float, float] | None" = None,
+        layer: str | None = None,
+        lazy: bool = False,
+        crs: str | None = None,
+        **opts: Any,
+    ) -> "gpd.GeoDataFrame | Any":
+        """Load any supported source into a GeoDataFrame.
+
+        The unified entry point over every reader GISPulse owns — local
+        files (GeoPackage, GeoJSON, GeoParquet, Shapefile, …) and remote
+        protocol sources (GeoParquet on S3/HTTP, OGC API Features, WFS,
+        STAC, …). The result is a plain GeoDataFrame, so any capability
+        runs on it directly: ``app.apply(verb, app.load(src), ...)``.
+
+        Args:
+            source: A path, a ``s3://`` / ``https://`` / named-protocol
+                URI, an :class:`~gispulse.core.plugin_model.AccessSpec`,
+                or an access-descriptor ``dict``.
+            bbox:   Spatial filter ``(minx, miny, maxx, maxy)`` pushed
+                    down to the reader/fetcher when supported.
+            layer:  Layer name for multi-layer file formats.
+            lazy:   Return a :class:`~gispulse.persistence.loader.LazyDataset`
+                    handle for remote sources instead of materialising.
+            crs:    Force this CRS when the source declares none.
+            **opts: Extra options forwarded to the underlying reader.
+
+        Returns:
+            A GeoDataFrame, or a ``LazyDataset`` when ``lazy=True`` on a
+            remote source.
+        """
+        from gispulse.persistence.loader import load as _load
+
+        return _load(source, bbox=bbox, layer=layer, lazy=lazy, crs=crs, **opts)
+
+    def publish(
+        self,
+        gdf: "gpd.GeoDataFrame",
+        target: str,
+        *,
+        auth: str | None = None,
+        overwrite: bool = True,
+        **opts: Any,
+    ) -> dict:
+        """Publish a GeoDataFrame to a writable destination.
+
+        Currently supports GeoNode (``geonode://<instance>/<dataset>``),
+        the write counterpart of :meth:`load`. The frame is packaged and
+        uploaded through the destination's native publish API.
+
+        Args:
+            gdf:       The GeoDataFrame to publish.
+            target:    Destination URI (``geonode://…``).
+            auth:      Credential/token; falls back to the instance config.
+            overwrite: Replace an existing dataset of the same name.
+            **opts:    Extra options forwarded to the writer.
+
+        Returns:
+            The writer's response payload.
+        """
+        from gispulse.persistence.geonode import GEONODE_SCHEME, publish as _publish
+
+        if str(target).partition("://")[0].lower() == GEONODE_SCHEME:
+            return _publish(gdf, target, auth=auth, overwrite=overwrite, **opts)
+        raise ValueError(
+            f"unsupported publish target {target!r}; "
+            "supported schemes: geonode://"
+        )
+
     def load_dataset(
         self, path: "str | Path", layer: str | None = None
     ) -> "gpd.GeoDataFrame":
@@ -480,6 +554,33 @@ class GISPulseApp:
 
         return build_runtime(gpkg_path, triggers, **kwargs)
 
+    # ------------------------------------------------------------------
+    # ELT — manifest v3 introspection (Lot 4E / #251)
+    # ------------------------------------------------------------------
+    def explain(
+        self,
+        manifest: "str | Path | ManifestV3",
+        *,
+        engine: str | None = None,
+    ) -> "ManifestExplanation":
+        """Return a structured explanation of a v3 manifest.
+
+        Walks the manifest's compiled DAG and, for each step, surfaces
+        which :class:`ExecutionStrategy` ``select_strategy()`` would pick
+        under the configured engine. Capabilities with no SQL strategy
+        are flagged ``etl_strict``. See
+        :func:`gispulse.core.explain.explain_manifest` for the report
+        shape and :func:`format_explanation_text` to render it.
+        """
+        from gispulse.core.explain import explain_manifest
+        from gispulse.core.manifest_v3 import ManifestV3, load_manifest_v3
+
+        if isinstance(manifest, ManifestV3):
+            mf = manifest
+        else:
+            mf = load_manifest_v3(manifest)
+        return explain_manifest(mf, engine=engine)
+
 
 @lru_cache(maxsize=1)
 def get_app() -> GISPulseApp:
@@ -506,4 +607,33 @@ def run(
     return get_app().run_pipeline(spec, inputs, params)
 
 
-__all__ = ["GISPulseApp", "get_app", "apply", "run"]
+def load(
+    source: "str | Path | Any",
+    *,
+    bbox: "tuple[float, float, float, float] | None" = None,
+    layer: str | None = None,
+    lazy: bool = False,
+    crs: str | None = None,
+    **opts: Any,
+) -> "gpd.GeoDataFrame | Any":
+    """Load any supported source — shortcut for ``get_app().load``."""
+    return get_app().load(
+        source, bbox=bbox, layer=layer, lazy=lazy, crs=crs, **opts
+    )
+
+
+def publish(
+    gdf: "gpd.GeoDataFrame",
+    target: str,
+    *,
+    auth: str | None = None,
+    overwrite: bool = True,
+    **opts: Any,
+) -> dict:
+    """Publish a GeoDataFrame — shortcut for ``get_app().publish``."""
+    return get_app().publish(
+        gdf, target, auth=auth, overwrite=overwrite, **opts
+    )
+
+
+__all__ = ["GISPulseApp", "get_app", "apply", "load", "publish", "run"]