core-lens 0.1.dev114__tar.gz → 0.1.dev120__tar.gz

{core_lens-0.1.dev114 → core_lens-0.1.dev120}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: core-lens
-Version: 0.1.dev114
+Version: 0.1.dev120
 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
@@ -17,6 +17,7 @@ Requires-Python: >=3.13
 Requires-Dist: core-lens[core]
 Requires-Dist: core-lens[spatial]
 Provides-Extra: core
+Requires-Dist: loguru>=0.7.3; extra == 'core'
 Requires-Dist: polars<2,>=1.39.0; extra == 'core'
 Requires-Dist: pyarrow<25,>=23.0.0; extra == 'core'
 Requires-Dist: pydantic<3,>=2.13.3; extra == 'core'
@@ -25,6 +26,7 @@ Requires-Dist: bokeh<4,>=3.6.0; extra == 'full'
 Requires-Dist: duckdb<2,>=1.5.3; extra == 'full'
 Requires-Dist: geoarrow-rust-core>=0.3.0; extra == 'full'
 Requires-Dist: geopandas<2,>=1.1.3; extra == 'full'
+Requires-Dist: loguru>=0.7.3; extra == 'full'
 Requires-Dist: lonboard<1,>=0.16.0; extra == 'full'
 Requires-Dist: matplotlib<4,>=3.10.9; extra == 'full'
 Requires-Dist: polars<2,>=1.39.0; extra == 'full'
@@ -41,6 +43,7 @@ Requires-Dist: cudf-polars-cu13==26.6.*; extra == 'full-gpu'
 Requires-Dist: duckdb<2,>=1.5.3; extra == 'full-gpu'
 Requires-Dist: geoarrow-rust-core>=0.3.0; extra == 'full-gpu'
 Requires-Dist: geopandas<2,>=1.1.3; extra == 'full-gpu'
+Requires-Dist: loguru>=0.7.3; extra == 'full-gpu'
 Requires-Dist: lonboard<1,>=0.16.0; extra == 'full-gpu'
 Requires-Dist: matplotlib<4,>=3.10.9; extra == 'full-gpu'
 Requires-Dist: polars<2,>=1.39.0; extra == 'full-gpu'
@@ -53,18 +56,21 @@ Requires-Dist: statsmodels<1,>=0.14.6; extra == 'full-gpu'
 Provides-Extra: gpu
 Requires-Dist: cudf-cu13==26.6.*; extra == 'gpu'
 Requires-Dist: cudf-polars-cu13==26.6.*; extra == 'gpu'
+Requires-Dist: loguru>=0.7.3; extra == 'gpu'
 Requires-Dist: polars<2,>=1.39.0; extra == 'gpu'
 Requires-Dist: pyarrow<25,>=23.0.0; extra == 'gpu'
 Requires-Dist: pydantic<3,>=2.13.3; extra == 'gpu'
 Provides-Extra: spatial
 Requires-Dist: duckdb<2,>=1.5.3; extra == 'spatial'
 Requires-Dist: geopandas<2,>=1.1.3; extra == 'spatial'
+Requires-Dist: loguru>=0.7.3; extra == 'spatial'
 Requires-Dist: polars<2,>=1.39.0; extra == 'spatial'
 Requires-Dist: pyarrow<25,>=23.0.0; extra == 'spatial'
 Requires-Dist: pydantic<3,>=2.13.3; extra == 'spatial'
 Requires-Dist: pyproj<4,>=3.7.2; extra == 'spatial'
 Requires-Dist: shapely<3,>=2.1.2; extra == 'spatial'
 Provides-Extra: stats
+Requires-Dist: loguru>=0.7.3; extra == 'stats'
 Requires-Dist: polars<2,>=1.39.0; extra == 'stats'
 Requires-Dist: pyarrow<25,>=23.0.0; extra == 'stats'
 Requires-Dist: pydantic<3,>=2.13.3; extra == 'stats'
@@ -73,6 +79,7 @@ Requires-Dist: statsmodels<1,>=0.14.6; extra == 'stats'
 Provides-Extra: viz
 Requires-Dist: bokeh<4,>=3.6.0; extra == 'viz'
 Requires-Dist: geoarrow-rust-core>=0.3.0; extra == 'viz'
+Requires-Dist: loguru>=0.7.3; extra == 'viz'
 Requires-Dist: lonboard<1,>=0.16.0; extra == 'viz'
 Requires-Dist: matplotlib<4,>=3.10.9; extra == 'viz'
 Requires-Dist: polars<2,>=1.39.0; extra == 'viz'

