neural-structured-learning: training with structured signals

A paradigm, not a layer

Neural Structured Learning is a learning paradigm to train neural networks by leveraging structured signals in addition to feature inputs. Structure can be explicit as represented by a graph, or implicit as induced by adversarial perturbation.

That is the whole idea, and it is worth being clear about why it is not just another regularisation trick. The structured signals are commonly used to represent relations or similarity among samples that may be labeled or unlabeled. Leveraging these signals during neural network training harnesses both labeled and unlabeled data, which can improve model accuracy, particularly when the amount of labeled data is relatively small.

The second claim is about security. Models trained with samples that are generated by adversarial perturbation have been shown to be robust against malicious attacks, which are designed to mislead a model's prediction or classification.

NSL generalizes to Neural Graph Learning as well as to Adversarial Learning, so the two directions share one framework rather than being two projects that happen to use the same name.

And the framework is designed to be flexible and can be used to train any kind of neural network. Feed-forward, convolutional and recurrent networks can all be trained using it, and in addition to supervised and semi-supervised learning, with a low amount of supervision, NSL can in theory be generalized to unsupervised learning.

The design constraint that makes it usable in production is that incorporating structured signals is done only during training, so the performance of the serving and inference workflow remains unchanged. You are not paying for the graph at request time, and that is the property that separates this from a graph neural network.

Three API surfaces for the same idea

The framework provides three groups of APIs, and the choice between them is about how much of your model you are willing to restructure.

The Keras APIs enable training with graphs, which is explicit structure, and with adversarial perturbations, which is implicit structure. This is the path for a team that already has a Keras model and wants to add a graph to it.

The TF ops and functions enable training with structure when using lower-level TensorFlow APIs. That is the path for a team with a custom training loop, or a model built on the estimator style, where there is no Keras model object to attach a graph layer to.

The third group is the tools to build graphs and construct graph inputs for training. This is the part people underestimate, because building the graph is often more work than training with it. If your relations come from a corpus, a knowledge base or a domain expert, the tool that turns that into the input tensors the model expects is what makes the approach practical rather than theoretical.

That split into three surfaces is the design, and it is the reason the library can sit under an existing training pipeline without rewriting it. Whichever level your code operates at, there is a way to feed structured signals in.

The framework is deliberately not tied to a particular architecture, which is what allows the same graph tooling to be used with a feed-forward model in one experiment and a recurrent one in the next.

Installing it, and the TensorFlow version to avoid

The prebuilt pip package is installed with:

pip install neural-structured-learning

And the version requirements are where the practical detail is. NSL requires a TensorFlow version of 1.15 or higher, and it also supports TensorFlow 2.x with the exception of version 2.1, which contains a bug that is incompatible with NSL.

That is an unusual kind of statement, a specific version excluded with a specific reason, and it saves you an afternoon if you hit it. A project that knows which of its own supported versions it breaks against is a project that has been tested against those versions.

For more detailed instructions on how to install NSL as a package, or to build it from source in various environments, the documentation points at the installation guide in the g3doc directory.

The package metadata reflects a deliberately small dependency set. The setup file lists the install requirements as:

INSTALL_REQUIRES = [
    "absl-py",
    "attrs",
    "scipy",
    "six",
]

TensorFlow itself is not in that list, which tells you the framework is designed to sit inside an environment where TensorFlow is already installed and pinned, rather than to bring its own copy along.

Videos, notebooks and the worked examples

The project has two layers of learning material, and they serve different purposes.

The video series on YouTube gives an overall framework view and then goes into the individual areas, with entries on the overall framework, natural graphs, synthetic graphs and adversarial learning. That is the right order for understanding the ideas, and the four videos split cleanly along the same lines as the two kinds of structure.

