/**
 * Chain Helper Functions
 *
 * Utility functions for parsing call_chain paths, resolving values,
 * and deep merging results in prompt chains.
 */
import type { Logger, ChainFieldDefinition, ChainVariableDefinition, ChainImageDefinition, ChainCallResult, PromptVariables } from './types.js';
interface ParsedPath {
    call_index: number;
    property_path: string[];
}
/**
 * Parse a call_chain path expression like "call[0].tax_category" or "call[2].data.nested.value"
 *
 * @param path_expr - The path expression to parse
 * @param logger - Logger instance
 * @returns Parsed path with call index and property path array, or null if invalid
 */
export declare function parse_call_chain_path(path_expr: string, logger: Logger): ParsedPath | null;
/**
 * Extract a value from a nested object using a property path array
 *
 * @param obj - The object to extract from
 * @param path - Array of property names to traverse
 * @param logger - Logger instance
 * @returns The extracted value as a string, or null if not found
 */
export declare function extract_value_from_path(obj: Record<string, unknown>, path: string[], logger: Logger): string | null;
/**
 * Extract a value from a ChainCallResult using a property path
 * Supports both parsed_result fields and top-level image/text fields
 *
 * Examples:
 * - "image_b64" -> returns result.image_b64
 * - "image_mime_type" -> returns result.image_mime_type
 * - "raw_text" -> returns result.raw_text
 * - "country" -> traverses result.parsed_result.country
 * - "data.nested.value" -> traverses result.parsed_result.data.nested.value
 *
 * @param result - The ChainCallResult to extract from
 * @param property_path - Array of property names to traverse
 * @param logger - Logger instance
 * @returns The extracted value as a string, or null if not found
 */
export declare function extract_value_from_result(result: ChainCallResult, property_path: string[], logger: Logger): string | null;
/**
 * Resolve a chain field definition to its actual value
 * Supports both parsed_result fields and top-level image/text fields
 *
 * @param field - The field definition to resolve
 * @param previous_results - Array of previous call results
 * @param logger - Logger instance
 * @returns Resolved string value, or null if resolution failed
 */
export declare function resolve_chain_field(field: ChainFieldDefinition, previous_results: ChainCallResult[], logger: Logger): string | null;
/**
 * Resolve a chain variable definition to its actual value
 * Supports both parsed_result fields and top-level image/text fields
 *
 * @param variable - The variable definition to resolve
 * @param previous_results - Array of previous call results
 * @param logger - Logger instance
 * @returns Resolved string value, or null if resolution failed
 */
export declare function resolve_chain_variable(variable: ChainVariableDefinition, previous_results: ChainCallResult[], logger: Logger): string | null;
/**
 * Build prompt variables from a variables array in a chain call definition
 *
 * @param variables_array - Array of variable definitions
 * @param previous_results - Array of previous call results
 * @param logger - Logger instance
 * @returns PromptVariables array for substitution
 */
export declare function build_prompt_variables(variables_array: ChainVariableDefinition[] | undefined, previous_results: ChainCallResult[], logger: Logger): PromptVariables;
/**
 * Resolved image data from a ChainImageDefinition
 */
export interface ResolvedImage {
    image_b64: string;
    image_mime_type: string;
}
/**
 * Resolve a ChainImageDefinition to actual image data
 *
 * @param image_def - The image definition to resolve
 * @param previous_results - Array of previous call results
 * @param logger - Logger instance
 * @returns Resolved image data or null if resolution failed
 */
export declare function resolve_chain_image_definition(image_def: ChainImageDefinition, previous_results: ChainCallResult[], logger: Logger): ResolvedImage | null;
/**
 * Deep merge two objects, with source values overwriting target values
 *
 * @param target - Target object
 * @param source - Source object to merge in
 * @returns New merged object
 */
export declare function deep_merge(target: Record<string, unknown>, source: Record<string, unknown>): Record<string, unknown>;
/**
 * Merge multiple call results into a single object
 *
 * @param results - Array of chain call results
 * @param logger - Logger instance
 * @returns Deep-merged object from all successful calls
 */
export declare function merge_chain_results(results: ChainCallResult[], logger: Logger): Record<string, unknown>;
/**
 * Attempt to parse LLM response text as JSON
 * Handles common LLM output formats (with markdown code blocks, etc.)
 *
 * @param text - Raw text response from LLM
 * @param logger - Logger instance
 * @returns Parsed JSON object or null if parsing fails
 */
export declare function parse_llm_json_response(text: string, logger: Logger): Record<string, unknown> | null;
export {};
//# sourceMappingURL=chain_helpers.d.ts.map