Python API Reference

The public package entrypoint is fresh_hectaresbc.HectaresBC. It exposes catalog search and lookup, local path/status inspection, backend diagnostics, and fetch planning/retrieval methods.

Public Package

Public package interface for fresh-hectaresbc.

API Facade

Top-level public API facade.

class fresh_hectaresbc.api.HectaresBC(metadata_root=None, data_repo_path=None, backend=None)[source]

Convenience entrypoint for HectaresBC catalog and data access.

The facade exposes catalog, local path/status, diagnostics, and fetch behavior through structured result objects.

Parameters:
  • metadata_root (Path | str | None)

  • data_repo_path (Path | str | None)

  • backend (BackendAdapter | None)

backend: BackendAdapter | None = None
property catalog: Catalog

Load the recovered catalog on first use.

content_status(dataset)[source]

Report local content status without fetching data.

Parameters:

dataset (str | DatasetRecord)

Return type:

ContentStatus

data_repo_path: Path | str | None = None
diagnostics()[source]

Return backend diagnostics.

Return type:

tuple[BackendDiagnostic, …]

fetch(dataset, *, force=False, dry_run=False)[source]

Retrieve or plan retrieval for one dataset.

Parameters:
Return type:

FetchResult

fetch_many(datasets, *, force=False, dry_run=False)[source]

Retrieve or plan retrieval for multiple datasets.

Parameters:
Return type:

tuple[FetchResult, …]

filter(**filters)[source]

Filter recovered catalog records.

Parameters:

filters (object)

Return type:

list[DatasetRecord]

get(dataset_id)[source]

Return one dataset record by exact recovered ID.

Parameters:

dataset_id (str)

Return type:

DatasetRecord

local_path(dataset)[source]

Return the expected local filesystem path for a dataset.

Parameters:

dataset (str | DatasetRecord)

Return type:

Path

metadata_root: Path | str | None = None
resolve(dataset)[source]

Resolve a dataset ID or record to a data-repository path.

Parameters:

dataset (str | DatasetRecord)

Return type:

ResolvedDatasetPath

property resolver: Resolver

Create the read-only data repository resolver on first use.

search(query, *, family=None, limit=None, allow_empty=False)[source]

Search recovered catalog records.

Parameters:
  • query (str)

  • family (str | None)

  • limit (int | None)

  • allow_empty (bool)

Return type:

list[DatasetRecord]

Catalog

Recovered HectaresBC catalog loading and query APIs.

class fresh_hectaresbc.catalog.Catalog(records, metadata_root)[source]

In-memory view of recovered HectaresBC metadata records.

Parameters:
  • records (Iterable[DatasetRecord])

  • metadata_root (Path | str | Traversable)

exists(dataset_id)[source]

Return whether a recovered dataset ID exists.

Parameters:

dataset_id (str)

Return type:

bool

filter(*, family=None, dataset_id_prefix=None, source_path_prefix=None, name_prefix=None, virtual_layer_id=None, has_category_metadata=None, has_value_metadata=None, has_wms_xml=None, has_tiff=None, verification_status=None, zip_read_status=None, min_size_bytes=None, max_size_bytes=None)[source]

Return records matching structured recovered-catalog filters.

Parameters:
  • family (str | None)

  • dataset_id_prefix (str | None)

  • source_path_prefix (str | None)

  • name_prefix (str | None)

  • virtual_layer_id (str | int | None)

  • has_category_metadata (bool | None)

  • has_value_metadata (bool | None)

  • has_wms_xml (bool | None)

  • has_tiff (bool | None)

  • verification_status (str | None)

  • zip_read_status (str | None)

  • min_size_bytes (int | None)

  • max_size_bytes (int | None)

Return type:

list[DatasetRecord]

classmethod from_default_paths(start=None)[source]

Load recovered catalog records from source metadata or package data.

Parameters:

start (Path | str | None)

Return type:

Catalog

