@bratsos/workflow-engine 0.0.11 → 0.1.0

package/dist/client-5vz5Vv4A.d.ts

@@ -0,0 +1,938 @@
+import { ToolSet, generateText, StepResult, streamText } from 'ai';
+import z$1, { z } from 'zod';
+import { A as AICallLogger } from './interface-Cv22wvLG.js';
+
+/**
+ * Schema Helpers and Utilities
+ *
+ * Provides common schemas and utilities for building type-safe workflows.
+ * Reduces boilerplate and enforces best practices.
+ */
+
+/**
+ * Constant for stages that don't need sequential input
+ * Use when a stage receives data from workflowContext instead of the input parameter
+ *
+ * @example
+ * export const myStage: Stage<
+ *   typeof NoInputSchema,  // Explicit: this stage uses workflowContext
+ *   typeof OutputSchema,
+ *   typeof ConfigSchema
+ * > = {
+ *   inputSchema: NoInputSchema,
+ *   // ...
+ * };
+ */
+declare const NoInputSchema: z.ZodObject<{}, z.core.$strip>;
+/**
+ * Access previous stage output with guaranteed type safety
+ *
+ * Requires that the stage output exists, throws clear error if missing.
+ * Use this for required dependencies on previous stages.
+ *
+ * @param workflowContext - The workflow context containing all previous stage outputs
+ * @param stageId - ID of the stage to access
+ * @param field - Optional: specific field to extract from stage output
+ * @returns The stage output (or field within it)
+ * @throws Error if stage or field is missing
+ *
+ * @example
+ * // Get entire stage output
+ * const extractedData = requireStageOutput<ExtractedData>(
+ *   context.workflowContext,
+ *   "data-extraction"
+ * );
+ *
+ * // Get specific field
+ * const guidelines = requireStageOutput<Guideline[]>(
+ *   context.workflowContext,
+ *   "guidelines",
+ *   "guidelines"
+ * );
+ */
+declare function requireStageOutput<T>(workflowContext: Record<string, unknown>, stageId: string, field?: string): T;
+
+/**
+ * Core type definitions for Workflow System v2
+ *
+ * See WORKFLOW_SYSTEM_PROPOSAL.md for full architectural details
+ */
+
+interface ProgressUpdate {
+    stageId: string;
+    stageName: string;
+    progress: number;
+    message: string;
+    details?: Record<string, unknown>;
+}
+interface StageMetrics {
+    startTime: number;
+    endTime: number;
+    duration: number;
+    itemsProcessed?: number;
+    itemsProduced?: number;
+    aiCalls?: number;
+    totalTokens?: number;
+    totalCost?: number;
+}
+interface EmbeddingResult {
+    id: string;
+    content: string;
+    embedding: number[];
+    similarity?: number;
+    metadata?: Record<string, unknown>;
+}
+interface EmbeddingInfo {
+    model: string;
+    dimensions: number;
+    results: EmbeddingResult[];
+    totalProcessed?: number;
+    averageSimilarity?: number;
+}
+interface StageResult<TOutput> {
+    output: TOutput;
+    metrics: StageMetrics;
+    artifacts?: Record<string, unknown>;
+    embeddings?: EmbeddingInfo;
+}
+declare const SuspendedStateSchema: z.ZodObject<{
+    batchId: z.ZodString;
+    statusUrl: z.ZodOptional<z.ZodString>;
+    apiKey: z.ZodOptional<z.ZodString>;
+    submittedAt: z.ZodString;
+    pollInterval: z.ZodNumber;
+    maxWaitTime: z.ZodNumber;
+    metadata: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
+}, z.core.$strip>;
+interface SuspendedResult {
+    suspended: true;
+    state: z.infer<typeof SuspendedStateSchema>;
+    pollConfig: {
+        pollInterval: number;
+        maxWaitTime: number;
+        nextPollAt: Date;
+    };
+    metrics: StageMetrics;
+}
+interface CompletionCheckResult<TOutput> {
+    ready: boolean;
+    output?: TOutput;
+    error?: string;
+    nextCheckIn?: number;
+    metrics?: StageMetrics;
+    embeddings?: EmbeddingInfo;
+}
+type LogLevel = "DEBUG" | "INFO" | "WARN" | "ERROR";
+type StageMode = "sync" | "async-batch";
+
+/**
+ * Stage interface and context definitions
+ *
+ * Stages are the building blocks of workflows. Each stage:
+ * - Has strongly-typed input, output, and config schemas (Zod)
+ * - Can be sync or async-batch
+ * - Has access to AI helper, storage, and logging via context
+ * - Can suspend workflow for long-running batch operations
+ */
+
+interface StageContext<TInput, TConfig, TWorkflowContext = Record<string, unknown>> {
+    workflowRunId: string;
+    stageId: string;
+    stageNumber: number;
+    stageName: string;
+    /** Database record ID for this stage execution (for logging to persistence) */
+    stageRecordId?: string;
+    input: TInput;
+    config: TConfig;
+    resumeState?: z.infer<typeof SuspendedStateSchema>;
+    onProgress: (update: ProgressUpdate) => void;
+    onLog: (level: LogLevel, message: string, meta?: Record<string, unknown>) => void;
+    log: (level: LogLevel, message: string, meta?: Record<string, unknown>) => void;
+    storage: StageStorage;
+    workflowContext: Partial<TWorkflowContext>;
+}
+interface StageStorage {
+    save<T>(key: string, data: T): Promise<void>;
+    load<T>(key: string): Promise<T>;
+    exists(key: string): Promise<boolean>;
+    delete(key: string): Promise<void>;
+    getStageKey(stageId: string, suffix?: string): string;
+}
+/**
+ * Context passed to checkCompletion for async-batch stages.
+ * Includes identification info so stages don't need to store it in metadata.
+ */
+interface CheckCompletionContext<TConfig> {
+    workflowRunId: string;
+    stageId: string;
+    /** Database record ID for this stage execution (for logging to persistence) */
+    stageRecordId?: string;
+    config: TConfig;
+    onLog: (level: LogLevel, message: string, meta?: Record<string, unknown>) => void;
+    log: (level: LogLevel, message: string, meta?: Record<string, unknown>) => void;
+    storage: StageStorage;
+}
+interface Stage<TInput extends z.ZodTypeAny, TOutput extends z.ZodTypeAny, TConfig extends z.ZodTypeAny, TWorkflowContext = Record<string, unknown>> {
+    id: string;
+    name: string;
+    description?: string;
+    /**
+     * Optional: List of stage IDs that this stage depends on.
+     * The workflow builder will validate that all dependencies are present
+     * in the workflow before this stage is executed.
+     *
+     * Example: dependencies: ["data-extraction", "guidelines"]
+     */
+    dependencies?: string[];
+    inputSchema: TInput;
+    outputSchema: TOutput;
+    configSchema: TConfig;
+    execute: (context: StageContext<z.infer<TInput>, z.infer<TConfig>, TWorkflowContext>) => Promise<StageResult<z.infer<TOutput>> | SuspendedResult>;
+    checkCompletion?: (suspendedState: z.infer<typeof SuspendedStateSchema>, context: CheckCompletionContext<z.infer<TConfig>>) => Promise<CompletionCheckResult<z.infer<TOutput>>>;
+    mode?: StageMode;
+    estimateCost?: (input: z.infer<TInput>, config: z.infer<TConfig>) => number;
+}
+
+/**
+ * Stage Factory - Simplified stage definition with auto-metrics
+ *
+ * Provides a `defineStage()` function that reduces boilerplate by:
+ * - Inferring types from schemas
+ * - Auto-calculating metrics (timing handled by executor)
+ * - Adding fluent context helpers (require/optional)
+ * - Supporting both sync and async-batch modes
+ *
+ * @example
+ * ```typescript
+ * export const myStage = defineStage({
+ *   id: "my-stage",
+ *   name: "My Stage",
+ *   description: "Does something useful",
+ *   dependencies: ["previous-stage"],
+ *
+ *   schemas: {
+ *     input: InputSchema,      // or "none" for NoInputSchema
+ *     output: OutputSchema,
+ *     config: ConfigSchema,
+ *   },
+ *
+ *   async execute(ctx) {
+ *     const prevData = ctx.require("previous-stage");
+ *     // ... stage logic
+ *     return { output: { ... } };
+ *   },
+ * });
+ * ```
+ */
+
+/**
+ * Helper type to safely infer input type, handling the "none" special case
+ */
+type InferInput<TInput extends z.ZodTypeAny | "none"> = TInput extends "none" ? z.infer<typeof NoInputSchema> : TInput extends z.ZodTypeAny ? z.infer<TInput> : never;
+/**
+ * Enhanced stage context with fluent helpers
+ */
+interface EnhancedStageContext<TInput, TConfig, TContext extends Record<string, unknown>> extends StageContext<TInput, TConfig, TContext> {
+    /**
+     * Require output from a previous stage (throws if not found)
+     *
+     * @example
+     * const { extractedData } = ctx.require("data-extraction");
+     */
+    require: <K extends keyof TContext>(stageId: K) => TContext[K];
+    /**
+     * Optionally get output from a previous stage (returns undefined if not found)
+     *
+     * @example
+     * const optionalData = ctx.optional("optional-stage");
+     * if (optionalData) { ... }
+     */
+    optional: <K extends keyof TContext>(stageId: K) => TContext[K] | undefined;
+}
+/**
+ * Simplified execute result - just output and optional custom metrics
+ */
+interface SimpleStageResult<TOutput> {
+    output: TOutput;
+    /**
+     * Custom metrics specific to this stage (e.g., itemsProcessed, sectionsFound)
+     * Timing metrics (startTime, endTime, duration) are auto-calculated by executor
+     * AI metrics should be added here by stages that create their own AIHelper
+     */
+    customMetrics?: Record<string, number>;
+    /**
+     * Optional artifacts to store
+     */
+    artifacts?: Record<string, unknown>;
+}
+/**
+ * Simplified suspended result - metrics are auto-filled by the factory
+ */
+interface SimpleSuspendedResult {
+    suspended: true;
+    state: {
+        batchId: string;
+        submittedAt: string;
+        pollInterval: number;
+        maxWaitTime: number;
+        metadata?: Record<string, unknown>;
+        apiKey?: string;
+    };
+    pollConfig: {
+        pollInterval: number;
+        maxWaitTime: number;
+        nextPollAt: Date;
+    };
+    /**
+     * Optional custom metrics (timing & AI metrics are auto-filled)
+     */
+    customMetrics?: Record<string, number>;
+}
+/**
+ * Sync stage definition
+ */
+interface SyncStageDefinition<TInput extends z.ZodTypeAny | "none", TOutput extends z.ZodTypeAny, TConfig extends z.ZodTypeAny, TContext extends Record<string, unknown> = Record<string, unknown>> {
+    /** Unique stage identifier */
+    id: string;
+    /** Human-readable name */
+    name: string;
+    /** Optional description */
+    description?: string;
+    /** Stage IDs this stage depends on (validated at workflow build time) */
+    dependencies?: string[];
+    /** Zod schemas for validation */
+    schemas: {
+        /** Input schema, or "none" for stages that use workflowContext */
+        input: TInput;
+        /** Output schema */
+        output: TOutput;
+        /** Configuration schema */
+        config: TConfig;
+    };
+    /**
+     * Execute the stage logic
+     * Return just { output } - metrics are auto-calculated
+     */
+    execute: (ctx: EnhancedStageContext<InferInput<TInput>, z.infer<TConfig>, TContext>) => Promise<SimpleStageResult<z.infer<TOutput>>>;
+    /**
+     * Optional: Estimate cost before execution
+     */
+    estimateCost?: (input: InferInput<TInput>, config: z.infer<TConfig>) => number;
+}
+/**
+ * Async-batch stage definition (for long-running batch jobs)
+ */
+interface AsyncBatchStageDefinition<TInput extends z.ZodTypeAny | "none", TOutput extends z.ZodTypeAny, TConfig extends z.ZodTypeAny, TContext extends Record<string, unknown> = Record<string, unknown>> extends Omit<SyncStageDefinition<TInput, TOutput, TConfig, TContext>, "execute"> {
+    /** Mark as async-batch mode */
+    mode: "async-batch";
+    /**
+     * Execute the stage - either return result or suspend for batch processing
+     *
+     * When resuming from suspension, ctx.resumeState contains the suspended state.
+     * Check this to determine whether to submit a new batch or fetch results.
+     *
+     * Return SimpleSuspendedResult when suspending - metrics will be auto-filled.
+     */
+    execute: (ctx: EnhancedStageContext<InferInput<TInput>, z.infer<TConfig>, TContext>) => Promise<SimpleStageResult<z.infer<TOutput>> | SimpleSuspendedResult>;
+    /**
+     * Check if the batch job is complete
+     * Called by the orchestrator when polling suspended stages
+     *
+     * Context includes workflowRunId, stageId, config, log, and storage
+     * so you don't need to store these in metadata.
+     */
+    checkCompletion: (suspendedState: z.infer<typeof SuspendedStateSchema>, context: CheckCompletionContext<z.infer<TConfig>>) => Promise<CompletionCheckResult<z.infer<TOutput>>>;
+}
+/**
+ * Define a sync stage with simplified API
+ */
+declare function defineStage<TInput extends z.ZodTypeAny | "none", TOutput extends z.ZodTypeAny, TConfig extends z.ZodTypeAny, TContext extends Record<string, unknown> = Record<string, unknown>>(definition: SyncStageDefinition<TInput, TOutput, TConfig, TContext>): Stage<TInput extends "none" ? typeof NoInputSchema : TInput, TOutput, TConfig, TContext>;
+/**
+ * Define an async-batch stage with simplified API
+ */
+declare function defineStage<TInput extends z.ZodTypeAny | "none", TOutput extends z.ZodTypeAny, TConfig extends z.ZodTypeAny, TContext extends Record<string, unknown> = Record<string, unknown>>(definition: AsyncBatchStageDefinition<TInput, TOutput, TConfig, TContext>): Stage<TInput extends "none" ? typeof NoInputSchema : TInput, TOutput, TConfig, TContext>;
+/**
+ * Define an async-batch stage with proper type inference for checkCompletion
+ *
+ * This is a dedicated function (not an alias) to ensure TypeScript properly
+ * infers callback parameter types without overload resolution ambiguity.
+ */
+declare function defineAsyncBatchStage<TInput extends z.ZodTypeAny | "none", TOutput extends z.ZodTypeAny, TConfig extends z.ZodTypeAny, TContext extends Record<string, unknown> = Record<string, unknown>>(definition: AsyncBatchStageDefinition<TInput, TOutput, TConfig, TContext>): Stage<TInput extends "none" ? typeof NoInputSchema : TInput, TOutput, TConfig, TContext>;
+
+/**
+ * Model Helper - Centralized model selection and cost tracking for AI scripts
+ */
+
+interface ModelConfig {
+    id: string;
+    name: string;
+    inputCostPerMillion: number;
+    outputCostPerMillion: number;
+    provider: "openrouter" | "google" | "other";
+    description?: string;
+    supportsAsyncBatch?: boolean;
+    batchDiscountPercent?: number;
+    isEmbeddingModel?: boolean;
+    supportsTools?: boolean;
+    supportsStructuredOutputs?: boolean;
+    contextLength?: number;
+    maxCompletionTokens?: number | null;
+}
+/**
+ * Filter options for listModels()
+ */
+interface ModelFilter {
+    /** Only include embedding models */
+    isEmbeddingModel?: boolean;
+    /** Only include models that support function calling */
+    supportsTools?: boolean;
+    /** Only include models that support structured outputs */
+    supportsStructuredOutputs?: boolean;
+    /** Only include models that support async batch */
+    supportsAsyncBatch?: boolean;
+}
+/**
+ * Configuration for workflow-engine.models.ts sync config
+ */
+interface ModelSyncConfig {
+    /** Only include models matching these patterns (applied before exclude) */
+    include?: (string | RegExp)[];
+    /** Output path relative to consumer's project root (default: src/generated/models.ts) */
+    outputPath?: string;
+    /** Patterns to exclude models (string for exact match, RegExp for pattern) */
+    exclude?: (string | RegExp)[];
+    /** Custom models to add (embeddings, rerankers, etc.) */
+    customModels?: Record<string, ModelConfig>;
+}
+/**
+ * Model Registry - augmented by consumer's generated file for autocomplete
+ * Import the generated file to populate this interface
+ */
+interface ModelRegistry {
+}
+/**
+ * Register models at runtime (called by generated file)
+ */
+declare function registerModels(models: Record<string, ModelConfig>): void;
+/**
+ * Get a model from the runtime registry
+ */
+declare function getRegisteredModel(key: string): ModelConfig | undefined;
+/**
+ * List all registered models
+ */
+declare function listRegisteredModels(): Array<{
+    key: string;
+    config: ModelConfig;
+}>;
+interface ModelStats {
+    modelId: string;
+    modelName: string;
+    apiCalls: number;
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+    inputCost: number;
+    outputCost: number;
+    totalCost: number;
+}
+/**
+ * Static enum for built-in models - provides .enum accessor for AVAILABLE_MODELS keys
+ */
+declare const ModelKeyEnum: z$1.ZodEnum<{
+    "gemini-2.5-flash": "gemini-2.5-flash";
+}>;
+/**
+ * Type representing all available model keys
+ * Supports both built-in enum keys AND dynamically registered keys via ModelRegistry
+ */
+type ModelKey = z$1.infer<typeof ModelKeyEnum> | keyof ModelRegistry;
+/**
+ * Zod schema that validates model keys against both the static enum AND the runtime registry
+ * Use ModelKey.parse() to validate and type model key strings
+ */
+declare const ModelKey: z$1.ZodPipe<z$1.ZodString, z$1.ZodTransform<"gemini-2.5-flash", string>>;
+/**
+ * Available AI models with their configurations
+ * Prices should be updated regularly from provider pricing pages
+ */
+declare const AVAILABLE_MODELS: Record<string, ModelConfig>;
+/**
+ * Default model selection
+ * Change this to switch the default model across all scripts
+ */
+declare const DEFAULT_MODEL_KEY: ModelKey;
+/**
+ * Get a model configuration by key
+ * Checks both built-in AVAILABLE_MODELS and runtime MODEL_REGISTRY
+ */
+declare function getModel(key: ModelKey): ModelConfig;
+/**
+ * Get the default model configuration
+ */
+declare function getDefaultModel(): ModelConfig;
+/**
+ * List all available models (built-in + registered)
+ * @param filter Optional filter to narrow down models by capability
+ */
+declare function listModels(filter?: ModelFilter): Array<{
+    key: string;
+    config: ModelConfig;
+}>;
+/**
+ * Check if a model supports async batch processing
+ */
+declare function modelSupportsBatch(modelKey: ModelKey): boolean;
+/**
+ * Interface for model with bound recording function
+ * Useful for parallel execution where you want to pass model + recordCall together
+ */
+interface ModelWithRecorder {
+    id: string;
+    name: string;
+    recordCall: (inputTokens: number, outputTokens: number) => void;
+}
+/**
+ * Get model by key with bound recordCall function
+ * Perfect for parallel execution - no need to write model name twice
+ *
+ * Usage:
+ * const model = getModelById("gemini-2.5-flash", modelTracker);
+ * const result = await generateText({
+ *   model: openRouter(model.id),
+ *   prompt: "...",
+ * });
+ * model.recordCall(result.usage.inputTokens, result.usage.outputTokens);
+ */
+declare function getModelById(modelKey: ModelKey, tracker?: ModelStatsTracker): ModelWithRecorder;
+/**
+ * Calculate costs based on token usage
+ */
+declare function calculateCost(modelKey: ModelKey, inputTokens: number, outputTokens: number): {
+    inputCost: number;
+    outputCost: number;
+    totalCost: number;
+};
+/**
+ * Model stats tracker class - tracks single model OR aggregates multiple models
+ */
+declare class ModelStatsTracker {
+    private modelKey?;
+    private modelConfig?;
+    private stats;
+    private perModelStats;
+    private isAggregating;
+    constructor(modelKey?: ModelKey);
+    /**
+     * Create an aggregating tracker that combines stats from multiple models
+     * Perfect for parallel execution where different calls use different models
+     */
+    static createAggregating(): ModelStatsTracker;
+    /**
+     * Get the model ID for use with AI SDK
+     * @deprecated Use getModelById(modelKey).id instead for parallel execution
+     */
+    getModelId(): string;
+    /**
+     * Get the model configuration
+     * @deprecated Use getModelById(modelKey) instead for parallel execution
+     */
+    getModelConfig(): ModelConfig;
+    /**
+     * Switch model (useful for sequential model switching)
+     * @deprecated For parallel execution, pass model key to recordCall() instead
+     */
+    switchModel(modelKey: ModelKey): void;
+    /**
+     * Get a model helper with bound recordCall for parallel execution
+     * Perfect for running multiple AI calls in parallel with different models
+     *
+     * Usage:
+     *   const flashModel = tracker.getModelById("gemini-2.5-flash");
+     *   const liteModel = tracker.getModelById("gemini-2.5-flash-lite");
+     *
+     *   const [result1, result2] = await Promise.all([
+     *     generateText({
+     *       model: openRouter(flashModel.id),
+     *       prompt: prompt1,
+     *     }).then(r => { flashModel.recordCall(r.usage.inputTokens, r.usage.outputTokens); return r; }),
+     *     generateText({
+     *       model: openRouter(liteModel.id),
+     *       prompt: prompt2,
+     *     }).then(r => { liteModel.recordCall(r.usage.inputTokens, r.usage.outputTokens); return r; }),
+     *   ]);
+     */
+    getModelById(modelKey: ModelKey): {
+        id: string;
+        name: string;
+        recordCall: (inputTokens: number, outputTokens: number) => void;
+    };
+    /**
+     * Record an API call with token usage
+     *
+     * For sequential execution:
+     *   tracker.switchModel("gemini-2.5-flash")
+     *   tracker.recordCall(inputTokens, outputTokens)
+     *
+     * For parallel execution:
+     *   tracker.recordCall(inputTokens, outputTokens, "gemini-2.5-flash")
+     *   tracker.recordCall(inputTokens, outputTokens, "gemini-2.5-pro")
+     */
+    recordCall(inputTokens?: number, outputTokens?: number, modelKeyOverride?: ModelKey): void;
+    /**
+     * Estimate cost for a prompt without making an API call
+     * Useful for dry-run mode to preview costs
+     *
+     * Note: This method is async because it lazy-loads the tiktoken library
+     * to avoid bundling 2MB of tokenizer data for browser clients.
+     *
+     * @param prompt - The prompt text to estimate
+     * @param estimatedOutputTokens - Estimated number of output tokens (default: 500)
+     * @returns Object with token counts and cost estimates
+     */
+    estimateCost(prompt: string, estimatedOutputTokens?: number): Promise<{
+        inputTokens: number;
+        outputTokens: number;
+        totalTokens: number;
+        inputCost: number;
+        outputCost: number;
+        totalCost: number;
+    }>;
+    /**
+     * Get current statistics (single model or aggregated)
+     * Returns null only if tracker is in aggregating mode - use getAggregatedStats() instead
+     */
+    getStats(): ModelStats | null;
+    /**
+     * Get aggregated statistics from all models
+     */
+    getAggregatedStats(): {
+        perModel: ModelStats[];
+        totals: {
+            totalApiCalls: number;
+            totalInputTokens: number;
+            totalOutputTokens: number;
+            totalTokens: number;
+            totalInputCost: number;
+            totalOutputCost: number;
+            totalCost: number;
+        };
+    };
+    /**
+     * Print statistics to console
+     */
+    printStats(): void;
+    /**
+     * Print aggregated statistics from all models
+     */
+    printAggregatedStats(): void;
+    /**
+     * Reset statistics
+     */
+    reset(): void;
+}
+/**
+ * Print available models to console
+ */
+declare function printAvailableModels(): void;
+
+/**
+ * AI Helper - Unified AI interaction tracking with hierarchical topics
+ *
+ * This is the new unified AI tracking system that replaces workflow-specific tracking.
+ * It supports:
+ * - Hierarchical topics for flexible categorization (e.g., "workflow.abc.stage.extraction")
+ * - All AI call types: generateText, generateObject, embed, streamText, batch
+ * - Automatic cost calculation with batch discounts
+ * - Persistent DB logging to AICall table
+ *
+ * @example
+ * ```typescript
+ * const ai = createAIHelper("workflow.abc123").createChild("stage", "extraction");
+ * const result = await ai.generateText("gemini-2.5-flash", prompt);
+ * ```
+ */
+
+type AICallType = "text" | "object" | "embed" | "stream" | "batch";
+interface AITextResult {
+    text: string;
+    inputTokens: number;
+    outputTokens: number;
+    cost: number;
+    /** Structured output when experimental_output is used */
+    output?: any;
+}
+interface AIObjectResult<T> {
+    object: T;
+    inputTokens: number;
+    outputTokens: number;
+    cost: number;
+}
+interface AIEmbedResult {
+    embedding: number[];
+    embeddings: number[][];
+    dimensions: number;
+    inputTokens: number;
+    cost: number;
+}
+type AISDKStreamResult = ReturnType<typeof streamText>;
+interface AIStreamResult {
+    stream: AsyncIterable<string>;
+    getUsage(): Promise<{
+        inputTokens: number;
+        outputTokens: number;
+        cost: number;
+    }>;
+    /** The raw AI SDK result - use this for methods like toUIMessageStreamResponse */
+    rawResult: AISDKStreamResult;
+}
+/**
+ * Context for logging to workflow persistence (optional).
+ * When provided, batch operations can log to the database.
+ */
+interface LogContext {
+    workflowRunId: string;
+    stageRecordId: string;
+    /** Function to create a log entry in persistence */
+    createLog: (data: {
+        workflowRunId: string;
+        workflowStageId: string;
+        level: "DEBUG" | "INFO" | "WARN" | "ERROR";
+        message: string;
+        metadata?: Record<string, unknown>;
+    }) => Promise<void>;
+}
+/** Log function type for batch operations */
+type BatchLogFn = (level: "DEBUG" | "INFO" | "WARN" | "ERROR", message: string, meta?: Record<string, unknown>) => void;
+interface TextOptions<TTools extends ToolSet = ToolSet> {
+    temperature?: number;
+    maxTokens?: number;
+    /** Tool definitions for the model to use */
+    tools?: TTools;
+    /** Tool choice: 'auto' (default), 'required' (force tool use), 'none', or specific tool name */
+    toolChoice?: Parameters<typeof generateText>[0]["toolChoice"];
+    /** Condition to stop tool execution (e.g., stepCountIs(3)) */
+    stopWhen?: Parameters<typeof generateText>[0]["stopWhen"];
+    /** Callback fired when each step completes (for collecting tool results) */
+    onStepFinish?: (stepResult: StepResult<TTools>) => Promise<void> | void;
+    /** Experimental structured output - use with tools for combined tool calling + structured output */
+    experimental_output?: Parameters<typeof generateText>[0]["experimental_output"];
+}
+interface ObjectOptions<TTools extends ToolSet = ToolSet> {
+    temperature?: number;
+    maxTokens?: number;
+    /** Tool definitions for the model to use */
+    tools?: TTools;
+    /** Condition to stop tool execution (e.g., stepCountIs(3)) */
+    stopWhen?: Parameters<typeof generateText>[0]["stopWhen"];
+    /** Callback fired when each step completes (for collecting tool results) */
+    onStepFinish?: (stepResult: StepResult<TTools>) => Promise<void> | void;
+}
+interface EmbedOptions {
+    taskType?: "RETRIEVAL_QUERY" | "RETRIEVAL_DOCUMENT" | "SEMANTIC_SIMILARITY";
+    /** Override the default embedding dimensions (from embedding-config.ts) */
+    dimensions?: number;
+}
+interface StreamOptions {
+    temperature?: number;
+    maxTokens?: number;
+    onChunk?: (chunk: string) => void;
+    /** Tool definitions for the model to use */
+    tools?: Parameters<typeof streamText>[0]["tools"];
+    /** Condition to stop tool execution (e.g., stepCountIs(3)) */
+    stopWhen?: Parameters<typeof streamText>[0]["stopWhen"];
+    /** Callback fired when each step completes (for collecting tool results) */
+    onStepFinish?: Parameters<typeof streamText>[0]["onStepFinish"];
+}
+interface MediaPart {
+    type: "file";
+    data: Buffer | Uint8Array | string;
+    mediaType: string;
+    filename?: string;
+}
+interface TextPart {
+    type: "text";
+    text: string;
+}
+type ContentPart = TextPart | MediaPart;
+type TextInput = string | ContentPart[];
+type StreamTextInput = {
+    prompt: string;
+    messages?: never;
+    system?: string;
+} | {
+    messages: Parameters<typeof streamText>[0]["messages"];
+    prompt?: never;
+    system?: string;
+};
+/** Provider identifier for batch operations */
+type AIBatchProvider = "google" | "anthropic" | "openai";
+/** A request to be processed in a batch */
+interface AIBatchRequest {
+    /** Unique identifier for this request (used to match results) */
+    id: string;
+    /** The prompt to send to the model */
+    prompt: string;
+    /** Optional Zod schema for structured JSON output */
+    schema?: z.ZodTypeAny;
+}
+/** Result of a single request in a batch */
+interface AIBatchResult<T = string> {
+    /** The request ID (matches the id from AIBatchRequest) */
+    id: string;
+    /** Original prompt (may be empty if not available from provider) */
+    prompt: string;
+    /** The parsed result (JSON object if schema was provided, otherwise string) */
+    result: T;
+    /** Input tokens used */
+    inputTokens: number;
+    /** Output tokens used */
+    outputTokens: number;
+    /** Status of this individual result */
+    status: "succeeded" | "failed";
+    /** Error message if status is "failed" */
+    error?: string;
+}
+/** Handle for tracking a submitted batch */
+interface AIBatchHandle {
+    /** Batch identifier from the provider */
+    id: string;
+    /** Current status of the batch */
+    status: "pending" | "processing" | "completed" | "failed";
+    /** The provider used for this batch (for resume support) */
+    provider?: AIBatchProvider;
+}
+/** Interface for batch operations on an AI model */
+interface AIBatch<T = string> {
+    /** Submit requests for batch processing */
+    submit(requests: AIBatchRequest[]): Promise<AIBatchHandle>;
+    /** Check the status of a batch */
+    getStatus(batchId: string): Promise<AIBatchHandle>;
+    /** Retrieve results from a completed batch */
+    getResults(batchId: string, metadata?: Record<string, unknown>): Promise<AIBatchResult<T>[]>;
+    /** Check if results have been recorded for this batch */
+    isRecorded(batchId: string): Promise<boolean>;
+    /** Record batch results manually when batch provider integration is not implemented */
+    recordResults(batchId: string, results: AIBatchResult<T>[]): Promise<void>;
+}
+interface RecordCallParams {
+    modelKey: ModelKey;
+    callType: AICallType;
+    prompt: string;
+    response: string;
+    inputTokens: number;
+    outputTokens: number;
+    metadata?: Record<string, unknown>;
+}
+interface AIHelperStats {
+    totalCalls: number;
+    totalInputTokens: number;
+    totalOutputTokens: number;
+    totalCost: number;
+    perModel: Record<string, {
+        calls: number;
+        inputTokens: number;
+        outputTokens: number;
+        cost: number;
+    }>;
+}
+interface AIHelper {
+    /** Current topic path */
+    readonly topic: string;
+    generateText<TTools extends ToolSet = ToolSet>(modelKey: ModelKey, prompt: TextInput, options?: TextOptions<TTools>): Promise<AITextResult>;
+    generateObject<TSchema extends z.ZodTypeAny>(modelKey: ModelKey, prompt: TextInput, schema: TSchema, options?: ObjectOptions): Promise<AIObjectResult<z.infer<TSchema>>>;
+    embed(modelKey: ModelKey, text: string | string[], options?: EmbedOptions): Promise<AIEmbedResult>;
+    streamText(modelKey: ModelKey, input: StreamTextInput, options?: StreamOptions): AIStreamResult;
+    batch<T = string>(modelKey: ModelKey, provider?: AIBatchProvider): AIBatch<T>;
+    createChild(segment: string, id?: string): AIHelper;
+    recordCall(params: RecordCallParams): void;
+    recordCall(modelKey: ModelKey, prompt: string, response: string, tokens: {
+        input: number;
+        output: number;
+    }, options?: {
+        callType?: AICallType;
+        isBatch?: boolean;
+        metadata?: Record<string, unknown>;
+    }): void;
+    getStats(): Promise<AIHelperStats>;
+}
+/**
+ * Create an AI helper instance with topic-based tracking.
+ *
+ * @param topic - Initial topic path (e.g., "workflow.abc123" or "reranker")
+ * @returns AIHelper instance
+ *
+ * @example
+ * ```typescript
+ * // Simple topic
+ * const ai = createAIHelper("reranker");
+ *
+ * // Hierarchical topic
+ * const ai = createAIHelper("workflow.abc123", logger)
+ *   .createChild("stage", "extraction");
+ * // topic: "workflow.abc123.stage.extraction"
+ *
+ * // Use AI methods
+ * const result = await ai.generateText("gemini-2.5-flash", prompt);
+ * ```
+ */
+declare function createAIHelper(topic: string, logger: AICallLogger, logContext?: LogContext): AIHelper;
+
+/**
+ * Workflow Event Types for SSE Streaming
+ *
+ * This file contains ONLY types and interfaces for workflow events.
+ * It is safe to use in both client and server environments.
+ */
+interface WorkflowSSEEvent {
+    type: WorkflowEventType;
+    workflowRunId: string;
+    timestamp: Date;
+    data: Record<string, unknown>;
+}
+type WorkflowEventType = "connected" | "workflow:started" | "workflow:completed" | "workflow:suspended" | "workflow:cancelled" | "workflow:failed" | "stage:started" | "stage:progress" | "stage:completed" | "stage:suspended" | "stage:failed" | "log";
+interface WorkflowStartedPayload {
+    workflowRunId: string;
+    workflowName: string;
+}
+interface WorkflowCompletedPayload {
+    workflowRunId: string;
+    output: unknown;
+    duration?: number;
+    totalCost?: number;
+    totalTokens?: number;
+}
+interface WorkflowSuspendedPayload {
+    workflowRunId: string;
+    stageId: string;
+}
+interface WorkflowFailedPayload {
+    workflowRunId: string;
+    error: string;
+}
+interface StageStartedPayload {
+    stageId: string;
+    stageName: string;
+    stageNumber: number;
+}
+interface StageCompletedPayload {
+    stageId: string;
+    stageName: string;
+    duration: number;
+    cost?: number;
+    inputTokens?: number;
+    outputTokens?: number;
+    outputCount?: number;
+}
+interface StageFailedPayload {
+    stageId: string;
+    stageName: string;
+    error: string;
+}
+interface LogPayload {
+    level: string;
+    message: string;
+    meta?: Record<string, unknown>;
+}
+
+export { type ModelFilter as $, type AIHelper as A, type BatchLogFn as B, createAIHelper as C, DEFAULT_MODEL_KEY as D, type EmbedOptions as E, defineAsyncBatchStage as F, defineStage as G, getDefaultModel as H, type InferInput as I, getModel as J, getModelById as K, type LogContext as L, ModelKey as M, NoInputSchema as N, type ObjectOptions as O, getRegisteredModel as P, listModels as Q, type RecordCallParams as R, type Stage as S, type TextOptions as T, listRegisteredModels as U, modelSupportsBatch as V, type WorkflowEventType as W, printAvailableModels as X, registerModels as Y, requireStageOutput as Z, type LogPayload as _, type StageMetrics as a, type StageCompletedPayload as a0, type StageFailedPayload as a1, type StageStartedPayload as a2, type WorkflowCompletedPayload as a3, type WorkflowFailedPayload as a4, type WorkflowStartedPayload as a5, type WorkflowSuspendedPayload as a6, type WorkflowSSEEvent as b, type LogLevel as c, type AIBatch as d, type AIBatchHandle as e, type AIBatchProvider as f, type AIBatchRequest as g, type AIBatchResult as h, type AICallType as i, type AIEmbedResult as j, type AIObjectResult as k, type AIStreamResult as l, type AITextResult as m, AVAILABLE_MODELS as n, type AsyncBatchStageDefinition as o, type EnhancedStageContext as p, type ModelConfig as q, type ModelRegistry as r, type ModelStats as s, ModelStatsTracker as t, type ModelSyncConfig as u, type SimpleStageResult as v, type StageResult as w, type StreamOptions as x, type SyncStageDefinition as y, calculateCost as z };