Spaces:
Sleeping
Sleeping
REFINE: add usage logging for response in query classification and RAG answer generation; enhance inventory prompt for structured field extraction
Browse files- rag/generator.py +3 -1
- rag/prompts/prompts.py +24 -8
- rag/query_router.py +1 -0
- services/product_search_service.py +203 -132
rag/generator.py
CHANGED
|
@@ -27,6 +27,8 @@ def generate_rag_answer(query: str, chunks: list[dict], brand_name: str) -> str:
|
|
| 27 |
max_tokens=256,
|
| 28 |
)
|
| 29 |
|
|
|
|
|
|
|
| 30 |
return response.choices[0].message.content.strip()
|
| 31 |
|
| 32 |
|
|
@@ -49,7 +51,7 @@ def generate_reply_from_contexts(query: str, rag_context: str, inventory_context
|
|
| 49 |
temperature=0.1,
|
| 50 |
max_tokens=300,
|
| 51 |
)
|
| 52 |
-
|
| 53 |
return response.choices[0].message.content.strip()
|
| 54 |
|
| 55 |
|
|
|
|
| 27 |
max_tokens=256,
|
| 28 |
)
|
| 29 |
|
| 30 |
+
print(response.usage)
|
| 31 |
+
|
| 32 |
return response.choices[0].message.content.strip()
|
| 33 |
|
| 34 |
|
|
|
|
| 51 |
temperature=0.1,
|
| 52 |
max_tokens=300,
|
| 53 |
)
|
| 54 |
+
print(response.usage)
|
| 55 |
return response.choices[0].message.content.strip()
|
| 56 |
|
| 57 |
|
rag/prompts/prompts.py
CHANGED
|
@@ -1,6 +1,9 @@
|
|
| 1 |
INVENTORY_PROMPT = """You are a Shopify product search FIELD EXTRACTOR.
|
| 2 |
|
| 3 |
-
Your job is to extract structured search fields from a customer message.
|
|
|
|
|
|
|
|
|
|
| 4 |
DO NOT build a query string.
|
| 5 |
|
| 6 |
OUTPUT ONLY valid JSON.
|
|
@@ -22,8 +25,13 @@ RULES:
|
|
| 22 |
4. Extract only what is clearly implied.
|
| 23 |
5. If nothing exists for a field, return empty array.
|
| 24 |
6. Never guess brand, SKU, or barcode.
|
| 25 |
-
7.
|
| 26 |
-
8.
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 27 |
|
| 28 |
FIELD USAGE:
|
| 29 |
|
|
@@ -39,10 +47,20 @@ FIELD USAGE:
|
|
| 39 |
not as a structured field, so don't worry about exact Shopify field
|
| 40 |
names here.
|
| 41 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 42 |
IMPORTANT BEHAVIOR:
|
| 43 |
|
| 44 |
- Do NOT invent vendor, sku, or barcode values
|
| 45 |
-
- Do NOT overfill fields
|
| 46 |
- Keep extraction conservative but useful
|
| 47 |
"""
|
| 48 |
|
|
@@ -64,10 +82,8 @@ REPLY_PROMPT = """You are a helpful customer support assistant for {brand_name}.
|
|
| 64 |
|
| 65 |
STRICT RULES:
|
| 66 |
1. Answer using ONLY the product knowledge and inventory data provided below - no outside knowledge, no guessing.
|
| 67 |
-
2. If
|
| 68 |
-
|
| 69 |
-
- If the requested information does not exist → say:
|
| 70 |
-
"We carry [product], but I don't have that specific information. Please contact our support team for help."
|
| 71 |
|
| 72 |
3. Only say:
|
| 73 |
"I don't have that information. Please contact our support team for help."
|
|
|
|
| 1 |
INVENTORY_PROMPT = """You are a Shopify product search FIELD EXTRACTOR.
|
| 2 |
|
| 3 |
+
Your job is to extract structured search fields from a customer message. The message
|
| 4 |
+
might contain some information about the product the customer is looking for, but it
|
| 5 |
+
will be unstructured and may contain a lot of extra words. Your task is to pull out any
|
| 6 |
+
specific details you can find that would help identify the product, and return them in a structured JSON format.
|
| 7 |
DO NOT build a query string.
|
| 8 |
|
| 9 |
OUTPUT ONLY valid JSON.
|
|
|
|
| 25 |
4. Extract only what is clearly implied.
|
| 26 |
5. If nothing exists for a field, return empty array.
|
| 27 |
6. Never guess brand, SKU, or barcode.
|
| 28 |
+
7. Keep values short (single words or short phrases).
|
| 29 |
+
8. For EVERY non-empty field, generate up to 3 variations to maximise recall:
|
| 30 |
+
- title: the exact name + common abbreviations or alternate spellings
|
| 31 |
+
- product_type: the main category + broader and narrower alternatives (e.g. "sneakers", "shoes", "footwear")
|
| 32 |
+
- tag: the literal tag + synonyms or related descriptors (e.g. "running", "athletic", "sport")
|
| 33 |
+
- vendor: the brand as written + common alternate spellings or abbreviations
|
| 34 |
+
- keywords: singular and plural forms, related use-cases, synonyms (e.g. "running shoe", "running shoes", "jogging shoes")
|
| 35 |
|
| 36 |
FIELD USAGE:
|
| 37 |
|
|
|
|
| 47 |
not as a structured field, so don't worry about exact Shopify field
|
| 48 |
names here.
|
| 49 |
|
| 50 |
+
EXAMPLE:
|
| 51 |
+
Customer message: "looking for running shoes"
|
| 52 |
+
{
|
| 53 |
+
"title": [],
|
| 54 |
+
"product_type": ["sneakers", "shoes", "footwear"],
|
| 55 |
+
"tag": ["running", "athletic", "sport"],
|
| 56 |
+
"vendor": [],
|
| 57 |
+
"keywords": ["running shoe", "running shoes", "jogging shoes"]
|
| 58 |
+
}
|
| 59 |
+
|
| 60 |
IMPORTANT BEHAVIOR:
|
| 61 |
|
| 62 |
- Do NOT invent vendor, sku, or barcode values
|
| 63 |
+
- Do NOT overfill fields beyond 3 values each
|
| 64 |
- Keep extraction conservative but useful
|
| 65 |
"""
|
| 66 |
|
|
|
|
| 82 |
|
| 83 |
STRICT RULES:
|
| 84 |
1. Answer using ONLY the product knowledge and inventory data provided below - no outside knowledge, no guessing.
|
| 85 |
+
2. If the product exists but it is out of stock or unavailable, say:
|
| 86 |
+
"We carry [product], but it is currently out of stock. Please contact our support team for help."
|
|
|
|
|
|
|
| 87 |
|
| 88 |
3. Only say:
|
| 89 |
"I don't have that information. Please contact our support team for help."
|
rag/query_router.py
CHANGED
|
@@ -21,6 +21,7 @@ def classify_query_route(query: str) -> str:
|
|
| 21 |
],
|
| 22 |
temperature=0,
|
| 23 |
)
|
|
|
|
| 24 |
decision = response.choices[0].message.content.strip().upper()
|
| 25 |
result = decision if decision in ["INVENTORY", "RAG", "BOTH"] else "RAG"
|
| 26 |
|
|
|
|
| 21 |
],
|
| 22 |
temperature=0,
|
| 23 |
)
|
| 24 |
+
print(response.usage)
|
| 25 |
decision = response.choices[0].message.content.strip().upper()
|
| 26 |
result = decision if decision in ["INVENTORY", "RAG", "BOTH"] else "RAG"
|
| 27 |
|
services/product_search_service.py
CHANGED
|
@@ -19,33 +19,20 @@ SHOPIFY_FIELD_MAP = {
|
|
| 19 |
EXPECTED_EXTRACTOR_FIELDS = list(SHOPIFY_FIELD_MAP.keys()) + ["keywords"]
|
| 20 |
|
| 21 |
STRONG_FIELDS = {"title", "product_type", "sku", "barcode"}
|
| 22 |
-
|
| 23 |
WEAK_FIELDS = {"tag", "vendor"}
|
| 24 |
-
MAX_PRODUCTS_IN_CONTEXT = 20
|
| 25 |
|
|
|
|
| 26 |
PRICE_SORT_MAX_RESULTS = 500
|
| 27 |
-
|
| 28 |
DESCRIPTION_TRUNCATE_LEN = 200
|
| 29 |
HASHTAG_OR_MENTION_RE = re.compile(r"[#@]\w+")
|
| 30 |
MAX_EXTRACTION_INPUT_CHARS = 600
|
|
|
|
| 31 |
|
| 32 |
-
|
| 33 |
-
KEYWORD_EXTRACTOR_MAX_TOKENS = 120
|
| 34 |
|
| 35 |
-
|
| 36 |
-
|
| 37 |
-
|
| 38 |
-
LLM extraction call. Safe to call on any input -- it's a no-op
|
| 39 |
-
(aside from whitespace collapsing) for queries that don't have any."""
|
| 40 |
-
cleaned = HASHTAG_OR_MENTION_RE.sub("", raw_query)
|
| 41 |
-
cleaned = re.sub(r"\s+", " ", cleaned).strip()
|
| 42 |
-
if len(cleaned) > MAX_EXTRACTION_INPUT_CHARS:
|
| 43 |
-
logger.warning(
|
| 44 |
-
"Truncating extraction input from %d to %d chars",
|
| 45 |
-
len(cleaned), MAX_EXTRACTION_INPUT_CHARS,
|
| 46 |
-
)
|
| 47 |
-
cleaned = cleaned[:MAX_EXTRACTION_INPUT_CHARS]
|
| 48 |
-
return cleaned
|
| 49 |
|
| 50 |
REDIRECT_INTENTS = [
|
| 51 |
"full catalog",
|
|
@@ -70,6 +57,10 @@ EXPENSIVE_INTENTS = [
|
|
| 70 |
PRICE_INTENTS = CHEAP_INTENTS + EXPENSIVE_INTENTS
|
| 71 |
|
| 72 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 73 |
def is_redirect_query(query: str) -> bool:
|
| 74 |
query_lower = query.lower()
|
| 75 |
return any(intent in query_lower for intent in REDIRECT_INTENTS)
|
|
@@ -80,19 +71,91 @@ def is_price_sort_query(query: str) -> bool:
|
|
| 80 |
return any(intent in query_lower for intent in PRICE_INTENTS)
|
| 81 |
|
| 82 |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 83 |
def safe_json_load(text: str):
|
| 84 |
text = text.strip().replace("```json", "").replace("```", "")
|
|
|
|
|
|
|
|
|
|
|
|
|
| 85 |
return json.loads(text)
|
| 86 |
|
| 87 |
|
| 88 |
-
|
| 89 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 90 |
|
| 91 |
-
|
| 92 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 93 |
"""
|
| 94 |
try:
|
| 95 |
-
cleaned_query = _clean_query_for_extraction(user_query)
|
| 96 |
response = client.chat.completions.create(
|
| 97 |
model="llama-3.1-8b-instant",
|
| 98 |
messages=[
|
|
@@ -103,6 +166,7 @@ def extract_shopify_fields(user_query: str) -> dict:
|
|
| 103 |
response_format={"type": "json_object"},
|
| 104 |
max_tokens=FIELD_EXTRACTOR_MAX_TOKENS,
|
| 105 |
)
|
|
|
|
| 106 |
raw = response.choices[0].message.content
|
| 107 |
data = safe_json_load(raw)
|
| 108 |
if not isinstance(data, dict):
|
|
@@ -110,15 +174,15 @@ def extract_shopify_fields(user_query: str) -> dict:
|
|
| 110 |
return {}
|
| 111 |
return data
|
| 112 |
except Exception:
|
| 113 |
-
logger.exception("extract_shopify_fields failed for query=%r",
|
| 114 |
return {}
|
| 115 |
|
| 116 |
|
| 117 |
def _normalize_fields(raw: dict) -> dict:
|
| 118 |
"""Coerce whatever the LLM returned into {field: list[str]} safely.
|
| 119 |
|
| 120 |
-
Handles
|
| 121 |
-
|
| 122 |
"""
|
| 123 |
normalized = {}
|
| 124 |
for key in EXPECTED_EXTRACTOR_FIELDS:
|
|
@@ -132,9 +196,12 @@ def _normalize_fields(raw: dict) -> dict:
|
|
| 132 |
return normalized
|
| 133 |
|
| 134 |
|
|
|
|
|
|
|
|
|
|
|
|
|
| 135 |
def _quote_term(term: str) -> str:
|
| 136 |
-
"""Quote multi-word values so Shopify treats them as a phrase
|
| 137 |
-
separate implicitly-ANDed/ORed words."""
|
| 138 |
term = term.strip()
|
| 139 |
if not term:
|
| 140 |
return ""
|
|
@@ -145,7 +212,9 @@ def _quote_term(term: str) -> str:
|
|
| 145 |
|
| 146 |
|
| 147 |
def _build_field_clause(field_name: str, values: list[str]) -> str:
|
| 148 |
-
|
|
|
|
|
|
|
| 149 |
quoted = [q for q in quoted if q]
|
| 150 |
if not quoted:
|
| 151 |
return ""
|
|
@@ -155,10 +224,14 @@ def _build_field_clause(field_name: str, values: list[str]) -> str:
|
|
| 155 |
|
| 156 |
|
| 157 |
def _build_keyword_clause(values: list[str]) -> str:
|
| 158 |
-
"""Unscoped free-text terms
|
| 159 |
-
|
| 160 |
-
|
| 161 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
| 162 |
quoted = [q for q in quoted if q]
|
| 163 |
if not quoted:
|
| 164 |
return ""
|
|
@@ -166,7 +239,14 @@ def _build_keyword_clause(values: list[str]) -> str:
|
|
| 166 |
return quoted[0]
|
| 167 |
return f"({' OR '.join(quoted)})"
|
| 168 |
|
|
|
|
| 169 |
def build_shopify_query_from_fields(fields: dict) -> str:
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 170 |
fields = _normalize_fields(fields)
|
| 171 |
clauses = []
|
| 172 |
|
|
@@ -181,73 +261,21 @@ def build_shopify_query_from_fields(fields: dict) -> str:
|
|
| 181 |
|
| 182 |
return " OR ".join(clauses)
|
| 183 |
|
| 184 |
-
def build_shopify_search_query(user_query: str) -> str:
|
| 185 |
-
logger.info("Building Shopify query | query='%s'", user_query)
|
| 186 |
|
| 187 |
-
|
| 188 |
-
query
|
| 189 |
|
| 190 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
| 191 |
return query
|
| 192 |
-
def extract_search_terms(query: str) -> list[str]:
|
| 193 |
-
cleaned_query = _clean_query_for_extraction(query)
|
| 194 |
-
logger.info("Extracting fallback terms | query='%s'", cleaned_query)
|
| 195 |
-
|
| 196 |
-
try:
|
| 197 |
-
response = client.chat.completions.create(
|
| 198 |
-
model="llama-3.1-8b-instant",
|
| 199 |
-
messages=[
|
| 200 |
-
{
|
| 201 |
-
"role": "system",
|
| 202 |
-
"content": """
|
| 203 |
-
Return ONLY a JSON array of plain string keywords. No explanation, no markdown, no nested objects.
|
| 204 |
-
|
| 205 |
-
Extract at most 6 short, concrete search terms from the customer's message: product name/type, color, material, size, or other literal searchable words.
|
| 206 |
-
|
| 207 |
-
Skip hashtags, usernames, and generic marketing words ("smarter", "sharp", "look").
|
| 208 |
-
""",
|
| 209 |
-
},
|
| 210 |
-
{"role": "user", "content": cleaned_query},
|
| 211 |
-
],
|
| 212 |
-
temperature=0,
|
| 213 |
-
max_tokens=KEYWORD_EXTRACTOR_MAX_TOKENS,
|
| 214 |
-
)
|
| 215 |
-
|
| 216 |
-
raw = response.choices[0].message.content.strip()
|
| 217 |
-
data = safe_json_load(raw)
|
| 218 |
-
|
| 219 |
-
if isinstance(data, dict):
|
| 220 |
-
list_values = [v for v in data.values() if isinstance(v, list)]
|
| 221 |
-
data = list_values[0] if list_values else []
|
| 222 |
-
|
| 223 |
-
if not isinstance(data, list):
|
| 224 |
-
logger.warning("Fallback extractor returned non-list: %r", data)
|
| 225 |
-
return [cleaned_query]
|
| 226 |
-
|
| 227 |
-
flat_terms = []
|
| 228 |
-
for item in data:
|
| 229 |
-
if isinstance(item, str):
|
| 230 |
-
flat_terms.append(item)
|
| 231 |
-
continue
|
| 232 |
-
# Tolerate the old verbose shape too, in case the model
|
| 233 |
-
# ignores the simplified schema on a given run.
|
| 234 |
-
if isinstance(item, dict):
|
| 235 |
-
flat_terms.append(item.get("main_term"))
|
| 236 |
-
flat_terms.append(item.get("synonym"))
|
| 237 |
-
flat_terms.append(item.get("simplified_version"))
|
| 238 |
-
flat_terms.extend(item.get("optional_split_terms", []) or [])
|
| 239 |
|
| 240 |
-
flat_terms = [t for t in flat_terms if isinstance(t, str) and t.strip()]
|
| 241 |
|
| 242 |
-
|
| 243 |
-
|
| 244 |
-
|
| 245 |
-
logger.info("Fallback terms flattened | %s", flat_terms)
|
| 246 |
-
return flat_terms
|
| 247 |
-
|
| 248 |
-
except Exception:
|
| 249 |
-
logger.exception("Fallback term extraction failed for query=%r", cleaned_query)
|
| 250 |
-
return [cleaned_query]
|
| 251 |
|
| 252 |
def format_products_for_llm(products: list[dict], max_products: int = MAX_PRODUCTS_IN_CONTEXT) -> str:
|
| 253 |
if not products:
|
|
@@ -257,36 +285,75 @@ def format_products_for_llm(products: list[dict], max_products: int = MAX_PRODUC
|
|
| 257 |
products_to_show = products[:max_products]
|
| 258 |
|
| 259 |
lines = []
|
| 260 |
-
|
| 261 |
for product in products_to_show:
|
| 262 |
lines.append(
|
| 263 |
f"\nProduct: {product.get('title', '')} ({product.get('product_type', '')})"
|
| 264 |
)
|
| 265 |
-
|
| 266 |
if product.get("description"):
|
| 267 |
lines.append(f" Description: {product['description'][:DESCRIPTION_TRUNCATE_LEN]}")
|
| 268 |
-
|
| 269 |
if product.get("tags"):
|
| 270 |
lines.append(f" Tags: {', '.join(product['tags'])}")
|
| 271 |
-
|
| 272 |
for variant in product.get("variants", []):
|
| 273 |
status = "In Stock" if variant.get("available") else "Out of Stock"
|
| 274 |
price = variant.get("price", "N/A")
|
| 275 |
-
|
| 276 |
lines.append(
|
| 277 |
-
f" - {variant.get('title')} | "
|
| 278 |
-
f"Price: ${price} | "
|
| 279 |
-
f"{status}"
|
| 280 |
)
|
| 281 |
|
| 282 |
if truncated:
|
|
|
|
|
|
|
|
|
|
|
|
|
| 283 |
lines.append(f"\n...and {len(products) - max_products} more matching products not shown.")
|
| 284 |
|
| 285 |
return "\n".join(lines)
|
| 286 |
|
| 287 |
|
| 288 |
-
|
| 289 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 290 |
|
| 291 |
try:
|
| 292 |
products = []
|
|
@@ -299,7 +366,7 @@ def _handle_price_sort_query(shop_domain: str, access_token: str, query: str) ->
|
|
| 299 |
shop_domain, access_token, "", max_results=PRICE_SORT_MAX_RESULTS
|
| 300 |
)
|
| 301 |
except Exception:
|
| 302 |
-
logger.exception("Price-sort product fetch failed | query='%s'",
|
| 303 |
return "Sorry, I couldn't look up pricing right now."
|
| 304 |
|
| 305 |
all_variants = []
|
|
@@ -319,7 +386,7 @@ def _handle_price_sort_query(shop_domain: str, access_token: str, query: str) ->
|
|
| 319 |
if not all_variants:
|
| 320 |
return "No products found."
|
| 321 |
|
| 322 |
-
query_lower =
|
| 323 |
cheapest = min(all_variants, key=lambda x: x["price"])
|
| 324 |
expensive = max(all_variants, key=lambda x: x["price"])
|
| 325 |
|
|
@@ -331,44 +398,48 @@ def _handle_price_sort_query(shop_domain: str, access_token: str, query: str) ->
|
|
| 331 |
return f"Cheapest: {cheapest['product']} ({cheapest['variant']}) ${cheapest['price']:.2f}"
|
| 332 |
|
| 333 |
|
| 334 |
-
|
|
|
|
|
|
|
| 335 |
|
|
|
|
| 336 |
logger.info("=" * 60)
|
| 337 |
logger.info("Inventory lookup | query='%s'", query)
|
| 338 |
|
| 339 |
-
|
|
|
|
|
|
|
|
|
|
| 340 |
return f"Please visit: https://{shop_domain}"
|
| 341 |
|
| 342 |
-
|
| 343 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
| 344 |
|
| 345 |
-
shopify_query = build_shopify_search_query(
|
| 346 |
|
| 347 |
products = []
|
| 348 |
if shopify_query:
|
| 349 |
try:
|
| 350 |
products = search_products(shop_domain, access_token, shopify_query)
|
| 351 |
-
|
| 352 |
-
|
|
|
|
|
|
|
| 353 |
except Exception:
|
| 354 |
logger.exception("search_products failed for shopify_query=%r", shopify_query)
|
| 355 |
-
products = []
|
| 356 |
-
else:
|
| 357 |
-
logger.info("No extractable fields/keywords; skipping scoped search, going to fallback terms")
|
| 358 |
-
if not products:
|
| 359 |
-
for term in extract_search_terms(query):
|
| 360 |
-
try:
|
| 361 |
-
products = search_products(shop_domain, access_token, term)
|
| 362 |
-
print("\n=== PRODUCTS FROM SHOPIFY ===")
|
| 363 |
-
print(json.dumps(products, indent=2))
|
| 364 |
-
except Exception:
|
| 365 |
-
logger.exception("search_products failed for fallback term=%r", term)
|
| 366 |
-
continue
|
| 367 |
-
if products:
|
| 368 |
-
break
|
| 369 |
|
| 370 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 371 |
|
|
|
|
|
|
|
| 372 |
|
| 373 |
-
|
| 374 |
-
handle_product_query = build_inventory_context
|
|
|
|
| 19 |
EXPECTED_EXTRACTOR_FIELDS = list(SHOPIFY_FIELD_MAP.keys()) + ["keywords"]
|
| 20 |
|
| 21 |
STRONG_FIELDS = {"title", "product_type", "sku", "barcode"}
|
|
|
|
| 22 |
WEAK_FIELDS = {"tag", "vendor"}
|
|
|
|
| 23 |
|
| 24 |
+
MAX_PRODUCTS_IN_CONTEXT = 20
|
| 25 |
PRICE_SORT_MAX_RESULTS = 500
|
|
|
|
| 26 |
DESCRIPTION_TRUNCATE_LEN = 200
|
| 27 |
HASHTAG_OR_MENTION_RE = re.compile(r"[#@]\w+")
|
| 28 |
MAX_EXTRACTION_INPUT_CHARS = 600
|
| 29 |
+
FIELD_EXTRACTOR_MAX_TOKENS = 600 # bumped: LLM now returns up to 3 values per field
|
| 30 |
|
| 31 |
+
_BATCH_SIZE = 10
|
|
|
|
| 32 |
|
| 33 |
+
# Suffixes to strip when generating a stemmed root for fuzzy matching.
|
| 34 |
+
# Ordered longest-first so "ies" is tried before "es" and "s".
|
| 35 |
+
_STEM_SUFFIXES = re.compile(r"(ing|tion|ness|ies|es|s)$", re.IGNORECASE)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 36 |
|
| 37 |
REDIRECT_INTENTS = [
|
| 38 |
"full catalog",
|
|
|
|
| 57 |
PRICE_INTENTS = CHEAP_INTENTS + EXPENSIVE_INTENTS
|
| 58 |
|
| 59 |
|
| 60 |
+
# ---------------------------------------------------------------------------
|
| 61 |
+
# Query helpers
|
| 62 |
+
# ---------------------------------------------------------------------------
|
| 63 |
+
|
| 64 |
def is_redirect_query(query: str) -> bool:
|
| 65 |
query_lower = query.lower()
|
| 66 |
return any(intent in query_lower for intent in REDIRECT_INTENTS)
|
|
|
|
| 71 |
return any(intent in query_lower for intent in PRICE_INTENTS)
|
| 72 |
|
| 73 |
|
| 74 |
+
def _clean_query_for_extraction(raw_query: str) -> str:
|
| 75 |
+
"""Strip hashtags/mentions and cap length before sending to an LLM call.
|
| 76 |
+
|
| 77 |
+
Safe to call on any input — it's a no-op (aside from whitespace
|
| 78 |
+
collapsing) for queries that don't contain any of those patterns.
|
| 79 |
+
"""
|
| 80 |
+
cleaned = HASHTAG_OR_MENTION_RE.sub("", raw_query)
|
| 81 |
+
cleaned = re.sub(r"\s+", " ", cleaned).strip()
|
| 82 |
+
if len(cleaned) > MAX_EXTRACTION_INPUT_CHARS:
|
| 83 |
+
logger.warning(
|
| 84 |
+
"Truncating extraction input from %d to %d chars",
|
| 85 |
+
len(cleaned), MAX_EXTRACTION_INPUT_CHARS,
|
| 86 |
+
)
|
| 87 |
+
cleaned = cleaned[:MAX_EXTRACTION_INPUT_CHARS]
|
| 88 |
+
return cleaned
|
| 89 |
+
|
| 90 |
+
|
| 91 |
def safe_json_load(text: str):
|
| 92 |
text = text.strip().replace("```json", "").replace("```", "")
|
| 93 |
+
# Guard against models that prepend prose before the JSON object/array.
|
| 94 |
+
match = re.search(r"(\{.*\}|\[.*\])", text, re.DOTALL)
|
| 95 |
+
if match:
|
| 96 |
+
text = match.group(1)
|
| 97 |
return json.loads(text)
|
| 98 |
|
| 99 |
|
| 100 |
+
# ---------------------------------------------------------------------------
|
| 101 |
+
# Stemming / term expansion
|
| 102 |
+
# ---------------------------------------------------------------------------
|
| 103 |
+
|
| 104 |
+
def _stem_term(term: str) -> str:
|
| 105 |
+
"""Strip common suffixes to get a root form.
|
| 106 |
+
|
| 107 |
+
Not a full linguistic stemmer — just enough to collapse plural/gerund
|
| 108 |
+
variants that trip up Shopify's exact-match search.
|
| 109 |
+
e.g. "essentials" -> "essential", "chargers" -> "charger"
|
| 110 |
+
|
| 111 |
+
Terms of 4 chars or fewer are left alone to avoid mangling short words
|
| 112 |
+
like "bus" -> "bu".
|
| 113 |
+
"""
|
| 114 |
+
if len(term) <= 4:
|
| 115 |
+
return term
|
| 116 |
+
return _STEM_SUFFIXES.sub("", term.strip())
|
| 117 |
+
|
| 118 |
+
|
| 119 |
+
def _expand_term(term: str) -> list[str]:
|
| 120 |
+
"""Return [original, stemmed_root] when they differ, else just [original].
|
| 121 |
+
|
| 122 |
+
This means Shopify ORs both forms so "essentials" matches products
|
| 123 |
+
tagged/titled with "essential" and vice versa.
|
| 124 |
+
"""
|
| 125 |
+
term = term.strip()
|
| 126 |
+
if not term:
|
| 127 |
+
return []
|
| 128 |
+
stemmed = _stem_term(term)
|
| 129 |
+
if stemmed and stemmed != term:
|
| 130 |
+
return [term, stemmed]
|
| 131 |
+
return [term]
|
| 132 |
+
|
| 133 |
+
|
| 134 |
+
def _expand_terms(values: list[str]) -> list[str]:
|
| 135 |
+
"""Expand a list of terms to include stemmed roots, deduplicating order-preserving."""
|
| 136 |
+
seen = set()
|
| 137 |
+
expanded = []
|
| 138 |
+
for v in values:
|
| 139 |
+
for t in _expand_term(v):
|
| 140 |
+
if t.lower() not in seen:
|
| 141 |
+
seen.add(t.lower())
|
| 142 |
+
expanded.append(t)
|
| 143 |
+
return expanded
|
| 144 |
+
|
| 145 |
+
|
| 146 |
+
# ---------------------------------------------------------------------------
|
| 147 |
+
# LLM field extraction (single call — result is reused throughout)
|
| 148 |
+
# ---------------------------------------------------------------------------
|
| 149 |
|
| 150 |
+
def extract_shopify_fields(cleaned_query: str) -> dict:
|
| 151 |
+
"""Extract structured Shopify search fields from a pre-cleaned query.
|
| 152 |
+
|
| 153 |
+
Accepts an already-cleaned query so the caller controls cleaning and
|
| 154 |
+
can reuse the same cleaned string for logging / fallback terms.
|
| 155 |
+
|
| 156 |
+
Returns an empty dict on any failure so callers fall back gracefully.
|
| 157 |
"""
|
| 158 |
try:
|
|
|
|
| 159 |
response = client.chat.completions.create(
|
| 160 |
model="llama-3.1-8b-instant",
|
| 161 |
messages=[
|
|
|
|
| 166 |
response_format={"type": "json_object"},
|
| 167 |
max_tokens=FIELD_EXTRACTOR_MAX_TOKENS,
|
| 168 |
)
|
| 169 |
+
logger.debug("Field extractor usage | %s", response.usage)
|
| 170 |
raw = response.choices[0].message.content
|
| 171 |
data = safe_json_load(raw)
|
| 172 |
if not isinstance(data, dict):
|
|
|
|
| 174 |
return {}
|
| 175 |
return data
|
| 176 |
except Exception:
|
| 177 |
+
logger.exception("extract_shopify_fields failed for query=%r", cleaned_query)
|
| 178 |
return {}
|
| 179 |
|
| 180 |
|
| 181 |
def _normalize_fields(raw: dict) -> dict:
|
| 182 |
"""Coerce whatever the LLM returned into {field: list[str]} safely.
|
| 183 |
|
| 184 |
+
Handles strings instead of lists, extra/missing keys, nulls, and
|
| 185 |
+
non-string list items without raising.
|
| 186 |
"""
|
| 187 |
normalized = {}
|
| 188 |
for key in EXPECTED_EXTRACTOR_FIELDS:
|
|
|
|
| 196 |
return normalized
|
| 197 |
|
| 198 |
|
| 199 |
+
# ---------------------------------------------------------------------------
|
| 200 |
+
# Shopify query builder
|
| 201 |
+
# ---------------------------------------------------------------------------
|
| 202 |
+
|
| 203 |
def _quote_term(term: str) -> str:
|
| 204 |
+
"""Quote multi-word values so Shopify treats them as a phrase."""
|
|
|
|
| 205 |
term = term.strip()
|
| 206 |
if not term:
|
| 207 |
return ""
|
|
|
|
| 212 |
|
| 213 |
|
| 214 |
def _build_field_clause(field_name: str, values: list[str]) -> str:
|
| 215 |
+
# Expand each value to include its stemmed root before quoting.
|
| 216 |
+
expanded = _expand_terms(values)
|
| 217 |
+
quoted = [_quote_term(v) for v in expanded if v.strip()]
|
| 218 |
quoted = [q for q in quoted if q]
|
| 219 |
if not quoted:
|
| 220 |
return ""
|
|
|
|
| 224 |
|
| 225 |
|
| 226 |
def _build_keyword_clause(values: list[str]) -> str:
|
| 227 |
+
"""Unscoped free-text terms — Shopify's default multi-field search.
|
| 228 |
+
|
| 229 |
+
Used for anything that isn't a filterable field: vibe, use-case,
|
| 230 |
+
collection names, variant/option phrases, claimed attributes, etc.
|
| 231 |
+
Each value is expanded to include its stemmed root.
|
| 232 |
+
"""
|
| 233 |
+
expanded = _expand_terms(values)
|
| 234 |
+
quoted = [_quote_term(v) for v in expanded if v.strip()]
|
| 235 |
quoted = [q for q in quoted if q]
|
| 236 |
if not quoted:
|
| 237 |
return ""
|
|
|
|
| 239 |
return quoted[0]
|
| 240 |
return f"({' OR '.join(quoted)})"
|
| 241 |
|
| 242 |
+
|
| 243 |
def build_shopify_query_from_fields(fields: dict) -> str:
|
| 244 |
+
"""Build a Shopify search query from extracted fields using pure OR.
|
| 245 |
+
|
| 246 |
+
All field clauses and keywords are OR-joined for maximum recall.
|
| 247 |
+
Each term is also expanded to include its stemmed root so singular/
|
| 248 |
+
plural variants ("essential" / "essentials") both match.
|
| 249 |
+
"""
|
| 250 |
fields = _normalize_fields(fields)
|
| 251 |
clauses = []
|
| 252 |
|
|
|
|
| 261 |
|
| 262 |
return " OR ".join(clauses)
|
| 263 |
|
|
|
|
|
|
|
| 264 |
|
| 265 |
+
def build_shopify_search_query(cleaned_query: str, fields: dict) -> str:
|
| 266 |
+
"""Build the final Shopify query string from pre-extracted fields.
|
| 267 |
|
| 268 |
+
Separated from extraction so callers own the single LLM call and can
|
| 269 |
+
reuse `fields` for fallback without a second round-trip.
|
| 270 |
+
"""
|
| 271 |
+
query = build_shopify_query_from_fields(fields)
|
| 272 |
+
logger.info("Generated Shopify query | query='%s' -> %r", cleaned_query, query)
|
| 273 |
return query
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 274 |
|
|
|
|
| 275 |
|
| 276 |
+
# ---------------------------------------------------------------------------
|
| 277 |
+
# Product formatting
|
| 278 |
+
# ---------------------------------------------------------------------------
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 279 |
|
| 280 |
def format_products_for_llm(products: list[dict], max_products: int = MAX_PRODUCTS_IN_CONTEXT) -> str:
|
| 281 |
if not products:
|
|
|
|
| 285 |
products_to_show = products[:max_products]
|
| 286 |
|
| 287 |
lines = []
|
|
|
|
| 288 |
for product in products_to_show:
|
| 289 |
lines.append(
|
| 290 |
f"\nProduct: {product.get('title', '')} ({product.get('product_type', '')})"
|
| 291 |
)
|
|
|
|
| 292 |
if product.get("description"):
|
| 293 |
lines.append(f" Description: {product['description'][:DESCRIPTION_TRUNCATE_LEN]}")
|
|
|
|
| 294 |
if product.get("tags"):
|
| 295 |
lines.append(f" Tags: {', '.join(product['tags'])}")
|
|
|
|
| 296 |
for variant in product.get("variants", []):
|
| 297 |
status = "In Stock" if variant.get("available") else "Out of Stock"
|
| 298 |
price = variant.get("price", "N/A")
|
|
|
|
| 299 |
lines.append(
|
| 300 |
+
f" - {variant.get('title')} | Price: ${price} | {status}"
|
|
|
|
|
|
|
| 301 |
)
|
| 302 |
|
| 303 |
if truncated:
|
| 304 |
+
logger.debug(
|
| 305 |
+
"format_products_for_llm: capped at %d, dropped %d products",
|
| 306 |
+
max_products, len(products) - max_products,
|
| 307 |
+
)
|
| 308 |
lines.append(f"\n...and {len(products) - max_products} more matching products not shown.")
|
| 309 |
|
| 310 |
return "\n".join(lines)
|
| 311 |
|
| 312 |
|
| 313 |
+
# ---------------------------------------------------------------------------
|
| 314 |
+
# Batched fallback search
|
| 315 |
+
# ---------------------------------------------------------------------------
|
| 316 |
+
|
| 317 |
+
def _search_terms_batched(
|
| 318 |
+
shop_domain: str,
|
| 319 |
+
access_token: str,
|
| 320 |
+
terms: list[str],
|
| 321 |
+
batch_size: int = _BATCH_SIZE,
|
| 322 |
+
) -> list:
|
| 323 |
+
"""Search Shopify using OR-batches of fallback terms.
|
| 324 |
+
|
| 325 |
+
Batches `batch_size` terms per request instead of one-by-one, and
|
| 326 |
+
short-circuits as soon as any batch returns results.
|
| 327 |
+
"""
|
| 328 |
+
for i in range(0, len(terms), batch_size):
|
| 329 |
+
batch = terms[i: i + batch_size]
|
| 330 |
+
batched_query = " OR ".join(f'"{t}"' for t in batch)
|
| 331 |
+
try:
|
| 332 |
+
products = search_products(shop_domain, access_token, batched_query)
|
| 333 |
+
logger.debug("Batched fallback | hits=%d terms=%r", len(products), batch)
|
| 334 |
+
if products:
|
| 335 |
+
return products
|
| 336 |
+
except Exception:
|
| 337 |
+
logger.exception("search_products failed for batched terms=%r", batch)
|
| 338 |
+
continue
|
| 339 |
+
return []
|
| 340 |
+
|
| 341 |
+
|
| 342 |
+
# ---------------------------------------------------------------------------
|
| 343 |
+
# Price-sort handler
|
| 344 |
+
# ---------------------------------------------------------------------------
|
| 345 |
+
|
| 346 |
+
def _handle_price_sort_query(
|
| 347 |
+
shop_domain: str,
|
| 348 |
+
access_token: str,
|
| 349 |
+
cleaned_query: str,
|
| 350 |
+
fields: dict,
|
| 351 |
+
) -> str:
|
| 352 |
+
"""Handle cheapest/most-expensive queries.
|
| 353 |
+
|
| 354 |
+
Reuses already-extracted `fields` — no second LLM call.
|
| 355 |
+
"""
|
| 356 |
+
scoped_query = build_shopify_search_query(cleaned_query, fields)
|
| 357 |
|
| 358 |
try:
|
| 359 |
products = []
|
|
|
|
| 366 |
shop_domain, access_token, "", max_results=PRICE_SORT_MAX_RESULTS
|
| 367 |
)
|
| 368 |
except Exception:
|
| 369 |
+
logger.exception("Price-sort product fetch failed | query='%s'", cleaned_query)
|
| 370 |
return "Sorry, I couldn't look up pricing right now."
|
| 371 |
|
| 372 |
all_variants = []
|
|
|
|
| 386 |
if not all_variants:
|
| 387 |
return "No products found."
|
| 388 |
|
| 389 |
+
query_lower = cleaned_query.lower()
|
| 390 |
cheapest = min(all_variants, key=lambda x: x["price"])
|
| 391 |
expensive = max(all_variants, key=lambda x: x["price"])
|
| 392 |
|
|
|
|
| 398 |
return f"Cheapest: {cheapest['product']} ({cheapest['variant']}) ${cheapest['price']:.2f}"
|
| 399 |
|
| 400 |
|
| 401 |
+
# ---------------------------------------------------------------------------
|
| 402 |
+
# Main entry point
|
| 403 |
+
# ---------------------------------------------------------------------------
|
| 404 |
|
| 405 |
+
def build_inventory_context(shop_domain: str, access_token: str, query: str) -> str:
|
| 406 |
logger.info("=" * 60)
|
| 407 |
logger.info("Inventory lookup | query='%s'", query)
|
| 408 |
|
| 409 |
+
# Clean once — reused for LLM call, fallback terms, and logging.
|
| 410 |
+
cleaned_query = _clean_query_for_extraction(query)
|
| 411 |
+
|
| 412 |
+
if is_redirect_query(cleaned_query):
|
| 413 |
return f"Please visit: https://{shop_domain}"
|
| 414 |
|
| 415 |
+
# Single LLM call — fields are passed down to every subsequent step
|
| 416 |
+
# so nothing needs to re-extract from the same query.
|
| 417 |
+
fields = extract_shopify_fields(cleaned_query)
|
| 418 |
+
|
| 419 |
+
if is_price_sort_query(cleaned_query):
|
| 420 |
+
return _handle_price_sort_query(shop_domain, access_token, cleaned_query, fields)
|
| 421 |
|
| 422 |
+
shopify_query = build_shopify_search_query(cleaned_query, fields)
|
| 423 |
|
| 424 |
products = []
|
| 425 |
if shopify_query:
|
| 426 |
try:
|
| 427 |
products = search_products(shop_domain, access_token, shopify_query)
|
| 428 |
+
logger.debug(
|
| 429 |
+
"search_products result count=%d for shopify_query=%r",
|
| 430 |
+
len(products), shopify_query,
|
| 431 |
+
)
|
| 432 |
except Exception:
|
| 433 |
logger.exception("search_products failed for shopify_query=%r", shopify_query)
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 434 |
|
| 435 |
+
if not products:
|
| 436 |
+
# Reuse keywords from the already-extracted fields — no second LLM call.
|
| 437 |
+
fallback_terms = _normalize_fields(fields).get("keywords", [])
|
| 438 |
+
if fallback_terms:
|
| 439 |
+
logger.info("Primary search empty, trying keyword fallback | terms=%r", fallback_terms)
|
| 440 |
+
products = _search_terms_batched(shop_domain, access_token, fallback_terms)
|
| 441 |
|
| 442 |
+
print("\n=== ALL PRODUCTS RETURNED ===")
|
| 443 |
+
print(json.dumps(products, indent=2))
|
| 444 |
|
| 445 |
+
return format_products_for_llm(products)
|
|
|