digital-workers 0.1.1 → 2.0.2

package/src/generate.ts

@@ -0,0 +1,364 @@
+/**
+ * Content generation functionality for digital workers
+ */
+
+import { generateObject, generateText } from 'ai-functions'
+import type { SimpleSchema } from 'ai-functions'
+import type { GenerateResult, GenerateOptions } from './types.js'
+
+/**
+ * Generate content
+ *
+ * Uses AI to generate various types of content including text,
+ * code, structured data, images, video, and audio.
+ *
+ * @param prompt - What to generate
+ * @param options - Generation options
+ * @returns Promise resolving to generated content
+ *
+ * @example
+ * ```ts
+ * // Generate text content
+ * const result = await generate('Write a product description for wireless earbuds', {
+ *   type: 'text',
+ *   instructions: 'Focus on sound quality and battery life. Keep it under 100 words.',
+ * })
+ * console.log(result.content)
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Generate structured data
+ * const result = await generate('Create a user profile', {
+ *   type: 'structured',
+ *   schema: {
+ *     name: 'User full name',
+ *     email: 'Email address',
+ *     role: 'admin | user | guest',
+ *     preferences: {
+ *       theme: 'light | dark',
+ *       notifications: 'Whether to receive notifications (boolean)',
+ *     },
+ *   },
+ * })
+ * console.log(result.content) // { name: '...', email: '...', ... }
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Generate code
+ * const result = await generate('Create a React component for a todo list', {
+ *   type: 'code',
+ *   instructions: 'Use TypeScript and hooks. Include prop types.',
+ * })
+ * console.log(result.content) // TypeScript React component code
+ * ```
+ */
+export async function generate<T = string>(
+  prompt: string,
+  options: GenerateOptions = {}
+): Promise<GenerateResult<T>> {
+  const {
+    type = 'text',
+    schema,
+    instructions,
+    model = 'sonnet',
+  } = options
+
+  const startTime = Date.now()
+
+  switch (type) {
+    case 'text': {
+      const systemPrompt = instructions
+        ? `You are an expert content generator. ${instructions}`
+        : 'You are an expert content generator.'
+
+      const result = await generateText({
+        model,
+        prompt,
+        system: systemPrompt,
+      })
+
+      return {
+        content: result.text as T,
+        type: 'text',
+        metadata: {
+          model,
+          tokens: result.usage?.totalTokens,
+          duration: Date.now() - startTime,
+        },
+      }
+    }
+
+    case 'structured': {
+      if (!schema) {
+        throw new Error('Schema is required for structured content generation')
+      }
+
+      const systemPrompt = instructions
+        ? `You are an expert at generating structured data. ${instructions}`
+        : 'You are an expert at generating structured data.'
+
+      const result = await generateObject({
+        model,
+        schema,
+        prompt,
+        system: systemPrompt,
+      })
+
+      return {
+        content: result.object as T,
+        type: 'structured',
+        metadata: {
+          model,
+          tokens: result.usage?.totalTokens,
+          duration: Date.now() - startTime,
+        },
+      }
+    }
+
+    case 'code': {
+      const systemPrompt = instructions
+        ? `You are an expert programmer. Generate clean, well-documented code. ${instructions}`
+        : 'You are an expert programmer. Generate clean, well-documented code.'
+
+      const result = await generateObject({
+        model,
+        schema: {
+          code: 'The generated code',
+          language: 'Programming language used',
+          explanation: 'Brief explanation of the code',
+        },
+        prompt,
+        system: systemPrompt,
+      })
+
+      const codeResult = result.object as {
+        code: string
+        language: string
+        explanation: string
+      }
+
+      return {
+        content: codeResult.code as T,
+        type: 'code',
+        metadata: {
+          model,
+          tokens: result.usage?.totalTokens,
+          duration: Date.now() - startTime,
+          language: codeResult.language,
+          explanation: codeResult.explanation,
+        },
+      }
+    }
+
+    case 'image': {
+      // Image generation would integrate with image generation APIs
+      // For now, return a placeholder
+      throw new Error('Image generation not yet implemented')
+    }
+
+    case 'video': {
+      // Video generation would integrate with video generation APIs
+      throw new Error('Video generation not yet implemented')
+    }
+
+    case 'audio': {
+      // Audio generation would integrate with audio generation APIs
+      throw new Error('Audio generation not yet implemented')
+    }
+
+    default:
+      throw new Error(`Unknown content type: ${type}`)
+  }
+}
+
+/**
+ * Generate multiple variations of content
+ *
+ * @param prompt - What to generate
+ * @param count - Number of variations to generate
+ * @param options - Generation options
+ * @returns Promise resolving to array of generated content
+ *
+ * @example
+ * ```ts
+ * const variations = await generate.variations(
+ *   'Write a catchy headline for a coffee shop',
+ *   5,
+ *   { type: 'text' }
+ * )
+ *
+ * variations.forEach((v, i) => {
+ *   console.log(`${i + 1}. ${v.content}`)
+ * })
+ * ```
+ */
+generate.variations = async <T = string>(
+  prompt: string,
+  count: number,
+  options: GenerateOptions = {}
+): Promise<Array<GenerateResult<T>>> => {
+  return Promise.all(
+    Array.from({ length: count }, () => generate<T>(prompt, options))
+  )
+}
+
+/**
+ * Generate content with a specific tone
+ *
+ * @param prompt - What to generate
+ * @param tone - The desired tone
+ * @param options - Generation options
+ * @returns Promise resolving to generated content
+ *
+ * @example
+ * ```ts
+ * const professional = await generate.withTone(
+ *   'Write an email declining a meeting',
+ *   'professional',
+ *   { type: 'text' }
+ * )
+ *
+ * const friendly = await generate.withTone(
+ *   'Write an email declining a meeting',
+ *   'friendly',
+ *   { type: 'text' }
+ * )
+ * ```
+ */
+generate.withTone = async <T = string>(
+  prompt: string,
+  tone: 'professional' | 'casual' | 'friendly' | 'formal' | 'humorous' | 'empathetic',
+  options: GenerateOptions = {}
+): Promise<GenerateResult<T>> => {
+  const toneInstructions = {
+    professional: 'Use a professional, business-appropriate tone.',
+    casual: 'Use a casual, conversational tone.',
+    friendly: 'Use a warm, friendly tone.',
+    formal: 'Use a formal, ceremonious tone.',
+    humorous: 'Use a light, humorous tone.',
+    empathetic: 'Use an empathetic, understanding tone.',
+  }
+
+  return generate<T>(prompt, {
+    ...options,
+    instructions: `${toneInstructions[tone]} ${options.instructions || ''}`,
+  })
+}
+
+/**
+ * Generate content for a specific audience
+ *
+ * @param prompt - What to generate
+ * @param audience - Target audience
+ * @param options - Generation options
+ * @returns Promise resolving to generated content
+ *
+ * @example
+ * ```ts
+ * const technical = await generate.forAudience(
+ *   'Explain how OAuth works',
+ *   'software engineers',
+ *   { type: 'text' }
+ * )
+ *
+ * const nonTechnical = await generate.forAudience(
+ *   'Explain how OAuth works',
+ *   'non-technical business users',
+ *   { type: 'text' }
+ * )
+ * ```
+ */
+generate.forAudience = async <T = string>(
+  prompt: string,
+  audience: string,
+  options: GenerateOptions = {}
+): Promise<GenerateResult<T>> => {
+  return generate<T>(prompt, {
+    ...options,
+    instructions: `Write for ${audience}. ${options.instructions || ''}`,
+  })
+}
+
+/**
+ * Generate content with specific length
+ *
+ * @param prompt - What to generate
+ * @param length - Desired length
+ * @param options - Generation options
+ * @returns Promise resolving to generated content
+ *
+ * @example
+ * ```ts
+ * const short = await generate.withLength(
+ *   'Describe our company',
+ *   'short',
+ *   { type: 'text' }
+ * )
+ *
+ * const detailed = await generate.withLength(
+ *   'Describe our company',
+ *   'detailed',
+ *   { type: 'text' }
+ * )
+ * ```
+ */
+generate.withLength = async <T = string>(
+  prompt: string,
+  length: 'brief' | 'short' | 'medium' | 'long' | 'detailed',
+  options: GenerateOptions = {}
+): Promise<GenerateResult<T>> => {
+  const lengthInstructions = {
+    brief: 'Keep it very brief - 1-2 sentences maximum.',
+    short: 'Keep it short - around 50-100 words.',
+    medium: 'Use a medium length - around 150-300 words.',
+    long: 'Write a longer piece - around 400-600 words.',
+    detailed: 'Write a detailed, comprehensive piece - 800+ words.',
+  }
+
+  return generate<T>(prompt, {
+    ...options,
+    instructions: `${lengthInstructions[length]} ${options.instructions || ''}`,
+  })
+}
+
+/**
+ * Generate content by iteratively refining it
+ *
+ * @param prompt - What to generate
+ * @param refinements - Refinement prompts to apply
+ * @param options - Generation options
+ * @returns Promise resolving to refined content
+ *
+ * @example
+ * ```ts
+ * const refined = await generate.refine(
+ *   'Write a product tagline',
+ *   [
+ *     'Make it more memorable',
+ *     'Add a sense of urgency',
+ *     'Emphasize the value proposition',
+ *   ],
+ *   { type: 'text' }
+ * )
+ * ```
+ */
+generate.refine = async <T = string>(
+  prompt: string,
+  refinements: string[],
+  options: GenerateOptions = {}
+): Promise<GenerateResult<T>> => {
+  // Generate initial content
+  let result = await generate<T>(prompt, options)
+
+  // Apply refinements iteratively
+  for (const refinement of refinements) {
+    result = await generate<T>(
+      `Refine the following content: ${result.content}\n\nRefinement: ${refinement}`,
+      options
+    )
+  }
+
+  return result
+}

