Source code for fresh_hectaresbc.femic_bridge

"""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.
"""

from __future__ import annotations

import json
import re
import sys
from dataclasses import dataclass
from datetime import UTC, datetime
from pathlib import Path
from typing import Any

BC_BBOX_3005 = (159587.5, 173787.5, 1881187.5, 1748187.5)
NAME_FIELD_HINTS = (
    "name",
    "description",
    "label",
    "tsa",
    "region",
    "district",
    "area",
    "unit",
)


class FemicBridgeError(RuntimeError):
    """Raised when FEMIC cannot resolve or materialize an AOI boundary."""


@dataclass(frozen=True)
class AoiBoundary:
    """One resolved AOI boundary ready for raster clipping."""

    query: str
    name: str
    package_title: str
    package_name: str
    resource_name: str
    wfs_typename: str
    feature_count: int
    labels: tuple[str, ...]
    geometry: dict[str, Any]
    bbox_wgs84: tuple[float, float, float, float]
    bbox_3005: tuple[float, float, float, float]
    area_ha: float
    saved_geojson: Path
    saved_metadata: Path

    def to_dict(self, *, include_geometry: bool = True) -> dict[str, Any]:
        payload: dict[str, Any] = {
            "status": "ok",
            "query": self.query,
            "name": self.name,
            "package_title": self.package_title,
            "package_name": self.package_name,
            "resource_name": self.resource_name,
            "wfs_typename": self.wfs_typename,
            "feature_count": self.feature_count,
            "labels": list(self.labels),
            "bbox_wgs84": list(self.bbox_wgs84),
            "bbox_3005": list(self.bbox_3005),
            "area_ha": self.area_ha,
            "saved_geojson": str(self.saved_geojson),
            "saved_metadata": str(self.saved_metadata),
        }
        if include_geometry:
            payload["geometry"] = self.geometry
        return payload


def _ensure_femic(femic_src: str | Path | None = None) -> None:
    if femic_src:
        path = str(Path(femic_src).expanduser().resolve())
        if path not in sys.path:
            sys.path.insert(0, path)
    try:
        import femic  # noqa: F401
    except ImportError as exc:  # pragma: no cover - environment dependent
        raise FemicBridgeError(
            "FEMIC is not importable. Install FEMIC or pass --femic-src / set "
            "FRESH_HECTARESBC_FEMIC_SRC to the FEMIC src directory."
        ) from exc


def _normalize(value: Any) -> str:
    return re.sub(r"\s+", " ", str(value or "").casefold()).strip()


def _flatten_properties(properties: dict[str, Any]) -> str:
    values: list[str] = []
    for value in properties.values():
        if isinstance(value, str):
            values.append(value)
        elif isinstance(value, (int, float)):
            values.append(str(value))
        elif isinstance(value, (list, tuple)):
            values.extend(str(item) for item in value)
    return _normalize(" ".join(values))


def _label_for_properties(properties: dict[str, Any]) -> str:
    pieces: list[str] = []
    for key, value in properties.items():
        key_lower = key.casefold()
        if value in (None, "") or not any(hint in key_lower for hint in NAME_FIELD_HINTS):
            continue
        pieces.append(f"{key}={value}")
    if pieces:
        return " | ".join(pieces[:4])
    return " | ".join(
        f"{key}={value}"
        for key, value in list(properties.items())[:4]
        if value not in (None, "")
    )


def _candidate_options(
    features: list[dict[str, Any]], limit: int = 40
) -> list[dict[str, str]]:
    """Return display labels plus a safe name to pass back to resolve."""

    options: list[dict[str, str]] = []
    seen: set[str] = set()
    for feature in features:
        properties = feature.get("properties") or {}
        label = _label_for_properties(properties)
        preferred = ""
        for key, value in properties.items():
            if value in (None, ""):
                continue
            key_lower = key.casefold()
            if "description" in key_lower or key_lower in {
                "name",
                "admin_area_name",
                "region_name",
                "management_area_name",
                "unit_name",
            }:
                preferred = str(value)
                break
        name = preferred or label
        key = name.casefold()
        if not name or key in seen:
            continue
        seen.add(key)
        options.append({"label": label, "name": name})
        if len(options) >= limit:
            break
    return options


def _candidate_labels(features: list[dict[str, Any]], limit: int = 40) -> list[str]:
    labels: list[str] = []
    for feature in features:
        label = _label_for_properties(feature.get("properties") or {})
        if label and label not in labels:
            labels.append(label)
        if len(labels) >= limit:
            break
    return labels


