Hyperfold AI

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    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

FactorWeightDescription
CategoryHighProducts in the same category hierarchy
AttributesHighSimilar specifications and features
Price RangeMediumWithin similar price tier
Visual StyleMediumSimilar aesthetic from image analysis
Usage ContextHighSame 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 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:

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 history

Cross-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 plate

Configuration

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.