ai-functions/dist/context.d.ts

Core AI primitives for building intelligent applications

/**
 * Execution Context for AI Functions
 *
 * Standalone context module with batch processing and budget tracking features.
 * 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 { BatchProvider } from './batch-queue.js';
import type { RequestContext as IRequestContext, ModelPricing } from './budget.js';
/**
 * 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';
}
/** Batch execution mode */
export type BatchMode = 'auto' | 'immediate' | 'flex' | 'deferred';
/** Budget configuration for context */
export interface ContextBudgetConfig {
    /** Maximum total tokens allowed */
    maxTokens?: number;
    /** Maximum cost in USD */
    maxCost?: number;
    /** Alert thresholds as fractions (e.g., [0.5, 0.8, 1.0]) */
    alertThresholds?: number[];
    /** Custom pricing for models not in default pricing table */
    customPricing?: Record<string, ModelPricing>;
}
/**
 * Execution context with batch processing and budget features.
 */
export interface ExecutionContext extends FunctionOptions {
    /** Provider to use (for model resolution) */
    provider?: BatchProvider | string;
    /** 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>;
    /** Budget configuration for tracking and limits */
    budget?: ContextBudgetConfig;
    /** Request context for tracing */
    requestContext?: IRequestContext;
}
/**
 * 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 (typed as BatchProvider)
 */
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 {@link getExecutionTier} instead for more granular control.
 * This function will be removed in a future major version.
 *
 * @param itemCount - Number of items to process
 * @returns true if batch or flex tier should be used, false for immediate
 *
 * @example
 * ```ts
 * // Deprecated usage:
 * if (shouldUseBatchAPI(items.length)) { ... }
 *
 * // Recommended:
 * const tier = getExecutionTier(items.length)
 * if (tier === 'batch' || tier === 'flex') { ... }
 * ```
 */
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