| 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:
- Search "running" in Sports & Outdoors + Apparel
- Filter by price <= 150
- Boost products with "athletic", "lightweight" tags
- 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:
- Search "headphones" in Electronics/Audio
- Filter for wireless + noise-cancelling tags
- Sort by rating descending
- 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:
- Search "fitness" in Sports & Outdoors
- Filter price <= 50
- 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
