@ddse/acm-examples 0.5.0

package/src/tools/index.ts

@@ -0,0 +1,192 @@
+import { Tool } from '@ddse/acm-sdk';
+import {
+  FetchCustomerProfileTool,
+  EvaluateEntitlementTool,
+  EntitlementNotifySupervisorTool,
+} from './entitlement/index.js';
+import {
+  SearchKnowledgeTool,
+  SummarizeSnippetTool,
+  SuggestFollowupsTool,
+} from './knowledge/index.js';
+import {
+  FetchIncidentTool,
+  ClassifySeverityTool,
+  SelectQueueTool,
+  EscalateIncidentTool,
+} from './incidents/index.js';
+import {
+  FetchInvoiceTool,
+  FetchPurchaseOrderTool,
+  CompareLineItemsTool,
+  RecordFindingsTool,
+} from './invoices/index.js';
+import {
+  AnalyzeTranscriptTool,
+  GenerateFeedbackTool,
+  LogCoachingNoteTool,
+} from './coaching/index.js';
+import { searchSnippets } from '../data/knowledge.js';
+
+export {
+  FetchCustomerProfileTool,
+  EvaluateEntitlementTool,
+  EntitlementNotifySupervisorTool,
+  SearchKnowledgeTool,
+  SummarizeSnippetTool,
+  SuggestFollowupsTool,
+  FetchIncidentTool,
+  ClassifySeverityTool,
+  SelectQueueTool,
+  EscalateIncidentTool,
+  FetchInvoiceTool,
+  FetchPurchaseOrderTool,
+  CompareLineItemsTool,
+  RecordFindingsTool,
+  AnalyzeTranscriptTool,
+  GenerateFeedbackTool,
+  LogCoachingNoteTool,
+};
+
+export type ExampleToolInstance = {
+  tool: Tool<any, any>;
+  category: 'entitlement' | 'knowledge' | 'incident' | 'invoice' | 'coaching';
+};
+
+export function createExampleTools(): ExampleToolInstance[] {
+  return [
+    { tool: new FetchCustomerProfileTool(), category: 'entitlement' },
+    { tool: new EvaluateEntitlementTool(), category: 'entitlement' },
+    { tool: new EntitlementNotifySupervisorTool(), category: 'entitlement' },
+    { tool: new SearchKnowledgeTool(), category: 'knowledge' },
+    { tool: new SummarizeSnippetTool(), category: 'knowledge' },
+    { tool: new SuggestFollowupsTool(), category: 'knowledge' },
+    { tool: new FetchIncidentTool(), category: 'incident' },
+    { tool: new ClassifySeverityTool(), category: 'incident' },
+    { tool: new SelectQueueTool(), category: 'incident' },
+    { tool: new EscalateIncidentTool(), category: 'incident' },
+    { tool: new FetchInvoiceTool(), category: 'invoice' },
+    { tool: new FetchPurchaseOrderTool(), category: 'invoice' },
+    { tool: new CompareLineItemsTool(), category: 'invoice' },
+    { tool: new RecordFindingsTool(), category: 'invoice' },
+    { tool: new AnalyzeTranscriptTool(), category: 'coaching' },
+    { tool: new GenerateFeedbackTool(), category: 'coaching' },
+    { tool: new LogCoachingNoteTool(), category: 'coaching' },
+  ];
+}
+
+export type SearchToolInput = {
+  query: string;
+  limit?: number;
+};
+
+export type SearchToolOutput = {
+  results: Array<{
+    id: string;
+    title: string;
+    score: number;
+    type: string;
+    summary: string;
+    tags: string[];
+  }>;
+};
+
+export class SearchTool extends Tool<SearchToolInput, SearchToolOutput> {
+  name(): string {
+    return 'search';
+  }
+
+  async call(input: SearchToolInput): Promise<SearchToolOutput> {
+    const query = input?.query?.trim();
+    if (!query) {
+      throw new Error('query is required');
+    }
+
+    const limit = Math.max(1, Math.min(input.limit ?? 5, 10));
+    const snippets = await searchSnippets(query);
+    const results = snippets.slice(0, limit).map((snippet, index) => ({
+      id: snippet.id,
+      title: snippet.title,
+      summary: snippet.summary,
+      tags: snippet.tags,
+      type: 'knowledge',
+      score: Math.max(1, snippets.length - index),
+    }));
+
+    return { results };
+  }
+}
+
+export class ExtractEntitiesTool extends Tool<{ text: string }, { entities: string[] }> {
+  name(): string {
+    return 'extract_entities';
+  }
+
+  async call(input: { text: string }): Promise<{ entities: string[] }> {
+    const text = input?.text ?? '';
+    const entities = Array.from(new Set(text.match(/[A-Z]{2,}-\d+/g) ?? []));
+    if (!entities.includes('ORDER-REF')) {
+      entities.push('ORDER-REF');
+    }
+    return { entities };
+  }
+}
+
+export class AssessRiskTool extends Tool<{ context: any }, { riskTier: string; score: number }> {
+  name(): string {
+    return 'assess_risk';
+  }
+
+  async call(input: { context: any }): Promise<{ riskTier: string; score: number }> {
+    const serialized = JSON.stringify(input?.context ?? {});
+    let hash = 0;
+    for (let i = 0; i < serialized.length; i++) {
+      hash = (hash + serialized.charCodeAt(i) * (i + 1)) % 101;
+    }
+    const score = hash;
+    const riskTier = score > 70 ? 'HIGH' : score > 40 ? 'MEDIUM' : 'LOW';
+    return { riskTier, score };
+  }
+}
+
+export class CreateRefundTxnTool extends Tool<
+  { orderId: string; amount: number },
+  { transactionId: string; status: string }
+> {
+  name(): string {
+    return 'create_refund_txn';
+  }
+
+  async call(input: { orderId: string; amount: number }): Promise<{ transactionId: string; status: string }> {
+    if (!input?.orderId || typeof input.amount !== 'number') {
+      throw new Error('orderId and amount are required');
+    }
+
+    return {
+      transactionId: `TXN-${Date.now()}`,
+      status: input.amount > 0 ? 'COMPLETED' : 'REJECTED',
+    };
+  }
+}
+
+export class NotifySupervisorToolLegacy extends Tool<
+  { message: string; channel: string },
+  { sent: boolean; messageId: string }
+> {
+  name(): string {
+    return 'notify_supervisor_legacy';
+  }
+
+  async call(input: { message: string; channel: string }): Promise<{ sent: boolean; messageId: string }> {
+    if (!input?.message) {
+      throw new Error('message is required');
+    }
+
+    return {
+      sent: true,
+      messageId: `MSG-${Date.now()}`,
+    };
+  }
+}
+
+export { NotifySupervisorToolLegacy as NotifySupervisorTool };

