fhelium.execution.signature

Structural signatures for reusable FHElium execution values.

Signatures describe copy-compatible tensor topology and exact FHElium value state. They deliberately exclude tensor residency: a CPU value and a CUDA value may have the same signature and can therefore be copied through a fhelium.execution.ReusableValueBuffer whose target device is tracked separately.

TensorSignature

class View source

TensorSignature(shape: tuple[int, ...], stride: tuple[int, ...], dtype: torch.dtype, layout: torch.layout, requires_grad: bool)

Device-independent tensor topology accepted by one execution buffer.

device is intentionally absent. Shape, stride, dtype, layout, and requires_grad determine whether payload can be copied into fixed target storage; the target residency belongs to the buffer or program that owns that storage.

Parameters

• shape: Exact tensor dimensions.
• stride: Exact element strides required by fixed target storage.
• dtype: Tensor scalar dtype.
• layout: PyTorch tensor layout, normally torch.strided.
• requires_grad: Autograd flag expected by the reusable payload.

Attributes

Name	Type	Default/value
shape	tuple[int, ...]
stride	tuple[int, ...]
dtype	torch.dtype
layout	torch.layout
requires_grad	bool

from_tensor

method

def from_tensor(tensor: torch.Tensor) -> TensorSignature: ...

Build a copy-compatibility signature for tensor.

Parameters

• tensor: Representative tensor whose device-independent topology is captured.

Returns

Signature excluding the tensor's current device.

ValueSignature

class View source

ValueSignature(type_name: str, schema_version: int, context_id: str | None, metadata: tuple[tuple[str, object], ...], tensors: tuple[tuple[str, TensorSignature], ...])

Exact FHElium value state plus device-independent tensor topology.

A value signature fixes cryptographic metadata such as context, level, scale, plaintext representation, polynomial domain, modulus basis, residue representation, prime identities, schema version, and key identity. A value signature is storage-independent metadata. Model, user, request, and cache associations remain external.

Parameters

• type_name: Registered serialized exact-value class name.
• schema_version: Exact-value serialization schema version.
• context_id: Cryptographic context identity, if the value has one.
• metadata: Frozen, deterministically ordered non-tensor exact state.
• tensors: Ordered tensor names and their device-independent signatures.

Attributes

Name	Type	Default/value
type_name	str
schema_version	int
context_id	str | None
metadata	tuple[tuple[str, object], ...]
tensors	tuple[tuple[str, TensorSignature], ...]

from_value

method

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

Describe one serializable exact FHElium value.

Parameters

• value: Exact resident value whose type, metadata, and tensor topology are captured.

Returns

Device-independent exact-value signature.

ValueTreeSignature

class View source

ValueTreeSignature(kind: TreeKind, leaf: TensorSignature | ValueSignature | None = None, children: tuple[ValueTreeSignature, ...] = (), keys: tuple[object, ...] = ())

Structure of tensors and exact values in a reusable execution payload.

Supported leaves are torch.Tensor and serializable FHElium fhelium.core.TensorResident values. Lists, tuples, and dictionaries may nest those leaves. Arbitrary Python scalars and control objects are intentionally unsupported; bind them statically in a callable or keep them in the application control plane.

ValueTreeSignature composes TensorSignature and ValueSignature rather than replacing them: tensor leaves need only tensor topology, while exact-value leaves additionally require cryptographic metadata.

Parameters

• kind: Node kind: tensor, exact value, list, tuple, or dictionary.
• leaf: Tensor/value signature for a leaf node; None for containers.
• children: Ordered signatures nested by a container node.
• keys: Dictionary keys in the same order as children; empty for all other node kinds.

Attributes

Name	Type	Default/value
kind	TreeKind
leaf	TensorSignature | ValueSignature | None	None
children	tuple[ValueTreeSignature, ...]	()
keys	tuple[object, ...]	()

from_value

method

def from_value(value: object) -> ValueTreeSignature: ...

Describe a supported tensor/exact-value tree.

Parameters

• value: Representative tensor/exact-value tree to describe.

Returns

Recursive device-independent structure and exact-state signature.

Raises

• TypeError: If a leaf is not a tensor or serializable exact FHElium value, or if a container is not a list, tuple, or dictionary.

validate

method

def validate(value: object, *, path: str='value') -> None: ...

Require value to have this exact structure and state.

Tensor devices may differ because signatures describe transfer compatibility, not residency. Validation completes for the full tree before fhelium.execution.ReusableValueBuffer copies any payload.

Parameters

• value: Candidate tree to compare with this signature.
• path: Root label used in mismatch diagnostics.

Raises

• ExecutionInputError: If structure, tensor topology, or exact-value metadata differs.