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 key-provider-protected object.

Functions¶

_resolve_key_provider(key_provider, passphrase, salt)

Return a concrete KeyProvider, preferring an explicit provider over passphrase.

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:: xtrace_sdk.x_vec.utils.xtrace_types.EncryptedVector

encrypt_vec_batch(embds)¶

Parameters:: embds (list[list[int]])
Return type:: list[xtrace_sdk.x_vec.utils.xtrace_types.EncryptedVector]

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

xtrace_sdk.x_vec.utils.execution_context._resolve_key_provider(key_provider, passphrase, salt)¶

Return a concrete KeyProvider, preferring an explicit provider over passphrase.

Parameters:

key_provider (xtrace_sdk.x_vec.crypto.key_provider.KeyProvider | None)
passphrase (str | None)
salt (bytes | None)

Return type:

xtrace_sdk.x_vec.crypto.key_provider.KeyProvider

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

Bundles a homomorphic encryption client and an AES key under a single key-provider-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 supplied by a KeyProvider, used to encrypt chunk content before upload.

The secret key is never transmitted in plaintext — it is AES-encrypted with the key provider’s key before any remote storage.

Parameters:

homomorphic_client (HomomorphicClient) – An initialised PaillierClient or PaillierLookupClient.
key_provider (xtrace_sdk.x_vec.crypto.key_provider.KeyProvider) – A KeyProvider that supplies 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¶

key_provider¶

aes¶

classmethod create(passphrase=None, homomorphic_client_type='paillier', embedding_length=512, key_len=1024, salt=None, path=None, key_provider=None)¶

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

Supply either key_provider or passphrase (with optional salt). If both are given, key_provider takes precedence.

Parameters:

passphrase (str | None) – 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).
salt (bytes | None) – Optional salt bytes for passphrase-based key derivation.
path (str | None) – If provided, persist the context to this file path via save_to_disk().
key_provider (xtrace_sdk.x_vec.crypto.key_provider.KeyProvider | None) – Explicit KeyProvider instance (e.g. AWSKMSKeyProvider).

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 key provider.

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 key provider 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(json_obj, passphrase=None, key_provider=None, context_id=None)¶

Reconstruct an ExecutionContext from a previously serialised dict.

Supply either key_provider or passphrase. For passphrase-based contexts the salt is read from the stored wrapped_key field automatically.

Parameters:

json_obj (dict) – Dict produced by to_dict_enc().
passphrase (str | None) – Passphrase for passphrase-based contexts.
key_provider (xtrace_sdk.x_vec.crypto.key_provider.KeyProvider | None) – Explicit KeyProvider to use for decryption.
context_id (str | None) – Optional context ID to attach; if None one is recomputed.

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/key is not stored.

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

classmethod load_from_disk(passphrase=None, path='', key_provider=None)¶

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

Parameters:

passphrase (str | None) – Passphrase for passphrase-based contexts.
path (str) – File path to read from.
salt – Optional salt for passphrase-based key derivation.
key_provider (xtrace_sdk.x_vec.crypto.key_provider.KeyProvider | None) – Explicit KeyProvider (e.g. AWSKMSKeyProvider).

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 key provider 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=None, context_id='', integration=None, key_provider=None)¶

Async:

Parameters:

passphrase (str | None)
context_id (str)
integration (XTraceIntegration | None)
key_provider (xtrace_sdk.x_vec.crypto.key_provider.KeyProvider | None)

Return type:

ExecutionContext

Fetch and decrypt an ExecutionContext from XTrace remote storage.

Parameters:

passphrase (str | None) – Passphrase for passphrase-based contexts.
context_id (str) – ID returned when the context was originally saved.
integration (XTraceIntegration | None) – Authenticated XTraceIntegration instance.
salt – Optional salt for passphrase-based key derivation.
key_provider (xtrace_sdk.x_vec.crypto.key_provider.KeyProvider | None) – Explicit KeyProvider (e.g. AWSKMSKeyProvider).

Returns:

Restored ExecutionContext.

Return type:

ExecutionContext