Flatten Nested Files v0.2

Downloaded datasets and scraped galleries have a signature look: forty levels of nested folders with one image at the bottom. Training data, captioning jobs, and archive cleanups all hit the same wall - you want everything in one flat directory, and doing it by hand is misery. Flatten Nested Files v2 (displayed as v0.2, the naming is optimistic) recursively walks a directory tree and moves the files up, with an unusually thoughtful feature: it keeps paired files together. That's the thing most flattening scripts get wrong, and it's why this node earns its place.

The one required input is main_directory plus operation_mode: flatten_only moves everything straight into the target, flatten_and_organize also creates type subfolders (images/, movies/, text/), and organize_only tidies files in place without moving them up. The optional section is where the real control lives: flatten_depth lets you keep the first level of subfolders (useful when each subfolder is a source you want to preserve, like an Instagram profile), respect_paired_files (on by default) moves photo.jpg together with photo.xmp and photo.txt as a unit, and sidecar_handling decides whether captions ride along into the images folder or go to a sidecars folder.

The rest reads like a checklist of someone who's burned themselves before: dry_run previews without moving anything, handle_conflicts offers rename/skip/overwrite for duplicate filenames, preserve_source_folder prefixes or suffixes the original folder name onto files so you don't lose provenance, remove_empty_folders cleans up after itself, and max_scan_depth guards against pathological nesting. Outputs are status_message, files_moved (INT), paired_files_moved (INT) - a nice touch, because it confirms your captions actually followed their images - plus stats_json and log_output.

The mechanism is straightforward recursion with smart pairing logic, no magic. The trap is the same as any file-mover: this runs when the workflow executes, so a stray Queue press with dry_run off and handle_conflicts on overwrite is a permanent change. The dry_run default being off is the one thing I'd change about this node.

Framing honestly: this is a one-author pack with no community footprint, and Flatten is a utility that earns its keep on real dataset work but won't be in anyone's shareable art workflow. If your training folder looks like a fractal, though, this is the tool that flattens it while keeping every .txt caption glued to its image.

Install the pack and restart:

cd ComfyUI/custom_nodes
git clone https://github.com/EricRollei/AAA_Metadata_System
cd AAA_Metadata_System
pip install -r requirements.txt

Then the smart path: set dry_run to true, run it, read the log, and only flip dry_run off when the preview matches your mental model. Flattening is reversible in theory; doing it wrong is not.