@higher.archi/boe 1.0.30 → 1.0.31

package/src/engines/menu-engineering/strategy.ts

@@ -0,0 +1,414 @@
+/**
+ * Menu Engineering Engine Strategy
+ *
+ * Core execution logic for all menu engineering strategies:
+ * - classify: categorize items into Stars/Plowhorses/Puzzles/Dogs
+ * - price-optimization: model price change impacts with elasticity
+ * - mix-analysis: analyze category/daypart mix with divergence detection
+ */
+
+import type {
+  CompiledMenuEngineeringRuleSet,
+  CompiledClassifyRuleSet,
+  CompiledPriceOptimizationRuleSet,
+  CompiledMixAnalysisRuleSet,
+  MenuItem,
+  MenuClassification,
+  ClassifiedItem,
+  MenuSummary,
+  PriceOptimizationItem,
+  CategoryMixResult,
+  ClassifyResult,
+  PriceOptimizationResult,
+  MixAnalysisResult,
+  MenuEngineeringResult,
+  MenuEngineeringOptions
+} from './types';
+
+// ========================================
+// Helpers
+// ========================================
+
+function round(value: number, decimals: number): number {
+  const factor = Math.pow(10, decimals);
+  return Math.round(value * factor) / factor;
+}
+
+function classifyItem(
+  salesMixPct: number,
+  contributionMargin: number,
+  mixThreshold: number,
+  marginThreshold: number
+): MenuClassification {
+  const highMix = salesMixPct >= mixThreshold;
+  const highMargin = contributionMargin >= marginThreshold;
+
+  if (highMix && highMargin) return 'star';
+  if (highMix && !highMargin) return 'plowhorse';
+  if (!highMix && highMargin) return 'puzzle';
+  return 'dog';
+}
+
+function getRecommendation(classification: MenuClassification): string {
+  switch (classification) {
+    case 'star':
+      return 'Maintain quality and visibility. Signature item -- protect pricing and placement.';
+    case 'plowhorse':
+      return 'Popular but low margin. Consider portion adjustments, ingredient substitution, or slight price increase.';
+    case 'puzzle':
+      return 'High margin but low sales. Improve menu placement, rename, or bundle with popular items.';
+    case 'dog':
+      return 'Low popularity and low margin. Consider removing, repositioning, or reworking the recipe.';
+  }
+}
+
+function computeClassifiedItems(
+  items: MenuItem[],
+  mixThreshold: number,
+  marginThreshold: number
+): { classifiedItems: ClassifiedItem[]; totalSalesCount: number } {
+  const totalSalesCount = items.reduce((sum, item) => sum + item.salesCount, 0);
+
+  const classifiedItems: ClassifiedItem[] = items.map(item => {
+    const contributionMargin = round(item.sellingPrice - item.plateCost, 2);
+    const foodCostPct = item.sellingPrice > 0
+      ? round((item.plateCost / item.sellingPrice) * 100, 2)
+      : 0;
+    const salesMixPct = totalSalesCount > 0
+      ? round((item.salesCount / totalSalesCount) * 100, 2)
+      : 0;
+
+    const classification = classifyItem(salesMixPct, contributionMargin, mixThreshold, marginThreshold);
+
+    return {
+      id: item.id,
+      name: item.name,
+      category: item.category,
+      sellingPrice: item.sellingPrice,
+      plateCost: item.plateCost,
+      salesCount: item.salesCount,
+      contributionMargin,
+      foodCostPct,
+      salesMixPct,
+      classification,
+      recommendation: getRecommendation(classification)
+    };
+  });
+
+  return { classifiedItems, totalSalesCount };
+}
+
+function computeSummary(items: ClassifiedItem[]): MenuSummary {
+  const totalItems = items.length;
+  const totalSalesCount = items.reduce((sum, i) => sum + i.salesCount, 0);
+  const totalRevenue = items.reduce((sum, i) => sum + i.sellingPrice * i.salesCount, 0);
+  const totalCost = items.reduce((sum, i) => sum + i.plateCost * i.salesCount, 0);
+  const totalProfit = round(totalRevenue - totalCost, 2);
+
+  const avgContributionMargin = totalItems > 0
+    ? round(items.reduce((sum, i) => sum + i.contributionMargin, 0) / totalItems, 2)
+    : 0;
+  const avgFoodCostPct = totalItems > 0
+    ? round(items.reduce((sum, i) => sum + i.foodCostPct, 0) / totalItems, 2)
+    : 0;
+  const avgSalesMixPct = totalItems > 0
+    ? round(100 / totalItems, 2)
+    : 0;
+
+  const classificationCounts: Record<MenuClassification, number> = {
+    star: 0,
+    plowhorse: 0,
+    puzzle: 0,
+    dog: 0
+  };
+  for (const item of items) {
+    classificationCounts[item.classification]++;
+  }
+
+  return {
+    totalItems,
+    totalSalesCount,
+    totalRevenue: round(totalRevenue, 2),
+    totalCost: round(totalCost, 2),
+    totalProfit,
+    avgContributionMargin,
+    avgFoodCostPct,
+    avgSalesMixPct,
+    classificationCounts
+  };
+}
+
+// ========================================
+// Strategy Executor
+// ========================================
+
+export class MenuEngineeringExecutor {
+  run(
+    ruleSet: CompiledMenuEngineeringRuleSet,
+    _options: MenuEngineeringOptions = {}
+  ): MenuEngineeringResult {
+    switch (ruleSet.strategy) {
+      case 'classify':
+        return this.runClassify(ruleSet);
+      case 'price-optimization':
+        return this.runPriceOptimization(ruleSet);
+      case 'mix-analysis':
+        return this.runMixAnalysis(ruleSet);
+      default:
+        throw new Error(`Unknown menu engineering strategy: '${(ruleSet as any).strategy}'`);
+    }
+  }
+
+  // ========================================
+  // Classify Strategy
+  // ========================================
+
+  private runClassify(ruleSet: CompiledClassifyRuleSet): ClassifyResult {
+    const startTime = performance.now();
+
+    // Compute thresholds
+    const items = ruleSet.items;
+    const totalSalesCount = items.reduce((sum, i) => sum + i.salesCount, 0);
+    const margins = items.map(i => i.sellingPrice - i.plateCost);
+    const mixPcts = items.map(i => totalSalesCount > 0 ? (i.salesCount / totalSalesCount) * 100 : 0);
+
+    const avgMargin = margins.reduce((sum, m) => sum + m, 0) / margins.length;
+    const avgMix = mixPcts.reduce((sum, m) => sum + m, 0) / mixPcts.length;
+
+    const mixThreshold = ruleSet.config.mixThresholdMode === 'custom'
+      ? ruleSet.config.customMixThreshold
+      : avgMix;
+    const marginThreshold = ruleSet.config.marginThresholdMode === 'custom'
+      ? ruleSet.config.customMarginThreshold
+      : avgMargin;
+
+    const { classifiedItems } = computeClassifiedItems(items, mixThreshold, marginThreshold);
+    const summary = computeSummary(classifiedItems);
+
+    const executionTimeMs = round((performance.now() - startTime) * 100, 0) / 100;
+
+    return {
+      items: classifiedItems,
+      summary,
+      executionTimeMs
+    };
+  }
+
+  // ========================================
+  // Price Optimization Strategy
+  // ========================================
+
+  private runPriceOptimization(ruleSet: CompiledPriceOptimizationRuleSet): PriceOptimizationResult {
+    const startTime = performance.now();
+
+    // Run baseline classify
+    const items = ruleSet.items;
+    const totalSalesCount = items.reduce((sum, i) => sum + i.salesCount, 0);
+    const margins = items.map(i => i.sellingPrice - i.plateCost);
+    const mixPcts = items.map(i => totalSalesCount > 0 ? (i.salesCount / totalSalesCount) * 100 : 0);
+
+    const avgMargin = margins.reduce((sum, m) => sum + m, 0) / margins.length;
+    const avgMix = mixPcts.reduce((sum, m) => sum + m, 0) / mixPcts.length;
+
+    const { classifiedItems: baselineItems } = computeClassifiedItems(items, avgMix, avgMargin);
+
+    // Build lookup maps
+    const baselineMap = new Map(baselineItems.map(i => [i.id, i]));
+    const priceChangeMap = new Map(ruleSet.config.priceChanges.map(pc => [pc.itemId, pc]));
+    const elasticityMap = new Map<string, number>();
+
+    for (const e of ruleSet.config.elasticities) {
+      if (e.itemId) {
+        elasticityMap.set(`item:${e.itemId}`, e.elasticity);
+      }
+      if (e.category) {
+        elasticityMap.set(`cat:${e.category}`, e.elasticity);
+      }
+    }
+
+    // Apply price changes and compute new projected items
+    const modifiedItems: MenuItem[] = items.map(item => {
+      const change = priceChangeMap.get(item.id);
+      if (!change) return item;
+      return { ...item, sellingPrice: change.newPrice };
+    });
+
+    // Estimate new sales counts based on elasticity
+    const projectedItems: MenuItem[] = modifiedItems.map(item => {
+      const change = priceChangeMap.get(item.id);
+      if (!change) return item;
+
+      const originalItem = items.find(i => i.id === item.id)!;
+      const priceChangePct = (change.newPrice - originalItem.sellingPrice) / originalItem.sellingPrice;
+
+      // Resolve elasticity: item-specific > category > default
+      let elasticity = ruleSet.config.defaultElasticity;
+      if (elasticityMap.has(`item:${item.id}`)) {
+        elasticity = elasticityMap.get(`item:${item.id}`)!;
+      } else if (item.category && elasticityMap.has(`cat:${item.category}`)) {
+        elasticity = elasticityMap.get(`cat:${item.category}`)!;
+      }
+
+      const estimatedNewSalesCount = Math.max(0, Math.round(
+        originalItem.salesCount * (1 + elasticity * priceChangePct)
+      ));
+
+      return { ...item, salesCount: estimatedNewSalesCount };
+    });
+
+    // Re-classify with new data
+    const newTotalSalesCount = projectedItems.reduce((sum, i) => sum + i.salesCount, 0);
+    const newMargins = projectedItems.map(i => i.sellingPrice - i.plateCost);
+    const newMixPcts = projectedItems.map(i =>
+      newTotalSalesCount > 0 ? (i.salesCount / newTotalSalesCount) * 100 : 0
+    );
+
+    const newAvgMargin = newMargins.reduce((sum, m) => sum + m, 0) / newMargins.length;
+    const newAvgMix = newMixPcts.reduce((sum, m) => sum + m, 0) / newMixPcts.length;
+
+    const { classifiedItems: newClassifiedItems } = computeClassifiedItems(
+      projectedItems, newAvgMix, newAvgMargin
+    );
+    const newClassifiedMap = new Map(newClassifiedItems.map(i => [i.id, i]));
+
+    // Build optimization results for changed items
+    const optimizationItems: PriceOptimizationItem[] = [];
+    for (const change of ruleSet.config.priceChanges) {
+      const baseline = baselineMap.get(change.itemId)!;
+      const projected = newClassifiedMap.get(change.itemId)!;
+      const originalItem = items.find(i => i.id === change.itemId)!;
+
+      const priceChangePct = round(
+        ((change.newPrice - originalItem.sellingPrice) / originalItem.sellingPrice) * 100, 2
+      );
+
+      const originalRevenue = originalItem.sellingPrice * originalItem.salesCount;
+      const originalProfit = baseline.contributionMargin * originalItem.salesCount;
+      const projectedRevenue = projected.sellingPrice * projected.salesCount;
+      const projectedProfit = projected.contributionMargin * projected.salesCount;
+
+      optimizationItems.push({
+        id: change.itemId,
+        name: baseline.name,
+        originalPrice: originalItem.sellingPrice,
+        newPrice: change.newPrice,
+        priceChangePct,
+        originalMargin: baseline.contributionMargin,
+        newMargin: projected.contributionMargin,
+        estimatedNewSalesCount: projected.salesCount,
+        originalClassification: baseline.classification,
+        newClassification: projected.classification,
+        projectedRevenueChange: round(projectedRevenue - originalRevenue, 2),
+        projectedProfitChange: round(projectedProfit - originalProfit, 2)
+      });
+    }
+
+    const summary = computeSummary(newClassifiedItems);
+    const executionTimeMs = round((performance.now() - startTime) * 100, 0) / 100;
+
+    return {
+      items: optimizationItems,
+      summary,
+      executionTimeMs
+    };
+  }
+
+  // ========================================
+  // Mix Analysis Strategy
+  // ========================================
+
+  private runMixAnalysis(ruleSet: CompiledMixAnalysisRuleSet): MixAnalysisResult {
+    const startTime = performance.now();
+
+    const items = ruleSet.items;
+    const groupField = ruleSet.config.groupBy === 'daypart'
+      ? ruleSet.config.daypartField
+      : 'category';
+
+    // Group items
+    const groups = new Map<string, MenuItem[]>();
+    for (const item of items) {
+      const key = (item as any)[groupField] as string ?? 'uncategorized';
+      if (!groups.has(key)) {
+        groups.set(key, []);
+      }
+      groups.get(key)!.push(item);
+    }
+
+    // Compute overall totals for mix percentages
+    const overallTotalSalesCount = items.reduce((sum, i) => sum + i.salesCount, 0);
+    const overallTotalRevenue = items.reduce((sum, i) => sum + i.sellingPrice * i.salesCount, 0);
+    const overallTotalProfit = items.reduce(
+      (sum, i) => sum + (i.sellingPrice - i.plateCost) * i.salesCount, 0
+    );
+
+    // Run classify within each group and compute category-level metrics
+    const categories: CategoryMixResult[] = [];
+    for (const [category, groupItems] of groups) {
+      // Classify within group
+      const totalGroupSales = groupItems.reduce((sum, i) => sum + i.salesCount, 0);
+      const groupMargins = groupItems.map(i => i.sellingPrice - i.plateCost);
+      const groupMixPcts = groupItems.map(i =>
+        totalGroupSales > 0 ? (i.salesCount / totalGroupSales) * 100 : 0
+      );
+      const groupAvgMargin = groupMargins.reduce((sum, m) => sum + m, 0) / groupMargins.length;
+      const groupAvgMix = groupMixPcts.reduce((sum, m) => sum + m, 0) / groupMixPcts.length;
+
+      const { classifiedItems } = computeClassifiedItems(groupItems, groupAvgMix, groupAvgMargin);
+
+      const totalRevenue = groupItems.reduce((sum, i) => sum + i.sellingPrice * i.salesCount, 0);
+      const totalCost = groupItems.reduce((sum, i) => sum + i.plateCost * i.salesCount, 0);
+      const totalProfit = totalRevenue - totalCost;
+
+      const avgContributionMargin = groupItems.length > 0
+        ? round(groupItems.reduce((sum, i) => sum + (i.sellingPrice - i.plateCost), 0) / groupItems.length, 2)
+        : 0;
+
+      categories.push({
+        category,
+        itemCount: groupItems.length,
+        totalSalesCount: totalGroupSales,
+        totalRevenue: round(totalRevenue, 2),
+        totalCost: round(totalCost, 2),
+        totalProfit: round(totalProfit, 2),
+        avgContributionMargin,
+        salesMixPct: overallTotalSalesCount > 0
+          ? round((totalGroupSales / overallTotalSalesCount) * 100, 2)
+          : 0,
+        revenueMixPct: overallTotalRevenue > 0
+          ? round((totalRevenue / overallTotalRevenue) * 100, 2)
+          : 0,
+        profitMixPct: overallTotalProfit > 0
+          ? round((totalProfit / overallTotalProfit) * 100, 2)
+          : 0,
+        items: classifiedItems
+      });
+    }
+
+    // Sort categories by revenue descending
+    categories.sort((a, b) => b.totalRevenue - a.totalRevenue);
+
+    // Compute overall summary using all items classified globally
+    const allMargins = items.map(i => i.sellingPrice - i.plateCost);
+    const allMixPcts = items.map(i =>
+      overallTotalSalesCount > 0 ? (i.salesCount / overallTotalSalesCount) * 100 : 0
+    );
+    const overallAvgMargin = allMargins.reduce((sum, m) => sum + m, 0) / allMargins.length;
+    const overallAvgMix = allMixPcts.reduce((sum, m) => sum + m, 0) / allMixPcts.length;
+    const { classifiedItems: allClassified } = computeClassifiedItems(
+      items, overallAvgMix, overallAvgMargin
+    );
+    const summary = computeSummary(allClassified);
+
+    const executionTimeMs = round((performance.now() - startTime) * 100, 0) / 100;
+
+    return {
+      categories,
+      summary,
+      executionTimeMs
+    };
+  }
+}
+
+/** Singleton instance */
+export const menuEngineeringStrategy = new MenuEngineeringExecutor();

