Hyperfold AI

Nov 25, 2025

Product Recommendations

H
Hyperfold Team
AgentsSearch

Recommendation Types

Hyperfold supports multiple recommendation strategies:

  • Similar Products: Items with similar attributes/embeddings
  • Complementary Products: Items frequently bought together
  • Personalized: Based on customer purchase history
  • Trending: Popular items in the category

Similar Products

Find similar products using vector embeddings:

# Test similar product recommendations
$ hyperfold catalog recommend similar prod_aero_x2 --limit=5

SIMILAR TO: AeroRun X2 Marathon Shoe

PRODUCT                    SIMILARITY  PRICE    CATEGORY
StormRunner Pro            0.94        $165     Running/Trail
SpeedLite X               0.91        $145     Running/Road
AeroRun X1 (Previous)      0.89        $150     Running/Marathon
CloudStep Elite            0.87        $185     Running/Premium

Complementary Items

Suggest items that go well together:

// Vector-based similarity search
async function findSimilarProducts(productId: string, limit: number) {
const product = await getProduct(productId);

// Get product embedding
const embedding = product.embedding;

// Vector similarity search excluding the source product
const similar = await db.collection('products')
  .where('product_id', '!=', productId)
  .findNearest({
    vectorField: 'embedding',
    queryVector: embedding,
    limit,
    distanceMeasure: 'COSINE',
  });

return similar.docs.map(doc => ({
  ...doc.data(),
  similarity_score: doc.distance,
}));
}

// Complementary products based on purchase history
async function findComplementaryProducts(productId: string) {
// Query orders containing this product
const orders = await db.collection('orders')
  .where('items', 'array-contains', productId)
  .limit(100)
  .get();

// Count co-purchased products
const coPurchased = new Map<string, number>();
for (const order of orders.docs) {
  for (const item of order.data().items) {
    if (item !== productId) {
      coPurchased.set(item, (coPurchased.get(item) || 0) + 1);
    }
  }
}

// Return top co-purchased products
return [...coPurchased.entries()]
  .sort((a, b) => b[1] - a[1])
  .slice(0, 5)
  .map(([id, count]) => ({ product_id: id, co_purchase_count: count }));
}

Personalization

Personalize recommendations based on customer context:

// Personalized recommendations
async function getPersonalizedRecommendations(customerId: string) {
const customer = await getCustomerContext(customerId);

// Get customer's purchase history embedding
const historyEmbedding = await computeHistoryEmbedding(
  customer.purchase_history
);

// Find products similar to their preferences
return await db.collection('products')
  .findNearest({
    vectorField: 'embedding',
    queryVector: historyEmbedding,
    limit: 10,
  });
}

Bundle Suggestions

Use recommendations to create bundle offers:

// Recommendation implementation
import { recommendSimilar, recommendComplementary } from '@hyperfold/tools';

@OnACPEvent('quote')
async handleQuote(productId: string, offer: number, context: any) {
const product = await getProduct(productId);
const pricing = await calculateDynamicPrice(product, context);

// Get recommendations for upsell/cross-sell
const [similar, complementary] = await Promise.all([
  recommendSimilar(productId, { limit: 3 }),
  recommendComplementary(productId, { limit: 2 }),
]);

return {
  status: 'counter_offer',
  price: pricing.suggested,

  // Suggest premium alternative (upsell)
  upsell_suggestion: similar.find(p => p.price > product.price),

  // Suggest bundle (cross-sell)
  bundle_suggestion: {
    items: [product, ...complementary],
    bundle_price: calculateBundlePrice([product, ...complementary]),
    savings: calculateSavings([product, ...complementary]),
  },
};
}