@ddse/acm-examples 0.5.0

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@ddse/acm-examples",
+  "version": "0.5.0",
+  "description": "ACM v0.5 Examples - CLI demo and sample implementations",
+  "type": "module",
+  "bin": {
+    "acm-demo": "./dist/bin/acm-demo.js"
+  },
+  "dependencies": {
+    "@ddse/acm-framework": "0.5.0",
+    "@ddse/acm-sdk": "0.5.0",
+    "@ddse/acm-planner": "0.5.0",
+    "@ddse/acm-runtime": "0.5.0",
+    "@ddse/acm-mcp": "0.5.0",
+    "@ddse/acm-llm": "0.5.0",
+    "@ddse/acm-adapters": "0.5.0",
+    "@ddse/acm-replay": "0.5.0"
+  },
+  "keywords": [
+    "acm",
+    "examples",
+    "cli"
+  ],
+  "license": "MIT",
+  "scripts": {
+    "build": "tsc",
+    "clean": "rm -rf dist",
+    "dev": "tsc --watch",
+    "demo": "node ./dist/bin/acm-demo.js",
+    "test": "node ./dist/tests/integration.test.js && node ./dist/tests/plan-hydration.test.js",
+    "test:bm25": "node ./dist/tests/bm25.test.js"
+  }
+}

package/src/context/directives.ts

