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