@ddse/acm-examples 0.5.0

package/src/tasks/invoices.ts

@@ -0,0 +1,269 @@
+import { Task, type RunContext } from '@ddse/acm-sdk';
+import type { InvoiceRecord, PurchaseOrderRecord } from '../data/invoices.js';
+import {
+  type FetchInvoiceInput,
+  type FetchInvoiceOutput,
+  type FetchPurchaseOrderInput,
+  type FetchPurchaseOrderOutput,
+  type CompareLineItemsInput,
+  type CompareLineItemsOutput,
+  type RecordFindingsInput,
+  type RecordFindingsOutput,
+} from '../tools/invoices/index.js';
+
+export class FetchInvoiceTask extends Task<FetchInvoiceInput, FetchInvoiceOutput> {
+  constructor() {
+    super('task-invoice-fetch', 'invoice.fetch');
+  }
+
+  idemKey(_ctx: RunContext, input: FetchInvoiceInput): string | undefined {
+    return input?.invoiceId ? `invoice:${input.invoiceId}` : undefined;
+  }
+
+  policyInput(_ctx: RunContext, input: FetchInvoiceInput): Record<string, unknown> {
+    return {
+      action: 'fetch_invoice',
+      invoiceId: input.invoiceId,
+    };
+  }
+
+  verification(): string[] {
+    return ['output.invoice !== undefined'];
+  }
+
+  async execute(
+    ctx: RunContext,
+    input: FetchInvoiceInput
+  ): Promise<FetchInvoiceOutput> {
+    const tool = ctx.getTool('fetch_invoice');
+    if (!tool) {
+      throw new Error('fetch_invoice tool is not registered');
+    }
+
+    const result = (await tool.call(input)) as FetchInvoiceOutput;
+    ctx.stream?.emit('task', {
+      taskId: this.id,
+      stage: 'invoice_loaded',
+      invoiceId: input.invoiceId,
+    });
+    return result;
+  }
+}
+
+export class FetchPurchaseOrderTask extends Task<
+  FetchPurchaseOrderInput,
+  FetchPurchaseOrderOutput
+> {
+  constructor() {
+    super('task-invoice-fetch-po', 'invoice.fetch_purchase_order');
+  }
+
+  idemKey(_ctx: RunContext, input: FetchPurchaseOrderInput): string | undefined {
+    return input?.purchaseOrderId ? `purchase-order:${input.purchaseOrderId}` : undefined;
+  }
+
+  policyInput(_ctx: RunContext, input: FetchPurchaseOrderInput): Record<string, unknown> {
+    return {
+      action: 'fetch_purchase_order',
+      purchaseOrderId: input.purchaseOrderId,
+    };
+  }
+
+  verification(): string[] {
+    return ['output.purchaseOrder !== undefined'];
+  }
+
+  async execute(
+    ctx: RunContext,
+    input: FetchPurchaseOrderInput
+  ): Promise<FetchPurchaseOrderOutput> {
+    const tool = ctx.getTool('fetch_purchase_order');
+    if (!tool) {
+      throw new Error('fetch_purchase_order tool is not registered');
+    }
+
+    const result = (await tool.call(input)) as FetchPurchaseOrderOutput;
+    ctx.stream?.emit('task', {
+      taskId: this.id,
+      stage: 'purchase_order_loaded',
+      purchaseOrderId: input.purchaseOrderId,
+    });
+    return result;
+  }
+}
+
+export interface CompareLineItemsTaskInput extends Partial<CompareLineItemsInput> {
+  invoiceId?: string;
+  purchaseOrderId?: string;
+}
+
+export class CompareLineItemsTask extends Task<
+  CompareLineItemsTaskInput,
+  CompareLineItemsOutput
+> {
+  constructor() {
+    super('task-invoice-compare-lines', 'invoice.compare_line_items');
+  }
+
+  policyInput(_ctx: RunContext, input: CompareLineItemsTaskInput): Record<string, unknown> {
+    const invoice = this.resolveInvoice(_ctx, input);
+    const purchaseOrder = this.resolvePurchaseOrder(_ctx, input);
+    return {
+      action: 'compare_line_items',
+      invoiceId: invoice?.id ?? input.invoiceId,
+      purchaseOrderId: purchaseOrder?.id ?? input.purchaseOrderId,
+    };
+  }
+
+  verification(): string[] {
+    return ['Array.isArray(output.discrepancies)', 'typeof output.variance === "number"'];
+  }
+
+  async execute(
+    ctx: RunContext,
+    input: CompareLineItemsTaskInput
+  ): Promise<CompareLineItemsOutput> {
+    const tool = ctx.getTool('compare_line_items');
+    if (!tool) {
+      throw new Error('compare_line_items tool is not registered');
+    }
+
+    const invoice = this.resolveInvoice(ctx, input);
+    const purchaseOrder = this.resolvePurchaseOrder(ctx, input);
+
+    if (!invoice || !purchaseOrder) {
+      throw new Error('invoice and purchaseOrder are required');
+    }
+
+    const result = (await tool.call({ invoice, purchaseOrder })) as CompareLineItemsOutput;
+    ctx.stream?.emit('task', {
+      taskId: this.id,
+      stage: 'invoice_line_items_compared',
+      invoiceId: invoice.id,
+      purchaseOrderId: purchaseOrder.id,
+      discrepancies: result.discrepancies.length,
+      variance: result.variance,
+    });
+    return result;
+  }
+
+  private resolveInvoice(
+    ctx: RunContext,
+    input: CompareLineItemsTaskInput
+  ): InvoiceRecord | undefined {
+    if (input?.invoice) {
+      return input.invoice;
+    }
+
+    const fetchOutput = ctx.outputs?.['task-invoice-fetch'] as FetchInvoiceOutput | undefined;
+    const invoice = fetchOutput?.invoice;
+    if (!invoice) {
+      return undefined;
+    }
+
+    if (!input?.invoiceId || invoice.id === input.invoiceId) {
+      return invoice;
+    }
+
+    return undefined;
+  }
+
+  private resolvePurchaseOrder(
+    ctx: RunContext,
+    input: CompareLineItemsTaskInput
+  ): PurchaseOrderRecord | undefined {
+    if (input?.purchaseOrder) {
+      return input.purchaseOrder;
+    }
+
+    const fetchOutput = ctx.outputs?.['task-invoice-fetch-po'] as FetchPurchaseOrderOutput | undefined;
+    const purchaseOrder = fetchOutput?.purchaseOrder;
+    if (!purchaseOrder) {
+      return undefined;
+    }
+
+    if (!input?.purchaseOrderId || purchaseOrder.id === input.purchaseOrderId) {
+      return purchaseOrder;
+    }
+
+    return undefined;
+  }
+}
+
+export interface RecordFindingsTaskInput extends Partial<RecordFindingsInput> {
+  invoiceId?: string;
+  purchaseOrderId?: string;
+}
+
+export class RecordFindingsTask extends Task<
+  RecordFindingsTaskInput,
+  RecordFindingsOutput
+> {
+  constructor() {
+    super('task-invoice-record-findings', 'invoice.record_findings');
+  }
+
+  policyInput(_ctx: RunContext, input: RecordFindingsTaskInput): Record<string, unknown> {
+    const resolved = this.resolveInput(_ctx, input);
+    return {
+      action: 'record_findings',
+      invoiceId: resolved.invoice.id,
+      purchaseOrderId: resolved.purchaseOrder.id,
+      discrepancyCount: resolved.discrepancies.length,
+    };
+  }
+
+  verification(): string[] {
+    return ['typeof output.reportId === "string"', 'Array.isArray(output.nextSteps)'];
+  }
+
+  async execute(
+    ctx: RunContext,
+    input: RecordFindingsTaskInput
+  ): Promise<RecordFindingsOutput> {
+    const tool = ctx.getTool('record_findings');
+    if (!tool) {
+      throw new Error('record_findings tool is not registered');
+    }
+
+    const resolved = this.resolveInput(ctx, input);
+
+    const result = (await tool.call(resolved)) as RecordFindingsOutput;
+    ctx.stream?.emit('task', {
+      taskId: this.id,
+      stage: 'invoice_findings_recorded',
+      invoiceId: resolved.invoice.id,
+      purchaseOrderId: resolved.purchaseOrder.id,
+      status: result.status,
+    });
+    return result;
+  }
+
+  private resolveInput(
+    ctx: RunContext,
+    input: RecordFindingsTaskInput
+  ): RecordFindingsInput {
+    const invoice = input.invoice ?? (ctx.outputs?.['task-invoice-fetch'] as FetchInvoiceOutput | undefined)?.invoice;
+    const purchaseOrder =
+      input.purchaseOrder ?? (ctx.outputs?.['task-invoice-fetch-po'] as FetchPurchaseOrderOutput | undefined)?.purchaseOrder;
+    const compareOutput = ctx.outputs?.['task-invoice-compare-lines'] as CompareLineItemsOutput | undefined;
+
+    if (!invoice) {
+      throw new Error('invoice is required for recording findings');
+    }
+
+    if (!purchaseOrder) {
+      throw new Error('purchaseOrder is required for recording findings');
+    }
+
+    const discrepancies = input.discrepancies ?? compareOutput?.discrepancies ?? [];
+    const variance = input.variance ?? compareOutput?.variance ?? 0;
+
+    return {
+      invoice,
+      purchaseOrder,
+      discrepancies,
+      variance,
+    };
+  }
+}

