@ddse/acm-examples 0.5.0

package/src/tools/coaching/index.ts

@@ -0,0 +1,197 @@
+import { Tool } from '@ddse/acm-sdk';
+import {
+  getTranscript,
+  getAgent,
+  type CoachingTranscript,
+  type AgentProfile,
+} from '../../data/coaching.js';
+
+export type AnalyzeTranscriptInput = {
+  transcriptId: string;
+};
+
+export type AnalyzeTranscriptOutput = {
+  transcript: CoachingTranscript;
+  sentimentScore: number;
+  complianceScore: number;
+  complianceBreaches: string[];
+  highlights: string[];
+  summary: string;
+};
+
+function computeSentimentScore(transcript: CoachingTranscript): number {
+  switch (transcript.customerSentiment) {
+    case 'POSITIVE':
+      return 0.85;
+    case 'NEUTRAL':
+      return 0.55;
+    case 'NEGATIVE':
+      return 0.25;
+    default:
+      return 0.5;
+  }
+}
+
+function computeComplianceScore(flags: string[]): number {
+  if (flags.length === 0) {
+    return 0.95;
+  }
+  return Math.max(0.2, 0.95 - flags.length * 0.15);
+}
+
+function buildHighlights(transcript: CoachingTranscript): string[] {
+  const highlights: string[] = [];
+  if (transcript.followUpRequired) {
+    highlights.push('Customer requested follow-up action');
+  }
+  if (transcript.transcript.some(line => /apolog/i.test(line))) {
+    highlights.push('Agent provided customer apology');
+  }
+  const empathyLine = transcript.transcript.find(line => /understand|appreciate|thanks/i.test(line));
+  if (empathyLine) {
+    highlights.push(`Empathy signal captured: "${empathyLine.trim().slice(0, 120)}"`);
+  }
+  return highlights.slice(0, 3);
+}
+
+export class AnalyzeTranscriptTool extends Tool<
+  AnalyzeTranscriptInput,
+  AnalyzeTranscriptOutput
+> {
+  name(): string {
+    return 'analyze_transcript';
+  }
+
+  async call(input: AnalyzeTranscriptInput): Promise<AnalyzeTranscriptOutput> {
+    if (!input?.transcriptId) {
+      throw new Error('transcriptId is required');
+    }
+
+    const transcript = await getTranscript(input.transcriptId);
+    if (!transcript) {
+      throw new Error(`Transcript ${input.transcriptId} not found`);
+    }
+
+    const sentimentScore = computeSentimentScore(transcript);
+    const complianceScore = computeComplianceScore(transcript.complianceFlags);
+    const summary = transcript.transcript.slice(0, 6).join(' ');
+
+    return {
+      transcript,
+      sentimentScore,
+      complianceScore,
+      complianceBreaches: transcript.complianceFlags,
+      highlights: buildHighlights(transcript),
+      summary,
+    };
+  }
+}
+
+export type GenerateFeedbackInput = {
+  transcriptId: string;
+  metrics: Pick<
+    AnalyzeTranscriptOutput,
+    'sentimentScore' | 'complianceScore' | 'complianceBreaches' | 'highlights' | 'summary'
+  >;
+};
+
+export type GenerateFeedbackOutput = {
+  transcriptId: string;
+  feedbackSummary: string;
+  actionItems: string[];
+  escalationRequired: boolean;
+};
+
+function formatPercent(score: number): string {
+  return `${Math.round(score * 100)}%`;
+}
+
+export class GenerateFeedbackTool extends Tool<
+  GenerateFeedbackInput,
+  GenerateFeedbackOutput
+> {
+  name(): string {
+    return 'generate_feedback';
+  }
+
+  async call(input: GenerateFeedbackInput): Promise<GenerateFeedbackOutput> {
+    if (!input?.transcriptId || !input?.metrics) {
+      throw new Error('transcriptId and metrics are required');
+    }
+
+    const transcript = await getTranscript(input.transcriptId);
+    if (!transcript) {
+      throw new Error(`Transcript ${input.transcriptId} not found`);
+    }
+
+    const escalationRequired = input.metrics.complianceBreaches.length > 0;
+    const sentimentStr = formatPercent(input.metrics.sentimentScore);
+    const complianceStr = formatPercent(input.metrics.complianceScore);
+
+    const feedbackSummary = [
+      `Overall sentiment scored at ${sentimentStr}.`,
+      `Compliance adherence at ${complianceStr}.`,
+    ].join(' ');
+
+    const actionItems: string[] = [];
+    if (input.metrics.complianceBreaches.length > 0) {
+      actionItems.push(
+        `Address compliance items: ${input.metrics.complianceBreaches.join(', ')}`,
+      );
+    }
+    if (input.metrics.sentimentScore < 0.5) {
+      actionItems.push('Practice empathy statements to de-escalate frustrated customers');
+    }
+    actionItems.push('Acknowledge customer feelings before delivering resolution details');
+
+    return {
+      transcriptId: input.transcriptId,
+      feedbackSummary,
+      actionItems,
+      escalationRequired,
+    };
+  }
+}
+
+export type LogCoachingNoteInput = {
+  agentId: string;
+  feedbackSummary: string;
+  actionItems: string[];
+  escalationRequired: boolean;
+};
+
+export type LogCoachingNoteOutput = {
+  logId: string;
+  agent: AgentProfile;
+  stored: boolean;
+  escalationNotified: boolean;
+  timestamp: string;
+};
+
+export class LogCoachingNoteTool extends Tool<
+  LogCoachingNoteInput,
+  LogCoachingNoteOutput
+> {
+  name(): string {
+    return 'log_coaching_note';
+  }
+
+  async call(input: LogCoachingNoteInput): Promise<LogCoachingNoteOutput> {
+    if (!input?.agentId || !input?.feedbackSummary) {
+      throw new Error('agentId and feedbackSummary are required');
+    }
+
+    const agent = await getAgent(input.agentId);
+    if (!agent) {
+      throw new Error(`Agent ${input.agentId} not found`);
+    }
+
+    return {
+      logId: `coach-${Date.now()}`,
+      agent,
+      stored: true,
+      escalationNotified: input.escalationRequired,
+      timestamp: new Date().toISOString(),
+    };
+  }
+}

