feat(scaling): enterprise multi-market dynamic registry and international scaling support

config.py

@@ -28,3 +28,14 @@ APP_WRITE_BUCKET_ID = os.environ.get("APP_WRITE_BUCKET_ID", "")
 MAPBOX_ACCESS_TOKEN = os.environ.get("MAPBOX_ACCESS_TOKEN", "")
 CONTACT_EMAIL = os.environ.get("CONTACT_EMAIL", "hello@example.com")
 CONTACT_WHATSAPP = os.environ.get("CONTACT_WHATSAPP", "1234567890")
+
+# ── Market Registry ───────────────────────────────────────────────────────────
+# How often (seconds) the background task should re-fetch the market list.
+# Default 300 s (5 min). Set to 0 to disable automatic background refresh.
+MARKET_CACHE_TTL_SECONDS = int(os.environ.get("MARKET_CACHE_TTL_SECONDS", "300"))
+
+# ── Geocoding ─────────────────────────────────────────────────────────────────
+# Optional ISO 3166-1 alpha-2 country code(s) to restrict Mapbox geocoding
+# (e.g. "US" for US-only, "NG" for Nigeria-only, "US,NG" for both).
+# Leave empty (default) to allow global geocoding across all tracked markets.
+GEOCODE_COUNTRY_FILTER = os.environ.get("GEOCODE_COUNTRY_FILTER", "")

main.py

@@ -37,6 +37,14 @@ app.add_middleware(
 import unified_ingest
 unified_ingest.ensure_ingested()
 
+# ── Startup: initialize live market registry ──────────────────────────────────
+# Fetches the authoritative market list from Supabase once at boot.
+# All downstream consumers (prompts, tools, agent_loop) read from this cache.
+# Adding a new market (e.g. Dubai) is now a DB operation — no code change needed.
+from services.market_registry import market_registry
+market_registry.refresh()
+logger.info(f"Market registry initialized: {market_registry.get_markets()}")
+
 # ── Mount all versioned routers ───────────────────────────────────────────────
 from routes import v1_router
 app.include_router(v1_router)

methodology_kb.json

@@ -1,7 +1,7 @@
 [
   {
     "section_title": "Overview & Purpose of the Real Estate Dashboard",
-    "chunk_content": "The Joule Dynamics Real Estate Intelligence Dashboard is a live market intelligence interface designed for short-term rental property managers, investors, and hosts. It provides real-time pricing intelligence, rate change monitoring, historical trailing average benchmarks, and volatility tracking across competitive rental properties in major markets like Miami and the NYC/NJ Metro area."
+    "chunk_content": "The Joule Dynamics Real Estate Intelligence Dashboard is a live market intelligence interface designed for short-term rental property managers, investors, and hosts. It provides real-time pricing intelligence, rate change monitoring, historical trailing average benchmarks, and volatility tracking across competitive rental properties in multiple global markets. Currently tracked markets include Miami, NYC/NJ Metro, Abuja, and Lagos, with the platform designed to scale to any new market without application code changes."
   },
   {
     "section_title": "Top KPI Metric Cards",
@@ -9,7 +9,7 @@
   },
   {
     "section_title": "Global Filters & Control Bar",
-    "chunk_content": "The Global Control Bar sits above the dashboard components and allows users to slice and filter all dashboard data simultaneously:\n- Properties: A searchable multi-select checkbox dropdown to isolate one or more specific listings.\n- Market: Filter by geographic market ('Miami' or 'NYC/NJ Metro').\n- Platform: Filter by booking platform ('Airbnb' for live daily tracking, 'Vrbo' for historical data).\n- Bedrooms: Filter by property size (e.g. 1 bedroom, 2 bedrooms, etc.).\n- Status (Currently Tracked vs Untracked): 'Currently Tracked' shows actively monitored listings (is_active = true); 'Untracked' shows archived/unmonitored listings; 'All Historical' displays everything.\n- Stay Dates (Date Range Picker): Filters the data based on the stay check-in date being priced, which automatically triggers dynamic Temporal UX States across the dashboard."
+    "chunk_content": "The Global Control Bar sits above the dashboard components and allows users to slice and filter all dashboard data simultaneously:\n- Properties: A searchable multi-select checkbox dropdown to isolate one or more specific listings.\n- Market: Filter by geographic market (any of the currently tracked markets, e.g. Miami, NYC/NJ Metro, Abuja, or Lagos).\n- Platform: Filter by booking platform ('Airbnb' for live daily tracking, 'Vrbo' for historical data).\n- Bedrooms: Filter by property size (e.g. 1 bedroom, 2 bedrooms, etc.).\n- Status (Currently Tracked vs Untracked): 'Currently Tracked' shows actively monitored listings (is_active = true); 'Untracked' shows archived/unmonitored listings; 'All Historical' displays everything.\n- Stay Dates (Date Range Picker): Filters the data based on the stay check-in date being priced, which automatically triggers dynamic Temporal UX States across the dashboard."
   },
   {
     "section_title": "Temporal UX States: Present, Historical, and Future Modes",
@@ -25,11 +25,11 @@
   },
   {
     "section_title": "Market Averages Summary Chips",
-    "chunk_content": "The Market Averages bar displays regional summary chips summarizing the mean price per market (e.g., '[ Miami avg $450/night (12) ]'). The parenthesized number indicates how many distinct properties contributed to the calculation. The average is computed by taking the latest available nightly price for each property matching the active filters."
+    "chunk_content": "The Market Averages bar displays regional summary chips summarizing the mean price per market (e.g., '[ Miami avg $450/night (12) ]' or '[ Abuja avg $120/night (8) ]'). The parenthesized number indicates how many distinct properties contributed to the calculation. The average is computed by taking the latest available nightly price for each property matching the active filters. A chip appears for every tracked market that has active properties under the current filter selection."
   },
   {
     "section_title": "Property Rate Snapshot Table",
-    "chunk_content": "The Property Rate Snapshot table is the core tabular view listing all properties matching the active filter criteria. Columns include:\n- Property: Listing title with an external link icon opening the live booking page.\n- Market & Platform: Region ('Miami', 'NYC/NJ Metro') and platform ('Airbnb', 'Vrbo').\n- Beds / Rating: Bedroom count with bed icon, star rating out of 5, and total review count.\n- Stay Date: The check-in date being evaluated.\n- Rate: The nightly price in USD. If a listing is unavailable, the cell displays 'Unavailable' with a tooltip and an inline mini sparkline chart showing the last 5 known rates and last recorded date.\n- vs 7d Avg: The percentage deviation from the listing's 7-day trailing average (green for above average, red for below average)."
+    "chunk_content": "The Property Rate Snapshot table is the core tabular view listing all properties matching the active filter criteria. Columns include:\n- Property: Listing title with an external link icon opening the live booking page.\n- Market & Platform: Region (any tracked market such as 'Miami', 'NYC/NJ Metro', 'Abuja', or 'Lagos') and platform ('Airbnb', 'Vrbo').\n- Beds / Rating: Bedroom count with bed icon, star rating out of 5, and total review count.\n- Stay Date: The check-in date being evaluated.\n- Rate: The nightly price in USD. If a listing is unavailable, the cell displays 'Unavailable' with a tooltip and an inline mini sparkline chart showing the last 5 known rates and last recorded date.\n- vs 7d Avg: The percentage deviation from the listing's 7-day trailing average (green for above average, red for below average)."
   },
   {
     "section_title": "Table Availability Badges & Stale Row Dimming",
@@ -61,11 +61,11 @@
   },
   {
     "section_title": "Curated Showcase Sandbox Scope",
-    "chunk_content": "The data presented on the live dashboard represents a curated, proof-of-concept sample of properties across Miami and the NYC/NJ Metro area. It is designed to demonstrate real-time pricing intelligence, volatility alerts, and architectural data pipelines. It is not an exhaustive city-wide census. Joule Dynamics builds full-scale, bespoke data pipelines tracking thousands of listings for enterprise clients."
+    "chunk_content": "The data presented on the live dashboard represents a curated, proof-of-concept sample of properties across multiple global markets — currently Miami, NYC/NJ Metro, Abuja, and Lagos. It is designed to demonstrate real-time pricing intelligence, volatility alerts, and architectural data pipelines. It is not an exhaustive city-wide census. Joule Dynamics builds full-scale, bespoke data pipelines tracking thousands of listings for enterprise clients."
   },
   {
     "section_title": "Troubleshooting: Why is Property X Missing from the Chart, Table, or Map?",
-    "chunk_content": "If a user cannot find a specific property on the dashboard:\n1. Check Global Filters: Verify if filters for Market (e.g. Miami vs NYC), Bedrooms, Platform, or Status (Tracked vs Untracked) are excluding the listing.\n2. Stay Dates Filter: If a date range is selected, listings with no data recorded for that window may be hidden.\n3. Map Zoom & Bounds: On the map, check if the property lies outside the current zoom area or is grouped inside a numbered cluster circle.\n4. Chart Auto-Selection: On the line chart, the auto-selection algorithm selects a single optimal property by default. Use the property dropdown above the chart to explicitly select the desired listing."
+    "chunk_content": "If a user cannot find a specific property on the dashboard:\n1. Check Global Filters: Verify if filters for Market (check that you have selected the correct market name), Bedrooms, Platform, or Status (Tracked vs Untracked) are excluding the listing.\n2. Stay Dates Filter: If a date range is selected, listings with no data recorded for that window may be hidden.\n3. Map Zoom & Bounds: On the map, check if the property lies outside the current zoom area or is grouped inside a numbered cluster circle.\n4. Chart Auto-Selection: On the line chart, the auto-selection algorithm selects a single optimal property by default. Use the property dropdown above the chart to explicitly select the desired listing."
   },
   {
     "section_title": "Troubleshooting: Why Does the Table Say 'Was Available' or 'Pre-open'?",
@@ -126,5 +126,9 @@
   {
     "section_title": "Managing Multiple Properties Easily",
     "chunk_content": "If you manage many properties, it can be exhausting to check every single listing one by one to see how they are doing. We solve this by building a single, simple dashboard that puts all your properties in one place. You can see your entire portfolio at a glance, instantly spotting which homes are doing well and which ones need your attention today, saving you hours of clicking around."
+  },
+  {
+    "section_title": "Multi-Market Global Coverage & Dynamic Market Registry",
+    "chunk_content": "The Joule Dynamics dashboard is built to support multiple real estate markets simultaneously across any geography. The list of active markets is dynamic and driven by the database — it is not hardcoded in the application. Currently tracked markets include Miami, NYC/NJ Metro, Abuja, and Lagos, but new markets can be onboarded by the engineering team without modifying any application code. Users can ask 'What markets do you track?' or 'Which cities are available?' at any time to receive the authoritative live list directly from the database. Each market operates with independent property tracking, scraping schedules, and pricing benchmarks."
   }
 ]

routes/v1/real_estate.py

@@ -216,12 +216,12 @@ async def handle_real_estate_chat_stream(payload: ChatRequest, request: Request)
 async def get_starter_prompts():
     return {
         "starters": [
-            "What's today's biggest rate spike?",
+            "What markets are you currently tracking?",
+            "Which properties have the biggest rate spike today?",
             "What does the 7-day trailing average mean?",
-            "Which Miami properties are unavailable right now?",
-            "Is NYC/NJ Metro trending up or down this week?",
-            "How often is listing data refreshed?",
-            "Show me the most volatile properties in Miami.",
+            "Show me the most volatile properties across all markets.",
+            "Are there any 25%+ price spikes this week?",
+            "What's the average nightly rate in Abuja right now?",
             "Compare the top 3 available Airbnb properties.",
         ]
     }

services/agent_loop.py

@@ -151,7 +151,7 @@ _REPLY_GREETING = (
 )
 _REPLY_FALLBACK = (
     "I was unable to retrieve the data needed to answer your question. "
-    "Please try rephrasing, or ask about a specific market (Miami or NYC/NJ Metro)."
+    "Please try rephrasing, or ask 'What markets do you track?' to see all available options."
 )
 
 
@@ -254,8 +254,8 @@ async def classify_query(user_query: str) -> tuple[str, list[str]]:
 ACTION_RESOLVER_PROMPT = """You are an interactive action generator for Joule Dynamics Real Estate Intelligence.
 Given the user's query and the assistant's final response, determine 0 to 4 short, highly relevant follow-up actions or clarifying choices for the user.
 Guidelines:
-- If the assistant asked a clarifying question (e.g. which market or date), provide those exact choices (e.g. ["Miami", "NYC/NJ Metro"]).
-- If the assistant provided market/price analysis, suggest logical next-step actions (e.g. ["Compare with Miami", "See Rate Volatility", "Generate Download Report"]).
+- If the assistant asked a clarifying question (e.g. which market or date), provide those exact choices using the actual tracked market names available in the conversation context.
+- If the assistant provided market/price analysis, suggest logical next-step actions (e.g. ["Compare market averages", "See Rate Volatility", "Generate Download Report"]).
 - If the conversation is complete, a simple greeting, or no follow-up is genuinely useful, return an empty array actions: [].
 - You must return ONLY via the suggest_actions tool call. Do not force suggestions if none are genuinely helpful."""
 
@@ -769,8 +769,10 @@ async def stream_chat_message(
         if classification in ("PATH_B", "BOTH", "COMMERCIAL_HANDOFF"):
             rag_chunks = await search_methodology_rag(user_query)
 
-        # STEP 3: Messages
-        system_prompt = build_system_prompt(classification)
+        # STEP 3: Messages — build system prompt with live market list
+        from services.market_registry import market_registry
+        current_markets = market_registry.get_markets()
+        system_prompt = build_system_prompt(classification, markets=current_markets)
         messages: list[dict] = [{"role": "system", "content": system_prompt}]
         messages.extend(get_context_window(session_id))
         user_msg = f"User Context Filters: {json.dumps(session_context)}\nUser Query: {user_query}"

services/appwrite_service.py

@@ -21,7 +21,7 @@ client.set_key(APP_WRITE_API_KEY)
 
 storage = Storage(client)
 
-async def upload_document_to_appwrite(content: str, format: str) -> str:
+async def upload_document_to_appwrite(content: str, format: str) -> dict:
     """
     Uploads a generated document to Appwrite storage and returns a view/download URL.
     """

services/market_registry.py

@@ -0,0 +1,139 @@
+"""
+services/market_registry.py
+──────────────────────────────
+Dynamic Market Registry — the authoritative source of tracked markets.
+
+Fetches the live market list from Supabase at startup (and on demand) and
+caches it in-memory. All downstream consumers (prompts, tools, fallback
+strings) read from this registry rather than hardcoded strings.
+
+Benefit: Adding a new market (e.g. Dubai) is now a database operation,
+not a code change. No restart required — the next cache refresh picks it up.
+
+SQL return shape (from public.get_tracked_markets):
+    TABLE(market character varying, active_properties bigint)
+"""
+
+import time
+from services.observability import setup_logger
+
+logger = setup_logger(__name__)
+
+# Safe bootstrap fallback used only when DB is unreachable during initial load.
+# This list is NEVER used as the authoritative market list in normal operation.
+_BOOTSTRAP_FALLBACK: list[str] = ["Miami", "NYC/NJ Metro"]
+
+
+class MarketRegistry:
+    """
+    Singleton holding the live market list fetched from Supabase.
+
+    Usage (anywhere in the codebase):
+        from services.market_registry import market_registry
+
+        markets = market_registry.get_markets()          # sync, always returns list
+        market_registry.refresh()                        # sync DB fetch (call at startup)
+        desc    = market_registry.get_formatted()        # "'Miami', 'NYC/NJ Metro', 'Abuja', 'Lagos'"
+    """
+
+    def __init__(self) -> None:
+        self._markets: list[str] = list(_BOOTSTRAP_FALLBACK)
+        self._last_fetched: float = 0.0
+        self._initialized: bool = False
+
+    # ── Public API ─────────────────────────────────────────────────────────────
+
+    def get_markets(self) -> list[str]:
+        """
+        Return the cached market list synchronously.
+        Never blocks on a network call — always instant.
+        Falls back to the bootstrap list before first successful refresh.
+        """
+        return list(self._markets)
+
+    def get_formatted(self, separator: str = ", ", quote: bool = True) -> str:
+        """
+        Return market names as a formatted inline string.
+        Default: \"'Miami', 'NYC/NJ Metro', 'Abuja', 'Lagos'\"
+        """
+        markets = self.get_markets()
+        if quote:
+            return separator.join(f"'{m}'" for m in markets)
+        return separator.join(markets)
+
+    def refresh(self) -> list[str]:
+        """
+        Synchronously fetch the authoritative market list from Supabase and
+        update the in-memory cache. Safe to call at startup (sync context) or
+        from a background coroutine via asyncio executor.
+
+        Returns the updated market list. On failure, retains the last known
+        cache (graceful degradation — never crashes the application).
+        """
+        try:
+            # Import lazily to avoid circular import at module load time
+            from services.supabase_service import supabase as _supabase
+
+            res = _supabase.rpc("get_tracked_markets", {}).execute()
+            raw: list[dict] = res.data or []
+
+            # SQL returns: TABLE(market character varying, active_properties bigint)
+            markets: list[str] = [
+                row["market"].strip()
+                for row in raw
+                if isinstance(row, dict)
+                and isinstance(row.get("market"), str)
+                and row["market"].strip()
+            ]
+
+            if markets:
+                self._markets = markets
+                self._last_fetched = time.time()
+                self._initialized = True
+                logger.info(f"[market_registry] Refreshed — active markets: {markets}")
+                # Invalidate the tool embedding cache so new market names are
+                # reflected in semantic tool discovery on the next query.
+                self._invalidate_tool_embeddings()
+            else:
+                logger.warning(
+                    "[market_registry] RPC returned no markets — retaining last known list."
+                )
+                if not self._initialized:
+                    self._markets = list(_BOOTSTRAP_FALLBACK)
+                    self._initialized = True
+
+        except Exception as exc:
+            logger.error(f"[market_registry] Supabase fetch failed: {exc}")
+            if not self._initialized:
+                self._markets = list(_BOOTSTRAP_FALLBACK)
+                self._initialized = True
+                logger.warning(
+                    f"[market_registry] Using bootstrap fallback: {self._markets}"
+                )
+
+        return list(self._markets)
+
+    def is_tracked(self, market: str) -> bool:
+        """Case-insensitive check whether a market name is currently tracked."""
+        market_lower = market.strip().lower()
+        return any(m.lower() == market_lower for m in self._markets)
+
+    # ── Internal ────────────────────────────────────────────────────────────────
+
+    def _invalidate_tool_embeddings(self) -> None:
+        """
+        Reset the tool embedding cache in tools.py so that updated market
+        descriptions (which now reflect the new market list) are re-embedded
+        on the next tool discovery call.
+        """
+        try:
+            from services import tools as _tools
+            _tools._TOOL_EMBEDDINGS = None
+            logger.info("[market_registry] Tool embedding cache invalidated — will rebuild on next query.")
+        except Exception as exc:
+            logger.warning(f"[market_registry] Could not invalidate tool embeddings: {exc}")
+
+
+# ── Module-level singleton ────────────────────────────────────────────────────
+# Import this instance everywhere — never instantiate MarketRegistry directly.
+market_registry = MarketRegistry()

services/prompts.py

@@ -39,14 +39,15 @@ INSTRUCTIONS FOR tool_categories:
 
 # ─── SYNTHESIS PROMPT — CORE (always included) ────────────────────────────────
 
-_PROMPT_CORE = """You are Pulse AI, a Real Estate Intelligence Assistant for Joule Dynamics.
+_PROMPT_CORE = """\
+You are Pulse AI, a Real Estate Intelligence Assistant for Joule Dynamics.
 You provide precise data analysis to real estate investors and property managers reviewing short-term rental market performance. If asked about your identity or underlying model, identify yourself as Pulse AI, developed for Joule Dynamics.
 
 IMMUTABLE SYSTEM BOUNDARIES & HARD FACTS:
 1. SANDBOX SCOPE: The data you have access to is a proof-of-concept showcase tracking a curated sample of properties. It is NOT a complete city-wide market census. You must clarify this if a user attempts to use this data for macro-market investment decisions.
-2. TRACKED MARKETS: You ONLY track two markets: 'NYC/NJ Metro' and 'Miami'.
+2. TRACKED MARKETS: The currently active tracked markets are: {market_list}. If you are ever uncertain which markets are available, call get_tracked_markets first — the database is the source of truth.
 3. TRACKED PLATFORMS: You ONLY track 'Airbnb' (Active daily tracking) and 'Vrbo' (Historical data only).
-4. ABSOLUTE FORBIDDEN ENTITIES: You must NEVER list, suggest, or mention any other cities or other booking platforms.
+4. MARKET ACCURACY: Do NOT invent or assume market names. If a user asks about a city that may not be tracked, call get_tracked_markets to verify before responding. Never speculate about data you don't have.
 5. ZERO FABRICATION: Every single price, rate change percentage, property count, and availability status MUST come directly from a returned tool output.
 
 OPERATIONAL RULES:
@@ -95,7 +96,7 @@ DASHBOARD UI & VISUAL GUIDANCE: When a user asks questions about what they see o
 - Temporal UX States & Badges: Explain that changing the Stay Dates filter triggers Present Mode ('YES'/'NO', relative times, 'STALE' warning), Historical Mode (past stay dates: 'Was Available'/'Was Booked', recorded dates), or Future Mode ('Pre-open'/'Pre-booked', projected anomalies).
 - Property Rate Table: Clarify percentage deviations vs 7d avg, inline mini sparklines on unavailable properties showing the last 5 known prices, and 60% row opacity dimming for stale data older than 24 hours.
 - Interactive Map: Explain color-coded pins (green=available, red=booked/unavailable, grey=no rate), circular numbered cluster badges, and popup cards.
-- Troubleshooting Missing Listings: Guide the user to check active Global Filters (Market, Bedrooms, Status, Stay Date range) or map zoom bounds.
+- Troubleshooting Missing Listings: Guide the user to check active Global Filters (Market — make sure the correct market name is selected, Bedrooms, Status, Stay Date range) or map zoom bounds.
 """
 
 # ─── RECAP EXTENSION (PATH_B / BOTH) ─────────────────────────────────────────
@@ -120,12 +121,25 @@ When a user asks about custom builds, deploying this system for their business,
 # ─── COMPOSER ─────────────────────────────────────────────────────────────────
 
 
-def build_system_prompt(classification: str) -> str:
+def build_system_prompt(classification: str, markets: list | None = None) -> str:
     """
     Compose the system prompt from core + relevant extension blocks only.
     Saves 600-900 tokens per PATH_A turn vs. always sending the full monolith.
+
+    Args:
+        classification: Router classification string (PATH_A, PATH_B, etc.)
+        markets: Optional pre-fetched market list. If None, reads from market_registry.
+                 Always pass this from agent_loop to avoid redundant registry reads.
     """
-    prompt = _PROMPT_CORE
+    # Resolve the current tracked market list dynamically
+    if markets is None:
+        from services.market_registry import market_registry
+        markets = market_registry.get_markets()
+
+    market_list = ", ".join(f"'{m}'" for m in markets) if markets else "use get_tracked_markets to retrieve the current list"
+
+    # Inject the live market list into the core prompt template
+    prompt = _PROMPT_CORE.format(market_list=market_list)
 
     if classification in ("PATH_A", "BOTH"):
         prompt += _PROMPT_PATH_A

services/rate_limiter.py

@@ -9,9 +9,27 @@ class SessionRateLimiter:
         self.requests = defaultdict(list)
         self.daily_counts = defaultdict(lambda: {"count": 0, "reset_at": 0})
 
+    def evict_stale(self, max_idle_seconds: int = 90_000) -> None:
+        """
+        Evict sessions that have been idle for longer than max_idle_seconds
+        (~25 hours) from both stores to prevent unbounded dict growth.
+        Called on every rate-limit check — O(n) but cheap for typical loads.
+        """
+        now = time.time()
+        cutoff = now - max_idle_seconds
+        stale_req = [sid for sid, times in self.requests.items() if not times or max(times) < cutoff]
+        stale_daily = [sid for sid, data in self.daily_counts.items() if data["reset_at"] < cutoff]
+        for sid in stale_req:
+            del self.requests[sid]
+        for sid in stale_daily:
+            del self.daily_counts[sid]
+
     def check_rate_limit(self, client_id: str):
         now = time.time()
-        
+
+        # Evict sessions idle for >25 hours to prevent unbounded memory growth
+        self.evict_stale()
+
         # Check 24-hour Daily Limit
         daily = self.daily_counts[client_id]
         if now > daily["reset_at"]:

services/supabase_service.py

@@ -63,7 +63,9 @@ async def execute_tool_rpc(func_name: str, args: dict) -> dict:
 
     # ── 3. get_market_snapshot ──
     elif func_name == "get_market_snapshot":
-        market = args.get("p_market") or args.get("market") or "Miami"
+        market = args.get("p_market") or args.get("market")
+        if not market:
+            return {"status": "error", "message": "p_market is required for get_market_snapshot. Call get_tracked_markets to see available markets."}
         start = args.get("p_start_date") or args.get("start_date")
         end = args.get("p_end_date") or args.get("end_date")
         if not start or not end:
@@ -85,7 +87,9 @@ async def execute_tool_rpc(func_name: str, args: dict) -> dict:
 
     # ── 4. get_market_trend ──
     elif func_name == "get_market_trend":
-        market = args.get("p_market") or args.get("market") or "Miami"
+        market = args.get("p_market") or args.get("market")
+        if not market:
+            return {"status": "error", "message": "p_market is required for get_market_trend. Call get_tracked_markets to see available markets."}
         days = _clamp(args.get("p_days") or args.get("days"), 7, 90, default=14)
         plat = args.get("p_platform") or args.get("platform")
         is_act = args.get("p_is_active") if "p_is_active" in args else True

services/tool_compressor.py

@@ -162,12 +162,16 @@ def geocode_address_handler(address: str) -> dict:
         return {"status": "error", "message": "No address was provided to geocode."}
 
     url = "https://api.mapbox.com/search/geocode/v6/forward"
-    params = {
+    params: dict = {
         "q": address.strip(),
         "access_token": MAPBOX_ACCESS_TOKEN,
-        "country": "US",
         "limit": 1,
     }
+    # Optional country restriction (configurable via GEOCODE_COUNTRY_FILTER env var).
+    # Left empty by default so all tracked markets (including Nigeria) are geocodable.
+    from config import GEOCODE_COUNTRY_FILTER
+    if GEOCODE_COUNTRY_FILTER:
+        params["country"] = GEOCODE_COUNTRY_FILTER
 
     try:
         response = requests.get(url, params=params, timeout=6)

services/tools.py

@@ -10,6 +10,23 @@ Implements Hierarchical Dynamic Tool Discovery / Schema Gating:
 from typing import List, Dict, Any, Optional
 import numpy as np
 
+
+def _market_desc() -> str:
+    """
+    Returns a live, formatted string of currently tracked market names.
+    Called inline within tool description strings so the LLM always sees the
+    current market list when tool schemas are built for a request.
+    Example output: "'Miami', 'NYC/NJ Metro', 'Abuja', 'Lagos'"
+    """
+    try:
+        from services.market_registry import market_registry
+        markets = market_registry.get_markets()
+        if markets:
+            return ", ".join(f"'{m}'" for m in markets)
+    except Exception:
+        pass
+    return "any tracked market (call get_tracked_markets for the live list)"
+
 # ── 1. UNIVERSAL TOOLS (Always attached to tool payloads) ──
 
 SUGGEST_ACTIONS_TOOL = {
@@ -84,7 +101,7 @@ REAL_ESTATE_TOOLS = [
                 "properties": {
                     "p_market": {
                         "type": "string",
-                        "description": "Optional market region filter ('Miami' or 'NYC/NJ Metro')",
+                        "description": f"Optional market region filter. Currently tracked: {_market_desc()}",
                     },
                     "p_platform": {
                         "type": "string",
@@ -126,7 +143,7 @@ REAL_ESTATE_TOOLS = [
                 "properties": {
                     "market_param": {
                         "type": "string",
-                        "description": "Market region name: 'Miami' or 'NYC/NJ Metro'",
+                        "description": f"Market region name. Currently tracked markets: {_market_desc()}",
                     }
                 },
                 "required": ["market_param"],
@@ -137,13 +154,13 @@ REAL_ESTATE_TOOLS = [
         "type": "function",
         "function": {
             "name": "get_market_snapshot",
-            "description": "Fetch a comprehensive single-day snapshot for a market (active property count, average nightly rate, min rate, max rate, availability rate %, and rate spike event count). Use when the user asks for a daily market overview, daily summary, market condition, or specific date performance in Miami or NYC.",
+            "description": f"Fetch a comprehensive single-day snapshot for a market (active property count, average nightly rate, min rate, max rate, availability rate %, and rate spike event count). Use when the user asks for a daily market overview, daily summary, market condition, or specific date performance in any tracked market.",
             "parameters": {
                 "type": "object",
                 "properties": {
                     "p_market": {
                         "type": "string",
-                        "description": "Market region: 'Miami' or 'NYC/NJ Metro'",
+                        "description": f"Market region. Currently tracked markets: {_market_desc()}",
                     },
                     "p_start_date": {
                         "type": "string",
@@ -162,13 +179,13 @@ REAL_ESTATE_TOOLS = [
         "type": "function",
         "function": {
             "name": "get_market_trend",
-            "description": "Fetch historical daily average rate trends for a market over a specified number of days (up to 90 days). Use when the user asks how rates have changed over time, weekly/monthly trajectories, or market direction in Miami or NYC.",
+            "description": f"Fetch historical daily average rate trends for a market over a specified number of days (up to 90 days). Use when the user asks how rates have changed over time, weekly/monthly trajectories, or market direction in any tracked market.",
             "parameters": {
                 "type": "object",
                 "properties": {
                     "p_market": {
                         "type": "string",
-                        "description": "Market region: 'Miami' or 'NYC/NJ Metro'",
+                        "description": f"Market region. Currently tracked markets: {_market_desc()}",
                     },
                     "p_days": {
                         "type": "integer",
@@ -207,7 +224,7 @@ REAL_ESTATE_TOOLS = [
                     },
                     "p_market": {
                         "type": "string",
-                        "description": "Optional market filter ('Miami' or 'NYC/NJ Metro')",
+                        "description": f"Optional market filter. Currently tracked: {_market_desc()}",
                     },
                     "p_limit": {
                         "type": "integer",
@@ -258,7 +275,7 @@ REAL_ESTATE_TOOLS = [
                 "properties": {
                     "p_market": {
                         "type": "string",
-                        "description": "Optional market filter ('Miami' or 'NYC/NJ Metro')",
+                        "description": f"Optional market filter. Currently tracked: {_market_desc()}",
                     },
                     "p_days": {
                         "type": "integer",
@@ -377,7 +394,7 @@ REAL_ESTATE_TOOLS = [
         "type": "function",
         "function": {
             "name": "search_properties",
-            "description": "Search and filter tracked properties by market ('Miami' or 'NYC/NJ Metro'), bedroom count, platform ('airbnb' or 'vrbo'), availability status, title substring, and ranked slices.",
+            "description": f"Search and filter tracked properties by market (any tracked region), bedroom count, platform ('airbnb' or 'vrbo'), availability status, title substring, and ranked slices. Currently tracked markets: {_market_desc()}",
             "parameters": {
                 "type": "object",
                 "properties": {
@@ -387,7 +404,7 @@ REAL_ESTATE_TOOLS = [
                     },
                     "p_market": {
                         "type": "string",
-                        "description": "Optional market filter ('Miami' or 'NYC/NJ Metro')",
+                        "description": f"Optional market filter. Currently tracked: {_market_desc()}",
                     },
                     "p_platform": {
                         "type": "string",
@@ -428,13 +445,13 @@ REAL_ESTATE_TOOLS = [
         "type": "function",
         "function": {
             "name": "get_availability_rate",
-            "description": "Fetch availability percentage and booked vs available listing counts for a market or platform. Use when user asks about occupancy rates, calendar status, or vacancy in Miami or NYC.",
+            "description": f"Fetch availability percentage and booked vs available listing counts for a market or platform. Use when user asks about occupancy rates, calendar status, or vacancy in any tracked market.",
             "parameters": {
                 "type": "object",
                 "properties": {
                     "p_market": {
                         "type": "string",
-                        "description": "Optional market filter ('Miami' or 'NYC/NJ Metro')",
+                        "description": f"Optional market filter. Currently tracked: {_market_desc()}",
                     },
                     "p_platform": {
                         "type": "string",
@@ -520,7 +537,7 @@ REAL_ESTATE_TOOLS = [
         "type": "function",
         "function": {
             "name": "get_tracked_markets",
-            "description": "Fetch a list of all active metropolitan real estate markets currently tracked by the system (Miami, NYC/NJ Metro) with property counts.",
+            "description": f"Fetch a list of all active metropolitan real estate markets currently tracked by the system, with property counts per market. Currently includes: {_market_desc()}.",
             "parameters": {
                 "type": "object",
                 "properties": {
@@ -571,25 +588,25 @@ TOOL_REGISTRY: List[Dict[str, Any]] = [
     {
         "name": "get_market_averages",
         "category": "MARKET",
-        "retrieval_description": "Average nightly rate and price baselines for Miami or NYC/NJ Metro over 7-day, 14-day, or 30-day periods, market benchmark pricing.",
+        "retrieval_description": "Average nightly rate and price baselines for any tracked market region over 7-day, 14-day, or 30-day periods, market benchmark pricing.",
         "schema": REAL_ESTATE_TOOLS[1],
     },
     {
         "name": "get_market_snapshot",
         "category": "MARKET",
-        "retrieval_description": "Daily overview snapshot of market performance, market condition in Miami or NYC, nightly rates range, minimum maximum rates, daily summary and availability.",
+        "retrieval_description": "Daily overview snapshot of market performance, market condition in any tracked city or region, nightly rates range, minimum maximum rates, daily summary and availability.",
         "schema": REAL_ESTATE_TOOLS[2],
     },
     {
         "name": "get_market_trend",
         "category": "MARKET",
-        "retrieval_description": "Historical pricing trend direction, rising or falling rates over time, week-over-week rate trajectory in Miami or NYC/NJ Metro.",
+        "retrieval_description": "Historical pricing trend direction, rising or falling rates over time, week-over-week rate trajectory in any tracked market region.",
         "schema": REAL_ESTATE_TOOLS[3],
     },
     {
         "name": "get_spike_alerts",
         "category": "ANOMALY",
-        "retrieval_description": "Sudden sharp price jumps, 25% plus rate increases, price spikes, surge pricing alerts, unseasonal rate surges in Miami or NYC, ranked slices.",
+        "retrieval_description": "Sudden sharp price jumps, 25% plus rate increases, price spikes, surge pricing alerts, unseasonal rate surges in any tracked market, ranked slices.",
         "schema": REAL_ESTATE_TOOLS[4],
     },
     {
@@ -631,13 +648,13 @@ TOOL_REGISTRY: List[Dict[str, Any]] = [
     {
         "name": "search_properties",
         "category": "PROPERTY",
-        "retrieval_description": "Find, list, and filter property listings by bedroom count, price range, market (Miami, NYC), availability status, listing name, or ranked slices.",
+        "retrieval_description": "Find, list, and filter property listings by bedroom count, price range, market region, availability status, listing name, or ranked slices.",
         "schema": REAL_ESTATE_TOOLS[11],
     },
     {
         "name": "get_availability_rate",
         "category": "PROPERTY",
-        "retrieval_description": "Percentage of units booked versus available, occupancy rates, reservation calendar status in Miami or NYC.",
+        "retrieval_description": "Percentage of units booked versus available, occupancy rates, reservation calendar status in any tracked market or city.",
         "schema": REAL_ESTATE_TOOLS[12],
     },
     {
@@ -661,7 +678,7 @@ TOOL_REGISTRY: List[Dict[str, Any]] = [
     {
         "name": "get_tracked_markets",
         "category": "MARKET",
-        "retrieval_description": "List all cities and regions currently supported and monitored in the database (NYC/NJ Metro, Miami).",
+        "retrieval_description": "List all cities and regions currently supported and monitored in the database, fetch the live market registry.",
         "schema": REAL_ESTATE_TOOLS[16],
     },
     {
@@ -757,6 +774,12 @@ def discover_tools(
     return results
 
 
+def invalidate_tool_embeddings() -> None:
+    """Public API to reset the tool embedding cache (e.g. called after market registry refresh)."""
+    global _TOOL_EMBEDDINGS
+    _TOOL_EMBEDDINGS = None
+
+
 # ── 5. BACKWARDS COMPATIBLE SELECTOR ──
 
 def select_tools(user_query: str) -> List[Dict[str, Any]]:

unified_ingest.py

@@ -132,7 +132,7 @@ def ensure_ingested():
         try:
             with open("section_titles.json", "r", encoding="utf-8") as f:
                 saved_titles = json.load(f)
-            if saved_titles != section_titles or stats["added"] > 0 or stats["deleted"] > 0:
+            if saved_titles != section_titles or stats["added"] > 0 or stats["deleted"] > 0 or stats["updated"] > 0:
                 regenerate_titles = True
         except Exception:
             regenerate_titles = True