File Loader - Synthreo Builder

---

Purpose

The File Loader node reads files or directories and makes their contents available to other nodes in your Builder workflow. It supports structured data files (CSV, Excel, JSON), documents (PDF), media (video, audio, image), and directory-level batch processing. Once loaded, file contents can be passed to LLM nodes, transformation nodes, or any downstream step that needs file data.

---

Supported File Types

File Type	Description
CSV	Delimited text data. Rows become individual items; columns are mapped to named properties. A Key Column Name uniquely identifies each row.
JSON	Structured JSON data loaded directly into the workflow context.
Excel	Spreadsheet data (.xlsx). Rows and columns behave similarly to CSV.
PDF	Document content loaded as raw binary or converted to base64 for AI processing or downstream extraction.
Video	Video file processed for frame extraction and audio separation.
Audio	Audio file made available for downstream speech or audio processing nodes.
Image	Image file loaded as raw binary or converted to base64 for vision model input.
Directory	Loads all matching files from a folder, optionally including subdirectories. Enables batch file processing across many files in a single workflow run.

---

Inputs

The node loads data from the file system path or directory path you configure. It does not require an upstream node connection, though it can be positioned anywhere in the workflow where file loading is needed.

---

Outputs

Output	Description
Filename	The name of the file (without path). Available as a variable downstream.
Full path	The complete file system path to the loaded file.
base64	The Base64-encoded content of the file (only when Convert Files to base64 is enabled). Use this to send file content to LLM vision nodes or external APIs that accept Base64-encoded data.
Video Frames	Extracted frame images from a video file, available under the property name set in Image Frames Property Name (only in video mode).
Audio path	The file system path to the extracted audio track from a video file, available under the property name set in Audio File Path Property Name (only in video mode).

---

Parameters

Name	Type	Required	Default	Description
File Type	Dropdown	Yes	None	Select the type of file to load: CSV, JSON, Excel, PDF, Video, Audio, Image, or Directory. The selection determines which other parameters appear.
File Path	String	Required for single-file modes	Empty	The full path to the target file on the DCS file system. Used when loading a single file. Leave empty if using Directory Source for batch processing.
Key Column Name	String	No	id	For CSV and Excel files, this is the column that uniquely identifies each row. The value from this column is used as the row’s identifier when the data flows through the workflow. Change this to match the actual unique identifier column in your file (e.g., order_id, sku, customer_id).
Directory Source	String	Required for Directory mode	Empty	The folder path to scan when loading multiple files. All files in the folder (matching the extension filter if set) are loaded as individual items.
Allowed File Extensions	String	No	Empty	Comma-separated list of file extensions to include when in Directory mode (e.g., .pdf,.docx or .csv,.xlsx). Files with other extensions are ignored. Leave empty to include all file types found in the directory.
Include Sub Directories	Boolean	No	false	When enabled in Directory mode, the node recursively scans subdirectories and loads matching files from all nested folders.
Convert Files to base64	Boolean	No	false	Converts the file content to a Base64-encoded string. Enable this when sending file content to an LLM vision model, an OCR service, or any external API that requires Base64-encoded file data.
Frames per second	Number	No	4	For video files, controls how frequently frames are extracted (in seconds between frames). A value of 4 extracts one frame every 4 seconds. Lower values produce more frames and more detail but increase processing time and data volume.
Image Frames Property Name	String	No	video_frames	The workflow variable name under which extracted video frames are stored. Reference this downstream as {{Out.video_frames}} (substituting your chosen name).
Audio File Path Property Name	String	No	audio_path	The workflow variable name under which the extracted audio file path is stored. Reference downstream as {{Out.audio_path}}.
Columns Config	Data Grid	No	Empty	For CSV and Excel files, define each column’s name and data type. Setting types explicitly (e.g., string, number, date) prevents type conversion errors when column values are used in downstream calculations or comparisons.
Disable Cache	Boolean	No	false	By default, file contents may be cached between runs. Enable this when the source file is updated between workflow executions and the workflow must always read the latest version.

---

Key Column Examples

The Key Column Name parameter identifies which column in a CSV or Excel file serves as the unique row identifier. Setting this correctly ensures that downstream nodes can reference and distinguish individual rows.

Scenario	Key Column Name to use
Order data with an order_id column	order_id
Customer list with a customer_id column	customer_id
Product catalog with a sku column	sku
Employee records with an employee_number column	employee_number
Generic data with no natural key	Leave as id and ensure the CSV includes an id column

---

Example Usage

• Sales Reporting: Import a daily Excel file with sales transactions, set order_id as the Key Column Name, configure column types in Columns Config, and pass the structured data into an analytics or summarization node.
• Contract Review: Set File Type to Directory, set Directory Source to a legal contracts folder, add .pdf to Allowed File Extensions, enable Include Sub Directories, enable Convert Files to base64, and forward each contract to an LLM for clause extraction.
• Video Highlight Extraction: Load a training video, set Frames per second to 5, and send the extracted frames to an image classifier node to detect key scenes.
• Inventory Management: Load a CSV inventory export, set sku as the Key Column Name, map column types in Columns Config, and use the data to trigger automated restocking alerts based on quantity thresholds.
• Batch PDF Processing: Configure Directory mode with .pdf extension filter and Include Sub Directories enabled to process all PDFs in a folder hierarchy in a single workflow run.

---

Best Practices

• Use consistent file names and folder structures so that File Path and Directory Source values remain stable across workflow runs.
• Define Columns Config types explicitly for CSV and Excel files to prevent unexpected behavior when column values are used in numeric comparisons or date operations.
• Enable Disable Cache for files that are updated frequently (e.g., daily exports, live inventory feeds). Leave cache enabled for static reference data that does not change between runs.
• Use Allowed File Extensions in Directory mode to skip irrelevant files and reduce processing time.
• Keep Frames per second settings reasonable for video processing. Extracting too many frames per second significantly increases processing time and memory usage.
• When loading files for LLM vision input, enable Convert Files to base64 and reference {{Out.base64}} in the LLM prompt field that accepts image data.