> For the complete documentation index, see [llms.txt](https://docs.envector.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.envector.io/1.4.x/api-reference/client.md). # EnvectorClient ## module `client` PyEnvector client module This module provides the EnvectorClient class (formerly ES2) and helpers for managing connections, keys, and indexes against the enVector server. * `EnvectorClient` — Main class for managing enVector operations. * `init_connect` — Initializes the connection to the enVector server. * `init_index_config` — Initializes the index configuration. * `create_index` — Creates a new index. * `init` — Initializes the PyEnvector client environment. ### class `EnvectorClient` ```python class EnvectorClient() ``` Main class for managing enVector operations. Methods: init\_connect(host, port, address, access\_token): Initializes the connection to the enVector server. register\_key(key\_id, key\_path): Registers a key with the enVector server. generate\_and\_register\_key(key\_id, key\_path, preset): Generates and registers a key. init\_index\_config(key\_path, key\_id, preset, query\_encryption, index\_encryption, index\_type): Initializes the index configuration. create\_index(index\_name, dim, index\_encryption, index\_type): Creates a new index. init(host, port, address, access\_token, key\_path, key\_id, preset, query\_encryption, index\_encryption, index\_type, auto\_key\_setup): Initializes the EnvectorClient environment. *** #### `__init__()` ```python def __init__() ``` Initializes the EnvectorClient class. *** #### `indexer()` ```python @property def indexer() ``` Returns the indexer object. **Raises**: * `ValueError`: If the indexer is not initialized. *** #### `indexer()` ```python @indexer.setter def indexer(indexer: Indexer) ``` Sets the indexer object. **ARGUMENTS** * `indexer` (`Indexer`): The indexer object. **Raises**: * `ValueError`: If the indexer is not an instance of Indexer. *** #### `index_config()` ```python @property def index_config() ``` Returns the index configuration. **Raises**: * `ValueError`: If the index configuration is not initialized. *** #### `index_config()` ```python @index_config.setter def index_config(index_config: IndexConfig) ``` Sets the index configuration. **ARGUMENTS** * `index_config` (`IndexConfig`): The index configuration. **Raises**: * `ValueError`: If the index configuration is not an instance of IndexConfig. *** #### `kms_client()` ```python @property def kms_client() ``` Returns the KMS client, if configured. **RETURNS** KMSClient or None: The KMS client instance. *** #### `is_connected()` ```python @property def is_connected() ``` Checks if the EnvectorClient client is connected to the server. **RETURNS** `bool`: True if connected, False otherwise. *** #### `disconnect()` ```python def disconnect() ``` Disconnects the EnvectorClient client from the server. *** #### `register_key()` ```python def register_key(key_id: Optional[str] = None) ``` Registers and loads a key with the enVector server. **ARGUMENTS** * `key_id` (`str`): The key ID. If omitted the ID from `index_config` is used. **Raises**: * `ValueError`: If the indexer is not initialized. *** #### `load_key()` ```python def load_key(key_id: Optional[str] = None) ``` Loads a key with the enVector server. **ARGUMENTS** * `key_id` (`str`): The key ID. **Raises**: * `ValueError`: If the indexer is not initialized. *** #### `unload_key()` ```python def unload_key(key_id: Optional[str] = None) ``` Unloads a key with the enVector server. **ARGUMENTS** * `key_id` (`str`): The key ID. **Raises**: * `ValueError`: If the indexer is not initialized. *** #### `get_key_list()` ```python def get_key_list() ``` Retrieves the list of registered keys. **Raises**: * `ValueError`: If the indexer is not initialized. **RETURNS** `list`: A list of registered keys. *** #### `get_key_info()` ```python def get_key_info(key_id: Optional[str] = None) ``` Retrieves the information of the registered keys. **Raises**: * `ValueError`: If the indexer is not initialized. **RETURNS** `dict`: A dictionary containing key information. *** #### `get_index_list()` ```python def get_index_list() ``` Retrieves the list of registered index. **Raises**: * `ValueError`: If the indexer is not initialized. **RETURNS** `list`: A list of registered indexes. *** #### `get_index_summary()` ```python def get_index_summary(index_name: str) ``` Retrieves lightweight summary information for a registered index. **ARGUMENTS** * `index_name` (`str`): The target index name. **Raises**: * `ValueError`: If the indexer is not initialized. **RETURNS** `dict`: A dictionary containing summary index information. *** #### `clone_index()` ```python def clone_index(source_index_name: str, target_index_name: str) ``` Clone an existing index on the server. **ARGUMENTS** * `source_index_name` (`str`): The source index name. * `target_index_name` (`str`): The target index name to create. **Raises**: * `ValueError`: If the indexer is not initialized. **RETURNS** `dict`: A dictionary containing the source and target index names. *** #### `generate_and_store_remote()` ```python def generate_and_store_remote(key_store: str, key_id: Optional[str] = None) ``` Retrieves the key from a remote key store using KeyManager. **ARGUMENTS** * `key_store` (`str`): Remote key store name ("aws" or "gcp" or "vault"). * `key_id` (`str`): Override for `index_config.key_id` when retrieving the key. *** #### `generate_key()` ```python def generate_key(key_id: Optional[str] = None) ``` Generates a key using the KeyGenerator. **ARGUMENTS** * `key_id` (`str`): Override for `index_config.key_id` when generating the key. **RETURNS** `KeyGenerator`: The KeyGenerator instance used to generate the key. *** #### `generate_and_register_key()` ```python def generate_and_register_key() ``` Generates and registers a key. *** #### `context_param()` ```python @property def context_param() -> "ContextParameter" ``` Returns the context parameters. **RETURNS** `ContextParameter`: The context parameters. *** #### `key_param()` ```python @property def key_param() -> "KeyParameter" ``` Returns the key parameters. **RETURNS** `KeyParameter`: The key parameters. *** #### `init_connect()` ```python def init_connect(host: Optional[str] = None, port: Optional[int] = None, address: Optional[str] = None, access_token: AccessTokenInput = None, secure: Optional[bool] = None, refresh_token: Optional[str] = None, oidc_issuer: Optional[str] = None, token_endpoint: Optional[str] = None, client_id: Optional[str] = None, client_secret: Optional[str] = None, scope: Optional[str] = None) ``` Initializes the connection to the enVector server. **ARGUMENTS** * `host` (`str`): The host address. * `port` (`int`): The port number. * `address` (`str`): The full address. * `access_token` (`str or callable`): Bearer token string, or a callable returning the current token for refreshable auth flows. * `secure` (`bool`): Whether to use a secure connection. If None, (defaults to True when access\_token or refresh\_token is provided, otherwise False.) * `refresh_token` (`str`): OIDC refresh token used by the SDK to renew bearer tokens. * `oidc_issuer` (`str`): OIDC issuer URL used to discover the token endpoint. * `token_endpoint` (`str`): Explicit token endpoint used for refresh token exchange. * `client_id` (`str`): OIDC client ID for refresh token exchange. * `client_secret` (`str`): OIDC client secret for refresh token exchange. * `scope` (`str`): Optional scope value included in refresh requests. **Raises**: * `ValueError`: If neither host and port nor address are provided. **RETURNS** `EnvectorClient`: The initialized EnvectorClient object. *** #### `init_index_config()` ```python def init_index_config(index_name: Optional[str] = None, dim: Optional[int] = None, key_path: Optional[str] = None, key_id: Optional[str] = None, seal_mode: Optional[str] = None, seal_kek_path: Optional[str] = None, preset: Optional[str] = None, eval_mode: Optional[str] = None, query_encryption: Optional[str] = None, index_encryption: Optional[str] = None, index_params: Optional[dict] = None, index_type: Optional[str] = None, metadata_encryption: Optional[bool] = None, description: Optional[str] = None, auto_key_setup: Optional[bool] = None, use_key_stream: Optional[bool] = None, enc_key: Optional[bytes] = None, eval_key: Optional[bytes] = None, sec_key: Optional[bytes] = None, metadata_key: Optional[bytes] = None, seal_kek: Optional[bytes] = None, key_store: Optional[str] = None, region_name: Optional[str] = None, bucket_name: Optional[str] = None, secret_prefix: Optional[str] = None, vault_addr: Optional[str] = None, vault_mount: Optional[str] = None) ``` Initializes the index configuration. **PARAMETERS** * `index_name` (str, optional): The name of the index. * `dim` (int, optional): The dimensionality of the index. * `key_path` (str, optional): The path to the key. Defaults to None. * `key_id` (str, optional): The key ID. Defaults to None. * `seal_mode` (str, optional): The seal mode. Defaults to None. * `seal_kek_path` (str, optional): The key encryption key (KEK) path. Defaults to None. * `preset` (str, optional): The preset for the key. Defaults to None. * `eval_mode` (str, optional): The evaluation mode. Defaults to None. * `query_encryption` (str, optional): The encryption type for query. Currently “plain” supported only. * `index_encryption` (str, optional): The encryption type for database. Currently “cipher” supported only. * `index_params` (dict, optional): The parameters for the index. Defaults to None. * `index_type` (str, optional): The type of index. Currently, `flat`, `ivf_flat` and `ivf_vct` index types are supported. * `metadata_encryption` (bool, optional): The encryption type for metadata, e.g. True, False. Defaults to None. * `description` (str, optional): A human-readable description for the index. * `auto_key_setup` (bool, optional): When True, automatically generate/register the key material. * `use_key_stream` (bool, optional): When True, expect in-memory key bytes instead of files. * `enc_key` (bytes, optional): Encryption key bytes when `use_key_stream` is True. * `eval_key` (bytes, optional): Evaluation key bytes for key-stream mode. * `sec_key` (bytes, optional): Secret key bytes for key-stream mode. * `metadata_key` (bytes, optional): Metadata key bytes for key-stream mode. * `seal_kek` (bytes, optional): Raw KEK bytes overriding `seal_kek_path`. Examples: Initialize EnvectorClient environment: ```pycon >>> pyenvector_client = EnvectorClient() >>> pyenvector_client.init_index_config( ... key_path="./keys", ... key_id="example_key", ... preset="ip2", ... query_encryption="plain", ... index_encryption="cipher", ... index_params={"index_type": "flat"} ... metadata_encryption=True, ... auto_key_setup=True ... ) ``` *** #### `init()` ```python def init(host: Optional[str] = None, port: Optional[int] = None, address: Optional[str] = None, access_token: AccessTokenInput = None, secure: Optional[bool] = None, refresh_token: Optional[str] = None, oidc_issuer: Optional[str] = None, token_endpoint: Optional[str] = None, client_id: Optional[str] = None, client_secret: Optional[str] = None, scope: Optional[str] = None, index_name: Optional[str] = None, dim: Optional[int] = None, key_path: Optional[str] = None, key_id: Optional[str] = None, seal_mode: Optional[str] = None, seal_kek_path: Optional[str] = None, preset: Optional[str] = None, eval_mode: Optional[str] = None, query_encryption: Optional[str] = None, index_encryption: Optional[str] = None, index_params: Optional[dict] = None, index_type: Optional[str] = None, metadata_encryption: Optional[bool] = None, description: Optional[str] = None, auto_key_setup: Optional[bool] = True, use_key_stream: Optional[bool] = False, enc_key: Optional[bytes] = None, eval_key: Optional[bytes] = None, sec_key: Optional[bytes] = None, metadata_key: Optional[bytes] = None, seal_kek: Optional[bytes] = None, key_store: Optional[str] = None, region_name: Optional[str] = None, bucket_name: Optional[str] = None, secret_prefix: Optional[str] = None, vault_addr: Optional[str] = None, vault_mount: Optional[str] = None, kms_address: Optional[str] = None) ``` Initializes the EnvectorClient environment (connection, key, and index config). **ARGUMENTS** * `host` (`str`): The host address to connect to enVector server. * `port` (`int`): The port number to connect to enVector server. * `address` (`str`): The full address to connect to enVector server. * `access_token` (`str or callable`): Bearer token string, or a callable returning the current token to connect to enVector server. * `secure` (`bool`): Whether to use a secure connection. If None, defaults to True when access\_token is provided or refresh\_token is configured, otherwise False. * `refresh_token` (`str`): OIDC refresh token used by the SDK to renew bearer tokens. * `oidc_issuer` (`str`): OIDC issuer URL used to discover the token endpoint. * `token_endpoint` (`str`): Explicit token endpoint used for refresh token exchange. * `client_id` (`str`): OIDC client ID for refresh token exchange. * `client_secret` (`str`): OIDC client secret for refresh token exchange. * `scope` (`str`): Optional scope value included in refresh requests. * `index_name` (`str`): The name of the index. * `dim` (`int`): The dimensionality of the index. * `key_path` (`str`): The path to the key directory. * `key_id` (`str`): The key ID. * `seal_mode` (`str`): Seal mode such as `AES_KEK` when secret keys are sealed at rest. * `seal_kek_path` (`str`): The path to the key encryption key for secret key sealing. * `seal_kek` (`bytes`): In-memory KEK bytes that override `seal_kek_path`. * `preset` (`str`): The preset for the key. * `eval_mode` (`str`): The evaluation mode. * `query_encryption` (`str`): The encryption type for query. Currently “plain” supported only. * `index_encryption` (`str`): The encryption type for database. Currently, "cipher" supported only. * `index_params` (`dict`): The parameters for the index. Defaults to {"index\_type": "flat"}. Currently, `flat`, `ivf_flat` and `ivf_vct` index types are supported. * `index_type` (`str`): The type of index. Currently, `flat`, `ivf_flat` and `ivf_vct` index types are supported. * `metadata_encryption` (`bool`): The encryption type for metadata, e.g. True, False. Defaults to None. * `description` (`str`): A human-readable description for the index. * `auto_key_setup` (`bool`): Whether to automatically generate and register the key. Defaults to `True`. * `use_key_stream` (`bool`): Whether keys are supplied as in-memory byte streams rather than files. Defaults to `False`. * `enc_key` (`bytes`): Encryption key bytes when `use_key_stream` is enabled. * `eval_key` (`bytes`): Evaluation key bytes when `use_key_stream` is enabled. * `sec_key` (`bytes`): Secret key bytes when `use_key_stream` is enabled. * `metadata_key` (`bytes`): Metadata encryption key bytes used when `metadata_encryption` is True and `use_key_stream` is enabled. * `kms_address` (`str`): `host:port` of the KMS combined service (gRPC). When provided, the KMS client is activated for key generation, secret management, and TopK operations. **RETURNS** `EnvectorClient`: The initialized EnvectorClient object. *** #### `create_index()` ```python def create_index(index_name: Optional[str] = None, dim: Optional[int] = None, key_path: Optional[str] = None, key_id: Optional[str] = None, seal_mode: Optional[str] = None, seal_kek_path: Optional[str] = None, preset: Optional[str] = None, eval_mode: Optional[str] = None, query_encryption: Optional[str] = None, index_encryption: Optional[str] = None, index_params: Optional[dict] = None, index_type: Optional[str] = None, metadata_encryption: Optional[bool] = None, description: Optional[str] = None, use_key_stream: Optional[bool] = None, enc_key: Optional[bytes] = None, eval_key: Optional[bytes] = None, sec_key: Optional[bytes] = None, metadata_key: Optional[bytes] = None, seal_kek: Optional[bytes] = None, key_store: Optional[str] = None, region_name: Optional[str] = None, bucket_name: Optional[str] = None, secret_prefix: Optional[str] = None, vault_addr: Optional[str] = None, vault_mount: Optional[str] = None) ``` Creates a new index. **ARGUMENTS** * `index_name` (`str`): The name of the index. * `dim` (`int`): The dimensionality of the index. * `index_encryption` (`str`): The encryption type for database, e.g. "plain", "cipher", "hybrid". * `index_type` (`str`): The type of index. * `description` (`str`): A human-readable description for the index. * `key_path` (`str`): Directory containing keys. Required unless `use_key_stream` is True. * `key_id` (`str`): Identifier of the key bundle to load. * `seal_mode` (`str`): Seal mode name (for example `AES_KEK`). * `seal_kek_path` (`str`): Path to the KEK when seal mode is enabled. * `preset` (`str`): Context preset. * `eval_mode` (`str`): Evaluation mode. * `query_encryption` (`str`): Query encryption configuration. * `index_encryption` (`str`): Database encryption configuration. * `index_params` (`dict`): Additional index build parameters. * `index_type` (`str`): Convenience alias for `index_params['index_type']`. * `metadata_encryption` (`bool`): Whether metadata is encrypted. * `use_key_stream` (`bool`): When True, use in-memory key bytes instead of disk paths. * `enc_key` (`bytes`): Encryption key stream for key-stream mode. * `eval_key` (`bytes`): Evaluation key stream for key-stream mode. * `sec_key` (`bytes`): Secret key stream for key-stream mode. * `metadata_key` (`bytes`): Metadata key stream for key-stream mode. * `seal_kek` (`bytes`): Raw KEK bytes overriding `seal_kek_path`. **RETURNS** `Index`: The created index. *** #### `drop_index()` ```python def drop_index(index_name: str) ``` Drops the current index. **Raises**: * `ValueError`: If the indexer is not connected. **RETURNS** `Index`: The current index after dropping it. *** #### `delete_key()` ```python def delete_key(key_id: str) ``` Delete the key with the given key\_id. **ARGUMENTS** * `key_id` (`str`): The ID of the key to delete. **Raises**: * `ValueError`: If the indexer is not connected. *** #### `key_path()` ```python @property def key_path() ``` Returns the path to the key directory. **RETURNS** `str`: The path to the key directory. *** #### `describe()` ```python def describe(verbose: bool = False) ``` Provide a snapshot of the current EnvectorClient client state. **ARGUMENTS** * `verbose` (`bool`): When True, include the full list of keys and indexes. When False (default) only aggregated counts are returned. **RETURNS** `dict`: Summary or detailed information depending on `verbose`. *** #### `info()` ```python def info(verbose: bool = False) -> str ``` Provide a human-readable summary of the EnvectorClient client. **ARGUMENTS** * `verbose` (`bool`): When True, include detailed per-resource information. Defaults to False which emits a short numeric summary. **RETURNS** `str`: A formatted string representation of the EnvectorClient client state. *** #### `reset()` ```python def reset() ``` Reset the enVector server state for this client session. This helper performs a best-effort cleanup by: 1. Dropping all indexes 2. Unloading keys (best-effort; may be a no-op) 3. Deleting keys **RETURNS** `EnvectorClient`: The reset EnvectorClient object. --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question. Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter: ``` GET https://docs.envector.io/1.4.x/api-reference/client.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.