feat: sanitize project structure + dynamic contact tool + export download fix

- Restructured repository to clean production FastAPI package layout
- Moved research docs, scratch scripts, and legacy routes to misc/
- Added COMMERCIAL_TOOLS with generate_contact_buttons for dynamic handoffs
- Configured direct file downloads (/download endpoint) in Appwrite storage
- Fixed middleware compression to preserve tool payload output for python tools
- Updated requirements.txt and verified test suite

README.Docker.md

@@ -1,22 +0,0 @@
-### Building and running your application
-
-When you're ready, start your application by running:
-`docker compose up --build`.
-
-Your application will be available at http://localhost:8000.
-
-### Deploying your application to the cloud
-
-First, build your image, e.g.: `docker build -t myapp .`.
-If your cloud uses a different CPU architecture than your development
-machine (e.g., you are on a Mac M1 and your cloud provider is amd64),
-you'll want to build the image for that platform, e.g.:
-`docker build --platform=linux/amd64 -t myapp .`.
-
-Then, push it to your registry, e.g. `docker push myregistry.com/myapp`.
-
-Consult Docker's [getting started](https://docs.docker.com/go/get-started-sharing/)
-docs for more detail on building and pushing.
-
-### References
-* [Docker's Python guide](https://docs.docker.com/language/python/)

config.py

@@ -4,6 +4,8 @@ from dotenv import load_dotenv
 load_dotenv()
 
 GROQ_API_KEY = os.environ.get("GROQ_API_KEY", "")
+GROQ_ROUTE_MODEL = os.environ.get("GROQ_ROUTE_MODEL", "openai/gpt-oss-20b")
+GROQ_SYNTHESIS_MODEL = os.environ.get("GROQ_SYNTHESIS_MODEL", "llama-3.3-70b-versatile")
 SUPABASE_URL = os.environ.get("SUPABASE_URL", "")
 SUPABASE_KEY = os.environ.get("SUPABASE_KEY", "")
 
@@ -13,3 +15,5 @@ APP_WRITE_API_KEY = os.environ.get("APP_WRITE_API_KEY", "")
 APP_WRITE_BUCKET_ID = os.environ.get("APP_WRITE_BUCKET_ID", "")
 
 MAPBOX_ACCESS_TOKEN = os.environ.get("MAPBOX_ACCESS_TOKEN", "")
+CONTACT_EMAIL = os.environ.get("CONTACT_EMAIL", "hello@example.com")
+CONTACT_WHATSAPP = os.environ.get("CONTACT_WHATSAPP", "1234567890")

methodology_kb.json

@@ -90,7 +90,7 @@
   },
   {
     "section_title": "About Joule Dynamics",
-    "chunk_content": "Joule Dynamics is an AI automation agency that builds and personally maintains live systems like this one — RAG pipelines, web scraping and monitoring, lead generation, and AI automation for businesses. This Real Estate Rate Monitor is one of several live systems Joule Dynamics runs; the others include a pricing-monitor system and a lead-generation system."
+    "chunk_content": "Joule Dynamics is an AI automation agency that builds and personally maintains live systems like this one — RAG pipelines, AI Agents, Large Langchain & LlamaIndex automations, web scraping and monitoring, lead generation, and AI automation for businesses. This Real Estate Rate Monitor is one of several live systems Joule Dynamics runs."
   },
   {
     "section_title": "What's Available Now",
@@ -107,5 +107,50 @@
   {
     "section_title": "What This Demo Represents",
     "chunk_content": "This is a real, live, working system built and operated by Joule Dynamics' founder personally — not a mature enterprise SaaS product with a large team behind it. Its scope (two markets, Airbnb-primary, a 2-night availability window) reflects genuine current capability, not a limitation being hidden. Custom builds are scoped to what's realistic to deliver, not oversold."
+  },
+  
+  {
+    "section_title": "The Live Demo Explained vs. Real Client Systems",
+    "chunk_content": "The dashboard and Pulse AI assistant you see on this page are a live demonstration. We track a small, hand-picked sample of short-term rentals in Miami and the New York/New Jersey Metro area to show exactly how our technology works in real-time. Because it is a small sample, it should not be used as complete market advice for those cities. When a property manager or investor hires us, we build them a completely private, secure system. Their custom build tracks only their specific properties and their direct local competitors, keeping their business data entirely isolated and confidential."
+  },
+  {
+    "section_title": "Meet Pulse: The AI Real Estate Assistant; Pulse Capabilities",
+    "chunk_content": "Pulse is the conversational intelligence layer you can interact with on this page. Instead of using generic AI guesses, Pulse reads the actual live data on our dashboard to answer your questions. You can ask Pulse to find sudden rate spikes or crashes, calculate the average nightly rates in Miami, check the 7-day pricing trends, or rank properties by how often they change their prices. It can also map distances between properties, search for specific bedroom counts, and give you a snapshot of what percentage of listings are currently booked. Details the specific capabilities of the Pulse AI assistant based on the live Rate Monitor. Covers its ability to filter by bedrooms, calculate geography, compare rates, and spot pricing anomalies in plain English."
+  },
+  {
+    "section_title": "Managing Inquiries: The Unified Triage Engine",
+    "chunk_content": "Property managers are constantly flooded with questions across emails, WhatsApp, and social media (Scoped to Facebook and Instagram Only) at all hours. A Triage Engine connects all these different channels into one smooth, organized inbox. When a prospect reaches out, the AI instantly reads the message, checks your property data, and immediately answers routine questions—like parking rules, availability, or office hours. This cuts response times down from hours to under 30 seconds, keeping potential renters engaged while your team focuses on higher-value work."
+  },
+  {
+    "section_title": "Smart Human Handoffs and Lead Routing for Unified Triage Engine",
+    "chunk_content": "The AI is smart enough to know its limits. If a potential renter asks to negotiate a price, wants a personalized recommendation, or is ready to close a deal, the AI stops instantly and alerts your human sales team. It sends your staff a quick summary of the entire conversation so they do not have to read through long chat histories. At the same time, the AI gives the customer your direct contact card so they can easily call you, ensuring the customer never feels stuck talking to a bot."
+  },
+  {
+    "section_title": "Built-in Safety and Fair Housing Compliance",
+    "chunk_content": "Real estate professionals face strict legal liabilities, which is why a custom built AI from us has built-in safety nets. To comply fully with Fair Housing laws, the AI is strictly blocked from answering any questions about neighborhood demographics, steering tenants to specific areas, or making subjective judgments about who qualifies for a lease. It is only permitted to auto-reply to objective, factual questions. Anything requiring judgment or subjective advice is safely passed to a human team member to review."
+  },
+  {
+    "section_title": "Why Real Estate Businesses Need This in 2026",
+    "chunk_content": "Why invest in Joule Dynamics' tools? The 2026 real estate and short-term rental markets are highly competitive. Supply growth has leveled out, and travelers are waiting longer to book, creating shorter booking windows. Relying on static pricing or manual research means losing money. By using our dynamic Competitor Rate Watch, operators can spot market trends instantly and adjust prices before competitors do. Furthermore, automating late-night tenant inquiries and maintenance requests ensures a premium customer experience without needing to hire a 24/7 call center staff."
+  },
+  {
+    "section_title": "Custom Data Dashboards We Build For Clients",
+    "chunk_content": "Beyond the live demo, we build customized data tools for property managers, agents, and investors. We build 'Competitor Rate Watch' to instantly notify you when rival properties drop their prices. We design 'Owner Acquisition Reports' to help property managers prove their value and win new contracts. We also build 'Automated Comp Sheets' that gather comparable pricing data in minutes instead of hours, and systems that flag off-market, distressed properties that have been sitting unsold or dropping their prices repeatedly."
+  },
+  {
+    "section_title": "Daily Operations: Guest and Tenant Assistants",
+    "chunk_content": "Operational use cases for the Pulse intelligence pattern. Our technology goes beyond pricing—it streamlines daily property management. For short-term rentals, we build 'Guest Concierges' that answer 24/7 questions about WiFi passwords, trash days, and smart locks based entirely on your exact house manual. For multifamily apartment buildings, we build 'Leasing Assistants' that automatically answer prospect questions about pet policies, deposit structures, and floor plans, instantly qualifying renters before they ever take up your team's time for a tour."
+  },
+  {
+    "section_title": "How Rate Monitoring Increases Bookings and Revenue",
+    "chunk_content": "Most property managers change their prices by hand, but they usually do it too late—after they have already lost guests to a competitor who lowered their price first. Our live rate monitor constantly watches prices across platforms like Airbnb. It compares current prices to the past week to find unusual changes instantly. By catching these changes immediately, property managers can adjust their own prices right away. This proactive approach typically helps properties get 12 to 18 percent more bookings because they are always priced competitively."
+  },
+  {
+    "section_title": "Data Tools for Real Estate Agents and Investors",
+    "chunk_content": "When real estate agents try to pitch a property to an investor, the investor wants proof that the property will make money. Instead of relying on guesswork, our custom systems create clear, easy-to-read reports showing exactly how much similar properties are earning and how often they are booked. We also help agents find hidden opportunities—like normal, long-term rental homes that could make a lot more money if they were converted into short-term vacation rentals. This gives agents the exact numbers they need to confidently show investors a great deal."
+  },
+  {
+    "section_title": "Managing Multiple Properties Easily",
+    "chunk_content": "If you manage many properties, it can be exhausting to check every single listing one by one to see how they are doing. We solve this by building a single, simple dashboard that puts all your properties in one place. You can see your entire portfolio at a glance, instantly spotting which homes are doing well and which ones need your attention today, saving you hours of clicking around."
   }
-]
+]

