@bratsos/workflow-engine 0.0.11 → 0.2.0

package/dist/client-D4PoxADF.d.ts

@@ -0,0 +1,798 @@
+import { ToolSet, generateText, StepResult, streamText } from 'ai';
+import z$1, { z } from 'zod';
+import { A as AICallLogger } from './interface-MMqhfQQK.js';
+import { b as StageContext, c as SuspendedStateSchema, C as CheckCompletionContext, d as CompletionCheckResult, S as Stage } from './stage-BPw7m9Wx.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;
+
+/**
+ * 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 WorkflowCompletedPayload as $, type AIBatch as A, type BatchLogFn as B, getModel as C, DEFAULT_MODEL_KEY as D, type EmbedOptions as E, getModelById as F, getRegisteredModel as G, listModels as H, type InferInput as I, listRegisteredModels as J, modelSupportsBatch as K, type LogContext as L, ModelKey as M, NoInputSchema as N, type ObjectOptions as O, printAvailableModels as P, registerModels as Q, type RecordCallParams as R, type SimpleStageResult as S, type TextOptions as T, requireStageOutput as U, type LogPayload as V, type WorkflowEventType as W, type ModelFilter as X, type StageCompletedPayload as Y, type StageFailedPayload as Z, type StageStartedPayload as _, type AIBatchHandle as a, type WorkflowFailedPayload as a0, type WorkflowStartedPayload as a1, type WorkflowSuspendedPayload as a2, type AIBatchProvider as b, type AIBatchRequest as c, type AIBatchResult as d, type AICallType as e, type AIEmbedResult as f, type AIHelper as g, type AIObjectResult as h, type AIStreamResult as i, type AITextResult as j, AVAILABLE_MODELS as k, type AsyncBatchStageDefinition as l, type EnhancedStageContext as m, type ModelConfig as n, type ModelRegistry as o, type ModelStats as p, ModelStatsTracker as q, type ModelSyncConfig as r, type StreamOptions as s, type SyncStageDefinition as t, type WorkflowSSEEvent as u, calculateCost as v, createAIHelper as w, defineAsyncBatchStage as x, defineStage as y, getDefaultModel as z };