fix(router): architectural fix for multi-turn conversational continuations

- Pass recent history to classify_query for context-aware routing
- Add multi-turn continuation rules to ROUTER_PROMPT
- Add deterministic _rescue_classification guardrail for active sessions
- Increase max_tokens in router (1500) and agent loop (3500) to prevent thinking tag cutoffs
- Add unit test coverage for multi-turn and continuation classification

services/agent_loop.py

@@ -115,7 +115,7 @@ async def resolve_suggested_actions(user_query: str, assistant_reply: str) -> li
                 messages=messages,
                 tools=[SUGGEST_ACTIONS_TOOL],
                 tool_choice={"type": "function", "function": {"name": "suggest_actions"}},
-                max_tokens=250,
+                max_tokens=500,
                 temperature=0.0,
             )
             actions = _extract_suggested_actions_from_response(res)
@@ -157,7 +157,7 @@ async def _call_retrieval_model(messages: list[dict], active_tools: list, round_
                 messages=messages,
                 tools=active_tools,
                 tool_choice="auto",
-                max_tokens=2500,
+                max_tokens=3500,
                 temperature=0.2,
             )
             return res.choices[0].message
@@ -195,7 +195,7 @@ async def _synthesize_markdown(messages: list[dict]) -> str:
                 messages=synth_messages,
                 tools=None,
                 tool_choice="none",
-                max_tokens=2500,
+                max_tokens=3500,
                 temperature=0.2,
             )
             raw = res.choices[0].message.content or ""
@@ -252,7 +252,7 @@ async def _stream_synthesis(synth_messages: list[dict], loop: asyncio.AbstractEv
                     tools=None,
                     tool_choice="none",
                     temperature=0.2,
-                    max_tokens=2500,
+                    max_tokens=3500,
                     stream=True,
                 ),
             )
