Add country metadata and source quality signals for immigration research.

apis/country_profile.py

@@ -0,0 +1,44 @@
+"""Country profile helpers for the Borderless agent."""
+
+from __future__ import annotations
+
+from typing import Any
+
+from apis.official_sources import hints_for_country
+from apis.rest_countries import lookup_country
+
+
+def get_country_profiles(countries: list[str]) -> dict[str, Any]:
+    profiles: list[dict[str, Any]] = []
+    unknown: list[str] = []
+
+    for raw_code in countries:
+        code = (raw_code or "").strip().upper()
+        if not code:
+            continue
+        info = lookup_country(code)
+        if not info:
+            unknown.append(code)
+            continue
+
+        iso2 = info["cca2"]
+        profiles.append(
+            {
+                "name": info["name"],
+                "iso2": iso2,
+                "iso3": info["cca3"],
+                "region": info.get("region"),
+                "subregion": info.get("subregion"),
+                "capital": info.get("capital") or [],
+                "area_sq_km": info.get("area"),
+                "lat": info["lat"],
+                "lng": info["lng"],
+                "flag": info.get("flag"),
+                "official_immigration_domains": hints_for_country(iso2),
+            }
+        )
+
+    result: dict[str, Any] = {"countries": profiles}
+    if unknown:
+        result["unknown_codes"] = unknown
+    return result

apis/exa.py

@@ -8,6 +8,8 @@ from typing import Any
 
 from exa_py import Exa
 
+from apis.official_sources import classify_source, infer_official_domains
+
 HIGHLIGHT_CHAR_LIMIT = 2000
 SUMMARY_CHAR_LIMIT = 500
 DEFAULT_NUM_RESULTS = 8
@@ -36,11 +38,13 @@ def _result_dict(result: Any) -> dict[str, Any]:
         _truncate(highlight, HIGHLIGHT_CHAR_LIMIT) for highlight in highlights
     ]
     summary = getattr(result, "summary", None)
+    source_quality = classify_source(result.url or "")
     return {
         "title": result.title or "",
         "url": result.url or "",
         "published_date": result.published_date,
         "score": result.score,
+        "source_quality": source_quality,
         "highlights": trimmed_highlights,
         "summary": _truncate(summary, SUMMARY_CHAR_LIMIT) if summary else None,
     }
@@ -88,11 +92,19 @@ def search_immigration(
         if include_domains:
             kwargs["include_domains"] = include_domains
 
+        official_domain_hints = infer_official_domains(normalized_query, country)
+
         response = _client().search(normalized_query, **kwargs)
         results = [_result_dict(result) for result in (response.results or [])]
         return {
             "query": normalized_query,
             "num_results": len(results),
+            "official_domain_hints": official_domain_hints,
+            "official_results": sum(
+                1
+                for result in results
+                if result.get("source_quality", {}).get("is_official")
+            ),
             "results": results,
         }
     except Exception as exc:

apis/official_sources.py

@@ -0,0 +1,158 @@
+"""Helpers for identifying official immigration source domains."""
+
+from __future__ import annotations
+
+from urllib.parse import urlparse
+
+OFFICIAL_DOMAIN_HINTS: dict[str, list[str]] = {
+    "AU": ["homeaffairs.gov.au", "immi.homeaffairs.gov.au"],
+    "CA": ["canada.ca", "cic.gc.ca"],
+    "DE": ["make-it-in-germany.com", "bamf.de", "auswaertiges-amt.de"],
+    "DK": ["nyidanmark.dk"],
+    "ES": ["inclusion.gob.es", "exteriores.gob.es"],
+    "FI": ["migri.fi"],
+    "FR": ["france-visas.gouv.fr", "service-public.fr"],
+    "GB": ["gov.uk"],
+    "IE": ["irishimmigration.ie", "enterprise.gov.ie"],
+    "JP": ["isa.go.jp", "mofa.go.jp"],
+    "NL": ["ind.nl"],
+    "NO": ["udi.no"],
+    "NZ": ["immigration.govt.nz"],
+    "PT": ["aima.gov.pt", "eportugal.gov.pt", "vistos.mne.gov.pt"],
+    "SE": ["migrationsverket.se"],
+    "SG": ["ica.gov.sg", "mom.gov.sg"],
+    "US": ["uscis.gov", "travel.state.gov"],
+}
+
+COUNTRY_ALIASES: dict[str, str] = {
+    "australia": "AU",
+    "canada": "CA",
+    "denmark": "DK",
+    "finland": "FI",
+    "france": "FR",
+    "germany": "DE",
+    "ireland": "IE",
+    "japan": "JP",
+    "netherlands": "NL",
+    "new zealand": "NZ",
+    "norway": "NO",
+    "portugal": "PT",
+    "singapore": "SG",
+    "spain": "ES",
+    "sweden": "SE",
+    "uk": "GB",
+    "united kingdom": "GB",
+    "united states": "US",
+    "usa": "US",
+}
+
+UNOFFICIAL_CONTEXT_TERMS = (
+    "blog",
+    "forum",
+    "reddit",
+    "quora",
+    "lawfirm",
+    "law-firm",
+    "immigrationlaw",
+    "relocation",
+    "movingto",
+)
+
+
+def domain_from_url(url: str) -> str:
+    parsed = urlparse(url or "")
+    host = parsed.netloc.lower().split("@")[-1].split(":")[0]
+    if host.startswith("www."):
+        host = host[4:]
+    return host
+
+
+def is_domain_match(domain: str, official_domain: str) -> bool:
+    normalized = official_domain.lower()
+    return domain == normalized or domain.endswith(f".{normalized}")
+
+
+def hints_for_country(country: str | None) -> list[str]:
+    if not country:
+        return []
+    normalized = country.strip().upper()
+    return OFFICIAL_DOMAIN_HINTS.get(normalized, [])
+
+
+def infer_country_codes(text: str, country: str | None = None) -> list[str]:
+    codes: list[str] = []
+    if country:
+        normalized = country.strip().upper()
+        if normalized in OFFICIAL_DOMAIN_HINTS:
+            codes.append(normalized)
+
+    lowered = (text or "").lower()
+    for alias, code in COUNTRY_ALIASES.items():
+        if alias in lowered and code not in codes:
+            codes.append(code)
+    return codes
+
+
+def infer_official_domains(
+    text: str,
+    country: str | None = None,
+    *,
+    max_domains: int = 8,
+) -> list[str]:
+    domains: list[str] = []
+    for code in infer_country_codes(text, country):
+        for domain in OFFICIAL_DOMAIN_HINTS.get(code, []):
+            if domain not in domains:
+                domains.append(domain)
+            if len(domains) >= max_domains:
+                return domains
+    return domains
+
+
+def classify_source(url: str) -> dict[str, object]:
+    domain = domain_from_url(url)
+    known_official = [
+        official_domain
+        for domains in OFFICIAL_DOMAIN_HINTS.values()
+        for official_domain in domains
+        if is_domain_match(domain, official_domain)
+    ]
+
+    if known_official:
+        return {
+            "domain": domain,
+            "type": "official_government",
+            "is_official": True,
+            "reason": f"Matches official domain hint {known_official[0]}",
+        }
+
+    if domain.endswith(".gov") or ".gov." in domain or domain.endswith(".gouv.fr"):
+        return {
+            "domain": domain,
+            "type": "government",
+            "is_official": True,
+            "reason": "Government domain pattern",
+        }
+
+    if "embassy" in domain or "consulate" in domain:
+        return {
+            "domain": domain,
+            "type": "embassy_or_consulate",
+            "is_official": True,
+            "reason": "Embassy or consulate domain pattern",
+        }
+
+    if any(term in domain for term in UNOFFICIAL_CONTEXT_TERMS):
+        return {
+            "domain": domain,
+            "type": "unofficial_context",
+            "is_official": False,
+            "reason": "Likely blog, forum, legal-service, or relocation context",
+        }
+
+    return {
+        "domain": domain,
+        "type": "unknown",
+        "is_official": False,
+        "reason": "No official-domain signal detected",
+    }

apis/rest_countries.py

@@ -41,6 +41,9 @@ def _country_index() -> dict[str, dict[str, Any]]:
             "subregion": country.get("subregion"),
             "capital": country.get("capital") or [],
             "area": country.get("area"),
+            "flag": (country.get("flags") or {}).get("png")
+            or (country.get("flags") or {}).get("svg"),
+            "flag_alt": (country.get("flags") or {}).get("alt"),
         }
 
         if entry["cca2"]:

ui/inference/tool_schemas/__init__.py

@@ -3,6 +3,7 @@ from __future__ import annotations
 from typing import Any
 
 from .crawl_web_site import SCHEMA as crawl_web_site
+from .get_country_profile import SCHEMA as get_country_profile
 from .scrape_web_page import SCHEMA as scrape_web_page
 from .search_immigration_info import SCHEMA as search_immigration_info
 from .think import SCHEMA as think
@@ -10,6 +11,7 @@ from .update_globe import SCHEMA as update_globe
 
 TOOL_SCHEMAS: list[dict[str, Any]] = [
     think,
+    get_country_profile,
     search_immigration_info,
     scrape_web_page,
     crawl_web_site,

ui/inference/tool_schemas/get_country_profile.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+from typing import Any
+
+SCHEMA: dict[str, Any] = {
+    "type": "function",
+    "function": {
+        "name": "get_country_profile",
+        "description": (
+            "Fetch basic country metadata and official immigration domain hints. "
+            "Use this before comparing or marking destination countries on the globe."
+        ),
+        "parameters": {
+            "type": "object",
+            "properties": {
+                "countries": {
+                    "type": "array",
+                    "items": {"type": "string"},
+                    "description": "ISO-2 or ISO-3 country codes, e.g. ['CA', 'DE', 'AUS']",
+                },
+            },
+            "required": ["countries"],
+        },
+    },
+}

ui/inference/tool_schemas/search_immigration_info.py

@@ -10,8 +10,9 @@ SCHEMA: dict[str, Any] = {
             "Search the web for immigration, visa, and relocation information. "
             "Use this as the primary discovery tool when you need to find "
             "official government pages, embassy sites, or current policy details. "
-            "Returns titles, URLs, and relevant excerpts. Follow up with "
-            "scrape_web_page on the best official URLs for full page content."
+            "Returns titles, URLs, relevant excerpts, source-quality labels, and "
+            "official domain hints. Follow up with scrape_web_page on the best "
+            "official URLs for full page content."
         ),
         "parameters": {
             "type": "object",