routes/real_estate_chat.py

@@ -1,68 +0,0 @@
-from typing import Any, Dict, List, Optional
-
-from fastapi import APIRouter, Depends, Request, BackgroundTasks
-from pydantic import BaseModel
-
-import logging
-
-logger = logging.getLogger(__name__)
-
-from services.groq_service import process_chat_message
-from services.rate_limiter import limiter
-
-router = APIRouter(
-    prefix="/api/v1/real-estate", tags=["Real Estate Intelligence Layer"]
-)
-
-
-class ChatRequest(BaseModel):
-    message: str
-    session_id: str
-    context: Optional[Dict[str, Any]] = {}
-
-
-class ChatResponse(BaseModel):
-    reply: str
-    path_used: str
-    tools_called: List[Dict[str, Any]]
-    suggested_actions: Optional[List[str]] = []
-
-
-@router.post("/chat", response_model=ChatResponse)
-async def handle_real_estate_chat(payload: ChatRequest, request: Request):
-    # Enforce token bucket rate limiting by session ID or client IP
-    client_key = payload.session_id or request.client.host
-    limiter.check_rate_limit(client_key)
-
-    try:
-        result = await process_chat_message(
-            user_query=payload.message,
-            session_id=payload.session_id,
-            session_context=payload.context or {},
-        )
-    except Exception as e:
-        logger.error(f"Error in handle_real_estate_chat: {e}")
-        return ChatResponse(
-            reply="Unable to reach the intelligence layer. Please try again shortly.",
-            path_used="ERROR",
-            tools_called=[],
-        )
-
-    return ChatResponse(
-        reply=result["reply"],
-        path_used=result["path_used"],
-        tools_called=result["tools_called"],
-        suggested_actions=result.get("suggested_actions", []),
-    )
-
-
-@router.get("/chat/starters")
-async def get_starter_prompts():
-    return {
-        "starters": [
-            "What's today's biggest rate spike?",
-            "What does the 7-day average mean?",
-            "Which Miami properties are unavailable right now?",
-            "How often is listing data refreshed?",
-        ]
-    }