@@ -389,7 +389,8 @@ async def process_chat_message(
     with propagate_attributes(session_id=session_id, tags=["real-estate-chat"]):
         get_client().update_current_span(input=user_query)
 
-        classification, tool_categories = await classify_query(user_query)
+        recent_history = get_context_window(session_id, limit=4)
+        classification, tool_categories = await classify_query(user_query, recent_history=recent_history)
 
         if classification == "OUT_OF_SCOPE":
             get_client().update_current_span(output=_REPLY_OUT_OF_SCOPE)
@@ -437,7 +438,8 @@ async def stream_chat_message(
 ) -> AsyncIterator[dict]:
     """SSE streaming chat handler."""
     with propagate_attributes(session_id=session_id, tags=["real-estate-chat", "stream"]):
-        classification, tool_categories = await classify_query(user_query)
+        recent_history = get_context_window(session_id, limit=4)
+        classification, tool_categories = await classify_query(user_query, recent_history=recent_history)
         yield {"type": "status", "classification": classification}
 
         if classification == "OUT_OF_SCOPE":

services/prompts.py

@@ -3,15 +3,22 @@ Prompt definitions and dynamic prompt composer for the Joule Dynamics Real Estat
 """
 
 ROUTER_PROMPT = """You are the classification router for the Joule Dynamics Real Estate Intelligence Layer.
-Analyze the user query and classify it into EXACTLY ONE of seven classifications:
-
-1. "OUT_OF_SCOPE": Query asks about topics completely unrelated to real estate, data monitoring, or the current conversation (e.g. sports, general coding, cooking, recipes). IMPORTANT: Questions asking who you are ("who are you?"), what model you are, or asking to summarize/recap what was discussed in the current chat ("what have we discussed so far?", "summarize our chat") are ALWAYS IN-SCOPE and must NEVER be classified as OUT_OF_SCOPE.
-2. "PATH_A": Query asks a live-data question (prices, spikes, availability, market averages, KPIs, specific listing rates).
+Analyze the user's latest query in the context of the ongoing conversation and classify it into EXACTLY ONE of seven classifications:
+
+1. "OUT_OF_SCOPE": Query asks about topics completely unrelated to real estate, data monitoring, or the current conversation (e.g. sports, general coding, cooking, recipes).
+CRITICAL MULTI-TURN CONTINUATION RULES:
+- If the conversation is already in progress and the user is answering or continuing an ongoing topic, it is NEVER OUT_OF_SCOPE.
+- An answer providing an email address, frequency (daily/weekly), threshold percentage, or confirmation for an alert setup MUST be classified as "ALERT_SUBSCRIPTION".
+- An answer specifying a market name (e.g. "Abuja", "Miami"), property name, date range, or filter in response to an assistant question MUST be classified as "PATH_A" or "BOTH".
+- Questions asking who you are ("who are you?"), what model you are, or asking to summarize/recap what was discussed ("what have we discussed so far?", "summarize our chat") are ALWAYS IN-SCOPE (classify as "GREETING" or "PATH_B").
+- ONLY classify as "OUT_OF_SCOPE" if the user explicitly switches the topic to a completely unrelated subject outside real estate and outside the chat history.
+2. "PATH_A": Query asks a live-data question (prices, spikes, availability, market averages, KPIs, specific listing rates), OR provides clarification (market, date, property) for an active data query.
 3. "PATH_B": Query asks a dashboard visual/UI question (e.g. "What do the top 4 metric cards mean?", "Why does the table say 'Was Available'?", "What do the green/red map pins mean?", "Why is the chart line dotted?", "What does the sparkline mean?", "Why is a row dimmed?"), OR asks a real estate methodology/business logic question (7-day average definition, 2-night check-in window, 4x daily scrape cadence, booked vs host-blocked, temporal UX states), OR asks a meta-conversational question (e.g. "What have we discussed so far?", "Can you summarize our conversation?", "Recap what we talked about").
 4. "BOTH": Query requires BOTH explaining a dashboard UI/methodology concept AND fetching live data metrics via tools.
 5. "GREETING": User is saying hello, thanking the assistant, asking "who are you?", or making casual conversation.
 6. "COMMERCIAL_HANDOFF": Query asks about getting started, hiring Joule Dynamics, custom builds, custom dashboards, pricing for software, or requests tracking for their own specific portfolio outside the demo scope.
-7. "ALERT_SUBSCRIPTION": User wants to be notified about a future event — price spikes, rate changes, availability changes, new listings, pricing anomalies, volatility, trend reversals, or recurring market digests. Keywords: "alert me", "notify me", "let me know when", "tell me when", "tell me whenever", "subscribe", "watch this", "track this for me". This is DISTINCT from PATH_A (which asks about current/historical data, not future notifications).
+7. "ALERT_SUBSCRIPTION": User wants to be notified about a future event — price spikes, rate changes, availability changes, new listings, pricing anomalies, volatility, trend reversals, or recurring market digests (e.g. "alert me", "notify me", "let me know when", "tell me when", "tell me whenever", "subscribe", "watch this", "track this for me").
+CRITICAL: ALSO includes any follow-up response where the user provides an email address, threshold, frequency, or market choice after the assistant offered or asked to set up an alert!
 
 Respond ONLY with valid JSON matching this schema:
 {

services/query_router.py

@@ -53,19 +53,71 @@ def _normalize_tool_categories(categories: object) -> list[str]:
     return []
 
 
-async def classify_query(user_query: str) -> tuple[str, list[str]]:
-    """Classify user query and extract tool categories for category gating."""
-    messages = [
-        {"role": "system", "content": ROUTER_PROMPT},
-        {"role": "user", "content": user_query},
-    ]
+def _build_router_messages(user_query: str, recent_history: list[dict] | None = None) -> list[dict]:
+    """Constructs router message list with recent conversation history for multi-turn awareness."""
+    messages = [{"role": "system", "content": ROUTER_PROMPT}]
+    if recent_history:
+        for msg in recent_history[-2:]:
+            content = msg.get("content", "")
+            if "User Query:" in content:
+                content = content.split("User Query:", 1)[-1].strip()
+            messages.append({
+                "role": msg.get("role", "user"),
+                "content": content[:400],
+            })
+    messages.append({"role": "user", "content": user_query})
+    return messages
+
+
+def _find_last_assistant_message(recent_history: list[dict]) -> str:
+    """Extracts the text of the most recent assistant turn in the history."""
+    for msg in reversed(recent_history):
+        if msg.get("role") == "assistant":
+            return msg.get("content", "").lower()
+    return ""
+
+
+def _rescue_classification(
+    classification: str,
+    user_query: str,
+    recent_history: list[dict] | None,
+) -> str:
+    """Architectural guardrail: rescues false OUT_OF_SCOPE classifications during active conversational flows."""
+    if classification != "OUT_OF_SCOPE" or not recent_history:
+        return classification
+
+    query_lower = user_query.strip().lower()
+
+    if re.search(r"[\w\.-]+@[\w\.-]+\.\w+", query_lower):
+        logger.info("[router] Rescuing OUT_OF_SCOPE -> ALERT_SUBSCRIPTION (email address in active session)")
+        return "ALERT_SUBSCRIPTION"
+
+    last_assistant_msg = _find_last_assistant_message(recent_history)
+    alert_keywords = ("alert", "notification", "email address", "subscribe", "digest")
+    if any(kw in last_assistant_msg for kw in alert_keywords) and len(query_lower.split()) <= 8:
+        logger.info("[router] Rescuing OUT_OF_SCOPE -> ALERT_SUBSCRIPTION (continuation of alert setup)")
+        return "ALERT_SUBSCRIPTION"
+
+    if len(query_lower.split()) <= 5 and any(c in last_assistant_msg for c in ("?", "which", "would you", "what")):
+        logger.info("[router] Rescuing OUT_OF_SCOPE -> PATH_A (short answer to assistant question)")
+        return "PATH_A"
+
+    return classification
+
+
+async def classify_query(
+    user_query: str,
+    recent_history: list[dict] | None = None,
+) -> tuple[str, list[str]]:
+    """Classify user query and extract tool categories for category gating with multi-turn awareness."""
+    messages = _build_router_messages(user_query, recent_history)
 
     for model in [GROQ_ROUTE_MODEL, GROQ_FALLBACK_ROUTE_MODEL]:
         try:
             res = await groq_call(
                 model=model,
                 messages=messages,
-                max_tokens=600,
+                max_tokens=1500,
                 temperature=0.0,
             )
             raw = res.choices[0].message.content or "{}"
@@ -79,6 +131,8 @@ async def classify_query(user_query: str) -> tuple[str, list[str]]:
                 )
                 classification = "PATH_A"
 
+            classification = _rescue_classification(classification, user_query, recent_history)
+
             logger.info(
                 f"[router] {model} -> {classification} (categories={tool_categories}): {data.get('reason', '')}"
             )
@@ -90,4 +144,5 @@ async def classify_query(user_query: str) -> tuple[str, list[str]]:
             else:
                 logger.warning(f"[router] {model} failed, trying fallback: {exc}")
 
-    return "PATH_A", []
+    fallback_classification = _rescue_classification("PATH_A", user_query, recent_history)
+    return fallback_classification, []

tests/test_alert_system.py

@@ -37,6 +37,51 @@ class TestRouterClassification:
         from services.query_router import _VALID_CLASSIFICATIONS
         assert len(_VALID_CLASSIFICATIONS) == 7
 
+    def test_rescue_classification_email_address(self):
+        from services.query_router import _rescue_classification
+        history = [
+            {"role": "user", "content": "Send me a report whenever rate changes in Abuja"},
+            {"role": "assistant", "content": "Sure thing! To set up a notification for any rate changes in Abuja, I'll need the email address where you'd like to receive the alerts."},
+        ]
+        result = _rescue_classification("OUT_OF_SCOPE", "john.albarka.ibrahim@gmail.com", history)
+        assert result == "ALERT_SUBSCRIPTION"
+
+    def test_rescue_classification_alert_short_reply(self):
+        from services.query_router import _rescue_classification
+        history = [
+            {"role": "assistant", "content": "Would you like a daily or weekly digest for Miami?"},
+        ]
+        assert _rescue_classification("OUT_OF_SCOPE", "weekly", history) == "ALERT_SUBSCRIPTION"
+        assert _rescue_classification("OUT_OF_SCOPE", "daily please", history) == "ALERT_SUBSCRIPTION"
+
+    def test_rescue_classification_general_question_short_reply(self):
+        from services.query_router import _rescue_classification
+        history = [
+            {"role": "assistant", "content": "Which market would you like me to analyze?"},
+        ]
+        assert _rescue_classification("OUT_OF_SCOPE", "Miami", history) == "PATH_A"
+
+    def test_rescue_classification_truly_out_of_scope_preserved(self):
+        from services.query_router import _rescue_classification
+        history = [
+            {"role": "assistant", "content": "Sure thing! I need your email address."},
+        ]
+        result = _rescue_classification("OUT_OF_SCOPE", "how do I bake a chocolate cake with vanilla frosting?", history)
+        assert result == "OUT_OF_SCOPE"
+
+    def test_build_router_messages_includes_history(self):
+        from services.query_router import _build_router_messages
+        history = [
+            {"role": "user", "content": "User Context Filters: {}\nUser Query: Track Abuja"},
+            {"role": "assistant", "content": "What is your email address?"},
+        ]
+        messages = _build_router_messages("john@example.com", history)
+        assert len(messages) == 4
+        assert messages[0]["role"] == "system"
+        assert messages[1]["content"] == "Track Abuja"
+        assert messages[2]["content"] == "What is your email address?"
+        assert messages[3]["content"] == "john@example.com"
+
 
 class TestToolResolution:
     """Verify _resolve_active_tools returns exactly 2 tools for ALERT_SUBSCRIPTION."""