ai-functions/dist/batch-map.d.ts

Core AI primitives for building intelligent applications

/**
 * Batch Map - Automatic batch detection for .map() operations
 *
 * When you call .map() on a list result, the individual operations
 * are captured and automatically batched when resolved.
 *
 * @example
 * ```ts
 * // This automatically batches the write operations
 * const titles = await list`10 blog post titles`
 * const posts = titles.map(title => write`blog post: # ${title}`)
 *
 * // When awaited, posts are generated via batch API
 * console.log(await posts) // 10 blog posts
 * ```
 *
 * @packageDocumentation
 */
import type { SimpleSchema } from './schema.js';
/**
 * Symbol to identify BatchMapPromise instances
 *
 * Used internally to detect BatchMapPromise objects for proper handling.
 */
export declare const BATCH_MAP_SYMBOL: unique symbol;
/**
 * A captured operation from the map callback
 *
 * When recording mode is active, AI operations are captured instead of executed.
 * This allows batch processing of multiple operations in a single API call.
 */
export interface CapturedOperation {
    /** Unique ID for this operation */
    id: string;
    /** The prompt template */
    prompt: string;
    /** The item value that will be substituted */
    itemPlaceholder: string;
    /** Schema for structured output */
    schema?: SimpleSchema;
    /** Generation type */
    type: 'text' | 'object' | 'boolean' | 'list';
    /** System prompt */
    system?: string;
}
/**
 * Options for batch map
 *
 * Control how batch map operations are executed.
 */
export interface BatchMapOptions {
    /** Force immediate execution (no batching) */
    immediate?: boolean;
    /** Force batch API (even for small batches) */
    deferred?: boolean;
}
/**
 * A promise that represents a batch of mapped operations.
 * Resolves by either:
 * - Executing via batch API (for large batches or when deferred)
 * - Executing concurrently (for small batches or when immediate)
 */
export declare class BatchMapPromise<T> implements PromiseLike<T[]> {
    readonly [BATCH_MAP_SYMBOL] = true;
    /** The source list items */
    private _items;
    /** The captured operations (one per item) */
    private _operations;
    /** Options for batch execution */
    private _options;
    /** Cached resolver promise */
    private _resolver;
    constructor(items: unknown[], operations: CapturedOperation[][], options?: BatchMapOptions);
    /**
     * Get the number of items in the batch
     */
    get size(): number;
    /**
     * Resolve the batch
     */
    resolve(): Promise<T[]>;
    /**
     * Execute via flex processing (faster than batch, ~50% discount)
     * Available for OpenAI and AWS Bedrock
     */
    private _resolveViaFlex;
    /**
     * Execute via provider batch API (deferred, 50% discount)
     */
    private _resolveViaBatchAPI;
    /**
     * Execute immediately (concurrent requests)
     */
    private _resolveImmediately;
    /**
     * Execute a single operation
     */
    private _executeOperation;
    /**
     * Reconstruct results from batch response
     */
    private _reconstructResults;
    /**
     * Promise interface - then()
     */
    then<TResult1 = T[], TResult2 = never>(onfulfilled?: ((value: T[]) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: unknown) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
    /**
     * Promise interface - catch()
     */
    catch<TResult = never>(onrejected?: ((reason: unknown) => TResult | PromiseLike<TResult>) | null): Promise<T[] | TResult>;
    /**
     * Promise interface - finally()
     */
    finally(onfinally?: (() => void) | null): Promise<T[]>;
}
/**
 * Check if we're in recording mode
 *
 * Recording mode is active during batch map callback execution.
 * When true, AI operations are captured instead of executed.
 *
 * @returns true if currently recording operations for batch processing
 */
export declare function isInRecordingMode(): boolean;
/**
 * Get the current item placeholder for template substitution
 *
 * During recording mode, this returns a placeholder string that will be
 * replaced with the actual item value when the batch is executed.
 *
 * @returns The placeholder string if in recording mode, null otherwise
 */
export declare function getCurrentItemPlaceholder(): string | null;
/**
 * Capture an operation during recording
 *
 * Called by AI template functions when in recording mode to capture
 * operations for later batch execution.
 *
 * @param prompt - The prompt template
 * @param type - The operation type (text, object, boolean, list)
 * @param schema - Optional schema for structured output
 * @param system - Optional system prompt
 */
export declare function captureOperation(prompt: string, type: CapturedOperation['type'], schema?: SimpleSchema, system?: string): void;
/**
 * Create a batch map from an array and a callback
 *
 * This is called internally by AIPromise.map() to enable automatic
 * batch processing of mapped operations.
 *
 * @typeParam T - The type of items in the source array
 * @typeParam U - The return type of the callback
 * @param items - Array of items to map over
 * @param callback - Function called for each item (operations are captured, not executed)
 * @param options - Batch map options
 * @returns A BatchMapPromise that resolves to an array of results
 */
export declare function createBatchMap<T, U>(items: T[], callback: (item: T, index: number) => U, options?: BatchMapOptions): BatchMapPromise<U>;
/**
 * Check if a value is a BatchMapPromise
 *
 * @param value - Value to check
 * @returns true if value is a BatchMapPromise instance
 */
export declare function isBatchMapPromise(value: unknown): value is BatchMapPromise<unknown>;
//# sourceMappingURL=batch-map.d.ts.map