Catalog Recommend
Generate product recommendations for similar, complementary, and personalized suggestions.
Overview
The hyperfold catalog recommend command generates intelligent product recommendations using vector similarity, purchase patterns, and customer profiles. These recommendations power agent upselling and bundling strategies.
Recommendations are used by the Negotiator Agent to suggest bundles during price negotiations, increasing average order value while providing customer value.
Similar Products
Find products similar to a reference product based on semantic embeddings:
# Find products similar to a given product
$ hyperfold catalog recommend --similar="prod_aero_x2"
> [Vector] Finding nearest neighbors in embedding space...
> [Results] 5 similar products found
SIMILAR TO: AeroRun X2 Marathon Shoe ($180)
RANK PRODUCT SIMILARITY PRICE DIFF
1 StormRunner GT 0.94 $165 -$15
2 TrailKing WP 0.91 $142 -$38
3 Marathon Pro Gore-Tex 0.88 $210 +$30
4 All-Weather Racer 0.85 $198 +$18
5 EnduroFlex Rain 0.82 $155 -$25
> [Insight] All similar products are waterproof running shoes
> [Insight] Price range: $142 - $210 (category average: $175)
Similarity Factors
| Factor | Weight | Description |
|---|---|---|
| Category | High | Products in the same category hierarchy |
| Attributes | High | Similar specifications and features |
| Price Range | Medium | Within similar price tier |
| Visual Style | Medium | Similar aesthetic from image analysis |
| Usage Context | High | Same use cases and occasions |
Complementary Products
Find products frequently purchased together:
# Find products frequently bought together
$ hyperfold catalog recommend --complements="prod_aero_x2"
> [Analysis] Analyzing purchase patterns...
> [Results] Complementary products found
COMPLEMENTS: AeroRun X2 Marathon Shoe
PRODUCT CO-PURCHASE % BUNDLE PRICE
Waterproof Running Socks 67% $18
Performance Insoles 54% $35
Reflective Running Vest 43% $45
Sport Sunglasses 38% $89
Energy Gel Pack (12) 31% $24
BUNDLE SUGGESTION:
AeroRun X2 + Socks + Insoles
Individual: $233
Bundle: $209 (10% off)
Margin: 22% (above floor)
Complementary recommendations require purchase history data. Import historical orders with hyperfold orders import to enable this feature.
Personalized Recommendations
Generate recommendations tailored to customer profiles:
# Get recommendations for a specific customer profile
$ hyperfold catalog recommend \
--persona="active_runner" \
--budget="100-200" \
--preferences="waterproof,lightweight"
> [Profile] Building recommendation context...
> [Results] Personalized recommendations
FOR: Active Runner | Budget: $100-$200
TOP PICKS:
1. AeroRun X2 Waterproof $180 ★★★★★
Perfect match: waterproof + lightweight (280g)
2. StormRunner GT $165 ★★★★☆
Great value: waterproof, slightly heavier (310g)
3. EnduroFlex Rain $155 ★★★★☆
Budget-friendly: water-resistant, ultra-light (250g)
# Recommendations based on purchase history
$ hyperfold catalog recommend --customer="cust_xyz123"
> [History] Loading customer purchase history...
> [Pattern] Customer prefers: running gear, premium brands
> [Results] Personalized recommendations based on history
Cross-sell During Checkout
Get recommendations based on current cart contents:
# Cross-sell recommendations during checkout
$ hyperfold catalog recommend --cart="prod_aero_x2,prod_socks_wp"
> [Cart] Analyzing cart contents...
> [Cross-sell] Finding relevant additions
CART CONTENTS:
- AeroRun X2 Marathon Shoe $180
- Waterproof Running Socks $18
Subtotal: $198
SUGGESTED ADDITIONS:
1. Performance Insoles $35 +18% orders include this
"Customers who bought running shoes often add insoles"
2. Reflective Armband $12 +15% orders include this
"Essential for early morning runs"
3. Energy Gel Pack $24 +12% orders include this
"Marathon prep essential"
POTENTIAL UPSELL:
Upgrade to AeroRun X2 Pro ($220) for carbon-fiber plate
Configuration
Configure recommendation behavior in hyperfold.yaml:
recommendations:
# Similar product settings
similar:
max_results: 5
min_similarity: 0.7
exclude_same_brand: false
# Complementary product settings
complements:
min_co_purchase_rate: 0.2
max_results: 5
enable_bundles: true
bundle_discount: 0.10
# Personalization settings
personalization:
use_purchase_history: true
history_window_days: 90
weight_recent_purchases: 1.5
# Cross-sell settings
cross_sell:
cart_threshold: 50.00
max_suggestions: 3
exclude_categories: ["gift_cards"]
API Integration
Get recommendations as JSON for programmatic use:
# Output recommendations as JSON for API integration
$ hyperfold catalog recommend --similar="prod_aero_x2" --output=json
{
"source_product": "prod_aero_x2",
"recommendations": [
{
"product_id": "prod_storm_gt",
"name": "StormRunner GT",
"similarity_score": 0.94,
"price": 165.00,
"reason": "Similar waterproof running shoe"
}
],
"bundle_suggestion": {
"products": ["prod_aero_x2", "prod_socks_wp", "prod_insoles"],
"individual_total": 233.00,
"bundle_price": 209.00,
"savings": 24.00
}
}
Next, learn about deploying agents that use these recommendations during negotiations.