Configuration

The XTraceSDK is designed to be highly configurable to suit various use cases and environments. This section will guide you through the configuration options available in the SDK. You can configure the SDK by setting environment variables or by passing parameters directly to the classes and methods.

Cryptography Configuration

The SDK supports various cryptographic algorithms for data encryption and decryption. You can configure the cryptographic settings by passing the appropriate parameters to the crypto client classes. For example, when using the PaillierClient, you can specify the embedding length, and key length:

from xtrace_sdk.crypto.paillier_client import PaillierClient

paillier_client = PaillierClient(embd_len=512, key_len=1024)

Execution Context Configuration

The ExecutionContext class allows you to configure the execution environment for the SDK. It contains configs for cryptographic clients and sensitive cryptographic parameters. You can create an instance of the ExecutionContext class by passing the required parameters:

from xtrace_sdk.utils.execution_context import ExecutionContext
from xtrace_sdk.crypto.paillier_client import PaillierClient
from xtrace_sdk.crypto.encryption.aes import AESClient
from xtrace_sdk.compute import Compute

paillier_client = PaillierClient(embd_len=512, key_len=1024)

execution_context = ExecutionContext(
    paillier_client=paillier_client,
    passphrase="this is a super safe passphrase",
)

Note the passphrase is used to encrypt/decrypt sensitive cryptographic parameters, such as the homomorphic secret key, and it should be kept secret. By design, there’s no way to store or retrieve the passphrase in the SDK. You should manage it securely in your application.

You can store/load the execution context to a file for later use:

# Save to disk
execution_context.save_to_disk("execution_context.json")

# Load from disk
execution_context = ExecutionContext._load_from_disk("execution_context.json", "this is a super safe passphrase")

If you have an Xtrace integration object, you can also choose to store/load the execution context remotely:

from xtrace_sdk.integrations.xtrace import XTraceIntegration
xtrace_integration = XTraceIntegration(org_id="your_org_id", api_key="your_api_key")

# Save to remote
await execution_context.save_to_remote(xtrace_integration)

# Load from remote
await execution_context = ExecutionContext._load_from_remote("this is a super safe passphrase","ctx_id", xtrace_integration)

Note that when creating a new ExecutionContext, an context ID will be generated as <id> as an attribute of the class instance. You can use this context ID to identify and manage different execution contexts.

Data Loader Configuration

The SDK provides a data loader module that can be configured to encrypt and load vectors into the system. The dataloader needs an execution context and an integration object to function properly.

from xtrace_sdk.data_loaders.base import DataLoaderBase
from xtrace_sdk.crypto.paillier_client import PaillierClient
from xtrace_sdk.integrations.xtrace import XTraceIntegration


# if you have already stored the execution context, you can load it from disk or remote
execution_context = ExecutionContext(
    paillier_client=paillier_client = PaillierClient(embd_len=512, key_len=1024),
    passphrase="this is a super safe passphrase",
)
xtrace_integration = XTraceIntegration(org_id="your_org_id", api_key="your_api_key")

# construct data loader instance
data_loader = DataLoaderBase(execution_context, xtrace_integration)

Retriever Configuration

Retriever configuration is similar to data loader configuration. Retrievers are used to fetch and decrypt data from the system. You need an execution context and an integration object to create a retriever instance.

from xtrace_sdk.retrievers.simple_retriever import SimpleRetriever

retriever = SimpleRetriever(execution_context, xtrace_integration)