> ## Documentation Index
> Fetch the complete documentation index at: https://docs.reducto.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Migration Guide: V2 to V3 Config
> Complete guide for migrating from Legacy (V2) to 2025-10-14 (V3) configuration format
export const V2ToV3Converter = () => {
const isDict = value => value !== null && typeof value === 'object' && !Array.isArray(value);
const isBool = value => typeof value === 'boolean';
const pyTruthy = value => {
if (value === null || value === undefined || value === false || value === 0 || value === '') return false;
if (Array.isArray(value) || isDict(value)) return Object.keys(value).length > 0;
return true;
};
const pyString = value => typeof value === 'boolean' ? value ? 'True' : 'False' : String(value);
const pyGet = (object, key, fallback) => isDict(object) && Object.prototype.hasOwnProperty.call(object, key) ? object[key] : fallback;
const highlight = value => {
const escaped = value.replace(/&/g, '&').replace(//g, '>');
return escaped.replace(/"([^"\\]*(\\.[^"\\]*)*)"|\b(\d+\.?\d*)\b|\b(true|false|null)\b/g, (match, _stringBody, _escapedCharacter, number, literal) => {
if (number !== undefined) return `${number}`;
if (literal !== undefined) return `${literal}`;
return `${match}`;
});
};
const deepMerge = (base, override) => {
const result = {
...base
};
Object.entries(override || ({})).forEach(([key, value]) => {
const existing = result[key];
if (Object.prototype.hasOwnProperty.call(result, key) && isDict(existing) && isDict(value)) {
result[key] = deepMerge(existing, value);
} else if (value !== null) {
result[key] = value;
}
});
return result;
};
const detectRequestType = payload => {
if (Object.prototype.hasOwnProperty.call(payload, 'schema') || Object.prototype.hasOwnProperty.call(payload, 'extract_schema')) return 'extract';
if (Object.prototype.hasOwnProperty.call(payload, 'split_description')) return 'split';
return 'parse';
};
const getDefaultV2ParsePayload = () => ({
document_url: '',
options: {
ocr_mode: 'standard',
extraction_mode: 'ocr',
chunking: {
chunk_mode: 'variable'
},
table_summary: {
enabled: false
},
figure_summary: {
enabled: false,
override: false
},
filter_blocks: [],
force_url_result: false
},
advanced_options: {
ocr_system: 'highres',
table_output_format: 'html',
merge_tables: false,
include_formula_information: false,
include_color_information: false,
continue_hierarchy: true,
keep_line_breaks: false,
page_range: {},
large_table_chunking: {
enabled: true,
size: 50
},
spreadsheet_table_clustering: 'default',
add_page_markers: false,
remove_text_formatting: false,
return_ocr_data: false,
filter_line_numbers: false,
read_comments: false,
persist_results: false,
exclude_hidden_sheets: false,
exclude_hidden_rows_cols: false,
enable_change_tracking: false,
enable_highlight_detection: false
},
experimental_options: {
enrich: {
enabled: false,
mode: 'standard'
},
layout_enrichment: false,
native_docx_parsing: false,
native_office_conversion: false,
enable_checkboxes: false,
enable_equations: false,
rotate_pages: true,
rotate_figures: false,
enable_scripts: false,
return_figure_images: false,
return_table_images: false,
return_page_images: false,
layout_model: 'default',
embed_text_metadata_pdf: false,
detect_signatures: false,
danger_filter_wide_boxes: false
}
});
const getDefaultV2ExtractPayload = () => ({
...getDefaultV2ParsePayload(),
schema: {},
extract_schema: {},
system_prompt: 'Be precise and thorough.',
generate_citations: false,
array_extract: {
enabled: false,
mode: 'legacy',
pages_per_segment: 10
},
use_chunking: false,
include_images: false,
spreadsheet_agent: false,
experimental_table_citations: true,
agent_extract: {
enabled: false
},
latency_sensitive: false,
citations_options: {
numerical_confidence: false
}
});
const getDefaultV2SplitPayload = () => ({
...getDefaultV2ParsePayload(),
split_description: [],
split_rules: 'Split the document into the applicable sections. Sections may only overlap at their first and last page if at all.',
split_options: {
table_cutoff: 'truncate'
}
});
const getDefaultV2Payload = (requestType = 'parse') => requestType === 'extract' ? getDefaultV2ExtractPayload() : requestType === 'split' ? getDefaultV2SplitPayload() : getDefaultV2ParsePayload();
const findExtraFields = (input, defaults, path = '') => {
const warnings = [];
if (!isDict(input) || !isDict(defaults)) return warnings;
Object.entries(input).forEach(([key, value]) => {
const currentPath = path ? `${path}.${key}` : key;
if (!Object.prototype.hasOwnProperty.call(defaults, key)) {
warnings.push(`\`${currentPath}\` cannot be set in V3`);
} else if (isDict(value) && isDict(defaults[key])) {
warnings.push(...findExtraFields(value, defaults[key], currentPath));
}
});
return warnings;
};
const convertParseOptions = payload => {
const options = pyGet(payload, 'options', {});
const advanced = pyGet(payload, 'advanced_options', {});
const experimental = pyGet(payload, 'experimental_options', {});
const result = {
enhance: {
agentic: [],
summarize_figures: true
},
retrieval: {
chunking: {
chunk_mode: 'disabled'
},
filter_blocks: [],
embedding_optimized: false
},
formatting: {
add_page_markers: false,
table_output_format: 'dynamic',
merge_tables: false,
include: []
},
spreadsheet: {
split_large_tables: {
enabled: true,
size: 50
},
include: [],
clustering: 'accurate',
exclude: []
},
settings: {
ocr_system: 'standard',
force_url_result: false,
return_ocr_data: false,
return_images: [],
embed_pdf_metadata: false,
persist_results: false
}
};
result.retrieval.chunking = pyGet(options, 'chunking', {
chunk_mode: 'disabled'
});
if (pyGet(options, 'ocr_mode', undefined) === 'agentic') {
result.enhance.agentic.push({
scope: 'text'
}, {
scope: 'table'
});
}
result.retrieval.filter_blocks = pyGet(options, 'filter_blocks', []);
const tableSummary = pyGet(options, 'table_summary', undefined);
if (isDict(tableSummary)) result.retrieval.embedding_optimized = pyGet(tableSummary, 'enabled', false); else if (isBool(tableSummary)) result.retrieval.embedding_optimized = tableSummary;
const figureSummary = pyGet(options, 'figure_summary', undefined);
if (isDict(figureSummary)) {
result.enhance.summarize_figures = pyGet(figureSummary, 'enabled', true);
if (pyTruthy(pyGet(figureSummary, 'enhanced', undefined)) || pyTruthy(pyGet(figureSummary, 'override', undefined))) {
const figureAgentic = {
scope: 'figure'
};
if (pyTruthy(pyGet(figureSummary, 'prompt', undefined))) figureAgentic.prompt = figureSummary.prompt;
result.enhance.agentic.push(figureAgentic);
}
} else if (isBool(figureSummary)) result.enhance.summarize_figures = figureSummary;
result.settings.force_url_result = pyGet(options, 'force_url_result', false);
result.settings.extraction_mode = pyGet(options, 'extraction_mode', 'ocr');
result.settings.ocr_system = ({
highres: 'legacy',
multilingual: 'standard',
legacy: 'legacy',
reducto: 'legacy',
combined: 'standard'
})[pyGet(advanced, 'ocr_system', undefined)] || 'standard';
const tableFormat = pyGet(advanced, 'table_output_format', undefined);
result.formatting.table_output_format = tableFormat === 'jsonbbox' ? 'json' : tableFormat;
result.formatting.merge_tables = pyGet(advanced, 'merge_tables', false);
if (pyTruthy(pyGet(advanced, 'keep_line_breaks', false))) result.settings.alpha = {
keep_line_breaks: true
};
result.settings.return_ocr_data = pyGet(advanced, 'return_ocr_data', false);
result.formatting.add_page_markers = pyGet(advanced, 'add_page_markers', false);
if (pyTruthy(pyGet(advanced, 'page_range', undefined))) result.settings.page_range = pyGet(advanced, 'page_range', undefined);
if (pyTruthy(pyGet(advanced, 'document_password', undefined))) result.settings.document_password = pyGet(advanced, 'document_password', undefined);
if (pyTruthy(pyGet(advanced, 'include_color_information', false))) result.spreadsheet.include.push('cell_colors');
if (pyTruthy(pyGet(advanced, 'include_formula_information', false))) result.spreadsheet.include.push('formula');
const largeTable = pyGet(advanced, 'large_table_chunking', undefined);
if (isDict(largeTable)) {
result.spreadsheet.split_large_tables.enabled = pyGet(largeTable, 'enabled', true);
result.spreadsheet.split_large_tables.size = pyGet(largeTable, 'size', 50);
} else if (isBool(largeTable)) result.spreadsheet.split_large_tables.enabled = largeTable;
result.spreadsheet.clustering = ({
default: 'fast',
disabled: 'disabled',
intelligent: 'accurate'
})[pyGet(advanced, 'spreadsheet_table_clustering', undefined)] || 'fast';
result.settings.persist_results = pyGet(advanced, 'persist_results', false);
if (pyTruthy(pyGet(advanced, 'exclude_hidden_sheets', false))) result.spreadsheet.exclude.push('hidden_sheets');
if (pyTruthy(pyGet(advanced, 'exclude_hidden_rows_cols', false))) result.spreadsheet.exclude.push('hidden_rows', 'hidden_cols');
if (pyTruthy(pyGet(advanced, 'read_comments', false))) result.formatting.include.push('comments');
if (pyTruthy(pyGet(advanced, 'enable_change_tracking', false))) result.formatting.include.push('change_tracking');
if (pyTruthy(pyGet(advanced, 'enable_highlight_detection', false))) result.formatting.include.push('highlight');
result.settings.embed_pdf_metadata = pyGet(experimental, 'embed_text_metadata_pdf', false);
const enrich = pyGet(experimental, 'enrich', undefined);
if (isDict(enrich) && pyTruthy(pyGet(enrich, 'enabled', false)) && pyGet(enrich, 'mode', undefined) === 'table') {
const agentic = {
scope: 'table'
};
if (pyTruthy(pyGet(enrich, 'prompt', undefined))) agentic.prompt = enrich.prompt;
result.enhance.agentic.push(agentic);
}
if (pyTruthy(pyGet(experimental, 'return_figure_images', false))) result.settings.return_images.push('figure');
if (pyTruthy(pyGet(experimental, 'return_table_images', false))) result.settings.return_images.push('table');
if (pyTruthy(pyGet(experimental, 'return_page_images', false))) result.settings.return_images.push('page');
if (pyTruthy(pyGet(experimental, 'detect_signatures', false))) result.formatting.include.push('signatures');
if (pyTruthy(pyGet(experimental, 'user_specified_timeout_seconds', undefined))) result.settings.timeout = pyGet(experimental, 'user_specified_timeout_seconds', undefined);
if (pyTruthy(pyGet(experimental, 'enable_checkboxes', false))) result.settings.alpha = {
...result.settings.alpha || ({}),
enable_checkboxes: true
};
if (pyTruthy(pyGet(experimental, 'native_docx_parsing', false))) result.settings.alpha = {
...result.settings.alpha || ({}),
native_docx_parsing: true
};
const dpi = pyGet(experimental, 'dpi', undefined);
if (dpi !== null && dpi !== undefined) result.settings.alpha = {
...result.settings.alpha || ({}),
dpi
};
const customDpiModel = pyGet(experimental, 'custom_dpi_model', undefined);
if (customDpiModel !== null && customDpiModel !== undefined) result.settings.alpha = {
...result.settings.alpha || ({}),
custom_dpi_model: customDpiModel
};
const customArgs = pyGet(experimental, 'custom_dpi_additional_args', undefined);
if (pyTruthy(customArgs)) result.settings.alpha = {
...result.settings.alpha || ({}),
custom_dpi_additional_args: customArgs
};
return result;
};
const fillV2Defaults = payload => deepMerge(getDefaultV2Payload(detectRequestType(payload)), payload);
const convertV2ToV3 = input => {
const warnings = [];
const requestType = detectRequestType(input);
const defaults = getDefaultV2Payload(requestType);
warnings.push(...findExtraFields(input, defaults));
const payload = deepMerge(defaults, input);
const advanced = payload.advanced_options;
const experimental = payload.experimental_options;
const continueHierarchy = pyGet(advanced, 'continue_hierarchy', true);
if (!pyTruthy(continueHierarchy)) warnings.push(`\`advanced_options.continue_hierarchy\`=${pyString(continueHierarchy)} cannot be set in V3. V3 will default to True.`);
const removeFormatting = pyGet(advanced, 'remove_text_formatting', false);
if (pyTruthy(removeFormatting)) warnings.push(`\`advanced_options.remove_text_formatting\`=${pyString(removeFormatting)} cannot be set in V3. V3 will default to False.`);
const layoutModel = pyGet(experimental, 'layout_model', 'default');
if (layoutModel === 'default') warnings.push(`\`experimental_options.layout_model\`='${layoutModel}' cannot be set in V3. V3 will default to 'beta'.`);
const chunkTableBlocks = pyGet(experimental, 'chunk_table_blocks', false);
if (pyTruthy(chunkTableBlocks)) warnings.push(`\`experimental_options.chunk_table_blocks\`=${pyString(chunkTableBlocks)} cannot be set in V3. V3 will default to False.`);
const parsing = convertParseOptions(payload);
if (requestType === 'extract') {
const schema = pyTruthy(payload.schema) ? payload.schema : pyGet(payload, 'extract_schema', {});
const citationsOptions = pyGet(payload, 'citations_options', {});
const v3 = {
input: pyGet(payload, 'document_url', ''),
parsing,
instructions: {
schema,
system_prompt: pyGet(payload, 'system_prompt', 'Be precise and thorough.')
},
settings: {
include_images: pyGet(payload, 'include_images', false),
optimize_for_latency: pyGet(payload, 'latency_sensitive', false),
array_extract: isDict(payload.array_extract) ? pyGet(payload.array_extract, 'enabled', false) : false,
citations: {
enabled: pyGet(payload, 'generate_citations', false),
numerical_confidence: isDict(citationsOptions) ? pyGet(citationsOptions, 'numerical_confidence', true) : true,
parent_block: isDict(citationsOptions) ? pyGet(citationsOptions, 'parent_block', 'full') : 'full'
}
}
};
if (pyTruthy(payload.use_chunking)) warnings.push('`use_chunking` cannot be set in V3. Use `parsing.retrieval.chunking.chunk_mode` instead.');
if (pyTruthy(payload.spreadsheet_agent)) warnings.push('`spreadsheet_agent` cannot be set in V3. Spreadsheet agent is automatically enabled when needed.');
if (!pyTruthy(payload.experimental_table_citations)) warnings.push('`experimental_table_citations` cannot be disabled in V3. Table citations are always enabled.');
if (pyTruthy(payload.alpha_deep_extract)) warnings.push('`alpha_deep_extract` cannot be set in V3 without alpha options.');
if (pyTruthy(payload.alpha_table_citations)) warnings.push('`alpha_table_citations` cannot be set in V3 without alpha options.');
if (!pyTruthy(pyGet(payload, 'alpha_big_extraction_model', true))) warnings.push('`alpha_big_extraction_model` cannot be disabled in V3 without alpha options.');
if (isDict(payload.agent_extract) && pyTruthy(payload.agent_extract.enabled)) v3.instructions.agent_in_the_loop = {
enabled: true,
fields_to_verify: []
};
return [v3, warnings];
}
if (requestType === 'split') {
const options = pyGet(payload, 'split_options', {});
return [{
input: pyGet(payload, 'document_url', ''),
parsing,
split_description: pyGet(payload, 'split_description', []),
split_rules: pyGet(payload, 'split_rules', 'Split the document into the applicable sections. Sections may only overlap at their first and last page if at all.'),
settings: {
table_cutoff: isDict(options) ? pyGet(options, 'table_cutoff', 'truncate') : 'truncate',
allow_page_overlap: isDict(options) ? pyGet(options, 'allow_page_overlap', true) : true
}
}, warnings];
}
return [{
input: pyGet(payload, 'document_url', ''),
...parsing
}, warnings];
};
const [input, setInput] = React.useState(JSON.stringify(getDefaultV2ParsePayload(), null, 2));
const [state, setState] = React.useState(() => {
const parsed = getDefaultV2ParsePayload();
const [output, warnings] = convertV2ToV3(parsed);
return {
output,
warnings,
filled: fillV2Defaults(parsed),
error: ''
};
});
const [copyStatus, setCopyStatus] = React.useState('idle');
const copyResetTimer = React.useRef(null);
React.useEffect(() => () => {
if (copyResetTimer.current) clearTimeout(copyResetTimer.current);
}, []);
React.useEffect(() => {
const timer = setTimeout(() => {
try {
const parsed = JSON.parse(input);
if (!isDict(parsed)) throw new Error('Expected a JSON object.');
const [output, warnings] = convertV2ToV3(parsed);
setState({
output,
warnings,
filled: fillV2Defaults(parsed),
error: ''
});
} catch (error) {
setState({
output: null,
warnings: [],
filled: null,
error: error.message
});
}
}, 250);
return () => clearTimeout(timer);
}, [input]);
const outputText = state.output ? JSON.stringify(state.output, null, 2) : '';
const showCopyStatus = status => {
if (copyResetTimer.current) clearTimeout(copyResetTimer.current);
setCopyStatus(status);
copyResetTimer.current = setTimeout(() => setCopyStatus('idle'), 1500);
};
const copyOutput = () => {
if (!outputText) return;
if (typeof navigator === 'undefined' || !navigator.clipboard?.writeText) {
showCopyStatus('error');
return;
}
navigator.clipboard.writeText(outputText).then(() => showCopyStatus('success'), () => showCopyStatus('error'));
};
return