ai-workflows 1.1.0 → 2.0.1

package/.turbo/turbo-build.log

@@ -0,0 +1,5 @@
+
+
+> ai-workflows@2.0.1 build /Users/nathanclevenger/projects/primitives.org.ai/packages/ai-workflows
+> tsc
+

package/CHANGELOG.md

@@ -0,0 +1,3 @@
+# ai-workflows
+
+## 2.0.1

package/README.md

@@ -1,45 +1,306 @@
-[![npm version](https://badge.fury.io/js/ai-workflows.svg)](https://badge.fury.io/js/ai-workflows)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
-
 # ai-workflows
 
-Composable AI Workflows & Durable Execution Framework
+Event-driven workflows with the `$` context. Handle events, schedule tasks, and orchestrate processes.
 
-## Overview
+```typescript
+import { Workflow } from 'ai-workflows'
 
-ai-workflows is a powerful framework for building event-driven, AI-powered workflows with durable execution guarantees. It provides both a JavaScript API and MDX-based workflow definitions for maximum flexibility.
+const workflow = Workflow($ => {
+  $.on.Customer.created(async (customer, $) => {
+    $.log('New customer:', customer.name)
+    await $.send('Email.welcome', { to: customer.email })
+  })
 
-## Features
+  $.every.Monday.at9am(async ($) => {
+    $.log('Weekly standup reminder')
+  })
+})
 
-- 🎯 **Event-Driven Architecture** - Build reactive workflows that respond to external events
-- 🤖 **AI Functions** - Built-in MDX-based AI functions structured data generation and processing
-- ⏰ **Smart Scheduling** - Schedule tasks with natural language time expressions
-- 📝 **Workflow Definitions** - Design workflows by composing AI functions and events
-- 💪 **Durable Execution** - Reliable workflow execution with state persistence
+await workflow.start()
+await workflow.send('Customer.created', { name: 'John', email: 'john@example.com' })
+```
 
 ## Installation
 
 ```bash
-npm install ai-workflows
+pnpm add ai-workflows
+```
+
+## The `$` Context
+
+Everything flows through `$`. It's your workflow's connection to events, schedules, state, and the outside world.
+
+```typescript
+Workflow($ => {
+  // Event handlers
+  $.on.Order.completed(async (order, $) => {
+    await $.send('Invoice.generate', { orderId: order.id })
+    $.log('Order completed', order)
+  })
+
+  // Scheduled tasks
+  $.every.hour(async ($) => {
+    $.log('Hourly health check')
+  })
+})
+```
+
+## Event Handling
+
+Events follow the `Noun.verb` pattern:
+
+```typescript
+$.on.Customer.created(handler)   // Customer created
+$.on.Order.shipped(handler)      // Order shipped
+$.on.Payment.failed(handler)     // Payment failed
+$.on.Ticket.resolved(handler)    // Ticket resolved
+```
+
+### Sending Events
+
+```typescript
+// Fire and forget
+await $.send('Email.welcome', { to: 'user@example.com' })
+
+// Execute and wait for result (durable)
+const result = await $.do('Order.process', orderData)
+
+// Execute without durability
+const result = await $.try('Order.validate', orderData)
+```
+
+## Scheduling
+
+Natural language scheduling with `$.every`:
+
+```typescript
+// Simple intervals
+$.every.second(handler)
+$.every.minute(handler)
+$.every.hour(handler)
+$.every.day(handler)
+$.every.week(handler)
+
+// Days of the week
+$.every.Monday(handler)
+$.every.Friday(handler)
+$.every.weekday(handler)
+$.every.weekend(handler)
+
+// Day + time combinations
+$.every.Monday.at9am(handler)
+$.every.Friday.at5pm(handler)
+$.every.weekday.at8am(handler)
+
+// Intervals with values
+$.every.minutes(30)(handler)
+$.every.hours(4)(handler)
+
+// Natural language (requires AI converter)
+$.every('first Monday of the month at 9am', handler)
+$.every('every 15 minutes during business hours', handler)
+```
+
+### Available Times
+
+```typescript
+.at6am   .at7am   .at8am   .at9am   .at10am  .at11am
+.at12pm  .atnoon  .at1pm   .at2pm   .at3pm   .at4pm
+.at5pm   .at6pm   .at7pm   .at8pm   .at9pm   .atmidnight
+```
+
+## Standalone API
+
+Use `on`, `every`, and `send` for global registration:
+
+```typescript
+import { on, every, send } from 'ai-workflows'
+
+on.Customer.created(async (customer, $) => {
+  await $.send('Email.welcome', { to: customer.email })
+})
+
+every.hour(async ($) => {
+  $.log('Hourly task')
+})
+
+await send('Customer.created', { name: 'John' })
 ```
 
-## Usage
+## Real-World Examples
 
-### JavaScript API
+### Order Processing
 
-```javascript
-import { ai, Workflow } from 'ai-workflows'
+```typescript
+const workflow = Workflow($ => {
+  $.on.Order.placed(async (order, $) => {
+    $.log('Processing order', order.id)
 
-const workflow = Workflow()
+    // Validate inventory
+    const valid = await $.do('Inventory.check', order.items)
+    if (!valid) {
+      await $.send('Order.cancelled', { orderId: order.id, reason: 'Out of stock' })
+      return
+    }
 
-workflow.on('ticket.created', (ticket) => {
-  const summary = ai.summarize(ticket)
-  workflow.send('ticket.summarized', summary)
+    // Process payment
+    const payment = await $.do('Payment.charge', {
+      amount: order.total,
+      customer: order.customerId,
+    })
+
+    // Fulfill order
+    await $.send('Fulfillment.ship', { orderId: order.id })
+  })
+
+  $.on.Order.shipped(async (data, $) => {
+    await $.send('Email.tracking', { orderId: data.orderId })
+  })
+})
+```
+
+### Customer Lifecycle
+
+```typescript
+Workflow($ => {
+  $.on.Customer.signedUp(async (customer, $) => {
+    await $.send('Email.welcome', { to: customer.email })
+    await $.send('Slack.notify', { message: `New signup: ${customer.name}` })
+  })
+
+  $.on.Customer.upgraded(async (customer, $) => {
+    await $.send('Email.upgradeConfirmation', { to: customer.email })
+    await $.send('Analytics.track', { event: 'upgrade', plan: customer.plan })
+  })
+
+  // Check for inactive users daily
+  $.every.day.at9am(async ($) => {
+    const inactive = await $.do('Customer.findInactive', { days: 30 })
+    for (const customer of inactive) {
+      await $.send('Email.reengagement', { to: customer.email })
+    }
+  })
+})
+```
+
+### Scheduled Reports
+
+```typescript
+Workflow($ => {
+  $.every.Monday.at9am(async ($) => {
+    const report = await $.do('Analytics.weeklyReport', {})
+    await $.send('Email.report', {
+      to: 'team@company.com',
+      report,
+    })
+  })
+
+  $.every.month(async ($) => {
+    const metrics = await $.do('Metrics.monthly', {})
+    await $.send('Dashboard.update', { metrics })
+  })
+})
+```
+
+## Workflow Instance
+
+The `Workflow()` function returns an instance with:
+
+```typescript
+const workflow = Workflow($ => { /* ... */ })
+
+// Access the workflow
+workflow.definition  // Event and schedule registrations
+workflow.state       // Current state and history
+workflow.$           // The $ context
+
+// Control the workflow
+await workflow.start()  // Begin processing schedules
+await workflow.stop()   // Stop all schedules
+
+// Send events
+await workflow.send('Customer.created', { name: 'John' })
+```
+
+## Testing
+
+Create isolated test contexts:
+
+```typescript
+import { createTestContext } from 'ai-workflows'
+
+const $ = createTestContext()
+
+// Call your handler
+await yourHandler({ name: 'test' }, $)
+
+// Check what was emitted
+expect($.emittedEvents).toContainEqual({
+  event: 'Email.welcome',
+  data: { to: 'test@example.com' },
 })
+```
 
-workflow.on('ticket.summarized', (summary) => ai.sentiment(summary).then('update.ticket'))
+## API Reference
 
-workflow.every('30 minutes during business hours', (context) => ai.reviewKPIs(context).then('slack.post'))
+### Workflow Functions
 
-export default workflow
+| Export | Description |
+|--------|-------------|
+| `Workflow($)` | Create a workflow with $ context |
+| `on` | Standalone event registration |
+| `every` | Standalone schedule registration |
+| `send` | Emit events globally |
+| `createTestContext()` | Create isolated $ for testing |
+
+### Context Methods
+
+| Method | Description |
+|--------|-------------|
+| `$.on.Noun.verb(handler)` | Register event handler |
+| `$.every.*` | Register scheduled handler |
+| `$.send(event, data)` | Emit event (fire and forget) |
+| `$.do(event, data)` | Execute handler (durable) |
+| `$.try(event, data)` | Execute handler (non-durable) |
+| `$.log(message, data?)` | Log with history |
+| `$.state` | Access workflow state |
+
+### Schedule Helpers
+
+| Export | Description |
+|--------|-------------|
+| `toCron(description)` | Convert to cron expression |
+| `setCronConverter(fn)` | Set AI cron converter |
+| `intervalToMs(interval)` | Get interval in milliseconds |
+| `formatInterval(interval)` | Format for display |
+
+## Types
+
+```typescript
+interface WorkflowContext {
+  on: OnProxy
+  every: EveryProxy
+  send<T>(event: string, data: T): Promise<void>
+  do<T, R>(event: string, data: T): Promise<R>
+  try<T, R>(event: string, data: T): Promise<R>
+  log(message: string, data?: unknown): void
+  state: Record<string, unknown>
+  db?: DatabaseContext
+}
+
+interface WorkflowInstance {
+  definition: WorkflowDefinition
+  state: WorkflowState
+  $: WorkflowContext
+  send<T>(event: string, data: T): Promise<void>
+  start(): Promise<void>
+  stop(): Promise<void>
+}
 ```
+
+## Related Packages
+
+- [`ai-functions`](../ai-functions) — AI-powered functions
+- [`ai-database`](../ai-database) — Durable event storage
+- [`human-in-the-loop`](../human-in-the-loop) — Human workflow steps
+- [`digital-tasks`](../digital-tasks) — Task management

package/dist/context.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Workflow context implementation
+ */
+import type { WorkflowContext } from './types.js';
+/**
+ * Event bus interface (imported from send.ts to avoid circular dependency)
+ */
+interface EventBusLike {
+    emit(event: string, data: unknown): Promise<void>;
+}
+/**
+ * Create a workflow context
+ */
+export declare function createWorkflowContext(eventBus: EventBusLike): WorkflowContext;
+/**
+ * Create an isolated workflow context (not connected to event bus)
+ * Useful for testing or standalone execution
+ */
+export declare function createIsolatedContext(): WorkflowContext & {
+    getEmittedEvents: () => Array<{
+        event: string;
+        data: unknown;
+    }>;
+};
+export {};
+//# sourceMappingURL=context.d.ts.map

package/dist/context.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,KAAK,EAAE,eAAe,EAA4D,MAAM,YAAY,CAAA;AAE3G;;GAEG;AACH,UAAU,YAAY;IACpB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CAClD;AAED;;GAEG;AACH,wBAAgB,qBAAqB,CAAC,QAAQ,EAAE,YAAY,GAAG,eAAe,CAwE7E;AAED;;;GAGG;AACH,wBAAgB,qBAAqB,IAAI,eAAe,GAAG;IAAE,gBAAgB,EAAE,MAAM,KAAK,CAAC;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,OAAO,CAAA;KAAE,CAAC,CAAA;CAAE,CAa7H"}

package/dist/context.js

@@ -0,0 +1,84 @@
+/**
+ * Workflow context implementation
+ */
+/**
+ * Create a workflow context
+ */
+export function createWorkflowContext(eventBus) {
+    const workflowState = {
+        context: {},
+        history: [],
+    };
+    const addHistory = (entry) => {
+        workflowState.history.push({
+            ...entry,
+            timestamp: Date.now(),
+        });
+    };
+    // Create no-op proxies for on/every (these are used in send context, not workflow setup)
+    const noOpOnProxy = new Proxy({}, {
+        get() {
+            return new Proxy({}, {
+                get() {
+                    return () => { };
+                }
+            });
+        }
+    });
+    const noOpEveryProxy = new Proxy(function () { }, {
+        get() {
+            return () => () => { };
+        },
+        apply() { }
+    });
+    return {
+        async send(event, data) {
+            addHistory({ type: 'event', name: event, data });
+            await eventBus.emit(event, data);
+        },
+        async do(_event, _data) {
+            throw new Error('$.do not available in this context');
+        },
+        async try(_event, _data) {
+            throw new Error('$.try not available in this context');
+        },
+        on: noOpOnProxy,
+        every: noOpEveryProxy,
+        state: workflowState.context,
+        getState() {
+            // Return a deep copy to prevent mutation
+            return {
+                current: workflowState.current,
+                context: { ...workflowState.context },
+                history: [...workflowState.history],
+            };
+        },
+        set(key, value) {
+            workflowState.context[key] = value;
+        },
+        get(key) {
+            return workflowState.context[key];
+        },
+        log(message, data) {
+            addHistory({ type: 'action', name: 'log', data: { message, data } });
+            console.log(`[workflow] ${message}`, data ?? '');
+        },
+    };
+}
+/**
+ * Create an isolated workflow context (not connected to event bus)
+ * Useful for testing or standalone execution
+ */
+export function createIsolatedContext() {
+    const emittedEvents = [];
+    const ctx = createWorkflowContext({
+        async emit(event, data) {
+            emittedEvents.push({ event, data });
+        },
+    });
+    return {
+        ...ctx,
+        getEmittedEvents: () => [...emittedEvents],
+    };
+}
+//# sourceMappingURL=context.js.map

package/dist/context.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"context.js","sourceRoot":"","sources":["../src/context.ts"],"names":[],"mappings":"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"}

package/dist/every.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Schedule registration using natural language
+ *
+ * Usage:
+ *   every.hour($ => { ... })
+ *   every.Thursday.at8am($ => { ... })
+ *   every.weekday.at9am($ => { ... })
+ *   every('hour during business hours', $ => { ... })
+ *   every('first Monday of the month at 9am', $ => { ... })
+ */
+import type { ScheduleHandler, ScheduleRegistration, ScheduleInterval } from './types.js';
+/**
+ * Get all registered schedule handlers
+ */
+export declare function getScheduleHandlers(): ScheduleRegistration[];
+/**
+ * Clear all registered schedule handlers
+ */
+export declare function clearScheduleHandlers(): void;
+/**
+ * Register a schedule handler directly
+ */
+export declare function registerScheduleHandler(interval: ScheduleInterval, handler: ScheduleHandler): void;
+/**
+ * Set the AI cron converter function
+ */
+export declare function setCronConverter(converter: (description: string) => Promise<string>): void;
+/**
+ * Convert natural language to cron expression
+ */
+export declare function toCron(description: string): Promise<string>;
+/**
+ * The `every` function/object for registering scheduled handlers
+ *
+ * @example
+ * ```ts
+ * import { every } from 'ai-workflows'
+ *
+ * // Simple intervals
+ * every.hour($ => $.log('Hourly task'))
+ * every.day($ => $.log('Daily task'))
+ *
+ * // Day + time combinations
+ * every.Monday.at9am($ => $.log('Monday morning standup'))
+ * every.weekday.at8am($ => $.log('Workday start'))
+ * every.Friday.at5pm($ => $.log('End of week report'))
+ *
+ * // Plural intervals with values
+ * every.minutes(30)($ => $.log('Every 30 minutes'))
+ * every.hours(4)($ => $.log('Every 4 hours'))
+ *
+ * // Natural language (requires AI converter)
+ * every('hour during business hours', $ => { ... })
+ * every('first Monday of the month at 9am', $ => { ... })
+ * every('every 15 minutes between 9am and 5pm on weekdays', $ => { ... })
+ * ```
+ */
+export declare const every: any;
+/**
+ * Convert interval to milliseconds (for simulation/testing)
+ */
+export declare function intervalToMs(interval: ScheduleInterval): number;
+/**
+ * Format interval for display
+ */
+export declare function formatInterval(interval: ScheduleInterval): string;
+//# sourceMappingURL=every.d.ts.map

package/dist/every.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"every.d.ts","sourceRoot":"","sources":["../src/every.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,KAAK,EAAE,eAAe,EAAE,oBAAoB,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAOzF;;GAEG;AACH,wBAAgB,mBAAmB,IAAI,oBAAoB,EAAE,CAE5D;AAED;;GAEG;AACH,wBAAgB,qBAAqB,IAAI,IAAI,CAE5C;AAED;;GAEG;AACH,wBAAgB,uBAAuB,CACrC,QAAQ,EAAE,gBAAgB,EAC1B,OAAO,EAAE,eAAe,GACvB,IAAI,CAMN;AA6ED;;GAEG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,CAAC,WAAW,EAAE,MAAM,KAAK,OAAO,CAAC,MAAM,CAAC,GAAG,IAAI,CAE1F;AAED;;GAEG;AACH,wBAAsB,MAAM,CAAC,WAAW,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAmBjE;AAgED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,eAAO,MAAM,KAAK,KAAqB,CAAA;AAEvC;;GAEG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CAiB/D;AAED;;GAEG;AACH,wBAAgB,cAAc,CAAC,QAAQ,EAAE,gBAAgB,GAAG,MAAM,CA+BjE"}