The hands-on colab-based tutorials let you explore the thing interactively, and there are three of them, one per example. Training with natural graphs is the graph_keras_mlp_cora notebook, which is a multi-layer perceptron on the Cora citation graph. Training with synthesized graphs is graph_keras_lstm_imdb, which is a recurrent model on IMDB. And adversarial learning is adversarial_keras_cnn_mnist, a convolutional model on MNIST.

The choice of datasets is a good guide to the shape of each problem. Cora is a citation network where the graph is the structure and the labels are sparse, which is exactly the case the framework is meant for. IMDB with an LSTM is a sequence task where the graph is synthesized from the sequence rather than observed. And MNIST with a CNN is the classic place to see adversarial perturbation doing something visible.

More examples and tutorials live under the examples directory in the repository, and the README asks you to check the tutorials for a practical introduction to NSL.

The written material is the notebooks, and the video material is the concepts, and the tutorials are where you would start.

The research directory is part of the product

There is a research/ directory in the repository, and the README points at it for research projects in Neural Structured Learning, which is an unusual thing to find in a library repository and a reasonable thing to find in one that exists to host a research programme.

The projects listed are Low-Dimensional Hyperbolic Knowledge Graph Embeddings, A2N for attending to neighbors for knowledge graph inference, GAM for graph agreement models for semi-supervised learning, Neural Clustering Processes, CARLS for cross-platform asynchronous representation learning, and a third-party entry, Denoised Smoothing, described as a provable defense for pretrained classifiers.

The list tells you what the framework is being used for. Knowledge graph inference and knowledge graph embeddings are the graph half, semi-supervised learning and clustering are the semi-supervised half, and denoised smoothing is the adversarial half.

The contributing guidance reflects the same shape. New algorithms are expected to be staged in the research directory with a colab notebook that showcases the new features, and the project says that if you develop new algorithms in your own repository, the maintainers would be happy to feature pointers to academic publications or repositories using NSL.

There is also a workshops/ directory in the repository root, which suggests the framework is used in teaching settings as well as in research, and a usage.md page that collects how NSL is discussed and used in the open source community.

Maintenance, tooling and where to ask

The repository is a mix of Python package and Bazel project, with the WORKSPACE file and the .bazelrc at the root, and the neural_structured_learning/ directory holding the package itself alongside the g3doc/ documentation, the research/ projects and the workshops/. There is a setup.py, a setup.cfg, a LICENSE and a RELEASE.md with the release notes.

The licence is Apache-2.0, the primary language is Python, and the homepage is the TensorFlow documentation page for the framework. The last push was on 2026-10-05 and the repository is not archived, but the release history is the part to look at: v1.3.0 on 2020-07-31, v1.3.1 on 2020-08-18 and v1.4.0 on 2022-07-29.

So the last tagged release is more than four years old while the branch is still receiving commits. That is the profile of a project that is maintained in the sense that bugs get fixed but is not shipping releases on a schedule, and it means the practical step is to install from the branch or the package index and check what you get against the version of TensorFlow you have.

Support is routed three ways. Issues, bugs and feature requests go to GitHub issues, questions go to Stack Overflow with the nsl tag, and feedback goes through a form.

Contributions are welcomed in three shapes, and the distinction is a useful one for anybody considering contributing: case studies, where you wrap your usage up as a tutorial, a new dataset or an example model that others could use, product excellence, where you improve the implementation and send a pull request, and new algorithms, where you study the existing implementations first and stage your project in the research directory with a colab notebook.

Editorial conclusion

Adopt Neural Structured Learning if your problem has structure you are not using, a graph of relations between samples, a similarity signal, or a threat model that needs adversarial training, and if you are working with a TensorFlow version the library supports. Do not adopt it for a model that has no structure to exploit, because the library would then be overhead, and check the TensorFlow version before you install, since the project documents an incompatibility with version 2.1. Before you start, read the installation guide rather than only the pip command, and remember that the structured signals are a training-time concern, so you should not expect a serving pipeline to change.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. Project website
3. README
4. Releases
5. tensorflow/neural-structured-learning on GitHub