xtrace_sdk.x_vec.utils.execution_context ======================================== .. py:module:: xtrace_sdk.x_vec.utils.execution_context Attributes ---------- .. autoapisummary:: xtrace_sdk.x_vec.utils.execution_context._log Classes ------- .. autoapisummary:: xtrace_sdk.x_vec.utils.execution_context.HomomorphicClient xtrace_sdk.x_vec.utils.execution_context.ExecutionContext Module Contents --------------- .. py:data:: _log .. py:class:: HomomorphicClient Bases: :py:obj:`Protocol` Protocol describing all methods used by ExecutionContext on a homomorphic client. .. py:method:: encrypt_vec_one(embd) .. py:method:: encrypt_vec_batch(embds) .. py:method:: decode_hamming_client_one(cipher) .. py:method:: decode_hamming_client_batch(ciphers) .. py:method:: stringify_sk() .. py:method:: stringify_pk() .. py:method:: stringify_config() .. py:method:: load_stringified_keys(pk, sk) .. py:class:: 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. :param homomorphic_client: An initialised ``PaillierClient`` or ``PaillierLookupClient``. :param passphrase: Secret passphrase used to derive the AES encryption key. :param context_id: Optional deterministic ID. If omitted, one is derived from a SHA-256 hash of the public key and configuration. .. py:attribute:: homomorphic .. py:attribute:: aes .. py:method:: create(passphrase, homomorphic_client_type, embedding_length, key_len, path = None) :classmethod: Create a new execution context and optionally save it to disk. :param passphrase: Secret passphrase used to derive the AES encryption key and protect the homomorphic secret key at rest. :param homomorphic_client_type: ``"paillier"`` or ``"paillier_lookup"``. :param embedding_length: Dimension of the binary embedding vectors (must match the model). :param key_len: RSA modulus size in bits (minimum ``1024``). :param path: If provided, persist the context to this file path via :meth:`save_to_disk`. :return: Initialised ``ExecutionContext``. :raises ValueError: If ``homomorphic_client_type`` is not recognised or ``embedding_length >= key_len``. .. py:property:: device :type: str ``"cpu"`` or ``"gpu"``. :type: Active compute backend .. py:method:: to_dict_enc() Return a serialisable dict with the secret key AES-encrypted under the passphrase. .. py:method:: to_dict_plain() Return a serialisable dict with the secret key in plaintext. Do not persist or transmit. .. py:method:: embed_len() Embedding vector dimension this context was configured for. .. py:method:: key_len() RSA modulus size in bits used for key generation. .. py:method:: __str__() .. py:method:: 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. :return: Hex-encoded SHA-256 digest. :rtype: str .. py:method:: __hash__() .. py:method:: __eq__(other) .. py:method:: _config_with_device() .. py:method:: 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. :return: JSON string representing the encrypted execution context. :rtype: str :raises ValueError: If the homomorphic client type is not supported. .. py:method:: _from_serialized_exec_context(passphrase, json_obj, context_id = None) :classmethod: Reconstruct an ``ExecutionContext`` from a previously serialised dict. :param passphrase: Passphrase used to decrypt the secret key. :param json_obj: Dict produced by :meth:`to_dict_enc`. :param context_id: Optional context ID to attach; if ``None`` one is recomputed from the keys. :return: Restored ``ExecutionContext``. :raises ValueError: If the stored homomorphic client type is not supported. .. py:method:: dump_tables() Dump precomputed encryption tables (Paillier-Lookup only) for caching. :return: Dict containing ``g_table`` and ``noise_table``, or an empty dict if the underlying client does not support table export. :rtype: dict .. py:method:: 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. :param path: File path to write to. :type path: str .. py:method:: load_from_disk(passphrase, path) :classmethod: Load an ``ExecutionContext`` from a file previously saved with :meth:`save_to_disk`. :param passphrase: Passphrase used to decrypt the secret key. :param path: File path to read from. :return: Restored ``ExecutionContext``. .. py:method:: save_to_remote(integration) :async: 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. :param integration: Authenticated :class:`~xtrace_sdk.integrations.xtrace.XTraceIntegration` instance. :return: The ``context_id`` assigned by the server. :rtype: str .. py:method:: load_from_remote(passphrase, context_id, integration) :classmethod: :async: Fetch and decrypt an ``ExecutionContext`` from XTrace remote storage. :param passphrase: Passphrase used to decrypt the secret key. :param context_id: ID returned when the context was originally saved. :param integration: Authenticated :class:`~xtrace_sdk.integrations.xtrace.XTraceIntegration` instance. :return: Restored ``ExecutionContext``.