services/appwrite_service.py

@@ -42,11 +42,11 @@ async def upload_document_to_appwrite(content: str, format: str) -> str:
             file=InputFile.from_path(temp_path)
         )
         
-        url = f"{APP_WRITE_API_ENDPOINT}/storage/buckets/{APP_WRITE_BUCKET_ID}/files/{file_id}/view?project={APP_WRITE_PROJECT_ID}"
-        return url
+        url = f"{APP_WRITE_API_ENDPOINT}/storage/buckets/{APP_WRITE_BUCKET_ID}/files/{file_id}/download?project={APP_WRITE_PROJECT_ID}"
+        return {"status": "success", "download_url": url, "filename": filename, "format": format}
     except Exception as e:
         logger.error(f"Appwrite Upload Error: {e}")
-        return f"Error uploading file: {e}"
+        return {"status": "error", "message": f"Failed to upload export file: {str(e)}"}
     finally:
         if os.path.exists(temp_path):
             os.remove(temp_path)

services/groq_service.py

@@ -7,11 +7,18 @@ import time
 import requests
 import numpy as np
 from groq import Groq
-from services.tools import REAL_ESTATE_TOOLS
+from services.tools import REAL_ESTATE_TOOLS, COMMERCIAL_TOOLS
 from services.supabase_service import execute_tool_rpc, search_methodology_rag
 from services.embedding_service import get_embedding_model
 from services.observability import setup_logger
-from config import GROQ_API_KEY, MAPBOX_ACCESS_TOKEN
+from config import (
+    GROQ_API_KEY,
+    MAPBOX_ACCESS_TOKEN,
+    CONTACT_EMAIL,
+    CONTACT_WHATSAPP,
+    GROQ_ROUTE_MODEL,
+    GROQ_SYNTHESIS_MODEL,
+)
 from langfuse import observe, propagate_attributes, get_client
 import langfuse
 
@@ -23,11 +30,15 @@ groq_client = Groq(api_key=GROQ_API_KEY)
 embedder = get_embedding_model()
 
 try:
-    if os.path.exists("section_title_embeddings.npy") and os.path.exists("section_titles.json"):
+    if os.path.exists("section_title_embeddings.npy") and os.path.exists(
+        "section_titles.json"
+    ):
         section_title_embeddings = np.load("section_title_embeddings.npy")
         with open("section_titles.json", "r", encoding="utf-8") as f:
             section_titles = json.load(f)
-        logger.info(f"Loaded {len(section_titles)} local section titles for pre-routing.")
+        logger.info(
+            f"Loaded {len(section_titles)} local section titles for pre-routing."
+        )
     else:
         section_title_embeddings = None
         section_titles = []
@@ -37,51 +48,50 @@ except Exception as e:
     section_titles = []
 
 ROUTER_PROMPT = """You are the classification router for the Joule Dynamics Real Estate Intelligence Layer.
-Analyze the user query and classify it into EXACTLY ONE of five classifications:
+Analyze the user query and classify it into EXACTLY ONE of six classifications:
 
-1. "OUT_OF_SCOPE": Query asks about Leads, Lead-capture, Pricing Monitor data, general web crawling, or cross-system topics outside of the /real-estate page.
+1. "OUT_OF_SCOPE": Query asks about Leads, general web crawling, or cross-system topics outside of the real estate domain.
 2. "PATH_A": Query asks a live-data question (prices, spikes, availability, market averages, KPIs, specific listing rates).
-3. "PATH_B": Query asks a methodology/system design question (7-day average definition, 2-night check-in window, 4x daily scrape cadence, Vrbo status, World Cup strategy).
+3. "PATH_B": Query asks a methodology/system design question (7-day average definition, 2-night check-in window, 4x daily scrape cadence).
 4. "BOTH": Query requires BOTH explaining a methodology concept AND fetching live data metrics.
 5. "GREETING": User is saying hello, thanking the assistant, or making casual conversation without asking a specific question.
+6. "COMMERCIAL_HANDOFF": Query asks about getting started, hiring Joule Dynamics, custom builds, pricing for the software, or requests tracking for their own specific portfolio outside the demo scope.
 
 Respond ONLY with valid JSON matching this schema:
-{"classification": "OUT_OF_SCOPE" | "PATH_A" | "PATH_B" | "BOTH" | "GREETING", "reason": "1-sentence justification"}
+{"classification": "OUT_OF_SCOPE" | "PATH_A" | "PATH_B" | "BOTH" | "GREETING" | "COMMERCIAL_HANDOFF", "reason": "1-sentence justification"}
 """
 
