@contractspec/lib.support-bot 1.57.0 → 1.58.0

package/dist/node/index.js

@@ -0,0 +1,517 @@
+// src/bot/auto-responder.ts
+class AutoResponder {
+  llm;
+  model;
+  tone;
+  closing;
+  constructor(options) {
+    this.llm = options?.llm;
+    this.model = options?.model;
+    this.tone = options?.tone ?? "friendly";
+    this.closing = options?.closing ?? (this.tone === "friendly" ? "We remain available if you need anything else." : "Please let us know if you require additional assistance.");
+  }
+  async draft(ticket, resolution, classification) {
+    if (this.llm) {
+      return this.generateWithLLM(ticket, resolution, classification);
+    }
+    return this.generateTemplate(ticket, resolution, classification);
+  }
+  async generateWithLLM(ticket, resolution, classification) {
+    const prompt = `You are a ${this.tone} support agent. Draft an email response.
+Ticket Subject: ${ticket.subject}
+Ticket Body: ${ticket.body}
+Detected Category: ${classification.category}
+Detected Priority: ${classification.priority}
+Resolution:
+${resolution.answer}
+Citations: ${resolution.citations.map((c) => c.label).join(", ")}`;
+    const response = await this.llm.chat([
+      {
+        role: "system",
+        content: [
+          {
+            type: "text",
+            text: "Write empathetic, accurate support replies that cite sources when relevant."
+          }
+        ]
+      },
+      {
+        role: "user",
+        content: [{ type: "text", text: prompt }]
+      }
+    ], { model: this.model });
+    const body = response.message.content.map((part) => ("text" in part) ? part.text : "").join("").trim();
+    return this.buildDraft(ticket, resolution, classification, body);
+  }
+  generateTemplate(ticket, resolution, classification) {
+    const greeting = ticket.customerName ? `Hi ${ticket.customerName},` : "Hi there,";
+    const body = `${greeting}
+
+Thanks for contacting us about "${ticket.subject}". ${this.renderCategoryIntro(classification)}
+
+${resolution.answer}
+
+${this.renderCitations(resolution)}
+${this.closing}
+
+— ContractSpec Support`;
+    return this.buildDraft(ticket, resolution, classification, body);
+  }
+  buildDraft(ticket, resolution, classification, body) {
+    return {
+      ticketId: ticket.id,
+      subject: ticket.subject.startsWith("Re:") ? ticket.subject : `Re: ${ticket.subject}`,
+      body,
+      confidence: Math.min(resolution.confidence, classification.confidence),
+      requiresEscalation: resolution.actions.some((action) => action.type === "escalate") || Boolean(classification.escalationRequired),
+      citations: resolution.citations
+    };
+  }
+  renderCategoryIntro(classification) {
+    switch (classification.category) {
+      case "billing":
+        return "I understand billing issues can be stressful, so let me clarify the situation.";
+      case "technical":
+        return "I see you encountered a technical issue. Here is what happened and how to fix it.";
+      case "product":
+        return "Thanks for sharing feedback about the product. Here are the next steps.";
+      case "account":
+        return "Account access is critical, so let me walk you through the resolution.";
+      case "compliance":
+        return "Compliance questions require precision. See the policy-aligned answer below.";
+      default:
+        return "Here is what we found after reviewing your request.";
+    }
+  }
+  renderCitations(resolution) {
+    if (!resolution.citations.length)
+      return "";
+    const lines = resolution.citations.map((citation, index) => {
+      const label = citation.label || `Source ${index + 1}`;
+      const link = citation.url ? ` (${citation.url})` : "";
+      return `- ${label}${link}`;
+    });
+    return `References:
+${lines.join(`
+`)}`;
+  }
+}
+
+// src/bot/feedback-loop.ts
+class SupportFeedbackLoop {
+  history = [];
+  responseTimes = new Map;
+  recordResolution(payload, responseTimeMs) {
+    this.history.push(payload);
+    if (responseTimeMs != null) {
+      this.responseTimes.set(payload.ticket.id, responseTimeMs);
+    }
+  }
+  metrics() {
+    const total = this.history.length;
+    const autoResolved = this.history.filter((entry) => !entry.resolution.actions.some((action) => action.type === "escalate")).length;
+    const escalated = total - autoResolved;
+    const avgConfidence = total === 0 ? 0 : this.history.reduce((sum, entry) => sum + entry.resolution.confidence, 0) / total;
+    const avgResponseTimeMs = this.responseTimes.size === 0 ? 0 : [...this.responseTimes.values()].reduce((a, b) => a + b, 0) / this.responseTimes.size;
+    return {
+      totalTickets: total,
+      autoResolved,
+      escalated,
+      avgConfidence: Number(avgConfidence.toFixed(2)),
+      avgResponseTimeMs: Math.round(avgResponseTimeMs)
+    };
+  }
+  feedbackSummary(limit = 5) {
+    const recent = this.history.slice(-limit);
+    if (!recent.length)
+      return "No feedback recorded yet.";
+    return recent.map((entry) => {
+      const status = entry.resolution.actions.some((action) => action.type === "escalate") ? "Escalated" : "Auto-resolved";
+      return `${entry.ticket.subject} – ${status} (confidence: ${entry.resolution.confidence})`;
+    }).join(`
+`);
+  }
+}
+
+// src/bot/tools.ts
+import * as z from "zod";
+var ticketSchema = z.object({
+  id: z.string(),
+  subject: z.string(),
+  body: z.string(),
+  channel: z.enum(["email", "chat", "phone", "portal"]),
+  customerName: z.string().optional(),
+  customerEmail: z.string().optional(),
+  metadata: z.object().optional()
+});
+var supportCitationSchema = z.object({
+  label: z.string(),
+  url: z.string().optional(),
+  snippet: z.string().optional(),
+  score: z.number().optional()
+});
+var supportActionSchema = z.object({
+  type: z.enum(["respond", "escalate", "refund", "manual"]),
+  label: z.string(),
+  payload: z.record(z.string(), z.string())
+});
+var supportResolutionSchema = z.object({
+  ticketId: z.string(),
+  answer: z.string(),
+  confidence: z.number(),
+  citations: supportCitationSchema.array(),
+  actions: supportActionSchema.array(),
+  escalationReason: z.string().optional(),
+  knowledgeUpdates: z.array(z.string()).optional()
+});
+var ticketClassificationSchema = z.object({
+  ticketId: z.string(),
+  category: z.enum([
+    "billing",
+    "technical",
+    "product",
+    "account",
+    "compliance",
+    "other"
+  ]),
+  priority: z.enum([
+    "urgent",
+    "high",
+    "medium",
+    "low"
+  ]),
+  sentiment: z.enum([
+    "positive",
+    "neutral",
+    "negative",
+    "frustrated"
+  ]),
+  intents: z.array(z.string()),
+  tags: z.array(z.string()),
+  confidence: z.number(),
+  escalationRequired: z.boolean().optional()
+});
+function ensureTicket(input) {
+  if (!input || typeof input !== "object" || !("ticket" in input)) {
+    throw new Error("Input must include ticket");
+  }
+  const ticket = input.ticket;
+  if (!ticket?.id)
+    throw new Error("Ticket is missing id");
+  return ticket;
+}
+function extractResolution(input) {
+  if (!input || typeof input !== "object" || !("resolution" in input))
+    return;
+  return input.resolution;
+}
+function extractClassification(input) {
+  if (!input || typeof input !== "object" || !("classification" in input))
+    return;
+  return input.classification;
+}
+function createSupportTools(options) {
+  const classifyTool = {
+    title: "support_classify_ticket",
+    description: "Classify a ticket for priority, sentiment, and category",
+    inputSchema: z.object({ ticket: ticketSchema }),
+    execute: async (input) => {
+      const ticket = ensureTicket(input);
+      const classification = await options.classifier.classify(ticket);
+      return {
+        content: JSON.stringify(classification),
+        metadata: { ticketId: ticket.id }
+      };
+    }
+  };
+  const resolveTool = {
+    title: "support_resolve_ticket",
+    description: "Generate a knowledge-grounded resolution for a ticket",
+    inputSchema: z.object({ ticket: ticketSchema }),
+    execute: async (input) => {
+      const ticket = ensureTicket(input);
+      const resolution = await options.resolver.resolve(ticket);
+      return {
+        content: JSON.stringify(resolution),
+        metadata: { ticketId: ticket.id }
+      };
+    }
+  };
+  const responderTool = {
+    title: "support_draft_response",
+    description: "Draft a user-facing reply based on resolution + classification",
+    inputSchema: z.object({
+      ticket: ticketSchema,
+      resolution: supportResolutionSchema,
+      classification: ticketClassificationSchema
+    }),
+    execute: async (input) => {
+      const ticket = ensureTicket(input);
+      const resolution = extractResolution(input);
+      const classification = extractClassification(input);
+      if (!resolution || !classification) {
+        throw new Error("resolution and classification are required");
+      }
+      const draft = await options.responder.draft(ticket, resolution, classification);
+      return {
+        content: JSON.stringify(draft),
+        metadata: { ticketId: ticket.id }
+      };
+    }
+  };
+  return [classifyTool, resolveTool, responderTool];
+}
+// src/spec.ts
+import { defineAgent } from "@contractspec/lib.ai-agent";
+function defineSupportBot(definition) {
+  const base = defineAgent({
+    ...definition.base,
+    policy: {
+      ...definition.base.policy,
+      confidence: {
+        min: definition.base.policy?.confidence?.min ?? 0.7,
+        default: definition.base.policy?.confidence?.default ?? 0.6
+      },
+      escalation: {
+        confidenceThreshold: definition.autoEscalateThreshold ?? definition.base.policy?.escalation?.confidenceThreshold ?? definition.base.policy?.confidence?.min ?? 0.7,
+        ...definition.base.policy?.escalation
+      }
+    },
+    memory: definition.base.memory ?? { maxEntries: 120, ttlMinutes: 120 },
+    tools: definition.tools ?? definition.base.tools,
+    instructions: `${definition.base.instructions}
+
+Always cite support knowledge sources and flag compliance/billing issues for human review when unsure.`
+  });
+  return {
+    ...base,
+    thresholds: {
+      autoResolveMinConfidence: definition.autoEscalateThreshold ?? 0.75,
+      maxIterations: 6
+    }
+  };
+}
+
+// src/rag/ticket-resolver.ts
+class TicketResolver {
+  knowledge;
+  minConfidence;
+  prependPrompt;
+  constructor(options) {
+    this.knowledge = options.knowledge;
+    this.minConfidence = options.minConfidence ?? 0.65;
+    this.prependPrompt = options.prependPrompt;
+  }
+  async resolve(ticket) {
+    const question = this.buildQuestion(ticket);
+    const answer = await this.knowledge.query(question);
+    return this.toResolution(ticket, answer);
+  }
+  buildQuestion(ticket) {
+    const header = [`Subject: ${ticket.subject}`, `Channel: ${ticket.channel}`];
+    if (ticket.customerName)
+      header.push(`Customer: ${ticket.customerName}`);
+    const sections = [
+      this.prependPrompt,
+      header.join(`
+`),
+      "---",
+      ticket.body
+    ].filter(Boolean);
+    return sections.join(`
+`);
+  }
+  toResolution(ticket, answer) {
+    const citations = answer.references.map((ref) => {
+      const label = typeof ref.payload?.title === "string" ? ref.payload.title : typeof ref.payload?.documentId === "string" ? ref.payload.documentId : ref.id;
+      return {
+        label,
+        url: typeof ref.payload?.url === "string" ? ref.payload.url : undefined,
+        snippet: typeof ref.payload?.text === "string" ? ref.payload.text.slice(0, 280) : undefined,
+        score: ref.score
+      };
+    });
+    const confidence = this.deriveConfidence(answer);
+    const escalate = confidence < this.minConfidence || citations.length === 0;
+    return {
+      ticketId: ticket.id,
+      answer: answer.answer,
+      confidence,
+      citations,
+      actions: [
+        escalate ? { type: "escalate", label: "Escalate for human review" } : { type: "respond", label: "Send automated response" }
+      ],
+      escalationReason: escalate ? "Insufficient confidence or missing knowledge references" : undefined,
+      knowledgeUpdates: escalate ? [ticket.body.slice(0, 200)] : undefined
+    };
+  }
+  deriveConfidence(answer) {
+    if (!answer.references.length)
+      return 0.3;
+    const topScore = answer.references[0]?.score ?? 0.4;
+    const normalized = Math.min(1, Math.max(0, topScore));
+    const tokenPenalty = answer.usage?.completionTokens ? Math.min(answer.usage.completionTokens / 1000, 0.2) : 0;
+    return Number((normalized - tokenPenalty).toFixed(2));
+  }
+}
+// src/tickets/classifier.ts
+var CATEGORY_KEYWORDS = {
+  billing: ["invoice", "payout", "refund", "charge", "billing", "payment"],
+  technical: ["bug", "error", "crash", "issue", "failed", "timeout"],
+  product: ["feature", "roadmap", "idea", "request", "feedback"],
+  account: ["login", "password", "2fa", "account", "profile", "email change"],
+  compliance: ["kyc", "aml", "compliance", "regulation", "gdpr"],
+  other: []
+};
+var PRIORITY_HINTS = {
+  urgent: ["urgent", "asap", "immediately", "today", "right away"],
+  high: ["high priority", "blocking", "major", "critical"],
+  medium: ["soon", "next few days"],
+  low: ["nice to have", "when possible", "later"]
+};
+var SENTIMENT_HINTS = {
+  positive: ["love", "great", "awesome", "thank you"],
+  neutral: ["question", "wonder", "curious"],
+  negative: ["unhappy", "bad", "terrible", "awful", "angry"],
+  frustrated: ["furious", "frustrated", "fed up", "ridiculous"]
+};
+
+class TicketClassifier {
+  keywords;
+  llm;
+  llmModel;
+  constructor(options) {
+    this.keywords = {
+      ...CATEGORY_KEYWORDS,
+      ...options?.keywords ?? {}
+    };
+    this.llm = options?.llm;
+    this.llmModel = options?.llmModel;
+  }
+  async classify(ticket) {
+    const heuristics = this.heuristicClassification(ticket);
+    if (!this.llm)
+      return heuristics;
+    try {
+      const llmResult = await this.llm.chat([
+        {
+          role: "system",
+          content: [{ type: "text", text: "Classify the support ticket." }]
+        },
+        {
+          role: "user",
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify({
+                subject: ticket.subject,
+                body: ticket.body,
+                channel: ticket.channel
+              })
+            }
+          ]
+        }
+      ], {
+        responseFormat: "json",
+        model: this.llmModel
+      });
+      const content = llmResult.message.content.find((part) => ("text" in part));
+      if (content && "text" in content) {
+        const parsed = JSON.parse(content.text);
+        return {
+          ...heuristics,
+          ...parsed,
+          intents: parsed.intents ?? heuristics.intents,
+          tags: parsed.tags ?? heuristics.tags
+        };
+      }
+    } catch {}
+    return heuristics;
+  }
+  heuristicClassification(ticket) {
+    const text = `${ticket.subject}
+${ticket.body}`.toLowerCase();
+    const category = this.detectCategory(text);
+    const priority = this.detectPriority(text);
+    const sentiment = this.detectSentiment(text);
+    const intents = this.extractIntents(text);
+    const tags = intents.slice(0, 3);
+    const confidence = this.estimateConfidence(category, priority, sentiment);
+    return {
+      ticketId: ticket.id,
+      category,
+      priority,
+      sentiment,
+      intents,
+      tags,
+      confidence,
+      escalationRequired: priority === "urgent" || category === "compliance"
+    };
+  }
+  detectCategory(text) {
+    for (const [category, keywords] of Object.entries(this.keywords)) {
+      if (keywords.some((keyword) => text.includes(keyword))) {
+        return category;
+      }
+    }
+    return "other";
+  }
+  detectPriority(text) {
+    for (const priority of [
+      "urgent",
+      "high",
+      "medium",
+      "low"
+    ]) {
+      if (PRIORITY_HINTS[priority].some((word) => text.includes(word))) {
+        return priority;
+      }
+    }
+    return "medium";
+  }
+  detectSentiment(text) {
+    for (const sentiment of [
+      "frustrated",
+      "negative",
+      "neutral",
+      "positive"
+    ]) {
+      if (SENTIMENT_HINTS[sentiment].some((word) => text.includes(word))) {
+        return sentiment;
+      }
+    }
+    return "neutral";
+  }
+  extractIntents(text) {
+    const intents = [];
+    if (text.includes("refund") || text.includes("chargeback"))
+      intents.push("refund");
+    if (text.includes("payout"))
+      intents.push("payout");
+    if (text.includes("login"))
+      intents.push("login-help");
+    if (text.includes("feature"))
+      intents.push("feature-request");
+    if (text.includes("bug") || text.includes("error"))
+      intents.push("bug-report");
+    return intents.length ? intents : ["general"];
+  }
+  estimateConfidence(category, priority, sentiment) {
+    let base = 0.6;
+    if (category !== "other")
+      base += 0.1;
+    if (priority === "urgent" || priority === "low")
+      base += 0.05;
+    if (sentiment === "frustrated")
+      base -= 0.05;
+    return Math.min(0.95, Math.max(0.4, Number(base.toFixed(2))));
+  }
+}
+export {
+  defineSupportBot,
+  createSupportTools,
+  TicketResolver,
+  TicketClassifier,
+  SupportFeedbackLoop,
+  AutoResponder
+};

