xtrace_sdk.x_vec.utils.execution_context¶

Attributes¶

_log

Classes¶

`HomomorphicClient`	Protocol describing all methods used by ExecutionContext on a homomorphic client.
`ExecutionContext`	Bundles a homomorphic encryption client and an AES key under a single passphrase-protected object.

Module Contents¶

xtrace_sdk.x_vec.utils.execution_context._log¶

class xtrace_sdk.x_vec.utils.execution_context.HomomorphicClient¶

Bases: Protocol

Protocol describing all methods used by ExecutionContext on a homomorphic client.

encrypt_vec_one(embd)¶

Parameters:: embd (list[int])
Return type:: list[int]

encrypt_vec_batch(embds)¶

Parameters:: embds (list[list[int]])
Return type:: list[list[int]]

decode_hamming_client_one(cipher)¶

Parameters:: cipher (list[int | bytes])
Return type:: int

decode_hamming_client_batch(ciphers)¶

Parameters:: ciphers (list[list[int | bytes]])
Return type:: list[int]

stringify_sk()¶

Return type:: str

stringify_pk()¶

Return type:: str

stringify_config()¶

Return type:: str

load_stringified_keys(pk, sk)¶

Parameters:

pk (str)
sk (str)

Return type:

None

class xtrace_sdk.x_vec.utils.execution_context.ExecutionContext(homomorphic_client, passphrase, context_id=None)¶

Bundles a homomorphic encryption client and an AES key under a single passphrase-protected object.

An ExecutionContext is the root secret for a XTrace deployment. It holds:

A homomorphic client (PaillierClient or PaillierLookupClient) whose secret key is used to decrypt Hamming distances returned by the XTrace server.
An AES key derived from passphrase, used to encrypt chunk content before upload.

The secret key is never transmitted in plaintext — it is AES-encrypted with the passphrase before any remote storage. The passphrase itself is never sent anywhere.

Parameters:

homomorphic_client (HomomorphicClient) – An initialised PaillierClient or PaillierLookupClient.
passphrase (str) – Secret passphrase used to derive the AES encryption key.
context_id (str | None) – Optional deterministic ID. If omitted, one is derived from a SHA-256 hash of the public key and configuration.

homomorphic¶

aes¶

classmethod create(passphrase, homomorphic_client_type, embedding_length, key_len, path=None)¶

Create a new execution context and optionally save it to disk.

Parameters:

passphrase (str) – Secret passphrase used to derive the AES encryption key and protect the homomorphic secret key at rest.
homomorphic_client_type (str) – "paillier" or "paillier_lookup".
embedding_length (int) – Dimension of the binary embedding vectors (must match the model).
key_len (int) – RSA modulus size in bits (minimum 1024).
path (str | None) – If provided, persist the context to this file path via save_to_disk().

Returns:

Initialised ExecutionContext.

Raises:

ValueError – If homomorphic_client_type is not recognised or embedding_length >= key_len.

Return type:

ExecutionContext

property device: str¶

"cpu" or "gpu".

Type:: Active compute backend
Return type:: str

to_dict_enc()¶

Return a serialisable dict with the secret key AES-encrypted under the passphrase.

Return type:: dict

to_dict_plain()¶

Return a serialisable dict with the secret key in plaintext. Do not persist or transmit.

Return type:: dict

embed_len()¶

Embedding vector dimension this context was configured for.

Return type:: int

key_len()¶

RSA modulus size in bits used for key generation.

Return type:: int

__str__()¶

Return type:: str

hash()¶

Compute a deterministic SHA-256 fingerprint of this context’s cryptographic identity.

The device field is excluded so that CPU and GPU contexts sharing the same keys compare as equal.

Returns:: Hex-encoded SHA-256 digest.
Return type:: str

__hash__()¶

Return type:: int

__eq__(other)¶

Parameters:: other (Any)
Return type:: bool

_config_with_device()¶

Return type:: str

serialize_exec_context()¶

Serialise the execution context to a JSON string suitable for storage or transmission.

The secret key is AES-encrypted under the passphrase before inclusion.

Returns:: JSON string representing the encrypted execution context.
Return type:: str
Raises:: ValueError – If the homomorphic client type is not supported.

classmethod _from_serialized_exec_context(passphrase, json_obj, context_id=None)¶

Reconstruct an ExecutionContext from a previously serialised dict.

Parameters:

passphrase (str) – Passphrase used to decrypt the secret key.
json_obj (dict) – Dict produced by to_dict_enc().
context_id (str | None) – Optional context ID to attach; if None one is recomputed from the keys.

Returns:

Restored ExecutionContext.

Raises:

ValueError – If the stored homomorphic client type is not supported.

Return type:

ExecutionContext

dump_tables()¶

Dump precomputed encryption tables (Paillier-Lookup only) for caching.

Returns:: Dict containing g_table and noise_table, or an empty dict if the underlying client does not support table export.
Return type:: dict

save_to_disk(path)¶

Persist the execution context to a local file.

The secret key is AES-encrypted before writing. The passphrase is not stored.

Parameters:: path (str) – File path to write to.
Return type:: None

classmethod load_from_disk(passphrase, path)¶

Load an ExecutionContext from a file previously saved with save_to_disk().

Parameters:

passphrase (str) – Passphrase used to decrypt the secret key.
path (str) – File path to read from.

Returns:

Restored ExecutionContext.

Return type:

ExecutionContext

async save_to_remote(integration)¶

Upload the execution context to XTrace remote storage.

The secret key is AES-encrypted under the passphrase before upload — XTrace never sees the plaintext secret key or the passphrase.

Parameters:: integration (xtrace_sdk.integrations.xtrace.XTraceIntegration) – Authenticated XTraceIntegration instance.
Returns:: The context_id assigned by the server.
Return type:: str

classmethod load_from_remote(passphrase, context_id, integration)¶

Async:

Parameters:

passphrase (str)
context_id (str)
integration (xtrace_sdk.integrations.xtrace.XTraceIntegration)

Return type:

ExecutionContext

Fetch and decrypt an ExecutionContext from XTrace remote storage.

Parameters:

passphrase (str) – Passphrase used to decrypt the secret key.
context_id (str) – ID returned when the context was originally saved.
integration (xtrace_sdk.integrations.xtrace.XTraceIntegration) – Authenticated XTraceIntegration instance.

Returns:

Restored ExecutionContext.

Return type:

ExecutionContext