ai-functions 0.3.0 → 0.4.0

package/dist/batch-queue.d.ts

@@ -0,0 +1,273 @@
+/**
+ * BatchQueue - Deferred execution queue for batch processing
+ *
+ * Collects AI operations and submits them to provider batch APIs
+ * for cost-effective processing (typically 50% discount, 24hr turnaround).
+ *
+ * @example
+ * ```ts
+ * // Create a batch queue
+ * const batch = createBatch({ provider: 'openai' })
+ *
+ * // Add items to the batch (these are deferred, not executed)
+ * const titles = await list`10 blog post titles about startups`
+ * const posts = titles.map(title => batch.add(write`blog post about ${title}`))
+ *
+ * // Submit the batch - returns job info
+ * const job = await batch.submit()
+ * console.log(job.id) // batch_abc123
+ *
+ * // Poll for results or use webhook
+ * const results = await batch.wait()
+ * ```
+ *
+ * @packageDocumentation
+ */
+import type { FunctionOptions } from './template.js';
+import type { SimpleSchema } from './schema.js';
+/** Batch processing mode */
+export type BatchMode = 'sync' | 'async' | 'background';
+/** Supported batch providers */
+export type BatchProvider = 'openai' | 'anthropic' | 'google' | 'bedrock' | 'cloudflare';
+/** Status of a batch job */
+export type BatchStatus = 'pending' | 'validating' | 'in_progress' | 'finalizing' | 'completed' | 'failed' | 'expired' | 'cancelling' | 'cancelled';
+/** Individual item in a batch */
+export interface BatchItem<T = unknown> {
+    /** Unique ID for this item */
+    id: string;
+    /** The prompt to process */
+    prompt: string;
+    /** Schema for structured output */
+    schema?: SimpleSchema;
+    /** Generation options */
+    options?: FunctionOptions;
+    /** Custom metadata */
+    metadata?: Record<string, unknown>;
+    /** Resolved value (after completion) */
+    result?: T;
+    /** Error if failed */
+    error?: string;
+    /** Status of this item */
+    status: 'pending' | 'completed' | 'failed';
+}
+/** Batch job information */
+export interface BatchJob {
+    /** Unique batch ID */
+    id: string;
+    /** Provider this batch was submitted to */
+    provider: BatchProvider;
+    /** Current status */
+    status: BatchStatus;
+    /** Number of items in the batch */
+    totalItems: number;
+    /** Number of completed items */
+    completedItems: number;
+    /** Number of failed items */
+    failedItems: number;
+    /** When the batch was created */
+    createdAt: Date;
+    /** When the batch started processing */
+    startedAt?: Date;
+    /** When the batch completed */
+    completedAt?: Date;
+    /** Expected completion time */
+    expiresAt?: Date;
+    /** Webhook URL for completion notification */
+    webhookUrl?: string;
+    /** Input file ID (for OpenAI) */
+    inputFileId?: string;
+    /** Output file ID (for OpenAI) */
+    outputFileId?: string;
+    /** Error file ID (for OpenAI) */
+    errorFileId?: string;
+}
+/** Result of a batch submission */
+export interface BatchSubmitResult {
+    job: BatchJob;
+    /** Promise that resolves when batch is complete */
+    completion: Promise<BatchResult[]>;
+}
+/** Result of a single item in the batch */
+export interface BatchResult<T = unknown> {
+    /** Item ID */
+    id: string;
+    /** Custom ID if provided */
+    customId?: string;
+    /** Status */
+    status: 'completed' | 'failed';
+    /** The result (if successful) */
+    result?: T;
+    /** Error message (if failed) */
+    error?: string;
+    /** Token usage */
+    usage?: {
+        promptTokens: number;
+        completionTokens: number;
+        totalTokens: number;
+    };
+}
+/** Options for creating a batch queue */
+export interface BatchQueueOptions {
+    /** Provider to use for batch processing */
+    provider?: BatchProvider;
+    /** Model to use */
+    model?: string;
+    /** Webhook URL for completion notification */
+    webhookUrl?: string;
+    /** Custom metadata for the batch */
+    metadata?: Record<string, unknown>;
+    /** Maximum items per batch (provider-specific limits) */
+    maxItems?: number;
+    /** Auto-submit when queue reaches maxItems */
+    autoSubmit?: boolean;
+}
+/**
+ * BatchQueue collects AI operations for deferred batch execution
+ */
+export declare class BatchQueue {
+    private items;
+    private options;
+    private idCounter;
+    private submitted;
+    private job;
+    constructor(options?: BatchQueueOptions);
+    /**
+     * Add an item to the batch queue
+     * Returns a placeholder that will be resolved after batch completion
+     */
+    add<T = unknown>(prompt: string, options?: {
+        schema?: SimpleSchema;
+        options?: FunctionOptions;
+        customId?: string;
+        metadata?: Record<string, unknown>;
+    }): BatchItem<T>;
+    /**
+     * Get all items in the queue
+     */
+    getItems(): BatchItem[];
+    /**
+     * Get the number of items in the queue
+     */
+    get size(): number;
+    /**
+     * Check if the batch has been submitted
+     */
+    get isSubmitted(): boolean;
+    /**
+     * Get the batch job info (after submission)
+     */
+    getJob(): BatchJob | null;
+    /**
+     * Submit the batch to the provider
+     */
+    submit(): Promise<BatchSubmitResult>;
+    /**
+     * Cancel the batch (if supported by provider)
+     */
+    cancel(): Promise<void>;
+    /**
+     * Get the current status of the batch
+     */
+    getStatus(): Promise<BatchJob>;
+    /**
+     * Wait for the batch to complete and return results
+     */
+    wait(pollInterval?: number): Promise<BatchResult[]>;
+}
+/**
+ * Interface for provider-specific batch implementations
+ */
+export interface BatchAdapter {
+    /** Submit a batch to the provider */
+    submit(items: BatchItem[], options: BatchQueueOptions): Promise<BatchSubmitResult>;
+    /** Get the status of a batch */
+    getStatus(batchId: string): Promise<BatchJob>;
+    /** Cancel a batch */
+    cancel(batchId: string): Promise<void>;
+    /** Get results of a completed batch */
+    getResults(batchId: string): Promise<BatchResult[]>;
+    /** Wait for batch completion */
+    waitForCompletion(batchId: string, pollInterval?: number): Promise<BatchResult[]>;
+}
+/**
+ * Interface for flex processing (faster than batch, ~50% discount)
+ * Available for OpenAI and AWS Bedrock
+ */
+export interface FlexAdapter {
+    /**
+     * Submit items for flex processing
+     * Flex is faster than batch (minutes vs hours) but has same discount
+     *
+     * @param items - Items to process
+     * @param options - Processing options
+     * @returns Results (resolves when all items complete)
+     */
+    submitFlex(items: BatchItem[], options: {
+        model?: string;
+    }): Promise<BatchResult[]>;
+}
+/**
+ * Register a batch adapter for a provider
+ */
+export declare function registerBatchAdapter(provider: BatchProvider, adapter: BatchAdapter): void;
+/**
+ * Register a flex adapter for a provider
+ */
+export declare function registerFlexAdapter(provider: BatchProvider, adapter: FlexAdapter): void;
+/**
+ * Get the batch adapter for a provider
+ */
+export declare function getBatchAdapter(provider: BatchProvider): BatchAdapter;
+/**
+ * Get the flex adapter for a provider
+ */
+export declare function getFlexAdapter(provider: BatchProvider): FlexAdapter;
+/**
+ * Check if flex is available for a provider
+ */
+export declare function hasFlexAdapter(provider: BatchProvider): boolean;
+/**
+ * Create a new batch queue
+ *
+ * @example
+ * ```ts
+ * const batch = createBatch({ provider: 'openai' })
+ * batch.add('Write a poem about cats')
+ * batch.add('Write a poem about dogs')
+ * const { job } = await batch.submit()
+ * const results = await batch.wait()
+ * ```
+ */
+export declare function createBatch(options?: BatchQueueOptions): BatchQueue;
+/**
+ * Execute operations in batch mode
+ *
+ * @example
+ * ```ts
+ * const results = await withBatch(async (batch) => {
+ *   const titles = ['TypeScript', 'React', 'Next.js']
+ *   return titles.map(title => batch.add(`Write a blog post about ${title}`))
+ * })
+ * ```
+ */
+export declare function withBatch<T>(fn: (batch: BatchQueue) => T[] | Promise<T[]>, options?: BatchQueueOptions): Promise<BatchResult<T>[]>;
+/** Symbol to mark an AIPromise as batched/deferred */
+export declare const BATCH_MODE_SYMBOL: unique symbol;
+/** Options for deferred execution */
+export interface DeferredOptions extends FunctionOptions {
+    /** Batch queue to add to */
+    batch?: BatchQueue;
+    /** Custom ID for this item in the batch */
+    customId?: string;
+}
+/**
+ * Check if we're in batch mode
+ */
+export declare function isBatchMode(options?: DeferredOptions): boolean;
+/**
+ * Add an operation to the batch queue instead of executing immediately
+ */
+export declare function deferToBatch<T>(batch: BatchQueue, prompt: string, schema: SimpleSchema | undefined, options?: FunctionOptions & {
+    customId?: string;
+}): BatchItem<T>;
+//# sourceMappingURL=batch-queue.d.ts.map

