Update hierarchical_search.py

hierarchical_search.py

@@ -59,13 +59,7 @@ logger = logging.getLogger(__name__)
 # ---------------------------------------------------------------------------
 # Depth -> data resolution
 # ---------------------------------------------------------------------------
-# Coarse levels use cheap/already-area-representative sources; only the
-# deepest, smallest, flagged nodes ever pay for the expensive ones.
-# BMKG_STATION (Indonesian met agency station data) is the ideal finest-leaf
-# source for an Indonesia deployment if a real feed is wired up -- left out
-# of the default chain since era5_data_pipeline.py's fetchers dict (in
-# fetch_zone_obs) doesn't currently implement a BMKG fetcher; add one there
-# first, then just append it below.
+
 RESOLUTION_BY_DEPTH: List[DataSource] = [
     DataSource.ERA5_REANALYSIS,   # depth 0-1: country / province scale
     DataSource.ERA5_REANALYSIS,
@@ -95,8 +89,6 @@ class BBox:
         return ((self.lat_min + self.lat_max) / 2.0, (self.lon_min + self.lon_max) / 2.0)
 
     def split(self) -> Tuple["BBox", "BBox"]:
-        """Bisect along whichever axis (lat or lon) currently spans further --
-        literally the 'top/bottom or left/right 50%' heuristic."""
         lat_span = self.lat_max - self.lat_min
         lon_span = self.lon_max - self.lon_min
         if lat_span >= lon_span:
@@ -140,8 +132,6 @@ class SpatialNode:
 
 @dataclass
 class ResolvedLeaf:
-    """One terminal result from the search -- either max_depth was hit or the
-    node's coarse read was already below the alert floor."""
     node: SpatialNode
     max_risk: float
     alert_level: AlertLevel
@@ -157,20 +147,11 @@ def _score_node(
     date_range: Tuple[datetime, datetime],
     config_template: ForecastConfig,
 ) -> Tuple[float, AlertLevel, DataSource]:
-    """Register this node's bbox as a zone (idempotent -- register_zone just
-    overwrites), fetch it at the resolution appropriate for its depth, and
-    score it with the exact same crop_risk_scorer used everywhere else in
-    this project. No RL involved -- this is Phase 1's entire decision rule.
-    """
     polygon = node.bbox.to_polygon(node.node_id)
     register_zone(polygon)
 
     cfg_dict = config_template.to_dict()
     if config_template.force_data_source is None:
-        # Only apply depth-based resolution when the caller hasn't already
-        # pinned a source -- an explicit override (e.g. forcing SYNTHETIC
-        # for an offline test) must actually take effect everywhere, not
-        # get silently clobbered per-node.
         source = _resolution_for_depth(node.depth)
         cfg_dict["force_data_source"] = source.value
     else:
@@ -193,18 +174,6 @@ def hierarchical_search(
     recurse_floor: AlertLevel = AlertLevel.WARNING,
     config_template: Optional[ForecastConfig] = None,
 ) -> List[ResolvedLeaf]:
-    """Budget-constrained best-first traversal of the bisection tree.
-
-    Best-first: a max-heap on max_risk, so a hard budget cap spends its
-    fetches on the worst-looking parts of the map first. A branch stops
-    (records a ResolvedLeaf) at max_depth or once alert_level drops below
-    recurse_floor. Total fetches <= budget always, regardless of leaf count
-    -- that's what makes country scale tractable.
-
-    Default recurse_floor is WARNING (product freeze): only refine regions
-    that already clear the client-facing drought/flood bars. Pass
-    AlertLevel.WATCH or ADVISORY to recurse more aggressively.
-    """
     cfg_template = config_template or ForecastConfig()
     root = SpatialNode("root", root_bbox, depth=0)
 
@@ -238,10 +207,6 @@ def hierarchical_search(
             heapq.heappush(frontier, (-max_risk, next(counter), child))
 
     if failed > 0 and failed == spent:
-        # Every single node failed -- almost certainly a systemic problem
-        # (bad config, no network at all, wrong credentials), not noise.
-        # Returning an empty/near-empty list here would look identical to
-        # "searched thoroughly, found nothing risky" -- silently wrong.
         raise RuntimeError(
             f"hierarchical_search: all {spent} scored nodes failed -- "
             f"check config_template/credentials before trusting any result "
@@ -289,7 +254,6 @@ def _decide_with_policy(node: SpatialNode, children_contexts, model, env_factory
 if __name__ == "__main__":
     logging.basicConfig(level=logging.INFO, format="%(asctime)s | %(levelname)s | %(message)s")
 
-    # Roughly Indonesia's bounding box, for a realistic worst-case leaf count.
     indonesia_bbox = BBox(lat_min=-11.0, lat_max=6.0, lon_min=95.0, lon_max=141.0)
 
     date_range = (
@@ -297,8 +261,6 @@ if __name__ == "__main__":
         datetime(2026, 7, 31, tzinfo=timezone.utc),
     )
 
-    # force SYNTHETIC everywhere so this self-test needs no API credentials
-    # and no network access -- purely validates the tree/budget/pruning logic.
     cfg = ForecastConfig(force_data_source=DataSource.SYNTHETIC)
 
     results = hierarchical_search(
@@ -317,4 +279,4 @@ if __name__ == "__main__":
     for depth in sorted(by_depth):
         leaves = by_depth[depth]
         alerts = [l.alert_level.value for l in leaves]
-        print(f"  depth {depth}: {len(leaves)} branches stopped here -- alerts: {alerts}")
+        print(f"  depth {depth}: {len(leaves)} branches stopped here -- alerts: {alerts}")