package/dist/node/rag/index.js

@@ -0,0 +1,65 @@
+// src/rag/ticket-resolver.ts
+class TicketResolver {
+  knowledge;
+  minConfidence;
+  prependPrompt;
+  constructor(options) {
+    this.knowledge = options.knowledge;
+    this.minConfidence = options.minConfidence ?? 0.65;
+    this.prependPrompt = options.prependPrompt;
+  }
+  async resolve(ticket) {
+    const question = this.buildQuestion(ticket);
+    const answer = await this.knowledge.query(question);
+    return this.toResolution(ticket, answer);
+  }
+  buildQuestion(ticket) {
+    const header = [`Subject: ${ticket.subject}`, `Channel: ${ticket.channel}`];
+    if (ticket.customerName)
+      header.push(`Customer: ${ticket.customerName}`);
+    const sections = [
+      this.prependPrompt,
+      header.join(`
+`),
+      "---",
+      ticket.body
+    ].filter(Boolean);
+    return sections.join(`
+`);
+  }
+  toResolution(ticket, answer) {
+    const citations = answer.references.map((ref) => {
+      const label = typeof ref.payload?.title === "string" ? ref.payload.title : typeof ref.payload?.documentId === "string" ? ref.payload.documentId : ref.id;
+      return {
+        label,
+        url: typeof ref.payload?.url === "string" ? ref.payload.url : undefined,
+        snippet: typeof ref.payload?.text === "string" ? ref.payload.text.slice(0, 280) : undefined,
+        score: ref.score
+      };
+    });
+    const confidence = this.deriveConfidence(answer);
+    const escalate = confidence < this.minConfidence || citations.length === 0;
+    return {
+      ticketId: ticket.id,
+      answer: answer.answer,
+      confidence,
+      citations,
+      actions: [
+        escalate ? { type: "escalate", label: "Escalate for human review" } : { type: "respond", label: "Send automated response" }
+      ],
+      escalationReason: escalate ? "Insufficient confidence or missing knowledge references" : undefined,
+      knowledgeUpdates: escalate ? [ticket.body.slice(0, 200)] : undefined
+    };
+  }
+  deriveConfidence(answer) {
+    if (!answer.references.length)
+      return 0.3;
+    const topScore = answer.references[0]?.score ?? 0.4;
+    const normalized = Math.min(1, Math.max(0, topScore));
+    const tokenPenalty = answer.usage?.completionTokens ? Math.min(answer.usage.completionTokens / 1000, 0.2) : 0;
+    return Number((normalized - tokenPenalty).toFixed(2));
+  }
+}
+export {
+  TicketResolver
+};