package/src/goals.ts

@@ -0,0 +1,220 @@
+/**
+ * Goals definition for digital workers
+ */
+
+import type { WorkerGoals, KPI } from './types.js'
+
+/**
+ * Define worker goals
+ *
+ * Goals provide direction and metrics for workers and teams.
+ * Supports short-term, long-term, and strategic objectives with KPIs.
+ *
+ * @param definition - Goals definition
+ * @returns The defined goals
+ *
+ * @example
+ * ```ts
+ * const engineeringGoals = Goals({
+ *   shortTerm: [
+ *     'Complete Q1 roadmap features',
+ *     'Reduce bug backlog by 30%',
+ *     'Improve test coverage to 80%',
+ *   ],
+ *   longTerm: [
+ *     'Migrate to microservices architecture',
+ *     'Achieve 99.9% uptime',
+ *     'Build scalable platform for 1M users',
+ *   ],
+ *   strategic: [
+ *     'Become industry leader in performance',
+ *     'Enable product innovation through technology',
+ *   ],
+ *   metrics: [
+ *     {
+ *       name: 'Deployment Frequency',
+ *       description: 'Number of deployments per week',
+ *       current: 5,
+ *       target: 10,
+ *       unit: 'deploys/week',
+ *       trend: 'up',
+ *       period: 'weekly',
+ *     },
+ *     {
+ *       name: 'Mean Time to Recovery',
+ *       description: 'Average time to recover from incidents',
+ *       current: 45,
+ *       target: 30,
+ *       unit: 'minutes',
+ *       trend: 'down',
+ *       period: 'monthly',
+ *     },
+ *   ],
+ * })
+ * ```
+ *
+ * @example
+ * ```ts
+ * const supportGoals = Goals({
+ *   shortTerm: [
+ *     'Achieve 95% customer satisfaction',
+ *     'Reduce average response time to < 5 min',
+ *   ],
+ *   longTerm: [
+ *     'Build comprehensive knowledge base',
+ *     'Implement AI-first support workflow',
+ *   ],
+ *   metrics: [
+ *     {
+ *       name: 'Customer Satisfaction',
+ *       description: 'CSAT score from surveys',
+ *       current: 92,
+ *       target: 95,
+ *       unit: '%',
+ *       trend: 'up',
+ *       period: 'monthly',
+ *     },
+ *   ],
+ * })
+ * ```
+ */
+export function Goals(definition: WorkerGoals): WorkerGoals {
+  return definition
+}
+
+/**
+ * Add a short-term goal
+ *
+ * @param goals - The goals object
+ * @param goal - Goal to add
+ * @returns Updated goals
+ *
+ * @example
+ * ```ts
+ * const updated = Goals.addShortTerm(engineeringGoals, 'Complete security audit')
+ * ```
+ */
+Goals.addShortTerm = (goals: WorkerGoals, goal: string): WorkerGoals => ({
+  ...goals,
+  shortTerm: [...goals.shortTerm, goal],
+})
+
+/**
+ * Add a long-term goal
+ *
+ * @param goals - The goals object
+ * @param goal - Goal to add
+ * @returns Updated goals
+ *
+ * @example
+ * ```ts
+ * const updated = Goals.addLongTerm(engineeringGoals, 'Build ML platform')
+ * ```
+ */
+Goals.addLongTerm = (goals: WorkerGoals, goal: string): WorkerGoals => ({
+  ...goals,
+  longTerm: [...goals.longTerm, goal],
+})
+
+/**
+ * Add a strategic goal
+ *
+ * @param goals - The goals object
+ * @param goal - Goal to add
+ * @returns Updated goals
+ *
+ * @example
+ * ```ts
+ * const updated = Goals.addStrategic(engineeringGoals, 'Become carbon neutral')
+ * ```
+ */
+Goals.addStrategic = (goals: WorkerGoals, goal: string): WorkerGoals => ({
+  ...goals,
+  strategic: [...(goals.strategic || []), goal],
+})
+
+/**
+ * Add a KPI metric
+ *
+ * @param goals - The goals object
+ * @param kpi - KPI to add
+ * @returns Updated goals
+ *
+ * @example
+ * ```ts
+ * const updated = Goals.addMetric(engineeringGoals, {
+ *   name: 'Code Quality',
+ *   description: 'Code quality score from SonarQube',
+ *   current: 85,
+ *   target: 90,
+ *   unit: 'score',
+ *   trend: 'up',
+ *   period: 'weekly',
+ * })
+ * ```
+ */
+Goals.addMetric = (goals: WorkerGoals, kpi: KPI): WorkerGoals => ({
+  ...goals,
+  metrics: [...(goals.metrics || []), kpi],
+})
+
+/**
+ * Update a KPI metric
+ *
+ * @param goals - The goals object
+ * @param name - Name of KPI to update
+ * @param updates - Fields to update
+ * @returns Updated goals
+ *
+ * @example
+ * ```ts
+ * const updated = Goals.updateMetric(engineeringGoals, 'Deployment Frequency', {
+ *   current: 8,
+ *   trend: 'up',
+ * })
+ * ```
+ */
+Goals.updateMetric = (
+  goals: WorkerGoals,
+  name: string,
+  updates: Partial<Omit<KPI, 'name'>>
+): WorkerGoals => ({
+  ...goals,
+  metrics: goals.metrics?.map((kpi) =>
+    kpi.name === name ? { ...kpi, ...updates } : kpi
+  ),
+})
+
+/**
+ * Get progress for a KPI (0-1)
+ *
+ * @param kpi - The KPI
+ * @returns Progress value between 0 and 1
+ *
+ * @example
+ * ```ts
+ * const kpi = { current: 75, target: 100 }
+ * const progress = Goals.progress(kpi) // 0.75
+ * ```
+ */
+Goals.progress = (kpi: Pick<KPI, 'current' | 'target'>): number => {
+  if (kpi.target === 0) return 0
+  return Math.min(1, Math.max(0, kpi.current / kpi.target))
+}
+
+/**
+ * Check if a KPI is on track
+ *
+ * @param kpi - The KPI
+ * @param threshold - Minimum progress to be considered "on track" (default: 0.8)
+ * @returns Whether the KPI is on track
+ *
+ * @example
+ * ```ts
+ * const kpi = { current: 85, target: 100 }
+ * const onTrack = Goals.onTrack(kpi) // true (85% >= 80% threshold)
+ * ```
+ */
+Goals.onTrack = (kpi: Pick<KPI, 'current' | 'target'>, threshold = 0.8): boolean => {
+  return Goals.progress(kpi) >= threshold
+}

