fyp

HOW_TO_RUN.md

@@ -1,58 +0,0 @@
-# How to Run AIDA Agent for Testing
-
-## 1. Start the Backend Server
-
-In the AIDA directory, run:
-
-```bash
-python -m uvicorn main:app --reload
-```
-
-**Note:** Use `main:app` not `app.main:app` (main.py is in the root, not in the app folder)
-
-The server will start on `http://127.0.0.1:8000`
-
-You should see:
-```
-INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
-INFO:     Started reloader process [xxxx] using WatchFiles
-```
-
-## 2. Open the Test UI
-
-Simply open `test_chat_ui.html` in your browser:
-- Double-click the file, OR
-- Right-click → Open with → Chrome/Edge/Firefox
-
-The UI will automatically connect to `http://localhost:8000`
-
-## 3. Test the Agent
-
-1. **Login** (in the sidebar):
-   - Enter your test credentials
-   - Or paste a JWT token in the "Manual Token Override" field
-
-2. **Chat**:
-   - Type messages in the input box at the bottom
-   - Click Send or press Enter
-   - View responses in the chat area
-
-3. **Debug**:
-   - Check the "Debug Output" section in the sidebar for raw JSON responses
-   - Monitor the server terminal for backend logs
-
-## Troubleshooting
-
-### Server won't start
-- Check if port 8000 is already in use
-- Verify MongoDB, Redis, Qdrant connection strings in `.env`
-- Check the terminal for specific error messages
-
-### UI shows "Offline"
-- Make sure the server is running on port 8000
-- Check browser console (F12) for CORS or network errors
-
-### Authentication fails
-- Verify your test user exists in the database
-- Check the credentials match
-- Use the manual token input as a fallback

app/ai/agent/agent_hub.py

@@ -0,0 +1,389 @@
+# app/ai/agent/agent_hub.py
+"""
+AIDA Agent Hub — Multi-Agent Router
+
+Architecture:
+  GENERAL (default)  — Search, listing, market price, general queries, alerts setup.
+                        Handles everything until a specialist flow is triggered.
+  CONCIERGE          — Triggered when user taps Book / Help me choose on a short-stay listing.
+                        Owns the full booking flow + pre-checkin reminders + post-checkout reviews.
+  BROKER             — Triggered when user wants to schedule a property viewing (rent/sale).
+                        Owns viewing scheduling, calendar cross-check, post-viewing review.
+  MATCHER            — Triggered when roommate intent detected.
+                        Owns both Host and Seeker roommate flows + double opt-in.
+
+The user NEVER sees agent switching — transitions are seamless.
+"""
+
+from typing import Optional
+from structlog import get_logger
+from langchain_core.messages import HumanMessage
+
+from app.ai.agent.state import AgentState
+from app.ai.agent.brain import _invoke_with_fallback, generate_localized_response
+
+logger = get_logger(__name__)
+
+# ============================================================
+# AGENT IDENTIFIERS
+# ============================================================
+
+AGENT_GENERAL = "general"       # brain.py — default for everything
+AGENT_CONCIERGE = "concierge"   # short-stay booking flow
+AGENT_BROKER = "broker"         # viewing scheduling + deal flow
+AGENT_MATCHER = "matcher"       # roommate matching
+
+HANDOFF_MAP = {
+    "HANDOFF_CONCIERGE": AGENT_CONCIERGE,
+    "HANDOFF_BROKER": AGENT_BROKER,
+    "HANDOFF_MATCHER": AGENT_MATCHER,
+    "HANDOFF_GENERAL": AGENT_GENERAL,
+}
+
+# ============================================================
+# FAST KEYWORD ROUTING
+# ============================================================
+
+# Booking flow — only when user is actively booking a short-stay
+# Triggered by "Book" button action or explicit booking language
+_BOOKING_SIGNALS = [
+    "book this", "book now", "i want to book", "confirm booking", "proceed to book",
+    "book it", "reserve this", "reserve now", "check availability", "check-in",
+    "checkout", "check out", "réserver", "je veux réserver", "confirm my booking",
+    "initiate booking", "start booking",
+]
+
+# Viewing scheduling — only when user wants to schedule a visit for rent/sale
+_SCHEDULING_SIGNALS = [
+    "schedule a viewing", "schedule viewing", "book a viewing", "book a visit",
+    "schedule a visit", "arrange a visit", "visit the property", "see the property",
+    "view the property", "when can i visit", "when can i see it",
+    "planifier une visite", "prendre rendez-vous", "organiser une visite",
+    "schedule an appointment", "book an appointment",
+]
+
+# Roommate — anyone looking to share or find someone to share with
+_ROOMMATE_SIGNALS = [
+    "roommate", "room mate", "colocataire", "colocation", "co-living", "coliving",
+    "share apartment", "share my apartment", "share flat", "share my place", "share a place",
+    "looking for someone to share", "cherche colocataire", "find a roommate",
+    "list a room", "list my room", "have a room", "spare room",
+    "looking for a room to share", "trouver un colocataire",
+    "cherche quelqu'un pour partager", "want a flatmate", "need a flatmate",
+]
+
+
+def _fast_route(message: str, state: AgentState) -> Optional[str]:
+    """
+    Fast keyword routing — no LLM call.
+    Returns agent id if confident, None if ambiguous (let LLM decide).
+    """
+    msg = message.lower()
+
+    # Roommate is the highest-confidence signal — very specific vocabulary
+    if any(s in msg for s in _ROOMMATE_SIGNALS):
+        return AGENT_MATCHER
+
+    # Viewing scheduling — unambiguous when present
+    if any(s in msg for s in _SCHEDULING_SIGNALS):
+        return AGENT_BROKER
+
+    # Booking flow — only if user is clearly trying to book
+    if any(s in msg for s in _BOOKING_SIGNALS):
+        return AGENT_CONCIERGE
+
+    # Listing signals — always handled by general brain regardless of role
+    # (The general brain's listing flow handles the extra fee prompt for rent/sale)
+    listing_signals = [
+        "list my property", "list my apartment", "list my house", "list my place",
+        "list my flat", "i want to list", "publish my property",
+        "publier mon bien", "mettre en location", "je veux lister",
+    ]
+    if any(s in msg for s in listing_signals):
+        # Renters can only list roommate → redirect to matcher
+        if state.user_role == "renter":
+            return AGENT_MATCHER
+        return AGENT_GENERAL   # landlords: general brain handles full listing flow
+
+    return None   # ambiguous — let LLM classify
+
+
+# ============================================================
+# LLM CLASSIFIER (for ambiguous messages)
+# ============================================================
+
+_CLASSIFICATION_PROMPT = """You are the routing layer for AIDA, a real estate AI on Lojiz.
+
+Classify the user's message into ONE of these routing targets:
+
+- "general"    → Search for properties (any type), listing creation/management, market prices,
+                  alerts, general questions, greetings, anything not covered below.
+                  This is the DEFAULT — when in doubt, use "general".
+
+- "concierge"  → User is actively BOOKING a short-stay property right now.
+                  Triggers: "book this", "I want to book", confirming a booking, payment step.
+                  NOT for searching short-stays — only for the booking transaction itself.
+
+- "broker"     → User wants to SCHEDULE A VIEWING for a rental or sale property.
+                  Triggers: "schedule a viewing", "when can I visit", "arrange an appointment".
+                  NOT for searching rentals/sales — only for the viewing scheduling flow.
+
+- "matcher"    → Roommate search or co-living: looking for a flatmate, listing a room to share,
+                  wanting someone to share their apartment with.
+
+User message: "{message}"
+Conversation context (last 2 turns): {context}
+Current agent: {current_agent}
+User role: {user_role}
+
+Rules:
+1. DEFAULT IS "general" — only route to a specialist when the trigger is clearly present.
+2. Searching for a house/apartment → "general" (not broker).
+3. Booking a short-stay → "concierge". Searching for short-stays → "general".
+4. Scheduling a viewing → "broker". Looking for rental/sale listings → "general".
+5. Roommate intent → "matcher".
+6. Listing creation (rent/sale/short-stay) → "general" (general brain handles all listing flows).
+7. If user role is "renter" and they want to list → "matcher" (renters can only list roommate spaces).
+8. If current_agent is set and message is a follow-up in the same flow, keep the same agent.
+9. Reply with ONLY one word: general, concierge, broker, or matcher.
+"""
+
+
+async def classify_intent(
+    message: str,
+    state: AgentState,
+    current_agent: Optional[str] = None,
+) -> str:
+    """
+    Classify user intent → select the right agent.
+    Fast keyword check first, LLM fallback for ambiguous messages.
+    """
+    # Fast path
+    fast = _fast_route(message, state)
+    if fast:
+        logger.info("Hub fast-routed", agent=fast, message=message[:60])
+        return fast
+
+    # LLM classification
+    try:
+        history = state.conversation_history or []
+        ctx_turns = history[-4:] if len(history) >= 4 else history
+        ctx_text = " | ".join(
+            f"{m.get('role', '')}: {str(m.get('content', ''))[:80]}"
+            for m in ctx_turns
+        ) or "No prior context"
+
+        prompt = _CLASSIFICATION_PROMPT.format(
+            message=message,
+            context=ctx_text,
+            current_agent=current_agent or "none",
+            user_role=state.user_role or "unknown",
+        )
+        response = await _invoke_with_fallback(
+            [HumanMessage(content=prompt)],
+            caller="hub_classify_intent",
+        )
+        result = response.content.strip().lower().split()[0]
+        if result in (AGENT_GENERAL, AGENT_CONCIERGE, AGENT_BROKER, AGENT_MATCHER):
+            logger.info("Hub LLM-classified intent", result=result, message=message[:60])
+            return result
+    except Exception as e:
+        logger.warning("Hub LLM classification failed, falling back", error=str(e))
+
+    # Fallback: stay with current agent or go to general
+    return current_agent or AGENT_GENERAL
+
+
+# ============================================================
+# AGENT DISPATCH
+# ============================================================
+
+async def _dispatch(agent_id: str, state: AgentState) -> AgentState:
+    """Route to the correct brain."""
+    if agent_id == AGENT_CONCIERGE:
+        from app.ai.agent.concierge_brain import process
+        return await process(state)
+
+    elif agent_id == AGENT_BROKER:
+        from app.ai.agent.broker_brain import process
+        return await process(state)
+
+    elif agent_id == AGENT_MATCHER:
+        from app.ai.agent.matcher_brain import process
+        return await process(state)
+
+    else:
+        # general or unknown → general brain (brain.py agent_think)
+        from app.ai.agent.brain import agent_think
+        return await agent_think(state)
+
+
+# ============================================================
+# HANDOFF HANDLER
+# ============================================================
+
+async def _handle_handoff(state: AgentState, max_hops: int = 2) -> AgentState:
+    """
+    Re-dispatch when a brain returns a HANDOFF signal.
+    Caps at max_hops to prevent loops.
+    """
+    hops = 0
+    while hops < max_hops:
+        handoff = state.temp_data.pop("handoff", None)
+        if not handoff:
+            break
+
+        target = HANDOFF_MAP.get(handoff)
+        if not target:
+            logger.warning("Unknown handoff signal", signal=handoff)
+            break
+
+        reason = state.temp_data.pop("handoff_reason", "")
+        logger.info(
+            "Hub executing handoff",
+            from_agent=state.temp_data.get("active_agent"),
+            to_agent=target,
+            reason=reason[:80],
+        )
+        state.temp_data["pre_handoff_context"] = reason
+        state = await _dispatch(target, state)
+        hops += 1
+
+    return state
+
+
+# ============================================================
+# MAIN ENTRY POINT
+# ============================================================
+
+async def _load_sticky_agent(user_id: str) -> Optional[str]:
+    """
+    Load the persisted active agent for this user from MongoDB.
+    Returns None if no session exists yet.
+    """
+    try:
+        from app.database import get_db
+        db = await get_db()
+        doc = await db["aida_sessions"].find_one({"user_id": user_id})
+        return doc.get("active_agent") if doc else None
+    except Exception as e:
+        logger.warning("Failed to load sticky agent", user_id=user_id, error=str(e))
+        return None
+
+
+async def _save_sticky_agent(user_id: str, agent_id: str) -> None:
+    """
+    Persist the active agent for this user to MongoDB so it survives session resume.
+    Uses upsert so we never create duplicates.
+    """
+    try:
+        from app.database import get_db
+        from datetime import datetime
+        db = await get_db()
+        await db["aida_sessions"].update_one(
+            {"user_id": user_id},
+            {"$set": {"active_agent": agent_id, "updated_at": datetime.utcnow()}},
+            upsert=True,
+        )
+    except Exception as e:
+        logger.warning("Failed to save sticky agent", user_id=user_id, error=str(e))
+
+
+async def run(state: AgentState) -> AgentState:
+    """
+    Primary entry point for ALL messages through the LangGraph "brain" node.
+
+    Flow:
+    1. Load persisted active_agent from DB (session resume stickiness)
+    2. Classify intent — if user is continuing a specialist flow, stay there
+    3. Dispatch to the correct agent brain
+    4. Handle any handoff signals (max 2 hops)
+    5. Persist the active_agent back to DB for next session
+    6. Guarantee a response is always set
+    """
+    message = state.last_user_message or ""
+
+    # 1. Load sticky agent — prefer what's already on state (current session),
+    #    fall back to DB (cross-session resume)
+    if not state.active_agent:
+        state.active_agent = await _load_sticky_agent(state.user_id)
+
+    current_agent = state.active_agent  # may still be None on first ever message
+
+    logger.info(
+        "Hub received message",
+        user_id=state.user_id,
+        current_agent=current_agent,
+        message=message[:60],
+    )
+
+    # 2. Classify
+    agent_id = await classify_intent(message, state, current_agent)
+    logger.info("Hub dispatching", agent=agent_id)
+
+    # 3. Dispatch — run context loader on resume if agent switched or first load
+    is_resume = current_agent == agent_id and agent_id != AGENT_GENERAL and not state.agent_context
+    if is_resume:
+        state = await _run_context_loader(agent_id, state)
+
+    state = await _dispatch(agent_id, state)
+
+    # 4. Handle handoffs — update agent_id after any hop
+    if state.temp_data.get("handoff"):
+        state = await _handle_handoff(state)
+        # After handoff the actual agent may have changed — read from temp_data
+        agent_id = state.temp_data.get("active_agent", agent_id)
+
+    # 5. Persist active agent — general is transient, specialists are sticky
+    state.active_agent = agent_id
+    if agent_id != AGENT_GENERAL:
+        await _save_sticky_agent(state.user_id, agent_id)
+    else:
+        # If user explicitly returned to general (e.g. after booking complete), clear sticky
+        await _save_sticky_agent(state.user_id, AGENT_GENERAL)
+
+    # 6. Safety net — always have a response
+    if not state.temp_data.get("response_text"):
+        lang = state.language_detected or state.app_language or "en"
+        state.temp_data["response_text"] = await generate_localized_response(
+            context="Something unexpected happened. Tell the user AIDA is ready to help and ask what they need.",
+            language=lang,
+            tone="friendly",
+            max_length="short",
+        )
+        state.temp_data["action"] = "respond"
+
+    return state
+
+
+async def _run_context_loader(agent_id: str, state: AgentState) -> AgentState:
+    """
+    On session resume (same specialist agent, no context loaded yet),
+    call that brain's context loader to pre-populate agent_context.
+    """
+    try:
+        if agent_id == AGENT_CONCIERGE:
+            from app.ai.agent.concierge_brain import load_context
+            state = await load_context(state)
+        elif agent_id == AGENT_BROKER:
+            from app.ai.agent.broker_brain import load_context
+            state = await load_context(state)
+        elif agent_id == AGENT_MATCHER:
+            from app.ai.agent.matcher_brain import load_context
+            state = await load_context(state)
+    except Exception as e:
+        logger.warning("Context loader failed (non-fatal)", agent=agent_id, error=str(e))
+    return state
+
+
+# ============================================================
+# HELPERS
+# ============================================================
+
+def get_agent_display_name(agent_id: str) -> str:
+    return {
+        AGENT_GENERAL: "AIDA",
+        AGENT_CONCIERGE: "AIDA-Primary (Concierge)",
+        AGENT_BROKER: "AIDA-Market (Broker)",
+        AGENT_MATCHER: "AIDA-Social (Matcher)",
+    }.get(agent_id, "AIDA")

app/ai/agent/brain.py

