mixle.experimental.typed_runtime.compression moduleΒΆ

Explicit exact/approximate delta transport with acknowledged error feedback.

class CompressedDelta(method, shape, dtype, arrays, receipt, feedback_token)[source]

Bases: object

Immutable wire payload whose residual transition is pending acknowledgement.

Parameters:

  • method (CompressionMethod)

  • shape (tuple[int, ...])

  • dtype (str)

  • arrays (tuple[ndarray, ...])

  • receipt (CompressionReceipt)

  • feedback_token (str)

reconstruct()[source]

Reconstruct a dense delta in the declared dtype and shape.

Return type:

ndarray

property payload_hash: str

Deterministic transport fingerprint.

as_dict()[source]

Return metadata without serializing array contents.

Return type:

dict[str, Any]

class CompressionAcknowledgement(key, feedback_token, payload_hash, applied, residual_l2_norm_before, residual_l2_norm_after)[source]

Bases: object

Committed or rejected residual transition for one delivered payload.

Parameters:

  • key (str)

  • feedback_token (str)

  • payload_hash (str)

  • applied (bool)

  • residual_l2_norm_before (float)

  • residual_l2_norm_after (float)

class CompressionMethod(*values)[source]

Bases: StrEnum

Wire representation selected for one delta.

class CompressionReceipt(key, method, input_bytes, payload_bytes, rank_or_nnz, realized_l2_error, relative_l2_error, pending_residual_l2_norm, exact, approximation_authorized, maximum_relative_l2_error)[source]

Bases: object

Measured bytes/error and authorization for one staged transport payload.

Parameters:

  • key (str)

  • method (CompressionMethod)

  • input_bytes (int)

  • payload_bytes (int)

  • rank_or_nnz (int)

  • realized_l2_error (float)

  • relative_l2_error (float)

  • pending_residual_l2_norm (float)

  • exact (bool)

  • approximation_authorized (bool)

  • maximum_relative_l2_error (float | None)

property compression_ratio: float

Dense bytes divided by transmitted payload bytes.

as_dict()[source]

Return a JSON-compatible staged-compression receipt.

Return type:

dict[str, Any]

class ErrorFeedbackCompressor(*, default_rank=1, default_topk_fraction=0.1, exact_threshold_bytes=4_096)[source]

Bases: object

Compressor whose residual changes only after acknowledged payload application.

Parameters:

  • default_rank (int)

  • default_topk_fraction (float)

  • exact_threshold_bytes (int)

residual(key)[source]

Return a copy of one committed error-feedback residual.

Parameters:

key (str)

Return type:

ndarray | None

compress(key, delta, contract, *, allow_approximation=False, maximum_relative_l2_error=None, rank=None, topk_fraction=None)[source]

Stage one payload without changing committed residual state.

Lossy transport requires allow_approximation=True, a finite error budget, and a non-exact update contract. Merge-law metadata never authorizes approximation. Call acknowledge() after delivery/application; until then another payload for key is refused.

Parameters:

  • key (str)

  • delta (Any)

  • contract (UpdateContract)

  • allow_approximation (bool)

  • maximum_relative_l2_error (float | None)

  • rank (int | None)

  • topk_fraction (float | None)

Return type:

CompressedDelta

acknowledge(delta, *, applied)[source]

Commit a staged residual only after the payload was applied, or discard it on failure.

Parameters:

  • delta (CompressedDelta)

  • applied (bool)

Return type:

CompressionAcknowledgement

state_dict()[source]

Return checkpointable committed state; in-flight transitions must be resolved first.

Return type:

dict[str, Any]

load_state_dict(state)[source]

Atomically restore validated committed error-feedback state.

Parameters:

state (dict[str, Any])

Return type:

None