classmethod from_metadata_root(metadata_root)[source]

Load recovered catalog records from a metadata directory.

Parameters:

metadata_root (Path | str)

Return type:

Catalog

classmethod from_package_data()[source]

Load recovered catalog records bundled with the installed package.

Return type:

Catalog

get(dataset_id)[source]

Return exactly one record by recovered dataset ID.

Parameters:

dataset_id (str)

Return type:

DatasetRecord

iter_records(*, family=None, verification_status=None, has_known_gaps=None, has_uncertainty=None)[source]

Iterate records with basic catalog-contract filters.

Parameters:
  • family (str | None)

  • verification_status (str | None)

  • has_known_gaps (bool | None)

  • has_uncertainty (bool | None)

Return type:

Iterator[DatasetRecord]

property records: tuple[DatasetRecord, ...]
search(query, *, family=None, limit=None, allow_empty=False)[source]

Search recovered source-backed text fields.

Parameters:
  • query (str)

  • family (str | None)

  • limit (int | None)

  • allow_empty (bool)

Return type:

list[DatasetRecord]

exception fresh_hectaresbc.catalog.CatalogError[source]

Base class for catalog API errors.

exception fresh_hectaresbc.catalog.CatalogFileMissing[source]

Raised when a required catalog CSV is missing.

exception fresh_hectaresbc.catalog.CatalogHeaderInvalid[source]

Raised when a catalog CSV does not contain required columns.

exception fresh_hectaresbc.catalog.DatasetNotFound[source]

Raised when exact dataset lookup fails.

exception fresh_hectaresbc.catalog.DuplicateDatasetId[source]

Raised when recovered catalog inputs contain duplicate IDs.

exception fresh_hectaresbc.catalog.QueryInvalid[source]

Raised when a query cannot be evaluated.

Models

Shared catalog data models.

class fresh_hectaresbc.models.BackendDiagnostic(backend, check, status, message, command_summary=None, remediation=None, secret_safe=True)[source]

One backend readiness diagnostic check.

Parameters:
  • backend (str)

  • check (str)

  • status (str)

  • message (str)

  • command_summary (str | None)

  • remediation (str | None)

  • secret_safe (bool)

backend: str
check: str
command_summary: str | None = None
message: str
remediation: str | None = None
secret_safe: bool = True
status: str
class fresh_hectaresbc.models.ContentStatus(dataset_id, status, local_path, submodule_initialized, path_metadata_exists, content_present, message)[source]

Local content status for a resolved raw ZIP payload.

Parameters:
  • dataset_id (str)

  • status (str)

  • local_path (Path)

  • submodule_initialized (bool)

  • path_metadata_exists (bool)

  • content_present (bool)

  • message (str)

content_present: bool
dataset_id: str
local_path: Path
message: str
path_metadata_exists: bool
status: str
submodule_initialized: bool
class fresh_hectaresbc.models.DatasetRecord(dataset_id, source_family, source_zip_path, source_filename, source_stem, title_candidate, verification_status, manifest_size_bytes, known_gaps, uncertainty_notes, fields)[source]

One recovered HectaresBC catalog record.

Parameters:
  • dataset_id (str)

  • source_family (str)

  • source_zip_path (str)

  • source_filename (str)

  • source_stem (str)

  • title_candidate (str)

  • verification_status (str)

  • manifest_size_bytes (int | None)

  • known_gaps (str)

  • uncertainty_notes (str)

  • fields (Mapping[str, str])

bool_field(name)[source]

Return a recovered flag-like field as a boolean.

Parameters:

name (str)

Return type:

bool

dataset_id: str
field(name, default='')[source]

Return a raw recovered field without changing source names.

Parameters:
  • name (str)

  • default (str)

Return type:

str

fields: Mapping[str, str]
classmethod from_row(row)[source]
Parameters:

row (Mapping[str, str])

Return type:

DatasetRecord

int_field(name)[source]

Return a recovered integer field when present.

Parameters:

