Qurrah commited on
Commit
fb7ef33
·
1 Parent(s): d6abbac

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 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. Use synonyms only for product_type and tag when obvious.
26
- 8. Keep values short (single words or short phrases).
 
 
 
 
 
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 INVENTORY DATA contains a matching product:
68
- - If the requested information exists → answer it.
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
- FIELD_EXTRACTOR_MAX_TOKENS = 400
33
- KEYWORD_EXTRACTOR_MAX_TOKENS = 120
34
 
35
-
36
- def _clean_query_for_extraction(raw_query: str) -> str:
37
- """Strip hashtags/mentions and cap length before sending text to an
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
- def extract_shopify_fields(user_query: str) -> dict:
89
- """Extract structured search fields from a customer message.
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
90
 
91
- Returns an empty dict on any failure (network error, bad JSON, etc.)
92
- so callers can fall back to plain keyword search instead of crashing.
 
 
 
 
 
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", user_query)
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 the LLM returning a string instead of a list, extra/missing
121
- keys, nulls, non-string list items, etc. without raising.
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, not
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
- quoted = [_quote_term(v) for v in values if v.strip()]
 
 
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 (Shopify's 'default' multi-field search),
159
- used for anything that isn't a real filterable field (vibe, use-case,
160
- collection names, variant/option phrases, claimed attributes, etc.)."""
161
- quoted = [_quote_term(v) for v in values if v.strip()]
 
 
 
 
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
- fields = extract_shopify_fields(user_query)
188
- query = build_shopify_query_from_fields(fields)
189
 
190
- logger.info("Generated query | %s", query)
 
 
 
 
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
- if not flat_terms:
243
- return [cleaned_query]
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
- def _handle_price_sort_query(shop_domain: str, access_token: str, query: str) -> str:
289
- scoped_query = build_shopify_search_query(query)
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
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'", query)
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 = 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
- def build_inventory_context(shop_domain: str, access_token: str, query: str) -> str:
 
 
335
 
 
336
  logger.info("=" * 60)
337
  logger.info("Inventory lookup | query='%s'", query)
338
 
339
- if is_redirect_query(query):
 
 
 
340
  return f"Please visit: https://{shop_domain}"
341
 
342
- if is_price_sort_query(query):
343
- return _handle_price_sort_query(shop_domain, access_token, query)
 
 
 
 
344
 
345
- shopify_query = build_shopify_search_query(query)
346
 
347
  products = []
348
  if shopify_query:
349
  try:
350
  products = search_products(shop_domain, access_token, shopify_query)
351
- print("\n=== PRODUCTS FROM SHOPIFY ===")
352
- print(json.dumps(products, indent=2))
 
 
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
- return format_products_for_llm(products)
 
 
 
 
 
371
 
 
 
372
 
373
- build_shopify_query = build_shopify_search_query
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)