@ddse/acm-examples 0.5.0

package/src/goals/index.ts

@@ -0,0 +1,18 @@
+// Goal/context index derived from scenario catalog
+import type { Goal, Context } from '@ddse/acm-sdk';
+import { scenarios, type ScenarioKey } from '../examples/scenarios.js';
+
+type GoalMap = Record<ScenarioKey, Goal> & Record<string, Goal>;
+type ContextMap = Record<ScenarioKey, Context> & Record<string, Context>;
+
+export const goals = Object.keys(scenarios).reduce((acc, key) => {
+  const scenario = scenarios[key as ScenarioKey];
+  acc[key] = scenario.goal;
+  return acc;
+}, {} as GoalMap);
+
+export const contexts = Object.keys(scenarios).reduce((acc, key) => {
+  const scenario = scenarios[key as ScenarioKey];
+  acc[key] = scenario.context;
+  return acc;
+}, {} as ContextMap);

package/src/policy.ts

@@ -0,0 +1,30 @@
+// Simple policy engine implementation
+import { PolicyEngine, type PolicyDecision } from '@ddse/acm-sdk';
+
+export class SimplePolicyEngine implements PolicyEngine {
+  async evaluate(
+    action: 'plan.admit' | 'task.pre' | 'task.post',
+    payload: any
+  ): Promise<PolicyDecision> {
+    // Simple rule: deny high-risk refunds
+    if (action === 'task.pre' && payload.action === 'create_refund') {
+      // In a real implementation, we'd check risk from context
+      // For demo, randomly allow/deny based on amount
+      if (payload.amount && payload.amount > 100) {
+        return {
+          allow: false,
+          reason: 'Refund amount exceeds policy limit',
+        };
+      }
+    }
+
+    // Default: allow
+    return {
+      allow: true,
+      limits: {
+        timeoutMs: 30000,
+        retries: 3,
+      },
+    };
+  }
+}

package/src/registries.ts

@@ -0,0 +1,48 @@
+// Concrete registry implementations
+import { CapabilityRegistry, ToolRegistry, type Capability, type Task, type Tool } from '@ddse/acm-sdk';
+
+export class SimpleCapabilityRegistry extends CapabilityRegistry {
+  private tasks = new Map<string, Task>();
+  private capabilities = new Map<string, Capability>();
+
+  register(capability: Capability, task: Task): void {
+    this.capabilities.set(capability.name, capability);
+    this.tasks.set(capability.name, task);
+  }
+
+  list(): Capability[] {
+    return Array.from(this.capabilities.values());
+  }
+
+  has(name: string): boolean {
+    return this.capabilities.has(name);
+  }
+
+  resolve(name: string): Task | undefined {
+    return this.tasks.get(name);
+  }
+
+  inputSchema(name: string): unknown | undefined {
+    return this.capabilities.get(name)?.inputSchema;
+  }
+
+  outputSchema(name: string): unknown | undefined {
+    return this.capabilities.get(name)?.outputSchema;
+  }
+}
+
+export class SimpleToolRegistry extends ToolRegistry {
+  private tools = new Map<string, Tool>();
+
+  register(tool: Tool): void {
+    this.tools.set(tool.name(), tool);
+  }
+
+  get(name: string): Tool | undefined {
+    return this.tools.get(name);
+  }
+
+  list(): string[] {
+    return Array.from(this.tools.keys());
+  }
+}

package/src/renderer.ts

