core-lens 0.1.dev135__tar.gz → 0.1.dev138__tar.gz

{core_lens-0.1.dev135 → core_lens-0.1.dev138}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: core-lens
-Version: 0.1.dev135
+Version: 0.1.dev138
 Summary: Query, analyse, and visualise CoreStack's microwatershed and Earth science data through a clean, composable Python API.
 Project-URL: Homepage, https://github.com/ApoorvaKashyap/core-lens
 Project-URL: Issues, https://github.com/ApoorvaKashyap/core-lens/issues

{core_lens-0.1.dev135 → core_lens-0.1.dev138}/docs/source/export.md

@@ -41,7 +41,13 @@ geoparquet(
 
 # Export to GeoJSON
 geojson(spatial_res, "output.json")
+
+# Export to newline-delimited GeoJSON (GeoJSONSeq)
+geojson(spatial_res, "output.ndjson", driver="GeoJSONSeq")
 ```
 
-> [!NOTE]
-> Exporting to geospatial formats automatically uses DuckDB to cast WKB geometries to proper spatial types via the `spatial` extension. CoreLens handles the installation and loading of the extension seamlessly under the hood.
+```{note}
+Exporting to **GeoParquet** uses DuckDB to cast WKB geometries to proper spatial types via the `spatial` extension. CoreLens handles the installation and loading of the extension seamlessly under the hood.
+
+Exporting to **GeoJSON** is fully natively streamed directly from Polars and Shapely without invoking GDAL or DuckDB, making it extremely fast for large datasets. Driver-specific kwargs for GeoJSON are ignored.
+```

{core_lens-0.1.dev135 → core_lens-0.1.dev138}/docs/source/intro.md

@@ -13,4 +13,6 @@ CoreLens provides a unified interface over microwatersheds, administrative bound
 - **Temporal & Seasonal Awareness**: Native support for agronomic seasons (Kharif, Rabi, Zaid) and time-range filtering.
 - **Spatial Statistics & Analysis**: Built-in methods for anomaly detection, spatial similarity, temporal correlation, and hypothesis testing.
 - **Interactive Visualisation**: Generate interactive maps using Lonboard with zero-copy GeoArrow rendering directly from Polars, and timeseries/scatter plots using Bokeh.
-- **High-Performance Exports**: Export results directly to Parquet, JSON, CSV, or spatially-enabled GeoParquet and GeoJSON using integrated DuckDB spatial extensions.
+- **Cloud & Local Data**: Native support for reading Parquet data from local filesystems or directly from cloud storage (e.g., `s3://`).
+- **High-Performance Exports**: Export results directly to Parquet, JSON, CSV, or spatially-enabled GeoParquet and GeoJSON (with a fast streaming writer).
+- **Advanced Caching**: Transparently caches boundaries and pre-computes spatial indices (via on-disk sidecars) to achieve sub-second query initialisation times.

{core_lens-0.1.dev135 → core_lens-0.1.dev138}/docs/source/queries.md

@@ -58,5 +58,6 @@ joined_view = aoi.mws.spatial_join(
 # res = joined_view.annual
 ```
 
-> [!NOTE]
-> Cross-entity spatial join execution (materialisation) is currently under development and will be added in a subsequent release. Calling materialisation methods (like `.annual`, `.static`, or `.fortnightly`) on a joined view will raise a `NotImplementedError` in the current version.
+```{note}
+Cross-entity spatial join execution (materialisation) is currently under development and will be added in a subsequent release. Calling materialisation methods (like `.annual`, `.static`, or `.fortnightly`) on a joined view will raise a `NotImplementedError` in the current version.
+```

{core_lens-0.1.dev135 → core_lens-0.1.dev138}/docs/source/quickstart.md

@@ -25,18 +25,18 @@ AoI.register(MWSEntity)
 AoI.register(TehsilEntity)
 ```
 
-Create an `AoI` (Area of Interest) by specifying the `data_root` and your boundary (either by name, bounding box, or Shapely geometry):
+Create an `AoI` (Area of Interest) by specifying the `data_root` (which can be a local path or a cloud URI like `s3://bucket/data`) and your boundary (either by name, bounding box, or Shapely geometry):
 
 ```python
-# Create an AoI scoped to a specific Tehsil
+# Create an AoI scoped to a specific Tehsil using a local path
 aoi = AoI(
     data_root="/path/to/data",
     tehsil="Pangi"
 )
 
-# Or scope it directly to a specific list of entity IDs
+# Or scope it directly to a specific list of entity IDs using an S3 bucket
 aoi_specific = AoI(
-    data_root="/path/to/data",
+    data_root="s3://my-cloud-bucket/core-lens-data",
     mws_id=["13_001", "13_002"]
 )
 

{core_lens-0.1.dev135 → core_lens-0.1.dev138}/src/core_lens/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.1.dev135'
-__version_tuple__ = version_tuple = (0, 1, 'dev135')
+__version__ = version = '0.1.dev138'
+__version_tuple__ = version_tuple = (0, 1, 'dev138')
 
 __commit_id__ = commit_id = None

{core_lens-0.1.dev135 → core_lens-0.1.dev138}/src/core_lens/aoi.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import functools
 import os
 import pathlib
 from dataclasses import dataclass
@@ -12,13 +13,15 @@ if TYPE_CHECKING:
     from core_lens.base.result import Result
 
 import polars as pl
+import shapely
+import shapely.geometry as sgeom
+import shapely.ops as sops
 from loguru import logger
 
 from core_lens.base.entity import BaseEntity, EntityValidationError
 from core_lens.utils.paths import is_cloud_uri
 
 if TYPE_CHECKING:
-    import shapely
     from core_lens.base.view import View
 
 
@@ -125,6 +128,121 @@ def _default_season_config() -> SeasonConfig:
 _REGISTRY: dict[str, type[BaseEntity]] = {}
 
 
+# ---------------------------------------------------------------------------
+# Process-level boundary cache — shared across all AoI instances.
+#
+# Keyed on (data_root, storage_options_key, entity_kwargs_key).
+# Returns a (geometry_wkb, entity_name, key_rows_tuple) triple so the
+# expensive scan + WKB decode + unary_union is only paid once per process
+# per unique boundary specification.
+#
+# Cache diagnostics: _cached_resolve_boundary.cache_info()
+# Cache reset (tests): _cached_resolve_boundary.cache_clear()
+# ---------------------------------------------------------------------------
+
+
+@functools.cache
+def _cached_resolve_boundary(
+    data_root: str,
+    storage_options_key: tuple[tuple[str, Any], ...],
+    entity_kwargs_key: tuple[tuple[str, Any], ...],
+) -> tuple[bytes, str, tuple[tuple[Any, ...], ...]]:
+    """Cached boundary resolution: return ``(geometry_wkb, entity_name, key_rows)``.
+
+    All arguments must be hashable.  ``entity_kwargs`` must be converted to a
+    sorted tuple of ``(key, value)`` pairs before calling this function.
+
+    The returned triple contains:
+
+    * **geometry_wkb** — WKB bytes of the unioned boundary geometry.
+    * **entity_name** — name of the entity that defined the boundary
+      (e.g. ``"mws"`` or ``"tehsil"``).
+    * **key_rows** — tuple of key-value tuples for the matched rows
+      (e.g. ``(("mws_id", "13_551"),)`` for a single-row result).
+
+    Args:
+        data_root (str): Resolved data root path or cloud URI.
+        storage_options_key (tuple): Sorted ``storage_options`` items (hashable).
+        entity_kwargs_key (tuple): Sorted ``entity_kwargs`` items (hashable).
+
+    Returns:
+        tuple: ``(geometry_wkb, entity_name, key_rows)``.
+    """
+    from core_lens.base.entity import _entity_name as _ename
+
+    entity_kwargs: dict[str, Any] = dict(entity_kwargs_key)
+    storage_options: dict[str, Any] = dict(storage_options_key)
+
+    # Instantiate a throw-away AoI-like context to run the resolution logic.
+    # We cannot use a live AoI instance here (would be circular), so we
+    # inline the logic from _resolve_named_boundary.
+    candidate: BaseEntity | None = None
+
+    # First pass: find entity whose schema columns match the kwargs.
+    for ename in _REGISTRY:
+        entity_cls = _REGISTRY[ename]
+        entity = entity_cls(
+            data_root=data_root,
+            storage_options=storage_options or None,
+        )
+        schema = entity.schema_profile  # uses _cached_detect — I/O only once
+        if any(
+            k in schema.key_cols or k in schema.extra_static_cols for k in entity_kwargs
+        ):
+            candidate = entity
+            break
+
+    # Fallback: entity name matches a kwarg key.
+    if candidate is None:
+        for ename in _REGISTRY:
+            if ename in entity_kwargs:
+                entity_cls = _REGISTRY[ename]
+                candidate = entity_cls(
+                    data_root=data_root,
+                    storage_options=storage_options or None,
+                )
+                break
+
+    if candidate is None:
+        raise EntityValidationError(
+            f"No registered entity can satisfy the filters {entity_kwargs}. "
+            f"Registered entities: {sorted(_REGISTRY)}."
+        )
+
+    schema = candidate.schema_profile
+    geom_col = schema.geometry_col
+    static_path = candidate._resolve(candidate.static_path)
+
+    lf = pl.scan_parquet(static_path, storage_options=storage_options or None)
+    filter_expr = pl.lit(True)
+    for col, val in entity_kwargs.items():
+        if col in schema.key_cols or col in schema.extra_static_cols:
+            if isinstance(val, list):
+                lf = lf.filter(pl.col(col).is_in(val))
+            else:
+                filter_expr = filter_expr & (pl.col(col) == val)
+
+    df = lf.filter(filter_expr).select(candidate.key_cols + [geom_col]).collect()
+
+    if df.is_empty():
+        raise ValueError(
+            f"No rows matched the filters {entity_kwargs} in {candidate.static_path!r}."
+        )
+
+    geoms = shapely.from_wkb(df[geom_col].to_numpy())
+    unified = sops.unary_union(geoms) if len(geoms) > 1 else geoms[0]
+    geom_wkb: bytes = shapely.to_wkb(unified)
+
+    entity_name = _ename(type(candidate))
+    # Serialise key DataFrame as a tuple-of-tuples for the cache return value.
+    key_rows = tuple(
+        tuple(row[c] for c in candidate.key_cols)
+        for row in df.select(candidate.key_cols).to_dicts()
+    )
+
+    return geom_wkb, entity_name, key_rows
+
+
 class AoI:
     """Area of Interest — the primary entry point for querying geospatial data.
 
@@ -365,7 +483,9 @@ class AoI:
                 data_root=self.data_root,
                 storage_options=self._storage_options or None,
             )
-            _validate_entity(entity, name)
+            # Only validate path existence here — schema detection (parquet
+            # footer reads) is deferred to first data access via schema_profile.
+            _validate_entity_paths(entity, name)
             self._entity_instances[name] = entity
         return self._entity_instances[name]
 
@@ -427,9 +547,11 @@ class AoI:
     ) -> "shapely.Geometry":
         """Resolve a set of named attribute filters to a Shapely geometry.
 
-        The entity whose key column matches one of the kwargs is queried.
-        Multiple kwargs act as AND-filters (e.g. tehsil + district narrows to
-        the unique matching row).
+        Delegates to the process-level :func:`_cached_resolve_boundary` cache
+        so that the expensive Parquet scan + WKB decode + ``unary_union`` is
+        only paid once per unique ``(data_root, entity_kwargs)`` combination
+        within a Python process.  Subsequent ``AoI()`` calls with the same
+        boundary specification reconstruct the geometry from cached WKB bytes.
 
         Args:
             entity_kwargs (dict[str, str | list[str]]): Column–value pairs used to identify the boundary.
@@ -441,85 +563,47 @@ class AoI:
             :class:`~core_lens.base.EntityValidationError`: If no registered entity can satisfy the filters.
             ValueError: If the filters match zero rows.
         """
-        import shapely.ops as sops
-
         logger.debug("Resolving named boundary using kwargs: {}", entity_kwargs)
 
-        # Find the registered entity whose key_col or known attribute column
-        # matches one of the filter keys.  Entities are lazily instantiated
-        # via _get_entity() — only those inspected during the search are built.
-        candidate: BaseEntity | None = None
-        for name in _REGISTRY:
-            entity = self._get_entity(name)
-            schema = entity.schema_profile
-            if any(
-                k in schema.key_cols or k in schema.extra_static_cols
-                for k in entity_kwargs
-            ):
-                candidate = entity
-                break
-
-        # Fall back: look for an entity whose name matches a kwarg key
-        # (e.g. tehsil="Pangi" → TehsilEntity if registered as "tehsil").
-        if candidate is None:
-            logger.debug(
-                "No direct column match found for kwargs, attempting entity name fallback"
-            )
-            for name in _REGISTRY:
-                if name in entity_kwargs:
-                    candidate = self._get_entity(name)
-                    break
-
-        if candidate is None:
-            logger.error(
-                "Boundary resolution failed: no registered entity matched filters {}",
-                entity_kwargs,
-            )
-            raise EntityValidationError(
-                f"No registered entity can satisfy the filters {entity_kwargs}. "
-                f"Registered entities: {sorted(_REGISTRY)}."
-            )
-
-        schema = candidate.schema_profile
-        geom_col = schema.geometry_col
-
-        # Build a lazy frame to push filters down into the Parquet reader.
-        # This avoids loading the entire geometry column into memory.
-        lf = pl.scan_parquet(candidate._resolve(candidate.static_path))
-
-        filter_expr = pl.lit(True)
-        for col, val in entity_kwargs.items():
-            if (
-                col in candidate.schema_profile.key_cols
-                or col in candidate.schema_profile.extra_static_cols
-            ):
-                if isinstance(val, list):
-                    lf = lf.filter(pl.col(col) == val)
-                else:
-                    filter_expr = filter_expr & (pl.col(col) == val)
-
-        df = lf.filter(filter_expr).select(candidate.key_cols + [geom_col]).collect()
-
-        # Cache the boundary-defining entity's name and its exact key rows so
-        # that __getattr__ can short-circuit the spatial_filter for this one
-        # entity — the keys are already known, no need to rebuild the bbox
-        # index or re-run a geometric predicate.
-        self._boundary_entity_name = _entity_name(type(candidate))
-        self._boundary_keys = df.select(candidate.key_cols)
+        from core_lens.base.entity import _so_key
+
+        # Build hashable cache key from entity_kwargs.
+        # list values are converted to tuples so they are hashable.
+        kwargs_hashable: dict[str, Any] = {
+            k: tuple(v) if isinstance(v, list) else v for k, v in entity_kwargs.items()
+        }
+        entity_kwargs_key = tuple(sorted(kwargs_hashable.items()))
+        data_root_str = str(self.data_root)
+        so_key = _so_key(self._storage_options)
+
+        # Delegate to the process-level cache.  On a cache miss this runs the
+        # full scan + WKB decode + unary_union; on a hit it returns instantly.
+        geom_wkb, boundary_entity_name, key_rows = _cached_resolve_boundary(
+            data_root_str, so_key, entity_kwargs_key
+        )
 
-        if df.is_empty():
-            logger.error(
-                "Boundary resolution failed: no rows matched filters {}", entity_kwargs
+        # Reconstruct the boundary geometry from cached WKB bytes (fast).
+        geometry: shapely.Geometry = shapely.from_wkb(geom_wkb)
+
+        # Reconstruct _boundary_keys DataFrame from cached key_rows.
+        # We need the key column names — get them from the boundary entity.
+        boundary_entity_cls = _REGISTRY.get(boundary_entity_name)
+        if boundary_entity_cls is not None:
+            key_cols = boundary_entity_cls().key_cols
+            self._boundary_entity_name = boundary_entity_name
+            self._boundary_keys = pl.DataFrame(
+                {col: [row[i] for row in key_rows] for i, col in enumerate(key_cols)}
             )
-            raise ValueError(
-                f"No rows matched the filters {entity_kwargs} "
-                f"in {candidate.static_path!r}."
+        else:
+            # Registry changed since cache was populated — defensive fallback.
+            logger.warning(
+                "Boundary cache returned entity name '{}' not found in current registry.",
+                boundary_entity_name,
             )
+            self._boundary_entity_name = None
+            self._boundary_keys = None
 
-        import shapely
-
-        geoms = shapely.from_wkb(df[geom_col].to_numpy())
-        return sops.unary_union(geoms) if len(geoms) > 1 else geoms[0]
+        return geometry
 
     @classmethod
     def register(cls, entity_cls: type[BaseEntity]) -> None:
@@ -588,27 +672,29 @@ def _entity_name(entity_cls: type[BaseEntity]) -> str:
 def _bbox_to_polygon(
     bbox: tuple[float, float, float, float],
 ) -> "shapely.Geometry":
-    import shapely.geometry as sgeom
-
     minx, miny, maxx, maxy = bbox
     return sgeom.box(minx, miny, maxx, maxy)
 
 
-def _validate_entity(entity: BaseEntity, name: str) -> None:
-    """Validate an entity's paths and schema.
+def _validate_entity_paths(entity: BaseEntity, name: str) -> None:
+    """Validate an entity's path existence only — no Parquet I/O.
 
-    File-existence checks are performed eagerly for local paths.  Schema
-    validation (key columns, geometry column) is delegated to
-    :attr:`BaseEntity.schema_profile`, which routes through the process-level
-    :func:`_cached_detect` cache — so the second ``AoI()`` pointed at the
-    same ``data_root`` pays zero Parquet footer reads for validation.
+    Checks that ``static_path``, ``annual_path``, and ``fortnightly_path``
+    resolve to existing local files.  Schema validation (key columns,
+    geometry column, geometry type) is intentionally deferred to first data
+    access via :attr:`BaseEntity.schema_profile`, which routes through the
+    process-level :func:`~core_lens.base.entity._cached_detect` cache.
+
+    This is the fast variant called from :meth:`AoI._get_entity`.  Use
+    :func:`_validate_entity` for the full eager check (e.g. in
+    :meth:`AoI.validate` or for absolute-path entities at register time).
 
     Args:
         entity (BaseEntity): The entity instance to validate.
         name (str): Human-readable entity name for error messages.
 
     Raises:
-        EntityValidationError: If any validation check fails.
+        EntityValidationError: If any path does not exist.
     """
     # --- Static path existence check ----------------------------------------
     try:
@@ -623,9 +709,6 @@ def _validate_entity(entity: BaseEntity, name: str) -> None:
             f"Entity {name!r}: static_path {entity.static_path!r} does not exist."
         )
 
-    # For local paths perform an eager existence check; for cloud paths we rely
-    # on the schema-read below to surface a missing-file error (avoids an extra
-    # HeadObject call per entity at startup).
     if not is_cloud_uri(static) and not os.path.exists(static):
         logger.error(
             "Validation failed for entity {}: static path '{}' does not exist.",
@@ -636,26 +719,7 @@ def _validate_entity(entity: BaseEntity, name: str) -> None:
             f"Entity {name!r}: static_path {static!r} does not exist."
         )
 
-    # --- Schema validation (key_cols, geometry_col, geometry_type) -----------
-    # Delegate to schema_profile which routes through _cached_detect.
-    # detect() internally calls _require_cols for key_cols and geometry_col,
-    # and infers geometry_type — so this covers the same checks that the old
-    # _validate_entity did with a raw pl.scan_parquet().collect_schema(), but
-    # without a redundant footer read.
-    try:
-        _ = entity.schema_profile
-    except Exception as exc:
-        logger.error(
-            "Validation failed for entity {}: could not read schema from '{}': {}",
-            name,
-            static,
-            exc,
-        )
-        raise EntityValidationError(
-            f"Entity {name!r}: could not read schema from {static!r}: {exc}"
-        ) from exc
-
-    # --- Temporal path existence checks -------------------------------------
+    # --- Temporal path existence checks (no schema read) --------------------
     for attr, label in [("annual_path", "annual"), ("fortnightly_path", "fortnightly")]:
         path = getattr(entity, attr)
         if path is not None:
@@ -663,10 +727,8 @@ def _validate_entity(entity: BaseEntity, name: str) -> None:
                 abs_path = entity._resolve(path)
             except FileNotFoundError:
                 abs_path = None
-            if (
-                abs_path is not None
-                and not is_cloud_uri(abs_path)
-                and not os.path.exists(abs_path)
+            if abs_path is None or (
+                not is_cloud_uri(abs_path) and not os.path.exists(abs_path)
             ):
                 logger.error(
                     "Validation failed for entity {}: {} path '{}' does not exist.",
@@ -677,13 +739,47 @@ def _validate_entity(entity: BaseEntity, name: str) -> None:
                 raise EntityValidationError(
                     f"Entity {name!r}: {label}_path {path!r} does not exist."
                 )
-            elif abs_path is None:
-                logger.error(
-                    "Validation failed for entity {}: {} path '{}' does not exist.",
-                    name,
-                    label,
-                    path,
-                )
-                raise EntityValidationError(
-                    f"Entity {name!r}: {label}_path {path!r} does not exist."
-                )
+
+
+def _validate_entity(entity: BaseEntity, name: str) -> None:
+    """Validate an entity's paths and schema (full eager check).
+
+    Runs path existence checks via :func:`_validate_entity_paths`, then
+    triggers schema detection (Parquet footer reads) by accessing
+    :attr:`BaseEntity.schema_profile`.  The result is cached by
+    :func:`~core_lens.base.entity._cached_detect`, so the second call for the
+    same ``data_root`` pays no I/O.
+
+    Called by :meth:`AoI.validate` and by :meth:`AoI.register` for
+    entities with absolute paths.  Normal lazy instantiation via
+    :meth:`AoI._get_entity` uses the cheaper :func:`_validate_entity_paths`.
+
+    Args:
+        entity (BaseEntity): The entity instance to validate.
+        name (str): Human-readable entity name for error messages.
+
+    Raises:
+        EntityValidationError: If any validation check fails.
+    """
+    # Fast path-only check first.
+    _validate_entity_paths(entity, name)
+
+    # --- Schema validation (key_cols, geometry_col, geometry_type) -----------
+    # Accessing schema_profile triggers _cached_detect, which reads Parquet
+    # footer metadata.  Subsequent calls for the same data_root are free.
+    try:
+        static = entity._resolve(entity.static_path)
+        _ = entity.schema_profile
+    except EntityValidationError:
+        raise
+    except Exception as exc:
+        static = entity.static_path  # best-effort for the error message
+        logger.error(
+            "Validation failed for entity {}: could not read schema from '{}': {}",
+            name,
+            static,
+            exc,
+        )
+        raise EntityValidationError(
+            f"Entity {name!r}: could not read schema from {static!r}: {exc}"
+        ) from exc

{core_lens-0.1.dev135 → core_lens-0.1.dev138}/src/core_lens/schema/detection.py

@@ -178,6 +178,14 @@ def _infer_bbox_cols(schema: pl.Schema) -> tuple[str, str, str, str] | None:
     for pattern in _BBOX_PATTERNS:
         if all(col in schema for col in pattern):
             return pattern
+
+    for col_name, dtype in schema.items():
+        if isinstance(dtype, pl.Struct):
+            struct_fields = [f.name for f in dtype.fields]
+            for pattern in _BBOX_PATTERNS:
+                if all(f in struct_fields for f in pattern):
+                    return tuple(f"{col_name}.{f}" for f in pattern)  # type: ignore
+
     return None
 
 

{core_lens-0.1.dev135 → core_lens-0.1.dev138}/src/core_lens/utils/spatial.py

@@ -5,7 +5,9 @@ from __future__ import annotations
 import pathlib
 from typing import TYPE_CHECKING, Any
 
+import numpy as np
 import polars as pl
+import pyarrow.dataset as ds
 import shapely
 from loguru import logger
 
@@ -14,6 +16,98 @@ from core_lens.utils.paths import is_cloud_uri, path_exists, resolve_fs_and_path
 if TYPE_CHECKING:
     pass
 
+# ---------------------------------------------------------------------------
+# Bbox index sidecar helpers
+#
+# A sidecar Parquet file caches the pre-computed bounding-box index so that
+# the expensive WKB-decode loop in build_bbox_index is only paid once per
+# dataset (not once per process).  Subsequent runs load the index directly
+# from the sidecar — no geometry decoding required.
+#
+# Sidecar location priority:
+#   1. Alongside the static parquet directory/file (requires write access).
+#   2. ~/.cache/core_lens/ (fallback for read-only data roots).
+# ---------------------------------------------------------------------------
+
+_SIDECAR_SUFFIX = ".bbox_index.parquet"
+_CACHE_DIR = pathlib.Path.home() / ".cache" / "core_lens"
+
+
+def _bbox_sidecar_path(static_path: str) -> pathlib.Path | None:
+    """Return the preferred path for the bbox index sidecar, or ``None`` for cloud URIs.
+
+    Tries the directory alongside ``static_path`` first; if that directory is
+    not writable (e.g. read-only data root), falls back to
+    ``~/.cache/core_lens/``.
+
+    Args:
+        static_path (str): Absolute local path to the static parquet file/directory.
+
+    Returns:
+        pathlib.Path | None: Sidecar path, or ``None`` if ``static_path`` is a cloud URI.
+    """
+    if is_cloud_uri(static_path):
+        return None
+    p = pathlib.Path(static_path)
+    # For a partitioned directory dataset, the sidecar lives inside the directory.
+    # For a single file, it lives next to it.
+    parent = p if p.is_dir() else p.parent
+    sidecar = parent / (p.name + _SIDECAR_SUFFIX)
+    # Check if the parent directory is writable.
+    if not parent.exists() or not parent.stat().st_mode & 0o200:
+        # Fallback to user cache dir.
+        import hashlib
+
+        fingerprint = hashlib.sha1(static_path.encode()).hexdigest()[:16]
+        _CACHE_DIR.mkdir(parents=True, exist_ok=True)
+        sidecar = _CACHE_DIR / (fingerprint + _SIDECAR_SUFFIX)
+    return sidecar
+
+
+def _read_bbox_sidecar(sidecar: pathlib.Path, static_path: str) -> pl.DataFrame | None:
+    """Read the sidecar if it exists and is newer than the static data.
+
+    Args:
+        sidecar (pathlib.Path): Candidate sidecar path.
+        static_path (str): Absolute local path to the static parquet file/directory.
+
+    Returns:
+        pl.DataFrame | None: The cached index, or ``None`` if the sidecar is
+        absent or stale.
+    """
+    if not sidecar.exists():
+        return None
+    try:
+        static_mtime = pathlib.Path(static_path).stat().st_mtime
+        sidecar_mtime = sidecar.stat().st_mtime
+        if sidecar_mtime < static_mtime:
+            logger.debug(
+                "Bbox sidecar {} is stale (older than {}), rebuilding.",
+                sidecar,
+                static_path,
+            )
+            return None
+        logger.debug("Loading bbox index from sidecar: {}", sidecar)
+        return pl.read_parquet(str(sidecar))
+    except Exception as exc:
+        logger.warning("Failed to read bbox sidecar {}: {}", sidecar, exc)
+        return None
+
+
+def _write_bbox_sidecar(df: pl.DataFrame, sidecar: pathlib.Path) -> None:
+    """Write ``df`` to the sidecar file, silently ignoring any write errors.
+
+    Args:
+        df (pl.DataFrame): The bbox index DataFrame to persist.
+        sidecar (pathlib.Path): Destination sidecar path.
+    """
+    try:
+        sidecar.parent.mkdir(parents=True, exist_ok=True)
+        df.write_parquet(str(sidecar))
+        logger.debug("Wrote bbox index sidecar: {}", sidecar)
+    except Exception as exc:
+        logger.debug("Could not write bbox index sidecar {}: {}", sidecar, exc)
+
 
 def resolve_path(path: str) -> str:
     """Return an absolute path or cloud URI string, resolving local relative paths against cwd.
@@ -79,14 +173,27 @@ def build_bbox_index(
     _so = storage_options or {}
     if bbox_cols is not None:
         logger.debug("Using pre-computed bbox columns: {}", bbox_cols)
-        cols_to_read = key_cols + list(bbox_cols)
+        base_bbox_cols = list(dict.fromkeys(c.split(".")[0] for c in bbox_cols))
+        cols_to_read = key_cols + base_bbox_cols
         df = pl.read_parquet(
             static_path, columns=cols_to_read, storage_options=_so or None
         )
         minx_col, miny_col, maxx_col, maxy_col = bbox_cols
-        return df.rename(
-            {minx_col: "minx", miny_col: "miny", maxx_col: "maxx", maxy_col: "maxy"}
-        )
+
+        for alias, col_path in zip(
+            ["minx", "miny", "maxx", "maxy"],
+            [minx_col, miny_col, maxx_col, maxy_col],
+        ):
+            parts = col_path.split(".")
+            if len(parts) == 1:
+                df = df.rename({col_path: alias})
+            else:
+                expr = pl.col(parts[0])
+                for p in parts[1:]:
+                    expr = expr.struct.field(p)
+                df = df.with_columns(expr.alias(alias))
+
+        return df.select(key_cols + ["minx", "miny", "maxx", "maxy"])
 
     cols_to_read = key_cols + [geometry_col]
     if geometry_type == "latlon":
@@ -99,7 +206,15 @@ def build_bbox_index(
             + "Cannot compute bounds from separate lat/lon columns without bbox hints."
         )
 
-    import pyarrow.dataset as ds
+    # --- Sidecar fast path (local paths only) --------------------------------
+    # Check for a pre-built index sidecar before doing the expensive WKB loop.
+    sidecar: pathlib.Path | None = None
+    if not is_cloud_uri(static_path):
+        sidecar = _bbox_sidecar_path(static_path)
+        if sidecar is not None:
+            cached = _read_bbox_sidecar(sidecar, static_path)
+            if cached is not None:
+                return cached
 
     logger.debug(
         "No pre-computed bbox found in {}; falling back to Shapely decoding",
@@ -133,17 +248,23 @@ def build_bbox_index(
             chunks.append(chunk)
 
     if chunks:
-        return pl.concat(chunks)
+        result = pl.concat(chunks)
+    else:
+        empty_df = pl.read_parquet(
+            static_path, columns=key_cols, storage_options=_so or None
+        )
+        result = empty_df.with_columns(
+            pl.Series("minx", [], dtype=pl.Float64),
+            pl.Series("miny", [], dtype=pl.Float64),
+            pl.Series("maxx", [], dtype=pl.Float64),
+            pl.Series("maxy", [], dtype=pl.Float64),
+        )
 
-    empty_df = pl.read_parquet(
-        static_path, columns=key_cols, storage_options=_so or None
-    )
-    return empty_df.with_columns(
-        pl.Series("minx", [], dtype=pl.Float64),
-        pl.Series("miny", [], dtype=pl.Float64),
-        pl.Series("maxx", [], dtype=pl.Float64),
-        pl.Series("maxy", [], dtype=pl.Float64),
-    )
+    # Persist the sidecar for future runs (local paths only, errors silenced).
+    if sidecar is not None:
+        _write_bbox_sidecar(result, sidecar)
+
+    return result
 
 
 def bbox_intersects_geometry(
@@ -213,8 +334,6 @@ def exact_spatial_filter(
     Raises:
         ValueError: If ``relationship`` is not one of the valid options.
     """
-    import shapely
-
     logger.debug(
         "Refining {} candidates with exact spatial filter (relationship='{}')",
         len(candidates),
@@ -247,8 +366,6 @@ def exact_spatial_filter(
     else:
         geoms = shapely.from_wkt(geom_array)
 
-    import numpy as np
-
     if relationship == "centroid":
         # Centroid mode: entity centroid must lie within the AoI geometry.
         # STRtree is overkill for a single-query containment test — building
@@ -320,8 +437,6 @@ def execute_spatial_join(
         pl.DataFrame: ``primary_df`` with additional columns
         ``{other_entity_name}_{col}`` appended for each ``agg`` entry.
     """
-    import shapely
-
     logger.info(
         "Starting execute_spatial_join for other_entity_name={}", other_entity_name
     )
@@ -353,8 +468,6 @@ def execute_spatial_join(
         return primary_df
 
     # Compute bounding box of all primary geometries
-    import numpy as np
-
     bnds = shapely.bounds(primary_geoms)
     valid_bnds = bnds[~np.isnan(bnds).any(axis=1)]
     if len(valid_bnds) > 0: