ai-functions 0.2.19 → 0.4.0

package/test/tagged-templates.test.ts

@@ -0,0 +1,302 @@
+/**
+ * Tests for tagged template literal support
+ *
+ * Every function should support:
+ * 1. Tagged template syntax: fn`prompt ${variable}`
+ * 2. Objects/arrays auto-convert to YAML in templates
+ * 3. Options chaining: fn`prompt`({ model: '...' })
+ */
+
+import { describe, it, expect } from 'vitest'
+import { stringify } from 'yaml'
+
+// ============================================================================
+// Template Parsing Tests (Unit Tests - No AI calls)
+// ============================================================================
+
+/**
+ * Parse a tagged template literal into a prompt string
+ * Objects and arrays are converted to YAML for readability
+ */
+function parseTemplate(strings: TemplateStringsArray, ...values: unknown[]): string {
+  return strings.reduce((result, str, i) => {
+    const value = values[i]
+    if (value === undefined) {
+      return result + str
+    }
+
+    // Convert objects/arrays to YAML
+    if (typeof value === 'object' && value !== null) {
+      const yaml = stringify(value).trim()
+      return result + str + '\n' + yaml
+    }
+
+    // Primitives use toString()
+    return result + str + String(value)
+  }, '')
+}
+
+/**
+ * Create a template function that supports both call styles
+ */
+function createTemplateFunction<T>(
+  handler: (prompt: string, options?: Record<string, unknown>) => Promise<T>
+): {
+  (strings: TemplateStringsArray, ...values: unknown[]): Promise<T> & { (options?: Record<string, unknown>): Promise<T> }
+  (prompt: string, options?: Record<string, unknown>): Promise<T>
+} {
+  function templateFn(promptOrStrings: string | TemplateStringsArray, ...args: unknown[]) {
+    // Tagged template literal
+    if (Array.isArray(promptOrStrings) && 'raw' in promptOrStrings) {
+      const prompt = parseTemplate(promptOrStrings as TemplateStringsArray, ...args)
+
+      // Return a thenable that also accepts options
+      const promise = handler(prompt)
+
+      // Allow chaining with options: fn`prompt`({ model: '...' })
+      // Create a function that also implements then/catch for Promise interface
+      const chainable = (options?: Record<string, unknown>) => handler(prompt, options)
+
+      // Make it thenable by adding then/catch from the original promise
+      ;(chainable as unknown as Promise<T>).then = promise.then.bind(promise)
+      ;(chainable as unknown as Promise<T>).catch = promise.catch.bind(promise)
+
+      return chainable
+    }
+
+    // Regular function call
+    return handler(promptOrStrings as string, args[0] as Record<string, unknown> | undefined)
+  }
+
+  return templateFn as ReturnType<typeof createTemplateFunction<T>>
+}
+
+describe('template parsing', () => {
+  it('parses simple string interpolation', () => {
+    const topic = 'TypeScript'
+    const result = parseTemplate`Write about ${topic}`
+    expect(result).toBe('Write about TypeScript')
+  })
+
+  it('parses multiple interpolations', () => {
+    const topic = 'TypeScript'
+    const audience = 'beginners'
+    const result = parseTemplate`Write about ${topic} for ${audience}`
+    expect(result).toBe('Write about TypeScript for beginners')
+  })
+
+  it('converts objects to YAML', () => {
+    const context = { topic: 'TypeScript', level: 'beginner' }
+    const result = parseTemplate`Write a post about ${{ context }}`
+
+    expect(result).toContain('context:')
+    expect(result).toContain('topic: TypeScript')
+    expect(result).toContain('level: beginner')
+  })
+
+  it('converts arrays to YAML lists', () => {
+    const topics = ['React', 'Vue', 'Angular']
+    const result = parseTemplate`Compare ${topics}`
+
+    expect(result).toContain('- React')
+    expect(result).toContain('- Vue')
+    expect(result).toContain('- Angular')
+  })
+
+  it('handles nested objects', () => {
+    const brand = {
+      hero: 'developers',
+      problem: {
+        internal: 'complexity',
+        external: 'time constraints',
+      },
+    }
+    const result = parseTemplate`Create a story for ${{ brand }}`
+
+    expect(result).toContain('brand:')
+    expect(result).toContain('hero: developers')
+    expect(result).toContain('problem:')
+    expect(result).toContain('internal: complexity')
+    expect(result).toContain('external: time constraints')
+  })
+
+  it('handles numbers and booleans', () => {
+    const count = 10
+    const active = true
+    const result = parseTemplate`Generate ${count} items, active: ${active}`
+
+    expect(result).toBe('Generate 10 items, active: true')
+  })
+
+  it('handles null and undefined gracefully', () => {
+    const value = null
+    const result = parseTemplate`Value is ${value}`
+    expect(result).toContain('Value is')
+  })
+
+  it('preserves template structure with objects inline', () => {
+    const requirements = {
+      pages: ['home', 'about', 'contact'],
+      features: ['dark mode', 'responsive'],
+    }
+    const result = parseTemplate`marketing site${{ requirements }}`
+
+    expect(result).toContain('marketing site')
+    expect(result).toContain('requirements:')
+    expect(result).toContain('pages:')
+    expect(result).toContain('- home')
+    expect(result).toContain('features:')
+    expect(result).toContain('- dark mode')
+  })
+})
+
+describe('template function creation', () => {
+  it('creates a function that handles tagged templates', async () => {
+    const mockHandler = async (prompt: string) => `Processed: ${prompt}`
+    const fn = createTemplateFunction(mockHandler)
+
+    const result = await fn`Hello ${'world'}`
+    expect(result).toBe('Processed: Hello world')
+  })
+
+  it('creates a function that handles regular calls', async () => {
+    const mockHandler = async (prompt: string) => `Processed: ${prompt}`
+    const fn = createTemplateFunction(mockHandler)
+
+    const result = await fn('Hello world')
+    expect(result).toBe('Processed: Hello world')
+  })
+
+  it('supports options chaining on tagged templates', async () => {
+    let capturedOptions: Record<string, unknown> | undefined
+    const mockHandler = async (prompt: string, options?: Record<string, unknown>) => {
+      capturedOptions = options
+      return `Processed: ${prompt}`
+    }
+    const fn = createTemplateFunction(mockHandler)
+
+    const result = await fn`Hello world`({ model: 'claude-opus-4-5' })
+
+    expect(result).toBe('Processed: Hello world')
+    expect(capturedOptions).toEqual({ model: 'claude-opus-4-5' })
+  })
+
+  it('passes options in regular calls', async () => {
+    let capturedOptions: Record<string, unknown> | undefined
+    const mockHandler = async (prompt: string, options?: Record<string, unknown>) => {
+      capturedOptions = options
+      return `Processed: ${prompt}`
+    }
+    const fn = createTemplateFunction(mockHandler)
+
+    await fn('Hello world', { model: 'gpt-5-1', temperature: 0.7 })
+
+    expect(capturedOptions).toEqual({ model: 'gpt-5-1', temperature: 0.7 })
+  })
+
+  it('converts complex objects to YAML in templates', async () => {
+    let capturedPrompt = ''
+    const mockHandler = async (prompt: string) => {
+      capturedPrompt = prompt
+      return 'ok'
+    }
+    const fn = createTemplateFunction(mockHandler)
+
+    const brand = { hero: 'developers', guide: 'ai-functions' }
+    await fn`Create story for ${{ brand }}`
+
+    expect(capturedPrompt).toContain('brand:')
+    expect(capturedPrompt).toContain('hero: developers')
+    expect(capturedPrompt).toContain('guide: ai-functions')
+  })
+})
+
+describe('options parameter', () => {
+  it('supports model option', async () => {
+    let capturedOptions: Record<string, unknown> | undefined
+    const mockHandler = async (_prompt: string, options?: Record<string, unknown>) => {
+      capturedOptions = options
+      return 'ok'
+    }
+    const fn = createTemplateFunction(mockHandler)
+
+    await fn`test`({ model: 'claude-opus-4-5' })
+
+    expect(capturedOptions?.model).toBe('claude-opus-4-5')
+  })
+
+  it('supports thinking option', async () => {
+    let capturedOptions: Record<string, unknown> | undefined
+    const mockHandler = async (_prompt: string, options?: Record<string, unknown>) => {
+      capturedOptions = options
+      return 'ok'
+    }
+    const fn = createTemplateFunction(mockHandler)
+
+    await fn`complex analysis`({ thinking: 'high' })
+
+    expect(capturedOptions?.thinking).toBe('high')
+  })
+
+  it('supports thinking as token budget number', async () => {
+    let capturedOptions: Record<string, unknown> | undefined
+    const mockHandler = async (_prompt: string, options?: Record<string, unknown>) => {
+      capturedOptions = options
+      return 'ok'
+    }
+    const fn = createTemplateFunction(mockHandler)
+
+    await fn`complex analysis`({ thinking: 10000 })
+
+    expect(capturedOptions?.thinking).toBe(10000)
+  })
+
+  it('supports temperature option', async () => {
+    let capturedOptions: Record<string, unknown> | undefined
+    const mockHandler = async (_prompt: string, options?: Record<string, unknown>) => {
+      capturedOptions = options
+      return 'ok'
+    }
+    const fn = createTemplateFunction(mockHandler)
+
+    await fn`creative writing`({ temperature: 0.9 })
+
+    expect(capturedOptions?.temperature).toBe(0.9)
+  })
+
+  it('supports maxTokens option', async () => {
+    let capturedOptions: Record<string, unknown> | undefined
+    const mockHandler = async (_prompt: string, options?: Record<string, unknown>) => {
+      capturedOptions = options
+      return 'ok'
+    }
+    const fn = createTemplateFunction(mockHandler)
+
+    await fn`long article`({ maxTokens: 4000 })
+
+    expect(capturedOptions?.maxTokens).toBe(4000)
+  })
+
+  it('supports multiple options together', async () => {
+    let capturedOptions: Record<string, unknown> | undefined
+    const mockHandler = async (_prompt: string, options?: Record<string, unknown>) => {
+      capturedOptions = options
+      return 'ok'
+    }
+    const fn = createTemplateFunction(mockHandler)
+
+    await fn`complex task`({
+      model: 'claude-opus-4-5',
+      thinking: 'high',
+      temperature: 0.7,
+      maxTokens: 8000,
+    })
+
+    expect(capturedOptions).toEqual({
+      model: 'claude-opus-4-5',
+      thinking: 'high',
+      temperature: 0.7,
+      maxTokens: 8000,
+    })
+  })
+})

package/tsconfig.json

@@ -1,8 +1,10 @@
 {
-  "extends": "./tsconfig-base.json",
+  "extends": "../../tsconfig.base.json",
   "compilerOptions": {
-      "module": "esnext",
-      "outDir": "dist/mjs",
-      "target": "esnext"
-  }
-}
+    "rootDir": "src",
+    "outDir": "dist",
+    "lib": ["ES2022", "DOM", "DOM.Iterable"]
+  },
+  "include": ["src/**/*"],
+  "exclude": ["node_modules", "dist", "**/*.test.ts", "**/*.spec.ts"]
+}

package/vitest.config.ts

@@ -0,0 +1,42 @@
+import { defineConfig } from 'vitest/config'
+import { config } from 'dotenv'
+import { resolve } from 'path'
+import { existsSync } from 'fs'
+
+// Load .env from current directory, parent directories, and root
+// This supports primitives being used as a submodule
+const envPaths = [
+  resolve(process.cwd(), '.env'),
+  resolve(process.cwd(), '..', '.env'),
+  resolve(process.cwd(), '..', '..', '.env'),
+  resolve(process.cwd(), '..', '..', '..', '.env'),
+]
+
+for (const envPath of envPaths) {
+  if (existsSync(envPath)) {
+    config({ path: envPath })
+  }
+}
+
+export default defineConfig({
+  test: {
+    globals: false,
+    environment: 'node',
+    include: ['test/**/*.test.ts'],
+    // Exclude runtime-specific tests (use separate configs)
+    exclude: [
+      'test/rpc/workers/**',
+      'test/rpc/bun/**',
+      'node_modules/**',
+    ],
+    testTimeout: 60000, // AI calls can take time
+    hookTimeout: 30000,
+    // Run tests sequentially to avoid rate limiting
+    pool: 'forks',
+    poolOptions: {
+      forks: {
+        singleFork: true,
+      },
+    },
+  },
+})

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2023 Nathan Clevenger
-
-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/db/cache.ts