@@ -0,0 +1,366 @@
+import { ExternalContextProviderAdapter, Tool, type ContextRetrievalArtifact } from '@ddse/acm-sdk';
+import { getCustomerProfile, getPolicy } from '../data/entitlement.js';
+import { getSnippetMeta, loadSnippetContent } from '../data/knowledge.js';
+import { getIncident, findRoutingRule } from '../data/incidents.js';
+import { getInvoice, getPurchaseOrder } from '../data/invoices.js';
+import { getTranscript, getAgent } from '../data/coaching.js';
+
+function extractPayload(directive: string): string | Record<string, any> | undefined {
+  const separator = directive.indexOf(':');
+  if (separator < 0) {
+    return undefined;
+  }
+
+  const raw = directive.slice(separator + 1).trim();
+  if (!raw) {
+    return undefined;
+  }
+
+  if (raw.startsWith('{')) {
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return undefined;
+    }
+  }
+
+  return raw;
+}
+
+abstract class ContextTool<I> extends Tool<I, ContextRetrievalArtifact[]> {
+  async call(input: I): Promise<ContextRetrievalArtifact[]> {
+    const artifacts = await this.produceArtifacts(input);
+    return Array.isArray(artifacts) ? artifacts : [artifacts];
+  }
+
+  protected abstract produceArtifacts(input: I): Promise<ContextRetrievalArtifact | ContextRetrievalArtifact[]>;
+}
+
+class CustomerContextTool extends ContextTool<{ customerId: string }> {
+  name(): string {
+    return 'crm';
+  }
+
+  protected async produceArtifacts(input: { customerId: string }): Promise<ContextRetrievalArtifact> {
+    const customer = await getCustomerProfile(input.customerId);
+    if (!customer) {
+      throw new Error(`Customer ${input.customerId} not found`);
+    }
+
+    return {
+      type: 'crm.customer',
+      content: customer,
+      promote: true,
+      provenance: {
+        tool: this.name(),
+        customerId: input.customerId,
+      },
+    };
+  }
+}
+
+class PolicyContextTool extends ContextTool<{ benefitCode: string }> {
+  name(): string {
+    return 'policy';
+  }
+
+  protected async produceArtifacts(input: { benefitCode: string }): Promise<ContextRetrievalArtifact> {
+    const policy = await getPolicy(input.benefitCode);
+    if (!policy) {
+      throw new Error(`Policy ${input.benefitCode} not found`);
+    }
+
+    return {
+      type: 'crm.policy',
+      content: policy,
+      promote: true,
+      provenance: {
+        tool: this.name(),
+        benefitCode: input.benefitCode,
+      },
+    };
+  }
+}
+
+class KnowledgeContextTool extends ContextTool<{ docId: string }> {
+  name(): string {
+    return 'kb';
+  }
+
+  protected async produceArtifacts(input: { docId: string }): Promise<ContextRetrievalArtifact[]> {
+    const [meta, content] = await Promise.all([
+      getSnippetMeta(input.docId),
+      loadSnippetContent(input.docId),
+    ]);
+
+    if (!meta || !content) {
+      throw new Error(`Knowledge doc ${input.docId} not found`);
+    }
+
+    return [
+      {
+        type: 'kb.meta',
+        content: meta,
+        promote: true,
+        provenance: {
+          tool: this.name(),
+          docId: input.docId,
+          stage: 'metadata',
+        },
+      },
+      {
+        type: 'kb.content',
+        content: content,
+        promote: false,
+        provenance: {
+          tool: this.name(),
+          docId: input.docId,
+          stage: 'content',
+        },
+      },
+    ];
+  }
+}
+
+class IncidentContextTool extends ContextTool<{ incidentId: string }> {
+  name(): string {
+    return 'inc';
+  }
+
+  protected async produceArtifacts(input: { incidentId: string }): Promise<ContextRetrievalArtifact> {
+    const incident = await getIncident(input.incidentId);
+    if (!incident) {
+      throw new Error(`Incident ${input.incidentId} not found`);
+    }
+
+    return {
+      type: 'incident.record',
+      content: incident,
+      promote: true,
+      provenance: {
+        tool: this.name(),
+        incidentId: input.incidentId,
+      },
+    };
+  }
+}
+
+class RoutingContextTool extends ContextTool<{ incidentId: string; severity?: string }> {
+  name(): string {
+    return 'routing';
+  }
+
+  protected async produceArtifacts(input: { incidentId: string; severity?: string }): Promise<ContextRetrievalArtifact> {
+    const incident = await getIncident(input.incidentId);
+    if (!incident) {
+      throw new Error(`Incident ${input.incidentId} not found for routing lookup`);
+    }
+
+    const rule = await findRoutingRule(incident, input.severity as any);
+    if (!rule) {
+      throw new Error(`Routing rule not found for incident ${input.incidentId}`);
+    }
+
+    return {
+      type: 'incident.routing_rule',
+      content: rule,
+      promote: true,
+      provenance: {
+        tool: this.name(),
+        incidentId: input.incidentId,
+        severity: input.severity,
+      },
+    };
+  }
+}
+
+class InvoiceContextTool extends ContextTool<{ invoiceId: string }> {
+  name(): string {
+    return 'erp';
+  }
+
+  protected async produceArtifacts(input: { invoiceId: string }): Promise<ContextRetrievalArtifact[]> {
+    const invoice = await getInvoice(input.invoiceId);
+    if (!invoice) {
+      throw new Error(`Invoice ${input.invoiceId} not found`);
+    }
+
+    const purchaseOrder = invoice.purchaseOrderId
+      ? await getPurchaseOrder(invoice.purchaseOrderId)
+      : undefined;
+
+    const artifacts: ContextRetrievalArtifact[] = [
+      {
+        type: 'erp.invoice',
+        content: invoice,
+        promote: true,
+        provenance: {
+          tool: this.name(),
+          stage: 'invoice',
+          invoiceId: input.invoiceId,
+        },
+      },
+    ];
+
+    if (purchaseOrder) {
+      artifacts.push({
+        type: 'erp.purchase_order',
+        content: purchaseOrder,
+        promote: true,
+        provenance: {
+          tool: this.name(),
+          stage: 'purchase-order',
+          invoiceId: input.invoiceId,
+          purchaseOrderId: purchaseOrder.id,
+        },
+      });
+    }
+
+    return artifacts;
+  }
+}
+
+class TranscriptContextTool extends ContextTool<{ transcriptId: string }> {
+  name(): string {
+    return 'transcript';
+  }
+
+  protected async produceArtifacts(input: { transcriptId: string }): Promise<ContextRetrievalArtifact[]> {
+    const transcript = await getTranscript(input.transcriptId);
+    if (!transcript) {
+      throw new Error(`Transcript ${input.transcriptId} not found`);
+    }
+
+    const agent = await getAgent(transcript.agentId);
+
+    const artifacts: ContextRetrievalArtifact[] = [
+      {
+        type: 'coaching.transcript',
+        content: transcript,
+        promote: true,
+        provenance: {
+          tool: this.name(),
+          transcriptId: input.transcriptId,
+        },
+      },
+    ];
+
+    if (agent) {
+      artifacts.push({
+        type: 'coaching.agent',
+        content: agent,
+        promote: true,
+        provenance: {
+          tool: this.name(),
+          transcriptId: input.transcriptId,
+          stage: 'agent-profile',
+        },
+      });
+    }
+
+    return artifacts;
+  }
+}
+
+export function registerExampleContextProviders(adapter: ExternalContextProviderAdapter): void {
+  const customerTool = new CustomerContextTool();
+  adapter.register(customerTool, {
+    match: directive => directive.startsWith('crm:'),
+    buildInput: directive => {
+      const payload = extractPayload(directive);
+      if (typeof payload !== 'string') {
+        throw new Error(`crm directive expects customer id payload, got ${JSON.stringify(payload)}`);
+      }
+      return { customerId: payload };
+    },
+    describe: 'CRM customer profile loader',
+  });
+
+  const policyTool = new PolicyContextTool();
+  adapter.register(policyTool, {
+    match: directive => directive.startsWith('policy:'),
+    buildInput: directive => {
+      const payload = extractPayload(directive);
+      if (typeof payload !== 'string') {
+        throw new Error(`policy directive expects benefit code payload`);
+      }
+      return { benefitCode: payload };
+    },
+    describe: 'Entitlement policy lookup',
+  });
+
+  const knowledgeTool = new KnowledgeContextTool();
+  adapter.register(knowledgeTool, {
+    match: directive => directive.startsWith('kb:'),
+    buildInput: directive => {
+      const payload = extractPayload(directive);
+      if (typeof payload !== 'string') {
+        throw new Error(`kb directive expects document id payload`);
+      }
+      return { docId: payload };
+    },
+    autoPromote: false,
+    describe: 'Knowledge base snippet fetcher',
+  });
+
+  const incidentTool = new IncidentContextTool();
+  adapter.register(incidentTool, {
+    match: directive => directive.startsWith('inc:'),
+    buildInput: directive => {
+      const payload = extractPayload(directive);
+      if (typeof payload !== 'string') {
+        throw new Error('inc directive expects incident id payload');
+      }
+      return { incidentId: payload };
+    },
+    describe: 'Incident record retrieval',
+  });
+
+  const routingTool = new RoutingContextTool();
+  adapter.register(routingTool, {
+    match: directive => directive.startsWith('routing:'),
+    buildInput: directive => {
+      const payload = extractPayload(directive);
+      if (typeof payload === 'string') {
+        return { incidentId: payload };
+      }
+      if (payload && typeof payload === 'object' && typeof payload.incidentId === 'string') {
+        return {
+          incidentId: payload.incidentId,
+          severity: typeof payload.severity === 'string' ? payload.severity : undefined,
+        };
+      }
+      throw new Error('routing directive expects incident id payload');
+    },
+    describe: 'Routing rule lookup',
+  });
+
+  const invoiceTool = new InvoiceContextTool();
+  adapter.register(invoiceTool, {
+    match: directive => directive.startsWith('erp:'),
+    buildInput: directive => {
+      const payload = extractPayload(directive);
+      if (typeof payload === 'string') {
+        return { invoiceId: payload };
+      }
+      if (payload && typeof payload === 'object' && typeof payload.invoiceId === 'string') {
+        return { invoiceId: payload.invoiceId };
+      }
+      throw new Error('erp directive expects invoice id payload');
+    },
+    describe: 'ERP invoice + purchase order fetcher',
+  });
+
+  const transcriptTool = new TranscriptContextTool();
+  adapter.register(transcriptTool, {
+    match: directive => directive.startsWith('transcript:'),
+    buildInput: directive => {
+      const payload = extractPayload(directive);
+      if (typeof payload !== 'string') {
+        throw new Error('transcript directive expects transcript id payload');
+      }
+      return { transcriptId: payload };
+    },
+    describe: 'Contact center transcript loader',
+  });
+}