package/src/tasks/knowledge.ts

@@ -0,0 +1,169 @@
+import { Task, type RunContext } from '@ddse/acm-sdk';
+import {
+  type KnowledgeSearchInput,
+  type KnowledgeSearchOutput,
+  type SummarizeSnippetInput,
+  type SummarizeSnippetOutput,
+  type SuggestFollowupsInput,
+  type SuggestFollowupsOutput,
+} from '../tools/knowledge/index.js';
+
+export class SearchKnowledgeTask extends Task<
+  KnowledgeSearchInput,
+  KnowledgeSearchOutput
+> {
+  constructor() {
+    super('task-knowledge-search', 'knowledge.search');
+  }
+
+  idemKey(_ctx: RunContext, input: KnowledgeSearchInput): string | undefined {
+    const query = input?.query?.trim();
+    return query ? `knowledge:search:${query.toLowerCase()}` : undefined;
+  }
+
+  policyInput(_ctx: RunContext, input: KnowledgeSearchInput): Record<string, unknown> {
+    return {
+      action: 'search_knowledge',
+      query: input.query,
+      limit: input.limit,
+    };
+  }
+
+  verification(): string[] {
+    return ['Array.isArray(output.hits)', 'output.hits.length >= 0'];
+  }
+
+  async execute(
+    ctx: RunContext,
+    input: KnowledgeSearchInput
+  ): Promise<KnowledgeSearchOutput> {
+    const tool = ctx.getTool('search_knowledge');
+    if (!tool) {
+      throw new Error('search_knowledge tool is not registered');
+    }
+
+    const result = (await tool.call(input)) as KnowledgeSearchOutput;
+    ctx.stream?.emit('task', {
+      taskId: this.id,
+      stage: 'knowledge_hits_found',
+      hits: result.hits?.map(hit => ({ docId: hit.id, score: hit.score })),
+    });
+    return result;
+  }
+}
+
+export class SummarizeSnippetTask extends Task<
+  SummarizeSnippetInput,
+  SummarizeSnippetOutput
+> {
+  constructor() {
+    super('task-knowledge-summarize', 'knowledge.summarize');
+  }
+
+  policyInput(_ctx: RunContext, input: SummarizeSnippetInput): Record<string, unknown> {
+    return {
+      action: 'summarize_snippet',
+      docId: input.docId,
+      maxSentences: input.maxSentences,
+      focus: input.focus,
+    };
+  }
+
+  verification(): string[] {
+    return ['typeof output.summary === "string"', 'Array.isArray(output.highlights)'];
+  }
+
+  async execute(
+    ctx: RunContext,
+    input: SummarizeSnippetInput
+  ): Promise<SummarizeSnippetOutput> {
+    const tool = ctx.getTool('summarize_snippet');
+    if (!tool) {
+      throw new Error('summarize_snippet tool is not registered');
+    }
+
+    const result = (await tool.call(input)) as SummarizeSnippetOutput;
+    ctx.stream?.emit('task', {
+      taskId: this.id,
+      stage: 'knowledge_snippet_summarized',
+      docId: input.docId,
+      title: result.title,
+    });
+    return result;
+  }
+}
+
+export class SuggestFollowupsTask extends Task<
+  SuggestFollowupsInput,
+  SuggestFollowupsOutput
+> {
+  constructor() {
+    super('task-knowledge-followups', 'knowledge.followups');
+  }
+
+  private resolveDocId(
+    ctx: RunContext,
+    input: SuggestFollowupsInput
+  ): string | undefined {
+    const direct = input?.docId;
+    if (typeof direct === 'string' && direct.trim()) {
+      return direct.trim();
+    }
+
+    const summary = ctx.outputs?.['task-knowledge-summarize'] as
+      | SummarizeSnippetOutput
+      | undefined;
+    const summaryDocId = summary?.docId;
+    if (typeof summaryDocId === 'string' && summaryDocId.trim()) {
+      return summaryDocId.trim();
+    }
+
+    const search = ctx.outputs?.['task-knowledge-search'] as
+      | KnowledgeSearchOutput
+      | undefined;
+    const firstHitId = search?.hits?.[0]?.id;
+    if (typeof firstHitId === 'string' && firstHitId.trim()) {
+      return firstHitId.trim();
+    }
+
+    return undefined;
+  }
+
+  policyInput(_ctx: RunContext, input: SuggestFollowupsInput): Record<string, unknown> {
+    const docId = this.resolveDocId(_ctx, input);
+
+    return {
+      action: 'suggest_followups',
+      docId,
+      context: input.context,
+    };
+  }
+
+  verification(): string[] {
+    return ['Array.isArray(output.suggestions)', 'output.suggestions.length >= 0'];
+  }
+
+  async execute(
+    ctx: RunContext,
+    input: SuggestFollowupsInput
+  ): Promise<SuggestFollowupsOutput> {
+    const tool = ctx.getTool('suggest_followups');
+    if (!tool) {
+      throw new Error('suggest_followups tool is not registered');
+    }
+
+    const docId = this.resolveDocId(ctx, input);
+    if (!docId) {
+      throw new Error('docId is required');
+    }
+
+    const result = (await tool.call({ ...input, docId })) as SuggestFollowupsOutput;
+    ctx.stream?.emit('task', {
+      taskId: this.id,
+      stage: 'knowledge_followups_suggested',
+      docId,
+      suggestionCount: result.suggestions.length,
+    });
+    return result;
+  }
+}

