mixle.utils.serialization module

Safe JSON serialization helpers for mixle distribution and estimator objects.

The legacy load_models(eval_string) path reconstructed models by executing their repr strings. This module instead serializes distribution state as a small tagged JSON value graph and reconstructs only classes registered from mixle’s own distribution modules.

exception SerializationError

Bases: ValueError

Raised when an object cannot be serialized or decoded safely.

deserialization_is_trusted()

Whether the current context has opted into code-executing deserialization.

Checked by mixle.models._neural_serial before unpickling an embedded torch module. Not needed for the ordinary registry-based path (from_serializable() on a payload with no embedded module blob), which never executes code regardless of this flag.

Return type:

bool

trusted_deserialization()

Permit code-executing deserialization (an embedded torch module) for this with block.

Only enter this around an artifact whose SOURCE you trust: within the block, decoding a NeuralLeaf-family object (or anything else that persists live code/objects via pickle) executes that pickle’s __reduce__/__setstate__ arbitrarily, exactly like pickle.load on an untrusted file. Nested/re-entrant use is safe (the gate stays open until the outermost block exits).

The authority is deliberately NOT inherited by child work. contextvars are copied into child asyncio tasks and into an explicitly copied context on another thread, so ambient propagation would let a task spawned inside this block keep decoding trusted artifacts for its whole lifetime – including after the parent block exited. _TrustScope therefore pins the owning thread and task, and deserialization_is_trusted() reports False anywhere but that one synchronous decode context. Open the block again in the child if it genuinely needs the authority.

Return type:

Iterator[None]

register_serializable_class(cls, type_id=None)

Register a class that may be reconstructed from serialized state.

Deserialization never imports a class named in the payload. The class must already be present in this registry, which is populated from mixle package modules by ensure_pysp_serialization_registry.

Parameters:

• cls (type[Any])

• type_id (str | None)

Return type:

type[Any]

register_serializable_callable(fn, callable_id=None)

Register a callable that may appear inside a serialized distribution.

This is intentionally explicit. Arbitrary lambdas or local functions cannot be made safe by JSON alone; callers that need SelectDistribution-like routing should register a stable process-local callable id.

Parameters:

• fn (Callable[[...], Any])

• callable_id (str | None)

Return type:

Callable[[…], Any]

serializable_class_ids()

Return the registered class ids, primarily for diagnostics/tests.

Return type:

set[str]

serializable_schema_records(profile='full')

Return the declared per-type schema records for one generation profile.

base excludes torch-backed mixle.models types. full includes every type available after the optional serialization-module discovery. A generator must separately attest that the profile’s dependency inventory is installed before treating this record as complete.

Parameters:

profile (str)

Return type:

dict[str, dict[str, Any]]

ensure_pysp_serialization_registry()

Populate the closed registry of mixle classes that can be decoded.

Return type:

None

to_serializable(value)

Convert a mixle model/value to a JSON-compatible tagged value.

Parameters:

value (Any)

Return type:

Any

from_serializable(payload)

Decode a value produced by to_serializable.

Parameters:

payload (Any)

Return type:

Any

to_json(value, **kwargs)

Serialize a mixle model/value to strict JSON.

Parameters:

• value (Any)

• kwargs (Any)

Return type:

str

from_json(text)

Deserialize a value produced by to_json.

Parameters:

text (str)

Return type:

Any

rebuild_through_init(instance, state, *, parameters, label)

Rebuild instance from a serialized parameter state by re-running its own __init__.

The counterpart of a __pysp_getstate__ that writes constructor parameters only: derived caches are recomputed rather than persisted, so an artifact does not depend on how the caches were laid out when it was written, and every constructor invariant re-runs on load. Families whose state carried derived caches, or whose constructor keyword differs from the attribute name, could not be read back at all – to_json produced text from_json refused, and Model.deploy fell back to a code-executing pickle for them (P05-F17, P09-F05, P10-F05).

parameters names the constructor keywords in the order they are written; each must be present in state, and nothing else may be.

Parameters:

• instance (Any)

• state (Any)

• parameters (tuple[str, ...])

• label (str)

Return type:

None