@@ -0,0 +1,82 @@
+// CLI renderer for streaming output
+export class CLIRenderer {
+  private taskStatus = new Map<string, string>();
+
+  renderPlannerToken(chunk: any): void {
+    if (chunk.delta) {
+      process.stdout.write(chunk.delta);
+    }
+
+    const summary: string[] = [];
+    if (typeof chunk.plans === 'number') {
+      const label = chunk.plans === 1 ? 'plan' : 'plans';
+      summary.push(`Generated ${chunk.plans} ${label}.`);
+    }
+    if (chunk.rationale) {
+      summary.push(chunk.rationale);
+    }
+
+    if (summary.length > 0) {
+      process.stdout.write(`\n\n${summary.join('\n\n')}\n\n`);
+    }
+
+    if (chunk.done && summary.length === 0) {
+      process.stdout.write('\n\n');
+    }
+  }
+
+  renderTaskUpdate(update: any): void {
+    const { taskId, status, step, output, error } = update;
+
+    if (status) {
+      this.taskStatus.set(taskId, status);
+    }
+
+    if (status === 'running') {
+      console.log(`\n[${taskId}] Task started`);
+    } else if (status === 'completed') {
+      console.log(`[${taskId}] ✓ Task completed`);
+      if (output) {
+        console.log(`  Output: ${JSON.stringify(output, null, 2)}`);
+      }
+    } else if (status === 'failed') {
+      console.error(`[${taskId}] ✗ Task failed: ${error}`);
+    } else if (step) {
+      console.log(`[${taskId}]   → ${step}`);
+    }
+  }
+
+  renderLedgerEntry(entry: any): void {
+    const icon = this.getIconForType(entry.type);
+    console.log(`${icon} [${entry.type}] ${JSON.stringify(entry.details)}`);
+  }
+
+  renderSummary(result: any): void {
+    console.log('\n' + '='.repeat(60));
+    console.log('EXECUTION SUMMARY');
+    console.log('='.repeat(60));
+    const taskEntries = Object.entries(result.outputsByTask ?? {});
+    const ledgerEntries = Array.isArray(result.ledger) ? result.ledger.length : 0;
+    console.log(`Total tasks: ${taskEntries.length}`);
+    console.log(`Ledger entries: ${ledgerEntries}`);
+    console.log('\nOutputs:');
+    for (const [taskId, record] of taskEntries) {
+      const output = record && typeof record === 'object' && 'output' in record ? record.output : record;
+      console.log(`  ${taskId}:`, JSON.stringify(output, null, 2));
+    }
+  }
+
+  private getIconForType(type: string): string {
+    switch (type) {
+      case 'PLAN_SELECTED': return '📋';
+      case 'GUARD_EVAL': return '🚦';
+      case 'TASK_START': return '▶️ ';
+      case 'TASK_END': return '✅';
+      case 'POLICY_PRE': return '🔒';
+      case 'POLICY_POST': return '🔓';
+      case 'VERIFICATION': return '✔️ ';
+      case 'ERROR': return '❌';
+      default: return '•';
+    }
+  }
+}

package/src/search/bm25.ts

@@ -0,0 +1,173 @@
+// Simple BM25 search implementation for ACM examples
+
+/**
+ * Document interface for BM25 search
+ */
+export interface Document {
+  id: string;
+  title?: string;
+  content: string;
+  [key: string]: any;
+}
+
+/**
+ * Search result with score
+ */
+export interface SearchResult {
+  document: Document;
+  score: number;
+}
+
+/**
+ * BM25 parameters
+ */
+export interface BM25Params {
+  k1?: number; // Term frequency saturation (default: 1.5)
+  b?: number;  // Length normalization (default: 0.75)
+}
+
+/**
+ * Simple tokenizer
+ */
+function tokenize(text?: string | null): string[] {
+  if (!text) return [];
+
+  return text
+    .toLowerCase()
+    .replace(/[^\w\s]/g, ' ')
+    .split(/\s+/)
+    .filter((token) => token.length > 0);
+}
+
+/**
+ * BM25 Search Engine
+ * 
+ * Implements the BM25 ranking function for full-text search.
+ * BM25 is a probabilistic ranking function used by search engines
+ * to estimate the relevance of documents to a query.
+ */
+export class BM25Search {
+  private documents: Document[] = [];
+  private documentTokens: Map<string, string[]> = new Map();
+  private documentFrequency: Map<string, number> = new Map();
+  private averageDocumentLength: number = 0;
+  private k1: number;
+  private b: number;
+
+  constructor(params: BM25Params = {}) {
+    this.k1 = params.k1 ?? 1.5;
+    this.b = params.b ?? 0.75;
+  }
+
+  /**
+   * Index documents for search
+   */
+  index(documents: Document[]): void {
+    this.documents = documents;
+    this.documentTokens.clear();
+    this.documentFrequency.clear();
+
+    // Tokenize documents
+    let totalLength = 0;
+    for (const doc of documents) {
+      const text = this.extractText(doc);
+      const tokens = tokenize(text);
+      this.documentTokens.set(doc.id, tokens);
+      totalLength += tokens.length;
+
+      // Update document frequency
+      const uniqueTokens = new Set(tokens);
+      for (const token of uniqueTokens) {
+        this.documentFrequency.set(token, (this.documentFrequency.get(token) || 0) + 1);
+      }
+    }
+
+    this.averageDocumentLength = totalLength / documents.length;
+  }
+
+  /**
+   * Extract searchable text from document
+   */
+  private extractText(doc: Document): string {
+    const parts: string[] = [];
+    if (doc.title) parts.push(doc.title);
+    if (doc.content) parts.push(doc.content);
+    return parts.join(' ');
+  }
+
+  /**
+   * Calculate IDF (Inverse Document Frequency)
+   */
+  private idf(term: string): number {
+    const df = this.documentFrequency.get(term) || 0;
+    if (df === 0) return 0;
+
+    const n = this.documents.length;
+    return Math.log((n - df + 0.5) / (df + 0.5) + 1);
+  }
+
+  /**
+   * Calculate BM25 score for a document
+   */
+  private score(docId: string, queryTokens: string[]): number {
+    const tokens = this.documentTokens.get(docId);
+    if (!tokens) return 0;
+
+    const docLength = tokens.length;
+    let score = 0;
+
+    for (const queryToken of queryTokens) {
+      const termFreq = tokens.filter((t) => t === queryToken).length;
+      if (termFreq === 0) continue;
+
+      const idf = this.idf(queryToken);
+      const numerator = termFreq * (this.k1 + 1);
+      const denominator = termFreq + this.k1 * (1 - this.b + this.b * (docLength / this.averageDocumentLength));
+
+      score += idf * (numerator / denominator);
+    }
+
+    return score;
+  }
+
+  /**
+   * Search for documents matching the query
+   */
+  search(query: string, limit: number = 10): SearchResult[] {
+    if (this.documents.length === 0) {
+      return [];
+    }
+
+    const queryTokens = tokenize(query);
+    if (queryTokens.length === 0) {
+      return [];
+    }
+
+    // Score all documents
+    const results: SearchResult[] = [];
+    for (const doc of this.documents) {
+      const score = this.score(doc.id, queryTokens);
+      if (score > 0) {
+        results.push({ document: doc, score });
+      }
+    }
+
+    // Sort by score (descending) and limit
+    results.sort((a, b) => b.score - a.score);
+    return results.slice(0, limit);
+  }
+
+  /**
+   * Get all indexed documents
+   */
+  getDocuments(): Document[] {
+    return this.documents;
+  }
+
+  /**
+   * Get document count
+   */
+  getDocumentCount(): number {
+    return this.documents.length;
+  }
+}

