Latest changes
Browse files- .gitignore +2 -1
- Frontend_API_Updates.md +8 -0
- services/groq_service.py +16 -7
- services/supabase_service.py +19 -0
- services/tools.py +64 -0
.gitignore
CHANGED
|
@@ -64,4 +64,5 @@ docs_research
|
|
| 64 |
tools
|
| 65 |
Real Estate Intelligence Layer.md
|
| 66 |
grant_privileges.sql
|
| 67 |
-
agent_prompt.md
|
|
|
|
|
|
| 64 |
tools
|
| 65 |
Real Estate Intelligence Layer.md
|
| 66 |
grant_privileges.sql
|
| 67 |
+
agent_prompt.md
|
| 68 |
+
dynamic_tool_calling_features.txt
|
Frontend_API_Updates.md
CHANGED
|
@@ -36,3 +36,11 @@ The LLM is now strictly instructed to output its replies using **Markdown** form
|
|
| 36 |
- The frontend chat UI must be capable of rendering standard Markdown into HTML.
|
| 37 |
- When the user asks to "download this data" or "export a CSV", the backend will generate the file, upload it to Appwrite, and return a Markdown link in the `reply` text (e.g., `[Download your CSV Report here](https://fra.cloud.appwrite.io/v1/storage/...)`).
|
| 38 |
- The frontend's markdown parser should seamlessly render this as a standard clickable anchor tag (`<a>`) so the user can download the file.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 36 |
- The frontend chat UI must be capable of rendering standard Markdown into HTML.
|
| 37 |
- When the user asks to "download this data" or "export a CSV", the backend will generate the file, upload it to Appwrite, and return a Markdown link in the `reply` text (e.g., `[Download your CSV Report here](https://fra.cloud.appwrite.io/v1/storage/...)`).
|
| 38 |
- The frontend's markdown parser should seamlessly render this as a standard clickable anchor tag (`<a>`) so the user can download the file.
|
| 39 |
+
|
| 40 |
+
## 4. Expanded Tool Registry & New Route
|
| 41 |
+
|
| 42 |
+
The backend has been upgraded with a new fallback route and additional Postgres RPC tools.
|
| 43 |
+
|
| 44 |
+
**Frontend Impact:**
|
| 45 |
+
- **PATH_C Fallback:** A new routing classification (`PATH_C`) is returned in `path_used` when the user asks a general real estate context question. The assistant will dynamically inject a disclaimer into the response text stating: *"Note: This is general market context, not live data from the Joule Dynamics tracking system."* No UI changes are strictly necessary, but be aware of the new `PATH_C` value in the response.
|
| 46 |
+
- **Robust Error Handling:** The assistant is explicitly instructed to never guess missing parameters or write ad-hoc queries. Missing parameters or invalid formats (such as UUID validation errors) will cleanly trigger the `suggested_actions` clarification flow to ask the user for correct details. Ensure the clarification buttons are rendered robustly.
|
services/groq_service.py
CHANGED
|
@@ -10,27 +10,28 @@ session_history = {}
|
|
| 10 |
groq_client = Groq(api_key=GROQ_API_KEY)
|
| 11 |
|
| 12 |
ROUTER_PROMPT = """You are the classification router for the Joule Dynamics Real Estate Intelligence Layer.
|
| 13 |
-
Analyze the user query and classify it into EXACTLY ONE of
|
| 14 |
|
| 15 |
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.
|
| 16 |
2. "PATH_A": Query asks a live-data question (prices, spikes, availability, market averages, KPIs, specific listing rates).
|
| 17 |
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).
|
| 18 |
-
4. "
|
| 19 |
-
5. "
|
|
|
|
| 20 |
|
| 21 |
Respond ONLY with valid JSON matching this schema:
|
| 22 |
-
{"classification": "OUT_OF_SCOPE" | "PATH_A" | "PATH_B" | "BOTH" | "GREETING", "reason": "1-sentence justification"}
|
| 23 |
"""
|
| 24 |
|
| 25 |
SYNTHESIS_PROMPT = """You are the B2B Real Estate Intelligence Assistant for Joule Dynamics.
|
| 26 |
You provide precise data analysis to real estate investors and property managers reviewing short-term rental market performance.
|
| 27 |
|
| 28 |
OPERATIONAL RULES:
|
| 29 |
-
1. NEVER FABRICATE DATA: Rely strictly on returned tool outputs or retrieved methodology chunks.
|
| 30 |
2. ZERO GUESSING: If data or methodology is missing, state plainly: "I don't have that information in the current real estate scope."
|
| 31 |
3. SCOPE BOUNDARY: If asked about Leads or Price Monitors, state that you are currently scoped exclusively to the Real Estate Rate Monitor.
|
| 32 |
-
4. FORMAT: Always format your final output in valid Markdown.
|
| 33 |
-
5. CLARIFICATION: If the user's request is ambiguous or if a tool
|
| 34 |
```json
|
| 35 |
{"clarification_options": ["Option A", "Option B"]}
|
| 36 |
```
|
|
@@ -62,6 +63,8 @@ async def process_chat_message(user_query: str, session_id: str, session_context
|
|
| 62 |
routing = {}
|
| 63 |
|
| 64 |
classification = routing.get("classification", "PATH_A")
|
|
|
|
|
|
|
| 65 |
|
| 66 |
# Guardrail: Immediate short-circuit if Out of Scope
|
| 67 |
if classification == "OUT_OF_SCOPE":
|
|
@@ -94,6 +97,12 @@ async def process_chat_message(user_query: str, session_id: str, session_context
|
|
| 94 |
messages = [
|
| 95 |
{"role": "system", "content": SYNTHESIS_PROMPT}
|
| 96 |
]
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 97 |
messages.extend(session_history[session_id])
|
| 98 |
|
| 99 |
user_msg_content = f"User Context Filters: {json.dumps(session_context)}\nUser Query: {user_query}"
|
|
|
|
| 10 |
groq_client = Groq(api_key=GROQ_API_KEY)
|
| 11 |
|
| 12 |
ROUTER_PROMPT = """You are the classification router for the Joule Dynamics Real Estate Intelligence Layer.
|
| 13 |
+
Analyze the user query and classify it into EXACTLY ONE of six classifications:
|
| 14 |
|
| 15 |
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.
|
| 16 |
2. "PATH_A": Query asks a live-data question (prices, spikes, availability, market averages, KPIs, specific listing rates).
|
| 17 |
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).
|
| 18 |
+
4. "PATH_C": Query asks a general real estate market context question that does not require live data metrics from our system.
|
| 19 |
+
5. "BOTH": Query requires BOTH explaining a methodology concept AND fetching live data metrics.
|
| 20 |
+
6. "GREETING": User is saying hello, thanking the assistant, or making casual conversation without asking a specific question.
|
| 21 |
|
| 22 |
Respond ONLY with valid JSON matching this schema:
|
| 23 |
+
{"classification": "OUT_OF_SCOPE" | "PATH_A" | "PATH_B" | "PATH_C" | "BOTH" | "GREETING", "reason": "1-sentence justification"}
|
| 24 |
"""
|
| 25 |
|
| 26 |
SYNTHESIS_PROMPT = """You are the B2B Real Estate Intelligence Assistant for Joule Dynamics.
|
| 27 |
You provide precise data analysis to real estate investors and property managers reviewing short-term rental market performance.
|
| 28 |
|
| 29 |
OPERATIONAL RULES:
|
| 30 |
+
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.
|
| 31 |
2. ZERO GUESSING: If data or methodology is missing, state plainly: "I don't have that information in the current real estate scope."
|
| 32 |
3. SCOPE BOUNDARY: If asked about Leads or Price Monitors, state that you are currently scoped exclusively to the Real Estate Rate Monitor.
|
| 33 |
+
4. FORMAT: Always format your final output in valid Markdown. Ensure you use tables, bold headers, and bulleted lists to make data highly readable.
|
| 34 |
+
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 human-friendly response 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:
|
| 35 |
```json
|
| 36 |
{"clarification_options": ["Option A", "Option B"]}
|
| 37 |
```
|
|
|
|
| 63 |
routing = {}
|
| 64 |
|
| 65 |
classification = routing.get("classification", "PATH_A")
|
| 66 |
+
if classification not in ["OUT_OF_SCOPE", "PATH_A", "PATH_B", "PATH_C", "BOTH", "GREETING"]:
|
| 67 |
+
classification = "PATH_A"
|
| 68 |
|
| 69 |
# Guardrail: Immediate short-circuit if Out of Scope
|
| 70 |
if classification == "OUT_OF_SCOPE":
|
|
|
|
| 97 |
messages = [
|
| 98 |
{"role": "system", "content": SYNTHESIS_PROMPT}
|
| 99 |
]
|
| 100 |
+
if classification == "PATH_C":
|
| 101 |
+
messages.append({
|
| 102 |
+
"role": "system",
|
| 103 |
+
"content": "Note: Because this is a PATH_C query, you must prepend a strict disclaimer stating: 'Note: This is general market context, not live data from the Joule Dynamics tracking system.'"
|
| 104 |
+
})
|
| 105 |
+
|
| 106 |
messages.extend(session_history[session_id])
|
| 107 |
|
| 108 |
user_msg_content = f"User Context Filters: {json.dumps(session_context)}\nUser Query: {user_query}"
|
services/supabase_service.py
CHANGED
|
@@ -1,4 +1,5 @@
|
|
| 1 |
import os
|
|
|
|
| 2 |
from supabase import create_client, Client
|
| 3 |
from services.embedding_service import get_embedding_model
|
| 4 |
from config import SUPABASE_URL, SUPABASE_KEY
|
|
@@ -6,8 +7,26 @@ from config import SUPABASE_URL, SUPABASE_KEY
|
|
| 6 |
supabase: Client = create_client(SUPABASE_URL, SUPABASE_KEY)
|
| 7 |
embedder = get_embedding_model()
|
| 8 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 9 |
async def execute_tool_rpc(func_name: str, args: dict) -> dict:
|
| 10 |
"""Executes a read-only Supabase RPC matching the tool schema."""
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 11 |
try:
|
| 12 |
res = supabase.rpc(func_name, args).execute()
|
| 13 |
return {"status": "success", "data": res.data}
|
|
|
|
| 1 |
import os
|
| 2 |
+
import re
|
| 3 |
from supabase import create_client, Client
|
| 4 |
from services.embedding_service import get_embedding_model
|
| 5 |
from config import SUPABASE_URL, SUPABASE_KEY
|
|
|
|
| 7 |
supabase: Client = create_client(SUPABASE_URL, SUPABASE_KEY)
|
| 8 |
embedder = get_embedding_model()
|
| 9 |
|
| 10 |
+
def is_valid_uuid(val):
|
| 11 |
+
if not isinstance(val, str):
|
| 12 |
+
return False
|
| 13 |
+
return bool(re.match(r'^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$', val.lower()))
|
| 14 |
+
|
| 15 |
async def execute_tool_rpc(func_name: str, args: dict) -> dict:
|
| 16 |
"""Executes a read-only Supabase RPC matching the tool schema."""
|
| 17 |
+
# Application layer clamping and validation
|
| 18 |
+
if func_name == "search_properties":
|
| 19 |
+
if "p_limit" in args and args["p_limit"] is not None:
|
| 20 |
+
args["p_limit"] = max(1, min(int(args["p_limit"]), 200))
|
| 21 |
+
elif func_name == "get_property_rate_changes":
|
| 22 |
+
if "days_param" in args and args["days_param"] is not None:
|
| 23 |
+
args["days_param"] = max(1, min(int(args["days_param"]), 90))
|
| 24 |
+
if "compare_window_days" in args and args["compare_window_days"] is not None:
|
| 25 |
+
args["compare_window_days"] = max(1, min(int(args["compare_window_days"]), 14))
|
| 26 |
+
elif func_name == "get_distance_km":
|
| 27 |
+
if not is_valid_uuid(args.get("property_a_id")) or not is_valid_uuid(args.get("property_b_id")):
|
| 28 |
+
return {"status": "error", "message": "Invalid UUID format. Both property IDs must be valid UUIDs."}
|
| 29 |
+
|
| 30 |
try:
|
| 31 |
res = supabase.rpc(func_name, args).execute()
|
| 32 |
return {"status": "success", "data": res.data}
|
services/tools.py
CHANGED
|
@@ -82,5 +82,69 @@ REAL_ESTATE_TOOLS = [
|
|
| 82 |
"required": ["format", "content"]
|
| 83 |
}
|
| 84 |
}
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 85 |
}
|
| 86 |
]
|
|
|
|
| 82 |
"required": ["format", "content"]
|
| 83 |
}
|
| 84 |
}
|
| 85 |
+
},
|
| 86 |
+
{
|
| 87 |
+
"type": "function",
|
| 88 |
+
"function": {
|
| 89 |
+
"name": "get_tracked_markets",
|
| 90 |
+
"description": "Fetch active markets being tracked, optionally filtered by platform.",
|
| 91 |
+
"parameters": {
|
| 92 |
+
"type": "object",
|
| 93 |
+
"properties": {
|
| 94 |
+
"p_platform": {"type": "string", "description": "Optional platform filter (e.g. 'Airbnb' or 'Vrbo')"}
|
| 95 |
+
},
|
| 96 |
+
"required": []
|
| 97 |
+
}
|
| 98 |
+
}
|
| 99 |
+
},
|
| 100 |
+
{
|
| 101 |
+
"type": "function",
|
| 102 |
+
"function": {
|
| 103 |
+
"name": "search_properties",
|
| 104 |
+
"description": "Search and filter properties by text, market, platform, bedrooms, or availability.",
|
| 105 |
+
"parameters": {
|
| 106 |
+
"type": "object",
|
| 107 |
+
"properties": {
|
| 108 |
+
"p_search": {"type": "string", "description": "Search text (name or uuid)"},
|
| 109 |
+
"p_market": {"type": "string", "description": "Market region name"},
|
| 110 |
+
"p_platform": {"type": "string", "description": "Platform (e.g. 'Airbnb')"},
|
| 111 |
+
"p_bedrooms": {"type": "integer", "description": "Number of bedrooms"},
|
| 112 |
+
"p_available": {"type": "boolean", "description": "Availability status"},
|
| 113 |
+
"p_limit": {"type": "integer", "default": 50, "description": "Number of results to return (max 200)"}
|
| 114 |
+
},
|
| 115 |
+
"required": []
|
| 116 |
+
}
|
| 117 |
+
}
|
| 118 |
+
},
|
| 119 |
+
{
|
| 120 |
+
"type": "function",
|
| 121 |
+
"function": {
|
| 122 |
+
"name": "get_property_rate_changes",
|
| 123 |
+
"description": "Show historical rate changes and trailing averages for a specific property over time.",
|
| 124 |
+
"parameters": {
|
| 125 |
+
"type": "object",
|
| 126 |
+
"properties": {
|
| 127 |
+
"property_search": {"type": "string", "description": "Property name or UUID (required)"},
|
| 128 |
+
"days_param": {"type": "integer", "default": 14, "description": "Lookback window in days (max 90)"},
|
| 129 |
+
"compare_window_days": {"type": "integer", "default": 1, "description": "Days to compare against for pct_change_vs_prev (max 14)"}
|
| 130 |
+
},
|
| 131 |
+
"required": ["property_search"]
|
| 132 |
+
}
|
| 133 |
+
}
|
| 134 |
+
},
|
| 135 |
+
{
|
| 136 |
+
"type": "function",
|
| 137 |
+
"function": {
|
| 138 |
+
"name": "get_distance_km",
|
| 139 |
+
"description": "Calculate the geographic distance in kilometers between two properties.",
|
| 140 |
+
"parameters": {
|
| 141 |
+
"type": "object",
|
| 142 |
+
"properties": {
|
| 143 |
+
"property_a_id": {"type": "string", "description": "UUID of the first property"},
|
| 144 |
+
"property_b_id": {"type": "string", "description": "UUID of the second property"}
|
| 145 |
+
},
|
| 146 |
+
"required": ["property_a_id", "property_b_id"]
|
| 147 |
+
}
|
| 148 |
+
}
|
| 149 |
}
|
| 150 |
]
|