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
- content_status(dataset)[source]
Report local content status without fetching data.
- Parameters:
dataset (str | DatasetRecord)
- Return type:
- 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:
dataset (str | DatasetRecord)
force (bool)
dry_run (bool)
- Return type:
- fetch_many(datasets, *, force=False, dry_run=False)[source]
Retrieve or plan retrieval for multiple datasets.
- Parameters:
datasets (list[str | DatasetRecord] | tuple[str | DatasetRecord, ...])
force (bool)
dry_run (bool)
- 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:
- 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:
- 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:
- classmethod from_metadata_root(metadata_root)[source]
Load recovered catalog records from a metadata directory.
- Parameters:
metadata_root (Path | str)
- Return type:
- classmethod from_package_data()[source]
Load recovered catalog records bundled with the installed package.
- Return type:
- get(dataset_id)[source]
Return exactly one record by recovered dataset ID.
- Parameters:
dataset_id (str)
- Return type:
- 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.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.
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]
- 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:
catalog (Catalog)
data_repo_path (Path | str | None)
backend (BackendAdapter | None)
- content_status(dataset)[source]
Report local availability without fetching content.
- Parameters:
dataset (str | DatasetRecord)
- Return type:
- 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:
dataset (str | DatasetRecord)
force (bool)
dry_run (bool)
- Return type:
- fetch_many(datasets, *, force=False, dry_run=False)[source]
Retrieve or plan retrieval for multiple datasets in input order.
- Parameters:
datasets (list[str | DatasetRecord] | tuple[str | DatasetRecord, ...])
force (bool)
dry_run (bool)
- 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:
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:
- 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:
resolved_path (ResolvedDatasetPath)
force (bool)
dry_run (bool)
- Return type:
- 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:
- 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:
resolved_path (ResolvedDatasetPath)
force (bool)
dry_run (bool)
- Return type:
- 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_daysandaoi_max_age_daysof 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_nameorambiguousresponse 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_daysto zero or a negative value disables age pruning.- Parameters:
limit (int | None)
max_age_days (float | None)
- Return type:
dict[str, int]
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