fyp

app/ai/agent/agent_hub.py

@@ -37,12 +37,14 @@ 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
+AGENT_SCOUT = "scout"           # proactive property-hunting agent
 
 HANDOFF_MAP = {
     "HANDOFF_CONCIERGE": AGENT_CONCIERGE,
     "HANDOFF_BROKER": AGENT_BROKER,
     "HANDOFF_MATCHER": AGENT_MATCHER,
     "HANDOFF_GENERAL": AGENT_GENERAL,
+    "HANDOFF_SCOUT": AGENT_SCOUT,
 }
 
 # ============================================================
@@ -56,6 +58,9 @@ _BOOK_TAG_PATTERN   = _re_hub_signals.compile(r'\[BOOK_LISTING:[^\]]+\]')
 _COMPARE_TAG_PATTERN = _re_hub_signals.compile(r'\[COMPARE_LISTINGS:[^\]]+\]|\[COMPARE_PROPERTIES:[^\]]+\]')
 _SCHEDULE_TAG_PATTERN = _re_hub_signals.compile(r'\[SCHEDULE_VIEWING:[^\]]+\]')
 
+# @Scout / @Démarcheur mention — highest priority, always routes to Scout
+_SCOUT_MENTION_PATTERN = _re_hub_signals.compile(r'@[Ss]cout|@[Dd][eé]marcheur', _re_hub_signals.IGNORECASE)
+
 # Roommate — seeker intent in any language
 _ROOMMATE_SIGNALS = [
     "roommate", "room mate", "colocataire", "colocation", "co-living", "coliving",
@@ -79,6 +84,10 @@ def _fast_route(message: str, state: AgentState) -> Optional[str]:
     """
     msg = message.lower()
 
+    # @Scout / @Démarcheur mention — absolute highest priority
+    if _SCOUT_MENTION_PATTERN.search(message):
+        return AGENT_SCOUT
+
     # Button-tag triggers (highest priority — unambiguous UI actions)
     if _BOOK_TAG_PATTERN.search(message) or _COMPARE_TAG_PATTERN.search(message):
         return AGENT_CONCIERGE
@@ -193,7 +202,7 @@ async def classify_intent(
             caller="hub_classify_intent",
         )
         result = response.content.strip().lower().split()[0]
-        if result in (AGENT_GENERAL, AGENT_CONCIERGE, AGENT_BROKER, AGENT_MATCHER):
+        if result in (AGENT_GENERAL, AGENT_CONCIERGE, AGENT_BROKER, AGENT_MATCHER, AGENT_SCOUT):
             logger.info("Hub LLM-classified intent", result=result, message=message[:60])
             return result
     except Exception as e:
@@ -221,6 +230,10 @@ async def _dispatch(agent_id: str, state: AgentState) -> AgentState:
         from app.ai.agent.matcher_brain import process
         return await process(state)
 
+    elif agent_id == AGENT_SCOUT:
+        from app.ai.agent.scout_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
@@ -781,4 +794,5 @@ def get_agent_display_name(agent_id: str) -> str:
         AGENT_CONCIERGE: "AIDA-Primary (Concierge)",
         AGENT_BROKER: "AIDA-Market (Broker)",
         AGENT_MATCHER: "AIDA-Social (Matcher)",
+        AGENT_SCOUT: "Scout",
     }.get(agent_id, "AIDA")

app/ai/agent/scout_brain.py

@@ -0,0 +1,292 @@
+# app/ai/agent/scout_brain.py
+"""
+Scout (EN) / Démarcheur (FR) — Proactive property-hunting agent.
+
+Scout is triggered whenever the user mentions @Scout or @Démarcheur in
+AIDA chat or AIDA DM. She manages search mandates: hunts properties in
+the background and delivers results as personal DM messages.
+
+Mandate lifecycle:
+  ACTIVE   → Scout is searching; results delivered via DM
+  PAUSED   → User paused the mandate
+  COMPLETED → User found what they wanted
+  EXPIRED  → Deadline passed or 30 days of inactivity
+
+Scout NEVER initiates conversation — users must @mention her.
+Scout NEVER repeats the same listing twice per mandate.
+"""
+
+import re
+import json
+import random
+import logging
+from datetime import datetime, timedelta
+from typing import Optional
+
+from structlog import get_logger
+from bson import ObjectId
+
+from app.ai.agent.state import AgentState
+from app.ai.agent.actions import AgentAction, set_action
+from app.ai.agent.brain import _invoke_with_fallback, generate_localized_response
+from app.database import get_db
+from app.models.scout_mandate import ScoutMandate, MandateStatus
+
+logger = get_logger(__name__)
+
+# ── Persona ──────────────────────────────────────────────────────────────────
+
+_SCOUT_INTRO = {
+    "en": "I'm Scout — I hunt properties for you in the background.",
+    "fr": "Je suis Scout — je cherche des biens pour toi en arrière-plan.",
+}
+
+_CONFIRM_CREATE = {
+    "en": [
+        "On it! I'll start hunting and ping you in this DM when I find something good. 🔍",
+        "Mandate received. I'll search quietly and drop results right here when I find matches. 🏠",
+        "Got it — I'll track this for you. I'll message you here whenever something fits.",
+        "Consider it done. I'll keep an eye out and DM you when something shows up.",
+    ],
+    "fr": [
+        "C'est noté ! Je commence à chercher et je te préviens ici dès que je trouve quelque chose. 🔍",
+        "Mandat reçu. Je cherche en silence et je t'envoie les résultats ici dès qu'il y a des correspondances. 🏠",
+        "Compris — je vais surveiller ça pour toi. Je te dis ici quand quelque chose correspond.",
+        "Considère c'est fait. Je garde un œil et je t'écris dès qu'un bien apparaît.",
+    ],
+}
+
+_CONFIRM_PAUSE = {
+    "en": "OK, I've paused that mandate. Say '@Scout resume' whenever you want me back on it.",
+    "fr": "OK, j'ai mis ce mandat en pause. Dis '@Scout reprends' quand tu veux que je reprenne.",
+}
+
+_CONFIRM_STOP = {
+    "en": "Mandate stopped. Let me know if you ever need me to search for something else.",
+    "fr": "Mandat arrêté. Dis-moi si tu as besoin que je cherche autre chose.",
+}
+
+_NO_MANDATES = {
+    "en": "You don't have any active mandates right now. Tell me what to hunt — for example: '@Scout find me a 2-bed apartment in Cotonou under 150k'.",
+    "fr": "Tu n'as aucun mandat actif pour le moment. Dis-moi ce qu'il faut chercher — par exemple : '@Scout trouve-moi un appartement 2 chambres à Cotonou sous 150k'.",
+}
+
+
+def _pick(pool: list) -> str:
+    return random.choice(pool)
+
+
+def _lang(state: AgentState) -> str:
+    return (state.language_detected or state.app_language or "en")[:2].lower()
+
+
+# ── Mandate extraction via LLM ────────────────────────────────────────────────
+
+_EXTRACT_PROMPT = """You are a parameter extractor for Scout, a property-hunting agent.
+
+Extract search mandate parameters from the user's message. Reply with ONLY valid JSON.
+
+User message: {message}
+
+Return this schema (omit any field that is not mentioned):
+{{
+  "action": "create" | "list" | "pause" | "stop" | "resume" | "status",
+  "search_params": {{
+    "location": "string or null",
+    "listing_type": "rent" | "sale" | "short-stay" | "roommate" | null,
+    "max_price": number or null,
+    "min_price": number or null,
+    "bedrooms": number or null,
+    "amenities": ["string"] or null
+  }},
+  "deadline_days": number or null,
+  "user_query": "cleaned original intent, max 80 chars"
+}}
+
+Rules:
+- "action" is REQUIRED — infer from context (mention of "find", "hunt", "search" = create; "pause", "stop", "cancel" = stop; "list", "what mandates", "my mandates" = list; "resume", "continue", "restart" = resume).
+- If action is not create, omit search_params.
+- deadline_days: only set if user mentions a time limit (e.g. "find within 3 days" → 3).
+- Reply with ONLY the JSON object. No explanation."""
+
+
+async def _extract_mandate(message: str, state: AgentState) -> dict:
+    from langchain_core.messages import HumanMessage
+    try:
+        prompt = _EXTRACT_PROMPT.format(message=message)
+        resp = await _invoke_with_fallback(
+            [HumanMessage(content=prompt)],
+            caller="scout_extract_mandate",
+        )
+        raw = resp.content.strip()
+        # strip markdown fences if present
+        raw = re.sub(r"^```json\s*", "", raw, flags=re.IGNORECASE)
+        raw = re.sub(r"```$", "", raw)
+        return json.loads(raw)
+    except Exception as e:
+        logger.warning("Scout: mandate extraction failed", error=str(e))
+        return {"action": "create", "search_params": {}, "user_query": message[:80]}
+
+
+# ── DB helpers ────────────────────────────────────────────────────────────────
+
+async def _get_active_mandates(user_id: str) -> list[ScoutMandate]:
+    db = await get_db()
+    cursor = db["scout_mandates"].find({
+        "user_id": user_id,
+        "status": {"$in": [MandateStatus.ACTIVE.value, MandateStatus.PAUSED.value]},
+    })
+    mandates = []
+    async for doc in cursor:
+        mandates.append(ScoutMandate(**doc))
+    return mandates
+
+
+async def _create_mandate(user_id: str, params: dict, query: str, language: str, deadline_days: Optional[int]) -> ScoutMandate:
+    db = await get_db()
+    deadline = datetime.utcnow() + timedelta(days=deadline_days) if deadline_days else None
+    mandate = ScoutMandate(
+        user_id=user_id,
+        search_params=params,
+        user_query=query,
+        language=language,
+        deadline=deadline,
+        status=MandateStatus.ACTIVE,
+    )
+    doc = mandate.model_dump(by_alias=True, exclude={"id"})
+    result = await db["scout_mandates"].insert_one(doc)
+    inserted = await db["scout_mandates"].find_one({"_id": result.inserted_id})
+    return ScoutMandate(**inserted)
+
+
+async def _pause_latest_mandate(user_id: str) -> bool:
+    db = await get_db()
+    doc = await db["scout_mandates"].find_one(
+        {"user_id": user_id, "status": MandateStatus.ACTIVE.value},
+        sort=[("created_at", -1)],
+    )
+    if not doc:
+        return False
+    await db["scout_mandates"].update_one(
+        {"_id": doc["_id"]},
+        {"$set": {"status": MandateStatus.PAUSED.value}},
+    )
+    return True
+
+
+async def _resume_latest_mandate(user_id: str) -> bool:
+    db = await get_db()
+    doc = await db["scout_mandates"].find_one(
+        {"user_id": user_id, "status": MandateStatus.PAUSED.value},
+        sort=[("created_at", -1)],
+    )
+    if not doc:
+        return False
+    await db["scout_mandates"].update_one(
+        {"_id": doc["_id"]},
+        {"$set": {"status": MandateStatus.ACTIVE.value}},
+    )
+    return True
+
+
+async def _stop_latest_mandate(user_id: str) -> bool:
+    db = await get_db()
+    doc = await db["scout_mandates"].find_one(
+        {"user_id": user_id, "status": {"$in": [MandateStatus.ACTIVE.value, MandateStatus.PAUSED.value]}},
+        sort=[("created_at", -1)],
+    )
+    if not doc:
+        return False
+    await db["scout_mandates"].update_one(
+        {"_id": doc["_id"]},
+        {"$set": {"status": MandateStatus.COMPLETED.value}},
+    )
+    return True
+
+
+def _mandate_summary(mandates: list[ScoutMandate], lang: str) -> str:
+    if not mandates:
+        return _NO_MANDATES.get(lang, _NO_MANDATES["en"])
+    lines = []
+    for m in mandates:
+        status_emoji = "🟢" if m.status == MandateStatus.ACTIVE else "⏸"
+        deadline_str = f" (until {m.deadline.strftime('%b %d')})" if m.deadline else ""
+        lines.append(f"{status_emoji} {m.user_query}{deadline_str} — {m.delivery_count} result(s) sent")
+    header = "Your mandates:" if lang == "en" else "Tes mandats :"
+    return f"{header}\n" + "\n".join(lines)
+
+
+# ── Main process entry point ──────────────────────────────────────────────────
+
+async def process(state: AgentState) -> AgentState:
+    """Scout brain entry point — called by agent_hub when @Scout is detected."""
+    lang = _lang(state)
+    message = (state.last_user_message or "").strip()
+    user_id = state.user_id
+
+    try:
+        extracted = await _extract_mandate(message, state)
+        action = extracted.get("action", "create")
+        params = extracted.get("search_params", {})
+        query = extracted.get("user_query", message[:80])
+        deadline_days = extracted.get("deadline_days")
+
+        if action == "list" or action == "status":
+            mandates = await _get_active_mandates(user_id)
+            reply = _mandate_summary(mandates, lang)
+
+        elif action == "pause":
+            ok = await _pause_latest_mandate(user_id)
+            reply = _CONFIRM_PAUSE.get(lang, _CONFIRM_PAUSE["en"]) if ok else (
+                "No active mandate to pause." if lang == "en" else "Aucun mandat actif à mettre en pause."
+            )
+
+        elif action == "resume":
+            ok = await _resume_latest_mandate(user_id)
+            reply = (
+                ("Resumed! I'm back on it. 🔍" if lang == "en" else "Repris ! Je suis de retour. 🔍") if ok else
+                ("No paused mandate found." if lang == "en" else "Aucun mandat en pause trouvé.")
+            )
+
+        elif action == "stop":
+            ok = await _stop_latest_mandate(user_id)
+            reply = _CONFIRM_STOP.get(lang, _CONFIRM_STOP["en"]) if ok else (
+                "No active mandate to stop." if lang == "en" else "Aucun mandat actif à arrêter."
+            )
+
+        else:
+            # Default: create mandate
+            if not params.get("location") and not params.get("listing_type"):
+                # Unclear — ask for more details
+                reply = await generate_localized_response(
+                    context=(
+                        "The user wants Scout to find a property but hasn't specified enough details. "
+                        "Ask them to clarify: what type of property, where, and their budget. "
+                        "Be conversational, 1-2 sentences, Scout persona."
+                    ),
+                    language=lang,
+                    tone="friendly",
+                    max_length="short",
+                )
+            else:
+                mandate = await _create_mandate(user_id, params, query, lang, deadline_days)
+                reply = _pick(_CONFIRM_CREATE.get(lang, _CONFIRM_CREATE["en"]))
+                logger.info(
+                    "Scout: mandate created",
+                    mandate_id=mandate.id,
+                    user_id=user_id,
+                    query=query,
+                )
+
+    except Exception as e:
+        logger.error("Scout brain error", error=str(e), user_id=user_id)
+        reply = await generate_localized_response(
+            context="Tell the user Scout hit a small snag and to try again in a moment. Keep it light.",
+            language=lang,
+            tone="friendly",
+            max_length="short",
+        )
+
+    state.temp_data["response_text"] = reply
+    set_action(state, AgentAction.RESPOND)
+    return state

app/ai/services/search_responder.py

@@ -5,6 +5,7 @@ Used by both the REST API and the AI Agent.
 """
 
 import logging
+import random
 from app.core.mimo_client import get_mimo_client
 
 logger = logging.getLogger(__name__)
@@ -57,6 +58,30 @@ YOUR TASK - Generate a NATURAL, CONVERSATIONAL response:
 
 Write ONLY the response message (no quotes, no extra formatting)."""
 
+# Scout ad pool — one is picked randomly and appended after every search result.
+# Kept human-toned and varied so users don't feel they're seeing the same bot ad.
+_SCOUT_ADS_EN = [
+    "you know I actually have a peer called Scout who can keep hunting this for you — just say '@Scout [what you want]' and she goes and does it.",
+    "by the way, if you want someone to track this automatically, Scout's got you — mention '@Scout [your search]' anytime.",
+    "not exactly what you wanted? Scout can search for it 24/7 while you sleep. Just say '@Scout find me [what you want]'.",
+    "want these results to come to you automatically? Try '@Scout [describe it]' and she'll ping you here whenever something fits.",
+    "Scout can keep an eye out for you — just drop '@Scout [what you're looking for]' and she handles the rest.",
+]
+_SCOUT_ADS_FR = [
+    "tu sais, j'ai une collègue qui s'appelle Scout et qui peut continuer à chercher ça pour toi — dis juste '@Scout [ce que tu veux]' et elle s'en occupe.",
+    "au fait, si tu veux que quelqu'un traque ça automatiquement, Scout est là — mentionne '@Scout [ta recherche]' n'importe quand.",
+    "pas exactement ce que tu cherchais ? Scout peut rechercher 24h/24. Dis juste '@Scout trouve-moi [ce que tu veux]'.",
+    "tu veux recevoir des résultats automatiquement ? Essaie '@Scout [décris]' et elle te prévient ici dès qu'il y a une correspondance.",
+    "Scout peut surveiller ça pour toi — dis '@Scout [ce que tu cherches]' et elle s'occupe du reste.",
+]
+
+
+def get_scout_ad(language: str = "en") -> str:
+    """Return a random, rotating Scout advertisement in the user's language."""
+    if language.startswith("fr"):
+        return random.choice(_SCOUT_ADS_FR)
+    return random.choice(_SCOUT_ADS_EN)
+
 
 async def generate_natural_response(
     user_query: str,
@@ -156,13 +181,16 @@ async def generate_natural_response(
         )
 
         message = raw.strip()
-        
+
         # Remove quotes if LLM added them
         if message.startswith('"') and message.endswith('"'):
             message = message[1:-1]
         if message.startswith("'") and message.endswith("'"):
             message = message[1:-1]
-        
+
+        # Append rotating Scout ad on every search result
+        message = f"{message}\n\n{get_scout_ad(user_lang)}"
+
         return message
     
     except Exception as e:

app/jobs/scout_jobs.py

@@ -0,0 +1,287 @@
+# app/jobs/scout_jobs.py
+"""
+Scout background job — runs every 4 hours.
+
+For each ACTIVE ScoutMandate:
+  1. Run the stored search_params against the listing DB.
+  2. Filter out already-delivered listings (delivered_listing_ids).
+  3. Score candidates — exact match first, then ±15% price / adjacent area.
+  4. Deliver up to 3 new results per run via AIDA DM.
+  5. Mark delivered listings so they are never repeated.
+  6. Expire mandates past their deadline or with no activity for 30 days.
+"""
+
+import logging
+import random
+from datetime import datetime, timedelta
+from typing import Optional
+
+from bson import ObjectId
+from app.database import get_db
+from app.models.scout_mandate import ScoutMandate, MandateStatus
+from app.models.conversation import Conversation
+from app.models.message import Message
+
+logger = logging.getLogger(__name__)
+
+AIDA_BOT_ID = "AIDA_BOT"
+MAX_RESULTS_PER_RUN = 3
+INACTIVITY_EXPIRY_DAYS = 30
+
+# ── Pitch templates (Scout's personal property pitch) ─────────────────────────
+
+_PITCHES_EN = [
+    "Hey, I found something that looks like a match for you 🏠",
+    "Scout here — this one just popped up and it fits your mandate.",
+    "Found a property that matches what you asked for. Take a look 👀",
+    "This just came up — I think you'd like it.",
+    "I've been watching and this one fits what you described. Worth a look!",
+]
+
+_PITCHES_FR = [
+    "Hey, j'ai trouvé quelque chose qui correspond à ton mandat 🏠",
+    "Scout ici — celui-là vient d'apparaître et il correspond à ta recherche.",
+    "J'ai trouvé un bien qui correspond à ce que tu cherchais. Regarde 👀",
+    "Ça vient de sortir — je crois que ça t'intéresserait.",
+    "Je surveillais et celui-là correspond à ce que tu m'as décrit. Ça vaut le coup !",
+]
+
+
+def _pick_pitch(language: str) -> str:
+    if language.startswith("fr"):
+        return random.choice(_PITCHES_FR)
+    return random.choice(_PITCHES_EN)
+
+
+# ── Search helper ─────────────────────────────────────────────────────────────
+
+async def _search_listings(params: dict, exclude_ids: list[str], limit: int = 10) -> list[dict]:
+    """Basic MongoDB search against the listings collection."""
+    db = await get_db()
+    query: dict = {"status": "active"}
+
+    location = params.get("location", "").strip()
+    if location:
+        query["$or"] = [
+            {"location": {"$regex": location, "$options": "i"}},
+            {"city": {"$regex": location, "$options": "i"}},
+            {"neighborhood": {"$regex": location, "$options": "i"}},
+            {"address": {"$regex": location, "$options": "i"}},
+        ]
+
+    listing_type = params.get("listing_type", "").strip()
+    if listing_type:
+        query["listing_type"] = listing_type
+
+    max_price = params.get("max_price")
+    min_price = params.get("min_price")
+    if max_price or min_price:
+        price_q: dict = {}
+        if min_price:
+            price_q["$gte"] = min_price * 0.85  # allow 15% below min
+        if max_price:
+            price_q["$lte"] = max_price * 1.15  # allow 15% above max
+        if price_q:
+            query["price"] = price_q
+
+    bedrooms = params.get("bedrooms")
+    if bedrooms is not None:
+        query["bedrooms"] = {"$in": [bedrooms - 1, bedrooms, bedrooms + 1]}
+
+    # Exclude already-delivered listings
+    if exclude_ids:
+        try:
+            oid_excludes = [ObjectId(lid) for lid in exclude_ids if ObjectId.is_valid(lid)]
+            if oid_excludes:
+                query["_id"] = {"$nin": oid_excludes}
+        except Exception:
+            pass
+
+    cursor = db["listings"].find(query).sort("createdAt", -1).limit(limit)
+    return await cursor.to_list(length=limit)
+
+
+# ── DM delivery ───────────────────────────────────────────────────────────────
+
+async def _get_or_create_aida_conversation(user_id: str) -> str:
+    db = await get_db()
+    participants = sorted([AIDA_BOT_ID, user_id])
+    participants_key = "::".join(participants)
+
+    existing = await db.conversations.find_one({"participants_key": participants_key})
+    if existing:
+        return str(existing["_id"])
+
+    conv_doc = Conversation.create_document(
+        listing_id="system",
+        participants=participants,
+        listing_title="AIDA Assistant",
+        listing_image=None,
+    )
+    try:
+        result = await db.conversations.insert_one(conv_doc)
+        return str(result.inserted_id)
+    except Exception as e:
+        if "duplicate key" in str(e).lower() or "E11000" in str(e):
+            existing = await db.conversations.find_one({"participants_key": participants_key})
+            if existing:
+                return str(existing["_id"])
+        raise
+
+
+async def _deliver_listing(mandate: ScoutMandate, listing: dict, conv_id: str) -> None:
+    """Send a Scout DM with the listing as a property card attachment."""
+    db = await get_db()
+    now = datetime.utcnow()
+
+    listing_id = str(listing.get("_id", ""))
+    pitch = _pick_pitch(mandate.language)
+
+    property_card = {
+        "listing_id": listing_id,
+        "title": listing.get("title", ""),
+        "price": listing.get("price"),
+        "currency": listing.get("currency", "XOF"),
+        "bedrooms": listing.get("bedrooms"),
+        "location": listing.get("location") or listing.get("city", ""),
+        "image_url": (listing.get("images") or [None])[0],
+        "listing_type": listing.get("listing_type", ""),
+    }
+
+    message_doc = Message.create_document(
+        conversation_id=conv_id,
+        sender_id=AIDA_BOT_ID,
+        sender_name="Scout",
+        sender_avatar=None,
+        message_type="scout_result",
+        content=pitch,
+        property_card=property_card,
+    )
+    # Attach metadata so Flutter's bubble recognises this as a Scout result
+    message_doc["metadata"] = {
+        "scout_result": True,
+        "listing": {
+            "_id": listing_id,
+            "title": listing.get("title", ""),
+            "price": listing.get("price"),
+            "location": listing.get("location") or listing.get("city", ""),
+            "images": listing.get("images", [])[:1],
+            "listing_type": listing.get("listing_type", ""),
+            "bedrooms": listing.get("bedrooms"),
+        },
+    }
+    await db.messages.insert_one(message_doc)
+
+    # Update conversation last_message_at
+    await db.conversations.update_one(
+        {"_id": ObjectId(conv_id)},
+        {"$set": {"last_message_at": now, "last_message": pitch}},
+    )
+
+    # Mark in delivered_listing_ids
+    await db["scout_mandates"].update_one(
+        {"_id": ObjectId(mandate.id)},
+        {
+            "$addToSet": {"delivered_listing_ids": listing_id},
+            "$inc": {"delivery_count": 1},
+            "$set": {"last_run_at": now},
+        },
+    )
+
+    logger.info(
+        "Scout: delivered listing",
+        mandate_id=mandate.id,
+        listing_id=listing_id,
+        user_id=mandate.user_id,
+    )
+
+    # Push notification — wakes up the user even when the app is closed
+    try:
+        from app.services.push_service import PushService
+        listing_title = listing.get("title", "a new property")
+        await PushService.send_to_user(
+            user_id=mandate.user_id,
+            title="Scout found a match! 🏠",
+            body=f"{listing_title} — {listing.get('location') or ''}",
+            category="property_alerts",
+            data={
+                "type": "scout_result",
+                "listing_id": listing_id,
+                "mandate_id": mandate.id or "",
+            },
+        )
+    except Exception as _push_err:
+        logger.warning(f"Scout push notification failed (non-fatal): {_push_err}")
+
+
+# ── Expiry helpers ────────────────────────────────────────────────────────────
+
+async def _expire_stale_mandates() -> int:
+    db = await get_db()
+    cutoff = datetime.utcnow() - timedelta(days=INACTIVITY_EXPIRY_DAYS)
+    # Expire mandates that haven't run in 30 days OR whose deadline has passed
+    result = await db["scout_mandates"].update_many(
+        {
+            "status": {"$in": [MandateStatus.ACTIVE.value, MandateStatus.PAUSED.value]},
+            "$or": [
+                {"last_run_at": {"$lt": cutoff}, "last_run_at": {"$ne": None}},
+                {"created_at": {"$lt": cutoff}, "last_run_at": None},
+                {"deadline": {"$lt": datetime.utcnow(), "$ne": None}},
+            ],
+        },
+        {"$set": {"status": MandateStatus.EXPIRED.value}},
+    )
+    return result.modified_count
+
+
+# ── Main job ──────────────────────────────────────────────────────────────────
+
+async def dispatch_scout_job():
+    """
+    Main Scout background job. Called every 4 hours by APScheduler.
+    """
+    logger.info("[Scout] Starting background hunt job…")
+    db = await get_db()
+    now = datetime.utcnow()
+
+    # 1. Expire stale mandates first
+    expired = await _expire_stale_mandates()
+    if expired:
+        logger.info(f"[Scout] Expired {expired} stale mandate(s)")
+
+    # 2. Load all ACTIVE mandates
+    cursor = db["scout_mandates"].find({"status": MandateStatus.ACTIVE.value})
+    mandates = [ScoutMandate(**doc) async for doc in cursor]
+    logger.info(f"[Scout] Processing {len(mandates)} active mandate(s)")
+
+    for mandate in mandates:
+        try:
+            listings = await _search_listings(
+                mandate.search_params,
+                exclude_ids=mandate.delivered_listing_ids,
+                limit=MAX_RESULTS_PER_RUN + 5,  # fetch a few extra to allow scoring
+            )
+
+            if not listings:
+                # Update last_run_at even when empty so inactivity clock resets
+                await db["scout_mandates"].update_one(
+                    {"_id": ObjectId(mandate.id)},
+                    {"$set": {"last_run_at": now}},
+                )
+                logger.info(f"[Scout] No new results for mandate {mandate.id}")
+                continue
+
+            conv_id = await _get_or_create_aida_conversation(mandate.user_id)
+            delivered = 0
+            for listing in listings:
+                if delivered >= MAX_RESULTS_PER_RUN:
+                    break
+                await _deliver_listing(mandate, listing, conv_id)
+                delivered += 1
+
+            logger.info(f"[Scout] Delivered {delivered} result(s) for mandate {mandate.id}")
+
+        except Exception as e:
+            logger.error(f"[Scout] Error processing mandate {mandate.id}: {e}")
+
+    logger.info("[Scout] Hunt job complete")

app/models/scout_mandate.py

@@ -0,0 +1,38 @@
+from datetime import datetime
+from typing import Optional, List
+from enum import Enum
+from pydantic import BaseModel, Field, field_validator
+from bson import ObjectId
+
+
+class MandateStatus(str, Enum):
+    ACTIVE = "active"
+    PAUSED = "paused"
+    COMPLETED = "completed"
+    EXPIRED = "expired"
+
+
+class ScoutMandate(BaseModel):
+    id: Optional[str] = Field(alias="_id", default=None)
+    user_id: str
+    search_params: dict
+    user_query: str
+    language: str = "en"
+    deadline: Optional[datetime] = None
+    status: MandateStatus = MandateStatus.ACTIVE
+    created_at: datetime = Field(default_factory=datetime.utcnow)
+    last_run_at: Optional[datetime] = None
+    delivered_listing_ids: List[str] = Field(default_factory=list)
+    delivery_count: int = 0
+
+    @field_validator("id", mode="before")
+    @classmethod
+    def convert_objectid(cls, v):
+        if isinstance(v, ObjectId):
+            return str(v)
+        return v
+
+    class Config:
+        populate_by_name = True
+        arbitrary_types_allowed = True
+        json_encoders = {ObjectId: str}

main.py

@@ -96,6 +96,7 @@ from app.models.viewing import ensure_viewing_indexes
 from app.models.calendar import ensure_calendar_indexes
 from app.jobs.payout_jobs import process_escrow_payouts
 from app.jobs.agent_jobs import dispatch_agent_deadlock_check
+from app.jobs.scout_jobs import dispatch_scout_job
 from app.jobs.stay_notification_jobs import (
     dispatch_booking_status_transitions,
     dispatch_checkin_reminders,
@@ -237,6 +238,7 @@ async def lifespan(app: FastAPI):
     scheduler.add_job(_lock(dispatch_checkout_review_requests, 30), "interval", minutes=30)
     scheduler.add_job(_lock(dispatch_viewing_reminders, 30), "interval", minutes=30)
     scheduler.add_job(_lock(dispatch_post_viewing_followups, 30), "interval", minutes=30)
+    scheduler.add_job(_lock(dispatch_scout_job, 240), "interval", minutes=240)
 
     # Register proactive alert scheduler
     try:
@@ -299,7 +301,7 @@ _openapi_tags = [
     {"name": "Wishlist",                "description": "Save and manage favourite listings"},
     {"name": "Reviews",                 "description": "Property and user reviews"},
     {"name": "Notifications",           "description": "Push notification preferences and inbox"},
-    {"name": "Alerts",                  "description": "Saved search alerts"},
+    {"name": "Scout",                   "description": "Scout proactive property-hunting mandates"},
     {"name": "Stripe Connect",          "description": "Landlord payout accounts"},
     {"name": "Admin",                   "description": "Admin-only dashboard endpoints"},
     {"name": "Claim",                   "description": "Shadow-user account claim flow"},