@startsimpli/funnels 0.1.4 → 0.1.6

package/src/core/engine.ts

@@ -0,0 +1,329 @@
+/**
+ * @startsimpli/funnels - Core Funnel Execution Engine
+ *
+ * BRUTALLY GENERIC - Works for ANY entity type:
+ * - Investors, firms, contacts, organizations
+ * - Recipes, ingredients, users
+ * - Leads, tasks, projects
+ * - GitHub repos, pull requests, issues
+ *
+ * The engine processes entities through stages sequentially,
+ * evaluating rules and applying actions based on match results.
+ */
+
+import type {
+  Funnel,
+  FunnelStage,
+  FilterRule,
+  MatchAction,
+  NoMatchAction,
+  FunnelResult,
+  StageResult,
+  RuleResult,
+  StageStats,
+} from '../types';
+
+// ============================================================================
+// Execution Result Types
+// ============================================================================
+
+/**
+ * Complete result of funnel execution
+ */
+export interface ExecutionResult<T = any> {
+  /** Entities that matched and are in output */
+  matched: FunnelResult<T>[];
+
+  /** Entities that were excluded */
+  excluded: FunnelResult<T>[];
+
+  /** Total entities processed */
+  total_input: number;
+
+  /** Total entities that matched */
+  total_matched: number;
+
+  /** Total entities excluded */
+  total_excluded: number;
+
+  /** Total entities tagged */
+  total_tagged: number;
+
+  /** Per-stage statistics */
+  stage_stats: Record<string, StageStats>;
+
+  /** Execution duration in milliseconds */
+  duration_ms: number;
+
+  /** Errors encountered (non-fatal) */
+  errors?: string[];
+}
+
+// ============================================================================
+// BEAD: fund-your-startup-a0b8 - Funnel engine evaluateRule is a non-functional stub
+// evaluateRule always returns error='Evaluator not implemented yet' — funnels cannot match anything
+// resolveField should import from /packages/funnels/src/core/field-resolver.ts
+// ============================================================================
+
+function evaluateRule<T>(_entity: T, _rule: FilterRule): RuleResult {
+  throw new Error('Not implemented - BEAD: fund-your-startup-a0b8. evaluateRule must import from rule evaluator.');
+  // return {
+  //   field_path: _rule.field_path,
+  //   operator: _rule.operator,
+  //   value: _rule.value,
+  //   actual_value: undefined,
+  //   matched: false,
+  //   error: 'Evaluator not implemented yet',
+  // };
+}
+
+function resolveField<T>(_entity: T, _fieldPath: string): any {
+  throw new Error('Not implemented - BEAD: fund-your-startup-a0b8. resolveField must import from field-resolver.ts.');
+  // const keys = _fieldPath.split('.');
+  // let value: any = _entity;
+  // for (const key of keys) {
+  //   if (value === null || value === undefined) return undefined;
+  //   value = value[key];
+  // }
+  // return value;
+}
+
+// ============================================================================
+// Funnel Engine
+// ============================================================================
+
+/**
+ * Core funnel execution engine
+ *
+ * Processes entities through stages sequentially, evaluating rules
+ * and applying actions based on match results.
+ *
+ * Generic over entity type T - works with ANY data structure.
+ */
+export class FunnelEngine<T = any> {
+  /**
+   * Execute a funnel on a set of entities
+   *
+   * @param funnel - The funnel definition to execute
+   * @param entities - Input entities to process
+   * @returns ExecutionResult with matched/excluded entities and stats
+   */
+  execute(funnel: Funnel<T>, entities: T[]): ExecutionResult<T> {
+    const startTime = Date.now();
+
+    // Initialize results
+    const results: FunnelResult<T>[] = entities.map(entity => ({
+      entity,
+      matched: true, // Start as matched, exclude as needed
+      accumulated_tags: [],
+      context: {},
+      stage_results: [],
+    }));
+
+    const stageStats: Record<string, StageStats> = {};
+    const errors: string[] = [];
+
+    // Sort stages by order
+    const sortedStages = [...funnel.stages].sort((a, b) => a.order - b.order);
+
+    // Process each stage sequentially
+    for (const stage of sortedStages) {
+      const stageStartTime = Date.now();
+
+      // Track entities entering this stage
+      const inputEntities = results.filter(r => r.matched && !r.excluded_at_stage);
+
+      const stats: StageStats = {
+        stage_id: stage.id,
+        stage_name: stage.name,
+        input_count: inputEntities.length,
+        matched_count: 0,
+        not_matched_count: 0,
+        excluded_count: 0,
+        tagged_count: 0,
+        continued_count: 0,
+        error_count: 0,
+      };
+
+      // Process each entity through this stage
+      for (const result of inputEntities) {
+        try {
+          const stageResult = this.processStage(stage, result.entity);
+
+          // Update entity result
+          result.stage_results!.push(stageResult);
+
+          // Apply stage result to entity
+          if (stageResult.matched) {
+            stats.matched_count++;
+          } else {
+            stats.not_matched_count++;
+          }
+
+          if (stageResult.tags_added && stageResult.tags_added.length > 0) {
+            result.accumulated_tags.push(...stageResult.tags_added);
+            stats.tagged_count++;
+          }
+
+          if (stageResult.context_added) {
+            result.context = { ...result.context, ...stageResult.context_added };
+          }
+
+          if (stageResult.excluded) {
+            result.matched = false;
+            result.excluded_at_stage = stage.id;
+            stats.excluded_count++;
+          } else if (stageResult.continued) {
+            stats.continued_count++;
+          }
+        } catch (error) {
+          stats.error_count!++;
+          errors.push(`Stage ${stage.name}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+      }
+
+      stats.duration_ms = Date.now() - stageStartTime;
+      stageStats[stage.id] = stats;
+    }
+
+    // Apply completion tags to matched entities
+    if (funnel.completion_tags && funnel.completion_tags.length > 0) {
+      for (const result of results) {
+        if (result.matched) {
+          result.accumulated_tags.push(...funnel.completion_tags);
+        }
+      }
+    }
+
+    // Separate matched and excluded
+    const matched = results.filter(r => r.matched);
+    const excluded = results.filter(r => !r.matched);
+
+    // Count unique tagged entities
+    const totalTagged = results.filter(r => r.accumulated_tags.length > 0).length;
+
+    return {
+      matched,
+      excluded,
+      total_input: entities.length,
+      total_matched: matched.length,
+      total_excluded: excluded.length,
+      total_tagged: totalTagged,
+      stage_stats: stageStats,
+      duration_ms: Date.now() - startTime,
+      errors: errors.length > 0 ? errors : undefined,
+    };
+  }
+
+  /**
+   * Process a single entity through a stage
+   *
+   * @param stage - The stage to process
+   * @param entity - The entity to evaluate
+   * @returns StageResult with match status and actions taken
+   */
+  private processStage(stage: FunnelStage<T>, entity: T): StageResult {
+    // Evaluate all rules
+    const ruleResults: RuleResult[] = [];
+    let matched = false;
+
+    if (stage.custom_evaluator) {
+      // Use custom evaluator if provided (highest priority)
+      try {
+        matched = stage.custom_evaluator(entity);
+      } catch (error) {
+        matched = false;
+      }
+    } else if (stage.rules.length === 0) {
+      // No rules and no custom evaluator = always match
+      matched = true;
+    } else {
+      // Evaluate rules with filter logic
+      for (const rule of stage.rules) {
+        const ruleResult = evaluateRule(entity, rule);
+        ruleResults.push(ruleResult);
+      }
+
+      // Apply filter logic (AND/OR)
+      if (stage.filter_logic === 'AND') {
+        // All rules must match
+        matched = ruleResults.every(r => r.matched);
+      } else {
+        // At least one rule must match
+        matched = ruleResults.some(r => r.matched);
+      }
+    }
+
+    // Determine action based on match result
+    let action: MatchAction | NoMatchAction;
+    let tagsAdded: string[] = [];
+    let contextAdded: Record<string, any> | undefined;
+    let excluded = false;
+    let continued = false;
+
+    if (matched) {
+      action = stage.match_action;
+
+      // Add match tags
+      if (stage.match_tags && stage.match_tags.length > 0) {
+        tagsAdded = [...stage.match_tags];
+      }
+
+      // Add match context
+      if (stage.match_context) {
+        contextAdded = stage.match_context;
+      }
+
+      // Apply match action
+      switch (stage.match_action) {
+        case 'continue':
+          continued = true;
+          break;
+        case 'tag':
+          // Tags added, stop processing
+          excluded = true;
+          break;
+        case 'tag_continue':
+          // Tags added, continue processing
+          continued = true;
+          break;
+        case 'output':
+          // Add to output, stop processing (but not excluded)
+          continued = false;
+          break;
+      }
+    } else {
+      action = stage.no_match_action;
+
+      // Add no-match tags
+      if (stage.no_match_tags && stage.no_match_tags.length > 0) {
+        tagsAdded = [...stage.no_match_tags];
+      }
+
+      // Apply no-match action
+      switch (stage.no_match_action) {
+        case 'continue':
+          continued = true;
+          break;
+        case 'exclude':
+          excluded = true;
+          break;
+        case 'tag_exclude':
+          excluded = true;
+          break;
+      }
+    }
+
+    return {
+      stage_id: stage.id,
+      stage_name: stage.name,
+      matched,
+      rule_results: ruleResults.length > 0 ? ruleResults : undefined,
+      action,
+      tags_added: tagsAdded.length > 0 ? tagsAdded : undefined,
+      context_added: contextAdded,
+      excluded,
+      continued,
+    };
+  }
+}

package/src/core/evaluator.example.ts

@@ -0,0 +1,353 @@
+/**
+ * @startsimpli/funnels - Evaluator Usage Examples
+ *
+ * This file demonstrates how to use the rule evaluation engine
+ * with various entity types and operators.
+ */
+
+import {
+  evaluateRule,
+  evaluateRules,
+  evaluateRulesWithResults,
+  filterEntities,
+} from './evaluator';
+import type { FilterRule } from '../types';
+
+// ============================================================================
+// Example 1: Investor Qualification
+// ============================================================================
+
+interface Investor {
+  name: string;
+  email: string;
+  firm: {
+    name: string;
+    stage: string;
+    aum: number;
+    geography: string[];
+  };
+  tags: string[];
+  created_at: Date;
+}
+
+const investors: Investor[] = [
+  {
+    name: 'John Doe',
+    email: 'john@acme.vc',
+    firm: {
+      name: 'Acme Ventures',
+      stage: 'Series A',
+      aum: 100000000,
+      geography: ['US', 'Canada'],
+    },
+    tags: ['qualified', 'active'],
+    created_at: new Date('2024-01-15'),
+  },
+  {
+    name: 'Jane Smith',
+    email: 'jane@seed.fund',
+    firm: {
+      name: 'Seed Fund',
+      stage: 'Seed',
+      aum: 50000000,
+      geography: ['US'],
+    },
+    tags: ['active'],
+    created_at: new Date('2024-02-01'),
+  },
+  {
+    name: 'Bob Johnson',
+    email: 'bob@growth.capital',
+    firm: {
+      name: 'Growth Capital',
+      stage: 'Series B',
+      aum: 500000000,
+      geography: ['US', 'Europe', 'Asia'],
+    },
+    tags: ['qualified', 'premium'],
+    created_at: new Date('2024-01-20'),
+  },
+];
+
+// Example 1a: Single rule evaluation
+console.log('=== Example 1a: Single Rule ===');
+const rule1: FilterRule = {
+  field_path: 'firm.aum',
+  operator: 'gte',
+  value: 100000000,
+};
+
+investors.forEach(investor => {
+  const matches = evaluateRule(investor, rule1);
+  console.log(`${investor.name}: AUM >= $100M? ${matches}`);
+});
+
+// Example 1b: Multiple rules with AND logic
+console.log('\n=== Example 1b: Multiple Rules (AND) ===');
+const rules1: FilterRule[] = [
+  { field_path: 'firm.stage', operator: 'in', value: ['Series A', 'Series B'] },
+  { field_path: 'firm.aum', operator: 'gte', value: 100000000 },
+  { field_path: 'tags', operator: 'has_tag', value: 'qualified' },
+];
+
+const qualified = filterEntities(investors, rules1, 'AND');
+console.log('Qualified investors:', qualified.map(i => i.name));
+
+// Example 1c: Detailed results with diagnostics
+console.log('\n=== Example 1c: Detailed Results ===');
+const result1 = evaluateRulesWithResults(investors[0], rules1, 'AND');
+console.log('Evaluation for John Doe:');
+console.log('Overall match:', result1.matched);
+console.log('Rule results:');
+result1.rule_results.forEach(r => {
+  console.log(`  - ${r.field_path} ${r.operator} ${JSON.stringify(r.value)}`);
+  console.log(`    Actual: ${JSON.stringify(r.actual_value)}, Matched: ${r.matched}`);
+});
+
+// ============================================================================
+// Example 2: Recipe Filtering
+// ============================================================================
+
+interface Recipe {
+  name: string;
+  cuisine: string;
+  difficulty: 'easy' | 'medium' | 'hard';
+  prep_time_minutes: number;
+  ingredients: string[];
+  dietary: string[];
+  rating: number;
+}
+
+const recipes: Recipe[] = [
+  {
+    name: 'Pasta Carbonara',
+    cuisine: 'Italian',
+    difficulty: 'easy',
+    prep_time_minutes: 20,
+    ingredients: ['pasta', 'eggs', 'bacon', 'cheese'],
+    dietary: [],
+    rating: 4.5,
+  },
+  {
+    name: 'Vegan Buddha Bowl',
+    cuisine: 'Fusion',
+    difficulty: 'medium',
+    prep_time_minutes: 30,
+    ingredients: ['quinoa', 'chickpeas', 'avocado', 'vegetables'],
+    dietary: ['vegan', 'gluten-free'],
+    rating: 4.8,
+  },
+  {
+    name: 'Beef Wellington',
+    cuisine: 'British',
+    difficulty: 'hard',
+    prep_time_minutes: 120,
+    ingredients: ['beef', 'pastry', 'mushrooms', 'pate'],
+    dietary: [],
+    rating: 4.9,
+  },
+];
+
+// Example 2a: Filter by dietary restrictions
+console.log('\n=== Example 2: Recipe Filtering ===');
+const veganRules: FilterRule[] = [
+  { field_path: 'dietary', operator: 'has_tag', value: 'vegan' },
+];
+
+const veganRecipes = filterEntities(recipes, veganRules);
+console.log('Vegan recipes:', veganRecipes.map(r => r.name));
+
+// Example 2b: Filter by multiple criteria (quick meals)
+const quickMealRules: FilterRule[] = [
+  { field_path: 'prep_time_minutes', operator: 'lte', value: 30 },
+  { field_path: 'difficulty', operator: 'in', value: ['easy', 'medium'] },
+  { field_path: 'rating', operator: 'gte', value: 4.0 },
+];
+
+const quickMeals = filterEntities(recipes, quickMealRules, 'AND');
+console.log('Quick high-rated meals:', quickMeals.map(r => r.name));
+
+// ============================================================================
+// Example 3: GitHub Repository Filtering
+// ============================================================================
+
+interface GitHubRepo {
+  name: string;
+  owner: string;
+  stars: number;
+  forks: number;
+  language: string;
+  topics: string[];
+  has_issues: boolean;
+  is_archived: boolean;
+  last_updated: Date;
+}
+
+const repos: GitHubRepo[] = [
+  {
+    name: 'awesome-project',
+    owner: 'acme',
+    stars: 1500,
+    forks: 200,
+    language: 'TypeScript',
+    topics: ['frontend', 'react', 'nextjs'],
+    has_issues: true,
+    is_archived: false,
+    last_updated: new Date('2024-02-01'),
+  },
+  {
+    name: 'legacy-tool',
+    owner: 'acme',
+    stars: 50,
+    forks: 10,
+    language: 'JavaScript',
+    topics: ['legacy'],
+    has_issues: false,
+    is_archived: true,
+    last_updated: new Date('2020-01-01'),
+  },
+  {
+    name: 'python-ml-lib',
+    owner: 'datascience',
+    stars: 5000,
+    forks: 800,
+    language: 'Python',
+    topics: ['machine-learning', 'ai', 'data-science'],
+    has_issues: true,
+    is_archived: false,
+    last_updated: new Date('2024-02-10'),
+  },
+];
+
+// Example 3a: Find popular active repos
+console.log('\n=== Example 3: GitHub Repos ===');
+const popularRepoRules: FilterRule[] = [
+  { field_path: 'stars', operator: 'gte', value: 100 },
+  { field_path: 'is_archived', operator: 'is_false', value: null },
+  { field_path: 'last_updated', operator: 'gte', value: new Date('2024-01-01') },
+];
+
+const popularRepos = filterEntities(repos, popularRepoRules, 'AND');
+console.log('Popular active repos:', popularRepos.map(r => r.name));
+
+// Example 3b: Find TypeScript projects with React
+const tsReactRules: FilterRule[] = [
+  { field_path: 'language', operator: 'eq', value: 'TypeScript' },
+  { field_path: 'topics', operator: 'has_tag', value: 'react' },
+];
+
+const tsReactRepos = filterEntities(repos, tsReactRules, 'AND');
+console.log('TypeScript + React repos:', tsReactRepos.map(r => r.name));
+
+// ============================================================================
+// Example 4: Advanced Patterns
+// ============================================================================
+
+console.log('\n=== Example 4: Advanced Patterns ===');
+
+// Pattern 1: Negation
+const notArchivedRule: FilterRule = {
+  field_path: 'is_archived',
+  operator: 'is_true',
+  value: null,
+  negate: true, // Negate the result
+};
+
+const activeRepos = filterEntities(repos, [notArchivedRule]);
+console.log('Active repos (using negate):', activeRepos.map(r => r.name));
+
+// Pattern 2: Complex string matching
+const emailDomainRule: FilterRule = {
+  field_path: 'email',
+  operator: 'matches',
+  value: '@acme\\.vc$', // Matches emails ending with @acme.vc
+};
+
+const acmeInvestors = filterEntities(investors, [emailDomainRule]);
+console.log('Acme VC investors:', acmeInvestors.map(i => i.name));
+
+// Pattern 3: OR logic (match any condition)
+const flexibleStageRules: FilterRule[] = [
+  { field_path: 'firm.stage', operator: 'eq', value: 'Series A' },
+  { field_path: 'firm.aum', operator: 'gte', value: 500000000 }, // OR very large fund
+];
+
+const flexibleMatch = filterEntities(investors, flexibleStageRules, 'OR');
+console.log('Series A OR large fund:', flexibleMatch.map(i => i.name));
+
+// Pattern 4: Null handling
+const investorsWithoutEmail = investors.filter(i => !i.email);
+investorsWithoutEmail.push({
+  name: 'No Email User',
+  email: null as any,
+  firm: { name: 'Test', stage: 'Seed', aum: 0, geography: [] },
+  tags: [],
+  created_at: new Date(),
+});
+
+const hasEmailRule: FilterRule = {
+  field_path: 'email',
+  operator: 'isnotnull',
+  value: null,
+};
+
+const withEmail = filterEntities(investorsWithoutEmail, [hasEmailRule]);
+console.log('Investors with email:', withEmail.map(i => i.name));
+
+// Pattern 5: Array operations
+const multiGeographyRule: FilterRule = {
+  field_path: 'firm.geography',
+  operator: 'has_all',
+  value: ['US', 'Europe'],
+};
+
+const globalFunds = filterEntities(investors, [multiGeographyRule]);
+console.log('Global funds (US + Europe):', globalFunds.map(i => i.name));
+
+console.log('\n=== All Examples Complete ===');
+
+// ============================================================================
+// Example 5: Real-World Funnel Stage Simulation
+// ============================================================================
+
+console.log('\n=== Example 5: Funnel Stage Simulation ===');
+
+// Simulate a multi-stage funnel
+function simulateFunnel<T>(entities: T[], stages: Array<{ name: string; rules: FilterRule[]; logic: 'AND' | 'OR' }>) {
+  let remaining = entities;
+
+  stages.forEach((stage, index) => {
+    const before = remaining.length;
+    remaining = filterEntities(remaining, stage.rules, stage.logic);
+    const after = remaining.length;
+    console.log(`Stage ${index + 1} (${stage.name}): ${before} → ${after} (${before - after} excluded)`);
+  });
+
+  return remaining;
+}
+
+const investorFunnelStages = [
+  {
+    name: 'Active & Not Archived',
+    rules: [{ field_path: 'tags', operator: 'has_tag', value: 'active' } as FilterRule],
+    logic: 'AND' as const,
+  },
+  {
+    name: 'Series A+ Stage',
+    rules: [{ field_path: 'firm.stage', operator: 'in', value: ['Series A', 'Series B', 'Series C'] } as FilterRule],
+    logic: 'AND' as const,
+  },
+  {
+    name: 'Minimum AUM $100M',
+    rules: [{ field_path: 'firm.aum', operator: 'gte', value: 100000000 } as FilterRule],
+    logic: 'AND' as const,
+  },
+  {
+    name: 'Qualified Tag',
+    rules: [{ field_path: 'tags', operator: 'has_tag', value: 'qualified' } as FilterRule],
+    logic: 'AND' as const,
+  },
+];
+
+const finalInvestors = simulateFunnel(investors, investorFunnelStages);
+console.log('Final qualified investors:', finalInvestors.map(i => i.name));