package/src/tools/entitlement/index.ts

@@ -0,0 +1,199 @@
+import { Tool } from '@ddse/acm-sdk';
+import {
+  getCustomerProfile,
+  getPolicy,
+  type CustomerProfile,
+  type EntitlementPolicy,
+} from '../../data/entitlement.js';
+
+export type FetchCustomerProfileInput = {
+  customerId: string;
+};
+
+export type FetchCustomerProfileOutput = {
+  customer: CustomerProfile;
+};
+
+export class FetchCustomerProfileTool extends Tool<
+  FetchCustomerProfileInput,
+  FetchCustomerProfileOutput
+> {
+  name(): string {
+    return 'fetch_customer_profile';
+  }
+
+  async call(input: FetchCustomerProfileInput): Promise<FetchCustomerProfileOutput> {
+    if (!input?.customerId) {
+      throw new Error('customerId is required');
+    }
+
+    const customer = await getCustomerProfile(input.customerId);
+    if (!customer) {
+      throw new Error(`Customer ${input.customerId} not found`);
+    }
+
+    return { customer };
+  }
+}
+
+export type EvaluateEntitlementInput = {
+  customerId: string;
+  benefitCode: string;
+};
+
+export type EvaluateEntitlementViolation = {
+  code: 'tier_mismatch' | 'account_age' | 'compliance_hold' | 'customer_missing' | 'policy_missing';
+  message: string;
+};
+
+export type EvaluateEntitlementOutput = {
+  decision: 'allow' | 'deny';
+  policy: EntitlementPolicy;
+  customer: CustomerProfile;
+  slaMinutes: number;
+  rationale: string[];
+  violations: EvaluateEntitlementViolation[];
+};
+
+const tierRank: Record<CustomerProfile['tier'], number> = {
+  STANDARD: 1,
+  GOLD: 2,
+  PLATINUM: 3,
+};
+
+export class EvaluateEntitlementTool extends Tool<
+  EvaluateEntitlementInput,
+  EvaluateEntitlementOutput
+> {
+  name(): string {
+    return 'evaluate_entitlement';
+  }
+
+  async call(input: EvaluateEntitlementInput): Promise<EvaluateEntitlementOutput> {
+    if (!input?.customerId || !input?.benefitCode) {
+      throw new Error('customerId and benefitCode are required');
+    }
+
+    const [customer, policy] = await Promise.all([
+      getCustomerProfile(input.customerId),
+      getPolicy(input.benefitCode),
+    ]);
+
+    const violations: EvaluateEntitlementViolation[] = [];
+    const rationale: string[] = [];
+
+    if (!customer) {
+      violations.push({
+        code: 'customer_missing',
+        message: `Customer ${input.customerId} was not found in CRM snapshot`,
+      });
+    }
+
+    if (!policy) {
+      violations.push({
+        code: 'policy_missing',
+        message: `Policy ${input.benefitCode} was not found in entitlement catalog`,
+      });
+    }
+
+    if (!customer || !policy) {
+      throw new Error(
+        `Unable to evaluate entitlement: ${violations.map(v => v.message).join('; ')}`,
+      );
+    }
+
+    if (tierRank[customer.tier] < tierRank[policy.requiredTier]) {
+      violations.push({
+        code: 'tier_mismatch',
+        message: `Customer tier ${customer.tier} does not meet required tier ${policy.requiredTier}`,
+      });
+    } else {
+      rationale.push(`Customer tier ${customer.tier} satisfies required tier ${policy.requiredTier}`);
+    }
+
+    if (customer.accountAgeDays < policy.minAccountAgeDays) {
+      violations.push({
+        code: 'account_age',
+        message: `Account age ${customer.accountAgeDays} days is below minimum ${policy.minAccountAgeDays} days`,
+      });
+    } else {
+      rationale.push(
+        `Account age ${customer.accountAgeDays} days exceeds minimum ${policy.minAccountAgeDays} days`,
+      );
+    }
+
+    const hasComplianceHold = customer.complianceFlags.length > 0;
+    if (policy.requiresComplianceClearance && hasComplianceHold) {
+      violations.push({
+        code: 'compliance_hold',
+        message: `Compliance flags present: ${customer.complianceFlags.join(', ')}`,
+      });
+    } else if (policy.requiresComplianceClearance) {
+      rationale.push('No compliance holds found for customer');
+    }
+
+    const decision = violations.length === 0 ? 'allow' : 'deny';
+    if (decision === 'deny') {
+      rationale.push('Entitlement denied due to policy violations');
+    } else {
+      rationale.push('Entitlement approved according to policy requirements');
+    }
+
+    return {
+      decision,
+      policy,
+      customer,
+      slaMinutes: policy.slaMinutes,
+      rationale,
+      violations,
+    };
+  }
+}
+
+export type NotifySupervisorInput = {
+  customerId: string;
+  message: string;
+  channel?: 'email' | 'slack';
+};
+
+export type NotifySupervisorOutput = {
+  notified: boolean;
+  channel: string;
+  supervisor: {
+    name: string;
+    email: string;
+  };
+  messageId: string;
+  timestamp: string;
+};
+
+export class EntitlementNotifySupervisorTool extends Tool<
+  NotifySupervisorInput,
+  NotifySupervisorOutput
+> {
+  name(): string {
+    return 'notify_supervisor';
+  }
+
+  async call(input: NotifySupervisorInput): Promise<NotifySupervisorOutput> {
+    if (!input?.customerId || !input?.message) {
+      throw new Error('customerId and message are required');
+    }
+
+    const customer = await getCustomerProfile(input.customerId);
+    if (!customer) {
+      throw new Error(`Customer ${input.customerId} not found`);
+    }
+
+    const channel = input.channel ?? 'email';
+    const messageId = `notif-${Date.now()}`;
+
+    return {
+      notified: true,
+      channel,
+      supervisor: customer.supervisor,
+      messageId,
+      timestamp: new Date().toISOString(),
+    };
+  }
+}