package/dist/node/rag/ticket-resolver.js

@@ -0,0 +1,65 @@
+// src/rag/ticket-resolver.ts
+class TicketResolver {
+  knowledge;
+  minConfidence;
+  prependPrompt;
+  constructor(options) {
+    this.knowledge = options.knowledge;
+    this.minConfidence = options.minConfidence ?? 0.65;
+    this.prependPrompt = options.prependPrompt;
+  }
+  async resolve(ticket) {
+    const question = this.buildQuestion(ticket);
+    const answer = await this.knowledge.query(question);
+    return this.toResolution(ticket, answer);
+  }
+  buildQuestion(ticket) {
+    const header = [`Subject: ${ticket.subject}`, `Channel: ${ticket.channel}`];
+    if (ticket.customerName)
+      header.push(`Customer: ${ticket.customerName}`);
+    const sections = [
+      this.prependPrompt,
+      header.join(`
+`),
+      "---",
+      ticket.body
+    ].filter(Boolean);
+    return sections.join(`
+`);
+  }
+  toResolution(ticket, answer) {
+    const citations = answer.references.map((ref) => {
+      const label = typeof ref.payload?.title === "string" ? ref.payload.title : typeof ref.payload?.documentId === "string" ? ref.payload.documentId : ref.id;
+      return {
+        label,
+        url: typeof ref.payload?.url === "string" ? ref.payload.url : undefined,
+        snippet: typeof ref.payload?.text === "string" ? ref.payload.text.slice(0, 280) : undefined,
+        score: ref.score
+      };
+    });
+    const confidence = this.deriveConfidence(answer);
+    const escalate = confidence < this.minConfidence || citations.length === 0;
+    return {
+      ticketId: ticket.id,
+      answer: answer.answer,
+      confidence,
+      citations,
+      actions: [
+        escalate ? { type: "escalate", label: "Escalate for human review" } : { type: "respond", label: "Send automated response" }
+      ],
+      escalationReason: escalate ? "Insufficient confidence or missing knowledge references" : undefined,
+      knowledgeUpdates: escalate ? [ticket.body.slice(0, 200)] : undefined
+    };
+  }
+  deriveConfidence(answer) {
+    if (!answer.references.length)
+      return 0.3;
+    const topScore = answer.references[0]?.score ?? 0.4;
+    const normalized = Math.min(1, Math.max(0, topScore));
+    const tokenPenalty = answer.usage?.completionTokens ? Math.min(answer.usage.completionTokens / 1000, 0.2) : 0;
+    return Number((normalized - tokenPenalty).toFixed(2));
+  }
+}
+export {
+  TicketResolver
+};

package/dist/node/spec.js

@@ -0,0 +1,33 @@
+// src/spec.ts
+import { defineAgent } from "@contractspec/lib.ai-agent";
+function defineSupportBot(definition) {
+  const base = defineAgent({
+    ...definition.base,
+    policy: {
+      ...definition.base.policy,
+      confidence: {
+        min: definition.base.policy?.confidence?.min ?? 0.7,
+        default: definition.base.policy?.confidence?.default ?? 0.6
+      },
+      escalation: {
+        confidenceThreshold: definition.autoEscalateThreshold ?? definition.base.policy?.escalation?.confidenceThreshold ?? definition.base.policy?.confidence?.min ?? 0.7,
+        ...definition.base.policy?.escalation
+      }
+    },
+    memory: definition.base.memory ?? { maxEntries: 120, ttlMinutes: 120 },
+    tools: definition.tools ?? definition.base.tools,
+    instructions: `${definition.base.instructions}
+
+Always cite support knowledge sources and flag compliance/billing issues for human review when unsure.`
+  });
+  return {
+    ...base,
+    thresholds: {
+      autoResolveMinConfidence: definition.autoEscalateThreshold ?? 0.75,
+      maxIterations: 6
+    }
+  };
+}
+export {
+  defineSupportBot
+};