Skip to main content

Phase 4: Diversity Selection

Approach​

Method: Deterministic Heuristic
No Model Used
Input: 10-20 scored products
Output: Final 3 diverse recommendations

Purpose​

Select final 3 products ensuring diversity across:

  • Category distribution: Different product types
  • Price range: Varied price points
  • Gift-card handling: Strict rules (max 1, only if explicitly requested)
  • Deterministic: Same inputs → same outputs every time

Why Heuristic (No Model)?​

Deterministic​

  • Reproducible: Exact same selection every time
  • Testable: Easy to verify behavior
  • Debuggable: Clear logic, no black box
  • Stable: No model updates changing behavior

Fast​

  • Latency: <10ms (pure computation)
  • No API calls: Zero network overhead
  • No waiting: Instant selection
  • Predictable: Consistent timing

Controlled​

  • Exact rules: Business logic enforced precisely
  • No hallucination: Can't select non-existent products
  • No variability: Product selection is stable
  • Quality assured: Rules guarantee diversity

Cost-Free​

  • Zero model cost: No LLM inference
  • Pure computation: Only CPU cycles
  • Scalable: No per-request charges

Implementation​

Location: services/diversity.ts

function selectDiverseProducts(
  scoredProducts: ScoredProduct[],
  count: number = 3
): Product[] {
  const selected: Product[] = [];
  const usedCategories = new Set<string>();
  const priceRanges = { low: 0, medium: 0, high: 0 };
  
  // Sort by relevance score (descending)
  const sorted = [...scoredProducts].sort((a, b) => 
    b.relevanceScore - a.relevanceScore
  );
  
  // Gift card handling (max 1, only if explicit)
  const giftCards = sorted.filter(isGiftCard);
  const nonGiftCards = sorted.filter(p => !isGiftCard(p));
  
  // Strategy: Prefer non-gift-cards first
  for (const product of nonGiftCards) {
    if (selected.length >= count) break;
    
    // Check category diversity
    if (!usedCategories.has(product.category)) {
      selected.push(product);
      usedCategories.add(product.category);
      trackPriceRange(product.price, priceRanges);
      continue;
    }
    
    // Allow same category if different price range
    const priceRange = getPriceRange(product.price);
    if (priceRanges[priceRange] === 0) {
      selected.push(product);
      usedCategories.add(product.category);
      trackPriceRange(product.price, priceRanges);
    }
  }
  
  // Fill remaining slots (if any)
  while (selected.length < count && nonGiftCards.length > 0) {
    const next = nonGiftCards.find(p => !selected.includes(p));
    if (next) selected.push(next);
    else break;
  }
  
  return selected;
}

Diversity Rules​

1. Category Diversity​

// Prefer unique categories
const categoryCount = new Map<string, number>();

for (const product of sorted) {
  const count = categoryCount.get(product.category) || 0;
  
  if (count === 0) {
    // First in category - high priority
    score = product.relevanceScore * 1.2;
  } else if (count === 1) {
    // Second in category - normal priority
    score = product.relevanceScore;
  } else {
    // Third+ in category - low priority
    score = product.relevanceScore * 0.7;
  }
}

2. Price Distribution​

function getPriceRange(price: number): 'low' | 'medium' | 'high' {
  if (price < 15) return 'low';
  if (price < 40) return 'medium';
  return 'high';
}

// Aim for one from each range
const targetDistribution = {
  low: 1,
  medium: 1,
  high: 1
};

3. Gift Card Rules​

Strict enforcement:

const MAX_GIFT_CARDS = 1;
const GIFT_CARD_ONLY_IF_EXPLICIT = true;

// Only include gift card if:
// 1. User explicitly asked for gift cards
// 2. OR all other candidates exhausted
if (isGiftCard(product)) {
  if (!contextMentionsGiftCards(giftContext)) {
    continue; // Skip
  }
  
  const giftCardCount = selected.filter(isGiftCard).length;
  if (giftCardCount >= MAX_GIFT_CARDS) {
    continue; // Already have one
  }
}

Selection Algorithm​

Performance Characteristics​

Typical Execution:

Input: 20 scored products

Timing:
├─ Sort by score: ~1ms
├─ Category tracking: ~2ms
├─ Price range logic: ~2ms
├─ Gift card filtering: ~1ms
├─ Selection loop: ~3ms
└─ Validation: ~1ms
──────────────────────
Total: ~10ms ✓

Output: 3 diverse products

Example Scenarios​

Scenario 1: All Same Category​

Input:

20 products, all "Raamat" category, scores 0.9-0.5

Strategy:

  1. Take top 3 by score
  2. Ensure different price ranges
  3. Result: 3 books at different prices

Scenario 2: Mixed Categories​

Input:

10 products:
- 4 "Raamat" (scores 0.9, 0.85, 0.8, 0.75)
- 3 "Kinkekaart" (scores 0.7, 0.65, 0.6)
- 3 "Mänguasi" (scores 0.88, 0.82, 0.78)

Strategy:

  1. Take best "Raamat" (0.9)
  2. Take best "Mänguasi" (0.88)
  3. Take next best unique: "Raamat" (0.85) or "Kinkekaart" (0.7)?
  4. Result: 1 Book, 1 Toy, 1 Book (different price)

Scenario 3: Gift Card Request​

Input:

User: "kinkekaart sünnipäevaks"
10 products:
- 5 "Kinkekaart" (scores 0.95-0.85)
- 5 "Kingitus" (scores 0.7-0.6)

Strategy:

  1. Take top "Kinkekaart" (0.95)
  2. Take next best non-gift-card "Kingitus" (0.7)
  3. Take another "Kingitus" (0.68) - different price
  4. Result: 1 Gift Card, 2 Regular Gifts

Edge Cases​

Too Few Candidates​

if (products.length < 3) {
  // Return what we have
  return products;
}

All Same Category & Price​

if (allSameCategoryAndPrice(products)) {
  // Just take top 3 by score
  return products.slice(0, 3);
}

Gift Cards Only​

if (allGiftCards(products) && !explicitGiftCardRequest) {
  // Trigger broader search fallback
  throw new PoolExhaustionError('gift-cards-only');
}

Testing​

describe('Diversity Selection', () => {
  it('selects different categories', () => {
    const products = [
      { category: 'A', score: 0.9, price: 20 },
      { category: 'A', score: 0.85, price: 25 },
      { category: 'B', score: 0.8, price: 22 },
      { category: 'C', score: 0.75, price: 18 }
    ];
    
    const selected = selectDiverseProducts(products, 3);
    
    const categories = new Set(selected.map(p => p.category));
    expect(categories.size).toBeGreaterThanOrEqual(2);
  });
  
  it('enforces max 1 gift card rule', () => {
    const products = [
      { category: 'Kinkekaart', score: 0.95, price: 20 },
      { category: 'Kinkekaart', score: 0.9, price: 50 },
      { category: 'Kingitus', score: 0.85, price: 25 }
    ];
    
    const selected = selectDiverseProducts(products, 3);
    
    const giftCards = selected.filter(isGiftCard);
    expect(giftCards.length).toBeLessThanOrEqual(1);
  });
});

Monitoring​

{
  diversityTimeMs: number,       // Should be &lt;20ms
  inputCount: number,            // Candidates considered
  outputCount: number,           // Always 3 (or less)
  categoryDiversity: number,     // Unique categories / total
  priceSpread: number,          // max - min price
  giftCardIncluded: boolean,
  
  // Quality metrics
  averageScore: number,         // Of selected products
  scoreDropoff: number          // Highest - lowest score
}