package/src/tools/invoices/index.ts

@@ -0,0 +1,165 @@
+import { Tool } from '@ddse/acm-sdk';
+import {
+  getInvoice,
+  getPurchaseOrder,
+  compareLineItems,
+  type InvoiceRecord,
+  type PurchaseOrderRecord,
+} from '../../data/invoices.js';
+
+export type FetchInvoiceInput = {
+  invoiceId: string;
+};
+
+export type FetchInvoiceOutput = {
+  invoice: InvoiceRecord;
+};
+
+export class FetchInvoiceTool extends Tool<FetchInvoiceInput, FetchInvoiceOutput> {
+  name(): string {
+    return 'fetch_invoice';
+  }
+
+  async call(input: FetchInvoiceInput): Promise<FetchInvoiceOutput> {
+    if (!input?.invoiceId) {
+      throw new Error('invoiceId is required');
+    }
+
+    const invoice = await getInvoice(input.invoiceId);
+    if (!invoice) {
+      throw new Error(`Invoice ${input.invoiceId} not found`);
+    }
+
+    return { invoice };
+  }
+}
+
+export type FetchPurchaseOrderInput = {
+  purchaseOrderId: string;
+};
+
+export type FetchPurchaseOrderOutput = {
+  purchaseOrder: PurchaseOrderRecord;
+};
+
+export class FetchPurchaseOrderTool extends Tool<
+  FetchPurchaseOrderInput,
+  FetchPurchaseOrderOutput
+> {
+  name(): string {
+    return 'fetch_purchase_order';
+  }
+
+  async call(input: FetchPurchaseOrderInput): Promise<FetchPurchaseOrderOutput> {
+    if (!input?.purchaseOrderId) {
+      throw new Error('purchaseOrderId is required');
+    }
+
+    const purchaseOrder = await getPurchaseOrder(input.purchaseOrderId);
+    if (!purchaseOrder) {
+      throw new Error(`Purchase order ${input.purchaseOrderId} not found`);
+    }
+
+    return { purchaseOrder };
+  }
+}
+
+export type CompareLineItemsInput = {
+  invoice: InvoiceRecord;
+  purchaseOrder: PurchaseOrderRecord;
+};
+
+export type Discrepancy = ReturnType<typeof compareLineItems>[number] & {
+  varianceAmount: number;
+};
+
+export type CompareLineItemsOutput = {
+  discrepancies: Discrepancy[];
+  variance: number;
+  matchedLines: number;
+};
+
+export class CompareLineItemsTool extends Tool<
+  CompareLineItemsInput,
+  CompareLineItemsOutput
+> {
+  name(): string {
+    return 'compare_line_items';
+  }
+
+  async call(input: CompareLineItemsInput): Promise<CompareLineItemsOutput> {
+    if (!input?.invoice || !input?.purchaseOrder) {
+      throw new Error('invoice and purchaseOrder are required');
+    }
+
+    const discrepancies = compareLineItems(input.invoice, input.purchaseOrder).map(item => ({
+      ...item,
+      varianceAmount:
+        (item.actualQuantity - item.expectedQuantity) * item.expectedPrice ||
+        (item.actualPrice - item.expectedPrice) * item.actualQuantity,
+    }));
+
+    const matchedLines = input.invoice.lines.length - discrepancies.length;
+    const variance = discrepancies.reduce((sum, item) => sum + item.varianceAmount, 0);
+
+    return {
+      discrepancies,
+      variance,
+      matchedLines,
+    };
+  }
+}
+
+export type RecordFindingsInput = {
+  invoice: InvoiceRecord;
+  purchaseOrder: PurchaseOrderRecord;
+  discrepancies: Discrepancy[];
+  variance: number;
+};
+
+export type RecordFindingsOutput = {
+  reportId: string;
+  status: 'clean' | 'needs_remediation';
+  summary: string;
+  nextSteps: string[];
+  generatedAt: string;
+};
+
+export class RecordFindingsTool extends Tool<
+  RecordFindingsInput,
+  RecordFindingsOutput
+> {
+  name(): string {
+    return 'record_findings';
+  }
+
+  async call(input: RecordFindingsInput): Promise<RecordFindingsOutput> {
+    if (!input?.invoice || !input?.purchaseOrder) {
+      throw new Error('invoice and purchaseOrder are required');
+    }
+
+    const status = input.discrepancies.length === 0 && Math.abs(input.variance) < 1
+      ? 'clean'
+      : 'needs_remediation';
+
+    const summary = status === 'clean'
+      ? `Invoice ${input.invoice.id} matches purchase order ${input.purchaseOrder.id}`
+      : `Invoice ${input.invoice.id} has ${input.discrepancies.length} discrepancy(s)`;
+
+    const nextSteps = status === 'clean'
+      ? ['Archive reconciliation report in AP system']
+      : [
+          'Open remediation ticket with procurement',
+          'Notify accounts payable supervisor',
+          'Schedule supplier follow-up call',
+        ];
+
+    return {
+      reportId: `recon-${Date.now()}`,
+      status,
+      summary,
+      nextSteps,
+      generatedAt: new Date().toISOString(),
+    };
+  }
+}

