neuralqx.experimental.utils.struct.registry module

Class-reference registry utilities for struct and pytree serialisation.

This module provides a stable mechanism for converting runtime classes into importable string references and resolving them back later.

Class references use the canonical format:

"module.path:QualifiedClassName"

Examples: - "neuralqx.graph.core.graph_handler:GraphHandler" - "my_pkg.subpkg.models:Outer.Inner"

Struct and pytree serialisation needs a process-independent way to identify types. Raw class objects are not portable across sessions, but importable class references are.

The registry combines:

  • a fast in-memory cache for already-seen classes,

  • a lazy importer fallback for classes not yet loaded in the process.

class_ref(cls)

Return canonical class reference string for cls.

Parameters:

cls (type[Any]) – Runtime class object to encode.

Return type:

str

Returns:

A deterministic "module:qualname" reference suitable for manifests.

Notes

The returned value is purely structural and does not validate importability at call time. Import validation occurs during resolve_class().

register_class_ref(cls)

Register cls in the process-local class cache.

This improves resolution speed and avoids repeated import traversal for classes already encountered during struct/pytree processing.

Return type:

None

resolve_class(ref)

Resolve a class reference into a runtime class object.

This functions resolves by:

  1. Look up ref in the in-memory registry cache.

  2. If missing, import module + qualified name lazily.

  3. Cache resolved result for future calls.

Parameters:

ref (str) – Class reference in "module:qualname" format.

Return type:

type[Any]

Returns:

Imported and validated class object.

Raises:

SerializationError – If the reference format is invalid, import fails, attribute traversal fails, or the resolved object is not a class.