package/src/context/index.ts

@@ -0,0 +1 @@
+export { registerExampleContextProviders } from './directives.js';

package/src/data/coaching.ts

@@ -0,0 +1,50 @@
+import { loadJson } from './loader.js';
+
+export interface CoachingTranscript {
+  id: string;
+  agentId: string;
+  customerSentiment: 'POSITIVE' | 'NEUTRAL' | 'NEGATIVE';
+  complianceFlags: string[];
+  transcript: string[];
+  callDurationSeconds: number;
+  followUpRequired: boolean;
+}
+
+export interface AgentProfile {
+  id: string;
+  name: string;
+  region: string;
+  tenureMonths: number;
+  managerEmail: string;
+}
+
+interface CoachingData {
+  transcripts: CoachingTranscript[];
+  agents: AgentProfile[];
+}
+
+let cache: CoachingData | null = null;
+
+async function loadData(): Promise<CoachingData> {
+  if (cache) {
+    return cache;
+  }
+
+  const [transcripts, agents] = await Promise.all([
+    loadJson<CoachingTranscript[]>('data/coaching/transcripts.json'),
+    loadJson<AgentProfile[]>('data/coaching/agents.json'),
+  ]);
+
+  cache = { transcripts, agents };
+  return cache;
+}
+
+export async function getTranscript(id: string): Promise<CoachingTranscript | undefined> {
+  const { transcripts } = await loadData();
+  return transcripts.find(item => item.id === id);
+}
+
+export async function getAgent(agentId: string): Promise<AgentProfile | undefined> {
+  const { agents } = await loadData();
+  return agents.find(agent => agent.id === agentId);
+}

