ai-functions 0.2.19 → 0.4.0

package/src/schema.ts

@@ -0,0 +1,147 @@
+/**
+ * Simplified schema syntax for AI generation
+ *
+ * Converts human-readable schema definitions to Zod schemas:
+ * - 'description' → z.string().describe('description')
+ * - 'description (number)' → z.number().describe('description')
+ * - 'description (boolean)' → z.boolean().describe('description')
+ * - 'description (integer)' → z.number().int().describe('description')
+ * - 'description (date)' → z.string().datetime().describe('description')
+ * - 'opt1 | opt2 | opt3' → z.enum(['opt1', 'opt2', 'opt3'])
+ * - ['description'] → z.array(z.string()).describe('description')
+ * - { nested } → z.object() recursively
+ *
+ * @packageDocumentation
+ */
+
+import { z, type ZodTypeAny } from 'zod'
+
+/**
+ * Simplified schema types
+ */
+export type SimpleSchema =
+  | string                           // z.string().describe(value)
+  | [string]                         // z.array(z.string()).describe(value)
+  | [number]                         // z.array(z.number()).describe(value)
+  | [SimpleSchema]                   // z.array(converted).describe(value)
+  | { [key: string]: SimpleSchema }  // z.object() recursively
+  | ZodTypeAny                       // Pass-through for actual Zod schemas
+
+/**
+ * Check if value is a Zod schema
+ */
+function isZodSchema(value: unknown): value is ZodTypeAny {
+  return value !== null &&
+    typeof value === 'object' &&
+    '_def' in value &&
+    'parse' in value
+}
+
+/**
+ * Convert a simplified schema to a Zod schema
+ *
+ * @example
+ * ```ts
+ * import { schema } from 'ai-functions'
+ * import { z } from 'zod'
+ *
+ * // These are equivalent:
+ * const simple = schema({
+ *   name: 'What is the recipe name?',
+ *   ingredients: ['List all ingredients'],
+ *   steps: ['List all cooking steps'],
+ * })
+ *
+ * const zod = z.object({
+ *   name: z.string().describe('What is the recipe name?'),
+ *   ingredients: z.array(z.string()).describe('List all ingredients'),
+ *   steps: z.array(z.string()).describe('List all cooking steps'),
+ * })
+ * ```
+ */
+export function schema<T extends SimpleSchema>(input: T): ZodTypeAny {
+  return convertToZod(input)
+}
+
+function convertToZod(input: SimpleSchema): ZodTypeAny {
+  // Already a Zod schema - pass through
+  if (isZodSchema(input)) {
+    return input
+  }
+
+  // String handling
+  if (typeof input === 'string') {
+    // Enum syntax: 'option1 | option2 | option3'
+    if (input.includes(' | ')) {
+      const options = input.split(' | ').map(s => s.trim())
+      return z.enum(options as [string, ...string[]])
+    }
+
+    // Type hint syntax: 'description (type)'
+    const typeMatch = input.match(/^(.+?)\s*\((number|boolean|integer|date)\)$/i)
+    if (typeMatch) {
+      const [, description, type] = typeMatch
+      const desc = description!.trim()
+      switch (type!.toLowerCase()) {
+        case 'number':
+          return z.number().describe(desc)
+        case 'integer':
+          return z.number().int().describe(desc)
+        case 'boolean':
+          return z.boolean().describe(desc)
+        case 'date':
+          return z.string().datetime().describe(desc)
+        default:
+          return z.string().describe(desc)
+      }
+    }
+
+    // Regular string description → z.string().describe()
+    return z.string().describe(input)
+  }
+
+  // Array with single element → z.array().describe()
+  if (Array.isArray(input) && input.length === 1) {
+    const [desc] = input
+
+    // [string] → z.array(z.string()).describe(string)
+    if (typeof desc === 'string') {
+      return z.array(z.string()).describe(desc)
+    }
+
+    // [number] → z.array(z.number()) - number as type indicator
+    if (typeof desc === 'number') {
+      return z.array(z.number())
+    }
+
+    // [SimpleSchema] → z.array(converted)
+    return z.array(convertToZod(desc as SimpleSchema))
+  }
+
+  // Object → z.object() with recursive conversion
+  if (typeof input === 'object' && input !== null) {
+    const shape: Record<string, ZodTypeAny> = {}
+
+    for (const [key, value] of Object.entries(input)) {
+      shape[key] = convertToZod(value as SimpleSchema)
+    }
+
+    return z.object(shape)
+  }
+
+  // Fallback - shouldn't reach here
+  return z.unknown()
+}
+
+/**
+ * Type helper to infer the output type from a simple schema
+ */
+export type InferSimpleSchema<T> = T extends string
+  ? string
+  : T extends [string]
+  ? string[]
+  : T extends [number]
+  ? number[]
+  : T extends { [K in keyof T]: SimpleSchema }
+  ? { [K in keyof T]: InferSimpleSchema<T[K]> }
+  : unknown

package/src/template.ts

@@ -0,0 +1,209 @@
+/**
+ * Tagged template literal utilities
+ *
+ * Provides support for tagged template syntax across all AI functions:
+ * - fn`prompt ${variable}` - template literal syntax
+ * - Objects/arrays auto-convert to YAML
+ * - Options chaining: fn`prompt`({ model: '...' })
+ *
+ * @packageDocumentation
+ */
+
+import { stringify } from 'yaml'
+
+/**
+ * Common options for all AI functions
+ */
+export interface FunctionOptions {
+  /** Model to use (e.g., 'claude-opus-4-5', 'gpt-5-1', 'gemini-3-pro') */
+  model?: string
+  /** Thinking level: 'none', 'low', 'medium', 'high', or token budget number */
+  thinking?: 'none' | 'low' | 'medium' | 'high' | number
+  /** Temperature (0-2) */
+  temperature?: number
+  /** Maximum tokens to generate */
+  maxTokens?: number
+  /** System prompt */
+  system?: string
+  /** Processing mode */
+  mode?: 'default' | 'background'
+}
+
+/**
+ * Parse a tagged template literal into a prompt string
+ * Objects and arrays are converted to YAML for readability
+ */
+export 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)
+  }, '')
+}
+
+/**
+ * Result type that is both a Promise and can be called with options
+ */
+export type ChainablePromise<T> = Promise<T> & {
+  (options?: FunctionOptions): Promise<T>
+}
+
+/**
+ * Create a chainable promise that supports both await and options chaining
+ */
+export function createChainablePromise<T>(
+  executor: (options?: FunctionOptions) => Promise<T>,
+  defaultOptions?: FunctionOptions
+): ChainablePromise<T> {
+  // Create the base promise
+  const basePromise = executor(defaultOptions)
+
+  // Create a function that accepts options
+  const chainable = ((options?: FunctionOptions) => {
+    return executor({ ...defaultOptions, ...options })
+  }) as ChainablePromise<T>
+
+  // Make it thenable
+  chainable.then = basePromise.then.bind(basePromise)
+  chainable.catch = basePromise.catch.bind(basePromise)
+  ;(chainable as Promise<T>).finally = basePromise.finally.bind(basePromise)
+
+  return chainable
+}
+
+/**
+ * Template function signature
+ */
+export type TemplateFunction<T> = {
+  (strings: TemplateStringsArray, ...values: unknown[]): ChainablePromise<T>
+  (prompt: string, options?: FunctionOptions): Promise<T>
+}
+
+/**
+ * Create a function that supports both tagged templates and regular calls
+ */
+export function createTemplateFunction<T>(
+  handler: (prompt: string, options?: FunctionOptions) => Promise<T>
+): TemplateFunction<T> {
+  function templateFn(
+    promptOrStrings: string | TemplateStringsArray,
+    ...args: unknown[]
+  ): Promise<T> | ChainablePromise<T> {
+    // Tagged template literal
+    if (Array.isArray(promptOrStrings) && 'raw' in promptOrStrings) {
+      const prompt = parseTemplate(promptOrStrings as TemplateStringsArray, ...args)
+      return createChainablePromise((options) => handler(prompt, options))
+    }
+
+    // Regular function call
+    return handler(promptOrStrings as string, args[0] as FunctionOptions | undefined)
+  }
+
+  return templateFn as TemplateFunction<T>
+}
+
+/**
+ * Create a function with batch support
+ */
+export interface BatchableFunction<T, TInput = string> extends TemplateFunction<T> {
+  batch: (inputs: TInput[]) => Promise<T[]>
+}
+
+/**
+ * Add batch capability to a template function
+ */
+export function withBatch<T, TInput = string>(
+  fn: TemplateFunction<T>,
+  batchHandler: (inputs: TInput[]) => Promise<T[]>
+): BatchableFunction<T, TInput> {
+  const batchable = fn as BatchableFunction<T, TInput>
+  batchable.batch = batchHandler
+  return batchable
+}
+
+/**
+ * Create an async iterable from a streaming generator
+ */
+export function createAsyncIterable<T>(
+  items: T[] | (() => AsyncGenerator<T>)
+): AsyncIterable<T> {
+  if (Array.isArray(items)) {
+    return {
+      async *[Symbol.asyncIterator]() {
+        for (const item of items) {
+          yield item
+        }
+      },
+    }
+  }
+  return {
+    [Symbol.asyncIterator]: items,
+  }
+}
+
+/**
+ * Create a result that is both a Promise (resolves to array) and AsyncIterable (streams items)
+ */
+export type StreamableList<T> = Promise<T[]> & AsyncIterable<T>
+
+export function createStreamableList<T>(
+  getItems: () => Promise<T[]>,
+  streamItems?: () => AsyncGenerator<T>
+): StreamableList<T> {
+  const promise = getItems()
+
+  const asyncIterator = streamItems
+    ? streamItems
+    : async function* () {
+        const items = await promise
+        for (const item of items) {
+          yield item
+        }
+      }
+
+  // Create a proper Promise-like object with async iterator
+  const result = Object.create(null) as StreamableList<T>
+
+  // Add Promise methods
+  Object.defineProperty(result, 'then', {
+    value: promise.then.bind(promise),
+    writable: false,
+    enumerable: false,
+  })
+  Object.defineProperty(result, 'catch', {
+    value: promise.catch.bind(promise),
+    writable: false,
+    enumerable: false,
+  })
+  Object.defineProperty(result, 'finally', {
+    value: promise.finally.bind(promise),
+    writable: false,
+    enumerable: false,
+  })
+
+  // Add async iterator
+  Object.defineProperty(result, Symbol.asyncIterator, {
+    value: asyncIterator,
+    writable: false,
+    enumerable: false,
+  })
+
+  // Add Symbol.toStringTag for Promise compatibility
+  Object.defineProperty(result, Symbol.toStringTag, {
+    value: 'Promise',
+    writable: false,
+    enumerable: false,
+  })
+
+  return result
+}