feat: new parameter types and handlers: Directory and FileSequence

[alex-rumsey-foundry]

feat: add Directory and FileSequence output parameter types

Closes #4634

Context

Nodes that produce files currently express their output as a single File with a resolved path. Two common output shapes weren't representable:

• A directory — e.g. a node that organises its outputs into a folder
• A file sequence — e.g. a renderer that writes frame_v001_0001.exr … frame_v001_0042.exr (or dialogue_v001_001.md … dialogue_v001_099.md) into a versioned directory

What changed

New types (files/directory.py, files/file_sequence.py)

• Directory / DirectoryDestination — thin wrappers around MacroPath | str, parallel to the existing File / FileDestination. DirectoryDestination.create() handles CREATE_NEW versioning by incrementing _index until a non-existent path is found, then mkdirs.
• FileSequence / FileSequenceDestination — represents a collection of numbered files identified by an entry-number pattern. Internally uses {entry:04} macro syntax; exposes industry-standard #### notation (and all other fileseq token forms: %04d, @@@@, $F4) at
  property boundaries via the fileseq library. FileSequenceDestination.entry(n) returns a FileDestination for writing a specific entry; the version index (_index) is resolved once at construction and held constant across all entries. FileSequence.scan() delegates to
  ScanSequencesRequest rather than calling the internal scanner directly.

New parameter components (exe_types/param_components/)

• ProjectOutputParameter — new shared base class extracted from ProjectFileParameter, consolidating the common wiring: adding a file-path parameter, attaching an open-in-explorer button, and emitting the resolved path via node messages. ProjectFileParameter now extends
  this.
• ProjectDirectoryParameter — mirrors ProjectFileParameter; build_directory() returns a DirectoryDestination backed by the save_output_directory situation.
• ProjectFileSequenceParameter — build_sequence() returns a FileSequenceDestination backed by the save_file_sequence_entry situation.

Both new components support the cog-button pattern to auto-create and connect a settings node.

New situations (default_project_template.py)

save_output_directory:
{outputs}/{sub_dirs?:/}{node_name?:_}{dir_name}_v{_index:03}

save_file_sequence_entry:
{outputs}/{sub_dirs?:/}{node_name?:_}{file_name_base}_v{_index:03}/
{file_name_base}_v{index:03}{entry:04}.{file_extension}

Version number (_v001, _v002, …) appears in both the directory name and sequence entry filenames. Padding defaults to 3 digits for versions, 4 for entries.

Wire types: "Directory" and "FileSequence" — new distinct output_type values so the UI can render them with appropriate icons/pickers.

Important note

• the standard library needs updating the FileOutputSettings node in filesystem, to use new output types (any other libs use them?)

[SavagePencil]

is this unique to images? Could I use it for dialogue files, too? After convos with Jason we'd like to ensure that other sequential artifact types can benefit from it, so I'll be moving away from terms like "frames".

[SavagePencil]

I'll have to double check on this, but I don't think there's a hardcoded use of index as the indexing variable. Also note that the _index (underbar) is a prepend to put an underbar when rendered.

[SavagePencil]

if we have existing request to cover this, it'd be great to use it

[alex-rumsey-foundry]

Added a MakeDirectoryRequest

[Copilot]

Pull request overview

This PR adds first-class filesystem output shapes beyond a single file path by introducing Directory and ImageSequence types, along with project-aware parameter components and new default project situations to generate versioned output directories and frame sequences.

Changes:

• Added Directory/DirectoryDestination and ImageSequence/ImageSequenceDestination filesystem abstractions.
• Added ProjectDirectoryParameter and ProjectImageSequenceParameter param components to build destinations from project situations (including “cog” settings-node wiring).
• Extended the default project template with save_output_directory and save_image_sequence_frame situations.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
src/griptape_nodes/files/image_sequence.py	Introduces ImageSequence read descriptor, ImageSequenceDestination write handle, and frame-pattern conversion helpers.
src/griptape_nodes/files/directory.py	Introduces Directory path wrapper and DirectoryDestination for creation/versioning + mapping back to project macros.
src/griptape_nodes/files/init.py	Exposes the new Directory/ImageSequence APIs from the files package.
src/griptape_nodes/exe_types/param_components/project_image_sequence_parameter.py	Adds a project-aware parameter component that builds image-sequence destinations from situations and supports settings-node wiring.
src/griptape_nodes/exe_types/param_components/project_directory_parameter.py	Adds a project-aware parameter component that builds directory destinations from situations and supports settings-node wiring.
src/griptape_nodes/common/project_templates/default_project_template.py	Adds two new default situations for versioned directory and image-sequence outputs.

Comments suppressed due to low confidence (3)

src/griptape_nodes/files/image_sequence.py:214

• build_versioned_sequence_destination always scans for a non-existent parent directory and locks a new _index even when existing_file_policy is OVERWRITE or FAIL. That means callers cannot opt into reusing an existing versioned directory via situation policy (OVERWRITE/FAIL) or by supplying a specific _index. Consider only performing the version scan when the caller intends CREATE_NEW behavior (or add an explicit versioning policy parameter), and otherwise lock _index deterministically (e.g., 1 or a caller-supplied value).

def build_versioned_sequence_destination(
    frame_macro: MacroPath,
    *,
    existing_file_policy: ExistingFilePolicy = ExistingFilePolicy.OVERWRITE,
    create_parents: bool = True,
) -> ImageSequenceDestination:
    """Find the first available version index and return a locked ImageSequenceDestination.

    Increments ``_index`` in the frame macro starting at 1 until the corresponding
    parent directory does not exist. Returns an ``ImageSequenceDestination`` with
    that index locked into the variables dict.

src/griptape_nodes/files/directory.py:231

• When mapping the created directory back to a portable project macro fails, _map_to_macro_directory currently returns Directory(fallback_path) if fallback_path is a MacroPath. That means Directory.location will be the unresolved template (dropping the locked _index variables), which is easy for callers to accidentally persist and later fail to resolve. Consider falling back to Directory(str(absolute_path)) (mirroring ProjectFileDestination’s behavior of returning an absolute-path File when mapping fails), or provide a way to serialize both template + variables.

    map_result = GriptapeNodes.handle_request(AttemptMapAbsolutePathToProjectRequest(absolute_path=absolute_path))
    if isinstance(map_result, AttemptMapAbsolutePathToProjectResultSuccess) and map_result.mapped_path is not None:
        return Directory(map_result.mapped_path)
    if isinstance(fallback_path, MacroPath):
        return Directory(fallback_path)
    return Directory(str(absolute_path))

src/griptape_nodes/files/directory.py:154

• DirectoryDestination.create() routes any CREATE_NEW + MacroPath into _create_with_versioning(), but it doesn’t verify that the macro template actually references {_index}. If the directory already exists and the template doesn’t use _index, the loop will repeatedly resolve the same path and eventually raise the misleading “no available path found after 9999 attempts”. Consider checking whether _index is referenced in macro_path.parsed_macro before versioning, and either fall back to direct creation (with an appropriate policy) or raise a targeted error explaining that CREATE_NEW requires an {_index} slot.

    def create(self) -> Directory:
        """Create the directory and return a Directory referencing it.

        When policy is CREATE_NEW and the path is a MacroPath containing
        ``{_index}``, increments the index starting at 1 until a non-existent
        directory is found, then creates it.

        Returns:
            Directory referencing the created path (in macro form if inside project).

        Raises:
            DirectoryError: If the directory cannot be created.
        """
        if self._existing_dir_policy == ExistingFilePolicy.CREATE_NEW and isinstance(self._dir_path, MacroPath):
            return self._create_with_versioning()
        return self._create_direct()

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[codecov]

Codecov Report

❌ Patch coverage is 75.82160% with 103 lines in your changes missing coverage. Please review.

Files with missing lines	Patch %	Lines
...types/param_components/project_output_parameter.py	60.24%	33 Missing ⚠️
...e_types/param_components/project_file_parameter.py	0.00%	23 Missing ⚠️
...es/param_components/project_directory_parameter.py	74.54%	14 Missing ⚠️
src/griptape_nodes/files/file_sequence.py	88.61%	14 Missing ⚠️
...aram_components/project_file_sequence_parameter.py	75.92%	13 Missing ⚠️
src/griptape_nodes/files/directory.py	93.18%	6 Missing ⚠️

📢 Thoughts on this report? Let us know!

[collindutter]

Does this integrate with #4550 at all?

[alex-rumsey-foundry]

Does this integrate with #4550 at all?

Eh, not really, no. But I agree with an implication that it should, let me do one more pass to see if I can align it with James' changes.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 4 comments.