name (str)

Return type:

int | None

known_gaps: str
manifest_size_bytes: int | None
source_family: str
source_filename: str
source_stem: str
source_zip_path: str
title_candidate: str
to_dict()[source]

Serialize the record while preserving all recovered source fields.

Return type:

dict[str, object]

uncertainty_notes: str
verification_status: str
class fresh_hectaresbc.models.FetchResult(dataset_id, status, backend, local_path, message, diagnostics=(), command_summary=None, verification_performed=False, secret_safe=True)[source]

Structured result for a dataset retrieval request.

Parameters:
  • dataset_id (str)

  • status (str)

  • backend (str)

  • local_path (Path)

  • message (str)

  • diagnostics (tuple[BackendDiagnostic, ...])

  • command_summary (str | None)

  • verification_performed (bool)

  • secret_safe (bool)

backend: str
command_summary: str | None = None
dataset_id: str
diagnostics: tuple[BackendDiagnostic, ...] = ()
local_path: Path
message: str
secret_safe: bool = True
status: str
verification_performed: bool = False
class fresh_hectaresbc.models.ResolvedDatasetPath(dataset_id, source_zip_path, data_repo_path, raw_relative_path, absolute_path, submodule_initialized, path_metadata_exists, content_present)[source]

Filesystem resolution for a catalog record’s raw ZIP payload.

Parameters:
  • dataset_id (str)

  • source_zip_path (str)

  • data_repo_path (Path)

  • raw_relative_path (Path)

  • absolute_path (Path)

  • submodule_initialized (bool)

  • path_metadata_exists (bool)

  • content_present (bool)

absolute_path: Path
content_present: bool
data_repo_path: Path
dataset_id: str
path_metadata_exists: bool
raw_relative_path: Path
source_zip_path: str
submodule_initialized: bool

Retrieval

Read-only dataset resolution and local content-status APIs.

class fresh_hectaresbc.retrieval.Resolver(catalog, data_repo_path=None, backend=None)[source]

Resolve catalog records to paths in the linked data repository.

Parameters:
content_status(dataset)[source]

Report local availability without fetching content.

Parameters:

dataset (str | DatasetRecord)

Return type:

ContentStatus

diagnostics()[source]

Return backend diagnostics.

Return type:

tuple[BackendDiagnostic, …]

fetch(dataset, *, force=False, dry_run=False)[source]

Retrieve or plan retrieval for one dataset.

Parameters:
Return type:

FetchResult

fetch_many(datasets, *, force=False, dry_run=False)[source]

Retrieve or plan retrieval for multiple datasets in input order.

Parameters:
Return type:

tuple[FetchResult, …]

local_path(dataset)[source]

Return the expected local filesystem path for a dataset.

Parameters:

dataset (str | DatasetRecord)

Return type:

Path

resolve(dataset)[source]

Resolve a dataset ID or record to the expected raw ZIP path.

Parameters:

dataset (str | DatasetRecord)

Return type:

ResolvedDatasetPath

Backends

Backend adapter protocol.

class fresh_hectaresbc.backends.base.BackendAdapter(*args, **kwargs)[source]

Minimal interface for dataset retrieval backends.

content_status(resolved_path)[source]

Return local content status for a resolved path.

Parameters:

resolved_path (ResolvedDatasetPath)

Return type:

ContentStatus

diagnostics()[source]

Return non-mutating backend readiness diagnostics.

Return type:

tuple[BackendDiagnostic, …]

fetch(resolved_path, *, force=False, dry_run=False)[source]

Retrieve or plan retrieval for one resolved path.

Parameters:
Return type:

FetchResult

name: str

DataLad/git-annex backend adapter.

class fresh_hectaresbc.backends.datalad.DataladBackend(data_repo_path, *, special_remote='arbutus-s3', command_timeout=120, env=None)[source]

Backend adapter for the linked DataLad/git-annex data repository.