-SYNTHESIS_PROMPT = """You are the B2B Real Estate Intelligence Assistant for Joule Dynamics.
+SYNTHESIS_PROMPT = """You are Pulse AI, the B2B Real Estate Intelligence Assistant for Joule Dynamics.
 You provide precise data analysis to real estate investors and property managers reviewing short-term rental market performance.
 
 IMMUTABLE SYSTEM BOUNDARIES & HARD FACTS:
-1. TRACKED MARKETS: You ONLY track two markets: 'NYC/NJ Metro' and 'Miami'. 
-2. TRACKED PLATFORMS: You ONLY track two platforms: 'Airbnb' (Active daily tracking) and 'Vrbo' (Historical data only).
-3. ABSOLUTE FORBIDDEN ENTITIES: You must NEVER list, suggest, or mention any other cities (e.g., Los Angeles, Chicago, Houston, Orlando) or other booking platforms (e.g., Booking.com, Expedia, Tripadvisor). If asked about them, state plainly that they are outside Joule Dynamics' current tracking scope.
-4. ZERO FABRICATION: Every single price, rate change percentage, property count, and availability status MUST come directly from a returned tool output. If a tool returns no data or an error, state: "I don't have that information in the current real estate scope."
-5. NO RAW SQL: Never attempt to write or generate SQL queries. Rely strictly on the registered tool RPCs provided.
+1. SANDBOX SCOPE: The data you have access to is a proof-of-concept showcase tracking a curated sample of exactly 25 properties. It is NOT a complete city-wide market census. You must clarify this if a user attempts to use this data for macro-market investment decisions.
+2. TRACKED MARKETS: You ONLY track two markets: 'NYC/NJ Metro' and 'Miami'. 
+3. TRACKED PLATFORMS: You ONLY track 'Airbnb' (Active daily tracking) and 'Vrbo' (Historical data only).
+4. ABSOLUTE FORBIDDEN ENTITIES: You must NEVER list, suggest, or mention any other cities or other booking platforms.
+5. ZERO FABRICATION: Every single price, rate change percentage, property count, and availability status MUST come directly from a returned tool output. 
 
 OPERATIONAL RULES:
-1. NEVER FABRICATE DATA: Rely strictly on returned tool outputs or retrieved methodology chunks. NEVER write ad-hoc SQL. You must exclusively use the registered tools provided.
-2. ZERO GUESSING: If data or methodology is missing, state plainly: "I don't have that information in the current real estate scope."
-3. SCOPE BOUNDARY: If asked about Leads or Price Monitors, state that you are currently scoped exclusively to the Real Estate Rate Monitor.
-4. FORMAT: Always format your final output in valid Markdown. Ensure you use tables, bold headers, and bulleted lists to make data highly readable. NEVER include technical debugging headers or metadata in your response (e.g. do not write "Error Response", "Clarification Needed", "Route:", etc.).
-5. CLARIFICATION & ERRORS: If the user's request is ambiguous, a tool is missing parameters (like a market name or UUID), or if a tool returns an error message, DO NOT hallucinate inputs. Stop and provide a seamless, conversational, and human-friendly response explaining the issue and asking for clarification. To provide clickable options to the user, include a specific JSON block at the very end of your response exactly like this:
+1. CONVERSATIONAL ELEGANCE (NO RAW TOOLS): NEVER output raw technical tool names (e.g., `get_market_averages`, `geocode_address`). NEVER dump long, robotic lists of your capabilities. If asked what you can do, reply conversationally and naturally (e.g., "I can track live rate spikes, calculate trailing averages, and analyze pricing volatility.").
+2. NO RAW SQL: Never attempt to write or generate SQL queries. Rely strictly on the registered tool RPCs provided.
+3. ZERO GUESSING: If data or methodology is missing, state plainly: "I don't have that information in the current real estate scope."
+4. FORMAT: Always format your final output in valid Markdown. Use tables, bold headers, and bulleted lists. NEVER include technical debugging headers or metadata in your response.
+5. CLARIFICATION & ERRORS: If a tool is missing parameters or returns an error, DO NOT hallucinate inputs. Provide a human-friendly response asking for clarification. To provide clickable options, include this exact JSON block at the very end of your response:
 ```json
 {"clarification_options": ["Option A", "Option B"]}
-```
-6. ADVISORY & STRATEGY RESPONSES: When a user asks for pricing recommendations, competitive strategy, or "what should I do?" guidance, you MUST use a strict two-part structure:
-
-   **What the data shows:** (grounded section)
-   Present only facts derived directly from tool outputs. Use precise numbers. Format as a table or bullet list.
+ADVISORY & STRATEGY RESPONSES: When a user asks for pricing recommendations, use a strict two-part structure:
+What the data shows: Present only facts derived directly from tool outputs.
+Suggested approach (data-informed): Offer strategic interpretation based on the data.
+Every advisory response MUST close with this disclaimer on its own line:
 