package/src/tasks/legacy.ts

@@ -0,0 +1,112 @@
+import { Task, type RunContext } from '@ddse/acm-sdk';
+
+export class SearchTask extends Task<{ query: string }, { results: string[] }> {
+  constructor() {
+    super('search-task', 'search');
+  }
+
+  async execute(ctx: RunContext, input: { query: string }): Promise<{ results: string[] }> {
+    const tool = ctx.getTool('search');
+    if (!tool) {
+      throw new Error('Search tool not found');
+    }
+
+    const result = await tool.call(input);
+    ctx.stream?.emit('task', { taskId: this.id, step: 'search_complete', results: result });
+    return result;
+  }
+}
+
+export class EnrichAndActTask extends Task<
+  { searchQuery: string; orderId: string },
+  { action: string; details: any }
+> {
+  constructor() {
+    super('enrich-and-act-task', 'enrich_and_act');
+  }
+
+  async execute(
+    ctx: RunContext,
+    input: { searchQuery: string; orderId: string }
+  ): Promise<{ action: string; details: any }> {
+    const searchTool = ctx.getTool('search');
+    if (!searchTool) throw new Error('Search tool not found');
+
+    const searchResult = await searchTool.call({ query: input.searchQuery });
+    ctx.stream?.emit('task', { taskId: this.id, step: 'search_done' });
+
+    const extractTool = ctx.getTool('extract_entities');
+    if (!extractTool) throw new Error('Extract entities tool not found');
+
+    const entities = await extractTool.call({ text: JSON.stringify(searchResult) });
+    ctx.stream?.emit('task', { taskId: this.id, step: 'entities_extracted' });
+
+    const riskTool = ctx.getTool('assess_risk');
+    if (!riskTool) throw new Error('Risk assessment tool not found');
+
+    const risk = await riskTool.call({ context: { entities, orderId: input.orderId } });
+    ctx.stream?.emit('task', { taskId: this.id, step: 'risk_assessed', risk });
+
+    return {
+      action: risk.riskTier === 'HIGH' ? 'ESCALATE' : 'PROCEED',
+      details: { searchResult, entities, risk },
+    };
+  }
+
+  policyInput(ctx: RunContext, input: any): Record<string, unknown> {
+    return {
+      orderId: input.orderId,
+      action: 'enrich_and_assess',
+    };
+  }
+
+  verification(): string[] {
+    return ['output.action !== undefined', 'output.details !== undefined'];
+  }
+}
+
+export class RefundFlowTask extends Task<
+  { orderId: string; amount: number },
+  { transactionId: string; notified: boolean }
+> {
+  constructor() {
+    super('refund-flow-task', 'refund_flow');
+  }
+
+  async execute(
+    ctx: RunContext,
+    input: { orderId: string; amount: number }
+  ): Promise<{ transactionId: string; notified: boolean }> {
+    const refundTool = ctx.getTool('create_refund_txn');
+    if (!refundTool) throw new Error('Refund tool not found');
+
+    const txn = await refundTool.call(input);
+    ctx.stream?.emit('task', { taskId: this.id, step: 'refund_created', txn });
+
+  const notifyTool = ctx.getTool('notify_supervisor_legacy');
+    if (!notifyTool) throw new Error('Notify tool not found');
+
+    const notification = await notifyTool.call({
+      message: `Refund ${txn.transactionId} created for order ${input.orderId}`,
+      channel: 'email',
+    });
+    ctx.stream?.emit('task', { taskId: this.id, step: 'notification_sent' });
+
+    return {
+      transactionId: txn.transactionId,
+      notified: notification.sent,
+    };
+  }
+
+  policyInput(ctx: RunContext, input: any): Record<string, unknown> {
+    return {
+      orderId: input.orderId,
+      amount: input.amount,
+      action: 'create_refund',
+    };
+  }
+
+  verification(): string[] {
+    return ['output.transactionId !== undefined', 'output.notified === true'];
+  }
+}