Parameters:
  • data_repo_path (Path | str)

  • special_remote (str)

  • command_timeout (int)

  • env (dict[str, str] | None)

content_status(resolved_path)[source]

Return local content status without retrieving content.

Parameters:

resolved_path (ResolvedDatasetPath)

Return type:

ContentStatus

diagnostics()[source]

Return non-mutating backend readiness checks.

Return type:

tuple[BackendDiagnostic, …]

fetch(resolved_path, *, force=False, dry_run=False)[source]

Retrieve or plan retrieval for one resolved path.

Parameters:
Return type:

FetchResult

name = 'datalad'

Service And GIS Helpers

Optional FastAPI service for the HectaresBC browser app and GIS assistant.

The service is a thin shell around the static catalog and the optional agent tools. It keeps credentials in the service/CLI environment, never in browser code, and exposes only catalog, AOI, and bundle operations.

class fresh_hectaresbc.web_service.ServiceConfig(host='127.0.0.1', port=8030, root_path='', allow_remote=False, allow_agent=False, agent_model='opencode-go/deepseek-v4.1-flash', agent_timeout=300.0, workspace=<factory>, archive_root=None, femic_src=None, bundle_root=<factory>, tile_cache_root=<factory>, tile_cache_max_bytes=4294967296, tile_cog_root=<factory>, max_layers=6, max_area_ha=10000000.0, job_history_limit=100, job_history_max_age_days=30.0, bundle_history_limit=50, bundle_history_max_age_days=30.0, bundle_aoi_max_age_days=7.0, bundle_aoi_max_files=500, public_url=None, title='HectaresBC')[source]

Web service configuration.

Parameters:
  • host (str)

  • port (int)

  • root_path (str)

  • allow_remote (bool)

  • allow_agent (bool)

  • agent_model (str)

  • agent_timeout (float)

  • workspace (Path)

  • archive_root (Path | None)

  • femic_src (Path | None)

  • bundle_root (Path)

  • tile_cache_root (Path)

  • tile_cache_max_bytes (int)

  • tile_cog_root (Path)

  • max_layers (int)

  • max_area_ha (float)

  • job_history_limit (int)

  • job_history_max_age_days (float)

  • bundle_history_limit (int)

  • bundle_history_max_age_days (float)

  • bundle_aoi_max_age_days (float)

  • bundle_aoi_max_files (int)

  • public_url (str | None)

  • title (str)

fresh_hectaresbc.web_service.create_app(config)[source]

Create the FastAPI application.

Parameters:

config (ServiceConfig)

Return type:

FastAPI

Validate browser-drawn AOI geometry and inspect its area before clipping.

fresh_hectaresbc.aoi.inspect_aoi_geometry(geometry, *, max_area_ha)[source]

Return area, bounds, and limit status for a WGS84 AOI geometry.

Parameters:
  • geometry (dict[str, Any])

  • max_area_ha (float)

Return type:

dict[str, Any]

fresh_hectaresbc.aoi.validate_aoi_geometry(geometry)[source]

Validate a finite Polygon/MultiPolygon and return a shapely geometry.

Parameters:

geometry (dict[str, Any])

Return type:

Any

Clip recovered HectaresBC raster layers to a GeoJSON AOI.

fresh_hectaresbc.clip.clip_raster_to_aoi(dataset_id, aoi_geojson, output_dir, *, archive_root=None)[source]

Clip one catalog raster to the first feature in aoi_geojson.

Parameters:
  • dataset_id (str)

  • aoi_geojson (str | Path)

  • output_dir (str | Path)

  • archive_root (str | Path | None)

Return type:

ClipResult

Prepare multi-layer clipped raster bundles for an AOI.

exception fresh_hectaresbc.bundle.BundleCancelled[source]

Raised when a bundle job is cancelled between clipping steps.

exception fresh_hectaresbc.bundle.BundleError[source]

Raised when an AOI bundle cannot be prepared safely.