core_lens-0.1.dev120/docs/source/export.md

@@ -0,0 +1,47 @@
+# Data Export
+
+CoreLens provides a unified `core_lens.export` module for saving `Result` objects to various file formats. Standard tabular formats use Polars for high-speed writes, while geospatial formats leverage DuckDB's spatial extensions for robust geometry encoding.
+
+## Standard Formats
+
+Export non-spatial results to standard formats. Note that these formats cannot encode geometry columns; if your `Result` has geometry, these functions will raise a `TypeError`.
+
+```python
+from core_lens.export import parquet, csv, json
+
+res = aoi.mws.annual
+
+# Export to Parquet with ZSTD compression
+parquet(res, "output.parquet", compression="zstd")
+
+# Export to CSV
+csv(res, "output.csv", separator=",")
+
+# Export to JSON
+json(res, "output.json", pretty=True)
+```
+
+## Geospatial Formats
+
+Export spatial data to GeoParquet and GeoJSON. The result must have geometry attached (e.g., by calling `.with_geometry()`).
+
+```python
+from core_lens.export import geoparquet, geojson
+
+# Make sure geometry is attached!
+spatial_res = aoi.mws.annual.with_geometry()
+
+# Export to GeoParquet with DuckDB COPY options (e.g., partitioning)
+geoparquet(
+    spatial_res,
+    "output.geoparquet",
+    compression="ZSTD",
+    partition_by="year"
+)
+
+# Export to GeoJSON
+geojson(spatial_res, "output.json")
+```
+
+> [!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.

{core_lens-0.1.dev114 → core_lens-0.1.dev120}/docs/source/index.rst

@@ -21,5 +21,7 @@ Provides a unified interface over microwatershed hydrology, administrative bound
    queries
    stats
    plots
+   export
    plugins
+   logging
    autoapi/index

{core_lens-0.1.dev114 → core_lens-0.1.dev120}/docs/source/intro.md

@@ -12,4 +12,5 @@ CoreLens provides a unified interface over microwatersheds, administrative bound
 - **Pluggable Entities**: Built-in support for standard units (MWS, Tehsil) with a simple plugin architecture for adding new domain entities.
 - **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 and timeseries/scatter plots using Bokeh directly from results.
+- **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.

core_lens-0.1.dev120/docs/source/logging.md

@@ -0,0 +1,32 @@
+# Logging
+
+`core_lens` uses [Loguru](https://loguru.readthedocs.io/) for internal logging and tracing.
+
+To avoid polluting the standard output of your downstream applications, the logger is disabled by default upon import.
+
+## Enabling Logs
+
+If you want to view the internal tracing logs (useful for debugging spatial resolution issues, inspecting generated time filters, or tracing validation errors), you need to explicitly enable the `core_lens` logger in your application and add a handler (e.g., `sys.stdout` or a log file).
+
+```python
+import sys
+from loguru import logger
+from core_lens import AoI
+
+# 1. Enable the internal logger
+logger.enable("core_lens")
+
+# 2. Add a handler with your desired level and formatting
+logger.add(sys.stdout, level="DEBUG")
+
+# 3. Operations will now emit tracing logs
+aoi = AoI("data/", tehsil="Pangi", district="Chamba")
+```
+
+## Log Levels
+
+`core_lens` emits logs at different levels depending on the operational context:
+
+- **INFO**: Materialisation events (reading static, annual, or fortnightly Parquet files), entity registrations, AoI initialisation, and cross-entity spatial joins.
+- **DEBUG**: Sub-operations such as spatial bounding box index generation, exact geometry relationships, lazy attribute filters, and query generation.
+- **ERROR**: Incorrect initialisation arguments, failed path validations, missing geometries, unknown schema structures, or conflicting date configurations.

{core_lens-0.1.dev114 → core_lens-0.1.dev120}/docs/source/plots.md

@@ -1,6 +1,6 @@
 # Visualisation and Plots
 
-The `result.plot` namespace provides integrated plotting capabilities. Spatial plots use **Lonboard** for high-performance interactive maps, while charts and timeseries use **Bokeh**.
+The `result.plot` namespace provides integrated plotting capabilities. Spatial plots use **Lonboard** for high-performance interactive maps (achieved via zero-copy GeoArrow memory mapping directly from Polars, bypassing GeoPandas), while charts and timeseries use **Bokeh**.
 
 Plot methods return plot objects (like a Bokeh Figure or Lonboard Map) which can be displayed using `bokeh.io.show` or exported via `bokeh.io.save`.
 

{core_lens-0.1.dev114 → core_lens-0.1.dev120}/pyproject.toml

@@ -44,7 +44,12 @@ venvPath = "."
 venv = ".venv"
 
 [project.optional-dependencies]
-core = ["polars>=1.39.0,<2", "pyarrow>=23.0.0,<25", "pydantic>=2.13.3,<3"]
+core = [
+    "polars>=1.39.0,<2",
+    "pyarrow>=23.0.0,<25",
+    "pydantic>=2.13.3,<3",
+    "loguru>=0.7.3",
+]
 spatial = [
     "core-lens[core]",
     "duckdb>=1.5.3,<2",

{core_lens-0.1.dev114 → core_lens-0.1.dev120}/src/core_lens/__init__.py

@@ -6,4 +6,8 @@ except ImportError:
 from core_lens.aoi import AoI, SeasonConfig
 from core_lens.entities.tehsil import TehsilEntity
 
+from loguru import logger
+
+logger.disable("core_lens")
+
 __all__ = ["__version__", "AoI", "SeasonConfig", "TehsilEntity"]

{core_lens-0.1.dev114 → core_lens-0.1.dev120}/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.dev114'
-__version_tuple__ = version_tuple = (0, 1, 'dev114')
+__version__ = version = '0.1.dev120'
+__version_tuple__ = version_tuple = (0, 1, 'dev120')
 
 __commit_id__ = commit_id = None

{core_lens-0.1.dev114 → core_lens-0.1.dev120}/src/core_lens/aoi.py

@@ -12,6 +12,7 @@ if TYPE_CHECKING:
     from core_lens.base.result import Result
 
 import polars as pl
+from loguru import logger
 
 from core_lens.base.entity import BaseEntity, EntityValidationError
 
@@ -67,10 +68,10 @@ class SeasonConfig:
         """Return the season name for a given date.
 
         Args:
-            d: The date to classify.
+            d (date): The date to classify.
 
         Returns:
-            ``"kharif"``, ``"rabi"``, or ``"zaid"``.
+            str: ``"kharif"``, ``"rabi"``, or ``"zaid"``.
         """
         md = f"{d.month:02d}-{d.day:02d}"
         for name in ("kharif", "rabi", "zaid"):
@@ -155,16 +156,16 @@ class AoI:
         """Resolve the AoI boundary and scope all registered entities.
 
         Args:
-            data_root: Path to the root data directory.  Prepended to every
+            data_root (str): Path to the root data directory.  Prepended to every
                 relative entity path that does not start with ``/`` or a URI
                 scheme.
-            bbox: Bounding box as ``(minx, miny, maxx, maxy)`` in WGS-84.
+            bbox (tuple[float, float, float, float] | None, optional): Bounding box as ``(minx, miny, maxx, maxy)`` in WGS-84.
                 Mutually exclusive with ``geometry`` and ``entity_kwargs``.
-            geometry: Arbitrary Shapely geometry.  Used as-is.  Mutually
+            geometry (shapely.Geometry | None, optional): Arbitrary Shapely geometry.  Used as-is.  Mutually
                 exclusive with ``bbox`` and ``entity_kwargs``.
-            seasons: :class:`SeasonConfig` override.  Defaults to the library
+            seasons (SeasonConfig | None, optional): :class:`SeasonConfig` override.  Defaults to the library
                 agronomic defaults.
-            **entity_kwargs: Named filter pairs that identify the boundary,
+            **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"``.
                 Mutually exclusive with ``bbox`` and ``geometry``.
@@ -177,6 +178,7 @@ class AoI:
         """
         self.data_root = pathlib.Path(data_root).resolve()
         self.seasons: SeasonConfig = seasons or SeasonConfig()
+        logger.info("Initializing AoI with data_root={}", self.data_root)
 
         n_modes = sum(
             [
@@ -186,11 +188,13 @@ class AoI:
             ]
         )
         if n_modes == 0:
+            logger.error("AoI initialization failed: no boundary argument supplied.")
             raise ValueError(
                 "AoI requires exactly one boundary argument: "
                 "bbox=, geometry=, or entity keyword filters such as tehsil='Pangi'."
             )
         if n_modes > 1:
+            logger.error("AoI initialization failed: multiple boundary modes supplied.")
             raise ValueError(
                 "bbox, geometry, and entity keyword filters are mutually exclusive. "
                 "Provide exactly one boundary mode."
@@ -219,7 +223,7 @@ class AoI:
         """The season name for today's date under the AoI's SeasonConfig.
 
         Returns:
-            ``"kharif"``, ``"rabi"``, or ``"zaid"``.
+            str: ``"kharif"``, ``"rabi"``, or ``"zaid"``.
         """
         return self.seasons.season_for(date.today())
 
@@ -228,7 +232,7 @@ class AoI:
         """The current calendar year.
 
         Returns:
-            Current year as an integer.
+            int: Current year as an integer.
         """
         return date.today().year
 
@@ -236,11 +240,11 @@ class AoI:
         """Render an interactive Lonboard map of the AoI and its entity layers.
 
         Args:
-            overlay: An optional :class:`~core_lens.base.result.Result` to
+            overlay (Result | None, optional): An optional :class:`~core_lens.base.result.Result` to
                 overlay on the map.
 
         Returns:
-            A Lonboard Map object.
+            Any: A Lonboard Map object.
         """
         import lonboard
         import geopandas as gpd
@@ -309,10 +313,10 @@ class AoI:
         the unique matching row).
 
         Args:
-            entity_kwargs: Column–value pairs used to identify the boundary.
+            entity_kwargs (dict[str, str | list[str]]): Column–value pairs used to identify the boundary.
 
         Returns:
-            The union of all matching entity geometries as a Shapely object.
+            shapely.Geometry: The union of all matching entity geometries as a Shapely object.
 
         Raises:
             :class:`~core_lens.base.EntityValidationError`: If no registered entity can satisfy the filters.
@@ -320,6 +324,8 @@ class AoI:
         """
         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
@@ -335,12 +341,19 @@ class AoI:
         # 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)}."
@@ -367,6 +380,9 @@ class AoI:
         df = lf.filter(filter_expr).select(candidate.key_cols + [geom_col]).collect()
 
         if df.is_empty():
+            logger.error(
+                "Boundary resolution failed: no rows matched filters {}", entity_kwargs
+            )
             raise ValueError(
                 f"No rows matched the filters {entity_kwargs} "
                 f"in {candidate.static_path!r}."
@@ -391,7 +407,7 @@ class AoI:
         :class:`AoI` is instantiated (when ``data_root`` is known).
 
         Args:
-            entity_cls: A concrete subclass of
+            entity_cls (type[BaseEntity]): A concrete subclass of
                 :class:`~core_lens.base.entity.BaseEntity`.
 
         Raises:
@@ -401,6 +417,7 @@ class AoI:
         import pathlib as _pathlib
 
         name = _entity_name(entity_cls)
+        logger.info("Registering entity class: {}", name)
         # Probe with a no-root instance to check if paths are absolute.
         probe = entity_cls()
         static = probe.static_path
@@ -417,9 +434,10 @@ class AoI:
         Primarily useful in tests where a clean registry is needed between runs.
 
         Args:
-            entity_cls: The entity class to remove.
+            entity_cls (type[BaseEntity]): The entity class to remove.
         """
         name = _entity_name(entity_cls)
+        logger.info("Deregistering entity class: {}", name)
         _REGISTRY.pop(name, None)
 
     @classmethod
@@ -427,7 +445,7 @@ class AoI:
         """Return the names of all currently registered entities.
 
         Returns:
-            A sorted list of entity name strings.
+            list[str]: A sorted list of entity name strings.
         """
         return sorted(_REGISTRY)
 
@@ -452,11 +470,21 @@ def _validate_entity(entity: BaseEntity, name: str) -> None:
     try:
         static = entity._resolve(entity.static_path)
     except FileNotFoundError:
+        logger.error(
+            "Validation failed for entity {}: static_path '{}' does not exist.",
+            name,
+            entity.static_path,
+        )
         raise EntityValidationError(
             f"Entity {name!r}: static_path {entity.static_path!r} does not exist."
         )
 
     if not os.path.exists(static):
+        logger.error(
+            "Validation failed for entity {}: static path '{}' does not exist.",
+            name,
+            static,
+        )
         raise EntityValidationError(
             f"Entity {name!r}: static_path {static!r} does not exist."
         )
@@ -464,18 +492,34 @@ def _validate_entity(entity: BaseEntity, name: str) -> None:
     try:
         schema = pl.read_parquet_schema(static)
     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())}."
@@ -489,6 +533,12 @@ def _validate_entity(entity: BaseEntity, name: str) -> None:
             except FileNotFoundError:
                 abs_path = None
             if abs_path is None or not os.path.exists(abs_path):
+                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."
                 )