@@ -1170,7 +1170,7 @@ async def execute_tool(tool_name: str, params: Dict[str, Any], state: AgentState
             rlm_used = False
 
             # ================================================================
-            # Step 2.5: CHECK IF RLM SHOULD BE USED (NEW!)
+            # Step 3: CHECK IF RLM SHOULD BE USED
             # ================================================================
             strategy_result = await select_search_strategy(state.last_user_message, search_params)
 
@@ -1473,8 +1473,8 @@ async def execute_tool(tool_name: str, params: Dict[str, Any], state: AgentState
         elif tool_name == "create_alert":
             # Save user's search alert for notifications
             from app.services.alert_service import create_alert
-            from app.ai.tools.search_tool import perform_search
-            
+            from app.ai.services.search_service import search_mongodb
+
             # Get search params - either from params or from last search
             search_params = params.get("criteria") or state.temp_data.get("last_search_params") or state.temp_data.get("search_params") or {}
             search_query = state.temp_data.get("last_search_query", state.last_user_message)
@@ -1494,14 +1494,15 @@ async def execute_tool(tool_name: str, params: Dict[str, Any], state: AgentState
                 # Step 1: Search current listings immediately
                 current_results = []
                 try:
-                    from app.ai.tools.search_tool import rigid_search
-                    current_results = await rigid_search(
-                        search_params.get("location"),
-                        search_params.get("listing_type"),
-                        search_params.get("min_price"),
-                        search_params.get("max_price"),
-                        search_params.get("bedrooms"),
-                        search_params.get("bathrooms"),
+                    current_results = await search_mongodb(
+                        params={
+                            "location": search_params.get("location"),
+                            "listing_type": search_params.get("listing_type"),
+                            "min_price": search_params.get("min_price"),
+                            "max_price": search_params.get("max_price"),
+                            "bedrooms": search_params.get("bedrooms"),
+                            "bathrooms": search_params.get("bathrooms"),
+                        },
                         limit=10
                     )
                     
@@ -2278,6 +2279,92 @@ Instructions:
             # No action, just respond
             return True, "Response ready", None
 
+        elif tool_name == "get_price_trends":
+            # Market price query — run aggregation and format with disclaimer
+            try:
+                from app.database import get_db
+                db = await get_db()
+                location = params.get("location") or state.user_location
+
+                pipeline = []
+                if location:
+                    # Use country expansion for broad locations
+                    from app.ai.services.search_service import _get_country_cities
+                    cities = await _get_country_cities(location)
+                    if cities:
+                        city_regexes = [{"location": {"$regex": c, "$options": "i"}} for c in cities]
+                        city_regexes.append({"location": {"$regex": location, "$options": "i"}})
+                        pipeline.append({"$match": {"status": "active", "$or": city_regexes}})
+                    else:
+                        pipeline.append({"$match": {"status": "active", "location": {"$regex": location, "$options": "i"}}})
+                else:
+                    pipeline.append({"$match": {"status": "active"}})
+
+                pipeline += [
+                    {"$group": {
+                        "_id": {"location": "$location", "listing_type": "$listing_type"},
+                        "avg_price": {"$avg": "$price"},
+                        "min_price": {"$min": "$price"},
+                        "max_price": {"$max": "$price"},
+                        "count": {"$sum": 1},
+                        "currency": {"$first": "$currency"},
+                    }},
+                    {"$match": {"count": {"$gte": 1}}},
+                    {"$sort": {"count": -1}},
+                    {"$limit": 15},
+                ]
+
+                cursor = db["listings"].aggregate(pipeline)
+                rows = await cursor.to_list(length=15)
+
+                if not rows:
+                    no_data_msg = await generate_localized_response(
+                        context=f"Tell the user there is no listing price data available{' for ' + location if location else ''} on the platform yet. Be empathetic and suggest they check back later.",
+                        language=state.language_detected or state.app_language or "en",
+                        tone="friendly",
+                        max_length="short"
+                    )
+                    state.temp_data["response_text"] = no_data_msg
+                    state.temp_data["action"] = "respond"
+                    return True, "No price data", None
+
+                # Build structured summary for the LLM to narrate
+                summary_lines = []
+                for row in rows:
+                    loc = row["_id"].get("location", "Unknown")
+                    ltype = row["_id"].get("listing_type", "property")
+                    curr = row.get("currency") or ""
+                    avg = row.get("avg_price", 0)
+                    mn = row.get("min_price", 0)
+                    mx = row.get("max_price", 0)
+                    cnt = row.get("count", 0)
+                    summary_lines.append(
+                        f"{loc} ({ltype}): avg {curr} {avg:,.0f}/month, range {curr} {mn:,.0f}–{mx:,.0f} ({cnt} listings)"
+                    )
+                data_summary = "\n".join(summary_lines)
+
+                price_response = await generate_localized_response(
+                    context=(
+                        f"Present the following real estate market price data clearly and naturally to the user. "
+                        f"Group by location if multiple cities. Use natural human language — not a raw table. "
+                        f"After presenting the data, add a short disclaimer that these prices are based on "
+                        f"listings currently available on the Lojiz platform only, and actual market prices "
+                        f"may vary by exact neighborhood and current market conditions.\n\n"
+                        f"Price data:\n{data_summary}"
+                    ),
+                    language=state.language_detected or state.app_language or "en",
+                    tone="professional",
+                    max_length="long"
+                )
+                state.temp_data["response_text"] = price_response
+                state.temp_data["action"] = "respond"
+                await log_reward(state.session_id, REWARD_MARKET_INSIGHT, "price_trends", {"location": location})
+                return True, "Price trends generated", rows
+
+            except Exception as price_err:
+                logger.error("get_price_trends failed", error=str(price_err))
+                return False, str(price_err), None
+
         else:
             # Try dynamic tool from registry (api / db_query)
             try:
@@ -2612,16 +2699,20 @@ Generate one friendly question (1 sentence max):"""
         if count > 0:
             if is_suggestion:
                 # Relaxed search — no exact match, showing closest alternatives
+                # REQUIREMENT (Problem 19): MUST explicitly restate what wasn't found before showing alternatives
                 context = (
                     f"The user said: \"{user_msg_snippet}\"\n"
-                    f"You searched the market for '{search_desc}' but found no exact matches. "
-                    f"However you found {count} similar propert{'y' if count == 1 else 'ies'} that could work for them. "
-                    f"Be warm and personal — if their message contains emotional context (honeymoon, new job, family move, etc.) "
-                    f"acknowledge it naturally before presenting results. "
-                    f"Sound like a friend who went out and searched on their behalf — not a robot. "
-                    f"Do NOT say phrases like 'I am thrilled to share' or 'I found X properties matching your search'. "
-                    f"Suggest they activate alerts to be notified when an exact match becomes available — "
-                    f"phrase it naturally in their language, do NOT hardcode 'Notify me' in English if the language is different. Include 👇 emoji."
+                    f"You searched the market specifically for '{search_desc}' and found ZERO exact matches. "
+                    f"However you found {count} similar propert{'y' if count == 1 else 'ies'} that might interest them. "
+                    f"\n\nCRITICAL RULES for your response:\n"
+                    f"1. You MUST explicitly state what you couldn't find — name the exact criteria: '{search_desc}'. "
+                    f"   Example: 'I couldn't find any {search_desc} right now, but...' or "
+                    f"   'Nothing came up for {search_desc} specifically, but I found something close...'\n"
+                    f"2. Then present the alternatives warmly.\n"
+                    f"3. If their message has emotional context (honeymoon, moving, new job, etc.) acknowledge it naturally.\n"
+                    f"4. Suggest they activate alerts so you can notify them when an exact match appears — "
+                    f"   phrase it naturally in their language (do NOT hardcode 'Notify me' in English if different language).\n"
+                    f"5. Sound like a friend who genuinely searched on their behalf. Include 👇 emoji."
                 )
                 return await generate_localized_response(
                     context=context,

app/ai/agent/broker_brain.py

@@ -0,0 +1,347 @@
+# app/ai/agent/broker_brain.py
+"""
+AIDA-Market — The Deal Broker Brain
+
+Domain: Long-term rentals (monthly/yearly), property sales, viewing scheduling,
+        post-viewing follow-up, anti-scam transparency, async alert hunting.
+
+Triggered when:
+  - User clicks "Schedule Viewing" in a landlord chat
+  - General brain detects rent/sale deal-flow intent (not just search)
+
+Responsibilities:
+  - Viewing scheduling: cross-check both calendars, suggest 3 slots, notify landlord, confirm
+  - Pre-viewing reminder via AIDA DM (1–3 hours before)
+  - Post-viewing follow-up: check in with visitor, collect rating for landlord/agent profile
+  - Anti-scam transparency checks
+  - Async alert hunting: scan market when user is offline, notify via AIDA DM on match
+  - Market intelligence (price trends, insights)
+
+NOT responsible for:
+  - Listing creation/management — handled by general brain
+  - Short-stay booking — handled by AIDA-Concierge
+  - Roommate matching — handled by AIDA-Social
+  - Negotiation — user initiates contact with landlord directly
+"""
+
+from structlog import get_logger
+from bson import ObjectId
+
+from app.ai.agent.state import AgentState
+from app.ai.agent.brain import (
+    brain_decide,
+    execute_tool,
+    generate_localized_response,
+    generate_contextual_response,
+)
+from app.ai.lightning.rewards import log_reward, REWARD_SEARCH_COMPLETED
+
+logger = get_logger(__name__)
+
+# ============================================================
+# BROKER IDENTITY
+# ============================================================
+
+AGENT_ID = "broker"
+AGENT_NAME = "AIDA-Market"
+AGENT_DOMAIN = "long-term rent, property sales, viewing scheduling, anti-scam"
+
+OWNED_LISTING_TYPES = {"rent", "sale"}
+
+BROKER_TOOLS = """
+AVAILABLE TOOLS (use ONLY these):
+
+SEARCH & DISCOVERY:
+1. search_properties(query, location, min_price, max_price, beds, listing_type)
+   - Find long-term rentals (listing_type="rent") or properties for sale (listing_type="sale").
+   - NEVER search for short-stay here — that belongs to the Concierge.
+
+2. analyze_listing(listing_id)
+   - Deep analysis: price fairness, market position, hidden fees check.
+   - ANTI-SCAM: Always flag if price is suspiciously low or listing lacks key details.
+
+3. get_landlord_info(user_id)
+   - Public profile of a landlord/agent. Use for trust checks.
+
+4. get_price_trends(location)
+   - Average rent/sale prices for an area.
+
+5. get_market_insights(location)
+   - Demand trends, best areas, investment signals.
+
+VIEWING SCHEDULING:
+6. schedule_visit(listing_id, preferred_slots, message)
+   - Propose up to 3 viewing time slots to the landlord after cross-checking availability.
+   - Triggers RSVP notification to the landlord.
+
+7. check_calendar_availability(user_id, date_range)
+   - Check a user's or landlord's available windows within a date range.
+
+8. confirm_viewing(visit_id)
+   - Confirm a viewing once landlord accepts. Saves to both parties' schedules.
+
+9. cancel_viewing(visit_id, reason)
+   - Cancel a confirmed or pending viewing.
+
+ALERTS & ASYNC HUNTING:
+10. create_alert(criteria)
+    - Set up background market scanning. Broker hunts even when user is offline.
+    - Notify via AIDA DM when a match appears or price drops.
+
+11. delete_alert(alert_id) / pause_alert(alert_id) / resume_alert(alert_id)
+12. get_my_alerts()
+
+NOTIFICATIONS (triggered by Broker events):
+13. send_viewing_reminder(visit_id, recipient_user_id)
+    - Send AIDA DM reminder to a party 1–3 hours before their viewing.
+
+14. send_post_viewing_followup(visit_id, visitor_user_id)
+    - Send AIDA DM to the visitor after a viewing to collect their experience + rating.
+
+15. submit_person_review(reviewed_user_id, rating, review_text, context)
+    - Save rating and review to a landlord's or agent's profile (NOT the property).
+    - Use after post-viewing follow-up is complete.
+
+GENERAL:
+16. remember_preference(key, value, category)
+    - Save search criteria or preferences for future sessions.
+
+17. track_user_feedback(feedback_type, context, correction_text)
+    - Internally log corrections or negative reactions.
+
+18. respond(message)
+    - Market Q&A, anti-scam education, scheduling updates, general deal chat.
+
+HANDOFF SIGNALS (do NOT handle — return handoff instead):
+- Short-stay booking intent → set tool: "HANDOFF_CONCIERGE"
+- Roommate search/listing intent → set tool: "HANDOFF_MATCHER"
+"""
+
+BROKER_SYSTEM_PROMPT = """You are AIDA-Market, the deal specialist on Lojiz.
+
+YOUR SPECIALTY: Helping people find long-term rentals and properties to buy — then making the
+viewing and deal process smooth, safe, and transparent.
+
+YOUR PERSONALITY:
+- Professional, calm, and thorough
+- You protect users — proactively flag suspicious listings before they commit
+- You work even when users are offline — alerts scan the market continuously on their behalf
+- You follow through: you check in after viewings and hold people accountable
+
+══════════════════���════════════════════════════
+VIEWING SCHEDULING FLOW
+═══════════════════════════════════════════════
+
+Triggered when user wants to schedule a viewing (via "Schedule Viewing" button or request):
+
+1. Ask the user: "When are you generally free this week or next?"
+2. Call check_calendar_availability for the landlord (get their open slots).
+3. Cross-reference → suggest up to 3 overlapping time slots to the user.
+4. User picks one → call schedule_visit to send the proposal to the landlord.
+5. Landlord confirms → call confirm_viewing → notify both parties via AIDA DM.
+6. 1–3 hours before viewing → call send_viewing_reminder for both parties.
+7. After viewing → call send_post_viewing_followup to the visitor.
+8. Visitor responds → call submit_person_review → saved to landlord/agent profile.
+
+NOTE: If user prefers to schedule directly with the landlord without AIDA, that's fine —
+      both paths exist. AIDA only takes over when asked.
+
+═══════════════════════════════════════════════
+POST-VIEWING FOLLOW-UP
+═══════════════════════════════════════════════
+
+After a viewing, send the visitor an AIDA DM:
+  "Hey! How did the viewing go? Was [Landlord/Agent name] professional and the property
+   as described? Rate them 1–5 ⭐ — it helps the next person."
+
+The rating and review go to the LANDLORD/AGENT profile, not the property.
+This is because for rentals and sales, the person matters more than the walls.
+
+═══════════════════════════════════════════════
+ANTI-SCAM RULES (MANDATORY)
+═══════════════════════════════════════════════
+
+- If listing price is 40%+ below market average for that area → flag it as suspicious
+- If listing demands cash before viewing → flag it immediately
+- Always say: "After your viewing, let me know if the property matched the listing"
+- Educate naturally: "Always insist on a signed agreement before any payment"
+
+═══════════════════════════════════════════════
+YOUR RULES
+═══════════════════════════════════════════════
+1. Long-term rent and sale ONLY.
+   Short-stay → HANDOFF_CONCIERGE. Roommate → HANDOFF_MATCHER.
+2. Listing creation and management is handled elsewhere — do NOT run listing flows here.
+3. No negotiation on behalf of users — they talk directly to landlords. You only assist with scheduling.
+4. Always suggest setting an alert when search returns no results.
+5. Respond entirely in the user's detected language.
+6. Never mention "HANDOFF", "broker", or internal agent names to the user.
+"""
+
+
+# ============================================================
+# MAIN ENTRY POINT
+# ============================================================
+
+async def process(state: AgentState) -> AgentState:
+    """
+    Broker brain entry point.
+    Handles rent/sale deal flow: search, viewing scheduling, post-viewing follow-up.
+    """
+    logger.info("AIDA-Market activated", user_id=state.user_id, message=state.last_user_message[:60])
+
+    state.temp_data["active_agent"] = AGENT_ID
+    state.temp_data["agent_system_prompt"] = BROKER_SYSTEM_PROMPT
+    state.temp_data["agent_tools"] = BROKER_TOOLS
+
+    try:
+        decision = await brain_decide(state)
+    except Exception as e:
+        logger.error("Broker brain_decide failed", error=str(e))
+        state.temp_data["response_text"] = await generate_localized_response(
+            context="Tell the user there was a brief issue and you're ready to help them now.",
+            language=state.language_detected or state.app_language or "en",
+            tone="apologetic",
+            max_length="short",
+        )
+        state.temp_data["action"] = "respond"
+        return state
+
+    # Handoff signals
+    if decision.tool in ("HANDOFF_CONCIERGE", "HANDOFF_MATCHER"):
+        state.temp_data["handoff"] = decision.tool
+        state.temp_data["handoff_reason"] = decision.thinking
+        logger.info("Broker signalling handoff", target=decision.tool)
+        return state
+
+    # Execute tool
+    if decision.tool and decision.tool != "respond":
+        try:
+            success, message, result = await execute_tool(decision.tool, decision.params, state)
+            if not success:
+                logger.warning("Broker tool failed", tool=decision.tool, message=message)
+        except Exception as e:
+            logger.error("Broker tool execution error", tool=decision.tool, error=str(e))
+
+    # Generate response
+    if decision.tool == "search_properties":
+        try:
+            log_reward(REWARD_SEARCH_COMPLETED, state.user_id, {"agent": AGENT_ID})
+        except Exception:
+            pass
+        state.temp_data["response_text"] = await generate_contextual_response(state, decision)
+    elif not state.temp_data.get("response_text"):
+        if decision.response:
+            state.temp_data["response_text"] = decision.response
+        else:
+            state.temp_data["response_text"] = await generate_contextual_response(state, decision)
+
+    return state
+
+
+# ============================================================
+# CONTEXT LOADER — session resume
+# ============================================================
+
+async def load_context(state: AgentState) -> AgentState:
+    """
+    Called on session resume. Loads the user's most recent active viewing
+    into state.agent_context["viewing"] — includes scheduling step, proposed slots,
+    and availability data — so the brain can resume mid-flow without re-asking.
+    """
+    try:
+        from app.database import get_db
+        db = await get_db()
+
+        # User could be the visitor OR the landlord — check both sides
+        viewing = await db["viewings"].find_one(
+            {
+                "$or": [
+                    {"visitor_id": state.user_id},
+                    {"landlord_id": state.user_id},
+                ],
+                "status": {"$in": ["pending", "confirmed"]},
+            },
+            sort=[("created_at", -1)],
+        )
+
+        if viewing:
+            viewing["_id"] = str(viewing["_id"])
+            # Derive which step the flow is at
+            step = _infer_viewing_step(viewing, state.user_id)
+            state.agent_context["viewing"] = {
+                **viewing,
+                "current_step": step,
+                "user_is_visitor": viewing.get("visitor_id") == state.user_id,
+            }
+            logger.info(
+                "Broker context loaded",
+                user_id=state.user_id,
+                viewing_id=viewing["_id"],
+                status=viewing.get("status"),
+                step=step,
+            )
+        else:
+            logger.info("Broker context: no active viewing found", user_id=state.user_id)
+
+    except Exception as e:
+        logger.warning("Broker load_context failed (non-fatal)", error=str(e))
+
+    return state
+
+
+def _infer_viewing_step(viewing: dict, user_id: str) -> str:
+    """Map viewing document fields → which step the user is currently on."""
+    is_visitor  = viewing.get("visitor_id") == user_id
+    is_landlord = viewing.get("landlord_id") == user_id
+    status      = viewing.get("status", "pending")
+
+    if status == "confirmed":
+        return "viewing_confirmed"
+
+    visitor_avail  = viewing.get("visitor_availability", [])
+    landlord_avail = viewing.get("landlord_availability", [])
+    suggested      = viewing.get("suggested_slots", [])
+    confirmed_slot = viewing.get("confirmed_slot")
+
+    if confirmed_slot:
+        return "landlord_confirm_slot"
+    if suggested:
+        return "visitor_pick_slot"
+    if is_visitor and not visitor_avail:
+        return "collect_visitor_availability"
+    if is_landlord and not landlord_avail:
+        return "collect_landlord_availability"
+    if visitor_avail and not landlord_avail:
+        return "collect_landlord_availability"
+    if landlord_avail and not visitor_avail:
+        return "collect_visitor_availability"
+    return "cross_check"
+
+
+# ============================================================
+# TOOL FILTER — only broker-relevant tools
+# ============================================================
+
+BROKER_TOOL_NAMES = {
+    "search_properties",
+    "analyze_listing",
+    "get_landlord_info",
+    "get_price_trends",
+    "get_market_insights",
+    "schedule_visit",
+    "check_calendar_availability",
+    "confirm_viewing",
+    "cancel_viewing",
+    "create_alert",
+    "delete_alert",
+    "get_my_alerts",
+    "pause_alert",
+    "resume_alert",
+    "send_viewing_reminder",
+    "send_post_viewing_followup",
+    "submit_person_review",
+    "remember_preference",
+    "track_user_feedback",
+    "respond",
+}

app/ai/agent/concierge_brain.py

@@ -0,0 +1,291 @@
+# app/ai/agent/concierge_brain.py
+"""
+AIDA-Primary — The Concierge Brain
+
+Domain: Short-stay bookings, guest relations, booking flow, post-stay reviews.
+
+Triggered when:
+  - User clicks "Book" or "Help me choose" on a short-stay listing
+  - General brain detects short-stay / travel / booking intent
+
+Responsibilities:
+  - End-to-end booking flow (availability check, payment trigger)
+  - Pre-check-in reminder via AIDA DM (3 hours before)
+  - Post-checkout review collection via AIDA DM → saved to PROPERTY profile
+  - Short-stay property comparison to help user decide
+  - Handoff to other agents when intent is outside short-stay
+"""
+
+from structlog import get_logger
+from bson import ObjectId
+
+from app.ai.agent.state import AgentState
+from app.ai.agent.brain import (
+    brain_decide,
+    execute_tool,
+    generate_localized_response,
+    generate_contextual_response,
+)
+from app.ai.lightning.rewards import log_reward, REWARD_SEARCH_COMPLETED
+
+logger = get_logger(__name__)
+
+# ============================================================
+# CONCIERGE IDENTITY
+# ============================================================
+
+AGENT_ID = "concierge"
+AGENT_NAME = "AIDA-Primary"
+AGENT_DOMAIN = "short-stay, booking flow, guest relations, post-stay reviews"
+
+OWNED_LISTING_TYPES = {"short-stay", "short_stay"}
+
+CONCIERGE_TOOLS = """
+AVAILABLE TOOLS (use ONLY these):
+
+SEARCH & COMPARISON (before booking):
+1. search_properties(query, location, min_price, max_price, beds, listing_type)
+   - Find short-stay properties. ALWAYS set listing_type="short-stay".
+   - Trigger: "trip", "stay", "accommodation", "weekend", "holiday", "travel", "book a place"
+
+2. analyze_listing(listing_id)
+   - Deep overview of a specific short-stay property.
+   - Use when user taps "Tell me more" or asks about a specific listing.
+
+3. compare_properties(listing_ids)
+   - Compare 2–4 short-stay properties side by side.
+   - Trigger: user taps "Help me choose", "which is better", "compare these".
+
+4. get_price_trends(location)
+   - Short-stay market price data for an area.
+
+BOOKING FLOW:
+5. check_availability(listing_id, check_in, check_out)
+   - Verify a property is free for the requested dates.
+
+6. calculate_booking_cost(listing_id, check_in, check_out, guests)
+   - Show total cost breakdown before user commits (nightly rate + fees).
+
+7. initiate_booking(listing_id, check_in, check_out, guests)
+   - Start the booking transaction. Triggers payment flow.
+
+8. confirm_booking(booking_id)
+   - Finalize a booking after payment is authorised.
+
+9. cancel_booking(booking_id, reason)
+   - Cancel an existing booking.
+
+10. get_my_bookings()
+    - List user's upcoming and past short-stay bookings.
+
+NOTIFICATIONS (triggered by booking events):
+11. send_checkin_reminder(booking_id, guest_user_id)
+    - Send AIDA DM reminder to guest 3 hours before check-in.
+    - Also notify host 3 hours before.
+
+12. send_checkout_review_request(booking_id, guest_user_id)
+    - Send AIDA DM to guest after checkout asking for their review.
+    - Message: conversational, warm — not a form.
+
+13. submit_property_review(listing_id, booking_id, rating, review_text)
+    - Save the guest's rating and review to the PROPERTY profile.
+    - Triggered after guest responds to the review request.
+
+ALERTS:
+14. create_alert(criteria)
+    - Notify user when a matching short-stay appears.
+15. delete_alert(alert_id) / pause_alert(alert_id) / resume_alert(alert_id)
+16. get_my_alerts()
+
+GENERAL:
+17. remember_preference(key, value, category)
+    - Save guest preference (areas, budget, amenities, travel style).
+
+18. track_user_feedback(feedback_type, context, correction_text)
+    - Log corrections or negative reactions silently.
+
+19. respond(message)
+    - General chat, trip planning, booking clarification, empathy.
+
+HANDOFF SIGNALS (do NOT handle — return handoff instead):
+- Long-term rental or property sale intent → set tool: "HANDOFF_BROKER"
+- Roommate search intent → set tool: "HANDOFF_MATCHER"
+"""
+
+CONCIERGE_SYSTEM_PROMPT = """You are AIDA-Primary, the short-stay concierge on Lojiz.
+
+YOUR SPECIALTY: Helping guests find, compare, and book short-stay properties —
+and making sure their experience is great from booking to checkout.
+
+YOUR PERSONALITY:
+- Warm, fast, and traveller-friendly
+- Think like a knowledgeable local friend who knows the best places to stay
+- Proactive: if user mentions a trip or travel, start searching immediately
+- Empathetic: acknowledge emotional context (honeymoon, work trip, family visit) before showing results
+- You follow through — you don't just book and disappear
+
+═══════════════════════════════════════════════
+BOOKING FLOW (your core job)
+═══════════════════════════════════════════════
+
+When user taps "Book" or "Help me choose" on a listing:
+
+1. Call check_availability for their requested dates.
+2. Call calculate_booking_cost so they see the full price before committing.
+3. On user confirmation → call initiate_booking → triggers payment.
+4. Payment authorised → call confirm_booking → send confirmation via AIDA DM.
+5. 3 hours before check-in → call send_checkin_reminder for both guest and host.
+6. After checkout → call send_checkout_review_request to the guest.
+7. Guest replies (voice or text) → extract rating + review → call submit_property_review.
+   The review is saved to the PROPERTY profile for future guests to see.
+
+═══════════════════════════════════════════════
+POST-CHECKOUT REVIEW (conversational, not a form)
+═══════════════════════════════════════════════
+
+After checkout send via AIDA DM:
+  "Hey! Hope you had a great stay at [property name] 🏠
+   How was it? Drop a rating (1–5 ⭐) and tell me anything you want other guests to know."
+
+User can respond by text or voice note. Extract the rating and review text naturally.
+Save it to the property profile with submit_property_review.
+
+═══════════════════════════════════════════════
+YOUR RULES
+═══════════════════════════════════════════════
+1. Short-stay ONLY. Long-term/sale → HANDOFF_BROKER. Roommate → HANDOFF_MATCHER.
+2. When user gives location + travel context, call search_properties immediately. No unnecessary questions.
+3. Suggest alerts warmly when nothing is found — never robotically.
+4. Respond entirely in the user's detected language.
+5. Never mention "HANDOFF", agent names, or internal routing to the user.
+6. Listing creation is handled elsewhere — do NOT run listing flows here.
+"""
+
+
+# ============================================================
+# MAIN ENTRY POINT
+# ============================================================
+
+async def process(state: AgentState) -> AgentState:
+    """
+    Concierge brain entry point.
+    Handles short-stay booking flow, pre-checkin reminders, post-checkout reviews.
+    """
+    logger.info("AIDA-Primary activated", user_id=state.user_id, message=state.last_user_message[:60])
+
+    state.temp_data["active_agent"] = AGENT_ID
+    state.temp_data["agent_system_prompt"] = CONCIERGE_SYSTEM_PROMPT
+    state.temp_data["agent_tools"] = CONCIERGE_TOOLS
+
+    try:
+        decision = await brain_decide(state)
+    except Exception as e:
+        logger.error("Concierge brain_decide failed", error=str(e))
+        state.temp_data["response_text"] = await generate_localized_response(
+            context="Tell the user there was a temporary issue and you're back now. Ask how you can help.",
+            language=state.language_detected or state.app_language or "en",
+            tone="apologetic",
+            max_length="short",
+        )
+        state.temp_data["action"] = "respond"
+        return state
+
+    # Handoff signals
+    if decision.tool in ("HANDOFF_BROKER", "HANDOFF_MATCHER"):
+        state.temp_data["handoff"] = decision.tool
+        state.temp_data["handoff_reason"] = decision.thinking
+        logger.info("Concierge signalling handoff", target=decision.tool)
+        return state
+
+    # Execute tool
+    if decision.tool and decision.tool != "respond":
+        try:
+            success, message, result = await execute_tool(decision.tool, decision.params, state)
+            if not success:
+                logger.warning("Concierge tool failed", tool=decision.tool, message=message)
+        except Exception as e:
+            logger.error("Concierge tool execution error", tool=decision.tool, error=str(e))
+
+    # Generate response
+    if decision.tool in ("search_properties", "compare_properties"):
+        try:
+            log_reward(REWARD_SEARCH_COMPLETED, state.user_id, {"agent": AGENT_ID})
+        except Exception:
+            pass
+        state.temp_data["response_text"] = await generate_contextual_response(state, decision)
+    elif not state.temp_data.get("response_text"):
+        if decision.response:
+            state.temp_data["response_text"] = decision.response
+        else:
+            state.temp_data["response_text"] = await generate_contextual_response(state, decision)
+
+    return state
+
+
+# ============================================================
+# CONTEXT LOADER — session resume
+# ============================================================
+
+async def load_context(state: AgentState) -> AgentState:
+    """
+    Called on session resume. Loads the user's most recent active booking
+    into state.agent_context["booking"] so the brain has full context without
+    needing to ask the user to re-explain what they were doing.
+    """
+    try:
+        from app.database import get_db
+        db = await get_db()
+
+        booking = await db["bookings"].find_one(
+            {
+                "user_id": state.user_id,
+                "status": {"$in": ["Pending", "Confirmed", "ActiveStay"]},
+            },
+            sort=[("created_at", -1)],
+        )
+
+        if booking:
+            booking["_id"] = str(booking["_id"])
+            state.agent_context["booking"] = booking
+            logger.info(
+                "Concierge context loaded",
+                user_id=state.user_id,
+                booking_id=booking["_id"],
+                status=booking.get("status"),
+            )
+        else:
+            logger.info("Concierge context: no active booking found", user_id=state.user_id)
+
+    except Exception as e:
+        logger.warning("Concierge load_context failed (non-fatal)", error=str(e))
+
+    return state
+
+
+# ============================================================
+# TOOL FILTER — only concierge-relevant tools
+# ============================================================
+
+CONCIERGE_TOOL_NAMES = {
+    "search_properties",
+    "analyze_listing",
+    "compare_properties",
+    "get_price_trends",
+    "check_availability",
+    "calculate_booking_cost",
+    "initiate_booking",
+    "confirm_booking",
+    "cancel_booking",
+    "get_my_bookings",
+    "send_checkin_reminder",
+    "send_checkout_review_request",
+    "submit_property_review",
+    "create_alert",
+    "delete_alert",
+    "get_my_alerts",
+    "pause_alert",
+    "resume_alert",
+    "remember_preference",
+    "track_user_feedback",
+    "respond",
+}

app/ai/agent/dm_brain.py

@@ -164,7 +164,17 @@ DM_TOOLS = """
 
 
 class DmBrain:
-    async def process(self, message: str, user_id: str, source: str = "dm", reply_context: Optional[dict] = None, user_role: str = "renter", app_language: Optional[str] = None) -> Any:
+    async def process(
+        self,
+        message: str,
+        user_id: str,
+        source: str = "dm",
+        reply_context: Optional[dict] = None,
+        user_role: str = "renter",
+        app_language: Optional[str] = None,
+        user_name: Optional[str] = None,
+        user_location: Optional[str] = None,
+    ) -> Any:
         # Initialize state
         state = AgentState(
             user_id=user_id,
@@ -172,13 +182,50 @@ class DmBrain:
             user_role=user_role,
             source=source,
             last_user_message=message,
+            user_name=user_name,
+            user_location=user_location,
         )
         if app_language:
             state.app_language = app_language
         if reply_context:
             state.temp_data["reply_context"] = reply_context
-            
+
         logger.info("DM Brain processing message", user_id=user_id, message=message[:50])
+
+        # ── Agent Hub routing for general search / listing / roommate intents ──
+        # DM-Brain handles DM-specific tools (alerts, booking, overview, landlord).
+        # For broader intents that need a specialist (broker/concierge/matcher),
+        # delegate to the hub and convert its AgentState back to a DM response dict.
+        import re as _re_hub
+        _is_booking_tag = bool(_re_hub.search(r'\[BOOKING_OVERVIEW:([\w]+)\]', message))
+        _dm_specific_signals = [
+            "my alert", "my alerts", "notify me", "alert me", "book it",
+            "book this", "check in", "check out", "is anyone checking",
+            "my bookings", "booking summary", "pursue", "stop searching",
+            "resume my search", "found my place", "i got it", "deal fell through",
+        ]
+        _needs_hub = not _is_booking_tag and not any(s in message.lower() for s in _dm_specific_signals)
+
+        if _needs_hub:
+            from app.ai.agent.agent_hub import classify_intent as hub_classify
+            hub_intent = await hub_classify(message, state, current_agent=None)
+            if hub_intent in ("concierge", "broker", "matcher"):
+                try:
+                    from app.ai.agent.agent_hub import run as hub_run
+                    state = await hub_run(state)
+                    return {
+                        "text": state.temp_data.get("response_text", ""),
+                        "metadata": {
+                            "action": state.temp_data.get("action", "respond"),
+                            "active_agent": state.temp_data.get("active_agent"),
+                            **{k: v for k, v in state.temp_data.items()
+                               if k in ("search_results", "my_listings", "draft", "draft_ui",
+                                        "alert_results", "comparison_data")},
+                        },
+                        "action": state.temp_data.get("action", "respond"),
+                    }
+                except Exception as hub_err:
+                    logger.warning("Hub routing failed in DM, falling through to dm_brain", error=str(hub_err))
         
         try:
             # Fast-path: detect [BOOKING_OVERVIEW:id] tag — skip LLM routing

app/ai/agent/graph.py

@@ -17,7 +17,7 @@ from structlog import get_logger
 from app.ai.agent.state import AgentState, FlowState
 from app.ai.lightning.tracer import wrap_graph_if_enabled
 from app.ai.agent.nodes.authenticate import authenticate
-from app.ai.agent.brain import agent_think
+from app.ai.agent.agent_hub import run as hub_run
 from app.ai.agent.nodes.validate_output import validate_output_node
 from app.ai.agent.nodes.respond import respond_to_user
 from app.ai.agent.nodes.listing_publish import listing_publish_handler
@@ -67,8 +67,8 @@ def build_aida_graph():
     # 1. Authenticate user
     graph.add_node("authenticate", authenticate)
     
-    # 2. Brain thinks and acts (THE CORE)
-    graph.add_node("brain", agent_think)
+    # 2. Agent Hub — routes to the right specialist brain (THE CORE)
+    graph.add_node("brain", hub_run)
     
     # 3. Publish flow (for DB operations)
     graph.add_node("publish", listing_publish_handler)

app/ai/agent/matcher_brain.py

@@ -0,0 +1,313 @@
+# app/ai/agent/matcher_brain.py
+"""
+AIDA-Social — The Roommate Matcher Brain
+
+Domain: Co-living compatibility, roommate discovery, lifestyle-first matching,
+        double opt-in gating.
+
+Two flows:
+  HOST   — Has a space, wants to find the right person to share with.
+           Routed here when someone lists a roommate space OR says they have a
+           place and want a roommate.
+  SEEKER — No place yet, looking to join someone's space.
+           Routed here when someone says they're looking for a room to share.
+
+Both flows build a lifestyle profile and enter the same matching pool.
+The double opt-in shield ensures neither party gets the other's contact until
+both have confirmed interest.
+"""
+
+from structlog import get_logger
+from bson import ObjectId
+
+from app.ai.agent.state import AgentState
+from app.ai.agent.brain import (
+    brain_decide,
+    execute_tool,
+    generate_localized_response,
+    generate_contextual_response,
+)
+
+logger = get_logger(__name__)
+
+# ============================================================
+# MATCHER IDENTITY
+# ============================================================
+
+AGENT_ID = "matcher"
+AGENT_NAME = "AIDA-Social"
+AGENT_DOMAIN = "roommate matching, co-living, lifestyle compatibility"
+
+OWNED_LISTING_TYPES = {"roommate"}
+
+MATCHER_TOOLS = """
+AVAILABLE TOOLS (use ONLY these):
+
+SEARCH & DISCOVERY:
+1. search_properties(query, location, min_price, max_price, beds, listing_type)
+   - Always set listing_type="roommate".
+   - Use ONLY after extracting the user's lifestyle profile from their free-form message.
+
+2. analyze_listing(listing_id)
+   - Deep profile of a shared living space and its current occupant(s).
+
+3. create_alert(criteria)
+   - Notify user when a matching roommate listing appears.
+
+4. delete_alert(alert_id) / pause_alert(alert_id) / resume_alert(alert_id)
+5. get_my_alerts()
+6. get_price_trends(location)
+
+LISTING MANAGEMENT (HOST flow only):
+7. update_listing(fields, list_mode, replace_index)
+   - listing_type is always "roommate".
+   - Collect: location, price, available rooms, house rules, preferred flatmate lifestyle.
+
+8. edit_listing(listing_id)
+9. publish_listing()
+10. delete_listing(listing_id)
+11. get_my_listings()
+12. geocode_address(address)
+
+PROFILE & COMPATIBILITY:
+13. remember_preference(key, value, category)
+    - Save extracted lifestyle data. Call once per extracted field.
+    - Keys: sleep_schedule, cleanliness, pets, smoking, wfh, social_preference,
+            budget, location, move_in_date, gender_preference, occupation
+
+14. track_user_feedback(feedback_type, context, correction_text)
+
+15. respond(message)
+    - Free-form open question, follow-up if something is missing, compatibility summary.
+
+HANDOFF SIGNALS (do NOT handle — return handoff instead):
+- Short-stay accommodation intent → set tool: "HANDOFF_CONCIERGE"
+- Long-term rental or sale intent → set tool: "HANDOFF_BROKER"
+"""
+
+MATCHER_SYSTEM_PROMPT = """You are AIDA-Social, the roommate matching specialist on Lojiz.
+
+YOUR SPECIALTY: Lifestyle-first co-living discovery. You find compatible people, not just available rooms.
+
+YOUR PERSONALITY:
+- Friendly, perceptive, socially intelligent
+- You listen deeply and extract meaning from natural, free-flowing messages
+- You are a discreet gatekeeper who protects users from unwanted contact
+- You celebrate great matches — it's genuinely exciting when lifestyles align
+
+═══════════════════════════════════════════════
+TWO FLOWS — DETECT WHICH ONE THIS IS
+═══════════════════════════════════════════════
+
+SEEKER FLOW — User has no place, wants to join someone's space
+  Trigger: "looking for a room", "need a flatmate", "want to share", "find a roommate"
+  Opening: "Tell me a bit about yourself and what you're looking for in a place and a flatmate —
+            lifestyle, schedule, habits, anything on your mind. Voice or text, whatever works."
+
+HOST FLOW — User has a space, wants to find the right person
+  Trigger: "I have a 2-bedroom", "looking for someone to share with me", "list my room",
+           "want a roommate for my place", or roommate listing type detected
+  Opening: "Tell me about yourself and the kind of person you'd love to share your space with —
+            your lifestyle, your vibe, any house rules, anything you want them to know."
+
+═══════════════════════════════════════════════
+FREE-FORM EXTRACTION — HOW IT WORKS
+═══════════════════════════════════════════════
+
+Step 1 — Ask ONE open question (the opening above). Do NOT ask a Q&A form.
+
+Step 2 — Extract ALL lifestyle signals from their free-form response:
+  • sleep_schedule  (early bird / night owl / flexible)
+  • cleanliness     (relaxed / moderate / very tidy)
+  • pets            (has pets / no pets / allergic)
+  • smoking         (smoker / non-smoker / outdoor only)
+  • wfh             (never / sometimes / full-time)
+  • social_preference (quiet / moderate / social)
+  • budget          (price range)
+  • location        (area/city)
+  • move_in_date    (when they want to move)
+  • gender_preference (if stated)
+  • occupation      (if stated — affects schedule compatibility)
+
+Step 3 — Save each extracted signal with remember_preference.
+
+Step 4 — If ONE critical field is missing (location or budget), ask exactly ONE follow-up.
+  Never ask more than one follow-up question. If other fields are missing, infer or leave blank.
+
+Step 5 — Search for matches. Present results showing WHY each is compatible
+  (e.g. "Both night owls, both non-smokers, similar cleanliness standards").
+
+═══════════════════════════════════════════════
+DOUBLE OPT-IN SHIELD (NON-NEGOTIABLE)
+═══════════════════════════════════════════════
+
+When showing a match, NEVER share contact details, full name, or exact address.
+Instead say: "I'll send them a summary of your profile. If they're interested too, I'll connect you."
+Only open contact after BOTH parties confirm interest.
+This protects everyone from harassment.
+
+═══════════════════════════════════════════════
+YOUR RULES
+═══════════════════════════════════════════════
+1. Roommate/co-living ONLY.
+   Short-stay → HANDOFF_CONCIERGE. Long-term/sale → HANDOFF_BROKER.
+2. If a renter asks to list for rent or sale (not roommate), tell them:
+   "On Lojiz, renters can list a shared space to find a roommate — listing for
+    full rent or sale is for landlords. Want to post a roommate listing instead?"
+   Do NOT hand off — just explain and offer the roommate option.
+3. Never share another user's personal details before double opt-in.
+4. One open question → extract → at most one follow-up. Never a questionnaire.
+5. Respond entirely in the user's detected language.
+6. Never mention "HANDOFF" or internal agent names to the user.
+"""
+
+
+# ============================================================
+# MAIN ENTRY POINT
+# ============================================================
+
+async def process(state: AgentState) -> AgentState:
+    """
+    Matcher brain entry point.
+    Handles both HOST and SEEKER flows via free-form extraction.
+    """
+    logger.info("AIDA-Social activated", user_id=state.user_id, message=state.last_user_message[:60])
+
+    state.temp_data["active_agent"] = AGENT_ID
+    state.temp_data["agent_system_prompt"] = MATCHER_SYSTEM_PROMPT
+    state.temp_data["agent_tools"] = MATCHER_TOOLS
+
+    try:
+        decision = await brain_decide(state)
+    except Exception as e:
+        logger.error("Matcher brain_decide failed", error=str(e))
+        state.temp_data["response_text"] = await generate_localized_response(
+            context="Tell the user there was a brief issue and you're ready to help them find the perfect roommate.",
+            language=state.language_detected or state.app_language or "en",
+            tone="apologetic",
+            max_length="short",
+        )
+        state.temp_data["action"] = "respond"
+        return state
+
+    # Handoff signals
+    if decision.tool in ("HANDOFF_CONCIERGE", "HANDOFF_BROKER"):
+        state.temp_data["handoff"] = decision.tool
+        state.temp_data["handoff_reason"] = decision.thinking
+        logger.info("Matcher signalling handoff", target=decision.tool)
+        return state
+
+    # Execute tool
+    if decision.tool and decision.tool != "respond":
+        try:
+            success, message, result = await execute_tool(decision.tool, decision.params, state)
+            if not success:
+                logger.warning("Matcher tool failed", tool=decision.tool, message=message)
+        except Exception as e:
+            logger.error("Matcher tool execution error", tool=decision.tool, error=str(e))
+
+    # Generate response
+    if decision.tool == "search_properties":
+        state.temp_data["response_text"] = await generate_contextual_response(state, decision)
+    elif not state.temp_data.get("response_text"):
+        if decision.response:
+            state.temp_data["response_text"] = decision.response
+        else:
+            state.temp_data["response_text"] = await generate_contextual_response(state, decision)
+
+    return state
+
+
+# ============================================================
+# CONTEXT LOADER — session resume
+# ============================================================
+
+async def load_context(state: AgentState) -> AgentState:
+    """
+    Called on session resume. Loads the user's active matcher profile:
+    - HOST: their most recent published roommate listing (with preferred_flatmate)
+    - SEEKER: their stored lifestyle preferences (from user profile or listings collection)
+
+    Both are placed in state.agent_context["matcher_profile"] so the brain
+    can resume the conversation naturally — e.g. "Still looking for a flatmate?"
+    instead of starting from scratch.
+    """
+    try:
+        from app.database import get_db
+        db = await get_db()
+
+        profile: dict = {}
+
+        # 1. Check if user has an active roommate HOST listing
+        host_listing = await db["listings"].find_one(
+            {
+                "user_id": state.user_id,
+                "listing_type": "roommate",
+                "status": {"$in": ["published", "active", "pending"]},
+            },
+            sort=[("created_at", -1)],
+        )
+
+        if host_listing:
+            host_listing["_id"] = str(host_listing["_id"])
+            profile["flow"] = "host"
+            profile["listing"] = host_listing
+            profile["preferred_flatmate"] = host_listing.get("preferred_flatmate", {})
+            logger.info(
+                "Matcher context: host flow",
+                user_id=state.user_id,
+                listing_id=host_listing["_id"],
+            )
+        else:
+            # 2. Seeker — load lifestyle prefs from user profile
+            user_doc = await db["users"].find_one(
+                {"_id": ObjectId(state.user_id)},
+                {"lifestyle_prefs": 1, "roommate_seeker": 1},
+            )
+            if user_doc:
+                seeker_data = user_doc.get("roommate_seeker") or user_doc.get("lifestyle_prefs") or {}
+                if seeker_data:
+                    profile["flow"] = "seeker"
+                    profile["lifestyle_prefs"] = seeker_data
+                    logger.info(
+                        "Matcher context: seeker flow",
+                        user_id=state.user_id,
+                        fields=list(seeker_data.keys()),
+                    )
+                else:
+                    logger.info("Matcher context: seeker with no stored prefs yet", user_id=state.user_id)
+                    profile["flow"] = "seeker"
+                    profile["lifestyle_prefs"] = {}
+
+        if profile:
+            state.agent_context["matcher_profile"] = profile
+
+    except Exception as e:
+        logger.warning("Matcher load_context failed (non-fatal)", error=str(e))
+
+    return state
+
+
+# ============================================================
+# TOOL FILTER — only matcher-relevant tools
+# ============================================================
+
+MATCHER_TOOL_NAMES = {
+    "search_properties",
+    "analyze_listing",
+    "create_alert",
+    "delete_alert",
+    "get_my_alerts",
+    "pause_alert",
+    "resume_alert",
+    "get_price_trends",
+    "update_listing",
+    "edit_listing",
+    "publish_listing",
+    "delete_listing",
+    "get_my_listings",
+    "geocode_address",
+    "remember_preference",
+    "track_user_feedback",
+    "respond",
+}

app/ai/agent/nodes/listing_collect.py

@@ -470,7 +470,7 @@ async def listing_collect_handler(state: AgentState) -> AgentState:
             # IMPORTANT: Only sync raw data fields - NOT translated content fields
             # amenities, requirements are stored in user's original language in provided_fields
             # but listing_draft may have LLM-translated versions - preserve those
-            sync_fields = ["location", "address", "latitude", "longitude", "bedrooms", "bathrooms", "price", "price_type", "images"]
+            sync_fields = ["location", "address", "latitude", "longitude", "bedrooms", "bathrooms", "price", "price_type", "images", "preferred_flatmate"]
             for field in sync_fields:
                 value = state.provided_fields.get(field)
                 if value is not None and field in state.listing_draft:
@@ -602,6 +602,7 @@ async def listing_collect_handler(state: AgentState) -> AgentState:
                         "amenities": state.listing_draft.get("amenities", []),
                         "images": state.listing_draft.get("images", []),
                         "listing_type": state.listing_draft.get("listing_type"),
+                        "preferred_flatmate": state.listing_draft.get("preferred_flatmate") or {},
                         "updated_at": datetime.utcnow(),
                     }
                     

app/ai/agent/nodes/listing_publish.py

@@ -275,6 +275,7 @@ async def listing_publish_handler(state: AgentState) -> AgentState:
             "images": draft.images,
             "video": draft.video,
             "video_thumbnail": draft.video_thumbnail,
+            "preferred_flatmate": draft.preferred_flatmate or {},  # Populated for roommate listings
             "status": "active",
             "created_at": datetime.utcnow(),
             "updated_at": datetime.utcnow(),

app/ai/agent/planner.py

@@ -81,6 +81,21 @@ async def detect_complexity(user_message: str, state) -> bool:
         logger.info("Complexity detection: edit/update operation → single-tool", message=user_message[:60])
         return False
 
+    # Fast-path: market price / price trends are always single-tool (get_price_trends)
+    price_keywords = ["market price", "market prices", "prix du marché", "precio del mercado",
+                      "price trend", "average price", "how much does it cost", "average cost",
+                      "prix moyen", "combien ça coûte", "💰"]
+    if any(pk in msg_lower for pk in price_keywords):
+        logger.info("Complexity detection: market price query → single-tool", message=user_message[:60])
+        return False
+
+    # Fast-path: single-entity search requests are always single-tool
+    single_search_keywords = ["find me", "show me", "search for", "look for", "i want to find",
+                               "find a", "find an", "show a", "i need a place", "looking for a place"]
+    if any(sk in msg_lower for sk in single_search_keywords) and "and" not in msg_lower and "also" not in msg_lower:
+        logger.info("Complexity detection: single search → single-tool", message=user_message[:60])
+        return False
+
     prompt = f"""Analyze this user request and determine if it requires multiple steps/tools to complete.
 
 User request: "{user_message}"
@@ -93,13 +108,15 @@ Does this request need 2 or more DIFFERENT tools to fulfill completely?
 
 ALWAYS answer "no" for these (they are conversational single-tool flows):
 - ANY edit, update, modify, change, or delete request → "no" (these need user interaction)
+- ANY market price / price trend query → "no" (just get_price_trends)
+- "market prices" → "no"
+- "💰 Market prices" → "no"
 - "edit my listing" → "no"
-- "update the price on my listing" → "no"
-- "delete my listing" → "no"
-- "publish my listing" → "no"
 - "find me apartments" → "no" (just search_properties)
 - "show my listings" → "no" (just get_my_listings)
 - "find houses in Nigeria" → "no" (search handles location expansion)
+- "I want to buy a house in Lagos" → "no" (just search_properties)
+- "I'm planning a trip to Lagos, where can I stay?" → "no" (just search_properties short-stay)
 
 Answer "yes" ONLY when user explicitly asks for 2+ distinct actions in one message:
 - "find apartments in Paris AND set up an alert" → "yes" (search + create_alert)

app/ai/agent/schema.py

@@ -111,14 +111,43 @@ LISTING_FIELDS = {
         "description": "Geocoded longitude. Auto from address",
         "required": False,
         "auto_infer": True
+    },
+    "preferred_flatmate": {
+        "type": "object",
+        "description": (
+            "Roommate listings only. Lifestyle profile of the ideal flatmate. "
+            "Fields: sleep_schedule (early bird|night owl|flexible), "
+            "cleanliness (very clean|average|relaxed), pets (bool), "
+            "smoking (bool — indoor OK?), wfh (bool), "
+            "social_preference (social|quiet|balanced), "
+            "gender_preference (any|male|female|non-binary), "
+            "move_in_date (ISO string), occupation (string), "
+            "age_preference (string), notes (string)."
+        ),
+        "required": False,
+        "roommate_only": True,
+        "example": {
+            "sleep_schedule": "flexible",
+            "cleanliness": "very clean",
+            "pets": False,
+            "smoking": False,
+            "wfh": True,
+            "social_preference": "balanced",
+            "gender_preference": "any",
+            "move_in_date": "2025-07-01",
+            "occupation": "professional",
+            "age_preference": "any",
+            "notes": ""
+        }
     }
 }
 
 # Required fields by listing type
 REQUIRED_BY_TYPE = {
-    "rent": ["location", "address", "bedrooms", "bathrooms", "price", "price_type", "images"],
-    "sale": ["location", "address", "bedrooms", "bathrooms", "price", "images"],
-    "short-stay": ["location", "address", "bedrooms", "bathrooms", "price", "price_type", "images"]
+    "rent":       ["location", "address", "bedrooms", "bathrooms", "price", "price_type", "images"],
+    "sale":       ["location", "address", "bedrooms", "bathrooms", "price", "images"],
+    "short-stay": ["location", "address", "bedrooms", "bathrooms", "price", "price_type", "images"],
+    "roommate":   ["location", "bedrooms", "price", "price_type"],  # preferred_flatmate added after lifestyle interview
 }
 
 # Price type → Listing type inference
@@ -159,6 +188,12 @@ def get_schema_for_llm() -> str:
     lines.append("• nightly/daily price → short-stay")
     lines.append("• one-time price → sale")
     lines.append("• monthly/yearly price → rent")
+    lines.append("• shared space / roommate context → roommate")
+    lines.append("• renter role → always roommate")
+    lines.append("\n=== ROOMMATE LISTINGS ===")
+    lines.append("• After standard fields: ask ONE lifestyle question")
+    lines.append("• Extract preferred_flatmate object from free-form answer")
+    lines.append("• Save to listing document (NOT user profile)")
     
     return "\n".join(lines)
 

app/ai/agent/schemas.py

@@ -80,6 +80,7 @@ class ListingDraft(BaseModel):
     images: List[str] = Field(default_factory=list)
     video: Optional[str] = None  # Video URL (R2 temp → Cloudinary permanent on publish)
     video_thumbnail: Optional[str] = None  # Video thumbnail URL
+    preferred_flatmate: Optional[Dict[str, Any]] = None  # Roommate listings only — lifestyle profile of ideal flatmate
 
     @validator("images")
     def validate_image_urls(cls, v):
@@ -109,6 +110,7 @@ class ListingExtracted(BaseModel):
     images: List[str] = Field(default_factory=list)
     video: Optional[str] = None
     video_thumbnail: Optional[str] = None
+    preferred_flatmate: Optional[Dict[str, Any]] = None  # Extracted from lifestyle interview (roommate only)
 
 
 # ============================================================

app/ai/agent/state.py

@@ -100,6 +100,15 @@ class AgentState(BaseModel):
     retries: int = 0
     max_retries: int = 3
     
+    # Active specialist agent — persisted to DB so it survives session resume.
+    # Values: "general" | "concierge" | "broker" | "matcher"
+    # None means: not yet set (hub will classify on next message).
+    active_agent: Optional[str] = None
+
+    # Loaded by each specialist brain's context loader on session resume.
+    # Concierge loads booking doc, Broker loads viewing doc, Matcher loads profile.
+    agent_context: Dict[str, Any] = Field(default_factory=dict)
+
     # Temporary data for current operation
     temp_data: Dict[str, Any] = Field(default_factory=dict)
     

app/ai/prompts/system_prompt.py

@@ -137,6 +137,15 @@ REQUIRED FIELDS TO COLLECT:
 - Amenities (optional but ask: wifi, parking, furnished, washing machine, ac, balcony, etc.)
 - Requirements (optional but ask: "3-month deposit", "no pets", "stable income", etc.)
 
+EXTRA FEES QUESTION (rent and sale listings ONLY — never ask for short-stay or roommate):
+After collecting requirements, ask ONE additional question:
+  "Are there any extra charges the {{"renter" if rent else "buyer"}} should know about upfront?
+   For example: agency/consultation fee, inspection fee, legal fees, service charge, caution fee, etc."
+- If YES: save the fee details into the requirements field (e.g., "Agency fee: 10%", "Caution: 2 months")
+- If NO or "none": skip it, don't add anything
+- This ensures full transparency and protects users from hidden costs
+- Phrase the question naturally in the user's language
+
 IMPORTANT SALE HANDLING:
 - If user says "for sale", "sell", "selling" → listing_type = "sale", price_type = "one-time"
 - DO NOT ask "is it monthly or yearly?" for sales - sales are ALWAYS one-time purchases!
@@ -226,8 +235,49 @@ Description Generation:
 - Example: "Spacious 3-bedroom, 2-bathroom rental in Lagos with wifi, parking, and balcony. Priced at 50,000 NGN per month. Tenants must provide 3-month security deposit."
 - CRITICAL: Always ensure at least 3 complete sentences
 
+STEP 4B: ROOMMATE LIFESTYLE INTERVIEW (ONLY when listing_type = "roommate")
+
+Trigger: After collecting standard listing fields AND auto-detecting listing_type = "roommate"
+This applies to BOTH landlords sharing a room AND renters listing their space.
+
+WHY: The Matcher agent needs lifestyle compatibility data attached to THIS LISTING
+(not just the user's profile). Flatmate search uses this to find compatible matches.
+
+HOW — Ask ONE open-ended question (after standard fields are done):
+
+  "One more thing — tell me a bit about yourself and the kind of person you'd love to share with!
+   Things like your sleep schedule, how tidy you like things, whether you're okay with pets or
+   smoking indoors, if you work from home, that kind of vibe 🏠"
+
+EXTRACT these lifestyle fields from their free-form answer:
+
+  sleep_schedule      → "early bird" | "night owl" | "flexible"
+  cleanliness         → "very clean" | "average" | "relaxed"
+  pets                → true | false (are pets welcome?)
+  smoking             → true | false (is indoor smoking okay?)
+  wfh                 → true | false (do they / will flatmate work from home?)
+  social_preference   → "social" | "quiet" | "balanced"
+  gender_preference   → "any" | "male" | "female" | "non-binary"
+  move_in_date        → ISO date string e.g. "2025-06-01" (when do they want someone?)
+  occupation          → string e.g. "student", "professional", "remote worker" (optional)
+  age_preference      → string e.g. "20s", "any", "25-35" (optional, if mentioned)
+  notes               → any extra details that don't fit above categories
+
+SAVE all extracted fields into:  listing.preferred_flatmate = {{ ...extracted fields }}
+
+This is SEPARATE from the user's profile — it lives on the listing document so the
+Matcher agent can score compatibility between seekers and this specific listing.
+
+IF the user gives a short or vague answer (e.g. "I'm chill with anything"):
+- Extract what you can, default unmentioned fields to permissive values:
+  sleep_schedule="flexible", cleanliness="average", pets=true, smoking=false,
+  social_preference="balanced", gender_preference="any"
+- Do NOT interrogate further — one question is the limit.
+
+AFTER the lifestyle question is answered → proceed to STEP 5 as normal.
+
 STEP 5: WHEN ALL FIELDS COLLECTED
-Once all required fields complete:
+Once all required fields complete (including preferred_flatmate for roommate listings):
 - Say a SHORT confirmation message like "Perfect! Here's your listing preview:"
 - DO NOT write out the draft in text - the UI will display a visual card automatically
 - Just ask: "Ready to publish? Say 'publish', 'edit [field]' to change, or 'discard' to cancel."
@@ -407,8 +457,26 @@ SMART INTENT DETECTION — be proactive, do NOT wait for explicit "search" comma
 - "Short stay in Abuja" → search_properties, listing_type="short-stay", location="Abuja"
 - "Houses for sale" → search_properties, listing_type="sale"
 - "Any studios available in Ibadan?" → search_properties, listing_type="rent", location="Ibadan"
+- "I'm planning a trip to Lagos, I don't know where to stay" → search_properties, listing_type="short-stay", location="Lagos"
+- "Heading to Abuja next week, need accommodation" → search_properties, listing_type="short-stay", location="Abuja"
 Users do NOT need to say "show me" or "search for" — detect intent from context and call the tool.
 
+BROAD LOCATION INTELLIGENCE — You understand country-level searches:
+- "houses in Nigeria" → search across all major Nigerian cities (Lagos, Abuja, Owerri, Port Harcourt, etc.)
+- "apartments in Benin" → search across Cotonou, Porto-Novo, Parakou, etc.
+- The search engine handles this automatically — just pass the country name as location.
+
+MISSING LOCATION — If user gives NO location in a search request, ASK for it:
+- Do NOT silently assume a location. Always confirm with the user.
+- Example: "Find me a rental" → "Sure! Which city or area are you looking in? 😊"
+- Exception: For market price questions, use the user's profile location automatically — it makes sense to show them prices for where they live.
+
+EMPATHY IN CONTEXT — Respond with warmth when user shares personal situations:
+- "I'm planning a trip and I don't know where to stay" → "Don't worry, I've got you! Let me search for short-stay options right now..." → then search
+- "I'm moving to Lagos soon" → acknowledge the exciting move, then search for rentals
+- "I need a place urgently" → acknowledge the urgency, search immediately, skip small talk
+- Always ACTION first (start the search), then empathy words — not the other way around.
+
 NEVER say "go to your DM", "continue in DM", "the DM has booking tools" — these are internal details.
 The user experience is seamless: they search here, tap a card, booking opens automatically.
 
@@ -421,8 +489,9 @@ SIMPLIFIED LISTING FLOW:
 4. Extract fields, ask missing ones ONE at a time
 5. Ask about amenities/requirements (ONCE)
 6. Auto-detect: listing_type, currency, title, description
-7. Generate and show draft preview
-8. User: publish / edit / discard
+7. IF listing_type = "roommate" → Ask ONE lifestyle question → Extract + save preferred_flatmate to listing
+8. Generate and show draft preview
+9. User: publish / edit / discard
 
 NO PROPERTY TYPE QUESTIONS - it's auto-detected
 NO CURRENCY QUESTIONS - it's auto-detected

app/jobs/stay_notification_jobs.py

@@ -1,223 +1,298 @@
 import logging
-from datetime import datetime, time
+from datetime import datetime, timedelta
 from bson import ObjectId
 from app.database import get_db
 from app.models.booking import BookingStatus
-from app.services.translate_service import translate_notification
+from app.services.aida_dm_service import send_aida_dm
+from app.ai.agent.brain import generate_localized_response
 
 logger = logging.getLogger(__name__)
 
-async def get_or_create_aida_conversation(db, user_id: str):
-    """Retrieve or create the persistent AIDA DM thread for a user."""
-    conv = await db["conversations"].find_one({
-        "participants": [user_id, "aida"],
-        "is_aida": True
-    })
-    
-    if conv:
-        return str(conv["_id"])
-        
-    # Create new
-    insert = await db["conversations"].insert_one({
-        "participants": [user_id, "aida"],
-        "is_aida": True,
-        "created_at": datetime.utcnow(),
-        "updated_at": datetime.utcnow(),
-        "last_message": "AIDA Chat initialized."
-    })
-    return str(insert.inserted_id)
+
+def _lang(user: dict) -> str:
+    """Return the user's preferred language code, defaulting to English."""
+    return (user or {}).get("preferredLanguage", "en")
+
 
 async def dispatch_stay_control_cards():
     """
-    Background job to run daily (e.g., via cron) or periodically.
-    Dispatches:
+    Background job — runs daily.
     1. Check-In cards at 08:00 AM on check-in day.
     2. Check-Out reminders at 10:00 AM on check-out day.
+    Messages are generated directly in the guest's preferred language.
     """
     logger.info("Executing stay notification job...")
     db = await get_db()
     now_dt = datetime.utcnow()
-    
-    # Simple check to enforce time thresholds (only dispatch if it's past the designated hour today)
-    # We use UTC time here. In production, localized timechecks are better.
-    should_dispatch_checkin = now_dt.hour >= 8  # Past 8 AM UTC
-    should_dispatch_checkout = now_dt.hour >= 10 # Past 10 AM UTC
 
-    # 1. Dispatch Check-In Cards
+    should_dispatch_checkin  = now_dt.hour >= 8
+    should_dispatch_checkout = now_dt.hour >= 10
+
+    # ── 1. Check-In Cards ────────────────────────────────────────────────────
     if should_dispatch_checkin:
-        # Find bookings Confirmed, Check-in is today (or past), but card not sent yet
         cursor = db["bookings"].find({
             "status": BookingStatus.CONFIRMED.value,
-            "check_in_card_sent": {"$ne": True}
+            "check_in_card_sent": {"$ne": True},
         })
-        
+
         async for booking in cursor:
             try:
-                # Compare check_in_date (ignoring time)
                 check_in = booking.get("check_in_date")
                 if isinstance(check_in, str):
                     check_in = datetime.fromisoformat(check_in)
-                    
+
                 if check_in.date() <= now_dt.date():
-                    guest_id = booking["user_id"]
+                    guest_id    = booking["user_id"]
                     property_id = booking["listing_id"]
-                    
+
                     listing = await db["listings"].find_one({"_id": ObjectId(property_id)})
                     property_data = {
-                        "id": str(listing.get("_id", "")),
-                        "title": listing.get("title", "Property"),
+                        "id":     str(listing.get("_id", "")),
+                        "title":  listing.get("title", "Property"),
                         "images": listing.get("images", []),
-                        "image": listing.get("image", None)
+                        "image":  listing.get("image", None),
                     }
-                    
-                    booking["id"] = str(booking["_id"])
-                    booking["booking_id"] = str(booking["_id"]) 
-                    
-                    # Ensure JSON serialization friendly booking dict
+                    property_name = listing.get("title", "the property") if listing else "the property"
+
+                    # Serialise booking for metadata
+                    booking["id"]         = str(booking["_id"])
+                    booking["booking_id"] = str(booking["_id"])
                     booking.pop("_id", None)
-                    if isinstance(booking.get("created_at"), datetime):
-                        booking["created_at"] = booking["created_at"].isoformat()
-                    if isinstance(booking.get("updated_at"), datetime):
-                        booking["updated_at"] = booking["updated_at"].isoformat()
+                    for field in ("created_at", "updated_at"):
+                        if isinstance(booking.get(field), datetime):
+                            booking[field] = booking[field].isoformat()
                     booking["check_in_date"] = check_in.isoformat()
-                    
-                    checkout_dt = booking.get("check_out_date")
-                    if isinstance(checkout_dt, datetime):
-                        booking["check_out_date"] = checkout_dt.isoformat()
-                    
-                    conv_id = await get_or_create_aida_conversation(db, guest_id)
-                    
-                    # Guest Language Preferences
+                    if isinstance(booking.get("check_out_date"), datetime):
+                        booking["check_out_date"] = booking["check_out_date"].isoformat()
+
+                    # Get guest's preferred language — generate message directly in it
                     guest = await db["users"].find_one({"_id": ObjectId(guest_id)})
-                    pref_lang = guest.get("preferredLanguage", "en") if guest else "en"
-                    
-                    raw_content = "Good morning! Today is your check-in day. When you arrive at the property, you can check in securely using the card below."
-                    translated_content = translate_notification(raw_content, pref_lang)
-                    
-                    # Inject message
-                    new_msg = {
-                        "conversation_id": conv_id,
-                        "sender_id": "aida",
-                        "content": translated_content,
-                        "is_user": False,
-                        "timestamp": datetime.utcnow(),
-                        "read": False,
-                        "metadata": {
+                    lang  = _lang(guest)
+
+                    content = await generate_localized_response(
+                        context=(
+                            f"Send a warm check-in day greeting to a guest staying at '{property_name}'. "
+                            "Tell them today is their check-in day and they can check in securely "
+                            "using the card below when they arrive. Keep it short and welcoming."
+                        ),
+                        language=lang,
+                        tone="friendly",
+                        max_length="short",
+                    )
+
+                    await send_aida_dm(
+                        guest_id,
+                        content,
+                        metadata={
                             "stay_control_card": {
-                                "bookingData": booking,
-                                "propertyData": property_data
+                                "bookingData":  booking,
+                                "propertyData": property_data,
                             }
-                        }
-                    }
-                    
-                    await db["messages"].insert_one(new_msg)
-                    
-                    # Update conversation
-                    await db["conversations"].update_one(
-                        {"_id": ObjectId(conv_id)},
-                        {
-                            "$set": {
-                                "updated_at": datetime.utcnow(),
-                                "last_message": translated_content,
-                                "last_sender_id": "aida"
-                            }
-                        }
+                        },
                     )
-                    
-                    # Mark booking
+
                     await db["bookings"].update_one(
                         {"_id": ObjectId(booking["id"])},
-                        {"$set": {"check_in_card_sent": True}}
+                        {"$set": {"check_in_card_sent": True}},
                     )
-                    
                     logger.info(f"Dispatched check-in card for booking {booking['id']}")
+
             except Exception as e:
-                logger.error(f"Failed handling check-in card for booking {booking.get('_id')}: {e}")
+                logger.error(f"Failed handling check-in card for booking {booking.get('id')}: {e}")
 
-    # 2. Dispatch Check-Out Cards
+    # ── 2. Check-Out Cards ───────────────────────────────────────────────────
     if should_dispatch_checkout:
         cursor = db["bookings"].find({
             "status": BookingStatus.ACTIVE_STAY.value,
-            "check_out_card_sent": {"$ne": True}
+            "check_out_card_sent": {"$ne": True},
         })
-        
+
         async for booking in cursor:
             try:
                 check_out = booking.get("check_out_date")
                 if isinstance(check_out, str):
                     check_out = datetime.fromisoformat(check_out)
-                    
+
                 if check_out.date() <= now_dt.date():
-                    guest_id = booking["user_id"]
+                    guest_id    = booking["user_id"]
                     property_id = booking["listing_id"]
-                    
+
                     listing = await db["listings"].find_one({"_id": ObjectId(property_id)})
                     property_data = {
-                        "id": str(listing.get("_id", "")),
-                        "title": listing.get("title", "Property"),
+                        "id":     str(listing.get("_id", "")),
+                        "title":  listing.get("title", "Property"),
                         "images": listing.get("images", []),
-                        "image": listing.get("image", None)
+                        "image":  listing.get("image", None),
                     }
-                    
-                    booking["id"] = str(booking["_id"])
+                    property_name = listing.get("title", "the property") if listing else "the property"
+
+                    # Serialise booking for metadata
+                    booking["id"]         = str(booking["_id"])
                     booking["booking_id"] = str(booking["_id"])
                     booking.pop("_id", None)
-                    
-                    if isinstance(booking.get("created_at"), datetime):
-                        booking["created_at"] = booking["created_at"].isoformat()
-                    if isinstance(booking.get("updated_at"), datetime):
-                        booking["updated_at"] = booking["updated_at"].isoformat()
-                    
-                    checkin_dt = booking.get("check_in_date")
-                    if isinstance(checkin_dt, datetime):
-                        booking["check_in_date"] = checkin_dt.isoformat()
+                    for field in ("created_at", "updated_at"):
+                        if isinstance(booking.get(field), datetime):
+                            booking[field] = booking[field].isoformat()
+                    if isinstance(booking.get("check_in_date"), datetime):
+                        booking["check_in_date"] = booking["check_in_date"].isoformat()
                     booking["check_out_date"] = check_out.isoformat()
-                    
-                    conv_id = await get_or_create_aida_conversation(db, guest_id)
-                    
-                    # Guest Language Preferences
+
                     guest = await db["users"].find_one({"_id": ObjectId(guest_id)})
-                    pref_lang = guest.get("preferredLanguage", "en") if guest else "en"
-                    
-                    raw_content = "Good morning! We hope you enjoyed your stay. Today is your scheduled check-out day. Please remember to gather all your belongings and use the Check-Out button below when you leave."
-                    translated_content = translate_notification(raw_content, pref_lang)
-                    
-                    # Inject message
-                    new_msg = {
-                        "conversation_id": conv_id,
-                        "sender_id": "aida",
-                        "content": translated_content,
-                        "is_user": False,
-                        "timestamp": datetime.utcnow(),
-                        "read": False,
-                        "metadata": {
+                    lang  = _lang(guest)
+
+                    content = await generate_localized_response(
+                        context=(
+                            f"Send a warm check-out day message to a guest at '{property_name}'. "
+                            "Hope they enjoyed their stay. Remind them today is their check-out day, "
+                            "to gather their belongings, and to use the Check-Out button below when "
+                            "they leave. Keep it friendly and brief."
+                        ),
+                        language=lang,
+                        tone="friendly",
+                        max_length="short",
+                    )
+
+                    await send_aida_dm(
+                        guest_id,
+                        content,
+                        metadata={
                             "stay_control_card": {
-                                "bookingData": booking,
-                                "propertyData": property_data
+                                "bookingData":  booking,
+                                "propertyData": property_data,
                             }
-                        }
-                    }
-                    
-                    await db["messages"].insert_one(new_msg)
-                    
-                    # Update conversation
-                    await db["conversations"].update_one(
-                        {"_id": ObjectId(conv_id)},
-                        {
-                            "$set": {
-                                "updated_at": datetime.utcnow(),
-                                "last_message": translated_content,
-                                "last_sender_id": "aida"
-                            }
-                        }
+                        },
                     )
-                    
-                    # Mark booking
+
                     await db["bookings"].update_one(
                         {"_id": ObjectId(booking["id"])},
-                        {"$set": {"check_out_card_sent": True}}
+                        {"$set": {"check_out_card_sent": True}},
                     )
-                    
                     logger.info(f"Dispatched check-out card for booking {booking['id']}")
+
             except Exception as e:
-                logger.error(f"Failed handling check-out card for booking {booking.get('_id')}: {e}")
+                logger.error(f"Failed handling check-out card for booking {booking.get('id')}: {e}")
+
+
+async def dispatch_checkin_reminders():
+    """
+    Send a warm AIDA DM to the guest and host ~3 hours before check-in.
+    Runs every 30 minutes — duplicate-safe via sent flag.
+    Messages generated directly in each user's preferred language.
+    """
+    logger.info("Running pre-check-in reminder job...")
+    db  = await get_db()
+    now = datetime.utcnow()
+    window_start = now + timedelta(hours=2, minutes=45)
+    window_end   = now + timedelta(hours=3, minutes=15)
+
+    cursor = db["bookings"].find({
+        "status":               BookingStatus.CONFIRMED.value,
+        "checkin_reminder_sent": {"$ne": True},
+        "check_in_date":        {"$gte": window_start, "$lte": window_end},
+    })
+
+    async for booking in cursor:
+        try:
+            guest_id = booking["user_id"]
+            host_id  = booking["landlord_id"]
+            listing  = await db["listings"].find_one({"_id": ObjectId(booking["listing_id"])})
+            property_name = listing.get("title", "your property") if listing else "your property"
+
+            # ── Guest ─────────────────────────────────────────────────────
+            guest      = await db["users"].find_one({"_id": ObjectId(guest_id)})
+            guest_lang = _lang(guest)
+
+            guest_msg = await generate_localized_response(
+                context=(
+                    f"Remind the guest that their check-in at '{property_name}' is in about 3 hours. "
+                    "Tell them to make sure they're packed and ready. Sound warm and excited for them. 🏠"
+                ),
+                language=guest_lang,
+                tone="friendly",
+                max_length="short",
+            )
+            await send_aida_dm(guest_id, guest_msg, push_body=guest_msg[:80])
+
+            # ── Host ──────────────────────────────────────────────────────
+            host      = await db["users"].find_one({"_id": ObjectId(host_id)})
+            host_lang = _lang(host)
+
+            host_msg = await generate_localized_response(
+                context=(
+                    f"Remind the property host that a guest is checking in to '{property_name}' "
+                    "in about 3 hours. Ask them to make sure everything is ready for the guest. 🏠"
+                ),
+                language=host_lang,
+                tone="friendly",
+                max_length="short",
+            )
+            await send_aida_dm(host_id, host_msg, push_body=host_msg[:80])
+
+            await db["bookings"].update_one(
+                {"_id": booking["_id"]},
+                {"$set": {"checkin_reminder_sent": True}},
+            )
+            logger.info(f"Sent pre-check-in reminder for booking {booking['_id']}")
+
+        except Exception as e:
+            logger.error(f"Pre-check-in reminder failed for booking {booking.get('_id')}: {e}")
+
+
+async def dispatch_checkout_review_requests():
+    """
+    After booking status moves to COMPLETED, send a conversational AIDA DM
+    asking the guest to review the property.
+    Runs every 30 minutes — duplicate-safe via sent flag.
+    Message generated directly in the guest's preferred language.
+    """
+    logger.info("Running post-checkout review request job...")
+    db = await get_db()
+
+    cursor = db["bookings"].find({
+        "status":               BookingStatus.COMPLETED.value,
+        "review_request_sent":  {"$ne": True},
+    })
+
+    async for booking in cursor:
+        try:
+            guest_id      = booking["user_id"]
+            listing       = await db["listings"].find_one({"_id": ObjectId(booking["listing_id"])})
+            property_name = listing.get("title", "the property") if listing else "the property"
+
+            guest = await db["users"].find_one({"_id": ObjectId(guest_id)})
+            lang  = _lang(guest)
+
+            msg = await generate_localized_response(
+                context=(
+                    f"Ask the guest how their stay at '{property_name}' was. "
+                    "Invite them to drop a 1–5 star rating and share anything "
+                    "future guests should know — voice or text, whatever works. "
+                    "Sound casual, warm, and genuinely interested. Include a 🏠 emoji."
+                ),
+                language=lang,
+                tone="friendly",
+                max_length="short",
+            )
+
+            await send_aida_dm(
+                guest_id,
+                msg,
+                metadata={
+                    "review_request": {
+                        "booking_id":  str(booking["_id"]),
+                        "listing_id":  str(booking["listing_id"]),
+                        "review_type": "property",
+                    }
+                },
+                push_title="AIDA — Rate your stay",
+                push_body=f"How was your stay at '{property_name}'? Tap to rate.",
+            )
+
+            await db["bookings"].update_one(
+                {"_id": booking["_id"]},
+                {"$set": {"review_request_sent": True}},
+            )
+            logger.info(f"Sent checkout review request for booking {booking['_id']}")
+
+        except Exception as e:
+            logger.error(f"Checkout review request failed for booking {booking.get('_id')}: {e}")

app/jobs/viewing_notification_jobs.py

@@ -0,0 +1,186 @@
+# app/jobs/viewing_notification_jobs.py
+"""
+Background jobs for viewing appointment notifications (rent/sale).
+
+  dispatch_viewing_reminders()      — 3 hours before viewing → AIDA DM to visitor + landlord
+  dispatch_post_viewing_followups() — After viewing passes → AIDA DM to visitor asking for
+                                      landlord/agent review (saved to their profile, not property)
+
+Messages are generated directly in each user's preferred language — no English template,
+no translation step. Language is read from user.preferredLanguage in the DB.
+"""
+
+import logging
+from datetime import datetime, timedelta
+from bson import ObjectId
+
+from app.database import get_db
+from app.models.viewing import ViewingStatus
+from app.services.aida_dm_service import send_aida_dm as _send_aida_dm
+from app.ai.agent.brain import generate_localized_response
+
+logger = logging.getLogger(__name__)
+
+
+def _lang(user: dict) -> str:
+    return (user or {}).get("preferredLanguage", "en")
+
+
+# ============================================================
+# JOB 1 — PRE-VIEWING REMINDER (3 hours before)
+# ============================================================
+
+async def dispatch_viewing_reminders():
+    """
+    Find confirmed viewings scheduled ~3 hours from now and send reminders
+    to both the visitor and the landlord via AIDA DM.
+    Runs every 30 minutes — duplicate-safe via reminder flags.
+    """
+    logger.info("Running viewing reminder job...")
+    db           = await get_db()
+    now          = datetime.utcnow()
+    window_start = now + timedelta(hours=2, minutes=45)
+    window_end   = now + timedelta(hours=3, minutes=15)
+
+    cursor = db["viewings"].find({
+        "status":       ViewingStatus.CONFIRMED.value,
+        "scheduled_at": {"$gte": window_start, "$lte": window_end},
+        "$or": [
+            {"visitor_reminder_sent":  {"$ne": True}},
+            {"landlord_reminder_sent": {"$ne": True}},
+        ],
+    })
+
+    async for viewing in cursor:
+        viewing_id   = viewing["_id"]
+        visitor_id   = viewing["visitor_id"]
+        landlord_id  = viewing["landlord_id"]
+        scheduled_at = viewing["scheduled_at"]
+        time_str     = scheduled_at.strftime("%I:%M %p") if isinstance(scheduled_at, datetime) else str(scheduled_at)
+
+        listing       = await db["listings"].find_one({"_id": ObjectId(viewing["listing_id"])})
+        property_name = listing.get("title", "the property") if listing else "the property"
+
+        # ── Visitor reminder ──────────────────────────────────────────────
+        if not viewing.get("visitor_reminder_sent"):
+            try:
+                visitor = await db["users"].find_one({"_id": ObjectId(visitor_id)})
+                msg = await generate_localized_response(
+                    context=(
+                        f"Remind the visitor they have a property viewing at '{property_name}' "
+                        f"today at {time_str}. Tell them not to be late. Sound friendly. 🏠"
+                    ),
+                    language=_lang(visitor),
+                    tone="friendly",
+                    max_length="short",
+                )
+                await _send_aida_dm(visitor_id, msg)
+                await db["viewings"].update_one(
+                    {"_id": viewing_id},
+                    {"$set": {"visitor_reminder_sent": True}},
+                )
+                logger.info(f"Sent visitor viewing reminder for viewing {viewing_id}")
+            except Exception as e:
+                logger.error(f"Visitor reminder failed for viewing {viewing_id}: {e}")
+
+        # ── Landlord reminder ─────────────────────────────────────────────
+        if not viewing.get("landlord_reminder_sent"):
+            try:
+                landlord = await db["users"].find_one({"_id": ObjectId(landlord_id)})
+                msg = await generate_localized_response(
+                    context=(
+                        f"Remind the landlord/agent that a prospective tenant or buyer is visiting "
+                        f"'{property_name}' today at {time_str}. Ask them to make sure the property "
+                        "is ready. Sound professional but warm. 🏠"
+                    ),
+                    language=_lang(landlord),
+                    tone="friendly",
+                    max_length="short",
+                )
+                await _send_aida_dm(landlord_id, msg)
+                await db["viewings"].update_one(
+                    {"_id": viewing_id},
+                    {"$set": {"landlord_reminder_sent": True}},
+                )
+                logger.info(f"Sent landlord viewing reminder for viewing {viewing_id}")
+            except Exception as e:
+                logger.error(f"Landlord reminder failed for viewing {viewing_id}: {e}")
+
+
+# ============================================================
+# JOB 2 — POST-VIEWING FOLLOW-UP (review of landlord/agent)
+# ============================================================
+
+async def dispatch_post_viewing_followups():
+    """
+    After a confirmed viewing's scheduled time has passed, send a follow-up
+    AIDA DM to the visitor asking for a review of the landlord/agent.
+
+    The review goes to the LANDLORD/AGENT profile — not the property —
+    because for rentals and sales, the person matters more than the walls.
+
+    Runs every 30 minutes — duplicate-safe via followup_sent flag.
+    """
+    logger.info("Running post-viewing follow-up job...")
+    db  = await get_db()
+    now = datetime.utcnow()
+
+    cursor = db["viewings"].find({
+        "status":       ViewingStatus.CONFIRMED.value,
+        "scheduled_at": {"$lte": now - timedelta(hours=1)},
+        "followup_sent": {"$ne": True},
+    })
+
+    async for viewing in cursor:
+        viewing_id  = viewing["_id"]
+        visitor_id  = viewing["visitor_id"]
+        landlord_id = viewing["landlord_id"]
+
+        try:
+            await db["viewings"].update_one(
+                {"_id": viewing_id},
+                {"$set": {"status": ViewingStatus.COMPLETED.value}},
+            )
+
+            visitor  = await db["users"].find_one({"_id": ObjectId(visitor_id)})
+            landlord = await db["users"].find_one({"_id": ObjectId(landlord_id)})
+            listing  = await db["listings"].find_one({"_id": ObjectId(viewing["listing_id"])})
+
+            property_name = listing.get("title", "the property") if listing else "the property"
+            landlord_name = (landlord or {}).get("name", "the landlord/agent")
+
+            msg = await generate_localized_response(
+                context=(
+                    f"Ask the visitor how the property viewing at '{property_name}' went. "
+                    f"Ask if {landlord_name} was professional and honest. "
+                    "Invite them to give a 1–5 star rating — it helps the next person decide. "
+                    "Sound casual and genuine. Include a ⭐ emoji."
+                ),
+                language=_lang(visitor),
+                tone="friendly",
+                max_length="short",
+            )
+
+            await _send_aida_dm(
+                visitor_id,
+                msg,
+                metadata={
+                    "review_request": {
+                        "viewing_id":       str(viewing_id),
+                        "reviewed_user_id": landlord_id,
+                        "listing_id":       str(viewing["listing_id"]),
+                        "review_type":      "landlord_agent",
+                    }
+                },
+                push_title="AIDA — Rate your viewing",
+                push_body=f"How did the viewing at '{property_name}' go? Tap to rate.",
+            )
+
+            await db["viewings"].update_one(
+                {"_id": viewing_id},
+                {"$set": {"followup_sent": True}},
+            )
+            logger.info(f"Sent post-viewing follow-up for viewing {viewing_id}")
+
+        except Exception as e:
+            logger.error(f"Post-viewing follow-up failed for viewing {viewing_id}: {e}")

app/models/viewing.py

@@ -0,0 +1,52 @@
+# app/models/viewing.py
+"""
+Viewing appointment model — for rent and sale property visits.
+Created when AIDA-Market schedules a viewing between a visitor and a landlord.
+"""
+
+from datetime import datetime
+from typing import Optional
+from enum import Enum
+from bson import ObjectId
+from pydantic import BaseModel, Field
+from app.database import get_db
+
+
+class ViewingStatus(str, Enum):
+    PENDING   = "pending"     # Proposed, waiting for landlord to confirm
+    CONFIRMED = "confirmed"   # Landlord accepted
+    CANCELLED = "cancelled"   # Cancelled by either party
+    COMPLETED = "completed"   # Visit happened (past scheduled time)
+
+
+class Viewing(BaseModel):
+    id: Optional[str] = Field(default_factory=lambda: str(ObjectId()), alias="_id")
+    visitor_id:  str                   # User requesting the viewing
+    landlord_id: str                   # Property owner / agent
+    listing_id:  str                   # Property being viewed
+    scheduled_at: datetime             # Agreed date & time
+    status: ViewingStatus = ViewingStatus.PENDING
+    notes: Optional[str] = None        # Optional message from visitor
+
+    # Notification flags — prevent duplicate sends
+    visitor_reminder_sent:  bool = False
+    landlord_reminder_sent: bool = False
+    followup_sent:          bool = False   # Post-viewing review request sent
+
+    created_at: Optional[datetime] = None
+    updated_at: Optional[datetime] = None
+
+    class Config:
+        populate_by_name = True
+        json_encoders = {ObjectId: str}
+
+
+async def ensure_viewing_indexes():
+    """Create indexes at startup."""
+    db = await get_db()
+    col = db["viewings"]
+    await col.create_index("visitor_id")
+    await col.create_index("landlord_id")
+    await col.create_index("listing_id")
+    await col.create_index("status")
+    await col.create_index("scheduled_at")

app/routes/booking.py

@@ -36,7 +36,7 @@ def _format_natural_date(dt) -> str:
     return str(dt)
 
 
-def _build_host_confirmation_message(
+async def _build_host_confirmation_message(
     host_name: str,
     guest_name: str,
     property_title: str,
@@ -44,30 +44,44 @@ def _build_host_confirmation_message(
     check_out,
     guest_count: int,
     payout_amount: float,
+    language: str = "en",
 ) -> str:
     check_in_str = _format_natural_date(check_in)
     check_out_str = _format_natural_date(check_out)
     payout_str = f"₦{payout_amount:,.0f}" if payout_amount else ""
 
-    lines = [
-        "🎉 New Booking Confirmed!",
-        "",
-        f"Hi {host_name}! You have a new confirmed booking for **{property_title}**.",
-        "",
-        f"📅 Check-in:  {check_in_str}",
-        "",
-        f"📅 Check-out: {check_out_str}",
-        "",
-        f"👥 Guests:    {guest_count}",
-    ]
-    if payout_str:
-        lines += ["", f"💰 Your payout: {payout_str}"]
-    lines += [
-        "",
-        f"Your guest **{guest_name}** has completed payment and their reservation is secured. "
-        "Prepare for a wonderful hosting experience! 🏡",
-    ]
-    return "\n".join(lines)
+    try:
+        from app.ai.agent.brain import generate_localized_response
+        context = (
+            f"You are AIDA, the AI co-host assistant. Send a booking confirmation notification to host '{host_name}'.\n"
+            f"A guest named '{guest_name}' just confirmed a booking for '{property_title}'.\n"
+            f"Check-in: {check_in_str}\n"
+            f"Check-out: {check_out_str}\n"
+            f"Guests: {guest_count}\n"
+            + (f"Host payout: {payout_str}\n" if payout_str else "") +
+            "\nWrite a warm, professional notification. Include: 🎉 opener, guest name, property name, "
+            "check-in and check-out dates on separate lines, number of guests, and payout amount if provided. "
+            "End with a short encouraging note about hosting. Keep it concise."
+        )
+        return await generate_localized_response(
+            context=context,
+            language=language,
+            tone="professional",
+            max_length="medium",
+        )
+    except Exception:
+        # Fallback to English template if LLM fails
+        payout_line = f"\n\n💰 Your payout: {payout_str}" if payout_str else ""
+        return (
+            f"🎉 New Booking Confirmed!\n\n"
+            f"Hi {host_name}! You have a new confirmed booking for **{property_title}**.\n\n"
+            f"📅 Check-in:  {check_in_str}\n\n"
+            f"📅 Check-out: {check_out_str}\n\n"
+            f"👥 Guests:    {guest_count}"
+            f"{payout_line}\n\n"
+            f"Your guest **{guest_name}** has completed payment and their reservation is secured. "
+            "Prepare for a wonderful hosting experience! 🏡"
+        )
 
 
 async def _build_guest_confirmation_message(
@@ -414,8 +428,9 @@ async def stripe_webhook(request: Request):
                     f"{_h.get('firstName', '')} {_h.get('lastName', '')}".strip()
                     or _h.get("name") or _h.get("full_name") or "there"
                 )
+                host_language = _h.get("preferredLanguage", "en") or "en"
 
-                msg = _build_host_confirmation_message(
+                msg = await _build_host_confirmation_message(
                     host_name=host_name,
                     guest_name=guest_name,
                     property_title=property_title,
@@ -423,6 +438,7 @@ async def stripe_webhook(request: Request):
                     check_out=booking.get("check_out_date"),
                     guest_count=booking.get("guest_count", 1),
                     payout_amount=booking.get("payout_amount", 0),
+                    language=host_language,
                 )
                 import asyncio
                 asyncio.create_task(notify_landlord_via_aida(booking["landlord_id"], msg))
@@ -731,8 +747,9 @@ async def simulate_payment(booking_id: str, current_user: dict = Depends(get_cur
             f"{_hd.get('firstName', '')} {_hd.get('lastName', '')}".strip()
             or _hd.get("name") or _hd.get("full_name") or "there"
         )
+        host_language = _hd.get("preferredLanguage", "en") or "en"
 
-        msg = _build_host_confirmation_message(
+        msg = await _build_host_confirmation_message(
             host_name=host_name,
             guest_name=guest_name,
             property_title=property_title,
@@ -740,6 +757,7 @@ async def simulate_payment(booking_id: str, current_user: dict = Depends(get_cur
             check_out=booking.get("check_out_date"),
             guest_count=booking.get("guest_count", 1),
             payout_amount=booking.get("payout_amount", 0),
+            language=host_language,
         )
         import asyncio
         asyncio.create_task(notify_landlord_via_aida(landlord_id, msg))
@@ -810,6 +828,19 @@ async def simulate_payment(booking_id: str, current_user: dict = Depends(get_cur
             }
         )
 
+        # FCM push to guest — fires even when app is closed/backgrounded
+        try:
+            from app.services.push_service import push_service
+            await push_service.send_to_user(
+                user_id=str(booking["user_id"]),
+                title="🎉 Booking Confirmed!",
+                body=guest_content[:100],
+                category="booking_updates",
+                data={"type": "booking_confirmation", "conversation_id": str(conversation["_id"])},
+            )
+        except Exception as push_err:
+            logging.getLogger(__name__).warning(f"Guest push notification failed (non-fatal): {push_err}")
+
         # Broadcast via WebSocket
         try:
             from app.routes.websocket_chat import chat_manager

app/routes/websocket_chat.py

@@ -34,6 +34,9 @@ async def _process_aida_dm_response(
     reply_context: Optional[dict] = None,
     audio_url: Optional[str] = None,
     app_language: Optional[str] = None,
+    user_name: Optional[str] = None,
+    user_location: Optional[str] = None,
+    user_role: Optional[str] = "renter",
 ):
     """
     Process user message through AIDA AI brain and send response in DM.
@@ -150,6 +153,9 @@ async def _process_aida_dm_response(
             source="dm",
             reply_context=reply_context,
             app_language=app_language,
+            user_name=user_name,
+            user_location=user_location,
+            user_role=user_role or "renter",
         )
         
         # Extract response
@@ -712,7 +718,19 @@ async def websocket_chat_endpoint(websocket: WebSocket, token: str = Query(...))
             
             elif action == "clear_chat":
                 await handle_clear_chat(user_id, websocket, message)
-    
+
+            elif action == "schedule_viewing":
+                await handle_schedule_viewing(user_id, websocket, message)
+
+            elif action == "viewing_availability":
+                await handle_viewing_availability(user_id, message)
+
+            elif action == "viewing_pick_slot":
+                await handle_viewing_pick_slot(user_id, message)
+
+            elif action == "viewing_confirm":
+                await handle_viewing_confirm(user_id, message)
+
     except WebSocketDisconnect:
         chat_manager.disconnect(websocket)
         # Only set offline if user has no other connections
@@ -728,6 +746,98 @@ async def websocket_chat_endpoint(websocket: WebSocket, token: str = Query(...))
         await broadcast_user_status(user_id, is_online=False)
 
 
+async def handle_schedule_viewing(user_id: str, websocket, message: dict) -> None:
+    """
+    Triggered when user taps "Schedule Viewing" on a rent/sale listing.
+    Creates a pending Viewing doc and sends opening AIDA DMs to both parties.
+    Payload: { action: "schedule_viewing", listing_id, landlord_id, message? }
+    """
+    try:
+        from app.services.viewing_service import initiate_viewing_request
+        listing_id  = message.get("listing_id")
+        landlord_id = message.get("landlord_id")
+        note        = message.get("message")
+
+        if not listing_id or not landlord_id:
+            await websocket.send_json({"action": "error", "message": "listing_id and landlord_id are required"})
+            return
+
+        viewing_id = await initiate_viewing_request(
+            visitor_id=user_id,
+            landlord_id=landlord_id,
+            listing_id=listing_id,
+            visitor_message=note,
+        )
+        await websocket.send_json({
+            "action": "schedule_viewing_ack",
+            "viewing_id": viewing_id,
+            "message": "Viewing request initiated. Check your AIDA messages for next steps.",
+        })
+        logger.info(f"[Viewing] Initiated: {viewing_id} by user {user_id}")
+    except Exception as e:
+        logger.error(f"[Viewing] handle_schedule_viewing error: {e}")
+        await websocket.send_json({"action": "error", "message": "Failed to initiate viewing request"})
+
+
+async def handle_viewing_availability(user_id: str, message: dict) -> None:
+    """
+    User replies with their availability for a scheduled viewing.
+    Payload: { action: "viewing_availability", viewing_id, raw_text, slots: ["Monday 10am", ...] }
+    """
+    try:
+        from app.services.viewing_service import store_availability
+        viewing_id = message.get("viewing_id")
+        raw_text   = message.get("raw_text", "")
+        slots      = message.get("slots", [])
+
+        if not viewing_id:
+            return
+
+        await store_availability(
+            viewing_id=viewing_id,
+            user_id=user_id,
+            raw_availability=raw_text,
+            parsed_slots=slots,
+        )
+        logger.info(f"[Viewing] Availability stored for viewing {viewing_id} by {user_id}")
+    except Exception as e:
+        logger.error(f"[Viewing] handle_viewing_availability error: {e}")
+
+
+async def handle_viewing_pick_slot(user_id: str, message: dict) -> None:
+    """
+    Visitor picks one of the suggested time slots.
+    Payload: { action: "viewing_pick_slot", viewing_id, chosen_slot }
+    """
+    try:
+        from app.services.viewing_service import visitor_picked_slot
+        viewing_id   = message.get("viewing_id")
+        chosen_slot  = message.get("chosen_slot")
+        if not viewing_id or not chosen_slot:
+            return
+        await visitor_picked_slot(viewing_id=viewing_id, chosen_slot=chosen_slot)
+        logger.info(f"[Viewing] Slot picked for viewing {viewing_id}: {chosen_slot}")
+    except Exception as e:
+        logger.error(f"[Viewing] handle_viewing_pick_slot error: {e}")
+
+
+async def handle_viewing_confirm(user_id: str, message: dict) -> None:
+    """
+    Landlord confirms the proposed slot.
+    Payload: { action: "viewing_confirm", viewing_id, confirmed_slot }
+    """
+    try:
+        from app.services.viewing_service import confirm_viewing
+        viewing_id      = message.get("viewing_id")
+        confirmed_slot  = message.get("confirmed_slot")
+        if not viewing_id or not confirmed_slot:
+            return
+        await confirm_viewing(viewing_id=viewing_id, confirmed_slot=confirmed_slot)
+        logger.info(f"[Viewing] Confirmed: viewing {viewing_id} at {confirmed_slot}")
+    except Exception as e:
+        logger.error(f"[Viewing] handle_viewing_confirm error: {e}")
+
+
 async def handle_send_message(user_id: str, user_name: str, user_avatar: Optional[str], data: dict):
     """Handle sending a message via WebSocket"""
     conversation_id = data.get("conversation_id")
@@ -902,6 +1012,9 @@ async def handle_send_message(user_id: str, user_name: str, user_avatar: Optiona
             reply_context=reply_context,
             audio_url=audio_url,
             app_language=app_language,
+            user_name=user_name,
+            user_location=data.get("user_location"),
+            user_role=data.get("user_role", "renter"),
         ))
 
 

app/schemas/user.py

@@ -142,6 +142,12 @@ class ProfileUpdateRequest(BaseModel):
         description="URL to the user's profile picture",
         examples=["https://example.com/images/profile.jpg"]
     )
+    preferredLanguage: Optional[str] = Field(
+        None,
+        pattern="^(en|fr|es|ar|pt)$",
+        description="User's preferred language for notifications and messages",
+        examples=["fr"]
+    )
 
     class Config:
         json_schema_extra = {

app/services/aida_dm_service.py

@@ -0,0 +1,161 @@
+# ============================================================
+# app/services/aida_dm_service.py
+#
+# Centralized helper for sending AIDA-initiated DMs.
+# Every call does THREE things atomically:
+#   1. Insert message into MongoDB
+#   2. Broadcast via WebSocket  → in-app notification banner fires
+#   3. FCM push to recipient    → works even when user is offline
+#
+# Canonical AIDA participant ID: "AIDA_BOT"
+#   - Matches Flutter's DirectMessage.isAi check (senderId == 'AIDA_BOT')
+#   - Matches booking.py, conversations.py, landlord_notifications.py
+#   - Never creates a duplicate conversation — delegates to
+#     get_or_create_aida_conversation() which has full multi-step
+#     lookup + legacy "aida" → "AIDA_BOT" migration built in.
+#
+# Usage:
+#   from app.services.aida_dm_service import send_aida_dm
+#   await send_aida_dm(user_id="abc123", text="Hello!", metadata={...})
+# ============================================================
+import logging
+from datetime import datetime
+
+from bson import ObjectId
+
+from app.database import get_db
+from app.services.push_service import push_service
+
+logger = logging.getLogger(__name__)
+
+AIDA_BOT_ID = "AIDA_BOT"   # canonical participant ID — must match Flutter & all routes
+
+AIDA_AVATAR = (
+    "https://imagedelivery.net/0utJlkqgAVuawL5OpMWxgw/"
+    "3922956f-b69d-4cb3-97b9-3a185abec900/public"
+)
+
+
+def _build_message_doc(conv_id: str, text: str, metadata: dict | None) -> dict:
+    """Build the raw MongoDB document for an AIDA-sent message."""
+    return {
+        "conversation_id": conv_id,
+        "sender_id":       AIDA_BOT_ID,   # Flutter checks senderId == 'AIDA_BOT'
+        "sender_name":     "AIDA",
+        "sender_avatar":   AIDA_AVATAR,
+        "message_type":    "ai",
+        "content":         text,
+        "metadata":        metadata or {},
+        "is_read":         False,
+        "is_edited":       False,
+        "is_deleted":      False,
+        "reactions":       {},
+        "created_at":      datetime.utcnow(),
+    }
+
+
+def _format_for_ws(msg_doc: dict) -> dict:
+    """Convert the raw MongoDB doc to the shape Flutter's DirectMessage.fromJson expects."""
+    return {
+        "id":             str(msg_doc["_id"]),
+        "conversation_id": msg_doc["conversation_id"],
+        "sender_id":       msg_doc["sender_id"],
+        "sender_name":     msg_doc.get("sender_name", "AIDA"),
+        "sender_avatar":   msg_doc.get("sender_avatar"),
+        "message_type":    msg_doc.get("message_type", "ai"),
+        "content":         msg_doc.get("content", ""),
+        "metadata":        msg_doc.get("metadata", {}),
+        "is_read":         False,
+        "is_edited":       False,
+        "is_deleted":      False,
+        "reactions":       {},
+        "created_at":      msg_doc["created_at"].isoformat(),
+    }
+
+
+async def send_aida_dm(
+    user_id: str,
+    text: str,
+    metadata: dict | None = None,
+    *,
+    push_title: str = "AIDA",
+    push_body: str | None = None,
+    conv_id: str | None = None,
+) -> str:
+    """
+    Send an AIDA DM to *user_id*.
+
+    Steps:
+      1. Resolve the EXISTING AIDA conversation for this user (create only if none exists).
+         Uses get_or_create_aida_conversation() which:
+           - Looks for AIDA_BOT participant first (canonical)
+           - Falls back to participants_key lookup
+           - Migrates legacy "aida" conversations to AIDA_BOT in-place
+           - Only creates a new conversation as last resort
+      2. Insert message into `messages` collection.
+      3. Update conversation preview.
+      4. Broadcast `new_message` WebSocket event (triggers in-app banner).
+      5. Send FCM push notification (triggers system notification when offline).
+
+    Returns the conversation ID.
+    """
+    db = await get_db()
+
+    # 1. Resolve conversation — reuse canonical lookup, never duplicate
+    if conv_id is None:
+        from app.services.landlord_notifications import get_or_create_aida_conversation
+        conv_id = await get_or_create_aida_conversation(db, user_id)
+
+    # 2. Insert message
+    doc = _build_message_doc(conv_id, text, metadata)
+    result = await db["messages"].insert_one(doc)
+    doc["_id"] = result.inserted_id
+
+    # 3. Update conversation preview
+    await db["conversations"].update_one(
+        {"_id": ObjectId(conv_id)},
+        {
+            "$set": {
+                "updated_at":    datetime.utcnow(),
+                "last_message":  text[:120],
+                "last_sender_id": AIDA_BOT_ID,
+            }
+        },
+    )
+
+    # 4. WebSocket broadcast — lazy import to avoid circular dependency
+    try:
+        from app.routes.websocket_chat import chat_manager  # type: ignore
+
+        participants = [user_id, AIDA_BOT_ID]
+        payload = {
+            "action":          "new_message",
+            "conversation_id": conv_id,
+            "message":         _format_for_ws(doc),
+        }
+        await chat_manager.broadcast_to_conversation(conv_id, participants, payload)
+        logger.debug(f"[AIDA DM] WS broadcast sent for conv {conv_id}")
+    except Exception as exc:
+        logger.warning(f"[AIDA DM] WS broadcast failed: {exc}")
+
+    # 5. FCM push
+    try:
+        body = push_body or (text[:100] + "…" if len(text) > 100 else text)
+        await push_service.send_to_user(
+            user_id=user_id,
+            title=push_title,
+            body=body,
+            category="messages",
+            data={
+                "category":       "messages",
+                "sender_name":    "AIDA",
+                "avatar_url":     AIDA_AVATAR,
+                "route":          "/direct_chat",
+                "conversation_id": conv_id,
+            },
+        )
+        logger.debug(f"[AIDA DM] Push sent for user {user_id}")
+    except Exception as exc:
+        logger.warning(f"[AIDA DM] Push failed: {exc}")
+
+    return conv_id

app/services/landlord_notifications.py

@@ -2,7 +2,6 @@ import logging
 from datetime import datetime
 from bson import ObjectId
 from app.database import get_db
-from app.services.translate_service import translate_notification
 
 logger = logging.getLogger(__name__)
 
@@ -108,25 +107,22 @@ async def notify_landlord_via_aida(landlord_id: str, message_content: str):
     Acts as AIDA the Co-Host, sending proactive DMs to the landlord
     about their properties. All messages go into the ONE canonical
     AIDA_BOT conversation (no duplicate DM is created).
+
+    NOTE: message_content is expected to already be in the host's preferred
+    language (built by booking.py using generate_localized_response).
+    No translation is applied here.
     """
     try:
         db = await get_db()
         conv_id = await get_or_create_aida_conversation(db, landlord_id)
 
-        # Determine landlord preferred language
-        landlord = await db["users"].find_one({"_id": ObjectId(landlord_id)})
-        pref_lang = landlord.get("preferredLanguage", "en") if landlord else "en"
-
-        # Translate if needed
-        translated_msg = translate_notification(message_content, pref_lang)
-
         now = datetime.utcnow()
 
         new_msg = {
             "_id": str(ObjectId()),
             "conversation_id": conv_id,
             "sender_id": AIDA_BOT_ID,
-            "content": translated_msg,
+            "content": message_content,
             "type": "text",
             "is_user": False,
             "is_ai": True,
@@ -147,7 +143,7 @@ async def notify_landlord_via_aida(landlord_id: str, message_content: str):
                     "updated_at": now,
                     "last_message": {
                         "id": new_msg["_id"],
-                        "content": translated_msg,
+                        "content": message_content,
                         "sender_id": AIDA_BOT_ID,
                         "type": "text",
                         "created_at": now,
@@ -157,7 +153,21 @@ async def notify_landlord_via_aida(landlord_id: str, message_content: str):
             }
         )
 
-        # ── Broadcast via WebSocket so the message appears instantly ──
+        # ── FCM push notification ──────────────────────────────────────────
+        # Fires even when the user's app is closed / backgrounded.
+        try:
+            from app.services.push_service import push_service
+            await push_service.send_to_user(
+                user_id=landlord_id,
+                title="🎉 New Booking Confirmed!",
+                body=message_content[:100],
+                category="booking_updates",
+                data={"type": "booking_confirmation", "conversation_id": conv_id},
+            )
+        except Exception as push_err:
+            logger.warning(f"Push notification failed for landlord {landlord_id} (non-fatal): {push_err}")
+
+        # ── Broadcast via WebSocket so the message appears instantly ──────
         try:
             from app.routes.websocket_chat import chat_manager
 
@@ -188,9 +198,6 @@ async def notify_landlord_via_aida(landlord_id: str, message_content: str):
         except Exception as ws_err:
             logger.warning(f"AIDA notification WS broadcast failed (non-fatal): {ws_err}")
 
-        logger.info(
-            f"Landlord {landlord_id} notified via AIDA [{pref_lang}]: "
-            f"{translated_msg[:50]}..."
-        )
+        logger.info(f"Landlord {landlord_id} notified via AIDA: {message_content[:50]}...")
     except Exception as e:
         logger.error(f"Failed to send landlord AIDA notification: {e}")

app/services/proactive_service.py

@@ -11,6 +11,7 @@ from typing import Any, Dict, List, Optional
 from structlog import get_logger
 
 from app.database import get_db
+from app.services.aida_dm_service import send_aida_dm
 
 logger = get_logger(__name__)
 
@@ -115,6 +116,37 @@ async def _send_proactive_push(
     return count
 
 
+async def _send_aida_dm_alert(
+    user_id: str,
+    message: str,
+    listing_id: str,
+    listing: dict,
+) -> None:
+    """
+    Send an alert match or price drop as an AIDA DM.
+    Delegates to send_aida_dm which handles DB + WebSocket broadcast + push notification.
+    """
+    try:
+        await send_aida_dm(
+            user_id=user_id,
+            text=message,
+            metadata={
+                "alert_card": {
+                    "listing_id": listing_id,
+                    "title": listing.get("title", ""),
+                    "price": listing.get("price"),
+                    "currency": listing.get("currency", ""),
+                    "location": listing.get("location", ""),
+                    "images": listing.get("images", []),
+                }
+            },
+            push_title="AIDA — New match found",
+            push_body=message[:100],
+        )
+    except Exception as e:
+        logger.warning("Failed to send AIDA DM alert", user_id=user_id, error=str(e))
+
+
 async def _send_proactive_email(
     user_id: str,
     title: str,
@@ -270,7 +302,14 @@ async def check_new_listings_against_preferences(
                 location = listing.get("location", "")
                 price = listing.get("price", "")
                 currency = listing.get("currency", "")
+                dm_msg = (
+                    f"Found one! '{title}' in {location} — {currency} {price} 🏠\n"
+                    "Tap to view details."
+                )
 
+                # Primary: AIDA DM (in-app, actionable)
+                await _send_aida_dm_alert(user_id, dm_msg, listing_id, listing)
+                # Fallback: push notification (for when user is outside the app)
                 push_count = await _send_proactive_push(
                     user_id=user_id,
                     title="New listing matches your preferences!",
@@ -347,7 +386,14 @@ async def check_alerts_against_new_listings(
                     location = listing.get("location", "")
                     price = listing.get("price", "")
                     currency = listing.get("currency", "")
+                    dm_msg = (
+                        f"Your alert matched! '{title}' in {location} — {currency} {price} 🏠\n"
+                        "Tap to view details."
+                    )
 
+                    # Primary: AIDA DM
+                    await _send_aida_dm_alert(alert.user_id, dm_msg, listing_id, listing)
+                    # Fallback: push + email
                     push_count = await _send_proactive_push(
                         user_id=alert.user_id,
                         title="Alert match found!",
@@ -357,7 +403,6 @@ async def check_alerts_against_new_listings(
                     )
                     sent_count += push_count
 
-                    # Optional email for alert matches
                     await _send_proactive_email(
                         user_id=alert.user_id,
                         title="A property matches your alert!",
@@ -482,6 +527,11 @@ async def _notify_price_drop(
         if await _was_already_notified(user_id, listing_id, "price_drop"):
             continue
         if _preferences_match_listing(prefs, listing):
+            dm_msg = (
+                f"Price drop! '{title}' just dropped {drop_pct:.0f}% "
+                f"to {currency} {new_price:,.0f} 📉 Tap to check it out."
+            )
+            await _send_aida_dm_alert(user_id, dm_msg, listing_id, listing)
             push_count = await _send_proactive_push(
                 user_id=user_id,
                 title="Price dropped!",
@@ -509,6 +559,11 @@ async def _notify_price_drop(
 
         try:
             if await check_listing_matches_alert(listing, alert):
+                dm_msg = (
+                    f"Your alert matched a price drop! '{title}' is now "
+                    f"{currency} {new_price:,.0f} (down {drop_pct:.0f}%) 📉 Tap to view."
+                )
+                await _send_aida_dm_alert(alert.user_id, dm_msg, listing_id, listing)
                 push_count = await _send_proactive_push(
                     user_id=alert.user_id,
                     title="Price dropped on a match!",

app/services/translate_service.py

@@ -1,34 +1,130 @@
+"""
+translate_service.py
+--------------------
+Translates AIDA system-generated notification messages into the user's preferred language.
+
+Strategy (in order):
+  1. LLM  — generate_localized_response(): natural, warm, AIDA-voiced output in target language
+  2. Google Translate — deep-translator fallback if LLM call fails
+  3. English original  — last resort
+
+The LLM path also rewrites the tone so it feels like AIDA wrote it in that language natively,
+not like English that was run through a translator.
+"""
+
+import asyncio
 import logging
 from typing import Optional
 
 logger = logging.getLogger(__name__)
 
-# Try importing the translator. If the module isn't available due to pip errors, fallback gracefully.
+# ── Google Translate fallback ─────────────────────────────────────────────────
 try:
     from deep_translator import GoogleTranslator
-    has_translator = True
+    _has_google = True
 except ImportError:
-    logger.warning("deep-translator is not installed. Background translations will fallback to English.")
-    has_translator = False
+    logger.warning("deep-translator not installed — Google Translate fallback unavailable.")
+    _has_google = False
 
-def translate_notification(text: str, target_lang: str) -> str:
+
+def _google_translate(text: str, target_lang: str) -> Optional[str]:
+    """Attempt a Google Translate call. Returns None on any failure."""
+    if not _has_google or not text.strip():
+        return None
+    try:
+        return GoogleTranslator(source="auto", target=target_lang[:2]).translate(text)
+    except Exception as e:
+        logger.warning(f"[translate] Google Translate failed ({target_lang}): {e}")
+        return None
+
+
+# ── LLM-primary translation ───────────────────────────────────────────────────
+
+async def _llm_translate(text: str, target_lang: str, context_hint: str = "") -> Optional[str]:
     """
-    Translates a backend system notification into the user's preferred language.
-    If the target_lang is 'en' or translation fails, returns the original text.
+    Use generate_localized_response to rewrite the message natively in target_lang.
+    Returns None if the LLM call fails.
     """
-    if not target_lang or target_lang.lower() == 'en':
-        return text
-        
-    if not has_translator:
-        return text
-        
+    if target_lang.lower().startswith("en"):
+        return text  # Already English — no-op
+
     try:
-        # Prevent errors from empty strings
-        if not text.strip():
-            return text
-            
-        result = GoogleTranslator(source='auto', target=target_lang[:2]).translate(text)
-        return result
+        from app.ai.agent.brain import generate_localized_response
+        result = await generate_localized_response(
+            context=(
+                f"Rewrite the following AIDA notification message natively in the language "
+                f"with ISO code '{target_lang}'. Keep the same meaning and all details. "
+                f"Preserve emojis. Sound warm and friendly — as if AIDA wrote it in that "
+                f"language from scratch, NOT like a translation.\n\n"
+                f"Message: {text}"
+                + (f"\n\nContext: {context_hint}" if context_hint else "")
+            ),
+            language=target_lang,
+            tone="friendly",
+            max_length="medium",
+        )
+        return result.strip() if result else None
     except Exception as e:
-        logger.warning(f"Translation to {target_lang} failed: {e}. Falling back to English.")
+        logger.warning(f"[translate] LLM translation failed ({target_lang}): {e}")
+        return None
+
+
+# ── Public API ────────────────────────────────────────────────────────────────
+
+async def translate_notification_async(
+    text: str,
+    target_lang: str,
+    context_hint: str = "",
+) -> str:
+    """
+    Async version — preferred for all background jobs and services.
+
+    1. Skip translation entirely if already English.
+    2. Try LLM (warm, AIDA-voiced).
+    3. Fallback to Google Translate (mechanical but correct).
+    4. Fallback to original English text.
+    """
+    if not target_lang or target_lang.lower().startswith("en"):
         return text
+
+    # 1. LLM — primary
+    result = await _llm_translate(text, target_lang, context_hint)
+    if result:
+        return result
+
+    # 2. Google Translate — fallback
+    result = _google_translate(text, target_lang)
+    if result:
+        logger.info(f"[translate] Used Google Translate fallback for lang={target_lang}")
+        return result
+
+    # 3. Original text
+    logger.warning(f"[translate] All translation paths failed for lang={target_lang}. Returning English.")
+    return text
+
+
+def translate_notification(text: str, target_lang: str) -> str:
+    """
+    Sync shim kept for backward compatibility with existing callers.
+
+    Runs the async path in a new event loop if no loop is running,
+    otherwise falls straight to Google Translate (since you can't nest
+    await in a sync context that's already inside an event loop).
+
+    Prefer calling translate_notification_async() directly from async code.
+    """
+    if not target_lang or target_lang.lower().startswith("en"):
+        return text
+
+    # Try to run async version
+    try:
+        loop = asyncio.get_event_loop()
+        if loop.is_running():
+            # We're inside an async context — can't nest; use Google Translate
+            result = _google_translate(text, target_lang)
+            return result or text
+        else:
+            return loop.run_until_complete(translate_notification_async(text, target_lang))
+    except Exception:
+        result = _google_translate(text, target_lang)
+        return result or text

app/services/viewing_service.py

@@ -0,0 +1,375 @@
+# app/services/viewing_service.py
+"""
+Viewing Scheduling Service — AIDA-Broker flow for rent/sale property visits.
+
+Flow:
+  1. initiate_viewing_request()
+     - Flutter taps "Schedule Viewing" → creates pending Viewing doc
+     - Sends AIDA DM to visitor: "When are you free this week?"
+     - Sends AIDA DM to landlord: "Someone wants to visit. When are you available?"
+
+  2. store_availability()
+     - Called when either party replies with their available times
+     - Stored on the Viewing doc (visitor_availability / landlord_availability)
+     - When BOTH are stored → trigger cross_check_and_suggest()
+
+  3. cross_check_and_suggest()
+     - Compares both availability lists → finds overlapping slots
+     - Sends AIDA DM to visitor with up to 3 suggested times to pick from
+
+  4. confirm_viewing_slot()
+     - Visitor picks a slot → sends confirmation request to landlord
+     - Landlord confirms → status = CONFIRMED → both get confirmation DM
+
+How AIDA knows who the visitor is:
+  The visitor_id is stored in the Viewing document when initiated.
+  Post-viewing follow-up jobs use visitor_id to send the review request.
+"""
+
+import logging
+from datetime import datetime, timezone
+from typing import List, Optional
+from bson import ObjectId
+
+from app.database import get_db
+from app.models.viewing import ViewingStatus
+from app.services.aida_dm_service import send_aida_dm as _send_aida_dm
+from app.ai.agent.brain import generate_localized_response
+
+
+def _lang(user: dict) -> str:
+    return (user or {}).get("preferredLanguage", "en")
+
+logger = logging.getLogger(__name__)
+
+
+def _user_lang(user: dict) -> str:
+    return (user or {}).get("preferredLanguage", "en")
+
+
+# ============================================================
+# STEP 1 — INITIATE
+# ============================================================
+
+async def initiate_viewing_request(
+    visitor_id: str,
+    landlord_id: str,
+    listing_id: str,
+    visitor_message: Optional[str] = None,
+) -> str:
+    """
+    Create a pending Viewing document and send opening AIDA DMs
+    to both the visitor and the landlord asking for their availability.
+
+    Returns the new viewing_id.
+    """
+    db = await get_db()
+
+    # Create pending viewing
+    doc = {
+        "visitor_id": visitor_id,
+        "landlord_id": landlord_id,
+        "listing_id": listing_id,
+        "status": ViewingStatus.PENDING.value,
+        "visitor_availability": [],   # filled when visitor responds
+        "landlord_availability": [],  # filled when landlord responds
+        "visitor_availability_raw": None,
+        "landlord_availability_raw": None,
+        "suggested_slots": [],
+        "confirmed_slot": None,
+        "visitor_reminder_sent": False,
+        "landlord_reminder_sent": False,
+        "followup_sent": False,
+        "notes": visitor_message,
+        "created_at": datetime.now(timezone.utc),
+        "updated_at": datetime.now(timezone.utc),
+    }
+    result = await db["viewings"].insert_one(doc)
+    viewing_id = str(result.inserted_id)
+
+    # Fetch names and listing
+    visitor  = await db["users"].find_one({"_id": ObjectId(visitor_id)})
+    landlord = await db["users"].find_one({"_id": ObjectId(landlord_id)})
+    listing  = await db["listings"].find_one({"_id": ObjectId(listing_id)})
+
+    property_name    = (listing  or {}).get("title", "the property")
+    listing_type_str = "tenant" if listing and listing.get("listing_type") == "rent" else "buyer"
+
+    # DM to visitor — in visitor's preferred language
+    visitor_msg = await generate_localized_response(
+        context=(
+            f"Tell the visitor you're going to schedule a viewing for '{property_name}'. "
+            "Ask them to share a few days and time slots that work for them this week. "
+            "Sound excited and helpful. Include a 📅 emoji."
+        ),
+        language=_lang(visitor),
+        tone="friendly",
+        max_length="short",
+    )
+    await _send_aida_dm(visitor_id, visitor_msg, metadata={
+        "viewing_flow": {
+            "viewing_id": viewing_id,
+            "step": "collect_visitor_availability",
+        }
+    })
+
+    # DM to landlord — in landlord's preferred language
+    landlord_msg = await generate_localized_response(
+        context=(
+            f"Tell the landlord/agent that a potential {listing_type_str} wants to visit "
+            f"'{property_name}'. Ask them when they're available this week for a viewing — "
+            "a few time slots would be great. Sound professional and warm. Include a 📅 emoji."
+        ),
+        language=_lang(landlord),
+        tone="friendly",
+        max_length="short",
+    )
+    await _send_aida_dm(landlord_id, landlord_msg, metadata={
+        "viewing_flow": {
+            "viewing_id": viewing_id,
+            "step": "collect_landlord_availability",
+        }
+    })
+
+    logger.info(f"Viewing initiated: {viewing_id} | visitor: {visitor_id} | landlord: {landlord_id}")
+    return viewing_id
+
+
+# ============================================================
+# STEP 2 — STORE AVAILABILITY
+# ============================================================
+
+async def store_availability(
+    viewing_id: str,
+    user_id: str,
+    raw_availability: str,
+    parsed_slots: List[str],
+) -> None:
+    """
+    Store a party's availability on the Viewing document.
+    If both parties now have availability → trigger cross-check.
+
+    parsed_slots: list of human-readable strings like ["Monday 10am", "Tuesday 2pm"]
+    raw_availability: the user's original free-form message
+    """
+    db = await get_db()
+    viewing = await db["viewings"].find_one({"_id": ObjectId(viewing_id)})
+    if not viewing:
+        logger.warning(f"store_availability: viewing {viewing_id} not found")
+        return
+
+    is_visitor  = viewing["visitor_id"] == user_id
+    is_landlord = viewing["landlord_id"] == user_id
+
+    if not is_visitor and not is_landlord:
+        logger.warning(f"store_availability: user {user_id} is not a party to viewing {viewing_id}")
+        return
+
+    update_field = "visitor_availability" if is_visitor else "landlord_availability"
+    raw_field    = "visitor_availability_raw" if is_visitor else "landlord_availability_raw"
+
+    await db["viewings"].update_one(
+        {"_id": ObjectId(viewing_id)},
+        {"$set": {
+            update_field: parsed_slots,
+            raw_field: raw_availability,
+            "updated_at": datetime.now(timezone.utc),
+        }},
+    )
+
+    # Reload and check if both are ready
+    viewing = await db["viewings"].find_one({"_id": ObjectId(viewing_id)})
+    if viewing.get("visitor_availability") and viewing.get("landlord_availability"):
+        await cross_check_and_suggest(viewing_id)
+
+
+# ============================================================
+# STEP 3 — CROSS-CHECK & SUGGEST
+# ============================================================
+
+async def cross_check_and_suggest(viewing_id: str) -> None:
+    """
+    Compare visitor and landlord availability → find overlapping slots.
+    Send up to 3 suggestions to the visitor to pick from.
+    If no overlap → ask each party for more options.
+    """
+    db = await get_db()
+    viewing = await db["viewings"].find_one({"_id": ObjectId(viewing_id)})
+    if not viewing:
+        return
+
+    visitor_slots  = viewing.get("visitor_availability", [])
+    landlord_slots = viewing.get("landlord_availability", [])
+    visitor_id     = viewing["visitor_id"]
+    landlord_id    = viewing["landlord_id"]
+
+    listing = await db["listings"].find_one({"_id": ObjectId(viewing["listing_id"])})
+    property_name = (listing or {}).get("title", "the property")
+
+    # Simple overlap check (string match on normalised slot labels)
+    v_norm = {s.lower().strip() for s in visitor_slots}
+    l_norm = {s.lower().strip() for s in landlord_slots}
+    overlap = list(v_norm & l_norm)[:3]  # up to 3 overlapping slots
+
+    visitor  = await db["users"].find_one({"_id": ObjectId(visitor_id)})
+    landlord = await db["users"].find_one({"_id": ObjectId(landlord_id)})
+
+    if overlap:
+        await db["viewings"].update_one(
+            {"_id": ObjectId(viewing_id)},
+            {"$set": {"suggested_slots": overlap}},
+        )
+
+        slots_text = "\n".join(f"  {i+1}. {s.title()}" for i, s in enumerate(overlap))
+        visitor_msg = await generate_localized_response(
+            context=(
+                f"Tell the visitor you found {len(overlap)} time slot(s) that work for both them "
+                f"and the landlord for a viewing of '{property_name}'. "
+                f"List the slots:\n{slots_text}\n"
+                "Ask which one works best — they can reply with the number. Sound excited. Include a 📅 emoji."
+            ),
+            language=_lang(visitor),
+            tone="friendly",
+            max_length="short",
+        )
+        await _send_aida_dm(visitor_id, visitor_msg, metadata={
+            "viewing_flow": {
+                "viewing_id":     viewing_id,
+                "step":           "visitor_pick_slot",
+                "suggested_slots": overlap,
+            }
+        })
+    else:
+        # No overlap — ask each party for more options in their own language
+        visitor_msg = await generate_localized_response(
+            context=(
+                f"Tell the visitor their availability doesn't overlap with the landlord's "
+                f"for a viewing of '{property_name}'. Ask if they can suggest a few more "
+                "time slots this week or next. Sound understanding. Include a 📅 emoji."
+            ),
+            language=_lang(visitor),
+            tone="friendly",
+            max_length="short",
+        )
+        landlord_msg = await generate_localized_response(
+            context=(
+                f"Tell the landlord/agent the visitor's schedule for '{property_name}' "
+                "doesn't overlap with theirs yet. Ask if they can share a couple more "
+                "available windows. Sound professional and warm. Include a 📅 emoji."
+            ),
+            language=_lang(landlord),
+            tone="friendly",
+            max_length="short",
+        )
+        await _send_aida_dm(visitor_id, visitor_msg, metadata={
+            "viewing_flow": {"viewing_id": viewing_id, "step": "collect_visitor_availability"}
+        })
+        await _send_aida_dm(landlord_id, landlord_msg, metadata={
+            "viewing_flow": {"viewing_id": viewing_id, "step": "collect_landlord_availability"}
+        })
+
+        await db["viewings"].update_one(
+            {"_id": ObjectId(viewing_id)},
+            {"$set": {"visitor_availability": [], "landlord_availability": []}},
+        )
+
+
+# ============================================================
+# STEP 4 — VISITOR PICKS SLOT → LANDLORD CONFIRMS
+# ============================================================
+
+async def visitor_picked_slot(viewing_id: str, chosen_slot: str) -> None:
+    """
+    Visitor chose a time slot. Send confirmation request to landlord.
+    """
+    db = await get_db()
+    viewing = await db["viewings"].find_one({"_id": ObjectId(viewing_id)})
+    if not viewing:
+        return
+
+    landlord_id   = viewing["landlord_id"]
+    visitor_id    = viewing["visitor_id"]
+    listing       = await db["listings"].find_one({"_id": ObjectId(viewing["listing_id"])})
+    property_name = (listing or {}).get("title", "the property")
+
+    visitor      = await db["users"].find_one({"_id": ObjectId(visitor_id)})
+    landlord_user = await db["users"].find_one({"_id": ObjectId(landlord_id)})
+    visitor_name  = (visitor or {}).get("name", "The visitor").split()[0]
+
+    await db["viewings"].update_one(
+        {"_id": ObjectId(viewing_id)},
+        {"$set": {"pending_slot": chosen_slot, "updated_at": datetime.now(timezone.utc)}},
+    )
+
+    landlord_msg = await generate_localized_response(
+        context=(
+            f"Tell the landlord/agent that {visitor_name} would like to visit "
+            f"'{property_name}' on {chosen_slot}. Ask if that still works for them — "
+            "they can reply Yes to confirm or suggest a different time. Include a 📅 emoji."
+        ),
+        language=_lang(landlord_user),
+        tone="friendly",
+        max_length="short",
+    )
+    await _send_aida_dm(landlord_id, landlord_msg, metadata={
+        "viewing_flow": {
+            "viewing_id":   viewing_id,
+            "step":         "landlord_confirm_slot",
+            "proposed_slot": chosen_slot,
+        }
+    })
+
+
+async def confirm_viewing(viewing_id: str, confirmed_slot: str) -> None:
+    """
+    Landlord confirmed the slot. Finalise the viewing and notify both parties.
+    """
+    db = await get_db()
+    viewing = await db["viewings"].find_one({"_id": ObjectId(viewing_id)})
+    if not viewing:
+        return
+
+    visitor_id    = viewing["visitor_id"]
+    landlord_id   = viewing["landlord_id"]
+    listing       = await db["listings"].find_one({"_id": ObjectId(viewing["listing_id"])})
+    property_name = (listing or {}).get("title", "the property")
+
+    # Finalise
+    await db["viewings"].update_one(
+        {"_id": ObjectId(viewing_id)},
+        {"$set": {
+            "status": ViewingStatus.CONFIRMED.value,
+            "confirmed_slot": confirmed_slot,
+            "updated_at": datetime.now(timezone.utc),
+        }},
+    )
+
+    visitor  = await db["users"].find_one({"_id": ObjectId(visitor_id)})
+    landlord = await db["users"].find_one({"_id": ObjectId(landlord_id)})
+
+    # Confirmation DMs — each in the recipient's preferred language
+    visitor_msg = await generate_localized_response(
+        context=(
+            f"Tell the visitor their viewing of '{property_name}' is confirmed for "
+            f"{confirmed_slot}. Let them know you'll remind them a few hours before. "
+            "Sound warm and reassuring. Include a 🏠 emoji."
+        ),
+        language=_lang(visitor),
+        tone="friendly",
+        max_length="short",
+    )
+    landlord_msg = await generate_localized_response(
+        context=(
+            f"Tell the landlord/agent the viewing of '{property_name}' is confirmed — "
+            f"a visitor will come on {confirmed_slot}. Let them know you'll send a reminder "
+            "closer to the time. Sound professional and warm. Include a 🏠 emoji."
+        ),
+        language=_lang(landlord),
+        tone="friendly",
+        max_length="short",
+    )
+
+    await _send_aida_dm(visitor_id, visitor_msg)
+    await _send_aida_dm(landlord_id, landlord_msg)
+
+    logger.info(f"Viewing {viewing_id} confirmed for slot: {confirmed_slot}")

main.py

@@ -91,8 +91,17 @@ except ImportError as e:
 
 from app.models.listing import ensure_listing_indexes
 from app.models.booking import ensure_booking_indexes
+from app.models.viewing import ensure_viewing_indexes
 from app.jobs.payout_jobs import process_escrow_payouts
-from app.jobs.stay_notification_jobs import dispatch_stay_control_cards
+from app.jobs.stay_notification_jobs import (
+    dispatch_stay_control_cards,
+    dispatch_checkin_reminders,
+    dispatch_checkout_review_requests,
+)
+from app.jobs.viewing_notification_jobs import (
+    dispatch_viewing_reminders,
+    dispatch_post_viewing_followups,
+)
 
 # ENVIRONMENT
 environment = os.getenv("ENVIRONMENT", "development")
@@ -116,6 +125,7 @@ async def lifespan(app: FastAPI):
         await ensure_auth_indexes()
         await ensure_listing_indexes()
         await ensure_booking_indexes()
+        await ensure_viewing_indexes()
         await ensure_review_indexes()
         
         # Import and create chat indexes
@@ -190,8 +200,12 @@ async def lifespan(app: FastAPI):
 
     # Initialize APScheduler for Background Jobs (Payouts & Escrow)
     scheduler = AsyncIOScheduler()
-    scheduler.add_job(process_escrow_payouts, 'interval', minutes=30)
-    scheduler.add_job(dispatch_stay_control_cards, 'interval', hours=1) # Runs every hour to check for 8 AM and 10 AM thresholds
+    scheduler.add_job(process_escrow_payouts, "interval", minutes=30)
+    scheduler.add_job(dispatch_stay_control_cards, "interval", hours=1)       # check-in/checkout cards at 8 AM / 10 AM
+    scheduler.add_job(dispatch_checkin_reminders, "interval", minutes=30)     # 3-hour pre-check-in reminder
+    scheduler.add_job(dispatch_checkout_review_requests, "interval", minutes=30)  # post-checkout review request
+    scheduler.add_job(dispatch_viewing_reminders, "interval", minutes=30)     # 3-hour pre-viewing reminder
+    scheduler.add_job(dispatch_post_viewing_followups, "interval", minutes=30)    # post-viewing follow-up
 
     # Register proactive alert scheduler
     try:

tests/test_todays_features.py

@@ -0,0 +1,314 @@
+# tests/test_todays_features.py
+"""
+Automated tests for logic implemented in today's session.
+Covers everything that does NOT require a running DB or LLM.
+
+Run with:
+    cd python-Backend/lojiz-backend/AIDA
+    pytest tests/test_todays_features.py -v
+"""
+
+import sys
+import os
+sys.path.insert(0, os.path.dirname(os.path.dirname(os.path.abspath(__file__))))
+
+import pytest
+from datetime import datetime
+
+
+# ============================================================
+# 1. AGENT HUB — fast keyword routing
+# ============================================================
+
+from app.ai.agent.agent_hub import (
+    _fast_route,
+    AGENT_GENERAL,
+    AGENT_CONCIERGE,
+    AGENT_BROKER,
+    AGENT_MATCHER,
+    HANDOFF_MAP,
+    get_agent_display_name,
+)
+from app.ai.agent.state import AgentState
+
+
+def _state(role: str = "renter") -> AgentState:
+    return AgentState(
+        user_id="test_user_001",
+        session_id="sess_001",
+        user_role=role,
+    )
+
+
+class TestFastRoute:
+    def test_roommate_keywords_route_to_matcher(self):
+        msgs = [
+            "I'm looking for a roommate",
+            "cherche colocataire",
+            "want a flatmate",
+            "I have a spare room",
+            "share my apartment with someone",
+            "find a roommate for me",
+        ]
+        for msg in msgs:
+            assert _fast_route(msg, _state()) == AGENT_MATCHER, f"Failed for: {msg}"
+
+    def test_viewing_keywords_route_to_broker(self):
+        msgs = [
+            "schedule a viewing",
+            "book a viewing",
+            "schedule a visit",
+            "when can i visit the property",
+            "planifier une visite",
+            "book an appointment",
+        ]
+        for msg in msgs:
+            assert _fast_route(msg, _state()) == AGENT_BROKER, f"Failed for: {msg}"
+
+    def test_booking_keywords_route_to_concierge(self):
+        msgs = [
+            "book this place",
+            "i want to book",
+            "confirm booking",
+            "check-in next friday",
+            "réserver cet appartement",
+            "initiate booking",
+        ]
+        for msg in msgs:
+            assert _fast_route(msg, _state()) == AGENT_CONCIERGE, f"Failed for: {msg}"
+
+    def test_listing_by_landlord_routes_to_general(self):
+        msgs = [
+            "list my property",
+            "list my apartment",
+            "i want to list",
+            "publish my property",
+        ]
+        for msg in msgs:
+            result = _fast_route(msg, _state(role="landlord"))
+            assert result == AGENT_GENERAL, f"Landlord listing failed for: {msg}"
+
+    def test_listing_by_renter_routes_to_matcher(self):
+        """Renters can only list roommate spaces — redirect to matcher."""
+        msgs = [
+            "list my property",
+            "i want to list",
+        ]
+        for msg in msgs:
+            result = _fast_route(msg, _state(role="renter"))
+            assert result == AGENT_MATCHER, f"Renter listing should go to matcher: {msg}"
+
+    def test_ambiguous_message_returns_none(self):
+        msgs = [
+            "hello",
+            "what are the prices in Lagos?",
+            "tell me about this property",
+            "how does lojiz work?",
+        ]
+        for msg in msgs:
+            assert _fast_route(msg, _state()) is None, f"Should be None for ambiguous: {msg}"
+
+    def test_roommate_takes_priority_over_booking(self):
+        """Roommate is highest-confidence — checked before booking."""
+        msg = "I want to book a roommate place"
+        assert _fast_route(msg, _state()) == AGENT_MATCHER
+
+    def test_case_insensitive(self):
+        assert _fast_route("SCHEDULE A VIEWING", _state()) == AGENT_BROKER
+        assert _fast_route("Book This", _state()) == AGENT_CONCIERGE
+        assert _fast_route("ROOMMATE needed", _state()) == AGENT_MATCHER
+
+
+# ============================================================
+# 2. HANDOFF MAP completeness
+# ============================================================
+
+class TestHandoffMap:
+    def test_all_handoff_signals_are_mapped(self):
+        required = {"HANDOFF_CONCIERGE", "HANDOFF_BROKER", "HANDOFF_MATCHER", "HANDOFF_GENERAL"}
+        assert required == set(HANDOFF_MAP.keys())
+
+    def test_handoff_targets_are_valid_agent_ids(self):
+        valid = {AGENT_GENERAL, AGENT_CONCIERGE, AGENT_BROKER, AGENT_MATCHER}
+        for signal, target in HANDOFF_MAP.items():
+            assert target in valid, f"Bad target {target} for {signal}"
+
+
+# ============================================================
+# 3. AGENT DISPLAY NAMES
+# ============================================================
+
+class TestGetAgentDisplayName:
+    def test_known_agents(self):
+        assert get_agent_display_name(AGENT_GENERAL) == "AIDA"
+        assert get_agent_display_name(AGENT_CONCIERGE) == "AIDA-Primary (Concierge)"
+        assert get_agent_display_name(AGENT_BROKER) == "AIDA-Market (Broker)"
+        assert get_agent_display_name(AGENT_MATCHER) == "AIDA-Social (Matcher)"
+
+    def test_unknown_agent_falls_back(self):
+        assert get_agent_display_name("unknown_agent") == "AIDA"
+        assert get_agent_display_name("") == "AIDA"
+
+
+# ============================================================
+# 4. BROKER BRAIN — viewing step inference
+# ============================================================
+
+from app.ai.agent.broker_brain import _infer_viewing_step
+
+VISITOR_ID  = "visitor_123"
+LANDLORD_ID = "landlord_456"
+
+
+def _viewing(
+    status="pending",
+    visitor_avail=None,
+    landlord_avail=None,
+    suggested=None,
+    confirmed_slot=None,
+):
+    return {
+        "visitor_id": VISITOR_ID,
+        "landlord_id": LANDLORD_ID,
+        "status": status,
+        "visitor_availability": visitor_avail or [],
+        "landlord_availability": landlord_avail or [],
+        "suggested_slots": suggested or [],
+        "confirmed_slot": confirmed_slot,
+    }
+
+
+class TestInferViewingStep:
+    def test_confirmed_viewing(self):
+        v = _viewing(status="confirmed")
+        assert _infer_viewing_step(v, VISITOR_ID) == "viewing_confirmed"
+        assert _infer_viewing_step(v, LANDLORD_ID) == "viewing_confirmed"
+
+    def test_confirmed_slot_pending_landlord(self):
+        v = _viewing(confirmed_slot="Monday 10am")
+        assert _infer_viewing_step(v, VISITOR_ID) == "landlord_confirm_slot"
+
+    def test_suggested_slots_visitor_picks(self):
+        v = _viewing(suggested=["Mon 10am", "Tue 2pm"])
+        assert _infer_viewing_step(v, VISITOR_ID) == "visitor_pick_slot"
+
+    def test_visitor_has_no_availability_yet(self):
+        v = _viewing()
+        assert _infer_viewing_step(v, VISITOR_ID) == "collect_visitor_availability"
+
+    def test_landlord_has_no_availability_yet(self):
+        v = _viewing()
+        assert _infer_viewing_step(v, LANDLORD_ID) == "collect_landlord_availability"
+
+    def test_visitor_submitted_waiting_for_landlord(self):
+        v = _viewing(visitor_avail=["Monday 9am"])
+        assert _infer_viewing_step(v, LANDLORD_ID) == "collect_landlord_availability"
+
+    def test_landlord_submitted_waiting_for_visitor(self):
+        v = _viewing(landlord_avail=["Tuesday 3pm"])
+        assert _infer_viewing_step(v, VISITOR_ID) == "collect_visitor_availability"
+
+    def test_both_submitted_ready_for_crosscheck(self):
+        v = _viewing(visitor_avail=["Mon 9am"], landlord_avail=["Mon 9am", "Tue 11am"])
+        assert _infer_viewing_step(v, VISITOR_ID) == "cross_check"
+
+
+# ============================================================
+# 5. AGENT STATE — new fields exist and default correctly
+# ============================================================
+
+class TestAgentStateNewFields:
+    def test_active_agent_defaults_to_none(self):
+        state = _state()
+        assert state.active_agent is None
+
+    def test_agent_context_defaults_to_empty_dict(self):
+        state = _state()
+        assert state.agent_context == {}
+
+    def test_active_agent_can_be_set(self):
+        state = _state()
+        state.active_agent = AGENT_CONCIERGE
+        assert state.active_agent == AGENT_CONCIERGE
+
+    def test_agent_context_can_be_populated(self):
+        state = _state()
+        state.agent_context["booking"] = {"_id": "abc", "status": "Pending"}
+        assert state.agent_context["booking"]["status"] == "Pending"
+
+    def test_serialization_includes_new_fields(self):
+        state = _state()
+        state.active_agent = AGENT_BROKER
+        state.agent_context["viewing"] = {"_id": "xyz"}
+        dumped = state.model_dump()
+        assert dumped["active_agent"] == AGENT_BROKER
+        assert dumped["agent_context"]["viewing"]["_id"] == "xyz"
+
+
+# ============================================================
+# 6. AGENT STATE — existing flow transitions still work
+# ============================================================
+
+from app.ai.agent.state import FlowState
+
+
+class TestFlowTransitions:
+    def test_idle_to_classify_intent(self):
+        state = _state()
+        ok, err = state.transition_to(FlowState.CLASSIFY_INTENT, "test")
+        assert ok and err is None
+
+    def test_listing_collect_to_validate(self):
+        state = _state()
+        state.current_flow = FlowState.LISTING_COLLECT
+        ok, err = state.transition_to(FlowState.LISTING_VALIDATE, "test")
+        assert ok
+
+    def test_invalid_transition_rejected(self):
+        state = _state()
+        state.current_flow = FlowState.SEARCH_RESULTS
+        ok, err = state.transition_to(FlowState.LISTING_PUBLISH, "test")
+        assert not ok
+        assert "Cannot transition" in err
+
+    def test_steps_taken_increments(self):
+        state = _state()
+        initial = state.steps_taken
+        state.transition_to(FlowState.CLASSIFY_INTENT, "test")
+        assert state.steps_taken == initial + 1
+
+
+# ============================================================
+# 7. CONCIERGE / MATCHER TOOL NAME SETS
+# ============================================================
+
+from app.ai.agent.concierge_brain import CONCIERGE_TOOL_NAMES
+from app.ai.agent.broker_brain import BROKER_TOOL_NAMES
+from app.ai.agent.matcher_brain import MATCHER_TOOL_NAMES
+
+
+class TestToolNameSets:
+    def test_concierge_has_booking_tools(self):
+        required = {"initiate_booking", "confirm_booking", "check_availability", "calculate_booking_cost"}
+        assert required.issubset(CONCIERGE_TOOL_NAMES)
+
+    def test_concierge_does_not_have_viewing_tools(self):
+        assert "schedule_visit" not in CONCIERGE_TOOL_NAMES
+        assert "confirm_viewing" not in CONCIERGE_TOOL_NAMES
+
+    def test_broker_has_viewing_tools(self):
+        required = {"schedule_visit", "confirm_viewing", "check_calendar_availability"}
+        assert required.issubset(BROKER_TOOL_NAMES)
+
+    def test_broker_does_not_have_booking_tools(self):
+        assert "initiate_booking" not in BROKER_TOOL_NAMES
+        assert "confirm_booking" not in BROKER_TOOL_NAMES
+
+    def test_matcher_has_listing_tools(self):
+        required = {"update_listing", "publish_listing", "get_my_listings"}
+        assert required.issubset(MATCHER_TOOL_NAMES)
+
+    def test_all_sets_contain_respond(self):
+        assert "respond" in CONCIERGE_TOOL_NAMES
+        assert "respond" in BROKER_TOOL_NAMES
+        assert "respond" in MATCHER_TOOL_NAMES