-   **Suggested approach (data-informed):** (reasoned section)
-   Offer strategic interpretation based on the data patterns above. Be specific but clearly frame this as inference from data, not a certainty.
+⚠️ This is a data-informed observation, not professional pricing or financial advice.
 
-   Every advisory response MUST close with this disclaimer on its own line:
-   > ⚠️ *This is a data-informed observation, not professional pricing or financial advice. Consult a revenue management specialist for investment decisions.*
+EXPORTS & DOWNLOADS: When a user requests an export or download, invoke `generate_data_export`. In your final response, provide the download URL as a clean markdown link (e.g. `[Download CSV Report](<download_url>)`). Do NOT dump the full raw CSV/Markdown text into the chat message.
 
-   NEVER present a strategic recommendation with the same flat, factual confidence as a queried data point. The boundary between retrieved fact and model reasoning must always be explicit and visible to the user.
+COMMERCIAL HANDOFFS: If the user wants to deploy this system for their own business, asks how to get started, or wants to track their own portfolio, gracefully explain that this page is a live sandbox demonstration. Then, use the generate_contact_buttons tool to generate contact links. You MUST include the exact markdown strings returned by the tool at the end of your response to render the action buttons correctly.
 """
 
+
 # ─── PAYLOAD COMPRESSOR ────────────────────────────────────────────────────────
 # MAX rows the LLM receives from any single tool call. Beyond this, data is
 # sliced and the LLM is told to recommend narrowing filters.
@@ -91,13 +101,13 @@ _MAX_ROWS = 50
 def compress_tool_output(func_name: str, db_result: dict) -> str:
     """
     Converts raw tool RPC responses into a token-efficient string for LLM context.
-    
+
     Three-step compression pipeline:
     1. Metadata hoisting — keys with identical values across all rows extracted
        to a single header line, removing them from every row.
     2. Null stripping — any key with a null/None value in a row is omitted.
     3. CSV rendering — remaining data written as CSV (headers once, values compact).
-    
+
     For non-tabular (scalar/dict) results, returns a minimal string representation.
     Estimated reduction: 70–90% vs raw JSON for time-series data.
     """
@@ -105,10 +115,13 @@ def compress_tool_output(func_name: str, db_result: dict) -> str:
         msg = db_result.get("message", "unknown error")
         return f"Tool '{func_name}' error: {msg}"
 
-    data = db_result.get("data")
+    if "data" in db_result:
+        data = db_result.get("data")
+    else:
+        data = {k: v for k, v in db_result.items() if k != "status"}
 
     # ── Scalar / single-object results ──────────────────────────────────────
-    if data is None:
+    if data is None or (isinstance(data, dict) and len(data) == 0):
         return f"Tool '{func_name}': no data returned."
 
     if isinstance(data, (str, int, float, bool)):
@@ -124,7 +137,11 @@ def compress_tool_output(func_name: str, db_result: dict) -> str:
 
     # ── List of rows ─────────────────────────────────────────────────────────
     # Filter out rows where everything is None (pure null rows add no signal)
-    data = [row for row in data if isinstance(row, dict) and any(v is not None for v in row.values())]
+    data = [
+        row
+        for row in data
+        if isinstance(row, dict) and any(v is not None for v in row.values())
+    ]
 
     if not data:
         return f"Tool '{func_name}': all returned rows were empty."
@@ -163,13 +180,15 @@ def compress_tool_output(func_name: str, db_result: dict) -> str:
 
     truncation_notice = (
         f"\n[Truncated to {_MAX_ROWS} rows. Advise user to narrow date range or add filters.]"
-        if truncated else ""
+        if truncated
+        else ""
     )
     return f"{header_str}{buf.getvalue().strip()}{truncation_notice}"
 
 
 # ─── GEOCODE HANDLER (Python-side, Mapbox API) ────────────────────────────────
 
+
 def geocode_address_handler(address: str) -> dict:
     """
     Resolves a free-text address to lat/lng via the Mapbox Geocoding API.
@@ -179,7 +198,7 @@ def geocode_address_handler(address: str) -> dict:
     if not MAPBOX_ACCESS_TOKEN:
         return {
             "status": "error",
-            "message": "We are unable to geocode addresses at this time — the mapping service is not configured."
+            "message": "We are unable to geocode addresses at this time — the mapping service is not configured.",
         }
     if not address or not address.strip():
         return {"status": "error", "message": "No address was provided to geocode."}
@@ -189,7 +208,7 @@ def geocode_address_handler(address: str) -> dict:
         "q": address.strip(),
         "access_token": MAPBOX_ACCESS_TOKEN,
         "country": "US",
