fabricpc 0.4.0__tar.gz

fabricpc-0.4.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Matthew Behrend
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

fabricpc-0.4.0/PKG-INFO

@@ -0,0 +1,184 @@
+Metadata-Version: 2.4
+Name: fabricpc
+Version: 0.4.0
+Summary: A flexible, performant predictive coding library using JAX
+Author-email: SingularityNET Foundation <info@singularitynet.io>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/trueagi-io/FabricPC
+Project-URL: Repository, https://github.com/trueagi-io/FabricPC
+Project-URL: Documentation, https://github.com/trueagi-io/FabricPC/blob/main/docs/user_guides/00_index.md
+Project-URL: Changelog, https://github.com/trueagi-io/FabricPC/blob/main/CHANGELOG.md
+Project-URL: Issues, https://github.com/trueagi-io/FabricPC/issues
+Keywords: predictive-coding,jax,neural-networks,machine-learning
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: jax>=0.7.0
+Requires-Dist: optax>=0.1.7
+Requires-Dist: orbax-checkpoint>=0.4.0
+Requires-Dist: flax>=0.7.5
+Requires-Dist: chex>=0.1.84
+Requires-Dist: jaxtyping>=0.2.23
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: tqdm>=4.65.0
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0.0; extra == "dev"
+Requires-Dist: hypothesis>=6.0.0; extra == "dev"
+Requires-Dist: black[colorama]==26.1.0; extra == "dev"
+Requires-Dist: ruff==0.15.19; extra == "dev"
+Requires-Dist: mypy>=1.0.0; extra == "dev"
+Requires-Dist: pre-commit>=3.0.0; extra == "dev"
+Requires-Dist: build>=1.0.0; extra == "dev"
+Requires-Dist: twine>=5.0.0; extra == "dev"
+Provides-Extra: tfds
+Requires-Dist: tensorflow-datasets>=4.9.0; extra == "tfds"
+Requires-Dist: tensorflow-cpu>=2.15.0; (platform_system == "Linux" and platform_machine == "x86_64") and extra == "tfds"
+Requires-Dist: tensorflow>=2.15.0; (platform_system != "Linux" or platform_machine != "x86_64") and extra == "tfds"
+Requires-Dist: importlib_resources; extra == "tfds"
+Requires-Dist: tokenizers>=0.15.0; extra == "tfds"
+Provides-Extra: experiments
+Requires-Dist: scipy>=1.10.0; extra == "experiments"
+Requires-Dist: optuna>=3.0.0; extra == "experiments"
+Provides-Extra: viz
+Requires-Dist: plotly>=5.0.0; extra == "viz"
+Requires-Dist: kaleido>=0.2.1; extra == "viz"
+Requires-Dist: pandas>=2.0.0; extra == "viz"
+Requires-Dist: aim>=3.0.0; (python_version < "3.13" and platform_system != "Windows") and extra == "viz"
+Provides-Extra: cpu
+Requires-Dist: jax[cpu]; extra == "cpu"
+Provides-Extra: cuda12
+Requires-Dist: jax[cuda12]; extra == "cuda12"
+Provides-Extra: cuda13
+Requires-Dist: jax[cuda13]; extra == "cuda13"
+Provides-Extra: all
+Requires-Dist: fabricpc[experiments,tfds,viz]; extra == "all"
+Dynamic: license-file
+
+# FabricPC
+
+**State-of-the-art predictive coding, made easy.**
+
+FabricPC is an easy-to-use, high-performance open-source Python library for building and training predictive coding networks. It is designed to get researchers from idea to running experiment as fast as possible, eliminating algorithm boilerplate. A single directed edge between nodes is all that's needed to define a connection. Local derivatives are built in, following graph topology. The framework handles inference and learning dynamics automatically for whatever you write in a node's `forward()` method.
+
+Built on JAX for GPU and multi-GPU acceleration with local (node-level) automatic differentiation.
+
+## What It Does
+
+FabricPC supports arbitrary graph topologies: feedforward, recurrent, skip connections, and cyclic architectures. Heterogeneous components such as linear, convolutional, and pooling nodes, transformer blocks, and Storkey-Hopfield associative memory coexist within the same energy-minimization graph. The same graph topology can be trained by predictive coding (`train_pcn`) or by backpropagation (`train_backprop`), so controlled PC-vs-backprop comparisons reuse one model definition instead of two. See `examples/PC_backprop_compare.py`.
+
+Internally, everything is organized around three abstractions: nodes (state and computation), edges (connections between nodes), and updates (inference and learning algorithms).
+
+## Installation
+
+Python 3.11–3.13. Install into a virtual environment, not the system Python. Create and activate the environment, then one command installs FabricPC, its optional dependencies, and a version-matched JAX backend — pick the line for your hardware:
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
+
+pip install -U "fabricpc[all,cuda13]"   # GPU, CUDA 13 (NVIDIA driver ≥580)
+pip install -U "fabricpc[all,cuda12]"   # GPU, CUDA 12
+pip install -U "fabricpc[all]"          # CPU only
+pip install fabricpc                    # core library only, CPU
+```
+
+`nvidia-smi` reports the CUDA version your driver supports.
+
+**Platform:** GPU acceleration requires **Linux** (x86_64 or aarch64) — JAX publishes CUDA wheels for Linux only. On native Windows or macOS, install CPU-only; for GPU on Windows use WSL2 (JAX marks WSL2 GPU support experimental). The optional Aim experiment tracker in `[viz]`/`[all]` is Linux/macOS only and supports Python ≤3.12; on Windows or Python 3.13 it is skipped automatically and everything else installs normally.
+
+See the [installation guide](https://github.com/trueagi-io/FabricPC/blob/main/docs/user_guides/01_installation.md) for details.
+
+### From source (contributors)
+
+```bash
+git clone https://github.com/trueagi-io/FabricPC.git
+cd FabricPC
+python3 -m venv .venv && source .venv/bin/activate
+pip install -U -e ".[all,dev]"    # add a backend extra for GPU: ".[all,dev,cuda12]"
+
+# Install pre-commit hooks for code quality
+pre-commit install
+
+# Run an example
+python examples/mnist_demo.py
+```
+
+## Build a Model
+
+Define the graph. Initialize the parameters. Start experimenting.
+
+```python
+import jax
+from fabricpc.nodes import Linear
+from fabricpc.core.topology import Edge
+from fabricpc.graph_assembly import TaskMap, graph
+from fabricpc.graph_initialization import initialize_params
+from fabricpc.core.inference import InferenceSGD
+from fabricpc import setup_jax
+
+setup_jax()
+
+layer1 = Linear(shape=(784,), name="input")
+layer2 = Linear(shape=(256,), name="hidden")
+layer3 = Linear(shape=(10,), name="output")
+
+structure = graph(
+    nodes=[layer1, layer2, layer3],
+    edges=[Edge(source=layer1, target=layer2.slot("in")),
+           Edge(source=layer2, target=layer3.slot("in"))],
+    task_map=TaskMap(x=layer1, y=layer3),
+    inference=InferenceSGD(eta_infer=0.05, infer_steps=20),
+)
+
+rng_key = jax.random.PRNGKey(0)
+params = initialize_params(structure, rng_key)
+```
+
+## Demos
+
+The [`examples`](https://github.com/trueagi-io/FabricPC/tree/main/examples) folder includes working demonstrations across image classification, sequence modeling, depth scaling (`examples/scaling/`), associative memory, and architectural probes. Start with [`mnist_demo.py`](https://github.com/trueagi-io/FabricPC/blob/main/examples/mnist_demo.py) (over 98% accuracy on MNIST) and explore from there:
+
+- [`mnist_conv_demo.py`](https://github.com/trueagi-io/FabricPC/blob/main/examples/mnist_conv_demo.py) — convolutional MNIST classifier with `ConvNode` and `MaxPool`
+- [`resnet18_cifar10_demo.py`](https://github.com/trueagi-io/FabricPC/blob/main/examples/resnet18_cifar10_demo.py) — ResNet-18 as a PC graph, with global average pooling
+- [`transformer_v2_demo.py`](https://github.com/trueagi-io/FabricPC/blob/main/examples/transformer_v2_demo.py) — character- or BPE-level language modeling with text generation
+- [`transformer_tuning.py`](https://github.com/trueagi-io/FabricPC/blob/main/examples/transformer_tuning.py) — two-phase hyperparameter search minimizing validation perplexity
+
+## Documentation
+
+User guides, API reference, and tutorials live in [`docs/user_guides`](https://github.com/trueagi-io/FabricPC/blob/main/docs/user_guides/00_index.md). Development plans and technical design documents are in [`docs/dev_plans`](https://github.com/trueagi-io/FabricPC/tree/main/docs/dev_plans).
+
+## Extending FabricPC
+
+### Custom Nodes
+
+Create custom node types by subclassing `NodeBase`. Implement the `get_slots()`, `initialize_params()`, and `forward()` methods. Nodes have a single output. Slots define incoming connections and are referenced in edges when building the graph.
+
+See [`docs/user_guides/06_custom_nodes.md`](https://github.com/trueagi-io/FabricPC/blob/main/docs/user_guides/06_custom_nodes.md) for the node contract and a Conv2D teaching example (the production node is `fabricpc.nodes.ConvNode`).
+
+## Contributing
+
+Contributions are welcome! Please open issues or pull requests on the GitHub repository.
+- Develop on a branch using the convention `username/your_feature_name`.
+- Demos must match baseline results, or explain any divergence.
+- The test suite must pass.
+- Write unit tests and docstrings for new code.
+- Use the pre-commit hooks for PEP8 style and code quality.
+- Rebase before opening PR.
+
+This is a research-first project.
+- APIs may change frequently until the v1.0 release.
+- Any breaking changes are documented in the changelog.
+
+## Team
+
+FabricPC is actively maintained by SingularityNET as part of the Artificial Superintelligence Alliance. Project lead: Dr. Matthew Behrend.
+
+## License
+
+This project is licensed under the [MIT License](https://github.com/trueagi-io/FabricPC/blob/main/LICENSE).

fabricpc-0.4.0/README.md

@@ -0,0 +1,121 @@
+# FabricPC
+
+**State-of-the-art predictive coding, made easy.**
+
+FabricPC is an easy-to-use, high-performance open-source Python library for building and training predictive coding networks. It is designed to get researchers from idea to running experiment as fast as possible, eliminating algorithm boilerplate. A single directed edge between nodes is all that's needed to define a connection. Local derivatives are built in, following graph topology. The framework handles inference and learning dynamics automatically for whatever you write in a node's `forward()` method.
+
+Built on JAX for GPU and multi-GPU acceleration with local (node-level) automatic differentiation.
+
+## What It Does
+
+FabricPC supports arbitrary graph topologies: feedforward, recurrent, skip connections, and cyclic architectures. Heterogeneous components such as linear, convolutional, and pooling nodes, transformer blocks, and Storkey-Hopfield associative memory coexist within the same energy-minimization graph. The same graph topology can be trained by predictive coding (`train_pcn`) or by backpropagation (`train_backprop`), so controlled PC-vs-backprop comparisons reuse one model definition instead of two. See `examples/PC_backprop_compare.py`.
+
+Internally, everything is organized around three abstractions: nodes (state and computation), edges (connections between nodes), and updates (inference and learning algorithms).
+
+## Installation
+
+Python 3.11–3.13. Install into a virtual environment, not the system Python. Create and activate the environment, then one command installs FabricPC, its optional dependencies, and a version-matched JAX backend — pick the line for your hardware:
+
+```bash
+python3 -m venv .venv && source .venv/bin/activate   # Windows: .venv\Scripts\activate
+
+pip install -U "fabricpc[all,cuda13]"   # GPU, CUDA 13 (NVIDIA driver ≥580)
+pip install -U "fabricpc[all,cuda12]"   # GPU, CUDA 12
+pip install -U "fabricpc[all]"          # CPU only
+pip install fabricpc                    # core library only, CPU
+```
+
+`nvidia-smi` reports the CUDA version your driver supports.
+
+**Platform:** GPU acceleration requires **Linux** (x86_64 or aarch64) — JAX publishes CUDA wheels for Linux only. On native Windows or macOS, install CPU-only; for GPU on Windows use WSL2 (JAX marks WSL2 GPU support experimental). The optional Aim experiment tracker in `[viz]`/`[all]` is Linux/macOS only and supports Python ≤3.12; on Windows or Python 3.13 it is skipped automatically and everything else installs normally.
+
+See the [installation guide](https://github.com/trueagi-io/FabricPC/blob/main/docs/user_guides/01_installation.md) for details.
+
+### From source (contributors)
+
+```bash
+git clone https://github.com/trueagi-io/FabricPC.git
+cd FabricPC
+python3 -m venv .venv && source .venv/bin/activate
+pip install -U -e ".[all,dev]"    # add a backend extra for GPU: ".[all,dev,cuda12]"
+
+# Install pre-commit hooks for code quality
+pre-commit install
+
+# Run an example
+python examples/mnist_demo.py
+```
+
+## Build a Model
+
+Define the graph. Initialize the parameters. Start experimenting.
+
+```python
+import jax
+from fabricpc.nodes import Linear
+from fabricpc.core.topology import Edge
+from fabricpc.graph_assembly import TaskMap, graph
+from fabricpc.graph_initialization import initialize_params
+from fabricpc.core.inference import InferenceSGD
+from fabricpc import setup_jax
+
+setup_jax()
+
+layer1 = Linear(shape=(784,), name="input")
+layer2 = Linear(shape=(256,), name="hidden")
+layer3 = Linear(shape=(10,), name="output")
+
+structure = graph(
+    nodes=[layer1, layer2, layer3],
+    edges=[Edge(source=layer1, target=layer2.slot("in")),
+           Edge(source=layer2, target=layer3.slot("in"))],
+    task_map=TaskMap(x=layer1, y=layer3),
+    inference=InferenceSGD(eta_infer=0.05, infer_steps=20),
+)
+
+rng_key = jax.random.PRNGKey(0)
+params = initialize_params(structure, rng_key)
+```
+
+## Demos
+
+The [`examples`](https://github.com/trueagi-io/FabricPC/tree/main/examples) folder includes working demonstrations across image classification, sequence modeling, depth scaling (`examples/scaling/`), associative memory, and architectural probes. Start with [`mnist_demo.py`](https://github.com/trueagi-io/FabricPC/blob/main/examples/mnist_demo.py) (over 98% accuracy on MNIST) and explore from there:
+
+- [`mnist_conv_demo.py`](https://github.com/trueagi-io/FabricPC/blob/main/examples/mnist_conv_demo.py) — convolutional MNIST classifier with `ConvNode` and `MaxPool`
+- [`resnet18_cifar10_demo.py`](https://github.com/trueagi-io/FabricPC/blob/main/examples/resnet18_cifar10_demo.py) — ResNet-18 as a PC graph, with global average pooling
+- [`transformer_v2_demo.py`](https://github.com/trueagi-io/FabricPC/blob/main/examples/transformer_v2_demo.py) — character- or BPE-level language modeling with text generation
+- [`transformer_tuning.py`](https://github.com/trueagi-io/FabricPC/blob/main/examples/transformer_tuning.py) — two-phase hyperparameter search minimizing validation perplexity
+
+## Documentation
+
+User guides, API reference, and tutorials live in [`docs/user_guides`](https://github.com/trueagi-io/FabricPC/blob/main/docs/user_guides/00_index.md). Development plans and technical design documents are in [`docs/dev_plans`](https://github.com/trueagi-io/FabricPC/tree/main/docs/dev_plans).
+
+## Extending FabricPC
+
+### Custom Nodes
+
+Create custom node types by subclassing `NodeBase`. Implement the `get_slots()`, `initialize_params()`, and `forward()` methods. Nodes have a single output. Slots define incoming connections and are referenced in edges when building the graph.
+
+See [`docs/user_guides/06_custom_nodes.md`](https://github.com/trueagi-io/FabricPC/blob/main/docs/user_guides/06_custom_nodes.md) for the node contract and a Conv2D teaching example (the production node is `fabricpc.nodes.ConvNode`).
+
+## Contributing
+
+Contributions are welcome! Please open issues or pull requests on the GitHub repository.
+- Develop on a branch using the convention `username/your_feature_name`.
+- Demos must match baseline results, or explain any divergence.
+- The test suite must pass.
+- Write unit tests and docstrings for new code.
+- Use the pre-commit hooks for PEP8 style and code quality.
+- Rebase before opening PR.
+
+This is a research-first project.
+- APIs may change frequently until the v1.0 release.
+- Any breaking changes are documented in the changelog.
+
+## Team
+
+FabricPC is actively maintained by SingularityNET as part of the Artificial Superintelligence Alliance. Project lead: Dr. Matthew Behrend.
+
+## License
+
+This project is licensed under the [MIT License](https://github.com/trueagi-io/FabricPC/blob/main/LICENSE).

fabricpc-0.4.0/fabricpc/__init__.py

@@ -0,0 +1,84 @@
+"""
+FabricPC-JAX: Predictive Coding Networks in JAX
+================================================
+
+A functional, high-performance implementation of predictive coding networks
+using JAX for automatic differentiation, JIT compilation, and multi-device parallelism.
+
+Key Features:
+- Functional programming paradigm (immutable data structures)
+- JIT-compiled inference and training loops
+- Multi-GPU/TPU support with pmap
+- XLA optimization for maximum performance
+
+Example:
+    >>> from fabricpc.nodes import Linear
+    >>> from fabricpc.core.topology import Edge
+    >>> from fabricpc.graph_assembly import TaskMap, graph
+    >>> from fabricpc.graph_initialization import initialize_params
+    >>> from fabricpc.training import train_pcn, evaluate_pcn
+    >>>
+    >>> # Define nodes
+    >>> input_node = Linear(shape=(784,), name="input")
+    >>> hidden = Linear(shape=(128,), name="hidden")
+    >>> output = Linear(shape=(10,), name="output")
+    >>>
+    >>> # Build graph
+    >>> structure = graph(
+    ...     nodes=[input_node, hidden, output],
+    ...     edges=[
+    ...         Edge(source=input_node, target=hidden.slot("in")),
+    ...         Edge(source=hidden, target=output.slot("in")),
+    ...     ],
+    ...     task_map=TaskMap(x=input_node, y=output),
+    ...     inference=InferenceSGD(eta_infer=0.05, infer_steps=10),
+    ... )
+    >>> params = initialize_params(structure, rng_key)
+    >>> trained_params, history, _ = train_pcn(params, structure, train_loader, config)
+    >>> metrics = evaluate_pcn(trained_params, structure, test_loader, config)
+"""
+
+from importlib.metadata import version
+
+__version__ = version("fabricpc")
+
+# Submodules (for advanced use)
+from fabricpc import (
+    core,
+    graph_initialization,
+    nodes,
+    training,
+    utils,
+    graph_assembly,
+    models,
+    experiments,
+)
+
+# Core API - what most users need
+from fabricpc.graph_initialization import initialize_params
+from fabricpc.training import train_pcn, evaluate_pcn
+from fabricpc.jax_config import setup_jax
+
+# Types - for type hints
+from fabricpc.core.types import GraphParams, GraphState, GraphStructure
+
+__all__ = [
+    # Core API (common use)
+    "initialize_params",
+    "train_pcn",
+    "evaluate_pcn",
+    "setup_jax",
+    # Types (for type hints)
+    "GraphParams",
+    "GraphState",
+    "GraphStructure",
+    # Submodules (advanced use)
+    "core",
+    "graph_assembly",
+    "graph_initialization",
+    "models",
+    "nodes",
+    "training",
+    "utils",
+    "experiments",
+]

fabricpc-0.4.0/fabricpc/core/__init__.py

@@ -0,0 +1,111 @@
+"""Core JAX predictive coding components."""
+
+# Type definitions
+from fabricpc.core.types import (
+    GraphParams,
+    GraphState,
+    GraphStructure,
+    NodeInfo,
+    EdgeInfo,
+    SlotInfo,
+    NodeParams,
+    NodeState,
+)
+
+# Activation functions
+from fabricpc.core.activations import (
+    ActivationBase,
+    IdentityActivation,
+    SigmoidActivation,
+    TanhActivation,
+    ReLUActivation,
+    LeakyReLUActivation,
+    GeluActivation,
+    SoftmaxActivation,
+    HardTanhActivation,
+)
+
+# Energy functions
+from fabricpc.core.energy import (
+    EnergyFunctional,
+    GaussianEnergy,
+    BernoulliEnergy,
+    CrossEntropyEnergy,
+    LaplacianEnergy,
+    HuberEnergy,
+    KLDivergenceEnergy,
+    compute_energy,
+    compute_energy_gradient,
+    get_energy_and_gradient,
+)
+
+# Inference functions and classes
+from fabricpc.core.inference import (
+    InferenceBase,
+    InferenceSGD,
+    InferenceSGDNormClip,
+    gather_inputs,
+    run_inference,
+)
+
+# Initializers
+from fabricpc.core.initializers import (
+    InitializerBase,
+    ZerosInitializer,
+    OnesInitializer,
+    NormalInitializer,
+    UniformInitializer,
+    XavierInitializer,
+    KaimingInitializer,
+    MuPCInitializer,
+    initialize,
+)
+
+__all__ = [
+    # Types
+    "GraphParams",
+    "GraphState",
+    "GraphStructure",
+    "NodeInfo",
+    "EdgeInfo",
+    "SlotInfo",
+    "NodeParams",
+    "NodeState",
+    # Activation functions
+    "ActivationBase",
+    "IdentityActivation",
+    "SigmoidActivation",
+    "TanhActivation",
+    "ReLUActivation",
+    "LeakyReLUActivation",
+    "GeluActivation",
+    "SoftmaxActivation",
+    "HardTanhActivation",
+    # Energy functions
+    "EnergyFunctional",
+    "GaussianEnergy",
+    "BernoulliEnergy",
+    "CrossEntropyEnergy",
+    "LaplacianEnergy",
+    "HuberEnergy",
+    "KLDivergenceEnergy",
+    "compute_energy",
+    "compute_energy_gradient",
+    "get_energy_and_gradient",
+    # Inference
+    "InferenceBase",
+    "InferenceSGD",
+    "InferenceSGDNormClip",
+    "gather_inputs",
+    "run_inference",
+    # Initializers
+    "InitializerBase",
+    "ZerosInitializer",
+    "OnesInitializer",
+    "NormalInitializer",
+    "UniformInitializer",
+    "XavierInitializer",
+    "KaimingInitializer",
+    "MuPCInitializer",
+    "initialize",
+]

fabricpc-0.4.0/fabricpc/core/_frozen.py

@@ -0,0 +1,59 @@
+"""Shared immutability mixin for stateless config value objects.
+
+``ActivationBase``, ``EnergyFunctional``, and ``InitializerBase`` place a single
+default instance directly in node ``__init__`` signatures. A signature default
+is evaluated once at import and shared by every defaulted call, so that instance
+is only safe if it cannot be mutated. ``FrozenConfig`` is the single source of
+that freeze for all three families.
+"""
+
+import types
+
+# Immutable scalar types accepted as config values. Tuples are accepted too,
+# recursively. A future structured value (e.g. a per-channel alpha) is a tuple,
+# not a list or an array.
+_IMMUTABLE_SCALARS = (bool, int, float, str, bytes, type(None))
+
+
+def _validate_immutable(value, key, owner):
+    """Reject any config value that is not an immutable scalar or a tuple of them."""
+    if isinstance(value, _IMMUTABLE_SCALARS):
+        return
+    if isinstance(value, tuple):
+        for item in value:
+            _validate_immutable(item, key, owner)
+        return
+    raise TypeError(
+        f"{owner} config value {key!r} must be an immutable scalar "
+        f"(int, float, str, bool, bytes, None) or a tuple of those; "
+        f"got {type(value).__name__}"
+    )
+
+
+class FrozenConfig:
+    """Freezes an instance after construction.
+
+    Once ``__init__`` has run, attributes cannot be set or deleted, and
+    ``config`` is a read-only mapping whose keys cannot be added, removed, or
+    reassigned. Config values are validated at construction: only immutable
+    scalars (int, float, str, bool, bytes, None) and tuples of those are
+    accepted, so the whole object is immutable, not just its top level.
+    """
+
+    def __init__(self, **config):
+        for key, value in config.items():
+            _validate_immutable(value, key, type(self).__name__)
+        # object.__setattr__ bypasses the freeze below to set these two fields
+        # once; every later assignment goes through __setattr__ and is rejected.
+        object.__setattr__(self, "config", types.MappingProxyType(config))
+        object.__setattr__(self, "_frozen", True)
+
+    def __setattr__(self, name, value):
+        if getattr(self, "_frozen", False):
+            raise AttributeError(
+                f"{type(self).__name__} is immutable; cannot set {name!r}"
+            )
+        object.__setattr__(self, name, value)
+
+    def __delattr__(self, name):
+        raise AttributeError(f"{type(self).__name__} is immutable")