feat(chat): add mobile city context

Verification: backend prompt-cache, async-offload, and geocoding unit tests; backend typecheck.

Author: undivisible

backend/tests/unit/test_chat_async_offload.py

@@ -49,7 +49,9 @@ async def _collect_agentic_chunks(producer, callback_data=None):
         stack.enter_context(patch.object(agentic, 'get_user_timezone', lambda _uid: 'UTC'))
         stack.enter_context(patch.object(agentic, '_get_agentic_qa_prompt', lambda *_args, **_kwargs: 'SYSTEM'))
         stack.enter_context(patch.object(agentic, 'load_app_tools', lambda _uid: []))
-        stack.enter_context(patch.object(agentic, 'get_current_datetime_block', lambda _uid, tz=None: ''))
+        stack.enter_context(
+            patch.object(agentic, 'get_current_datetime_block', lambda _uid, tz=None, location=None: '')
+        )
         stack.enter_context(patch.object(agentic, '_convert_tools', lambda _core, _app: ([], {})))
         stack.enter_context(patch.object(agentic, '_messages_to_anthropic', lambda _messages: []))
         stack.enter_context(patch.object(agentic, '_inject_current_datetime', lambda messages, _block: messages))
@@ -84,6 +86,21 @@ def fake_is_file_question(question):
     assert ran_on['thread'] is not loop_thread, "retrieve_is_file_question must run off the event-loop thread"
 
 
+async def test_mobile_city_context_uses_only_mobile_platforms():
+    async def fake_run_blocking(_executor, _function, _uid):
+        return {'latitude': 40.7128, 'longitude': -74.006}
+
+    async def fake_city(latitude, longitude):
+        assert (latitude, longitude) == (40.7128, -74.006)
+        return 'New York, New York, United States'
+
+    with patch.object(agentic, 'run_blocking', fake_run_blocking), patch(
+        'utils.conversations.location.async_get_google_maps_city', fake_city
+    ):
+        assert await agentic._get_mobile_city('uid1', 'ios') == 'New York, New York, United States'
+        assert await agentic._get_mobile_city('uid1', 'macos') is None
+
+
 def _file_chat_tool_for_stream_test():
     """Create a FileChatTool without its production Firestore constructor for a hermetic stream test."""
     tool = object.__new__(chat_file.FileChatTool)
@@ -226,7 +243,7 @@ async def fake_agent_stream(
     with patch.object(agentic, 'get_user_timezone', rec('tz', 'UTC')), patch.object(
         agentic, '_get_agentic_qa_prompt', rec('prompt', 'SYSTEM')
     ), patch.object(agentic, 'load_app_tools', rec('app_tools', [])), patch.object(
-        agentic, 'get_current_datetime_block', lambda uid, tz=None: ''
+        agentic, 'get_current_datetime_block', lambda uid, tz=None, location=None: ''
     ), patch.object(
         agentic, '_convert_tools', lambda core, app: ([], {})
     ), patch.object(

backend/tests/unit/test_prompt_cache_integration.py

@@ -991,6 +991,19 @@ def test_current_datetime_block_carries_live_time():
     assert "2024-01-19" in block, "Datetime block should contain the live date"
 
 
+def test_current_datetime_block_includes_city_without_coordinates():
+    chat_mod = _get_chat_module()
+    _set_user(chat_mod, "Alice", "America/New_York")
+
+    block = chat_mod.get_current_datetime_block(
+        "uid_alice", tz="America/New_York", location="New York, New York, United States"
+    )
+
+    assert "Current city-level location: New York, New York, United States" in block
+    assert "latitude" not in block.lower()
+    assert "longitude" not in block.lower()
+
+
 def test_datetime_injected_into_user_turn_not_system():
     """
     _inject_current_datetime must attach the datetime block to the latest user turn so the

backend/utils/conversations/location.py

@@ -142,3 +142,42 @@ async def async_resolve_geolocation(geolocation: Optional[Geolocation]) -> Optio
         logger.error('async_resolve_geolocation enrichment failed: %s', e)
         return geolocation
     return enriched or geolocation
+
+
+async def async_get_google_maps_city(latitude: float, longitude: float) -> Optional[str]:
+    cache_key = f"geocode-city:{latitude:.3f},{longitude:.3f}"
+    try:
+        cached = r.get(cache_key)
+        if cached:
+            return cached.decode() if isinstance(cached, bytes) else str(cached)
+    except Exception as error:
+        logger.warning('Failed to read city geocode cache error_type=%s', type(error).__name__)
+
+    key = os.getenv('GOOGLE_MAPS_API_KEY')
+    try:
+        async with get_maps_semaphore():
+            response = await get_maps_client().get(
+                "https://maps.googleapis.com/maps/api/geocode/json",
+                params={"latlng": f"{latitude},{longitude}", "key": key},
+            )
+        data = response.json()
+    except Exception as error:
+        logger.error('City geocoding failed error_type=%s', type(error).__name__)
+        return None
+
+    if data.get('status') != 'OK' or not data.get('results'):
+        return None
+    parts = {}
+    for component in data['results'][0].get('address_components') or []:
+        for component_type in component.get('types') or []:
+            if component_type in {'locality', 'postal_town', 'administrative_area_level_1', 'country'}:
+                parts.setdefault(component_type, component.get('long_name'))
+    city = parts.get('locality') or parts.get('postal_town')
+    if not city:
+        return None
+    result = ', '.join(part for part in (city, parts.get('administrative_area_level_1'), parts.get('country')) if part)
+    try:
+        r.set(cache_key, result, ex=172800)
+    except Exception as error:
+        logger.warning('Failed to cache city geocode error_type=%s', type(error).__name__)
+    return result

backend/utils/llm/chat.py

@@ -480,7 +480,7 @@ def get_user_timezone(uid: str) -> str:
         return "UTC"
 
 
-def get_current_datetime_block(uid: str, tz: Optional[str] = None) -> str:
+def get_current_datetime_block(uid: str, tz: Optional[str] = None, location: Optional[str] = None) -> str:
     """Build the current-datetime block injected into the user turn.
 
     Kept out of the cached system prefix so the cached bytes stay stable across requests
@@ -497,10 +497,12 @@ def get_current_datetime_block(uid: str, tz: Optional[str] = None) -> str:
         tz = "UTC"
     current_datetime_str = current_datetime_user.strftime('%Y-%m-%d %H:%M:%S')
     current_datetime_iso = current_datetime_user.isoformat()
+    location_line = f"Current city-level location: {location}\n" if location else ""
     return (
         "<current_datetime>\n"
         f"Current date time in {tz}: {current_datetime_str}\n"
         f"Current date time ISO format: {current_datetime_iso}\n"
+        f"{location_line}"
         "</current_datetime>"
     )
 

backend/utils/retrieval/agentic.py

@@ -425,6 +425,24 @@ def _inject_current_datetime(anthropic_messages: list, datetime_block: str) -> l
     return anthropic_messages
 
 
+async def _get_mobile_city(uid: str, platform: Optional[str]) -> Optional[str]:
+    if platform is None or platform.strip().lower() not in {'ios', 'android'}:
+        return None
+    try:
+        from database.redis_db import get_cached_user_geolocation
+        from utils.conversations.location import async_get_google_maps_city
+
+        geolocation = await run_blocking(db_executor, get_cached_user_geolocation, uid)
+        if not geolocation:
+            return None
+        return await async_get_google_maps_city(float(geolocation['latitude']), float(geolocation['longitude']))
+    except (KeyError, TypeError, ValueError):
+        return None
+    except Exception as error:
+        logger.warning('Mobile city context unavailable error_type=%s', type(error).__name__)
+        return None
+
+
 # ---------------------------------------------------------------------------
 # Core Anthropic agent streaming loop
 # ---------------------------------------------------------------------------
@@ -685,6 +703,7 @@ async def execute_agentic_chat_stream(
         # so they share the first-event deadline instead of leaving the SSE body silent.
         async with asyncio.timeout(AGENT_STREAM_FIRST_EVENT_TIMEOUT_SECONDS):
             tz = await run_blocking(db_executor, get_user_timezone, uid)
+            city = await _get_mobile_city(uid, platform)
             system_prompt = await run_blocking(
                 db_executor, _get_agentic_qa_prompt, uid, app, messages, context=context, tz=tz, platform=platform
             )
@@ -755,7 +774,9 @@ async def execute_agentic_chat_stream(
     # Convert messages to Anthropic format. The current datetime is injected into the user
     # turn (not the system prompt) so the cache_control system prefix stays byte-stable.
     anthropic_messages = _messages_to_anthropic(messages)
-    anthropic_messages = _inject_current_datetime(anthropic_messages, get_current_datetime_block(uid, tz=tz))
+    anthropic_messages = _inject_current_datetime(
+        anthropic_messages, get_current_datetime_block(uid, tz=tz, location=city)
+    )
 
     callback = AsyncStreamingCallback()