-        "limit": 1
+        "limit": 1,
     }
 
     try:
@@ -201,7 +220,7 @@ def geocode_address_handler(address: str) -> dict:
         if not features:
             return {
                 "status": "error",
-                "message": f"We are unable to locate coordinates for '{address}' at this time. Please try a more specific address or city name."
+                "message": f"We are unable to locate coordinates for '{address}' at this time. Please try a more specific address or city name.",
             }
 
         feature = features[0]
@@ -211,51 +230,58 @@ def geocode_address_handler(address: str) -> dict:
             "status": "success",
             "latitude": round(lat, 6),
             "longitude": round(lon, 6),
-            "resolved_address": resolved
+            "resolved_address": resolved,
         }
 
     except requests.exceptions.Timeout:
         logger.error(f"Mapbox geocode timeout for address: {address}")
         return {
             "status": "error",
-            "message": "We are unable to geocode this address at this time — the mapping service timed out. Please try again shortly."
+            "message": "We are unable to geocode this address at this time — the mapping service timed out. Please try again shortly.",
         }
     except requests.exceptions.HTTPError as e:
-        logger.error(f"Mapbox geocode HTTP error {e.response.status_code} for: {address}")
+        logger.error(
+            f"Mapbox geocode HTTP error {e.response.status_code} for: {address}"
+        )
         return {
             "status": "error",
-            "message": "We are unable to geocode this address at this time due to a service error. Please try again later."
+            "message": "We are unable to geocode this address at this time due to a service error. Please try again later.",
         }
     except requests.exceptions.RequestException as e:
         logger.error(f"Mapbox geocode request failed for '{address}': {e}")
         return {
             "status": "error",
-            "message": "We are unable to reach the mapping service at this time. Please try again later."
+            "message": "We are unable to reach the mapping service at this time. Please try again later.",
         }
     except (KeyError, IndexError, ValueError) as e:
         logger.error(f"Mapbox geocode parsing error for '{address}': {e}")
         return {
             "status": "error",
-            "message": f"We are unable to parse the location for '{address}'. Please try a more specific address."
+            "message": f"We are unable to parse the location for '{address}'. Please try a more specific address.",
         }
 
 
 # ─── MAIN CHAT HANDLER ────────────────────────────────────────────────────────
 
+
 @observe(name="process-chat")
-async def process_chat_message(user_query: str, session_id: str, session_context: dict) -> dict:
+async def process_chat_message(
+    user_query: str, session_id: str, session_context: dict
+) -> dict:
     global section_title_embeddings, section_titles
     start_time = time.time()
-    
+
     with propagate_attributes(session_id=session_id, tags=["real-estate-chat"]):
         get_client().update_current_span(input=user_query)
-        
+
         if session_id not in session_history:
             session_history[session_id] = []
 
     # STEP 1: Pre-Router Local Vector Search
     pre_check_hint = ""
-    if section_title_embeddings is None and os.path.exists("section_title_embeddings.npy"):
+    if section_title_embeddings is None and os.path.exists(
+        "section_title_embeddings.npy"
+    ):
         try:
             section_title_embeddings = np.load("section_title_embeddings.npy")
             with open("section_titles.json", "r", encoding="utf-8") as f:
