[FEATURE] Reusable Parameterized Subflow Components

[LucaSforza]

Overview

Allow a subflow to be saved as a reusable, parameterized component definition and instantiated multiple times across diagrams. Definitions should expose a formal interface while hiding their internal graph, similar to PrototypeML blocks.

A reusable ResidualBlock, for example, should declare named ports and public parameters once, then be instantiated with different bindings without copying and manually maintaining its internal nodes.

Dependencies

• Depends on [FEATURE] Scoped Variables and Parameter Expression Language #21 for scoped variables and parameter expressions.
• Depends on [FEATURE] Named Multi-Input and Multi-Output Subflow Ports #22 for named multi-input/multi-output subflow interfaces.

Definition and instance model

Introduce a versioned component format such as .nnm-component.json containing:

• schema version, component ID, name, description, and component version;
• named input/output port definitions;
• typed public parameters with defaults and validation;
• private/local variables;
• the internal nodes, edges, and nested component references;
• optional documentation and preview metadata.

Diagrams keep a shared componentDefinitions table. Component instances reference a definition ID/version and store only instance name, position, port connections, and parameter bindings. This avoids duplicating the same internal graph for every instance while keeping the diagram self-contained.

Each instance creates independent PyTorch modules and weights. Weight sharing is never implicit.

Parameters and encapsulation

• Public parameters may be literals or expressions resolved through [FEATURE] Scoped Variables and Parameter Expression Language #21.
• Internal node parameters can bind to public parameters or private variables.
• Private values are not editable from the instance.
• Definition validation rejects missing bindings, invalid types, unknown names, and cyclic dependencies.
• Internal node IDs are namespaced by definition/instance during compilation to prevent collisions.

Version and update semantics

• Imported definitions are immutable snapshots identified by component ID and version.
• Updating a definition is explicit and previews affected instances before migration.
• No instance silently tracks or downloads a newer external version.
• A Detach action converts one instance into a normal editable local subflow.
• Recursive direct or indirect component definitions are rejected.

UX

• Save a selected subflow as a component file.
• Import component files into a diagram-local library.
• Browse, inspect, and instantiate imported definitions from the sidebar.
• Edit instance parameters without exposing internal nodes by default.
• Open the shared definition in a dedicated editing view.
• Show version, source, update availability, validation status, and instance count.
• Confirm breaking interface changes and list affected instances.

Compilation and packaging

• TypeEngine caches validated definition transforms where safe, then evaluates each instance with its bindings.
• NNTree resolves component instances into deterministic subflow runtime configurations.
• convert.py and the Python runtime instantiate each component independently.
• Exported model wheels include all required component definitions or their fully resolved graph representation.
• Diagram export remains portable and does not depend on an unavailable local filesystem path.

Acceptance criteria

• A valid subflow can be exported as a versioned .nnm-component.json definition.
• A component can be imported once and instantiated multiple times in one or more diagrams.
• Definitions expose typed public parameters and named ports; internals remain encapsulated.
• Instance parameter bindings support literals and [FEATURE] Scoped Variables and Parameter Expression Language #21 expressions.
• Instances compile to independent modules with independent weights.
• Component IDs and namespaced node IDs prevent collisions.
• Definition edits and version upgrades are explicit and report affected instances.
• Detaching creates an equivalent editable local subflow without changing behavior.
• Missing definitions, incompatible versions, invalid bindings, and recursive definitions produce actionable errors.
• Save/load, undo/redo, duplication, Browser RPC, and MCP preserve definitions and instances.
• Type inference, NNTree conversion, Python forward, remote training, and wheel export work for nested reusable components.
• Tests cover round-trip packaging, multiple instances, parameter overrides, version mismatch, detach, nesting, recursion rejection, and backward compatibility.
• Documentation defines the component schema, lifecycle, parameter scope, and independent-weight semantics.

Out of scope

• A hosted/social component marketplace.
• Automatic dependency downloads.
• Cryptographic signing or trust policy.
• Shared weights between component instances.
• Importing arbitrary Python modules as visual definitions.