ai-workflows 0.0.2 → 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 AI Primitives
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,18 +1,45 @@
+[![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
+
+## Overview
+
+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.
+
+## Features
+
+- 🎯 **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
+
+## Installation
+
+```bash
+npm install ai-workflows
+```
+
+## Usage
+
+### JavaScript API
+
 ```javascript
 import { ai, Workflow } from 'ai-workflows'
 
 const workflow = Workflow()
 
-workflow.on('ticket.created', ticket => {
+workflow.on('ticket.created', (ticket) => {
   const summary = ai.summarize(ticket)
   workflow.send('ticket.summarized', summary)
 })
 
-workflow.on('ticket.summarized', summary => ai.sentiment(summary).then('update.ticket'))
+workflow.on('ticket.summarized', (summary) => ai.sentiment(summary).then('update.ticket'))
 
-workflow.every('30 minutes during business hours', context => ai.reviewKPIs(context).then('slack.post'))
+workflow.every('30 minutes during business hours', (context) => ai.reviewKPIs(context).then('slack.post'))
 
 export default workflow
-```
+```

package/dist/scripts/generate-types.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/scripts/generate-types.js

@@ -0,0 +1,57 @@
+import { readFileSync, writeFileSync, readdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, resolve } from 'node:path';
+import matter from 'gray-matter';
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = dirname(__filename);
+const aiDir = resolve(process.cwd(), 'ai');
+const outputFile = resolve(process.cwd(), 'src/ai-types.d.ts');
+/**
+ * Converts an MDX output type definition to a TypeScript type
+ * Handles enum types (separated by |) and string types
+ */
+function convertOutputTypeToTS(type) {
+    if (type.includes('|')) {
+        // Handle enum types (e.g., "Article | BlogPosting | Thing")
+        return type.split('|').map(t => `'${t.trim()}'`).join(' | ');
+    }
+    return 'string';
+}
+/**
+ * Generates TypeScript type definitions from MDX files
+ */
+function generateTypes() {
+    const mdxFiles = readdirSync(aiDir).filter(file => file.endsWith('.mdx'));
+    let typeDefinitions = `// Generated TypeScript definitions for AI methods
+// DO NOT EDIT DIRECTLY - Generated from MDX files in ai/
+
+declare const ai: {
+`;
+    for (const file of mdxFiles) {
+        const methodName = file.replace('.mdx', '');
+        const content = readFileSync(resolve(aiDir, file), 'utf-8');
+        const { data: frontmatter } = matter(content);
+        if (!frontmatter.output?.type) {
+            console.warn(`Warning: ${file} is missing output type definition`);
+            continue;
+        }
+        const tsType = convertOutputTypeToTS(frontmatter.output.type);
+        const description = frontmatter.output.description || 'No description provided';
+        typeDefinitions += `  /**
+   * ${description}
+   * @param input The input data for the AI operation
+   * @returns A promise that resolves to the generated output
+   */
+  ${methodName}(input: unknown): Promise<${tsType}>;
+
+`;
+    }
+    typeDefinitions += `}
+
+export { ai }
+`;
+    writeFileSync(outputFile, typeDefinitions);
+    console.log(`Generated type definitions at ${outputFile}`);
+}
+// Run the generator
+generateTypes();

package/dist/src/ai-proxy.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The ai object is a Proxy that dynamically loads MDX files for each method call
+ * Example: ai.summarize(ticket) will load ai/summarize.mdx and use its configuration
+ */
+export declare const ai: {};

package/dist/src/ai-proxy.js

@@ -0,0 +1,94 @@
+import { readFileSync, existsSync } from 'fs';
+import path from 'path';
+import matter from 'gray-matter';
+import { z } from 'zod';
+import { OpenAI } from 'openai';
+const aiBasePath = path.resolve(process.cwd(), 'ai');
+const openai = new OpenAI({
+    apiKey: process.env.OPENAI_API_KEY
+});
+// Schema for required MDX frontmatter
+const frontmatterSchema = z.object({
+    model: z.string(),
+    system: z.string(),
+    output: z.object({
+        type: z.string(),
+        description: z.string()
+    })
+});
+/**
+ * Creates a Zod schema from an output definition in MDX frontmatter
+ * Handles enum types (separated by |) and string types with descriptions
+ * @param outputDef - The output definition from MDX frontmatter
+ * @returns A Zod schema for validating the output
+ */
+function createZodSchemaFromOutput(outputDef) {
+    const { type, description } = outputDef;
+    // Create schema based on output type
+    const schema = type.includes('|')
+        ? z.object({
+            type: z.enum(type.split('|').map(t => t.trim())),
+            description: z.string()
+        })
+        : z.object({
+            type: z.string(),
+            description: z.string()
+        });
+    return schema.describe(description);
+}
+/**
+ * The ai object is a Proxy that dynamically loads MDX files for each method call
+ * Example: ai.summarize(ticket) will load ai/summarize.mdx and use its configuration
+ */
+export const ai = new Proxy({}, {
+    get(_target, methodName) {
+        return async (input) => {
+            try {
+                // Check if MDX file exists
+                const mdxFile = path.join(aiBasePath, `${methodName}.mdx`);
+                if (!existsSync(mdxFile)) {
+                    throw new Error(`No MDX file found for ai.${methodName}(). Create ${methodName}.mdx in the ai/ directory.`);
+                }
+                // Load and parse the MDX file
+                const fileContent = readFileSync(mdxFile, 'utf-8');
+                const { data: rawFrontmatter, content } = matter(fileContent);
+                // Validate frontmatter against schema
+                const frontmatter = frontmatterSchema.parse(rawFrontmatter);
+                // Create Zod schema from output definition
+                const outputSchema = createZodSchemaFromOutput(frontmatter.output);
+                // Generate response using OpenAI
+                const completion = await openai.chat.completions.create({
+                    model: frontmatter.model,
+                    messages: [
+                        { role: 'system', content: frontmatter.system },
+                        { role: 'user', content: `${content}\n\nInput: ${JSON.stringify(input, null, 2)}` }
+                    ],
+                    response_format: { type: 'json_object' },
+                    temperature: 0.7, // Add some creativity while maintaining structure
+                });
+                // Parse and validate the response
+                let result;
+                try {
+                    result = JSON.parse(completion.choices[0].message.content || '{}');
+                }
+                catch (error) {
+                    // Narrow error type for proper handling
+                    const parseError = error;
+                    throw new Error(`Failed to parse OpenAI response as JSON: ${parseError.message}`);
+                }
+                // Validate against our schema and return
+                return outputSchema.parse(result);
+            }
+            catch (error) {
+                // Enhance error messages for different types of failures
+                if (error instanceof z.ZodError) {
+                    throw new Error(`Schema validation failed in ai.${methodName}(): ${error.errors.map(e => e.message).join(', ')}`);
+                }
+                else if (error instanceof Error) {
+                    throw new Error(`Error in ai.${methodName}(): ${error.message}`);
+                }
+                throw error;
+            }
+        };
+    }
+});

package/dist/src/index.d.ts

@@ -0,0 +1,9 @@
+import { ai } from './ai-proxy.js';
+export { ai };
+/**
+ * A placeholder function that adds two numbers
+ * @param a First number
+ * @param b Second number
+ * @returns The sum of a and b
+ */
+export declare function add(a: number, b: number): number;

package/dist/src/index.js

@@ -0,0 +1,11 @@
+import { ai } from './ai-proxy.js';
+export { ai };
+/**
+ * A placeholder function that adds two numbers
+ * @param a First number
+ * @param b Second number
+ * @returns The sum of a and b
+ */
+export function add(a, b) {
+    return a + b;
+}

package/dist/src/index.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/src/index.test.js

@@ -0,0 +1,35 @@
+import { describe, it, expect, beforeAll } from '@jest/globals';
+import { add, ai } from './index.js';
+import { mkdir, writeFile } from 'fs/promises';
+import path from 'path';
+describe('add', () => {
+    it('should add two numbers correctly', () => {
+        expect(add(2, 3)).toBe(5);
+        expect(add(-1, 1)).toBe(0);
+        expect(add(0, 0)).toBe(0);
+    });
+});
+describe('ai', () => {
+    beforeAll(async () => {
+        // Create ai directory and test MDX file
+        await mkdir(path.resolve(process.cwd(), 'ai'), { recursive: true });
+        await writeFile(path.resolve(process.cwd(), 'ai/test.mdx'), `---
+model: gpt-3.5-turbo
+system: Test system prompt
+output:
+  type: Article | BlogPosting
+  description: Test description
+---
+
+# Test MDX
+
+Test content`);
+    });
+    it('should handle AI method calls correctly', async () => {
+        const result = await ai.test({ input: 'test' });
+        expect(result).toEqual({
+            type: 'Article',
+            description: 'Test description'
+        });
+    });
+});

package/package.json

@@ -1,42 +1,83 @@
 {
   "name": "ai-workflows",
-  "version": "0.0.2",
-  "description": "Framework for Developing AI-Native Workflows",
+  "type": "module",
+  "version": "1.1.0",
+  "description": "Composable AI Workflows & Durable Execution Framework",
+  "main": "dist/index.js",
   "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "ai-workflows": "bin/cli.js"
+  },
+  "files": [
+    "dist",
+    "bin"
+  ],
   "scripts": {
-    "build": "tsc",
-    "format": "prettier --write .",
-    "test": "dotenv -- vitest --globals"
+    "build": "tsc && NODE_OPTIONS=\"--experimental-specifier-resolution=node --loader ts-node/esm\" ts-node scripts/generate-types.ts",
+    "test": "jest",
+    "test:watch": "jest --watch",
+    "lint": "eslint src",
+    "format": "prettier --write \"src/**/*.{ts,tsx,js,jsx}\" \"*.{md,mdx}\"",
+    "prepublishOnly": "pnpm run build",
+    "generate-types": "NODE_OPTIONS=\"--experimental-specifier-resolution=node --loader ts-node/esm\" ts-node scripts/generate-types.ts"
   },
+  "keywords": [
+    "ai",
+    "workflows",
+    "mdx",
+    "durable-execution"
+  ],
+  "author": "AI Primitives",
+  "license": "MIT",
+  "homepage": "https://mdx.org.ai",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/nathanclevenger/ai-workflows.git"
+    "url": "git+https://github.com/ai-primitives/ai-workflows.git"
   },
-  "keywords": [],
-  "author": "Nathan Clevenger",
-  "license": "MIT",
   "bugs": {
-    "url": "https://github.com/nathanclevenger/ai-workflows/issues"
+    "url": "https://github.com/ai-primitives/ai-workflows/issues"
   },
-  "homepage": "https://github.com/nathanclevenger/ai-workflows#readme",
   "devDependencies": {
-    "@cloudflare/workers-types": "^4.20241018.0",
-    "typescript": "^5.6.3",
-    "vitest": "^2.1.3"
+    "@babel/core": "^7.26.0",
+    "@babel/preset-env": "^7.26.0",
+    "@eslint/js": "^9.17.0",
+    "@jest/globals": "^29.7.0",
+    "@semantic-release/commit-analyzer": "^13.0.0",
+    "@semantic-release/github": "^11.0.1",
+    "@semantic-release/npm": "^12.0.1",
+    "@semantic-release/release-notes-generator": "^14.0.1",
+    "@swc/core": "^1.10.1",
+    "@testing-library/jest-dom": "^6.4.2",
+    "@testing-library/react": "^16.1.0",
+    "@types/jest": "^29.5.14",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^22.10.2",
+    "@types/react": "^18.3.17",
+    "@types/react-dom": "^18.2.0",
+    "@typescript-eslint/eslint-plugin": "^8.18.0",
+    "@typescript-eslint/parser": "^8.18.0",
+    "babel-jest": "^29.7.0",
+    "eslint": "^9.17.0",
+    "identity-obj-proxy": "^3.0.0",
+    "jest": "^29.7.0",
+    "jest-environment-jsdom": "^29.7.0",
+    "prettier": "^3.4.2",
+    "semantic-release": "^24.2.0",
+    "ts-jest": "^29.2.5",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.7.2"
   },
   "dependencies": {
-    "ai": "^3.4.18",
+    "@ai-sdk/openai": "^1.0.8",
+    "ai": "^4.0.18",
     "ai-functions": "^0.2.19",
-    "autoevals": "^0.0.99",
-    "braintrust": "^0.0.166",
-    "itty-router": "^5.0.18",
-    "openai": "^4.68.1"
-  },
-  "prettier": {
-    "semi": false,
-    "singleQuote": true,
-    "trailingComma": "es5",
-    "tabWidth": 2,
-    "printWidth": 120
+    "gray-matter": "^4.0.3",
+    "mdxld": "^0.1.1",
+    "openai": "^4.77.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.2.0",
+    "yaml": "^2.6.1",
+    "zod": "^3.24.1"
   }
-}
+}

package/index.test.ts

@@ -1,9 +0,0 @@
-import { describe, it } from 'vitest'
-
-// An entry will be shown in the report for this suite
-describe.todo('unimplemented suite')
-
-// An entry will be shown in the report for this test
-describe('suite', () => {
-  it.todo('unimplemented test')
-})

package/index.ts

@@ -1,81 +0,0 @@
-import { AI } from 'ai-functions'
-import { AutoRouter } from 'itty-router'
-
-export const ai: Record<string, any> = {}
-
-export type WorkflowOptions = {
-  queue?: string
-  dql?: string
-}
-
-// export let send: (event: string | WorkflowEvent) => Promise<any>
-
-// TODO: Add generic type for the event data
-export const Workflow = (options: WorkflowOptions) => {
-
-
-  const { queue = 'workflows' } = options
-
-  const api = AutoRouter()
-
-  const events: Record<string, any> = {}
-
-  const send = (env: any) => async (event: string | WorkflowEvent) => {
-    if (env[queue] && env[queue].send) {
-      if (typeof event === 'string') {
-        return (data: any) => (env[queue] as Queue<WorkflowEvent>).send({ event, data })
-      }
-      return await (env[queue] as Queue<WorkflowEvent>).send(event)
-    }
-    throw new Error('Queue not found')
-  }
-
-  return {
-    on: (event: string, handler: WorkflowEventHandler) => {
-      events[event] = handler
-      api.get('/' + event, async (req, env, ctx) => {
-        const data = Object.fromEntries(new URL(req.url).searchParams)
-        return send(env)({ event, data })
-      })
-      api.post('/' + event, async (req, env, ctx) => {
-        const data = await req.json()
-        return send(env)({ event, data })
-      })
-    },
-    fetch: api.fetch,
-    queue: (batch: MessageBatch<WorkflowEvent>, env: any, ctx: ExecutionContext) => {
-      batch.messages.map(async (message) => {
-        const { event, data } = message.body
-        if (events[event]) {
-          try {
-            const results = await events[event](message.body, { ai, db: env.db, api: env.api, data, message, send: send(env) })
-            console.log(results)
-            message.ack()
-            // TODO: Try to support `workflow.on('ticket.summarized', summary => ai.sentiment(summary).then('update.ticket'))`
-            // if (typeof results === 'string') {
-            //   const resultData = await results
-            //   return send(env)({ event: results, data })
-            // }
-          } catch (error) {
-            console.error(error)
-            message.retry()
-          }
-        }
-        throw new Error('Event not found')
-      })
-    },
-  }
-}
-
-export type WorkflowEvent<T = any> = {
-  event: string
-  data: T
-}
-
-export type WorkflowContext = {
-  ai: Record<string, any>
-  db: Record<string, any>
-  api: Record<string, any>
-}
-
-export type WorkflowEventHandler = (event: WorkflowEvent, context: WorkflowContext) => Promise<any>

package/tsconfig.json

@@ -1,48 +0,0 @@
-{
-  "compilerOptions": {
-    /* Visit https://aka.ms/tsconfig.json to read more about this file */
-
-    /* Set the JavaScript language version for emitted JavaScript and include compatible library declarations. */
-    "target": "es2021",
-    /* Specify a set of bundled library declaration files that describe the target runtime environment. */
-    "lib": ["es2021"],
-    /* Specify what JSX code is generated. */
-    "jsx": "react-jsx",
-    "jsxImportSource": "hono/jsx",
-
-    /* Specify what module code is generated. */
-    "module": "es2022",
-    /* Specify how TypeScript looks up a file from a given module specifier. */
-    "moduleResolution": "Bundler",
-    /* Specify type package names to be included without being referenced in a source file. */
-    "types": ["@cloudflare/workers-types/2023-07-01"],
-    /* Enable importing .json files */
-    "resolveJsonModule": true,
-
-    /* Allow JavaScript files to be a part of your program. Use the `checkJS` option to get errors from these files. */
-    "allowJs": true,
-    /* Enable error reporting in type-checked JavaScript files. */
-    "checkJs": false,
-
-    /* Disable emitting files from a compilation. */
-    "noEmit": false,
-
-    /* Emit the compiled files to the ./dist folder */
-    "outDir": "./dist",
-
-    /* Ensure that each file can be safely transpiled without relying on other imports. */
-    "isolatedModules": true,
-    /* Allow 'import x from y' when a module doesn't have a default export. */
-    "allowSyntheticDefaultImports": true,
-    /* Ensure that casing is correct in imports. */
-    "forceConsistentCasingInFileNames": true,
-
-    /* Enable all strict type-checking options. */
-    "strict": true,
-
-    /* Skip type checking all .d.ts files. */
-    "skipLibCheck": true
-  },
-  "exclude": ["test"],
-  "include": ["types.d.ts", "**/*.ts", "**/*.tsx"]
-}