@@ -268,38 +294,54 @@ async def process_chat_message(user_query: str, session_id: str, session_context
         sims = section_title_embeddings @ query_emb
         top_idx = np.argsort(sims)[::-1][:3]
         matched_titles = [section_titles[i] for i in top_idx if sims[i] >= 0.45]
-        
+
         if matched_titles:
             pre_check_hint = f"\n\nLocal Methodology Pre-Check: High similarity match with section titles: {matched_titles}. Consider classifying as PATH_B or BOTH."
-            get_client().update_current_span(metadata={"matched_section_titles": matched_titles, "similarity_scores": [float(sims[i]) for i in top_idx if sims[i] >= 0.45]})
+            get_client().update_current_span(
+                metadata={
+                    "matched_section_titles": matched_titles,
+                    "similarity_scores": [
+                        float(sims[i]) for i in top_idx if sims[i] >= 0.45
+                    ],
+                }
+            )
 
     router_sys_prompt = ROUTER_PROMPT + pre_check_hint
     router_messages = [{"role": "system", "content": router_sys_prompt}]
-    
+
     # Router only needs last 4 history messages — cheap model, keep it lean
     router_messages.extend(session_history[session_id][-4:])
     router_messages.append({"role": "user", "content": user_query})
 
     router_res = groq_client.chat.completions.create(
-        model="llama-3.1-8b-instant",
+        model=GROQ_ROUTE_MODEL,
         messages=router_messages,
         temperature=0.0,
-        response_format={"type": "json_object"}
+        response_format={"type": "json_object"},
     )
-    
+
     routing = json.loads(router_res.choices[0].message.content)
-    
+
     if isinstance(routing, list) and len(routing) > 0:
         routing = routing[0]
     elif not isinstance(routing, dict):
         routing = {}
-        
+
     classification = routing.get("classification", "PATH_A")
     reason = routing.get("reason")
-    if classification not in ["OUT_OF_SCOPE", "PATH_A", "PATH_B", "BOTH", "GREETING"]:
+    if classification not in [
+        "OUT_OF_SCOPE",
+        "PATH_A",
+        "PATH_B",
+        "BOTH",
+        "GREETING",
+        "COMMERCIAL_HANDOFF",
+    ]:
         classification = "PATH_A"
 
-    get_client().update_current_span(metadata={"classification": classification, "reason": reason})
+    get_client().update_current_span(
+        metadata={"classification": classification, "reason": reason}
+    )
 
     # Guardrail: Immediate short-circuit if Out of Scope
     if classification == "OUT_OF_SCOPE":
@@ -309,7 +351,7 @@ async def process_chat_message(user_query: str, session_id: str, session_context
             "reply": reply_out,
             "path_used": "OUT_OF_SCOPE",
             "tools_called": [],
-            "suggested_actions": []
+            "suggested_actions": [],
         }
 
     if classification == "GREETING":
@@ -319,41 +361,51 @@ async def process_chat_message(user_query: str, session_id: str, session_context
             "reply": reply_greeting,
             "path_used": "GREETING",
             "tools_called": [],
-            "suggested_actions": []
+            "suggested_actions": [],
         }
 
     tool_results = []
     rag_chunks = []
 
-    # STEP 2: Execute Vector Search if Path B or Both
-    if classification in ["PATH_B", "BOTH"]:
+    # STEP 2: Execute Vector Search if Path B, Both, or Commercial Handoff
+    if classification in ["PATH_B", "BOTH", "COMMERCIAL_HANDOFF"]:
         rag_chunks = await search_methodology_rag(user_query)
 
-    messages = [
-        {"role": "system", "content": SYNTHESIS_PROMPT}
-    ]
+    messages = [{"role": "system", "content": SYNTHESIS_PROMPT}]
 
     # Cap history at 6 messages to avoid token inflation in multi-turn sessions
     messages.extend(session_history[session_id][-6:])
 
-    user_msg_content = f"User Context Filters: {json.dumps(session_context)}\nUser Query: {user_query}"
+    user_msg_content = (
+        f"User Context Filters: {json.dumps(session_context)}\nUser Query: {user_query}"
+    )
     messages.append({"role": "user", "content": user_msg_content})
     session_history[session_id].append({"role": "user", "content": user_msg_content})
 
     if rag_chunks:
-        messages.append({
-            "role": "system", 
-            "content": "Retrieved Methodology Context:\n" + "\n---\n".join(rag_chunks)
-        })
+        messages.append(
+            {
+                "role": "system",
+                "content": "Retrieved Methodology Context:\n"
+                + "\n---\n".join(rag_chunks),
+            }
+        )
+
+    # Select active tools based on classification
+    active_tools = None
+    if classification in ["PATH_A", "BOTH"]:
+        active_tools = REAL_ESTATE_TOOLS
+    elif classification == "COMMERCIAL_HANDOFF":
+        active_tools = COMMERCIAL_TOOLS
 
     # STEP 3: Initial Brain Completion (llama-3.3-70b-versatile)
     brain_res = groq_client.chat.completions.create(
-        model="llama-3.3-70b-versatile",
+        model=GROQ_SYNTHESIS_MODEL,
         messages=messages,
-        tools=REAL_ESTATE_TOOLS if classification in ["PATH_A", "BOTH"] else None,
-        tool_choice="auto" if classification in ["PATH_A", "BOTH"] else "none",
+        tools=active_tools,
+        tool_choice="auto" if active_tools else "none",
         temperature=0.2,
-        max_tokens=600
+        max_tokens=600,
     )
 
     response_message = brain_res.choices[0].message
@@ -364,38 +416,56 @@ async def process_chat_message(user_query: str, session_id: str, session_context
         for tool_call in response_message.tool_calls:
             func_name = tool_call.function.name
             func_args = json.loads(tool_call.function.arguments)
-            
+
             # ── Python-side tool handlers (not routed to Supabase) ──────────
             if func_name == "generate_data_export":
                 from services.appwrite_service import upload_document_to_appwrite
-                url = await upload_document_to_appwrite(func_args.get("content", ""), func_args.get("format", "md"))
-                db_result = {"status": "success", "url": url}
+
+                db_result = await upload_document_to_appwrite(
+                    func_args.get("content", ""), func_args.get("format", "md")
+                )
 
             elif func_name == "geocode_address":
                 # Mapbox API call handled in Python — never hits Supabase
                 db_result = geocode_address_handler(func_args.get("address", ""))
 
+            elif func_name == "generate_contact_buttons":
+                import urllib.parse
+
+                raw_message = func_args.get(
+                    "message", "Hi, I'd like to discuss a custom build."
+                )
+                encoded_message = urllib.parse.quote(raw_message)
+
+                db_result = {
+                    "status": "success",
+                    "email_button_markdown": f'[Get in touch via Email](<mailto:{CONTACT_EMAIL} "button">)',
+                    "whatsapp_button_markdown": f'[Chat on WhatsApp](<https://wa.me/{CONTACT_WHATSAPP}?text={encoded_message} "button">)',
+                }
+
             else:
                 db_result = await execute_tool_rpc(func_name, func_args)
-                
+
             tool_results.append({"tool": func_name, "args": func_args})
 
             # ── Payload compression before entering LLM context ─────────────
             compressed_content = compress_tool_output(func_name, db_result)
 
-            messages.append({
-                "tool_call_id": tool_call.id,
-                "role": "tool",
-                "name": func_name,
-                "content": compressed_content
-            })
+            messages.append(
+                {
+                    "tool_call_id": tool_call.id,
+                    "role": "tool",
+                    "name": func_name,
+                    "content": compressed_content,
+                }
+            )
 
         # Second Brain Call to Synthesize Final Output
         final_res = groq_client.chat.completions.create(
-            model="llama-3.3-70b-versatile",
+            model=GROQ_SYNTHESIS_MODEL,
             messages=messages,
             temperature=0.2,
-            max_tokens=600
+            max_tokens=600,
         )
         final_reply = final_res.choices[0].message.content
     else:
@@ -408,10 +478,14 @@ async def process_chat_message(user_query: str, session_id: str, session_context
 
     # Parse clarification options
     suggested_actions = []
-    json_match = re.search(r'```json\s*(\{.*"clarification_options".*\})\s*```', final_reply, re.DOTALL)
+    json_match = re.search(
+        r'```json\s*(\{.*"clarification_options".*\})\s*```', final_reply, re.DOTALL
+    )
     if not json_match:
-        json_match = re.search(r'(\{.*"clarification_options".*\})', final_reply, re.DOTALL)
-        
+        json_match = re.search(
+            r'(\{.*"clarification_options".*\})', final_reply, re.DOTALL
+        )
+
     if json_match:
         try:
             clarification_data = json.loads(json_match.group(1))
@@ -426,5 +500,5 @@ async def process_chat_message(user_query: str, session_id: str, session_context
         "reply": final_reply,
         "path_used": classification,
         "tools_called": tool_results,
-        "suggested_actions": suggested_actions
+        "suggested_actions": suggested_actions,
     }

services/tools.py

@@ -415,3 +415,23 @@ REAL_ESTATE_TOOLS = [
         },
     },
 ]
+
+COMMERCIAL_TOOLS = [
+    {
+        "type": "function",
+        "function": {
+            "name": "generate_contact_buttons",
+            "description": "Generates clickable Email and WhatsApp contact buttons. Use this whenever the user asks about hiring us, pricing, custom builds, or tracking their own portfolios. The tool returns the exact markdown syntax you must use to display the buttons.",
+            "parameters": {
+                "type": "object",
+                "properties": {
+                    "message": {
+                        "type": "string",
+                        "description": "A personalized, plain English greeting message to pre-fill in the WhatsApp chat based on the user's inquiry (e.g., 'Hi John, I would like to discuss a custom build for my 10 properties in Miami.')."
+                    }
+                },
+                "required": ["message"],
+            },
+        },
+    }
+]

test_api.py

@@ -1,59 +0,0 @@
-from fastapi.testclient import TestClient
-from main import app
-import json
-
-client = TestClient(app)
-
-print("--- Testing /health ---")
-try:
-    resp = client.get("/health")
-    print(f"Status: {resp.status_code}")
-    print(f"Response: {resp.json()}")
-except Exception as e:
-    print(f"Failed: {e}")
-
-print("\n--- Testing /api/v1/real-estate/chat/starters ---")
-try:
-    resp = client.get("/api/v1/real-estate/chat/starters")
-    print(f"Status: {resp.status_code}")
-    print(f"Response: {resp.json()}")
-except Exception as e:
-    print(f"Failed: {e}")
-
-messages = [
-    "Hello there!",
-    "What does the 7-day average mean?",
-    "Can you export the market averages for Miami to a CSV file?"
-]
-
-print("\n--- Testing /api/v1/real-estate/chat ---")
-
-# First, test isolated queries
-for i, msg in enumerate(messages):
-    print(f"\nTest {i+1}: '{msg}'")
-    try:
-        payload = {"message": msg, "session_id": f"isolated_session_{i}"}
-        resp = client.post("/api/v1/real-estate/chat", json=payload)
-        print(f"Status: {resp.status_code}")
-        print(f"Response: {json.dumps(resp.json(), indent=2)}")
-    except Exception as e:
-        print(f"Failed: {e}")
-
-# Next, test multi-turn conversation
-print("\n--- Testing Multi-Turn Conversation & Memory ---")
-multi_turn_msgs = [
-    "What's the market average for Miami?",
-    "Can you export that data into a CSV file for me?",
-    "Are there any other markets you track? I'm not sure which one I want."
-]
-session_id = "multi_turn_test_session_1"
-
-for i, msg in enumerate(multi_turn_msgs):
-    print(f"\nTurn {i+1}: '{msg}'")
-    try:
-        payload = {"message": msg, "session_id": session_id}
-        resp = client.post("/api/v1/real-estate/chat", json=payload)
-        print(f"Status: {resp.status_code}")
-        print(f"Response: {json.dumps(resp.json(), indent=2)}")
-    except Exception as e:
-        print(f"Failed: {e}")