package/src/data/entitlement.ts

@@ -0,0 +1,60 @@
+import { loadJson } from './loader.js';
+
+export interface CustomerProfile {
+  id: string;
+  name: string;
+  tier: 'STANDARD' | 'GOLD' | 'PLATINUM';
+  accountAgeDays: number;
+  complianceFlags: string[];
+  benefits: string[];
+  supervisor: {
+    name: string;
+    email: string;
+  };
+}
+
+export interface EntitlementPolicy {
+  id: string;
+  benefitCode: string;
+  description: string;
+  requiredTier: 'STANDARD' | 'GOLD' | 'PLATINUM';
+  minAccountAgeDays: number;
+  requiresComplianceClearance: boolean;
+  slaMinutes: number;
+}
+
+interface EntitlementData {
+  customers: CustomerProfile[];
+  policies: EntitlementPolicy[];
+}
+
+let cachedData: EntitlementData | null = null;
+
+async function loadData(): Promise<EntitlementData> {
+  if (cachedData) {
+    return cachedData;
+  }
+
+  const [customers, policies] = await Promise.all([
+    loadJson<CustomerProfile[]>('data/entitlement/customers.json'),
+    loadJson<EntitlementPolicy[]>('data/entitlement/policies.json'),
+  ]);
+
+  cachedData = { customers, policies };
+  return cachedData;
+}
+
+export async function getCustomerProfile(customerId: string): Promise<CustomerProfile | undefined> {
+  const { customers } = await loadData();
+  return customers.find(c => c.id === customerId);
+}
+
+export async function getPolicy(benefitCode: string): Promise<EntitlementPolicy | undefined> {
+  const { policies } = await loadData();
+  return policies.find(p => p.benefitCode === benefitCode);
+}
+
+export async function listPolicies(): Promise<EntitlementPolicy[]> {
+  const { policies } = await loadData();
+  return policies;
+}

package/src/data/incidents.ts

