> 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/sdk-user-guide/initialize.md).

# Initialize

## 🚀 `ev.init()`: The Entry Point

`ev.init()` is a single high-level call that prepares everything the SDK needs before you can create indexes, insert vectors, or run encrypted searches. Rather than a single action, it is an **umbrella** over three configuration stages that you would otherwise have to set up individually.

| Stage                      | What it sets up                                                                                               | Sub-page                                                                       |
| -------------------------- | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------ |
| 🔌 **Connection**          | gRPC endpoint, TLS, access token                                                                              | [Connection](/1.4.x/sdk-user-guide/initialize/connecting-to-the-service.md)    |
| ⚙️ **Index Configuration** | `index_name`, `dim`, HE preset, evaluator mode, index type                                                    | [Index Configuration](/1.4.x/sdk-user-guide/initialize/index-configuration.md) |
| 🔑 **Key Management**      | Key **generation** (if missing), loading, registration with the server, optional sealing / AWS-backed storage | [Key Management](/1.4.x/sdk-user-guide/initialize/key-config.md)               |

In one call, `ev.init()` answers three questions:

1. **Where** is the service? → connection
2. **What** does the target index look like (shape, HE preset, index type)? → index configuration
3. **Which** keys will encrypt my data, and where do they live? → key management (covers both *key generation* and *key configuration*)

If encryption keys do not yet exist at `key_path` (or in AWS when `key_store="aws"`), `ev.init()` will **generate** them, **register** the public keys with the server, and **load** them into the session automatically — no extra steps required.

#### Basic Usage Example

```python
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 (`ip1` or `ip2`) and evaluator mode (`mm`, `mms`, `mm32`, `mms32`; default `mm32`). MM-family modes pin the preset automatically (`mm`/`mms` → `ip1`, `mm32`/`mms32` → `ip2`). See [Presets](/1.4.x/sdk-user-guide/initialize/index-configuration/2.-presets.md) for the full table.
* `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. Currently, only `"plain"` is supported for queries, while indexes are always encrypted with `"cipher"`.
* `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:

```python
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.


---

# 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/sdk-user-guide/initialize.md?ask=<question>&goal=<endgoal>
```

`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.