@conversionpros/aiva 1.0.0

package/router-v2/knowledge-base.js

@@ -0,0 +1,231 @@
+// ── Knowledge Base - Structured FAQ + BM25 Workspace Search ──
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { getStmts } = require('./db');
+
+const WORKSPACE = path.join(process.env.HOME || '/Users/brandonburgan', '.openclaw', 'workspace');
+
+function log(msg, data) {
+  const ts = new Date().toISOString();
+  if (data) console.log(`[${ts}] [KB] ${msg}`, JSON.stringify(data));
+  else console.log(`[${ts}] [KB] ${msg}`);
+}
+
+// ── BM25 Search Implementation ──
+
+function tokenize(text) {
+  return (text || '').toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, ' ')
+    .split(/\s+/)
+    .filter(t => t.length > 1);
+}
+
+function bm25Score(queryTokens, docTokens, avgDl, N, dfMap) {
+  const k1 = 1.5, b = 0.75;
+  const dl = docTokens.length;
+  const tf = {};
+  for (const t of docTokens) tf[t] = (tf[t] || 0) + 1;
+
+  let score = 0;
+  for (const qt of queryTokens) {
+    const termTf = tf[qt] || 0;
+    if (termTf === 0) continue;
+    const df = dfMap[qt] || 0;
+    const idf = Math.log((N - df + 0.5) / (df + 0.5) + 1);
+    const tfNorm = (termTf * (k1 + 1)) / (termTf + k1 * (1 - b + b * (dl / avgDl)));
+    score += idf * tfNorm;
+  }
+  return score;
+}
+
+/**
+ * Search FAQ entries for a query. Checks device-specific FAQ first, then global.
+ * @param {string} query - Search query
+ * @param {string|null} [deviceId] - Device ID for device-specific FAQ
+ * @param {number} [limit=5] - Max results
+ * @returns {Array<{question: string, answer: string, score: number}>}
+ */
+function searchFaq(query, deviceId = null, limit = 5) {
+  const stmts = getStmts();
+  const entries = deviceId
+    ? stmts.getFaqByDevice.all(deviceId)
+    : stmts.getAllFaq.all();
+
+  if (entries.length === 0) return [];
+
+  const queryTokens = tokenize(query);
+  if (queryTokens.length === 0) return [];
+
+  // Build document frequency map
+  const N = entries.length;
+  const dfMap = {};
+  const docTokensList = entries.map(e => {
+    const tokens = tokenize(`${e.question} ${e.answer} ${e.keywords || ''}`);
+    const tokenSet = new Set(tokens);
+    for (const qt of queryTokens) {
+      if (tokenSet.has(qt)) dfMap[qt] = (dfMap[qt] || 0) + 1;
+    }
+    return tokens;
+  });
+
+  const avgDl = docTokensList.reduce((s, t) => s + t.length, 0) / N;
+
+  const scored = entries.map((entry, i) => ({
+    ...entry,
+    score: bm25Score(queryTokens, docTokensList[i], avgDl, N, dfMap),
+  }));
+
+  scored.sort((a, b) => b.score - a.score);
+  return scored.filter(s => s.score > 0).slice(0, limit);
+}
+
+/**
+ * Search workspace files as a fallback when FAQ doesn't have answers.
+ * Searches MEMORY.md, SOPs, and other workspace files.
+ * @param {string} query
+ * @param {number} [limit=3]
+ * @returns {Array<{file: string, excerpt: string, score: number}>}
+ */
+function searchWorkspace(query, limit = 3) {
+  const queryTokens = tokenize(query);
+  if (queryTokens.length === 0) return [];
+
+  const filesToSearch = [];
+  const watchPaths = [
+    path.join(WORKSPACE, 'memory'),
+    path.join(WORKSPACE, 'MEMORY.md'),
+    path.join(WORKSPACE, 'TOOLS.md'),
+  ];
+
+  for (const p of watchPaths) {
+    try {
+      const stat = fs.statSync(p);
+      if (stat.isDirectory()) {
+        const files = fs.readdirSync(p).filter(f => f.endsWith('.md'));
+        for (const f of files) filesToSearch.push(path.join(p, f));
+      } else {
+        filesToSearch.push(p);
+      }
+    } catch { /* skip missing files */ }
+  }
+
+  const chunks = [];
+  for (const filePath of filesToSearch) {
+    try {
+      const content = fs.readFileSync(filePath, 'utf-8');
+      // Split into paragraphs
+      const paragraphs = content.split(/\n\n+/).filter(p => p.trim().length > 50);
+      for (const para of paragraphs) {
+        chunks.push({ file: path.basename(filePath), text: para.trim() });
+      }
+    } catch { /* skip unreadable files */ }
+  }
+
+  if (chunks.length === 0) return [];
+
+  const N = chunks.length;
+  const dfMap = {};
+  const docTokensList = chunks.map(c => {
+    const tokens = tokenize(c.text);
+    const tokenSet = new Set(tokens);
+    for (const qt of queryTokens) {
+      if (tokenSet.has(qt)) dfMap[qt] = (dfMap[qt] || 0) + 1;
+    }
+    return tokens;
+  });
+
+  const avgDl = docTokensList.reduce((s, t) => s + t.length, 0) / N;
+
+  const scored = chunks.map((chunk, i) => ({
+    file: chunk.file,
+    excerpt: chunk.text.substring(0, 300),
+    score: bm25Score(queryTokens, docTokensList[i], avgDl, N, dfMap),
+  }));
+
+  scored.sort((a, b) => b.score - a.score);
+  return scored.filter(s => s.score > 0).slice(0, limit);
+}
+
+/**
+ * Combined search - FAQ first, workspace as fallback.
+ * @param {string} query
+ * @param {string|null} [deviceId]
+ * @returns {Array}
+ */
+function search(query, deviceId = null) {
+  const faqResults = searchFaq(query, deviceId, 3);
+  if (faqResults.length > 0) return faqResults.map(r => ({ type: 'faq', question: r.question, answer: r.answer, score: r.score }));
+
+  const wsResults = searchWorkspace(query, 3);
+  return wsResults.map(r => ({ type: 'workspace', file: r.file, excerpt: r.excerpt, score: r.score }));
+}
+
+// ── CRUD for FAQ management API ──
+
+/**
+ * List all FAQ entries.
+ * @param {string|null} [deviceId]
+ * @returns {Array}
+ */
+function listFaq(deviceId = null) {
+  return deviceId ? getStmts().getFaqByDevice.all(deviceId) : getStmts().getAllFaq.all();
+}
+
+/**
+ * Create a FAQ entry.
+ * @param {Object} entry
+ * @returns {Object}
+ */
+function createFaq(entry) {
+  const stmts = getStmts();
+  const info = stmts.insertFaq.run(
+    entry.device_id || null,
+    entry.question,
+    entry.answer,
+    entry.category || 'general',
+    entry.keywords || '',
+  );
+  log('Created FAQ entry', { id: info.lastInsertRowid });
+  return stmts.getFaqById.get(info.lastInsertRowid);
+}
+
+/**
+ * Update a FAQ entry.
+ * @param {number} id
+ * @param {Object} updates
+ * @returns {Object|null}
+ */
+function updateFaq(id, updates) {
+  const stmts = getStmts();
+  const existing = stmts.getFaqById.get(id);
+  if (!existing) return null;
+  stmts.updateFaq.run(
+    updates.question ?? existing.question,
+    updates.answer ?? existing.answer,
+    updates.category ?? existing.category,
+    updates.keywords ?? existing.keywords,
+    updates.enabled ?? existing.enabled,
+    id,
+  );
+  return stmts.getFaqById.get(id);
+}
+
+/**
+ * Delete a FAQ entry.
+ * @param {number} id
+ */
+function deleteFaq(id) {
+  getStmts().deleteFaq.run(id);
+}
+
+module.exports = {
+  searchFaq,
+  searchWorkspace,
+  search,
+  listFaq,
+  createFaq,
+  updateFaq,
+  deleteFaq,
+};

