fhelium.serialization

Exact typed serialization primitives for FHElium values.

FILE_FORMAT

constant View source

FILE_FORMAT = 'fhelium-value'

FILE_SCHEMA_VERSION

constant View source

FILE_SCHEMA_VERSION = 1

VALUE_SCHEMA_VERSION

constant View source

VALUE_SCHEMA_VERSION = 2

ValueEnvelope

class View source

ValueEnvelope(schema_version: int, value_type: str, context_id: str | None, metadata: dict[str, Any], tensors: dict[str, torch.Tensor])

An exact value description with tensors but no path or store policy.

The envelope is the shared representation for application-owned storage and memory managers. Its tensors may be moved or persisted by the caller, then passed to to_value to reconstruct the exact FHElium value type.

Attributes

Name	Type	Default/value
schema_version	int
value_type	str
context_id	str | None
metadata	dict[str, Any]
tensors	dict[str, torch.Tensor]

from_value

method

def from_value(value: TensorResident) -> Self: ...

Describe one exact live value without choosing storage policy.

to_value

method

def to_value() -> TensorResident: ...

Reconstruct the exact concrete FHElium value type.

nbytes

property

nbytes: int

ValueFileMetadata

class View source

ValueFileMetadata(file_schema_version: int, value_schema_version: int, value_type: str, context_id: str | None, nbytes: int, tensor_metadata: dict[str, dict[str, Any]], value_metadata: dict[str, Any])

Validated metadata inspectable without materializing tensor payloads.

Attributes

Name	Type	Default/value
file_schema_version	int
value_schema_version	int
value_type	str
context_id	str | None
nbytes	int
tensor_metadata	dict[str, dict[str, Any]]
value_metadata	dict[str, Any]

inspect_value

function View source

def inspect_value(path: str | os.PathLike[str]) -> ValueFileMetadata: ...

Inspect one value file without materializing its tensor payloads.

load_value

function View source

def load_value(path: str | os.PathLike[str], *, device: torch.device | str='cpu', expected_type: type[T] | None=None, expected_context_id: str | None=None) -> T: ...

Load one exact value from a caller-selected value-file path.

This is a file-codec operation: the caller owns path naming, replacement, and lifecycle. ArtifactStore.get is the separate repository operation for logical names, generations, checksums, and catalog transactions. Materialization defaults to CPU unless device selects another target.

save_value

function View source

def save_value(value: TensorResident, path: str | os.PathLike[str], *, allow_secret: bool=False, overwrite: bool=False) -> ValueFileMetadata: ...

Atomically save one exact value to the caller-selected file path.

This function provides a versioned file representation, not a namespace, cache, encryption-at-rest policy, or storage manager. Secret-key material requires explicit opt-in and remains unencrypted unless the caller wraps this API in an appropriate security layer.

supported_value_types

function View source

def supported_value_types() -> tuple[str, ...]: ...