@@ -0,0 +1,78 @@
+import { loadJson } from './loader.js';
+
+export type IncidentSeverity = 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL';
+
+export interface IncidentRecord {
+  id: string;
+  service: string;
+  reportedAt: string;
+  customerImpact: 'NONE' | 'MINOR' | 'MAJOR';
+  category: 'PERFORMANCE' | 'OUTAGE' | 'SECURITY' | 'QUALITY';
+  signalScore: number;
+  declaredSeverity: IncidentSeverity;
+  vipCustomer?: boolean;
+}
+
+export interface RoutingRule {
+  id: string;
+  service: string;
+  category: IncidentRecord['category'];
+  minSeverity: IncidentSeverity;
+  queue: string;
+  escalatesTo?: string;
+  notes?: string;
+}
+
+interface IncidentData {
+  incidents: IncidentRecord[];
+  routing: RoutingRule[];
+}
+
+let cache: IncidentData | null = null;
+
+async function loadData(): Promise<IncidentData> {
+  if (cache) {
+    return cache;
+  }
+
+  const [incidents, routing] = await Promise.all([
+    loadJson<IncidentRecord[]>('data/incidents/incidents.json'),
+    loadJson<RoutingRule[]>('data/incidents/routing_rules.json'),
+  ]);
+
+  cache = { incidents, routing };
+  return cache;
+}
+
+export async function getIncident(incidentId: string): Promise<IncidentRecord | undefined> {
+  const { incidents } = await loadData();
+  return incidents.find(item => item.id === incidentId);
+}
+
+function severityRank(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 async function findRoutingRule(
+  incident: IncidentRecord,
+  severityOverride?: IncidentSeverity,
+): Promise<RoutingRule | undefined> {
+  const { routing } = await loadData();
+  const effectiveSeverity = severityOverride ?? incident.declaredSeverity;
+  const effectiveRank = severityRank(effectiveSeverity);
+
+  const candidates = routing.filter(rule =>
+    rule.service === incident.service &&
+    rule.category === incident.category &&
+    severityRank(rule.minSeverity) <= effectiveRank,
+  );
+
+  candidates.sort((a, b) => severityRank(b.minSeverity) - severityRank(a.minSeverity));
+  return candidates[0];
+}

package/src/data/invoices.ts

@@ -0,0 +1,103 @@
+import { loadJson } from './loader.js';
+
+export interface InvoiceLine {
+  sku: string;
+  description: string;
+  quantity: number;
+  unitPrice: number;
+}
+
+export interface InvoiceRecord {
+  id: string;
+  supplier: string;
+  total: number;
+  currency: string;
+  purchaseOrderId: string;
+  receivedAt: string;
+  lines: InvoiceLine[];
+}
+
+export interface PurchaseOrderRecord {
+  id: string;
+  initiator: string;
+  department: string;
+  total: number;
+  currency: string;
+  status: string;
+  lines: InvoiceLine[];
+}
+
+interface InvoiceData {
+  invoices: InvoiceRecord[];
+  purchaseOrders: PurchaseOrderRecord[];
+}
+
+let cached: InvoiceData | null = null;
+
+async function loadData(): Promise<InvoiceData> {
+  if (cached) {
+    return cached;
+  }
+
+  const [invoices, purchaseOrders] = await Promise.all([
+    loadJson<InvoiceRecord[]>('data/invoices/invoices.json'),
+    loadJson<PurchaseOrderRecord[]>('data/invoices/purchase-orders.json'),
+  ]);
+
+  cached = { invoices, purchaseOrders };
+  return cached;
+}
+
+export async function getInvoice(invoiceId: string): Promise<InvoiceRecord | undefined> {
+  const { invoices } = await loadData();
+  return invoices.find(inv => inv.id === invoiceId);
+}
+
+export async function getPurchaseOrder(poId: string): Promise<PurchaseOrderRecord | undefined> {
+  const { purchaseOrders } = await loadData();
+  return purchaseOrders.find(po => po.id === poId);
+}
+
+export function compareLineItems(invoice: InvoiceRecord, po: PurchaseOrderRecord): Array<{
+  sku: string;
+  expectedQuantity: number;
+  actualQuantity: number;
+  expectedPrice: number;
+  actualPrice: number;
+}> {
+  const discrepancies: Array<{
+    sku: string;
+    expectedQuantity: number;
+    actualQuantity: number;
+    expectedPrice: number;
+    actualPrice: number;
+  }> = [];
+
+  const poLines = new Map(po.lines.map(line => [line.sku, line]));
+
+  for (const invLine of invoice.lines) {
+    const poLine = poLines.get(invLine.sku);
+    if (!poLine) {
+      discrepancies.push({
+        sku: invLine.sku,
+        expectedQuantity: 0,
+        actualQuantity: invLine.quantity,
+        expectedPrice: 0,
+        actualPrice: invLine.unitPrice,
+      });
+      continue;
+    }
+
+    if (poLine.quantity !== invLine.quantity || poLine.unitPrice !== invLine.unitPrice) {
+      discrepancies.push({
+        sku: invLine.sku,
+        expectedQuantity: poLine.quantity,
+        actualQuantity: invLine.quantity,
+        expectedPrice: poLine.unitPrice,
+        actualPrice: invLine.unitPrice,
+      });
+    }
+  }
+
+  return discrepancies;
+}