zaina-ml/ml_forge: a node editor whose docs and manifest disagree on Python

The stated Python floor and the required floor are different numbers

The requirements section lists Python 3.10 or newer, then PyTorch 2.0 or newer and torchvision. The packaging metadata requires Python 3.11.

Those are not the same claim, and the stricter one wins at install time. A user on 3.10 who believes the stated requirement will get a resolution failure from pip rather than a message about the version floor, and nothing in the documentation explains why the number moved.

The rest of the metadata is more consistent than that. The build backend is setuptools with wheel, the declared version is 1.0.4 matching the newest tag, the author is zain-a, the license file is referenced rather than spelled out inline, and the classifiers claim OS Independent. It is worth noting that OS Independent describes the wheel, not the application: the only two runtime dependencies are dearpygui at 1.11.0 or newer and Pillow at 9.0.0 or newer, and Dear PyGui is a native desktop GUI toolkit. So this is a desktop application with a native window, not something you open in a browser tab.

The console entry point is declared as `ml-forge = ml_forge.main:main`, which is also why the installed command is hyphenated while the importable package name is not.

PyTorch is declared as an extra that the documented install never pulls

The training requirement is called out with emphasis: PyTorch must be preinstalled for training, and it is not installed as a dependency. The command given is:

pip install torch torchvision

Half of that statement is out of date. The packaging metadata does declare torch at 2.0.0 or newer and torchvision at 0.15.0 or newer, under an optional dependency group named training. So a PyTorch dependency exists in the manifest, it is simply not part of the default install.

That distinction decides whether training works. The documented install is:

pip install zaina-ml-forge

which resolves dearpygui and Pillow and nothing else. The name of the extra is never mentioned in the walkthrough, so the documented path leaves you with a working editor and no training. Installing torch first, as the requirements section says, is what makes the training tab functional.

Hardware selection is automatic rather than configured. GPU training kicks in if CUDA is available, and CPU and Apple MPS are both supported paths, which is consistent with the 1.0.4 release note about a segfault on Mac.

The clone command and the project URL disagree on a hyphen

There are two ways to get the code and they name different repositories.

git clone https://github.com/zaina-ml/ml-forge
python -m ml_forge

The clone line puts a hyphen between ml and forge. The homepage field in the packaging metadata writes it as a single joined word instead, pointing at the same organization with ml_forge. Only one of those is the actual path, and the documentation shows the one that does not match the declared URL.

The two entry points differ too. The pip route gives you the `ml-forge` console script:

ml-forge

while the source route has you invoke the module directly with `python -m ml_forge`. Both reach the same main function, but only the pip route is declared as a script entry point, so a source checkout has no `ml-forge` on PATH until you install it.

The project file format is JSON saved under a .mlf extension, and the same extension is used for the packaged templates declared as package data. That matters more than it looks: a Mac segfault during template loading was one of the three fixes in 1.0.4, so the template files are the same artifacts as your saved projects and share the same loading path.

Validation is a second hand-built chain the metrics panel quietly needs

The data prep walkthrough describes one chain: a Dataset node, transforms, and a DataLoader (train) node. Validation is a second, separate chain you build yourself, using the same dataset with `train=False` and ending in a DataLoader (val) node. The instruction frames it as being for proper validation, which is accurate but understates the coupling.

The METRICS button reports a summary of a training run containing final loss, best validation accuracy, a fit diagnosis, and the loss and accuracy curves, with the curves also appearing on the right training panel. Best validation accuracy has nothing to read unless the second chain exists. A pipeline built strictly by following the numbered steps has a train chain and no val chain, so the headline metric on that panel is empty or degraded while the rest of the panel fills in normally.

Nothing in the walkthrough flags this. The val chain is presented as an optional refinement rather than as a prerequisite for a specific field on the metrics screen.

The dataset node itself is where shapes come from. Adding one of MNIST, CIFAR10, CIFAR100, FashionMNIST or ImageFolder is what allows the Model tab's Input node to auto-fill its shape and the Output node to auto-fill its class count, which is why the walkthrough insists on starting the model from an Input node rather than hardcoding dimensions.

ToTensor is mandatory, Normalize is advice, and nothing distinguishes them