package/src/tools/knowledge/index.ts

@@ -0,0 +1,203 @@
+import { Tool } from '@ddse/acm-sdk';
+import {
+  searchSnippets,
+  loadSnippetContent,
+  getSnippetMeta,
+  type KnowledgeSnippetMeta,
+} from '../../data/knowledge.js';
+
+export type KnowledgeSearchInput = {
+  query: string;
+  limit?: number;
+};
+
+export type KnowledgeSearchHit = KnowledgeSnippetMeta & {
+  score: number;
+};
+
+export type KnowledgeSearchOutput = {
+  hits: KnowledgeSearchHit[];
+};
+
+export class SearchKnowledgeTool extends Tool<KnowledgeSearchInput, KnowledgeSearchOutput> {
+  name(): string {
+    return 'search_knowledge';
+  }
+
+  async call(input: KnowledgeSearchInput): Promise<KnowledgeSearchOutput> {
+    const query = input?.query?.trim();
+    if (!query) {
+      throw new Error('query is required');
+    }
+
+    const limit = Math.max(1, Math.min(input.limit ?? 5, 10));
+    const snippets = await searchSnippets(query);
+
+    const hits: KnowledgeSearchHit[] = snippets.slice(0, limit).map((snippet, index) => ({
+      ...snippet,
+      score: Math.max(1, snippets.length - index),
+    }));
+
+    return { hits };
+  }
+}
+
+export type SummarizeSnippetInput = {
+  docId: string;
+  maxSentences?: number;
+  focus?: string;
+};
+
+export type SummarizeSnippetOutput = {
+  docId: string;
+  title: string;
+  summary: string;
+  highlights: string[];
+  followups: string[];
+};
+
+function summarizeContent(content: string, maxSentences: number): string {
+  const sentences = content
+    .replace(/\s+/g, ' ')
+    .split(/(?<=[.!?])\s+(?=[A-Z0-9])/)
+    .filter(Boolean);
+
+  if (sentences.length === 0) {
+    return content.trim();
+  }
+
+  return sentences.slice(0, maxSentences).join(' ');
+}
+
+function extractHighlights(content: string, maxHighlights = 3): string[] {
+  const lines = content.split(/\r?\n/).map(line => line.trim()).filter(Boolean);
+  const bulletLines = lines.filter(line => /^[-*]/.test(line));
+  const highlights: string[] = [];
+
+  for (const line of bulletLines) {
+    highlights.push(line.replace(/^[-*]\s*/, ''));
+    if (highlights.length >= maxHighlights) {
+      break;
+    }
+  }
+
+  if (highlights.length === 0) {
+    highlights.push(...lines.slice(0, maxHighlights));
+  }
+
+  return highlights.slice(0, maxHighlights);
+}
+
+function deriveFollowups(meta: KnowledgeSnippetMeta, focus?: string): string[] {
+  const followups = new Set<string>();
+
+  for (const tag of meta.tags) {
+    if (tag.toLowerCase().includes('escalation')) {
+      followups.add('Confirm escalation steps with runbook owner');
+    }
+    if (tag.toLowerCase().includes('training')) {
+      followups.add('Share summary with enablement channel for awareness');
+    }
+    if (tag.toLowerCase().includes('automation')) {
+      followups.add('Evaluate automation opportunity with platform team');
+    }
+  }
+
+  if (focus) {
+    followups.add(`Identify additional knowledge gaps related to "${focus}"`);
+  }
+
+  if (followups.size === 0) {
+    followups.add('Log follow-up tasks in support queue');
+  }
+
+  return Array.from(followups);
+}
+
+export class SummarizeSnippetTool extends Tool<
+  SummarizeSnippetInput,
+  SummarizeSnippetOutput
+> {
+  name(): string {
+    return 'summarize_snippet';
+  }
+
+  async call(input: SummarizeSnippetInput): Promise<SummarizeSnippetOutput> {
+    if (!input?.docId) {
+      throw new Error('docId is required');
+    }
+
+    const [meta, content] = await Promise.all([
+      getSnippetMeta(input.docId),
+      loadSnippetContent(input.docId),
+    ]);
+
+    if (!meta || !content) {
+      throw new Error(`Snippet ${input.docId} not found`);
+    }
+
+    const maxSentences = Math.max(1, Math.min(input.maxSentences ?? 3, 6));
+    const summary = summarizeContent(content, maxSentences);
+    const highlights = extractHighlights(content);
+    const followups = deriveFollowups(meta, input.focus);
+
+    return {
+      docId: input.docId,
+      title: meta.title,
+      summary,
+      highlights,
+      followups,
+    };
+  }
+}
+
+export type SuggestFollowupsInput = {
+  docId: string;
+  context?: {
+    channel?: string;
+    urgency?: 'low' | 'normal' | 'high';
+  };
+};
+
+export type SuggestFollowupsOutput = {
+  docId: string;
+  suggestions: Array<{
+    action: string;
+    owner: string;
+    dueInHours: number;
+  }>;
+};
+
+export class SuggestFollowupsTool extends Tool<
+  SuggestFollowupsInput,
+  SuggestFollowupsOutput
+> {
+  name(): string {
+    return 'suggest_followups';
+  }
+
+  async call(input: SuggestFollowupsInput): Promise<SuggestFollowupsOutput> {
+    if (!input?.docId) {
+      throw new Error('docId is required');
+    }
+
+    const meta = await getSnippetMeta(input.docId);
+    if (!meta) {
+      throw new Error(`Snippet ${input.docId} not found`);
+    }
+
+    const baseDue = input.context?.urgency === 'high' ? 4 : input.context?.urgency === 'low' ? 24 : 8;
+
+    const suggestions = deriveFollowups(meta)
+      .map((action, index) => ({
+        action,
+        owner: index === 0 ? 'support.enablement' : 'support.lead',
+        dueInHours: baseDue + index * 4,
+      }));
+
+    return {
+      docId: input.docId,
+      suggestions,
+    };
+  }
+}