package/router-v2/lead-qualifier.js

@@ -0,0 +1,152 @@
+// ── Lead Qualifier - Scoring + Pipeline Stage ────────────
+// Natural conversation-based qualification. Invisible to contacts,
+// visible to Brandon in the AIVA app.
+'use strict';
+
+const { getStmts } = require('./db');
+const { callAI } = require('./utils/ai');
+const { updateQualification } = require('./contact-manager');
+
+function log(msg, data) {
+  const ts = new Date().toISOString();
+  if (data) console.log(`[${ts}] [LEAD-QUAL] ${msg}`, JSON.stringify(data));
+  else console.log(`[${ts}] [LEAD-QUAL] ${msg}`);
+}
+
+// Pipeline stage thresholds
+const STAGE_THRESHOLDS = {
+  cold: { min: 0, max: 20 },
+  warm: { min: 21, max: 50 },
+  hot: { min: 51, max: 75 },
+  qualified: { min: 76, max: 100 },
+};
+
+/**
+ * Determine pipeline stage from score.
+ * @param {number} score - 0-100
+ * @returns {string} Pipeline stage
+ */
+function scoreToStage(score) {
+  if (score >= 76) return 'qualified';
+  if (score >= 51) return 'hot';
+  if (score >= 21) return 'warm';
+  return 'cold';
+}
+
+/**
+ * Run post-message qualification analysis.
+ * Analyzes the latest conversation to update qualification score.
+ * Only runs for lead and qualified-lead categories.
+ * @param {Object} contact - Contact record
+ * @param {Array} recentMessages - Recent messages (last 10-15)
+ * @returns {Promise<{score: number, stage: string, changed: boolean}>}
+ */
+async function analyzeQualification(contact, recentMessages) {
+  if (!['lead', 'qualified-lead'].includes(contact.category)) {
+    return { score: contact.qualification_score || 0, stage: contact.pipeline_stage || 'none', changed: false };
+  }
+
+  const currentScore = contact.qualification_score || 0;
+  const history = recentMessages.map(m => {
+    const role = m.sent_by === 'contact' ? 'Contact' : 'AIVA';
+    return `${role}: ${m.text}`;
+  }).join('\n');
+
+  const systemPrompt = `You are a lead qualification scorer. Analyze the conversation and return a qualification score (0-100) based on these signals:
+
+POSITIVE SIGNALS (add points):
+- Stated a specific need (+20): "I need a new website"
+- Mentioned timeline (+15): "We're launching in March"
+- Asked about pricing (+15): "What do you charge?"
+- Mentioned budget (+20): "Our budget is around $5k"
+- Business context shared (+10): "We're a dental practice"
+- Responded to follow-up (+10): engagement signal
+- Multiple conversations (+10): came back after initial chat
+
+NEGATIVE SIGNALS (subtract points):
+- Just browsing (-10): "Just looking around"
+- Competitor research (-20): "How do you compare to X?"
+- No clear need expressed (-5)
+- Short, disengaged responses (-5)
+
+Current score: ${currentScore}
+
+Respond with ONLY a JSON object:
+{"score": <0-100>, "reasoning": "<brief explanation>", "signals": ["<signal1>", "<signal2>"]}`;
+
+  const userMsg = `Contact: ${contact.name} (${contact.phone})\n\nConversation:\n${history}`;
+
+  try {
+    const result = await callAI(systemPrompt, userMsg, { maxTokens: 300, temperature: 0.3 });
+    if (!result) return { score: currentScore, stage: scoreToStage(currentScore), changed: false };
+
+    const jsonMatch = result.match(/\{[\s\S]*\}/);
+    if (!jsonMatch) return { score: currentScore, stage: scoreToStage(currentScore), changed: false };
+
+    const parsed = JSON.parse(jsonMatch[0]);
+    const newScore = Math.max(0, Math.min(100, parsed.score || 0));
+    const newStage = scoreToStage(newScore);
+    const changed = newScore !== currentScore;
+
+    if (changed) {
+      updateQualification(contact.phone, newScore, newStage);
+      log('Score updated', {
+        phone: contact.phone,
+        oldScore: currentScore,
+        newScore,
+        stage: newStage,
+        reasoning: parsed.reasoning,
+      });
+    }
+
+    return { score: newScore, stage: newStage, changed, reasoning: parsed.reasoning, signals: parsed.signals };
+  } catch (err) {
+    log('Analysis error', { phone: contact.phone, error: err.message });
+    return { score: currentScore, stage: scoreToStage(currentScore), changed: false };
+  }
+}
+
+/**
+ * Check if a lead should be escalated for personal outreach (score >= 76).
+ * @param {Object} contact
+ * @returns {boolean}
+ */
+function shouldEscalateForOutreach(contact) {
+  return (contact.qualification_score || 0) >= 76 && contact.pipeline_stage !== 'client';
+}
+
+/**
+ * Get follow-up behavior for a lead's pipeline stage.
+ * @param {string} stage
+ * @returns {{ template: string, urgency: string }}
+ */
+function getFollowUpBehavior(stage) {
+  const behaviors = {
+    cold: {
+      template: 'Hey! Just wanted to see if you had any questions about what we do.',
+      urgency: 'low',
+    },
+    warm: {
+      template: 'Hey {name}! You mentioned {need} - I had a thought about that. Got a sec?',
+      urgency: 'medium',
+    },
+    hot: {
+      template: 'Hi {name}, just following up on {need}. Brandon has some availability this week if you\'d like to hop on a quick call.',
+      urgency: 'high',
+    },
+    qualified: {
+      template: 'Hi {name}, wanted to follow up on our conversation. Brandon would love to connect - can I set up a quick call?',
+      urgency: 'high',
+    },
+  };
+
+  return behaviors[stage] || behaviors.cold;
+}
+
+module.exports = {
+  analyzeQualification,
+  scoreToStage,
+  shouldEscalateForOutreach,
+  getFollowUpBehavior,
+  STAGE_THRESHOLDS,
+};

