digital-workers 2.1.1 → 2.3.0

package/src/generate.ts

@@ -1,5 +1,34 @@
 /**
  * Content generation functionality for digital workers
+ *
+ * IMPORTANT: Worker-Context Generation vs Direct LLM Generation
+ * --------------------------------------------------------------
+ * This module provides content generation within a worker context,
+ * with rich metadata about the generation process.
+ *
+ * - `digital-workers.generate()` - Generates content with full metadata
+ *   (tokens used, duration, model info) and supports multiple content types
+ *   including text, code, structured, image, video, and audio.
+ *
+ * - `ai-functions.generate()` - Core generation primitive that powers all
+ *   ai-functions; lower-level function with type-based dispatch.
+ *
+ * The key difference is context and metadata:
+ * - digital-workers returns `GenerateResult<T>` with content + metadata
+ * - ai-functions returns just the generated content
+ *
+ * Use digital-workers when you need:
+ * - Rich metadata about generation (tokens, duration, model)
+ * - Content type variants (text, code, structured, media)
+ * - Tone, audience, and length modifiers
+ * - Iterative refinement workflows
+ *
+ * Use ai-functions when you need:
+ * - Direct LLM generation without metadata
+ * - Template literal syntax (`ai\`prompt\``)
+ * - Promise pipelining and schema inference
+ *
+ * @module
  */
 
 import { generateObject, generateText } from 'ai-functions'