@@ -1,6 +0,0 @@
-import crypto from 'node:crypto'
-
-export const md5 = (data: string | object) => {
-  const input = typeof data === 'string' ? data : JSON.stringify(data)
-  return crypto.createHash('md5').update(input).digest('hex')
-}

package/db/mongo.ts

@@ -1,75 +0,0 @@
-import type { MongoClient, Db, Collection, InsertOneResult, BSON } from 'mongodb'
-import type { ChatCompletion, ChatCompletionCreateParamsNonStreaming } from 'openai/resources'
-import { QueueInput } from '../queue/mongo'
-
-export let client: MongoClient
-export let db: Db
-export let cache: Collection
-export let cacheTTL: number
-export let events: Collection
-export let queue: Collection
-export let actors: Collection
-
-export type AIDBConfig = {
-  client: MongoClient
-  db?: Db | string
-  cache?: Collection | string
-  cacheTTL?: number
-  actors?: Collection | string
-  events?: Collection | string
-  queue?: Collection | string
-}
-
-export type AIDB = {
-  client: MongoClient
-  db: Db
-  cache: Collection
-  cacheTTL: number
-  actors: Collection
-  events: Collection
-  queue: Collection
-  log: (prompt: ChatCompletionCreateParamsNonStreaming, completion: ChatCompletion) => Promise<InsertOneResult<any>>
-  send: (input: QueueInput | QueueInput[]) => Promise<InsertOneResult<any>>
-}
-
-export const AIDB = (args: AIDBConfig | MongoClient) => {
-  const config = (args as AIDBConfig).client ? (args as AIDBConfig) : { client: args as MongoClient }
-  client = config.client
-  db = typeof config.db === 'string' ? client.db(config.db) : config.db ?? client.db()
-  cache = typeof config.cache === 'string' ? db.collection(config.cache) : config.cache ?? db.collection('ai-cache')
-  cacheTTL = config.cacheTTL ?? 1000 * 60 * 60 * 24 * 30
-  events =
-    typeof config.events === 'string' ? db.collection(config.events) : config.events ?? db.collection('ai-events')
-  // queue = typeof config.queue === 'string' ? db.collection(config.queue) : config.queue ?? db.collection('ai-queue')
-  // actors = typeof config.queue === 'string' ? db.collection(config.queue) : config.queue ?? db.collection('ai-actors')
-  return { client, db, cache, actors, events, queue, log }  as AIDB // , send } as AIDB
-}
-
-// const send = (input: QueueInput | QueueInput[]) =>
-//   Array.isArray(input) ? queue.insertMany(input) : queue.insertOne(input)
-
-const log = (prompt: ChatCompletionCreateParamsNonStreaming, completion: ChatCompletion) => {
-  const system = prompt.messages.find((message: any) => message.role === 'system')?.content
-  const userMessages = prompt.messages.filter((message: any) => message.role === 'user').map((message) => message.content)
-  const user = userMessages.length === 1 ? userMessages[0] : userMessages
-  const content = completion.choices?.[0].message.content
-  const tool = completion.choices?.[0].message.tool_calls?.[0].function
-  let functionData: object | string | undefined
-  try {
-    if (tool) functionData = JSON.parse(tool.arguments)
-  } catch (err) {
-    functionData = tool?.arguments
-  }
-  const timestamp = new Date()
-  const event = {
-    timestamp,
-    user,
-    system,
-    content,
-    functionName: tool?.name,
-    functionData,
-    prompt,
-    completion,
-  }
-  return events.insertOne(event, { ignoreUndefined: true })
-}