package/dist/batch-queue.d.ts.map

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

package/dist/batch-queue.js

@@ -0,0 +1,271 @@
+/**
+ * BatchQueue - Deferred execution queue for batch processing
+ *
+ * Collects AI operations and submits them to provider batch APIs
+ * for cost-effective processing (typically 50% discount, 24hr turnaround).
+ *
+ * @example
+ * ```ts
+ * // Create a batch queue
+ * const batch = createBatch({ provider: 'openai' })
+ *
+ * // Add items to the batch (these are deferred, not executed)
+ * const titles = await list`10 blog post titles about startups`
+ * const posts = titles.map(title => batch.add(write`blog post about ${title}`))
+ *
+ * // Submit the batch - returns job info
+ * const job = await batch.submit()
+ * console.log(job.id) // batch_abc123
+ *
+ * // Poll for results or use webhook
+ * const results = await batch.wait()
+ * ```
+ *
+ * @packageDocumentation
+ */
+// ============================================================================
+// BatchQueue Implementation
+// ============================================================================
+/**
+ * BatchQueue collects AI operations for deferred batch execution
+ */
+export class BatchQueue {
+    items = [];
+    options;
+    idCounter = 0;
+    submitted = false;
+    job = null;
+    constructor(options = {}) {
+        this.options = {
+            provider: 'openai',
+            maxItems: 50000, // OpenAI's limit
+            autoSubmit: false,
+            ...options,
+        };
+    }
+    /**
+     * Add an item to the batch queue
+     * Returns a placeholder that will be resolved after batch completion
+     */
+    add(prompt, options) {
+        if (this.submitted) {
+            throw new Error('Cannot add items to a submitted batch');
+        }
+        const item = {
+            id: options?.customId || `item_${++this.idCounter}`,
+            prompt,
+            schema: options?.schema,
+            options: options?.options,
+            metadata: options?.metadata,
+            status: 'pending',
+        };
+        this.items.push(item);
+        // Auto-submit if we hit the limit
+        if (this.options.autoSubmit && this.items.length >= (this.options.maxItems || 50000)) {
+            // Fire and forget - user can await the completion promise
+            this.submit().catch(console.error);
+        }
+        return item;
+    }
+    /**
+     * Get all items in the queue
+     */
+    getItems() {
+        return [...this.items];
+    }
+    /**
+     * Get the number of items in the queue
+     */
+    get size() {
+        return this.items.length;
+    }
+    /**
+     * Check if the batch has been submitted
+     */
+    get isSubmitted() {
+        return this.submitted;
+    }
+    /**
+     * Get the batch job info (after submission)
+     */
+    getJob() {
+        return this.job;
+    }
+    /**
+     * Submit the batch to the provider
+     */
+    async submit() {
+        if (this.submitted) {
+            throw new Error('Batch has already been submitted');
+        }
+        if (this.items.length === 0) {
+            throw new Error('Cannot submit empty batch');
+        }
+        this.submitted = true;
+        // Get the appropriate batch adapter
+        const adapter = getBatchAdapter(this.options.provider || 'openai');
+        // Submit the batch
+        const result = await adapter.submit(this.items, this.options);
+        this.job = result.job;
+        // When completion resolves, update item statuses
+        result.completion.then((results) => {
+            for (const r of results) {
+                const item = this.items.find((i) => i.id === r.id);
+                if (item) {
+                    item.status = r.status;
+                    item.result = r.result;
+                    item.error = r.error;
+                }
+            }
+        });
+        return result;
+    }
+    /**
+     * Cancel the batch (if supported by provider)
+     */
+    async cancel() {
+        if (!this.job) {
+            throw new Error('Batch has not been submitted');
+        }
+        const adapter = getBatchAdapter(this.options.provider || 'openai');
+        await adapter.cancel(this.job.id);
+        this.job.status = 'cancelling';
+    }
+    /**
+     * Get the current status of the batch
+     */
+    async getStatus() {
+        if (!this.job) {
+            throw new Error('Batch has not been submitted');
+        }
+        const adapter = getBatchAdapter(this.options.provider || 'openai');
+        this.job = await adapter.getStatus(this.job.id);
+        return this.job;
+    }
+    /**
+     * Wait for the batch to complete and return results
+     */
+    async wait(pollInterval = 5000) {
+        if (!this.job) {
+            throw new Error('Batch has not been submitted');
+        }
+        const adapter = getBatchAdapter(this.options.provider || 'openai');
+        return adapter.waitForCompletion(this.job.id, pollInterval);
+    }
+}
+// Adapter registry
+const adapters = {
+    openai: null,
+    anthropic: null,
+    google: null,
+    bedrock: null,
+    cloudflare: null,
+};
+// Flex adapter registry (only OpenAI and Bedrock support flex)
+const flexAdapters = {
+    openai: null,
+    anthropic: null,
+    google: null,
+    bedrock: null,
+    cloudflare: null,
+};
+/**
+ * Register a batch adapter for a provider
+ */
+export function registerBatchAdapter(provider, adapter) {
+    adapters[provider] = adapter;
+}
+/**
+ * Register a flex adapter for a provider
+ */
+export function registerFlexAdapter(provider, adapter) {
+    flexAdapters[provider] = adapter;
+}
+/**
+ * Get the batch adapter for a provider
+ */
+export function getBatchAdapter(provider) {
+    const adapter = adapters[provider];
+    if (!adapter) {
+        throw new Error(`No batch adapter registered for provider: ${provider}. ` +
+            `Import the adapter: import 'ai-functions/batch/${provider}'`);
+    }
+    return adapter;
+}
+/**
+ * Get the flex adapter for a provider
+ */
+export function getFlexAdapter(provider) {
+    const adapter = flexAdapters[provider];
+    if (!adapter) {
+        throw new Error(`No flex adapter registered for provider: ${provider}. ` +
+            `Flex processing is only available for OpenAI and AWS Bedrock.`);
+    }
+    return adapter;
+}
+/**
+ * Check if flex is available for a provider
+ */
+export function hasFlexAdapter(provider) {
+    return flexAdapters[provider] !== null;
+}
+// ============================================================================
+// Factory Functions
+// ============================================================================
+/**
+ * Create a new batch queue
+ *
+ * @example
+ * ```ts
+ * const batch = createBatch({ provider: 'openai' })
+ * batch.add('Write a poem about cats')
+ * batch.add('Write a poem about dogs')
+ * const { job } = await batch.submit()
+ * const results = await batch.wait()
+ * ```
+ */
+export function createBatch(options) {
+    return new BatchQueue(options);
+}
+/**
+ * Execute operations in batch mode
+ *
+ * @example
+ * ```ts
+ * const results = await withBatch(async (batch) => {
+ *   const titles = ['TypeScript', 'React', 'Next.js']
+ *   return titles.map(title => batch.add(`Write a blog post about ${title}`))
+ * })
+ * ```
+ */
+export async function withBatch(fn, options) {
+    const batch = createBatch(options);
+    const items = await fn(batch);
+    if (batch.size === 0) {
+        return [];
+    }
+    const { completion } = await batch.submit();
+    return completion;
+}
+// ============================================================================
+// Deferred Execution Support
+// ============================================================================
+/** Symbol to mark an AIPromise as batched/deferred */
+export const BATCH_MODE_SYMBOL = Symbol.for('ai-batch-mode');
+/**
+ * Check if we're in batch mode
+ */
+export function isBatchMode(options) {
+    return !!options?.batch;
+}
+/**
+ * Add an operation to the batch queue instead of executing immediately
+ */
+export function deferToBatch(batch, prompt, schema, options) {
+    return batch.add(prompt, {
+        schema,
+        options,
+        customId: options?.customId,
+    });
+}
+//# sourceMappingURL=batch-queue.js.map