package/tests/bm25.test.ts

@@ -0,0 +1,129 @@
+// Tests for BM25 search functionality
+import { BM25Search } from '../src/search/bm25.js';
+
+async function testIndexAndSearch() {
+  console.log('Testing index and search...');
+  
+  const documents = [
+    { id: 'doc1', content: 'The quick brown fox jumps over the lazy dog' },
+    { id: 'doc2', content: 'A fast brown fox leaps over a sleepy dog' },
+    { id: 'doc3', content: 'The cat sits on the mat' },
+  ];
+
+  const search = new BM25Search();
+  search.index(documents);
+
+  const results = search.search('brown fox');
+  
+  if (results.length === 0) {
+    throw new Error('Expected results, got none');
+  }
+  
+  if (!['doc1', 'doc2'].includes(results[0].document.id)) {
+    throw new Error(`Expected doc1 or doc2, got ${results[0].document.id}`);
+  }
+  
+  console.log('✅ Index and search test passed');
+}
+
+async function testEmptyQuery() {
+  console.log('Testing empty query...');
+  
+  const documents = [{ id: 'doc1', content: 'Test document' }];
+  const search = new BM25Search();
+  search.index(documents);
+  
+  const results = search.search('');
+  
+  if (results.length !== 0) {
+    throw new Error('Expected empty results for empty query');
+  }
+  
+  console.log('✅ Empty query test passed');
+}
+
+async function testRanking() {
+  console.log('Testing ranking...');
+  
+  const documents = [
+    { id: 'doc1', content: 'machine learning algorithms' },
+    { id: 'doc2', content: 'learning machine code' },
+    { id: 'doc3', content: 'deep learning neural networks' },
+  ];
+
+  const search = new BM25Search();
+  search.index(documents);
+
+  const results = search.search('machine learning');
+  
+  if (results.length < 2) {
+    throw new Error('Expected at least 2 results');
+  }
+  
+  if (results[0].score < results[1].score) {
+    throw new Error('Results not properly ranked');
+  }
+  
+  console.log('✅ Ranking test passed');
+}
+
+async function testLimitParameter() {
+  console.log('Testing limit parameter...');
+  
+  const documents = Array.from({ length: 10 }, (_, i) => ({
+    id: `doc${i}`,
+    content: `Document ${i} with test content`,
+  }));
+
+  const search = new BM25Search();
+  search.index(documents);
+
+  const results = search.search('test', 3);
+  
+  if (results.length > 3) {
+    throw new Error(`Expected max 3 results, got ${results.length}`);
+  }
+  
+  console.log('✅ Limit parameter test passed');
+}
+
+async function runTests() {
+  console.log('Running BM25 Search Tests\n');
+  console.log('='.repeat(50));
+
+  const tests = [
+    testIndexAndSearch,
+    testEmptyQuery,
+    testRanking,
+    testLimitParameter,
+  ];
+
+  let passed = 0;
+  let failed = 0;
+
+  for (const test of tests) {
+    try {
+      await test();
+      passed++;
+    } catch (error) {
+      console.error(`❌ Test failed: ${error}`);
+      failed++;
+    }
+  }
+
+  console.log('\n' + '='.repeat(50));
+  console.log(`Results: ${passed} passed, ${failed} failed\n`);
+
+  return failed === 0;
+}
+
+// Run if executed directly
+if (import.meta.url === `file://${process.argv[1]}`) {
+  runTests().then(success => {
+    process.exit(success ? 0 : 1);
+  }).catch(error => {
+    console.error('Test runner error:', error);
+    process.exit(1);
+  });
+}
+