page-analyzer 1.0.0

package/llm/analyzers/event-analyzer/event-analyzer.js

@@ -0,0 +1,546 @@
+import fs from 'fs';
+import path from 'path';
+import { fileURLToPath } from 'url';
+import { deriveEventTypeMetadata } from '../../utils/event-csv.js';
+import {
+  CSV_REPAIR_ATTEMPTS,
+  FULL_ANALYSIS_RETRY_ATTEMPTS,
+  MAX_CSV_REPAIR_INPUT_CHARS
+} from './event-analyzer-constants.js';
+import { EventAnalyzerResponse } from './event-analyzer-response.js';
+import { buildRunContextMetadata } from './event-analyzer-metadata.js';
+import {
+  buildEventAnalysisPrompt,
+  buildSpecialBlockPrompt,
+  buildCsvRepairPrompt as buildCsvRepairPromptTemplate
+} from './event-analyzer-prompt.js';
+import {
+  parseInputCsvRows as parseInputCsvRowsFromInput,
+  normalizeBlocks as normalizeBlocksFromInput,
+  serializeBlocksIndexCsv as serializeBlocksIndexCsvFromInput,
+  serializeBlockAnalysisCsv as serializeBlockAnalysisCsvFromInput,
+  serializeDomCsvRows as serializeDomCsvRowsFromInput
+} from './event-analyzer-input.js';
+import {
+  unwrapTextResponse as unwrapTextResponseFromBlocks,
+  defaultBlockNameForTag as defaultBlockNameForTagFromBlocks,
+  normalizePossibleEvents as normalizePossibleEventsFromBlocks,
+  parseSpecialBlockResponse as parseSpecialBlockResponseFromBlocks,
+  buildBlockContexts as buildBlockContextsFromBlocks,
+  buildLlmGroups as buildLlmGroupsFromBlocks,
+  buildBlockAnalysisArtifact as buildBlockAnalysisArtifactFromBlocks
+} from './event-analyzer-blocks.js';
+import {
+  buildDirectEvent as buildDirectEventFromEvents,
+  expandEventAttributes as expandEventAttributesFromEvents,
+  enforceAllowedEventType as enforceAllowedEventTypeFromEvents
+} from './event-analyzer-events.js';
+import { toCsvIdValue } from './event-analyzer-utils.js';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+class EventAnalyzer {
+  constructor(provider, config, runContext = {}) {
+    this.provider = provider;
+    this.config = config;
+    this.runContext = runContext && typeof runContext === 'object' ? runContext : {};
+    this.response = new EventAnalyzerResponse(config);
+
+    const eventTemplatePath = path.join(__dirname, '../prompts/event-analysis.txt');
+    this.eventAnalysisTemplate = fs.readFileSync(eventTemplatePath, 'utf-8');
+    const specialTemplatePath = path.join(__dirname, '../prompts/special-block-confirmation.txt');
+    this.specialBlockTemplate = fs.readFileSync(specialTemplatePath, 'utf-8');
+  }
+
+  parseInputCsvRows(csvData) {
+    return parseInputCsvRowsFromInput(csvData);
+  }
+
+  normalizeBlocks(blocks = []) {
+    return normalizeBlocksFromInput(blocks);
+  }
+
+  serializeBlocksIndexCsv(blocks = []) {
+    return serializeBlocksIndexCsvFromInput(blocks);
+  }
+
+  serializeBlockAnalysisCsv(blockContexts = []) {
+    return serializeBlockAnalysisCsvFromInput(blockContexts);
+  }
+
+  serializeDomCsvRows(rows = []) {
+    return serializeDomCsvRowsFromInput(rows);
+  }
+
+  unwrapTextResponse(response) {
+    return unwrapTextResponseFromBlocks(response);
+  }
+
+  defaultBlockNameForTag(tag) {
+    return defaultBlockNameForTagFromBlocks(tag);
+  }
+
+  normalizePossibleEvents(value) {
+    return normalizePossibleEventsFromBlocks(this.response, value);
+  }
+
+  parseSpecialBlockResponse(response, _blocks = []) {
+    return parseSpecialBlockResponseFromBlocks(this.response, response);
+  }
+
+  async runSpecialBlockConfirmation(blocks) {
+    const blocksIndexCsv = this.serializeBlocksIndexCsv(blocks);
+    const prompt = buildSpecialBlockPrompt({
+      template: this.specialBlockTemplate,
+      blocksIndexCsv
+    });
+    const attempts = FULL_ANALYSIS_RETRY_ATTEMPTS + 1;
+    let lastError = null;
+
+    for (let attempt = 1; attempt <= attempts; attempt += 1) {
+      try {
+        const startedAt = Date.now();
+        const response = await this.provider.analyze(prompt, {
+          parseJson: false,
+          metadata: buildRunContextMetadata(this.runContext, {
+            operation: 'special_block_confirmation',
+            attempt
+          })
+        });
+        const parsed = this.parseSpecialBlockResponse(response, blocks);
+        console.log(`[LLM] Special block confirmation completed in ${Date.now() - startedAt}ms`);
+        return parsed;
+      } catch (error) {
+        lastError = error;
+        if (attempt < attempts) {
+          console.warn(
+            `[LLM] Special block confirmation attempt ${attempt}/${attempts} failed: ${error.message}. Retrying...`
+          );
+        }
+      }
+    }
+
+    throw lastError || new Error('special block confirmation failed');
+  }
+
+  buildBlockContexts(blocks, csvRows, specialResult) {
+    return buildBlockContextsFromBlocks(blocks, csvRows, specialResult);
+  }
+
+  buildLlmGroups(blockContexts = []) {
+    return buildLlmGroupsFromBlocks(blockContexts);
+  }
+
+  buildDirectEvent(row, blockContext) {
+    return buildDirectEventFromEvents(row, blockContext);
+  }
+
+  expandEventAttributes(event, row, blockContext, options = {}) {
+    return expandEventAttributesFromEvents(event, row, blockContext, options);
+  }
+
+  enforceAllowedEventType(event, blockContext) {
+    return enforceAllowedEventTypeFromEvents(this.response, event, blockContext);
+  }
+
+  async analyzeLlmGroups(groups, siteSummary, rollingKnownEventTypes) {
+    const eventsByCsvId = new Map();
+    const parsedNewEventTypes = [];
+    const attributeKeys = this.response.getAttributeKeys();
+    const totalGroups = groups.length;
+
+    for (let index = 0; index < groups.length; index += 1) {
+      const group = groups[index];
+      const label = `${index + 1}/${totalGroups}`;
+      const groupBlocks = Array.isArray(group.blocks) ? group.blocks : [];
+      const groupRows = groupBlocks
+        .flatMap((block) => block.rows)
+        .sort((left, right) => left.order - right.order);
+      const expectedCsvIds = new Set(groupRows.map((row) => row.csv_id));
+      const blockContextByCsvId = new Map();
+      const rowByCsvId = new Map();
+      for (const block of groupBlocks) {
+        for (const row of block.rows) {
+          blockContextByCsvId.set(row.csv_id, block);
+          rowByCsvId.set(row.csv_id, row);
+        }
+      }
+
+      const prompt = buildEventAnalysisPrompt({
+        template: this.eventAnalysisTemplate,
+        siteSummary,
+        blockAnalysisCsv: this.serializeBlockAnalysisCsv(groupBlocks),
+        domCsv: this.serializeDomCsvRows(groupRows)
+      });
+      const parsed = await this.runPromptAnalysis(prompt, rollingKnownEventTypes, attributeKeys, {
+        label
+      });
+      const rows = Array.isArray(parsed?.events_by_node) ? parsed.events_by_node : [];
+      for (const event of rows) {
+        const csvId = toCsvIdValue(event?.csv_id);
+        if (!csvId || !expectedCsvIds.has(csvId)) {
+          continue;
+        }
+        const blockContext = blockContextByCsvId.get(csvId);
+        if (!blockContext) {
+          continue;
+        }
+        const normalizedEvent = this.enforceAllowedEventType(
+          {
+            ...event,
+            csv_id: csvId
+          },
+          blockContext
+        );
+        const expandedEvent = this.expandEventAttributes(
+          normalizedEvent,
+          rowByCsvId.get(csvId),
+          blockContext,
+          { includeBlockIdxs: false }
+        );
+        eventsByCsvId.set(csvId, expandedEvent);
+        const known = this.response.normalizeEventType(normalizedEvent.event_type);
+        if (known && !rollingKnownEventTypes.includes(known)) {
+          rollingKnownEventTypes.push(known);
+        }
+      }
+
+      const fallbackCsvIds = [];
+      for (const row of groupRows) {
+        if (eventsByCsvId.has(row.csv_id)) {
+          continue;
+        }
+        const blockContext = blockContextByCsvId.get(row.csv_id);
+        const fallbackEvent = this.buildDirectEvent(row, blockContext);
+        if (!fallbackEvent) {
+          continue;
+        }
+        fallbackCsvIds.push(row.csv_id);
+        eventsByCsvId.set(row.csv_id, fallbackEvent);
+      }
+      if (fallbackCsvIds.length > 0) {
+        const preview = fallbackCsvIds.slice(0, 12).join(',');
+        console.warn(
+          `[LLM] Group ${label} missing ${fallbackCsvIds.length} csv_id(s). ` +
+          `Applied block-allowed fallback for: ${preview}${fallbackCsvIds.length > 12 ? ',...' : ''}`
+        );
+      }
+
+      for (const item of Array.isArray(parsed?.new_event_types) ? parsed.new_event_types : []) {
+        parsedNewEventTypes.push(item);
+      }
+    }
+
+    return {
+      events: Array.from(eventsByCsvId.values()),
+      parsedNewEventTypes
+    };
+  }
+
+  buildBlockAnalysisArtifact(siteSummary, blockContexts = [], llmGroups = []) {
+    return buildBlockAnalysisArtifactFromBlocks(siteSummary, blockContexts, llmGroups);
+  }
+
+  buildSyntheticBlocksFromCsvRows(csvRows = []) {
+    const rows = Array.isArray(csvRows) ? csvRows : [];
+    const validBlockIdxs = Array.from(new Set(
+      rows
+        .map((row) => (Number.isInteger(row?.blockIdx) && row.blockIdx >= 0 ? row.blockIdx : null))
+        .filter((value) => value !== null)
+    )).sort((left, right) => left - right);
+
+    if (validBlockIdxs.length > 0) {
+      const blocks = validBlockIdxs.map((blockIdx, index) => {
+        const blockRows = rows.filter((row) => row.blockIdx === blockIdx);
+        const textPreview = blockRows
+          .map((row) => String(row?.text || '').trim())
+          .filter(Boolean)
+          .slice(0, 4)
+          .join(' | ')
+          .slice(0, 600);
+
+        return {
+          blockIdx,
+          branchPath: `fallback.${blockIdx}`,
+          depth: 0,
+          domOrder: index + 1,
+          tag: 'section',
+          fixed: false,
+          top: index * 120,
+          left: 0,
+          width: 1200,
+          height: 360,
+          textPreview,
+          childInteractiveCount: blockRows.length
+        };
+      });
+
+      return {
+        blocks: this.normalizeBlocks(blocks),
+        rows
+      };
+    }
+
+    const remappedRows = rows.map((row) => ({
+      ...row,
+      blockIdx: 0
+    }));
+
+    return {
+      blocks: this.normalizeBlocks([{
+        blockIdx: 0,
+        branchPath: 'fallback.0',
+        depth: 0,
+        domOrder: 1,
+        tag: 'section',
+        fixed: false,
+        top: 0,
+        left: 0,
+        width: 1200,
+        height: 360,
+        textPreview: 'Fallback synthetic block (snapshot missing)',
+        childInteractiveCount: remappedRows.length
+      }]),
+      rows: remappedRows
+    };
+  }
+
+  async analyzeEvents(csvData, _mdData, knownEventTypes = [], options = {}) {
+    const analyzeNodeEvents = !options?.analyzeNodeEvents;
+    const configuredKnownEventTypes = this.response.normalizeStringList(
+      this.config?.knownEventTypes,
+      { eventType: true }
+    );
+    const mergedKnownEventTypes = this.response.normalizeStringList(
+      [...configuredKnownEventTypes, ...(knownEventTypes || [])],
+      { eventType: true }
+    );
+    let csvRows = this.parseInputCsvRows(csvData);
+    if (csvRows.length === 0) {
+      return {
+        events_by_node: [],
+        event_types_summary: [],
+        new_event_types: [],
+        block_analysis: {
+          site_summary: '',
+          possible_event_types: [],
+          blocks: [],
+          stats: {
+            total_blocks: 0,
+            skipped_blocks: 0,
+            direct_blocks: 0,
+            llm_blocks: 0,
+            llm_group_count: 0,
+            llm_group_rows: 0
+          }
+        }
+      };
+    }
+
+    let blocks = this.normalizeBlocks(options?.blocks || []);
+    if (blocks.length === 0) {
+      const fallback = this.buildSyntheticBlocksFromCsvRows(csvRows);
+      blocks = fallback.blocks;
+      csvRows = fallback.rows;
+      console.warn(
+        '[LLM] Missing blocks snapshot for event analysis. ' +
+        'Using synthetic fallback blocks from CSV rows.'
+      );
+    }
+
+    const specialResult = await this.runSpecialBlockConfirmation(blocks);
+    const siteSummary = specialResult.siteSummary || `Page with ${blocks.length} visual blocks.`;
+    const blockContexts = this.buildBlockContexts(blocks, csvRows, specialResult);
+    if (!analyzeNodeEvents) {
+      return {
+        events_by_node: [],
+        event_types_summary: [],
+        new_event_types: [],
+        block_analysis: this.buildBlockAnalysisArtifact(siteSummary, blockContexts, [])
+      };
+    }
+
+    const blockContextByCsvId = new Map();
+    for (const blockContext of blockContexts) {
+      for (const row of blockContext.rows) {
+        blockContextByCsvId.set(row.csv_id, blockContext);
+      }
+    }
+
+    const eventsByCsvId = new Map();
+    for (const blockContext of blockContexts) {
+      if (blockContext.possibleEvents.length !== 1) {
+        continue;
+      }
+      for (const row of blockContext.rows) {
+        const event = this.buildDirectEvent(row, blockContext);
+        if (event) {
+          eventsByCsvId.set(event.csv_id, event);
+        }
+      }
+    }
+
+    const llmGroups = this.buildLlmGroups(blockContexts);
+    const rollingKnownEventTypes = [...mergedKnownEventTypes];
+    const llmResult = await this.analyzeLlmGroups(llmGroups, siteSummary, rollingKnownEventTypes);
+    for (const event of llmResult.events) {
+      eventsByCsvId.set(event.csv_id, event);
+    }
+
+    const orderedCsvIds = csvRows.map((row) => row.csv_id);
+    const events = orderedCsvIds
+      .filter((csvId) => eventsByCsvId.has(csvId))
+      .map((csvId) => eventsByCsvId.get(csvId))
+      .filter((event) => {
+        const blockContext = blockContextByCsvId.get(event.csv_id);
+        if (!blockContext) {
+          return false;
+        }
+        if (blockContext.possibleEvents.length === 0) {
+          return false;
+        }
+        return true;
+      });
+
+    const {
+      eventTypesSummary,
+      newEventTypes
+    } = deriveEventTypeMetadata(events, mergedKnownEventTypes);
+    const finalEventTypeSet = new Set(
+      events
+        .map((event) => this.response.normalizeEventType(event?.event_type))
+        .filter(Boolean)
+    );
+    const scopedParsedNewEventTypes = llmResult.parsedNewEventTypes.filter((item) => {
+      const normalized = this.response.normalizeEventType(item?.name);
+      return normalized && finalEventTypeSet.has(normalized);
+    });
+    const resolvedNewEventTypes = this.response.resolveNewEventTypes({
+      parsedNewEventTypes: scopedParsedNewEventTypes,
+      derivedNewEventTypes: newEventTypes,
+      knownEventTypes: mergedKnownEventTypes
+    });
+    const result = {
+      events_by_node: events,
+      event_types_summary: eventTypesSummary,
+      new_event_types: resolvedNewEventTypes,
+      block_analysis: this.buildBlockAnalysisArtifact(siteSummary, blockContexts, llmGroups)
+    };
+    this.response.logNewEventTypes(result);
+    return result;
+  }
+
+  async runPromptAnalysis(prompt, knownEventTypes, attributeKeys, options = {}) {
+    const label = String(options?.label || '').trim();
+    const labelPrefix = label ? ` [${label}]` : '';
+    const totalAnalysisAttempts = FULL_ANALYSIS_RETRY_ATTEMPTS + 1;
+    let lastError;
+
+    for (let analysisAttempt = 1; analysisAttempt <= totalAnalysisAttempts; analysisAttempt++) {
+      try {
+        const startTime = Date.now();
+        const response = await this.provider.analyze(prompt, {
+          parseJson: false,
+          metadata: buildRunContextMetadata(this.runContext, {
+            operation: 'analysis',
+            chunkLabel: label || null,
+            analysisAttempt
+          })
+        });
+
+        try {
+          const result = this.response.parseCsvResponse(response, knownEventTypes, {
+            logger: console
+          });
+          console.log(`[LLM] Event analysis completed${labelPrefix} in ${Date.now() - startTime}ms`);
+          return result;
+        } catch (parseError) {
+          const repaired = await this.tryRepairCsvResponse(
+            response,
+            knownEventTypes,
+            attributeKeys,
+            {
+              chunkLabel: label || null,
+              parseErrorMessage: parseError?.message
+            }
+          );
+          if (!repaired) {
+            throw parseError;
+          }
+          console.log(`[LLM] Event analysis CSV repaired${labelPrefix} in ${Date.now() - startTime}ms`);
+          return repaired;
+        }
+      } catch (error) {
+        lastError = error;
+        if (analysisAttempt < totalAnalysisAttempts) {
+          console.warn(
+            `[LLM] Event analysis attempt ${analysisAttempt}/${totalAnalysisAttempts} failed${labelPrefix}: ` +
+            `${error.message}. Retrying...`
+          );
+        }
+      }
+    }
+
+    console.error('[LLM] Event analysis error:', lastError?.message || 'unknown error');
+    throw lastError || new Error('Event analysis failed');
+  }
+
+  buildCsvRepairPrompt(rawResponse, knownEventTypes = [], attributeKeys = [], options = {}) {
+    return buildCsvRepairPromptTemplate({
+      rawResponse,
+      knownEventTypes,
+      attributeKeys,
+      parseErrorMessage: options?.parseErrorMessage
+    });
+  }
+
+  async tryRepairCsvResponse(response, knownEventTypes = [], attributeKeys = [], options = {}) {
+    const raw = String(response || '').trim();
+    if (!raw) {
+      return null;
+    }
+    const parseErrorMessage = String(options?.parseErrorMessage || '').trim();
+
+    const repairInput = raw.length > MAX_CSV_REPAIR_INPUT_CHARS
+      ? `${raw.slice(0, MAX_CSV_REPAIR_INPUT_CHARS)}\n...[truncated]`
+      : raw;
+
+    for (let attempt = 1; attempt <= CSV_REPAIR_ATTEMPTS; attempt++) {
+      try {
+        console.warn(
+          `[LLM][CSV] Invalid response format. Attempting repair (${attempt}/${CSV_REPAIR_ATTEMPTS})...`
+        );
+        const repairPrompt = this.buildCsvRepairPrompt(
+          repairInput,
+          knownEventTypes,
+          attributeKeys,
+          {
+            ...options,
+            parseErrorMessage
+          }
+        );
+        const repairedResponse = await this.provider.analyze(repairPrompt, {
+          parseJson: false,
+          metadata: buildRunContextMetadata(this.runContext, {
+            operation: 'repair',
+            chunkLabel: String(options?.chunkLabel || '').trim() || null,
+            repairAttempt: attempt
+          })
+        });
+        return this.response.parseCsvResponse(repairedResponse, knownEventTypes, {
+          logger: console
+        });
+      } catch (error) {
+        console.warn(`[LLM][CSV] Repair attempt ${attempt}/${CSV_REPAIR_ATTEMPTS} failed: ${error.message}`);
+        if (attempt >= CSV_REPAIR_ATTEMPTS) {
+          return null;
+        }
+      }
+    }
+
+    return null;
+  }
+}
+
+export { EventAnalyzer };