package/dist/batch-queue.js.map

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

package/dist/context.d.ts

@@ -0,0 +1,133 @@
+/**
+ * Execution Context for AI Functions
+ *
+ * Provides configuration without polluting function signatures.
+ * Settings flow from environment → global context → local context.
+ *
+ * @example
+ * ```ts
+ * // Set global defaults (from environment or initialization)
+ * configure({
+ *   provider: 'anthropic',
+ *   model: 'claude-sonnet-4-20250514',
+ *   batchMode: 'auto', // 'auto' | 'immediate' | 'deferred'
+ * })
+ *
+ * // Or use execution context for specific operations
+ * await withContext({ provider: 'openai', model: 'gpt-4o' }, async () => {
+ *   const titles = await list`10 blog titles`
+ *   return titles.map(title => write`blog post: ${title}`)
+ * })
+ * ```
+ *
+ * @packageDocumentation
+ */
+import type { FunctionOptions } from './template.js';
+import type { BatchProvider } from './batch-queue.js';
+/** Batch execution mode */
+export type BatchMode = 'auto' | 'immediate' | 'flex' | 'deferred';
+/** Execution context configuration */
+export interface ExecutionContext extends FunctionOptions {
+    /** Batch provider to use */
+    provider?: BatchProvider;
+    /** Batch execution mode */
+    batchMode?: BatchMode;
+    /** Minimum items to use flex processing (for 'auto' mode, default: 5) */
+    flexThreshold?: number;
+    /** Minimum items to use batch API (for 'auto' mode, default: 500) */
+    batchThreshold?: number;
+    /** Webhook URL for batch completion notifications */
+    webhookUrl?: string;
+    /** Custom metadata for batch jobs */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Configure global defaults for AI functions
+ *
+ * @example
+ * ```ts
+ * configure({
+ *   model: 'claude-sonnet-4-20250514',
+ *   provider: 'anthropic',
+ *   batchMode: 'auto',
+ *   batchThreshold: 5,
+ * })
+ * ```
+ */
+export declare function configure(context: ExecutionContext): void;
+/**
+ * Get the current global context
+ */
+export declare function getGlobalContext(): ExecutionContext;
+/**
+ * Reset global context to defaults
+ */
+export declare function resetContext(): void;
+/**
+ * Get the current execution context
+ * Merges: environment defaults → global context → local context
+ */
+export declare function getContext(): ExecutionContext;
+/**
+ * Run a function with a specific execution context
+ *
+ * @example
+ * ```ts
+ * const posts = await withContext({ provider: 'openai', batchMode: 'deferred' }, async () => {
+ *   const titles = await list`10 blog titles`
+ *   return titles.map(title => write`blog post: ${title}`)
+ * })
+ * ```
+ */
+export declare function withContext<T>(context: ExecutionContext, fn: () => T | Promise<T>): T | Promise<T>;
+/**
+ * Get the effective model from context
+ */
+export declare function getModel(): string;
+/**
+ * Get the effective provider from context
+ */
+export declare function getProvider(): BatchProvider;
+/**
+ * Get the effective batch mode from context
+ */
+export declare function getBatchMode(): BatchMode;
+/**
+ * Get the flex threshold from context (minimum items to use flex)
+ * Default: 5 items
+ */
+export declare function getFlexThreshold(): number;
+/**
+ * Get the batch threshold from context (minimum items to use full batch)
+ * Default: 500 items
+ */
+export declare function getBatchThreshold(): number;
+/** Execution tier for processing */
+export type ExecutionTier = 'immediate' | 'flex' | 'batch';
+/**
+ * Determine the execution tier for a given number of items
+ *
+ * Auto mode tiers:
+ * - immediate: < flexThreshold (default 5) - concurrent requests, full price
+ * - flex: flexThreshold to batchThreshold (5-500) - ~50% discount, minutes
+ * - batch: >= batchThreshold (500+) - 50% discount, up to 24hr
+ *
+ * @example
+ * ```ts
+ * getExecutionTier(3)   // 'immediate' (< 5)
+ * getExecutionTier(50)  // 'flex' (5-500)
+ * getExecutionTier(1000) // 'batch' (500+)
+ * ```
+ */
+export declare function getExecutionTier(itemCount: number): ExecutionTier;
+/**
+ * Check if we should use the batch API for a given number of items
+ * @deprecated Use getExecutionTier() instead for more granular control
+ */
+export declare function shouldUseBatchAPI(itemCount: number): boolean;
+/**
+ * Check if flex processing is available for the current provider
+ * Only OpenAI and AWS Bedrock support flex processing currently
+ */
+export declare function isFlexAvailable(): boolean;
+//# sourceMappingURL=context.d.ts.map