smart-search

name	smart-search
description	Advanced intelligent product search with query deconstruction, constraint extraction, and relevance ranking
version	1.0
authors	["Commerce Team"]
tags	["search","ai","ranking","nlp","smart","advanced"]

Smart Search Skill

Overview

An intelligent product search skill that goes beyond keyword matching. It deconstructs natural language queries into structured parameters, applies sophisticated constraints, and ranks results by relevance.

When to Use

• Complex natural language queries ("I need something for my morning jog under $100")
• Multi-constraint searches (price + category + features + rating)
• Vague or ambiguous requests requiring interpretation
• When simple keyword search returns too many or too few results
• When results need intelligent ranking and prioritization

Inputs

Input	Type	Required	Description
query	string	Yes	Natural language search query
constraints	object	No	Explicit constraints to override extracted ones

Constraint Object

{
  "category": "Electronics",
  "subcategory": "Audio",
  "minPrice": 0,
  "maxPrice": 100,
  "minRating": 4.0,
  "features": ["wireless", "bluetooth"],
  "excludeFeatures": ["wired"],
  "brands": ["AudioTech", "SoundWave"],
  "excludeBrands": [],
  "inStockOnly": true,
  "sortBy": "relevance"
}

Tools Required

Tool	Purpose
search_products	Search product catalog by keyword
get_categories	Get available category hierarchy
get_product_details	Get detailed product information

Logic Flow

┌─────────────────────────────────────────────────────────────────────┐
│                    SMART SEARCH PROCESS                             │
├─────────────────────────────────────────────────────────────────────┤
│                                                                     │
│  1. DECONSTRUCT QUERY                                               │
│     ├─ Extract intent (find, compare, recommend)                    │
│     ├─ Identify product type keywords                               │
│     ├─ Extract price constraints ("under $100", "budget")           │
│     ├─ Extract feature requirements ("wireless", "waterproof")      │
│     ├─ Identify use case context ("for running", "at the office")   │
│     └─ Detect quality preferences ("best", "top-rated")             │
│                                                                     │
│  2. APPLY CONSTRAINTS                                               │
│     ├─ Price range (extracted + explicit)                           │
│     ├─ Category filtering                                           │
│     ├─ Feature matching (required vs nice-to-have)                  │
│     ├─ Brand preferences                                            │
│     └─ Stock availability                                           │
│                                                                     │
│  3. SEARCH & FILTER                                                 │
│     ├─ Execute search_products with primary keywords                │
│     ├─ Apply hard filters (price, stock, category)                  │
│     └─ Apply soft filters (features, rating)                        │
│                                                                     │
│  4. RANK RESULTS                                                    │
│     ├─ Calculate relevance score                                    │
│     ├─ Boost for feature matches                                    │
│     ├─ Boost for rating/review quality                              │
│     ├─ Boost for price-to-value ratio                               │
│     └─ Penalize for missing "nice-to-have" features                 │
│                                                                     │
│  5. FORMAT OUTPUT                                                   │
│     ├─ Return top N ranked results                                  │
│     ├─ Include relevance explanation                                │
│     └─ Suggest refinements if results are poor                      │
│                                                                     │
└─────────────────────────────────────────────────────────────────────┘

Query Deconstruction Rules

Price Extraction

Pattern	Extracted Constraint
"under $X" / "below $X" / "less than $X"	maxPrice = X
"over $X" / "above $X" / "more than $X"	minPrice = X
"$X - $Y" / "between $X and $Y"	minPrice = X, maxPrice = Y
"budget" / "affordable" / "cheap"	maxPrice = 50
"mid-range"	minPrice = 50, maxPrice = 150
"premium" / "high-end" / "luxury"	minPrice = 150

Feature Extraction

Pattern	Feature Tags
"wireless" / "cordless" / "bluetooth"	["wireless", "bluetooth"]
"waterproof" / "water resistant"	["waterproof", "water-resistant"]
"noise cancelling" / "ANC"	["noise-cancelling", "anc"]
"portable" / "travel"	["portable", "lightweight"]
"fitness" / "workout" / "gym"	["fitness", "athletic"]
"eco-friendly" / "sustainable" / "green"	["eco-friendly", "sustainable", "organic"]

Use Case to Category Mapping