package/dist/mjs/db/cache.d.ts

@@ -1 +0,0 @@
-export declare const md5: (data: string | object) => string;

package/dist/mjs/db/cache.js

@@ -1,5 +0,0 @@
-import crypto from 'node:crypto';
-export const md5 = (data) => {
-    const input = typeof data === 'string' ? data : JSON.stringify(data);
-    return crypto.createHash('md5').update(input).digest('hex');
-};

package/dist/mjs/db/mongo.d.ts

@@ -1,31 +0,0 @@
-import type { MongoClient, Db, Collection, InsertOneResult } from 'mongodb';
-import type { ChatCompletion, ChatCompletionCreateParamsNonStreaming } from 'openai/resources';
-import { QueueInput } from '../queue/mongo';
-export declare let client: MongoClient;
-export declare let db: Db;
-export declare let cache: Collection;
-export declare let cacheTTL: number;
-export declare let events: Collection;
-export declare let queue: Collection;
-export declare let actors: Collection;
-export type AIDBConfig = {
-    client: MongoClient;
-    db?: Db | string;
-    cache?: Collection | string;
-    cacheTTL?: number;
-    actors?: Collection | string;
-    events?: Collection | string;
-    queue?: Collection | string;
-};
-export type AIDB = {
-    client: MongoClient;
-    db: Db;
-    cache: Collection;
-    cacheTTL: number;
-    actors: Collection;
-    events: Collection;
-    queue: Collection;
-    log: (prompt: ChatCompletionCreateParamsNonStreaming, completion: ChatCompletion) => Promise<InsertOneResult<any>>;
-    send: (input: QueueInput | QueueInput[]) => Promise<InsertOneResult<any>>;
-};
-export declare const AIDB: (args: AIDBConfig | MongoClient) => AIDB;