@@ -7,23 +36,31 @@ import type { SimpleSchema } from 'ai-functions'
 import type { GenerateResult, GenerateOptions } from './types.js'
 
 /**
- * Generate content
+ * Generate content with rich metadata and multiple content type support.
  *
- * Uses AI to generate various types of content including text,
- * code, structured data, images, video, and audio.
+ * **Key Difference from ai-functions.generate():**
+ * Unlike `ai-functions.generate()` which is a lower-level type-dispatch
+ * function, this function returns a `GenerateResult` wrapper with:
+ * - The generated content
+ * - Generation metadata (model, tokens, duration)
+ * - Content type information
+ *
+ * This provides better observability for worker-based content generation.
  *
  * @param prompt - What to generate
- * @param options - Generation options
- * @returns Promise resolving to generated content
+ * @param options - Generation options (type, schema, instructions, model)
+ * @returns Promise resolving to GenerateResult with content and metadata
  *
  * @example
  * ```ts
- * // Generate text content
+ * // Generate text content with metadata
  * 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)
+ * console.log(result.content) // The generated text
+ * console.log(result.metadata.tokens) // Tokens used
+ * console.log(result.metadata.duration) // Generation time in ms
  * ```
  *
  * @example
@@ -52,18 +89,17 @@ import type { GenerateResult, GenerateOptions } from './types.js'
  *   instructions: 'Use TypeScript and hooks. Include prop types.',
  * })
  * console.log(result.content) // TypeScript React component code
+ * console.log(result.metadata.language) // 'typescript'
  * ```
+ *
+ * @see {@link ai-functions#generate} for lower-level type-dispatch generation
+ * @see {@link ai-functions#ai} for template literal generation syntax
  */
 export async function generate<T = string>(
   prompt: string,
   options: GenerateOptions = {}
 ): Promise<GenerateResult<T>> {
-  const {
-    type = 'text',
-    schema,
-    instructions,
-    model = 'sonnet',
-  } = options
+  const { type = 'text', schema, instructions, model = 'sonnet' } = options
 
   const startTime = Date.now()
 
@@ -111,7 +147,7 @@ export async function generate<T = string>(
         type: 'structured',
         metadata: {
           model,
-          tokens: result.usage?.totalTokens,
+          tokens: (result.usage as { totalTokens?: number } | undefined)?.totalTokens,
           duration: Date.now() - startTime,
         },
       }
@@ -144,7 +180,7 @@ export async function generate<T = string>(
         type: 'code',
         metadata: {
           model,
-          tokens: result.usage?.totalTokens,
+          tokens: (result.usage as { totalTokens?: number } | undefined)?.totalTokens,
           duration: Date.now() - startTime,
           language: codeResult.language,
           explanation: codeResult.explanation,
@@ -199,9 +235,7 @@ generate.variations = async <T = string>(
   count: number,
   options: GenerateOptions = {}
 ): Promise<Array<GenerateResult<T>>> => {
-  return Promise.all(
-    Array.from({ length: count }, () => generate<T>(prompt, options))
-  )
+  return Promise.all(Array.from({ length: count }, () => generate<T>(prompt, options)))
 }
 
 /**

package/src/goals.ts

@@ -2,7 +2,10 @@
  * Goals definition for digital workers
  */
 
-import type { WorkerGoals, KPI } from './types.js'
+import { calculateProgress, isOnTrack } from 'org.ai'
+import type { WorkerGoals, WorkerKPI } from './types.js'
+
+// Note: Goal, Goals types are re-exported from types.ts which imports from org.ai
 
 /**
  * Define worker goals
@@ -15,7 +18,7 @@ import type { WorkerGoals, KPI } from './types.js'
  *
  * @example
  * ```ts
- * const engineeringGoals = Goals({
+ * const engineeringGoals = defineGoals({
  *   shortTerm: [
  *     'Complete Q1 roadmap features',
  *     'Reduce bug backlog by 30%',
@@ -55,7 +58,7 @@ import type { WorkerGoals, KPI } from './types.js'
  *
  * @example
  * ```ts
- * const supportGoals = Goals({
+ * const supportGoals = defineGoals({
  *   shortTerm: [
  *     'Achieve 95% customer satisfaction',
  *     'Reduce average response time to < 5 min',
@@ -78,7 +81,7 @@ import type { WorkerGoals, KPI } from './types.js'
  * })
  * ```
  */
-export function Goals(definition: WorkerGoals): WorkerGoals {
+export function defineGoals(definition: WorkerGoals): WorkerGoals {
   return definition
 }
 
@@ -91,10 +94,10 @@ export function Goals(definition: WorkerGoals): WorkerGoals {
  *
  * @example
  * ```ts
- * const updated = Goals.addShortTerm(engineeringGoals, 'Complete security audit')
+ * const updated = defineGoals.addShortTerm(engineeringGoals, 'Complete security audit')
  * ```
  */
-Goals.addShortTerm = (goals: WorkerGoals, goal: string): WorkerGoals => ({
+defineGoals.addShortTerm = (goals: WorkerGoals, goal: string): WorkerGoals => ({
   ...goals,
   shortTerm: [...goals.shortTerm, goal],
 })
@@ -108,10 +111,10 @@ Goals.addShortTerm = (goals: WorkerGoals, goal: string): WorkerGoals => ({
  *
  * @example
  * ```ts
- * const updated = Goals.addLongTerm(engineeringGoals, 'Build ML platform')
+ * const updated = defineGoals.addLongTerm(engineeringGoals, 'Build ML platform')
  * ```
  */
-Goals.addLongTerm = (goals: WorkerGoals, goal: string): WorkerGoals => ({
+defineGoals.addLongTerm = (goals: WorkerGoals, goal: string): WorkerGoals => ({
   ...goals,
   longTerm: [...goals.longTerm, goal],
 })
@@ -125,10 +128,10 @@ Goals.addLongTerm = (goals: WorkerGoals, goal: string): WorkerGoals => ({
  *
  * @example
  * ```ts
- * const updated = Goals.addStrategic(engineeringGoals, 'Become carbon neutral')
+ * const updated = defineGoals.addStrategic(engineeringGoals, 'Become carbon neutral')
  * ```
  */
-Goals.addStrategic = (goals: WorkerGoals, goal: string): WorkerGoals => ({
+defineGoals.addStrategic = (goals: WorkerGoals, goal: string): WorkerGoals => ({
   ...goals,
   strategic: [...(goals.strategic || []), goal],
 })
@@ -142,7 +145,7 @@ Goals.addStrategic = (goals: WorkerGoals, goal: string): WorkerGoals => ({
  *
  * @example
  * ```ts
- * const updated = Goals.addMetric(engineeringGoals, {
+ * const updated = defineGoals.addMetric(engineeringGoals, {
  *   name: 'Code Quality',
  *   description: 'Code quality score from SonarQube',
  *   current: 85,
@@ -153,7 +156,7 @@ Goals.addStrategic = (goals: WorkerGoals, goal: string): WorkerGoals => ({
  * })
  * ```
  */
-Goals.addMetric = (goals: WorkerGoals, kpi: KPI): WorkerGoals => ({
+defineGoals.addMetric = (goals: WorkerGoals, kpi: WorkerKPI): WorkerGoals => ({
   ...goals,
   metrics: [...(goals.metrics || []), kpi],
 })
@@ -168,22 +171,26 @@ Goals.addMetric = (goals: WorkerGoals, kpi: KPI): WorkerGoals => ({
  *
  * @example
  * ```ts
- * const updated = Goals.updateMetric(engineeringGoals, 'Deployment Frequency', {
+ * const updated = defineGoals.updateMetric(engineeringGoals, 'Deployment Frequency', {
  *   current: 8,
  *   trend: 'up',
  * })
  * ```
  */
-Goals.updateMetric = (
+defineGoals.updateMetric = (
   goals: WorkerGoals,
   name: string,
-  updates: Partial<Omit<KPI, 'name'>>
-): WorkerGoals => ({
-  ...goals,
-  metrics: goals.metrics?.map((kpi) =>
+  updates: Partial<Omit<WorkerKPI, 'name'>>
+): WorkerGoals => {
+  const updatedMetrics = goals.metrics?.map((kpi) =>
     kpi.name === name ? { ...kpi, ...updates } : kpi
-  ),
-})
+  )
+  const result: WorkerGoals = { ...goals }
+  if (updatedMetrics) {
+    result.metrics = updatedMetrics
+  }
+  return result
+}
 
 /**
  * Get progress for a KPI (0-1)
@@ -194,12 +201,11 @@ Goals.updateMetric = (
  * @example
  * ```ts
  * const kpi = { current: 75, target: 100 }
- * const progress = Goals.progress(kpi) // 0.75
+ * const progress = defineGoals.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))
+defineGoals.progress = (kpi: Pick<WorkerKPI, 'current' | 'target'>): number => {
+  return calculateProgress(kpi)
 }
 
 /**
@@ -212,9 +218,12 @@ Goals.progress = (kpi: Pick<KPI, 'current' | 'target'>): number => {
  * @example
  * ```ts
  * const kpi = { current: 85, target: 100 }
- * const onTrack = Goals.onTrack(kpi) // true (85% >= 80% threshold)
+ * const onTrack = defineGoals.onTrack(kpi) // true (85% >= 80% threshold)
  * ```
  */
-Goals.onTrack = (kpi: Pick<KPI, 'current' | 'target'>, threshold = 0.8): boolean => {
-  return Goals.progress(kpi) >= threshold
+defineGoals.onTrack = (kpi: Pick<WorkerKPI, 'current' | 'target'>, threshold = 0.8): boolean => {
+  return isOnTrack(kpi, threshold)
 }
+
+// Legacy alias for backward compatibility
+export { defineGoals as Goals }