@operor/copilot 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,282 @@
+import { KnowledgeBaseRuntime } from "@operor/core";
+
+//#region src/types.d.ts
+/**
+ * Training Copilot types
+ */
+/** Status of an unanswered query through the review lifecycle */
+type QueryStatus = 'pending' | 'taught' | 'dismissed';
+/** A customer query that the KB couldn't confidently answer */
+interface UnansweredQuery {
+  id: string;
+  query: string;
+  normalizedQuery: string;
+  channel: string;
+  customerPhone: string;
+  kbTopScore: number;
+  kbIsFaqMatch: boolean;
+  kbTopChunkContent?: string;
+  kbResultCount: number;
+  status: QueryStatus;
+  clusterId?: string;
+  timesAsked: number;
+  uniqueCustomers: string[];
+  embedding?: number[];
+  suggestedAnswer?: string;
+  taughtAnswer?: string;
+  createdAt: number;
+  updatedAt: number;
+}
+/** A cluster of semantically similar unanswered queries */
+interface QueryCluster {
+  id: string;
+  label?: string;
+  representativeQuery: string;
+  centroid?: number[];
+  queryCount: number;
+  uniqueCustomers: string[];
+  status: QueryStatus;
+  createdAt: number;
+  updatedAt: number;
+}
+/** Aggregate metrics for the copilot dashboard / digest */
+interface ImpactMetrics {
+  pendingCount: number;
+  taughtCount: number;
+  dismissedCount: number;
+  totalCustomersAffected: number;
+  totalTimesAsked: number;
+  topPendingQueries: UnansweredQuery[];
+}
+/** Configuration for the copilot subsystem */
+interface CopilotConfig {
+  enabled: boolean;
+  trackingThreshold: number;
+  clusterThreshold: number;
+  digestIntervalMs: number;
+  digestMaxItems: number;
+  autoSuggest: boolean;
+}
+/** Default copilot configuration values */
+declare const DEFAULT_COPILOT_CONFIG: CopilotConfig;
+/** Embedding service interface — decouples copilot from specific embedding providers */
+interface EmbeddingService {
+  embed(text: string): Promise<number[]>;
+  dimensions: number;
+}
+/** AI provider interface for suggestion generation */
+interface AIProviderLike {
+  generateText(options: {
+    model?: string;
+    system?: string;
+    prompt: string;
+    maxTokens?: number;
+    temperature?: number;
+  }): Promise<{
+    text: string;
+  }>;
+}
+/** Store interface for copilot persistence */
+interface CopilotStore {
+  initialize(): Promise<void>;
+  close(): Promise<void>;
+  addQuery(query: UnansweredQuery): Promise<void>;
+  getQuery(id: string): Promise<UnansweredQuery | null>;
+  updateQuery(id: string, updates: Partial<UnansweredQuery>): Promise<void>;
+  getPendingQueries(limit?: number): Promise<UnansweredQuery[]>;
+  findSimilarQuery(normalizedQuery: string): Promise<UnansweredQuery | null>;
+  getQueriesByCluster(clusterId: string): Promise<UnansweredQuery[]>;
+  addCluster(cluster: QueryCluster): Promise<void>;
+  getCluster(id: string): Promise<QueryCluster | null>;
+  updateCluster(id: string, updates: Partial<QueryCluster>): Promise<void>;
+  getOpenClusters(): Promise<QueryCluster[]>;
+  getImpactMetrics(topN?: number): Promise<ImpactMetrics>;
+  getLastDigestTime(): Promise<number>;
+  setLastDigestTime(time: number): Promise<void>;
+}
+/** Event emitted after a message is processed by the agent pipeline */
+interface MessageProcessedEvent {
+  query: string;
+  channel: string;
+  customerPhone: string;
+  response: {
+    text: string;
+    metadata?: {
+      kbTopScore?: number;
+      kbIsFaqMatch?: boolean;
+      kbTopChunkContent?: string;
+      kbResultCount?: number;
+    };
+  };
+}
+//#endregion
+//#region src/SQLiteCopilotStore.d.ts
+/**
+ * SQLite-backed copilot store with sqlite-vec for vector search on cluster centroids.
+ */
+declare class SQLiteCopilotStore implements CopilotStore {
+  private dbPath;
+  private dimensions;
+  private db;
+  constructor(dbPath: string, dimensions: number);
+  initialize(): Promise<void>;
+  close(): Promise<void>;
+  addQuery(query: UnansweredQuery): Promise<void>;
+  getQuery(id: string): Promise<UnansweredQuery | null>;
+  updateQuery(id: string, updates: Partial<UnansweredQuery>): Promise<void>;
+  getPendingQueries(limit?: number): Promise<UnansweredQuery[]>;
+  findSimilarQuery(normalizedQuery: string): Promise<UnansweredQuery | null>;
+  getQueriesByCluster(clusterId: string): Promise<UnansweredQuery[]>;
+  addCluster(cluster: QueryCluster): Promise<void>;
+  getCluster(id: string): Promise<QueryCluster | null>;
+  updateCluster(id: string, updates: Partial<QueryCluster>): Promise<void>;
+  getOpenClusters(): Promise<QueryCluster[]>;
+  /** Vector search cluster centroids — returns closest clusters by cosine distance */
+  searchClusters(embedding: number[], limit: number): Promise<Array<{
+    clusterId: string;
+    distance: number;
+  }>>;
+  getImpactMetrics(topN?: number): Promise<ImpactMetrics>;
+  getLastDigestTime(): Promise<number>;
+  setLastDigestTime(time: number): Promise<void>;
+  private rowToQuery;
+  private rowToCluster;
+}
+//#endregion
+//#region src/InMemoryCopilotStore.d.ts
+/**
+ * In-memory copilot store for testing and development.
+ */
+declare class InMemoryCopilotStore implements CopilotStore {
+  private queries;
+  private clusters;
+  private lastDigestTime;
+  initialize(): Promise<void>;
+  close(): Promise<void>;
+  addQuery(query: UnansweredQuery): Promise<void>;
+  getQuery(id: string): Promise<UnansweredQuery | null>;
+  updateQuery(id: string, updates: Partial<UnansweredQuery>): Promise<void>;
+  getPendingQueries(limit?: number): Promise<UnansweredQuery[]>;
+  findSimilarQuery(normalizedQuery: string): Promise<UnansweredQuery | null>;
+  getQueriesByCluster(clusterId: string): Promise<UnansweredQuery[]>;
+  addCluster(cluster: QueryCluster): Promise<void>;
+  getCluster(id: string): Promise<QueryCluster | null>;
+  updateCluster(id: string, updates: Partial<QueryCluster>): Promise<void>;
+  getOpenClusters(): Promise<QueryCluster[]>;
+  getImpactMetrics(topN?: number): Promise<ImpactMetrics>;
+  getLastDigestTime(): Promise<number>;
+  setLastDigestTime(time: number): Promise<void>;
+}
+//#endregion
+//#region src/QueryClusterer.d.ts
+/**
+ * Groups semantically similar unanswered queries into clusters.
+ */
+declare class QueryClusterer {
+  private store;
+  private embedder;
+  private config;
+  constructor(store: CopilotStore, embedder: EmbeddingService, config?: {
+    clusterThreshold: number;
+  });
+  /**
+   * Assign a query to an existing cluster or create a new one.
+   * Returns the cluster ID.
+   */
+  assignCluster(queryId: string, queryText: string, embedding: number[]): Promise<string>;
+  /** Cosine similarity between two vectors */
+  cosineSimilarity(a: number[], b: number[]): number;
+  /** Compute running average centroid */
+  updateCentroid(current: number[], newVec: number[], count: number): number[];
+}
+//#endregion
+//#region src/UnansweredQueryTracker.d.ts
+/**
+ * Tracks unanswered queries by listening to message:processed events.
+ * Runs non-blocking — errors are caught and logged, never thrown.
+ */
+declare class UnansweredQueryTracker {
+  private store;
+  private config;
+  private embedder;
+  private clusterer?;
+  constructor(store: CopilotStore, config: {
+    enabled: boolean;
+    trackingThreshold: number;
+  }, embedder: EmbeddingService, clusterer?: QueryClusterer | undefined);
+  /**
+   * Called after each message is processed. Decides whether to track the query.
+   * Non-blocking: catches all errors internally.
+   */
+  maybeTrack(event: MessageProcessedEvent): Promise<void>;
+  /** Normalize query text for deduplication */
+  normalizeQuery(text: string): string;
+}
+//#endregion
+//#region src/SuggestionEngine.d.ts
+/**
+ * Generates suggested answers for unanswered queries using the LLM + KB context.
+ */
+declare class SuggestionEngine {
+  private aiProvider;
+  private kb;
+  constructor(aiProvider: AIProviderLike, kb: KnowledgeBaseRuntime);
+  /**
+   * Generate a suggested answer for a query, optionally including related queries from a cluster.
+   */
+  suggest(query: string, relatedQueries?: string[]): Promise<string>;
+}
+//#endregion
+//#region src/CopilotCommandHandler.d.ts
+/**
+ * Handles /review commands from admin users in training mode.
+ */
+declare class CopilotCommandHandler {
+  private store;
+  private suggestionEngine;
+  private kb;
+  private clusterer?;
+  /** Per-admin session state: tracks which query they're currently reviewing */
+  private sessions;
+  constructor(store: CopilotStore, suggestionEngine: SuggestionEngine | undefined, kb: KnowledgeBaseRuntime, clusterer?: QueryClusterer | undefined);
+  /**
+   * Handle a /review subcommand.
+   * @param command The full command (always '/review')
+   * @param args Subcommand + arguments (e.g. 'accept This is the answer')
+   * @param adminPhone The admin's phone number
+   * @param reply Function to send a reply back to the admin
+   */
+  handleCommand(command: string, args: string, adminPhone: string, reply: (text: string) => Promise<void>): Promise<void>;
+  private getSession;
+  private handleNext;
+  private handleAccept;
+  private handleEdit;
+  private handleSkip;
+  private handleStats;
+  private handleCluster;
+  private handleHelp;
+}
+//#endregion
+//#region src/DigestScheduler.d.ts
+/**
+ * Periodically sends digest summaries of unanswered queries to admin phones.
+ */
+declare class DigestScheduler {
+  private store;
+  private config;
+  private sendMessage;
+  private timer;
+  constructor(store: CopilotStore, config: {
+    digestIntervalMs: number;
+    digestMaxItems: number;
+  }, sendMessage: (phone: string, text: string) => Promise<void>);
+  /** Start the digest scheduler for the given admin phones */
+  start(adminPhones: string[]): void;
+  /** Stop the digest scheduler */
+  stop(): void;
+  /** Build the digest message text */
+  buildDigest(): Promise<string | null>;
+}
+//#endregion
+export { AIProviderLike, CopilotCommandHandler, CopilotConfig, CopilotStore, DEFAULT_COPILOT_CONFIG, DigestScheduler, EmbeddingService, ImpactMetrics, InMemoryCopilotStore, MessageProcessedEvent, QueryCluster, QueryClusterer, QueryStatus, SQLiteCopilotStore, SuggestionEngine, UnansweredQuery, UnansweredQueryTracker };
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/types.ts","../src/SQLiteCopilotStore.ts","../src/InMemoryCopilotStore.ts","../src/QueryClusterer.ts","../src/UnansweredQueryTracker.ts","../src/SuggestionEngine.ts","../src/CopilotCommandHandler.ts","../src/DigestScheduler.ts"],"mappings":"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"}