package/src/tools/incidents/index.ts

@@ -0,0 +1,185 @@
+import { Tool } from '@ddse/acm-sdk';
+import {
+  getIncident,
+  findRoutingRule,
+  type IncidentRecord,
+  type IncidentSeverity,
+  type RoutingRule,
+} from '../../data/incidents.js';
+
+export type FetchIncidentInput = {
+  incidentId: string;
+};
+
+export type FetchIncidentOutput = {
+  incident: IncidentRecord;
+};
+
+export class FetchIncidentTool extends Tool<FetchIncidentInput, FetchIncidentOutput> {
+  name(): string {
+    return 'fetch_incident';
+  }
+
+  async call(input: FetchIncidentInput): Promise<FetchIncidentOutput> {
+    if (!input?.incidentId) {
+      throw new Error('incidentId is required');
+    }
+
+    const incident = await getIncident(input.incidentId);
+    if (!incident) {
+      throw new Error(`Incident ${input.incidentId} not found`);
+    }
+
+    return { incident };
+  }
+}
+
+export type ClassifySeverityInput = {
+  incident: IncidentRecord;
+};
+
+export type ClassifySeverityOutput = {
+  severity: IncidentSeverity;
+  score: number;
+  rationale: string[];
+};
+
+function scoreSeverity(incident: IncidentRecord): { severity: IncidentSeverity; score: number; rationale: string[] } {
+  const rationale: string[] = [];
+  let score = 0;
+
+  const declaredRank = rank(incident.declaredSeverity);
+  score += declaredRank * 20;
+  rationale.push(`Declared severity ${incident.declaredSeverity} provides base score ${declaredRank * 20}`);
+
+  if (incident.customerImpact === 'MAJOR') {
+    score += 30;
+    rationale.push('Major customer impact adds 30 points');
+  } else if (incident.customerImpact === 'MINOR') {
+    score += 15;
+    rationale.push('Minor customer impact adds 15 points');
+  }
+
+  score += Math.min(incident.signalScore, 40);
+  rationale.push(`Signal score contribution: ${Math.min(incident.signalScore, 40)}`);
+
+  if (incident.vipCustomer) {
+    score += 10;
+    rationale.push('VIP customer flag adds 10 points');
+  }
+
+  const severity = score >= 80 ? 'CRITICAL' : score >= 60 ? 'HIGH' : score >= 40 ? 'MEDIUM' : 'LOW';
+  rationale.push(`Composite score ${score} maps to severity ${severity}`);
+  return { severity, score, rationale };
+}
+
+function rank(severity: IncidentSeverity): number {
+  switch (severity) {
+    case 'LOW': return 1;
+    case 'MEDIUM': return 2;
+    case 'HIGH': return 3;
+    case 'CRITICAL': return 4;
+    default: return 0;
+  }
+}
+
+export class ClassifySeverityTool extends Tool<
+  ClassifySeverityInput,
+  ClassifySeverityOutput
+> {
+  name(): string {
+    return 'classify_severity';
+  }
+
+  async call(input: ClassifySeverityInput): Promise<ClassifySeverityOutput> {
+    if (!input?.incident) {
+      throw new Error('incident is required');
+    }
+
+    return scoreSeverity(input.incident);
+  }
+}
+
+export type SelectQueueInput = {
+  incident: IncidentRecord;
+  severityOverride?: IncidentSeverity;
+};
+
+export type SelectQueueOutput = {
+  queue: string;
+  rule: RoutingRule;
+  escalationRequired: boolean;
+  rationale: string[];
+};
+
+export class SelectQueueTool extends Tool<SelectQueueInput, SelectQueueOutput> {
+  name(): string {
+    return 'select_queue';
+  }
+
+  async call(input: SelectQueueInput): Promise<SelectQueueOutput> {
+    if (!input?.incident) {
+      throw new Error('incident is required');
+    }
+
+    const rule = await findRoutingRule(input.incident, input.severityOverride);
+    if (!rule) {
+      throw new Error(`No routing rule found for incident ${input.incident.id}`);
+    }
+
+    const rationale = [
+      `Matched routing rule ${rule.id} for service ${rule.service} category ${rule.category}`,
+    ];
+    if (rule.escalatesTo) {
+      rationale.push(`Escalation target defined: ${rule.escalatesTo}`);
+    }
+    if (rule.notes) {
+      rationale.push(`Routing notes: ${rule.notes}`);
+    }
+
+    return {
+      queue: rule.queue,
+      rule,
+      escalationRequired: Boolean(rule.escalatesTo),
+      rationale,
+    };
+  }
+}
+
+export type EscalateIncidentInput = {
+  incidentId: string;
+  target: string;
+  reason: string;
+};
+
+export type EscalateIncidentOutput = {
+  escalated: boolean;
+  ticketId: string;
+  target: string;
+  reason: string;
+  timestamp: string;
+};
+
+export class EscalateIncidentTool extends Tool<
+  EscalateIncidentInput,
+  EscalateIncidentOutput
+> {
+  name(): string {
+    return 'escalate_incident';
+  }
+
+  async call(input: EscalateIncidentInput): Promise<EscalateIncidentOutput> {
+    if (!input?.incidentId || !input?.target || !input?.reason) {
+      throw new Error('incidentId, target, and reason are required');
+    }
+
+    const ticketId = `esc-${Date.now()}`;
+    return {
+      escalated: true,
+      ticketId,
+      target: input.target,
+      reason: input.reason,
+      timestamp: new Date().toISOString(),
+    };
+  }
+}