fresh_hectaresbc.bundle.prepare_bundle(*, layer_ids, output_root, aoi_query=None, aoi_name=None, aoi_geojson=None, archive_root=None, femic_src=None, max_layers=6, max_area_ha=10000000.0, public_url=None, progress_callback=None, cancel_check=None)[source]

Resolve an AOI, clip selected rasters, and write a downloadable ZIP.

Parameters:
  • layer_ids (list[str])

  • output_root (str | Path)

  • aoi_query (str | None)

  • aoi_name (str | None)

  • aoi_geojson (str | Path | None)

  • archive_root (str | Path | None)

  • femic_src (str | Path | None)

  • max_layers (int)

  • max_area_ha (float)

  • public_url (str | None)

  • progress_callback (Callable[[dict[str, Any]], None] | None)

  • cancel_check (Callable[[], bool] | None)

Return type:

dict[str, Any]

Retention for bundle outputs and temporary AOI geometries.

Job records have their own retention policy. This module handles the larger artifacts: <bundle_id>/ directories, their ZIPs, and browser-drawn AOI files. The newest bundles are kept; older terminal outputs are removed. Active jobs are never targeted because their bundle directory has no manifest yet and therefore is not discovered by the bundle scan.

fresh_hectaresbc.bundle_retention.prune_bundle_outputs(output_root, *, max_bundles=50, max_age_days=30.0, aoi_max_age_days=7.0, aoi_max_files=500)[source]

Remove old bundle outputs and temporary drawn-AOI files.

max_age_days and aoi_max_age_days of zero or less disable age pruning. Active bundle jobs are not discovered until their manifest is written, so their in-progress directories are left alone.

Parameters:
  • output_root (str | Path)

  • max_bundles (int)

  • max_age_days (float)

  • aoi_max_age_days (float)

  • aoi_max_files (int)

Return type:

dict[str, int]

Advisory bundle preflight estimates from AOI and source metadata.

fresh_hectaresbc.preflight.estimate_bundle(*, layer_ids, aoi_geometry, archive_root=None, max_layers=6, max_area_ha=10000000.0)[source]

Return advisory pixel/size/time estimates without clipping pixels.

Parameters:
  • layer_ids (list[str])

  • aoi_geometry (dict[str, Any])

  • archive_root (str | Path | None)

  • max_layers (int)

  • max_area_ha (float)

Return type:

dict[str, Any]

FEMIC BC Data Catalogue bridge for AOI resolution and materialization.

FEMIC owns the BC Data Catalogue search/scoring and AOI-scoped WFS machinery. This module keeps that logic on the FEMIC side, then turns the selected boundary features into a small GeoJSON AOI that the HectaresBC raster clipper can use.

fresh_hectaresbc.femic_bridge.resolve_aoi(query, *, name=None, limit=5, output_dir, femic_src=None, bbox_epsg3005=(159587.5, 173787.5, 1881187.5, 1748187.5))[source]

Resolve a named TSA/admin boundary and write a small GeoJSON AOI.

Returns a structured needs_name or ambiguous response when the catalogue layer is found but the requested feature is not unique, so the agent can ask the user to choose rather than guessing.

Parameters:
  • query (str)

  • name (str | None)

  • limit (int)

  • output_dir (str | Path)

  • femic_src (str | Path | None)

  • bbox_epsg3005 (tuple[float, float, float, float])

Return type:

dict[str, Any]

fresh_hectaresbc.femic_bridge.search_aoi_layers(query, *, limit=5, femic_src=None)[source]

Resolve candidate BCDC boundary packages without downloading geometry.

Parameters:
  • query (str)

  • limit (int)

  • femic_src (str | Path | None)

Return type:

dict[str, Any]

In-process bundle jobs with progress and best-effort cancellation.

The demo service runs one bundle job at a time so a six-layer clip cannot starve tile rendering or the assistant. Jobs are persisted as JSON under the bundle root so API clients can inspect recent work and service restarts leave a clear interrupted record instead of a stuck running job.