package/llm/analyzers/prompts/event-analysis.txt

@@ -0,0 +1,52 @@
+You are a revenue-focused analytics event designer.
+
+INPUTS
+
+1) site_summary
+<<<SITE_SUMMARY>>>
+
+2) block analysis CSV
+<<<BLOCK_ANALYSIS_CSV>>>
+
+3) DOM CSV
+<<<DOM_CSV>>>
+
+GOAL
+
+Detect commercially meaningful interactions from DOM elements.
+
+Map events 1:1 to DOM rows.
+
+Focus on actions valuable to website owners:
+signup, trial, demo, purchase, contact, subscribe, search, product interest, etc.
+
+Use site_summary, blockName, and blockSemantic (if present) as context.
+
+RULES
+
+- Output CSV only.
+- Each output row must reuse DOM csv_id.
+- Exactly one event_type per csv_id.
+- Try to cover every DOM event.
+
+Use concise snake_case names such as:
+signup, login, start_trial, purchase, subscribe, book_demo,
+contact_submit, search, view_product, view_article,
+add_to_cart, checkout_start, pricing_view, cta_click.
+
+Create a new business event if needed.
+
+ATTRIBUTES
+
+attributes_kv should include concise business context extracted from the DOM.
+
+Guidelines:
+- Format: key=value&key=value
+- No spaces
+- Prefer semantic information (plan, product, tier, category, intent, action target)
+- Do NOT include structural attributes that can be derived by engineering (e.g. block name, label text, URL)
+- Leave empty only if no meaningful attributes exist
+
+OUTPUT (plain CSV only)
+
+csv_id,event_type,attributes_kv