Initialize

🚀 Getting Started: Initializing the Client

The first step to using the enVector SDK is to initialize the client environment. This process establishes a connection to the service and sets up the necessary enVector keys. The pyenvector.init() function is a convenient helper designed to make this process simple.

The pyenvector.init() Function

The pyenvector.init() function is a high-level helper that handles both the connection to the enVector service and the key management in a single call. If encryption keys do not exist at the specified path, it will automatically generate them for you, easily preparing everything needed to use the SDK.

Internally, this convenient init() function combines the functionality of two core components:

• init_connect(): Establishes the connection to the service.

• init_index_config(): Configures the keys and index settings.

Basic Usage Example

import pyenvector as ev

# Initialize the client environment
ev.init(
    address="localhost:50050",  # Address of the enVector service (host:port)
    key_path="./keys",          # Base directory to store keys
    key_id="ev-key",             # A unique ID to distinguish this key set
    host=None,                   # Host of the enVector service
    port=None,                   # Port of the enVector service
    access_token=None,           # Access Token of the enVector service
    index_name=None,
    dim=None,
    auto_key_setup=None,
    metadata_encryption=None,
    seal_mode=None,
    seal_kek_path=None,
    query_encryption=None,
    index_encryption=None,
    preset=None,
    eval_mode=None,
    index_type=None,
)

print("enVector SDK has been successfully initialized!")

After calling ev.init(), the SDK client is fully configured and ready to communicate with the server, handle data encryption, and perform operations.

EnvectorClient.init() Parameters

pyenvector.init() proxies to EnvectorClient.init(). The arguments below mirror the client class and let you tailor the connection, encryption, and key-management behavior that gets set up.

Connection & security

• host, port, address: Provide a host + port pair or a single address string (host:port) to reach the enVector gRPC endpoint.

• access_token: Bearer token for SaaS or authenticated clusters. Leave None for unauthenticated local deployments.

• secure: Force TLS. When omitted it defaults to True if an access_token was supplied, otherwise False.

• description: Optional free-form text that tags the index you will operate on.

Index definition

• index_name: Target index to create/use on the server.

• dim: Vector dimensionality (must match the model that generated your embeddings).

• preset, eval_mode: Choose the HE preset and evaluator mode (e.g., mm or ip).

• index_type, index_params: Configure the physical index on the server (e.g., {"index_type": "flat"} or ivf_flat with additional params).

Key management & automation

• key_path: Local directory that stores generated key files. Skip this (keep None) if you will stream keys or use AWS storage.

• key_id: Identifier for the key pair you want to register. Required when auto_key_setup=True.

• auto_key_setup: When True (default) the SDK will create/register keys as needed; set False if you plan to manage keys manually.

• key_store: Set to "aws" to use AWS-backed storage. Leave None (default) for filesystem-based keys.

Encryption controls

• query_encryption, index_encryption: Choose the encryption mode for queries and stored vectors (plain, cipher, or hybrid).

• metadata_encryption: Enable encryption of metadata payloads.

• seal_mode, seal_kek_path, seal_kek: Enable AES-KEK sealing of secret key blobs at rest and point to the KEK file or in-memory bytes.

In-memory key streams

• use_key_stream: When True, instructs the SDK to use byte streams instead of files. Automatically enabled when key_path is omitted.

• enc_key, eval_key, sec_key, metadata_key: Raw bytes for each key component when use_key_stream=True.

AWS-backed key storage

• region_name: AWS region where S3 and Secrets Manager live.

• bucket_name: S3 bucket that stores public key blobs (encryption/eval keys).

• secret_prefix: Secrets Manager prefix for secret/metadata keys.

When key_store="aws" the SDK uses KeyManager to pull key blobs directly from AWS (and, if auto_key_setup=True, it can generate a new key set and push it up as well). Make sure the environment running the SDK has AWS credentials with permission to access the bucket and secrets. The target bucket and any referenced Secrets Manager prefixes must already exist before running ev.init(), and the IAM role/credentials in use must allow both S3 (read/write objects) and Secrets Manager (read/write secrets) operations for the configured resources.

AWS-backed initialization example

The snippet below connects to a managed gRPC endpoint over TLS, generates keys if they do not exist, and stores them in AWS services instead of the local filesystem:

import os
import pyenvector as ev

ev.init(
    address="prod.grpc.envector.example.com:443",
    access_token=os.environ["ENVECTOR_ACCESS_TOKEN"],
    key_id="prod-key-01",
    key_store="aws",
    region_name="ap-northeast-2",
    bucket_name="envector-prod-keys",  # must already exist
    secret_prefix="/envector/prod",
    auto_key_setup=True,  # generate & upload key material if it is missing
)
print("Connected and ready with AWS-backed keys 🔐")

If the specified key_id already exists in AWS, the SDK loads it and registers the keys with the server. Otherwise it generates a fresh key set in memory, uploads it to S3/Secrets Manager, registers it with the endpoint, and loads it into the session automatically.