class fresh_hectaresbc.jobs.BundleJobManager(*, output_root, archive_root=None, femic_src=None, max_layers=6, max_area_ha=10000000.0, public_url=None, max_workers=1, job_history_limit=100, job_history_max_age_days=30.0, bundle_history_limit=50, bundle_history_max_age_days=30.0, bundle_aoi_max_age_days=7.0, bundle_aoi_max_files=500)[source]

Queue and track clipped-raster bundle jobs.

Parameters:
  • output_root (str | Path)

  • archive_root (str | Path | None)

  • femic_src (str | Path | None)

  • max_layers (int)

  • max_area_ha (float)

  • public_url (str | None)

  • max_workers (int)

  • job_history_limit (int)

  • job_history_max_age_days (float)

  • bundle_history_limit (int)

  • bundle_history_max_age_days (float)

  • bundle_aoi_max_age_days (float)

  • bundle_aoi_max_files (int)

prune_jobs(*, limit=None, max_age_days=None)[source]

Remove old terminal job records while keeping active jobs.

A terminal job is kept only when it is within both the newest-record limit and the age limit. Setting max_age_days to zero or a negative value disables age pruning.

Parameters:
  • limit (int | None)

  • max_age_days (float | None)

Return type:

dict[str, int]

prune_outputs()[source]

Prune expired bundle outputs and temporary AOI files.

Return type:

dict[str, int]

retry(job_id)[source]

Re-queue the failed layers of a terminal job using its bundle AOI.

Parameters:

job_id (str)

Return type:

dict[str, Any] | None

Zoom-dependent raster tiles from recovered HectaresBC source rasters.

The source rasters are 100 m (1 ha) BC Albers GeoTIFFs, usually tiled 64×64 inside the recovered ZIP payloads. This module renders 256×256 Web-Mercator tiles on demand so MapLibre can request only the tiles visible at the current zoom/pan instead of drawing one flattened preview image.

At z0–8 the renderer serves tiles from the already-generated 2048 px EPSG:3857 map overlay, which avoids reopening the multi-hundred-megabyte zip:// source for every low-zoom tile. At z9+ it reads and warps the source raster so the 1-ha cells remain available at high zoom. A bounded process cache keeps source dataset handles open and serializes reads per handle; metadata lookup opens the source once, after which high-zoom tile reads are typically tens of milliseconds.

fresh_hectaresbc.tiles.identify_pixel(dataset_id, lon, lat, *, archive_root=None)[source]

Read the source raster value and legend class at a WGS84 point.

Parameters:
  • dataset_id (str)

  • lon (float)

  • lat (float)

  • archive_root (str | Path | None)

Return type:

dict[str, Any]

fresh_hectaresbc.tiles.layer_metadata(dataset_id, *, archive_root=None)[source]

Return MapLibre raster-source metadata for one layer.

Parameters:
  • dataset_id (str)

  • archive_root (str | Path | None)

Return type:

dict[str, Any]

fresh_hectaresbc.tiles.prune_tile_cache(cache_root, *, max_bytes=4294967296)[source]

Delete least-recently-used tile files until the cache is under budget.

Parameters:
  • cache_root (str | Path)

  • max_bytes (int)

Return type:

dict[str, int]

fresh_hectaresbc.tiles.render_tile(dataset_id, z, x, y, *, archive_root=None, cache_root=None, cache_max_bytes=4294967296)[source]

Render one Web-Mercator PNG tile and record usage statistics.

Parameters:
  • dataset_id (str)

  • z (int)

  • x (int)

  • y (int)

  • archive_root (str | Path | None)

  • cache_root (str | Path | None)

  • cache_max_bytes (int)

Return type:

bytes

fresh_hectaresbc.tiles.tile_usage_stats(top=20)[source]

Return process-lifetime tile usage and cache statistics.

Parameters:

top (int)

Return type:

dict[str, Any]