core-lens 0.1.dev134__tar.gz → 0.1.dev136__tar.gz

{core_lens-0.1.dev134 → core_lens-0.1.dev136}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: core-lens
-Version: 0.1.dev134
+Version: 0.1.dev136
 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.dev134 → core_lens-0.1.dev136}/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.dev134'
-__version_tuple__ = version_tuple = (0, 1, 'dev134')
+__version__ = version = '0.1.dev136'
+__version_tuple__ = version_tuple = (0, 1, 'dev136')
 
 __commit_id__ = commit_id = None

{core_lens-0.1.dev134 → core_lens-0.1.dev136}/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.
 
@@ -176,6 +294,7 @@ class AoI:
         geometry: "shapely.Geometry | None" = None,
         seasons: SeasonConfig | None = None,
         storage_options: dict[str, Any] | None = None,
+        validate_all: bool = False,
         **entity_kwargs: str | list[str],
     ) -> None:
         """Resolve the AoI boundary and scope all registered entities.
@@ -195,6 +314,13 @@ class AoI:
                 calls.  For S3 the common keys are ``"region"``,
                 ``"access_key"``, and ``"secret_key"``.  ``None`` (default)
                 uses ambient credentials (env-vars / ``~/.aws/``).
+            validate_all (bool, optional): When ``True``, eagerly instantiate
+                and validate every registered entity at construction time,
+                preserving the original fail-fast behaviour.  When ``False``
+                (default), entities are built and validated lazily on first
+                access — a broken entity only surfaces an error when it is
+                actually used.  Use ``True`` in startup health-checks or
+                long-running services where early failure is preferable.
             **entity_kwargs (str | list[str]): Named filter pairs that identify the boundary,
                 e.g. ``tehsil="Pangi"``, ``district="Chamba"``,
                 ``state="Himachal Pradesh"``, ``mws_id="13_551"``.
@@ -237,15 +363,15 @@ class AoI:
                 "Provide exactly one boundary mode."
             )
 
-        # Instantiate and validate all registered entities with this data_root.
+        # Entity instances are created lazily on first access via _get_entity().
         self._entity_instances: dict[str, BaseEntity] = {}
-        for name, entity_cls in _REGISTRY.items():
-            entity = entity_cls(
-                data_root=self.data_root,
-                storage_options=self._storage_options or None,
-            )
-            _validate_entity(entity, name)
-            self._entity_instances[name] = entity
+
+        # Initialise boundary-entity cache.  Only populated by the
+        # named-boundary path (_resolve_named_boundary); bbox= / geometry=
+        # construction leaves these as None so __getattr__ falls through
+        # to the normal spatial_filter path for every entity.
+        self._boundary_entity_name: str | None = None
+        self._boundary_keys: pl.DataFrame | None = None
 
         if geometry is not None:
             self.geometry: "shapely.Geometry" = geometry
@@ -257,6 +383,12 @@ class AoI:
         # Entity views are created lazily on demand in __getattr__.
         self._scoped: dict[str, "View"] = {}
 
+        # Opt-in eager validation: instantiate + validate every registered
+        # entity now so that a bad entity fails immediately rather than on
+        # first access.  Useful for startup health-checks.
+        if validate_all:
+            self.validate()
+
     @property
     def current_season(self) -> str:
         """The season name for today's date under the AoI's SeasonConfig.
@@ -326,13 +458,81 @@ class AoI:
 
         return lonboard.Map(layers=layers)
 
+    def _get_entity(self, name: str) -> BaseEntity:
+        """Instantiate, validate, and cache an entity on first access.
+
+        Subsequent calls for the same *name* return the cached instance.
+        Validation delegates to :func:`_validate_entity` which routes
+        through the process-level :func:`_cached_detect` cache, so
+        repeated ``AoI()`` calls against the same ``data_root`` pay no
+        redundant Parquet footer reads.
+
+        Args:
+            name (str): The registered entity name (e.g. ``"mws"``).
+
+        Returns:
+            BaseEntity: The validated entity instance.
+
+        Raises:
+            KeyError: If *name* is not in :data:`_REGISTRY`.
+            :class:`~core_lens.base.EntityValidationError`: If validation fails.
+        """
+        if name not in self._entity_instances:
+            entity_cls = _REGISTRY[name]
+            entity = entity_cls(
+                data_root=self.data_root,
+                storage_options=self._storage_options or None,
+            )
+            # 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]
+
+    def validate(self) -> None:
+        """Eagerly validate every registered entity.
+
+        Instantiates and validates all entities in :data:`_REGISTRY` that
+        have not yet been accessed.  Raises on the first failure.
+
+        This is equivalent to the old eager-validation behaviour and is
+        useful for startup health-checks in long-running services::
+
+            aoi = AoI("data/", bbox=(...), validate_all=True)
+            # or:
+            aoi = AoI("data/", bbox=(...))
+            aoi.validate()  # explicit call, same effect
+
+        Raises:
+            :class:`~core_lens.base.EntityValidationError`: If any registered
+                entity fails validation.
+        """
+        for name in _REGISTRY:
+            self._get_entity(name)
+
     def __getattr__(self, name: str) -> "View":
         # Called only when normal attribute lookup has already failed, so this
         # never shadows real attributes.  Maps entity names to their scoped Views.
         if name in _REGISTRY:
             if name not in self._scoped:
-                entity = self._entity_instances[name]
-                view = entity.spatial_filter(geometry=self.geometry)
+                entity = self._get_entity(name)
+                if name == self._boundary_entity_name:
+                    # This entity *defined* the AoI boundary — we already
+                    # have its exact matching keys from
+                    # _resolve_named_boundary.  Skip the bbox-index build
+                    # and geometric predicate entirely.
+                    from core_lens.base.view import View
+
+                    assert (
+                        self._boundary_keys is not None
+                    )  # set by _resolve_named_boundary
+                    view = View(
+                        keys=self._boundary_keys,
+                        entity=entity,
+                        entity_name=name,
+                    )
+                else:
+                    view = entity.spatial_filter(geometry=self.geometry)
                 view._season_config = self.seasons
                 self._scoped[name] = view
             return self._scoped[name]
@@ -347,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.
@@ -361,76 +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.
-        candidate: BaseEntity | None = None
-        for name, entity in self._entity_instances.items():
-            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, entity in self._entity_instances.items():
-                if name in entity_kwargs:
-                    candidate = entity
-                    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()
+        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:
@@ -499,13 +672,31 @@ 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:
+def _validate_entity_paths(entity: BaseEntity, name: str) -> None:
+    """Validate an entity's path existence only — no Parquet I/O.
+
+    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 path does not exist.
+    """
+    # --- Static path existence check ----------------------------------------
     try:
         static = entity._resolve(entity.static_path)
     except FileNotFoundError:
@@ -518,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.",
@@ -531,47 +719,7 @@ def _validate_entity(entity: BaseEntity, name: str) -> None:
             f"Entity {name!r}: static_path {static!r} does not exist."
         )
 
-    storage_opts = entity._storage_options or {}
-    try:
-        schema = pl.scan_parquet(
-            static,
-            hive_partitioning=True,
-            storage_options=storage_opts or None,
-        ).collect_schema()
-    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
-
-    missing_keys = [c for c in entity.key_cols if c not in schema]
-    if missing_keys:
-        logger.error(
-            "Validation failed for entity {}: key columns {} not found in schema.",
-            name,
-            missing_keys,
-        )
-        raise EntityValidationError(
-            f"Entity {name!r}: key_cols {missing_keys} not found in {static!r}. "
-            f"Available columns: {list(schema.keys())}."
-        )
-
-    if entity.geometry_col not in schema:
-        logger.error(
-            "Validation failed for entity {}: geometry column '{}' not found in schema.",
-            name,
-            entity.geometry_col,
-        )
-        raise EntityValidationError(
-            f"Entity {name!r}: geometry_col {entity.geometry_col!r} "
-            f"not found in {static!r}. Available columns: {list(schema.keys())}."
-        )
-
+    # --- 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:
@@ -579,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.",
@@ -593,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.dev134 → core_lens-0.1.dev136}/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.
@@ -99,7 +193,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 +235,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 +321,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 +353,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 +424,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 +455,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:

{core_lens-0.1.dev134 → core_lens-0.1.dev136}/tests/unit/test_aoi.py

@@ -12,7 +12,6 @@ import shapely.wkb as swkb
 
 from core_lens.aoi import AoI, SeasonConfig, _REGISTRY, _entity_name
 from core_lens.base.entity import BaseEntity, EntityValidationError
-from core_lens.schema.profile import SchemaProfile
 
 
 def _write_parquet_no_key_col(path: pathlib.Path) -> None:
@@ -42,6 +41,10 @@ def _make_bad_entity(
 ) -> type[BaseEntity]:
     """Return a concrete entity class that deliberately mismatches the Parquet schema.
 
+    This helper does **not** override ``schema_profile``, so the detection
+    layer (``detect()``) runs against the actual file and raises on column
+    mismatches.
+
     Args:
         static: Path to an already-written Parquet file.
         key_cols: key_cols value to declare on the entity (may not exist in file).
@@ -50,16 +53,7 @@ def _make_bad_entity(
     Returns:
         A ``BaseEntity`` subclass whose declared columns differ from the file.
     """
-    profile = SchemaProfile(
-        key_cols=key_cols,
-        geometry_col=geometry_col,
-        geometry_type="wkb",
-        annual_time_col=None,
-        fortnightly_time_col=None,
-        bbox_cols=None,
-    )
     _static = str(static)
-    _profile = profile
     _key_cols = key_cols
     _geometry_col = geometry_col
 
@@ -76,10 +70,6 @@ def _make_bad_entity(
         def static_path(self) -> str:
             return _static
 
-        @property
-        def schema_profile(self) -> SchemaProfile:
-            return _profile
-
     return _BadEntity
 
 
@@ -182,7 +172,7 @@ class TestAoIRegister:
         _write_parquet_no_key_col(p)
         cls = _make_bad_entity(p, key_cols=["mws_id"], geometry_col="geometry")
 
-        with pytest.raises(EntityValidationError, match="key_cols"):
+        with pytest.raises(EntityValidationError, match="could not read schema"):
             AoI.register(cls)
 
     def test_register_missing_geometry_col_raises(self, tmp_path: Any) -> None:
@@ -190,7 +180,7 @@ class TestAoIRegister:
         _write_parquet_no_geom_col(p)
         cls = _make_bad_entity(p, key_cols=["mws_id"], geometry_col="geometry")
 
-        with pytest.raises(EntityValidationError, match="geometry_col"):
+        with pytest.raises(EntityValidationError, match="could not read schema"):
             AoI.register(cls)
 
     def test_register_missing_annual_path_raises(