neuralqx.experimental.utils.struct.io module

Public serialization APIs for Struct and registered pytree types.

The implementation lives in neuralqx.utils.struct._internals.io. This module intentionally exposes a compact, stable public surface while hiding wire-format and storage details behind internal helpers.

Supported use cases:

  1. Convert runtime values into Python-inspection views (to_python()).

  2. Build in-memory portable payloads (to_state_dict()).

  3. Restore from in-memory payloads (from_state_dict()).

  4. Persist payloads to directory or .zip bundles (export()).

  5. Load persisted bundles back into objects (load()).

Struct I/O uses a two-part representation:

  • manifest: JSON-friendly structural metadata and object graph encoding.

  • arrays: compressed array blobs stored separately for efficiency.

to_python(value, *, include_opaque=True)

Convert a possibly nested value into Python-native inspection form.

This helper recursively converts:

  • Struct objects into dict form,

  • registered pytrees into explicit structural views,

  • JAX/NumPy arrays into NumPy arrays.

Parameters:

  • value (Any) – Any value possibly containing structs/pytrees.

  • include_opaque (bool) – Whether to include opaque struct fields in the resulting object graph.

Return type:

Any

Returns:

A Python-friendly representation preserving overall structure.

Notes

to_python is designed for introspection/debugging, not for persistence. For portable storage use to_state_dict() or export().

to_state_dict(obj)

Encode an object graph into a portable state-dict payload.

The returned mapping contains:

  • version: schema version integer.

  • manifest: JSON-serialisable structural manifest.

  • arrays: array metadata (shape/dtype).

  • array_data: in-memory NumPy arrays.

Parameters:

obj (Any) – Root object to encode. May be a Struct, a registered pytree class, or nested built-in containers of supported types.

Return type:

dict[str, Any]

Returns:

In-memory transport format suitable for from_state_dict().

Raises:

SerializationError – if unsupported values are encountered and no adapter is registered.

from_state_dict(payload, *, expected_cls=None)

Reconstruct an object graph from to_state_dict() output.

Parameters:

  • payload (Mapping[str, Any]) – State payload produced by to_state_dict().

  • expected_cls (type[Any] | None) – Optional type guard. If provided, serialised root object must be an instance/subclass of this type.

Return type:

Any

Returns:

Reconstructed object graph.

Raises:

SerializationError – If payload schema/version is invalid, required arrays are missing, class resolution fails, adapters are unavailable, or type guard check fails.

export(obj, path, *, overwrite=False)

Export object state to a directory bundle or .zip archive.

Directory/zip output always includes:

  • manifest.json structural payload

  • arrays.npz compressed array buffer

Parameters:

  • obj (Any) – Object graph to export.

  • path (str | Path) – Output location. Suffix .zip writes a compressed archive, any other path writes a directory bundle.

  • overwrite (bool) – If False (default), existing output path raises FileExistsError.

Return type:

Path

Returns:

Final output path.

load(path, *, expected_cls=None)

Load a previously exported state bundle.

Parameters:

  • path (str | Path) – Either a directory path containing manifest.json and arrays.npz, or a .zip file with the same contents.

  • expected_cls (type[Any] | None) – Optional runtime guard for expected root type.

Return type:

Any

Returns:

Decoded object graph.

Raises: