kritmatta-lead-scorer 1.0.0

package/README.md

@@ -0,0 +1,46 @@
+# kritmatta-lead-scorer
+
+Single source of truth for lead qualification scoring. Consumed by both the Vega
+app (`hire-chat-next-app`) and the enrichment worker (`enrichment-worker`) so the
+scoring logic can never drift between them.
+
+## What's in it
+- `scorer.js` - weight-profile scorer with per-ICP `signal_overrides` (the app UI
+  and the worker score identically).
+- `decay.js` - intent-signal time decay.
+- `reasoningRewriter.js` - optional LLM rephrasing of the deterministic reasoning.
+  The AI call is **dependency-injected** so this package has no app/worker-specific
+  requires.
+
+## Install
+Public package on npmjs.com - no auth or `.npmrc` needed:
+
+```
+npm install kritmatta-lead-scorer
+```
+
+## Usage
+
+App (deterministic, no AI):
+```js
+const { scoreLeadFromEnrichment } = require('kritmatta-lead-scorer');
+const { score } = scoreLeadFromEnrichment(lead, icpCriteria);
+```
+
+Worker (with LLM-rewritten reasoning - inject callAI once at startup):
+```js
+const scorer = require('kritmatta-lead-scorer');
+const { callAI } = require('./utils/ai');
+scorer.setCallAI(callAI);            // enable reasoning rewriting
+await scorer.scoreLeadsMultiIcp(leads, job, supabase);
+```
+
+If `setCallAI` is never called, `scoreLeadsMultiIcp` still works and just returns
+the deterministic reasoning (that's the app's mode).
+
+## Publishing (maintainers)
+Public npm. Bump `version` in `package.json`, then:
+```
+npm login          # once, to npmjs.com
+npm publish        # public by default (unscoped name)
+```

package/decay.js

@@ -0,0 +1,112 @@
+/**
+ * Signal Decay Utility
+ *
+ * Applies exponential decay to intent signals based on their age.
+ * Each signal type has a different half-life reflecting how quickly
+ * the signal loses relevance for outreach timing.
+ *
+ * Freshness boost: signals < 48h old get a multiplier because
+ * reaching a prospect within 24-48h of a signal increases reply
+ * rates by up to 40% (Autobound/Gong data).
+ */
+
+const DECAY_HALF_LIVES = {
+  recent_funding: 60,       // days - funding rounds stay relevant longer
+  leadership_change: 45,    // days - new leaders settle in over weeks
+  urgent_hiring: 21,        // days - urgent roles fill fast
+  team_expansion: 45,       // days - expansion plans unfold over weeks
+  first_hire: 30,           // days - first hires happen quickly once decided
+};
+
+const DEFAULT_HALF_LIFE = 30;
+
+/**
+ * Per-signal freshness boost curves. Funding announcements specifically
+ * show a 4x reply-rate uplift within 48h (vs ~1.4x for other signals per
+ * generic urgency studies), so they get a steeper freshness curve. Other
+ * signal types keep the uniform 1.5x/1.25x pattern.
+ *
+ * Curve format: [{ maxAgeDays, multiplier }, ...] ordered ascending.
+ * First matching bucket wins; anything beyond returns 1.0.
+ */
+const FRESHNESS_CURVES = {
+  recent_funding: [
+    { maxAgeDays: 1, multiplier: 2.0 },    // within 24h = 2x
+    { maxAgeDays: 2, multiplier: 1.75 },   // 24-48h = 1.75x
+    { maxAgeDays: 3, multiplier: 1.5 },    // 48-72h = 1.5x still meaningful
+    { maxAgeDays: 7, multiplier: 1.25 },   // first week gets some boost
+  ],
+  leadership_change: [
+    { maxAgeDays: 1, multiplier: 1.75 },   // new leaders act fastest in first 90 days
+    { maxAgeDays: 2, multiplier: 1.4 },
+    { maxAgeDays: 7, multiplier: 1.15 },
+  ],
+  urgent_hiring: [
+    { maxAgeDays: 1, multiplier: 1.5 },
+    { maxAgeDays: 2, multiplier: 1.25 },
+  ],
+};
+
+const DEFAULT_FRESHNESS_CURVE = [
+  { maxAgeDays: 1, multiplier: 1.5 },
+  { maxAgeDays: 2, multiplier: 1.25 },
+];
+
+/**
+ * Get a freshness boost multiplier for very recent signals.
+ * Per-signal-type curve when defined, else the default curve.
+ *   recent_funding <24h: 2.0x (was 1.5x) - playbook: 4x reply rate within 48h
+ *   leadership_change <24h: 1.75x
+ *   other <24h: 1.5x
+ */
+function freshnessBoost(ageDays, signalType = null) {
+  const curve = (signalType && FRESHNESS_CURVES[signalType]) || DEFAULT_FRESHNESS_CURVE;
+  for (const band of curve) {
+    if (ageDays <= band.maxAgeDays) return band.multiplier;
+  }
+  return 1.0;
+}
+
+/**
+ * Apply exponential decay to a raw score based on signal age.
+ * Includes a freshness boost for signals < 48 hours old.
+ *
+ * Formula: decayed = rawScore * freshnessBoost * (0.5 ^ (ageDays / halfLife))
+ *
+ * @param {number} rawScore - The original signal score
+ * @param {string} signalType - One of the DECAY_HALF_LIVES keys
+ * @param {string|Date} signalDate - When the signal was observed
+ * @param {Date} [now] - Reference date (defaults to current time)
+ * @returns {number} Decayed score, floored at 0
+ */
+function decayScore(rawScore, signalType, signalDate, now = new Date()) {
+  if (!rawScore || rawScore <= 0) {
+    return 0;
+  }
+
+  const signalTime = signalDate instanceof Date ? signalDate : new Date(signalDate);
+  if (isNaN(signalTime.getTime())) {
+    // If the date is invalid, return the raw score unmodified
+    return rawScore;
+  }
+
+  const ageDays = (now.getTime() - signalTime.getTime()) / (1000 * 60 * 60 * 24);
+  if (ageDays <= 0) {
+    return Math.round(rawScore * freshnessBoost(0, signalType) * 100) / 100;
+  }
+
+  const halfLife = DECAY_HALF_LIVES[signalType] || DEFAULT_HALF_LIFE;
+  const boost = freshnessBoost(ageDays, signalType);
+  const decayed = rawScore * boost * Math.pow(0.5, ageDays / halfLife);
+
+  return Math.max(0, Math.round(decayed * 100) / 100);
+}
+
+module.exports = {
+  decayScore,
+  freshnessBoost,
+  DECAY_HALF_LIVES,
+  DEFAULT_HALF_LIFE,
+  FRESHNESS_CURVES,
+  DEFAULT_FRESHNESS_CURVE,
+};

package/index.js

@@ -0,0 +1,19 @@
+/**
+ * @duncanwilliam1976/lead-scorer
+ *
+ * Single source of truth for lead qualification scoring, shared by the Vega
+ * app (deterministic scoreLeadFromEnrichment) and the enrichment worker
+ * (scoreLeadsMultiIcp with LLM-rewritten reasoning).
+ *
+ * The AI used for reasoning rewriting is injected via setCallAI() - the worker
+ * calls it once at startup; the app leaves it unset and gets deterministic
+ * reasoning.
+ */
+
+const scorer = require('./scorer');
+const { setCallAI } = require('./reasoningRewriter');
+
+module.exports = {
+  ...scorer,
+  setCallAI,
+};

package/package.json

@@ -0,0 +1,23 @@
+{
+  "name": "kritmatta-lead-scorer",
+  "version": "1.0.0",
+  "description": "Lead qualification scorer - weight-profile scoring with per-ICP signal overrides. Single source of truth shared by the Vega app and the enrichment worker.",
+  "main": "index.js",
+  "files": [
+    "index.js",
+    "scorer.js",
+    "decay.js",
+    "reasoningRewriter.js"
+  ],
+  "scripts": {
+    "test": "node -e \"require('./index.js'); console.log('loads OK')\""
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/manjitjohal/lead-scorer.git"
+  },
+  "license": "UNLICENSED",
+  "engines": {
+    "node": ">=18"
+  }
+}

package/reasoningRewriter.js

@@ -0,0 +1,190 @@
+/**
+ * Reasoning Rewriter
+ *
+ * Takes the deterministic scoring breakdown produced by scorer.js and
+ * rewrites each clause in language that reflects the ICP's product, pain
+ * points, and fit signals. Score deltas are preserved exactly so totals
+ * stay consistent with the deterministic score.
+ *
+ * The AI call is dependency-injected via setCallAI() so this package has no
+ * app/worker-specific requires. Consumers that want LLM-rewritten reasoning
+ * (the enrichment worker) call setCallAI(callAI) once at startup. Consumers
+ * that only need deterministic scoring (the app) never inject one, and this
+ * function simply returns the deterministic reasoning unchanged.
+ */
+
+let _callAI = null;
+
+/**
+ * Inject the hybrid AI callAI(messages, options) function used for rewriting.
+ * If never called, rewriteReasoning() is a no-op that returns the deterministic
+ * reasoning (scoring still works, just without ICP-flavoured rephrasing).
+ */
+function setCallAI(fn) {
+  _callAI = typeof fn === 'function' ? fn : null;
+}
+
+const SYSTEM_PROMPT = `You rewrite lead-scoring reasoning to be specific to a chosen ICP (Ideal Customer Profile) instead of using generic SaaS-flavoured language.
+
+You will be given:
+- The ICP name and freeform context (product, pain points, fit signals, disqualifiers)
+- A summary of the lead's enrichment data
+- The deterministic scoring breakdown: a semicolon-separated list of "Reason (+N)" or "Reason (-N)" items
+
+Your job: rewrite each clause so it reads as ICP-specific. Reference the ICP's product or pain when it makes the line more meaningful. Drop nothing - every input clause must appear in the output.
+
+You may add at most ONE new clause if there is a strong fit signal in the enrichment that the deterministic scorer missed - use (+0) for it so totals do not change.
+
+Output rules:
+- Same format as input: "Reason (+N); Reason (-N); ..."
+- Each reason: short, plain English, ICP-flavoured.
+- Preserve every existing (+N) / (-N) value exactly. Never invent new score values.
+- Never add commentary, headers, markdown, or quoting.
+- Output ONLY the rewritten reasoning string.`;
+
+function buildIcpSummary(name, context) {
+  const c = context || {};
+  const lines = [`ICP name: ${name || 'unnamed'}`];
+  if (c.product_description) lines.push(`Product: ${c.product_description}`);
+  if (c.pain_solved) lines.push(`Pain solved: ${c.pain_solved}`);
+  if (c.great_fit_signals) lines.push(`Great fit signals: ${c.great_fit_signals}`);
+  if (c.bad_fit_signals) lines.push(`Bad fit signals: ${c.bad_fit_signals}`);
+  if (c.competitive_positioning) lines.push(`Positioning: ${c.competitive_positioning}`);
+  return lines.join('\n');
+}
+
+function summariseFunding(funding) {
+  if (!funding || typeof funding !== 'object') return null;
+  const bits = [];
+  const stage =
+    funding.latest_round_stage ||
+    funding.latest_stage ||
+    funding.last_round_type;
+  const date =
+    funding.latest_round_date ||
+    funding.last_round_date ||
+    funding.latest_date;
+  const total = funding.total_raised || funding.total_funding;
+  const count = funding.count || funding.rounds_count;
+  if (stage) bits.push(`latest stage ${stage}`);
+  if (date) bits.push(`on ${date}`);
+  if (total) bits.push(`total ${total}`);
+  if (count) bits.push(`${count} round${count > 1 ? 's' : ''}`);
+  return bits.length ? bits.join(', ') : null;
+}
+
+function buildLeadSummary(lead, signalsUsed) {
+  const enr = lead.enrichment_data || {};
+  const t0 = enr.tier0 || {};
+  const t2 = enr.tier2 || {};
+  const t4 = enr.tier4 || {};
+  const prospeo = enr.prospeo_enrich || {};
+  const pPerson = prospeo.person || {};
+  const pCo = prospeo.company || {};
+
+  const lines = [
+    `Person: ${lead.title || '(unknown title)'} at ${lead.company_name || '(unknown company)'}`,
+  ];
+  if (pPerson.headline) lines.push(`LinkedIn headline: ${pPerson.headline}`);
+  if (pPerson.last_job_change_detected_at) {
+    lines.push(`Last job change detected: ${pPerson.last_job_change_detected_at}`);
+  }
+  if (lead.industry || t0.industry || t2.industry) {
+    lines.push(`Industry: ${lead.industry || t0.industry || t2.industry}`);
+  }
+  const companyDesc = pCo.description_ai || pCo.description;
+  if (companyDesc) {
+    lines.push(`Company description: ${String(companyDesc).slice(0, 300)}`);
+  }
+  if (t2.business_model) lines.push(`Business model: ${t2.business_model}`);
+  if (t2.company_stage) lines.push(`Company stage: ${t2.company_stage}`);
+  const fundingSummary = summariseFunding(pCo.funding);
+  if (fundingSummary) lines.push(`Funding: ${fundingSummary}`);
+  const ap = pCo.job_postings;
+  if (ap?.active_count > 0) {
+    const titles =
+      Array.isArray(ap.active_titles) && ap.active_titles.length
+        ? ` (${ap.active_titles.slice(0, 5).join(', ')})`
+        : '';
+    lines.push(
+      `Active hiring: ${ap.active_count} role${ap.active_count > 1 ? 's' : ''}${titles}`
+    );
+  }
+  if (Array.isArray(t2.pain_indicators) && t2.pain_indicators.length) {
+    lines.push(`Pain indicators detected: ${t2.pain_indicators.join('; ')}`);
+  }
+  if (Array.isArray(t4.signals) && t4.signals.length) {
+    const types = t4.signals.map((s) => s.type).filter(Boolean);
+    if (types.length) lines.push(`Intent signals: ${types.join(', ')}`);
+  }
+  if (Array.isArray(signalsUsed) && signalsUsed.length) {
+    lines.push(`Signals scored: ${signalsUsed.join(', ')}`);
+  }
+  return lines.join('\n');
+}
+
+const SCORE_DELTA_REGEX = /\([+-]\d+(?:\.\d+)?\)/;
+
+/**
+ * Rewrite a deterministic reasoning string in ICP-specific language.
+ * Returns the original deterministic reasoning if no callAI is injected or on
+ * any failure - never throws.
+ */
+async function rewriteReasoning(args) {
+  const {
+    icpName,
+    icpContext,
+    lead,
+    deterministicReasoning,
+    signalsUsed,
+    options = {},
+  } = args;
+
+  // No AI injected (e.g. the app, which only needs deterministic scoring).
+  if (!_callAI) return deterministicReasoning;
+
+  if (
+    !icpContext ||
+    !deterministicReasoning ||
+    deterministicReasoning === 'No signals found'
+  ) {
+    return deterministicReasoning;
+  }
+
+  const userMsg = `${buildIcpSummary(icpName, icpContext)}
+
+Lead:
+${buildLeadSummary(lead, signalsUsed)}
+
+Deterministic reasoning:
+${deterministicReasoning}
+
+Rewrite the deterministic reasoning following the rules above.`;
+
+  try {
+    const result = await _callAI(
+      [
+        { role: 'system', content: SYSTEM_PROMPT },
+        { role: 'user', content: userMsg },
+      ],
+      {
+        context: 'summarization',
+        forceProvider: 'gemini',
+        maxTokens: 1024,
+        temperature: 0.3,
+        timeout: options.timeout || 35000,
+        thinkingConfig: { thinkingBudget: 0 },
+      }
+    );
+    const raw = (result?.content || '').trim();
+    const cleaned = raw.replace(/^```\w*\s*/, '').replace(/\s*```$/, '').trim();
+    if (!cleaned || !SCORE_DELTA_REGEX.test(cleaned)) {
+      return deterministicReasoning;
+    }
+    return cleaned;
+  } catch (err) {
+    return deterministicReasoning;
+  }
+}
+
+module.exports = { rewriteReasoning, setCallAI };