package/src/search/index.ts

@@ -0,0 +1,2 @@
+// Search functionality for ACM examples
+export { BM25Search, type Document, type SearchResult, type BM25Params } from './bm25.js';

package/src/tasks/coaching.ts

@@ -0,0 +1,217 @@
+import { Task, type RunContext } from '@ddse/acm-sdk';
+import {
+  type AnalyzeTranscriptInput,
+  type AnalyzeTranscriptOutput,
+  type GenerateFeedbackInput,
+  type GenerateFeedbackOutput,
+  type LogCoachingNoteInput,
+  type LogCoachingNoteOutput,
+} from '../tools/coaching/index.js';
+
+export class AnalyzeTranscriptTask extends Task<
+  AnalyzeTranscriptInput,
+  AnalyzeTranscriptOutput
+> {
+  constructor() {
+    super('task-coaching-analyze-transcript', 'coaching.analyze_transcript');
+  }
+
+  idemKey(_ctx: RunContext, input: AnalyzeTranscriptInput): string | undefined {
+    return input?.transcriptId ? `coaching:transcript:${input.transcriptId}` : undefined;
+  }
+
+  policyInput(_ctx: RunContext, input: AnalyzeTranscriptInput): Record<string, unknown> {
+    return {
+      action: 'analyze_transcript',
+      transcriptId: input.transcriptId,
+    };
+  }
+
+  verification(): string[] {
+    return ['typeof output.sentimentScore === "number"', 'Array.isArray(output.highlights)'];
+  }
+
+  async execute(
+    ctx: RunContext,
+    input: AnalyzeTranscriptInput
+  ): Promise<AnalyzeTranscriptOutput> {
+    const tool = ctx.getTool('analyze_transcript');
+    if (!tool) {
+      throw new Error('analyze_transcript tool is not registered');
+    }
+
+    const result = (await tool.call(input)) as AnalyzeTranscriptOutput;
+    ctx.stream?.emit('task', {
+      taskId: this.id,
+      stage: 'coaching_transcript_analyzed',
+      transcriptId: input.transcriptId,
+      sentimentScore: result.sentimentScore,
+      complianceScore: result.complianceScore,
+    });
+    return result;
+  }
+}
+
+export interface GenerateFeedbackTaskInput {
+  transcriptId?: string;
+  metrics?: GenerateFeedbackInput['metrics'];
+}
+
+export class GenerateFeedbackTask extends Task<
+  GenerateFeedbackTaskInput,
+  GenerateFeedbackOutput
+> {
+  constructor() {
+    super('task-coaching-generate-feedback', 'coaching.generate_feedback');
+  }
+
+  policyInput(ctx: RunContext, input: GenerateFeedbackTaskInput): Record<string, unknown> {
+    const resolved = this.resolveInput(ctx, input);
+    return {
+      action: 'generate_feedback',
+      transcriptId: resolved.transcriptId,
+      metrics: resolved.metrics,
+    };
+  }
+
+  verification(): string[] {
+    return ['typeof output.feedbackSummary === "string"', 'Array.isArray(output.actionItems)'];
+  }
+
+  async execute(
+    ctx: RunContext,
+    input: GenerateFeedbackTaskInput
+  ): Promise<GenerateFeedbackOutput> {
+    const tool = ctx.getTool('generate_feedback');
+    if (!tool) {
+      throw new Error('generate_feedback tool is not registered');
+    }
+
+    const resolved = this.resolveInput(ctx, input);
+    const result = (await tool.call(resolved)) as GenerateFeedbackOutput;
+    ctx.stream?.emit('task', {
+      taskId: this.id,
+      stage: 'coaching_feedback_generated',
+      transcriptId: resolved.transcriptId,
+      escalationRequired: result.escalationRequired,
+    });
+    return result;
+  }
+
+  private resolveInput(
+    ctx: RunContext,
+    input: GenerateFeedbackTaskInput
+  ): GenerateFeedbackInput {
+    const analyzeOutput = ctx.outputs?.['task-coaching-analyze-transcript'] as
+      | AnalyzeTranscriptOutput
+      | undefined;
+
+    const transcriptId =
+      input?.transcriptId ?? analyzeOutput?.transcript?.id;
+    if (!transcriptId) {
+      throw new Error('transcriptId is required for feedback generation');
+    }
+
+    const metrics =
+      input?.metrics ??
+      (analyzeOutput
+        ? {
+            sentimentScore: analyzeOutput.sentimentScore,
+            complianceScore: analyzeOutput.complianceScore,
+            complianceBreaches: analyzeOutput.complianceBreaches,
+            highlights: analyzeOutput.highlights,
+            summary: analyzeOutput.summary,
+          }
+        : undefined);
+
+    if (!metrics) {
+      throw new Error('metrics are required for feedback generation');
+    }
+
+    return {
+      transcriptId,
+      metrics,
+    };
+  }
+}
+
+export interface LogCoachingNoteTaskInput extends Partial<LogCoachingNoteInput> {}
+
+export class LogCoachingNoteTask extends Task<
+  LogCoachingNoteTaskInput,
+  LogCoachingNoteOutput
+> {
+  constructor() {
+    super('task-coaching-log-note', 'coaching.log_note');
+  }
+
+  policyInput(ctx: RunContext, input: LogCoachingNoteTaskInput): Record<string, unknown> {
+    const resolved = this.resolveInput(ctx, input);
+    return {
+      action: 'log_coaching_note',
+      agentId: resolved.agentId,
+      escalationRequired: resolved.escalationRequired,
+    };
+  }
+
+  verification(): string[] {
+    return ['output.stored === true', 'typeof output.logId === "string"'];
+  }
+
+  async execute(
+    ctx: RunContext,
+    input: LogCoachingNoteTaskInput
+  ): Promise<LogCoachingNoteOutput> {
+    const tool = ctx.getTool('log_coaching_note');
+    if (!tool) {
+      throw new Error('log_coaching_note tool is not registered');
+    }
+
+    const resolved = this.resolveInput(ctx, input);
+    const result = (await tool.call(resolved)) as LogCoachingNoteOutput;
+    ctx.stream?.emit('task', {
+      taskId: this.id,
+      stage: 'coaching_note_logged',
+      agentId: resolved.agentId,
+      escalationNotified: result.escalationNotified,
+    });
+    return result;
+  }
+
+  private resolveInput(
+    ctx: RunContext,
+    input: LogCoachingNoteTaskInput
+  ): LogCoachingNoteInput {
+    const analyzeOutput = ctx.outputs?.['task-coaching-analyze-transcript'] as
+      | AnalyzeTranscriptOutput
+      | undefined;
+    const feedbackOutput = ctx.outputs?.['task-coaching-generate-feedback'] as
+      | GenerateFeedbackOutput
+      | undefined;
+
+    const agentId = input.agentId ?? analyzeOutput?.transcript?.agentId;
+    if (!agentId) {
+      throw new Error('agentId is required to log coaching note');
+    }
+
+    const feedbackSummary = input.feedbackSummary ?? feedbackOutput?.feedbackSummary;
+    if (!feedbackSummary) {
+      throw new Error('feedbackSummary is required to log coaching note');
+    }
+
+    const actionItems = input.actionItems ?? feedbackOutput?.actionItems;
+    if (!actionItems) {
+      throw new Error('actionItems are required to log coaching note');
+    }
+
+    const escalationRequired =
+      input.escalationRequired ?? feedbackOutput?.escalationRequired ?? false;
+
+    return {
+      agentId,
+      feedbackSummary,
+      actionItems,
+      escalationRequired,
+    };
+  }
+}