@operor/copilot 0.1.0

package/src/SQLiteCopilotStore.ts

@@ -0,0 +1,300 @@
+import Database from 'better-sqlite3';
+import * as sqliteVec from 'sqlite-vec';
+import type { CopilotStore, UnansweredQuery, QueryCluster, ImpactMetrics } from './types.js';
+
+/**
+ * SQLite-backed copilot store with sqlite-vec for vector search on cluster centroids.
+ */
+export class SQLiteCopilotStore implements CopilotStore {
+  private db: Database.Database;
+
+  constructor(
+    private dbPath: string,
+    private dimensions: number,
+  ) {
+    this.db = new Database(dbPath);
+    this.db.pragma('journal_mode = WAL');
+    this.db.pragma('foreign_keys = ON');
+    sqliteVec.load(this.db);
+  }
+
+  async initialize(): Promise<void> {
+    this.db.exec(`
+      CREATE TABLE IF NOT EXISTS copilot_queries (
+        id TEXT PRIMARY KEY,
+        query TEXT NOT NULL,
+        normalized_query TEXT NOT NULL,
+        channel TEXT NOT NULL,
+        customer_phone TEXT NOT NULL,
+        kb_top_score REAL NOT NULL DEFAULT 0,
+        kb_is_faq_match INTEGER NOT NULL DEFAULT 0,
+        kb_top_chunk_content TEXT,
+        kb_result_count INTEGER NOT NULL DEFAULT 0,
+        status TEXT NOT NULL DEFAULT 'pending',
+        cluster_id TEXT,
+        times_asked INTEGER NOT NULL DEFAULT 1,
+        unique_customers TEXT NOT NULL DEFAULT '[]',
+        embedding BLOB,
+        suggested_answer TEXT,
+        taught_answer TEXT,
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_copilot_queries_status ON copilot_queries(status);
+      CREATE INDEX IF NOT EXISTS idx_copilot_queries_normalized ON copilot_queries(normalized_query);
+      CREATE INDEX IF NOT EXISTS idx_copilot_queries_cluster ON copilot_queries(cluster_id);
+
+      CREATE TABLE IF NOT EXISTS copilot_clusters (
+        id TEXT PRIMARY KEY,
+        label TEXT,
+        representative_query TEXT NOT NULL,
+        centroid BLOB,
+        query_count INTEGER NOT NULL DEFAULT 1,
+        unique_customers TEXT NOT NULL DEFAULT '[]',
+        status TEXT NOT NULL DEFAULT 'pending',
+        created_at INTEGER NOT NULL,
+        updated_at INTEGER NOT NULL
+      );
+
+      CREATE INDEX IF NOT EXISTS idx_copilot_clusters_status ON copilot_clusters(status);
+
+      CREATE TABLE IF NOT EXISTS copilot_meta (
+        key TEXT PRIMARY KEY,
+        value TEXT NOT NULL
+      );
+    `);
+
+    // Virtual table for vector search on cluster centroids
+    this.db.exec(`
+      CREATE VIRTUAL TABLE IF NOT EXISTS vec_copilot_clusters USING vec0(
+        cluster_id TEXT PRIMARY KEY,
+        centroid float[${this.dimensions}]
+      );
+    `);
+  }
+
+  async close(): Promise<void> {
+    this.db.close();
+  }
+
+  // --- Queries ---
+
+  async addQuery(query: UnansweredQuery): Promise<void> {
+    this.db.prepare(`
+      INSERT OR REPLACE INTO copilot_queries
+        (id, query, normalized_query, channel, customer_phone, kb_top_score, kb_is_faq_match,
+         kb_top_chunk_content, kb_result_count, status, cluster_id, times_asked,
+         unique_customers, embedding, suggested_answer, taught_answer, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      query.id,
+      query.query,
+      query.normalizedQuery,
+      query.channel,
+      query.customerPhone,
+      query.kbTopScore,
+      query.kbIsFaqMatch ? 1 : 0,
+      query.kbTopChunkContent ?? null,
+      query.kbResultCount,
+      query.status,
+      query.clusterId ?? null,
+      query.timesAsked,
+      JSON.stringify(query.uniqueCustomers),
+      query.embedding ? Buffer.from(new Float32Array(query.embedding).buffer) : null,
+      query.suggestedAnswer ?? null,
+      query.taughtAnswer ?? null,
+      query.createdAt,
+      query.updatedAt,
+    );
+  }
+
+  async getQuery(id: string): Promise<UnansweredQuery | null> {
+    const row = this.db.prepare('SELECT * FROM copilot_queries WHERE id = ?').get(id) as any;
+    return row ? this.rowToQuery(row) : null;
+  }
+
+  async updateQuery(id: string, updates: Partial<UnansweredQuery>): Promise<void> {
+    const existing = await this.getQuery(id);
+    if (!existing) return;
+
+    const merged = { ...existing, ...updates, updatedAt: Date.now() };
+    await this.addQuery(merged);
+  }
+
+  async getPendingQueries(limit?: number): Promise<UnansweredQuery[]> {
+    const sql = limit
+      ? 'SELECT * FROM copilot_queries WHERE status = ? ORDER BY times_asked DESC LIMIT ?'
+      : 'SELECT * FROM copilot_queries WHERE status = ? ORDER BY times_asked DESC';
+    const rows = limit
+      ? (this.db.prepare(sql).all('pending', limit) as any[])
+      : (this.db.prepare(sql).all('pending') as any[]);
+    return rows.map(r => this.rowToQuery(r));
+  }
+
+  async findSimilarQuery(normalizedQuery: string): Promise<UnansweredQuery | null> {
+    const row = this.db.prepare(
+      'SELECT * FROM copilot_queries WHERE normalized_query = ? AND status = ? LIMIT 1'
+    ).get(normalizedQuery, 'pending') as any;
+    return row ? this.rowToQuery(row) : null;
+  }
+
+  async getQueriesByCluster(clusterId: string): Promise<UnansweredQuery[]> {
+    const rows = this.db.prepare(
+      'SELECT * FROM copilot_queries WHERE cluster_id = ? ORDER BY times_asked DESC'
+    ).all(clusterId) as any[];
+    return rows.map(r => this.rowToQuery(r));
+  }
+
+  // --- Clusters ---
+
+  async addCluster(cluster: QueryCluster): Promise<void> {
+    this.db.prepare(`
+      INSERT OR REPLACE INTO copilot_clusters
+        (id, label, representative_query, centroid, query_count, unique_customers, status, created_at, updated_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)
+    `).run(
+      cluster.id,
+      cluster.label ?? null,
+      cluster.representativeQuery,
+      cluster.centroid ? Buffer.from(new Float32Array(cluster.centroid).buffer) : null,
+      cluster.queryCount,
+      JSON.stringify(cluster.uniqueCustomers),
+      cluster.status,
+      cluster.createdAt,
+      cluster.updatedAt,
+    );
+
+    // Upsert into vector table for similarity search
+    if (cluster.centroid) {
+      this.db.prepare('DELETE FROM vec_copilot_clusters WHERE cluster_id = ?').run(cluster.id);
+      this.db.prepare(
+        'INSERT INTO vec_copilot_clusters (cluster_id, centroid) VALUES (?, ?)'
+      ).run(cluster.id, new Float32Array(cluster.centroid));
+    }
+  }
+
+  async getCluster(id: string): Promise<QueryCluster | null> {
+    const row = this.db.prepare('SELECT * FROM copilot_clusters WHERE id = ?').get(id) as any;
+    return row ? this.rowToCluster(row) : null;
+  }
+
+  async updateCluster(id: string, updates: Partial<QueryCluster>): Promise<void> {
+    const existing = await this.getCluster(id);
+    if (!existing) return;
+
+    const merged = { ...existing, ...updates, updatedAt: Date.now() };
+    await this.addCluster(merged);
+  }
+
+  async getOpenClusters(): Promise<QueryCluster[]> {
+    const rows = this.db.prepare(
+      'SELECT * FROM copilot_clusters WHERE status = ? ORDER BY query_count DESC'
+    ).all('pending') as any[];
+    return rows.map(r => this.rowToCluster(r));
+  }
+
+  /** Vector search cluster centroids — returns closest clusters by cosine distance */
+  async searchClusters(embedding: number[], limit: number): Promise<Array<{ clusterId: string; distance: number }>> {
+    const rows = this.db.prepare(`
+      SELECT cluster_id, distance
+      FROM vec_copilot_clusters
+      WHERE centroid MATCH ?
+      ORDER BY distance
+      LIMIT ?
+    `).all(new Float32Array(embedding), limit) as any[];
+
+    return rows.map(r => ({
+      clusterId: r.cluster_id as string,
+      distance: r.distance as number,
+    }));
+  }
+
+  // --- Metrics ---
+
+  async getImpactMetrics(topN = 10): Promise<ImpactMetrics> {
+    const counts = this.db.prepare(`
+      SELECT
+        SUM(CASE WHEN status = 'pending' THEN 1 ELSE 0 END) as pending_count,
+        SUM(CASE WHEN status = 'taught' THEN 1 ELSE 0 END) as taught_count,
+        SUM(CASE WHEN status = 'dismissed' THEN 1 ELSE 0 END) as dismissed_count,
+        SUM(times_asked) as total_times_asked
+      FROM copilot_queries
+    `).get() as any;
+
+    // Aggregate unique customers across all queries
+    const allCustomerRows = this.db.prepare(
+      'SELECT unique_customers FROM copilot_queries'
+    ).all() as any[];
+    const allCustomers = new Set<string>();
+    for (const row of allCustomerRows) {
+      const customers: string[] = JSON.parse(row.unique_customers);
+      customers.forEach(c => allCustomers.add(c));
+    }
+
+    const topPending = await this.getPendingQueries(topN);
+
+    return {
+      pendingCount: counts.pending_count ?? 0,
+      taughtCount: counts.taught_count ?? 0,
+      dismissedCount: counts.dismissed_count ?? 0,
+      totalCustomersAffected: allCustomers.size,
+      totalTimesAsked: counts.total_times_asked ?? 0,
+      topPendingQueries: topPending,
+    };
+  }
+
+  // --- Digest tracking ---
+
+  async getLastDigestTime(): Promise<number> {
+    const row = this.db.prepare(
+      "SELECT value FROM copilot_meta WHERE key = 'last_digest_time'"
+    ).get() as any;
+    return row ? parseInt(row.value, 10) : 0;
+  }
+
+  async setLastDigestTime(time: number): Promise<void> {
+    this.db.prepare(
+      "INSERT OR REPLACE INTO copilot_meta (key, value) VALUES ('last_digest_time', ?)"
+    ).run(String(time));
+  }
+
+  // --- Row mappers ---
+
+  private rowToQuery(row: any): UnansweredQuery {
+    return {
+      id: row.id,
+      query: row.query,
+      normalizedQuery: row.normalized_query,
+      channel: row.channel,
+      customerPhone: row.customer_phone,
+      kbTopScore: row.kb_top_score,
+      kbIsFaqMatch: !!row.kb_is_faq_match,
+      kbTopChunkContent: row.kb_top_chunk_content ?? undefined,
+      kbResultCount: row.kb_result_count,
+      status: row.status,
+      clusterId: row.cluster_id ?? undefined,
+      timesAsked: row.times_asked,
+      uniqueCustomers: JSON.parse(row.unique_customers),
+      embedding: row.embedding ? Array.from(new Float32Array(row.embedding.buffer ?? row.embedding)) : undefined,
+      suggestedAnswer: row.suggested_answer ?? undefined,
+      taughtAnswer: row.taught_answer ?? undefined,
+      createdAt: row.created_at,
+      updatedAt: row.updated_at,
+    };
+  }
+
+  private rowToCluster(row: any): QueryCluster {
+    return {
+      id: row.id,
+      label: row.label ?? undefined,
+      representativeQuery: row.representative_query,
+      centroid: row.centroid ? Array.from(new Float32Array(row.centroid.buffer ?? row.centroid)) : undefined,
+      queryCount: row.query_count,
+      uniqueCustomers: JSON.parse(row.unique_customers),
+      status: row.status,
+      createdAt: row.created_at,
+      updatedAt: row.updated_at,
+    };
+  }
+}

package/src/SuggestionEngine.ts

@@ -0,0 +1,44 @@
+import type { AIProviderLike } from './types.js';
+import type { KnowledgeBaseRuntime } from '@operor/core';
+
+const SYSTEM_PROMPT = `You are a helpful assistant that drafts FAQ answers for a knowledge base. Write concise, accurate answers based on the available context. If the context doesn't contain enough information, say so.`;
+
+/**
+ * Generates suggested answers for unanswered queries using the LLM + KB context.
+ */
+export class SuggestionEngine {
+  constructor(
+    private aiProvider: AIProviderLike,
+    private kb: KnowledgeBaseRuntime,
+  ) {}
+
+  /**
+   * Generate a suggested answer for a query, optionally including related queries from a cluster.
+   */
+  async suggest(query: string, relatedQueries?: string[]): Promise<string> {
+    const kbResult = await this.kb.retrieve(query);
+
+    let prompt = `Customer query: "${query}"\n`;
+
+    if (relatedQueries && relatedQueries.length > 0) {
+      prompt += `\nRelated queries from other customers:\n`;
+      for (const rq of relatedQueries) {
+        prompt += `- "${rq}"\n`;
+      }
+    }
+
+    if (kbResult.context) {
+      prompt += `\nKnowledge base context:\n${kbResult.context}\n`;
+    }
+
+    prompt += `\nPlease draft a concise, helpful FAQ answer for this query.`;
+
+    const result = await this.aiProvider.generateText({
+      system: SYSTEM_PROMPT,
+      prompt,
+      temperature: 0.3,
+    });
+
+    return result.text;
+  }
+}

package/src/UnansweredQueryTracker.ts

@@ -0,0 +1,83 @@
+import crypto from 'node:crypto';
+import type { CopilotStore, EmbeddingService, MessageProcessedEvent, UnansweredQuery } from './types.js';
+import type { QueryClusterer } from './QueryClusterer.js';
+
+/**
+ * Tracks unanswered queries by listening to message:processed events.
+ * Runs non-blocking — errors are caught and logged, never thrown.
+ */
+export class UnansweredQueryTracker {
+  constructor(
+    private store: CopilotStore,
+    private config: { enabled: boolean; trackingThreshold: number },
+    private embedder: EmbeddingService,
+    private clusterer?: QueryClusterer,
+  ) {}
+
+  /**
+   * Called after each message is processed. Decides whether to track the query.
+   * Non-blocking: catches all errors internally.
+   */
+  async maybeTrack(event: MessageProcessedEvent): Promise<void> {
+    try {
+      if (!this.config.enabled) return;
+
+      const kbTopScore = event.response.metadata?.kbTopScore ?? 0;
+      const kbResultCount = event.response.metadata?.kbResultCount ?? 0;
+
+      // If KB answered confidently, skip tracking
+      if (kbResultCount > 0 && kbTopScore >= this.config.trackingThreshold) return;
+
+      const normalizedQuery = this.normalizeQuery(event.query);
+
+      const existing = await this.store.findSimilarQuery(normalizedQuery);
+
+      if (existing) {
+        const uniqueCustomers = existing.uniqueCustomers.includes(event.customerPhone)
+          ? existing.uniqueCustomers
+          : [...existing.uniqueCustomers, event.customerPhone];
+
+        await this.store.updateQuery(existing.id, {
+          timesAsked: existing.timesAsked + 1,
+          uniqueCustomers,
+          updatedAt: Date.now(),
+        });
+      } else {
+        const embedding = await this.embedder.embed(normalizedQuery);
+        const now = Date.now();
+        const id = crypto.randomUUID();
+
+        const newQuery: UnansweredQuery = {
+          id,
+          query: event.query,
+          normalizedQuery,
+          channel: event.channel,
+          customerPhone: event.customerPhone,
+          kbTopScore,
+          kbIsFaqMatch: event.response.metadata?.kbIsFaqMatch ?? false,
+          kbTopChunkContent: event.response.metadata?.kbTopChunkContent,
+          kbResultCount,
+          status: 'pending',
+          timesAsked: 1,
+          uniqueCustomers: [event.customerPhone],
+          embedding,
+          createdAt: now,
+          updatedAt: now,
+        };
+
+        await this.store.addQuery(newQuery);
+
+        if (this.clusterer) {
+          await this.clusterer.assignCluster(id, normalizedQuery, embedding);
+        }
+      }
+    } catch (_err) {
+      // Silently swallow — tracking must never disrupt the pipeline
+    }
+  }
+
+  /** Normalize query text for deduplication */
+  normalizeQuery(text: string): string {
+    return text.toLowerCase().trim().replace(/\s+/g, ' ');
+  }
+}