def _matching_features(
    features: list[dict[str, Any]], tokens: list[str]
) -> list[dict[str, Any]]:
    """Match features, preferring exact numeric property equality.

    ``TSA 27`` must select ``TSA_NUMBER=27`` rather than every feature whose
    area string happens to contain "27".
    """

    numeric_tokens = [token for token in tokens if token.isdigit()]
    text_tokens = [token for token in tokens if not token.isdigit()]
    exact: list[dict[str, Any]] = []
    substring: list[dict[str, Any]] = []
    for feature in features:
        properties = feature.get("properties") or {}
        text = _flatten_properties(properties)
        property_values = {
            _normalize(value)
            for value in properties.values()
            if isinstance(value, (str, int, float))
        }
        numeric_ok = all(
            any(
                value == token or value.lstrip("0") == token.lstrip("0")
                for value in property_values
            )
            for token in numeric_tokens
        )
        text_ok = all(token in text for token in text_tokens)
        if numeric_ok and text_ok:
            exact.append(feature)
        if all(token in text for token in tokens):
            substring.append(feature)
    return exact if exact else substring


def _infer_crs(features: list[dict[str, Any]]) -> str:
    coordinates: list[tuple[float, float]] = []

    def collect(value: Any) -> None:
        if isinstance(value, (list, tuple)):
            if (
                len(value) >= 2
                and isinstance(value[0], (int, float))
                and isinstance(value[1], (int, float))
            ):
                coordinates.append((float(value[0]), float(value[1])))
                return
            for item in value:
                collect(item)

    for feature in features[:50]:
        collect((feature.get("geometry") or {}).get("coordinates"))
    if not coordinates:
        return "EPSG:3005"
    max_x = max(abs(x) for x, _ in coordinates)
    max_y = max(abs(y) for _, y in coordinates)
    if max_x <= 180 and max_y <= 90:
        return "EPSG:4326"
    return "EPSG:3005"


def _select_wfs_resource(match: Any) -> Any | None:
    for resource in getattr(match, "resources", ()):
        if (
            getattr(resource, "wfs_queryable", False)
            and getattr(resource, "wfs_typename", None)
            and getattr(resource, "url", None)
        ):
            return resource
    return None


def _fetch_features(resource: Any, bbox_epsg3005: tuple[float, float, float, float]) -> tuple[list[dict[str, Any]], str]:
    """Fetch WFS features through FEMIC's materialization helper."""

    from femic.bcdc_fetch import _fetch_wfs_payload_paged

    payload, request_url, warnings = _fetch_wfs_payload_paged(
        base_url=resource.url,
        typename=resource.wfs_typename,
        bbox_epsg3005=bbox_epsg3005,
    )
    features = payload.get("features") or []
    if not isinstance(features, list):
        raise FemicBridgeError("WFS response did not contain a feature list.")
    return features, request_url


def _candidate_score(match: Any, query: str, name: str) -> int:
    text = _normalize(f"{getattr(match, 'title', '')} {getattr(match, 'package_name', '')}")
    query_tokens = set(_normalize(query).split(" "))
    name_tokens = set(_normalize(name).split(" ")) if name else set()
    score = 0
    score += 5 * sum(1 for token in query_tokens if token and token in text)
    score += 8 * sum(1 for token in name_tokens if token and token in text)
    if "timber supply" in text and ("tsa" in name_tokens or "timber" in query_tokens):
        score += 50
    if "regional district" in text and "regional" in query_tokens:
        score += 50
    if "management area" in text and "tsa" in name_tokens:
        score -= 40
    if _select_wfs_resource(match) is not None:
        score += 10
    return score


