Add geocoding bounds and cities management to address extraction settings

Backend:
- Add bounds_min_lat/max_lat/min_lng/max_lng to address extraction settings
- Add geocoding_cities table and CRUD functions (get/add/update/delete/reorder/bulk)
- Update AddressExtractionSettings dataclass with bounds and cities fields
- Add cities CRUD API endpoints and bounds/compute endpoint

Frontend:
- Add bounds input fields and inline Leaflet map picker to Address Extraction tab
- Add 'Compute from calls' and 'Fit map to values' buttons for bounds
- Add Geocoding Cities table with add/edit/delete/reorder (mirrors Regions UI)
- Add city modals and event handlers in edit_systems.js

Migrations:
- 029_add_geocode_bounds.sql
- 030_add_geocoding_cities.sql

Author: iCAD Dispatch

lib/address_extractor_module.py

@@ -59,6 +59,15 @@ class AddressExtractionSettings:
     geocode_state: Optional[str] = None
     geocode_city: Optional[str] = None
 
+    # Phase 1: Bounding box for Google Maps viewport bias
+    bounds_min_lat: Optional[float] = None
+    bounds_max_lat: Optional[float] = None
+    bounds_min_lng: Optional[float] = None
+    bounds_max_lng: Optional[float] = None
+
+    # Phase 2: Service area cities for LLM hints (ordered list)
+    geocode_cities: Optional[List[str]] = None
+
     # Regions table (list of dicts from DB/API: state_code, county_name, priority, ...)
     regions: Optional[List[Dict[str, Any]]] = None
 
@@ -73,6 +82,13 @@ def from_system_row(system_row: Dict[str, Any]) -> "AddressExtractionSettings":
         cfg = (system_row or {}).get("address_extraction") or {}
         regions = cfg.get("regions") or []
 
+        # Parse bounds from float or None
+        def _f(val):
+            try:
+                return float(val) if val is not None else None
+            except (ValueError, TypeError):
+                return None
+
         return AddressExtractionSettings(
             enabled=bool(int(cfg.get("enabled") or 0)),
             openai_api_key=cfg.get("openai_api_key"),
@@ -81,6 +97,11 @@ def from_system_row(system_row: Dict[str, Any]) -> "AddressExtractionSettings":
             geocode_country=cfg.get("geocode_country") or cfg.get("country"),
             geocode_state=cfg.get("geocode_state") or cfg.get("state"),
             geocode_city=cfg.get("geocode_city") or cfg.get("city"),
+            bounds_min_lat=_f(cfg.get("bounds_min_lat")),
+            bounds_max_lat=_f(cfg.get("bounds_max_lat")),
+            bounds_min_lng=_f(cfg.get("bounds_min_lng")),
+            bounds_max_lng=_f(cfg.get("bounds_max_lng")),
+            geocode_cities=cfg.get("geocode_cities") or [],
             regions=regions,
         )
 
@@ -194,6 +215,8 @@ def __init__(
             regions: Optional[Dict[str, List[str]]] = None,
             city_hint: Optional[str] = None,
             state_hint: Optional[str] = None,
+            bounds: Optional[Tuple[Tuple[float, float], Tuple[float, float]]] = None,
+            region: Optional[str] = None,
             timeout: int = 10,
             logger: Optional[logging.Logger] = None,
     ):
