Recommender Agent

// Similar Products - Vector Similarity
const similar = await recommender.getSimilar('prod_aero_x2', {
  limit: 5,
  min_similarity: 0.8,
});
// Returns products with similar attributes, style, category
 
// Complementary Products - Co-purchase Analysis
const complements = await recommender.getComplementary('prod_aero_x2', {
  limit: 3,
});
// Returns: socks, insoles, running vest (frequently bought together)
 
// Personalized - Customer History
const personalized = await recommender.getPersonalized('cust_xyz', {
  limit: 10,
  categories: ['footwear', 'apparel'],
});
// Returns products based on purchase history and preferences
 
// Contextual - Cart-Aware
const contextual = await recommender.getContextual({
  cart: ['prod_aero_x2', 'prod_socks_wp'],
  customer_id: 'cust_xyz',
  budget_remaining: 50,
});
// Returns products that complement cart within budget
 
// Upsell - Higher Value Alternatives
const upsell = await recommender.getUpsell('prod_aero_x2', {
  price_ceiling: 250,
});
// Returns premium alternatives: AeroRun X2 Pro, etc.

# Deploy reference recommender agent
$ hyperfold agent deploy --type=recommender --name="recommender-01"
 
> [Build] Using reference implementation...
> [Index] Verifying vector search index...
> [Deploy] Creating Cloud Run service...
 
✓ Recommender agent deployed!
 
  Name:      recommender-01
  Endpoints: /recommendations/*
  Index:     vertex_ai_vector_search (1,489 products)
 
# Deploy with custom model
$ hyperfold agent deploy --type=recommender \
  --name="smart-recommender" \
  --config=./agents/recommender-config.yaml

# recommender-config.yaml
name: recommender-agent
type: recommender
version: "1.0"
 
# Recommendation algorithms
algorithms:
  similar:
    enabled: true
    model: vertex_ai_vector_search
    min_similarity: 0.7
    exclude_same_category: false
 
  complementary:
    enabled: true
    source: co_purchase_data
    min_co_purchase_rate: 0.1
    lookback_days: 90
 
  personalized:
    enabled: true
    use_purchase_history: true
    use_browse_history: false  # Privacy setting
    history_window_days: 180
    weight_recent: 1.5
 
  contextual:
    enabled: true
    consider_cart: true
    consider_budget: true
    consider_session: true
 
# Filtering rules
filters:
  exclude_out_of_stock: true
  exclude_recently_purchased: true
  recently_purchased_days: 30
  min_inventory: 5
 
# Diversity settings
diversity:
  enabled: true
  max_same_category: 2
  max_same_brand: 2
 
# Caching
cache:
  similar_ttl: 3600        # 1 hour
  complementary_ttl: 86400 # 24 hours
  personalized_ttl: 300    # 5 minutes
 
# A/B testing
experiments:
  - name: algorithm_comparison
    variants:
      - name: vector_only
        weight: 0.5
        config:
          algorithms: [similar]
      - name: hybrid
        weight: 0.5
        config:
          algorithms: [similar, complementary, personalized]

// Using Recommender Agent in Negotiator
 
@HyperfoldAgent({ name: 'sales-bot', type: 'negotiator' })
export class SalesBot {
 
  @OnACPEvent('quote')
  async handleQuote(productId: string, offer: number, context: BuyerContext) {
    // Calculate quote as usual
    const quote = await this.calculateQuote(productId, offer, context);
 
    // Enhance with recommendations
    if (quote.status === 'counter_offer') {
      // Suggest bundle to increase value
      const complements = await this.recommender.getComplementary(productId, {
        limit: 2,
        max_price: 50,
      });
 
      if (complements.length > 0) {
        const bundlePrice = await this.calculateBundlePrice([
          { product_id: productId, price: quote.counter_price },
          ...complements,
        ]);
 
        quote.bundle_suggestion = {
          items: complements,
          bundle_price: bundlePrice.total,
          you_save: bundlePrice.savings,
        };
      }
    }
 
    return quote;
  }
 
  @OnACPEvent('search')
  async handleSearch(query: string, filters: SearchFilters) {
    const results = await this.catalog.search(query, filters);
 
    // Add personalized recommendations if customer known
    if (filters.customer_id) {
      const personalized = await this.recommender.getPersonalized(
        filters.customer_id,
        { limit: 3 }
      );
 
      results.personalized_picks = personalized;
    }
 
    return results;
  }
}