package/dist/mjs/db/mongo.js

@@ -1,48 +0,0 @@
-export let client;
-export let db;
-export let cache;
-export let cacheTTL;
-export let events;
-export let queue;
-export let actors;
-export const AIDB = (args) => {
-    const config = args.client ? args : { client: args };
-    client = config.client;
-    db = typeof config.db === 'string' ? client.db(config.db) : config.db ?? client.db();
-    cache = typeof config.cache === 'string' ? db.collection(config.cache) : config.cache ?? db.collection('ai-cache');
-    cacheTTL = config.cacheTTL ?? 1000 * 60 * 60 * 24 * 30;
-    events =
-        typeof config.events === 'string' ? db.collection(config.events) : config.events ?? db.collection('ai-events');
-    // queue = typeof config.queue === 'string' ? db.collection(config.queue) : config.queue ?? db.collection('ai-queue')
-    // actors = typeof config.queue === 'string' ? db.collection(config.queue) : config.queue ?? db.collection('ai-actors')
-    return { client, db, cache, actors, events, queue, log }; // , send } as AIDB
-};
-// const send = (input: QueueInput | QueueInput[]) =>
-//   Array.isArray(input) ? queue.insertMany(input) : queue.insertOne(input)
-const log = (prompt, completion) => {
-    const system = prompt.messages.find((message) => message.role === 'system')?.content;
-    const userMessages = prompt.messages.filter((message) => message.role === 'user').map((message) => message.content);
-    const user = userMessages.length === 1 ? userMessages[0] : userMessages;
-    const content = completion.choices?.[0].message.content;
-    const tool = completion.choices?.[0].message.tool_calls?.[0].function;
-    let functionData;
-    try {
-        if (tool)
-            functionData = JSON.parse(tool.arguments);
-    }
-    catch (err) {
-        functionData = tool?.arguments;
-    }
-    const timestamp = new Date();
-    const event = {
-        timestamp,
-        user,
-        system,
-        content,
-        functionName: tool?.name,
-        functionData,
-        prompt,
-        completion,
-    };
-    return events.insertOne(event, { ignoreUndefined: true });
-};