Top Customer Queries

When agentic_config.top_customer_queries is configured, queries matching one of the keywords bypass normal multi-category expansion. Instead, the LLM returns a single category using the matched keyword as the search term. This applies to both the agentic search and converse (chat) endpoints.

Configuration

Set top_customer_queries in agentic_config (DynamoDB):

{
  "agentic_config": {
    "top_customer_queries": ["new", "sale", "trending", "popular"]
  }
}

Disabled by default (empty list when not configured).

Should be used with filter_facets.enabled: true so the LLM can generate filters from remaining terms (see ./automatic-filters.md).

Behavior

User query	Matched keyword	Search query	Filter (if auto filters enabled)
trending	trending	trending	none
trending dresses	trending	trending	e.g. collections:(dresses)
new shoes	new	new	e.g. productType:(Shoes)
blue jacket	(no match)	normal multi-category expansion	normal behavior

• The category label is derived from the full user query (e.g. "Trending Dresses").
• Matching is case-insensitive and checks individual words in the query.
• Configured queries must be single words (e.g. "trending", "sale"). Multi-word entries like "best sellers" will never match.

Agentic search

• The LLM returns exactly 1 query_expansion with confidence 1.0, regardless of maxCategories.
• Short query bypass: normally, queries under 4 words skip the LLM and go straight to Marqo. Top customer query matches override this — a 1-word query like "trending" still goes through the LLM path.
• DDB cached queries still take priority: if a matching query is also cached in DDB, the cached result is used instead.

Converse (chat)

• The LLM calls execute_search with exactly 1 search pair (instead of the usual 3-4), using the matched keyword as the query and confidence 1.0.

Implementation

• Prompt utility: src/top-customer-query-prompt-utils.ts — reusable, injected into custom prompts alongside getFilterDSLInstructions
  • getTopCustomerQueryInstructions() — for agentic search (query_expansions format)
  • getTopCustomerQueryConverseInstructions() — for converse (execute_search format)
• Match detection: matchesTopCustomerQuery() in src/search/agentic-search.ts — used by both endpoints
• Agentic search: the base prompt injects the instructions automatically. Custom prompts must call getTopCustomerQueryInstructions() and include the result in their template (see the Fashion Nova prompt for an example).
• Converse: instructions are injected automatically via getConverseSystemInstructions() in src/converse/prompts.ts.