package/src/index.ts

@@ -0,0 +1,118 @@
+/**
+ * digital-workers - Abstract interface for organizing digital work
+ *
+ * This package provides the foundational abstraction for structuring work
+ * independent of whether AI agents or humans perform individual tasks. It
+ * defines a unified Worker interface that enables workflows to be designed
+ * once and executed by any combination of AI and human workers.
+ *
+ * Package relationships:
+ * - `autonomous-agents` - Implements Worker for AI agents
+ * - `human-in-the-loop` - Implements Worker for humans
+ * - `ai-workflows` - Uses digital-workers to orchestrate execution
+ *
+ * The key insight: define WHAT work needs to happen, not WHO does it.
+ *
+ * ## Worker Actions
+ *
+ * Worker actions (notify, ask, approve, decide, do) are durable workflow actions
+ * that integrate with ai-workflows. They can be invoked via:
+ *
+ * 1. `$.do('Worker.notify', data)` - Durable action
+ * 2. `$.send('Worker.notify', data)` - Fire and forget
+ * 3. `$.notify(target, message)` - Convenience method (when using withWorkers)
+ *
+ * @example
+ * ```ts
+ * import { Workflow } from 'ai-workflows'
+ * import { registerWorkerActions, withWorkers } from 'digital-workers'
+ *
+ * const workflow = Workflow($ => {
+ *   registerWorkerActions($)
+ *   const worker$ = withWorkers($)
+ *
+ *   $.on.Expense.submitted(async (expense) => {
+ *     await worker$.notify(finance, `New expense: ${expense.amount}`)
+ *
+ *     const approval = await worker$.approve(
+ *       `Expense: $${expense.amount}`,
+ *       manager,
+ *       { via: 'slack' }
+ *     )
+ *
+ *     if (approval.approved) {
+ *       await worker$.notify(expense.submitter, 'Expense approved!')
+ *     }
+ *   })
+ * })
+ * ```
+ *
+ * @packageDocumentation
+ */
+
+// Export all types
+export type * from './types.js'
+
+// Export workflow integration
+export {
+  registerWorkerActions,
+  withWorkers,
+  handleNotify,
+  handleAsk,
+  handleApprove,
+  handleDecide,
+  handleDo,
+  notify as notifyAction,
+  ask as askAction,
+  approve as approveAction,
+  decide as decideAction,
+} from './actions.js'
+
+// Export core functions
+export { Role } from './role.js'
+export { Team } from './team.js'
+export { Goals } from './goals.js'
+export { approve } from './approve.js'
+export { ask } from './ask.js'
+export { do } from './do.js'
+export { decide } from './decide.js'
+export { generate } from './generate.js'
+export { is } from './is.js'
+export { notify } from './notify.js'
+export { kpis, okrs } from './kpis.js'
+
+// Export verb definitions
+export { WorkerVerbs } from './types.js'
+
+// Export transport bridge (connects to digital-tools)
+export type {
+  Transport,
+  TransportConfig,
+  MessagePayload,
+  MessageAction,
+  DeliveryResult,
+  Address,
+  TransportHandler,
+} from './transports.js'
+
+export {
+  channelToTransport,
+  getWorkerTransports,
+  getTeamTransports,
+  resolveAddress,
+  resolveWorkerAddresses,
+  getPrimaryAddress,
+  registerTransport,
+  getTransportHandler,
+  hasTransport,
+  listTransports,
+  sendViaTransport,
+  sendToMultipleTransports,
+  buildNotifyPayload,
+  buildAskPayload,
+  buildApprovePayload,
+  toDigitalToolsMessage,
+  fromDigitalToolsMessage,
+  MessageTypeMapping,
+  CallTypeMapping,
+} from './transports.js'