Within the transform chain, two requirements are stated in the same voice with different force. ToTensor is required. Normalize is recommended for best results. Both appear as a single line: chain transforms, ToTensor is required, add Normalize for best results.

The consequence is that a missing ToTensor stops the chain outright, while a missing Normalize produces a pipeline that runs to completion and trains to a worse result with nothing to distinguish the two situations in the interface.

That matters because the fit diagnosis on the METRICS panel is the only feedback channel offered, and a model trained on unnormalized inputs is exactly the case where a diagnosis is hard to act on.

The rest of the auto-fill chain has the same theme. `in_features` and `in_channels` fill in when you connect layers, and after a Flatten node the next Linear layer's `in_features` is computed automatically. So most of the shape bookkeeping is handled, and the one thing the tool does not check is whether your preprocessing matches its own recommendation.

The training loop is four wires between four blocks

The entire training graph is given as four connections:

DataLoaderBlock.images  ->  ModelBlock.images
ModelBlock.predictions  ->  Loss.pred
DataLoaderBlock.labels  ->  Loss.target
Loss.loss               ->  Optimizer.params

Images into the model, predictions and labels into the loss, and the loss output into the optimizer's params input. That last edge is what closes the loop and ties the four blocks into a single graph rather than four independent stages.

The vocabulary is block-oriented rather than layer-oriented: DataLoaderBlock, ModelBlock, Loss and Optimizer. The palette contributes the interior of the model, where the named layers are Linear, Conv2D, ReLU, BatchNorm2D, Flatten and Dropout among others, and the training tab contributes the loop around it. Epochs, device, checkpointing and early stopping are not nodes at all; they live in the right-hand panel, and pressing RUN starts the job.

Live training updates loss curves in real time, checkpoints can be saved, and the same panel surfaces the curves. The palette hints added in 1.0.4, shown on hover for certain nodes, are aimed at exactly this wiring step.

Inference samples a test set the walkthrough never asks you to build

After training, inference is reached through Run -> Inference, where you browse to a .pth checkpoint and click Run Inference to sample from the test set and see top-k predictions.

The test set is the gap. The build-your-first-model walkthrough constructs two chains, one ending in DataLoader (train) and one ending in DataLoader (val). No test chain is described anywhere in it, and no test DataLoader node is mentioned as a step. Yet the inference path draws its samples from the test set.

The supported dataset table also shows why the class count is not a guess. MNIST and FashionMNIST carry 10 classes at 1 by 28 by 28, CIFAR-10 carries 10 at 3 by 32 by 32, CIFAR-100 carries 100 at 3 by 32 by 32, and ImageFolder is listed as custom classes at a nominal 3 by 224 by 224. Those are the values the Output node auto-fills from, and the ImageFolder row is a default rather than something derived from your folder.

The dataset names are spelled two ways. The Data Prep list writes CIFAR10 and CIFAR100, while the table writes CIFAR-10 and CIFAR-100.

Version 1.0.4 shipped a Mac segfault fix and two cosmetic additions

The release notes for 1.0.4 list three changes, and the balance between them is informative. The functional fix is a patched segfault error on Mac during template loading. The other two are a logo added to the splash loading window and hints added to the node palette when hovering over certain nodes.

So the only behavior change in this release was a crash on Apple hardware while loading templates, on a platform whose GPU path is listed as supported through MPS.

The version history is short. v1.0.2 and v1.0.3 both landed in March 2026, six days apart, and v1.0.4 followed on 2026-08-17. The last push landed on the same date as the v1.0.4 tag and the repository is not archived.

The stated future plans are to orient toward a more beginner-friendly approach and to add custom block functionality. The second one bounds what you can build today. Until custom blocks exist, a node outside the fixed palette cannot be expressed in this editor at all, which is the practical limit on a tool whose main appeal is that you do not write code.

Editorial conclusion

Good fit if you want to sketch a vision training pipeline visually and then keep the generated PyTorch as the real artifact. Not a fit if you need custom layers, since custom blocks are still listed as future work and the palette is a fixed set. Before installing, read requires-python in pyproject.toml rather than the stated Python floor, install torch yourself, and remember that every number the METRICS panel reports about validation depends on a second data chain you have to build by hand.

Frequently asked questions

Official sources

1. Issues
2. License: MIT
3. README
4. Releases
5. zaina-ml/ml_forge on GitHub