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:
bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
# 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 DIFF1 StormRunner GT 0.94 $165 -$152 TrailKing WP 0.91 $142 -$383 Marathon Pro Gore-Tex 0.88 $210 +$304 All-Weather Racer 0.85 $198 +$185 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:
bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
# 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 PRICEWaterproof Running Socks 67% $18Performance Insoles 54% $35Reflective Running Vest 43% $45Sport Sunglasses 38% $89Energy 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:
bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
# 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 historyCross-sell During Checkout
Get recommendations based on current cart contents:
bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
# 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 plateConfiguration
Configure recommendation behavior in hyperfold.yaml:
yaml
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
# Configuration 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:
bash
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
# 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.