Visual Similarity Product Recommendations

import { Mixpeek } from 'mixpeek';

const client = new Mixpeek({ apiKey: process.env.MIXPEEK_API_KEY });

// Index product catalog with visual analysis
await client.buckets.connect({
  collection_id: 'product-catalog',
  bucket_uri: 's3://catalog/images/',
  extractors: [
    'image-embedding',       // Visual similarity
    'color-extraction',      // Dominant colors, palette
    'pattern-detection',     // Stripes, florals, solids
    'style-classification',  // Modern, vintage, casual, formal
    'object-detection'       // Product type, components
  ],
  settings: {
    product_id_field: 'sku',
    multiple_images_per_product: true,
    extract_attributes: [
      'color_family', 'pattern', 'style', 'material_appearance',
      'shape', 'complexity', 'aesthetic'
    ]
  }
});

// Get visually similar product recommendations
async function getVisualRecommendations(productId: string, options?: {
  limit?: number;
  same_category?: boolean;
  price_range?: { min: number; max: number };
  exclude_owned?: string[];
}) {
  const product = await client.collections.get(productId);

  const similar = await client.retrieve({
    collection_id: 'product-catalog',
    query: {
      type: 'image',
      embedding: product.image_embedding
    },
    filters: {
      sku: { $ne: productId },
      in_stock: true,
      category: options?.same_category ? product.category : undefined,
      price: options?.price_range ? {
        $gte: options.price_range.min,
        $lte: options.price_range.max
      } : undefined
    },
    return_fields: [
      'sku', 'name', 'price', 'image_url',
      'category', 'similarity_score', 'visual_attributes'
    ],
    limit: options?.limit ?? 12
  });

  return similar.map(p => ({
    ...p,
    similarity_reason: explainSimilarity(product, p)
  }));
}

// Get complementary products for "shop the look"
async function getComplementaryProducts(productId: string, lookType: string) {
  const product = await client.collections.get(productId);

  // Find products that complement visually (same style, coordinating colors)
  const complementary = await client.recommendations.getComplementary({
    product_id: productId,
    product_embedding: product.image_embedding,
    product_attributes: product.visual_attributes,
    look_type: lookType,  // 'outfit', 'room', 'collection'
    rules: [
      { attribute: 'style', match: 'same' },
      { attribute: 'color_family', match: 'complementary' },
      { attribute: 'category', match: 'different' }  // Cross-category
    ],
    limit: 6
  });

  return {
    anchor_product: product,
    complementary_items: complementary,
    look_total: product.price + complementary.reduce((sum, p) => sum + p.price, 0)
  };
}

// Build visual preference profile from behavior
async function updateVisualPreferences(userId: string, interaction: {
  product_id: string;
  action: 'view' | 'save' | 'cart' | 'purchase';
}) {
  const product = await client.collections.get(interaction.product_id);

  // Weight by action strength
  const weight = {
    view: 0.1,
    save: 0.5,
    cart: 0.7,
    purchase: 1.0
  }[interaction.action];

  await client.users.updatePreferences({
    user_id: userId,
    visual_signals: {
      embedding: product.image_embedding,
      attributes: product.visual_attributes,
      weight: weight
    }
  });
}

// Get personalized visual recommendations
async function getPersonalizedRecommendations(userId: string) {
  return client.retrieve({
    collection_id: 'product-catalog',
    query: {
      type: 'user_preferences',
      user_id: userId
    },
    filters: { in_stock: true },
    limit: 20
  });
}