Product Recommendations

# 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

// 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 }));
}

// 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,
    });
}

// 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]),
    },
  };
}