@@ -206,6 +229,8 @@ def __init__(
             regions: Dict mapping state codes to county lists
             city_hint: Optional city to help filter city-level results
             state_hint: Optional state to help filter city-level results
+            bounds: Optional ((sw_lat, sw_lng), (ne_lat, ne_lng)) viewport bias
+            region: Optional ccTLD region bias (e.g. 'ca', 'us')
             timeout: Request timeout in seconds
             logger: Custom logger instance
         """
@@ -216,6 +241,8 @@ def __init__(
         self.country = (country or "us").lower()
         self.city_hint = (city_hint or "").strip()
         self.state_hint = (state_hint or "").strip()
+        self.bounds = bounds
+        self.region = (region or "").strip().lower()
         self.timeout = timeout
 
         # Derived values
@@ -227,9 +254,11 @@ def __init__(
         self._validate_config()
 
         self.log.info(
-            "AddressGeocoder initialized: states=%s, counties=%d",
+            "AddressGeocoder initialized: states=%s, counties=%d, bounds=%s, region=%s",
             self.target_states,
             len(self.target_counties),
+            "yes" if self.bounds else "no",
+            self.region or "none",
         )
 
     def _validate_config(self) -> None:
@@ -298,6 +327,16 @@ def geocode_once(query: str) -> Optional[dict]:
                 "components": components,
             }
 
+            # Phase 1: Add viewport bounds bias
+            if self.bounds:
+                sw_lat, sw_lng = self.bounds[0]
+                ne_lat, ne_lng = self.bounds[1]
+                params["bounds"] = f"{sw_lat},{sw_lng}|{ne_lat},{ne_lng}"
+
+            # Phase 3: Add region (ccTLD) bias
+            if self.region:
+                params["region"] = self.region
+
             try:
                 response = requests.get(
                     endpoint,
@@ -595,7 +634,8 @@ def extract_address(
             self,
             transcript: str,
             *,
-            town_hint: Optional[str] = None,
+            town_hints: Optional[List[str]] = None,
+            town_hint: Optional[str] = None,  # legacy alias
             county_hint: Optional[str] = None,
             state_hint: Optional[str] = None,
             country_hint: str = "US",
@@ -605,7 +645,8 @@ def extract_address(
 
         Args:
             transcript: The dispatch transcript text
-            town_hint: The town/city to use as a default when completing addresses
+            town_hints: List of cities/towns in the service area (Phase 2)
+            town_hint: Legacy single city hint (falls back to town_hints[0])
             county_hint: Expected county
             state_hint: Expected state
             country_hint: Expected country (default "US")
@@ -618,9 +659,14 @@ def extract_address(
             self.log.info("AddressExtractorLLM: empty transcript, skipping")
             return None
 
+        # Normalize legacy single hint to list
+        hints = town_hints or []
+        if not hints and town_hint:
+            hints = [town_hint]
+
         prompt = self._build_prompt(
             text,
-            town_hint=town_hint,
+            town_hints=hints,
             county_hint=county_hint,
             state_hint=state_hint,
             country_hint=country_hint,
@@ -641,7 +687,7 @@ def extract_address(
             return None
 
         # Filter out generic city/state-only responses
-        if town_hint and self._is_generic_city_response(raw, town_hint, state_hint):
+        if town_hints and self._is_generic_city_response(raw, town_hints, state_hint):
             self.log.info(
                 "AddressExtractorLLM: filtered generic city/state response: %s",
                 raw,
@@ -682,7 +728,7 @@ def _build_prompt(
             self,
             transcript: str,
             *,
-            town_hint: Optional[str],
+            town_hints: List[str],
             county_hint: Optional[str],
             state_hint: Optional[str],
             country_hint: str,
@@ -696,15 +742,16 @@ def _build_prompt(
         counties_str = ", ".join(self.target_counties) if self.target_counties else county_hint or "Not specified"
 
         town_section = ""
-        if town_hint:
+        if town_hints:
+            hints_str = ", ".join(f'"{h}"' for h in town_hints[:20])  # cap at 20 to keep prompt size reasonable
             town_section = f"""
-TOWN HINT (NOT A HARD FILTER)
-- The dispatch/talkgroup is associated with "{town_hint}".
-- Use "{town_hint}" ONLY as a hint to complete an address when:
+SERVICE AREA CITIES (NOT A HARD FILTER)
+- The following cities/towns are within this dispatch service area: {hints_str}.
+- Use these ONLY as hints to complete an address when:
   • The transcript clearly gives a street / intersection / place name
   • BUT does NOT clearly specify a city/town.
-- If the transcript clearly mentions a different city/town, use THAT city/town instead of "{town_hint}".
-- Do NOT restrict yourself to "{town_hint}" only. Any city/town INSIDE the service region is acceptable.
+- If the transcript clearly mentions a different city/town, use THAT city/town instead.
+- Do NOT restrict yourself to these cities only. Any city/town INSIDE the service region is acceptable.
 """
 
         return f"""You are an assistant that extracts and completes addresses from first responder dispatch transcripts.
@@ -820,27 +867,27 @@ def _is_no_address_response(s: str) -> bool:
     @staticmethod
     def _is_generic_city_response(
             response: str,
-            town_hint: Optional[str],
+            town_hints: List[str],
             state_hint: Optional[str],
     ) -> bool:
         """
-        Check if LLM just returned the generic city/state with no street.
+        Check if LLM just returned a generic city/state with no street.
         This indicates it couldn't find a real address.
         """
-        if not town_hint:
+        if not town_hints:
             return False
 
         response_clean = response.strip()
 
-        # Match patterns like "Sayre, PA" or just "Sayre"
-        patterns = [
-            rf"^{re.escape(town_hint)}$",
-            rf"^{re.escape(town_hint)},\s*{re.escape(state_hint or '')}$",
-        ]
-
-        for pattern in patterns:
-            if re.match(pattern, response_clean, re.IGNORECASE):
-                return True
+        for hint in town_hints:
+            # Match patterns like "Sayre, PA" or just "Sayre"
+            patterns = [
+                rf"^{re.escape(hint)}$",
+                rf"^{re.escape(hint)},\s*{re.escape(state_hint or '')}$",
+            ]
+            for pattern in patterns:
+                if re.match(pattern, response_clean, re.IGNORECASE):
+                    return True
 
         return False
 
@@ -918,13 +965,29 @@ def __init__(
         if not target_states and settings.geocode_state:
             target_states = [settings.geocode_state.strip().upper()]
 
+        # Build bounds tuple if all four corners are present
+        bounds = None
+        if (settings.bounds_min_lat is not None and
+            settings.bounds_max_lat is not None and
+            settings.bounds_min_lng is not None and
+            settings.bounds_max_lng is not None):
+            bounds = (
+                (settings.bounds_min_lat, settings.bounds_min_lng),
+                (settings.bounds_max_lat, settings.bounds_max_lng),
+            )
+
+        # Phase 3: derive region from country (ccTLD bias)
+        region = (settings.geocode_country or "us").lower()
+
         # Instantiate geocoder from settings (Google Maps only)
         self.geocoder = AddressGeocoder(
             google_api_key=settings.google_maps_api_key,
             country=(settings.geocode_country or "us").lower(),
             regions=region_map or None,
             city_hint=settings.geocode_city,
             state_hint=settings.geocode_state,
+            bounds=bounds,
+            region=region,
             timeout=10,
             logger=self.log,
         )
@@ -981,11 +1044,21 @@ def extract_and_geocode(
             )
             return {"extracted": None, "geocoded": None}
 
-        town_hint = town_hint_override or self.settings.geocode_city
+        # Build town hints list: override + configured cities
+        town_hints = []
+        if town_hint_override:
+            town_hints.append(town_hint_override)
+        if self.settings.geocode_cities:
+            for city in self.settings.geocode_cities:
+                if city and city not in town_hints:
+                    town_hints.append(city)
+        # Fallback to legacy single city if nothing else
+        if not town_hints and self.settings.geocode_city:
+            town_hints.append(self.settings.geocode_city)
 
         addr = self.llm.extract_address(
             transcript,
-            town_hint=town_hint,
+            town_hints=town_hints,
             county_hint=None,  # optional, could be wired from settings if needed
             state_hint=self.settings.geocode_state,
             country_hint=self.settings.geocode_country or "US",