package/router-v2/learning-loop.js

@@ -0,0 +1,202 @@
+// ── Learning Loop - Three-Tier Preference Cascade ────────
+// Router -> Main Agent -> User. Every resolved escalation becomes
+// a learned preference for future use.
+'use strict';
+
+const { getStmts, getDb } = require('./db');
+
+function log(msg, data) {
+  const ts = new Date().toISOString();
+  if (data) console.log(`[${ts}] [LEARNING] ${msg}`, JSON.stringify(data));
+  else console.log(`[${ts}] [LEARNING] ${msg}`);
+}
+
+/**
+ * Find matching preferences for a question/context.
+ * Returns per-contact preferences first, then global.
+ * @param {string} phone - Contact phone (for per-contact prefs)
+ * @param {string} questionText - The question/message to match
+ * @param {number} [limit=5] - Max preferences to return
+ * @returns {Array} Matching preferences sorted by relevance
+ */
+function findMatchingPreferences(phone, questionText, limit = 5) {
+  const stmts = getStmts();
+  // Get preferences scoped to this contact or global, with sufficient confidence
+  const prefs = stmts.getPreferencesByScope.all(phone, 'global', limit * 3);
+
+  if (prefs.length === 0) return [];
+
+  // Simple keyword-based relevance scoring
+  const queryTokens = tokenize(questionText);
+  if (queryTokens.length === 0) return prefs.slice(0, limit);
+
+  const scored = prefs.map(pref => {
+    const patternTokens = tokenize(pref.question_pattern);
+    const overlap = queryTokens.filter(t => patternTokens.includes(t)).length;
+    const score = overlap / Math.max(queryTokens.length, 1);
+    return { ...pref, relevanceScore: score };
+  });
+
+  scored.sort((a, b) => {
+    // Per-contact prefs first, then by relevance, then by confidence
+    if (a.scope === phone && b.scope !== phone) return -1;
+    if (b.scope === phone && a.scope !== phone) return 1;
+    if (b.relevanceScore !== a.relevanceScore) return b.relevanceScore - a.relevanceScore;
+    return b.confidence - a.confidence;
+  });
+
+  // Only return prefs with some relevance
+  return scored.filter(s => s.relevanceScore > 0.1).slice(0, limit);
+}
+
+/**
+ * Save a learned preference from an escalation resolution.
+ * @param {Object} pref
+ * @param {string} pref.scope - 'global' or phone number
+ * @param {string} pref.questionPattern - Normalized question pattern
+ * @param {string} pref.answer - The learned answer
+ * @param {string} pref.source - 'router', 'main_agent', or 'user'
+ * @param {number} [pref.confidence] - 0.0-1.0 (defaults based on source)
+ * @param {string} [pref.escalationId] - Which escalation triggered this
+ * @param {string} [pref.phone] - Contact whose question led to this
+ * @param {string} [pref.originalQuestion] - What the contact asked
+ * @returns {Object} Created preference
+ */
+function savePreference(pref) {
+  const stmts = getStmts();
+
+  // Confidence defaults by source
+  const defaultConfidence = { user: 1.0, main_agent: 0.9, router: 0.7 };
+  const confidence = pref.confidence ?? defaultConfidence[pref.source] ?? 0.7;
+
+  // Check for existing matching preference to update rather than duplicate
+  const db = getDb();
+  const existing = db.prepare(
+    "SELECT * FROM preferences WHERE scope = ? AND question_pattern = ?"
+  ).get(pref.scope || 'global', pref.questionPattern);
+
+  let prefId;
+  if (existing) {
+    stmts.updatePreference.run(pref.answer, pref.source, confidence, existing.id);
+    prefId = existing.id;
+    log('Updated existing preference', { id: prefId, pattern: pref.questionPattern });
+  } else {
+    const info = stmts.insertPreference.run(
+      pref.scope || 'global',
+      pref.questionPattern,
+      pref.answer,
+      pref.source,
+      confidence,
+    );
+    prefId = info.lastInsertRowid;
+    log('Created new preference', { id: prefId, pattern: pref.questionPattern, source: pref.source });
+  }
+
+  // Audit trail
+  if (pref.escalationId || pref.phone) {
+    stmts.insertPreferenceLog.run(
+      prefId,
+      pref.escalationId || null,
+      pref.phone || null,
+      pref.originalQuestion || null,
+      pref.source,
+    );
+  }
+
+  return { id: prefId, questionPattern: pref.questionPattern, confidence };
+}
+
+/**
+ * Bump the hit count on a preference (when it's used to answer a question).
+ * @param {number} prefId
+ */
+function recordPreferenceHit(prefId) {
+  getStmts().bumpPreferenceHit.run(prefId);
+}
+
+/**
+ * Run monthly confidence decay for non-user preferences.
+ * - main_agent: -0.05/month
+ * - router: -0.1/month
+ */
+function decayConfidence() {
+  const stmts = getStmts();
+  stmts.decayPreferences.run(0.05, 'main_agent');
+  stmts.decayPreferences.run(0.1, 'router');
+  log('Ran confidence decay');
+}
+
+/**
+ * Build a preferences prompt section for the Conversation Engine.
+ * @param {string} phone - Contact phone
+ * @param {string} messageText - Current message text
+ * @returns {string} Formatted preferences for prompt injection
+ */
+function buildPreferencesPrompt(phone, messageText) {
+  const matches = findMatchingPreferences(phone, messageText);
+  if (matches.length === 0) return '';
+
+  const lines = matches.map(p => {
+    const scopeLabel = p.scope === 'global' ? '' : ` (specific to this contact)`;
+    return `- "${p.question_pattern}" -> "${p.answer}"${scopeLabel}`;
+  });
+
+  return `[Learned Preferences - use these when relevant]\n${lines.join('\n')}`;
+}
+
+/**
+ * Get learning velocity metrics.
+ * @returns {Object} Metrics about learning progress
+ */
+function getMetrics() {
+  const db = getDb();
+  const totalPrefs = db.prepare('SELECT COUNT(*) as count FROM preferences').get().count;
+  const activePrefs = db.prepare('SELECT COUNT(*) as count FROM preferences WHERE confidence >= 0.5').get().count;
+  const bySource = db.prepare('SELECT source, COUNT(*) as count FROM preferences GROUP BY source').all();
+  const recentEscalations = db.prepare("SELECT COUNT(*) as count FROM escalations WHERE created_at >= datetime('now', '-7 days')").get().count;
+  const recentResolved = db.prepare("SELECT COUNT(*) as count FROM escalations WHERE status = 'responded' AND created_at >= datetime('now', '-7 days')").get().count;
+
+  return {
+    totalPreferences: totalPrefs,
+    activePreferences: activePrefs,
+    bySource: Object.fromEntries(bySource.map(r => [r.source, r.count])),
+    escalationsLast7Days: recentEscalations,
+    resolvedLast7Days: recentResolved,
+  };
+}
+
+/**
+ * List all preferences (for management API).
+ * @returns {Array}
+ */
+function listPreferences() {
+  return getStmts().getAllPreferences.all();
+}
+
+/**
+ * Delete a preference.
+ * @param {number} id
+ */
+function deletePreference(id) {
+  getStmts().deletePreference.run(id);
+}
+
+// ── Helper ──
+
+function tokenize(text) {
+  return (text || '').toLowerCase()
+    .replace(/[^a-z0-9\s-]/g, ' ')
+    .split(/\s+/)
+    .filter(t => t.length > 1);
+}
+
+module.exports = {
+  findMatchingPreferences,
+  savePreference,
+  recordPreferenceHit,
+  decayConfidence,
+  buildPreferencesPrompt,
+  getMetrics,
+  listPreferences,
+  deletePreference,
+};