[docs] def search_aoi_layers( query: str, *, limit: int = 5, femic_src: str | Path | None = None, ) -> dict[str, Any]: """Resolve candidate BCDC boundary packages without downloading geometry.""" _ensure_femic(femic_src) from femic.bcdc_catalog import resolve_bcdc_candidates result = resolve_bcdc_candidates(query, limit=limit) return { "query": query, "matches": [match.to_dict() for match in result.matches], "notes": list(result.notes), }
[docs] def resolve_aoi( query: str, *, name: str | None = None, limit: int = 5, output_dir: str | Path, femic_src: str | Path | None = None, bbox_epsg3005: tuple[float, float, float, float] = BC_BBOX_3005, ) -> dict[str, Any]: """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. """ _ensure_femic(femic_src) from femic.bcdc_catalog import resolve_bcdc_candidates resolved = resolve_bcdc_candidates(query, limit=max(limit, 8)) if not resolved.matches: raise FemicBridgeError(f"No BC Data Catalogue boundary match found for {query!r}.") requested_name = (name or "").strip() ranked = sorted( resolved.matches, key=lambda match: _candidate_score(match, query, requested_name), reverse=True, ) chosen = None features: list[dict[str, Any]] = [] request_url = "" resource = None for match in ranked[:5]: candidate_resource = _select_wfs_resource(match) if candidate_resource is None: continue try: candidate_features, candidate_url = _fetch_features( candidate_resource, bbox_epsg3005 ) except Exception: continue if not candidate_features: continue if requested_name: tokens = [token for token in _normalize(requested_name).split(" ") if token] candidate_matches = _matching_features(candidate_features, tokens) if not candidate_matches: continue features = candidate_features else: features = candidate_features chosen = match resource = candidate_resource request_url = candidate_url break if chosen is None or resource is None: # Return the best resolvable layer's candidate labels so the agent can # ask the user to choose a feature rather than silently picking one. for match in ranked: candidate_resource = _select_wfs_resource(match) if candidate_resource is None: continue try: features, request_url = _fetch_features( candidate_resource, bbox_epsg3005 ) except Exception: continue if features: chosen = match resource = candidate_resource break if chosen is None or resource is None or not features: raise FemicBridgeError( f"No WFS-backed boundary layer could be materialized for {query!r}." ) top_match = chosen assert resource is not None labels = _candidate_labels(features) options = _candidate_options(features) if not requested_name: return { "status": "needs_name", "query": query, "package_title": top_match.title, "resource_name": resource.name, "wfs_typename": resource.wfs_typename, "feature_count": len(features), "candidates": labels, "candidate_options": options, "request_url": request_url, } tokens = [token for token in _normalize(requested_name).split(" ") if token] matches = _matching_features(features, tokens) if not matches: return { "status": "needs_name", "query": query, "requested_name": requested_name, "package_title": top_match.title, "resource_name": resource.name, "wfs_typename": resource.wfs_typename, "feature_count": len(features), "candidates": labels, "candidate_options": options, "request_url": request_url, } matched_labels = _candidate_labels(matches, limit=10) if len(matches) > 8: return { "status": "ambiguous", "query": query, "requested_name": requested_name, "package_title": top_match.title, "resource_name": resource.name, "wfs_typename": resource.wfs_typename, "match_count": len(matches), "candidates": matched_labels, "candidate_options": _candidate_options(matches, limit=10), "request_url": request_url, } import geopandas as gpd # type: ignore[import-untyped] from shapely.geometry import shape # type: ignore[import-untyped] from shapely.ops import unary_union # type: ignore[import-untyped] crs = _infer_crs(matches) geometries = [ shape(feature["geometry"]) for feature in matches if feature.get("geometry") ] if not geometries: raise FemicBridgeError("Matched WFS features did not contain usable geometry.") geometry = unary_union(geometries) gdf = gpd.GeoDataFrame(geometry=[geometry], crs=crs) gdf_wgs84 = gdf.to_crs("EPSG:4326") gdf_3005 = gdf.to_crs("EPSG:3005") bounds_3005 = gdf_3005.total_bounds bounds_wgs84 = gdf_wgs84.total_bounds area_ha = float(gdf_3005.geometry.area.iloc[0] / 10_000.0) output_root = Path(output_dir).expanduser().resolve() output_root.mkdir(parents=True, exist_ok=True) slug = re.sub(r"[^A-Za-z0-9]+", "-", requested_name).strip("-").lower() or "aoi" geojson_path = output_root / f"{slug}.geojson" metadata_path = output_root / f"{slug}.json" feature = { "type": "Feature", "properties": { "name": requested_name, "query": query, "package_title": top_match.title, "resource_name": resource.name, "wfs_typename": resource.wfs_typename, "feature_count": len(matches), "labels": matched_labels, "area_ha": area_ha, }, "geometry": gdf_wgs84.geometry.iloc[0].__geo_interface__, } geojson_path.write_text( json.dumps( {"type": "FeatureCollection", "features": [feature]}, indent=2, ) + "\n", encoding="utf-8", ) metadata = AoiBoundary( query=query, name=requested_name, package_title=top_match.title, package_name=top_match.package_name, resource_name=resource.name, wfs_typename=resource.wfs_typename, feature_count=len(matches), labels=tuple(matched_labels), geometry=feature["geometry"], bbox_wgs84=tuple(float(value) for value in bounds_wgs84), bbox_3005=tuple(float(value) for value in bounds_3005), area_ha=area_ha, saved_geojson=geojson_path, saved_metadata=metadata_path, ) metadata_path.write_text( json.dumps( { **metadata.to_dict(include_geometry=False), "generated_utc": datetime.now(UTC).isoformat(), "request_url": request_url, }, indent=2, ) + "\n", encoding="utf-8", ) return metadata.to_dict()