ai-functions 0.2.19 → 0.4.0

package/dist/ai-promise.d.ts

@@ -0,0 +1,219 @@
+/**
+ * AIPromise - RPC-style promise pipelining for AI functions
+ *
+ * Inspired by capnweb's RpcPromise, this enables:
+ * - Property access tracking for dynamic schema inference
+ * - Promise pipelining without await
+ * - Magical .map() for batch processing
+ * - Dependency graph resolution
+ *
+ * @example
+ * ```ts
+ * // Dynamic schema from destructuring
+ * const { summary, keyPoints, conclusion } = ai`write about ${topic}`
+ *
+ * // Pipeline without await
+ * const isValid = is`${conclusion} is solid given ${keyPoints}`
+ *
+ * // Batch process with map
+ * const ideas = list`startup ideas`
+ * const evaluated = await ideas.map(idea => ({
+ *   idea,
+ *   viable: is`${idea} is viable`,
+ *   market: ai`market size for ${idea}`,
+ * }))
+ *
+ * // Only await at the end
+ * if (await isValid) { ... }
+ * ```
+ *
+ * @packageDocumentation
+ */
+import type { SimpleSchema } from './schema.js';
+import type { FunctionOptions } from './template.js';
+import { BatchMapPromise } from './batch-map.js';
+/** Symbol to identify AIPromise instances */
+export declare const AI_PROMISE_SYMBOL: unique symbol;
+/** Symbol to get the raw AIPromise from a proxy */
+export declare const RAW_PROMISE_SYMBOL: unique symbol;
+/** Recording mode for map() */
+export declare const RECORDING_MODE: unique symbol;
+/** Dependency tracking */
+interface Dependency {
+    promise: AIPromise<unknown>;
+    path: string[];
+}
+/** Options for AIPromise creation */
+export interface AIPromiseOptions extends FunctionOptions {
+    /** The type of generation */
+    type?: 'text' | 'object' | 'list' | 'lists' | 'boolean' | 'extract';
+    /** Base schema (can be extended by property access) */
+    baseSchema?: SimpleSchema;
+    /** Parent promise this was derived from */
+    parent?: AIPromise<unknown>;
+    /** Property path from parent */
+    propertyPath?: string[];
+}
+/**
+ * AIPromise - Like capnweb's RpcPromise but for AI functions
+ *
+ * Acts as both a Promise AND a stub that:
+ * - Tracks property accesses for dynamic schema inference
+ * - Records dependencies for promise pipelining
+ * - Supports .map() for batch processing
+ */
+export declare class AIPromise<T> implements PromiseLike<T> {
+    /** Marker to identify AIPromise instances */
+    readonly [AI_PROMISE_SYMBOL] = true;
+    /** The prompt that will generate this value */
+    private _prompt;
+    /** Options for generation */
+    private _options;
+    /** Properties accessed on this promise (for schema inference) */
+    private _accessedProps;
+    /** Property path from parent (for nested access) */
+    private _propertyPath;
+    /** Parent promise (if this is a property access) */
+    private _parent;
+    /** Dependencies (other AIPromises used in our prompt) */
+    private _dependencies;
+    /** Cached resolver promise */
+    private _resolver;
+    /** Resolved value (cached after first resolution) */
+    private _resolvedValue;
+    /** Whether this promise has been resolved */
+    private _isResolved;
+    /** Whether we're in recording mode */
+    private _isRecording;
+    constructor(prompt: string, options?: AIPromiseOptions);
+    /** Get the prompt */
+    get prompt(): string;
+    /** Get the property path */
+    get path(): string[];
+    /** Check if resolved */
+    get isResolved(): boolean;
+    /** Get accessed properties */
+    get accessedProps(): Set<string>;
+    /**
+     * Add a dependency (another AIPromise used in this one's prompt)
+     */
+    addDependency(promise: AIPromise<unknown>, path?: string[]): void;
+    /**
+     * Resolve this promise
+     */
+    resolve(): Promise<T>;
+    /**
+     * Build schema from accessed properties and base schema
+     */
+    private _buildSchema;
+    /**
+     * Map over array results - automatically batches operations!
+     *
+     * When you map over a list, the operations are captured and
+     * automatically batched when resolved. Uses provider batch APIs
+     * for cost savings (50% discount) when beneficial.
+     *
+     * @example
+     * ```ts
+     * // Simple map - each title becomes a blog post
+     * const titles = await list`10 blog post titles`
+     * const posts = titles.map(title => write`blog post: # ${title}`)
+     * console.log(await posts) // 10 blog posts via batch API
+     *
+     * // Complex map - multiple operations per item
+     * const ideas = await list`startup ideas`
+     * const evaluated = await ideas.map(idea => ({
+     *   idea,
+     *   viable: is`${idea} is viable`,
+     *   market: ai`market size for ${idea}`,
+     * }))
+     * ```
+     */
+    map<U>(callback: (item: T extends (infer I)[] ? I : T, index: number) => U): BatchMapPromise<U>;
+    /**
+     * Map with explicit batch options
+     *
+     * @example
+     * ```ts
+     * // Force immediate execution (no batch API)
+     * const posts = titles.mapImmediate(title => write`blog post: ${title}`)
+     *
+     * // Force batch API (even for small lists)
+     * const posts = titles.mapDeferred(title => write`blog post: ${title}`)
+     * ```
+     */
+    mapImmediate<U>(callback: (item: T extends (infer I)[] ? I : T, index: number) => U): BatchMapPromise<U>;
+    mapDeferred<U>(callback: (item: T extends (infer I)[] ? I : T, index: number) => U): BatchMapPromise<U>;
+    /**
+     * ForEach with automatic batching
+     *
+     * @example
+     * ```ts
+     * await list`startup ideas`.forEach(async idea => {
+     *   console.log(await is`${idea} is viable`)
+     * })
+     * ```
+     */
+    forEach(callback: (item: T extends (infer I)[] ? I : T, index: number) => void | Promise<void>): Promise<void>;
+    /**
+     * Async iterator support with smart batching
+     */
+    [Symbol.asyncIterator](): AsyncIterator<T extends (infer I)[] ? I : T>;
+    /**
+     * 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 a value is an AIPromise
+ */
+export declare function isAIPromise(value: unknown): value is AIPromise<unknown>;
+/**
+ * Get the raw AIPromise from a proxied value
+ */
+export declare function getRawPromise<T>(value: AIPromise<T>): AIPromise<T>;
+/**
+ * Create an AIPromise for text generation
+ */
+export declare function createTextPromise(prompt: string, options?: FunctionOptions): AIPromise<string>;
+/**
+ * Create an AIPromise for object generation with dynamic schema
+ */
+export declare function createObjectPromise<T = unknown>(prompt: string, options?: FunctionOptions): AIPromise<T>;
+/**
+ * Create an AIPromise for list generation
+ */
+export declare function createListPromise(prompt: string, options?: FunctionOptions): AIPromise<string[]>;
+/**
+ * Create an AIPromise for multiple lists generation
+ */
+export declare function createListsPromise(prompt: string, options?: FunctionOptions): AIPromise<Record<string, string[]>>;
+/**
+ * Create an AIPromise for boolean/is check
+ */
+export declare function createBooleanPromise(prompt: string, options?: FunctionOptions): AIPromise<boolean>;
+/**
+ * Create an AIPromise for extraction
+ */
+export declare function createExtractPromise<T = unknown>(prompt: string, options?: FunctionOptions): AIPromise<T[]>;
+/**
+ * Parse template literals and track AIPromise dependencies
+ */
+export declare function parseTemplateWithDependencies(strings: TemplateStringsArray, ...values: unknown[]): {
+    prompt: string;
+    dependencies: Dependency[];
+};
+/**
+ * Create a template function that returns AIPromise
+ */
+export declare function createAITemplateFunction<T>(type: AIPromiseOptions['type'], baseOptions?: FunctionOptions): ((strings: TemplateStringsArray, ...values: unknown[]) => AIPromise<T>) & ((prompt: string, options?: FunctionOptions) => AIPromise<T>);
+export {};
+//# sourceMappingURL=ai-promise.d.ts.map

package/dist/ai-promise.d.ts.map

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