Use Case	Category	Subcategory
"music" / "listening" / "audio"	Electronics	Audio
"fitness" / "workout" / "running"	Sports & Outdoors, Apparel	Fitness, Footwear
"office" / "work"	Electronics	Accessories
"travel" / "commute"	Various	(portable items)
"home" / "kitchen"	Home & Kitchen	Various

Quality Signals

Pattern	Constraint
"best" / "top" / "highest rated"	sortBy = "rating", minRating = 4.5
"popular" / "most reviewed"	sortBy = "reviews_count"
"new" / "latest"	sortBy = "date_added"
"value" / "bang for buck"	Calculate price/rating ratio

Ranking Algorithm

Relevance Score Calculation

score = baseRelevance
      + (featureMatchScore * 0.3)
      + (ratingScore * 0.2)
      + (priceValueScore * 0.2)
      + (reviewConfidenceScore * 0.1)
      + (stockBoost * 0.1)
      + (categoryMatchScore * 0.1)

Score Components

Component	Formula	Max Points
baseRelevance	keyword matches in name/description/tags	40
featureMatchScore	(matched features / required features) * 30	30
ratingScore	(rating - 3.0) / 2.0 * 20	20
priceValueScore	(category_avg_price - price) / category_avg_price * 20	20
reviewConfidenceScore	min(reviews_count / 1000, 1) * 10	10
stockBoost	inStock ? 10 : 0	10
categoryMatchScore	exact category match ? 10 : 0	10

Output Format

Success Response

{
  "success": true,
  "query": "wireless headphones under $100",
  "parsedConstraints": {
    "keywords": ["wireless", "headphones"],
    "maxPrice": 100,
    "features": ["wireless", "bluetooth"],
    "category": "Electronics"
  },
  "results": [
    {
      "product": { "id": "PROD-001", "name": "...", ... },
      "relevanceScore": 87,
      "matchedFeatures": ["wireless", "bluetooth", "noise-cancelling"],
      "priceValue": "excellent",
      "matchReason": "Matches all requirements with excellent rating"
    }
  ],
  "totalMatches": 3,
  "refinementSuggestions": []
}

Low Results Response

{
  "success": true,
  "query": "purple wireless headphones with GPS",
  "parsedConstraints": {...},
  "results": [...],
  "totalMatches": 0,
  "refinementSuggestions": [
    "Try removing 'GPS' - no audio products have GPS",
    "Try removing color constraint - limited purple options",
    "Consider 'blue' or 'black' colors instead"
  ]
}

Best Practices

Do

• Start by fully deconstructing the query before searching
• Apply hard constraints first (price, category), then soft constraints (features)
• Always calculate relevance scores for ranking
• Provide explanation for why each result matched
• Suggest refinements when results are poor

Don't

• Return unranked results
• Ignore implicit constraints in natural language
• Return more than 5 results without explanation
• Skip the deconstruction step for "simple" queries
• Fail silently when no results found

Examples

Example 1: Complex Natural Language

Query: "I need something for my morning runs, preferably under $150"

Deconstruction:

• Intent: Find product
• Use case: running (morning)
• Keywords: running, fitness
• Price: maxPrice = 150
• Implicit: athletic, comfortable, portable

Search Strategy:

1. Search "running" in Sports & Outdoors + Apparel
2. Filter by price <= 150
3. Boost products with "athletic", "lightweight" tags
4. Return Running Shoes (high score) + Fitness Watch (medium score)

Example 2: Feature-Heavy Query

Query: "best wireless noise cancelling headphones"

Deconstruction:

• Intent: Find best
• Product: headphones
• Required features: wireless, noise-cancelling
• Quality: highest rated (minRating = 4.5)

Search Strategy:

1. Search "headphones" in Electronics/Audio
2. Filter for wireless + noise-cancelling tags
3. Sort by rating descending
4. Return Wireless Bluetooth Headphones (matches all)

Example 3: Budget Query

Query: "cheap fitness gear"

Deconstruction:

• Intent: Find
• Category: Sports & Outdoors (fitness)
• Price: "cheap" = maxPrice = 50
• Keywords: fitness, workout

Search Strategy:

1. Search "fitness" in Sports & Outdoors
2. Filter price <= 50
3. Return: Yoga Mat ($39.99), Water Bottle ($24.99)

Integration Notes

This skill works best when combined with:

• product-comparison: For comparing top results
• product-recommendation: For personalized suggestions
• Memory tools: For learning user preferences over time