package/src/engines/menu-engineering/types.ts

@@ -0,0 +1,242 @@
+/**
+ * Menu Engineering Engine Types
+ *
+ * Classifies menu items into Stars/Plowhorses/Puzzles/Dogs based on
+ * sales mix percentage and contribution margin. Supports price optimization
+ * with elasticity modeling and category-level mix analysis.
+ */
+
+// ========================================
+// Semantic Types
+// ========================================
+
+/** Menu engineering strategy to use */
+export const MenuEngineeringStrategies = {
+  classify: 'classify',
+  priceOptimization: 'price-optimization',
+  mixAnalysis: 'mix-analysis',
+} as const;
+export type MenuEngineeringStrategy = typeof MenuEngineeringStrategies[keyof typeof MenuEngineeringStrategies];
+
+/** Menu item classification quadrant */
+export const MenuClassifications = {
+  star: 'star',
+  plowhorse: 'plowhorse',
+  puzzle: 'puzzle',
+  dog: 'dog',
+} as const;
+export type MenuClassification = typeof MenuClassifications[keyof typeof MenuClassifications];
+
+// ========================================
+// Core Domain Types
+// ========================================
+
+/** A menu item with sales and cost data */
+export type MenuItem = {
+  id: string;
+  name: string;
+  category?: string;
+  sellingPrice: number;
+  plateCost: number;
+  salesCount: number;
+};
+
+/** Price elasticity for an item or category */
+export type PriceElasticity = {
+  itemId?: string;
+  category?: string;
+  elasticity: number;
+};
+
+/** A proposed price change for a menu item */
+export type PriceChange = {
+  itemId: string;
+  newPrice: number;
+};
+
+// ========================================
+// Config Types
+// ========================================
+
+/** Configuration for classify strategy */
+export type ClassifyConfig = {
+  mixThresholdMode?: 'average' | 'custom';
+  customMixThreshold?: number;
+  marginThresholdMode?: 'average' | 'custom';
+  customMarginThreshold?: number;
+};
+
+/** Configuration for price-optimization strategy */
+export type PriceOptimizationConfig = {
+  priceChanges: PriceChange[];
+  elasticities?: PriceElasticity[];
+  defaultElasticity?: number;
+};
+
+/** Configuration for mix-analysis strategy */
+export type MixAnalysisConfig = {
+  groupBy?: 'category' | 'daypart';
+  daypartField?: string;
+};
+
+// ========================================
+// Source RuleSet Types (Discriminated Union)
+// ========================================
+
+type MenuEngineeringRuleSetBase = {
+  id: string;
+  name?: string;
+  mode: 'menu-engineering';
+  items: MenuItem[];
+};
+
+/** Classify strategy: categorize items into quadrants */
+export type ClassifyRuleSet = MenuEngineeringRuleSetBase & {
+  strategy: 'classify';
+  config?: ClassifyConfig;
+};
+
+/** Price-optimization strategy: model price change impacts */
+export type PriceOptimizationRuleSet = MenuEngineeringRuleSetBase & {
+  strategy: 'price-optimization';
+  config: PriceOptimizationConfig;
+};
+
+/** Mix-analysis strategy: analyze category/daypart mix */
+export type MixAnalysisRuleSet = MenuEngineeringRuleSetBase & {
+  strategy: 'mix-analysis';
+  config?: MixAnalysisConfig;
+};
+
+export type MenuEngineeringRuleSet =
+  | ClassifyRuleSet
+  | PriceOptimizationRuleSet
+  | MixAnalysisRuleSet;
+
+// ========================================
+// Compiled RuleSet Types
+// ========================================
+
+type CompiledMenuEngineeringRuleSetBase = {
+  id: string;
+  name?: string;
+  mode: 'menu-engineering';
+  items: MenuItem[];
+};
+
+export type CompiledClassifyRuleSet = CompiledMenuEngineeringRuleSetBase & {
+  strategy: 'classify';
+  config: Required<ClassifyConfig>;
+};
+
+export type CompiledPriceOptimizationRuleSet = CompiledMenuEngineeringRuleSetBase & {
+  strategy: 'price-optimization';
+  config: {
+    priceChanges: PriceChange[];
+    elasticities: PriceElasticity[];
+    defaultElasticity: number;
+  };
+};
+
+export type CompiledMixAnalysisRuleSet = CompiledMenuEngineeringRuleSetBase & {
+  strategy: 'mix-analysis';
+  config: {
+    groupBy: 'category' | 'daypart';
+    daypartField: string;
+  };
+};
+
+export type CompiledMenuEngineeringRuleSet =
+  | CompiledClassifyRuleSet
+  | CompiledPriceOptimizationRuleSet
+  | CompiledMixAnalysisRuleSet;
+
+// ========================================
+// Result Types
+// ========================================
+
+/** A classified menu item with computed metrics */
+export type ClassifiedItem = {
+  id: string;
+  name: string;
+  category?: string;
+  sellingPrice: number;
+  plateCost: number;
+  salesCount: number;
+  contributionMargin: number;
+  foodCostPct: number;
+  salesMixPct: number;
+  classification: MenuClassification;
+  recommendation: string;
+};
+
+/** Summary statistics for the menu */
+export type MenuSummary = {
+  totalItems: number;
+  totalSalesCount: number;
+  totalRevenue: number;
+  totalCost: number;
+  totalProfit: number;
+  avgContributionMargin: number;
+  avgFoodCostPct: number;
+  avgSalesMixPct: number;
+  classificationCounts: Record<MenuClassification, number>;
+};
+
+/** A price-optimized menu item with projected impact */
+export type PriceOptimizationItem = {
+  id: string;
+  name: string;
+  originalPrice: number;
+  newPrice: number;
+  priceChangePct: number;
+  originalMargin: number;
+  newMargin: number;
+  estimatedNewSalesCount: number;
+  originalClassification: MenuClassification;
+  newClassification: MenuClassification;
+  projectedRevenueChange: number;
+  projectedProfitChange: number;
+};
+
+/** Category-level mix analysis result */
+export type CategoryMixResult = {
+  category: string;
+  itemCount: number;
+  totalSalesCount: number;
+  totalRevenue: number;
+  totalCost: number;
+  totalProfit: number;
+  avgContributionMargin: number;
+  salesMixPct: number;
+  revenueMixPct: number;
+  profitMixPct: number;
+  items: ClassifiedItem[];
+};
+
+/** Result from classify strategy */
+export type ClassifyResult = {
+  items: ClassifiedItem[];
+  summary: MenuSummary;
+  executionTimeMs: number;
+};
+
+/** Result from price-optimization strategy */
+export type PriceOptimizationResult = {
+  items: PriceOptimizationItem[];
+  summary: MenuSummary;
+  executionTimeMs: number;
+};
+
+/** Result from mix-analysis strategy */
+export type MixAnalysisResult = {
+  categories: CategoryMixResult[];
+  summary: MenuSummary;
+  executionTimeMs: number;
+};
+
+/** Union of all menu engineering results */
+export type MenuEngineeringResult = ClassifyResult | PriceOptimizationResult | MixAnalysisResult;
+
+/** Runtime options */
+export type MenuEngineeringOptions = Record<string, never>;

package/src/engines/monte-carlo/index.ts

@@ -9,6 +9,7 @@
 // Types
 export {
   // Estimate types
+  EstimateTypes,
   EstimateType,
   PercentOrNumber,
   // Variable types