{core_lens-0.1.dev114 → core_lens-0.1.dev120}/src/core_lens/base/entity.py

@@ -16,6 +16,7 @@ from abc import ABC, abstractmethod
 from typing import TYPE_CHECKING, Any
 
 import polars as pl
+from loguru import logger
 
 from core_lens.utils.spatial import (
     bbox_intersects_geometry,
@@ -84,7 +85,7 @@ class BaseEntity(ABC):
         """Initialise the entity with an optional data root directory.
 
         Args:
-            data_root: Absolute path to the root data directory.  When
+            data_root (pathlib.Path | None, optional): Absolute path to the root data directory.  When
                 supplied, relative :attr:`static_path`, :attr:`annual_path`,
                 and :attr:`fortnightly_path` values are resolved against this
                 directory.  Defaults to ``None``, in which case relative paths
@@ -100,10 +101,10 @@ class BaseEntity(ABC):
         otherwise against the current working directory.
 
         Args:
-            path: A filesystem path, absolute or relative.
+            path (str): A filesystem path, absolute or relative.
 
         Returns:
-            An absolute path string.
+            str: An absolute path string.
 
         Raises:
             FileNotFoundError: If the resolved path does not exist.
@@ -115,6 +116,9 @@ class BaseEntity(ABC):
             )
             p = root / p
         if not p.exists():
+            logger.error(
+                "Path resolution failed: '{}' (resolved to {}) does not exist.", path, p
+            )
             raise FileNotFoundError(
                 f"Entity path {path!r} (resolved to {p}) does not exist. "
                 "Provide an absolute path or ensure the file exists relative to "
@@ -131,7 +135,7 @@ class BaseEntity(ABC):
         ``[\"mws_id\"]``), but the contract allows composite keys for plugins.
 
         Returns:
-            A list of column name strings present in the static file.
+            list[str]: A list of column name strings present in the static file.
         """
 
     @property
@@ -143,7 +147,7 @@ class BaseEntity(ABC):
         (WKB bytes, WKT string, or a native geometry column).
 
         Returns:
-            The column name as a string.
+            str: The column name as a string.
         """
 
     @property
@@ -156,7 +160,7 @@ class BaseEntity(ABC):
         ``FileNotFoundError`` is raised if the file does not exist.
 
         Returns:
-            A path string.
+            str: A path string.
         """
 
     @property
@@ -168,7 +172,7 @@ class BaseEntity(ABC):
         :class:`EntityValidationError` is raised.
 
         Returns:
-            A path string, or ``None`` if the entity has no annual data.
+            str | None: A path string, or ``None`` if the entity has no annual data.
         """
         return None
 
@@ -181,7 +185,7 @@ class BaseEntity(ABC):
         :class:`EntityValidationError` is raised.
 
         Returns:
-            A path string, or ``None`` if the entity has no fortnightly data.
+            str | None: A path string, or ``None`` if the entity has no fortnightly data.
         """
         return None
 
@@ -194,7 +198,7 @@ class BaseEntity(ABC):
         instead of relying on detection.
 
         Returns:
-            A fully-validated :class:`~core_lens.schema.profile.SchemaProfile`.
+            SchemaProfile: A fully-validated :class:`~core_lens.schema.profile.SchemaProfile`.
         """
         if not hasattr(self, "_schema_profile"):
             from core_lens.schema.detection import detect
@@ -219,6 +223,9 @@ class BaseEntity(ABC):
     @property
     def _index(self) -> pl.DataFrame:
         if not hasattr(self, "_cached_index"):
+            logger.debug(
+                "Building lazy bounding box index for {}", self.__class__.__name__
+            )
             profile = self.schema_profile
             self._cached_index: pl.DataFrame = build_bbox_index(
                 static_path=self._resolve(self.static_path),
@@ -247,7 +254,7 @@ class BaseEntity(ABC):
                 are resolved as entity-name lookups.
 
         Returns:
-            A lazy :class:`~core_lens.base.view.View` with resolved key pairs.
+            View: A lazy :class:`~core_lens.base.view.View` with resolved key pairs.
 
         Raises:
             ValueError: If a kwarg cannot be resolved as either an attribute
@@ -256,6 +263,10 @@ class BaseEntity(ABC):
         from core_lens.aoi import _REGISTRY
         from core_lens.base.view import View
 
+        logger.debug(
+            "Applying attribute filters on {}: {}", self.__class__.__name__, kwargs
+        )
+
         static = self._resolve(self.static_path)
         schema = pl.read_parquet_schema(static)
 
@@ -265,6 +276,10 @@ class BaseEntity(ABC):
         # Validate entity-kwargs early so we give a useful error message.
         for k in entity_kwargs:
             if k not in _REGISTRY:
+                logger.error(
+                    "BaseEntity.where failed: '{}' is neither a column nor a registered entity.",
+                    k,
+                )
                 raise ValueError(
                     f"BaseEntity.where: {k!r} is not a column in {self.static_path!r} "
                     f"and is not a registered entity name. "
@@ -306,6 +321,12 @@ class BaseEntity(ABC):
             )
 
             if matched.is_empty():
+                logger.error(
+                    "BaseEntity.where failed: No rows matched {}={!r} in {}",
+                    entity_kwarg_name,
+                    entity_kwarg_val,
+                    other_entity.static_path,
+                )
                 raise ValueError(
                     f"BaseEntity.where: No rows matched {entity_kwarg_name}={entity_kwarg_val!r} "
                     f"in {other_entity.static_path!r}."
@@ -354,21 +375,21 @@ class BaseEntity(ABC):
         refines with a Shapely STRtree exact-relationship check.
 
         Args:
-            geometry: A Shapely geometry representing the spatial extent.
-            bbox: Bounding box as ``(minx, miny, maxx, maxy)`` in WGS-84.
+            geometry (shapely.Geometry | None, optional): A Shapely geometry representing the spatial extent.
+            bbox (tuple[float, float, float, float] | None, optional): Bounding box as ``(minx, miny, maxx, maxy)`` in WGS-84.
                 Converted to a ``shapely.geometry.box`` internally.
-            relationship: Spatial relationship mode.
+            relationship (str, optional): Spatial relationship mode.
 
                 * ``"centroid"`` (default) — entity centroid must lie within
                   the geometry.
                 * ``"area"`` — intersection area / entity area must exceed
                   ``threshold``.
 
-            threshold: Area coverage threshold for ``"area"`` mode (0–1).
+            threshold (float, optional): Area coverage threshold for ``"area"`` mode (0–1).
                 Default 0.5.
 
         Returns:
-            A lazy :class:`~core_lens.base.view.View` scoped to the given
+            View: A lazy :class:`~core_lens.base.view.View` scoped to the given
             spatial extent.
 
         Raises:
@@ -379,6 +400,9 @@ class BaseEntity(ABC):
         from core_lens.base.view import View
 
         if geometry is None and bbox is None:
+            logger.error(
+                "BaseEntity.spatial_filter failed: neither 'geometry' nor 'bbox' provided."
+            )
             raise ValueError(
                 "spatial_filter() requires either 'geometry' or 'bbox' to be provided."
             )
@@ -387,6 +411,12 @@ class BaseEntity(ABC):
 
         assert geometry is not None  # guaranteed by the guards above
 
+        logger.debug(
+            "Applying spatial filter on {} (relationship='{}')",
+            self.__class__.__name__,
+            relationship,
+        )
+
         profile = self.schema_profile
         candidates = bbox_intersects_geometry(self._index, geometry)
         keys = exact_spatial_filter(
@@ -411,19 +441,25 @@ class BaseEntity(ABC):
         Joined columns are namespaced as ``{entity_name}_{column_name}``.
 
         Args:
-            other: The secondary :class:`BaseEntity` whose columns will be
+            other (BaseEntity): The secondary :class:`BaseEntity` whose columns will be
                 joined and aggregated onto ``self``.
-            agg: Mapping of ``{column: aggregation}`` specifying which columns
+            agg (dict[str, str]): Mapping of ``{column: aggregation}`` specifying which columns
                 from ``other`` to bring in and how to aggregate them.  Valid
                 aggregation strings are ``\"area\"``, ``\"count\"``, ``\"mean\"``,
                 ``\"sum\"``, ``\"min\"``, and ``\"max\"``.
 
         Returns:
-            A lazy :class:`~core_lens.base.view.View` with the join spec
+            View: A lazy :class:`~core_lens.base.view.View` with the join spec
             recorded for deferred execution.
         """
         from core_lens.base.view import View
 
+        logger.debug(
+            "Deferred spatial join registered for {} with {}",
+            self.__class__.__name__,
+            other.__class__.__name__,
+        )
+
         entity_name = _entity_name(type(self))
         join_spec = {"other": other, "agg": agg}
         return View(